115 lines
9.2 KiB
Markdown
115 lines
9.2 KiB
Markdown
# 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
|
||
> `~/ui` einschließ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-6` nachgehalten; 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-P22` und `VD-P28` — das alte Sammel-Ticket **`VD-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.exe` und 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/Load` wird 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 vorprovisionierten
|
||
> `KWP_HIVEGRID_TENANT_ID` beschrä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 `d4daa0421` setzte die Connection
|
||
> nach einem fehlgeschlagenen Refresh auf `broken` / `integrations.health.refreshFailed`. Der
|
||
> Haltbarkeits-Nachzug ist inzwischen als Revision `2938f29da` über Deploy-Run `10995` auf Staging aktiv;
|
||
> geschützter Health-Probe, neun automatische Refresh-Rotationen und weitere automatische Health-Probes
|
||
> blieben `active` und 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ätigten `active`-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-D0a` App-Shell, `D-D0b` Archetypen 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-P26` kann 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-6` geparkt 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`; bedient `VR-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:
|