133 lines
6.8 KiB
Markdown
133 lines
6.8 KiB
Markdown
<!-- status: done -->
|
|
<!-- started: 2026-04-29 -->
|
|
<!-- completed: 2026-04-29 -->
|
|
<!-- component: gateway -->
|
|
<!-- lastReviewed: 2026-04-29 -->
|
|
<!-- verifiedAgainst: gateway/modules/interfaces/interfaceBootstrap.py @ HEAD, audit dev 2026-04-29 -->
|
|
|
|
# Bootstrap-Migrations-Cleanup (idempotente Boot-Routinen)
|
|
|
|
## Beschreibung und Kontext
|
|
|
|
Beim App-Start liefen 5 idempotente "Self-Heal"- und "Backfill"-Routinen mit, die
|
|
historisch noetig waren, um produktive DBs nachtraeglich auf neue Schemata zu
|
|
heben (Mandate-Label-Logik, Slug-Regeln, Legacy-Root-Mandate, sysadmin-Split,
|
|
RAG-Bytes-Aggregation). Auf modernen DBs sind sie No-Ops und haben pro Boot
|
|
Tabellen-Scans gekostet plus den Lifespan-Pfad unleserlich gemacht.
|
|
|
|
**Resultat:** alle 5 Routinen aus dem Boot-Pfad entfernt, Tests fuer entfernte
|
|
Routinen geloescht, ein leichter Telemetrie-Helper (`runLegacyDataChecks`)
|
|
warnt im Boot-Log falls je doch noch Restbestand auftauchen sollte.
|
|
|
|
## Was wurde gemacht (chronologisch)
|
|
|
|
1. **Verifikation pro Kandidat** -- Code-Pfade in
|
|
`gateway/modules/interfaces/interfaceBootstrap.py` und
|
|
`gateway/modules/interfaces/interfaceDbKnowledge.py` neu vermessen.
|
|
Ergebnis: Plan-Annahmen waren teils ungenau (Pfad `system/` statt
|
|
`interfaces/`, ganze Funktionen statt einzelner Bloecke); Plan-Tabelle in
|
|
`1-plan/` korrigiert vor Removal.
|
|
2. **Audit-Skript** `gateway/scripts/script_db_audit_legacy_state.py` (NEU)
|
|
- Lese-only fuer 4 Mandate-/Role-Checks (App-DB) + 1 RAG-Check (Knowledge-DB).
|
|
- Optional `--purge-rag-orphans` Flag fuer den einzigen Daten-Cleanup.
|
|
- Exit-Code 0=GREEN / 1=RED / 2=ERROR fuer CI-Gating.
|
|
- JSON-Output-Modus.
|
|
3. **Audit-Lauf gegen Dev-DB:**
|
|
- 4 Checks GREEN sofort.
|
|
- 1 Check RED: 20 `FileContentIndex`-Rows ohne `mandateId`+`featureInstanceId`
|
|
(alte Test-Datei-Reste).
|
|
4. **Purge der 20 RAG-Orphans** via `--purge-rag-orphans`. Re-Audit: 5/5 GREEN.
|
|
5. **Telemetrie-Helper** `gateway/modules/interfaces/_legacyMigrationTelemetry.py`
|
|
(NEU) -- 4 nicht-blockierende SELECT-Checks (gleiche Logik wie Audit-Skript),
|
|
prozessweit gecached, Aufruf am Ende von `initBootstrap`. WARN-Log bei Restbestand.
|
|
6. **Code-Removals** in `gateway/modules/interfaces/interfaceBootstrap.py`:
|
|
- `_migrateMandateDescriptionToLabel` (Funktion + Aufruf) -- weg.
|
|
- `_migrateMandateNameLabelSlugRules` (Funktion + Aufruf) -- weg.
|
|
- `initRootMandate` Legacy-Block (`recordFilter={"name":"Root"}` + recordModify) -- weg.
|
|
Funktion `initRootMandate` selbst bleibt (legt Root-Mandat an wenn fehlt).
|
|
- `_migrateAndDropSysAdminRole` (Funktion + Aufruf) -- weg.
|
|
- `aggregateMandateRagTotalBytes` Fallback `try`/`except`-Block (Z. 606-635) --
|
|
weg. Funktion bleibt aktiv (4 Caller).
|
|
7. **Test-Cleanup** -- folgende Test-Files geloescht (referenzierten entfernte
|
|
Funktionen, wuerden ImportError werfen):
|
|
- `gateway/tests/unit/bootstrap/test_mandateNameMigration.py` (8 Tests)
|
|
- `gateway/tests/unit/rbac/test_sysadmin_migration.py` (5 Tests)
|
|
- Verzeichnis `gateway/tests/unit/bootstrap/` ist jetzt leer und entfernt.
|
|
8. **Smoke-Tests:** `python -m pytest tests/unit/rbac` -- 17/17 GREEN.
|
|
Import-Smoke fuer alle 3 geaenderten Module GREEN.
|
|
9. **Telemetrie-Aufruf** in `initBootstrap` als letzten Schritt nach
|
|
`_bootstrapBilling()`. Try/Except umschlossen damit Telemetrie nie
|
|
den Boot crashed.
|
|
|
|
## Geaenderte Dateien
|
|
|
|
| Datei | Aenderung |
|
|
|-------|----------|
|
|
| `gateway/modules/interfaces/interfaceBootstrap.py` | -3 Funktionen (~120 Zeilen), -3 Aufrufe, +6 Zeilen Telemetrie-Hook |
|
|
| `gateway/modules/interfaces/interfaceDbKnowledge.py` | -27 Zeilen Fallback-Block, vereinfachtes Log-Format |
|
|
| `gateway/modules/interfaces/_legacyMigrationTelemetry.py` | NEU (~145 Zeilen) |
|
|
| `gateway/scripts/script_db_audit_legacy_state.py` | NEU (~290 Zeilen) |
|
|
| `gateway/tests/unit/bootstrap/test_mandateNameMigration.py` | GELOESCHT |
|
|
| `gateway/tests/unit/rbac/test_sysadmin_migration.py` | GELOESCHT |
|
|
|
|
## Audit-Befund (Dev-DB, 2026-04-29 19:50)
|
|
|
|
| # | Check | Ergebnis nach Purge |
|
|
|---|-------|---------------------|
|
|
| 1 | mandate-description-to-label | GREEN (0) |
|
|
| 2 | mandate-name-slug-rules | GREEN (0) |
|
|
| 3 | root-mandate-legacy | GREEN (0) |
|
|
| 4 | sysadmin-role | GREEN (0) |
|
|
| 5 | rag-fallback-orphan-index | GREEN (0, nach Purge von 20 Test-Resten) |
|
|
|
|
## Operative Hinweise fuer Int + Prod
|
|
|
|
User-Statement (2026-04-29): "die codebase lief bereits auf int und main/prod" --
|
|
d.h. die idempotenten Migrations sind dort schon mehrfach durchgelaufen, das
|
|
Removal-Risiko = 0. Trotzdem empfohlen vor dem Deploy:
|
|
|
|
```pwsh
|
|
# (1) Audit lesend laufen lassen -- ohne Aenderung
|
|
python -m scripts.script_db_audit_legacy_state
|
|
|
|
# (2) Falls Check 5 RED (RAG-Orphans): purgen
|
|
python -m scripts.script_db_audit_legacy_state --purge-rag-orphans
|
|
```
|
|
|
|
Falls trotzdem Restbestand auftauchen sollte (alter DB-Restore o.ae.), feuert
|
|
nach dem Boot der Telemetrie-Helper eine WARN-Logzeile pro betroffenem Check
|
|
mit Routine-Name + IDs. Dann manuell mit dem Audit-Skript untersuchen.
|
|
|
|
## Folgearbeiten
|
|
|
|
- **Scripts-Cleanup -- erledigt 2026-04-29:** 5 one-shot-Scripts in
|
|
`gateway/scripts/_archive/` mit README, `_listMandates.py` geloescht.
|
|
Aktiv-Bestand: 21 Scripts inkl. dem neuen `script_db_audit_legacy_state.py`.
|
|
- **Telemetrie-Lebenszyklus:** in 30+ Tagen pruefen ob Telemetrie-Helper
|
|
Treffer hatte. Wenn 0, `_legacyMigrationTelemetry.py` komplett entfernen.
|
|
|
|
## Script-Archiv-Inhalt (2026-04-29)
|
|
|
|
| Datei | Migrationsthema | Begruendung |
|
|
|-------|-----------------|-------------|
|
|
| `check_orphan_featureinstance.py` | Vor-Ort-Check mit hardcoded UUIDs | Ad-hoc fuer einen konkreten Vorfall |
|
|
| `script_db_cleanup_duplicate_roles.py` | Cleanup doppelter Roles wegen IS-NULL-Bug | Bug laengst gefixt, Cleanup durchgelaufen |
|
|
| `migrate_async_to_sync.py` | One-shot Codemod `async def` -> `def` | Refactor abgeschlossen |
|
|
| `i18n_rekey_plaintext_keys.py` | Frontend Dot-Notation -> Klartext-Keys | Migration durch (`4-done/2026-04-ui-i18n-dynamic-language-sets.md`) |
|
|
| `script_db_migrate_accessrules_objectkeys.py` | AccessRule-Items kurz -> qualifiziert | Navigation-API live |
|
|
|
|
## Akzeptanzkriterien
|
|
|
|
| # | Kriterium | Status |
|
|
|---|-----------|--------|
|
|
| 1 | Audit-Skript laeuft Lese-only und liefert Exit-Code 0 wenn alle Checks GREEN | erfuellt |
|
|
| 2 | Boot mit entfernten Routinen startet ohne Fehler, Telemetrie-Hook laeuft am Ende | erfuellt (Smoke-Test gruen) |
|
|
| 3 | Telemetrie-Helper feuert klare WARN-Zeile bei Restbestand | erfuellt (Code-Pfad da, nicht ausgeloest da Dev GREEN) |
|
|
| 4 | Tests fuer entfernte Funktionen sind weg, restliche Tests laufen | erfuellt (17/17 rbac+bootstrap green) |
|
|
|
|
## Links
|
|
|
|
- Audit-Skript: `gateway/scripts/script_db_audit_legacy_state.py`
|
|
- Telemetrie: `gateway/modules/interfaces/_legacyMigrationTelemetry.py`
|
|
- Verwandte Done-Plans: `wiki/c-work/4-done/2026-04-mandate-name-label-logic.md`,
|
|
`wiki/c-work/4-done/2026-04-sysadmin-authority-split.md`.
|