# Design: Finanzberatungs-Umgebung & Finanzberatungs-Tool

Datum: 2026-07-17 · Status: vom Nutzer abgenommen

## Ziel

Eine finanziell schwierige Phase planbar machen: Kontobewegungen der nächsten
Zeit vorhersagen, Kreditbedarf (Zeitpunkt und Höhe) ermitteln und sinnvolle
Ausgabenkürzungen identifizieren. Dazu werden PDF-Kontoauszüge ausgewertet, in
einer Datenbank abgelegt und über Szenarien in die Zukunft gerechnet.

Das Vorhaben besteht aus zwei Repositories:

- **`~/fb`** (dieses Repo): die Claude-Code-Beratungsumgebung — CLAUDE.md,
  Projekt-Skills, Memory, Spezifikation und Plan. Kein Tool-Code.
- **`~/bin`**: das Finanzberatungs-Tool als rootless-Podman-Pod mit
  Web-GUI, API und Grafana.

## Rahmenbedingungen (geklärt)

- Kontoauszüge liegen als **PDF** vor, von **mehreren Konten bei mehreren
  Banken**: Volksbank/Raiffeisenbank, HypoVereinsbank, DKB.
- PDF-Verarbeitung durch **feste, deterministische Parser je Bank**
  (pdfplumber), keine KI-Abhängigkeit im Import.
- Import **immer mit Vorschau**: extrahierte Buchungen werden vor der
  Übernahme angezeigt und explizit bestätigt.
- Zugriff: Das Tool bindet nur an lokale Ports (**ab 8096**); externe
  Erreichbarkeit regelt der bestehende Traefik-Reverse-Proxy/VPN des
  Betreibers. Zusätzlich eigener Login-Schutz im Tool (siehe Sicherheit).
- Szenarien umfassen: wiederkehrende Posten, geplante Einmalposten,
  Kredit-Simulation, Sparpotenzial-Analyse (alle vier bestätigt).
- Architektur-Entscheidung: **Ansatz A, schlanker Pod** (drei Container),
  bewusst gegen feingranulare Microservices (B) und gegen Firefly III (C).

## Architektur

Podman Pod `finance_pod`, erstellt durch `~/bin/create_pod_finance.sh` exakt
nach dem Muster von `~/bin/example_create_pod_langflow.sh`:

- gepinnte, unveränderliche Image-Tags (kein `:latest`),
- Bind-Verzeichnisse unter `~/.local/share/finance_pod/` mit `:Z`-Flag,
- `podman generate systemd --new` + systemd-User-Service
  `pod-finance_pod.service` in `~/.config/systemd/user/`,
- Host-IP/Ports als Variablen am Skriptanfang.

| Container | Image | Port (Host → Container) |
|---|---|---|
| `finance-db_ctr` | `postgres:17.x` (gepinnt) | nur pod-intern (5432) |
| `finance-api_ctr` | eigenes Image aus `~/bin/finance/Containerfile` | `127.0.0.1:8096 → 8000` |
| `finance-grafana_ctr` | `grafana/grafana-oss` (gepinnt) | `127.0.0.1:8097 → 3000` |

Das Skript baut das API-Image vor dem Pod-Start per `podman build`.

Bind-Verzeichnisse: `postgres-data`, `grafana-data`, `inbox` (Import-Eingang,
auch vom Host direkt befüllbar), `uploads` (archivierte Original-PDFs).

### Sicherheit

- **Web-GUI:** Login-Seite mit Benutzername/Passwort, Session-Cookie.
  Passwort wird beim Setup gesetzt und nur als Hash gespeichert.
- **API:** statischer API-Schlüssel (langer Zufallswert), von Claude Code als
  `Authorization: Bearer`-Header mitgeschickt; Anfragen ohne gültigen
  Schlüssel werden abgelehnt.
- **Secrets:** `~/bin/finance/.env` (gitignored), beim ersten Skriptlauf mit
  Zufallswerten erzeugt: Postgres-Passwort, API-Schlüssel,
  Grafana-Admin-Passwort, GUI-Zugangsdaten.
- Grafana hat zusätzlich seinen eigenen Login; TLS/externes Auth macht
  Traefik.

## Datenmodell (Postgres, SQLAlchemy + Alembic)

- `accounts` — Konten: Bank, IBAN, Name, Typ (Giro/Tagesgeld/Kredit).
- `transactions` — Buchungen: Buchungs-/Wertstellungsdatum, Betrag
  (positiv = Eingang), Verwendungszweck, Gegenpartei, Konto, Kategorie,
  Quell-Auszug, Duplikat-Hash über (Konto, Datum, Betrag, Zweck).
