release: publish saldo 0.1.0

2026-04-21 21:17:36 +02:00
commit 6f5e704739
95 changed files with 9196 additions and 0 deletions
@@ -0,0 +1,51 @@
+# Saldo Architektur
+
+## Zielbild
+
+Saldo ist eine mobile-first Flask-PWA für monatliche Haushaltsplanung. Der Schwerpunkt liegt auf wiederkehrenden Kosten, variablen Einkommen, Restverteilung und externer Beteiligung ohne Benutzerkonto.
+
+## Schichten
+
+`app/__init__.py`
+Initialisiert App-Factory, Extensions, Logging, Blueprints und CLI-Kommandos.
+
+`app/models.py`
+Enthält das relationale Kernmodell für Monate, Kostenstruktur, Einkommen, Verteilungen, Beteiligungsregeln und Benachrichtigungen.
+
+`app/services/month_service.py`
+Domänenlogik für automatische Monatsanlage, Seed-Fallback, Kopieren eines Monats und Berechnung zentraler Kennzahlen.
+
+`app/services/allocation_service.py`
+Regel-Engine für Vorschlagsverteilungen. Gesperrte Zielkonten bleiben unangetastet, der restliche Betrag wird gewichtet verteilt.
+
+`app/services/comparison_service.py`
+Vergleicht Monate und erzeugt Deltas sowie Top-Veränderungen.
+
+`app/services/share_service.py`
+Berechnet interne und externe Anteile pro Eintrag und aggregiert externe Forderungen pro Monat.
+
+`app/services/notification_service.py`
+Erstellt In-App-Hinweise und triggert optional Web-Push für Monatsende, fehlende Verteilung und starke Einkommensänderungen.
+
+## Request Flow
+
+1. Authentifizierter Request startet.
+2. `before_request` ruft `MonthService.ensure_month()` auf.
+3. Falls der aktuelle Kalendermonat fehlt, wird er automatisch aus dem jüngsten Monat erzeugt.
+4. Views lesen die Monatszusammenfassung über `compute_summary()`.
+5. Änderungen an Einkommen oder Planwerten triggern `refresh_suggestions()`.
+6. Benutzer übernehmen Vorschläge komplett oder zielkontenweise.
+
+## Datenhaltung
+
+- Standard: SQLite
+- Pfad per `DATABASE_URL` oder `SALDO_DATA_DIR`
+- SQLAlchemy-Modelle sind bewusst nicht SQLite-spezifisch, damit ein Wechsel auf PostgreSQL später möglich bleibt
+
+## Deployment
+
+- WSGI-Entry: `wsgi.py`
+- Produktionsserver: Gunicorn
+- Healthcheck: `/health`
+- Migrationen: Flask-Migrate/Alembic in `migrations/`
+- Cloudron-Datenpfad: `/app/data`