Some more refactoring

AGENTS.md

@@ -71,7 +71,7 @@ Two sources with shared patterns:
 - **comdirect**: `ComdirectGiro`, `ComdirectCreditCard`, `ComdirectDepot`, import to `comdirect_giro` table
 - **unified**: `Transaction`, `TransactionDb` – both ingest pipelines project their staging rows (`import_b4w`, `comdirect_giro`) into one `transactions` table via `src/ingest/transactions.py` (`map_*` mappers + `consolidate_transactions`). Dedup uses a business-key `hash_id` (source + IBAN + value date + amount + text + counterparty) with a UNIQUE constraint and SQLite `INSERT OR IGNORE`, so re-imports are idempotent. Amounts are canonical signed (negative = money out). Depot/credit-card/tagesgeld are not projected yet.
 
-All models inherit from common base in `src/models/_common.py`:
+All models inherit from common base in `src/models/common.py`:
 - `_hash()`: SHA256-based deduplication key
 - `_parse_date_german()`: Handles "07.09.2026" format and values like "offen", "--"
 - `_parse_decimal_german()`: Converts "1,23" to Decimal

alembic/env.py

@@ -6,7 +6,7 @@ from sqlalchemy import engine_from_config, pool
 
 from alembic import context
 from src.db import get_set_engine
-from src.models._common import BaseModelDb
+from src.models.common import BaseModelDb
 
 load_dotenv()  # reads .env into os.environ
 

alembic/versions/fe23064de1c5_create_category_budget_table.py

