9.2 KiB
VD-P32 · Screens P32 — KWP-Setup (Integration)
| Typ | Screen (Design) |
| Owner | David (mit Akeshan — D-KWP) |
| Phase | P32 — KWP-Integration (v2-P5, Recut) · bedient VR-P32a/VR-P32b/VR-P32c |
| Cycle/Fenster | v2-W2 — KWP/Portal/Mobile-Start · 2026-07-20 → fällig 2026-07-26 |
| Status | geplant · design-nachzug offen; Interim-UI für VR-P32b/VR-P32d umgesetzt |
🎨 Design-Nachzug 2026-07-23: Der gemeinsame P32b/P32d-PR hat die nach AD-28 zulässige Interim-UI aus
~/uieinschließlich Visual-Baseline umgesetzt. Davids finale Subframe-Optik bleibt für Konflikt-/ Drift-Ansichten und den neuen gezielten Projektimport-Wizard offen; sie blockiert die Dev-DoD nicht.
🟢 Superseding Scope-Entscheidung 2026-07-22: Die initialen KWP-Screens bilden ausschließlich den read-only Connector und KWP→HiveGrid-Inbound-Sync ab. Es gibt keine UI-Aktion, die KWP mutiert. Writeback, Push-Queue und Project-/Auftrag-Create werden als geparkt / aktuell nicht verfügbar gekennzeichnet und extern in
VEXT-6nachgehalten; sie blockieren den read-only Design-Nachzug nicht. Historische Hinweise zum früheren Won→Auftrag-Ziel bleiben als Entscheidungsprotokoll erhalten.
🟢 CR-005 Design-Impact 2026-07-24: Die vollständige Adapterinventur erweitert keine Mutationsoberfläche. Sync-Log, Capability-Status und Contract-Diff müssen die fünf getrennten Bereiche Adresse, Aktivität, Archiv, Termin/Plantafel und Vorgang/Projekt darstellen können. Die 36 Mutation-Contracts bleiben unsichtbar beziehungsweise klar „nicht verfügbar“ und besitzen keine Aktion.
♻️ Löst Sammel-Ticket auf: Dieses Phasen-Ticket ersetzt — zusammen mit
VD-P22undVD-P28— das alte Sammel-TicketVD-5(„Public-API-Keys + Admin-Tiefe + KWP-Setup"). VD-P32 = der KWP-Setup-Anteil. 🟡 Vertragsstand 2026-07-12: KWP wird ein OAuth2/PKCE-Adapter über die Apps-Engine;kwpsync.exeund API-Key-Setup entfallen. Der Wizard startet mit Kundenkürzel/Relay-Auflösung und führt zum userbezogenen KWP-Login. Vertrag und Zugang sind vorhanden; offen bleiben Runtime-Scopes und der fehlende Endpoint für Won→Auftrag.
🟢 Mandanten-Verbindungsflow freigegeben 2026-07-21: Nach dem KWP-Login erhält der Wizard einen eigenen Schritt zur 1:1-Bindung des aktuellen HiveGrid-Tenants.
GET /api/Mandant/Loadwird bevorzugt zur Auswahl der erlaubten bnWin-Mandanten genutzt. Ein Treffer ist nur vorausgewählt und muss bestätigt werden; bei mehreren Treffern ist genau einer zu wählen. Ist die Discovery mit dem externen Client nicht erlaubt, muss die UI fail-closed zwischen der ausdrücklichen Bestätigung „kein bnWin-Mandant eingerichtet“ und der manuellen Eingabe des exakten Kürzels unterscheiden. Ein Fehler oder eine leere Liste darf nicht still als „kein Mandant“ gelten. Der Geerkens-Pilot bleibt auf den processweit vorprovisioniertenKWP_HIVEGRID_TENANT_IDbeschränkt; eine Mehr-Tenant-/Mehr-Kunden-Provisionierung gehört nicht zu diesem Design-Slice.
🟡 design-nachzug: offen (Stand 2026-07-22): Die frühere Revision
d4daa0421setzte die Connection nach einem fehlgeschlagenen Refresh aufbroken/integrations.health.refreshFailed. Der Haltbarkeits-Nachzug ist inzwischen als Revision2938f29daüber Deploy-Run10995auf Staging aktiv; geschützter Health-Probe, neun automatische Refresh-Rotationen und weitere automatische Health-Probes bliebenactiveund fehlerfrei. Er liefert strukturiertes Logger-Wiring, eindeutige replay-safe/ambiguous-Klassifikation, kein Provider-Replay eines möglicherweise verbrauchten Einmal-Tokens, ausschließlich lokale Persistenz-Retries und ein früherer KWP-Refresh-/Health-Gate. Das finale Design muss Claim, Retry, Recovered, diagnostischen Fehler und den erst nach Resource-Probe bestätigtenactive-Status unterscheidbar darstellen; diese Tokenzustände dürfen nicht wie Contract-Drift aussehen. VD-P32 bleibt als Design-Nachzug offen.
Abhängigkeiten & Parallelität
- Blocked by: D0-Baseline (
D-D0aApp-Shell,D-D0bArchetypen A2/A3/A5 + Diff-Ansicht) — Setup/Health/Log/Konflikt-Screens komponieren aus den D0-Archetypen; dockt am M33a-Interface an - Bedient (Dev):
VR-P32a(read-only Connector + Health, M089/090, 20.–22.07.),VR-P32b(Contract-Sentinel + Inbound-Konflikt „KWP gewinnt", 22.–24.07.),VR-P32c(read-only Inbound für Plantafel/Doku-Archiv/Task-ERP, 24.–26.07.) - Läuft parallel zu:
VD-P27(Mobile-PWA);VD-P26kann als separater, undatierter Design-Nachzug parallel laufen - Subframe: Pflicht je Route (A5/Wizard, A3/Status, A2, A5 + Diff, Banner)
Was wir bauen
Die KWP-Setup-/Betriebs-Oberflächen: OAuth2-Setup mit Kundenkürzel, dynamischer Relay-Auflösung und ausdrücklicher bnWin-Mandantenbindung für genau einen HiveGrid-Tenant, Connection-Health, read-only Inbound-Sync-Log, Konflikt-Resolution („KWP gewinnt" mit Snapshot-Diff + Audit-Restore), Contract-Drift-Banner und Admin-Sicht. Keine API-Key-Eingabe, kein fest konfigurierter Relay-Host und keine KWP-Mutationsaktion.
Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
|---|---|---|
KWP-Setup-Wizard [/integrations/kwp/setup] |
Kundenkürzel, Relay-Auflösung, OAuth2/PKCE-Login, bnWin-Mandanten laden/auswählen oder ausdrücklich „kein Mandant“ bestätigen, maskierter Token-/Scope-Status, Initial-Sync-Vorschau | A5/Wizard |
Connection-Health-View [/integrations/kwp] |
Verbindungsstatus (active, Claim, Retry, Recovered/Resource-Prüfung, broken), letzter Sync, Health-Probe, Re-Connect; Tokenzustände klar von Contract-Drift trennen |
A3/Status |
Sync-Log [/integrations/kwp/log] |
Read-only Inbound-Sync-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 |
Gezielter Projektimport [/{tenant}/settings/integrations/kwp/import] |
Suche ab zwei Zeichen, Treffer-/Detail-Diff, Status-Routing, Create/Link, drei CRM-Adressrollen, optional ein primärer Ansprechpartner je Rolle, Sync-/Ownership-Hinweise | A5/Wizard + Diff |
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 - Pro HiveGrid-Tenant genau eine bestätigte bnWin-Bindung: ausgewähltes Kürzel oder ausdrücklich
„kein Mandant“; Discovery mit manuellem fail-closed Fallback und eigener Darstellung für
unconfirmed - Capability-Vorschau kennzeichnet Writeback/„neuen Auftrag anlegen“ eindeutig als in
VEXT-6geparkt und aktuell nicht verfügbar; keine ausführbare Mutation - 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
- Read-only Plantafel-/Termin-Inbound + Dokumenten-Archiv-Inbound (Azure-Blob-Exchange →
@hivegrid/storage) - Read-only Task-/ERP-Inbound (M074)
- Gezielter Projektimport mit explizitem Create/Link, Status-Routing sowie Projekt-/Rechnungs-/ Bauherradresse; kein behaupteter Vollimport und kein automatisches Fuzzy-Merge
UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
Verbindungs-Setup-Wizard (Kundenkürzel → Relay gefunden → KWP-Login → bnWin-Mandant bestätigen;
maskierter Scope-/Token-Status); Mandanten-Auswahl für einen/mehrere Treffer; bewusste „kein Mandant“-Option;
manuelle Kürzeleingabe mit Klartext-Hinweis, wenn Discovery nicht berechtigt ist; eigener
unconfirmed-/abgelaufener-Auswahlzustand mit „Verbindung erneut starten“;
Initial-Sync-/Capability-Vorschau mit „Writeback geparkt, neuer Auftrag aktuell nicht verfügbar“ und Verweis
auf den externen Vertrag VEXT-6; Connection-Health mit letztem
Relay/Sync sowie getrennten Claim-/Retry-/Recovered-/Broken-Zuständen; Re-Connect; Sync-Log; Snapshot-basierte
Konflikt-Diff-Ansicht; Sync-Pausen-Banner; Admin-Tenant-Sync-Status; Contract-Diff/Freigabe;
Empty-/Loading-/Permission-Denied-States.
Quellen (granular)
designer-briefs/P32-kwp-integration.md(vollständiger Brief — diese Doc ist sein Ticket-Destillat)ENTITY-MODEL.md→ Domäne 4: Apps-Engine (M33a) +DataConnection/AppSyncItem- Plane-Snapshot: ersetzt Teil von
VD-5; bedientVR-P32a/VR-P32b/VR-P32c(v2-W2, 20.–26.07.)
Davids Delta (David füllt aus)
- Überschriebene/geänderte Spec-Punkte:
- Neue UI/UX-Entscheidungen:
- Subframe-Screen-Link(s):
- Offene Fragen an Dev: