18 KiB
R-P5 · P5 Apps-Engine & Integrations-Framework
⚠️ KI→MCP-Pivot (AD-26): Die KI-App-Kategorie bleibt im Katalog. Da HiveGrid kein eigenes LLM/RAG mehr hostet, sondern MCP-Server wird (VR-MCP), ist diese Kategorie der Andockpunkt für MCP-Server und künftige KI-Provider als reguläre Apps-Engine-
DataConnection— kein Sonderbau. Framework selbst unverändert.
| Typ | Dev (Code) |
| 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 | 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) - Blocks:
R-P6(CRM nutzt das Framework später),AK-P14a(Email/OAuth),AK-P15a(Telefonie/AirCall),AK-P16a(Kalender/Signatur),EXT-08/09/10(App-spezifische Setups) - Läuft parallel zu: Akeshans
AK-P3(Querschnitts-Oberflächen) — Paar AK-P3 ‖ R-P5. Disjunkte Domänen (Apps-Engine vs. Audit/Notif-UI), eigeneprisma/schema/apps.prisma→ kein Schema-Konflikt (AD-21). Berührung nur Sidebar/Admin-Routen — additiv. - 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, 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) — keinkwpsync.exe-Windows-Client-Flow (Scope-Schnitt #12).windows_clientbleibt 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.
Benötigte Screens (Backend bedient — Design liefert D-P5 aus D-D0a/D-D0b)
| Screen [Route] | Kern-Inhalt | Liefert (Design) |
|---|---|---|
Integrations-Katalog [/admin/integrations] |
App-Karten nach Kategorie (ERP/Kommunikation/Kalender/Signatur/Payment/KI), Status-Ampel, Anzahl Connections, Suche/Filter | D-P5 (A6) |
App-Detail / Connection-Verwaltung [/admin/integrations/:app] |
Pro DataConnection: Status-Indikator, Klartext-Hinweis, letzter Sync, Re-Sync/Reconnect/Disconnect, Sync-History; mehrere Connections pro App | D-P5 (A6+A2) |
| Connection-Setup-Wizard [Modal/Flow] | Voraussetzungen → auto-generiertes Credential-Formular (aus connection_schema) → Validation/Health-Check → Initial-Sync; OAuth2-Redirect + API-Key-Reveal |
D-P5 (A5+A6) |
Sync-History / Run-Detail […/syncs, …/syncs/:id] |
AppSyncRun-Liste (Datum/kind/Status/items-Zähler/Summary) + Filter; Run-Detail mit AppSyncItem-Liste + Log | D-P5 (A2/A3) |
Davids P5-Screens über D-P5 (Compose aus D0; Connection-Card als wiederverwendbares Element).
Definition of Done
- DataConnection per OAuth2-Connect oder API-Key-Connect — Backend (createConnection: Adapter-Validierung + Envelope-Crypto) + funktionale Route-Action fertig; finale Wizard-Optik = Davids D-P5.
- Type-safe Adapter-Registry (Drift-Check → Klartext-Warnung) — neue Typen ohne Kern-Änderung
- AppSyncRun/AppSyncItem/AppSyncRunLog mit Klartext-Summary
- 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. - OAuth-Tokens per-Tenant-DEK-verschlüsselt (AD-8)
- Lifecycle: Connect / Reconnect (gleiche ID, kein History-Verlust) / Disconnect (Status revoked statt Hard-Delete) — Backend + Route-Actions; finale Wizard-Optik = D-P5.
- Mehrere DataConnections pro App pro Tenant (mit User-Label)
- Manueller Re-Sync + Schema-Drift-Sentinel + Webhook-Storm-Schutz (
triggerWebhookSyncviawithIdempotency) - Permissions:
integrations.read/.connect/.disconnect/.manual_sync/.view_logs/.admin - (→ 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.prismanur für Tenant-Relationen berühren (AD-21). - RLS auf
DataConnection/AppSyncRun/AppSyncItem;Appglobal ohne RLS (Definitions-Tabelle). - Per-Tenant-DEK-Verschlüsselung (AD-8) für OAuth-/API-Key-Credentials; DEK-Master-Key aus EXT-06.
- Konnektor
tenantHasModule()für Admin-Integrations-Routen. - Adapter-Registry = Build-Time-Scan + Drift-Check (Klartext-Warnung im Plattform-Admin P19).
is_demo_dataauf Demo-Connections (Onboarding).
Quellen (granular)
ENTITY-MODEL.md→ Domäne 4: Apps-Engine (App/DataConnection/AppSyncRun/AppSyncRunLog/AppSyncItem) + Cross-Cutting (DataConnection)REQUIREMENTS.md→REQ-apps-engine-datenmodell,REQ-apps-engine-lifecycleROADMAP.md→ Phase 5 ·PHASE-SOURCES.md→ Phase 5 (M008/M009/M010)designer-briefs/P05-apps-engine-integrations-framework.md_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
maingemergt. R-P5 lief über den gemeinsamen Branchfeat/AK-P17aund ging mit PR #5 (squash, Merge-Commitb0fae1af8, Basemain, 2026-06-28 17:50) aufmain. Nachzug-Fixpackages/integrations/package.jsonim 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 immain-Tree. Die älteren „Branch lokal, nicht gepusht"-Notizen unten sind damit überholt. Backend 9/9 DoD grün. Extern offen bleibt nur: DavidsD-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:
b5aa98bPer-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).aed2a8bSchema 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.51b6b59Permissions + Entitlements (DoD #9) —integrations.*+ Grants + DefaultPermissions-Union;integrations-Feature/Blueprint/Plan;tenantHasModule('integrations').50bb9ddAdapter-Registry + Drift (DoD #2) —IntegrationAdapter-Contract + Registry +checkCatalogDrift(foundation) + Katalog +sample-data-sync-Referenz-Adapter + Drift-Gate-Test.f2ea4d2Domain-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. PureaggregateSyncOutcomegetestet.0ab0f3aRLS-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 (inapps/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.52b6113VMs + 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).a49d998Webhook-Storm-Schutz (triggerWebhookSyncviawithIdempotency, 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:i18nExit 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 viausers/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), wiederverwendbareConnectionCard(Status-Ampel/Klartext/letzter Check/Re-Sync/Reconnect/Trennen),ConnectWizardDialog(echterDialogM 720 +StepperHorizontal: Voraussetzungen → auto-generiertes Credential-Formular ausconnection_schemamit 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 (ServicereconnectConnectionexistierte; 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.tsnachrolesList-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) + idempotentesApp-Upsert im SeedService (global, kein RLS; Tenant-Flow liest weiter den Code-Katalog,DataConnection.appIdbleibt 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-P5aktualisiert