Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/designer-briefs/P05-apps-engine-integrations-framework.md
T

54 lines
6.4 KiB
Markdown

# Designer-Brief · P5 — Apps-Engine & Integrations-Framework
**Phase:** 5/21 · **Modul:** M33a (Apps-Engine / Adapter-Layer) · **Owner-Dev:** Raffael (R-P5) · **Designer:** David (D-P5)
**Aktive Quellen:** zugehörige Ticket-Docs · `ROADMAP.md`/`ROADMAP-V2.md` · `REQUIREMENTS.md` · `ENTITY-MODEL.md`.
**Subframe:** Pflicht je Route. Archetypen aus D0 (A6 Settings/Connection-Kit + Connection-Card, A5 Modal/Wizard, A2 Liste).
🖥️ **Interim-UI gebaut (AD-28):** lauffähige Screen-Referenz + genutzte Elemente/VM/Actions in `../HiveGrid-Wireframes/Tickets/Interim-Handover/P05-Integrations.md`. Layout bleibt frei.
> ⚙️ **Recut-Hinweis (KWP → v2, aktualisiert 2026-07-12):** KWP wird als `DataConnection type='oauth2'` (Authorization Code + PKCE, Kundenkürzel + dynamische Relay-Auflösung) abgebildet — **kein `kwpsync.exe`-Windows-Client-Flow und kein KWP-API-Key-Setup**. Connection-Type `windows_client` bleibt im Daten-Modell, hat in v1 aber keinen UI-Flow. Generische Connect-Typen in der UI bleiben **OAuth2** und **API-Key**; die KWP-spezifischen Felder kommen in P32.
## Was dieses Modul tut (Kurzfassung)
Bindet externe Systeme über ein einziges, typsicheres Integrations-Framework an — der Vertrag, über den später Gmail, Outlook, AirCall, PandaDoc, 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; `AppSyncRun`/`AppSyncItem` protokollieren Sync-Läufe in Klartext; Connection-Health-Monitoring zeigt den Status jeder Verbindung (active/degraded/broken/revoked/pending) mit Klartext-Diagnostik + Lösungs-Hinweisen; OAuth-Tokens sind per-Tenant-DEK-verschlüsselt (AD-8). Mehrere Connections pro App pro Tenant möglich (z. B. drei Gmail-Mailboxen).
## Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
|---|---|---|
| Integrations-Katalog [`/admin/integrations`] | App-Karten nach Kategorie (ERP / Kommunikation / Kalender / Signatur / Payment / KI) · je App: Logo, Beschreibung, Status-Ampel, Anzahl aktive Connections · Suche + Filter (Kategorie/Status/Phase) | A6 |
| App-Detail / Connection-Verwaltung [`/admin/integrations/:app`] | Pro DataConnection: Status-Indikator (grün active / gelb degraded / rot broken / grau revoked|pending), Klartext-Status-Hinweis, letzter Sync-Zeitpunkt, Re-Sync-Funktion, Reconnect (bei degraded/broken), Disconnect, Sync-History-Liste (AppSyncRun mit Klartext-Summary) · mehrere Connections pro App | A6+A2 |
| Connection-Setup-Wizard [Modal/Flow] | Voraussetzungen-Check → Credential-Formular (auto-generiert aus `connection_schema`) → Validation/Health-Check → Initial-Sync-Option · OAuth2-Redirect-Variante + API-Key-Eingabe-Variante (mit Reveal) | A5+A6 |
| Sync-History / Sync-Run-Detail [`…/syncs`, `…/syncs/:id`] | Liste der AppSyncRuns (Datum, kind pull/push/webhook/manual, Status, items_total/succeeded/failed, Klartext-Summary) · Filter (Datum/Status/Operation) · Run-Detail mit AppSyncItem-Liste (entity↔external_id, operation, Status, Klartext-Fehler) + AppSyncRunLog | A2/A3 |
*(Konkrete App-spezifische Setup-Komponenten = in den Modul-Phasen P14/P15/P16/P20. KWP-Sync-UI = v2/P32.)*
## Geplante Features (muss abgedeckt sein)
- [ ] DataConnection per OAuth2-Connect-Flow (Gmail, Outlook, AirCall, PandaDoc, Google Calendar, KWP) ODER API-Key-Connect (Legacy-Provider) in der Settings-UI herstellbar
- [ ] Type-safe Adapter-Registry: neue Connection-Typen ohne Kern-Änderung registrierbar (Build-Time-Scan von `app/integrations/`, Drift-Check → Klartext-Warnung im Plattform-Admin)
- [ ] AppSyncRun/AppSyncItem/AppSyncRunLog protokollieren Sync-Läufe mit Klartext-Summary („Sync mit KWP — 14 Aufträge gepullt, 2 fehlgeschlagen …")
- [ ] Connection-Health-Monitoring: Status active/degraded/broken/revoked/pending mit Klartext + Lösungs-Hinweisen; Health-Check-Intervalle; Recovery-Klartext
- [ ] OAuth-Tokens per-Tenant-DEK-verschlüsselt gespeichert (AD-8); Token-Refresh-Worker; degraded/broken → Klartext-Notification an Tenant-Admin (via notify())
- [ ] Lifecycle: Connect-Wizard (Voraussetzungen → auto-generiertes Credential-Formular → Validation → Initial-Sync), Reconnect (gleiche Connection-ID, kein History-Verlust), Disconnect (Multi-Step-Confirm + Cleanup, Status revoked statt Hard-Delete)
- [ ] Mehrere DataConnections pro App pro Tenant (z. B. drei Gmail-Mailboxen, mit User-Label)
- [ ] Manueller Re-Sync mit Klartext-Progress; Schema-Drift-Sentinel → degraded + Klartext; Webhook-Storm-/Anomalie-Schutz (Backend, prägt Status-UX)
- [ ] Permissions: integrations.read / .connect / .disconnect / .manual_sync / .view_logs / .admin
- [ ] *(→ v2)* ~~kwpsync.exe-Windows-Client-Setup-Flow~~ — KWP = OAuth2/PKCE-Connection; Community-/Template-Marketplace = Phase 2/3
## Benötigte UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
App-Katalog als Karten-Grid gruppiert nach Kategorie, je Karte App-Logo + Beschreibung + Status-Ampel + Anzahl-aktive-Connections, Such-Feld + Filter (Kategorie/Status/Phase); Connection-Card (App-Logo, Status-Ampel grün/gelb/rot/grau, Klartext-Status-Hinweis, letzte-Sync-Zeit, Buttons Verbinden/Re-Sync/Reconnect/Trennen) — als wiederverwendbares Element für mehrere Connections pro App; Setup-Wizard (mehrstufig, Progress) mit Voraussetzungen-Check-Schritt, auto-generiertem Credential-Formular aus JSON-Schema (Text-/Key-/Secret-Felder mit Reveal-Toggle), OAuth2-Redirect-Trigger-Variante, Validation-/Health-Check-Schritt, optionalem Initial-Sync-Schritt; Disconnect-Bestätigungs-Dialog (Multi-Step, Klartext „Beim Trennen werden alle Sync-Jobs gestoppt …"); Sync-History-Liste (Datum/kind/Status/items-Zähler/Klartext-Summary) mit Filter nach Datum/Status/Operation; Sync-Run-Detail mit AppSyncItem-Tabelle (entity↔external_id, operation, Status, Klartext-Fehler) + Log-Einträgen mit Severity; manueller Re-Sync-Trigger mit Klartext-Progress-Anzeige bei langen Läufen; Status-/Klartext-Banner für degraded/broken/Schema-Drift mit Lösungs-Knopf (Reconnect/Anleitung); Empty-/Loading-/Permission-Denied-/Fehler-States (Klartext).
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
- [ ] Neue UI/UX-Entscheidungen:
- [ ] Subframe-Screen-Link(s):
- [ ] Offene Fragen an Dev:
## Dev-Nachzug (wir nach Davids Delta)
- [ ] Spec/ENTITY-MODEL an Davids Entscheidungen angepasst:
- [ ] REQUIREMENTS/ROADMAP nachgezogen:
- [ ] Plane-Ticket (R-P5) aktualisiert: