Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

fix(reporting): honor effective_bill_date override in dashboard/report/budget aggregations (#327)

Tássio Noronhaa2e072efd10c
diff --git a/backend/app/services/_query_filters.py b/backend/app/services/_query_filters.py
index 12f8cb66..38ce94a5 100644
--- a/backend/app/services/_query_filters.py
+++ b/backend/app/services/_query_filters.py
@@ -15,6 +15,31 @@ from app.models.category import Category
from app.models.transaction import Transaction
+def reporting_date_col(accounting_mode: str):
+ """The date column a transaction should be *bucketed by* in period
+ aggregations (dashboard, reports, budgets).
+
+ Honors the manual credit-card cycle override (`effective_bill_date`)
+ FIRST — regardless of accounting mode — because that's the whole point
+ of the override: the user hand-corrected which invoice a purchase
+ belongs to (issue #92). When there's no override, fall back to
+ `effective_date` in accrual mode or the raw purchase `date` in cash
+ mode.
+
+ This mirrors the ordering used by the transaction list and the credit
+ card bill view, so a transaction lands in the same month everywhere the
+ user looks. Aggregations that skipped the override summed credit-card
+ spend under the purchase month instead of the invoice month (issue
+ #232).
+ """
+ base = (
+ Transaction.effective_date
+ if accounting_mode == "accrual"
+ else Transaction.date
+ )
+ return func.coalesce(Transaction.effective_bill_date, base)
+
+
def counts_as_pnl():
"""SQL filter: True when a transaction should contribute to income/expense totals.
@@ -99,7 +124,10 @@ async def owner_split_offset_pnl(
)
)
)
- date_col = Transaction.effective_date if use_effective_date else Transaction.date
+ date_col = func.coalesce(
+ Transaction.effective_bill_date,
+ Transaction.effective_date if use_effective_date else Transaction.date,
+ )
result = await session.execute(
select(
@@ -183,7 +211,10 @@ async def owner_split_offset_by_category(
)
)
)
- date_col = Transaction.effective_date if use_effective_date else Transaction.date
+ date_col = func.coalesce(
+ Transaction.effective_bill_date,
+ Transaction.effective_date if use_effective_date else Transaction.date,
+ )
result = await session.execute(
select(
@@ -257,7 +288,10 @@ async def viewer_shared_pnl(
GroupMember.linked_user_id == user_id,
GroupMember.is_self.is_(False),
)
- date_col = Transaction.effective_date if use_effective_date else Transaction.date
+ date_col = func.coalesce(
+ Transaction.effective_bill_date,
+ Transaction.effective_date if use_effective_date else Transaction.date,
+ )
result = await session.execute(
select(
@@ -341,7 +375,10 @@ async def viewer_shared_spending_by_category(
GroupMember.linked_user_id == user_id,
GroupMember.is_self.is_(False),
)
- date_col = Transaction.effective_date if use_effective_date else Transaction.date
+ date_col = func.coalesce(
+ Transaction.effective_bill_date,
+ Transaction.effective_date if use_effective_date else Transaction.date,
+ )
result = await session.execute(
select(
diff --git a/backend/app/services/budget_service.py b/backend/app/services/budget_service.py
index 26697708..b4595849 100644
--- a/backend/app/services/budget_service.py
+++ b/backend/app/services/budget_service.py
@@ -15,6 +15,7 @@ from app.schemas.budget import BudgetCreate, BudgetUpdate, BudgetVsActual
from app.services._query_filters import (
counts_as_user_pnl,
owner_split_offset_by_category,
+ reporting_date_col,
)
from app.services.admin_service import get_credit_card_accounting_mode
from app.services.dashboard_service import _get_recurring_projections
@@ -257,9 +258,7 @@ async def get_budget_vs_actual(
user = await session.get(User, user_id)
primary_currency = user.primary_currency if user else get_settings().default_currency
accounting_mode = await get_credit_card_accounting_mode(session)
- report_date = (
- Transaction.effective_date if accounting_mode == "accrual" else Transaction.date
- )
+ report_date = reporting_date_col(accounting_mode)
# Get actual spending by category for this month (exclude transfer pairs)
# Use amount_primary for multi-currency support
diff --git a/backend/app/services/dashboard_service.py b/backend/app/services/dashboard_service.py
index f0d99466..ca493332 100644
--- a/backend/app/services/dashboard_service.py
+++ b/backend/app/services/dashboard_service.py
@@ -17,6 +17,7 @@ from app.services._query_filters import (
counts_as_user_pnl,
owner_split_offset_by_category,
owner_split_offset_pnl,
+ reporting_date_col,
viewer_shared_pnl,
viewer_shared_spending_by_category,
)
@@ -117,9 +118,7 @@ async def get_summary(
# cash-flow view.
user = await session.get(User, user_id)
accounting_mode = await get_credit_card_accounting_mode(session)
- report_date = (
- Transaction.effective_date if accounting_mode == "accrual" else Transaction.date
- )
+ report_date = reporting_date_col(accounting_mode)
# Compute the effective cutoff date for balance calculation
if balance_date:
@@ -486,9 +485,7 @@ async def get_spending_by_category(
user = await session.get(User, user_id)
accounting_mode = await get_credit_card_accounting_mode(session)
primary_currency = user.primary_currency if user else get_settings().default_currency
- report_date = (
- Transaction.effective_date if accounting_mode == "accrual" else Transaction.date
- )
+ report_date = reporting_date_col(accounting_mode)
# Real transactions grouped by category (exclude transfer-like movements
# and closed accounts). Use amount_primary for multi-currency support.
@@ -650,9 +647,7 @@ async def get_monthly_trend(
filtered = account_ids is not None
acct_filter = [Transaction.account_id.in_(account_ids)] if filtered else []
accounting_mode = await get_credit_card_accounting_mode(session)
- report_date = (
- Transaction.effective_date if accounting_mode == "accrual" else Transaction.date
- )
+ report_date = reporting_date_col(accounting_mode)
month_label = func.to_char(report_date, 'YYYY-MM').label('month')
primary_amt = _primary_amount_expr()
result = await session.execute(
diff --git a/backend/app/services/report_service.py b/backend/app/services/report_service.py
index 9563a0c3..42bbee84 100644
--- a/backend/app/services/report_service.py
+++ b/backend/app/services/report_service.py
@@ -18,6 +18,7 @@ from app.services._query_filters import (
counts_as_pnl,
counts_as_user_pnl,
owner_split_offset_by_category,
+ reporting_date_col,
)
from app.services.admin_service import get_credit_card_accounting_mode
from app.services.account_service import get_account_name
@@ -371,9 +372,7 @@ async def get_income_expenses_report(
user = await session.get(User, user_id)
primary_currency = user.primary_currency if user else get_settings().default_currency
accounting_mode = await get_credit_card_accounting_mode(session)
- report_date = (
- Transaction.effective_date if accounting_mode == "accrual" else Transaction.date
- )
+ report_date = reporting_date_col(accounting_mode)
label_expr = _interval_label_expr(interval, report_date).label('period')
diff --git a/backend/app/services/transaction_service.py b/backend/app/services/transaction_service.py
index cef857de..023dbb3a 100644
--- a/backend/app/services/transaction_service.py
+++ b/backend/app/services/transaction_service.py
@@ -21,7 +21,7 @@ from app.services import split_service
from app.services.credit_card_service import apply_effective_date
from app.services.rule_service import apply_rules_to_transaction
from app.services.fx_rate_service import stamp_primary_amount, convert as fx_convert
-from app.services._query_filters import counts_as_pnl
+from app.services._query_filters import counts_as_pnl, reporting_date_col
def _apply_fx_override(transaction, amount, amount_primary=None, fx_rate_used=None):
@@ -93,11 +93,10 @@ async def get_transactions(
# line up with the cash-flow view used by the dashboard and reports.
# When the user has set a manual cycle override (effective_bill_date)
# we honor it FIRST regardless of accounting mode — that's the whole
- # point of the override (issue #92, LucasFidelis suggestion).
- date_col = func.coalesce(
- Transaction.effective_bill_date,
- Transaction.effective_date if accounting_mode == "accrual" else Transaction.date,
- )
+ # point of the override (issue #92, LucasFidelis suggestion). Shared
+ # with the dashboard/report/budget aggregations so a transaction lands
+ # in the same month everywhere (issue #232).
+ date_col = reporting_date_col(accounting_mode)
# Group-scope visibility: when the caller filters by a group they
# have access to (owner or linked member), bypass the user-owns-it
diff --git a/backend/tests/test_credit_card_accounting_mode.py b/backend/tests/test_credit_card_accounting_mode.py
index 463f1336..c2315884 100644
--- a/backend/tests/test_credit_card_accounting_mode.py
+++ b/backend/tests/test_credit_card_accounting_mode.py
@@ -523,6 +523,72 @@ class TestSpendingByCategory:
assert accrual_map.get("Alimentação", 0) == 100.0
assert accrual_map.get("Transporte", 0) == 0.0
+ @pytest.mark.asyncio
+ @pytest.mark.parametrize("mode", ["cash", "accrual"])
+ async def test_category_breakdown_honors_effective_bill_date_override(
+ self, session, test_user, test_workspace, cc_account, test_categories, mode
+ ):
+ """Issue #232: when the user manually moves a credit-card purchase to
+ a different invoice via effective_bill_date, the dashboard category
+ panel must aggregate it under the invoice month — not the purchase
+ month — in BOTH cash and accrual modes. The override beats whichever
+ date column the mode would otherwise bucket by, matching the
+ transaction list and the bill view."""
+ food = test_categories[0]
+ # Purchased May 27. effective_date deliberately left in May (the stale
+ # purchase month) so the only thing that can move it to June is the
+ # override — proving the override wins over both report columns.
+ tx = await _make_tx(
+ session, test_user.id, cc_account.id, date(2026, 5, 27),
+ Decimal("100"), effective_date=date(2026, 5, 27), category_id=food.id,
+ )
+ tx.effective_bill_date = date(2026, 6, 1) # user moved it to the June invoice
+ await session.commit()
+
+ await _set_mode(session, mode)
+
+ # May must NOT include the purchase anymore.
+ may = await dashboard_service.get_spending_by_category(
+ session, test_workspace.id, test_user.id, month=date(2026, 5, 1)
+ )
+ may_map = {c.category_name: c.total for c in may}
+ assert may_map.get("Alimentação", 0) == 0.0, (
+ f"{mode}: override'd tx must leave its purchase month"
+ )
+
+ # June (the invoice month) must include it.
+ june = await dashboard_service.get_spending_by_category(
+ session, test_workspace.id, test_user.id, month=date(2026, 6, 1)
+ )
+ june_map = {c.category_name: c.total for c in june}
+ assert june_map.get("Alimentação", 0) == 100.0, (
+ f"{mode}: override'd tx must land in the invoice month"
+ )
+
+ @pytest.mark.asyncio
+ async def test_summary_honors_effective_bill_date_override_in_cash_mode(
+ self, session, test_user, test_workspace, cc_account, test_categories
+ ):
+ """Companion to the category test: the dashboard summary totals must
+ also follow the manual invoice override (issue #232)."""
+ food = test_categories[0]
+ tx = await _make_tx(
+ session, test_user.id, cc_account.id, date(2026, 5, 27),
+ Decimal("100"), effective_date=date(2026, 5, 27), category_id=food.id,
+ )
+ tx.effective_bill_date = date(2026, 6, 1)
+ await session.commit()
+
+ await _set_mode(session, "cash")
+ may = await dashboard_service.get_summary(
+ session, test_workspace.id, test_user.id, month=date(2026, 5, 1)
+ )
+ june = await dashboard_service.get_summary(
+ session, test_workspace.id, test_user.id, month=date(2026, 6, 1)
+ )
+ assert may.monthly_expenses == 0.0
+ assert june.monthly_expenses == 100.0
+
# ---------------------------------------------------------------------------
# Budget vs actual.