577 lines
50 KiB
Markdown
577 lines
50 KiB
Markdown
# VR-P32a · KWP: Read-only Connector + Health (M089/090)
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Typ** | Dev (Code) |
|
|
| **Owner** | Raffael |
|
|
| **Phase** | Phase 32 (v2-P5) — KWP-Integration (Recut) |
|
|
| **Cycle/Fenster** | v2-W2 — KWP/Portal/Mobile-Start · fällig 2026-07-22 |
|
|
| **Status** | Done · **5/5 DoD = 100 % done** · Demand-Refresh auf Staging über zwei Stunden verifiziert |
|
|
|
|
> 🔴 **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
|
|
- **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 **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`] | 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`] | 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
|
|
- [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** (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.
|
|
- **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.
|
|
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
|
|
- **`.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)
|
|
|
|
## Dev-Nachzug (nach Davids `D-P32`-Delta + Recut-Detailplanung VEXT-1)
|
|
|
|
**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
|