Skip to content

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

fix: keep overlapping calendar balances consistent (#527)

seraphblade2010866fd5a470f9
diff --git a/backend/app/services/dashboard_service.py b/backend/app/services/dashboard_service.py
index 1a320b19..c572579a 100644
--- a/backend/app/services/dashboard_service.py
+++ b/backend/app/services/dashboard_service.py
@@ -889,10 +889,15 @@ async def _account_balance_at(
# Exclude ignored transactions from balance calculation
delta_after = await session.scalar(
select(func.coalesce(func.sum(_signed_balance_expr(account.currency)), 0))
+ .outerjoin(Category, Transaction.category_id == Category.id)
.where(
Transaction.account_id == account.id,
Transaction.date > cutoff,
Transaction.is_ignored == False,
+ or_(
+ Transaction.category_id.is_(None),
+ Category.is_ignored == False,
+ ),
)
)
return current_bal - float(delta_after or 0)
@@ -901,10 +906,15 @@ async def _account_balance_at(
# Exclude ignored transactions from balance calculation
result = await session.scalar(
select(func.coalesce(func.sum(_signed_balance_expr(account.currency)), 0))
+ .outerjoin(Category, Transaction.category_id == Category.id)
.where(
Transaction.account_id == account.id,
Transaction.date <= cutoff,
Transaction.is_ignored == False,
+ or_(
+ Transaction.category_id.is_(None),
+ Category.is_ignored == False,
+ ),
)
)
return float(result or 0)
diff --git a/backend/app/services/transaction_calendar_service.py b/backend/app/services/transaction_calendar_service.py
index 8be40336..69c22901 100644
--- a/backend/app/services/transaction_calendar_service.py
+++ b/backend/app/services/transaction_calendar_service.py
@@ -119,7 +119,7 @@ async def get_transaction_calendar(
day.actual_count += 1
day.items.append(_actual_item(tx, amount_primary, is_transfer, ignored))
- projected_items, projected_deltas = await _project_recurring_items(
+ projected_items, projected_deltas, carried_projected_delta = await _project_recurring_items(
session,
workspace_id,
primary_currency,
@@ -127,6 +127,7 @@ async def get_transaction_calendar(
grid_end,
requested_account_ids,
)
+ start_balance += carried_projected_delta
for item, signed_delta in projected_items:
day = days[item.date]
amount_primary = abs(signed_delta)
@@ -305,6 +306,35 @@ def _actual_item(
)
+def _count_occurrences_before(recurring: RecurringTransaction, end: date) -> int:
+ """Count still-virtual occurrences before ``end`` without truncating."""
+ range_end = end
+ if recurring.end_date is not None and recurring.end_date < range_end:
+ range_end = recurring.end_date + timedelta(days=1)
+
+ range_start = recurring.next_occurrence
+ occurrence_start = recurring.next_occurrence
+ count = 0
+ while range_start < range_end:
+ # Weekly is the shortest supported cadence. Two hundred-week chunks
+ # stay within the occurrence helper's collection limit while allowing
+ # an arbitrarily long carry horizon.
+ chunk_end = min(range_start + timedelta(weeks=200), range_end)
+ occurrences = get_occurrences_in_range(
+ start=occurrence_start,
+ frequency=recurring.frequency,
+ end_date=recurring.end_date,
+ range_start=range_start,
+ range_end=chunk_end,
+ intended_day=recurring.day_of_month or recurring.start_date.day,
+ )
+ count += len(occurrences)
+ if occurrences:
+ occurrence_start = occurrences[-1]
+ range_start = chunk_end
+ return count
+
+
async def _project_recurring_items(
session: AsyncSession,
workspace_id: uuid.UUID,
@@ -312,7 +342,7 @@ async def _project_recurring_items(
start: date,
end: date,
account_ids: Optional[list[uuid.UUID]],
-) -> tuple[list[tuple[TransactionCalendarItem, float]], dict[date, float]]:
+) -> tuple[list[tuple[TransactionCalendarItem, float]], dict[date, float], float]:
stmt = (
select(RecurringTransaction)
.join(Account, RecurringTransaction.account_id == Account.id)
@@ -335,6 +365,7 @@ async def _project_recurring_items(
items: list[tuple[TransactionCalendarItem, float]] = []
deltas: dict[date, float] = {}
+ carried_delta = 0.0
for rec in recurring_rows:
if rec.account_id is None:
continue
@@ -354,6 +385,8 @@ async def _project_recurring_items(
signed_delta = amount_primary if rec.type == "credit" else -amount_primary
is_transfer = bool(category and category.treat_as_transfer)
is_ignored = bool(category and category.is_ignored)
+ if not is_ignored:
+ carried_delta += _count_occurrences_before(rec, start) * signed_delta
for occ_date in occurrences:
item = TransactionCalendarItem(
kind="projected",
@@ -381,4 +414,4 @@ async def _project_recurring_items(
# balance that reverts the day the recurring actually posts.
if not is_ignored:
deltas[occ_date] = deltas.get(occ_date, 0.0) + signed_delta
- return items, deltas
+ return items, deltas, carried_delta
diff --git a/backend/tests/test_dashboard_service.py b/backend/tests/test_dashboard_service.py
index e4289565..2901764e 100644
--- a/backend/tests/test_dashboard_service.py
+++ b/backend/tests/test_dashboard_service.py
@@ -178,6 +178,98 @@ async def test_account_balance_at_bank_connected(session: AsyncSession, test_use
assert bal == pytest.approx(4700.0)
+async def test_account_balance_at_manual_excludes_ignored_categories(
+ session: AsyncSession, test_user
+):
+ account = await _make_account(session, test_user.id, "Manual ignored")
+ ignored = Category(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ name="Ignored",
+ is_ignored=True,
+ )
+ ordinary = Category(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ name="Ordinary",
+ is_ignored=False,
+ )
+ session.add_all([ignored, ordinary])
+ await session.commit()
+
+ await _add_txn(
+ session, test_user.id, account.id, 1000, "credit",
+ date(2026, 7, 1), source="opening_balance",
+ )
+ await _add_txn(
+ session, test_user.id, account.id, 100, "debit",
+ date(2026, 8, 3), category_id=ignored.id,
+ )
+ await _add_txn(
+ session, test_user.id, account.id, 40, "debit",
+ date(2026, 8, 4), category_id=ordinary.id,
+ )
+ await _add_txn(
+ session, test_user.id, account.id, 10, "debit",
+ date(2026, 8, 5),
+ )
+
+ balance = await _account_balance_at(session, account, date(2026, 9, 1))
+
+ assert balance == pytest.approx(950.0)
+
+
+async def test_account_balance_at_connected_excludes_ignored_categories(
+ session: AsyncSession, test_user, test_connection
+):
+ account = await _make_account(
+ session,
+ test_user.id,
+ "Connected ignored",
+ balance="850.00",
+ connection_id=test_connection.id,
+ )
+ ignored = Category(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ name="Ignored",
+ is_ignored=True,
+ )
+ ordinary = Category(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ name="Ordinary",
+ is_ignored=False,
+ )
+ session.add_all([ignored, ordinary])
+ await session.commit()
+
+ await _add_txn(
+ session, test_user.id, account.id, 100, "debit",
+ date(2026, 8, 2), category_id=ignored.id,
+ )
+ individually_ignored = await _add_txn(
+ session, test_user.id, account.id, 50, "debit",
+ date(2026, 8, 3),
+ )
+ individually_ignored.is_ignored = True
+ await _add_txn(
+ session, test_user.id, account.id, 200, "credit",
+ date(2026, 8, 4),
+ )
+ await _add_txn(
+ session, test_user.id, account.id, 50, "debit",
+ date(2026, 8, 5), category_id=ordinary.id,
+ )
+ await session.commit()
+
+ balance = await _account_balance_at(session, account, date(2026, 8, 1))
+
+ assert balance == pytest.approx(700.0)
+
+
@pytest.mark.asyncio
async def test_account_balance_at_credit_card_connected(session: AsyncSession, test_user, test_connection):
"""Bank-connected credit_card negates balance."""
@@ -724,6 +816,80 @@ async def test_balance_history_basic(session, test_user, test_workspace):
assert len(history.previous) > 0
+async def test_balance_history_ignored_category_is_consistent_across_months(
+ session: AsyncSession, test_user, test_workspace
+):
+ account = Account(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ name="Ignored boundary",
+ type="checking",
+ balance=Decimal("0"),
+ currency="BRL",
+ )
+ ignored = Category(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ name="Ignored",
+ is_ignored=True,
+ )
+ session.add_all([account, ignored])
+ await session.flush()
+ session.add_all([
+ Transaction(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ account_id=account.id,
+ description="Opening",
+ amount=Decimal("1000"),
+ currency="BRL",
+ date=date(2026, 7, 1),
+ type="credit",
+ source="opening_balance",
+ ),
+ Transaction(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ account_id=account.id,
+ category_id=ignored.id,
+ description="Ignored debit",
+ amount=Decimal("100"),
+ currency="BRL",
+ date=date(2026, 8, 3),
+ type="debit",
+ source="manual",
+ is_ignored=False,
+ ),
+ ])
+ await session.commit()
+
+ august = await get_balance_history(
+ session,
+ test_workspace.id,
+ test_user.id,
+ month=date(2026, 8, 1),
+ account_ids=[account.id],
+ )
+ september = await get_balance_history(
+ session,
+ test_workspace.id,
+ test_user.id,
+ month=date(2026, 9, 1),
+ account_ids=[account.id],
+ )
+
+ august_balance = next(
+ point.balance for point in reversed(august.current) if point.balance is not None
+ )
+ assert august_balance == 1000.0
+ assert september.current[0].balance == 1000.0
+
+
@pytest.mark.asyncio
async def test_balance_history_past_month(session, test_user, test_workspace):
past = date.today().replace(day=1) - timedelta(days=15)
diff --git a/backend/tests/test_transaction_calendar_service.py b/backend/tests/test_transaction_calendar_service.py
index 671190cc..e0bf5fe4 100644
--- a/backend/tests/test_transaction_calendar_service.py
+++ b/backend/tests/test_transaction_calendar_service.py
@@ -494,3 +494,274 @@ async def test_transaction_calendar_ignored_projection_matches_posted_balance(
# and snapped back as each one posted.
for day in (date(2026, 7, 6), date(2026, 7, 13), date(2026, 7, 20), date(2026, 7, 27)):
assert by_date[day].ending_balance == 1000.0
+
+
+async def test_transaction_calendar_overlap_carries_virtual_occurrences(
+ session: AsyncSession, test_user, test_workspace
+):
+ account = Account(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ name="Checking",
+ type="checking",
+ balance=Decimal("0"),
+ currency="BRL",
+ )
+ session.add(account)
+ await session.flush()
+
+ recurring = RecurringTransaction(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ account_id=account.id,
+ description="Weekly debit",
+ amount=Decimal("100"),
+ currency="BRL",
+ type="debit",
+ frequency="weekly",
+ start_date=date(2026, 8, 3),
+ next_occurrence=date(2026, 8, 3),
+ )
+ session.add_all([
+ Transaction(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ account_id=account.id,
+ description="Opening",
+ amount=Decimal("1000"),
+ currency="BRL",
+ date=date(2026, 7, 1),
+ type="credit",
+ source="opening_balance",
+ ),
+ recurring,
+ ])
+ await session.commit()
+
+ august = await get_transaction_calendar(
+ session, test_workspace.id, test_user.id, month=date(2026, 8, 1)
+ )
+ september = await get_transaction_calendar(
+ session, test_workspace.id, test_user.id, month=date(2026, 9, 1)
+ )
+ august_by_date = {day.date: day for day in august.days}
+ september_by_date = {day.date: day for day in september.days}
+
+ august_september_1 = august_by_date[date(2026, 9, 1)]
+ september_september_1 = september_by_date[date(2026, 9, 1)]
+ assert august_september_1.ending_balance == 500.0
+ assert september_september_1.ending_balance == 500.0
+ assert august_september_1.ending_balance == september_september_1.ending_balance
+
+ september_grid_start = september_by_date[date(2026, 8, 30)]
+ assert september_grid_start.ending_balance == 600.0
+ assert september_grid_start.projected_count == 0
+ assert september_grid_start.income == 0.0
+ assert september_grid_start.expense == 0.0
+ assert september_grid_start.transfer_net == 0.0
+ assert september_grid_start.items == []
+
+
+async def test_transaction_calendar_does_not_carry_ignored_virtual_occurrences(
+ session: AsyncSession, test_user, test_workspace
+):
+ account = Account(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ name="Checking",
+ type="checking",
+ balance=Decimal("0"),
+ currency="BRL",
+ )
+ ignored_category = Category(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ name="Ignored",
+ icon="eye-off",
+ color="#64748b",
+ is_ignored=True,
+ )
+ session.add_all([account, ignored_category])
+ await session.flush()
+
+ recurring = RecurringTransaction(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ account_id=account.id,
+ category_id=ignored_category.id,
+ description="Ignored weekly debit",
+ amount=Decimal("100"),
+ currency="BRL",
+ type="debit",
+ frequency="weekly",
+ start_date=date(2026, 8, 3),
+ next_occurrence=date(2026, 8, 3),
+ )
+ session.add_all([
+ Transaction(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ account_id=account.id,
+ description="Opening",
+ amount=Decimal("1000"),
+ currency="BRL",
+ date=date(2026, 7, 1),
+ type="credit",
+ source="opening_balance",
+ ),
+ recurring,
+ ])
+ await session.commit()
+
+ calendar = await get_transaction_calendar(
+ session, test_workspace.id, test_user.id, month=date(2026, 9, 1)
+ )
+ by_date = {day.date: day for day in calendar.days}
+
+ grid_start = by_date[date(2026, 8, 30)]
+ assert grid_start.ending_balance == 1000.0
+ assert grid_start.projected_count == 0
+ assert grid_start.items == []
+
+ visible_occurrence = by_date[date(2026, 8, 31)]
+ assert visible_occurrence.ending_balance == 1000.0
+ assert visible_occurrence.projected_count == 1
+ assert visible_occurrence.projected_expense == 0.0
+ assert visible_occurrence.items[0].recurring_id == recurring.id
+ assert visible_occurrence.items[0].is_ignored is True
+ assert by_date[date(2026, 9, 1)].ending_balance == 1000.0
+
+
+async def test_transaction_calendar_carries_more_than_occurrence_safety_limit(
+ session: AsyncSession, test_user, test_workspace
+):
+ account = Account(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ name="Checking",
+ type="checking",
+ balance=Decimal("0"),
+ currency="BRL",
+ )
+ session.add(account)
+ await session.flush()
+ session.add_all([
+ Transaction(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ account_id=account.id,
+ description="Opening",
+ amount=Decimal("1000"),
+ currency="BRL",
+ date=date(2019, 12, 1),
+ type="credit",
+ source="opening_balance",
+ ),
+ RecurringTransaction(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ account_id=account.id,
+ description="Long-running weekly debit",
+ amount=Decimal("1"),
+ currency="BRL",
+ type="debit",
+ frequency="weekly",
+ start_date=date(2020, 1, 6),
+ next_occurrence=date(2020, 1, 6),
+ ),
+ ])
+ await session.commit()
+
+ calendar = await get_transaction_calendar(
+ session, test_workspace.id, test_user.id, month=date(2026, 9, 1)
+ )
+ grid_start = next(day for day in calendar.days if day.date == date(2026, 8, 30))
+
+ # 347 weekly occurrences precede the grid, exceeding the helper's 200-row
+ # safety limit. Every one contributes to the carried balance, but no item.
+ assert grid_start.ending_balance == 653.0
+ assert grid_start.projected_count == 0
+ assert grid_start.items == []
+
+
+async def test_transaction_calendar_ignored_actual_is_consistent_across_months(
+ session: AsyncSession, test_user, test_workspace
+):
+ account = Account(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ name="Checking",
+ type="checking",
+ balance=Decimal("0"),
+ currency="BRL",
+ )
+ ignored_category = Category(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ name="Ignored",
+ icon="eye-off",
+ color="#64748b",
+ is_ignored=True,
+ )
+ session.add_all([account, ignored_category])
+ await session.flush()
+ session.add_all([
+ Transaction(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ account_id=account.id,
+ description="Opening",
+ amount=Decimal("1000"),
+ currency="BRL",
+ date=date(2026, 7, 1),
+ type="credit",
+ source="opening_balance",
+ ),
+ Transaction(
+ id=uuid.uuid4(),
+ user_id=test_user.id,
+ workspace_id=test_workspace.id,
+ account_id=account.id,
+ category_id=ignored_category.id,
+ description="Ignored debit",
+ amount=Decimal("100"),
+ currency="BRL",
+ date=date(2026, 8, 3),
+ type="debit",
+ source="manual",
+ is_ignored=False,
+ ),
+ ])
+ await session.commit()
+
+ august = await get_transaction_calendar(
+ session, test_workspace.id, test_user.id, month=date(2026, 8, 1)
+ )
+ september = await get_transaction_calendar(
+ session, test_workspace.id, test_user.id, month=date(2026, 9, 1)
+ )
+ august_by_date = {day.date: day for day in august.days}
+ september_by_date = {day.date: day for day in september.days}
+
+ august_september_1 = august_by_date[date(2026, 9, 1)]
+ september_september_1 = september_by_date[date(2026, 9, 1)]
+ assert august_september_1.ending_balance == 1000.0
+ assert september_september_1.ending_balance == 1000.0
+ assert august_september_1.ending_balance == september_september_1.ending_balance