Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VR-P32a.md
T
2026-07-08 16:15:37 +02:00

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.exe wird 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-OIDC kwp-federated, Auth-Code + PKCE/S256, Confidential Client + offline_access/Refresh; Multi-Tenant über tenant-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/Archiv laufen weiter in VEXT-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-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='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/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