# 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`.