Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VD-P32.md
T

115 lines
9.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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: