Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/KWP-API-CONTRACT.md
T

15 KiB
Raw Blame History

KWP-API-Vertrag (Stand 2026-07-12 · Read-only-Entscheidung 2026-07-22)

Auslöser: KWP bekommt eine offizielle API-Anbindung. Die historische 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. Aktuelle Grundlage: verifizierte Tenant-OpenAPI-/Staging-Proofs, AD-32, CR-003/CR-005 und die Ticket-Docs VR-P32*/VEXT-6.

🟢 Initialer Produkt-Scope nach CR-003/AD-32 (2026-07-22): HiveGrid nutzt KWP bis auf Weiteres ausschließlich read-only. Der ausgelieferte Scope umfasst OAuth2/PKCE, die bestätigte 1:1-Mandantenbindung, Connection-Health und spätere KWP→HiveGrid-Pulls. Keine KWP-Mutation wird registriert oder ausgeliefert. M091, kwp.push_auftrag, M094-Outbound und M074-Outbound sind geparkt. VEXT-6 hält den fehlenden Write-/Project-Create-Vertrag nach; es blockiert den read-only Ausbau nicht. Read-only ist eine HiveGrid-Produktgrenze und keine Behauptung über technisch mögliche BNWIN-Rechte.

Maßgeblicher Vertrag für Geerkens

KWP-Hosts sind dynamisch: Der Connector ermittelt den Relay-Host über https://loadbalancer.kwp-online.de/Relay/GetAppUrl?linkId=<KUNDENKUERZEL> und hängt /relay/<KUNDENKUERZEL>/pwa an. Ein Host wie app04 darf deshalb nicht dauerhaft in Code oder Tenant-Config festgeschrieben werden. Für geerkens2 lieferte der Loadbalancer am 2026-07-12:

Vertragsmerkmal Verifizierter Stand
Relay-Host https://geerkens2.app04.kwp-online.de
Tenant-OpenAPI /relay/geerkens2/pwa/swagger/v1/swagger.json
Vertrag OAS 3.0.1 · 301 Pfade · 303 Operationen · 396 Schemas
Snapshot-Proof SHA-256 5c504ffa955bc492fcc16ae01a92ad0491db29a904ad59058123fc3b24f26762
API-Metadaten Title KWP Api · Version v1 · Server /relay/geerkens2/pwa

Ergänzende Primärquelle ist die offizielle KWP-API-Dokumentation: Die API handelt im Namen eines bnWin-Benutzers; seine Rechte bestimmen Lese- und Schreibzugriff. Nutzt der Endkunde bnWin-Mandanten, muss jeder Request den Queryparameter mandant=<Mandantenkürzel> erhalten.

Mandanten-Verbindungsflow, freigegeben 2026-07-21: Die Tenant-OpenAPI enthält GET /api/Mandant/Load; der Endpoint beschreibt die für den angemeldeten Benutzer zulässigen Mandanten als DtoMandant{id, kuerzel, bezeichnung}. HiveGrid versucht diese Discovery direkt nach dem OAuth-Login. Ein Treffer wird vorausgewählt, muss aber vom Benutzer bestätigt werden; bei mehreren Treffern wird genau einer gewählt und bestätigt. Die OpenAPI-Security des Endpoints nennt allerdings andere KWP-interne Produkt-Scopes als die fünf für HiveGrid gelieferten *-extern-Scopes. Falls der externe Client die Liste nicht lesen darf, muss der Benutzer deshalb fail-closed entweder „kein bnWin-Mandant eingerichtet“ ausdrücklich bestätigen oder das exakte Kürzel manuell eingeben. Ein Fehler oder eine leere Liste ist keine implizite none-Bestätigung.

Die Produktgrenze bleibt 1:1: Ein HiveGrid-Tenant bindet genau ein KWP-Kundenkürzel plus genau eine bestätigte bnWin-Auswahl (selected) oder die bestätigte Abwesenheit eines bnWin-Mandanten (none). Ein fehlender Altwert ist unconfirmed und blockiert fachliche Calls. Der vorprovisionierte Geerkens-Pilot bleibt processweit auf KWP_HIVEGRID_TENANT_ID begrenzt. Die sichere Provisionierung mehrerer HiveGrid-Tenants oder weiterer KWP-Kundenclients ist Folge-Scope und wird nicht durch Entfernen dieses Gates vorgezogen.

OAuth-Runtime live geklärt (2026-07-22): Die Freischaltungs-Mail nennt Keycloak unter id.kwp-online.de/realms/kwp-federated, die Tenant-OpenAPI dagegen Relay-lokale Endpunkte /relay/geerkens2/pwa/connect/authorize und /connect/token. Ein Authorization-Probe mit dem gelieferten externen Client, PKCE/S256 und allen fünf externen Scopes erreichte am Keycloak-Pfad für Produktions- und Staging-Redirect jeweils die Login-Seite (HTTP 200; weder invalid_client noch invalid_redirect). Damit sind Client und beide Redirects am Authorization-Endpunkt plausibilisiert. client_credentials ist wegen deaktiviertem Service-Account nicht erlaubt; der Device Authorization Grant ist ebenfalls für den Client deaktiviert. Gültig ist openid + fünf *-extern-Scopes + offline_access; email erzeugt für diesen Client invalid_scope. Somit bleibt ausschließlich Authorization Code + PKCE mit einem echten bnWin-Benutzer. Token-Austausch, geschützter read-only Resource-Call, bestätigte Mandantenbindung und neun automatische Refresh-Rotationen sind auf Staging belegt. VN-1 bleibt nur für kontrollierte fachliche Testdaten offen.

Architektur: von 3 auf 2 Komponenten

Vorher: HiveGrid Cloud ↔ kwpsync.exe (Windows, beim Kunden) ↔ KWP-MSSQL Nachher: HiveGrid Cloud ↔ HTTPS ↔ dynamisch aufgelöster KWP-Relay

Der „Kunde-vor-Ort"-Mittelteil entfällt. KWP wird damit ein regulärer 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).

Überführung der historischen Milestones M089–M095

Milestone Vorher Nachher (Re-Cut) Verdict
M089 Sync-Programm externes kwpsync.exe (.NET/Go, NSSM, MSSQL, DPAPI, Auto-Update) KWP-API-Connector (Host-Resolver + OAuth + userbezogener Kontext + bestätigte 1:1-mandant-Bindung über M33a) 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) Zukünftige Cloud-Outbox nach belastbarem Write-Vertrag PARKED hinter VEXT-6
M092 Schema-Drift-Sentinel täglicher MSSQL-Schema-Snapshot+Hash-Diff API-Contract-Sentinel (zod-Response-Validierung + OpenAPI-Fingerprint + x-kwp-client-version) VEREINFACHT (ggf. in M089 integrierbar)
M093 Konflikt „KWP gewinnt" Domain-Regel Domain-Regel + HiveGrid-Snapshot/Audit; KWP-Änderungsfelder nur partiell UNVERÄNDERT, technische Erkennung angepasst
M094 Plantafel-Sync bidirektional via Client initial nur KWP→HiveGrid per Cron-Pull; Outbound geparkt READ-ONLY RECUT
M095 Dokumenten-Archiv-Sync Client-Dateizugriff Archiv-Metadaten via API, Dateiinhalt via Azure-Blob-Austausch → @hivegrid/storage VEREINFACHT

Netto: M089 ändert sich grundlegend (Client → Connector), M090/M092/M094/M095 werden teils erheblich leichter, M093 bleibt als Schutz für eingehende KWP-Daten. M091 ist kein Vorläufer des read-only Ausbaus mehr.

Datenmodell

  • Aus Apps-Engine (appsEngine.prisma) nutzen: App{key:"kwp", connectionType:"oauth2"}, DataConnection{credentialsCiphertext:<verschlüsselt>}, AppSyncRun, AppSyncRunLog, AppSyncItem (inkl. rolledBackData für M093-Restore). Plus IdempotencyKey/FileObject 1:1. Kundenkürzel und OAuth-Material liegen verschlüsselt in DataConnection.credentialsCiphertext; der dynamische Relay-Host wird nur gecacht. Die mandantBinding liegt ebenfalls ausschließlich im verschlüsselten Credential-Bundle und ist explizit unconfirmed, none oder selected(<Kürzel>). Ein fehlendes Feld aus Alt-Credentials bedeutet unconfirmed, nicht none; dafür ist kein Prisma-Schema-Delta nötig.
  • Neu im aktuellen Read-only-Scope in prisma/schema/kwp.prisma: KwpApiContractSnapshot (API-Version + Schema-Fingerprint, ersetzt KwpSchemaSnapshot) und KwpErrorReport.
  • PARKED, nicht im aktuellen Datenmodell: KwpProjectNumberSequence und KwpProjectNumberReservation gehören ausschließlich zum Project-/Auftrag-Create. Sie dürfen erst nach belastbarem Providervertrag aus VEXT-6 und erneuter ausdrücklicher Produktfreigabe angelegt werden.
  • Credentials: verschlüsselt in DataConnection.credentialsCiphertext 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.
  • Pilot-Provisionierung: Der bestehende Geerkens-OAuth-Client bleibt fail-closed an KWP_HIVEGRID_TENANT_ID gebunden. KWP_MANDANT wird für neue Connections nicht als processweite Mapping-Quelle verwendet. Ein späterer Mehr-Tenant-/Mehr-Kunden-Betrieb braucht einen eigenen sicheren Provisionierungsvertrag statt einer ersatzlosen Gate-Entfernung.

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.