- `categories` + `category_rules` — Kategorien und Zuordnungsregeln
  (Muster im Verwendungszweck/Gegenpartei → Kategorie), automatische
  Kategorisierung beim Import.
- `statements` — importierte PDFs: Datei, Bank, Konto, Zeitraum,
  Anfangs-/Endsaldo laut PDF, Status (Entwurf/übernommen/fehlerhaft).
- `recurring_items` — wiederkehrende Posten: Betrag, Rhythmus
  (monatlich/quartalsweise/jährlich), Stichtag, optionales Enddatum.
- `planned_items` — geplante Einmalposten: Datum, Betrag, Beschreibung.
- `loans` — Kredite: Auszahlungsdatum, Betrag, Zinssatz, Laufzeit,
  Tilgungsart (Annuität/endfällig).
- `scenarios` (+ Zuordnungs-/Modifikator-Tabellen) — benannte
  Was-wäre-wenn-Pakete; Kürzungs-Modifikatoren auf Kategorien oder einzelne
  wiederkehrende Posten (prozentual oder absolut, Streichung).

## Import-Pipeline

1. PDF landet in der Inbox (Drag-and-Drop in der GUI oder Datei-Kopie auf dem
   Host).
2. **Bank-Erkennung** anhand von Textmerkmalen wählt den Parser; drei
   Parser-Module (`vr.py`, `hvb.py`, `dkb.py`) mit gemeinsamem Interface
   `parse(pdf) → (Auszugsdaten, Buchungsliste)`.
3. **Prüfungen:**
   - Saldo-Plausibilisierung: Anfangssaldo + Summe der Buchungen muss den
     Endsaldo ergeben; Abweichung ⇒ Auszug wird als fehlerhaft markiert und
     nicht übernommen.
   - Duplikat-Prüfung über den Duplikat-Hash; bereits vorhandene Buchungen
     werden markiert und nicht doppelt übernommen.
4. **Vorschau (immer):** Buchungen werden als Entwurf gespeichert und in der
   GUI (bzw. per API) als Tabelle mit Saldo-Status, automatischen Kategorien
   und Duplikat-Markierungen angezeigt.
5. **Bestätigung** übernimmt die Buchungen endgültig; danach greifen sie in
   allen Auswertungen. Fehlgeschlagene Parses bleiben mit Fehlergrund auf der
   Import-Seite sichtbar, die Original-PDF bleibt in der Inbox.

## Szenario-Engine

Reines Python-Modul (`app/engine/`), ohne DB-/Web-Abhängigkeiten testbar.

- Eingabe: Startsaldo (echter aktueller Gesamtsaldo bzw. je Konto),
  Szenario-Definition, Horizont (konfigurierbar, Standard 18 Monate).
- Abrollen aller Posten zu einem **tagesgenauen Zahlungsstrom**:
  wiederkehrende Posten nach Rhythmus, Einmalposten am Datum, Kredite als
  Auszahlung + berechnete Raten (Annuitätenformel bzw. endfällig, inkl.
  Zins-/Tilgungsaufteilung und Restschuldverlauf), Kürzungs-Modifikatoren
  auf die betroffenen Posten/Kategorien.
- Ausgabe je Szenario: Saldo-Verlauf (Tagesreihe), **Tiefpunkt** (Datum +
  Betrag), erstes Datum der Unterschreitung von Null bzw. einer
  konfigurierbaren **Warnschwelle**.
- Ergebnisse werden in Projektions-Tabellen persistiert, damit Grafana sie
  direkt visualisieren kann; Neuberechnung per Knopf/API-Aufruf.
- Unterstützung beim Anlegen: Muster-Erkennung über importierte Buchungen
  schlägt wiederkehrende Posten vor (Bestätigen/Verwerfen durch den Nutzer).
- Echte Buchungen werden von Szenarien **nie verändert**.

## Web-GUI

FastAPI + Jinja2 + HTMX, deutschsprachig, vier Seiten:

1. **Übersicht:** Gesamtsaldo und Saldo je Konto, nächste anstehende
   Zahlungen, Warnhinweis bei drohender Schwellen-Unterschreitung,
   eingebettete Grafana-Panels.
2. **Import:** Drag-and-Drop-Fläche, Importliste mit Status, Vorschau-Tabelle
   mit Bestätigen-Aktion.
3. **Buchungen:** filterbare Tabelle (Konto, Zeitraum, Kategorie, Volltext),
   manuelle Kategorien-Korrektur mit „Regel daraus erzeugen“, **manuelles
   Erfassen** von Zahlungen/Einkünften per Formular.
4. **Planung:** wiederkehrende Posten (inkl. automatischer Vorschläge),
   Einmalposten, Kredite, Szenarien mit „Durchrechnen“-Aktion und
   Ergebnisanzeige.

## Grafana

Vollständig provisioniert (Datenquelle Postgres mit lesendem DB-User,
Dashboards als Dateien im Repo `~/bin/finance/grafana/`):

- Kontostand-Verlauf (je Konto und gesamt),
- Einnahmen/Ausgaben pro Monat, gestapelt nach Kategorie,
- Top-Ausgabenkategorien,
- Szenario-Vergleich (Vorschau-Kurven übereinander, Nulllinie, Warnschwelle).

## API für Claude Code

REST/JSON unter `http://127.0.0.1:8096/api/…`, OpenAPI-dokumentiert.
Abgedeckte Funktionen: Konten/Buchungen lesen und anlegen, Kategorien und
Regeln verwalten, Import-Status abfragen und Entwürfe bestätigen,
wiederkehrende/geplante Posten, Kredite und Szenarien anlegen/ändern,
Szenarien durchrechnen und Ergebnisse (Verlauf, Tiefpunkt, Unterschreitung)
abrufen.

## Claude-Code-Umgebung in `~/fb`

- **`CLAUDE.md`:** Umgebungsbeschreibung (API-URL, Ablageort des
  API-Schlüssels, Sprache Deutsch), Grundregeln („echte Buchungen nie
  ändern, Planung nur über Szenarien“).
- **Skills** (`.claude/skills/`):
  - `finanz-api` — Endpunkt-Referenz mit curl-Beispielen,
  - `finanzberatung` — Beratungs-Workflow: Lage abrufen → Basis-Szenario →
    Varianten (Kredit/Kürzung) anlegen und rechnen → vergleichen →
    Empfehlung mit Zahlen begründen,
  - `auszug-import` — Import-Betreuung: wartende/fehlgeschlagene Importe
    prüfen, Parser-Fehler im `~/bin`-Repo beheben.
- **Memory:** Kategorien-Konventionen, Entscheidungen (z. B. Warnschwelle),
  Eigenheiten einzelner Banken/Auszüge.

## Projektstruktur `~/bin`

```
~/bin/
├── create_pod_finance.sh        # Pod-Skript nach dem Beispiel-Muster
└── finance/
    ├── Containerfile            # Image für finance-api_ctr
    ├── .env                     # Secrets (gitignored, vom Skript erzeugt)
    ├── app/                     # FastAPI: API-Routen, GUI-Routen, Auth
    │   ├── models/              # SQLAlchemy-Tabellen + Alembic-Migrationen
    │   ├── parsers/             # vr.py, hvb.py, dkb.py + Bank-Erkennung
    │   ├── engine/              # Szenario-/Kredit-Rechnung (reines Python)
    │   └── templates/           # Jinja2 + HTMX
    ├── grafana/                 # provisionierte Datenquelle + Dashboards
    └── tests/                   # pytest
        └── fixtures/            # Beispiel-PDFs je Bank (gitignored)
```

## Tests

Testgetriebene Entwicklung (pytest):

- **Engine:** Annuitäten-/Zins-Mathematik und Projektionslogik als
  Unit-Tests (zuerst geschrieben).
- **Parser:** Tests gegen echte Beispiel-PDFs in `tests/fixtures/`
  (gitignored). Der Nutzer stellt pro Bank mindestens einen echten Auszug
  bereit (Beträge dürfen verfremdet sein, Layout muss echt sein) —
  zugesagt.
- **API/GUI:** FastAPI-TestClient gegen eine Test-Datenbank.
- **Deployment:** Smoke-Test am Skriptende (analog Beispiel-Skript:
  curl-Readiness-Check auf GUI und Grafana).

## Bewusst weggelassen (YAGNI)

- Kein automatischer Bank-Abruf (FinTS/PSD2) — Import nur über PDFs.
- Keine Mehrbenutzer-/Rollenverwaltung — ein GUI-Login genügt.
- Kein KI-Aufruf im Server — KI-Nutzung ausschließlich über Claude Code
  gegen die API.
- Keine Sofort-Übernahme beim Import — Vorschau ist verpflichtend.