Open-source personal finance manager. Self-hosted, privacy-first.
fix(credit-cards): assign bill overrides by due-date range in the cycle view (#1293)
Tássio Noronha985454d57551
diff --git a/backend/app/services/account_service.py b/backend/app/services/account_service.pyindex e12f4cc4..dbf68503 100644--- a/backend/app/services/account_service.py+++ b/backend/app/services/account_service.py@@ -34,7 +34,12 @@ from app.services._query_filters import (is_not_ignored,reporting_date_col,)-from app.services.credit_card_service import apply_effective_date, compute_available_credit, get_cycle_dates+from app.services.credit_card_service import (+ apply_effective_date,+ cc_cycle_bill_due_dates,+ compute_available_credit,+ get_cycle_dates,+)from app.services.fx_rate_service import _resolve_ratefrom app.models.category import Category@@ -880,6 +885,10 @@ async def get_account_summary(return Nonetoday = app_today()+ # Captured before the defaults below fill in None dates, so the+ # bill-based window rule only applies to windows the caller actually+ # sent (issue #563).+ explicit_window = date_from is not None and date_to is not Noneif not date_from:date_from = today.replace(day=1)if not date_to:@@ -935,6 +944,59 @@ async def get_account_summary(# totals card and bar chart agree with the transactions list (issue #92).bucket_date = func.coalesce(Transaction.effective_bill_date, Transaction.date)+ # Bill-based membership for the plain (cycle-math) window: when the+ # caller sent a window that is exactly one bill cycle of this credit+ # card account, an overridden tx belongs to the bill whose+ # (previous due date, due date] range contains the override, not to the+ # purchase window that contains it (for due-before-close cards a due+ # date sits in the NEXT cycle's window, issue #563).+ cycle = None+ if (+ explicit_window+ and bill_id is None+ and not unbilled_only+ and account.type == "credit_card"+ ):+ cycle = cc_cycle_bill_due_dates(+ date_from, date_to,+ account.statement_close_day, account.payment_due_day,+ )++ def _membership():+ """Window predicate for these totals: the plain date window, or+ the bill-based rule above when the window is one of this+ account's cycles. The actuals cap (bucket_date <= today) and the+ forecast condition stay on the queries, so a tx in one bill's+ window can still not leak into another bill's totals."""+ if cycle is None or cycle["degenerate"]:+ return and_(bucket_date >= date_from, bucket_date <= date_to)+ override = Transaction.effective_bill_date+ return or_(+ and_(+ override.is_(None),+ bucket_date >= date_from,+ bucket_date <= date_to,+ ),+ # (previous due date, this due date]: each override date maps+ # to exactly one bill.+ and_(override > cycle["prev"], override <= cycle["this"]),+ )++ def _before_window():+ """Rows that belong to an earlier cycle than this one, under the+ same rule as `_membership`: without a cycle, anything bucketed+ before the window; with one, rows without an override bucketed+ before the window plus overrides on or before the previous bill's+ due date. Keeps older debt and this cycle's rows disjoint, so a+ charge moved onto the previous bill counts as older debt."""+ if cycle is None or cycle["degenerate"]:+ return bucket_date < date_from+ override = Transaction.effective_bill_date+ return or_(+ and_(override.is_(None), bucket_date < date_from),+ override <= cycle["prev"],+ )+# Bill-driven filter (issue #92): when the caller passes bill_id, include# (a) txs linked to this bill via Pluggy's billId mapping, AND# (b) txs with NO bill_id (manual entries, OFX/CSV imports, recurring@@ -997,7 +1059,11 @@ async def get_account_summary(future_override,),)- return query.where(bucket_date >= date_from, bucket_date <= date_to)+ # Plain cycle-math window: bill-based membership when the window is+ # one of this credit card account's cycles (issue #563), plain date+ # window otherwise (non-CC accounts, wider ranges, degenerate+ # close/due pairs).+ return query.where(_membership())# Which exclusions these totals answer to. A credit card's four summary# numbers are all bill-side — they describe what the bank put on the@@ -1028,7 +1094,7 @@ async def get_account_summary()), 0)).where(Transaction.account_id == account_id,- bucket_date < date_from,+ _before_window(),# Rows linked to the selected bill belong to it whatever# their date (see `_scope`), so they are not older debt.*([] if bill_id is None else [or_(diff --git a/backend/app/services/credit_card_service.py b/backend/app/services/credit_card_service.pyindex 821d45ef..c3e9f10b 100644--- a/backend/app/services/credit_card_service.py+++ b/backend/app/services/credit_card_service.py@@ -1,5 +1,5 @@import calendar-from datetime import date+from datetime import date, timedeltafrom decimal import Decimalfrom typing import Optional@@ -143,3 +143,71 @@ def compute_effective_date(if cycle_end.month == 12:return _clamp_day(cycle_end.year + 1, 1, payment_due_day)return _clamp_day(cycle_end.year, cycle_end.month + 1, payment_due_day)+++def cc_cycle_bill_due_dates(+ window_start: Optional[date],+ window_end: Optional[date],+ statement_close_day: Optional[int],+ payment_due_day: Optional[int],+) -> Optional[dict]:+ """Due dates of a single bill cycle, when a window is exactly one.++ Returns None unless ``[window_start, window_end]`` is exactly one+ billing cycle of a credit card account with both cycle days set: the+ start is a clamped close day and the day after the end is the next+ clamped close day. Callers should keep their plain date-window+ behavior for any other window shape.++ When the window is a cycle, returns a dict with the due dates of the+ neighboring bills and a ``degenerate`` flag:++ - ``this``: the bill this cycle closes to.+ - ``prev``: the bill that closed right before the window.+ - ``next``: the bill the following cycle closes to.+ - ``degenerate``: True when this bill shares a due date with the+ previous or the next one (month-length clamping, e.g. close 29 /+ due 30 around February). A manual ``effective_bill_date`` then+ cannot name exactly one bill, so callers keep the historical window+ behavior.++ A manual ``effective_bill_date`` belongs to this bill when it falls in+ ``(prev, this]``: after the previous bill's due date, up to and+ including this bill's due date. Every date then maps to exactly one+ bill, so an override that is not an exact due date still shows up in+ one bill view and only one.++ Why this exists: a manual ``effective_bill_date`` names a bill by that+ bill's DUE date, but bucketing a transaction by the purchase window+ containing that date lands it on the wrong bill whenever the due date+ falls inside the NEXT cycle's window. With close 24 / due 18, the Aug+ bill is due 08-18, which sits inside the Sep cycle's 07-24 to 08-23+ purchase window, so the Aug bill shows empty and the Sep bill picks up+ its charges (issue #563).+ """+ if window_start is None or window_end is None:+ return None+ if not statement_close_day or not payment_due_day:+ return None+ if (window_end - window_start).days > 31:+ return None+ next_day = window_end + timedelta(days=1)+ days_next = calendar.monthrange(next_day.year, next_day.month)[1]+ if next_day.day != min(statement_close_day, days_next):+ return None+ days_start = calendar.monthrange(window_start.year, window_start.month)[1]+ if window_start.day != min(statement_close_day, days_start):+ return None+ d_this = compute_effective_date(window_start, statement_close_day, payment_due_day)+ d_prev = compute_effective_date(+ window_start - timedelta(days=1), statement_close_day, payment_due_day+ )+ d_next = compute_effective_date(+ window_end + timedelta(days=1), statement_close_day, payment_due_day+ )+ return {+ "this": d_this,+ "prev": d_prev,+ "next": d_next,+ "degenerate": d_this == d_prev or d_this == d_next,+ }diff --git a/backend/app/services/transaction_service.py b/backend/app/services/transaction_service.pyindex e33c1e4a..56cb5544 100644--- a/backend/app/services/transaction_service.py+++ b/backend/app/services/transaction_service.py@@ -26,7 +26,7 @@ from app.schemas.transaction import (from app.schemas.transaction_split import TransactionSplitInput, TransactionSplitsInputfrom app.services import reconciliation_service, split_servicefrom app.services.account_service import get_account, get_running_balances-from app.services.credit_card_service import apply_effective_date+from app.services.credit_card_service import apply_effective_date, cc_cycle_bill_due_datesfrom app.services.rule_service import apply_rules_to_transactionfrom app.services.fx_rate_service import stamp_primary_amount, convert as fx_convertfrom app.services._query_filters import (@@ -393,10 +393,64 @@ async def get_transactions(),))else:- if from_date:- base_query = base_query.where(filter_date_col >= from_date)- if to_date:- base_query = base_query.where(filter_date_col <= to_date)+ # Single-account date window: if it is exactly one bill cycle of+ # a credit card account, membership is bill-based, not+ # window-based. A manual effective_bill_date names a bill by its+ # DUE date, and a due date can sit inside the NEXT cycle's+ # purchase window (close 24 / due 18: the Aug bill is due 08-18,+ # inside the Sep window 07-24 to 08-23), so window bucketing+ # put overridden txs on the wrong bill and emptied their own+ # bill (issue #563). The rule: no override stays in the window+ # exactly as before; an override belongs to this bill when it+ # falls after the previous bill's due date and on or before+ # this bill's due date, so every override date maps to exactly+ # one bill. Any other window shape, or an account whose+ # close/due days make two bills share a due date (degenerate),+ # keeps the historical behavior untouched.+ cycle = None+ if from_date is not None and to_date is not None:+ # The list endpoint funnels the single account_id param into+ # account_ids, so accept either shape when exactly one+ # account is in scope.+ single_account = account_id+ if single_account is None and account_ids is not None and len(account_ids) == 1:+ single_account = account_ids[0]+ if single_account is not None:+ acct_row = (+ await session.execute(+ select(+ Account.type,+ Account.statement_close_day,+ Account.payment_due_day,+ ).where(Account.id == single_account)+ )+ ).first()+ if acct_row is not None and acct_row[0] == "credit_card":+ cycle = cc_cycle_bill_due_dates(+ from_date, to_date, acct_row[1], acct_row[2]+ )+ if cycle is None or cycle["degenerate"]:+ if from_date:+ base_query = base_query.where(filter_date_col >= from_date)+ if to_date:+ base_query = base_query.where(filter_date_col <= to_date)+ else:+ from sqlalchemy import and_ as _and++ override = Transaction.effective_bill_date+ base_query = base_query.where(+ or_(+ _and(+ override.is_(None),+ filter_date_col >= from_date,+ filter_date_col <= to_date,+ ),+ _and(+ override > cycle["prev"],+ override <= cycle["this"],+ ),+ )+ )if search:term = f"%{search}%"base_query = base_query.where(diff --git a/backend/tests/test_credit_card_accounting_mode.py b/backend/tests/test_credit_card_accounting_mode.pyindex 312b5182..ee19630b 100644--- a/backend/tests/test_credit_card_accounting_mode.py+++ b/backend/tests/test_credit_card_accounting_mode.py@@ -2011,3 +2011,320 @@ class TestBillTotalIgnoresReportingExclusions:assert summary is not Noneassert summary["monthly_expenses"] == 300.0+++# ---------------------------------------------------------------------------+# Bill-based membership for single-cycle windows (issue #563).+#+# A manual effective_bill_date names a bill by that bill's DUE date, but the+# cycle view used to bucket by the purchase window containing the date. With+# close=24 / due=18 the Aug bill is due 08-18, which sits inside the Sep+# cycle's purchase window 07-24..08-23, so a tx overridden onto the Aug bill+# showed up in the Sep bill and left the Aug bill empty.+# ---------------------------------------------------------------------------+++@pytest_asyncio.fixture+async def cc_account_due_before_close(session, test_user, test_connection):+ """A credit card account with close=24, due=18: the previous bill's due+ date (the 18th) falls INSIDE the next cycle's purchase window."""+ account = Account(+ id=uuid.uuid4(),+ user_id=test_user.id,+ connection_id=test_connection.id,+ external_id="cc-563",+ name="late due card",+ type="credit_card",+ balance=Decimal("0"),+ currency="BRL",+ statement_close_day=24,+ payment_due_day=18,+ credit_limit=Decimal("5000"),+ )+ session.add(account)+ await session.commit()+ await session.refresh(account)+ return account+++class TestCycleBillDueDates:+ """Unit tests for cc_cycle_bill_due_dates, the pure window-shape check."""++ def test_detects_cycle_window_and_returns_due_dates(self):+ from app.services.credit_card_service import cc_cycle_bill_due_dates+ r = cc_cycle_bill_due_dates(date(2026, 7, 24), date(2026, 8, 23), 24, 18)+ assert r == {+ "this": date(2026, 9, 18),+ "prev": date(2026, 8, 18),+ "next": date(2026, 10, 18),+ "degenerate": False,+ }++ def test_rejects_non_cycle_windows(self):+ from app.services.credit_card_service import cc_cycle_bill_due_dates+ # Calendar month, not a cycle of this account:+ assert cc_cycle_bill_due_dates(date(2026, 7, 1), date(2026, 7, 31), 24, 18) is None+ # Half-window (one bound missing):+ assert cc_cycle_bill_due_dates(date(2026, 7, 24), None, 24, 18) is None+ # Account without both cycle days set:+ assert cc_cycle_bill_due_dates(date(2026, 7, 24), date(2026, 8, 23), None, 18) is None++ def test_clamped_close_day_across_months(self):+ from app.services.credit_card_service import cc_cycle_bill_due_dates+ # close=31 clamps to 01-31 then 02-28 (2026 is not a leap year).+ r = cc_cycle_bill_due_dates(date(2026, 1, 31), date(2026, 2, 27), 31, 30)+ assert r is not None+ assert r["this"] == date(2026, 3, 30)+ assert r["prev"] == date(2026, 2, 28)+ assert r["degenerate"] is False++ def test_degenerate_shared_due_date_is_flagged(self):+ from app.services.credit_card_service import cc_cycle_bill_due_dates+ # close=29 / due=30: the bill closing 02-28 and the bill closing+ # 03-28 both clamp to a 03-30 due date, so an override of 03-30+ # cannot name exactly one bill. Callers keep the historical window+ # behavior when this flag is set.+ r = cc_cycle_bill_due_dates(date(2026, 2, 28), date(2026, 3, 28), 29, 30)+ assert r is not None+ assert r["this"] == date(2026, 3, 30)+ assert r["prev"] == date(2026, 3, 30)+ assert r["degenerate"] is True+++class TestCycleWindowBillMembership:+ """Integration tests: the cycle view must group by the bill an override+ names, not by the purchase window that contains the due date."""++ @pytest.mark.asyncio+ async def test_override_to_previous_bill_lands_in_previous_cycle_list(+ self, session, test_user, test_workspace, cc_account_due_before_close+ ):+ """The issue scenario: a tx overridden onto the previous bill (due+ 08-18) must show in the Aug cycle (window 06-24..07-23) and leave+ the Sep cycle (window 07-24..08-23) alone."""+ from app.services.transaction_service import get_transactions+ account = cc_account_due_before_close+ moved = await _make_tx(+ session, test_user.id, account.id,+ date(2026, 7, 25), Decimal("100.00"),+ )+ moved.effective_bill_date = date(2026, 8, 18) # Aug bill's due date+ natural = await _make_tx(+ session, test_user.id, account.id,+ date(2026, 7, 1), Decimal("10.00"),+ )+ await session.commit()++ aug_txs, _, _ = await get_transactions(+ session, test_workspace.id, test_user.id, account_id=account.id,+ from_date=date(2026, 6, 24), to_date=date(2026, 7, 23),+ accounting_mode="cash",+ )+ aug_ids = {t.id for t in aug_txs}+ assert moved.id in aug_ids # override names the Aug bill+ assert natural.id in aug_ids # non-overridden txs are untouched++ sep_txs, _, _ = await get_transactions(+ session, test_workspace.id, test_user.id, account_id=account.id,+ from_date=date(2026, 7, 24), to_date=date(2026, 8, 23),+ accounting_mode="cash",+ )+ sep_ids = {t.id for t in sep_txs}+ assert moved.id not in sep_ids # no longer shown in the Sep bill+ assert natural.id not in sep_ids++ @pytest.mark.asyncio+ async def test_override_to_own_bill_due_date_stays_in_own_cycle_list(+ self, session, test_user, test_workspace, cc_account_due_before_close+ ):+ """Forward case: a tx in the Sep cycle (window 07-24..08-23) whose+ override points at its own bill's due date (09-18, after the window)+ must stay on the Sep bill instead of vanishing from it, and must not+ leak into the Oct cycle (window 08-24..09-23)."""+ from app.services.transaction_service import get_transactions+ account = cc_account_due_before_close+ tx = await _make_tx(+ session, test_user.id, account.id,+ date(2026, 8, 1), Decimal("42.00"),+ )+ tx.effective_bill_date = date(2026, 9, 18)+ await session.commit()++ sep_txs, _, _ = await get_transactions(+ session, test_workspace.id, test_user.id, account_id=account.id,+ from_date=date(2026, 7, 24), to_date=date(2026, 8, 23),+ accounting_mode="cash",+ )+ assert any(t.id == tx.id for t in sep_txs)++ oct_txs, _, _ = await get_transactions(+ session, test_workspace.id, test_user.id, account_id=account.id,+ from_date=date(2026, 8, 24), to_date=date(2026, 9, 23),+ accounting_mode="cash",+ )+ assert not any(t.id == tx.id for t in oct_txs)++ @pytest.mark.asyncio+ async def test_summary_totals_follow_override_into_named_bill(+ self, session, test_user, test_workspace, cc_account_due_before_close+ ):+ """The totals card (get_account_summary plain path) must agree with+ the list: the Aug bill shows the overridden charge, the Sep bill+ shows nothing for it."""+ account = cc_account_due_before_close+ moved = await _make_tx(+ session, test_user.id, account.id,+ date(2026, 7, 25), Decimal("100.00"),+ )+ moved.effective_bill_date = date(2026, 8, 18)+ await session.commit()++ aug = await account_service.get_account_summary(+ session, account.id, test_workspace.id,+ date_from=date(2026, 6, 24), date_to=date(2026, 7, 23),+ )+ assert aug is not None+ assert aug["monthly_expenses"] == 100.0++ sep = await account_service.get_account_summary(+ session, account.id, test_workspace.id,+ date_from=date(2026, 7, 24), date_to=date(2026, 8, 23),+ )+ assert sep is not None+ assert sep["monthly_expenses"] == 0.0++ @pytest.mark.asyncio+ async def test_override_rule_applies_to_endpoint_account_ids_shape(+ self, session, test_user, test_workspace, cc_account_due_before_close+ ):+ """The list endpoint (api/transactions) funnels its single+ account_id param into account_ids, leaving account_id None. The+ bill-based rule must fire for that shape too, or the cycle list+ silently falls back to window bucketing while the totals follow+ the override."""+ from app.services.transaction_service import get_transactions+ account = cc_account_due_before_close+ moved = await _make_tx(+ session, test_user.id, account.id,+ date(2026, 7, 25), Decimal("100.00"),+ )+ moved.effective_bill_date = date(2026, 8, 18)+ await session.commit()++ aug_txs, _, _ = await get_transactions(+ session, test_workspace.id, test_user.id, account_ids=[account.id],+ from_date=date(2026, 6, 24), to_date=date(2026, 7, 23),+ accounting_mode="cash",+ )+ assert any(t.id == moved.id for t in aug_txs)++ sep_txs, _, _ = await get_transactions(+ session, test_workspace.id, test_user.id, account_ids=[account.id],+ from_date=date(2026, 7, 24), to_date=date(2026, 8, 23),+ accounting_mode="cash",+ )+ assert not any(t.id == moved.id for t in sep_txs)+++# Bills of the close=24 / due=18 card in 2025, keyed by name:+# (cycle window start, cycle window end, due date). Each bill owns the+# overrides in (previous due date, its due date].+_CYCLES_2025 = {+ "aug": (date(2025, 6, 24), date(2025, 7, 23)), # due 08-18, owns (07-18, 08-18]+ "sep": (date(2025, 7, 24), date(2025, 8, 23)), # due 09-18, owns (08-18, 09-18]+ "oct": (date(2025, 8, 24), date(2025, 9, 23)), # due 10-18, owns (09-18, 10-18]+}+++class TestOverrideRangeRule:+ """An override belongs to the bill whose (previous due date, due date]+ range contains it, whether or not it is an exact due date. It must show+ in that bill's list and totals and in no other bill."""++ @pytest.mark.parametrize(+ "purchase, override, expected",+ [+ # Exact due dates: the bill with that due date.+ (date(2025, 7, 25), date(2025, 8, 18), "aug"),+ (date(2025, 8, 1), date(2025, 9, 18), "sep"),+ # Inside (previous due, due] but not a due date.+ (date(2025, 8, 1), date(2025, 8, 20), "sep"),+ (date(2025, 8, 1), date(2025, 9, 1), "sep"),+ (date(2025, 9, 1), date(2025, 10, 1), "oct"),+ # Right after a due date: the next bill.+ (date(2025, 7, 10), date(2025, 7, 19), "aug"),+ (date(2025, 8, 1), date(2025, 8, 19), "sep"),+ # Inside the Sep purchase window but within (07-18, 08-18],+ # so it belongs to the Aug bill.+ (date(2025, 7, 25), date(2025, 7, 25), "aug"),+ ],+ )+ @pytest.mark.asyncio+ async def test_override_shows_in_exactly_one_bill(+ self, session, test_user, test_workspace, cc_account_due_before_close,+ purchase, override, expected,+ ):+ from app.services.transaction_service import get_transactions+ account = cc_account_due_before_close+ tx = await _make_tx(+ session, test_user.id, account.id, purchase, Decimal("25.00"),+ )+ tx.effective_bill_date = override+ await session.commit()++ for name, (start, end) in _CYCLES_2025.items():+ txs, _, _ = await get_transactions(+ session, test_workspace.id, test_user.id, account_id=account.id,+ from_date=start, to_date=end, accounting_mode="cash",+ )+ summary = await account_service.get_account_summary(+ session, account.id, test_workspace.id,+ date_from=start, date_to=end,+ )+ assert summary is not None+ listed = any(t.id == tx.id for t in txs)+ if name == expected:+ assert listed, f"missing from the {name} bill list"+ assert summary["monthly_expenses"] == 25.0, name+ else:+ assert not listed, f"leaked into the {name} bill list"+ assert summary["monthly_expenses"] == 0.0, name+++async def test_charge_moved_to_previous_bill_counts_as_prior_debt(+ session, test_user, test_workspace, cc_account_due_before_close+):+ """A charge whose override moves it onto the previous bill must count+ as older debt for that bill's payment inside this window. Otherwise the+ payment settles less older debt than it really does, and the excess is+ netted against this cycle's own charges."""+ account = cc_account_due_before_close+ # Aug bill (window 06-24 to 07-23, due 08-18): 200 in its window plus a+ # 100 charge from the Sep window overridden onto it.+ await _make_tx(session, test_user.id, account.id, date(2025, 7, 1), Decimal("200.00"))+ moved = await _make_tx(+ session, test_user.id, account.id, date(2025, 7, 25), Decimal("100.00"),+ )+ moved.effective_bill_date = date(2025, 8, 18)+ # The Aug bill paid in full on its due date, inside the Sep window.+ payment = await _make_tx(+ session, test_user.id, account.id, date(2025, 8, 18), Decimal("300.00"),+ tx_type="credit",+ )+ payment.transfer_pair_id = uuid.uuid4()+ # The Sep cycle's own charges.+ await _make_tx(session, test_user.id, account.id, date(2025, 8, 1), Decimal("50.00"))+ await session.commit()++ aug = await account_service.get_account_summary(+ session, account.id, test_workspace.id,+ date_from=date(2025, 6, 24), date_to=date(2025, 7, 23),+ )+ sep = await account_service.get_account_summary(+ session, account.id, test_workspace.id,+ date_from=date(2025, 7, 24), date_to=date(2025, 8, 23),+ )+ assert aug is not None and sep is not None+ assert aug["monthly_expenses"] == pytest.approx(300.0)+ assert sep["monthly_expenses"] == pytest.approx(50.0)