Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/ticket-docs/VR-P32b.md
T

4.7 KiB

VR-P32b · KWP: Contract-Sentinel + Konflikt 'KWP gewinnt' (M092/093)

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-24
Status geplant · 🟠 block-2 (Partner-API offen, agil)

🟠 block-2 — Partner-API offen, agil: Versions-Check und Konflikt-Felder hängen am realen KWP-API-Vertrag (liefert KWP version_hash/last_modified in Responses? Versionierung/Changelog?) — geklärt in VEXT-1. Umfang von M092 hängt davon ab, ob KWP eine eigenständige Versionierung hat oder ob der Sentinel in den Connector (M089) integriert werden kann. Agil, sobald der Vertrag steht.

Abhängigkeiten & Parallelität

  • Blocked by: VR-P32a (Connector + Push-Queue — Sentinel hängt an den API-Responses, Konflikt-Restore an AppSyncItem.rolledBackData)
  • Blocks: VR-P32c (Plantafel/Doku/Task-Sync nutzen die abgesicherte Sync-Schicht)
  • Läuft parallel zu: VA-P26/VA-P27 (Portal/Mobile, Akeshan) — kein Schema-Konflikt (Apps-Engine-Domäne).
  • Konflikt-Risiko: keines auf Schema-Ebene.

Was wir bauen

Die Schutz- und Konfliktschicht des KWP-Sync. Ein API-Contract-Sentinel (zod-Response-Validierung + Versions-Check) pausiert den Sync bei Drift und alarmiert den Plattform-Admin (statt fehlerhaft weiter zu syncen). Die Konflikt-Regel „KWP gewinnt" (Last-Write-Wins mit Audit-Restore über rolledBackData) löst Daten-Kollisionen deterministisch, ergänzt um HiveGrid-seitiges Optimistic Locking. Im Recut bleibt M093 transport-unabhängig unverändert; M092 wird vom täglichen MSSQL-Schema-Hash-Diff zur leichteren zod-Response-Validierung.

Benötigte Screens (Backend bedient — Design liefert D-P32/Akeshan)

Screen [Route] Kern-Inhalt
Konflikt-Resolution [/integrations/kwp/conflicts] Konflikt-Paare (HiveGrid vs. KWP), Feld-Diff, „KWP gewinnt"-Anzeige + Audit-Restore
Tenant-UI Sync-Pausen-Hinweis [Banner] Klartext bei Contract-Drift: „KWP-Update erkannt — Sync pausiert für Sicherheit. Wir sind informiert."
Admin: KWP-Sync-Status pro Tenant [admin.hivegrid.de/integrations/kwp] Sync-Status je Tenant, Contract-Diff-Tool, Sync-Freigabe nach Adapter-Update

Definition of Done

  • API-Contract-Sentinel (zod-Validierung der Responses + Versions-Check) pausiert Sync bei Drift + Plattform-Admin-Alarm
  • Konflikt „KWP gewinnt" (LWW + Audit-Restore über rolledBackData)
  • Optimistic Locking HiveGrid-seitig (version/updated_at-Guard bei Writes)
  • Tenant-Banner bei Drift (Klartext, Kontakt-Hinweis) + Admin Contract-Diff + Sync-Freigabe nach Adapter-Update

Technische Bausteine

  • Entities (prisma/schema/appsEngine.prisma, AD-21): nutzt AppSyncItem.rolledBackData (für den „KWP gewinnt"-Restore), AppSyncRun/AppSyncRunLog (Pause-Status), KwpErrorReport (Drift-/Konflikt-Einträge). Konflikt-Felder hängen an version_hash/last_modified in KWP-Responses (aus VEXT-1).
  • Contract-Sentinel: zod-Schema je KWP-Endpoint validiert jede Response; bei Mismatch oder Versions-Sprung → Sync auf paused + Admin-Alarm + Tenant-Banner; Freigabe erst nach Adapter-Update durch Plattform-Admin.
  • Konflikt 'KWP gewinnt' (transport-unabhängig, M093): bei Kollision gewinnt der KWP-Wert (LWW); der überschriebene HiveGrid-Wert wird in rolledBackData archiviert (Audit-Restore möglich). HiveGrid-seitige Writes nutzen Optimistic Locking gegen Lost-Updates.
  • RLS: Konflikt-/Sentinel-Daten Tenant-bezogen (app.tenant_id); Admin liest cross-tenant via RLS mit gesetztem app.tenant_id (kein BYPASSRLS, konsistent mit VR-P28a).
  • Konnektor: tenantHasModule('kwp_integration').
  • is_demo_data: ggf. Demo-Konflikt-Daten seedbar.

Quellen (granular)

  • ROADMAP-V2.md → §v2-P5 (Success-Criteria 3/4, Konflikt-/Banner-/Admin-Screens) — Hauptquelle
  • ROADMAP.md → Phase 32
  • docs/milestones/M19-KWP-API-RECUT.md (bindend) → M092 (API-Contract-Sentinel, zod + Versions-Check, ggf. in M089), M093 (Konflikt unverändert, transport-unabhängig), rolledBackData-Hinweis, offene Vertrags-Fragen 5/7
  • PHASE-SOURCES.md → Phase 32 (M092/093; Block-2)
  • ENTITY-MODEL.md → Domäne 7 Apps-Engine (AppSyncItem.rolledBackData), ProjektExternesFeld [v2] („KWP gewinnt")
  • designer-briefs/P32-kwp-integration.md (Konflikt-Diff, Sync-Pausen-Banner, Admin-Contract-Diff)
  • _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-P32b aktualisiert