Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -1,4 +1,4 @@
# VR-P32a · KWP: Connector + Health + Push-Queue (M089/090/091)
# VR-P32a · KWP: Read-only Connector + Health (M089/090)
| | |
|---|---|
@@ -6,54 +6,571 @@
| **Owner** | Raffael |
| **Phase** | Phase 32 (v2-P5) — KWP-Integration (Recut) |
| **Cycle/Fenster** | v2-W2 — KWP/Portal/Mobile-Start · fällig 2026-07-22 |
| **Status** | geplant · 🟠 **block-2 (Partner-API offen, agil)** |
| **Status** | Done · **5/5 DoD = 100 % done** · Demand-Refresh auf Staging über zwei Stunden verifiziert |
> 🟠 **block-2 — Partner-API offen, agil:** Der konkrete KWP-API-Vertrag (Auth/Endpoints/Webhook-Support/Rate-Limits/Versionierung/Doc-API) ist noch offen — **KWP-API-Zugang ~19./20.07.** ist der härteste Kalender-Anker (das v2-Hauptverkaufsargument). Detail-Planung pro Milestone erst gegen die echte API-Doku (→ `VEXT-1`). Bau startet, sobald der Zugang aktiv ist; Reihenfolge/Umfang sind agil. **`kwpsync.exe` wird NICHT gebaut** (3→2-Komponenten, Recut bindend, M089 obsolet als Windows-Client).
>
> 🟢 **Update 2026-06-25 — Zugang eingetroffen (früher):** Auth-Frage geklärt → **`type='oauth2'`** (Keycloak-OIDC `kwp-federated`, Auth-Code + PKCE/S256, Confidential Client + `offline_access`/Refresh; Multi-Tenant über `tenant`-Param + ClientId/Secret je Mandant). Resource-API = RPC-artige Action-API, basePath `/relay/kwp3/pwa` (Swagger `…/swagger/v1/swagger.json`). Endpoint-/Webhook-/Rate-Limit-Details + `Vorgang`/`Termin`/`Archiv` laufen weiter in `VEXT-1` (Spike). **Bleibt v2; `blocked-by R-P5` (M33a-Interface) unverändert.**
> 🔴 **Refresh-Regression 2026-07-23:** Nach dem bisherigen Dauer-Proof und 20 weiteren erfolgreichen
> Rotationen scheiterte um **21:08:10 CEST** eine HTTP-2xx-Tokenantwort an einem zusammengefassten
> semantischen Validator und setzte die Connection fail-closed auf `broken`. Die genaue Teilursache ist aus
> den damaligen Logs nicht rekonstruierbar. Der automatische Refresh verlangte abweichend vom bereits
> robusteren Erst-Login exakt 300 Sekunden Laufzeit. Dieser Regressionsfix vereinheitlicht beide Verträge,
> ergänzt ausschließlich feste secretsichere Diagnosecodes und behält das Replay-Verbot für möglicherweise
> verbrauchte Einmal-Refresh-Token bei. Verschlüsselung, Health/Reconnect, Mandantenbindung und OAuth2-
> Registrierung bleiben erfüllt. Bis Deploy, Reconnect und erneutem Langzeit-Proof gilt:
> **VR-P32a: 4/5 DoD = 80 % done · 1 Punkt offen · 1 selbst machbar.**
> 🟢 **Demand-Refresh-Live-Abschluss 2026-08-01:** PR `#312` wurde als normaler Merge
> `a55b811ccd652cc04264d8d09e0f270a6487f27d` mit **11/11 grünen CI-Jobs** übernommen und über
> Deploy-Run `11609` auf Staging ausgerollt. Nach genau einem normalen OAuth-Reconnect blieb die
> Connection vom 01.08.2026, **00:20 bis 02:20 CEST**, durchgehend gesund. Web-, Import- und
> General-Worker führten **20/20** fällige Einmal-Refresh-Token-Rotationen erfolgreich über den gemeinsamen
> durable Claim aus; es gab keinen Provider-, Persistenz- oder Claim-Fehler und keine erneute
> Reconnect-Aufforderung. Acht reguläre Health-Sweeps meldeten jeweils `checked=1`, `unhealthy=0`.
> Katalog- und Vertragsjobs liefen nach dem Demand-Refresh erfolgreich; der generische Minutensweep
> rotierte KWP nicht mehr. **VR-P32a: 5/5 DoD = 100 % done · 0 Punkte offen · Done.**
> 🟢 **Superseding Scope-Entscheidung 2026-07-22:** Der initiale aktuelle KWP-Scope ist verbindlich
> **read-only**. HiveGrid führt in diesem Scope keine KWP-Mutation aus. Push-Queue/M091,
> `kwp.push_auftrag` und Project-/Auftrag-Create sind deshalb keine DoD dieses Tickets mehr. Die extern
> fehlende Write-/Create-Capability wird ausschließlich in `VEXT-6` geparkt; `VEXT-6` blockiert weder diesen
> Connector noch die nachfolgenden read-only Inbound-Tickets. Die älteren datierten Fortschritts- und
> Blocker-Notizen unten bleiben als Entscheidungsprotokoll erhalten und werden durch diese Scope-Entscheidung
> für den aktuellen Stand ersetzt. Selbst 4/4 DoD in `VEXT-6` erzeugen kein Dev-Ticket; dafür ist danach eine
> separate erneute ausdrückliche Produktfreigabe nötig. **VR-P32a: 5/5 DoD = 100 % done.**
> 🎨 **design-nachzug: offen** — Der Mandanten-Verbindungsflow nutzt bis zu Davids `VD-P32`-Delta eine
> getestete Interim-UI aus `~/ui`; die finale Subframe-Optik bleibt separat getrackt und blockiert den
> funktionalen Pilot-Slice nach AD-28 nicht.
> 🟢 **Geerkens-Pilot-Slice freigegeben 2026-07-20:** Als schmaler, nicht abschließender Slice dürfen
> OAuth2/PKCE-Start, der feste Callback unter `/integrations/kwp/oauth/callback`, Code-/Token-Austausch und die
> per-Tenant-DEK-verschlüsselte Tokenpersistenz umgesetzt werden. Read-only Relay-Discovery und Health sind
> ausschließlich als notwendiger Live-Proof enthalten; die einmalige Refresh-Token-Rotation bei jeder
> Access-Token-Anforderung gehört zum Token-Lifecycle. **Pull, Push und manueller Sync sind in diesem Slice
> nicht freigegeben.** Der echte bnWin-Login sowie Token-, Scope-, Resource- und Refresh-Proof sind seit
> 2026-07-21 zunächst erfolgreich durchlaufen. Nach dem Haltbarkeits-Deploy vom 2026-07-22 und einem normalen
> OAuth-Reconnect blieben Connection und Health über neun weitere automatische Einmal-Refresh-Token-Rotationen
> stabil `active`; damit ist auch der Connector-Dauerbetrieb belastbar erfüllt. Push-Queue und
> `kwp.push_auftrag` bleiben außerhalb des Pilot-Slice offen.
> 🟢 **Vertragsstand 2026-07-20:** Zugang und beide Redirects sind am Keycloak-Authorization-Endpunkt
> plausibilisiert; `App.connectionType='oauth2'`, Authorization Code + PKCE/S256 und Refresh-Token sind gesetzt.
> Der aktuelle Geerkens-Relay wird dynamisch über das Kundenkürzel aufgelöst; seine Tenant-OpenAPI bestätigt
> Adresse/Aktivität/Termin/Vorgang/Archiv. Runtime-Probes zeigen: Service-Account und Device Flow sind für den
> Client deaktiviert; zulässig ist `openid` + fünf `*-extern`-Scopes + `offline_access`, nicht `email`. Offen
> bleiben der bnWin-Benutzerlogin aus VN-1, Token-/Resource-Call und die Resource-Scope-Semantik.
> Laut KWP-Logs aktualisierte sich der BackendApi-Dienst erst am **13.07.2026** auf **2.81.62**; die
> fehlgeschlagenen Versuche fanden großteils am 12.07. und damit vor diesem Stand statt. KWP erwartet, dass der
> Login jetzt funktioniert. Das ist eine Ursachenangabe des Herstellers, aber noch kein erfolgreicher
> HiveGrid-Retest. Verbindlicher Issuer ist
> `https://id.kwp-online.de/realms/kwp-federated`, die Resource-Audience für Geerkens
> `https://geerkens2.app04.kwp-online.de/relay/geerkens2/pwa`. Einen separaten `resource`-Wert hat KWP nicht
> bestätigt, sondern um Präzisierung der Frage gebeten; daraus wird bis zum Live-Proof kein zusätzlicher
> Token-Parameter oder Claim-Vertrag abgeleitet.
> Der Hersteller bestätigt außerdem: 60 Requests/Minute Hard-Cap pro Client; Access 5 Minuten plus 5 Minuten
> Clock-Skew; Refresh 30 Tage idle/maximal 365 Tage, einmalig und bei jeder Access-Token-Anforderung rotiert;
> keine Änderungs-Webhooks/authentifizierten Änderungs-Callbacks, Delta-Cursor oder „geändert seit“-Filter;
> keine Sandbox/Testkunde;
> `x-kwp-client-version` optional. `mandant` wird nur bei einem eingerichteten bnWin-Mandanten mit dessen Kürzel
> gesendet, sonst weggelassen; die konkrete Geerkens-Angabe steht noch aus und `KWP_MANDANT` bleibt bis dahin
> bewusst ungesetzt. **Harter fachlicher Blocker:** Die
> Neuanlage eines Projekts/Auftrags über die API ist ausdrücklich nicht vorgesehen. Der verpflichtende
> Won→Auftrag-Push darf nicht auf eine andere Operation umgedeutet werden. `kwpsync.exe` bleibt ausgeschlossen.
> 🟡 **Staging-Erst-Proof und Langzeitkorrektur 2026-07-21:** Revision `56d2b4f00` schloss den echten Authorization-Code-/PKCE-
> Flow erfolgreich ab, aktivierte die per-Tenant-DEK-verschlüsselte `DataConnection`, rief über den
> registrierten Adapter den geschützten KWP-Endpunkt `Core/GetApiVersion` auf und erneuerte das fünf Minuten
> gültige Access-Token anschließend automatisch mit einem rotierten Refresh-Token. Connection und Health
> blieben `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. Ein späterer Lauf endete jedoch mit
> `integrations.health.refreshFailed` und setzte die Connection auf `broken`. **VR-P32a: 3/6 DoD = 50 % done;
> offen: stabile Connector-Refresh-Diagnostik, Push-Queue und `kwp.push_auftrag`.**
> 🟢 **Mandanten-Verbindungsflow freigegeben 2026-07-21:** Der Geerkens-Pilot-Slice umfasst jetzt zusätzlich
> den vollständigen Verbindungsflow für die bnWin-Mandantenbindung: Nach dem OAuth-Login versucht HiveGrid,
> die für den angemeldeten Benutzer erlaubten Mandanten über `GET /api/Mandant/Load` zu laden. Ein Treffer
> wird vorausgewählt, mehrere Treffer werden zur Auswahl angeboten; jede Auswahl muss ausdrücklich bestätigt
> werden. Ist der Endpoint mit den gelieferten `*-extern`-Scopes nicht nutzbar, muss der Benutzer fail-closed
> entweder „kein bnWin-Mandant eingerichtet“ bestätigen oder das exakte Mandantenkürzel manuell angeben.
> Pro HiveGrid-Tenant wird genau **ein** KWP-Kontext gebunden: Kundenkürzel plus ein bestätigter bnWin-Mandant
> oder die bestätigte Abwesenheit eines solchen Mandanten. Eine fehlende Alt-Angabe gilt als `unconfirmed`,
> niemals still als „kein Mandant“. Die Bindung liegt ausschließlich im per-Tenant-DEK verschlüsselten
> Credential-Bundle der `DataConnection`; `KWP_MANDANT` ist für neue Verbindungen keine Mapping-Quelle.
> Pull, Push und manueller Sync bleiben weiterhin ausgeschlossen. Der vorprovisionierte Geerkens-Pilot bleibt
> processweit auf `KWP_HIVEGRID_TENANT_ID` begrenzt; eine sichere Mehr-Tenant-/Mehr-Kunden-Provisionierung ist
> expliziter Folge-Scope und wird hier nicht vorgezogen. Durch den neuen siebten DoD-Punkt lautet der aktuelle
> Stand **3/7 DoD = ~43 % done**.
## Abhängigkeiten & Parallelität
- **Blocked by:** `R-P5` (v1-Apps-Engine M33a-Adapter-Interface `connect/disconnect/validateConnection/syncPull/syncPush/handleWebhook` — KWP ist der **erste konkrete Adapter** dahinter), `VEXT-1` (KWP-API-Zugang aktiv + Recut-Detailplanung gegen die echte Doku)
- **Blocks:** `VR-P32b` (Contract-Sentinel + Konflikt bauen auf Connector/Push-Queue auf)
- **Erfüllte Voraussetzungen:** `R-P5` ✅ Done (Apps-Engine); `VEXT-1` ✅ Done
(dauerhafter Auth-/Resource-/Refresh-Proof).
- **Verbleibende Blocker:** keine für dieses Ticket. `VN-1` bleibt für einen kontrollierten bestehenden
Geerkens-Datenbereich und einen minimal berechtigten BNWIN-Testbenutzer offen, blockiert den read-only
Connector-Proof aber nicht.
Project-Create und jede KWP-Mutation sind aus dem aktuellen Scope entfernt und in `VEXT-6` geparkt. Die
generische Mandantenauswahl ist durch die
Userfreigabe vom 2026-07-21 abgeschlossen. Im Live-Reconnect wurde genau eine Bindung ausdrücklich
bestätigt und verschlüsselt gespeichert; ihr konkreter Wert wird nicht in die Ticket-Doc kopiert. `VN-1`
bleibt für kontrollierte fachliche Live-/E2E-Daten separat offen.
- **Design-Abhängigkeit:** `VD-P32` ist für die finale Subframe-Optik offen. Nach AD-28 blockiert das den
freigegebenen Pilot-Code nicht; für den vollständigen Ticket-Scope bleibt der Design-Nachzug sichtbar offen.
- **Blocks:** `VR-P32b` (Contract-Sentinel + Inbound-Konfliktschutz bauen auf dem stabilen read-only
Connector auf; keine Push-Queue-Abhängigkeit)
- **Läuft parallel zu:** `VA-P26` (Customer-Portal, Akeshan) — beide W2, kein Schema-Konflikt: KWP nutzt die bestehende `appsEngine.prisma`-Domäne (App/DataConnection/AppSyncRun/AppSyncItem). Konnektor-Pflicht je Modul.
- **Konflikt-Risiko:** keines auf Schema-Ebene (Apps-Engine-Domäne bereits in v1).
## Was wir bauen
Den **KWP-API-Connector** als ersten konkreten Adapter hinter dem M33a-Interface, plus **Connection-Health** und die **Push-Queue**. KWP wird ein regulärer `rest-api`/`oauth2`-Adapter über die Apps-Engine — der „Kunde-vor-Ort"-Mittelteil (`kwpsync.exe`) entfällt. Credentials liegen **per-Tenant-DEK-verschlüsselt** in `DataConnection.config`. Health läuft über den **generischen M33a-Health-Probe** (statt Client-Heartbeat). Push (gewonnener Deal → Auftrag) läuft über **eine Cloud-Outbox + Rate-Limited-Replay** (kein lokales SQLite mehr), idempotent über `AppSyncItem`.
Den **read-only KWP-OAuth2-Connector** als ersten konkreten Adapter hinter dem M33a-Interface, plus
**Connection-Health**. Der Connector speichert Kundenkürzel und OAuth-Material
per-Tenant-DEK in `DataConnection.credentialsCiphertext`, löst den Relay-Host über den offiziellen KWP-Loadbalancer auf und
führt nach dem OAuth-Login durch die explizite bnWin-Mandantenauswahl. Er sendet den `mandant`-Query nur bei
einer bestätigten Kürzel-Bindung; bei ausdrücklich bestätigter Abwesenheit eines bnWin-Mandanten lässt er ihn
weg. Unbestätigte Alt-Credentials dürfen keine fachlichen Calls ausführen. Health läuft über den generischen
M33a-Probe. Dieser Ticket-Scope sendet keine fachliche Mutation an KWP. Outbox, M091 und Won→Auftrag sind
unter dem aktuellen Herstellervertrag nicht umsetzbar und ausschließlich als konditionaler externer
Folgescope in `VEXT-6` geparkt.
## Benötigte Screens (Backend bedient — Design liefert `D-P32`/Akeshan)
| Screen [Route] | Kern-Inhalt |
|---|---|
| KWP-Setup-Wizard [`/integrations/kwp/setup`] | OAuth/API-Key-Verbindung, Credential-Eingabe (DEK-verschlüsselt, maskiert), Initial-Sync-Vorschau |
| KWP-Setup-Wizard [`/integrations/kwp/setup`] | Kundenkürzel → Relay-Auflösung → OAuth2/PKCE-Login → bnWin-Mandanten laden/auswählen oder „kein Mandant“ ausdrücklich bestätigen; maskierter Connection-Status + Initial-Sync-Vorschau |
| Connection-Health-View [`/integrations/kwp`] | Verbindungsstatus (verbunden/broken), letzter Sync, Health-Probe, Re-Connect |
| Sync-Log [`/integrations/kwp/log`] | Sync-Items (Push/Pull), Status, Zeit, `KwpErrorReport`-Einträge, Filter |
| Sync-Log [`/integrations/kwp/log`] | Nachgelagerte read-only Inbound-Sync-Items, Status, Zeit und `KwpErrorReport`-Einträge; gehört zu `VR-P32b/c/d`, nicht zur Connector-DoD |
## Definition of Done
- [ ] **KWP-Connector** hinterm M33a-Adapter-Interface (erster konkreter Adapter); `kwpsync.exe` **NICHT** gebaut
- [ ] Credentials **per-Tenant-DEK** verschlüsselt in `DataConnection.config` (AD-8)
- [ ] **Connection-Health-Probe** (generisch, statt Heartbeat) + Re-Connect
- [ ] **Push-Queue** via Cloud-Outbox + **Rate-Limited-Replay** (Replay-Rate aus KWP-Rate-Limits), idempotent über `AppSyncItem`
- [ ] Push „Won→Auftrag" als Automation-Action (`kwp.push_auftrag`) andockbar
- [ ] DataConnection **`type='oauth2'`** (geklärt 2026-06-25: Keycloak-OIDC Auth-Code + PKCE, Confidential Client + `offline_access`)
- [x] **KWP-Connector dauerhaft stabil** hinterm M33a-Adapter-Interface; erneuter Langzeit-Proof nach
Refresh-Regression mit 20/20 Demand-Rotationen und acht gesunden Staging-Health-Sweeps erbracht,
Reconnect und automatische geschützte Health-Probes vorhanden;
`kwpsync.exe` **NICHT** gebaut
- [x] Credentials **per-Tenant-DEK** verschlüsselt in `DataConnection.credentialsCiphertext` (AD-8)
- [x] **Connection-Health-Probe** (generisch, statt Heartbeat) + Re-Connect
- [x] **Mandanten-Verbindungsflow** vollständig: pro HiveGrid-Tenant genau eine bestätigte Bindung
`selected(<Kürzel>)` oder `none`, Discovery über `Mandant/Load` mit manuellem fail-closed Fallback,
verschlüsselte Persistenz und korrekte Request-Injektion (`selected`: `mandant` an jedem KWP-Resource-Request;
`none`: bewusst weglassen; `unconfirmed`: fachlichen Call blockieren)
- [x] OAuth2-Verbindung über **`App.connectionType='oauth2'`** und den registrierten Adapter (Keycloak-OIDC Auth-Code + PKCE, Confidential Client + `offline_access`)
## Technische Bausteine
- **Entities** (eigene `prisma/schema/appsEngine.prisma` — aus v1 übernommen, AD-21): `App{type:"kwp"}`, `DataConnection{type:"rest-api"|"oauth2", config:<DEK-verschlüsselt>, connection_status, last_health_check}`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` (`entity_type`/`id` HiveGrid ↔ `external_id`, `operation`, `status` — inkl. `rolledBackData` für den M093-Restore in VR-P32b). `KwpErrorReport` für Sync-Log-Fehler.
- **DataConnection `rest-api`:** KWP-Creds verschlüsselt in `config` (Per-Tenant-DEK). ⚠ Spec-19.1.2 („Creds verlassen Kundennetz nie") gilt bei API-Anbindung **nicht mehr 1:1** — Creds liegen jetzt verschlüsselt in der Cloud → Vermerk in AVV/Subprozessoren (M166/VR-P31) weiterreichen.
- **Entities** (bestehende `prisma/schema/appsEngine.prisma`, AD-21):
`App{key:"kwp", connectionType:"oauth2"}`,
`DataConnection{credentialsCiphertext:<DEK-verschlüsselt>, connectionStatus, lastHealthCheck}`,
`AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` (inkl. `rolledBackData` für VR-P32b). `KwpErrorReport` bleibt
KWP-spezifisch.
- **OAuth2-Verbindung:** `App.connectionType='oauth2'`; Kundenkürzel, Client-Metadaten und Refresh-Token
verschlüsselt in `DataConnection.credentialsCiphertext`.
Relay-Host nur gecacht, nicht als dauerhafte Wahrheit gespeichert. ⚠ Spec-19.1.2 („Creds verlassen Kundennetz
nie") gilt nicht mehr 1:1; der Nachzug ist in VR-P31 dokumentiert. Für Staging bleibt das aktuell
provisionierte Client-Secret unverändert; ohne ausdrücklichen User-Auftrag wird es weder rotiert noch als
Test-/Deploy-Blocker behandelt. Kein Secret-Wert gehört in Git oder diese Doc.
- **Mandantenbindung:** Das verschlüsselte KWP-Credential-Bundle führt einen expliziten Tri-State:
`unconfirmed` für Alt-/Zwischenstände, `none` nach ausdrücklicher Bestätigung ohne bnWin-Mandanten oder
`selected` mit dem exakten Kürzel. Ein fehlendes Feld ist rückwärtskompatibel `unconfirmed`; es darf nicht
als `none` interpretiert werden. Dafür ist kein Prisma-Schema-Delta nötig. Nach dem Token-Austausch bleiben
Credentials bis zur Auswahl in der reservierten `pending`-Connection verschlüsselt; erst die bestätigte
Bindung plus geschützter Health-Probe darf `active` setzen.
- **Reconnect-/Abbruch-Lifecycle:** Ein Reconnect übernimmt den letzten stabilen Connection-Snapshot
(Ciphertext, Status, Token-Ablauf, Health und Owner) in den verschlüsselten Pending-Envelope. Abbruch,
Providerfehler, ungültiger/abgelaufener Callback oder abgelaufene Mandantenauswahl stellen diesen Snapshot
per vollständigem CAS wieder her. Der bestehende 5-Minuten-Worker bereinigt abgelaufene Pending-Versuche
tenant- und RLS-gebunden auch für deaktivierte Tenants; bei einer Erstverbindung entfernt er die
Zwischen-Tokens. Dadurch bleiben weder abgebrochene Tokens liegen noch kann ein veralteter Callback einen
neueren Connection-Stand überschreiben.
- **Mandanten-Discovery:** `GET /api/Mandant/Load` wird mit dem frisch erhaltenen Access-Token ohne erfundenes
Kürzel versucht. Da die Tenant-OpenAPI für diesen Endpoint nicht die gelieferten fünf `*-extern`-Scopes
ausweist, ist die Liste keine garantierte Capability. `401` verlangt einen neuen Login; bei fehlender
Berechtigung muss die UI die bewusste `none`-Bestätigung oder manuelle Kürzeleingabe anbieten, ohne das
Weglassen des Parameters aus einem Fehler abzuleiten.
- **Pilot-Provisionierung:** Der processweite Geerkens-Client bleibt fail-closed an
`KWP_HIVEGRID_TENANT_ID` gebunden. Die sichere Provisionierung mehrerer HiveGrid-Tenants oder weiterer
KWP-Kundenclients ist ein eigener Folge-Scope; dieses Ticket entfernt den Schutz nicht still.
- **Token-Lifecycle:** Access-Token 5 Minuten plus 5 Minuten technischer Clock-Skew; Refresh-Token 30 Tage idle/
maximal 365 Tage, einmalig und bei jeder Access-Token-Anforderung rotiert. Der jeweils neue Refresh-Token muss
verschlüsselt den vorherigen ersetzen. Passwortänderung oder Benutzerdeaktivierung widerruft die Token.
- **OAuth-Scopes:** `openid adresse-extern archiv-extern termin-extern vorgang-extern aktivitaet-extern
offline_access`; `email` nicht anfordern. Der Client unterstützt weder Service-Account noch Device Flow.
- **Konnektor:** `tenantHasModule('kwp_integration')` (`SubscriptionFeature.code = kwp_integration`) gated die Integration komplett.
- **Outbox:** v1-Cloud-Outbox + Idempotency-Wrapper (M007) — eine Queue, Rate-Limited-Replay; **kein** lokales SQLite.
- **Keine KWP-Mutation:** Der aktuelle Scope hat keine Push-Outbox und keine Automation-Action
`kwp.push_auftrag`. M091/Writeback werden erst nach 4/4 Vertragsnachweis in `VEXT-6` und einer danach
separat erteilten ausdrücklichen Produktfreigabe neu als Dev-Ticket geschnitten. Das Hard-Cap von
**60 Requests/Minute pro Client** gilt unabhängig davon auch für spätere read-only Polling-Consumer.
- **Health-Probe:** generischer M33a-Health-Probe (`validateConnection`), nicht der alte 5-min-Client-Heartbeat.
- **`is_demo_data`:** Demo-DataConnection (Test-/Sandbox-KWP) seedbar, beim Echt-Start löschbar.
Im Pilot-Slice nur read-only und ausschließlich als notwendiger Live-Proof.
- **`is_demo_data`:** Nur lokale UI-/Fixture-Daten; KWP bietet keine Sandbox und keinen Testkunden.
## Quellen (granular)
- `ROADMAP-V2.md` → §v2-P5 (Success-Criteria 1/2, Setup/Health/Log-Screens) — **Hauptquelle**
- `ROADMAP.md` → Phase 32
- **`docs/milestones/M19-KWP-API-RECUT.md` (bindend)** → M089 (Connector), M090 (Health vereinfacht), M091 (eine Cloud-Outbox), Übernahme-Liste `appsEngine.prisma`, offene Vertrags-Fragen 1/4
- `PHASE-SOURCES.md` → Phase 32 (M089/090/091; Block-2-Hinweis: Partner-API offen, agil; Callback-URL `…/integrations/kwp/oauth/callback` in v1 gemeldet, OAuth Auth-Code + PKCE, Tenant im `state`)
- **`.planning/KWP-API-CONTRACT.md` (bindend)** → M089 (Connector), M090 (Health vereinfacht),
Übernahme-Liste `appsEngine.prisma`, abgeschlossener read-only Runtimevertrag; M091 ist durch die
Scope-Entscheidung in `VEXT-6` geparkt
- Historische Milestone-Zuordnung: Phase 32 (M089/090; Callback-URL `…/integrations/kwp/oauth/callback` in v1 gemeldet, OAuth Auth-Code + PKCE, Tenant im `state`)
- `ENTITY-MODEL.md` → Domäne 7 Apps-Engine (App/DataConnection/AppSyncItem), `ProjektExternesFeld` [v2] (KWP-Felder)
- `designer-briefs/P32-kwp-integration.md` (Setup/Health/Log-Screens, Recut-Sonderfall)
- `_bmad-output/specs/M19-kwp-integration.md`
## Dev-Nachzug (nach Davids `D-P32`-Delta + Recut-Detailplanung VEXT-1)
- [ ] Spec/ENTITY-MODEL an reale KWP-API + Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] Plane-Ticket `VR-P32a` aktualisiert
**Umsetzungsstand 2026-07-20:** **VR-P32a: 0/6 DoD = 0 % done.** Der Callback-Slice ist zum Beginn
freigegeben, aber noch kein DoD-Punkt vollständig erfüllt. Er umfasst nur den Geerkens-OAuth-Start/Callback,
Code-/Token-Austausch, verschlüsselte Persistenz, Refresh-Rotation sowie read-only Relay-Discovery/Health als
Live-Proof; **kein Pull, Push oder manueller Sync**. Live-/Done-Proof bleibt bis zum erfolgreichen bnWin-Login
sowie Token-/Scope-/Resource-Test durch `VEXT-1`/`VN-1` blockiert. Project-Create ist laut Hersteller nicht
unterstützt; Push-Queue, `kwp.push_auftrag` und alle weiteren DoD bleiben unverändert offen.
**Staging-Stand 2026-07-20:** Setup und Callback sind seit PR `#185`, Merge-Commit `4ffa3a4ac`, unter den festen
Routen `/integrations/kwp/setup` und `/integrations/kwp/oauth/callback` auf Staging deployt. Deploy-Run `10832`
war nach einem Retry des transienten Containerd-Layer-Pull-Fehlers erfolgreich; Web und General-Worker liefen
anschließend auf exakt dieser Revision. Die Prozess-Credentials werden an genau einen HiveGrid-Tenant über
`KWP_HIVEGRID_TENANT_ID` gebunden; `KWP_MANDANT` bleibt bis zur Geerkens-Antwort bewusst ungesetzt. Vor einem
Staging-Test wird das vorhandene Client-Secret unverändert verwendet; es gab keine Rotation. Der Stand schließt
ohne erfolgreichen BNWIN-Login, Token-Austausch und Resource-Aufruf weiterhin keinen DoD-Punkt.
**Lokaler Verifikations-Proof 2026-07-20:** Implementierungs-Commit `f0a0033bb`; `pnpm typecheck` und
`pnpm lint` grün; `pnpm test` grün mit **6.926 bestandenen Tests**. Zusätzlich grün:
`verify:env-drift`, `verify:i18n`, `verify:ci-baseline`, `verify:source-health`, `verify:secrets` und
`verify:test-density`; `git diff --check` sowie der verbotene-US-Provider-Import-Scan sind ebenfalls sauber.
Plane-Kommentar: `84bcbbed-42b7-47e3-adf6-b627d3ba3b98`.
`verify:route-inventory` bleibt wegen bereits auf unverändertem `origin/main` vorhandener Budgetdrift rot
(`tenant 122/111`, `public 72/71`). Der KWP-Diff erhöht keine dieser beiden Klassen: Setup und Callback sind
als `optional` klassifiziert (`153/208` inklusive KWP, Gesamtbestand `443/489`) und per Verifier-Test
abgesichert. Das ist ausschließlich lokaler Regressions-Proof, kein Deploy-, Login-, Token-, Scope-,
Resource- oder Refresh-Live-Proof; **VR-P32a bleibt 0/6 DoD = 0 % done**.
**Lokaler HTTP-/Provider-Proof 2026-07-20:** `pnpm dev:local` lief gegen eine wegwerfbare lokale Datenbank;
die vorhandenen KWP-Credentials blieben unverändert. Der echte HTTP-Pfad lieferte Login `200` → Session
`302` → authentifiziertes KWP-Setup `200` → Authorization-Redirect `302`. Der erzeugte Keycloak-Request
enthielt vollständig `response_type=code`, die lokale Callback-URL, exakt `openid` + fünf `*-extern`-Scopes +
`offline_access`, `tenant=geerkens2`, State, Nonce und PKCE/S256. Keycloak lehnt ausschließlich die lokale
Callback-URL mit `400 invalid_redirect_uri` ab; derselbe Request mit der bereits registrierten
`https://staging-app.hivegrid.de/integrations/kwp/oauth/callback` liefert `200` und das BNWIN-Loginformular.
Das bewies zu diesem Zeitpunkt die KWP-Registrierung, aber noch nicht den späteren Staging-Deploy aus PR `#185`.
Ein vollständiger lokaler Auth-Code-/Token-/Resource-/Refresh-Lauf ist ohne zusätzlich bei KWP registrierte
Localhost-Redirect-URI nicht möglich und wird nicht als DoD-Proof gezählt.
**Live-Read-only-Probe 2026-07-20:** OIDC-Discovery, KWP-Loadbalancer und Tenant-OpenAPI antworten jeweils mit
`200`; der Loadbalancer löst weiterhin auf `geerkens2.app04.kwp-online.de` auf. Die ungeschützten
Versionsaufrufe liefern `Core/GetApiVersion = 2` und `Core/GetVersion = 2.81.62`. Ein geschützter
`adresse-extern`-Aufruf ohne Token antwortet erwartungsgemäß mit `401 Bearer`. Das bestätigt Erreichbarkeit,
Backend-Version und Auth-Grenze; zusätzlich sind **5 KWP-Testdateien mit 63/63 Tests** grün. Das ersetzt aber
keinen Aufruf mit BNWIN-Access-Token. **VR-P32a bleibt 0/6 DoD = 0 % done.**
**Disconnect-Grenze im Pilot 2026-07-20:** KWP-Disconnect ist in UI und Action fail-closed deaktiviert. Eine
rein lokale Löschung der `DataConnection` würde den zugehörigen Keycloak-Refresh-Token nicht nachweisbar
widerrufen. Providerseitige Revocation ist noch nicht verifiziert und bleibt Token-Lifecycle-Nachzug sowie
Live-Blocker. Reconnect bleibt über den OAuth-Flow möglich; auch dieser Schutz schließt keinen DoD-Punkt.
**Staging-Fehleranalyse und Follow-up 2026-07-20:** Der erste interaktive Setup-Versuch nach dem Deploy endete
um `21:52:36 CEST` beim POST auf `/integrations/kwp/setup` vor jedem OIDC-/Keycloak-/KWP-Aufruf. Das generelle
Integrations- und das KWP-Entitlement waren aktiv; der angemeldete Benutzer hatte im gewählten Tenant jedoch
weder `integrations.connect` noch `integrations.admin`. Der erwartete `CatalogError` mit 404-Semantik wurde im
Production-ErrorBoundary als 500 dargestellt. Follow-up-Commit `85751f64b` filtert die tenantlose Auswahl auf
KWP- und Connect-berechtigte Mitgliedschaften und übersetzt Catalog-404 bei direktem GET/POST in eine echte
`Response` mit Status 404. Keine Rolle, kein Secret, kein Token und keine KWP-Runtime-Konfiguration wurden
verändert. Proof: KWP-Routentest **11/11**, vollständiger Testlauf **6.967 bestanden / 55 übersprungen**,
Typecheck, Lint, `verify:ci-baseline`, `verify:source-health`, `verify:secrets`, Diff-Check und EU-Provider-Scan
grün. Zu diesem Zeitpunkt blieben der Staging-Retest dieses Follow-ups und der eigentliche BNWIN-Login offen;
**VR-P32a bleibt 0/6 DoD = 0 % done**.
**Staging-Callback-Retest und Diagnose 2026-07-20:** Nach erfolgreichem BNWIN-Login und Zustimmung erreichte
der Rückruf Staging um `23:39:43 CEST`. OAuth-Challenge, Cookie und `state` waren gültig und wurden einmalig
eingelöst. Die reservierte `DataConnection` blieb anschließend unverändert im Status `pending`: Es wurden
weder Token-Ciphertext noch Ablaufzeit oder Health-Check persistiert; ein Datenbankfehler war nicht sichtbar.
Damit liegt der Fehler nach der Callback-Validierung und vor der Aktivierung, ohne dass der bisherige breite
Catch die Stufe eindeutig erkennen ließ. Der Follow-up ergänzt deshalb ausschließlich feste, secretsichere
Diagnosecodes für Provider-Antwort, Session/Berechtigung, Token-Austausch, KWP-Health und Persistenz. Code,
`state`, Token, Secret und Provider-Body werden nicht geloggt. Ein ungültiger Dummy-Code bestätigte am echten
Token-Endpunkt zusätzlich Client-Authentifizierung und Redirect-URI mit `400 invalid_grant`, ohne Credentials
zu verändern. Es gab keine Rotation, keine Rollenänderung, keine Produktionsänderung; `KWP_MANDANT` bleibt
unverändert ungesetzt. Der Callback ist noch nicht erfolgreich und kein geschützter Resource-Call bewiesen;
**VR-P32a bleibt 0/6 DoD = 0 % done**.
Lokaler Proof des Diagnose-Follow-ups: Implementierungs-Commit `4886f3132`; gezielter KWP-Satz **57/57**
grün, vollständiger Lauf **6.975 bestanden / 55 übersprungen**, Typecheck und Lint grün. Zusätzlich grün:
`verify:ci-baseline`, `verify:source-health`, `verify:secrets`, `verify:test-density`, `git diff --check` und
EU-Provider-Scan. Das ist noch kein Staging-Retest oder Live-Proof.
**Staging-Diagnose und Scope-Fix 2026-07-21:** PR `#190` ist als Revision `65976d712` ausschließlich auf
Staging deployt. Zwei danach neu gestartete OAuth-Versuche erreichten jeweils den Token-Austausch und endeten
mit den festen Diagnosewerten `exchange_failed` / `scope_mismatch`. Access-Token, rotierbarer Refresh-Token
und Ablaufzeit waren zu diesem Zeitpunkt bereits erfolgreich aus der Provider-Antwort gelesen; die bestehende
einzelne `pending`-Verbindung wird beim Retry wiederverwendet und ist nicht der Blocker. Ursache ist der
bisherige HiveGrid-Check, der fälschlich verlangte, dass KWP neben allen fünf `*-extern`-Scopes auch die
technischen Request-Scopes `openid` und `offline_access` im Token-Response exakt zurückspiegelt. Der lokale
Fix verwendet für Callback und Refresh denselben fail-closed Vertrag: Alle fünf Fach-Scopes bleiben zwingend,
`openid`/`offline_access` dürfen nur im Response-Echo fehlen, unbekannte oder doppelte Scopes bleiben verboten;
Authorization-/Refresh-Request und verschlüsselt gespeicherte Soll-Policy bleiben exakt die kanonischen sieben
Scopes. Refresh-Rotation und 300-Sekunden-TTL bleiben unverändert. 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, `verify:ci-baseline`, `verify:source-health`, `verify:secrets`,
`verify:test-density`, `git diff --check` und der EU-Provider-Scan. Es gab keine Credential-Rotation, keine
Änderung an `KWP_MANDANT` und keine Produktionsänderung. Der Fix ist noch nicht deployt und begründet noch
keinen Token-/Resource-/Refresh-Live-Proof;
**VR-P32a bleibt 0/6 DoD = 0 % done.**
**Ausdrücklich freigegebener CI-Nachzug außerhalb des Ticket-Scopes 2026-07-21:** PR `#190` wurde durch die
neu veröffentlichte High-Severity-Advisory `GHSA-3jxr-9vmj-r5cp` blockiert; die betroffenen
`brace-expansion`-Overrides waren bereits unverändert auf `main` vorhanden und wurden nicht durch den KWP-Diff
eingeführt. Nach explizitem User-OK hebt Commit `6e3914cac` ausschließlich die bestehenden Overrides von
`1.1.13` auf `1.1.16` und von `2.0.3` auf `2.1.2`. Proof: Production-Audit ohne Findings, Export-Paket
**107/107 Tests** grün, vollständiger Lauf **6.975 bestanden / 55 übersprungen**, Typecheck, Lint und
Lizenzprüfung grün. Das ändert weder KWP-Scope noch DoD-Zählung; **VR-P32a bleibt 0/6 DoD = 0 % done**.
**Staging-Erst-Proof des Pilot-Slice 2026-07-21:** Der Scope-Fix aus PR `#191` wurde als Revision
`56d2b4f00` ausschließlich auf Staging deployt; Deploy-Run `10863` sowie alle Staging-Health-/Readiness-Probes
waren grün. Ein danach neu gestarteter echter BNWIN-Login samt Zustimmung schloss Authorization Code +
PKCE/S256 und Token-Austausch erfolgreich ab. Der registrierte KWP-Adapter aktivierte genau eine Verbindung,
persistierte das OAuth-Material per-Tenant-DEK verschlüsselt und validierte die Verbindung mit einem
geschützten read-only Aufruf von `Core/GetApiVersion`. Der vorhandene Retry-/Re-Connect-Pfad verwendete dabei
die bereits reservierte `pending`-Verbindung weiter; es entstand kein doppelter Slot. Um **02:54:47 CEST**
schloss `integrations-token-refresh` erfolgreich ab, ersetzte den einmaligen Refresh-Token und setzte die neue
Access-Token-Ablaufzeit auf **02:59:47 CEST**; Status und Health blieben `active`. Kein Token-, Secret- oder
Passwortwert wurde 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 unverändert auf Revision `6100b4e16`.
Damit waren Adapterpfad, per-Tenant-DEK-Persistenz, Health/Re-Connect und der OAuth2-Vertrag im Erstlauf
bewiesen. Der nachfolgende Langzeitcheck nimmt den vollständigen Connector-DoD jedoch wieder zurück. Die
weiteren nicht implementierten DoD-Punkte bleiben Push-Queue und `kwp.push_auftrag`; KWP bietet laut Hersteller
keine Project-Create-Operation, weshalb dafür eine explizite Scope-/Produktentscheidung nötig ist.
**Langzeit-Korrektur 2026-07-21:** Nach mehreren erfolgreichen Rotationstakten endete der Lauf um
**03:09:54 CEST** nach **7,36 s** mit `refreshed=0`, `failed=1`; die Connection steht seitdem auf `broken` mit
`integrations.health.refreshFailed`. Ciphertext und letzte Ablaufzeit blieben erhalten. Der Provider-Fehler
wird im damals auf Staging laufenden `executeClaimedTokenRefresh` zu einem unklassifizierten `ok:false`
reduziert, und ein einziger Fehler schließt `broken` anschließend von jedem automatischen Refresh-/Health-
Kandidaten aus. Der
erste Auth-/Resource-Proof bleibt gültig, der Dauerbetrieb nicht. **VR-P32a: 3/6 DoD = 50 % done · 3 Punkte
offen, davon 2 fachlich blockiert und 1 diagnostisch selbst machbar.**
**Lokaler Refresh-Stabilitätsfix 2026-07-21:** Der Follow-up führt eine persistierte, CAS-gebundene
Refresh-State-Machine ein. Providerfehler werden secretsicher in feste Gründe, Disposition
`retry_once|reconnect` und optionalen HTTP-Status übersetzt. Nur `408`, `429`, `5xx`, Netzwerk/Timeout und die
allowgelisteten transienten OAuth-Fehler erhalten genau einen Retry nach frühestens fünf Minuten; permanente
Auth-/Scope-/Credential-Fehler sowie der zweite transiente Fehler enden `broken`. Claim- und Retry-Zustände
sind von Health-Kandidaten ausgeschlossen. Ein erfolgreicher Retry bleibt `degraded/refreshRecovered`, bis
der geschützte KWP-Resource-Probe erfolgreich ist; damit entsteht kein falscher `active`-Status nur durch
Tokenrotation. Claims älter als zehn Minuten werden vor dem Runtime-/Entitlement-Gate ohne erneuten
Provider-Aufruf terminalisiert. Die Worker-Summe führt `retryScheduled` separat von `failed`, und Logs
enthalten nur Task-, Tenant-, Connection-, Grund-, Dispositions- und optionale Statusfelder. Lokale Tests
decken unter anderem `r1 → r2 → r3`, den exakten Fünf-Minuten-Tick, unbekannten POST-Ausgang, `null`-/
Nichtobjekt-Providerantworten, Retry-Erschöpfung, Health-Sperre/-Recovery, unlesbare verschlüsselte
Credentials und Stale-Claims ab. Dieser Stand war zu diesem Zeitpunkt noch nicht auf Staging; danach benötigt
die bestehende `broken`-Verbindung einen neuen OAuth-Reconnect und mehrere echte Refresh-/Resource-Zyklen.
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.
Deshalb bleibt **VR-P32a: 3/6 DoD = 50 % done · 3 Punkte offen, davon 2 fachlich blockiert und 1 Live-Proof
selbst machbar.**
Kein Client-Secret, Passwort oder API-Key wurde manuell rotiert, `KWP_MANDANT` bleibt ungesetzt und Produktion
unverändert.
**Scope-Nachzug Mandanten-Verbindungsflow 2026-07-21:** Die ausdrückliche Userfreigabe erweitert nur den
Connector-/Setup-Slice um Discovery, bewusste Auswahl bzw. `none`-Bestätigung und verschlüsselte 1:1-Bindung.
Sie ist kein Proof einer konkreten Geerkens-Zuordnung, kein Sync-/Schreibfreigabe und keine Freigabe für eine
Mehr-Tenant-/Mehr-Kunden-Provisionierung. Diese Scope-Notiz beansprucht weder Umsetzungs- noch Live-Proof.
Mit dem siebten DoD-Punkt ist der aktuelle Stand neu zu zählen als
**VR-P32a: 3/7 DoD = ~43 % done · 4 Punkte offen**; davon bleiben Connector-Dauerbetrieb, Push-Queue und
`kwp.push_auftrag` unverändert offen, der Mandanten-Verbindungsflow ist selbst machbar.
**Lokaler Umsetzungs-Proof Mandanten-Verbindungsflow 2026-07-21:** Der Setup-Pfad führt jetzt vollständig von
der Auswahl des HiveGrid-Kontos über die Eingabe des vorprovisionierten KWP-Kundenkürzels, Authorization Code
+ PKCE und die opportunistische `Mandant/Load`-Discovery bis zur ausdrücklichen Auswahl genau einer Firma.
Bei nicht nutzbarer oder leerer Discovery gibt es ausschließlich den bewussten `none`-Pfad oder die manuelle
Eingabe eines exakten Kürzels. OAuth-Material und Discovery-Zwischenstand bleiben per Tenant-DEK verschlüsselt
in einer `pending`-Connection; erst die bestätigte Bindung plus geschützter Health-Probe aktiviert sie.
`selected` injiziert `mandant`, `none` lässt den Parameter bewusst weg und fehlende Alt-Bindungen blockieren
fachliche Calls als `unconfirmed`. Ein CAS-gebundener Attempt-Vertrag stellt sicher, dass nur der neueste
OAuth-Versuch gewinnen kann. Bei Reconnect wird der zuvor stabile Connection-Snapshot verschlüsselt
mitgeführt und bei Cancel, Providerfehler oder Ablauf exakt wiederhergestellt. Ein separater tenant- und
RLS-gebundener Cleanup-Sweep entfernt abgelaufene Erstversuche beziehungsweise stellt Reconnect-Snapshots
automatisch wieder her, auch wenn der betroffene Tenant zwischenzeitlich deaktiviert wurde. Die
Route-/View-Model-Grenze gibt keine Tokens oder Secrets an den Browser aus.
Proof: Root-Typecheck und Root-Lint grün; vollständiger Core-Lauf **7.074 bestanden / 55 übersprungen**;
Integrationspaket **252/252**; fokussierter OAuth-/Mandanten-/Worker-Satz **58/58**, darin
Connection-Service **34/34**, Setup-/Callback-Routen **21/21**, Worker-Einbindung **1/1** und zwei
Interim-Visual-Baselines. Die Tests decken mehrere gefundene Firmen, manuellen Fallback, Cancel/Fehler/Ablauf,
automatischen Pending-Cleanup, Worker-CAS-Races, v1-Kompatibilität und Credential-Leak-Guards ab. Ein
unabhängiger Read-only-Abschlussreview meldete keine Findings. Ebenfalls grün: `verify:i18n`,
`verify:ci-baseline`, `verify:source-health`, `verify:secrets`, `verify:test-density`, `verify:env-drift`,
`verify:a11y-coverage`, `verify:ui-hot-swap`, `test:hot-swap`, `git diff --check` und der verbotene
US-Provider-Import-Scan. Es gab keinen Deploy, keine Produktionsänderung und keine manuelle Rotation eines
Client-Secrets, Passworts, API-Keys oder anderen Staging-Credentials. `KWP_MANDANT` bleibt ungesetzt und wird
für neue Verbindungen ausdrücklich ignoriert. Die konkrete Geerkens-Auswahl und der echte Staging-E2E-Lauf
bleiben Live-Proof in `VEXT-1`/`VN-1`; sie ändern den abgeschlossenen lokalen Implementierungs-DoD nicht.
**VR-P32a: 4/7 DoD = ~57 % done · 3 Punkte offen**: stabiler Dauer-Live-Proof, Push-Queue und
`kwp.push_auftrag`; die beiden Schreibpunkte bleiben durch den Herstellervertrag beziehungsweise den nicht
freigegebenen Pilot-Scope blockiert.
**Setup-POST-404 Diagnose-Hotfix 2026-07-21:** Der erste Staging-Versuch nach Eingabe des KWP-
Kundenkürzels endete mit einer absichtlichen HiveGrid-404, noch bevor `beginKwpOAuthConnection` oder ein
Provider-Aufruf erreicht wurde; die bestehende `broken`-Connection blieb dabei unverändert. Commit
`d4d96fbf9` macht den Setup- und Mandanten-POST-Zielpfad sowie den Tenant-Formwert explizit und protokolliert
für alle absichtlichen Setup-404-Grenzen ausschließlich feste, secretsichere Diagnosecodes
(`intent_invalid`, `tenant_context_invalid`, `tenant_access_denied`, `session_mismatch`,
`membership_inactive`). Weder Kundenkürzel noch Tenant-ID, Token, Secret oder Providerdaten werden geloggt.
Die Härtung ist noch kein Beweis der ursprünglichen Fehlerursache; ein einzelner Staging-Retest muss den Flow
entweder fortsetzen oder den exakten Diagnosecode liefern. Lokaler Proof: KWP-Satz **29/29**, vollständiger
Root-Lauf **7.113 bestanden / 55 übersprungen**, Typecheck, Lint, `verify:i18n`, `verify:ci-baseline`,
`verify:source-health`, `verify:secrets`, `verify:test-density`, `git diff --check` und EU-Provider-Scan grün.
Es wurden keine Credentials oder Token manuell rotiert. Die DoD-Zählung ändert sich nicht:
**VR-P32a: 4/7 DoD = ~57 % done.**
**Staging-Langzeitstand und lokaler Haltbarkeits-Nachzug 2026-07-22:** Auf Staging lief Revision
`d4daa0421`. Der präzisierte Worker-/Datenbankabgleich belegt einen erfolgreichen KWP-Refresh um
**03:04:47 CEST** und den unmittelbar folgenden fehlgeschlagenen Lauf um **03:09:53 CEST**. Danach stand die
Connection auf `broken` mit `integrations.health.refreshFailed`; der konkrete Provider- oder Transportgrund
war in den verfügbaren Runtime-Diagnosen nicht enthalten. Damit bleiben der echte Erst-Proof und die
vorherigen Rotationen gültig, der Dauerbetrieb aber offen.
Der Haltbarkeits-Nachzug ist lokal **abgeschlossen**, aber noch nicht deployt. Er verdrahtet die
Handler-Diagnostik mit dem strukturierten Runtime-Logger, trennt eindeutig replay-sichere Providerantworten
von einem mehrdeutigen Ausgang des Token-POSTs und verbietet bei möglicherweise bereits verbrauchtem
Einmal-Refresh-Token jeden Provider-Replay. Wiederholt werden ausschließlich lokale Persistenzversuche nach
einem bereits abgeschlossenen Provider-Call; zusätzlich wird der KWP-spezifische Refresh-/Health-Gate vor die
bisherige Ablaufkante gezogen. Auswahl, Claim, Health-Probe und Health-Persistenz verwenden jeweils eine
frische Zeit pro Verbindung, damit lange Multi-Tenant-Sweeps weder neue Fälligkeiten verpassen noch Claims
vorzeitig als stale behandeln. Ein neuer Live-Claim setzt weiterhin mehrere erfolgreiche Refresh- und
geschützte Resource-Zyklen voraus. Lokaler Proof: Integrationspaket **254/254**, Worker **1.559 bestanden / 6
übersprungen** und vollständiger Root-Lauf **7.115 bestanden / 55 übersprungen**;
Root-Typecheck, Root-Lint, Worker-Build, Worker-Runtime-Closure, `verify:i18n`,
`verify:observability-console-baseline`, `verify:deploy-readiness`, `verify:gitea-ci-workflow`,
`verify:staging-live-uat-readiness`, `verify:ci-baseline`, `verify:source-health`, `verify:secrets`,
`verify:test-density` und `verify:env-drift` sind grün. `git diff --check` und der verbotene
US-Provider-Import-Scan sind ebenfalls sauber. Es wurde nichts manuell rotiert.
**Rollback:** keine Schemaänderung und keine Migration. Die Code-Revision kann auf das vorherige immutable
Image zurückgerollt werden. Ein vom Provider bereits verbrauchter Einmal-Refresh-Token lässt sich dadurch
nicht wiederherstellen; eine danach `broken` gebliebene Verbindung benötigt einen normalen OAuth-Reconnect.
**Zu diesem Zeitpunkt blieb VR-P32a 4/7 DoD = ~57 % done · 3 Punkte offen**: stabiler Dauer-Live-Proof, Push-Queue und
`kwp.push_auftrag`.
**Staging-Dauer-Live-Proof 2026-07-22:** PR `#210` wurde als Revision `2938f29da` über Deploy-Run `10995`
erfolgreich auf Staging ausgerollt; Web, API und `worker-general` meldeten exakt diese Revision gesund. Die
vorher unter der alten Revision `broken` gebliebene Connection wurde einmal über den normalen
Authorization-Code-/PKCE-Reconnect neu verbunden. Um **03:54:47 UTC** bestätigte der automatische geschützte
Health-Probe `checked=1`, `unhealthy=0`; die Connection stand auf `active` mit verschlüsseltem Credential-Bundle.
Danach rotierte der Worker den von KWP vorgeschriebenen Einmal-Refresh-Token neunmal automatisch:
- **03:58:09 UTC** → neues `tokenExpiresAt` **04:03:09.596 UTC**
- **04:02:09 UTC** → neues `tokenExpiresAt` **04:07:09.500 UTC**
- **04:06:09 UTC** → neues `tokenExpiresAt` **04:11:09.534 UTC**
- **04:10:09 UTC** → neues `tokenExpiresAt` **04:15:09.525 UTC**
- **04:14:09 UTC** → neues `tokenExpiresAt` **04:19:09.510 UTC**
- **04:18:09 UTC** → neues `tokenExpiresAt` **04:23:09 UTC**
- **04:22:09 UTC** → neues `tokenExpiresAt` **04:27:09.540 UTC**
- **04:38:09 UTC** → erneut erfolgreich rotiert
- **04:42:09 UTC** → neues `tokenExpiresAt` **04:47:09.642 UTC**
Alle neun Connection-Läufe endeten mit `outcome=refreshed`; die Batch-Summen waren jeweils `refreshed=1`,
`failed=0`, `retryScheduled=0`. Es gab keine `provider-failed`- oder `persistence-failed`-Events, und 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
`connectionStatus=active` / `integrations.kwp.health.active`. Kein
Client-Secret, Passwort, API-Key oder anderes Staging-Credential wurde manuell rotiert; nur KWP rotierte die
Einmal-Refresh-Token im vorgesehenen 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. Damit ist der
Connector-Dauerbetriebs-DoD geschlossen. **VR-P32a: 5/7 DoD = ~71 % done · 2 Punkte offen, davon 2 fachlich
blockiert und 0 im freigegebenen Pilot-Scope selbst machbar:** Push-Queue sowie `kwp.push_auftrag`/
Project-Create.
**Superseding Scope-Abschluss 2026-07-22:** Nach der Produktentscheidung bleibt der initiale aktuelle
KWP-Vertrag read-only; HiveGrid mutiert keine KWP-Daten. Die beiden im vorstehenden historischen Stand noch
offenen Write-Punkte gehören nicht mehr zur VR-P32a-DoD. Ein späterer Write-/Create-Vertrag wird in `VEXT-6`
extern nachgehalten. Auch nach 4/4 VEXT-6 entsteht ein eigenes Dev-Ticket erst nach einer separaten erneuten
ausdrücklichen Produktfreigabe. Damit gilt für den aktuellen Scope:
**VR-P32a: 5/5 DoD = 100 % done · 0 Punkte offen · Done.**
**Regression-Nachzug 2026-07-23:** Die vier unveränderten Connector-DoD bleiben abgeschlossen; nur der
Dauerbetriebs-DoD ist nach dem späteren Staging-Ausfall erneut offen. Es gibt keine Schemaänderung und keine
KWP-Mutation. **VR-P32a: 4/5 DoD = 80 % done · 1 Punkt offen · 1 selbst machbar.**
**Lokaler Regressionsfix-Proof 2026-07-23:** Commit `ccdc74ebe` akzeptiert beim automatischen Refresh wie
der bestehende Erst-Login jede positive ganzzahlige `expires_in`-Laufzeit bis maximal 300 Sekunden. Fehlender
Access-/Refresh-Token, nicht rotierender Refresh-Token, Scope-Abweichung, ungültige Laufzeit sowie
Nicht-JSON-/Nicht-Objekt-Antworten erhalten ausschließlich feste redigierte Diagnosecodes; Token oder
Provider-Payloads werden nicht geloggt. Das sichere Replay-Verbot für möglicherweise verbrauchte
Einmal-Refresh-Token bleibt unverändert. 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**; Prisma-Validate, Package-Tests, i18n, Tenant-Policy, Forced-RLS-Readiness,
Migration-Parity, CI-Baseline, Source-Health, Coverage, Hot-Swap, Secrets, Deploy-Readiness,
Deploy-Workflow, Staging-Live-UAT-Readiness und Produktions-Build grün. `git diff --check` und
EU-Provider-Scan sind sauber. Der Code-Proof schließt den offenen Live-DoD noch nicht:
**VR-P32a: 4/5 DoD = 80 % done · offen: normaler Reconnect und erneuter Dauer-Proof auf Staging.**
**Refresh-Frequenz-Nachzug 2026-07-31:** Die Staging-Diagnose des Ausfalls vom 2026-07-25 belegt bis zum
mehrdeutigen Token-POST-Ausgang **416 erfolgreiche Rotationen in rund 27,6 Stunden**, also ungefähr eine
Rotation alle vier Minuten. Diese hohe clientseitig erzeugte Frequenz war für den read-only Betrieb nicht
nötig und vergrößerte die Zahl der Einmal-Token-Übergänge unnötig. Der generische Minutensweep bereinigt
weiterhin abgelaufene OAuth-Versuche und versorgt andere Adapter, schließt KWP aber jetzt ausdrücklich aus.
KWP erneuert den Access-Token nur noch unmittelbar vor einem tatsächlichen Resource-Fenster oder dem
regulären 15-Minuten-Health-Fenster und nur bei höchstens zwei Minuten Restlaufzeit. Ohne KWP-Arbeit findet
keine Rotation statt.
Der bestehende persistierte Advisory-Lock-/CAS-Claim bleibt die Single Source of Truth für den
Einmal-Refresh-Token. Gleichzeitige Web-, Import- und Health-Aufrufer teilen sich dadurch genau eine
Provider-Rotation; Follower warten auf den verschlüsselt gespeicherten Nachfolger. Nach erfolgreicher
Provider-Antwort werden weiterhin ausschließlich lokale Persistenzversuche wiederholt, niemals der
Token-POST. Fällige replay-sichere Retries und stale Claims werden vom nächsten Health-Fenster wieder
aufgenommen. Strukturierte Logs verwenden den neuen secretsicheren Präfix
`integrations.kwp-token-demand.*`. Der Pilot-Tenant-, Entitlement-, RLS-, Mandanten-, Sentinel- und
Read-only-Vertrag bleibt unverändert. Es gibt kein Prisma-Schema-Delta und keine Migration.
Lokaler Zwischen-Proof: unverändertes `origin/main` vor dem Eingriff mit Root-Typecheck und **8.179
bestandenen / 60 übersprungenen Tests** grün; danach Integrations-Typecheck und **415/415 Pakettests**,
fokussierte Token-/Claim-Suite **48/48**, Worker-Typecheck und Demand-/Health-Handler **2/2** grün.
Abgedeckt sind frische Token-Wiederverwendung, Refresh unmittelbar vor Bedarf, zwei parallele Consumer mit
genau einem Provider-POST, lokaler Persistenz-Retry ohne Provider-Replay sowie fällige Retry-Recovery.
Deploy, Reconnect und mehrstündiger Staging-Proof stehen noch aus; daher bleibt
**VR-P32a: 4/5 DoD = 80 % done · 1 Punkt offen · 1 selbst machbar.**
**Worker-Runtime-Vertrag 2026-07-31:** Eine secretsichere, read-only Prüfung der laufenden
Staging-Container zeigte die Pilot-Tenant-Freigabe auf dem aktuellen `worker-general`, aber nicht auf
`worker-import`. Da echte KWP-Importjobs den gleichen Demand-Refresh-Gate verwenden, reicht der
Coolify-Provisioner `KWP_HIVEGRID_TENANT_ID` jetzt deterministisch von `worker-general` an
`worker-import` weiter und entfernt die Variable aus Mail-, Webhook- und Plugin-Workern. Die
Compose-Referenz bildet denselben Least-Privilege-Vertrag ab. OAuth-Client-Secret, Access- und
Refresh-Token werden dabei nicht verteilt. Der Deploy-Vertrag ist mit **72/72 Provisioner-Tests** und
dem Docker-Baseline-Verifier grün. Der Live-DoD bleibt bis Deploy, Reconnect und Dauerbeobachtung offen:
**VR-P32a: 4/5 DoD = 80 % done · 1 Punkt offen · 1 selbst machbar.**
**Abschluss lokaler Proof 2026-07-31:** Root-Typecheck, Root-Lint und der unbelastete Root-Testlauf mit
**1.160 bestandenen Testdateien / 8.180 bestandenen Tests / 60 übersprungenen Tests** sind grün. Ein im
vorherigen, parallel belasteten Lauf einmalig fehlgeschlagener Prozessgruppen-Timeout-Fixture-Test bestand
isoliert **15/15** und anschließend im vollständigen Wiederholungslauf. Zusätzlich grün:
Integrationspaket **415/415**, fokussierte Demand-/Claim-Suite **48/48**, Worker-Handler **2/2**,
Coolify-Worker-Provisioner **72/72**, Worker-Runtime-Closure, CI-/Source-/Secret-/Test-Density-/Env-/Docker-/
Deploy-/Gitea-/Staging-Readiness-Verifier sowie `git diff --check` und EU-Provider-Importscan. Der offene
DoD-Punkt ist ausschließlich der Staging-Dauerbeweis nach dem einmaligen Reconnect:
**VR-P32a: 4/5 DoD = 80 % done · 1 Punkt offen · 1 selbst machbar.**
**Staging-Demand-Refresh-Dauer-Proof 2026-08-01:** PR `#312` lief auf dem exakten Head in CI-Run `11608`
mit **11/11 grünen Jobs** und wurde ausdrücklich ohne Squash als normaler Merge
`a55b811ccd652cc04264d8d09e0f270a6487f27d` nach `main` übernommen. Deploy-Run `11609` schloss am
31.07.2026 um **22:43:45 CEST** für exakt diese Revision erfolgreich ab. Staging meldete denselben SHA;
`KWP_HIVEGRID_TENANT_ID` lag wie vorgesehen nur auf `worker-general` und `worker-import`.
Nach dem einmaligen normalen Authorization-Code-/PKCE-Reconnect am 01.08.2026 gegen **00:20 CEST** lief die
secretsichere Beobachtung bis **02:20 CEST**. In diesem Fenster endeten **20 von 20** protokollierten
Demand-Refreshes mit `outcome=refreshed`. Die Rotationen wurden aus Web-, Import- und General-Worker-Pfaden
ausgelöst; parallele Aufrufer erzeugten keinen zweiten Provider-POST. Es gab kein `provider-failed`,
`persistence-failed`, `claim-failed`, keinen Status `degraded`/`broken` und keine Reconnect-Aufforderung.
Acht unabhängige Health-Sweeps meldeten jeweils `checked=1`, `unhealthy=0`. Mehrfach lief der kurzlebige
Access-Token vor dem nächsten KWP-Zugriff ab, ohne die Connection fälschlich als defekt zu markieren; der
darauffolgende echte Zugriff rotierte jeweils genau einmal und speicherte den Nachfolger. Katalog- und
Vertragsjobs schlossen nach dem Gate erfolgreich ab. Der weiter minütlich laufende generische OAuth-Sweep
meldete `refreshed=0` und fasste KWP nicht mehr an.
Separat beobachtete `rate_limit_exceeded`-Fehler einzelner Projekt-Sync-Jobs entstanden erst nach
erfolgreicher Token-Rotation durch das gemeinsame 50-Requests/Minute-Budget. Sie veränderten Connection und
Health nicht und sind kein Restpunkt dieser Connector-DoD. Eine Serialisierung des gemeinsamen KWP-
Request-Budgets bleibt ein ausdrücklich freizugebender Folge-Scope. Damit ist der erneute
Connector-Dauerbetriebs-DoD geschlossen: **VR-P32a: 5/5 DoD = 100 % done · 0 Punkte offen · Done.**
**Rollback:** keine Schemaänderung. Ein Rollback auf das vorherige immutable Image stellt den alten
Minutensweep wieder her; ein bereits verbrauchter Einmal-Refresh-Token kann auch dadurch nicht rekonstruiert
werden. Die aktuelle `broken`-Verbindung benötigt nach dem Deploy genau einen normalen OAuth-Reconnect.
- [x] Spec-/ENTITY-MODEL-Abgleich abgeschlossen; für den read-only Connector-Scope ist kein Schema-Delta nötig
- [x] REQUIREMENTS/ROADMAP auf CR-003/AD-32 nachgezogen