Scarriffle/certain
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Phase 2 – Budget-Engine + Direktzugriff (http://IP:Port)

Browse Source 
Budget:
- Modelle + Migration 0003: budget_template_lines, planned_income_lines,
  budget_periods, budget_period_lines.
- services/budget: Perioden-Grenzen (einstellbarer Starttag, Label nach Endmonat),
  Standard-Vorlage vs. Monats-Override (Snapshot-on-Customize), Soll/Ist inkl.
  budgetierter Sparen-Transfers, geplante Einnahmen (Soll/Ist).
- routers/budgets: Vorlage, geplante Einnahmen (CRUD), Monats-Soll/Ist,
  Monats-Override, Zurücksetzen. pytest: Perioden, Soll/Ist, Override/Reset, Einnahmen.
- Frontend: Budget-Seite (Monat + Standard-Budget), Fortschrittsbalken grün/rot,
  Monats-Navigation, editierbare Soll-Beträge; Sparen-Option im Transfer-Formular.

Deployment-Fix (Nutzer-Anforderung: http://IP:Port muss funktionieren):
- Dienst bindet an APP_BIND_HOST=0.0.0.0 (direkt im LAN erreichbar).
- APP_COOKIE_SECURE=false als Standard (sonst kein Login über reines HTTP);
  für reinen HTTPS-Betrieb umstellbar. Doku + install.sh entsprechend angepasst.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Guido
2026-08-19 19:16:27 +02:00
co-authored by Claude Opus 4.8
parent d692c04cc1
commit 8ed4bf5254
21 changed files with 1352 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/app/main.py
+2
View File
@@ -20,6 +20,7 @@ from .migrate import upgrade_to_head
from .routers import (
accounts,
auth,
budgets,
categories,
rates,
settings as settings_router,
@@ -87,6 +88,7 @@ api.include_router(settings_router.router)
api.include_router(accounts.router)
api.include_router(categories.router)
api.include_router(transactions.router)
api.include_router(budgets.router)
api.include_router(rates.router)
app.include_router(api)
backend/app/models.py
+88
View File
@@ -289,3 +289,91 @@ class ExchangeRate(Base):
currency: Mapped[str] = mapped_column(String(3), primary_key=True)
rate_per_eur: Mapped[float] = mapped_column(Numeric(18, 8), nullable=False)
source: Mapped[str] = mapped_column(String(16), nullable=False, default="ecb")
# ---------------------------------------------------------------------------
# Phase 2: Budget (ein Standard-Budget als Vorlage + Monats-Overrides)
# Planned-Beträge sind in der Hauptwährung des Nutzers.
# ---------------------------------------------------------------------------
class BudgetTemplateLine(Base):
"""Standard-Budget je Kategorie (die editierbare Vorlage)."""
__tablename__ = "budget_template_lines"
id: Mapped[int] = mapped_column(Integer, primary_key=True)
owner_id: Mapped[int] = mapped_column(
ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
)
category_id: Mapped[int] = mapped_column(
ForeignKey("categories.id", ondelete="CASCADE"), nullable=False
)
planned_cents: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
__table_args__ = (
UniqueConstraint("owner_id", "category_id", name="uq_tpl_owner_category"),
)
class PlannedIncomeLine(Base):
"""Geplante Einnahme (z. B. Gehalt) mit optionaler Kategorie und Zielkonto."""
__tablename__ = "planned_income_lines"
id: Mapped[int] = mapped_column(Integer, primary_key=True)
owner_id: Mapped[int] = mapped_column(
ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
)
label: Mapped[str] = mapped_column(String(120), nullable=False)
category_id: Mapped[int | None] = mapped_column(
ForeignKey("categories.id", ondelete="SET NULL"), nullable=True
)
target_account_id: Mapped[int | None] = mapped_column(
ForeignKey("accounts.id", ondelete="SET NULL"), nullable=True
)
planned_cents: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
position: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
class BudgetPeriod(Base):
"""Ein Budget-Monat. Existiert erst, sobald der Monat angepasst wurde."""
__tablename__ = "budget_periods"
id: Mapped[int] = mapped_column(Integer, primary_key=True)
owner_id: Mapped[int] = mapped_column(
ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
)
label: Mapped[str] = mapped_column(String(7), nullable=False) # YYYY-MM (End-/Hauptmonat)
customized: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
lines: Mapped[list[BudgetPeriodLine]] = relationship(
back_populates="period", cascade="all, delete-orphan"
)
__table_args__ = (
UniqueConstraint("owner_id", "label", name="uq_period_owner_label"),
)
class BudgetPeriodLine(Base):
"""Monatsspezifischer Budget-Wert (Snapshot-on-Customize)."""
__tablename__ = "budget_period_lines"
id: Mapped[int] = mapped_column(Integer, primary_key=True)
budget_period_id: Mapped[int] = mapped_column(
ForeignKey("budget_periods.id", ondelete="CASCADE"), nullable=False, index=True
)
category_id: Mapped[int] = mapped_column(
ForeignKey("categories.id", ondelete="CASCADE"), nullable=False
)
planned_cents: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
period: Mapped[BudgetPeriod] = relationship(back_populates="lines")
__table_args__ = (
UniqueConstraint("budget_period_id", "category_id", name="uq_periodline_period_category"),
)
backend/app/routers/budgets.py
+256
View File
@@ -0,0 +1,256 @@
"""Budget: Standard-Vorlage, geplante Einnahmen und die Monats-Soll/Ist-Ansicht."""
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.orm import Session
from ..database import get_db
from ..deps import get_current_user, get_owned
from ..models import (
Account,
BudgetTemplateLine,
Category,
CategoryGroup,
CategoryKind,
PlannedIncomeLine,
User,
)
from ..schemas import PlannedIncomeCreate, PlannedIncomeOut, PlannedIncomeUpdate
from ..services import budget
from .accounts import base_currency
from .settings import BUDGET_START_DAY_KEY, get_user_setting
router = APIRouter(prefix="/budget", tags=["budget"])
def _start_day(db: Session, user: User) -> int:
try:
return max(1, min(31, int(get_user_setting(db, user, BUDGET_START_DAY_KEY) or "1")))
except ValueError:
return 1
def _require_expense_category(db: Session, user: User, category_id: int) -> Category:
cat = get_owned(db, Category, category_id, user)
if cat.type != CategoryKind.expense:
raise HTTPException(status.HTTP_400_BAD_REQUEST, "Nur Ausgabe-Kategorien sind budgetierbar")
return cat
# --- Standard-Vorlage ------------------------------------------------------
@router.get("/template")
def get_template(db: Session = Depends(get_db), user: User = Depends(get_current_user)) -> dict:
lines = db.query(BudgetTemplateLine).filter(BudgetTemplateLine.owner_id == user.id).all()
income = (
db.query(PlannedIncomeLine)
.filter(PlannedIncomeLine.owner_id == user.id)
.order_by(PlannedIncomeLine.position, PlannedIncomeLine.id)
.all()
)
return {
"lines": [{"category_id": ln.category_id, "planned_cents": ln.planned_cents} for ln in lines],
"income": [PlannedIncomeOut.model_validate(i).model_dump() for i in income],
}
@router.put("/template/category/{category_id}")
def set_template_category(
category_id: int,
planned_cents: int,
db: Session = Depends(get_db),
user: User = Depends(get_current_user),
) -> dict:
_require_expense_category(db, user, category_id)
line = (
db.query(BudgetTemplateLine)
.filter(BudgetTemplateLine.owner_id == user.id, BudgetTemplateLine.category_id == category_id)
.first()
)
if planned_cents <= 0:
if line is not None:
db.delete(line)
db.commit()
return {"category_id": category_id, "planned_cents": 0}
if line is None:
line = BudgetTemplateLine(owner_id=user.id, category_id=category_id, planned_cents=planned_cents)
db.add(line)
else:
line.planned_cents = planned_cents
db.commit()
return {"category_id": category_id, "planned_cents": planned_cents}
# --- Geplante Einnahmen ----------------------------------------------------
@router.post("/income", response_model=PlannedIncomeOut, status_code=status.HTTP_201_CREATED)
def create_income(
payload: PlannedIncomeCreate, db: Session = Depends(get_db), user: User = Depends(get_current_user)
):
if payload.category_id is not None:
get_owned(db, Category, payload.category_id, user)
if payload.target_account_id is not None:
get_owned(db, Account, payload.target_account_id, user)
max_pos = (
db.query(PlannedIncomeLine.position)
.filter(PlannedIncomeLine.owner_id == user.id)
.order_by(PlannedIncomeLine.position.desc())
.first()
)
line = PlannedIncomeLine(
owner_id=user.id,
label=payload.label.strip(),
category_id=payload.category_id,
target_account_id=payload.target_account_id,
planned_cents=payload.planned_cents,
position=(max_pos[0] + 1) if max_pos else 0,
)
db.add(line)
db.commit()
db.refresh(line)
return line
@router.patch("/income/{income_id}", response_model=PlannedIncomeOut)
def update_income(
income_id: int,
payload: PlannedIncomeUpdate,
db: Session = Depends(get_db),
user: User = Depends(get_current_user),
):
line = get_owned(db, PlannedIncomeLine, income_id, user)
data = payload.model_dump(exclude_unset=True)
if "category_id" in data and data["category_id"] is not None:
get_owned(db, Category, data["category_id"], user)
if "target_account_id" in data and data["target_account_id"] is not None:
get_owned(db, Account, data["target_account_id"], user)
for key, value in data.items():
setattr(line, key, value)
db.commit()
db.refresh(line)
return line
@router.delete("/income/{income_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_income(
income_id: int, db: Session = Depends(get_db), user: User = Depends(get_current_user)
) -> None:
line = get_owned(db, PlannedIncomeLine, income_id, user)
db.delete(line)
db.commit()
# --- Soll/Ist-Ansicht ------------------------------------------------------
def _build_view(db: Session, user: User, label: str) -> dict:
base = base_currency(db, user)
start_day = _start_day(db, user)
start, end = budget.period_bounds(label, start_day)
planned = budget.effective_planned(db, user, label)
actual = budget.actual_expense_by_category(db, user, start, end, base)
income_actual = budget.income_by_category(db, user, start, end, base)
groups_out = []
total_planned = total_actual = 0
groups = (
db.query(CategoryGroup)
.filter(CategoryGroup.owner_id == user.id, CategoryGroup.kind == CategoryKind.expense)
.order_by(CategoryGroup.position, CategoryGroup.name)
.all()
)
for g in groups:
cats = []
g_planned = g_actual = 0
for c in sorted(g.categories, key=lambda x: (x.position, x.name.lower())):
if c.is_archived:
continue
p = planned.get(c.id, 0)
a = actual.get(c.id, 0)
g_planned += p
g_actual += a
cats.append({
"category_id": c.id, "name": c.name, "icon": c.icon, "color": c.color,
"planned_cents": p, "actual_cents": a, "delta_cents": p - a, "over": a > p,
})
total_planned += g_planned
total_actual += g_actual
groups_out.append({
"id": g.id, "name": g.name, "icon": g.icon, "color": g.color,
"planned_cents": g_planned, "actual_cents": g_actual, "over": g_actual > g_planned,
"categories": cats,
})
income_lines = (
db.query(PlannedIncomeLine)
.filter(PlannedIncomeLine.owner_id == user.id)
.order_by(PlannedIncomeLine.position, PlannedIncomeLine.id)
.all()
)
income_out = []
total_planned_income = total_received_income = 0
for ln in income_lines:
received = income_actual.get(ln.category_id, 0) if ln.category_id else 0
total_planned_income += ln.planned_cents
total_received_income += received
income_out.append({
"id": ln.id, "label": ln.label, "category_id": ln.category_id,
"target_account_id": ln.target_account_id,
"planned_cents": ln.planned_cents, "received_cents": received,
})
return {
"label": label,
"start": start.isoformat(),
"end": end.isoformat(),
"customized": budget.is_customized(db, user, label),
"base_currency": base,
"prev": budget.shift_label(label, -1),
"next": budget.shift_label(label, 1),
"groups": groups_out,
"income": income_out,
"totals": {
"planned_expense": total_planned,
"actual_expense": total_actual,
"planned_income": total_planned_income,
"received_income": total_received_income,
},
}
@router.get("/current")
def current(db: Session = Depends(get_db), user: User = Depends(get_current_user)) -> dict:
return _build_view(db, user, budget.current_label(_start_day(db, user)))
@router.get("/{label}")
def view(label: str, db: Session = Depends(get_db), user: User = Depends(get_current_user)) -> dict:
try:
budget.parse_label(label)
except (ValueError, IndexError):
raise HTTPException(status.HTTP_400_BAD_REQUEST, "Ungültiges Monats-Label (YYYY-MM)")
return _build_view(db, user, label)
@router.put("/{label}/category/{category_id}")
def set_month_category(
label: str,
category_id: int,
planned_cents: int,
db: Session = Depends(get_db),
user: User = Depends(get_current_user),
) -> dict:
budget.parse_label(label)
_require_expense_category(db, user, category_id)
budget.set_month_category(db, user, label, category_id, max(0, planned_cents))
return _build_view(db, user, label)
@router.delete("/{label}")
def reset_month(
label: str, db: Session = Depends(get_db), user: User = Depends(get_current_user)
) -> dict:
budget.parse_label(label)
budget.reset_month(db, user, label)
return _build_view(db, user, label)
backend/app/schemas.py
+28
View File
@@ -255,3 +255,31 @@ class ConversionOut(BaseModel):
date: date_t
converted_cents: int | None
rate: float | None
# --- Budget: geplante Einnahmen --------------------------------------------
class PlannedIncomeCreate(BaseModel):
label: str = Field(min_length=1, max_length=120)
category_id: int | None = None
target_account_id: int | None = None
planned_cents: int = Field(ge=0)
class PlannedIncomeUpdate(BaseModel):
label: str | None = Field(default=None, min_length=1, max_length=120)
category_id: int | None = None
target_account_id: int | None = None
planned_cents: int | None = Field(default=None, ge=0)
class PlannedIncomeOut(BaseModel):
model_config = ConfigDict(from_attributes=True)
id: int
label: str
category_id: int | None
target_account_id: int | None
planned_cents: int
position: int
backend/app/services/budget.py
+198
View File
@@ -0,0 +1,198 @@
"""Budget-Engine: Perioden-Grenzen, Standard-Vorlage vs. Monats-Override, Soll/Ist.
Der Budget-Monat hat einen einstellbaren Starttag D. Ein Zeitraum ist nach seinem
End-/Hauptmonat benannt (YYYY-MM):
- D <= 1: der Kalendermonat.
- D >= 2: [Tag D des Vormonats … Tag D-1 des Hauptmonats].
Planned-Beträge liegen in der Hauptwährung des Nutzers; Ist-Werte werden über den
eingefrorenen EUR-Wert je Buchung in die Hauptwährung umgerechnet.
"""
import calendar
from collections import defaultdict
from datetime import date, timedelta
from dateutil.relativedelta import relativedelta
from sqlalchemy.orm import Session
from ..models import (
Account,
BudgetPeriod,
BudgetPeriodLine,
BudgetTemplateLine,
BudgetTreatment,
CategoryKind,
SAVINGS_ACCOUNT_TYPES,
Transaction,
TxnType,
User,
)
from . import currency
# --- Perioden --------------------------------------------------------------
def _clamp_day(year: int, month: int, day: int) -> date:
last = calendar.monthrange(year, month)[1]
return date(year, month, min(day, last))
def parse_label(label: str) -> tuple[int, int]:
y, m = label.split("-")
return int(y), int(m)
def period_bounds(label: str, start_day: int) -> tuple[date, date]:
"""(start, end) inklusive für einen Budget-Monat."""
y, m = parse_label(label)
if start_day <= 1:
return date(y, m, 1), date(y, m, calendar.monthrange(y, m)[1])
prev = date(y, m, 1) - relativedelta(months=1)
start = _clamp_day(prev.year, prev.month, start_day)
end = _clamp_day(y, m, start_day) - timedelta(days=1)
return start, end
def period_of(d: date, start_day: int) -> str:
"""Label des Budget-Monats, in den ein Datum fällt."""
if start_day <= 1:
return f"{d.year:04d}-{d.month:02d}"
if d.day >= start_day:
nxt = date(d.year, d.month, 1) + relativedelta(months=1)
return f"{nxt.year:04d}-{nxt.month:02d}"
return f"{d.year:04d}-{d.month:02d}"
def shift_label(label: str, months: int) -> str:
y, m = parse_label(label)
d = date(y, m, 1) + relativedelta(months=months)
return f"{d.year:04d}-{d.month:02d}"
def current_label(start_day: int) -> str:
return period_of(date.today(), start_day)
# --- Vorlage vs. Monats-Override ------------------------------------------
def _period(db: Session, user: User, label: str) -> BudgetPeriod | None:
return (
db.query(BudgetPeriod)
.filter(BudgetPeriod.owner_id == user.id, BudgetPeriod.label == label)
.first()
)
def effective_planned(db: Session, user: User, label: str) -> dict[int, int]:
"""Wirksame Soll-Beträge je Kategorie: Monats-Override falls vorhanden, sonst Vorlage."""
period = _period(db, user, label)
if period is not None:
return {ln.category_id: ln.planned_cents for ln in period.lines}
return {
tl.category_id: tl.planned_cents
for tl in db.query(BudgetTemplateLine).filter(BudgetTemplateLine.owner_id == user.id)
}
def is_customized(db: Session, user: User, label: str) -> bool:
return _period(db, user, label) is not None
def ensure_customized(db: Session, user: User, label: str) -> BudgetPeriod:
"""Legt (falls nötig) die Monats-Periode an und übernimmt einmalig die Vorlage."""
period = _period(db, user, label)
if period is None:
period = BudgetPeriod(owner_id=user.id, label=label, customized=True)
db.add(period)
db.flush()
for tl in db.query(BudgetTemplateLine).filter(BudgetTemplateLine.owner_id == user.id):
period.lines.append(
BudgetPeriodLine(category_id=tl.category_id, planned_cents=tl.planned_cents)
)
db.flush()
return period
def set_month_category(db: Session, user: User, label: str, category_id: int, planned_cents: int) -> None:
period = ensure_customized(db, user, label)
line = next((ln for ln in period.lines if ln.category_id == category_id), None)
if line is None:
period.lines.append(BudgetPeriodLine(category_id=category_id, planned_cents=planned_cents))
else:
line.planned_cents = planned_cents
db.commit()
def reset_month(db: Session, user: User, label: str) -> None:
period = _period(db, user, label)
if period is not None:
db.delete(period)
db.commit()
# --- Ist-Werte -------------------------------------------------------------
def _to_base(db: Session, eur_cents: int, base: str, on: date) -> int:
if base == "EUR":
return eur_cents
conv = currency.from_eur_cents(db, eur_cents, base, on)
return conv if conv is not None else eur_cents
def actual_expense_by_category(db: Session, user: User, start: date, end: date, base: str) -> dict[int, int]:
"""Ist-Ausgaben je Kategorie in Hauptwährung (inkl. budgetierter Sparen-Transfers)."""
result: dict[int, int] = defaultdict(int)
expenses = (
db.query(Transaction)
.filter(
Transaction.owner_id == user.id,
Transaction.type == TxnType.expense,
Transaction.date >= start,
Transaction.date <= end,
Transaction.category_id.isnot(None),
)
.all()
)
for t in expenses:
result[t.category_id] += _to_base(db, t.amount_eur_cents, base, t.date)
# Transfers auf Sparen/Depot zählen (sofern nicht auf "neutral" gesetzt) als
# budgetierte Ausgabe gegen budget_category_id.
transfers = (
db.query(Transaction)
.filter(
Transaction.owner_id == user.id,
Transaction.type == TxnType.transfer,
Transaction.date >= start,
Transaction.date <= end,
Transaction.budget_category_id.isnot(None),
)
.all()
)
for t in transfers:
if t.budget_treatment == BudgetTreatment.neutral:
continue
to_acc = db.get(Account, t.to_account_id) if t.to_account_id else None
if to_acc is not None and to_acc.type in SAVINGS_ACCOUNT_TYPES:
result[t.budget_category_id] += _to_base(db, t.amount_eur_cents, base, t.date)
return result
def income_by_category(db: Session, user: User, start: date, end: date, base: str) -> dict[int | None, int]:
result: dict[int | None, int] = defaultdict(int)
incomes = (
db.query(Transaction)
.filter(
Transaction.owner_id == user.id,
Transaction.type == TxnType.income,
Transaction.date >= start,
Transaction.date <= end,
)
.all()
)
for t in incomes:
result[t.category_id] += _to_base(db, t.amount_eur_cents, base, t.date)
return result