Files

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