395 lines
32 KiB
Markdown
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.**
|