Vertragsstand der sieben Re-Cut-Fragen

  1. Auth: OAuth2/Authorization Code + PKCE und Refresh/offline_access sind gesetzt; App.connectionType='oauth2'. Service-Account- und Device-Flow sind deaktiviert; der Request darf openid + fünf *-extern-Scopes + offline_access, aber nicht email enthalten. Userrechte sind bindend. Keycloak- versus Relay-/connect/*-Endpoint wird mit Token-Austausch und Resource-Call final entschieden.

  2. Endpoints/Capabilities: Die externen Scopes erscheinen in der Tenant-Spec an folgenden Operationen:

    Scope Operationen Fachliche Tags
    adresse-extern 23 Adresse
    archiv-extern 15 ArchivExternal, VorgangInfo
    termin-extern 14 Termin, Monteursteuerung
    vorgang-extern 31 Projekt, Projektampel, VorgangAnzeige
    aktivitaet-extern 31 Aktivitaet, Aktivitaetenverwaltung, Termin-Verknüpfungen

    Die *-extern-Scopes fehlen allerdings in der Scope-Liste des OAuth-Flows und stehen in den Operation-Security-Arrays zusammen mit internen Scopes. Nach strikter OpenAPI-Semantik wäre das eine UND-Anforderung; praktisch sieht es nach alternativen KWP-Berechtigungen aus. Lese- und Schreibrechte sind deshalb pro Scope im Runtime-Probe zu beweisen. Der aktuelle HiveGrid-Scope führt unabhängig davon keine Schreiboperation aus. Fachliche Lücke für einen späteren Writeback: Es gibt keinen dokumentierten Endpoint zum Anlegen eines kaufmännischen Auftrags/Projekts. /api/Projekt/Save speichert laut Vertrag nur eine neue Bezeichnung für ein bereits bestehendes Projekt. Der Won→Auftrag-Use-Case benötigt eine KWP-Erweiterung oder ein bestätigtes Alternativ-Mapping.

    Reale Vollinventur 2026-07-24 (CR-005): Die 2.062.387-Byte-Tenant-OpenAPI enthält 554 Operationen. Wegen überlappender Security-Arrays ergeben die Scope-Zahlen zusammen nicht die eindeutige Anzahl: 113 Operationen liegen in mindestens einem der fünf HiveGrid-Scopes. Davon sind 77 semantisch lesend und 36 mutierend. Alle 113 erhalten einen expliziten Contract; nur die 77 Reads sind runtime-ausführbar. Die übrigen 441 Operationen gehören nicht zum lizenzierten HiveGrid-Umfang und werden nicht allowlisted.

  3. Webhooks: In der vollständigen Tenant-OpenAPI gibt es weder Top-Level-webhooks noch Operation-callbacks. Das ist Abwesenheit im Vertrag, keine Bestätigung, dass KWP außerhalb davon keine Webhooks anbietet. M094 plant bis zur Herstellerantwort Cron-Pull.

  4. Rate-Limits: KWP bestätigt ein Hard-Cap von 60 Requests/Minute pro Client. Read-only-Pulls müssen dieses Limit aggregiert einhalten. M091 bleibt bis zum Write-Vertrag geparkt und muss bei einer späteren Freigabe zusätzlich Backoff, Jitter und 429 konservativ behandeln.

  5. Versionierung: OpenAPI/Info-Version v1; alle 303 Operationen führen optional x-kwp-client-version. Changelog- und Breaking-Change-Policy bleiben offen. M092 speichert deshalb OpenAPI-Hash plus beobachtete Serverversion und pausiert bei nicht validierbarer Drift.

  6. Dokumenten-API: Listing, Suche, Details, Revisionen, Export und Import sind unter /api/archiv-extern/* vorhanden. Der Dateitransfer läuft gemäß offizieller KWP-Doku separat über Azure Blob:

    • GetSetup.azureConnectionUri höchstens 6 Stunden cachen.
    • Upload in den Blob, danach ImportDatei(containerId, dateiname).
    • Dateien im Austausch-Storage werden nach 24 Stunden automatisch gelöscht.
    • Download: ExportDatei(revisionId, guid) → exchangeFileUri → JSON-Datei → eigentlicher Downloadlink.
  7. Konflikt-Felder: Aktivitäten liefern datumAenderung/userAenderung; Archiv-Daten liefern letzteAenderungAm/letzteAenderungVon sowie revisionId/revision. Adresse, Termin und Projekt/Vorgang haben keine einheitlichen Versions-/Änderungsfelder. Es sind keine ETag-/Last-Modified- Response-Header oder If-Match-Preconditions dokumentiert. M093 verwendet daher KWP-Felder nur, wo vorhanden, und sonst HiveGrid-Snapshot + „KWP gewinnt" + Audit-Restore.

Mandantenbindung als M089-Connector-Vertrag

  • OAuth-tenant=<Kundenkürzel> wählt die KWP-Installation; der Resource-Query mandant=<Mandantenkürzel> wählt optional die Firma innerhalb dieser Installation. Die Werte dürfen nicht gleichgesetzt werden.
  • Nach dem Token-Austausch bleiben die Credentials bis zur ausdrücklichen Auswahl per-Tenant-DEK verschlüsselt in der reservierten pending-Connection. Erst eine bestätigte Bindung und ein geschützter Health-Probe dürfen die Connection aktivieren.
  • selected setzt den Queryparameter an jedem KWP-Resource-Request, none lässt ihn bewusst weg und unconfirmed blockiert fachliche Calls fail-closed.
  • Discovery über Mandant/Load ist bevorzugt, aber wegen des abweichenden Scope-Vertrags nicht garantiert; der manuelle Fallback ist deshalb Bestandteil des Connectors, kein Sync-Feature.
  • Der Slice enthält weiterhin keinen Pull, Push, manuellen Sync und keine automatische Anlage weiterer HiveGrid-Tenants.

Noch extern zu bestätigen

  • für VEXT-6: belastbare Write-/Project-Create-Operationen, Scopes/BNWIN-Rechte, Payloads, Idempotenz-/Fehlervertrag und ein kontrollierbarer Testpfad;
  • kontrollierte fachliche Testdaten beziehungsweise ein sicherer Testpfad, obwohl KWP keine Sandbox und keinen Testkunden anbietet;
  • konkrete Pull-Intervalle innerhalb des bestätigten Hard-Caps von 60 Requests/Minute pro Client.

Phase 2 (unverändert)

Andere ERPs (Taifun/TopKontor/Streit) über dasselbe Adapter-Pattern. Streit hat ohnehin eine Cloud-API (analog zur KWP-API-Variante).