feat(service-integrations): phase 2 — integration widget & app form UI

- Add 6 renderer components: StatCard, Gauge, List, Progress, AlertBanner, Chart - Add IntegrationWidget container with auto-refresh, loading, error states - Add IntegrationAlertOverlay for layout-level critical alerts - Add IntegrationConfigFields for dynamic form generation from Zod schemas - Register integration type in WidgetRenderer - Extend WidgetCreationForm with integration app/endpoint pickers - Extend AppForm with integration config section and test connection button - Add /api/integrations/alerts endpoint
2026-03-25 22:07:51 +03:00
parent 114dee57a8
commit 50e8519220
25 changed files with 1360 additions and 1 deletions
@@ -0,0 +1,62 @@
+# Phase 1: Integration Architecture Foundation
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** backend
+
+## Objective
+Build the core integration framework: TypeScript interfaces, registry pattern, shared cache, Prisma schema changes, API routes, and updated app service. This phase unlocks all subsequent integration phases.
+
+## Tasks
+
+- [ ] Task 1: Create `src/lib/server/integrations/types.ts` — Define `Integration`, `IntegrationEndpoint`, `IntegrationData`, `IntegrationConfig` interfaces. Each integration has: id, name, icon, authConfigSchema (Zod), extraConfigSchema (optional Zod), endpoints array, testConnection method, fetchData method.
+- [ ] Task 2: Create `src/lib/server/integrations/registry.ts` — Registry singleton with `register(integration)`, `get(id)`, `list()`, `getForApp(app)` methods. Auto-imports integrations from subdirectories.
+- [ ] Task 3: Create `src/lib/server/integrations/cache.ts` — TTL-based cache for integration data. Key: `${appId}:${endpointId}`, configurable TTL per endpoint. Reuse pattern from `metricService.ts`.
+- [ ] Task 4: Create `src/lib/server/integrations/encryption.ts` — Encrypt/decrypt integration config JSON using AES-256-GCM with key from `INTEGRATION_ENCRYPTION_KEY` env var (fallback to `JWT_SECRET` for dev).
+- [ ] Task 5: Update Prisma schema — Add `integrationType String?`, `integrationConfig String?`, `integrationEnabled Boolean @default(false)` to `App` model. Run `npx prisma db push`.
+- [ ] Task 6: Update `src/lib/types/app.ts` — Add integration fields to `AppRecord` interface.
+- [ ] Task 7: Update `src/lib/server/services/appService.ts` — Handle integration fields on create/update. Encrypt `integrationConfig` before storing, decrypt on read.
+- [ ] Task 8: Update `src/lib/utils/validators.ts` — Add `integration` to `WidgetType` enum. Add Zod schema for integration widget config: `{ appId: string, endpointId: string, refreshInterval?: number }`.
+- [ ] Task 9: Create API route `src/routes/api/integrations/+server.ts` — `GET` returns list of available integration types with their endpoints and config schemas.
+- [ ] Task 10: Create API route `src/routes/api/integrations/test/+server.ts` — `POST { appId, integrationType, config }` tests connection to the service.
+- [ ] Task 11: Create API route `src/routes/api/integrations/[appId]/data/[endpointId]/+server.ts` — `GET` fetches live data from integration endpoint, uses cache.
+- [ ] Task 12: Create `src/lib/server/integrations/base.ts` — Abstract base class or helper functions for common integration patterns (HTTP fetch with timeout, error wrapping, response parsing).
+
+## Files to Modify/Create
+- `src/lib/server/integrations/types.ts` — new: core interfaces
+- `src/lib/server/integrations/registry.ts` — new: integration registry
+- `src/lib/server/integrations/cache.ts` — new: TTL cache
+- `src/lib/server/integrations/encryption.ts` — new: config encryption
+- `src/lib/server/integrations/base.ts` — new: shared helpers
+- `prisma/schema.prisma` — modify: add 3 fields to App model
+- `src/lib/types/app.ts` — modify: add integration fields
+- `src/lib/server/services/appService.ts` — modify: handle integration fields
+- `src/lib/utils/validators.ts` — modify: add integration widget type + config schema
+- `src/routes/api/integrations/+server.ts` — new: list integrations
+- `src/routes/api/integrations/test/+server.ts` — new: test connection
+- `src/routes/api/integrations/[appId]/data/[endpointId]/+server.ts` — new: fetch data
+
+## Acceptance Criteria
+- Integration interfaces are well-typed and extensible
+- Registry can register and retrieve integrations
+- Cache prevents repeated API calls within TTL
+- Prisma schema has integration fields, migration runs clean
+- App service encrypts/decrypts integration config transparently
+- API routes return proper envelope responses
+- All Zod schemas validate correctly
+
+## Notes
+- Encryption key: use `INTEGRATION_ENCRYPTION_KEY` env var, fallback to `JWT_SECRET` for development simplicity
+- The registry should be designed so adding a new integration is just: create a directory, implement the interface, register it
+- Cache should handle concurrent requests to the same endpoint gracefully
+- Big Bang strategy: build/tests may not pass after this phase since the integration widget type is registered but has no frontend renderer yet
+
+## Review Checklist
+- [ ] All tasks completed
+- [ ] Code follows project conventions
+- [ ] No unintended side effects
+- [ ] Types are comprehensive and well-documented
+- [ ] Encryption is properly implemented (no plaintext secrets in DB)
+
+## Handoff to Next Phase
+<!-- Filled in after completion -->