Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -6,117 +6,469 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | Phase 32 (v2-P5) — KWP-Integration (Vorlauf) |
|
||||
| **Cycle/Fenster** | v2-W2 — KWP/Portal/Mobile-Start · fällig 2026-07-20 |
|
||||
| **Status** | in Arbeit · 🟢 **Zugang aktiv seit 2026-06-25** (~3–4 Wochen früher als geplant) |
|
||||
| **Status** | Done · Demand-Refresh-Dauerbetrieb auf Staging verifiziert · **4/4 DoD = 100 % done** |
|
||||
|
||||
> 🟢 **Update 2026-06-25 — Zugang eingetroffen (früher als ~19./20.07.):** KWP hat den OAuth2-Zugang für den Mandanten `geerkens2` freigeschalten. Der block-2-Zustand der KWP-Phase ist damit faktisch **aufgelöst** — VR-P32a/b/c bleiben aber `blocked-by R-P5` (Apps-Engine M33a). Stand der 7 Vertrags-Fragen siehe Umsetzungs-Notiz unten. **KWP bleibt v2-Scope** (kein v1-Vorziehen — Big-Bang-Launch v1 zuerst, AD-19); der frühe Zugang wird genutzt, um die Vertrags-Fragen vorab gegen die echte API zu klären (Spike), nicht um den v1-Sprint aufzureißen.
|
||||
> 🔴 **Regression 2026-07-23:** Der Dauer-Proof vom 22.07. bleibt als historischer Nachweis gültig, reicht
|
||||
> aber nicht mehr für einen aktuellen Haltbarkeits-Claim. Nach 20 weiteren erfolgreichen automatischen
|
||||
> Rotationen akzeptierte der Token-Endpunkt um **21:08:10 CEST** noch eine HTTP-2xx-JSON-Antwort, die
|
||||
> anschließend an einem der zusammengefassten semantischen Refresh-Checks scheiterte. Die Connection wurde
|
||||
> fail-closed auf `broken` gesetzt und benötigt nach dem Fix einen normalen OAuth-Reconnect. Die vorhandene
|
||||
> Diagnose unterschied fehlenden Access-/Refresh-Token, nicht rotierenden Refresh-Token, Scope-Echo und
|
||||
> Ablaufzeit nicht. Zusätzlich verlangte der automatische Refresh fälschlich exakt `expires_in=300`, obwohl
|
||||
> der Erst-Login bereits jede positive Laufzeit bis maximal 300 Sekunden akzeptiert und OAuth `expires_in`
|
||||
> als tatsächliche Laufzeit definiert. Der Fix vereinheitlicht diesen Vertrag, protokolliert ausschließlich
|
||||
> feste redigierte Diagnosecodes und behält den sicheren Nicht-Replay bei möglicherweise verbrauchtem
|
||||
> Einmal-Refresh-Token bei. Bis Deploy, Reconnect und erneutem Langzeit-Proof gilt:
|
||||
> **VEXT-1: 3/4 DoD = 75 % done · 1 Punkt offen · 1 selbst machbar.**
|
||||
|
||||
> 🟢 **Regression geschlossen 2026-08-01:** Der Demand-Refresh-Fix aus PR `#312` lief nach einem
|
||||
> normalen OAuth-Reconnect zwei Stunden stabil auf Staging. **20/20** Einmal-Refresh-Token-Rotationen aus
|
||||
> Web-, Import- und Health-Pfaden gelangen; acht Health-Sweeps meldeten `checked=1`, `unhealthy=0`. Es gab
|
||||
> keinen Provider-, Persistenz- oder Claim-Fehler und keine erneute Reconnect-Aufforderung.
|
||||
> **VEXT-1: 4/4 DoD = 100 % done · 0 Punkte offen · Done.**
|
||||
|
||||
> 🟢 **Superseding Scope-Entscheidung 2026-07-22:** VEXT-1 ist für den initialen aktuellen
|
||||
> **read-only** KWP-Vertrag vollständig abgeschlossen. Project-/Auftrag-Create, Writeback, Push-Queue und
|
||||
> M091 sind keine Rest-DoD von VEXT-1 oder `VR-P32a`; die fehlende externe Write-/Create-Capability wird
|
||||
> separat in `VEXT-6` als Blocked / On Hold nachgehalten. `VEXT-6` blockiert keine read-only
|
||||
> Connector-/Inbound-Tickets. Die datierten Vertrags- und Diagnoseeinträge unten bleiben als Historie
|
||||
> erhalten.
|
||||
|
||||
> 🟢 **Update 2026-06-25 — Freischaltungsdaten eingetroffen (früher als ~19./20.07.):** KWP hat den OAuth2-Client für den Mandanten `geerkens2` bereitgestellt. Der reine Kalenderblocker ist damit aufgelöst; die KWP-Phase bleibt jedoch durch Runtime-Token/Scope-Proof und die fehlende Auftrag-Create-Capability blockiert. R-P5 (Apps-Engine M33a) ist inzwischen abgeschlossen. Stand der 7 Vertrags-Fragen siehe Umsetzungs-Notiz unten. **KWP bleibt v2-Scope.**
|
||||
|
||||
> 🟡 **Update 2026-07-12 — tenant-spezifischer Vertrag verifiziert:** Der KWP-Loadbalancer löst
|
||||
> `geerkens2` aktuell auf `https://geerkens2.app04.kwp-online.de` auf. Maßgeblich ist die Tenant-OpenAPI unter
|
||||
> `/relay/geerkens2/pwa/swagger/v1/swagger.json` (OAS 3.0.1, 301 Pfade, 303 Operationen, 396 Schemas,
|
||||
> SHA-256 `5c504ffa955bc492fcc16ae01a92ad0491db29a904ad59058123fc3b24f26762`). Endpoints,
|
||||
> Dokumentenfluss und partielle Konfliktfelder sind damit belastbar erfasst. Ein echter Token-/Resource-Call
|
||||
> bleibt offen, weil die per Mail genannten Keycloak-Endpunkte von den OAuth-Endpunkten der Tenant-Swagger
|
||||
> abweichen. Formal abgeschlossen sind der Recut-Ausschluss von `kwpsync.exe` sowie Redirect-/AVV-Nachzug.
|
||||
|
||||
> 🟡 **Runtime-Probe 2026-07-12 — Benutzerlogin fehlt:** Client-ID, Client-Secret, Kundenkürzel und die von
|
||||
> KWP gelieferten Scopes liegen verschlüsselt in `secrets/dev.sops.env`; Klartextwerte stehen nicht in Git oder
|
||||
> dieser Doc. Keycloak lehnt `client_credentials` ab, weil der Service-Account für den Client deaktiviert ist,
|
||||
> und lehnt den Device Authorization Grant ab, weil dieser Flow ebenfalls deaktiviert ist. Damit ist
|
||||
> **Authorization Code + PKCE mit einem echten bnWin-Benutzer der einzige freigeschaltete Login-Pfad**. Die
|
||||
> Kombination `openid` + fünf `*-extern`-Scopes + `offline_access` wird am Authorization-Endpunkt akzeptiert;
|
||||
> der zusätzliche Discovery-Scope `email` führt für diesen Client zu `invalid_scope`. Token-Austausch und erster
|
||||
> Resource-Call warten auf einen berechtigten Geerkens/bnWin-Testbenutzer aus `VN-1`.
|
||||
|
||||
> 🟢 **Herstellerantworten 2026-07-20 — Recut-Planung fachlich geklärt:** Pro Client gilt ein
|
||||
> Hard-Cap von **60 Requests/Minute**; weitere Vorgaben zu Parallelität, Backoff, Jitter oder `429` wurden nicht
|
||||
> gemacht. Access-Token gelten **5 Minuten** plus **5 Minuten technischen Clock-Skew**. Refresh-Token gelten
|
||||
> **30 Tage idle / maximal 365 Tage**, sind einmalig und rotieren bei jeder Access-Token-Anforderung; eine
|
||||
> Passwortänderung oder Benutzerdeaktivierung widerruft sie. KWP bietet keine Änderungs-Webhooks oder
|
||||
> authentifizierten Änderungs-Callbacks, Delta-Cursor, als Delta-Vertrag nutzbaren einheitlichen
|
||||
> Änderungszeitstempel oder „geändert
|
||||
> seit“-Filter und keine Sandbox bzw. keinen Testkunden. `x-kwp-client-version` ist optional. Die Neuanlage
|
||||
> eines Projekts/Auftrags über die API ist
|
||||
> ausdrücklich nicht vorgesehen. `mandant` wird nur gesendet, wenn in kwp-bnWin.net ein Mandant eingerichtet
|
||||
> ist, dann mit dessen Kürzel; andernfalls entfällt der Queryparameter. Ob dies für Geerkens zutrifft, ist noch
|
||||
> offen. Damit ist die Recut-Detailplanung abgeschlossen; nur der echte Login-/Token-/Resource-Proof bleibt offen.
|
||||
|
||||
> 🟢 **Herstellerdiagnose zum fehlgeschlagenen Login 2026-07-20:** Laut KWP-Logs aktualisierte sich der
|
||||
> BackendApi-Dienst erst am **13.07.2026** auf **2.81.62**; die damaligen Tests liefen größtenteils am 12.07.
|
||||
> und damit vor dem erforderlichen Backend-Stand. KWP erwartet, dass die Anmeldung jetzt funktioniert. Diese
|
||||
> Diagnose ersetzt den ausstehenden Retest nicht. Verbindlich sind der zentrale Issuer
|
||||
> `https://id.kwp-online.de/realms/kwp-federated` und für die Geerkens-Resource die Audience
|
||||
> `https://geerkens2.app04.kwp-online.de/relay/geerkens2/pwa`. Einen separaten `resource`-Wert hat KWP nicht
|
||||
> benannt, sondern um Präzisierung gebeten; er bleibt deshalb ohne erfundenen Claim-/Parametervertrag offen.
|
||||
|
||||
> 🟡 **Lokaler Retest 2026-07-20 — Versionsblocker weg, BNWIN-Login offen:** Der echte lokale HiveGrid-Pfad
|
||||
> erreicht nach Login, Tenant-/Feature-/Permission-Gate und CSRF-Prüfung den zentralen Keycloak-Authorization-
|
||||
> Endpoint mit allen sieben vereinbarten Scopes, `tenant=geerkens2`, State, Nonce und PKCE/S256. Die lokale
|
||||
> Callback-URL wird erwartungsgemäß mit `400 invalid_redirect_uri` abgelehnt; die bereits registrierte
|
||||
> Staging-Callback-URL liefert mit demselben Request `200` und das BNWIN-Loginformular. Parallel liefern
|
||||
> `Core/GetApiVersion` den Wert `2` und `Core/GetVersion` die Hersteller-Version **2.81.62**. Ein geschützter
|
||||
> Adressaufruf ohne Token endet korrekt mit `401 Bearer`. Damit ist der frühere Backend-Versionsblocker
|
||||
> ausgeräumt. Die registrierten HiveGrid-Staging-Routen selbst liefern aktuell noch `404`, weil der lokale
|
||||
> Pilot-Branch nicht deployt ist. Auth-Code, Token, Scope-Claims, authentifizierter Resource-Call und Refresh
|
||||
> bleiben bis zu Deploy und echtem BNWIN-Login offen. Es wurde kein Credential rotiert.
|
||||
|
||||
> 🟢 **Dependency-Ausnahme 2026-07-20:** In `VR-P32a` darf ausschließlich der schmale
|
||||
> **Geerkens-Pilot-Slice** vor Abschluss dieses Tickets umgesetzt werden: OAuth2/PKCE-Start, fester Callback,
|
||||
> Code-/Token-Austausch und per-Tenant-DEK-verschlüsselte Persistenz. Read-only Relay-Discovery und Health sind
|
||||
> ausschließlich als notwendiger Live-Proof enthalten; Refresh-Rotation gehört zum Token-Lifecycle. **Pull,
|
||||
> Push und manueller Sync sind in diesem Slice nicht freigegeben.** Die Ausnahme ersetzt weder den
|
||||
> berechtigten bnWin-Testbenutzer aus `VN-1` noch Auth-Code-, Token-, Scope- und Resource-Proof. `VEXT-1` bleibt
|
||||
> deshalb Blocker für Live-Verifikation und Done von `VR-P32a`; ohne erfolgreichen bnWin-Login begründet der
|
||||
> Slice keinen Live- oder Done-Claim.
|
||||
|
||||
> 🟡 **Staging-Erst-Proof 2026-07-21:** Der echte BNWIN-Authorization-Code-/PKCE-Flow war auf Staging
|
||||
> vollständig erfolgreich. HiveGrid tauschte den Code am zentralen Keycloak aus, akzeptierte ausschließlich
|
||||
> die fünf verpflichtenden `*-extern`-Scopes, rief mit dem Access-Token den geschützten Relay-Endpunkt
|
||||
> `Core/GetApiVersion` erfolgreich auf und persistierte die OAuth-Credentials per-Tenant-DEK-verschlüsselt in
|
||||
> einer aktiven `DataConnection`. Der General Worker rotierte den einmaligen Refresh-Token anschließend
|
||||
> automatisch; die Token-Ablaufzeit rückte dabei um weitere fünf Minuten vor und der Connection-Health blieb
|
||||
> `active`. Kein Client-Secret, Passwort oder API-Key wurde rotiert; ausschließlich der von KWP zwingend
|
||||
> rotierende Einmal-Refresh-Token wurde im normalen Refresh-Flow ersetzt. `KWP_MANDANT` blieb ungesetzt und
|
||||
> Produktion blieb unverändert. Dieser Lauf beweist den echten Auth-/Resource-Pfad, aber noch keinen stabilen
|
||||
> Dauerbetrieb: Ein späterer Refresh schlug um 03:09:54 CEST fehl und setzte die Verbindung auf `broken`.
|
||||
|
||||
> 🟢 **Mandantenvertrag und Scope-Freigabe 2026-07-21:** Die aktuelle Geerkens-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}` und ist damit die bevorzugte Discovery für den neuen
|
||||
> VR-P32a-Verbindungsflow. Seine OpenAPI-Security nennt jedoch nicht die fünf für HiveGrid gelieferten
|
||||
> `*-extern`-Scopes, sondern andere KWP-interne Produkt-Scopes; die Capability ist für den externen Client
|
||||
> deshalb erst zur Laufzeit beweisbar. Die Implementierung darf bei fehlender Berechtigung nicht „kein
|
||||
> Mandant“ annehmen, sondern verlangt eine ausdrückliche `none`-Bestätigung oder das manuell eingegebene
|
||||
> exakte Kürzel. Die konkrete Geerkens-Zuordnung bleibt Live-/E2E-Input, blockiert aber nicht mehr den
|
||||
> generischen Setup-Bau. Der vorprovisionierte Pilot bleibt processweit an `KWP_HIVEGRID_TENANT_ID` gebunden;
|
||||
> eine sichere Mehr-Tenant-/Mehr-Kunden-Provisionierung ist Folge-Scope.
|
||||
|
||||
## Was zu tun
|
||||
KWP-API-Zugang aktivieren und die **Recut-Detailplanung pro Milestone gegen die echte API-Doku** durchführen — nicht gegen Annahmen. Konkret die 7 offenen Vertrags-Fragen aus dem bindenden Recut klären und je Milestone (M089–M095) entscheiden:
|
||||
1. **Auth-Methode** (API-Key / OAuth2 / mTLS?) → bestimmt `DataConnection.type` (`rest-api`/`oauth2`) + Credential-Handling
|
||||
KWP-API-Zugang aktivieren und die **Recut-Detailplanung pro Milestone gegen die echte API-Doku** durchführen — nicht gegen Annahmen. Konkret die 7 ursprünglich offenen Vertrags-Fragen aus dem bindenden Recut klären und je Milestone (M089–M095) entscheiden (Auflösungsstand siehe Umsetzung):
|
||||
1. **Auth-Runtime** (Keycloak- oder Relay-`/connect/*`-Endpoint, Token-/Refresh-Verhalten) → `App.connectionType='oauth2'` + Credential-Handling ist bereits gesetzt
|
||||
2. **Endpoints + Capabilities** (welche Entitäten les-/schreibbar: Aufträge, Stammdaten, Belege, Plantafel, Dokumente?)
|
||||
3. **Webhook-Support** (KWP→HiveGrid Push?) → entscheidet M094 (Trigger-Pull vs. Cron-Pull) und M092
|
||||
4. **Rate-Limits** → bestimmt Replay-Rate (M091) und Pull-Intervalle
|
||||
5. **Versionierung/Changelog** → bestimmt Umfang M092 (eigenständig vs. in M089)
|
||||
3. **Webhook-/Delta-Support** außerhalb der Tenant-OpenAPI → laut Hersteller nicht vorhanden; ein späterer Pull muss ohne Delta-Mechanismus geplant werden
|
||||
4. **Rate-Limits** → 60 Requests/Minute Hard-Cap pro Client; bestimmt Replay-Rate (M091) und Pull-Intervalle
|
||||
5. **Versionierung/Changelog** → API `v1`, `x-kwp-client-version` optional; bestimmt Umfang 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
|
||||
7. **Konflikt-Felder** pro Endpoint → M093 nutzt mangels einheitlicher Felder HiveGrid-Snapshots + Audit-Restore
|
||||
|
||||
In v1 bereits erledigt (Andockpunkte): Callback-URL `https://app.hivegrid.de/integrations/kwp/oauth/callback` an KWP gemeldet (feste URL, Tenant im `state`, OAuth Auth-Code + PKCE); bnWin.net-8.1-N3-Update bei Geerkens angestoßen. Staging-Redirect-URI (`staging-app.…`) bei KWP mitregistrieren.
|
||||
In v1 bereits erledigt (Andockpunkte): Callback-URL `https://app.hivegrid.de/integrations/kwp/oauth/callback` an KWP gemeldet (feste URL, Tenant im `state`, OAuth Auth-Code + PKCE); bnWin.net-8.1-N3-Update bei Geerkens angestoßen. Produktions- und Staging-Redirect werden vom Authorization-Endpunkt akzeptiert (Probe 2026-07-12).
|
||||
|
||||
## Warum / blockt
|
||||
Ohne aktiven Zugang + Detailplanung gegen die echte Doku ist der KWP-Bau (VR-P32a/b/c) reine Spekulation. Liefert die konkreten Parameter (Auth-Typ, Endpoints, Webhook-Support, Rate-Limits, Konflikt-Felder), die jeden der drei Dev-Tickets steuern. **`kwpsync.exe` NICHT bauen** (Recut bindend, M089 = Connector statt Windows-Client). ⚠ Creds liegen bei API-Anbindung verschlüsselt in der Cloud (`DataConnection.config`, Per-Tenant-DEK) — Spec-19.1.2 gilt nicht mehr 1:1 → Vermerk an AVV/Subprozessoren (VR-P31/M166) weiterreichen.
|
||||
Die Detailplanung ist durch OpenAPI, Herstellerantworten und den erfolgreichen Staging-Runtime-Proof belastbar.
|
||||
Der Proof gibt keinen über den read-only Geerkens-Scope hinausgehenden Sync-Bau frei. Der vom Hersteller
|
||||
nicht unterstützte Project-/Auftrag-Create wird in `VEXT-6` geparkt; die fehlenden kontrollierten fachlichen
|
||||
Testdaten bleiben in `VN-1` separat zu klären.
|
||||
**`kwpsync.exe` NICHT bauen** (Recut bindend, M089 = Connector statt Windows-Client). ⚠ Creds liegen bei API-Anbindung verschlüsselt in der Cloud
|
||||
(`DataConnection.credentialsCiphertext`, Per-Tenant-DEK) — Spec-19.1.2 gilt nicht mehr 1:1 → Vermerk an AVV/Subprozessoren
|
||||
(VR-P31/M166) weiterreichen.
|
||||
|
||||
## Abhängigkeiten
|
||||
- **Blocked by:** — (extern: KWP-Hersteller-Zugang ~19./20.07.)
|
||||
- **Blocks:** `VR-P32a` (Connector — braucht Auth/Endpoints/Webhook-Klärung), `VN-1` (KWP-Vorbereitung/Validierung)
|
||||
- **Blocked by:** keine. `VN-1` bleibt wegen des noch nicht kontrolliert freigegebenen Geerkens-Datenbereichs
|
||||
und des fehlenden minimal berechtigten BNWIN-Testbenutzers eigenständig bei 0/1.
|
||||
Die generische Discovery-/Auswahl-Implementierung in `VR-P32a` ist abgeschlossen; im Live-Reconnect wurde
|
||||
genau eine Geerkens-Bindung ausdrücklich bestätigt und verschlüsselt gespeichert. Kontrollierte fachliche
|
||||
Daten-Calls und Sync-E2E bleiben weiterhin Scope von `VN-1`/`VN-2`.
|
||||
- **Blocks:** keine read-only Connector-Tickets mehr. `VR-P32a` ist nach dem zweistündigen Demand-Refresh-
|
||||
Dauer-Proof 5/5 Done; der Code-/Fixture-Proof und credential-geschützte Staging-Betrieb von
|
||||
`VR-P32b`/`VR-P32d` bleiben abgeschlossen. Ein möglicher späterer Write-/Create-Vertrag liegt
|
||||
ausschließlich in `VEXT-6`.
|
||||
- **Parallel:** v1-Andockpunkte (Apps-Engine M33a, Extension-Points) stehen bereits — dieser Task füllt nur die Vertrags-Lücken.
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **KWP-API-Zugang aktiv** (Auth/Endpoints/Webhook-Support geklärt)
|
||||
- [ ] **Recut-Detailplanung pro Milestone** (M089–M095) gegen die echte Doku — alle 7 Vertrags-Fragen beantwortet
|
||||
- [ ] **`kwpsync.exe` NICHT gebaut** (Recut bindend bestätigt)
|
||||
- [ ] Staging-Redirect-URI bei KWP registriert; AVV/Subprozessor-Vermerk an VR-P31 weitergereicht
|
||||
- [x] **KWP-API-Zugang dauerhaft aktiv** (Auth-Code, Token, Scope und geschützter Resource-Call bleiben
|
||||
bewiesen; erneuter Langzeit-Proof nach Refresh-Regression mit 20/20 Demand-Rotationen erbracht)
|
||||
- [x] **Recut-Detailplanung pro Milestone** (M089–M095) gegen echte Doku + Herstellerantworten — alle 7 Vertrags-Fragen für die Planung beantwortet
|
||||
- [x] **`kwpsync.exe` NICHT gebaut** (Recut bindend bestätigt)
|
||||
- [x] Staging-Redirect-URI bei KWP registriert; AVV/Subprozessor-Vermerk an VR-P31 weitergereicht
|
||||
|
||||
## Quellen (granular)
|
||||
- **`docs/milestones/M19-KWP-API-RECUT.md` (bindend)** → 7 offene Vertrags-Fragen, `appsEngine.prisma`-Übernahme-Liste, Credential-Hinweis
|
||||
- `ROADMAP-V2.md` → §v2-P5 + §Offene Vorlauf-Tasks #1 (KWP-API-Vertrag ~20.07.)
|
||||
- `ROADMAP.md` → Phase 32 · `PHASE-SOURCES.md` → Phase 32 (Callback-URL gemeldet, bnWin.net-8.1-N3, Andockpunkte v1)
|
||||
- **`.planning/KWP-API-CONTRACT.md` (bindend)** → 7 offene Vertrags-Fragen, `appsEngine.prisma`-Übernahme-Liste, Credential-Hinweis
|
||||
- [Offizielle KWP-API-Dokumentation](https://www.kwpsoftware.de/kwp-api-dokumentation/) → dynamische
|
||||
Host-Auflösung, userbezogene Auth, `mandant`-Query und Azure-Blob-Dokumentenaustausch
|
||||
- Tenant-OpenAPI `https://geerkens2.app04.kwp-online.de/relay/geerkens2/pwa/swagger/v1/swagger.json`
|
||||
→ maßgeblicher maschinenlesbarer Vertrag für `geerkens2`, einschließlich
|
||||
`GET /api/Mandant/Load`/`DtoMandant` (Snapshot/Hash siehe Umsetzung)
|
||||
- `ROADMAP-V2.md` → §v2-P5 + §Offene Vorlauf-Tasks #1 (Runtime-/Capability-Restvertrag)
|
||||
- `ROADMAP.md` → Phase 32 · Milestones: (Callback-URL gemeldet, bnWin.net-8.1-N3, Andockpunkte v1)
|
||||
- abhängig-für: `ticket-docs/VR-P32a.md`/`VR-P32b.md`/`VR-P32c.md`
|
||||
|
||||
## Umsetzung (2026-06-25, Owner Raffael) — Zugang aktiv, Vertrags-Fragen teil-beantwortet
|
||||
## Umsetzung (2026-06-25 / Vertragsprüfung 2026-07-12 / Herstellerantworten 2026-07-20, Owner Raffael)
|
||||
|
||||
**Historischer Abschlussstand:** **VEXT-1: 4/4 DoD = 100 % done.** Der Staging-Erst-Proof vom 2026-07-21 schloss Auth-Code,
|
||||
Token, Scope, geschützten Resource-Call und verschlüsselte Persistenz ab. Der Haltbarkeits-Deploy und neun
|
||||
aufeinanderfolgende automatische Refresh-Rotationen vom 2026-07-22 schließen den Dauer-Live-Punkt. `VN-1`
|
||||
bleibt als eigenständiges Testumgebungs-Ticket offen. Im Reconnect wurde eine Bindung über den generischen
|
||||
Verbindungsflow ausdrücklich bestätigt und verschlüsselt gespeichert; ihr Wert wird nicht in dieser Doc
|
||||
wiederholt und begründet keine Freigabe kontrollierter Fach-E2E-Daten. Proof
|
||||
2026-07-12: Tenant-OpenAPI vollständig
|
||||
abgerufen und per SHA-256 fixiert; offizielle KWP-Webdoku gegengeprüft; Keycloak-Authorization-Probe mit dem
|
||||
gelieferten externen Client, PKCE/S256 und den fünf externen Scopes für Produktions- und Staging-Redirect jeweils
|
||||
HTTP 200/Login-Seite ohne `invalid_client` oder `invalid_redirect`; kein ausführbarer `kwpsync.exe`-Konsument
|
||||
im Repository angelegt. Der Staging-Redirect ist damit am Authorization-Endpunkt plausibilisiert; der konkrete
|
||||
Cloud-Credential-/Relay-/Azure-Austausch-Vermerk wurde am 2026-07-12 in `VR-P31` übernommen.
|
||||
|
||||
**Zusatz-Proof 2026-07-12:** Die Freischaltungs-Mail wurde ausschließlich lokal verarbeitet; die Felder
|
||||
`KWP_OAUTH_CLIENT_ID`, `KWP_OAUTH_CLIENT_SECRET`, `KWP_OAUTH_SCOPES`, `KWP_CUSTOMER_CODE` und
|
||||
`KWP_OIDC_ISSUER` wurden per SOPS/age verschlüsselt abgelegt. Für lokale Tests und Staging bleibt das aktuell
|
||||
provisionierte Secret unverändert; ohne ausdrücklichen User-Auftrag wird es weder rotiert noch als Test- oder
|
||||
Deploy-Blocker behandelt. Der Token-Endpunkt antwortete auf
|
||||
`client_credentials` mit `401 unauthorized_client` (Service-Account deaktiviert); der Device-Endpoint auf den
|
||||
Device Authorization Grant mit `400 unauthorized_client` (Flow deaktiviert). Scope-Probes bestätigten die fünf
|
||||
gelieferten `*-extern`-Scopes gemeinsam mit `openid`/`offline_access`; nur `email` ist für den Client nicht
|
||||
freigeschaltet. Der Auth-Code-Flow leitete an die bei KWP registrierte Staging-Redirect-URL weiter; dort war zu
|
||||
diesem Zeitpunkt noch kein HiveGrid-Callback-Handler deployt. Ohne bnWin-Benutzerlogin entstand zudem kein
|
||||
Code/Token. Einmalige PKCE-State-/Verifier-Dateien wurden danach lokal entfernt.
|
||||
|
||||
**Lokaler Pilot-Slice 2026-07-20:** Der Worktree enthält nun den festen Setup-/Callback-Pfad und bindet die
|
||||
Prozess-Credentials über `KWP_HIVEGRID_TENANT_ID` an genau einen HiveGrid-Tenant. Dieser Stand ist nicht auf
|
||||
Staging oder Produktion deployt und begründet weder einen erfolgreichen Callback noch Token-/Resource-Proof.
|
||||
`KWP_MANDANT` bleibt bis zur Geerkens-Antwort bewusst ungesetzt. Lokaler Basis-Proof: Implementierungs-Commit
|
||||
`f0a0033bb`, Typecheck/Lint grün und 6.926 Tests bestanden; den vollständigen Verify-Stand einschließlich der
|
||||
vorbestehenden Route-Inventar-Drift dokumentiert `VR-P32a`. Das ist nur Code-Regressions-Proof und kein
|
||||
Auth-/Token-/Scope-/Resource-/Refresh-Live-Proof. KWP-Disconnect ist im Pilot in UI und Action fail-closed deaktiviert, weil eine lokale
|
||||
Connection-Löschung den Keycloak-Refresh-Token nicht nachweisbar widerruft. Reconnect bleibt möglich;
|
||||
providerseitige Revocation ist unverifiziert und bleibt Token-Lifecycle-Nachzug sowie Live-Blocker.
|
||||
Plane-Kommentar: `00c2720b-1a72-44b8-9d51-5b7c7c1fa647`. **VEXT-1 bleibt 3/4 DoD = 75 % done**.
|
||||
|
||||
**Lokaler HTTP-/Provider-Proof 2026-07-20:** Login `200`, Session `302`, authentifiziertes KWP-Setup `200`
|
||||
und Authorization-Redirect `302` wurden über den laufenden lokalen Web-Prozess ausgeführt. Der erzeugte
|
||||
Authorization-Request ist vollständig und verwendet exakt die sieben vereinbarten Scopes sowie PKCE/S256.
|
||||
Keycloak akzeptiert die registrierte Staging-Callback-URL (`200`, BNWIN-Loginformular), nicht jedoch die nicht
|
||||
registrierte Localhost-Callback-URL (`400 invalid_redirect_uri`). Die Staging-Setup-/Callback-Routen liefern
|
||||
bis zum Deploy dieses Branches beide `404`. Damit endet ein rein lokaler E2E-Lauf vor der Benutzeranmeldung.
|
||||
Dieser Proof ändert die DoD-Zählung nicht: **VEXT-1 bleibt 3/4 DoD = 75 % done; offen:
|
||||
1 Punkt, extern durch BNWIN-Testzugang/`mandant`-Auskunft blockiert, 0 selbst machbar.**
|
||||
|
||||
**Staging-Callback-Retest 2026-07-20:** Der echte BNWIN-Login einschließlich Zustimmung wurde abgeschlossen
|
||||
und der gültige OAuth-Rückruf erreichte HiveGrid. Challenge und `state` wurden erfolgreich eingelöst; der
|
||||
anschließende Token-/Aktivierungspfad endete jedoch vor jeder verschlüsselten Token-Persistenz, und die
|
||||
reservierte Verbindung blieb `pending`. Der bisherige Catch ließ Token-Austausch, KWP-Health und Persistenz
|
||||
nicht sicher unterscheiden; der Follow-up ergänzt dafür ausschließlich feste, secretsichere Diagnosecodes.
|
||||
Ein geschützter Resource-Aufruf steht weiter aus. Es gab keine Credential-Rotation und keine Änderung an
|
||||
Produktion oder `KWP_MANDANT`. **VEXT-1 bleibt 3/4 DoD = 75 % done; offen: 1 Live-Proof-Punkt.**
|
||||
Der secretsichere Diagnose-Follow-up liegt lokal in Commit `4886f3132`; **57/57** gezielte KWP-Tests und der
|
||||
vollständige Lauf mit **6.975 bestandenen / 55 übersprungenen Tests** sind grün. Ein neuer Live-Versuch folgt
|
||||
erst nach dem Staging-Deploy dieses Commits.
|
||||
|
||||
**Staging-Scope-Diagnose 2026-07-21:** Nach dem Deploy der secretsicheren Diagnose auf Revision
|
||||
`65976d712` erreichten zwei frische OAuth-Rückrufe den Token-Austausch und scheiterten reproduzierbar mit
|
||||
`exchange_failed` / `scope_mismatch`. Damit ist die alte einzelne `pending`-Verbindung als Ursache
|
||||
ausgeschlossen: Der Setup-Pfad verwendet sie bei jedem neuen Versuch weiter, und ein fehlgeschlagener Callback
|
||||
verändert sie nicht. Der Token-Response enthielt bereits Access-Token, Refresh-Token und eine gültige Ablaufzeit;
|
||||
HiveGrid verlangte danach jedoch fälschlich ein exaktes Echo aller sieben Request-Scopes. Der lokale Fix lässt
|
||||
im Response-Echo ausschließlich das Fehlen von `openid` und/oder `offline_access` zu. Alle fünf
|
||||
`*-extern`-Scopes bleiben zwingend, unbekannte und doppelte Scopes werden abgelehnt, und Requests sowie
|
||||
verschlüsselte Soll-Policy bleiben exakt auf den sieben kanonischen Scopes. Derselbe Vertrag gilt beim Refresh;
|
||||
Rotation und 300-Sekunden-TTL ändern sich nicht. Lokaler Proof: **80/80** gezielte KWP-Tests, **189/189**
|
||||
Tests im Integrationspaket und der vollständige Lauf mit **6.985 bestandenen / 55 übersprungenen Tests** sind
|
||||
grün; ebenso Typecheck, Lint, die vier allgemeinen Repository-Validatoren, `git diff --check` und der
|
||||
EU-Provider-Scan. Keine Rotation, keine Änderung an `KWP_MANDANT`, keine Produktionsänderung. Ein Deploy und
|
||||
der geschützte Resource-Call stehen weiter aus;
|
||||
**VEXT-1 bleibt 3/4 DoD = 75 % done.**
|
||||
|
||||
**Staging-Abschluss-Proof 2026-07-21:** Der Scope-Fix aus PR `#191` wurde als Revision `56d2b4f00`
|
||||
ausschließlich auf Staging deployt; Deploy-Run `10863` war erfolgreich und alle Staging-Runtime-Container
|
||||
liefen anschließend auf exakt dieser Revision. Der danach neu gestartete echte BNWIN-Login samt Zustimmung
|
||||
schloss den Authorization-Code-/PKCE-Flow ab. Der Callback aktivierte genau eine `DataConnection`, speicherte
|
||||
die Credentials per-Tenant-DEK verschlüsselt und führte über den registrierten KWP-Adapter einen erfolgreichen
|
||||
geschützten Health-Aufruf auf `Core/GetApiVersion` aus. Der Datenbank-Proof zeigte `connectionStatus=active`,
|
||||
vorhandenes Ciphertext-Material und `healthMessageKey=integrations.kwp.health.active`. Um **02:54:47 CEST**
|
||||
schloss der General Worker `integrations-token-refresh` erfolgreich ab; `tokenExpiresAt` rückte dabei auf
|
||||
**02:59:47 CEST** vor und der anschließende Health-Stand blieb `active`. Da der Adapter beim Refresh einen
|
||||
neuen, vom vorherigen Wert verschiedenen Refresh-Token verlangt, beweist dieser Lauf auch die einmalige
|
||||
Refresh-Token-Rotation. Es wurden keine Token-, Secret- oder Passwortwerte ausgelesen oder protokolliert.
|
||||
Kein Client-Secret, Passwort oder API-Key wurde rotiert; ausschließlich der von KWP zwingend rotierende
|
||||
Einmal-Refresh-Token wurde im normalen Refresh-Flow ersetzt. `KWP_MANDANT` blieb ungesetzt und Produktion
|
||||
blieb auf der unveränderten Revision `6100b4e16`. Dieser Erstlauf erfüllte den Live-Proof zunächst vollständig;
|
||||
die nachfolgende Langzeitkorrektur nimmt den damaligen Abschluss-Claim wieder zurück.
|
||||
|
||||
**Langzeit-Korrektur 2026-07-21:** Der Erst-Proof war echt, der Dauerbetrieb ist jedoch nicht grün. Nach einem
|
||||
erfolgreichen Refresh um **03:04:46 CEST** (`refreshed=1`, Dauer 701 ms) endete der nächste Lauf um
|
||||
**03:09:54 CEST** nach **7,36 s** mit `refreshed=0`, `failed=1`. Die `DataConnection` steht seitdem auf
|
||||
`broken`, `healthMessageKey=integrations.health.refreshFailed`; Ciphertext bleibt vorhanden. Der auf der
|
||||
damaligen Staging-Revision laufende Worker verwirft beim Provider-Aufruf den konkreten Fehlercode, daher lässt
|
||||
sich aus Worker-, BullMQ- und Loki-Proof nicht sicher zwischen Provider-Ablehnung und transientem
|
||||
Transportfehler unterscheiden. Kein
|
||||
Client-Secret, Passwort oder API-Key wurde rotiert, `KWP_MANDANT` blieb ungesetzt und Produktion unverändert.
|
||||
Der vorherige 100-%-Claim wird zurückgenommen: **VEXT-1: 3/4 DoD = 75 % done · 1 Punkt diagnostisch offen ·
|
||||
1 selbst machbar.**
|
||||
|
||||
**Lokaler Refresh-Stabilitätsfix 2026-07-21:** Der zu diesem Zeitpunkt noch nicht deployte Follow-up klassifiziert
|
||||
Providerfehler ausschließlich über feste Diagnosecodes und einen optionalen numerischen HTTP-Status; weder
|
||||
Provider-Body noch Token- oder Secret-Werte werden gespeichert oder geloggt. Genau ein transienter Fehler
|
||||
(`408`, `429`, `5xx`, Netzwerk/Timeout oder die allowgelisteten OAuth-Fehler `server_error` und
|
||||
`temporarily_unavailable`) wird nach frühestens fünf Minuten einmal wiederholt. Dauerhafte Auth-/Scope-/
|
||||
Credential-Fehler und ein zweiter transienter Fehler setzen die Verbindung auf `broken` und verlangen einen
|
||||
Reconnect. Während des Retry-Fensters läuft keine konkurrierende Health-Probe. Auch nach erfolgreichem
|
||||
Token-Retry bleibt die Verbindung `degraded` mit `integrations.health.refreshRecovered`, bis ein echter
|
||||
geschützter `Core/GetApiVersion`-Probe sie wieder auf `active` setzt. Ein älter als zehn Minuten liegen
|
||||
gebliebener Claim wird ohne erneuten Provider-Aufruf terminalisiert. BullMQ weist geplante Retries separat als
|
||||
`retryScheduled` statt als `failed` aus. Tests decken die persistierte Einmal-Token-Kette `r1 → r2 → r3`,
|
||||
die Fünf-Minuten-Grenze, unbekannten POST-Ausgang, Status-/OAuth-Klassifizierung, Retry-Erschöpfung,
|
||||
Resource-Probe und Stale-Claim-Recovery ab. Der bestehende `broken`-Datensatz wird absichtlich nicht mit alten
|
||||
Credentials erneut verwendet; nach dem Staging-Deploy ist genau ein neuer interaktiver OAuth-Reconnect nötig.
|
||||
Lokaler Proof: **80/80** gezielte KWP-Tests, **217/217** Tests im Integrationspaket, **1/1** fokussierter
|
||||
Worker-Handler-Test sowie der vollständige Root-Lauf mit **7.026 bestandenen / 55 übersprungenen Tests** sind
|
||||
grün. Ebenso grün sind Root-Typecheck, Root-Lint, Integrations-/Worker-Typecheck, `verify:ci-baseline`,
|
||||
`verify:source-health`, `verify:i18n`, `verify:secrets`, `git diff --check` und der EU-Provider-Scan.
|
||||
Bis dieser Reconnect und mehrere echte Refresh-/Resource-Zyklen stabil belegt sind, bleibt
|
||||
**VEXT-1: 3/4 DoD = 75 % done · 1 Live-Punkt offen · 1 selbst machbar.** Es wurde nichts manuell rotiert,
|
||||
`KWP_MANDANT` bleibt ungesetzt und Produktion bleibt unverändert.
|
||||
|
||||
**Staging-Langzeitstand und lokaler Haltbarkeits-Nachzug 2026-07-22:** Die beobachtete Staging-Revision war
|
||||
`d4daa0421`. Der präzisierte Worker-/Datenbankabgleich zeigt um **03:04:47 CEST** einen erfolgreichen
|
||||
Refresh und um **03:09:53 CEST** den direkt folgenden fehlgeschlagenen Lauf. Die `DataConnection` wechselte
|
||||
auf `broken` mit `integrations.health.refreshFailed`; eine konkrete Provider-/Transportklassifikation war in
|
||||
den verfügbaren Runtime-Diagnosen nicht vorhanden. Der dauerhafte Runtime-Proof bleibt deshalb offen.
|
||||
|
||||
Der Haltbarkeits-Nachzug ist lokal **abgeschlossen**, aber noch nicht deployt. Er bindet die
|
||||
Handler-Diagnostik an den strukturierten Runtime-Logger, trennt nachweislich replay-sichere Fehlerantworten
|
||||
von mehrdeutigen Token-POST-Ausgängen und wiederholt einen möglicherweise bereits verbrauchten
|
||||
Einmal-Refresh-Token niemals beim Provider. Retries gelten ausschließlich der lokalen Persistenz eines schon
|
||||
erhaltenen Provider-Ergebnisses; der KWP-spezifische Refresh-/Health-Gate wird außerdem früher ausgeführt.
|
||||
Erst mehrere erneute echte Refresh-/Resource-Zyklen können den Live-Punkt schließen. Keine manuelle Rotation,
|
||||
keine Deploy- oder Live-Proof-Behauptung für diesen Nachzug. Der vollständige lokale Root-Testlauf ist mit
|
||||
**7.115 bestandenen / 55 übersprungenen Tests** grün; ebenso Root-Typecheck/-Lint, Worker-Build und die
|
||||
relevanten Deploy-, Runtime-, i18n-, Observability-, CI-, Source-, Secret- und Env-Gates. **VEXT-1 bleibt
|
||||
3/4 DoD = 75 % done · 1 Live-Punkt offen · 1 selbst machbar.**
|
||||
|
||||
**Staging-Abschluss des Dauer-Live-Proofs 2026-07-22:** Der Haltbarkeits-Nachzug aus PR `#210` wurde als
|
||||
Revision `2938f29da` über den erfolgreichen Deploy-Run `10995` auf Staging ausgerollt. Nach genau einem
|
||||
normalen Authorization-Code-/PKCE-Reconnect war die Connection spätestens beim automatischen geschützten
|
||||
Health-Probe um **03:54:47 UTC** `active`; der Probe meldete `checked=1`, `unhealthy=0`. Der
|
||||
`worker-general` rotierte die KWP-Einmal-Refresh-Token danach neunmal automatisch und ohne Fehler:
|
||||
**03:58:09**, **04:02:09**, **04:06:09**, **04:10:09**, **04:14:09**, **04:18:09**, **04:22:09**,
|
||||
**04:38:09** und **04:42:09 UTC**; `tokenExpiresAt` stieg dabei bis auf **04:47:09.642 UTC**. Alle neun Läufe
|
||||
meldeten `outcome=refreshed`, `failed=0` und `retryScheduled=0`; weder Provider- noch Persistenzfehler traten
|
||||
auf. Die automatischen geschützten Health-Sweeps um **04:24:47 UTC** und **04:39:47 UTC** meldeten jeweils
|
||||
`checked=1`, `unhealthy=0`. Der abschließende Read-only-Snapshot um **04:44:48 UTC** blieb `active` /
|
||||
`integrations.kwp.health.active` mit
|
||||
verschlüsselten Credentials. Kein Client-Secret, Passwort,
|
||||
API-Key oder anderes Staging-Credential wurde manuell rotiert; ausschließlich KWP rotierte den
|
||||
Einmal-Refresh-Token im normalen OAuth-Flow. Produktion blieb unverändert. Der Dokumentationsnachzug ist mit
|
||||
Root-Typecheck, Root-Lint, **7.115 bestandenen / 55 übersprungenen Tests**, `verify:ci-baseline`,
|
||||
`verify:source-health`, `verify:secrets`, `git diff --check` und dem EU-Provider-Scan grün.
|
||||
**VEXT-1: 4/4 DoD = 100 % done.**
|
||||
|
||||
**Geliefert von KWP (Mandant `geerkens2`):** OAuth2-Zugang via **Keycloak-OIDC, Realm `kwp-federated`**
|
||||
(`id.kwp-online.de`). Confidential Client (`offline_access`), ClientId-Schema `_extern-<tenant>`, Tenant-Kürzel
|
||||
als URL-Param `tenant=geerkens2` am Authorization-Endpoint. **Secret NICHT in Repo/Doc** — gehört in
|
||||
Coolify-Secret-Store bzw. später per-Tenant-DEK in `DataConnection.config` (AD-8); da es per Mail/Chat lief →
|
||||
bei KWP **Rotation vor Prod** einplanen.
|
||||
Coolify-Secret-Store bzw. später per-Tenant-DEK in `DataConnection.credentialsCiphertext` (AD-8). Für Staging gilt die
|
||||
verbindliche No-Rotation-Regel aus `AGENTS.md`: vorhandene Credentials unverändert verwenden, solange der User
|
||||
nicht ausdrücklich eine Rotation anordnet.
|
||||
|
||||
**OIDC-Discovery verifiziert** (`…/realms/kwp-federated/.well-known/openid-configuration`):
|
||||
**OIDC-Discovery aus dem Mail-/Keycloak-Pfad verifiziert** (`…/realms/kwp-federated/.well-known/openid-configuration`):
|
||||
Auth `…/protocol/openid-connect/auth` · Token `…/token` · Userinfo · JWKS `…/certs` · Logout · Introspection ·
|
||||
Revocation. `grant_types`: authorization_code, **refresh_token**, client_credentials, device_code, token-exchange u.a.
|
||||
`code_challenge_methods`: **plain, S256** (PKCE ✓). Token-Auth: client_secret_basic/-post, private_key_jwt, mTLS.
|
||||
`scopes_supported` global nur `openid, email` → die fachlichen Scopes sind **Client-zugewiesene Keycloak-Scopes**
|
||||
(die aus der Mail sind maßgeblich für unseren Token-Request).
|
||||
|
||||
**Resource-API gefunden** (vom Partner geliefert): Swagger-UI
|
||||
`https://kwp3.app02.kwp-online.de/relay/kwp3/pwa/swagger/index.html`, OpenAPI-JSON unter
|
||||
`…/swagger/v1/swagger.json`. Title „KWP Api" v1, basePath **`/relay/kwp3/pwa`**, Security = OAuth2.
|
||||
**Charakter: RPC-artige Action-API** (nicht REST-CRUD): `/api/Adresse/LoadAdressKomplett|Add|Save|Search|…`,
|
||||
`/api/Aktivitaet/AddAktivitaet|SaveInfoEintrag|…`, `/api/Abteilung/…`. Description: „respecting permissions and
|
||||
user context" → User-gebunden (deshalb Auth-Code-Flow, nicht reines client_credentials).
|
||||
**Token-Lifecycle laut Herstellerantwort 2026-07-20:** Access-Token gelten **5 Minuten** zuzüglich **5 Minuten
|
||||
technischem Clock-Skew**. Refresh-Token gelten **30 Tage idle**, höchstens **365 Tage**, sind einmalig und
|
||||
werden bei jeder Access-Token-Anforderung rotiert. Passwortänderung und Benutzerdeaktivierung widerrufen die
|
||||
Token. Der Geerkens-Pilot muss den jeweils neu gelieferten Refresh-Token verschlüsselt ersetzen.
|
||||
|
||||
**Auth-Endpunkt-Diskrepanz — Runtime-Pfad live geklärt:** Die Tenant-OpenAPI nennt dagegen
|
||||
`https://geerkens2.app04.kwp-online.de/relay/geerkens2/pwa/connect/authorize` und `…/connect/token`.
|
||||
Der Staging-Live-Lauf bestätigt den von KWP per Mail benannten zentralen Keycloak-Authorization- und
|
||||
Token-Endpunkt als verbindlichen Runtime-Pfad: Authorization Code + PKCE, Token-Austausch, geschützter
|
||||
Relay-Resource-Aufruf und Refresh liefen dort erfolgreich. Die abweichenden `/connect/*`-Metadaten der
|
||||
Tenant-Swagger werden daher nicht für HiveGrid verwendet. Service-Account- und Device-Flow bleiben für den
|
||||
Client deaktiviert; der echte bnWin-Benutzerlogin ist zwingend. Laut offizieller KWP-Doku handelt die API
|
||||
immer im Namen dieses Benutzers; dessen Rechte begrenzen alle Antworten und Schreibaktionen.
|
||||
|
||||
**Maßgebliche Resource-API für Geerkens:** Hosts werden nicht hart kodiert, sondern über
|
||||
`https://loadbalancer.kwp-online.de/Relay/GetAppUrl?linkId=<KUNDENKUERZEL>` ermittelt. Für `geerkens2` lieferte
|
||||
der Loadbalancer am 2026-07-12 `https://geerkens2.app04.kwp-online.de`; der Vertrag liegt unter
|
||||
`/relay/geerkens2/pwa/swagger/v1/swagger.json`. Snapshot: **OAS 3.0.1 · 301 Pfade · 303 Operationen ·
|
||||
396 Schemas · SHA-256 `5c504ffa955bc492fcc16ae01a92ad0491db29a904ad59058123fc3b24f26762`**.
|
||||
Eine erneute Live-Probe am 2026-07-20 nach dem Hersteller-Update liefert **OAS 3.0.4 · 550 Pfade · 554
|
||||
Operationen · 490 Schemas · SHA-256
|
||||
`dcaff9253fe1bd2bf9bf6f29c89de7bd1f4415e115d90320775ead7e49c5febc`**. Der ältere Wert bleibt als
|
||||
historischer 12.07.-Snapshot dokumentiert; für weitere Planung ist der 20.07.-Vertrag maßgeblich.
|
||||
Der Server-Pfad ist `/relay/geerkens2/pwa`; die API bleibt RPC-artig. Nutzt ein Kunde bnWin-Mandanten, verlangt
|
||||
die offizielle Doku bei jedem Request zusätzlich den Queryparameter `mandant=<Mandantenkürzel>`. Der Hersteller
|
||||
hat präzisiert: Der Parameter wird nur gesetzt, wenn in kwp-bnWin.net tatsächlich ein Mandant eingerichtet ist,
|
||||
dann mit dem dortigen Kürzel; andernfalls wird er weggelassen. `GET /api/Mandant/Load` beschreibt die für den
|
||||
aktuellen Benutzer zulässigen Mandanten als `DtoMandant` mit interner `id`, Kürzel und Bezeichnung. Da die
|
||||
OpenAPI-Security dieses Endpoints andere KWP-Produkt-Scopes statt der fünf gelieferten `*-extern`-Scopes nennt,
|
||||
muss VR-P32a den Zugriff opportunistisch prüfen und einen bewussten manuellen Fallback anbieten. Ein Fehler oder
|
||||
eine leere Antwort darf nicht automatisch als „kein Mandant“ gelten. Die konkrete Geerkens-Bindung steht noch
|
||||
aus.
|
||||
|
||||
**Stand der 7 Vertrags-Fragen:**
|
||||
1. **Auth-Methode → ✅ geklärt:** OAuth2/OIDC (Keycloak), Auth-Code + PKCE (S256), Confidential Client +
|
||||
`offline_access`/Refresh → `DataConnection.type='oauth2'` (NICHT `rest-api`). Pro HiveGrid-Tenant eigene
|
||||
ClientId/Secret/`tenant`-Kürzel in DEK-`config`.
|
||||
2. **Endpoints/Capabilities → 🟠 teilweise:** Adresse (Kontakte/Ansprechpartner/Custom-Felder/Geo/Anrufer-Info),
|
||||
Aktivität, Abteilung bestätigt. **`Vorgang` (=Projekt-Kern!), `Termin`, `Archiv` noch zu erfassen** — in der
|
||||
`pwa`-Spec nicht im (gekürzten) WebFetch-Ausschnitt sichtbar; evtl. eigene Relay-Module. → **Spike** (echter
|
||||
HTTP-Client, volle JSON laden).
|
||||
3. **Webhook-Support → 🟠 offen:** in der abgerufenen `pwa`-Spec keine `webhooks`/`callbacks` gesehen (Sicht war
|
||||
gekürzt) → Arbeitshypothese **Pull-Modell**; final im Spike/bei KWP bestätigen. Steuert M094 (Trigger- vs.
|
||||
Cron-Pull) + M092.
|
||||
4. **Rate-Limits → ❓ offen** (nicht in Discovery/Swagger-Übersicht) → bei KWP erfragen; steuert Replay-Rate M091.
|
||||
5. **Versionierung → 🟢 teilweise:** API `v1`, basePath `/relay/kwp3/pwa`. Changelog-Politik bei KWP erfragen.
|
||||
6. **Dokumenten-API → 🟠 offen:** Scope `archiv-extern` existiert, Endpoints noch zu erfassen (Spike) → M095.
|
||||
7. **Konflikt-Felder → ❓ offen:** Response-Schema je Entität auf `version_hash`/`last_modified` prüfen (Spike) → M093/M094.
|
||||
1. **Auth-Methode → 🟡 Vertrag sowie Auth-/Resource-Erst-Proof abgeschlossen; Dauerbetrieb offen:** OAuth2/Auth-Code + PKCE und Refresh/
|
||||
`offline_access` → `App.connectionType='oauth2'`. `client_credentials` und Device Flow sind für den Client
|
||||
deaktiviert. Gültiger Request-Scope ist `openid` + fünf `*-extern`-Scopes + `offline_access`; `email` darf
|
||||
nicht angefordert werden. Userbezogene Rechte sind bindend. Access-Token: 5 Minuten plus 5 Minuten Clock-Skew;
|
||||
Refresh-Token: 30 Tage idle/maximal 365 Tage, einmalig und bei jeder Access-Token-Anforderung rotiert,
|
||||
Widerruf bei Passwortänderung oder Benutzerdeaktivierung. Staging bewies Token-Austausch, geschützten
|
||||
Relay-Aufruf und automatische Refresh-Rotation über den zentralen Keycloak-Pfad.
|
||||
2. **Endpoints/Capabilities → 🟢 tenant-spezifisch erfasst, Project-Create nicht unterstützt:** In den
|
||||
Operation-Security-Angaben erscheint `adresse-extern` aktuell an **23**, `archiv-extern` an **15**, `termin-extern`
|
||||
an **14**, `vorgang-extern` an **31** und `aktivitaet-extern` an **31** Operationen. Adresse, Aktivität,
|
||||
Termin/Monteursteuerung, Projekt/Projektampel/Vorgangsanzeige und Archiv sind vorhanden. Laut Hersteller ist
|
||||
die **Neuanlage eines kaufmännischen Auftrags/Projekts über die API ausdrücklich nicht vorgesehen**;
|
||||
`/api/Projekt/Save` ändert laut Vertrag nur die Bezeichnung eines bestehenden Projekts. Der geplante
|
||||
Won→Auftrag-Push ist damit im aktuellen Vertrag nicht umsetzbar und darf nicht auf eine andere Operation
|
||||
umgedeutet werden.
|
||||
3. **Webhook-/Delta-Support → 🟢 geklärt, nicht vorhanden:** KWP bietet keine Änderungs-Webhooks oder
|
||||
authentifizierten Änderungs-Callbacks und keine Delta-Cursor, als Delta-Vertrag nutzbaren einheitlichen
|
||||
Änderungszeitstempel oder
|
||||
„geändert seit“-Filter. Einzelne DTO-Felder aus Punkt 7 bilden keinen Delta-Vertrag. Ein späterer Pull muss
|
||||
daher ohne diese Herstellermechanismen geplant werden; er gehört nicht zum freigegebenen Callback-Slice.
|
||||
4. **Rate-Limits → 🟢 geklärt:** **60 Requests/Minute Hard-Cap pro Client.** Weitere Vorgaben zu parallelen
|
||||
Verbindungen, Backoff, Jitter oder `429` wurden nicht gemacht. Replay und Pull müssen den Hard-Cap selbst
|
||||
sicher einhalten; ihre Implementierung gehört nicht zum freigegebenen Callback-Slice.
|
||||
5. **Versionierung → 🟢 Planungsgrundlage geklärt:** API-Dokument `v1`; der an allen 554 Operationen geführte
|
||||
Header `x-kwp-client-version` ist laut Hersteller optional. Ein Pflicht-/Mindestwert wurde nicht vorgegeben;
|
||||
M092 plant deshalb gegen den verifizierten Vertrag statt gegen einen angenommenen Mindestwert.
|
||||
6. **Dokumenten-API → 🟢 vertraglich geklärt:** Listing/Suche/Details/Revisionen und Export sind unter
|
||||
`/api/archiv-extern/*` vorhanden. Dateien laufen laut offizieller Doku nicht im API-Body, sondern über Azure
|
||||
Blob Storage: `GetSetup.azureConnectionUri` maximal **6 h cachen**; Blobs werden nach **24 h gelöscht**;
|
||||
`ExportDatei(revisionId,guid)` liefert `exchangeFileUri`, diese URL liefert JSON mit dem eigentlichen
|
||||
Downloadlink. Upload: Blob ablegen, dann `ImportDatei(containerId,dateiname)` aufrufen.
|
||||
7. **Konflikt-Felder → 🟢 Planungsentscheidung abgeschlossen:** Aktivitäten liefern `datumAenderung`/`userAenderung`; Archiv-
|
||||
DTOs liefern `letzteAenderungAm`/`letzteAenderungVon` sowie `revisionId`/`revision`. Adresse, Termin und
|
||||
Projekt/Vorgang haben keine einheitlichen Record-Versionen oder Änderungszeitstempel. Es gibt keine
|
||||
`ETag`-/`Last-Modified`-Responses oder `If-Match`-Preconditions. M093 darf daher nicht auf uniformes
|
||||
KWP-Optimistic-Locking bauen.
|
||||
|
||||
**NEU — offene Frage (Scope-Mapping):** Mail-Scopes sind `adresse-extern archiv-extern termin-extern
|
||||
vorgang-extern aktivitaet-extern offline_access`; die Swagger-Security nennt interne Scope-Namen
|
||||
(`adressverwaltung`, `aktivitaetenverwaltung`, `projektampel`, `wartungswesen`, `mobmont`, …). Klären, ob die
|
||||
`*-extern`-Scopes intern gemappt werden und alle benötigten Endpoints abdecken.
|
||||
**Scope-Mapping — Authorization und Resource-Akzeptanz live bewiesen:** Die fünf `*-extern`-Scopes stehen jetzt direkt
|
||||
an den oben gezählten Operationen. Sie fehlen jedoch in der Scope-Liste des OAuth-Flows; außerdem kombiniert die
|
||||
Spec interne und externe Scope-Namen in einer Security-Liste, die nach strikter OpenAPI-Semantik alle Scopes
|
||||
gleichzeitig verlangen würde. Der Live-Lauf bestätigte alle fünf Pflicht-Scopes im Provider-Echo und die
|
||||
Akzeptanz des Access-Tokens am geschützten read-only Resource-/Health-Endpunkt. Schreib-Calls gehören nicht
|
||||
zum Geerkens-Pilot-Slice und wurden nicht ausgeführt.
|
||||
|
||||
**Noch zu tun (Rest dieses Tickets):** Spike gegen die echte API (Token holen → 1 Resource-Call →
|
||||
`Vorgang`/`Termin`/`Archiv`-Endpoints + Konflikt-Felder + Webhook/Rate-Limit erfassen); Staging-Redirect-URI bei
|
||||
KWP registrieren; AVV/Subprozessor-Vermerk an VR-P31/M166. **Bleibt v2** — Spike erst sinnvoll nach/mit R-P5.
|
||||
**Abschluss:** Auth-Code, Token-Austausch, Pflicht-Scopes, Relay-Pfad, geschützter read-only Resource-/Health-
|
||||
Call, neun aufeinanderfolgende automatische Refresh-Rotationen und automatische geschützte
|
||||
Health-Probes sind live bewiesen. Der Providerpfad ist
|
||||
secretsicher klassifiziert; die Connection blieb `active`. Der AVV/Subprozessor-Vermerk ist in VR-P31/M166
|
||||
übernommen und beide Redirects sind registriert. Die weiterhin fehlende KWP-Testumgebung bleibt in `VN-1`;
|
||||
sie verhindert keine Erfüllung dieses Zugangstickets. Im Reconnect wurde genau eine Mandantenbindung
|
||||
ausdrücklich bestätigt und verschlüsselt gespeichert; der konkrete Wert wird nicht in die Ticket-Doc kopiert.
|
||||
`KWP_MANDANT` bleibt als processweite Mapping-Quelle ungenutzt.
|
||||
|
||||
### Rückfragen an KWP (Entwurf, 2026-06-25 — via Noah/Geerkens weiterleiten)
|
||||
**Superseding Scope-Abschluss 2026-07-22:** Der aktuelle Produktvertrag nutzt ausschließlich lesende
|
||||
KWP-Operationen. Die fehlende Project-/Auftrag-Create-Capability wird nicht mehr als Blocker des Connectors
|
||||
oder der Inbound-Tickets geführt, sondern in `VEXT-6` bis zu einem belastbaren Herstellervertrag geparkt.
|
||||
**VEXT-1: 4/4 DoD = 100 % done.**
|
||||
|
||||
> Betreff: Rückfragen zur KWP-API-Anbindung (Mandant `geerkens2`)
|
||||
**Regression-Nachzug 2026-07-23:** Die Scope-Entscheidung bleibt unverändert read-only. Der erste
|
||||
Dauerbetriebs-DoD ist wegen der oben dokumentierten späteren Refresh-Regression erneut offen; die drei
|
||||
Vertrags-/Recut-Punkte bleiben erfüllt. **VEXT-1: 3/4 DoD = 75 % done · 1 Punkt offen · 1 selbst machbar.**
|
||||
|
||||
vielen Dank für die Freischaltung des API-Zugangs. Den OAuth2-Flow (Keycloak, Realm `kwp-federated`,
|
||||
Auth-Code + PKCE) und die OpenAPI-Doku unter `…/relay/kwp3/pwa/swagger/v1/swagger.json` konnten wir bereits
|
||||
einsehen. Für die saubere Anbindung haben wir noch einige Rückfragen:
|
||||
**Lokaler Regressionsfix-Proof 2026-07-23:** Commit `ccdc74ebe` vereinheitlicht die Laufzeitprüfung von
|
||||
Erst-Login und automatischem Refresh auf positive ganzzahlige Werte bis maximal 300 Sekunden und ergänzt
|
||||
feste redigierte Diagnosecodes für sämtliche semantischen Ablehnungsgründe. Ein mehrdeutiger Token-POST wird
|
||||
weiterhin nicht wiederholt; es wurden keine Credentials manuell rotiert. Proof: Integrationspaket
|
||||
**290/290**, fokussierter Worker-Satz **6/6**, Root-Typecheck, Root-Lint und Root-Testlauf **1.028 Dateien /
|
||||
7.387 Tests bestanden, 55 übersprungen** sowie sämtliche release-relevanten Vertrags-, RLS-, Coverage-,
|
||||
Hot-Swap-, Secret-, Deploy- und Build-Gates grün. Der dauerhafte Runtime-Proof bleibt bis normalem Reconnect
|
||||
und erneutem Staging-Langzeitlauf offen. **VEXT-1: 3/4 DoD = 75 % done · 1 Live-Punkt offen.**
|
||||
|
||||
1. **Daten-Endpunkte/Umfang:** Die uns vorliegende `pwa`-Swagger zeigt vor allem Adresse, Aktivität und
|
||||
Abteilung. Über welche Endpunkte bzw. welche weiteren Relay-Module erreichen wir die Bereiche **Vorgang,
|
||||
Termin und Archiv** (unsere Scopes `vorgang-/termin-/archiv-extern`)? Gibt es eine vollständige/aggregierte
|
||||
OpenAPI-Spezifikation?
|
||||
2. **Scope-Mapping:** Zugewiesen sind `adresse-/archiv-/termin-/vorgang-/aktivitaet-extern` (+ `offline_access`).
|
||||
In der Swagger-Security stehen interne Scope-Namen (`adressverwaltung`, `aktivitaetenverwaltung`,
|
||||
`projektampel`, …). Werden die `*-extern`-Scopes intern darauf gemappt, und decken sie alle benötigten
|
||||
Endpunkte ab?
|
||||
3. **Synchronisation:** Gibt es **Webhooks/Push** bei Änderungen (KWP → uns), oder ist die Sync rein **Pull**?
|
||||
Falls Pull: gibt es Delta-/„geändert seit"-Parameter (Zeitstempel/Cursor)?
|
||||
4. **Konflikt-/Versionsfelder:** Liefern die Antworten je Datensatz ein Änderungsdatum bzw. eine Version
|
||||
(`last_modified`/`version`/ETag) für Delta-Sync und Konflikt-Erkennung?
|
||||
5. **Rate-Limits:** Welche Limits gelten (Requests/Minute, parallele Verbindungen)? Empfohlene Poll-Intervalle?
|
||||
6. **Token-Lebensdauer:** Gültigkeit Access-/Refresh-Token; rotieren die Refresh-Token bei Nutzung? (Relevant für
|
||||
den dauerhaften Hintergrund-Sync mit `offline_access`.)
|
||||
7. **Schreibzugriff:** Die Endpunkte enthalten Add/Save/Remove. Sind die externen Scopes lesend **und** schreibend
|
||||
nutzbar, und gibt es Einschränkungen, was ein externer Client schreiben darf?
|
||||
8. **Test-/Sandbox-Mandant:** Gibt es einen Test-/Sandbox-Tenant zum Entwickeln und für unsere Staging-Umgebung,
|
||||
statt gegen den Produktiv-Mandanten `geerkens2`?
|
||||
9. **Versionierung:** Wie wird die API versioniert (aktuell `/v1`) und wie werden Breaking Changes angekündigt?
|
||||
**Demand-Refresh-Live-Abschluss 2026-08-01:** PR `#312` wurde nach **11/11 grünen CI-Jobs** als normaler
|
||||
Merge `a55b811ccd652cc04264d8d09e0f270a6487f27d` über Deploy-Run `11609` auf Staging ausgerollt. Nach einem
|
||||
normalen Authorization-Code-/PKCE-Reconnect endeten im zweistündigen Fenster **20/20** Demand-Refreshes mit
|
||||
`outcome=refreshed`; acht Health-Sweeps meldeten `checked=1`, `unhealthy=0`. Es gab keine Provider-,
|
||||
Persistenz- oder Claim-Fehler, keinen `broken`-/`degraded`-Status und keine erneute Reconnect-Aufforderung.
|
||||
KWP wurde aus dem generischen Minutensweep ausgeschlossen und rotierte nur noch vor echter Arbeit oder dem
|
||||
regulären Health-Fenster. Damit ist der Runtime-DoD wieder geschlossen:
|
||||
**VEXT-1: 4/4 DoD = 100 % done · 0 Punkte offen · Done.**
|
||||
|
||||
Klein: Im Authorization-Beispiel stand `client_id=der-oauth-client` als Platzhalter — bestätigen Sie bitte, dass
|
||||
für uns `client_id=_extern-geerkens2` zu verwenden ist.
|
||||
### Herstellerantworten (eingearbeitet 2026-07-20)
|
||||
|
||||
1. **Project-Create:** Die Neuanlage eines Projekts/Auftrags über die API ist nicht vorgesehen.
|
||||
2. **Synchronisation:** Keine Änderungs-Webhooks oder authentifizierten Änderungs-Callbacks; keine Delta-Cursor, als Delta-Vertrag
|
||||
nutzbaren einheitlichen Änderungszeitstempel oder „geändert seit“-Filter.
|
||||
3. **Rate-Limit:** 60 Requests/Minute Hard-Cap pro Client; keine weiteren Vorgaben zu Parallelität,
|
||||
Backoff, Jitter oder `429`.
|
||||
4. **Token:** Access 5 Minuten plus 5 Minuten technischer Clock-Skew; Refresh 30 Tage idle/maximal 365 Tage,
|
||||
einmalig und bei jeder Access-Token-Anforderung rotiert; Widerruf bei Passwortänderung oder
|
||||
Benutzerdeaktivierung.
|
||||
5. **Testumgebung:** Keine Sandbox und kein Testkunde.
|
||||
6. **Mandant:** Nur setzen, wenn in kwp-bnWin.net ein Mandant eingerichtet ist; dann dessen Kürzel verwenden,
|
||||
sonst den Queryparameter erst nach ausdrücklicher `none`-Bestätigung weglassen. Bevorzugte Discovery ist
|
||||
`GET /api/Mandant/Load`; wegen der abweichenden Security-Scopes ist ein fail-closed manueller Fallback
|
||||
erforderlich. Im Live-Reconnect wurde genau eine Geerkens-Bindung bestätigt und verschlüsselt gespeichert;
|
||||
ihr konkreter Wert bleibt bewusst außerhalb der Ticket-Doc.
|
||||
7. **Client-Version:** `x-kwp-client-version` ist optional.
|
||||
|
||||
ClientId, Secret und reale Redirect-Werte bleiben ausschließlich im vereinbarten sicheren Kanal.
|
||||
Reference in new issue
Block a user