bin/docs/superpowers/plans/2026-07-20-ausbaustufe-4.md

Ausbaustufe 4 — Backup, Admin-Seite mit Passwortänderung, Grafana-Lücken, Architektur-Doku

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development. Fable-Testagent als Gate je Task (Nutzer-Vorgabe). Checkbox-Tracking.

Goal: Kalt-Backup-Skript; Admin-Seite (Passwortänderung vollintegriert + Regeln-neu-anwenden); durchgehende Grafana-Kontostandslinien; Architektur-Doku (Mermaid) + CLAUDE.md für künftige Sessions. Version 0.5.0.

Nutzerentscheidungen (2026-07-20): Backup kalt (Pod-Stopp) nach ~/backups/ (Zielverzeichnis als Argument überschreibbar); Passwortänderung vollintegriert (.env in Container gemountet, Laufzeit-Lesen, Grafana per HTTP-API); Admin-Zusatzfunktion NUR „Regeln neu anwenden".

Global Constraints

• Wie Ausbaustufe 3 (Decimal, Deutsch, Suite grün — Basis 132, Trailer, DATENSCHUTZ, UX-Regel sichtbar/disabled, Fable-Testagent-Gate je Task). Deployment gesammelt am Ende (Task 5).
• Backup-Datei enthält Secrets (.env) → chmod 600.
• KRITISCH (.env im Container): Bind-Mount einer EINZELDATEI folgt dem Inode — die App muss die Datei IN-PLACE beschreiben (open r+/truncate, flock), NIEMALS über Temp-Datei+rename. Host-Skript-seitige sed-Edits erzeugen neue Inodes — unkritisch, weil das Skript die Container ohnehin neu erstellt.

Task 1: Backup-Skript

Files: Create backup_finance_pod.sh (Repo-Root, ausführbar). Interface: ./backup_finance_pod.sh [ZIELDIR] (Default $HOME/backups): systemctl --user stop pod-finance_pod.service → tar czf ZIELDIR/finance_pod_$(date +%F_%H%M).tar.gz -C ~/.local/share finance_pod → start → Readiness-Curl /login → tar -tzf-Integritätscheck (muss .env und postgres-data enthalten) → chmod 600 → Ausgabe Pfad+Größe. Bei jedem Fehler: Service wieder starten (trap), Exit ≠ 0.

• Skript schreiben, bash -n · [ ] FABLE-TESTAGENT: Skript LIVE ausführen (kurze Downtime ok), prüfen: Service danach active, Login 200, Archiv 600 + enthält .env/postgres-data/grafana-data/data, Restore-Probe NUR als tar-Listing (kein Zurückspielen); Fehlerpfad: Skript mit unbeschreibbarem Ziel → Service läuft trotzdem weiter · [ ] Commit feat: Kalt-Backup-Skript finance_pod

Task 2: Admin-Seite (Passwortänderung + Regeln-Anwenden)

Files: Modify create_pod_finance.sh (Mount -v "$ENV_FILE:/data/.env:Z" am API-Container; Kommentar Inode-Regel), finance/app/config.py (+env_file: Path aus FB_ENV_FILE, Default /data/.env), finance/app/auth.py (Hash-Lookup zur Laufzeit: existiert env_file → Werte daraus parsen (single-quoted), sonst Fallback env; kleine Helferfunktion mit mtime-Cache), Create finance/app/services/admin.py (change_password(old, new): verify old → Grafana PUT http://localhost:3000/api/admin/users/1/password Basic-Auth admin:old → .env IN-PLACE (flock, FB_PASSWORD+FB_GUI_PASSWORD_HASH single-quoted ersetzen) → bei Grafana-Fehler abbrechen ohne .env-Änderung; apply_rules_retroactively(session) -> int auf unkategorisierte confirmed), Create finance/app/routers/admin.py (GUI GET /admin [gui_session] + POST /admin/passwort [gui_session, Form alt/neu/neu2, neu ≥ 8 Zeichen] + API POST /api/category-rules/apply [require_auth]), Templates admin.html + Nav „Admin", Tests. Semantik: Session-Cookies bleiben nach Änderung gültig (Secret unverändert — dokumentieren). Meldungen Deutsch. In Tests env_file → tmp_path (FB_ENV_FILE), Grafana-Call gemockt (monkeypatch), In-Place-Schreiben per Inode-Vergleich getestet.

• TDD · [ ] FABLE-TESTAGENT (Suite; Inode-Konstanz beim Schreiben; Mock-Grafana-Reihenfolge: kein .env-Write bei Grafana-Fehler; /admin-Auth; apply-Endpoint zählt korrekt) · [ ] Commit feat: Admin-Seite mit Passwortaenderung und Regel-Neuanwendung

Task 3: Grafana durchgehende Linien

Files: Modify finance/app/models/views.py (v_balance_history/v_balance_total: tägliche Reihe via generate_series(min(start), CURRENT_DATE, '1 day') je Konto mit Carry-Forward des ankerbasierten Saldos — keine NULL-Lücken mehr), finance/grafana/dashboards/finanzen.json (Panels 1+2: lineInterpolation: "stepAfter", spanNulls: true).

• Implementieren (SQL Postgres-only wie bisher) · [ ] FABLE-TESTAGENT: Wegwerf-DB auf finance-db_ctr (Muster A3-T1): synthetische Daten mit mehrtägigen Buchungslücken → Views liefern JEDEN Tag genau eine Zeile je Konto, Werte = Handrechnung, keine Lücken; finanzen.json parsebar + Optionen gesetzt; Suite grün · [ ] Commit fix: lueckenlose taegliche Saldo-Reihen fuer Grafana

Task 4: Architektur-Doku + CLAUDE.md

Files: Create docs/ARCHITEKTUR.md (Mermaid: (1) Komponenten-Diagramm Module→Funktionen: parsers [base/detect/validate/vr/hvb/dkb/csv_formats/registry], engine [loans/recurrence/projection/scenario], services [importer/balances/categorize/suggestions/projection_service/admin], routers [accounts/transactions/categories/imports/planning/scenarios/gui/admin], templates/Seiten, models+views, alembic; (2) Datenfluss-Sequenz Import CSV/PDF→Draft→Confirm→Anker/Salden; (3) Deployment-Diagramm Pod/Container/Mounts/Ports/systemd/.env; je Knoten Stichwort-Funktionsliste), Create CLAUDE.md (Repo-Root ~/bin: Projektüberblick, Betriebs-/Testkommandos, DATENSCHUTZ-Regeln [fixtures = echte Daten!], Konventionen [Decimal, Deutsch, Fable-Test-Gate, Superpowers-Workflow, Plan-/Ledger-Orte, Versions-Prozess VERSION-Datei, Backup/DR], Verweis auf ARCHITEKTUR.md + docs/superpowers/plans/), Update Claude-Memory.

• Schreiben · [ ] FABLE-TESTAGENT: Faktencheck der Doku gegen den Code (jede benannte Datei/Funktion existiert; Mermaid-Syntax valide; keine echten Daten) · [ ] Commit docs: Architektur (Mermaid) und CLAUDE.md fuer kuenftige Sessions

Task 5: v0.5.0 + Redeploy + Smoke

• VERSION 0.5.0, Build, Redeploy · [ ] Smoke: Kernseiten inkl. /admin; Passwortänderung E2E LIVE (auf Temp-Passwort ändern → GUI+Grafana-Login mit Temp OK → zurück auf Original ändern → Original-Login OK); Regeln-Anwenden-Button; Grafana-Panel liefert tägliche Punkte (View-COUNT == Kalendertage) · [ ] Backup-Skript einmal final ausführen (frisches Backup nach Abschluss) · [ ] Plan-Häkchen, Ledger, Memory, Commit + PUSH beider Repos

Abschluss-Checkliste

• Suite grün (>= 140 erwartet); alle Fable-Gates dokumentiert
• Live v0.5.0: Passwort unverändert (nach E2E-Probe zurückrotiert), Admin-Seite funktional, Grafana-Linien durchgehend, Backup in ~/backups vorhanden (600)
• ARCHITEKTUR.md + CLAUDE.md committet; Memory aktuell; gepusht