Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/designer-briefs/P32-kwp-integration.md
T

4.2 KiB
Raw Blame History

Designer-Brief · P32 — KWP-Integration (Recut)

Phase: 32/34 · Modul: M19 (M089–M095, M074) · Owner-Dev: Raffael (VR-P32a–c) · Designer: David/Akeshan (D-KWP) Quellen: ROADMAP-V2.md §v2-P5 · ROADMAP.md §Phase 32 · _bmad-output/specs/M19-kwp-integration.md + docs/milestones/M19-KWP-API-RECUT.md (bindend) Subframe: Pflicht je Route. Backend-lastig, aber Setup-/Health-/Sync-Log-/Konflikt-Screens existieren.

🔴 Recut-Sonderfall (Block 2): KWP wird regulärer REST/OAuth-Adapter über die Apps-Engine (M33a) — kwpsync.exe wird NICHT gebaut (3→2-Komponenten). Offizielle KWP-REST/OAuth-API. ⚠ Größter Blocker: der konkrete KWP-API-Vertrag (Auth/Endpoints/Webhook-Support/Rate-Limits/Versionierung/Doc-API) ist noch offen — Zugang ~20.07. ist der härteste Kalender-Anker; Detail-Planung pro Milestone braucht den Vertrag. Backend-lastige Phase, aber mit klar umrissenen Setup-/Health-/Log-/Konflikt-Oberflächen.

Was dieses Modul tut (Kurzfassung)

Bindet KWP als ersten konkreten Adapter hinter dem M33a-Interface an und spiegelt bidirektional: Push (gewonnener Deal → Auftrag) via Cloud-Outbox + rate-limited Replay, Pull via Webhook (falls KWP unterstützt) oder Cron, idempotent über AppSyncItem. Credentials liegen per-Tenant-DEK-verschlüsselt in DataConnection.config. Konflikte lösen sich nach „KWP gewinnt" (LWW mit Audit-Restore) plus HiveGrid-seitigem Optimistic Locking. Ein API-Contract-Sentinel (zod-Validierung + Versions-Check) pausiert den Sync bei Drift und alarmiert den Plattform-Admin. Plantafel- und Dokumenten-Archiv-Sync laufen über die API.

Benötigte Screens

Screen [Route] Kern-Inhalt Archetyp
KWP-Setup-Wizard [/integrations/kwp/setup] OAuth/API-Key-Verbindung, Credential-Eingabe (DEK-verschlüsselt), Initial-Sync-Vorschau A5/Wizard
Connection-Health-View [/integrations/kwp] Verbindungsstatus (verbunden/broken), letzter Sync, Health-Probe, Re-Connect A3/Status
Sync-Log [/integrations/kwp/log] Sync-Items (Push/Pull), Status, Zeit, KwpErrorReport-Einträge, Filter A2
Konflikt-Resolution [/integrations/kwp/conflicts] Konflikt-Paare (HiveGrid vs. KWP), Feld-Diff, „KWP gewinnt"-Anzeige + Audit-Restore A5 + Diff
Tenant-UI Sync-Pausen-Hinweis [Banner] Klartext bei Contract-Drift: „KWP-Update erkannt — Sync pausiert für Sicherheit. Wir sind informiert." Banner
Admin: KWP-Sync-Status pro Tenant [admin.hivegrid.de/integrations/kwp] Sync-Status je Tenant, Contract-Diff-Tool, Sync-Freigabe nach Adapter-Update A2 + A3

Geplante Features (muss abgedeckt sein)

  • KWP-API-Connector als erster konkreter Adapter hinterm M33a-Interface; kwpsync.exe NICHT bauen
  • Credentials per-Tenant-DEK-verschlüsselt in DataConnection.config
  • Bidirektionaler Sync: Push (Won→Auftrag) via Outbox + rate-limited Replay; Pull via Webhook/Cron, idempotent über AppSyncItem
  • Konflikt „KWP gewinnt" (LWW mit Audit-Restore) + Optimistic Locking HiveGrid-seitig
  • API-Contract-Sentinel (zod-Validierung + Versions-Check) pausiert Sync bei Drift + alarmiert Plattform-Admin
  • Plantafel-Sync + Dokumenten-Archiv-Sync (KWP-Doc → Storage) über die API
  • Task-ERP-Sync (M074)

Benötigte UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)

Verbindungs-Setup-Wizard (OAuth/API-Key-Eingabe, maskierte Credentials), Initial-Sync-Vorschau (was wird gespiegelt), Connection-Health-Statusanzeige (Ampel + letzter Heartbeat/Sync), Re-Connect-Button, Sync-Log-Tabelle (Push/Pull-Richtung, Status, Fehler-Report-Aufklappen), Konflikt-Diff-Ansicht (Feld-für-Feld HiveGrid vs. KWP, „KWP gewinnt"-Markierung, Restore-Aktion), Sync-Pausen-Banner (Klartext, Kontakt-Hinweis), Admin-Tenant-Sync-Statusliste, Contract-Diff-Tool, Sync-Freigabe-Aktion, Empty-/Loading-/Permission-Denied-States (Klartext).

Davids Delta (David füllt aus)

  • Überschriebene/geänderte Spec-Punkte:
  • Neue UI/UX-Entscheidungen:
  • Subframe-Screen-Link(s):
  • Offene Fragen an Dev:

Dev-Nachzug (wir nach Davids Delta)

  • Spec/ENTITY-MODEL an Davids Entscheidungen angepasst:
  • REQUIREMENTS/PHASE-SOURCES nachgezogen:
  • Plane-Ticket (VR-P32a–c) aktualisiert: