302 lines
24 KiB
Markdown
302 lines
24 KiB
Markdown
# VR-P32b · KWP: Contract-Sentinel + Konflikt 'KWP gewinnt' (M092/093)
|
|
|
|
| | |
|
|
|---|---|
|
|
| **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-24 |
|
|
| **Status** | abgeschlossen · **4/4 DoD = 100 % done** · Design-Nachzug offen |
|
|
|
|
**🎨 design-nachzug: offen** (seit 2026-07-23) — Interim-UI aus `~/ui` wird im gemeinsamen
|
|
P32b/P32d-PR gebaut; finale Subframe-Optik aus `VD-P32` bleibt ausstehend.
|
|
|
|
> 🟢 **CR-004 Scope-Entscheidung 2026-07-23:** `VR-P32b` und `VR-P32d` werden in einem gemeinsamen PR
|
|
> umgesetzt, intern aber weiterhin strikt in der Reihenfolge Schutzschicht → Projektimport. Dieses Ticket
|
|
> liefert den providerneutralen dauerhaften Binding-, Sentinel-, Konflikt- und Restore-Unterbau, den P32d
|
|
> konsumiert. Der gemeinsame PR hebt die Dependency nicht auf und zieht keinen P32c-Scope vor.
|
|
|
|
> 🟢 **Superseding Scope-Entscheidung 2026-07-22:** VR-P32b konsumiert ausschließlich den stabilen
|
|
> read-only Connector aus `VR-P32a`. Eine Push-Queue, `kwp.push_auftrag` oder andere KWP-Mutation ist weder
|
|
> Voraussetzung noch Scope dieses Tickets. „KWP gewinnt“ bezeichnet die Inbound-Reconciliation in HiveGrid,
|
|
> nicht einen Writeback an KWP. Die älteren datierten Blocker-Notizen unten bleiben historisch erhalten und
|
|
> werden für den aktuellen Stand durch diese Entscheidung ersetzt.
|
|
|
|
> 🟡 **Vertragsstand 2026-07-12:** Der tenant-spezifische Vertrag liefert kein einheitliches
|
|
> `version_hash`/`last_modified`, keine `ETag`-/`Last-Modified`-Header und keine `If-Match`-Preconditions.
|
|
> Aktivitäten haben `datumAenderung`, Archivdaten Änderungs-/Revisionsfelder; Adresse, Termin und
|
|
> Projekt/Vorgang haben keinen belastbaren Versionsmarker. M092 bleibt als OpenAPI-Fingerprint + zod-Sentinel
|
|
> eigenständig; M093 erkennt Konflikte über den letzten normalisierten KWP-Snapshot in `AppSyncItem`.
|
|
|
|
> 🟢 **Herstellerstand 2026-07-20:** KWP bestätigt, dass es keine Änderungs-Webhooks oder
|
|
> authentifizierten Änderungs-Callbacks,
|
|
> Delta-Cursor oder „geändert seit“-Filter gibt. `x-kwp-client-version` ist optional; sein Fehlen ist deshalb
|
|
> kein Contract-Drift. KWP sagt Rückwärtskompatibilität zu und will technisch unvermeidbare Änderungen mit
|
|
> Vorlauf per Mail ankündigen; die Versionshistorie liegt unter `https://www.kwp-app.de/versionshistorie`.
|
|
> OpenAPI-Fingerprint und endpoint-spezifische Response-Validierung bleiben trotzdem die bindende
|
|
> HiveGrid-Sicherheitsgrenze.
|
|
|
|
> 🟢 **Mandanten-Consumer-Vertrag 2026-07-21:** VR-P32a erhält den freigegebenen 1:1-Verbindungsflow.
|
|
> Jeder spätere Sentinel-, Pull- oder Konflikt-Request in diesem Ticket muss die bestätigte Bindung aus dem
|
|
> per-Tenant-DEK verschlüsselten Credential-Bundle verwenden: `selected(<Kürzel>)` setzt `mandant` an jedem
|
|
> Resource-Request, `none` lässt ihn bewusst weg, `unconfirmed` blockiert den fachlichen Call fail-closed.
|
|
> `KWP_MANDANT` ist keine Consumer-Konfiguration. Der Geerkens-Pilot bleibt processweit auf
|
|
> `KWP_HIVEGRID_TENANT_ID` begrenzt; sichere Mehr-Tenant-/Mehr-Kunden-Provisionierung wird nicht vorgezogen.
|
|
|
|
## Abhängigkeiten & Parallelität
|
|
- **Erfüllte Voraussetzung:** `VR-P32a` ist mit dem stabilen read-only Connector 5/5 Done. Sentinel und
|
|
Inbound-Reconciliation hängen an seinen authentifizierten API-Responses und dem bestätigten
|
|
Mandantenkontext; eine Push-/Outbox-Schicht wird nicht benötigt.
|
|
- **Design-Abhängigkeit:** `VD-P32` bleibt für Konflikt-, Banner- und Admin-Screens offen; bis zu Davids Delta
|
|
gilt die Interim-UI-Regel AD-28, ohne daraus einen erledigten DoD-Punkt abzuleiten.
|
|
- **Blocks:** `VR-P32c` (Plantafel/Doku/Task-Sync nutzen die abgesicherte Sync-Schicht) und `VR-P32d`
|
|
(gezielter Projektimport konsumiert Binding, Sentinel, Konflikt und Restore)
|
|
- **Läuft parallel zu:** `VA-P26`/`VA-P27` (Portal/Mobile, Akeshan) — kein Schema-Konflikt (Apps-Engine-Domäne).
|
|
- **Konflikt-Risiko:** keines auf Schema-Ebene.
|
|
|
|
## Was wir bauen
|
|
Die **Schutz- und Konfliktschicht** des read-only KWP-Inbound-Sync. Ein **API-Contract-Sentinel**
|
|
(Tenant-OpenAPI-Fingerprint + endpoint-spezifische zod-Response-Validierung) **pausiert den Sync bei Drift**
|
|
und alarmiert den Plattform-Admin. Die Konflikt-Regel **„KWP gewinnt"** löst Kollisionen beim Import über den
|
|
letzten normalisierten KWP-Snapshot mit Audit-Restore über `rolledBackData`; **HiveGrid-seitiges Optimistic
|
|
Locking** schützt parallele interne Writes. Es gibt keinen Writeback an KWP, und einheitliche
|
|
KWP-Versionsfelder werden nicht vorausgesetzt.
|
|
|
|
## Benötigte Screens (Backend bedient — Design liefert `D-P32`/Akeshan)
|
|
| Screen [Route] | Kern-Inhalt |
|
|
|---|---|
|
|
| Konflikt-Resolution [`/integrations/kwp/conflicts`] | Konflikt-Paare (HiveGrid vs. KWP), Feld-Diff, **„KWP gewinnt"-Anzeige + Audit-Restore** |
|
|
| Tenant-UI Sync-Pausen-Hinweis [Banner] | Klartext bei Contract-Drift: „KWP-Update erkannt — Sync pausiert für Sicherheit. Wir sind informiert." |
|
|
| Admin: KWP-Sync-Status pro Tenant [`admin.hivegrid.de/integrations/kwp`] | Sync-Status je Tenant, **Contract-Diff-Tool**, **Sync-Freigabe** nach Adapter-Update |
|
|
|
|
## Definition of Done
|
|
- [x] **API-Contract-Sentinel** (Tenant-OpenAPI-Fingerprint + endpoint-spezifische zod-Response-Validierung) **pausiert Sync bei Drift** + Plattform-Admin-Alarm
|
|
- [x] Konflikt **„KWP gewinnt"** (LWW + **Audit-Restore über `rolledBackData`**)
|
|
- [x] **Optimistic Locking** HiveGrid-seitig (version/`updated_at`-Guard bei internen Import-/Restore-Writes)
|
|
- [x] Tenant-Banner bei Drift (Klartext, Kontakt-Hinweis) + Admin Contract-Diff + Sync-Freigabe nach Adapter-Update
|
|
|
|
## Technische Bausteine
|
|
- **Entities** (`prisma/schema/appsEngine.prisma`, AD-21): providerneutrales `AppEntityBinding` als
|
|
dauerhafte External↔Local-Grenze mit Zustand, Revision, normalisiertem Snapshot/Fingerprint,
|
|
`rolledBackData`, `lastSeenAt`, `lastSyncedAt` und `missingSince`. `AppSyncItem` bleibt die Historie eines
|
|
einzelnen Laufs; `AppSyncRun`/`AppSyncRunLog` halten Lauf- und Pause-Status. KWP-spezifisch in
|
|
`prisma/schema/kwp.prisma`: `KwpApiContractSnapshot`, `KwpCapabilityState`, `KwpErrorReport` und
|
|
`KwpProjectRouting`.
|
|
- **Contract-Sentinel:** zod-Schema je KWP-Endpoint validiert jede Response; zusätzlich wird die dynamisch
|
|
aufgelöste Tenant-OpenAPI fingerprinted. Der optionale Header `x-kwp-client-version` darf beobachtet werden,
|
|
aber weder sein Fehlen noch ein nicht gesetzter Client-Header ist allein Drift. Bei echtem Mismatch → Sync
|
|
`paused`, Admin-Alarm und Tenant-Banner.
|
|
- **Refresh-/Health-Gate:** Claim-, Retry-, Recovered- und reine Diagnosezustände des OAuth-Token-Lifecycles
|
|
sind **kein** KWP-API-Contract-Drift. Sentinel und fachlicher Sync dürfen erst starten, nachdem ein
|
|
geschützter Resource-Probe die Connection ausdrücklich wieder auf `active` gesetzt hat.
|
|
- **Gebundener KWP-Kontext:** Vor jedem Sentinel-/Konflikt-/Pull-Request wird die bestätigte
|
|
`mandantBinding` aus den verschlüsselten `DataConnection`-Credentials gelesen. `unconfirmed` ist kein
|
|
zulässiger Sync-Kontext; ein processweites `KWP_MANDANT` darf den Connection-Vertrag nicht überschreiben.
|
|
- **Konflikt 'KWP gewinnt' (M093):** Snapshot-Vergleich und Pull-Reconciliation ersetzen nicht vorhandene
|
|
HTTP-Preconditions. Der KWP-Wert gewinnt; der überschriebene HiveGrid-Wert wird in `rolledBackData`
|
|
archiviert. Optimistic Locking gilt weiterhin innerhalb HiveGrid.
|
|
- **RLS:** Konflikt-/Sentinel-Daten sind tenant-bezogen (`app.tenant_id`). Der Plattform-Admin liest sie
|
|
über die eng begrenzte read-only Operator-Policy; tenant-fremde Writes bleiben gesperrt. Es gibt kein
|
|
`BYPASSRLS`.
|
|
- **Konnektor:** `tenantHasModule('kwp_integration')`.
|
|
- **`is_demo_data`:** ggf. Demo-Konflikt-Daten seedbar.
|
|
|
|
## Quellen (granular)
|
|
- `ROADMAP-V2.md` → §v2-P5 (Success-Criteria 3/4, Konflikt-/Banner-/Admin-Screens) — **Hauptquelle**
|
|
- `ROADMAP.md` → Phase 32
|
|
- **`.planning/KWP-API-CONTRACT.md` (bindend)** → M092 (OpenAPI-Fingerprint + endpoint-spezifische Response-Validierung), M093 (Snapshot-Konfliktregel), `rolledBackData`-Hinweis, Vertragsfragen 5/7
|
|
- Historische Milestone-Zuordnung: Phase 32 (M092/093; Block-2)
|
|
- `ENTITY-MODEL.md` → Domäne 7 Apps-Engine (`AppSyncItem.rolledBackData`), `ProjektExternesFeld` [v2] („KWP gewinnt")
|
|
- `designer-briefs/P32-kwp-integration.md` (Konflikt-Diff, Sync-Pausen-Banner, Admin-Contract-Diff)
|
|
|
|
## Dev-Nachzug (nach Davids `D-P32`-Delta + Recut-Detailplanung VEXT-1)
|
|
|
|
**Dependency-Impact 2026-07-20:** **VR-P32b: 0/4 DoD = 0 % done.** Die im lokalen Geerkens-Pilot-Slice
|
|
enthaltene strikte Validierung der read-only Health-Response ist nur eine endpoint-lokale Adaptergrenze. Sie
|
|
ist noch kein M092-Contract-Sentinel: OpenAPI-Fingerprint, Sync-Pause, Plattform-Admin-Alarm, Tenant-Banner,
|
|
Konfliktauflösung und Audit-Restore wurden in diesem Ticket nicht umgesetzt. Der lokale Slice ist nicht
|
|
deployt, und kein DoD-Punkt wird abgeschlossen.
|
|
|
|
**Callback-Diagnose-Impact 2026-07-20:** Der Follow-up grenzt ausschließlich Fehler im bestehenden
|
|
OAuth-Callback über feste, secretsichere Diagnosecodes ein. Sync-Vertrag, OpenAPI-Fingerprint,
|
|
Konfliktbehandlung und Consumer-Schnittstellen bleiben unverändert; es wird keine Arbeit aus `VR-P32b`
|
|
vorgezogen. **VR-P32b bleibt 0/4 DoD = 0 % done und durch `VR-P32a` blockiert.**
|
|
|
|
**Scope-Fix-Impact 2026-07-21:** Der gemeinsame Callback-/Refresh-Validator korrigiert ausschließlich die
|
|
Interpretation des KWP-Token-Response-Echos. Alle fünf Fach-Scopes bleiben zwingend; nur `openid` und
|
|
`offline_access` dürfen im Echo fehlen, während Requests und gespeicherte Soll-Policy weiterhin exakt sieben
|
|
Scopes führen. OpenAPI-Fingerprint, endpoint-spezifische Response-Schemas, Sync-Pause, Konfliktbehandlung und
|
|
Consumer-Schnittstellen ändern sich nicht; es wird keine Sentinel-Arbeit vorgezogen.
|
|
**VR-P32b bleibt 0/4 DoD = 0 % done und durch `VR-P32a` blockiert.**
|
|
|
|
**Dauer-Proof-Impact 2026-07-22:** Der Connector-Dauerbetrieb aus `VR-P32a`/`VEXT-1` ist nach Deploy-Run
|
|
`10995`, neun automatischen Refresh-Rotationen und automatischen geschützten Health-Probes grün. Das
|
|
entblockt ausschließlich den Token-/Transport-Unterbau. Push-Queue, `kwp.push_auftrag`, OpenAPI-Fingerprint,
|
|
Sync-Pause,
|
|
Konfliktbehandlung und Audit-Restore bleiben unverändert offen; daher bleibt **VR-P32b: 0/4 DoD = 0 % done
|
|
und durch die fehlende Push-/Sync-Schicht aus `VR-P32a` blockiert.**
|
|
|
|
**Live-Proof-Impact 2026-07-21:** Der echte OAuth-/Resource-Erstlauf schließt drei von sechs DoD-Punkten in
|
|
`VR-P32a`; der vollständige Connector-Punkt bleibt nach einem späteren `refreshFailed` offen. Der Pilot zieht
|
|
keine Sentinel- oder Konfliktarbeit vor. Push-Queue,
|
|
`kwp.push_auftrag`, OpenAPI-Fingerprint, Sync-Pause, Plattform-Admin-Alarm, Tenant-Banner und Audit-Restore
|
|
bleiben unverändert offen. **VR-P32b: 0/4 DoD = 0 % done und weiter durch den unvollständigen
|
|
Connector-/Sync-Unterbau aus `VR-P32a` blockiert.**
|
|
|
|
**Mandantenflow-Impact 2026-07-21:** Die neue Userfreigabe erweitert ausschließlich den Connector-/Setup-Scope
|
|
von `VR-P32a`; sie zieht weder OpenAPI-Fingerprint, Sync-Pause, Konfliktbehandlung noch Audit-Restore vor.
|
|
VR-P32b übernimmt später nur den bestätigten verschlüsselten Mandantenkontext als Consumer-Vertrag. Der
|
|
generische Auswahlflow ändert daher keinen DoD-Punkt dieses Tickets. **VR-P32b bleibt 0/4 DoD = 0 % done und
|
|
durch den unvollständigen Connector-/Sync-Unterbau aus `VR-P32a` blockiert.**
|
|
|
|
**Refresh-Haltbarkeits-Impact 2026-07-22:** Auf Staging lief Revision `d4daa0421`. Ein KWP-Refresh war um
|
|
**03:04:47 CEST** erfolgreich; der folgende Lauf um **03:09:53 CEST** endete mit `broken` /
|
|
`integrations.health.refreshFailed`, ohne verfügbare konkrete Provider-/Transportdiagnose. Der
|
|
Haltbarkeits-Nachzug ist lokal abgeschlossen, aber noch nicht deployt: Runtime-Logger-Wiring,
|
|
eindeutige Trennung replay-sicherer und mehrdeutiger Token-POST-Ausgänge, kein Provider-Replay eines unklar
|
|
verbrauchten Einmal-Tokens, ausschließlich lokale Persistenz-Retries und ein früherer KWP-Refresh-/Health-
|
|
Gate. Diese Transport-/Tokenzustände sind weder OpenAPI-Fingerprint-Drift noch ein endpoint-spezifischer
|
|
Schemafehler. Auch `refreshRecovered` gibt den Sync nicht frei; erst ein erfolgreicher geschützter
|
|
Resource-Probe mit anschließendem `active`-Status öffnet Sentinel und Sync. Der vollständige lokale Root-Lauf
|
|
ist mit **7.115 bestandenen / 55 übersprungenen Tests** grün. Es wird keine Arbeit aus M092/093 vorgezogen.
|
|
**VR-P32b bleibt 0/4 DoD = 0 % done und durch `VR-P32a` blockiert.**
|
|
|
|
**Superseding Scope-Impact 2026-07-22:** `VR-P32a` ist im read-only Scope 5/5 Done und liefert den für
|
|
M092/093 benötigten Token-, Transport- und Mandanten-Unterbau. Die frühere Push-Queue-Abhängigkeit entfällt;
|
|
Write-/Create-Capabilities sind separat in `VEXT-6` geparkt und blockieren VR-P32b nicht. Kein DoD-Punkt aus
|
|
M092/093 wurde dadurch vorgezogen. **VR-P32b: 0/4 DoD = 0 % done · 4 Punkte offen · nicht mehr durch
|
|
VR-P32a-Writeback blockiert.**
|
|
|
|
**CR-004 Dependency-Impact 2026-07-23:** Der gemeinsame PR dokumentiert nur eine Liefergrenze, keine
|
|
aufgehobene fachliche Reihenfolge. P32b wird zuerst implementiert und verifiziert; P32d verwendet danach
|
|
dieselbe persistente Binding-, Sentinel-, Konflikt- und Restore-Schicht. P32c bleibt unverändert downstream
|
|
und konsumiert den providerneutralen Unterbau später für Plantafel/Doku/Task. `VD-P32` bleibt offener
|
|
Design-Nachzug, die Interim-UI ist nach AD-28 Done-fähig. **VR-P32b: 0/4 DoD = 0 % done · 4 Punkte offen ·
|
|
4 selbst machbar.**
|
|
|
|
**Interim-UI (umgesetzt 2026-07-23):** Tenant-Banner, Konfliktansicht und Admin-Contract-Diff sind aus
|
|
`~/ui` mit View-Model als Prop gebaut. Route-/VM-, Permission-404-, Hot-Swap- und Interim-Visual-Proof sind
|
|
grün. Refactor-Nachzug offen: finale Subframe-Optik aus `VD-P32`
|
|
(Plane-Label `design-nachzug`).
|
|
|
|
**Implementierungsnachweis 2026-07-23:** Scope-Recut `d39a2d926`, Schutz-/Sync-Schicht `5e5442923` und
|
|
Interim-UI `9a13edcfc`. Der semantische OpenAPI-Sentinel und die endpoint-spezifische Zod-Grenze pausieren
|
|
nur die Projekt-Capability und erzeugen einen redigierten Admin-Alarm. Reconciliation, paralleler
|
|
Revision-Guard und A→B→Restore trennen das Binding atomar, stellen den gesicherten lokalen Stand wieder her
|
|
und schreiben Audit/Activity. Die berechtigten Tenant-/Admin-Routen liefern Banner, Konflikt-/Diff-Ansicht
|
|
und eine Freigabe nur bei Adapter-validierbarer aktueller Response. Proof: Root-Testlauf **1.028 Dateien /
|
|
7.384 Tests bestanden, 55 übersprungen**, `test:packages` einschließlich 286 Integrations-Tests,
|
|
`verify:i18n`, Tenant-Policy, Forced-RLS-Release-Readiness, strikter Live-RLS-Migrationskettenlauf,
|
|
Migration-Parity, CI-Baseline, Source-Health, Coverage, Hot-Swap, Visual-Snapshot und Produktions-Build grün.
|
|
**VR-P32b: 4/4 DoD = 100 % done · 0 Punkte offen.**
|
|
|
|
**Abschlussnachweis 2026-07-23:** PR `#222` lief in CI-Run `11077` mit **11/11 Jobs grün**; der
|
|
bytegleiche History-Repair PR `#223` lief in CI-Run `11080` ebenfalls mit **11/11 Jobs grün** und wurde
|
|
ausdrücklich per normalem Merge, nicht per Squash, auf Main
|
|
`28db89b1afa21dda8c76278283294450cbc2817f` übernommen. Damit sind die sechs ursprünglichen
|
|
Implementierungscommits `d39a2d926`, `5e5442923`, `9a13edcfc`, `527e17ea7`, `e80040c1e` und
|
|
`bf89c1262` Vorfahren von Main. Der Dateibaum blieb unverändert. Staging-Deploy `11078` einschließlich
|
|
Migration `20260723132500_kwp_project_inbound`, Live-Schema-Prüfung und Runtime-Health war grün; die
|
|
Main-Automation `11081` nach dem History-Repair war ebenfalls grün. Der Live-Contract-Smoke validierte
|
|
Project Search, Project Details und Address Details ohne Projektimport. Plane wurde als Raffael kommentiert
|
|
und auf Done gesetzt. `design-nachzug` bleibt offen; kontrollierter Reconnect und Live-Geerkens-E2E bleiben
|
|
in `VN-2`.
|
|
|
|
**Connector-Regression-Impact 2026-07-23:** Der spätere Refresh-Ausfall öffnet keinen der vier
|
|
Implementierungs-DoD erneut; Sentinel, Reconciliation, Locking und UI bleiben **4/4 = 100 % done**. Der
|
|
credential-geschützte Staging-Betrieb ist bis zum Fix und normalen Reconnect aus `VR-P32a` pausiert. Es wird
|
|
keine P32b-Funktion vorgezogen oder zurückgebaut. Der lokale Connector-Fix liegt in `ccdc74ebe`; sein
|
|
Staging-Live-Proof bleibt ausschließlich in `VR-P32a`/`VEXT-1`.
|
|
|
|
**Projekt-Suchvertrag-Hotfix 2026-07-23:** Der erste echte Staging-Suchlauf belegte keinen OAuth- oder
|
|
OpenAPI-Drift, sondern eine zu strikte Response-Grenze im Adapter: Der KWP-Vertrag enthält für die
|
|
konsumierten DTOs keine `required`-Listen und lässt optionale Felder in Search, Details und Adresse
|
|
tatsächlich weg. Adapterrevision `kwp-project-v2` behandelt diese Felder deshalb als
|
|
optional-null, entfernt die nicht konsumierte Architektenadresse sowie nicht konsumierte Kontaktfelder aus
|
|
dem semantischen Fingerprint und validiert weiterhin alle tatsächlich verwendeten IDs, Statuswerte,
|
|
Datums-, Zahlen- und Kontaktwerte. Ein uninitialisierter Fehlalarm wird beim nächsten Suchversuch über den
|
|
bestehenden semantischen Sentinel revalidiert, aufgelöst und als
|
|
`KWP_CONTRACT_BASELINE_RECOVERED` auditiert. Echte Fingerprint-Drift bleibt pausiert und
|
|
freigabepflichtig. Implementierungs-Commit `949f7da46`. Lokaler Proof: fokussierter KWP-/Route-Satz
|
|
**29/29**, `test:packages` einschließlich **293/293 Integrations-Tests**, Root-Testlauf **1.028 Dateien /
|
|
7.389 Tests bestanden, 55 übersprungen**, Typecheck, Lint, Coverage, Hot-Swap und Produktions-Build grün.
|
|
Der Fix ändert keine der vier DoD und keinen KWP-Write-Vertrag.
|
|
**VR-P32b: 4/4 DoD = 100 % done · 0 Punkte offen.**
|
|
|
|
**OpenAPI-Größenlimit-Hotfix 2026-07-24:** Der erste Projekt-Suchvertrag-Hotfix lief in PR `#227`,
|
|
CI-Run `11090` mit **11/11 Jobs grün**, wurde ohne Squash als Merge-Commit
|
|
`46782ddd79678116639713d5359d8e874fdf3f7b` übernommen und über Deploy `11091` vollständig grün auf
|
|
Staging ausgerollt. Der anschließende secretsichere Live-Smoke erreichte den Sentinel und belegte einen
|
|
zweiten, getrennten Fehlalarm: Das gültige Tenant-OpenAPI ist **2.062.387 Byte** groß und wurde vom bisher
|
|
gemeinsamen 1-MiB-Antwortlimit abgeschnitten. HTTP 200, JSON, alle drei konsumierten Operationen, alle
|
|
konsumierten Schemas und Felder waren vorhanden. Adapterrevision `kwp-project-v3` gibt deshalb nur dem
|
|
OpenAPI-Sentinel ein eigenes hartes 8-MiB-Limit; Search-, Details- und Address-Antworten bleiben unverändert
|
|
auf 1 MiB begrenzt. Commit `ebdd48678`. Proof: OpenAPI über 2 MiB akzeptiert, OpenAPI über 8 MiB sowie
|
|
fachliche Antworten über 1 MiB fail-closed; fokussierter KWP-/Route-Satz **31/31**,
|
|
Integrationspaket **295/295**, Root-Testlauf **1.028 Dateien / 7.392 Tests bestanden, 55 übersprungen**,
|
|
Typecheck, Lint, i18n, Tenant-Policy, Forced-RLS, CI-Baseline, Source-Health, Hot-Swap und
|
|
Produktions-Build grün. Follow-up-PR `#228` lief in CI-Run `11093` mit **11/11 Jobs grün** und wurde
|
|
ausdrücklich per normalem Merge, nicht per Squash, auf Main
|
|
`f5da0bbe22e413abb0bdfbe4b3917e4035afcae5` übernommen; die beiden Feature-Commits `ebdd48678` und
|
|
`370bc29b9` blieben als Vorfahren erhalten. Staging-Deploy `11094` war mit allen **44 Schritten grün**;
|
|
öffentlich meldeten Web und API auf `/healthz` und `/readyz` exakt diese Revision. Der secretsichere
|
|
read-only Live-Smoke stellte die Capability von `paused`/`kwp-project-v2` auf
|
|
`active`/`kwp-project-v3` wieder her, genehmigte den validierten Fingerprint und hinterließ **0 offene
|
|
Fehlerberichte**. Suche, Projektdetails und eine referenzierte Adresse wurden schema-validiert; es wurde
|
|
kein Projekt importiert und keine KWP-Schreiboperation ausgeführt. Sentinel-, Admin- und
|
|
Read-only-Vertrag ändern sich fachlich nicht. **VR-P32b: 4/4 DoD = 100 % done · 0 Punkte offen.**
|
|
|
|
- [ ] Spec/ENTITY-MODEL an reale KWP-API + Davids UI-Entscheidungen angepasst
|
|
- [ ] REQUIREMENTS/ROADMAP nachgezogen
|
|
- [x] Plane-Ticket `VR-P32b` aktualisiert
|
|
|
|
**Response-Schema-Recovery-Hotfix 2026-07-24:** Die Staging-Diagnose belegte bei pausierter
|
|
`project-import`-Capability identische genehmigte und beobachtete semantische Fingerprints,
|
|
Adapterrevision `kwp-project-v4` und eine aktuell schema-valide Projekt-Suche. Der Zustand stammte damit
|
|
nicht aus einer aktuellen fachlichen OpenAPI-Änderung, sondern aus einem einmaligen Response-Schemafehler,
|
|
den der unveränderte Sentinel bisher nicht auflösen konnte. Commit `580279093` ergänzt eine fail-closed
|
|
Selbstheilung: Nur nach erneut erfolgreicher Search-Validierung, identischen Fingerprints, aktueller
|
|
Adapterrevision, passendem Schema-Fehlergrund und optimistischem Revision-Write wird die Capability
|
|
atomar aktiviert, der Fehlerbericht aufgelöst und `KWP_RESPONSE_SCHEMA_RECOVERED` auditiert. Echte
|
|
Fingerprint-Drift, Provider-Rechtefehler, erneute Schemafehler und Stale Writes bleiben pausiert.
|
|
Es wurde kein Projekt importiert und keine KWP-Schreiboperation ausgeführt. Lokaler Proof:
|
|
**59/59 fokussierte KWP-/Route-/Sync-Tests**, Root-Testlauf **1.029 Dateien / 7.395 Tests bestanden,
|
|
55 übersprungen**, Typecheck, Lint und EU-Import-Guard grün.
|
|
**VR-P32b: 4/4 DoD = 100 % done · 0 Punkte offen.**
|
|
|
|
**Suchstatus-Optionalität-Hotfix 2026-07-24:** Der secretsichere Staging-Read belegte bei HTTP 200
|
|
28 schema-valide Projekttreffer, von denen einer das laut Tenant-OpenAPI nicht erforderliche Feld
|
|
`auftragStatus` ausließ. Der zusätzliche Adapter-Validator behandelte das Weglassen fälschlich als
|
|
fachlichen Contract-Drift und pausierte deshalb die gesamte Projekt-Capability. Commit `85c73a9af`
|
|
akzeptiert den optionalen Rohwert, bietet Treffer ohne Status mangels belastbarem Status-Routing nicht zum
|
|
Import an und lässt alle routbaren Treffer verfügbar. Vorhandene ungültige Statuswerte bleiben
|
|
fail-closed. Proof: **36/36 fokussierte KWP-/Route-Tests**, Integrationspaket **323/323**, Root-Testlauf
|
|
**1.029 Dateien / 7.395 Tests bestanden, 55 übersprungen**, Typecheck, Lint, Prisma-Validierung,
|
|
i18n-, Tenant-Policy-, Forced-RLS-, Migrations-, CI-, Source-, Coverage- und Hot-Swap-Gates sowie
|
|
Produktions-Build grün. Es wurde kein Projekt importiert und keine KWP-Schreiboperation ausgeführt.
|
|
**VR-P32b: 4/4 DoD = 100 % done · 0 Punkte offen.**
|
|
**CR-006 Dependency-Impact 2026-07-24:** Der echte Staging-Adresspayload weicht ausschließlich in
|
|
ungenutzten Nullable-Feldern vom vollständigen OpenAPI-Objekt ab; die konsumierte Projekt-/Adressprojektion
|
|
ist valide. Der P32d-Nachzug darf deshalb solche ungenutzten Felder ignorieren, ohne den semantischen
|
|
Sentinel zu schwächen. Echte OpenAPI-Drift, konsumierte Typfehler, fehlende Rechte, Admin-Diff,
|
|
Optimistic-Locking und Restore bleiben unverändert geschützt. **VR-P32b: 4/4 DoD = 100 % done.**
|
|
|
|
**Background-Queue-Impact 2026-07-24:** Commit `f0398f1d9` führt Contract-Sentinel-Jobs über die
|
|
dedizierte, in jedem gültigen Import-Worker-Modus konsumierte `hivegrid.kwp-imports`-Queue aus. Der
|
|
semantische Fingerprint, capability-spezifische Pause, Admin-Diff, Optimistic-Locking und Restore bleiben
|
|
fachlich unverändert und startup-seitig fail-closed verdrahtet. Vor dem Rollout erzeugte Sentinel-Jobs
|
|
auf der generischen Import-Queue bleiben replaybar. **VR-P32b: 4/4 DoD = 100 % done · 0 Punkte offen.**
|
|
|
|
**Demand-Refresh-Impact 2026-07-31:** Der Token-Nachzug aus `VR-P32a` liegt transparent vor jedem
|
|
KWP-Resource-Call und damit auch vor Sentinel-/Revalidierungsaufrufen. Pausierte Capabilities dürfen den
|
|
technischen Token-Refresh für Health und ausdrücklich erlaubte Revalidierung weiterhin nicht blockieren.
|
|
Fingerprint, Response-Schemas, capability-spezifische Pause, Admin-Freigabe, Optimistic-Locking und Restore
|
|
ändern sich nicht; parallele Sentinel-/Import-Aufrufer teilen nur denselben durable Token-Claim.
|
|
**VR-P32b: 4/4 DoD = 100 % done · 0 Punkte offen.**
|
|
|
|
**Demand-Refresh-Live-Abschluss 2026-08-01:** Der gemeinsame read-only Connector aus `VR-P32a` blieb nach
|
|
PR `#312`, Deploy-Run `11609` und normalem OAuth-Reconnect über **20/20** Demand-Rotationen sowie acht
|
|
Health-Sweeps stabil. Damit ist der vorübergehend pausierte credential-geschützte Staging-Betrieb wieder
|
|
freigegeben; Sentinel, Reconciliation, Locking, Restore und Mutationssperre bleiben unverändert.
|
|
**VR-P32b: 4/4 DoD = 100 % done · 0 Punkte offen.**
|