Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,55 @@
|
||||
# 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
|
||||
Reference in new issue
Block a user