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

6.4 KiB

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
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: