56 lines
6.0 KiB
Markdown
56 lines
6.0 KiB
Markdown
# 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 Legacy-Provider) 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. **KWP-Recut 2026-07-12:** KWP nutzt die OAuth2/PKCE-Variante mit Kundenkürzel und dynamischer Relay-Auflösung; kein API-Key-Feld und kein `kwpsync.exe`-Windows-Client-Flow. Die API-Key-Variante bleibt für andere Provider bestehen.
|
|
|
|
## 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`) · Milestones:
|
|
- 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:
|