Update hivegrid-cloud reference to latest main
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
e98d38e716
commit
7b21524c86
3781 files changed
+373484
-225607
No files matched your search
@@ -8,7 +8,9 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | P5 — Apps-Engine & Integrations-Framework |
|
||||
| **Cycle/Fenster** | W2 — Plattform & CRM (Demo 1) · fällig 2026-06-21 · Gate W2 (Noah-Demo #1) |
|
||||
| **Status** | geplant |
|
||||
| **Status** | **done (2026-07-07)** — 10/10 DoD = 100 %; Backend seit 2026-06-28, Interim-UI (AD-28) + Run-Detail + Katalog-Seed via PR #50, Sidebar-Reachability-Fix via PR #51; Plane auf Done, Label `design-nachzug` gesetzt |
|
||||
|
||||
**🎨 design-nachzug: offen** (seit 2026-07-07) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P5` ausstehend.
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `R-P2b` (RLS + Permissions — DataConnection ist tenant-bezogen + verschlüsselt)
|
||||
@@ -17,7 +19,7 @@
|
||||
- **Konflikt-Risiko:** gering — db push auf Branch, Migration erst beim Merge.
|
||||
|
||||
## Was wir bauen
|
||||
Das **eine, typsichere Integrations-Framework**, über das später Gmail, Outlook, AirCall, PandaDoc, Stripe und KWP laufen. Ein Admin stellt eine `DataConnection` über **OAuth2-Connect** oder **API-Key-Connect** in der Settings-UI her; die **type-safe Adapter-Registry** erlaubt neue Connection-Typen ohne Kern-Änderung (Build-Time-Scan, Drift-Check); `AppSyncRun`/`AppSyncItem`/`AppSyncRunLog` protokollieren Sync-Läufe in Klartext; **Connection-Health-Monitoring** zeigt active/degraded/broken/revoked/pending mit Klartext + Lösungs-Hinweisen; **OAuth-Tokens per-Tenant-DEK-verschlüsselt** (AD-8). Mehrere Connections pro App pro Tenant (z.B. drei Gmail-Mailboxen).
|
||||
Das **eine, typsichere Integrations-Framework**, über das später Gmail, Outlook, AirCall, Signatur-Adapter (SES-Default/PandaDoc-BYOK), Legacy-Provider und KWP laufen. Ein Admin stellt eine `DataConnection` über **OAuth2-Connect** oder **API-Key-Connect** in der Settings-UI her; die **type-safe Adapter-Registry** erlaubt neue Connection-Typen ohne Kern-Änderung (Build-Time-Scan, Drift-Check); `AppSyncRun`/`AppSyncItem`/`AppSyncRunLog` protokollieren Sync-Läufe in Klartext; **Connection-Health-Monitoring** zeigt active/degraded/broken/revoked/pending mit Klartext + Lösungs-Hinweisen; **OAuth-Tokens per-Tenant-DEK-verschlüsselt** (AD-8). Mehrere Connections pro App pro Tenant (z.B. drei Gmail-Mailboxen).
|
||||
|
||||
> ⚙️ **Recut (KWP → v2):** KWP = `DataConnection type='rest-api'` (API-Key-Connect) — **kein `kwpsync.exe`-Windows-Client-Flow** (Scope-Schnitt #12). `windows_client` bleibt im Datenmodell, hat in v1 keinen UI-Flow. Apps selbst werden erst in ihren Modul-Phasen (P14/P15/P16/P20) angedockt — P5 liefert nur das Framework + die generische Katalog-/Wizard-UI.
|
||||
|
||||
@@ -32,16 +34,16 @@ Das **eine, typsichere Integrations-Framework**, über das später Gmail, Outloo
|
||||
*Davids P5-Screens über `D-P5` (Compose aus D0; Connection-Card als wiederverwendbares Element).*
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **DataConnection** per OAuth2-Connect (Gmail/Outlook/AirCall/PandaDoc/Google Calendar) **oder** API-Key-Connect (KWP/Stripe) in Settings-UI herstellbar
|
||||
- [ ] **Type-safe Adapter-Registry** (Build-Time-Scan von `app/integrations/`, Drift-Check → Klartext-Warnung im Plattform-Admin) — neue Typen ohne Kern-Änderung
|
||||
- [ ] **AppSyncRun/AppSyncItem/AppSyncRunLog** mit Klartext-Summary
|
||||
- [ ] **Connection-Health-Monitoring** (active/degraded/broken/revoked/pending) + Token-Refresh-Worker + degraded/broken → `notify()` an Tenant-Admin
|
||||
- [ ] **OAuth-Tokens per-Tenant-DEK-verschlüsselt** (AD-8)
|
||||
- [ ] Lifecycle: Connect-Wizard / Reconnect (gleiche ID, kein History-Verlust) / Disconnect (Multi-Step-Confirm, Status revoked statt Hard-Delete)
|
||||
- [ ] Mehrere DataConnections pro App pro Tenant (mit User-Label)
|
||||
- [ ] Manueller Re-Sync + Schema-Drift-Sentinel + Webhook-Storm-Schutz
|
||||
- [ ] Permissions: `integrations.read/.connect/.disconnect/.manual_sync/.view_logs/.admin`
|
||||
- [ ] *(→ v2)* `kwpsync.exe`-Windows-Client-Flow ausgeschlossen (KWP = rest-api)
|
||||
- [x] **DataConnection** per OAuth2-Connect oder API-Key-Connect — *Backend (createConnection: Adapter-Validierung + Envelope-Crypto) + funktionale Route-Action fertig; finale Wizard-Optik = Davids D-P5.*
|
||||
- [x] **Type-safe Adapter-Registry** (Drift-Check → Klartext-Warnung) — neue Typen ohne Kern-Änderung
|
||||
- [x] **AppSyncRun/AppSyncItem/AppSyncRunLog** mit Klartext-Summary
|
||||
- [x] **Connection-Health-Monitoring** + Token-Refresh-Worker + degraded/broken → `notify()` — *Health-Probe + notify + Worker-Crons (token-refresh 5m, health-sweep 15m) über geteiltes @hivegrid/integrations-Paket.*
|
||||
- [x] **OAuth-Tokens per-Tenant-DEK-verschlüsselt** (AD-8)
|
||||
- [x] Lifecycle: Connect / Reconnect (gleiche ID, kein History-Verlust) / Disconnect (Status revoked statt Hard-Delete) — *Backend + Route-Actions; finale Wizard-Optik = D-P5.*
|
||||
- [x] Mehrere DataConnections pro App pro Tenant (mit User-Label)
|
||||
- [x] Manueller Re-Sync + Schema-Drift-Sentinel + Webhook-Storm-Schutz (`triggerWebhookSync` via `withIdempotency`)
|
||||
- [x] Permissions: `integrations.read/.connect/.disconnect/.manual_sync/.view_logs/.admin`
|
||||
- [x] *(→ v2)* `kwpsync.exe`-Windows-Client-Flow ausgeschlossen (KWP = rest-api)
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/apps.prisma`): `App` (key, category, connection_type oauth2/api_key, connection_schema, phase — **global, kein RLS**), `DataConnection` (tenant_id, app_id, credentials **verschlüsselt**, connection_status, last_health_check), `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` (entity_type/id ↔ external_id, polymorph). `core.prisma` nur für Tenant-Relationen berühren (AD-21).
|
||||
@@ -59,7 +61,71 @@ Das **eine, typsichere Integrations-Framework**, über das später Gmail, Outloo
|
||||
- `_bmad-output/specs/M33a-apps-engine.md` (⚠ alte Drei-Komponenten-KWP-Architektur **nicht** bauen — Recut)
|
||||
- `docs/ARCHITECTURE-DECISIONS.md` → AD-8 (per-Tenant-DEK)
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
|
||||
> **✅ Stand 2026-06-28 — auf `main` gemergt.** R-P5 lief über den gemeinsamen Branch `feat/AK-P17a` und ging mit **PR #5** (squash, Merge-Commit `b0fae1af8`, Base `main`, 2026-06-28 17:50) auf `main`. Nachzug-Fix `packages/integrations/package.json` im Docker-deps-Target via **PR #8** (`0b9d2e46`, 18:05). Alle R-P5-Artefakte (`appsEngineService`, `@hivegrid/integrations`, `crypto.prisma`/`appsEngine.prisma`, Worker-Crons, Admin-Routen-Hülle) liegen im `main`-Tree. *Die älteren „Branch lokal, nicht gepusht"-Notizen unten sind damit überholt.* **Backend 9/9 DoD grün.** Extern offen bleibt nur: Davids `D-P5`-Optik, RLS-Live/Visual-Regression gegen Staging-DB, ~~App-Tabellen-Katalog-Seed (deferred)~~ *(Seed am 2026-07-07 nachgezogen, s.u.)*, Plane-Ticket auf Done.
|
||||
|
||||
**2026-06-27 (Akeshan) — Backend-Kern + Crypto-Fundament, Branch `feat/R-P5` (lokal, nicht gepusht).**
|
||||
|
||||
R-P5 an Akeshan übergeben (Plane: Assignee Akeshan). Gebaut in 6 Commits, jeweils mit grünem lefthook:
|
||||
- `b5aa98b` **Per-Tenant-DEK-Envelope-Crypto (DoD #5)** — `packages/foundation/crypto` (seal/open + KeyWrapper, CRYPTO_SECRET jetzt, Vault später swappbar) + `packages/db/crypto/tenant-envelope.server.ts` (DEK je Tenant, Crypto-Shredding) + `crypto.prisma`. 16 Tests grün. **Entsperrt AK-P17a** (dort nur noch Seam-Rebind).
|
||||
- `aed2a8b` **Schema an ENTITY-MODEL Domäne 4** — App global, DataConnection (+Status/Token/Label/credentialsCiphertext/is_demo_data), Sync-Modelle; RLS-SQL deferred; Consumer (cli/dsgvo) nachgezogen.
|
||||
- `51b6b59` **Permissions + Entitlements (DoD #9)** — `integrations.*` + Grants + DefaultPermissions-Union; `integrations`-Feature/Blueprint/Plan; `tenantHasModule('integrations')`.
|
||||
- `50bb9dd` **Adapter-Registry + Drift (DoD #2)** — `IntegrationAdapter`-Contract + Registry + `checkCatalogDrift` (foundation) + Katalog + `sample-data-sync`-Referenz-Adapter + Drift-Gate-Test.
|
||||
- `f2ea4d2` **Domain-Service (DoD #1/#3/#6/#7 + #4-Health + #8-Re-Sync)** — Lifecycle connect/reconnect/disconnect (Envelope-Crypto + Adapter-Validierung + Audit), Sync-Run/Item/Log, Health-Probe + notify; `withTenantRLS`, Credentials nie in List-VMs. Pure `aggregateSyncOutcome` getestet.
|
||||
- `0ab0f3a` **RLS-Gate-Test (env-gegatet) + i18n** (de+en).
|
||||
|
||||
**DoD-Stand: 6/9 voll grün** (#2, #3, #5, #6, #7, #9) + Schema + v2-Ausschluss (KWP `windows_client` nur Datenmodell). **Backend von #1 fertig** (UI-Wizard blockiert durch D-P5). **Teil-offen:**
|
||||
- **#4 Token-Refresh-Worker** — *architektonisch blockiert:* der Worker hängt nur an `@hivegrid/db`, erreicht die Adapter (in `apps/web/app/integrations`) nicht. Provider-seitiger Token-Refresh braucht ein **geteiltes Adapter-Paket** (web+worker). Health-Probe + notify (web-seitig) ist fertig; die zeitbasierte Degradierung-Cron (ohne Adapter) ist selbst machbar.
|
||||
- **#8 Webhook-Storm-Schutz** — `withIdempotency()`-Wiring an einem Webhook-Ingest noch offen (Schema-Drift-Sentinel via Registry-Drift ist da).
|
||||
- **Reachability (DoD B/#10):** VMs + Admin-Routen-Hülle + Sidebar — selbst machbar (finale Optik wartet auf Davids D-P5).
|
||||
- **Katalog-Seed** (`INTEGRATION_CATALOG` → `App`-Tabelle upserten) — selbst machbar.
|
||||
- `db push` + RLS-Live-Verifikation env-gegatet (kein lokales PG); Merge-Migration beim main-Merge (AD-21).
|
||||
|
||||
**Pre-existing rot (nicht von R-P5):** cli/dsgvo „covers every"-Tests für File/Task/AdminTenantNote/EntityLink (merged AK-P4a/b/P19 haben die Registries nie nachgezogen); permissions-seed Windows-fileURL-Flake; roleDisplay i18n. Alle environmental/Fremd-Ticket.
|
||||
|
||||
**Update 2026-06-28 (Akeshan) — beide Entscheidungen umgesetzt, DoD jetzt 9/9 backend.** Co-Dev-Abstimmung: Akeshan macht R-P5. Entscheidungen: (1) geteiltes Adapter-Paket extrahieren, (2) funktionale UI-Hülle jetzt. 4 weitere Commits:
|
||||
- `f6272c1` **@hivegrid/integrations extrahiert** (catalog + adapters + registry/drift + worker-tasks) — web+worker importierbar; Contract bleibt in foundation. **Worker-Crons** integrations-token-refresh (5m) + integrations-health-sweep (15m) pro Tenant via withTenantRLS → **DoD #4 komplett**.
|
||||
- `52b6113` **VMs + Admin-Route-Hülle + Sidebar + i18n** — `app.$tenant/integrations.*` (Katalog, Connection-Verwaltung mit connect/disconnect/manual-sync-Actions, Sync-History); Konnektor- + Permission-Gate (404); Credentials nie im VM. DataConnection.appId = bare Katalog-Key (AD-21, kein App-FK).
|
||||
- `a49d998` **Webhook-Storm-Schutz** (`triggerWebhookSync` via `withIdempotency`, 60s-Dedup) → **DoD #8 komplett**.
|
||||
|
||||
**Stand: 9/9 DoD backend grün** + Reachability-Hülle. Verifiziert: typecheck alle Pakete + web (0 Fehler, Turbo-Cache-Falle 2x umgangen via direktem tsc), 30 neue Tests grün (Crypto/Registry/Worker-Sweep/VMs/Aggregate), RLS-Gate-Tests skippen sauber, verify:i18n Exit 0. **Nur noch offen:** finale Subframe-Optik (Davids D-P5), `db push` + RLS-Live + Visual-Regression/Smoke (env/Staging), App-Tabellen-Katalog-Seed (deferred — Tenant-Flow nutzt Code-Katalog), Merge-Migration (beim main-Merge, AD-21). Branch `feat/R-P5`, 11 Commits, lokal, nicht gepusht.
|
||||
|
||||
**Abgleich/Review 2026-06-28 (Akeshan) — Branch gegen Ticket + DoD unabhängig nachgeprüft.** Auslöser: R-P5 von Raffael übernommen, vollständiger Soll/Ist-Abgleich vor Übergabe-Doku. Ergebnis bestätigt den Stand oben:
|
||||
- **Code-Inventar:** alle 9 DoD-relevanten Artefakte vorhanden (crypto.prisma/appsEngine.prisma, RLS-SQL crypto+apps-engine, foundation/crypto envelope+key-wrapper, db/crypto tenant-envelope, foundation integration-adapters, Paket @hivegrid/integrations inkl. worker-tasks, appsEngineService, Worker-Maintenance-Cron, apps-engine VMs, Admin-Routen-Hülle, AppSidebar-Eintrag). `git diff main..feat/R-P5`: 74 Dateien, +6722/-5779.
|
||||
- **Gates frisch gefahren:** `pnpm typecheck` (alle Pakete + web, react-router typegen + Prisma-Client-Regen) **Exit 0, 0 TS-Fehler**; gezielte vitest (foundation/crypto + integration-adapters + @hivegrid/integrations registry/worker-tasks + apps-engine VMs) **24/24 grün**; `verify:i18n` **Exit 0**. Working Tree sauber.
|
||||
- **Plane abgeglichen:** Ticket `R-P5` = State **In Progress**, Assignee **Akeshan**, blocked-by R-P2b+D-P5, 0 Kommentare → Status-Kommentar mit diesem Stand gesetzt. Identität des Keys via `users/me` = akeshan (kein Mismatch).
|
||||
- **Kein Statuswechsel auf Done:** Backend ist 9/9, aber DoD #1/#6 tragen den UI-Wizard-Teil (D-P5 blockiert) und mehrere Reachability/Verifikations-Punkte hängen an Staging-DB/David → Ticket bleibt **In Progress**, bis das D-P5-Delta + Live-DB-Verifikation durch sind.
|
||||
- **Selbst machbar noch offen:** nichts (alle Rest-Punkte extern blockiert: D-P5-Optik, Staging-DB für `db push`/RLS-Live/Visual-Regression, plus Merge-Migration beim main-Merge). → backend-seitig **100 % der selbst machbaren DoD**, gesamt **9/9 backend grün**.
|
||||
|
||||
**2026-07-07 (Akeshan) — Interim-UI (AD-28) + Sync-Run-Detail + Katalog-Seed, Branch `akeshan/r-p5-interim-ui`.**
|
||||
|
||||
Die „Baseline functional UI" (nacktes Tailwind in den Routen) wurde durch **AD-28-konforme Interim-Screens aus `~/ui`** ersetzt; damit sind die UI-Anteile von DoD #1/#6 sowie DoD D19/D20 jetzt real erfüllt statt nur „Backend fertig":
|
||||
- **Screens** `apps/web/app/components/screens/integrations/`: `IntegrationsCatalogPage` (A6, Karten-Grid nach Kategorie + Suche), `ConnectionDetailPage` (A6+A2, Banner bei degraded/broken mit Reconnect-Knopf), wiederverwendbare **`ConnectionCard`** (Status-Ampel/Klartext/letzter Check/Re-Sync/Reconnect/Trennen), **`ConnectWizardDialog`** (echter `Dialog` M 720 + `StepperHorizontal`: Voraussetzungen → auto-generiertes Credential-Formular aus `connection_schema` mit Secret-Reveal → Prüfen & Verbinden; OAuth2-Apps mit Interim-Hinweis), Disconnect-Confirm (XS 420, Klartext „Sync-Jobs gestoppt, History bleibt"), `SyncHistoryPage` (A2, Status/Kind-Filter + Re-Sync), `SyncRunDetailPage` (A3). Routen rendern nur noch `<XPage vm={} actions={} />`, Fetcher/closeSignal in der Route (Layer-DoD A eingehalten).
|
||||
- **Neu: Sync-Run-Detail** — Route `integrations.$app.$connectionId.syncs.$runId.tsx` + `sync-run-detail.vm.ts` (Items + Logs, `view_logs`-gegated, 404-Pattern) — schließt die vierte Screen-Zeile der Tabelle oben.
|
||||
- **Reconnect-Intent** in der `$app`-Route-Action ergänzt (Service `reconnectConnection` existierte; UI/Action-Pfad fehlte → DoD #6 jetzt komplett bedienbar).
|
||||
- **Hot-Swap (D20):** Adapter `integrationsCatalog` (`packages/ui-app/src/adapters/`) + `renderIntegrationsCatalog` (ui-subframe) + `renderIntegrationsCatalogMock` (ui-mock) + `integrationsCatalog.hot-swap.test.ts` nach `rolesList`-Muster.
|
||||
- **Smoke (D19):** `tests/e2e/integrations.spec.ts` — Login → Katalog → sample-data-sync → Wizard öffnet (Schritt 1) → Sync-History; non-mutierend, skippt ohne E2E-Creds.
|
||||
- **Katalog-Seed (bisher deferred, jetzt drin):** `buildCatalogSeedPlan()` (pur, `packages/integrations/src/catalog-seed.ts` + Test) + idempotentes `App`-Upsert im SeedService (global, kein RLS; Tenant-Flow liest weiter den Code-Katalog, `DataConnection.appId` bleibt bare Key).
|
||||
- **i18n:** ~50 neue Keys de+en (wizard/disconnect/runDetail/syncItem*/syncLogSeverity/Filter), chirurgisch gespliced.
|
||||
|
||||
**Verifiziert (lokal, Windows):** typecheck web+view-models+ui-app+ui-mock+ui-subframe+integrations je 0 Fehler · 434 Tests der 5 angefassten Pakete grün (inkl. 5 neue VM-, 3 Seed-, 5 Hot-Swap-/Mock-Tests; SeedService 19/19) · `verify:i18n` Exit 0 · `verify:sidebar-routes`, `verify:cross-cutting-models` (178/178), `verify:phase-c-boundaries`, `verify:test-density`, `verify:production-seed-artifact` grün · eslint-staged 0 Findings. Kein Prisma-Schema-Delta → keine Migration nötig. **Visual-Baseline deferred** wie AK-P3/R-P2a/AK-P4b (keine Screen-Snapshot-Harness) — Interim-Baseline wird beim David-Nachzug gezogen.
|
||||
|
||||
**Nachtrag 2026-07-07 (Browser-Verifikation lokal + Staging):** Der Sidebar-Eintrag war trotz Code + Plan-Entitlement nie sichtbar, weil `integrations` in `tenantNavigationFeatureKeys` (`appData.ts`) fehlte (Alt-Bug seit R-P5-Merge, betraf auch dashboard/leads/hr/calendar/emails/booking/forms/automation). Gefixt auf Branch `akeshan/verify-fixups` inkl. Registry-Guard-Test (`sidebarFeatureAccess.test.ts`); dazu EmptyState-Dead-Button-Wrapper (DoD B10/E23) und Klartext beim Disconnect (`healthMessageKey` -> `integrations.health.notConnected`). Reachability B6/B7 damit real erfüllt und im Browser verifiziert (Sidebar-Eintrag, kompletter Lifecycle inkl. Reconnect-Submit E2E).
|
||||
|
||||
**Offen (extern):** finale Subframe-Optik aus `D-P5` (→ Tag oben; Plane-Label `design-nachzug` gesetzt 2026-07-07). **Selbst machbar offen: nichts.**
|
||||
|
||||
**Abschluss 2026-07-07:** PR #50 (Interim-UI) und PR #51 (Verifikations-Fixups: Sidebar-productAccess-Keys + Guard-Test, EmptyState-Wrapper, Disconnect-Klartext, Dev-Host-Ports) auf `main` gemergt und auf Staging deployed; Katalog/Wizard auf Staging verifiziert, kompletter Lifecycle inkl. Reconnect-Submit lokal E2E. Plane: Kommentar + Label `design-nachzug` + Status **Done** (Freigabe Akeshan, Chat 2026-07-07).
|
||||
|
||||
## Dev-Nachzug (nach Davids `D-P5`-Delta)
|
||||
|
||||
**Interim-UI (Vorschau, Stand 2026-07-07):** Alle vier Flächen aus `~/ui` gebaut (AD-28) —
|
||||
`apps/web/app/components/screens/integrations/{IntegrationsCatalogPage,ConnectionDetailPage,ConnectionCard,ConnectWizardDialog,SyncHistoryPage,SyncRunDetailPage}.tsx`.
|
||||
Proof: Smoke `tests/e2e/integrations.spec.ts`, Hot-Swap-Adapter `integrationsCatalog`
|
||||
(`packages/ui-app/src/adapters/integrationsCatalog.hot-swap.test.ts`) grün; Visual-Baseline deferred wie
|
||||
R-P2a/AK-P3/AK-P4b (keine Snapshot-Harness — Interim-Baseline wird beim David-Nachzug gezogen).
|
||||
Refactor-Nachzug offen: finale Subframe-Optik aus `D-P5` (Plane-Label `design-nachzug`).
|
||||
|
||||
- [ ] Katalog/Wizard/Connection-Card an Davids UI angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `R-P5` aktualisiert
|
||||
Reference in new issue
Block a user