15 KiB
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-6hä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.rolledBackDatafür M093-Restore). PlusIdempotencyKey/FileObject1:1. Kundenkürzel und OAuth-Material liegen verschlüsselt inDataConnection.credentialsCiphertext; der dynamische Relay-Host wird nur gecacht. DiemandantBindingliegt ebenfalls ausschließlich im verschlüsselten Credential-Bundle und ist explizitunconfirmed,noneoderselected(<Kürzel>). Ein fehlendes Feld aus Alt-Credentials bedeutetunconfirmed, nichtnone; 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, ersetztKwpSchemaSnapshot) undKwpErrorReport. - PARKED, nicht im aktuellen Datenmodell:
KwpProjectNumberSequenceundKwpProjectNumberReservationgehören ausschließlich zum Project-/Auftrag-Create. Sie dürfen erst nach belastbarem Providervertrag ausVEXT-6und erneuter ausdrücklicher Produktfreigabe angelegt werden. - Credentials: verschlüsselt in
DataConnection.credentialsCiphertextvia 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_IDgebunden.KWP_MANDANTwird 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
-
Auth: OAuth2/Authorization Code + PKCE und Refresh/
offline_accesssind gesetzt;App.connectionType='oauth2'. Service-Account- und Device-Flow sind deaktiviert; der Request darfopenid+ fünf*-extern-Scopes +offline_access, aber nichtemailenthalten. Userrechte sind bindend. Keycloak- versus Relay-/connect/*-Endpoint wird mit Token-Austausch und Resource-Call final entschieden. -
Endpoints/Capabilities: Die externen Scopes erscheinen in der Tenant-Spec an folgenden Operationen:
Scope Operationen Fachliche Tags adresse-extern23 Adressearchiv-extern15 ArchivExternal,VorgangInfotermin-extern14 Termin,Monteursteuerungvorgang-extern31 Projekt,Projektampel,VorgangAnzeigeaktivitaet-extern31 Aktivitaet,Aktivitaetenverwaltung, Termin-VerknüpfungenDie
*-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/Savespeichert 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.
-
Webhooks: In der vollständigen Tenant-OpenAPI gibt es weder Top-Level-
webhooksnoch 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. -
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
429konservativ behandeln. -
Versionierung: OpenAPI/Info-Version
v1; alle 303 Operationen führen optionalx-kwp-client-version. Changelog- und Breaking-Change-Policy bleiben offen. M092 speichert deshalb OpenAPI-Hash plus beobachtete Serverversion und pausiert bei nicht validierbarer Drift. -
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.azureConnectionUrihö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.
-
Konflikt-Felder: Aktivitäten liefern
datumAenderung/userAenderung; Archiv-Daten liefernletzteAenderungAm/letzteAenderungVonsowierevisionId/revision. Adresse, Termin und Projekt/Vorgang haben keine einheitlichen Versions-/Änderungsfelder. Es sind keineETag-/Last-Modified- Response-Header oderIf-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-Querymandant=<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. selectedsetzt den Queryparameter an jedem KWP-Resource-Request,nonelässt ihn bewusst weg undunconfirmedblockiert fachliche Calls fail-closed.- Discovery über
Mandant/Loadist 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).