Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
+25
-13
@@ -1,22 +1,30 @@
|
||||
# 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)**
|
||||
**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/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.
|
||||
> 🔴 **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 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.
|
||||
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`] | OAuth/API-Key-Verbindung, Credential-Eingabe (DEK-verschlüsselt), Initial-Sync-Vorschau | A5/Wizard |
|
||||
| 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`] | Sync-Items (Push/Pull), Status, Zeit, KwpErrorReport-Einträge, Filter | A2 |
|
||||
| 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 |
|
||||
@@ -24,16 +32,20 @@ Bindet KWP als ersten konkreten Adapter hinter dem M33a-Interface an und spiegel
|
||||
## 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)
|
||||
- [ ] 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 (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).
|
||||
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)
|
||||
|
||||
@@ -45,5 +57,5 @@ Verbindungs-Setup-Wizard (OAuth/API-Key-Eingabe, maskierte Credentials), Initial
|
||||
## Dev-Nachzug (wir nach Davids Delta)
|
||||
|
||||
- [ ] Spec/ENTITY-MODEL an Davids Entscheidungen angepasst:
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen:
|
||||
- [ ] REQUIREMENTS/ROADMAP nachgezogen:
|
||||
- [ ] Plane-Ticket (VR-P32a–c) aktualisiert:
|
||||
Reference in new issue
Block a user