From 42ce0ece6d6aac59a148a5ba5349346a4f9b1c4ed30c54316217c04669b7ecc2 Mon Sep 17 00:00:00 2001 From: wlfb Date: Fri, 17 Jul 2026 19:47:54 +0200 Subject: [PATCH] feat: Beratungsumgebung (CLAUDE.md, Skills finanz-api/finanzberatung/auszug-import) Co-Authored-By: Claude Fable 5 --- .claude/skills/auszug-import/SKILL.md | 74 +++++++++++++++ .claude/skills/finanz-api/SKILL.md | 123 +++++++++++++++++++++++++ .claude/skills/finanzberatung/SKILL.md | 61 ++++++++++++ CLAUDE.md | 18 ++++ 4 files changed, 276 insertions(+) create mode 100644 .claude/skills/auszug-import/SKILL.md create mode 100644 .claude/skills/finanz-api/SKILL.md create mode 100644 .claude/skills/finanzberatung/SKILL.md create mode 100644 CLAUDE.md diff --git a/.claude/skills/auszug-import/SKILL.md b/.claude/skills/auszug-import/SKILL.md new file mode 100644 index 0000000..94bb2b6 --- /dev/null +++ b/.claude/skills/auszug-import/SKILL.md @@ -0,0 +1,74 @@ +--- +name: auszug-import +description: Workflow zur Betreuung von Kontoauszugs-Importen (Inbox scannen, Entwürfe prüfen, Vorschau zusammenfassen, bestätigen) sowie zum Beheben von Parser-Fehlern im Tool-Repo ~/bin/finance. Use when neue PDF-Kontoauszüge importiert werden sollen, ein Import in der Vorschau (draft) auf Bestätigung wartet, oder ein Import mit Fehlerstatus (error) fehlgeschlagen ist und der Parser angepasst werden muss. +--- + +# Auszug-Import betreuen + +## 1. Status prüfen + +```bash +KEY=$(grep '^FB_API_KEY=' /home/wlfb/bin/finance/.env | cut -d= -f2) +curl -s -H "Authorization: Bearer $KEY" http://127.0.0.1:8096/api/imports | jq +``` + +Falls neue PDFs in der Inbox liegen könnten (`~/.local/share/finance_pod/data/inbox/`), +zuerst neu einscannen: + +```bash +curl -s -X POST -H "Authorization: Bearer $KEY" http://127.0.0.1:8096/api/imports/scan-inbox | jq +``` + +Auf Status `draft` (wartet auf Bestätigung) und `error` (Parser +fehlgeschlagen) filtern. + +## 2. Drafts: Vorschau prüfen und bestätigen + +```bash +curl -s -H "Authorization: Bearer $KEY" \ + http://127.0.0.1:8096/api/imports//preview | jq +``` + +Dem Nutzer zusammenfassen: Zeitraum, Anzahl Buchungen, Saldo-Check +(`balance_ok`), Zahl der erkannten Duplikate. Erst nach ausdrücklicher +Bestätigung durch den Nutzer: + +```bash +curl -s -X POST -H "Authorization: Bearer $KEY" \ + http://127.0.0.1:8096/api/imports//confirm | jq +``` + +Nie blind übernehmen — auch bei `balance_ok: true` dem Nutzer die Eckdaten +vorlegen. + +## 3. Parser-Fehler beheben + +Bei Status `error` (`error_message` beachten) liegt die Original-PDF weiterhin +in der Inbox. Vorgehen im Tool-Repo `/home/wlfb/bin/finance`: + +1. PDF-Text ansehen, um Regexe abzugleichen: + ```bash + cd /home/wlfb/bin/finance && .venv/bin/python scripts/dump_pdf_text.py \ + ~/.local/share/finance_pod/data/inbox/.pdf + ``` +2. Regex-Konstanten im passenden Parser fixen — je nach Bank + `app/parsers/vr.py`, `app/parsers/hvb.py` oder `app/parsers/dkb.py` + (Bank-Erkennung in `app/parsers/detect.py`, gemeinsames Interface in + `app/parsers/base.py`). +3. Tests laufen lassen: + ```bash + cd /home/wlfb/bin/finance && .venv/bin/python -m pytest -q + ``` +4. Image neu bauen und Pod neu aufsetzen, damit die Parser-Änderung im + laufenden Container wirksam wird: + ```bash + cd /home/wlfb/bin && ./create_pod_finance.sh + ``` +5. Import erneut anstoßen (`scan-inbox` bzw. erneuter Upload) und Vorschau + wie unter Schritt 2 prüfen. + +## Grundregeln (siehe auch CLAUDE.md) + +- Importe immer über die Vorschau bestätigen lassen, nie blind übernehmen. +- Echte, bereits bestätigte Buchungen nicht anfassen — nur Entwürfe/Importe + in diesem Workflow bearbeiten. diff --git a/.claude/skills/finanz-api/SKILL.md b/.claude/skills/finanz-api/SKILL.md new file mode 100644 index 0000000..1403a91 --- /dev/null +++ b/.claude/skills/finanz-api/SKILL.md @@ -0,0 +1,123 @@ +--- +name: finanz-api +description: Referenz aller REST-Endpunkte des Finanzberatungs-Tools (Konten, Buchungen, Kategorien, Regeln, Importe, wiederkehrende/geplante Posten, Kredite, Szenarien) mit curl-Beispielen. Use when Claude Code Daten aus dem Finanzberatungs-Tool lesen oder schreiben soll — Konten/Salden abfragen, Buchungen filtern/anlegen/korrigieren, Importe verwalten, Planungsposten oder Szenarien anlegen und durchrechnen. +--- + +# Finanz-API + +REST/JSON unter `http://127.0.0.1:8096/api/…`, vollständig dokumentiert unter +`http://127.0.0.1:8096/docs` (OpenAPI/Swagger). Alle Endpunkte erfordern den +Header `Authorization: Bearer `. + +## Key extrahieren + +```bash +KEY=$(grep '^FB_API_KEY=' /home/wlfb/bin/finance/.env | cut -d= -f2) +``` + +Verwende `$KEY` in allen folgenden Beispielen. Den Key niemals ausgeben, +loggen oder in Antworten an den Nutzer wiederholen. + +## Konten (`/api/accounts`) + +`GET` (Liste inkl. aktuellem Saldo je Konto), `GET /{id}`, `POST` (Konto +anlegen: `bank`, `iban`, `name`, `type`). + +```bash +curl -s -H "Authorization: Bearer $KEY" http://127.0.0.1:8096/api/accounts | jq +``` + +## Buchungen (`/api/transactions`) + +`GET` mit Filtern `account_id`, `date_from`, `date_to`, `category_id`, `q` +(Volltext auf Verwendungszweck/Gegenpartei), `status` (Default `confirmed`), +`limit`/`offset`. `POST` legt eine Buchung manuell an (`force: true` +überschreibt die Duplikat-Prüfung). `PATCH /{id}` ändert **nur** +`category_id` — echte Buchungen sonst nie verändern. + +```bash +curl -s -H "Authorization: Bearer $KEY" \ + "http://127.0.0.1:8096/api/transactions?date_from=2026-01-01&category_id=3&limit=50" | jq +``` + +## Kategorien & Regeln (`/api/categories`, `/api/category-rules`) + +`GET`/`POST /api/categories` (`name`). `GET`/`POST /api/category-rules` +(`pattern`, `category_id`, `priority`) und `DELETE /api/category-rules/{id}`. +Regeln kategorisieren künftige Importe automatisch. + +```bash +curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ + -d '{"pattern": "REWE", "category_id": 3, "priority": 50}' \ + http://127.0.0.1:8096/api/category-rules | jq +``` + +## Importe (`/api/imports`) + +`POST /upload` (multipart, PDF), `POST /scan-inbox` (scannt die Inbox neu), +`GET` (Liste mit Status `draft`/`confirmed`/`error`), `GET /{id}/preview` +(Buchungen + Saldo-Check + Duplikat-Zahl), `POST /{id}/confirm` +(übernimmt die Vorschau endgültig), `DELETE /{id}`. + +```bash +curl -s -X POST -H "Authorization: Bearer $KEY" \ + http://127.0.0.1:8096/api/imports/scan-inbox | jq +``` + +## Wiederkehrende Posten (`/api/recurring`) + +`GET`/`POST` (`name`, `amount`, `rhythm`, `due_day`, `start_date`, +`end_date`, `category_id`), `PATCH`/`DELETE /{id}`, sowie +`GET /recurring/suggestions` (Muster-Erkennung aus importierten Buchungen). + +```bash +curl -s -H "Authorization: Bearer $KEY" \ + http://127.0.0.1:8096/api/recurring/suggestions | jq +``` + +## Geplante Einmalposten (`/api/planned`) + +`GET`/`POST` (`name`, `amount`, `due`, `category_id`), `PATCH`/`DELETE /{id}`. + +```bash +curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ + -d '{"name": "Zahnarzt", "amount": -450.00, "due": "2026-09-01"}' \ + http://127.0.0.1:8096/api/planned | jq +``` + +## Kredite (`/api/loans`) + +`GET`/`POST` (`name`, `principal`, `annual_rate_pct`, `term_months`, +`payout_date`, `repayment_type`: `annuity`|`bullet`), `PATCH`/`DELETE /{id}`, +`GET /{id}/schedule` (Tilgungsplan: Rate, Zins, Tilgung, Restschuld je Termin). + +```bash +curl -s -H "Authorization: Bearer $KEY" \ + http://127.0.0.1:8096/api/loans/1/schedule | jq +``` + +## Szenarien (`/api/scenarios`) + +`GET`/`POST` (`name`, `description`, `include_recurring`, `include_planned`), +`PATCH`/`DELETE /{id}`. Kredit zuordnen: `POST`/`DELETE +/{id}/loans/{loan_id}`. Modifikator hinzufügen: `POST /{id}/modifiers` mit +`target_type` (`category`|`recurring`), `target_id`, `kind` +(`percent`|`absolute`|`remove`), `value`; löschen über `DELETE +/{id}/modifiers/{mod_id}`. + +```bash +curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ + -d '{"name": "Basis-Szenario"}' \ + http://127.0.0.1:8096/api/scenarios | jq +``` + +## Durchrechnen (`/api/scenarios/{id}/project`) + +`POST`, optionale Query-Parameter `horizon_days` und `start_date`. Antwort: +`low_point_date`, `low_point_balance`, `below_zero_date`, +`below_threshold_date`, `series` (Tagesreihe Datum/Saldo). + +```bash +curl -s -X POST -H "Authorization: Bearer $KEY" \ + "http://127.0.0.1:8096/api/scenarios/1/project?horizon_days=180" | jq +``` diff --git a/.claude/skills/finanzberatung/SKILL.md b/.claude/skills/finanzberatung/SKILL.md new file mode 100644 index 0000000..2de0eef --- /dev/null +++ b/.claude/skills/finanzberatung/SKILL.md @@ -0,0 +1,61 @@ +--- +name: finanzberatung +description: Fünf-Schritte-Workflow für Finanzberatung mit dem Finanzberatungs-Tool — Lage erfassen, Basis-Szenario, Varianten (Kredit/Kürzungen) durchrechnen, vergleichen, Empfehlung mit Zahlen begründen. Use when der Nutzer eine Finanzeinschätzung, Kreditberatung, Sparempfehlung oder Liquiditätsplanung ("reicht das Geld", "brauche ich einen Kredit", "wo kann ich kürzen") anfragt. +--- + +# Finanzberatung + +Beratung erfolgt datengetrieben über das Finanzberatungs-Tool (Skill +`finanz-api` für die API-Details). Kein Rat ohne durchgerechnetes Szenario. + +## 1. Lage erfassen + +- Konten und aktuelle Salden abrufen (`GET /api/accounts`). +- Unkategorisierte bzw. auffällige Buchungen prüfen (`GET /api/transactions` + ohne `category_id`-Filter bzw. mit `q`), damit Auswertungen nach Kategorie + belastbar sind. +- Prüfen, ob wiederkehrende Posten gepflegt sind (`GET /api/recurring`); falls + lückenhaft, `GET /api/recurring/suggestions` durchgehen und mit dem Nutzer + bestätigen/verwerfen, bevor weitergerechnet wird. + +## 2. Basis-Szenario anlegen/durchrechnen + +- Falls noch nicht vorhanden: Basis-Szenario anlegen (`POST /api/scenarios`, + ohne Modifikatoren, mit vorhandenen wiederkehrenden/geplanten Posten). +- Durchrechnen (`POST /api/scenarios/{id}/project`) und Ergebnis als + Referenzlinie festhalten (Tiefpunkt, Unterschreitungsdatum falls vorhanden). + +## 3. Fragestellung in Varianten übersetzen + +- Kreditbedarf: Kredit anlegen (`POST /api/loans` mit Betrag, Zinssatz, + Laufzeit, Auszahlungsdatum, Tilgungsart) und dem Szenario zuordnen + (`POST /api/scenarios/{id}/loans/{loan_id}`). +- Kürzungspotenzial: Modifikatoren je Kategorie oder wiederkehrendem Posten + anlegen (`POST /api/scenarios/{id}/modifiers`, `target_type` + `category`|`recurring`, `kind` `percent`|`absolute`|`remove`). +- Für jede Fragestellung ein eigenes Szenario (Kopie der Idee, nicht das + Basis-Szenario verändern), damit Varianten unabhängig vergleichbar bleiben. + +## 4. Varianten durchrechnen + +- Jede Variante mit `POST /api/scenarios/{id}/project` (gleicher Horizont wie + das Basis-Szenario, damit die Vergleichswerte konsistent sind) durchrechnen. +- Bei Kredit-Varianten zusätzlich den Tilgungsplan ziehen + (`GET /api/loans/{id}/schedule`) für Gesamtzinskosten und Ratenhöhe. + +## 5. Vergleichen und Empfehlung formulieren + +- Vergleichstabelle je Variante: Tiefpunkt (Datum + Betrag), + Unterschreitungsdatum (Null bzw. Warnschwelle), bei Krediten + Gesamtzinskosten und monatliche Rate aus dem Tilgungsplan. +- Empfehlung immer mit diesen Zahlen begründen, nicht nur qualitativ. +- Hinweis an den Nutzer: Das Grafana-Dashboard „Szenario-Vergleich“ + (http://127.0.0.1:8097) zeigt die Verlaufskurven der Varianten übereinander + mit Nulllinie und Warnschwelle — für die visuelle Gegenprobe verlinken bzw. + empfehlen, dort nachzusehen. + +## Grundregeln (siehe auch CLAUDE.md) + +- Echte, bestätigte Buchungen nie ändern — Korrekturen nur als + Kategorie-Anpassung. +- Zukunftsplanung ausschließlich über Szenarien, nie am Basis-Datenbestand. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b85ce48 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,18 @@ +# Finanzberatungs-Umgebung + +Beratung und Auswertung laufen auf Deutsch. + +## Finanzberatungs-Tool +- API + Web-GUI: http://127.0.0.1:8096 (OpenAPI: /docs), Grafana: http://127.0.0.1:8097 +- API-Key: `FB_API_KEY` in `/home/wlfb/bin/finance/.env` (Header `Authorization: Bearer `) +- Quellcode/Betrieb: Repo `/home/wlfb/bin` (Pod `finance_pod`, + `systemctl --user status pod-finance_pod.service`) +- Import-Inbox (PDFs hier ablegen): `~/.local/share/finance_pod/data/inbox/` + +## Grundregeln +- Echte (bestätigte) Buchungen niemals ändern oder löschen — Korrekturen nur + als Kategorie-Anpassung; Zukunftsplanung ausschließlich über Szenarien. +- Importe immer über die Vorschau bestätigen lassen, nie blind übernehmen. +- Empfehlungen (Kredit, Kürzungen) stets mit durchgerechneten Szenarien und + Zahlen (Tiefpunkt, Unterschreitungs-Datum, Ratenhöhe) begründen. +- Für API-Nutzung den Skill `finanz-api` verwenden.