Open-source personal finance manager. Self-hosted, privacy-first.
fix sync opening_balance on Pluggy accounts to match provider balance
Tássio Noronhafcaea5a85b65
diff --git a/backend/alembic/versions/029_backfill_opening_balance_for_connected_accounts.py b/backend/alembic/versions/029_backfill_opening_balance_for_connected_accounts.pynew file mode 100644index 00000000..c14e01ec--- /dev/null+++ b/backend/alembic/versions/029_backfill_opening_balance_for_connected_accounts.py@@ -0,0 +1,144 @@+"""backfill opening_balance for connected accounts++Revision ID: 029+Revises: 028+Create Date: 2026-04-16++Providers only return ~1 year of history but report the true current balance,+so for every existing Pluggy-linked account the sum of imported transactions+doesn't equal account.balance. The difference is the account's real balance+at the start of the import window, which was never recorded anywhere. This+migration inserts a synthetic `source='opening_balance'` transaction on each+connected account so that SUM(txs) = account.balance going forward — making+balance_history and the running-balance column in the UI line up with the+card balance.++Idempotent: skips accounts that already have an opening_balance transaction.+"""++import uuid+from datetime import timedelta+from decimal import Decimal++from alembic import op+from sqlalchemy import text++revision = "029"+down_revision = "028"+branch_labels = None+depends_on = None+++def upgrade() -> None:+ conn = op.get_bind()++ # Connected accounts that don't already have an opening_balance tx+ accounts = conn.execute(+ text(+ """+ SELECT a.id, a.user_id, a.balance, a.currency, a.type+ FROM accounts a+ WHERE a.connection_id IS NOT NULL+ AND NOT EXISTS (+ SELECT 1 FROM transactions t+ WHERE t.account_id = a.id AND t.source = 'opening_balance'+ )+ """+ )+ ).fetchall()++ for acc in accounts:+ acc_id, user_id, balance, currency, acc_type = acc+ is_cc = acc_type == "credit_card"+ # CC balance is stored as positive debt and displayed negated, so the+ # target that SUM(signed txs) must hit is -balance. Other accounts+ # target the stored balance directly.+ target = (-Decimal(balance)) if is_cc else Decimal(balance)++ row = conn.execute(+ text(+ """+ SELECT+ COALESCE(SUM(+ CASE+ WHEN t.type = 'credit' THEN+ CASE+ WHEN t.currency = :acc_currency THEN t.amount+ ELSE COALESCE(t.amount_primary, t.amount)+ END+ ELSE+ -CASE+ WHEN t.currency = :acc_currency THEN t.amount+ ELSE COALESCE(t.amount_primary, t.amount)+ END+ END+ ), 0) AS tx_sum,+ MIN(t.date) AS oldest_date+ FROM transactions t+ WHERE t.account_id = :acc_id+ AND t.source <> 'opening_balance'+ """+ ),+ {"acc_id": acc_id, "acc_currency": currency},+ ).fetchone()++ tx_sum = Decimal(str(row[0] or 0))+ oldest_date = row[1]+ offset = (target - tx_sum).quantize(Decimal("0.01"))++ # Sub-cent offsets are rounding noise; no backfill needed.+ if abs(offset) < Decimal("0.01"):+ continue++ opening_type = "credit" if offset > 0 else "debit"+ amount = abs(offset)+ opening_date = (oldest_date - timedelta(days=1)) if oldest_date else None++ if opening_date is None:+ # No transactions yet — skip; first sync will create the opening tx.+ continue++ conn.execute(+ text(+ """+ INSERT INTO transactions (+ id, user_id, account_id, description, amount, currency,+ date, effective_date, type, source, status, created_at+ ) VALUES (+ :id, :user_id, :account_id, :description, :amount, :currency,+ :date, :effective_date, :type, 'opening_balance', 'posted', NOW()+ )+ """+ ),+ {+ "id": str(uuid.uuid4()),+ "user_id": str(user_id),+ "account_id": str(acc_id),+ "description": "Saldo inicial",+ "amount": amount,+ "currency": currency,+ "date": opening_date,+ "effective_date": opening_date,+ "type": opening_type,+ },+ )+++def downgrade() -> None:+ # Reverse: drop every synthetic opening_balance on connected accounts that+ # this migration could have created. Can't distinguish rows created here+ # from ones created later by the sync service, so we match on description+ # + source + connected-ness, which is the signature this migration writes.+ conn = op.get_bind()+ conn.execute(+ text(+ """+ DELETE FROM transactions+ WHERE source = 'opening_balance'+ AND description = 'Saldo inicial'+ AND account_id IN (+ SELECT id FROM accounts WHERE connection_id IS NOT NULL+ )+ """+ )+ )diff --git a/backend/app/services/account_service.py b/backend/app/services/account_service.pyindex 3f027c15..38e9b5d9 100644--- a/backend/app/services/account_service.py+++ b/backend/app/services/account_service.py@@ -290,6 +290,101 @@ async def _recompute_effective_dates(session: AsyncSession, account: Account) ->apply_effective_date(tx, account)+async def sync_opening_balance_for_connected_account(+ session: AsyncSession, account: Account+) -> None:+ """Reconcile the opening_balance transaction so SUM(all txs) = account.balance.++ Providers (Pluggy etc.) typically only return ~1 year of history, so the sum+ of imported transactions rarely equals the account's true current balance.+ This helper computes the missing opening balance and upserts a synthetic+ `source='opening_balance'` transaction that closes the gap. After this runs,+ balance_history and running-balance walks line up with the card balance.++ Call after adding new transactions in a sync (initial or incremental).+ Does not commit; the caller is responsible for the transaction boundary.+ """+ if account.connection_id is None:+ return++ # For connected CC accounts the stored balance is positive debt and the UI+ # displays it negated (account_service.serialize_account). The sum of signed+ # transaction amounts on a CC trends negative as debt accrues, so the target+ # we want SUM(signed txs) to hit is -balance. For every other account type+ # the target is simply the stored balance.+ is_cc = account.type == "credit_card"+ target = -account.balance if is_cc else account.balance++ effective_amount = case(+ (Transaction.currency == account.currency, Transaction.amount),+ else_=func.coalesce(Transaction.amount_primary, Transaction.amount),+ )+ signed_amount = case(+ (Transaction.type == "credit", effective_amount),+ else_=-effective_amount,+ )++ sum_result = await session.execute(+ select(func.coalesce(func.sum(signed_amount), 0)).where(+ Transaction.account_id == account.id,+ Transaction.source != "opening_balance",+ )+ )+ tx_sum = Decimal(str(sum_result.scalar() or 0))++ offset = Decimal(str(target)) - tx_sum++ existing = await session.execute(+ select(Transaction).where(+ Transaction.account_id == account.id,+ Transaction.source == "opening_balance",+ )+ )+ existing_tx = existing.scalar_one_or_none()++ # Offsets below one cent are rounding noise; drop any stale opening tx.+ if abs(offset) < Decimal("0.01"):+ if existing_tx:+ await session.delete(existing_tx)+ return++ oldest_result = await session.execute(+ select(func.min(Transaction.date)).where(+ Transaction.account_id == account.id,+ Transaction.source != "opening_balance",+ )+ )+ oldest_date = oldest_result.scalar()+ opening_date = (oldest_date - timedelta(days=1)) if oldest_date else _Date.today()++ # Sign convention matches the rest of the codebase: credit = +, debit = -+ # regardless of account type. A positive offset needs a credit to raise the+ # running sum to target; a negative offset needs a debit.+ opening_type = "credit" if offset > 0 else "debit"+ amount = abs(offset).quantize(Decimal("0.01"))++ if existing_tx:+ existing_tx.amount = amount+ existing_tx.type = opening_type+ existing_tx.date = opening_date+ existing_tx.currency = account.currency+ apply_effective_date(existing_tx, account)+ else:+ opening_tx = Transaction(+ user_id=account.user_id,+ account_id=account.id,+ description="Saldo inicial",+ amount=amount,+ currency=account.currency,+ date=opening_date,+ type=opening_type,+ source="opening_balance",+ )+ apply_effective_date(opening_tx, account)+ session.add(opening_tx)+ await session.flush()++async def delete_account(session: AsyncSession, account_id: uuid.UUID, user_id: uuid.UUID) -> bool:account = await get_account(session, account_id, user_id)if not account:diff --git a/backend/app/services/connection_service.py b/backend/app/services/connection_service.pyindex 39185df5..5c2d0f29 100644--- a/backend/app/services/connection_service.py+++ b/backend/app/services/connection_service.py@@ -13,6 +13,7 @@ from app.models.category import Categoryfrom app.models.transaction import Transactionfrom app.models.user import Userfrom app.providers import get_provider+from app.services.account_service import sync_opening_balance_for_connected_accountfrom app.services.credit_card_service import apply_effective_datefrom app.services.rule_service import apply_rules_to_transactionfrom app.services.transfer_detection_service import detect_transfer_pairs@@ -215,6 +216,12 @@ async def handle_oauth_callback(else:await stamp_primary_amount(session, user_id, transaction)+ # After importing the initial batch, reconcile the opening balance so+ # that SUM(all transactions) matches the provider-reported balance. Any+ # history that falls outside the provider's lookback window gets+ # absorbed into this synthetic transaction.+ await sync_opening_balance_for_connected_account(session, account)+# Detect transfer pairs among newly synced transactionsawait detect_transfer_pairs(session, user_id, candidate_ids=new_tx_ids)@@ -499,6 +506,10 @@ async def sync_connection(else:await stamp_primary_amount(session, user_id, transaction)+ # Reconcile the opening balance after any new transactions land so+ # SUM(all txs) keeps matching account.balance from the provider.+ await sync_opening_balance_for_connected_account(session, account)+# Detect transfer pairs among newly synced transactionsif new_tx_ids:await detect_transfer_pairs(session, user_id, candidate_ids=new_tx_ids)diff --git a/backend/tests/test_connection_service.py b/backend/tests/test_connection_service.pyindex 2351594f..e39272b8 100644--- a/backend/tests/test_connection_service.py+++ b/backend/tests/test_connection_service.py@@ -512,7 +512,10 @@ async def test_oauth_callback_persists_installment_metadata(await handle_oauth_callback(session, test_user.id, "code", "pluggy")rows = (await session.execute(- select(Transaction).where(Transaction.user_id == test_user.id)+ select(Transaction).where(+ Transaction.user_id == test_user.id,+ Transaction.source != "opening_balance",+ ).order_by(Transaction.external_id))).scalars().all()assert len(rows) == 2