Finanzmanager/README.md

# Finanzmanager

Persönliche Finanzverwaltung als Web-Anwendung: Konten, Buchungen mit Kategorien und
Klassen, Jahresbudget, Monatsabschluss, Auswertungen, Online-Banking über FinTS und PayPal
sowie Wertpapierdepots.

Ersetzt den Lexware FinanzManager Deluxe, läuft auf einem Debian-Server statt auf einem
Windows-Client. Die fachlichen Begriffe bleiben bewusst identisch zum Original – im
Haushalt wird beides parallel genutzt.

## Stand

**Alle sieben Phasen aus `PLAN.md` sind umgesetzt.**

* **Stammdaten und Buchungen** – Konten, Kontengruppen, Kategorien, Klassen; Kontoblatt
  mit Schnellzuordnung und Splitdialog, Buchungsmaske mit Splitbuchungen und Umbuchungen;
  QIF-Import mit Stichtag.
* **Import und Export** – QIF und CSV in beide Richtungen: Stammdaten und Buchungen
  übernehmen, Buchungen nach Zeitraum, Konto, Kategorie und Klasse gefiltert ausgeben.
  Exportdateien werden nicht vorgehalten; das Housekeeping räumt hochgeladene Dateien weg.
* **Planung** – Budgetplaner mit Monatswerten je Kategorie, Monatsabschluss mit Prüflauf,
  Snapshot und Sperre.
* **Auswertungen** – Summen-, Buchungs-, Vergleichs-, Kontostands- und Budgetbericht mit
  Zeitraumvorgaben, Spalten-Aufteilung, Drilldown und CSV-Export; gespeicherte Berichte in
  Gruppen.
* **Cockpit** – konfigurierbare Kacheln: Vermögensentwicklung, Einnahmen/Ausgaben je
  Monat, Ausgaben nach Kategorie, Kontostände, offene Vorgänge.
* **Online-Banking** – FinTS-Abruf mit TAN-Dialog über mehrere Requests, Einrichtung in drei
  Schritten (Zugangsdaten, TAN-Verfahren, Kontenzuordnung mit Anlegen fehlender Konten),
  Abrufzeitraum als Spanne oder Stichtag – auch für einen einzelnen Abruf –, abgerufene
  Umsätze buchen sich auf Wunsch selbst, Abgleich gegen vorhandene Buchungen, Regeln für
  die automatische Kategorisierung. Alternativ **PayPal** über dessen NVP-Schnittstelle:
  ein Formular statt dreier Schritte, da PayPal genau ein Guthabenkonto führt.
  Die FinTS-Adresse muss niemand suchen: Das **Bankleitzahlen-Verzeichnis** unter
  *Verwaltung → Bankleitzahlen* nimmt die CSV-Institutsliste der Deutschen
  Kreditwirtschaft auf und füllt daraus das Formular einer neuen Verbindung.
* **Wertpapiere** – Depotbestände mit Einstand und Bewertung, Depotbuchungen, Kursabruf,
  Veräußerungsgeschäfte und Erträge; Bestandslisten der Bank lassen sich als CSV
  übernehmen. Eine abgerufene Wertpapierabrechnung wird im Kontoblatt zum Geschäft: Das
  Depot in der Zuordnungsliste öffnet die Maske für Stück, Kurs und Nebenkosten, und
  daraus entstehen die Depotbuchung mit dem Einstandspreis und die Splitbuchung, die die
  Gebühren und Steuern auf ihre Kategorien verteilt. Jeder Wertpapiername führt auf eine
  Detailseite mit Stammdaten, Kurs, Bestand je Depot, Wertentwicklung und den Buchungen
  eines wählbaren Zeitraums.
* **Nebenmodule** – Buchungsvorlagen, regelmäßige Buchungen mit Fälligkeitslauf und
  Finanzkalender, Erinnerungen, Adressen, Verträge, Sparziele, Kredite mit Tilgungsplan.
* **Zahlungsverkehr** – Überweisungen und Terminüberweisungen über FinTS.
* **Abgleich mit dem Bargeld-Tool** – wer Bargeldausgaben in einem zweiten Programm
  erfasst, sieht beim Zuweisen einer Kategorie sofort, ob die Buchung dort schon steht:
  grüner Haken, rotes X oder Ausrufezeichen in einer schmalen Spalte des Kontoblatts.
  Adresse, Zugangsdaten und die abzugleichenden Kategorien stehen unter
  *Verwaltung → Bargeld-Tool*.

Einzelheiten je Modul in `docs/`, die Entwicklung in `Changes.md`.

## Technik

| | |
|---|---|
| Sprache | PHP 8.3, kein Framework, eigenes MVC |
| Datenbank | MariaDB 11 |
| Webserver | nginx + php-fpm |
| Betrieb | Docker Compose (drei Services) |
| Frontend | serverseitiges HTML, Vanilla JS, CSS Custom Properties |
| Fremdbibliotheken | genau eine: `nemiah/php-fints` als eigener Fork auf Codeberg |

Diagramme werden als eigenes SVG erzeugt, PDF-Berichte gehen über die Druckfunktion des
Browsers, die SEPA-Nachricht für Überweisungen entsteht selbst – bewusst keine Chart-,
PDF- oder SEPA-Bibliothek. Der FinTS-Fork trägt `psr/log` direkt in sich; damit hängt die
Anwendung an keinem fremden Update-Zyklus.

## Start

```bash
cp .env.example .env      # Werte anpassen (APP_KEY darf leer bleiben)
docker compose up -d
```

Ist `APP_KEY` leer, erzeugt der Container beim ersten Start einen Schlüssel unter
`data/schluessel/app_key`. Er verschlüsselt die Zugangsdaten der Bankverbindungen und
**gehört ins Backup** – ohne ihn sind sie nicht mehr lesbar.

Danach http://localhost:8000 aufrufen. Beim ersten Aufruf führt die Anwendung zur
Ersteinrichtung und legt den ersten Benutzer an.

```bash
./scripts/run-tests.sh    # Tests
./scripts/backup.sh       # Backup mit Rotation
./scripts/update.sh       # Update (auf dem Produktionsserver)
```

## Verzeichnisse

```
src/            Anwendungscode (Controllers, Models, Services, Views)
public/         Front-Controller und statische Dateien
migrations/     nummerierte SQL-Migrationen, laufen beim Containerstart
scripts/        Migration, Update, Backup, Tests, Kursabruf, Housekeeping
tests/          PHP-Testsuite; tests/e2e/ für Playwright
data/           Nutzdaten: mariadb, logs, import, schluessel (nicht im Repository)
Altdaten/       Screenshots und QIF-Export der Altanwendung (nicht im Repository)
```

## Migration der Altdaten

Datenquelle ist der **QIF-Export** aus dem FinanzManager – die `.QDF`-Datei ist
verschlüsselt und nicht auswertbar. Der Importer liest Klassen, Kategorien, Konten,
Buchungen samt Splits sowie Wertpapierbuchungen. Einzelheiten zum Format und den
Fallstricken stehen in `PLAN.md`, Kapitel 4.

Klassen, Kategorien, Konten und Buchungen lassen sich übernehmen – im Dialog unter
*Verwaltung → Import/Export* oder auf der Kommandozeile. Buchungen ab dem Stichtag kommen
einzeln in die Datenbank, alles davor wird je Konto zum Anfangssaldo verrechnet:

```bash
docker compose exec -u www-data php php scripts/qif-import.php data/import/Export.QIF
docker compose exec -u www-data php php scripts/qif-import.php --uebernehmen data/import/Export.QIF
```

Ohne `--uebernehmen` läuft nur der Trockenlauf. Mit `--konto=NAME` (mehrfach angebbar,
im Dialog als Ankreuzliste nach dem Trockenlauf) bleibt der Import auf einzelne Konten
beschränkt; `--konten` nennt die Konten der Datei.

In die andere Richtung geht es über *Verwaltung → Import/Export → Export*: Buchungen als
QIF oder CSV, gefiltert nach Zeitraum, Konto, Kategorie und Klasse. Die Datei entsteht
erst beim Herunterladen und wird nirgends abgelegt. Der CSV-Import liest dieselbe Datei
wieder ein. Einzelheiten in `docs/import-export.md`.

## Dokumentation

- `PLAN.md` – Projektplan mit allen Phasen
- `CLAUDE.md` – Entwicklungsregeln
- `CONTRIBUTE.md` – Mitmachen: Leitlinien, Wege für Beiträge, Entwicklungsumgebung
- `Changes.md` – Änderungsprotokoll
- `docs/stammdaten.md` – Konten, Kontengruppen, Kategorien, Klassen
- `docs/buchungen.md` – Kontoblatt, Umbuchungen, Splitbuchungen, Salden
- `docs/planung.md` – Budgetplaner und Monatsabschluss
- `docs/auswertungen.md` – Berichtsmodul, Filterleiste, Drilldown, CSV
- `docs/cockpit.md` – Startseite und ihre Kacheln
- `docs/banking.md` – FinTS- und PayPal-Abruf, TAN-Dialog, Abgleich und Regeln
- `docs/wertpapiere.md` – Depots, Einstand, Kurse, Invst- und CSV-Bestandsimport
- `docs/nebenmodule.md` – Vorlagen, Termine, Verträge, Sparziele, Kredite, Zahlungsverkehr
- `docs/import-export.md` – QIF und CSV in beide Richtungen, Formatwahl, Housekeeping