# moneyfy

Selbst gehostete Web-Anwendung zur Planung monatlicher Kosten und Einkünfte.
Single-User, deutschsprachige Oberfläche, ausgelegt für den Betrieb im Homelab
hinter einem Reverse Proxy.

> **Status:** in Entwicklung. Siehe [CHANGELOG.md](CHANGELOG.md).

## Screenshots

_Platzhalter – werden ergänzt, sobald die Oberfläche steht._

| Dashboard | Cashflow-Kalender | Firmen |
|---|---|---|
| _folgt_ | _folgt_ | _folgt_ |

## Funktionsumfang

- Wiederkehrende Zahlungen und Einkünfte über vollständige RFC-5545-RRULEs,
  inklusive Werktagsverschiebung nach NRW-Feiertagen.
- Preishistorie je Vertrag, sodass vergangene Monate betragstreu bleiben.
- Verträge mit Mindestlaufzeit, Kündigungsfrist und automatischer Verlängerung.
- Ratenzahlungen mit Restschuld- und Restratenberechnung.
- Rücklagenbildung für nicht-monatliche Posten.
- Firmenlogos und Markenfarben, lokal zwischengespeichert (siehe unten).
- Auswertungen: Monatsübersicht, Cashflow-Kalender, 12-Monats-Forecast,
  Kategorien, Abo-Übersicht, Jahresvergleich, Budgets, Sparziele.
- Benachrichtigungen per SMTP und Apprise.

## Technischer Stack

| Bereich | Technologie |
|---|---|
| Backend | Python 3.12, FastAPI, SQLAlchemy 2 (async), Alembic, Pydantic v2 |
| Datenbank | PostgreSQL 17 |
| Scheduler | APScheduler (in-process) |
| Frontend | React 18, TypeScript, Vite, TailwindCSS |
| Charts | Recharts |
| Tests | pytest + httpx, vitest + testing-library |

## Schnellstart (Betrieb)

Voraussetzungen: Docker mit Compose-Plugin und ein externes Netz `proxy`.

```bash
mkdir -p /opt/moneyfy && cd /opt/moneyfy
curl -fsSLO https://git.menzel.center/menzeljonas/moneyfy/raw/branch/main/docker-compose.yml
curl -fsSLO https://git.menzel.center/menzeljonas/moneyfy/raw/branch/main/.env.example
cp .env.example .env

# Mindestens setzen: POSTGRES_PASSWORD, SECRET_KEY, MONEYFY_ADMIN_PASSWORD
$EDITOR .env

docker login git.menzel.center
docker compose up -d
```

Das Backend wartet auf die Datenbank, spielt die Migrationen ein und legt beim
allerersten Start den Kategoriebaum an. Danach läuft die Oberfläche auf
`http://127.0.0.1:8087`. Die vollständige Einrichtung samt Reverse Proxy und
Sicherung steht in [docs/deployment.md](docs/deployment.md).

## Schnellstart (lokale Entwicklung)

