57 lines
4.6 KiB
Markdown
57 lines
4.6 KiB
Markdown
# M19 / M089–M095 — Re-Cut gegen die KWP-API (Stand 2026-06-04)
|
||
|
||
> **Auslöser:** KWP bekommt eine offizielle **API-Anbindung**. Die ursprüngliche Planung
|
||
> (M089–M095) war für **KWP OHNE API** gebaut: lokaler Windows-Client `kwpsync.exe` (NSSM-Dienst)
|
||
> + MSSQL-Direktzugriff + lokale SQLite-Queue + MSSQL-Schema-Drift-Sentinel. Die Spec selbst hat
|
||
> das antizipiert (`_bmad-output/specs/M19-kwp-integration.md` Z. 367/388, 19.11.2).
|
||
> **Grundlage:** `docs/boilerplate-mapping/M19-kwp-integration.md` (Abschnitt „KWP-API-Auswirkung").
|
||
|
||
## Architektur: von 3 auf 2 Komponenten
|
||
|
||
**Vorher:** `HiveGrid Cloud ↔ kwpsync.exe (Windows, beim Kunden) ↔ KWP-MSSQL`
|
||
**Nachher:** `HiveGrid Cloud ↔ HTTPS ↔ KWP-API`
|
||
|
||
Der „Kunde-vor-Ort"-Mittelteil entfällt. KWP wird damit ein **regulärer `rest-api`/`oauth2`-Adapter**
|
||
(statt `windows_client`-Sonderweg) und passt direkt ins generische Apps-Engine-Muster
|
||
(`prisma/schema/appsEngine.prisma`: `App` / `DataConnection` / `AppSyncRun` / `AppSyncItem`).
|
||
Egress (Cloud ruft KWP aktiv auf) statt Ingress (Client pollt Cloud).
|
||
|
||
## Milestone-Verdikt
|
||
|
||
| Milestone | Vorher | Nachher (Re-Cut) | Verdict |
|
||
|---|---|---|---|
|
||
| **M089** Sync-Programm | externes `kwpsync.exe` (.NET/Go, NSSM, MSSQL, DPAPI, Auto-Update) | **KWP-API-Connector** (REST/OAuth über M33a-Adapter, im Monorepo) | **REPURPOSED** (Windows-Client entfällt) |
|
||
| **M090** Heartbeat+Recovery | Client-Heartbeat 5min + 15-min-Watchdog + Auto-Restart | **KWP-API Connection-Health** (generischer M33a-Health-Probe) | **STARK VEREINFACHT** |
|
||
| **M091** Warteschlange+Replay | zwei Queues (Cloud + lokale SQLite) | **eine** Cloud-Outbox + Rate-Limited-Replay | **VEREINFACHT** (SQLite weg) |
|
||
| **M092** Schema-Drift-Sentinel | täglicher MSSQL-Schema-Snapshot+Hash-Diff | **API-Contract-Sentinel** (zod-Response-Validierung + Versions-Check) | **VEREINFACHT** (ggf. in M089 integrierbar) |
|
||
| **M093** Konflikt „KWP gewinnt" | Domain-Regel | Domain-Regel | **UNVERÄNDERT** (transport-unabhängig) |
|
||
| **M094** Plantafel-Sync | bidirektional via Client | bidirektional via API (`syncPush` + Webhook/Cron-Pull) | **VEREINFACHT** |
|
||
| **M095** Dokumenten-Archiv-Sync | Client-Dateizugriff | API-Dokumenten-Endpoint → `@toolctrl/storage` | **VEREINFACHT** |
|
||
|
||
**Netto:** M089 ändert sich grundlegend (Client → Connector), M090–M092/M094/M095 werden teils erheblich leichter, nur M093 bleibt. Gesamt-Aufwand sinkt deutlich; faktisches Reuse-Level steigt von *medium* Richtung *medium-high*.
|
||
|
||
## Datenmodell
|
||
|
||
- **Aus Boilerplate (`appsEngine.prisma`) übernehmen:** `App{type:"kwp"}`, `DataConnection{type:"rest-api"|"oauth2", config:<verschlüsselt>}`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` (inkl. `rolledBackData` für M093-Restore). Plus `ApiKey`/`IdempotencyKey`/`FileObject` 1:1.
|
||
- **Neu in `prisma/schema/kwp.prisma`:** `KwpProjectNumberSequence`, `KwpProjectNumberReservation`, `KwpApiContractSnapshot` (API-Version + Schema-Fingerprint, ersetzt `KwpSchemaSnapshot`), `KwpErrorReport`.
|
||
- **Credentials:** verschlüsselt in `DataConnection.config` via **Per-Tenant-DEK** (AD-8). Achtung: Spec 19.1.2 („KWP-Zugangsdaten verlassen das Kunden-Netz nie") gilt bei API-Anbindung nicht mehr 1:1 — API-Creds liegen jetzt (verschlüsselt) in der Cloud. DSGVO-konform, aber bewusst neu bewertet → in AVV/Subprozessoren (M166) vermerken.
|
||
|
||
## Harte Vorbedingung
|
||
|
||
**M008–M010 (M33a Apps-Engine-Adapter-Interface)** — das echte `connect/disconnect/validateConnection/syncPull/syncPush/handleWebhook`-Interface. `defineAdapter()` aus der Boilerplate ist nur eine 18-Zeilen-Status-Registry, **nicht** das Connector-Framework. KWP-API ist dann der **erste konkrete Adapter** dahinter.
|
||
|
||
## ⚠️ Offene Abhängigkeit: der KWP-API-Vertrag
|
||
|
||
Dieser Re-Cut ist **strukturell**; die Detail-Planung pro Milestone braucht den konkreten KWP-API-Vertrag. Vor Umsetzung mit KWP klären:
|
||
1. **Auth-Methode** (API-Key / OAuth2 / mTLS?) → bestimmt `DataConnection.type` + Credential-Handling
|
||
2. **Endpoints + Capabilities** (welche Entitäten les-/schreibbar: Aufträge, Stammdaten, Belege, Plantafel, Dokumente?)
|
||
3. **Webhook-Support** (KWP→HiveGrid Push) → entscheidet M094 (Trigger-Pull Phase 1 vs. Cron-Pull) und M092
|
||
4. **Rate-Limits** → bestimmt Replay-Rate (M091) und Pull-Intervalle
|
||
5. **Versionierung / Changelog** → bestimmt Umfang von M092 (eigenständig vs. in M089)
|
||
6. **Dokumenten-API** (Listing + Download) → Voraussetzung M095
|
||
7. **Konflikt-Felder** (`version_hash`/`last_modified` in Responses?) → Voraussetzung M093/M094
|
||
|
||
## Phase 2 (unverändert)
|
||
|
||
Andere ERPs (Taifun/TopKontor/Streit) über dasselbe Adapter-Pattern. Streit hat ohnehin eine Cloud-API (analog zur KWP-API-Variante).
|