4.4 KiB
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.exewird 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-6geparkt. 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: