Refresh HiveGrid Cloud reference snapshot

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

No files matched your search

@@ -0,0 +1,145 @@
# DB-BASELINE · Prisma-Migrationshistorie konsolidieren
| | |
|---|---|
| **Typ** | Dev/Infra |
| **Owner** | Raffael |
| **Phase** | Querschnitt / Datenbankbetrieb |
| **Cycle/Fenster** | Sofortiger Wartungsschnitt |
| **Status** | Done |
## Abhängigkeiten & Parallelität
- **Blocked by:** keine. Der vollständige Main-Migrationsstand muss vor dem Schnitt reproduzierbar und schema-paritätisch sein.
- **Blocks:** keine fachlichen Tickets. Während des PRs gilt jedoch ein operativer Schema-Freeze; parallele Schema-Branches müssen nach dem Merge auf die Baseline rebasen und ihre Merge-Migration neu erzeugen.
- **Plane-Prüfung:** Beide Richtungen wurden am 2026-07-22 gelesen. Es gibt keine bestehende `blocked-by`-/`blocks`-Relation für diesen Wartungsschnitt.
- **Auswirkung auf Abhängige:** Keine Prisma-Modelle und keine Fachverträge ändern sich. Geändert werden ausschließlich die aktive Migrationshistorie, ihr Deploy-Cutover und die zugehörigen Verifikationsverträge.
## Was wir bauen
Die historische Prisma-Migrationskette wird in eine einzelne, aus einer leeren PostgreSQL-Datenbank reproduzierbare
HiveGrid-Baseline überführt. Die Baseline bildet nicht nur das deklarative Prisma-Schema ab, sondern auch alle
PostgreSQL-spezifischen Laufzeitverträge wie RLS-Policies, Security-Definer-Funktionen, Rollen-Grants, Extensions,
partielle Indizes und Constraints.
Bestehende Datenbanken übernehmen die neue Baseline genau einmal über `prisma migrate resolve --applied`, nachdem
ein fail-closed Check die vollständig angewendete Legacy-Historie einschließlich Checksums bestätigt hat. Frische
Datenbanken dürfen die Baseline nicht überspringen und wenden sie regulär mit `prisma migrate deploy` an.
## Benötigte Screens
Keine UI-Arbeit.
## Definition of Done
- [x] Eine einzelne Baseline-Migration stellt den aktuellen Main-Datenbankzustand aus einer leeren PostgreSQL-16-Datenbank her.
- [x] Prisma-Schema, RLS-Policies, Security-Definer-Funktionen, Grants, Extensions, Constraints und Indizes entsprechen katalogseitig dem Endzustand der bisherigen vollständigen Migrationskette.
- [x] Ein versioniertes Legacy-Manifest erfasst alle ersetzten Migrationen mit SHA-256-Checksum; die aktive Legacy-Kette ist aus `prisma/migrations/` entfernt und bleibt über ein checksum-verifiziertes Audit-Archiv sowie Git rekonstruierbar.
- [x] Der One-shot-Migrator übernimmt die Baseline nur bei einer vollständig erfolgreichen kanonischen Legacy-Historie oder bei Git-belegten historischen Checksums mit zusätzlicher Live-Schema-/Katalogparität; frische, bereits baselinierte, partielle oder unbekannt abweichende Datenbanken werden korrekt behandelt beziehungsweise fail-closed abgewiesen.
- [x] Der bestehende Migrator-Rollen-, Secret- und Runtime-Env-Vertrag bleibt unverändert scharf; Staging und Produktion verwenden weiterhin den kurzlebigen `DIRECT_URL`-Migrator vor jedem Rollout.
- [x] Automatisierte Tests decken Fresh-DB, Legacy-Adoption, wiederholten No-op, partielle/abweichende Historie und den vollständigen Alt-vs.-Baseline-Katalogvergleich ab.
- [x] `prisma validate`, Migrations-Parity, Tenant-Policy-Contract, RLS-Release-Readiness, strikter RLS-Live-Test, Docker-/Deploy-Verträge sowie die allgemeine Commit-/Push-Checkliste sind grün.
- [x] Rollback, Merge-Reihenfolge und der einmalige Staging-/Produktions-Cutover sind dokumentiert; PRs #215 und #218 sind nach gemeinsamem Sign-off mit grüner CI gemergt und die Staging-Adoption ist grün.
**Fortschritt:** `DB-BASELINE`: 8/8 DoD = 100 % done. Offen: 0 Punkte.
## Technische Bausteine
- `prisma/migrations/00000000000000_hivegrid_baseline/migration.sql`
- Legacy-Migrationsmanifest unter `prisma/`
- Fail-closed Adoption vor `prisma migrate deploy` im bestehenden One-shot-Migrator
- Unit-Tests für die History-Klassifikation und den Prisma-CLI-Aufruf
- Docker-basierter Alt-vs.-Baseline-Replay mit normalisiertem PostgreSQL-Katalogvergleich
- Anpassung der RLS-Generator-/Freeze-Verträge auf die neue Baseline
## Rollback-Pfad
- **Vor Merge:** Branch/PR verwerfen; produktive Datenbanken bleiben unverändert.
- **Nach Merge, vor Baseline-Adoption:** Merge-Commit revertieren und die Legacy-Migrationsordner aus Git wiederherstellen.
- **Nach erfolgreicher Adoption:** Keine DDL wird durch die Adoption ausgeführt. Bei einem Code-Rollback werden die Legacy-Migrationsordner wiederhergestellt; der zusätzliche erfolgreiche Baseline-Eintrag kann bestehen bleiben, solange kein Legacy-Image erneut `migrate deploy` ausführt. Der konkrete Rollback wird zuerst in Staging geprobt.
- **Nach Anwendung auf einer frischen Datenbank:** Datenbank verwerfen und aus Backup/Seed neu aufbauen. Die Baseline ist forward-only; ein produktives `DROP SCHEMA` ist kein zulässiger Rollback.
## Quellen
- `AGENTS.md` §Prisma-Schema & Migrationen, §RLS, §Ticket-Treue
- `docs/AGENT-CHECKLIST.md`
- `docs/deployment.md` §One-shot-Migrator
- `docs/security/RLS-HARDENING-2026-07-13.md`
- `infra/LESSONS.md` §9
- Prisma-Dokumentation: Baselining und Squashing migrations
## Umsetzungsnotiz
2026-07-22: Ticket als eigenständiger, fachmodell-neutraler Wartungsschnitt angelegt. Ausgangs-Pre-Flight auf
`origin/main` ist grün (`pnpm typecheck`; `pnpm test`: 999 Testdateien, 7.135 Tests bestanden). Der aktuelle
Main-Stand enthält 195 aktive Migrationen mit 42.140 SQL-Zeilen. Die Implementierung erfolgt isoliert auf
`chore/prisma-baseline-20260722`.
2026-07-22: Die 195 Legacy-Migrationen wurden durch
`00000000000000_hivegrid_baseline` ersetzt. Die Baseline enthält 293 Tabellen, 844 Policies, 92 Funktionen,
293 `ENABLE ROW LEVEL SECURITY`, 293 `FORCE ROW LEVEL SECURITY`, 2 Extensions sowie die migrations-eigenen
SHK-Onboarding- und Customer-Portal-Feature-Flag-Referenzdaten. Baseline-SHA-256:
`f39a3e6800356d3199b1274a492721217c12c0c5cafcf3f648b3050868c3abbe`. Das versionierte Audit-Archiv
`prisma/baseline-legacy-migrations.tar.gz` hat SHA-256
`0571766bcd2bc7d4424706617ad9a495c2b11d6b3e8f9511510dc710716d6093`; sein Manifest pinnt alle 195
Migrationen einzeln.
Proof: Fresh-DB-Deploy, checksum-verifizierte Legacy-Adoption, wiederholter No-op und der vollständige
PostgreSQL-Katalog- und Referenzdatenvergleich sind grün. `prisma validate`, Migrations-Parity,
Tenant-Policy-Contract (293/293), RLS-Release-Readiness (246/246), strikter RLS-Live-Test,
Docker-Baseline (399 Checks), Docker-Non-Root, Deploy-/CI-/Source-/Doku-Verträge, Typecheck und Lint sind grün.
Core-Tests: 1.001 Testdateien / 7.155 Tests bestanden; `@hivegrid/db`: 94 Testdateien / 854 Tests bestanden.
Rollback, Merge-Reihenfolge und Cutover sind in `docs/ops/prisma-baseline.md` dokumentiert. Lokal sind 7/8
DoD erfüllt; offen bleibt ausschließlich PR plus grüne Remote-CI vor dem gemeinsamen Merge-Sign-off.
2026-07-22: PR [#215](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/pulls/215) gegen `main` ist
eröffnet. Die Remote-CI für Implementierungs-Commit `66b1b1b68` ist mit 13/13 Checks grün, einschließlich
Database Checks mit Baseline-Äquivalenz und Live-RLS sowie Docker Smoke, Typecheck/Tests, Coverage und
Build/Bundle. Damit sind 8/8 DoD erfüllt. Der PR bleibt bis zum gemeinsamen Sign-off ungemergt.
2026-07-22: PR #215 wurde nach erneut grüner CI als Squash nach `main` gemergt. Der erste Staging-Deploy
stoppte erwartungsgemäß vor `migrate resolve` und vor jeder Datenbankmutation, weil die bestehende
Staging-Historie mindestens eine früher deployte, später im Git geänderte Migration mit ihrer damaligen
Prüfsumme enthält. Der Hotfix auf `fix/prisma-baseline-staging-adoption-20260722` pinnt alle zehn im
Git belegten historischen Prüfsummenvarianten samt Quellcommit. Eine solche Variante wird nur übernommen,
wenn ein Live-`prisma migrate diff` keine Schemaabweichung findet und die zusätzlichen PostgreSQL-
Katalogverträge für Audit-FKs, tenant-gebundenes Booking sowie Security-Definer-Owner/ACLs grün sind.
Lokaler Proof des Hotfixes: Der vollständige Äquivalenzlauf spielte alle 195 Migrationen ein, simulierte
alle acht betroffenen Migrationen mit den zehn historischen Ledger-Checksums und bestätigte danach
Adoption, wiederholten No-op sowie vollständige Katalog- und Referenzdatenäquivalenz. Zusätzlich grün:
`prisma validate`, Migrations-Parity, Tenant-Policy-Contract (293/293), RLS-Release-Readiness (246/246),
strikter RLS-Live-Test, Docker-/Deploy-/CI-/Source-/Doku-Verträge, Typecheck, Lint sowie 1.017 Testdateien
mit 7.341 bestandenen Tests. `DB-BASELINE`: 8/8 DoD = 100 % done; operativ offen ist nur der erneute
Remote-CI- und Staging-Deploy-Nachweis vor dem Ticketabschluss.
2026-07-22: Im ersten Lauf von Hotfix-PR #218 stoppte ausschließlich der SHK-Migrationsfixture, weil der
parallele Runner-Cold-Start von PostgreSQL das alte 30-Sekunden-Fenster überschritt; der Container war laut
Runner-Log unmittelbar danach gesund. Der Fixture nutzt nun wie der benachbarte Identity-/Invite-Check einen
auf 90 Sekunden begrenzten TCP-`pg_isready`-Probe. Der neue statische Vertragstest und der reale lokale
SHK-Clean-/Legacy-Upgrade-Lauf (9/9 Tests) sind grün. Es gab keine Datenbank- oder Anwendungsänderung.
2026-07-22: Hotfix-PR [#218](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/pulls/218) wurde mit
Merge-Commit `ce748f10b` nach `main` übernommen. Der exakt rebasierte PR-Head `bfbae1b98` bestand CI-Run
[11057](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/11057) mit 11/11 grünen Checks.
Der erste Post-Merge-Lauf übernahm die Baseline auf Staging nach Prüfung von drei Git-belegten historischen
Checksum-Varianten sowie Live-Schema- und sicherheitskritischer Katalogparität; anschließend meldete Prisma
keine ausstehenden Migrationen. Ein nachgelagerter, transienter Controller-Pre-Stop-Health-Probe brach den
Rollout sicher ab und stellte den vorherigen Release wieder her. Der idempotente Deploy-Re-Run
[11058, Job 46077](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/11058/jobs/46077)
erkannte die bereits verbuchte Baseline, bestätigte erneut keine ausstehenden Migrationen und rollte alle
Staging-Ressourcen einschließlich des revisionsgebundenen Portal-Domain-Controllers erfolgreich aus.
`DB-BASELINE`: 8/8 DoD = 100 % done; 0 Punkte offen.
2026-07-23: Die erste Forward-Migration nach der konsolidierten Baseline (`kwp_project_inbound`) hat einen
Reihenfolgefehler im One-shot-Migrator sichtbar gemacht: Ein Vergleich der bestehenden Legacy-Datenbank mit
dem aktuellen Prisma-Schema muss die noch nicht angewandte Forward-Migration zwangsläufig als Drift melden.
Der fail-closed Ablauf ist deshalb jetzt explizit `Rollen-Probe → Legacy-Historie und
sicherheitskritische Varianten-Kataloge prüfen → Baseline übernehmen → prisma migrate deploy → aktuelles
Live-Schema prüfen → Permission-Katalog synchronisieren`. Unbekannte Legacy-Checksums und abweichende
sicherheitskritische Kataloge stoppen weiterhin vor jeder Adoption; eine Abweichung vom aktuellen
Prisma-Schema stoppt nach den atomaren Forward-Migrationen und vor Permission-Sync beziehungsweise Rollout.
Der vollständige Docker-Nachweis spielte alle 195 Legacy-Migrationen ein, simulierte die acht historischen
Checksum-Varianten, adoptierte die Baseline, wandte `kwp_project_inbound` an und bestätigte anschließend
`No difference detected`; Fresh-DB und Legacy-DB blieben vollständig katalogäquivalent. Die Änderung betrifft
keine Prisma-Modelle oder Fachverträge. `DB-BASELINE`: 8/8 DoD = 100 % done; 0 Punkte offen.