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:

Auth-Methode (API-Key / OAuth2 / mTLS?) → bestimmt DataConnection.type + Credential-Handling
Endpoints + Capabilities (welche Entitäten les-/schreibbar: Aufträge, Stammdaten, Belege, Plantafel, Dokumente?)
Webhook-Support (KWP→HiveGrid Push) → entscheidet M094 (Trigger-Pull Phase 1 vs. Cron-Pull) und M092
Rate-Limits → bestimmt Replay-Rate (M091) und Pull-Intervalle
Versionierung / Changelog → bestimmt Umfang von M092 (eigenständig vs. in M089)
Dokumenten-API (Listing + Download) → Voraussetzung M095
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).

4.6 KiB Raw Blame History Unescape Escape