Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/ticket-docs/R-P5.md
T

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), eigene prisma/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) — 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.

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.prisma nur für Tenant-Relationen berühren (AD-21).
  • RLS auf DataConnection/AppSyncRun/AppSyncItem; App global 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_data auf 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-lifecycle
  • ROADMAP.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-P5 aktualisiert