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

188 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](https://www.kwpsoftware.de/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).