6.0 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 | geplant |
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, 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).
⚙️ 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 (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)
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)
Dev-Nachzug (nach Davids D-P5-Delta)
- Katalog/Wizard/Connection-Card an Davids UI angepasst
- REQUIREMENTS/PHASE-SOURCES nachgezogen
- Plane-Ticket
R-P5aktualisiert