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

4.4 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) Aktive Quellen: zugehörige Ticket-Docs · ROADMAP.md/ROADMAP-V2.md · REQUIREMENTS.md · ENTITY-MODEL.md. Subframe: Pflicht je Route. Backend-lastig, aber Setup-/Health-/Sync-Log-/Konflikt-Screens existieren.

🔴 Recut-Sonderfall (Block 2): KWP wird regulärer REST/OAuth2-Adapter über die Apps-Engine (M33a) — kwpsync.exe wird NICHT gebaut (3→2-Komponenten). Discovery, dynamische Relay-Auflösung, tenant-spezifischer OpenAPI-Vertrag, beide Redirects sowie Auth-/Resource-/Refresh-Dauerbetrieb sind verifiziert. Kontrollierte fachliche Inbound-Testdaten bleiben offen; Project-/Auftrag-Create gehört ausschließlich zum geparkten Writeback. Backend-lastige Phase, aber mit klar umrissenen Setup-/Health-/Log-/Konflikt-Oberflächen.

🟢 Initialer Read-only-Scope (CR-003/AD-32, 2026-07-22): Die aktuelle KWP-Oberfläche bietet keine schreibende Aktion. Writeback, Push-Queue und Auftragserstellung sind hinter VEXT-6 geparkt. Das Design darf sie nur als „nicht verfügbar / später nach KWP-Freigabe“ erklären, niemals als ausführbaren Button.

Was dieses Modul tut (Kurzfassung)

Bindet KWP als ersten konkreten Adapter hinter dem M33a-Interface an. Der initiale Ausbau liest ausschließlich aus KWP: Pull läuft per Cron, weil die Tenant-OpenAPI keine Webhooks dokumentiert, und bleibt über AppSyncItem idempotent. Konflikte folgen „KWP gewinnt" mit HiveGrid-Snapshot + Audit-Restore, da KWP keine einheitlichen Versionsfelder liefert. Ein API-Contract-Sentinel pausiert den Pull bei Drift. Archivdateien laufen über den dokumentierten Azure-Blob-exchangeFileUri-Austausch in @hivegrid/storage.

Benötigte Screens

Screen [Route] Kern-Inhalt Archetyp
KWP-Setup-Wizard [/integrations/kwp/setup] Kundenkürzel + OAuth2/PKCE-Verbindung, verschlüsselter Token-Status, 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] Pull-Items, 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.credentialsCiphertext
  • Pull zunächst per Cron, idempotent über AppSyncItem; Webhook nur nach separater KWP-Bestätigung
  • Konflikt „KWP gewinnt" mit HiveGrid-Snapshot + Audit-Restore; keine einheitlichen KWP-Versionsfelder voraussetzen
  • API-Contract-Sentinel (OpenAPI-Fingerprint + endpoint-spezifische Response-Validierung) pausiert Sync bei Drift + alarmiert Plattform-Admin
  • Plantafel-Spiegelung KWP→HiveGrid + Dokumenten-Archiv-Sync (Azure-Blob-Exchange → @hivegrid/storage)
  • Task-ERP-Spiegelung KWP→HiveGrid (M074)

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

Verbindungs-Setup-Wizard (Kundenkürzel, OAuth2/PKCE-Start, maskierter Token-Status; kein API-Key-Feld), aufgelöstes Relay-Ziel, Runtime-Scope-/Capability-Anzeige, Initial-Pull-Vorschau mit Klartext „Schreiben nach KWP ist derzeit nicht verfügbar", Connection-Health-Statusanzeige, Re-Connect-Button, Pull-Log-Tabelle, Konflikt-Diff-Ansicht, Sync-Pausen-Banner, Admin-Tenant-Sync-Statusliste, Contract-Diff-Tool, Sync-Freigabe-Aktion sowie Empty-/Loading-/Permission-Denied-States.

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/ROADMAP nachgezogen:
  • Plane-Ticket (VR-P32a–c) aktualisiert: