finance-dashboard/README.md

Finance Dashboard

Privates, schlankes Dashboard für passives Einkommen auf pinguAurora. FastAPI, Jinja2 und SQLite; Python 3.13 im Docker-Image. Kein Node, keine externen Finanz-APIs. Docker-Port 8081 → 8080, Daten-Volume ./data → /data, RAM-Limit 128 MiB bleiben bestehen.

Funktionen

• Acht Kennzahlen, dynamischer Monats-/Jahresvergleich und drei Chart.js-Diagramme.
• Zahlungen anlegen, bearbeiten, mit Bestätigung löschen; Positionen ergänzen.
• Vollständige Historie unter /income, nach Jahr, Monat, Position und Kategorie filterbar, 100 Buchungen pro Seite.
• CSV-Export, wiederholbarer XLSX-Import und getrennte Erfassung erwarteter/erhaltener Zahlungen.
• Alle Summen basieren ausschließlich auf received=1. Der Jahresvergleich vergleicht das aktuelle Kalenderjahr mit dem gesamten Vorjahr, kein YTD-Vergleich. Bei Vorjahreswert 0 erscheint –.
• Jahres-Spalten entstehen aus den vorhandenen Buchungsjahren, dem aktuellen Jahr und dem nächsten Kalenderjahr als Ausblick; Lücken werden ergänzt. Es sind keine konkreten Jahreszahlen im Dashboard fest programmiert.

Lokale Entwicklung

python3.13 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
export FINANCE_DB_PATH="$PWD/data/finance.db"
uvicorn main:app --app-dir app --reload --host 127.0.0.1 --port 8081

requirements.txt enthält nur die Web-Abhängigkeiten, einschließlich python-multipart für HTML-Formulare. SQLite ist Teil von Python. openpyxl wird nur beim Import benötigt; httpx nur für Tests. Templates und statische Dateien werden relativ zum Anwendungscode gefunden, im Container also unter /app/templates und /app/static.

.venv/bin/python -m unittest discover -s tests -v
docker compose config

Tests verwenden ausschließlich temporäre Datenbanken. Die Entwicklungsbibliotheken werden nicht im Produktionsimage installiert.

Docker Build und Start

DOCKER_BUILDKIT=0 docker build \
  -t finance-dashboard-finance-dashboard:latest \
  .
docker compose up -d --no-build
curl --fail http://127.0.0.1:8081/health

Die App ist unter http://localhost:8081 erreichbar. /health liefert {"status":"ok"}. python:3.13-slim wird ohne feste CPU-Plattform verwendet; auf dem Raspberry wird nativ für ARM64 gebaut.

SQLite und Geldbeträge

Standardpfad: /data/finance.db, persistent auf dem Host als ./data/finance.db. Für lokale Entwicklung/Import ist FINANCE_DB_PATH oder beim Import --db verfügbar. Tabellen und die neun Grundpositionen werden beim Start automatisch angelegt.

income_entries.amount enthält ganze Cent (INTEGER), keine Euro-Floats. Python summiert Integer und berechnet Prozentwerte mit Decimal. Formulare akzeptieren 0,04, 0.04 und 28,00, ohne Tausendertrennzeichen. Mehr als zwei Nachkommastellen werden abgelehnt. Negative Beträge sind für Korrekturen erlaubt. Nur Chart.js verwendet für die grafische Anzeige JavaScript-Zahlen; das ändert keine Finanzwerte in SQLite.

SQLite nutzt Foreign Keys, WAL, kurze Transaktionen und fünf Sekunden Wartezeit bei Locks. Referenzierte Positionen können nicht physisch gelöscht werden; active=0 deaktiviert sie für neue Buchungen, vorhandene Historie bleibt erhalten. Bei temporären Datenbankproblemen antwortet die App mit HTTP 503. Schema-Version 3 wird über PRAGMA user_version geführt.

expected=1, received=0 bezeichnet eine offene/ausgefallene erwartete Zahlung. Der Betrag enthält dann die Erwartung, fließt aber nicht in tatsächliche Summen ein. Eine teilweise erhaltene Zahlung wird als erhaltene Buchung plus separate offene Restbuchung erfasst. Es gibt noch keine automatische Prognose oder Fälligkeitsverwaltung.

Excel-Import

SQLite ist die primäre Datenquelle. Excel wird nach dem Import nicht im laufenden Dashboard gelesen. Die XLSX-Datei bleibt lokal im ignorierten Verzeichnis import/.

source .venv/bin/activate
pip install -r requirements-import.txt
python scripts/import_excel.py import/tr_verbessert_2027_vergleiche_enbridge.xlsx \
  --db ./data/finance.db --dry-run
python scripts/import_excel.py import/tr_verbessert_2027_vergleiche_enbridge.xlsx \
  --db ./data/finance.db

Ohne --db verwendet das Script FINANCE_DB_PATH bzw. /data/finance.db:

python scripts/import_excel.py /pfad/datei.xlsx

Es wird nur das erste Tabellenblatt gelesen. Der Import sucht den Buchungskopf Datum, Art des Ertrags/Position, Betrag (€) und Kategorie. Dashboard-Zellen davor und weitere Blätter werden ignoriert. Ungültige Buchungen oder Formeln innerhalb der Buchungsfelder brechen den gesamten Import mit Zeilenangabe ab; es werden keine Teilimporte gespeichert. --dry-run rollt Buchungsänderungen zurück, legt jedoch bei Bedarf Datenbank und Seed an.

Bekannte Aliase werden normalisiert: MSC → Main Street Capital, CSW/CSWC → Capital Southwest, PC → Prospect Capital, Stoxx → STOXX Global Select Dividend 100, Air Baltic → airBaltic. Präfixe wie „Dividende“ werden entfernt. Groß-/Kleinschreibung, Leerzeichen und Satzzeichen führen nicht zu neuen Positionen. Unbekannte Positionen werden angelegt; unsichere Namen werden nicht anhand von Ähnlichkeit zusammengelegt. Historische airBaltic-Buchungen mit Dividendenkategorie werden als Anleihezinsen übernommen und mit einer Notiz gekennzeichnet.

Dublettenidentität: Datum, normalisierte Position, Kategorie, Centbetrag, Erwartet-/Erhalten-Status und Vorkommensnummer. Dadurch bleiben mehrere identische echte Zahlungen in einer Datei erhalten, während wiederholte Imports und passende manuelle Buchungen wiederverwendet werden. import_records merkt sich den Import auch nach Bearbeiten/Löschen einer Buchung; ein erneuter Import stellt gelöschte Buchungen nicht wieder her. Änderungen an identitätsbildenden Excel-Feldern gelten als neue Buchungen: Korrekturen nach dem Erstimport deshalb im Dashboard vornehmen. Die Excel anschließend als Archiv behandeln.

Die vorliegende Excel besitzt im Ertragsbuch keine Erwartet-/Erhalten-Spalten. Diese historischen Buchungen gelten als erhalten. Aus widersprüchlichen Dashboard-Texten werden keine zusätzlichen Zahlungen oder Ausfälle erfunden. Falls eine historische Buchung tatsächlich ausgefallen ist, ihren Status nach fachlicher Prüfung im Dashboard korrigieren. Optionale Importspalten Erwartet/Erhalten unterstützen Ja/Nein, true/false und 1/0.

Das Script zeigt einen Plausibilitätscheck: September 2026 3,71 €, einschließlich Enbridge am 02.09.2026 mit 0,04 €. Abweichungen werden gemeldet, nicht durch erfundene Buchungen ausgeglichen.

Falls data/ bereits durch Docker angelegt wurde und für deinen lokalen Benutzer nicht beschreibbar ist, kann der Import im temporären Container laufen. Die Importbibliothek wird dabei nicht im Produktionsimage gespeichert:

docker compose run --rm --no-deps -v "$PWD:/workspace:ro" finance-dashboard sh -c \
  'pip install --no-cache-dir --target /tmp/import-deps openpyxl && PYTHONPATH=/tmp/import-deps python /workspace/scripts/import_excel.py /workspace/import/tr_verbessert_2027_vergleiche_enbridge.xlsx'

CSV-Export

/export/income.csv exportiert alle Buchungen einschließlich offener Zahlungen: Datum, Position, Kategorie, Betrag, Notiz, Erwartet, Erhalten. UTF-8 mit BOM, Semikolon, Dezimalkomma und CRLF für Excel. Gefährliche Formelpräfixe in Textfeldern erhalten ein schützendes Apostroph. Export ist eine Buchungsliste, kein vollständiges Datenbankbackup.

