# 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