@@ -0,0 +1,52 @@
+"""create category_budget table
+
+Revision ID: fe23064de1c5
+Revises: 78ec55b9e1d1
+Create Date: 2026-10-16 10:43:24.952699
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "fe23064de1c5"
+down_revision: str | Sequence[str] | None = "78ec55b9e1d1"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "category_budget",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("category_id", sa.Integer(), nullable=False),
+        sa.Column("amount_eur", sa.Numeric(precision=12, scale=2), nullable=False),
+        sa.Column("valid_from", sa.Date(), nullable=True),
+        sa.Column("valid_to", sa.Date(), nullable=True),
+        sa.ForeignKeyConstraint(
+            ["category_id"],
+            ["category.id"],
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "ix_category_budget_category_id",
+        "category_budget",
+        ["category_id"],
+        unique=False,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index("ix_category_budget_category_id", table_name="category_budget")
+    op.drop_table("category_budget")
+    # ### end Alembic commands ###

src/db_utils.py

@@ -1,20 +1,16 @@
-import csv
-from pathlib import Path
 from typing import Any
 
-from sqlalchemy.orm import Session
-
-from src.models._common import BaseModelDb
+from sqlalchemy.orm import DeclarativeBase, Session
 
 
-def _query_existing(
-    session: Session, DbModel: type[BaseModelDb], query_parameters: dict[str, Any]
-) -> BaseModelDb | None:
+def _query_existing[DbModelT: DeclarativeBase](
+    session: Session, DbModel: type[DbModelT], query_parameters: dict[str, Any]
+) -> DbModelT | None:
     query = session.query(DbModel).filter_by(**query_parameters)
     return query.first()
 
 
-def _upsert[DbModelT: BaseModelDb](
+def upsert[DbModelT: DeclarativeBase](
     session: Session,
     DbModel: type[DbModelT],
     parameters_existing: dict[str, Any],
@@ -28,7 +24,6 @@ def _upsert[DbModelT: BaseModelDb](
         if do_update:
             for key, value in parameters_new.items():
                 setattr(existing_db_row, key, value)
-        assert isinstance(existing_db_row, DbModel)
         return existing_db_row
 
     new_db_row = DbModel(**parameters_new)
@@ -37,8 +32,3 @@ def _upsert[DbModelT: BaseModelDb](
     if do_commit:
         session.commit()
     return new_db_row
-
-
-def _reader_raw(path: Path):
-    with path.open() as fid:
-        return list(csv.DictReader(fid))

src/helper/__init__.py

@@ -0,0 +1 @@
+"""Database helper for application-specific persistence operations."""

src/helper/category.py

@@ -0,0 +1,22 @@
+from sqlalchemy.orm import Session
+
+from src.db_utils import upsert
+from src.models.category import Category, CategoryDb
+
+
+def upsert_category(
+    session: Session, category: Category | None, do_commit: bool = True
+) -> CategoryDb | None:
+    if category is None:
+        return None
+
+    parent = upsert_category(session, category.parent, do_commit=False)
+    parameters = {"name": category.name, "parent": parent}
+    return upsert(
+        session,
+        CategoryDb,
+        parameters,
+        parameters,
+        do_update=False,
+        do_commit=do_commit,
+    )

src/ingest/b4w.py

@@ -2,9 +2,11 @@ from pathlib import Path
 
 from sqlalchemy.orm import Session
 
-from src.ingest._common import _reader_raw, _upsert
+from src.db_utils import upsert
+from src.helper.category import upsert_category
+from src.ingest.common import _reader_raw
 from src.ingest.transactions import consolidate_transactions, map_b4w_to_transaction
-from src.models.b4w import B4wDb, B4wExport, Category, CategoryDb
+from src.models.b4w import B4wDb, B4wExport
 
 
 def reader_b4w(path: Path) -> list[B4wExport]:
@@ -12,25 +14,6 @@ def reader_b4w(path: Path) -> list[B4wExport]:
     return list(map(B4wExport.model_validate, raw))
 
 
-def upsert_category(
-    session: Session, category: Category | None, do_commit=True
-) -> CategoryDb | None:
-    if category is None:
-        return None
-    parameters = {
-        "name": category.name,
-        "parent": upsert_category(session, category.parent),
-    }
-    return _upsert(
-        session,
-        CategoryDb,
-        parameters,
-        parameters,
-        do_update=False,
-        do_commit=do_commit,
-    )
-
-
 def upsert_b4w(
     session: Session, data: B4wExport, do_update=False, do_commit=True
 ) -> B4wDb | None:
@@ -54,7 +37,7 @@ def upsert_b4w(
         "notes": data.notes,
     }
 
-    return _upsert(
+    return upsert(
         session,
         B4wDb,
         parameters_existing,

src/ingest/comdirect.py

@@ -6,18 +6,18 @@ from typing import cast
 from sqlalchemy.orm import Session
 
 from settings import BANK_ACCOUNTS
-from src.ingest._common import _upsert
+from src.db_utils import upsert
 from src.ingest.transactions import (
     consolidate_transactions,
     map_comdirect_giro_to_transaction,
 )
-from src.models._common import Csv2Dict, CsV2DictMulti
 from src.models.comdirect import (
     ComdirectCreditCard,
     ComdirectDepot,
     ComdirectGiro,
     ComdirectGiroDb,
 )
+from src.models.common import Csv2Dict, CsV2DictMulti
 from src.models.settings import Account, Source
 
 PATTERN_ACCOUNT_NAME = r'^"Umsätze ([^"]+)";"Zeitraum: .*$'
@@ -73,6 +73,10 @@ def _reader_raw_comdirect(path: Path) -> CsV2DictMulti:
     account_name: str | None = None
     header: list[str] = []
     result: CsV2DictMulti = {}
+    # Comdirect groups "new" transactions (marked with "neu") under a header
+    # line that carries only their Buchungstag; remember it until the next
+    # transaction row for the same account.
+    pending_book_date: dict[str, str] = {}
     for line in lines:
         if expect_next == EXPECT_LINE.ACCOUNT_NAME:
             matches = re.findall(PATTERN_ACCOUNT_NAME, line)
@@ -91,13 +95,18 @@ def _reader_raw_comdirect(path: Path) -> CsV2DictMulti:
                 expect_next = EXPECT_LINE.DATA
         elif expect_next == EXPECT_LINE.DATA:
             data = re.findall(PATTERN_DATA, line)
-            if data:
-                assert account_name is not None
-                result[account_name].append(
-                    {column: value for column, value in zip(header, data)}
-                )
-            else:
+            if not data:
                 expect_next = EXPECT_LINE.ACCOUNT_NAME
+            elif len(data) == 1:
+                # Group header line (single Buchungstag for the "neu" rows below).
+                assert account_name is not None
+                pending_book_date[account_name] = data[0]
+            else:
+                assert account_name is not None
+                row = {column: value for column, value in zip(header, data)}
+                if data[0] == "neu" and account_name in pending_book_date:
+                    row["Buchungstag"] = pending_book_date.pop(account_name)
+                result[account_name].append(row)
         else:
             expect_next = EXPECT_LINE.ACCOUNT_NAME
     return result
@@ -128,7 +137,7 @@ def upsert_comdirect_giro(
         "text": data.text,
     }
 
-    return _upsert(
+    return upsert(
         session,
         ComdirectGiroDb,
         parameters_existing,

src/ingest/common.py

@@ -0,0 +1,7 @@
+import csv
+from pathlib import Path
+
+
+def _reader_raw(path: Path):
+    with path.open() as fid:
+        return list(csv.DictReader(fid))

src/ingest/transactions.py

@@ -4,9 +4,9 @@ from sqlalchemy import select
 from sqlalchemy.dialects.sqlite import insert as sqlite_insert
 from sqlalchemy.orm import Session
 
-from src.models._common import BaseModelDb
 from src.models.b4w import B4wDb
 from src.models.comdirect import ComdirectGiroDb
+from src.models.common import BaseModelDb
 from src.models.transactions import Transaction, TransactionDb
 
 

src/models/__init__.py

@@ -1,5 +1,39 @@
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+_EXPORTS = {
+    "B4wExport": ".b4w",
+    "Category": ".category",
+    "CategoryBudgetDb": ".category_budget",
+    "ComdirectCreditCard": ".comdirect",
+    "ComdirectDepot": ".comdirect",
+    "ComdirectGiro": ".comdirect",
+    "Account": ".settings",
+    "Source": ".settings",
+    "Transaction": ".transactions",
+    "TransactionDb": ".transactions",
+}
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str) -> Any:
+    module_name = _EXPORTS.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    value = getattr(import_module(module_name, __name__), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted([*globals(), *__all__])
+
+
+if TYPE_CHECKING:
     from src.models.b4w import B4wExport as B4wExport
-from src.models.b4w import Category as Category
+    from src.models.category import Category as Category
+    from src.models.category_budget import CategoryBudgetDb as CategoryBudgetDb
     from src.models.comdirect import ComdirectCreditCard as ComdirectCreditCard
     from src.models.comdirect import ComdirectDepot as ComdirectDepot
     from src.models.comdirect import ComdirectGiro as ComdirectGiro

src/models/b4w.py

@@ -2,17 +2,17 @@ from datetime import date
 from decimal import Decimal
 
 from pydantic import Field, computed_field, field_validator
-from sqlalchemy import Date, ForeignKey, Integer, String, UniqueConstraint
+from sqlalchemy import Date, ForeignKey, Integer, String
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from src.constants import IBAN_PATTERN, Currency
-from src.models._common import (
-    BaseModelDb,
+from src.models.category import Category
+from src.models.common import (
     ExportBaseModel,
     IngestdbBase,
     Sign,
-    _hash,
     date2str,
+    hashify,
 )
 
 
@@ -59,7 +59,7 @@ class B4wExport(ExportBaseModel):
     @computed_field  # type: ignore[prop-decorator]
     @property
     def hash_id(self) -> str:
-        return _hash(self.id)
+        return hashify(self.id)
 
     @property
     def amount_signed(self) -> Decimal:
@@ -87,56 +87,6 @@ class B4wExport(ExportBaseModel):
         return category
 
 
-class Category(ExportBaseModel):
-    name: str = Field(pattern=r"[^:\r\n]+")
-    parent: Category | None = None
-
-    @computed_field  # type: ignore[prop-decorator]
-    @property
-    def hash_id(self) -> str:
-        return _hash(self.name, self.parent)
-
-    @classmethod
-    def from_str(cls, s: str) -> Category | None:
-        if not s:
-            return None
-        components = s.split(":")
-        name = components[-1]
-        rest = ":".join(components[:-1])
-        return cls(name=name, parent=cls.from_str(rest))
-
-    def to_str(self) -> str | None:
-        if not self.parent:
-            return self.name
-        else:
-            return f"{self.parent.to_str()}:{self.name}"
-
-    def __str__(self):
-        return self.to_str()
-
-    def __repr__(self):
-        return f'Category.from_str("{self.__str__()}")'
-
-
-class CategoryDb(BaseModelDb):
-    __tablename__ = "category"
-    __table_args__ = (
-        UniqueConstraint("name", "parent_id", name="uq_category_name_parent"),
-    )
-
-    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
-    name: Mapped[str] = mapped_column(String, nullable=False)
-    parent_id: Mapped[int | None] = mapped_column(
-        ForeignKey("category.id"), nullable=True
-    )
-
-    # Relationships
-    parent = relationship(
-        "CategoryDb", remote_side="CategoryDb.id", back_populates="children"
-    )
-    children = relationship("CategoryDb", back_populates="parent")
-
-
 class B4wDb(IngestdbBase):
     __tablename__ = "import_b4w"
 

src/models/category.py

@@ -0,0 +1,56 @@
+from pydantic import Field, computed_field
+from sqlalchemy import ForeignKey, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.models.common import BaseModelDb, ExportBaseModel, hashify
+
+
+class Category(ExportBaseModel):
+    name: str = Field(pattern=r"[^:\r\n]+")
+    parent: Category | None = None
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def hash_id(self) -> str:
+        return hashify(self.name, self.parent)
+
+    @classmethod
+    def from_str(cls, s: str) -> Category | None:
+        if not s:
+            return None
+        components = s.split(":")
+        name = components[-1]
+        rest = ":".join(components[:-1])
+        return cls(name=name, parent=cls.from_str(rest))
+
+    def to_str(self) -> str | None:
+        if not self.parent:
+            return self.name
+        else:
+            return f"{self.parent.to_str()}:{self.name}"
+
+    def __str__(self):
+        return self.to_str()
+
+    def __repr__(self):
+        return f'Category.from_str("{self.__str__()}")'
+
+
+class CategoryDb(BaseModelDb):
+    __tablename__ = "category"
+    __table_args__ = (
+        UniqueConstraint("name", "parent_id", name="uq_category_name_parent"),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String, nullable=False)
+    parent_id: Mapped[int | None] = mapped_column(
+        ForeignKey("category.id"), nullable=True
+    )
+
+    # Relationships
+    parent = relationship(
+        "CategoryDb", remote_side="CategoryDb.id", back_populates="children"
+    )
+    children = relationship("CategoryDb", back_populates="parent")
+    budgets = relationship("CategoryBudgetDb", back_populates="category")

src/models/category_budget.py

@@ -0,0 +1,27 @@
+from datetime import date
+from decimal import Decimal
+
+from sqlalchemy import Date, ForeignKey, Numeric
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.models.common import BaseModelDb
+
+
+class CategoryBudgetDb(BaseModelDb):
+    """Budget amount for a category, optionally bounded to a time window.
+
+    Satellite table to ``category``: one category may have several budgets
+    (e.g. one per month). ``valid_from``/``valid_to`` are nullable; ``None``
+    means unbounded on that side.
+    """
+
+    __tablename__ = "category_budget"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    category_id: Mapped[int] = mapped_column(ForeignKey("category.id"), nullable=False)
+    amount_eur: Mapped[Decimal] = mapped_column(Numeric(12, 2), nullable=False)
+    valid_from: Mapped[date | None] = mapped_column(Date, nullable=True, default=None)
+    valid_to: Mapped[date | None] = mapped_column(Date, nullable=True, default=None)
+
+    # relationship
+    category = relationship("CategoryDb", back_populates="budgets")

src/models/comdirect.py

@@ -5,14 +5,14 @@ from pydantic import ConfigDict, Field, computed_field, field_validator
 from sqlalchemy import Date, String
 from sqlalchemy.orm import Mapped, mapped_column
 
-from src.models._common import (
+from src.models.common import (
     ExportBaseModel,
     IngestdbBase,
-    _hash,
     _parse_date_german,
     _parse_decimal_german,
     date2str,
     decimal2str,
+    hashify,
 )
 
 
@@ -72,7 +72,7 @@ class ComdirectGiro(ComdirectBase):
     @computed_field  # type: ignore[prop-decorator]
     @property
     def hash_id(self) -> str:
-        return _hash(self.date_val, self.date_book, self.text)
+        return hashify(self.date_val, self.date_book, self.text)
 
     @field_validator("date_book", mode="before")
     @classmethod

src/models/common.py

@@ -8,7 +8,7 @@ from sqlalchemy import Date, Numeric, String
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
 
-def _hash(*args):
+def hashify(*args):
     raw = "".join(str(args))
     return hashlib.sha256(raw.encode()).hexdigest()
 

src/models/transactions.py

@@ -5,7 +5,7 @@ from pydantic import Field, computed_field
 from sqlalchemy import Date, ForeignKey, Index, Integer, String, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
-from src.models._common import ExportBaseModel, IngestdbBase, _hash, date2str
+from src.models.common import ExportBaseModel, IngestdbBase, date2str, hashify
 
 
 class Transaction(ExportBaseModel):
@@ -33,7 +33,7 @@ class Transaction(ExportBaseModel):
     @computed_field  # type: ignore[prop-decorator]
     @property
     def hash_id(self) -> str:
-        return _hash(
+        return hashify(
             self.source,
             self.account_iban,
             self.date_valid,

tests/test_category_budget.py

@@ -0,0 +1,112 @@
+from datetime import date
+from decimal import Decimal
+
+from sqlalchemy import inspect
+from sqlalchemy.orm import Session
+
+from src.models.category import CategoryDb
+from src.models.category_budget import CategoryBudgetDb
+
+
+def test_category_budget_schema(db_session: Session):
+    inspector = inspect(db_session.get_bind())
+    columns = {c["name"]: c for c in inspector.get_columns("category_budget")}
+
+    assert set(columns) == {
+        "id",
+        "category_id",
+        "amount_eur",
+        "valid_from",
+        "valid_to",
+    }
+    assert columns["id"]["nullable"] is False
+    assert columns["category_id"]["nullable"] is False
+    assert columns["amount_eur"]["nullable"] is False
+    assert columns["valid_from"]["nullable"] is True
+    assert columns["valid_to"]["nullable"] is True
+    assert str(columns["amount_eur"]["type"]) == "NUMERIC(12, 2)"
+
+    foreign_keys = inspector.get_foreign_keys("category_budget")
+    assert len(foreign_keys) == 1
+    assert foreign_keys[0]["constrained_columns"] == ["category_id"]
+    assert foreign_keys[0]["referred_table"] == "category"
+
+
+def test_category_budget_defaults_null_dates(db_session: Session):
+    category = CategoryDb(name="Lebenshaltung")
+    db_session.add(category)
+    db_session.flush()
+
+    budget = CategoryBudgetDb(category_id=category.id, amount_eur=Decimal("150.00"))
+    db_session.add(budget)
+    db_session.commit()
+    db_session.refresh(budget)
+
+    assert budget.id is not None
+    assert budget.category_id == category.id
+    assert budget.amount_eur == Decimal("150.00")
+    # Null means unbounded in either direction.
+    assert budget.valid_from is None
+    assert budget.valid_to is None
+
+
+def test_category_budget_date_window(db_session: Session):
+    category = CategoryDb(name="Freizeit")
+    db_session.add(category)
+    db_session.flush()
+
+    budget = CategoryBudgetDb(
+        category_id=category.id,
+        amount_eur=Decimal("200.50"),
+        valid_from=date(2026, 10, 1),
+        valid_to=date(2026, 10, 31),
+    )
+    db_session.add(budget)
+    db_session.commit()
+    db_session.refresh(budget)
+
+    assert budget.valid_from == date(2026, 10, 1)
+    assert budget.valid_to == date(2026, 10, 31)
+
+
+def test_category_budget_relationship_both_ways(db_session: Session):
+    category = CategoryDb(name="Beruf")
+    db_session.add(category)
+    db_session.flush()
+
+    budget = CategoryBudgetDb(category_id=category.id, amount_eur=Decimal("1.00"))
+    db_session.add(budget)
+    db_session.commit()
+
+    # Force re-read from the database so the relationship is loaded, not
+    # just resolved from the session identity map.
+    db_session.expire_all()
+    assert [b.id for b in category.budgets] == [budget.id]
+    assert budget.category.id == category.id
+
+
+def test_category_has_multiple_budgets(db_session: Session):
+    category = CategoryDb(name="Wohnen")
+    db_session.add(category)
+    db_session.flush()
+
+    budgets = [
+        CategoryBudgetDb(
+            category_id=category.id,
+            amount_eur=Decimal("1200.00"),
+            valid_from=date(2026, 10, 1),
+            valid_to=date(2026, 10, 31),
+        ),
+        CategoryBudgetDb(
+            category_id=category.id,
+            amount_eur=Decimal("1300.00"),
+            valid_from=date(2026, 11, 1),
+            valid_to=date(2026, 11, 30),
+        ),
+    ]
+    for budget in budgets:
+        db_session.add(budget)
+    db_session.commit()
+    db_session.expire_all()
+
+    assert [b.id for b in category.budgets] == [b.id for b in budgets]

tests/test_helper_db.py

@@ -1,9 +1,9 @@
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
-from src.ingest.b4w import upsert_category
+from src.helper.category import upsert_category
 from src.models import Category
-from src.models.b4w import CategoryDb
+from src.models.category import CategoryDb
 
 
 def test_upsert_category_returns_orm_object(db_session: Session):