Backup und Wiederherstellung

data/, SQLite-Dateien, Excel-Dateien und .env werden von Git ausgeschlossen. .dockerignore hält sie auch aus dem Build-Kontext fern. Nie nur die laufende SQLite-Hauptdatei kopieren: Im WAL-Modus können neuere Transaktionen noch in -wal liegen.

Konsistentes Backup während des Betriebs mit der SQLite-Backup-API:

mkdir -p backups
docker compose exec -T finance-dashboard python -c 'import sqlite3; src=sqlite3.connect("/data/finance.db"); dst=sqlite3.connect("/data/finance-backup.db"); src.backup(dst); dst.close(); src.close()'
cp data/finance-backup.db "backups/finance-$(date +%Y%m%d-%H%M%S).db"

Backup zusätzlich auf einem anderen Datenträger sichern. Wiederherstellung nur bei gestoppter App: vorhandenes data/ vollständig beiseite sichern (inkl. WAL/SHM), ein frisches data/ anlegen, die Backup-Datei dort als finance.db einsetzen und Dateirechte prüfen. Anschließend docker compose up -d --no-build. Das Deploy-Script führt keine Wiederherstellung durch und löscht keine Daten.

Deployment auf pinguAurora

Wegen des aktuellen Buildx-Versionskonflikts nicht docker compose up -d --build verwenden. Im bestehenden Checkout auf dem Raspberry:

git pull

DOCKER_BUILDKIT=0 docker build \
  -t finance-dashboard-finance-dashboard:latest \
  .

docker compose up -d --no-build

Oder im Checkout einfach:

./deploy.sh

Das ausführbare Script wechselt in sein eigenes Projektverzeichnis, nutzt git pull --ff-only, führt genau den klassischen Build und den Start ohne Build aus, zeigt den Containerstatus und prüft http://127.0.0.1:8081/health mit Wiederholungen. Bei einem Fehler bricht es ab. Es verändert keine Datenbankdateien. Zugriff: http://pinguAurora:8081.

Die lokale Datenbank wird nicht mit Git übertragen. Für die Erstübernahme auf dem Raspberry entweder die XLSX-Datei separat übertragen und das Import-Script dort in einer Python-Umgebung mit requirements-import.txt gegen ./data/finance.db ausführen, oder ein konsistentes SQLite-Backup vor dem ersten Start in das dortige data/ übernehmen. Vor einem Import in einen vorhandenen Datenbestand ein Backup erstellen.

Betrieb und Quellen

Nur für das private LAN, ohne Benutzerverwaltung. Validierung, SQL-Parameterbindung, Jinja-Autoescaping und Prüfung fremder Browser-Formularursprünge sind enthalten. Chart.js wird fest versioniert vom CDN geladen; ohne Internet funktionieren Buchungen, Kennzahlen und Tabellen weiter. Die Diagramme benötigen Zugang zum CDN.

Implementierungsreferenzen: FastAPI Templates und Chart.js Integration.

REST-API aktivieren

Die API läuft im bestehenden FastAPI-Prozess unter /api/v1 und verwendet dieselben Services und dieselbe SQLite-Datenbank wie die Weboberfläche. Es gibt keine neue Datenhaltung und keine zusätzlichen Laufzeit-Abhängigkeiten.

1. Ein langes zufälliges Token erzeugen:

   python -c 'import secrets; print(secrets.token_urlsafe(32))'
   

2. Im Projektverzeichnis eine .env anlegen bzw. die vorhandene Datei ergänzen:

   FINANCE_API_TOKEN=<langes-zufälliges-token>
   

   .env.example enthält nur den Platzhalter change-me. Diesen durch das erzeugte Token ersetzen; change-me aktiviert die API ausdrücklich nicht. .env bleibt in .gitignore und .dockerignore. Ein echtes Token gehört niemals ins Repository.

3. Den Container nach einer Tokenänderung neu erstellen:

   docker compose up -d --no-build --force-recreate
   

Compose liest .env automatisch und reicht FINANCE_API_TOKEN weiter. Bei direktem Uvicorn-Start muss die Variable in der Prozessumgebung gesetzt sein. Ohne Token, bei leerem Token oder beim Beispiel-Platzhalter antwortet die API mit 503. Weboberfläche und /health funktionieren weiterhin. Ein fehlender/falscher Bearer-Header bei aktivierter API führt zu 401 mit WWW-Authenticate: Bearer. Der Vergleich erfolgt mit secrets.compare_digest. Tokens werden nicht protokolliert. CORS bleibt deaktiviert.

Für die folgenden curl-Beispiele muss FINANCE_API_TOKEN auch in der aufrufenden Shell gesetzt sein. Im eigenen Projektverzeichnis kann die selbst angelegte .env geladen werden:

set -a
. ./.env
set +a

curl \
  -H "Authorization: Bearer $FINANCE_API_TOKEN" \
  http://pinguAurora:8081/api/v1/assets

Endpunkte

Alle folgenden Pfade beginnen mit /api/v1 und erfordern den Bearer-Header, auch /meta.

Methode	Pfad	Verhalten
GET	/assets	Alle Positionen, optional active=true/false
GET	/assets/{id}	Einzelne Position, sonst 404
POST	/assets	Position erstellen, 201; normalisierte Duplikate 409
PATCH	/assets/{id}	Nur übergebene Felder ändern
DELETE	/assets/{id}	Position deaktivieren (active=false), 204; Historie bleibt erhalten
GET	/income	Historie, neueste zuerst; Filter und Pagination
GET	/income/{id}	Einzelne Buchung, sonst 404
POST	/income	Zahlung erstellen und zurückgeben, 201
PATCH	/income/{id}	Teiländerung, aktualisierte Zahlung zurückgeben
DELETE	/income/{id}	Buchung löschen, 204 ohne Inhalt
GET	/stats/summary	Dieselben acht Kennzahlen wie im Dashboard
GET	/stats/monthly	Monatswerte je Jahr, optional year
GET	/stats/by-asset	Betrag und Anteil je Position, alle Jahre
GET	/stats/by-category	Betrag und Anteil für alle vier Kategorien
GET	/meta	Name, API-Version und Datenbankstatus ohne Systemdetails

GET /income unterstützt year, month, asset_id, category, received, expected, limit (Standard 100, maximal 1000) und offset (Standard 0). Sortierung: Datum absteigend, bei gleichem Datum ID absteigend. Listen werden als JSON-Arrays geliefert. asset in Buchungen und Anteilen ist der normalisierte Positionsname; asset_id identifiziert die Position eindeutig.

Geldbeträge werden im JSON ausschließlich als Strings in Euro mit zwei Nachkommastellen ausgegeben, z. B. "0.04". Auch Eingaben müssen Dezimalstrings sein ("0.04" oder "0,04"); JSON-Fließkommazahlen werden abgelehnt. Intern bleibt es bei Decimal und Integer-Cent. Prozentwerte sind ebenfalls Strings mit zwei Nachkommastellen; bei Nenner 0 ist der Wert null. Ein Anteil wird relativ zur tatsächlichen Gesamtsumme berechnet, inklusive negativer Korrekturen.

/stats/monthly liefert ein Array aus {year, months: [{month, amount}], total} mit zwölf Monaten pro Jahr. Ein explizit angefragtes Jahr ohne Buchungen liefert Nullbeträge. Alle Statistik-Endpunkte zählen ausschließlich received=true; expected=true, received=false erhöht keine tatsächliche Einnahme. Der Jahresvergleich bleibt aktuelles Jahr gegen gesamtes Vorjahr. /stats/by-category trennt dividend und distribution; das Dashboard-Diagramm fasst sie zur Anzeige zusammen.

Unbekannte IDs liefern 404, doppelte Positionsnamen 409 und ungültige Felder/Referenzen 422. PATCH lässt fehlende Felder unverändert; note: null bzw. ticker: null leert optionale Felder. Andere Felder dürfen nicht null sein. Historische Buchungen deaktivierter Positionen bleiben lesbar und bearbeitbar; neue Buchungen für inaktive Positionen werden abgelehnt. Reaktivierung erfolgt über PATCH /assets/{id} mit {"active":true}. Datenbank-Locks führen nach der bestehenden Wartezeit zu 503 mit Wiederholungshinweis; interne Fehler zu 500 ohne Stacktrace oder interne Details.

