62 lines
4.4 KiB
Markdown
62 lines
4.4 KiB
Markdown
# 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:
|