6.0 KiB
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.exewird NICHT gebaut (3→2-Komponenten, Recut bindend, M089 obsolet als Windows-Client).🟢 Update 2026-06-25 — Zugang eingetroffen (früher): Auth-Frage geklärt →
type='oauth2'(Keycloak-OIDCkwp-federated, Auth-Code + PKCE/S256, Confidential Client +offline_access/Refresh; Multi-Tenant übertenant-Param + ClientId/Secret je Mandant). Resource-API = RPC-artige Action-API, basePath/relay/kwp3/pwa(Swagger…/swagger/v1/swagger.json). Endpoint-/Webhook-/Rate-Limit-Details +Vorgang/Termin/Archivlaufen weiter inVEXT-1(Spike). Bleibt v2;blocked-by R-P5(M33a-Interface) unverändert.
Abhängigkeiten & Parallelität
- Blocked by:
R-P5(v1-Apps-Engine M33a-Adapter-Interfaceconnect/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 bestehendeappsEngine.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.exeNICHT 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='oauth2'(geklärt 2026-06-25: Keycloak-OIDC Auth-Code + PKCE, Confidential Client +offline_access)
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/idHiveGrid ↔external_id,operation,status— inkl.rolledBackDatafür den M093-Restore in VR-P32b).KwpErrorReportfür Sync-Log-Fehler. - DataConnection
rest-api: KWP-Creds verschlüsselt inconfig(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) — HauptquelleROADMAP.md→ Phase 32docs/milestones/M19-KWP-API-RECUT.md(bindend) → M089 (Connector), M090 (Health vereinfacht), M091 (eine Cloud-Outbox), Übernahme-ListeappsEngine.prisma, offene Vertrags-Fragen 1/4PHASE-SOURCES.md→ Phase 32 (M089/090/091; Block-2-Hinweis: Partner-API offen, agil; Callback-URL…/integrations/kwp/oauth/callbackin v1 gemeldet, OAuth Auth-Code + PKCE, Tenant imstate)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-P32aaktualisiert