Voraussetzungen: Python 3.12, [uv](https://docs.astral.sh/uv/), Node 20+,
eine erreichbare PostgreSQL-17-Instanz.

```bash
git clone https://git.menzel.center/menzeljonas/moneyfy.git
cd moneyfy
cp .env.example backend/.env      # DATABASE_URL und SECRET_KEY anpassen

make install                      # Backend-Abhängigkeiten in backend/.venv
make migrate                      # Schema anlegen
make seed                         # Kategoriebaum und Standardregeln
make dev                          # http://localhost:8000/api/docs
```

In einem zweiten Terminal das Frontend, es leitet `/api` an das Backend weiter:

```bash
make fe-install
make fe-dev                       # http://localhost:5173
```

Nützliche Ziele: `make check` (alle Prüfungen), `make test`, `make lint`,
`make format`, `make fe-lint`, `make fe-test`, `make fe-build`.

## Konfiguration

Alle Einstellungen kommen aus Umgebungsvariablen; `.env.example` enthält die
vollständige, kommentierte Liste. Die wichtigsten:

| Variable | Standard | Bedeutung |
|---|---|---|
| `DATABASE_URL` | – | PostgreSQL-DSN, `postgresql://` wird auf asyncpg umgestellt |
| `SECRET_KEY` | – | Signaturschlüssel für JWTs, mind. 32 Zeichen (`openssl rand -hex 32`) |
| `MONEYFY_ADMIN_USER` / `MONEYFY_ADMIN_PASSWORD` | `admin` / – | Beim Erststart angelegter Benutzer |
| `TIMEZONE` | `Europe/Berlin` | Zeitzone der gesamten Anwendung |
| `HOLIDAY_REGION` | `DE-NW` | Feiertagsregion für Werktagsverschiebungen |
| `LOGO_STORAGE_DIR` | `/data/logos` | Verzeichnis des Logo-Caches |
| `LOGODEV_API_KEY` / `BRANDFETCH_API_KEY` | leer | Optionale Logo-Provider, ohne Schlüssel übersprungen |
| `SMTP_*` | leer | Mailversand für Benachrichtigungen |
| `APPRISE_URLS` | leer | Komma-separierte Apprise-Ziele |
| `COOKIE_SECURE` | `true` | Hinter HTTPS `true`, für lokales HTTP `false` |
| `SCHEDULER_ENABLED` | `true` | Täglicher Benachrichtigungslauf um 07:00 |

## Benachrichtigungen

Ein Job läuft täglich um 07:00 Uhr (`Europe/Berlin`) im Anwendungsprozess – ohne
Redis, ohne Celery. Er prüft vier Anlässe: bald fällige Posten, Kündigungsfristen
30, 14 und 7 Tage vor dem Termin, überschrittene Budgets und Vertragsverlängerungen
im kommenden Monat.

Der Duplikatsschutz hängt am **Zieltag des Ereignisses**, nicht am Versandtag:
Eine Fälligkeit am 15.03. wird genau einmal gemeldet, unabhängig davon, an
welchem Tag des Vorlaufs der Job läuft. Ein fehlgeschlagener Versand gilt als
offen und wird beim nächsten Lauf erneut versucht.

Als Kanäle stehen SMTP (HTML-Mail mit eingebetteten Firmenlogos) und Apprise zur
Verfügung. Über *Einstellungen → Benachrichtigungen* lassen sich Regeln pflegen,
eine Testnachricht verschicken und das Versandprotokoll einsehen.

## Diagramme

Die Serienfarben stammen aus einer Palette, die gegen die hellen und dunklen
Flächen der Anwendung auf Kontrast und Farbfehlsichtigkeit geprüft wurde; ihre
Reihenfolge ist Teil dieser Absicherung. Grün und Rot bleiben den Vorzeichen im
Text vorbehalten – als Serienpaar wären sie bei Deuteranopie nicht zu
unterscheiden. Jedes Diagramm mit mehr als einer Serie führt eine Legende, und
zu den Balkendiagrammen lässt sich die Wertetabelle aufklappen.

Einnahmen, Ausgaben und der kumulierte Kontostand stehen bewusst in zwei
getrennten Diagrammen untereinander: eine gemeinsame Größenachse würde bei so
verschiedenen Größenordnungen einen Zusammenhang vortäuschen.

## Logos und Markenfarben

Jede Firma bekommt ein Bild. Die Provider-Kette arbeitet der Reihe nach:

1. **simple-icons** – rund 3.500 Marken, im Repository unter
   `backend/app/assets/simple_icons.json.gz` mitgeliefert. Kein Schlüssel, kein
   Netzzugriff. Neu erzeugen mit `make vendor-icons`.
2. **logo.dev** – nur mit `LOGODEV_API_KEY`.
3. **Brandfetch** – nur mit `BRANDFETCH_API_KEY` und hinterlegter Domain.
4. **Favicon** – über den Google-Dienst, wenn eine Domain bekannt oder aus dem
   Namen ableitbar ist.
5. **Generierter Avatar** – Buchstaben-Monogramm mit fester Farbe aus dem
   Namens-Hash. Schlägt nie fehl.

Findet die Kette einen eindeutigen Treffer im lokalen Katalog, unterbleiben die
Anfragen nach außen vollständig – die Firmenliste verlässt den Server nicht. Im
Auswahldialog (`POST /api/merchants/{id}/logo/search`) läuft dagegen bewusst die
ganze Kette, damit Alternativen zur Wahl stehen.

Ausgewählte Logos landen unter `LOGO_STORAGE_DIR`, benannt nach ihrem
SHA-256-Hash, und werden nur über `GET /api/logos/{id}` ausgeliefert. Beim
Seitenaufruf entsteht dadurch kein Zugriff auf fremde Dienste. Ein Upload oder
eine bewusste Auswahl setzt den Status auf `manual` und wird von der Automatik
nie überschrieben.

## Projektstruktur

```
backend/     FastAPI-Anwendung, Modelle, Services, Alembic-Migrationen, Tests
frontend/    React-Oberfläche (Vite)
docs/        Betriebs- und Runner-Dokumentation
.gitea/      Gitea-Actions-Workflows
```

Alternativ lässt sich alles aus dem Quellcode bauen:

```bash
cp docker-compose.override.yml.example docker-compose.override.yml
docker compose up -d --build
```

Die Override-Datei baut beide Images lokal, bindet den Quellcode ein und öffnet
die Ports für Backend (8000) und Vite (5173).

## Bauen und Ausrollen

Zwei Gitea-Workflows unter `.gitea/workflows/`:

- **`ci.yml`** läuft bei jedem Push und Pull Request: `ruff`, `pytest`,
  `tsc --noEmit`, `eslint`, `vitest` und der Bundle-Bau.
- **`build.yml`** läuft auf `main` und bei Tags `v*` und lädt beide Images für
  `linux/amd64` in die Gitea-Registry. Push auf `main` erzeugt `:main` und
  `:sha-<kurz>`, ein Tag `v1.2.3` zusätzlich `:1.2.3`, `:1.2` und `:latest`.

Ausgerollt wird **nicht** automatisch. Die Einrichtung des Runners beschreibt
[docs/runner.md](docs/runner.md), das Ausrollen [docs/deployment.md](docs/deployment.md).

## Lizenz

[MIT](LICENSE)