Zahlung per API erstellen

Zuerst die passende asset_id über /assets ermitteln; die ID im folgenden Beispiel ersetzen:

curl -X POST \
  -H "Authorization: Bearer $FINANCE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "date":"2026-09-02",
    "asset_id":1,
    "category":"dividend",
    "amount":"0.04",
    "note":"Test",
    "expected":false,
    "received":true
  }' \
  http://pinguAurora:8081/api/v1/income

POST legt jeweils eine echte neue Zahlung an; die Dublettenerkennung des Excel-Imports gilt nicht für manuelle/API-Buchungen.

Swagger: http://pinguAurora:8081/docs. Unter Authorize nur das Token eingeben; Swagger ergänzt Bearer. OpenAPI: /openapi.json. Die Tags heißen Assets, Income und Stats. Die Dokumentation ist lesbar, die dokumentierten API-Aufrufe erfordern Authentifizierung.

API-Deployment auf pinguAurora

Einmalig .env mit einem echten Token auf dem Raspberry anlegen. Dann weiterhin der bestehende Weg ohne Buildx:

git pull
DOCKER_BUILDKIT=0 docker build \
  -t finance-dashboard-finance-dashboard:latest \
  .
docker compose up -d --no-build
curl --fail http://127.0.0.1:8081/health

./deploy.sh bleibt unverändert nutzbar. Die vorhandene /data/finance.db wird weiterverwendet und weder gelöscht noch überschrieben. API-Tests setzen ein zufälliges Testtoken in der Testumgebung und verwenden ausschließlich temporäre Datenbanken.

Technische Referenzen: FastAPI HTTPBearer und Pydantic Serialization.

Positionsänderung: Anleihezinsen und Notgroschen

Beim ersten Start dieser Version wird automatisch eine einmalige Datenmigration ausgeführt:

• Anleihezinsen (Anleihe) und Zinsen NG (Notgroschen/Zinskonto) werden angelegt bzw. aktiviert.
• Zinsen und Steuerrückzahlung werden deaktiviert und sind für neue Zahlungen nicht mehr auswählbar.
• Vorhandene Buchungen und ihre Zuordnung bleiben unverändert; sie bleiben in Historie und Auswertungen sichtbar.

Die Migration wird zusammen mit ihrer Ausführungsmarkierung in einer SQLite-Transaktion gespeichert. Spätere Starts überschreiben keine danach vorgenommenen Positionsänderungen. Auf pinguAurora reicht das normale Deployment mit ./deploy.sh; die Datenbank wird nicht über Git übertragen.

Trading-Buch und Positionshistorie

Das Trading-Buch (/trading) erfasst Käufe und Verkäufe getrennt von Dividenden/Zinsen. /trading/positions zeigt offene Positionen, /trading/transactions die vollständige filterbare Historie und /trading/assets/{asset_id} die Historie einer Position einschließlich Bestand vor und nach jeder Buchung. Geschlossene Positionen bleiben über ihre Transaktionen erreichbar. Neue Positionen lassen sich direkt aus dem Trading-Formular ergänzen.

Unterstützte Asset-Typen: Aktien (stock), ETFs (etf), Anleihen (bond) und Krypto (crypto). Transaktionstypen: buy und sell. Es gibt keine automatische Kursabfrage, keine Performance auf Basis aktueller Marktpreise und keine steuerliche Gewinnermittlung.

Genauigkeit und Durchschnittseinstand

Stückzahlen und Kurse werden als kanonische Dezimalstrings in SQLite gespeichert, mit bis zu 12 Vor- und 12 Nachkommastellen. Gebühren haben höchstens zwei Nachkommastellen. Eingaben akzeptieren Komma oder Punkt, keine Tausendertrennzeichen. JSON-Zahlen/Floats werden für diese Felder abgelehnt; die API erwartet Strings.

Berechnungen verwenden Python Decimal mit 60 Stellen Rechenpräzision:

• gross_amount = quantity × price_per_unit, kaufmännisch auf zwei Nachkommastellen gerundet (ROUND_HALF_UP).
• Kauf: total_cost = gross_amount + fees.
• Verkauf: net_proceeds = gross_amount - fees.
• Offenes investiertes Kapital ist der verbleibende Einstand inklusive Kaufgebühren, nicht die Summe aller historischen Einzahlungen oder der aktuelle Marktwert.
• Einstand je Stück = offenes investiertes Kapital / aktueller Bestand. Die API gibt den Durchschnitt mit zwölf Nachkommastellen aus, die UI zeigt acht.
• Beim Verkauf wird der anteilige Durchschnittseinstand auf Cent gerundet ausgebucht. Realisierter G/V = Nettoerlös minus ausgebuchter Einstand. Beim vollständigen Verkauf wird der gesamte restliche Einstand ausgebucht, ohne Rundungsrest.

Beispiel: 10 Stück zu 10,00 mit 2,00 Gebühren plus 10 Stück zu 20,00 mit 2,00 Gebühren ergeben 304,00 Einstand und einen Durchschnitt von 15,20 pro Stück. Verkauf von 5 Stück zu 30,00 mit 1,00 Gebühren: Nettoerlös 149,00, ausgebuchter Einstand 76,00, realisierter Gewinn 73,00. Offen bleiben 15 Stück mit 228,00 Einstand.

Dies ist keine deutsche steuerliche FIFO-Berechnung. FIFO, Steuerberechnung und steuerliche Verlusttöpfe sind nicht implementiert.

Die Reihenfolge ist deterministisch: Datum aufsteigend, bei gleichem Datum ID aufsteigend (Erfassungsreihenfolge). Jede Änderung wird in einer Schreibtransaktion gegen die gesamte Historie der betroffenen Position(en) geprüft. Überverkäufe werden auch bei Rückdatierung, Änderung des Assets oder Löschen eines früheren Kaufs verhindert. Solche Änderungen werden vollständig zurückgerollt. Quantity muss positiv sein; Kurs und Gebühren dürfen 0, aber nicht negativ sein. Ohne bekannten Kurs keine Buchung speichern; 0 ist nur für tatsächlich kostenlose Erwerbe gedacht.

Währungen

Jede Position wird in genau einer Währung geführt, auch über zwischenzeitliche Komplettverkäufe hinweg. Für denselben Asset-Datensatz dürfen keine unterschiedlichen Währungen gemischt werden. Es gibt keine Wechselkursumrechnung. Die Trading-KPIs und Diagramme beziehen sich auf die gewählte Währung (Standard EUR); Bestandslisten zeigen die Währung pro Position. Der dreistellige Währungscode muss zum dokumentierten Abrechnungskurs passen. Monetäre Beträge werden in dieser Version für alle Codes auf zwei Nachkommastellen geführt.

Source und Strategie

Feld	Werte
source	manual (Manuell), savings_plan (Sparplan), roundup (Round-up), cashback, rebalancing, other
strategy_tag (optional)	core, income, conviction, dip_buy, speculation, rebalancing, other

Beispiele: SpaceX Round-up → roundup / conviction; normaler SpaceX-Nachkauf → manual / conviction; FTSE-Sparplan → savings_plan / core; CSWC-Sparplan → savings_plan / income.

Die Diagramme zeigen den noch offenen Einstand nach Source und Strategie der ursprünglichen Käufe. Ein Verkauf reduziert diese Anteile proportional. Cent-Reste werden deterministisch nach dem größten Nachkomma-Rest verteilt, sodass die Anteile zusammen exakt dem offenen Einstand entsprechen. Tags des Verkaufs verändern nicht die Herkunft des bisherigen Einstands. Ohne Strategie wird untagged/„Ohne Tag“ als separate Auswertungsgruppe gezeigt. Das dritte Diagramm zählt echte Käufe pro Monat/Jahr. Alle Diagramme besitzen Tabellen als Alternative ohne CDN-Zugriff.

Trading-API und Export

Alle Endpunkte verwenden die vorhandene Bearer-Authentifizierung mit FINANCE_API_TOKEN, dokumentiert unter /docs im Tag Trading:

Methode	Pfad
GET, POST	/api/v1/transactions
GET, PATCH, DELETE	/api/v1/transactions/{id}
GET	/api/v1/positions
GET	/api/v1/trading/stats
GET	/api/v1/trading/by-source
GET	/api/v1/trading/by-strategy

