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_modifiedin Responses? Versionierung/Changelog?) — geklärt inVEXT-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 anAppSyncItem.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): nutztAppSyncItem.rolledBackData(für den „KWP gewinnt"-Restore),AppSyncRun/AppSyncRunLog(Pause-Status),KwpErrorReport(Drift-/Konflikt-Einträge). Konflikt-Felder hängen anversion_hash/last_modifiedin 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
rolledBackDataarchiviert (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 gesetztemapp.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) — HauptquelleROADMAP.md→ Phase 32docs/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/7PHASE-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-P32baktualisiert