PowerOn/wiki
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
wiki/c-work/4-done/2026-04-bootstrap-migrations-cleanup.md
ValueOn AG 6eeeb962f6 upd
2026-04-29 20:23:03 +02:00

6.3 KiB
Raw Blame History

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:

# (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 (separate Plans)

  • Scripts-Inventar: subagent hat 27 Files in gateway/scripts/ kategorisiert. Klar Archiv-Kandidaten (B): check_orphan_featureinstance.py (hardcoded UUIDs), script_db_cleanup_duplicate_roles.py (IS-NULL-Bug-Fix; Bug laengst gefixt). Unklar (C): _listMandates.py, migrate_async_to_sync.py, i18n_rekey_plaintext_keys.py, script_db_migrate_accessrules_objectkeys.py. Restliche 21 Files = AKTIV. Entscheidung pro File offen.
  • Telemetrie-Lebenszyklus: in 30+ Tagen pruefen ob Telemetrie-Helper Treffer hatte. Wenn 0, Helper komplett entfernen.

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.