Transaktionsfilter in Web und API: year, month, asset_id, transaction_type, source, strategy_tag. strategy_tag=untagged findet Einträge ohne Strategie. API zusätzlich limit (1–1000, Standard 100) und offset (Standard 0). Listen kommen neueste zuerst, nach Datum und ID absteigend. POST liefert 201, PATCH 200 und DELETE 204. Überschrittene Bestände oder unzulässige Änderungen liefern 422 mit einer fachlichen Fehlermeldung. Ein API-POST ist immer eine neue Buchung, nicht idempotent.

/positions liefert aktuelle Positionen aller Währungen; optional currency=EUR und include_closed=true. Felder: Asset-ID/-Name, Ticker, Asset-Typ, Währung, Stückzahl, Durchschnittseinstand, offenes Kapital, Summe Käufe inkl. Gebühren, Summe Verkäufe nach Gebühren, realisierter G/V, Kauf-/Verkaufsanzahl und erstes/letztes Datum. /trading/stats, /by-source und /by-strategy unterstützen currency (Standard EUR). Anteils-Endpunkte liefern {currency, items: [{key, amount, percentage}]}. Prozentwerte sind Strings bzw. null bei Gesamteinstand 0. Alle Geld- und Stückzahlwerte der API sind Dezimalstrings.

PATCH ändert nur übergebene Felder; nur strategy_tag und note dürfen explizit null sein. Inaktive Assets bleiben für Verkäufe und die Korrektur vorhandener Trades verfügbar; neue Käufe für inaktive Positionen sind gesperrt.

CSV unter /export/trading.csv enthält Datum, Position, Typ, Stückzahl, Kurs, Währung, Gebühren, Gesamtbetrag, Source, Strategie und Notiz. UTF-8 mit BOM, Semikolon, Dezimalkomma und CRLF; Textfelder sind gegen Excel-Formelinjektion geschützt. Gesamtbetrag bedeutet beim Kauf Gesamtkosten und beim Verkauf Nettoerlös.

Migration, Backup und Deployment

Schema-Version 3 ergänzt automatisch die Tabelle transactions, zwei Indizes und einen Eintrag in data_migrations. DDL und Migrationsmarkierung werden atomar ausgeführt. Bestehende Tabellen werden weder gelöscht noch ersetzt. Income-Einträge werden nicht verändert. Es werden keine Trades und keine aktuellen Bestände automatisch eingetragen.

Das oben beschriebene konsistente SQLite-Backup sichert jetzt auch Trading-Daten. Ein CSV-Export ersetzt weiterhin kein vollständiges Backup. Das Deployment auf pinguAurora bleibt unverändert:

git pull
DOCKER_BUILDKIT=0 docker build \
  -t finance-dashboard-finance-dashboard:latest \
  .
docker compose up -d --no-build
curl --fail http://127.0.0.1:8081/health

Alternativ ./deploy.sh. Niemals docker compose up -d --build auf dem Raspberry verwenden, solange der bekannte Buildx-Konflikt besteht. /data/finance.db bleibt persistent.

Referenzbestand – nicht importiert

Diese vom Nutzer genannten Stückzahlen sind ausschließlich eine spätere Referenz, keine Buchungen und kein verifizierter aktueller Depotstand:

Position	Stückzahl
AGNC	153,816
FTSE Global All Cap	244,284
STOXX Global Select Dividend 100	18
Main Street Capital	14,4758
AI ETF	2,14
SpaceX, nach Round-up	2,692262
Capital Southwest	8,28
Ares Capital	7,33
Enbridge	0,22

SpaceX-Beispiel: 2,600000 vor Round-up + 0,092262 = 2,692262 danach; buy, source=roundup, strategy_tag=conviction. Kein verlässlicher Kaufkurs liegt vor, deshalb wurde kein Preis und keine Transaktion eingetragen. Eine technische Anfangsposition (Opening Balance) ist noch nicht implementiert. Sie müsste künftig separat von echten Käufen modelliert werden und darf keine Kaufstatistiken erhöhen. Bis echte historische Käufe mit Datum und Kurs erfasst sind, zeigt das Trading-Buch entsprechend keine daraus abgeleiteten Bestände.