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,57 @@
# VR-P32a · KWP: Connector + Health + Push-Queue (M089/090/091)
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Raffael |
| **Phase** | Phase 32 (v2-P5) — KWP-Integration (Recut) |
| **Cycle/Fenster** | v2-W2 — KWP/Portal/Mobile-Start · fällig 2026-07-22 |
| **Status** | geplant · 🟠 **block-2 (Partner-API offen, agil)** |
> 🟠 **block-2 — Partner-API offen, agil:** Der konkrete KWP-API-Vertrag (Auth/Endpoints/Webhook-Support/Rate-Limits/Versionierung/Doc-API) ist noch offen — **KWP-API-Zugang ~19./20.07.** ist der härteste Kalender-Anker (das v2-Hauptverkaufsargument). Detail-Planung pro Milestone erst gegen die echte API-Doku (→ `VEXT-1`). Bau startet, sobald der Zugang aktiv ist; Reihenfolge/Umfang sind agil. **`kwpsync.exe` wird NICHT gebaut** (3→2-Komponenten, Recut bindend, M089 obsolet als Windows-Client).
## Abhängigkeiten & Parallelität
- **Blocked by:** `R-P5` (v1-Apps-Engine M33a-Adapter-Interface `connect/disconnect/validateConnection/syncPull/syncPush/handleWebhook` — KWP ist der **erste konkrete Adapter** dahinter), `VEXT-1` (KWP-API-Zugang aktiv + Recut-Detailplanung gegen die echte Doku)
- **Blocks:** `VR-P32b` (Contract-Sentinel + Konflikt bauen auf Connector/Push-Queue auf)
- **Läuft parallel zu:** `VA-P26` (Customer-Portal, Akeshan) — beide W2, kein Schema-Konflikt: KWP nutzt die bestehende `appsEngine.prisma`-Domäne (App/DataConnection/AppSyncRun/AppSyncItem). Konnektor-Pflicht je Modul.
- **Konflikt-Risiko:** keines auf Schema-Ebene (Apps-Engine-Domäne bereits in v1).
## Was wir bauen
Den **KWP-API-Connector** als ersten konkreten Adapter hinter dem M33a-Interface, plus **Connection-Health** und die **Push-Queue**. KWP wird ein regulärer `rest-api`/`oauth2`-Adapter über die Apps-Engine — der „Kunde-vor-Ort"-Mittelteil (`kwpsync.exe`) entfällt. Credentials liegen **per-Tenant-DEK-verschlüsselt** in `DataConnection.config`. Health läuft über den **generischen M33a-Health-Probe** (statt Client-Heartbeat). Push (gewonnener Deal → Auftrag) läuft über **eine Cloud-Outbox + Rate-Limited-Replay** (kein lokales SQLite mehr), idempotent über `AppSyncItem`.
## Benötigte Screens (Backend bedient — Design liefert `D-P32`/Akeshan)
| Screen [Route] | Kern-Inhalt |
|---|---|
| KWP-Setup-Wizard [`/integrations/kwp/setup`] | OAuth/API-Key-Verbindung, Credential-Eingabe (DEK-verschlüsselt, maskiert), Initial-Sync-Vorschau |
| Connection-Health-View [`/integrations/kwp`] | Verbindungsstatus (verbunden/broken), letzter Sync, Health-Probe, Re-Connect |
| Sync-Log [`/integrations/kwp/log`] | Sync-Items (Push/Pull), Status, Zeit, `KwpErrorReport`-Einträge, Filter |
## Definition of Done
- [ ] **KWP-Connector** hinterm M33a-Adapter-Interface (erster konkreter Adapter); `kwpsync.exe` **NICHT** gebaut
- [ ] Credentials **per-Tenant-DEK** verschlüsselt in `DataConnection.config` (AD-8)
- [ ] **Connection-Health-Probe** (generisch, statt Heartbeat) + Re-Connect
- [ ] **Push-Queue** via Cloud-Outbox + **Rate-Limited-Replay** (Replay-Rate aus KWP-Rate-Limits), idempotent über `AppSyncItem`
- [ ] Push „Won→Auftrag" als Automation-Action (`kwp.push_auftrag`) andockbar
- [ ] DataConnection `type='rest-api'`/`'oauth2'` je nach realer KWP-Auth-Methode (aus VEXT-1)
## Technische Bausteine
- **Entities** (eigene `prisma/schema/appsEngine.prisma` — aus v1 übernommen, AD-21): `App{type:"kwp"}`, `DataConnection{type:"rest-api"|"oauth2", config:<DEK-verschlüsselt>, connection_status, last_health_check}`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` (`entity_type`/`id` HiveGrid ↔ `external_id`, `operation`, `status` — inkl. `rolledBackData` für den M093-Restore in VR-P32b). `KwpErrorReport` für Sync-Log-Fehler.
- **DataConnection `rest-api`:** KWP-Creds verschlüsselt in `config` (Per-Tenant-DEK). ⚠ Spec-19.1.2 („Creds verlassen Kundennetz nie") gilt bei API-Anbindung **nicht mehr 1:1** — Creds liegen jetzt verschlüsselt in der Cloud → Vermerk in AVV/Subprozessoren (M166/VR-P31) weiterreichen.
- **Konnektor:** `tenantHasModule('kwp_integration')` (`SubscriptionFeature.code = kwp_integration`) gated die Integration komplett.
- **Outbox:** v1-Cloud-Outbox + Idempotency-Wrapper (M007) — eine Queue, Rate-Limited-Replay; **kein** lokales SQLite.
- **Health-Probe:** generischer M33a-Health-Probe (`validateConnection`), nicht der alte 5-min-Client-Heartbeat.
- **`is_demo_data`:** Demo-DataConnection (Test-/Sandbox-KWP) seedbar, beim Echt-Start löschbar.
## Quellen (granular)
- `ROADMAP-V2.md` → §v2-P5 (Success-Criteria 1/2, Setup/Health/Log-Screens) — **Hauptquelle**
- `ROADMAP.md` → Phase 32
- **`docs/milestones/M19-KWP-API-RECUT.md` (bindend)** → M089 (Connector), M090 (Health vereinfacht), M091 (eine Cloud-Outbox), Übernahme-Liste `appsEngine.prisma`, offene Vertrags-Fragen 1/4
- `PHASE-SOURCES.md` → Phase 32 (M089/090/091; Block-2-Hinweis: Partner-API offen, agil; Callback-URL `…/integrations/kwp/oauth/callback` in v1 gemeldet, OAuth Auth-Code + PKCE, Tenant im `state`)
- `ENTITY-MODEL.md` → Domäne 7 Apps-Engine (App/DataConnection/AppSyncItem), `ProjektExternesFeld` [v2] (KWP-Felder)
- `designer-briefs/P32-kwp-integration.md` (Setup/Health/Log-Screens, Recut-Sonderfall)
- `_bmad-output/specs/M19-kwp-integration.md`
## Dev-Nachzug (nach Davids `D-P32`-Delta + Recut-Detailplanung VEXT-1)
- [ ] Spec/ENTITY-MODEL an reale KWP-API + Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] Plane-Ticket `VR-P32a` aktualisiert