mirror of
https://github.com/Zproger/Aurum.git
synced 2026-11-17 23:52:49 +07:00
348 lines
14 KiB
Python
348 lines
14 KiB
Python
"""Long-range spending reports — the analysis the month-scoped Dashboard
|
|
breakdown can't answer on its own: "how much did I spend on X this month,
|
|
and how much in total over N years" (single-category detail), and "which
|
|
categories cost the most over this whole period" (ranking, across all
|
|
categories of one kind at once, not just the current month).
|
|
|
|
The same two shapes exist tag-side (get_tag_ranking_report /
|
|
get_tag_spending_report): a category answers "what kind of spend was this",
|
|
a tag answers "which event/project did it belong to" (models/tag.py), so
|
|
the tag reports are what answer "how much did this trip / these gifts cost
|
|
me", cutting across categories instead of along them.
|
|
"""
|
|
from collections import defaultdict
|
|
from datetime import date as date_
|
|
from decimal import Decimal
|
|
from typing import NamedTuple
|
|
|
|
from fastapi import HTTPException
|
|
from sqlalchemy import func, select
|
|
from sqlalchemy.ext.asyncio import AsyncSession
|
|
|
|
from app.models.category import Category
|
|
from app.models.enums import CategoryKind, TransactionType
|
|
from app.models.tag import Tag, transaction_tags
|
|
from app.models.transaction import Transaction, TransactionSplit
|
|
from app.schemas.reports import (
|
|
CategoryRankingChildItem,
|
|
CategoryRankingItem,
|
|
CategoryRankingReport,
|
|
CategorySpendingPoint,
|
|
CategorySpendingReport,
|
|
TagRankingCategoryItem,
|
|
TagRankingItem,
|
|
TagRankingReport,
|
|
TagSpendingReport,
|
|
)
|
|
from app.services.category_rollup import rollup_spending_by_top_level_category
|
|
from app.services.tag_rollup import rollup_spending_by_tag
|
|
|
|
|
|
def _next_month(year: int, month: int) -> tuple[int, int]:
|
|
return (year + 1, 1) if month == 12 else (year, month + 1)
|
|
|
|
|
|
class _MonthlySummary(NamedTuple):
|
|
start_date: date_
|
|
end_date: date_
|
|
total_amount: Decimal
|
|
transaction_count: int
|
|
average_per_month: Decimal
|
|
series: list[CategorySpendingPoint]
|
|
|
|
|
|
def _summarize_by_month(
|
|
contributions: list[tuple[int, date_, Decimal]], start_date: date_ | None, end_date: date_ | None
|
|
) -> _MonthlySummary:
|
|
"""Turns (transaction_id, date, amount) rows into the month-by-month
|
|
shape both detail reports return — gap months included as zeroes so the
|
|
chart's bars stay evenly spaced in time, and the period falling back to
|
|
the data's own first/last month when the caller didn't bound it.
|
|
|
|
Shared by the category and tag detail reports so the two can't drift on
|
|
what "average per month" or "transaction count" mean. Callers must
|
|
handle an empty `contributions` list themselves: with no rows there is
|
|
no period to fall back to.
|
|
"""
|
|
dates = [txn_date for _, txn_date, _ in contributions]
|
|
effective_start = start_date or min(dates)
|
|
effective_end = end_date or max(dates)
|
|
|
|
by_month: dict[tuple[int, int], Decimal] = defaultdict(Decimal)
|
|
for _, txn_date, amount in contributions:
|
|
by_month[(txn_date.year, txn_date.month)] += amount
|
|
|
|
total_amount = sum((amount for _, _, amount in contributions), Decimal("0"))
|
|
# Distinct transactions, not rows — a transaction split across two
|
|
# categories (e.g. parent + one of its children) must count once, the
|
|
# same as a plain transaction filed under just one of them.
|
|
total_count = len({transaction_id for transaction_id, _, _ in contributions})
|
|
|
|
series: list[CategorySpendingPoint] = []
|
|
year, month = effective_start.year, effective_start.month
|
|
while (year, month) <= (effective_end.year, effective_end.month):
|
|
series.append(CategorySpendingPoint(year=year, month=month, amount=by_month.get((year, month), Decimal("0"))))
|
|
year, month = _next_month(year, month)
|
|
|
|
months_count = len(series)
|
|
average_per_month = (total_amount / months_count).quantize(Decimal("0.01")) if months_count else Decimal("0")
|
|
|
|
return _MonthlySummary(
|
|
start_date=effective_start,
|
|
end_date=effective_end,
|
|
total_amount=total_amount,
|
|
transaction_count=total_count,
|
|
average_per_month=average_per_month,
|
|
series=series,
|
|
)
|
|
|
|
|
|
async def get_category_spending_report(
|
|
session: AsyncSession, category_id: int, start_date: date_ | None, end_date: date_ | None
|
|
) -> CategorySpendingReport:
|
|
category = await session.get(Category, category_id)
|
|
if category is None:
|
|
raise HTTPException(status_code=404, detail="Category not found")
|
|
|
|
# A top-level category's own report folds in its subcategories' spending
|
|
# too (same rollup as the Dashboard breakdown); a subcategory picked
|
|
# directly shows just its own transactions — there's nothing beneath it.
|
|
category_ids: list[int] = [category_id]
|
|
if category.parent_id is None:
|
|
child_ids = (
|
|
await session.execute(select(Category.id).where(Category.parent_id == category_id))
|
|
).scalars().all()
|
|
category_ids.extend(child_ids)
|
|
|
|
# Plain transactions filed directly under one of these categories, plus
|
|
# split lines that assign part of a transaction to one of them — same
|
|
# two sources category_rollup.py unions for the Dashboard/ranking report.
|
|
plain_stmt = select(Transaction.id, Transaction.date, Transaction.amount).where(
|
|
Transaction.category_id.in_(category_ids)
|
|
)
|
|
split_stmt = (
|
|
select(TransactionSplit.transaction_id, Transaction.date, TransactionSplit.amount)
|
|
.join(Transaction, Transaction.id == TransactionSplit.transaction_id)
|
|
.where(TransactionSplit.category_id.in_(category_ids))
|
|
)
|
|
if start_date:
|
|
plain_stmt = plain_stmt.where(Transaction.date >= start_date)
|
|
split_stmt = split_stmt.where(Transaction.date >= start_date)
|
|
if end_date:
|
|
plain_stmt = plain_stmt.where(Transaction.date <= end_date)
|
|
split_stmt = split_stmt.where(Transaction.date <= end_date)
|
|
|
|
plain_rows = (await session.execute(plain_stmt)).all()
|
|
split_rows = (await session.execute(split_stmt)).all()
|
|
contributions = [(r[0], r[1], r[2]) for r in plain_rows] + [(r[0], r[1], r[2]) for r in split_rows]
|
|
|
|
empty = CategorySpendingReport(
|
|
category_id=category.id,
|
|
category_name=category.name,
|
|
category_color=category.color,
|
|
category_icon=category.icon,
|
|
start_date=start_date,
|
|
end_date=end_date,
|
|
total_amount=Decimal("0"),
|
|
transaction_count=0,
|
|
average_per_month=Decimal("0"),
|
|
series=[],
|
|
)
|
|
if not contributions:
|
|
return empty
|
|
|
|
summary = _summarize_by_month(contributions, start_date, end_date)
|
|
|
|
return CategorySpendingReport(
|
|
category_id=category.id,
|
|
category_name=category.name,
|
|
category_color=category.color,
|
|
category_icon=category.icon,
|
|
start_date=summary.start_date,
|
|
end_date=summary.end_date,
|
|
total_amount=summary.total_amount,
|
|
transaction_count=summary.transaction_count,
|
|
average_per_month=summary.average_per_month,
|
|
series=summary.series,
|
|
)
|
|
|
|
|
|
_KIND_TO_TRANSACTION_TYPE = {
|
|
CategoryKind.EXPENSE: TransactionType.EXPENSE,
|
|
CategoryKind.INCOME: TransactionType.INCOME,
|
|
}
|
|
|
|
|
|
async def get_category_ranking_report(
|
|
session: AsyncSession, kind: CategoryKind, start_date: date_ | None, end_date: date_ | None
|
|
) -> CategoryRankingReport:
|
|
"""All categories of one kind, ranked by total spent/earned over an
|
|
arbitrary period — "which category costs the most" across the whole
|
|
range, unlike the month-scoped Dashboard breakdown or the
|
|
single-category detail above."""
|
|
# A transaction's type already restricts it to categories of the
|
|
# matching kind (enforced at write time by _ensure_category_matches_type
|
|
# in routes/transactions.py), so filtering by transaction_type below is
|
|
# enough — no separate kind filter needed, and the shared rollup already
|
|
# unions plain transactions with split lines the same way the Dashboard
|
|
# breakdown does.
|
|
rows = await rollup_spending_by_top_level_category(
|
|
session, transaction_type=_KIND_TO_TRANSACTION_TYPE[kind], start_date=start_date, end_date=end_date
|
|
)
|
|
total_amount = sum((row.amount for row in rows), Decimal("0"))
|
|
|
|
def _percent(amount: Decimal) -> float:
|
|
return float(amount / total_amount * 100) if total_amount else 0.0
|
|
|
|
items = [
|
|
CategoryRankingItem(
|
|
category_id=row.category_id,
|
|
name=row.name,
|
|
color=row.color,
|
|
icon=row.icon,
|
|
amount=row.amount,
|
|
percent=_percent(row.amount),
|
|
transaction_count=row.transaction_count,
|
|
children=[
|
|
CategoryRankingChildItem(
|
|
category_id=child.category_id, name=child.name, color=child.color, icon=child.icon,
|
|
amount=child.amount,
|
|
)
|
|
for child in row.children
|
|
],
|
|
)
|
|
for row in rows
|
|
]
|
|
|
|
return CategoryRankingReport(start_date=start_date, end_date=end_date, total_amount=total_amount, items=items)
|
|
|
|
|
|
async def _period_total(
|
|
session: AsyncSession,
|
|
*,
|
|
transaction_type: TransactionType,
|
|
start_date: date_ | None,
|
|
end_date: date_ | None,
|
|
tagged_only: bool = False,
|
|
) -> Decimal:
|
|
"""Everything spent/earned in the period — or only the part carrying at
|
|
least one tag. `Transaction.tags.any()` is an EXISTS, so a transaction
|
|
with three tags is still counted once; summing the ranking's items
|
|
instead would count it three times."""
|
|
stmt = select(func.coalesce(func.sum(Transaction.amount), 0)).where(Transaction.type == transaction_type)
|
|
if tagged_only:
|
|
stmt = stmt.where(Transaction.tags.any())
|
|
if start_date is not None:
|
|
stmt = stmt.where(Transaction.date >= start_date)
|
|
if end_date is not None:
|
|
stmt = stmt.where(Transaction.date <= end_date)
|
|
return Decimal(str((await session.execute(stmt)).scalar_one()))
|
|
|
|
|
|
async def get_tag_ranking_report(
|
|
session: AsyncSession, kind: CategoryKind, start_date: date_ | None, end_date: date_ | None
|
|
) -> TagRankingReport:
|
|
"""Every tag ranked by total spent/earned over an arbitrary period —
|
|
"which trip/project/person cost the most", the question the category
|
|
ranking above can't answer because one such answer cuts across several
|
|
categories at once.
|
|
|
|
Each tag is measured against the period's *whole* spending rather than
|
|
against the other tags: tags overlap, so a denominator built from the
|
|
items themselves would double-count every multi-tagged transaction and
|
|
quietly shrink each percentage.
|
|
"""
|
|
transaction_type = _KIND_TO_TRANSACTION_TYPE[kind]
|
|
rows = await rollup_spending_by_tag(
|
|
session, transaction_type=transaction_type, start_date=start_date, end_date=end_date
|
|
)
|
|
total_amount = await _period_total(
|
|
session, transaction_type=transaction_type, start_date=start_date, end_date=end_date
|
|
)
|
|
tagged_amount = await _period_total(
|
|
session, transaction_type=transaction_type, start_date=start_date, end_date=end_date, tagged_only=True
|
|
)
|
|
|
|
def _percent(amount: Decimal) -> float:
|
|
return float(amount / total_amount * 100) if total_amount else 0.0
|
|
|
|
items = [
|
|
TagRankingItem(
|
|
tag_id=row.tag_id,
|
|
name=row.name,
|
|
color=row.color,
|
|
amount=row.amount,
|
|
percent=_percent(row.amount),
|
|
transaction_count=row.transaction_count,
|
|
categories=[
|
|
TagRankingCategoryItem(
|
|
category_id=category.category_id, name=category.name, color=category.color,
|
|
icon=category.icon, amount=category.amount,
|
|
)
|
|
for category in row.categories
|
|
],
|
|
)
|
|
for row in rows
|
|
]
|
|
|
|
return TagRankingReport(
|
|
start_date=start_date,
|
|
end_date=end_date,
|
|
total_amount=total_amount,
|
|
tagged_amount=tagged_amount,
|
|
items=items,
|
|
)
|
|
|
|
|
|
async def get_tag_spending_report(
|
|
session: AsyncSession, tag_id: int, kind: CategoryKind, start_date: date_ | None, end_date: date_ | None
|
|
) -> TagSpendingReport:
|
|
"""One tag's spend over time. Unlike its category twin this needs no
|
|
split-line union: a tag sits on the transaction itself, so the
|
|
transaction's own amount is the whole of its contribution however many
|
|
categories it was split across.
|
|
|
|
`kind` is a parameter here rather than a property of the subject — a
|
|
category is either an expense or an income one, but a tag is neither and
|
|
can legitimately sit on both sides ("trip:georgia" on the flights and on
|
|
the refund), so the caller picks which side it's looking at.
|
|
"""
|
|
tag = await session.get(Tag, tag_id)
|
|
if tag is None:
|
|
raise HTTPException(status_code=404, detail="Tag not found")
|
|
|
|
stmt = (
|
|
select(Transaction.id, Transaction.date, Transaction.amount)
|
|
.join(transaction_tags, transaction_tags.c.transaction_id == Transaction.id)
|
|
.where(transaction_tags.c.tag_id == tag_id, Transaction.type == _KIND_TO_TRANSACTION_TYPE[kind])
|
|
)
|
|
if start_date is not None:
|
|
stmt = stmt.where(Transaction.date >= start_date)
|
|
if end_date is not None:
|
|
stmt = stmt.where(Transaction.date <= end_date)
|
|
|
|
contributions = [(r[0], r[1], r[2]) for r in (await session.execute(stmt)).all()]
|
|
if not contributions:
|
|
return TagSpendingReport(
|
|
tag_id=tag.id,
|
|
tag_name=tag.name,
|
|
start_date=start_date,
|
|
end_date=end_date,
|
|
total_amount=Decimal("0"),
|
|
transaction_count=0,
|
|
average_per_month=Decimal("0"),
|
|
series=[],
|
|
)
|
|
|
|
summary = _summarize_by_month(contributions, start_date, end_date)
|
|
return TagSpendingReport(
|
|
tag_id=tag.id,
|
|
tag_name=tag.name,
|
|
start_date=summary.start_date,
|
|
end_date=summary.end_date,
|
|
total_amount=summary.total_amount,
|
|
transaction_count=summary.transaction_count,
|
|
average_per_month=summary.average_per_month,
|
|
series=summary.series,
|
|
)
|