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

6.1 KiB

D-P5 · Screens P5 — Apps-Engine & Integrations-Framework

⚠️ KI→MCP-Pivot (AD-26): Die KI-Kategorie im App-Katalog bleibt — sie ist jetzt der Andockpunkt für MCP-Server/künftige KI-Provider als reguläre DataConnection (HiveGrid hostet kein eigenes LLM, sondern wird MCP-Server, VR-MCP). Katalog-/Wizard-/Sync-UI unverändert.

Typ Screen (Design)
Owner David
Phase P5 — Apps-Engine & Integrations-Framework (bedient R-P5)
Cycle/Fenster W2 — Plattform & CRM (Demo 1) · fällig 2026-06-21 (Dev-Fenster 2026-06-20 → 21) · Gate W2
Status geplant (NEU — schließt P5-Screen-Lücke)

Abhängigkeiten & Parallelität

  • Blocked by: D-D0a (App-Shell), D-D0b (Archetypen A6 Settings + Connection-Kit + Connection-Card, A5 Modal/Wizard, A2 Liste)
  • Bedient (Dev): R-P5 (Apps-Engine / Adapter-Layer)
  • Liefert wiederverwendbare Komponenten: Connection-Card + Setup-Wizard + Sync-History sind das generische Framework, gegen das alle späteren App-Connections (P14 Email, P15 Telefonie, P16 Kalender/Signatur, P20 Stripe) registrieren — App-spezifische Setup-Teile kommen in den Modul-Phasen
  • Subframe: Pflicht je Route (A6 Settings/Connection-Kit, A5 Wizard, A2 Liste)

Was wir bauen

Die generische Katalog-/Wizard-/Sync-UI des einen typsicheren Integrations-Frameworks: App-Katalog, Connection-Verwaltung (mehrere Connections pro App pro Tenant), Connect-Wizard (OAuth2-Redirect und API-Key-Eingabe), Connection-Health-Monitoring mit Klartext-Diagnostik und Sync-History/-Detail. Recut-Hinweis: KWP = DataConnection type='rest-api' (API-Key) — kein kwpsync.exe-Windows-Client-Flow (v1-Connect-Typen in der UI: OAuth2 + API-Key; windows_client bleibt im Modell ohne UI).

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, Reconnect (bei degraded/broken), Disconnect, Sync-History-Liste (AppSyncRun mit Klartext-Summary) · mehrere Connections pro App (z. B. drei Gmail-Mailboxen, mit User-Label)
Connection-Setup-Wizard [Modal/Flow] Voraussetzungen-Check → Credential-Formular (auto-generiert aus connection_schema/JSON-Schema) → Validation/Health-Check → Initial-Sync-Option · OAuth2-Redirect-Variante + API-Key-Eingabe-Variante (mit Reveal-Toggle) 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 (Severity) A2 / A3

(Konkrete App-spezifische Setup-Komponenten → Modul-Phasen P14/P15/P16/P20. KWP-Sync-UI = v2/P32.)

Features (muss abgedeckt sein)

  • DataConnection per OAuth2-Connect ODER API-Key-Connect in der Settings-UI herstellbar
  • Connection-Health-Monitoring: Status active/degraded/broken/revoked/pending mit Klartext + Lösungs-Hinweisen
  • Sync-Protokollierung (AppSyncRun/AppSyncItem/AppSyncRunLog) mit Klartext-Summary („Sync mit KWP — 14 Aufträge gepullt, 2 fehlgeschlagen …")
  • Connect-Wizard (Voraussetzungen → auto-generiertes Credential-Formular → Validation → Initial-Sync); Reconnect (gleiche Connection-ID); Disconnect (Multi-Step-Confirm + Cleanup, Status revoked statt Hard-Delete)
  • Mehrere DataConnections pro App pro Tenant mit User-Label
  • Manueller Re-Sync mit Klartext-Progress; Schema-Drift/degraded/broken → Klartext-Banner mit Lösungs-Knopf
  • Permission-aware (integrations.read/.connect/.disconnect/.manual_sync/.view_logs/.admin)
  • Empty/Loading/Permission-Denied/Fehler-States (Klartext)

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); wiederverwendbare Connection-Card (App-Logo, Status-Ampel grün/gelb/rot/grau, Klartext-Status-Hinweis, letzte-Sync-Zeit, Buttons Verbinden/Re-Sync/Reconnect/Trennen) 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; 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; Status-/Klartext-Banner für degraded/broken/Schema-Drift mit Lösungs-Knopf; Empty-/Loading-/Permission-Denied-/Fehler-States.

Quellen (granular)

  • designer-briefs/P05-apps-engine-integrations-framework.md (vollständiger Brief — Recut KWP→v2)
  • ENTITY-MODEL.md → Domäne 4 (App, DataConnection, AppSyncRun, AppSyncRunLog, AppSyncItem)
  • ROADMAP.md → Phase 5 · REQUIREMENTS.md → Modul 33a (REQ-apps-engine-datenmodell, -apps-engine-lifecycle) · PHASE-SOURCES.md → Phase 5
  • _bmad-output/specs/M33a-apps-engine.md (⚠ Drei-Komponenten-/kwpsync.exe-Architektur ist NICHT zu bauen — Scope-Schnitt #12)
  • Dev-Pendant: ticket-docs/R-P5.md

Davids Delta (David füllt aus)

  • Überschriebene/geänderte Spec-Punkte:
  • Neue UI/UX-Entscheidungen:
  • Subframe-Screen-Link(s):
  • Offene Fragen an Dev: