Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,56 @@
# 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) | A6 + A2 |
| 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: