Open-source personal finance manager. Self-hosted, privacy-first.
fix(accounts): net intermediate card payments into the bill total (#1267)
Tássio Noronha446351bd0c32
diff --git a/backend/app/services/_query_filters.py b/backend/app/services/_query_filters.pyindex 707b38fb..891fe3f5 100644--- a/backend/app/services/_query_filters.py+++ b/backend/app/services/_query_filters.py@@ -177,21 +177,27 @@ def counts_as_pnl():)-def counts_on_bill():+def counts_on_bill(net_payments: bool = False):"""SQL filter: True when a transaction belongs on a credit-card bill.A bill total is an *amount owed*, not a reporting figure, and the twoanswer to different authorities: the bill has to match what the banksays you owe, while P/L answers to how the user chose to categorizetheir spending. So the card's cycle total cannot reuse- `counts_as_pnl` — every judgment that helper makes about what counts+ `counts_as_pnl`. Every judgment that helper makes about what countsas *spending* is a judgment the bank never made.Kept out, because they are genuinely not charges on this bill:- - paired transfers (the bill *payment* is not a purchase),+ - paired transfers, by default (the bill *payment* is not a+ purchase). With ``net_payments=True`` the *credit* leg of a+ paired transfer counts instead: an intermediate payment into the+ card shrinks the amount owed, the way a refund does. Callers+ net only what is left after the payment settles any debt that+ was already outstanding (banks apply repayments oldest first),+ see `get_account_summary`.- settlement debits (a repayment of a share already booked),- rows the user flagged `is_ignored`, on the transaction or its- category — those leave the account balance too, so dropping them+ category. Those leave the account balance too, so dropping themfrom the bill keeps the card's two numbers telling one story.`treat_as_transfer` categories are handled asymmetrically, and this is@@ -226,12 +232,37 @@ def counts_on_bill():transfer_category = Transaction.category_id.in_(select(Category.id).where(Category.treat_as_transfer.is_(True)))+ if net_payments:+ # The credit leg of a paired transfer is a payment by+ # construction: the pair proves the money moved between the+ # user's own accounts, so the pair itself and a transfer-like+ # category tag on it cannot keep it off the bill.+ paired_payment = and_(+ Transaction.type == "credit",+ Transaction.transfer_pair_id.is_not(None),+ )+ transfer_clause = or_(+ Transaction.transfer_pair_id.is_(None), paired_payment,+ )+ category_clause = or_(+ Transaction.type == "debit",+ Transaction.category_id.is_(None),+ ~transfer_category,+ paired_payment,+ )+ else:+ transfer_clause = Transaction.transfer_pair_id.is_(None)+ category_clause = or_(+ Transaction.type == "debit",+ Transaction.category_id.is_(None),+ ~transfer_category,+ )return and_(- Transaction.transfer_pair_id.is_(None),+ transfer_clause,Transaction.is_ignored.is_(False),~and_(Transaction.source == "settlement", Transaction.type == "debit"),or_(Transaction.category_id.is_(None), ~ignored_category),- or_(Transaction.type == "debit", Transaction.category_id.is_(None), ~transfer_category),+ category_clause,)diff --git a/backend/app/services/account_service.py b/backend/app/services/account_service.pyindex 59737902..e12f4cc4 100644--- a/backend/app/services/account_service.py+++ b/backend/app/services/account_service.py@@ -1009,6 +1009,69 @@ async def get_account_summary(counts_on_bill() if account.type == "credit_card" else counts_as_pnl())+ # Intermediate payments into the card (the credit leg of a paired+ # transfer) reduce the bill total, but only by what is left after+ # they settle the debt that was already outstanding when the window+ # opened. Banks apply repayments oldest first: paying last cycle's+ # bill inside this window must not read as this cycle's charges+ # disappearing, while anything paid beyond that older debt can only+ # settle this cycle's charges, so the bank bills the net (issue #668).+ prior_debt = 0.0+ paid_now = 0.0+ paid_later = 0.0+ if account.type == "credit_card":+ prior_result = await session.execute(+ select(func.coalesce(func.sum(+ case(+ (Transaction.type == "credit", effective_amount),+ else_=-effective_amount,+ )+ ), 0)).where(+ Transaction.account_id == account_id,+ bucket_date < date_from,+ # 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_(+ Transaction.bill_id.is_(None), Transaction.bill_id != bill_id,+ )]),+ Transaction.is_ignored == False,+ or_(+ Transaction.category_id.is_(None),+ Transaction.category_id.not_in(+ select(Category.id).where(Category.is_ignored == True)+ ),+ ),+ )+ )+ prior_debt = max(0.0, -float(prior_result.scalar() or 0))+ paired_payment = and_(+ counts_on_bill(net_payments=True),+ Transaction.type == "credit",+ Transaction.transfer_pair_id.is_not(None),+ Transaction.source != "opening_balance",+ )+ paid_now_result = await session.execute(+ _scope(select(func.coalesce(func.sum(func.abs(effective_amount)), 0)).where(+ Transaction.account_id == account_id,+ bucket_date <= today,+ Transaction.status == "posted",+ paired_payment,+ ))+ )+ paid_now = float(paid_now_result.scalar() or 0)+ paid_later_result = await session.execute(+ _scope(select(func.coalesce(func.sum(func.abs(effective_amount)), 0)).where(+ Transaction.account_id == account_id,+ or_(Transaction.status == "pending", bucket_date > today),+ paired_payment,+ ))+ )+ paid_later = float(paid_later_result.scalar() or 0)+ # What the posted payments leave over after the older debt, and what+ # the pending/future ones add on top of that.+ netted_now = max(0.0, paid_now - prior_debt)+ netted_total = max(0.0, paid_now + paid_later - prior_debt)+# Income = SUM of credit transactions in window (excluding opening_balance# and paired transfers).income_result = await session.execute(@@ -1025,11 +1088,12 @@ async def get_account_summary(# Expenses = SUM of debit transactions in window (same exclusions).# For credit-card accounts, NET refund credits against debits so the- # cycle's "Total da fatura" matches the bank's bill (refunds reduce the- # invoice amount). Paired transfers are dropped by `transfer_pair_id`;- # unpaired card payments are dropped by the credit-side `treat_as_transfer`- # exclusion in `counts_on_bill` (see its docstring for why that's- # asymmetric with the debit side).+ # cycle's "Total da fatura" matches the bank's bill (refunds reduce+ # the invoice amount). Paired transfers are dropped by `transfer_pair_id`+ # and netted separately below (see `netted_now`); unpaired card payments+ # are dropped by the credit-side `treat_as_transfer` exclusion in+ # `counts_on_bill` (see its docstring for why that's asymmetric with the+ # debit side).if account.type == "credit_card":signed_for_bill = case((Transaction.type == "credit", -func.abs(effective_amount)),@@ -1054,7 +1118,7 @@ async def get_account_summary(summary_filter,)))- monthly_expenses = float(expenses_result.scalar())+ monthly_expenses = float(expenses_result.scalar()) - netted_now# Forecast values use the same cycle/date scope as the actual totals, but# include every pending row and every row bucketed after today. The current@@ -1094,7 +1158,9 @@ async def get_account_summary(summary_filter,)))- forecast_expenses = float(forecast_expense_result.scalar() or 0)+ forecast_expenses = float(forecast_expense_result.scalar() or 0) - (+ netted_total - netted_now+ )opening_balance = (await get_period_opening_balance(session, account, date_from)diff --git a/backend/tests/test_account_service.py b/backend/tests/test_account_service.pyindex 7d307e2a..7de82a94 100644--- a/backend/tests/test_account_service.py+++ b/backend/tests/test_account_service.py@@ -922,6 +922,160 @@ async def test_get_account_summary_bill_unpaired_payment_credit_still_nets_out(assert summary["monthly_expenses"] == pytest.approx(100.0)+async def test_get_account_summary_bill_nets_paired_payment_when_cycle_starts_flat(+ session: AsyncSession, test_user, test_workspace+):+ """An intermediate payment into the card (the credit leg of a paired+ transfer) nets against the bill total when the window started with no+ prior debt: nothing older exists for the payment to settle, so the+ bank bills the net (issue #668)."""+ account = await _make_account(session, test_user.id, "CC Mid Pay", acc_type="credit_card")+ today = date.today()+ pair_id = uuid.uuid4()++ await _add_txn(session, test_user.id, account.id, 1000, "debit", today)+ await _add_txn(session, test_user.id, account.id, 100, "credit", today)+ await _add_txn(session, test_user.id, account.id, 400, "credit", today,+ transfer_pair_id=pair_id)++ summary = await get_account_summary(session, account.id, test_workspace.id)+ assert summary is not None+ # 1000 (charge) - 100 (refund) - 400 (intermediate payment) = 500+ assert summary["monthly_expenses"] == pytest.approx(500.0)+ # the payment is not income; the refund still is+ assert summary["monthly_income"] == pytest.approx(100.0)+++async def test_get_account_summary_bill_nets_only_payment_beyond_prior_debt(+ session: AsyncSession, test_user, test_workspace+):+ """With last cycle's bill still open when the window starts, a payment+ first settles that older debt; only the excess nets this cycle's bill+ total (issue #668)."""+ account = await _make_account(session, test_user.id, "CC Mid Pay Prior", acc_type="credit_card")+ today = date.today()+ last_month = today.replace(day=1) - timedelta(days=1)++ await _add_txn(session, test_user.id, account.id, 800, "debit", last_month)+ await _add_txn(session, test_user.id, account.id, 1000, "debit", today)+ # 800 pays last cycle's bill, 400 is the intermediate payment.+ await _add_txn(session, test_user.id, account.id, 800, "credit", today,+ transfer_pair_id=uuid.uuid4())+ await _add_txn(session, test_user.id, account.id, 400, "credit", today,+ transfer_pair_id=uuid.uuid4())++ summary = await get_account_summary(session, account.id, test_workspace.id)+ assert summary is not None+ assert summary["monthly_expenses"] == pytest.approx(600.0)+ assert summary["projected_expenses"] == pytest.approx(600.0)+ assert summary["monthly_income"] == pytest.approx(0.0)+++async def test_get_account_summary_bill_payment_of_prior_debt_leaves_cycle_total(+ session: AsyncSession, test_user, test_workspace+):+ """Paying only last cycle's bill inside this window does not reduce+ this cycle's bill total (issue #668)."""+ account = await _make_account(session, test_user.id, "CC Prior Only", acc_type="credit_card")+ today = date.today()+ last_month = today.replace(day=1) - timedelta(days=1)++ await _add_txn(session, test_user.id, account.id, 800, "debit", last_month)+ await _add_txn(session, test_user.id, account.id, 1000, "debit", today)+ await _add_txn(session, test_user.id, account.id, 800, "credit", today,+ transfer_pair_id=uuid.uuid4())++ summary = await get_account_summary(session, account.id, test_workspace.id)+ assert summary is not None+ assert summary["monthly_expenses"] == pytest.approx(1000.0)+ assert summary["projected_expenses"] == pytest.approx(1000.0)+++async def test_get_account_summary_bill_linked_pre_window_payment_is_not_prior_debt(+ session: AsyncSession, test_user, test_workspace+):+ """With a synced bill selected, a paired payment linked to that bill+ but dated before the window already counts as paid on the bill, so it+ must not also cancel the older debt: 100 prior debt and a 100 linked+ payment leave nothing to net against this cycle (issue #668)."""+ from datetime import datetime, timezone+ from app.models.credit_card_bill import CreditCardBill++ account = await _make_account(session, test_user.id, "CC Linked Pay", acc_type="credit_card")+ today = date.today()+ last_month = today.replace(day=1) - timedelta(days=1)+ bill = CreditCardBill(+ user_id=test_user.id, account_id=account.id, external_id="bill-668",+ due_date=today + timedelta(days=10), total_amount=Decimal("1000"),+ currency="BRL", created_at=datetime.now(timezone.utc),+ updated_at=datetime.now(timezone.utc),+ )+ session.add(bill)+ await session.commit()++ await _add_txn(session, test_user.id, account.id, 100, "debit", last_month)+ payment = await _add_txn(session, test_user.id, account.id, 100, "credit", last_month,+ transfer_pair_id=uuid.uuid4())+ charge = await _add_txn(session, test_user.id, account.id, 1000, "debit", today)+ payment.bill_id = bill.id+ charge.bill_id = bill.id+ await session.commit()++ summary = await get_account_summary(+ session, account.id, test_workspace.id, bill_id=bill.id,+ )+ assert summary is not None+ assert summary["monthly_expenses"] == pytest.approx(1000.0)+ assert summary["projected_expenses"] == pytest.approx(1000.0)+++async def test_get_account_summary_bill_nets_paired_payment_with_transfer_category(+ session: AsyncSession, test_user, test_workspace+):+ """A paired payment filed under a transfer-like category still nets+ the bill total: the transfer pair already proves it is a payment, so+ the category tag cannot flip it back into 'not a payment'+ (issue #668)."""+ account = await _make_account(session, test_user.id, "CC Mid Pay Cat", acc_type="credit_card")+ today = date.today()+ pair_id = uuid.uuid4()+ transfer_cat = await _make_category(session, test_user.id, treat_as_transfer=True)++ await _add_txn(session, test_user.id, account.id, 1000, "debit", today)+ await _add_txn(session, test_user.id, account.id, 400, "credit", today,+ transfer_pair_id=pair_id, category_id=transfer_cat.id)++ summary = await get_account_summary(session, account.id, test_workspace.id)+ assert summary is not None+ assert summary["monthly_expenses"] == pytest.approx(600.0)+++async def test_get_account_summary_bill_nets_pending_paired_payment_in_projection(+ session: AsyncSession, test_user, test_workspace+):+ """A payment the user marked pending still nets the projected bill+ total: the projection is the final-bill estimate, and a scheduled+ payment is part of it (issue #668)."""+ account = await _make_account(session, test_user.id, "CC Mid Pay Pending", acc_type="credit_card")+ today = date.today()+ pair_id = uuid.uuid4()++ await _add_txn(session, test_user.id, account.id, 1000, "debit", today)+ await _add_txn(session, test_user.id, account.id, 400, "credit", today,+ transfer_pair_id=pair_id, status="pending")++ summary = await get_account_summary(session, account.id, test_workspace.id)+ assert summary is not None+ assert summary["monthly_expenses"] == pytest.approx(1000.0)+ assert summary["projected_expenses"] == pytest.approx(600.0)++@pytest.mark.asyncioasync def test_get_account_summary_bill_excludes_ignored_category_charge(session: AsyncSession, test_user, test_workspace