Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VR-P32d.md
T

395 lines
32 KiB
Markdown

# VR-P32d · KWP-Inbound Projekt-Upsert + Pipeline-Routing
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Raffael |
| **Phase** | v2-P5 — KWP-Integration |
| **Cycle/Fenster** | v2-W2 · 2026-07-24 → 2026-07-26 |
| **Status** | Done · **14/14 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:** Wegen fehlender garantierter Pagination behauptet dieses
> Ticket keinen KWP-Vollimport. Es liefert einen gezielten, wiederholbaren User-Flow:
> Projekt suchen → Details laden → Status-Routing festlegen → neues HiveGrid-Projekt anlegen oder ein
> sichtbares bestehendes verknüpfen → Projekt-/Rechnungs-/Bauherradresse verbinden → optional je Rolle einen
> primären Ansprechpartner wählen → dauerhaft read-only synchronisieren. P32b und P32d werden in einem PR
> geliefert, intern weiterhin strikt P32b vor P32d.
> 🟢 **CR-006 Scope-Entscheidung 2026-07-24:** Eine bestätigte Verbindung baut automatisch einen lokalen,
> tenant-/connectiongebundenen KWP-Projektkatalog auf. Discovery verwendet ausschließlich den laut
> Tenant-OpenAPI einstellungsabhängigen Platzhalterbestand aus `LoadProjekteNachFilter`; gezielte Suchen
> ergänzen denselben Katalog read-through. Ohne Provider-Pagination wird kein darüber hinausgehender
> Vollbestand behauptet. Der Import validiert ausschließlich seine konsumierte Response-Projektion, damit
> ungenutzte Nullable-Abweichungen keinen falschen Capability-Stopp auslösen.
> 🟢 **Superseding Scope-Entscheidung 2026-07-22:** Dieses Ticket bleibt ausschließlich
> KWP→HiveGrid. Es liest KWP-Projekte und mutiert nur den tenant-gebundenen HiveGrid-Projektkern; es sendet
> keine fachliche Mutation an KWP. Project-/Auftrag-Create, Writeback und M091 sind in `VEXT-6` geparkt und
> blockieren das Inbound-Ticket nicht. Historische Notizen zum früheren Outbound-Gegenpfad bleiben als
> Entscheidungsprotokoll erhalten.
## Abhängigkeiten & Parallelität
- **Blocked by:** `VR-P32b`. Im gemeinsamen CR-004-PR wird P32b intern zuerst vollständig umgesetzt und
verifiziert. `VEXT-1` ist seit dem stabilen Refresh-Dauer-Proof vom 2026-07-22 4/4 Done.
- **Erfüllte Voraussetzungen:** `R-P20b` liefert die stabilen Pipeline-/Stage-IDs; `R-P12c` liefert den
produktiven Inbound-Event-/Executor-Unterbau. Beide sind umgesetzt und keine offenen Blocker.
- **Lokaler Verifikationsvertrag:** Schema-valide KWP-Fixtures und tenant-/RLS-gebundene Integrationstests
belegen Mapping, Reconciliation, Replay, Quarantäne und Konfliktpfade. `VN-1`/`VN-2` sind keine
Implementierungs-Blocker; `VN-2` besitzt exklusiv den späteren Live-Geerkens-E2E.
- **Blocks:** `VN-2` als nachgelagerter Live-Proof
- **Abgrenzung:** `VR-P32a` liefert ausschließlich Connector/Health/Mandantenbindung; dieses Ticket besitzt
den fachlichen read-only KWP→HiveGrid-Projektimport. Ein späterer Outbound-Vertrag wird separat über
`VEXT-6` neu geschnitten.
- **Dependency-Stand 2026-07-22:** `R-P20b` liefert die stabile Drei-Pipeline-/Fünf-Stage-Baseline und den
inaktiven Metadaten-Key `shk.kwp-project-routing.v1`; `R-P12c` ist 7/7 umgesetzt. Der Bootstrap selbst
führt weiterhin keine KWP-Automation aus.
- **Runtime-Dependency-Stand 2026-07-21:** Der echte Staging-Erst-Proof umfasste OAuth, einen geschützten
read-only Core-Aufruf und mehrere Refresh-Rotationen; ein späterer Refresh setzte die Connection jedoch auf
`broken`, daher bleibt `VEXT-1` für Dauerbetrieb offen. Der Pilot enthielt
keinen Projekt-Pull oder -Write. KWP hat außerdem ausdrücklich bestätigt, dass es weder Delta-Cursor noch
„geändert seit“-Filter gibt. Die Implementierung muss deshalb eine konservative cursorlose Reconciliation
aus dem real dokumentierten Endpoint- und Pagination-Vertrag ableiten. CR-003/AD-32 legen dafür keine
konkrete Vollabzug-, Partitionierungs- oder lokale Cursorstrategie fest; eine providerseitige
Delta-Semantik wird nicht erfunden.
## Was wir bauen
KWP-Projekte werden über den freigegebenen read-only Polling-Vertrag idempotent in den typisierten
`Projekt`-Kern übernommen und anhand einer expliziten stabilen Mapping-Konfiguration geroutet. Der User sucht
gezielt ab zwei Zeichen, prüft den Detail-Diff und entscheidet zwischen Neuanlage und Verknüpfung. Die lokale
HiveGrid-Projektnummer bleibt unverändert; KWP-`projNr` wird als externe Referenz gespeichert und in der
normalen HiveGrid-Suche auffindbar.
Projekt-, Rechnungs- und Bauherradresse werden je Rolle explizit mit einem vorhandenen CRM-Kontakt verbunden
oder bewusst neu angelegt. Vorhandene External-Bindings gewinnen; danach sind nur Vorschläge über exakt
normalisierte E-Mail oder exakten Namen plus Anschrift erlaubt. Es gibt kein automatisches Fuzzy-Merge und
keine ungefragte Massenübernahme von Ansprechpartnern. Fehlende oder mehrdeutige Status-Mappings landen in
Quarantäne; HiveGrid rät keine Pipeline oder Stage und mutiert KWP nicht.
## Definition of Done
- [x] **Gezielte Suche:** `Projekt/Search` und Projektdetails sind schema-validiert; Suchbegriffe unter zwei
Zeichen werden abgewiesen und kein Vollimport behauptet
- [x] **Create/Link:** neues HiveGrid-Projekt oder explizites Linken eines sichtbaren bestehenden Projekts
nach Diff; lokale Projektnummer bleibt unverändert
- [x] **Adressen:** Projekt-, Rechnungs- und Bauherrrolle können jeweils vorhandene CRM-Daten wählen oder
bewusst dedupliziert neu anlegen
- [x] **Ansprechpartner:** pro Rolle höchstens eine ausgewählte Person; keine automatische Massenübernahme
- [x] **Dauerhaftes Mapping:** connectiongebundene eindeutige `AppEntityBinding`s bleiben über Runs und
Reconnects stabil; `AppSyncItem` bleibt Laufhistorie
- [x] **Status-Routing:** jeder auftretende KWP-Status verwendet gespeicherte stabile Pipeline-/Stage-IDs;
unbekannte Statuswerte oder archivierte Ziele quarantänisieren
- [x] **Ownership/Unlink:** KWP-eigene Felder sind serverseitig gegen lokale Änderung, Stage-Move,
Archivierung und Binding-Übernahme beim Duplizieren geschützt; Trennen behält lokale Projekt-/CRM-Daten
- [x] **Drei-Phasen-Sync:** Provider-I/O läuft außerhalb langer DB-Transaktionen; lokaler Projekt-/CRM-Upsert,
Binding, Audit, Activity, Search und Outbox werden atomar geschrieben
- [x] **Betriebssicherheit:** gemeinsames Rate-Budget, Lease, Replay, Retry und Quarantäne verhindern
Dopplungen und behandeln 429/401/403/404/5xx ohne lokale Teilmutation
- [x] **UI und Querschnitt:** Interim-UI, Suche nach KWP-Nummer, Audit, Activity, i18n,
Error-/Empty-/Loading-State und Permission-404-Gates sind mit VM-Unit, Smoke, Hot-Swap, Visual und
Forced-RLS-Test belegt
- [x] **Semantische Response-Projektion:** Search, Projekt- und Adressdetails pausieren nur bei ungültigen
konsumierten Feldern; ungenutzte OpenAPI-Felder mit abweichender Nullable-Semantik werden redigiert
ignoriert und ein unveränderter Vertrag kann revisionssicher wieder aktiviert werden
- [x] **Automatischer Projektkatalog:** aktive bestätigte Connections erhalten ohne User-Suchaktion einen
lease-/replay-sicheren Discovery-/Refresh-Lauf über die Import-Queue; große Bestände werden in begrenzten
Batches unter dem gemeinsamen Rate-Budget verarbeitet
- [x] **Skalierbare Cache-Suche:** schema-valide Live-Treffer und Discovery-Platzhalter werden dauerhaft
tenant-/connectiongebunden gespeichert; die Suche arbeitet cache-first über einen trigram-indizierten
normalisierten Suchtext und ergänzt kontrolliert live, ohne leere Provider-Suche
- [x] **Katalog- und UI-Recovery:** Import-VM und Interim-UI zeigen Katalogstatus/Alter/Fortschritt,
Search-/Select-/Button-Layout überlappt nicht, Error-/Loading-/Empty-State und Forced-RLS-/Visual-Proof
decken den neuen Flow ab
## Technische Bausteine
- **Transport:** zentraler serverseitiger Resource-Client in `packages/integrations/src/kwp/**` mit
`searchProjects({ connectionId, query })`, `loadProjectDetails({ connectionId, projectNumber })` und
`loadAddressDetails({ connectionId, addressCode })`. Er injiziert Access-Token und bestätigten Mandanten,
blockiert `unconfirmed`, validiert jede Response mit Zod und erlaubt ausschließlich
`POST /api/Projekt/Search`, `GET /api/Projektampel/LoadProjektDetails`,
`GET /api/Adresse/LoadAdressKomplett` sowie Tenant-OpenAPI für den Sentinel.
- **Schreibschutz KWP:** `Projekt/Save`, `Adresse/Save*`, `Adresse/Add*` und alle anderen fachlichen
KWP-Schreiboperationen werden vom Allowlist-Client abgewiesen. Resource-Calls führen keine eigene
Refresh-Token-Anforderung aus; der dauerhafte zentrale Refresh-/Health-Pfad bleibt alleiniger Besitzer der
Rotation.
- **Persistenz:** providerneutrales `AppEntityBinding` in `appsEngine.prisma`; KWP-spezifisch
`KwpApiContractSnapshot`, `KwpCapabilityState`, `KwpErrorReport` und `KwpProjectRouting` in `kwp.prisma`.
Alle Tabellen sind tenant-scoped, RLS-gebunden und in der Tenant-Registry eingetragen.
- **Feld-Ownership:** KWP besitzt Projektname, KWP-Status und daraus abgeleitete Pipeline/Stage, Beginn,
Auftragswert, externe Projektnummer sowie gebundene KWP-Adressen/-Kontaktdaten. Vor jeder Überschreibung
wird der alte lokale Stand im Binding gesichert. IBAN, Bank, Kreditlimit, Steuerdaten, Geburtstag, interne
KWP-Hinweise und Benutzerfelder werden nicht gespeichert.
- **CRM-Matching:** External-Binding zuerst; danach nur exakte normalisierte E-Mail oder exakter Name plus
Anschrift. Derselbe KWP-Adresscode wird nur einmal angelegt. Architektenadresse und weitere Ansprechpartner
sind außerhalb dieses Slices.
- **Permissions:** Ansicht/Suche `integrations.read`; Erstellen/Verknüpfen/Mapping/Trennen zusätzlich
`integrations.connect` und `projects.write`. Bestehende Projekte bleiben durch normale Projektsichtbarkeit
geschützt. Fehlende Berechtigung liefert 404.
- **Scheduler:** Projekte alle 15 Minuten, gebundene Adressen alle 60 Minuten oder sofort bei geändertem
Adresscode, Sentinel täglich und beim ersten Lauf einer neuen Revision. Maintenance plant; die vorhandene
Import-Queue führt aus.
- **Seiteneffekte:** Erstimport schreibt Search, Audit und Activity, aber kein Workflow-Event. Spätere
KWP-Stage-Änderungen veröffentlichen `project.stage_changed` mit `source=kwp`; reine Name-/Wert-/
Adressänderungen schreiben nur Audit, Activity und Search.
- **Fehlerregeln:** 429 jobweiter Backoff mit Jitter; 401 wartet auf zentralen Refresh/Health-Pfad; 403
pausiert nur die Projekt-Capability; 404/fehlender Treffer markiert `missing`; unbekannter Status oder
ungültiges Routing quarantänisiert; Schemafehler pausiert wegen Contract-Drift; Netzwerk/5xx retryt ohne
lokale Teilmutation.
## Quellen
- `.planning/ticket-docs/VR-P32a.md`, `VR-P32b.md`, `VR-P32c.md`, `R-P20b.md`, `R-P12c.md`, `VN-2.md`
- `.planning/KWP-API-CONTRACT.md`
- `docs/ARCHITECTURE-DECISIONS.md` → AD-1, AD-20, AD-21
## Umsetzungs-Notiz
**Historischer Stand vor dem Scope-Recut:** VR-P32d war 0/7 und durch `VR-P32b`, `R-P20b`, `R-P12c`,
`VN-1` sowie den widersprüchlichen Delta-Cursor-Vertrag blockiert.
**Dauer-Proof-Impact 2026-07-22:** `VEXT-1` ist nach Deploy-Run `10995`, neun automatischen
Refresh-Rotationen und automatischen geschützten Health-Probes 4/4 Done und wurde als Runtime-Blocker entfernt.
Da sämtliche sieben DoD-Punkte zu diesem Zeitpunkt weiterhin von `VR-P32b`, `R-P12c`, `VN-1` oder der
offenen Delta-Scope-Entscheidung abhingen, blieb
**VR-P32d: 0/7 DoD = 0 % done · 7 Punkte offen, davon 7 blockiert · 0 selbst machbar.**
**Superseding Scope-Impact 2026-07-22:** Der fehlende KWP-Create-/Write-Vertrag ist kein Blocker mehr, weil
VR-P32d ausschließlich read-only importiert. `VEXT-6` hält diese externe Zukunftscapability getrennt nach.
`R-P20b` und `R-P12c` sind erfüllt; die Grenze ohne erfundene Delta-, Cursor- oder Webhook-Semantik ist oben
festgelegt. Offen bleiben der
vorgelagerte Schutz-/Konflikt-Slice `VR-P32b` und die eigentliche Implementierung. Der konkrete
Reconciliation-Mechanismus wird erst aus dem realen Endpoint-/Pagination-Vertrag abgeleitet; CR-003/AD-32
erfinden keinen Cursorersatz. Lokale schema-valide Fixtures und Integrationstests schließen die sieben
Implementierungs-DoD; `VN-1`/`VN-2` folgen ausschließlich als nachgelagerter Live-Proof. Nach der
ticketgebundenen Reihenfolge beginnt VR-P32d erst nach VR-P32b. **VR-P32d: 0/7 DoD = 0 % done · 7 Punkte
offen · Start wartet auf `VR-P32b` · kein externer Live-Proof blockiert die Implementierung.**
**CR-004 Scope-/Dependency-Impact 2026-07-23:** Die sieben alten DoD werden durch zehn überprüfbare
Import-DoD ersetzt. Der gemeinsame PR liefert P32b zuerst und P32d danach; P32c konsumiert später denselben
providerneutralen Binding-/Sentinel-Unterbau, ohne dass Plantafel-, Doku-, Task- oder Material-Scope
vorgezogen wird. VN-2 bleibt exklusiver Live-Geerkens-Proof. VD-P32 bleibt offener Design-Nachzug; die
Interim-UI ist nach AD-28 Done-fähig. **VR-P32d: 0/10 DoD = 0 % done · 10 Punkte offen · Start intern nach
VR-P32b · kein externer Live-Proof blockiert die Implementierung.**
**Interim-UI (umgesetzt 2026-07-23):** Der Import-Wizard unter
`/{tenant}/settings/integrations/kwp/import` ist aus `~/ui` mit View-Model als Prop gebaut. VM-/Route-,
Permission-404-, Smoke-Manifest-, 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`, persistenter Transport-/Domain-/Sync-Slice
`5e5442923` und User-/Admin-Flow `9a13edcfc`. Die exakte Read-Allowlist akzeptiert ausschließlich
Projekt-Suche, Projekt-/Adressdetails und das Sentinel-OpenAPI; sie blockiert unbestätigte Mandanten und alle
KWP-Mutationen. Create/Link erhält die lokale Projektnummer, dedupliziert die drei CRM-Rollen ohne Fuzzy-Merge
und speichert je Rolle höchstens einen ausgewählten Ansprechpartner. Status-Routing, durable
External↔Local-Bindings, serverseitige Ownership-Gates, Unlink/Restore, Drei-Phasen-Sync, gemeinsames
Redis-Budget, Queue-Leases, Replay/Retry und Quarantäne sind fixture- und RLS-validiert. Erstimport erzeugt
kein Workflow-Event; spätere Stage-Wechsel nutzen `project.stage_changed` mit `source=kwp`. Proof: Root-Testlauf
**1.028 Dateien / 7.384 Tests bestanden, 55 übersprungen**, `test:packages` einschließlich 286
Integrations-Tests, i18n/Tenant-Policy/Forced-RLS/strikter Live-RLS-Migrationskettenlauf, Migration-Parity,
CI-Baseline, Source-Health, Coverage, Hot-Swap, Interim-Visual-Snapshot und Produktions-Build grün.
**VR-P32d: 10/10 DoD = 100 % done · 0 Punkte offen.**
**OpenAPI-Größenlimit-Hotfix 2026-07-24:** PR `#227` wurde nach **11/11 grünen CI-Jobs** normal, ohne
Squash, als Main-Merge `46782ddd79678116639713d5359d8e874fdf3f7b` übernommen; Staging-Deploy `11091`
war vollständig grün. Der danach ausgeführte read-only Smoke importierte kein Projekt, fand aber vor der
eigentlichen Suche einen separaten Sentinel-Fehlalarm: Das gültige Tenant-OpenAPI umfasst
**2.062.387 Byte** und überschritt das gemeinsame 1-MiB-Limit. HTTP 200, valides JSON, alle drei
konsumierten Operationen sowie sämtliche konsumierten Schemas/Felder wurden redigiert bestätigt.
Adapterrevision `kwp-project-v3` verwendet nun für OpenAPI ein hartes 8-MiB-Limit, während Search, Details
und Address weiterhin bei 1 MiB fail-closed bleiben. Commit `ebdd48678`; lokaler Proof: **31/31**
fokussierte Tests, Integrationspaket **295/295**, Root **1.028 Dateien / 7.392 Tests bestanden,
55 übersprungen**, Typecheck, Lint, i18n/RLS/CI/Hot-Swap und Produktions-Build grün. Follow-up-PR `#228`
lief in CI-Run `11093` mit **11/11 Jobs grün** und wurde ohne Squash als normaler Merge
`f5da0bbe22e413abb0bdfbe4b3917e4035afcae5` übernommen. Staging-Deploy `11094` war mit **44/44 grünen
Schritten** erfolgreich; Web und API meldeten öffentlich exakt diese Revision als healthy und ready. Der
read-only Live-Smoke bestätigte eine aktive KWP-Verbindung, `kwp-project-v3`, übereinstimmende genehmigte
Fingerprints und **0 offene Fehlerberichte**. Suche lieferte Treffer; gewählte Projektdetails und eine
referenzierte Adresse wurden schema-validiert. Es wurde kein Projekt importiert und keine KWP-
Schreiboperation ausgeführt. Create/Link, CRM-Bindung, Routing, Ownership und Read-only-Grenzen ändern sich
nicht. **VR-P32d: 10/10 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, credential-geschützte
read-only Live-Suche und Live-Geerkens-E2E bleiben in `VN-2`.
**Connector-Regression-Impact 2026-07-23:** Suche, Create/Link, CRM-Bindung, Routing, Ownership,
Drei-Phasen-Sync und UI bleiben implementiert und **10/10 = 100 % done**. Der echte credential-geschützte
Staging-Test kann erst nach dem `VR-P32a`-Fix und einem normalen OAuth-Reconnect fortgesetzt werden. Der Fix
ändert weder Projektimport-Scope noch KWP-Read-only-Grenze. Der lokale Connector-Fix liegt in `ccdc74ebe`;
sein Staging-Live-Proof bleibt ausschließlich in `VR-P32a`/`VEXT-1`.
**Projekt-Suche-Hotfix 2026-07-23:** Der erste echte Search-Aufruf auf Staging lieferte HTTP 200 und
gültige Treffer, ließ aber gemäß Tenant-OpenAPI optionale Felder wie `archAdr`, `beginn`, `sachBearb`,
`vertrieb`, einzelne Ortsfelder und `rechnungsmailadresse` weg. Die bisherige Zod-Grenze wertete dieses
zulässige Weglassen fälschlich als `contract_drift`, pausierte dadurch die Projekt-Capability und ließ die
Route vor dem Capability-Banner in den generischen 500er laufen. Adapterrevision `kwp-project-v2`
normalisiert fehlende konsumierte Felder auf `null`, ignoriert Architekt und weitere nicht konsumierte
Felder weiterhin vollständig und behält die strikte Typ-, Größen-, Allowlist- und Read-only-Grenze bei.
Die Route rendert Capability-Fehler nun als Klartextzustand; einen uninitialisierten Alt-Fehlalarm
revalidiert der Sentinel und wiederholt die Suche genau einmal. Netzwerk-/5xx-Fehler werden dabei nicht
verschluckt. Implementierungs-Commit `949f7da46`. Lokaler Proof: echte redigierte Shape-Diagnose gegen
Search, Details und Adresse ohne Projektimport, 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. Alle Importgrenzen
bleiben unverändert.
**VR-P32d: 10/10 DoD = 100 % done · 0 Punkte offen.**
**Response-Schema-Recovery-Hotfix 2026-07-24:** Eine spätere Staging-Suche traf auf einen persistenten
Pause-Zustand, obwohl genehmigter und beobachteter semantischer Fingerprint identisch waren und die
aktuelle Search-Response den Adapter `kwp-project-v4` validierte. Commit `580279093` lässt die
Import-Route bei einem unveränderten Sentinel genau diese Read-Anfrage einmal durch den pausierten Adapter
revalidieren. Die Entsperrung erfolgt nur mit gleichem Fingerprint, aktuellem Adapter, Schema-Fehlergrund
und Revisions-Guard; echte Drift, fehlende KWP-Rechte, ungültige Responses und Parallelkonflikte bleiben
pausiert. Der Flow schreibt ausschließlich Capability-State, Fehlerauflösung und Audit, niemals in KWP.
Create/Link, CRM-Bindung, Routing, Ownership und die Importgrenzen bleiben unverändert. Lokaler Proof:
**59/59 fokussierte Tests**, Root **1.029 Dateien / 7.395 Tests bestanden, 55 übersprungen**, Typecheck,
Lint und EU-Import-Guard grün. Es wurde kein Realprojekt importiert.
**VR-P32d: 10/10 DoD = 100 % done · 0 Punkte offen.**
**Suchstatus-Optionalität-Hotfix 2026-07-24:** Der echte read-only Staging-Search lieferte 28
OpenAPI-valide Treffer; genau ein Treffer enthielt keinen `auftragStatus`. Commit `85c73a9af` bildet diese
zulässige Optionalität im Resource-Adapter ab und filtert den nicht routbaren Treffer aus der
Importauswahl, statt einen Status zu erfinden oder die gesamte Capability zu pausieren. Routbare Treffer
bleiben suchbar; ein vorhandener Wert außerhalb des konsumierten KWP-Enums löst weiterhin
`contract_drift` aus. Proof: **36/36 fokussierte KWP-/Route-Tests**, Integrationspaket **323/323**,
Root-Testlauf **1.029 Dateien / 7.395 Tests bestanden, 55 übersprungen**, Typecheck, Lint,
Prisma-/RLS-/Migration-/i18n-/Coverage-/Hot-Swap-Gates und Produktions-Build grün. Kein Realprojekt wurde
importiert und keine Provider-Mutation ausgeführt. Create/Link, CRM-Bindung, Routing und Ownership bleiben
unverändert. **VR-P32d: 10/10 DoD = 100 % done · 0 Punkte offen.**
**CR-006 Scope-/Dependency-Impact 2026-07-24:** Der echte redigierte Staging-Proof hat Projekt-Suche und
Details mit HTTP 200 validiert. Die Adressresponse erfüllt alle von HiveGrid konsumierten Felder, weicht
aber in fünf ungenutzten Nullable-Feldern von der Tenant-OpenAPI ab. Deshalb ersetzt eine enge
Zod-Projektion die falsche Vollobjekt-Pause im Importpfad. Der neue Katalog verwendet
`LoadProjekteNachFilter` ausschließlich als einstellungsabhängige Discovery, reichert asynchron an und
ergänzt sich durch jede gezielte Suche. Vier neue DoD sind offen; die zehn bereits abgenommenen
Import-/Ownership-/Sync-DoD bleiben erfüllt. **VR-P32d: 10/14 DoD = ~71 % done · 4 Punkte selbst machbar ·
In Progress.**
**CR-006 Implementierungsnachweis 2026-07-24:** Die konsumierten Search-, Projekt- und
Adressprojektionen ignorieren ungenutzte Nullable-Abweichungen und halten tatsächlich konsumierte Typen
weiterhin fail-closed; Adapterrevision `kwp-project-v5` kann einen gleich gebliebenen Vertrag
revisionssicher entsperren. `KwpProjectCatalogState` und `KwpProjectCatalogItem` speichern ausschließlich
normalisierte, erlaubte Projektfelder tenant-/connectiongebunden unter erzwungenem RLS. Die
Maintenance-Planung startet aktive Verbindungen automatisch, die Import-Queue hydratisiert höchstens 20
Projekte pro Lauf unter dem gemeinsamen 50-Requests/Minute-Budget und setzt große Bestände per verzögerter
Continuation fort. Die Import-Suche arbeitet cache-first über den trigram-indizierten Suchtext und ergänzt
gezielt read-through, ohne `Search("")`; der Screen zeigt Katalogstatus und Fortschritt ohne überlappende
Controls. Atomare Commits: `5a95c2363`, `4aed86dff`, `61d3b0a2c`, `b304bb4b0`, `a65de8685`,
`40d6be07c`, `8e564dc91`, `437fd4422`. Lokaler Proof: Root **1.029 Dateien / 7.404 Tests bestanden,
55 übersprungen**, Integrationspaket **328/328**, Queue **131/131**, Worker-Einstieg **65/65**,
View-Models **586/586**, KWP-Route-/Visualtests, Typecheck, Lint, i18n, Tenant-Policy **301/301**,
RLS-Readiness **299/299 Modelle und 254/254 Policies**, Migration-Parity, CI-Baseline, Source-Health,
Coverage, Hot-Swap und Produktions-Build grün. `prisma migrate status` war lokal nur wegen des nicht
laufenden wegwerfbaren PostgreSQL-Dienstes auf Port 5434 nicht erreichbar; Schema-Validierung und die
reproduzierbare Migrations-Parität sind grün. Es wurde kein Realprojekt importiert und keine
KWP-Schreiboperation ausgeführt. `VD-P32` bleibt als `design-nachzug` offen; `VN-2` bleibt der kontrollierte
Live-Geerkens-E2E. **VR-P32d: 14/14 DoD = 100 % done · 0 Punkte offen.**
**Details-Interaktions-Hotfix 2026-07-24:** Die redigierte Staging-Diagnose bestätigte eine aktive
Projekt-Capability auf Adapterrevision `kwp-project-v5`, ausschließlich gelöste ältere Drift-Reports und
erfolgreich zwischengespeicherte Projektdetails. Der Klick erreichte damit bereits den read-only
Detailpfad; die Vorschau wurde jedoch ohne unmittelbaren Ladezustand unter der vollständigen Trefferliste
gerendert und wirkte dadurch wie eine wirkungslose Aktion. Commit `7a59116e1` zeigt den gewählten Treffer
sofort als „Details werden geladen“, verhindert parallele Auswahlaktionen und scrollt erst nach der
erfolgreichen Antwort zur eindeutig markierten Vorschau. Der neue Interaktionstest deckt Aktion,
Zwischenzustand und Scroll-Ziel ab; der Interim-Visual-Snapshot wurde nachgezogen. Proof: **12/12**
betroffene KWP-Tests, Root **1.030 Dateien / 7.405 Tests bestanden, 55 übersprungen**, Typecheck, Lint,
i18n, CI-Baseline, Source-Health, Coverage, Hot-Swap und Produktions-Build grün. Es wurde kein
Realprojekt importiert und keine KWP-Schreiboperation ausgeführt. `VD-P32` bleibt als
`design-nachzug` offen; `VN-2` bleibt der kontrollierte Live-Geerkens-E2E.
**VR-P32d: 14/14 DoD = 100 % done · 0 Punkte offen.**
**Background-Queue-Hotfix 2026-07-24:** Die Post-Deploy-Kontrolle fand trotz 48 durch gezielte
Suchen gespeicherter Katalogeinträge noch keinen automatischen `KwpProjectCatalogState`. Der
Maintenance-Scheduler plante KWP-Jobs korrekt, aber der Staging-Import-Worker konsumierte im aktiven
Portal-/GDPR-Modus ausschließlich `hivegrid.exports`; die gemeinsam verwendete generische
`hivegrid.imports`-Queue blieb absichtlich gegatet. Commit `f0398f1d9` isoliert deshalb alle
KWP-Projekt-, Katalog-, Contract- und Archivjobs auf `hivegrid.kwp-imports`. Der Import-Worker besitzt
diese Queue in jedem gültigen Gate-Modus; generische Dateiimporte und Exporte bleiben unabhängig
fail-closed. Vor dem Rollout erzeugte KWP-Jobs auf der alten Queue bleiben replaybar. Startup prüft alle
KWP-Services fail-closed. Lokaler Proof: fokussierte Queue-/Worker-Suite **390/390**, Root-Testlauf
**1.030 Dateien / 7.409 Tests bestanden, 55 übersprungen**, Paket-Tests, Typecheck, Lint,
Import-Boundary, CI-Baseline **35/35**, Source-Health und Produktions-Build grün. Es wurde kein
Realprojekt importiert und keine KWP-Schreiboperation ausgeführt. **VR-P32d: 14/14 DoD = 100 %
implementiert · Release-Proof offen · Plane bleibt bis grüner CI und Staging-Autosync in Progress.**
**Background-Queue Release-Proof 2026-07-24:** Die drei atomaren Commits `f0398f1d9`,
`9e55ff754` und `d24e8c6e6` liefen in PR `#242` auf dem exakten Head
`d24e8c6e65293fdacff2e68e547d5146e46b732b` durch CI-Run `11148` mit **11/11 grünen Jobs**.
Der PR wurde ausdrücklich ohne Squash als normaler Zwei-Parent-Merge
`ab0e84f0160dc6471e6a4ca3e6c4089d811a99cc` nach `main` übernommen. Deploy-Run `11149`
schloss für exakt diese Revision terminal grün ab; Staging-Migration, alle Kern- und abhängigen
Runtime-Healthchecks, Worker-Rollout, Portal-Domain-Controller, Signatur, Sentry-Markierung und
CDN-Purge waren erfolgreich.
Der secretsichere read-only Staging-Proof bestätigte alle fünf Worker auf dem Merge-SHA. Der
Import-Worker konsumierte im aktiven Portal-/GDPR-Modus `hivegrid.kwp-imports`; der regulär in Redis
registrierte 15-Minuten-Scheduler lief ohne manuellen Trigger und schloss eine Maintenance sowie zwei
dedizierte KWP-Jobs mit **0 Fehlern** ab. Der daraus entstandene lokale Katalog war `ready`: eine aktive
Connection, **51 aktive Katalogeinträge**, **6 aktive Capabilities**, kein Katalogfehler und **0 offene
KWP-Fehlerberichte**. Es wurde kein HiveGrid-Realprojekt importiert und keine KWP-Schreiboperation
ausgeführt. `VD-P32` bleibt als `design-nachzug` offen; der kontrollierte fachliche Geerkens-Live-E2E
bleibt ausschließlich in `VN-2`. **VR-P32d: 14/14 DoD = 100 % done · 0 Punkte offen.**
**Demand-Refresh-Impact 2026-07-31:** Projektkatalog, gezielte Suche, Details und laufende read-only
Reconciliation behalten ihre bestehenden Cache-, Routing-, Binding-, Sentinel- und 50-Requests/Minute-
Grenzen. Der gemeinsame Resource-Adapter erneuert den Access-Token nur noch direkt vor einem tatsächlich
fälligen Provider-Fenster; gleichzeitige Katalog-/Projektjobs verwenden denselben durable Token-Claim.
Import-Mapping, Ownership, Create/Link und die KWP-Mutationssperre bleiben unverändert.
**VR-P32d: 14/14 DoD = 100 % done · 0 Punkte offen.**
**Demand-Refresh-Live-Abschluss 2026-08-01:** Der gemeinsame Resource-Adapter aus `VR-P32a` bestand nach
PR `#312`, Deploy-Run `11609` und normalem OAuth-Reconnect **20/20** Demand-Rotationen und acht gesunde
Health-Sweeps. Projektkatalog, Vertragsprüfung und read-only Reconciliation können den technischen
Staging-Betrieb damit wieder nutzen; Mapping, Ownership, KWP-Mutationssperre und `VN-2`-Scope bleiben
unverändert. **VR-P32d: 14/14 DoD = 100 % done · 0 Punkte offen.**
**Shared-Request-Budget-Hotfix 2026-08-01:** Die anschließende Staging-Beobachtung zeigte keinen weiteren
Token- oder Connection-Fehler, aber eine lokale Budgetkollision: Katalog-, Contract- und Projektjobs
verbrauchten denselben 50-Requests/Minute-Sicherheitstopf; der bisherige Adapter warf beim ausgeschöpften
Topf sofort `rate_limit_exceeded` und ließ den Projektjob dadurch in die BullMQ-Retry-Kette laufen. Commit
`6e49701df` behält die 10-Request-Sicherheitsreserve unter KWP's 60er-Hard-Cap bei, bindet den durable
Redis-Zähler korrekt an die gemeinsame OAuth-Client-ID statt an einzelne Kundenkürzel und wartet bei lokaler
Erschöpfung bis `resetAt` plus 100 ms, bevor er atomar neu reserviert. Vor dem Reset findet kein Provider-I/O
statt; ein Redis-Ausfall bleibt fail-closed. Provider-429, Token-Claim, Mapping, Ownership und
Mutationssperre ändern sich nicht. Lokaler Proof: fokussierte KWP-/Worker-Suite **46/46**, vollständiges
Integrationspaket **416/416**, Root **1.160 Testdateien / 8.183 Tests bestanden / 60 übersprungen**,
Typecheck, Lint, CI-Baseline und Source-Health grün. Ein Test belegt zwei Verbindungen mit verschiedenen
Kundenkürzeln und derselben OAuth-Client-ID: Call 51 wartet ohne Provider-Aufruf und läuft nach dem Reset
erfolgreich weiter. **VR-P32d: 14/14 DoD = 100 % done · 0 Punkte offen · Release-/Staging-Proof offen.**
**Shared-Request-Budget Release- und Dauer-Proof 2026-08-01:** PR `#317` lief auf dem exakten Head
`69482e94bac69c594312a7056ad2d62b1cbf9088` in CI-Run `11624` mit **11/11 grünen Jobs** und wurde
ausdrücklich ohne Squash als normaler Zwei-Parent-Merge
`28b2c0258e3a0bd62f9287c12d117d9a6350f971` nach `main` übernommen. Staging-Deploy `11625` schloss
für exakt diese Revision am 01.08.2026 um **02:19:33 UTC** terminal grün ab; drei aufeinanderfolgende
Web-/API-Health- und Readiness-Proben meldeten denselben Merge-SHA. Nachfolgende Main-Rollouts behielten den
Fix; die am Ende öffentliche Revision `0141ad43bd52205a660425f673099d0a7ccfc961` enthält den Merge
nachweislich als Vorfahren.
Die secretsichere read-only Beobachtung von **02:24:48 bis 04:24:47 UTC** umfasste neun automatische
Health-Sweeps und neun KWP-Maintenance-Zyklen. Jeder Health-Sweep meldete `checked=1`, `unhealthy=0` und
null Tenant-Fehler; jeder Maintenance-Zyklus endete mit `failures=0`. Mindestens **29** protokollierte
Budget-Waits, darunter ein zweiter Wartezyklus bis **60,1 Sekunden**, liefen ohne lokalen
`rate_limit_exceeded` weiter. Mindestens **14** Demand-Refreshes endeten mit `outcome=refreshed`; es gab
keinen Claim-, Provider- oder Persistenzfehler. Am Ende blieb die Connection `active`, der Katalog `ready`
mit **102 aktiven Einträgen**, alle sechs Capabilities aktiv und die Zahl offener KWP-ErrorReports bei null.
Es wurde keine KWP-Mutation und kein manueller Realprojektimport ausgelöst. Die bestehende 20-Verzeichnisse-
Grenze des Archiv-Inbound-Readers erzeugte getrennt drei terminale `KwpInboundLimitError`-Jobs; sie änderte
weder Budget-, Token- noch Connectionstatus und gehört nicht in diesen Hotfix.
**VR-P32d: 14/14 DoD = 100 % done · 0 Punkte offen.**