Files

50 lines
4.2 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)
**Quellen:** `ROADMAP-V2.md` §v2-P5 · `ROADMAP.md` §Phase 32 · `_bmad-output/specs/M19-kwp-integration.md` + **`docs/milestones/M19-KWP-API-RECUT.md` (bindend)**
**Subframe:** Pflicht je Route. Backend-lastig, aber Setup-/Health-/Sync-Log-/Konflikt-Screens existieren.
> 🔴 **Recut-Sonderfall (Block 2):** KWP wird regulärer **REST/OAuth-Adapter über die Apps-Engine (M33a)** — **`kwpsync.exe` wird NICHT gebaut** (3→2-Komponenten). Offizielle KWP-REST/OAuth-API. ⚠ **Größter Blocker:** der konkrete KWP-API-Vertrag (Auth/Endpoints/Webhook-Support/Rate-Limits/Versionierung/Doc-API) ist noch offen — Zugang ~20.07. ist der härteste Kalender-Anker; Detail-Planung pro Milestone braucht den Vertrag. Backend-lastige Phase, aber mit klar umrissenen Setup-/Health-/Log-/Konflikt-Oberflächen.
## Was dieses Modul tut (Kurzfassung)
Bindet KWP als ersten konkreten Adapter hinter dem M33a-Interface an und spiegelt bidirektional: Push (gewonnener Deal → Auftrag) via Cloud-Outbox + rate-limited Replay, Pull via Webhook (falls KWP unterstützt) oder Cron, idempotent über `AppSyncItem`. Credentials liegen per-Tenant-DEK-verschlüsselt in `DataConnection.config`. Konflikte lösen sich nach „KWP gewinnt" (LWW mit Audit-Restore) plus HiveGrid-seitigem Optimistic Locking. Ein API-Contract-Sentinel (zod-Validierung + Versions-Check) pausiert den Sync bei Drift und alarmiert den Plattform-Admin. Plantafel- und Dokumenten-Archiv-Sync laufen über die API.
## Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
|---|---|---|
| KWP-Setup-Wizard [`/integrations/kwp/setup`] | OAuth/API-Key-Verbindung, Credential-Eingabe (DEK-verschlüsselt), 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`] | Sync-Items (Push/Pull), 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.config`
- [ ] Bidirektionaler Sync: Push (Won→Auftrag) via Outbox + rate-limited Replay; Pull via Webhook/Cron, idempotent über `AppSyncItem`
- [ ] Konflikt „KWP gewinnt" (LWW mit Audit-Restore) + Optimistic Locking HiveGrid-seitig
- [ ] API-Contract-Sentinel (zod-Validierung + Versions-Check) pausiert Sync bei Drift + alarmiert Plattform-Admin
- [ ] Plantafel-Sync + Dokumenten-Archiv-Sync (KWP-Doc → Storage) über die API
- [ ] Task-ERP-Sync (M074)
## Benötigte UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
Verbindungs-Setup-Wizard (OAuth/API-Key-Eingabe, maskierte Credentials), Initial-Sync-Vorschau (was wird gespiegelt), Connection-Health-Statusanzeige (Ampel + letzter Heartbeat/Sync), Re-Connect-Button, Sync-Log-Tabelle (Push/Pull-Richtung, Status, Fehler-Report-Aufklappen), Konflikt-Diff-Ansicht (Feld-für-Feld HiveGrid vs. KWP, „KWP gewinnt"-Markierung, Restore-Aktion), Sync-Pausen-Banner (Klartext, Kontakt-Hinweis), Admin-Tenant-Sync-Statusliste, Contract-Diff-Tool, Sync-Freigabe-Aktion, Empty-/Loading-/Permission-Denied-States (Klartext).
## 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/PHASE-SOURCES nachgezogen:
- [ ] Plane-Ticket (VR-P32a–c) aktualisiert: