# 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