Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,52 @@
|
||||
# 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)
|
||||
**Quellen:** `ROADMAP.md` §Phase 5 · `SCREEN-MAP.md` §2-Anhang (Integrations-Katalog / Connection-Setup-Wizard) · `REQUIREMENTS.md` Modul 33a (REQ-apps-engine-datenmodell, -apps-engine-lifecycle) · `ENTITY-MODEL.md` Domäne 4 (App, DataConnection, AppSyncRun, AppSyncRunLog, AppSyncItem) · `_bmad-output/specs/M33a-apps-engine.md`
|
||||
**Subframe:** Pflicht je Route. Archetypen aus D0 (A6 Settings/Connection-Kit + Connection-Card, A5 Modal/Wizard, A2 Liste).
|
||||
|
||||
> ⚙️ **Recut-Hinweis (KWP → v2):** KWP wird als `DataConnection type='rest-api'` (API-Key-Connect) abgebildet — **kein `kwpsync.exe`-Windows-Client-Flow** (Scope-Schnitt #12; die alte Drei-Komponenten-Architektur aus der M33a-Spec ist NICHT zu bauen). Connection-Type `windows_client` bleibt im Daten-Modell, hat in v1 aber keinen UI-Flow. v1-Connect-Typen in der UI: **OAuth2** (Gmail, Outlook, AirCall, PandaDoc, Google Calendar) und **API-Key** (KWP, Stripe). Apps selbst werden erst in ihren Modul-Phasen (P14/P15/P16/P20) angedockt — P5 liefert das Framework + die generische Katalog-/Wizard-UI, gegen die sich alle Connections registrieren.
|
||||
|
||||
## 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, 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; `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) ODER API-Key-Connect (KWP, Stripe) 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 = rest-api-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/PHASE-SOURCES nachgezogen:
|
||||
- [ ] Plane-Ticket (R-P5) aktualisiert:
|
||||
Reference in new issue
Block a user