Open-source personal finance manager. Self-hosted, privacy-first.
feat: hide transfers from dashboard/drill-down and add transfer tooltip
Tássio Noronhacae0ab7ce9b1
diff --git a/backend/app/api/transactions.py b/backend/app/api/transactions.pyindex 49d74287..83fb0b83 100644--- a/backend/app/api/transactions.py+++ b/backend/app/api/transactions.py@@ -45,12 +45,14 @@ async def list_transactions(page: int = Query(1, ge=1),limit: int = Query(50, ge=1, le=500),include_opening_balance: bool = Query(False),+ exclude_transfers: bool = Query(False),session: AsyncSession = Depends(get_async_session),user: User = Depends(current_active_user),):transactions, total = await transaction_service.get_transactions(session, user.id, account_id, category_id, payee_id, from_date, to_date, page, limit,include_opening_balance, search=q, uncategorized=uncategorized, txn_type=type,+ exclude_transfers=exclude_transfers,)primary_currency = user.primary_currencyitems = [_tag_fx_fallback(TransactionRead.model_validate(tx, from_attributes=True), primary_currency) for tx in transactions]diff --git a/backend/app/services/transaction_service.py b/backend/app/services/transaction_service.pyindex 6be04156..c6ffade8 100644--- a/backend/app/services/transaction_service.py+++ b/backend/app/services/transaction_service.py@@ -57,6 +57,7 @@ async def get_transactions(uncategorized: bool = False,txn_type: Optional[str] = None,skip_pagination: bool = False,+ exclude_transfers: bool = False,) -> tuple[list[Transaction], int]:# Base query: user's own transactions (manual or via account)base_query = (@@ -89,6 +90,8 @@ async def get_transactions(Transaction.category_id == None,Transaction.transfer_pair_id.is_(None),)+ if exclude_transfers:+ base_query = base_query.where(Transaction.transfer_pair_id.is_(None))if txn_type:base_query = base_query.where(Transaction.type == txn_type)if from_date:diff --git a/backend/app/services/transfer_detection_service.py b/backend/app/services/transfer_detection_service.pyindex eccb2e26..190cf53e 100644--- a/backend/app/services/transfer_detection_service.py+++ b/backend/app/services/transfer_detection_service.py@@ -17,14 +17,15 @@ async def detect_transfer_pairs("""Detect inter-account transfer pairs and link them with a shared UUID.Algorithm:- 1. Load unpaired debit transactions (optionally filtered to candidate_ids)+ 1. When candidate_ids is given, load candidate debits AND candidate credits+ so that detection works regardless of which side was just imported.2. For each debit, find an unpaired credit with: same user, different account,same absolute amount, date within ±tolerance days3. Greedy closest-date-first matching; each tx can only pair onceReturns the number of pairs created."""- # Load candidate debits+ # Load candidate debits — filtered to candidate_ids when provideddebit_query = select(Transaction).where(Transaction.user_id == user_id,Transaction.type == "debit",@@ -37,7 +38,24 @@ async def detect_transfer_pairs(debit_result = await session.execute(debit_query)debits = list(debit_result.scalars().all())- if not debits:+ # When candidate_ids is given, also load ALL unpaired debits that could+ # match new credits (the reverse direction).+ if candidate_ids:+ reverse_debit_query = select(Transaction).where(+ Transaction.user_id == user_id,+ Transaction.type == "debit",+ Transaction.transfer_pair_id.is_(None),+ Transaction.source != "opening_balance",+ Transaction.id.not_in(candidate_ids),+ )+ reverse_result = await session.execute(reverse_debit_query)+ reverse_debits = list(reverse_result.scalars().all())+ else:+ reverse_debits = []++ all_debits = debits + reverse_debits++ if not all_debits:return 0# Load all unpaired credits for the user (potential partners)@@ -53,27 +71,37 @@ async def detect_transfer_pairs(if not credits:return 0+ # When candidate_ids is given, restrict reverse debits to only match+ # credits that are in candidate_ids (avoid pairing two old transactions).+ candidate_id_set = set(candidate_ids) if candidate_ids else None+# Build a lookup: amount -> list of creditscredit_by_amount: dict[float, list[Transaction]] = defaultdict(list)for c in credits:credit_by_amount[abs(float(c.amount))].append(c)paired_credit_ids: set[uuid.UUID] = set()+ paired_debit_ids: set[uuid.UUID] = set()pairs_created = 0- for debit in debits:+ for debit in all_debits:debit_amount = abs(float(debit.amount))- candidates = credit_by_amount.get(debit_amount, [])+ amount_candidates = credit_by_amount.get(debit_amount, [])++ is_reverse_debit = candidate_id_set is not None and debit.id not in candidate_id_set# Find closest-date match in a different accountbest_match: Optional[Transaction] = Nonebest_delta: Optional[int] = None- for credit in candidates:+ for credit in amount_candidates:if credit.id in paired_credit_ids:continueif credit.account_id == debit.account_id:continue+ # Reverse debits may only match credits from candidate_ids+ if is_reverse_debit and candidate_id_set and credit.id not in candidate_id_set:+ continuedelta = abs((credit.date - debit.date).days)if delta > date_tolerance_days:@@ -88,6 +116,7 @@ async def detect_transfer_pairs(debit.transfer_pair_id = pair_idbest_match.transfer_pair_id = pair_idpaired_credit_ids.add(best_match.id)+ paired_debit_ids.add(debit.id)pairs_created += 1return pairs_createddiff --git a/backend/tests/test_transactions_api.py b/backend/tests/test_transactions_api.pyindex 13b393fe..54b64999 100644--- a/backend/tests/test_transactions_api.py+++ b/backend/tests/test_transactions_api.py@@ -1,9 +1,16 @@+import uuid+from datetime import date, datetime, timezone+from decimal import Decimal+import pytest+import pytest_asynciofrom httpx import AsyncClient+from sqlalchemy.ext.asyncio import AsyncSessionfrom app.models.account import Accountfrom app.models.transaction import Transactionfrom app.models.category import Category+from app.models.user import User@pytest.mark.asyncio@@ -290,3 +297,86 @@ async def test_create_transaction_without_account_fails(},)assert response.status_code == 422+++# --- exclude_transfers tests ---++@pytest_asyncio.fixture+async def test_transactions_with_transfers(+ session: AsyncSession, test_user: User, test_account: Account,+) -> list[Transaction]:+ """Create a mix of regular and transfer transactions."""+ today = date.today()+ pair_id = uuid.uuid4()+ transactions = []+ data = [+ ("GROCERIES", Decimal("50.00"), today, "debit", None, None),+ ("SALARY", Decimal("3000.00"), today, "credit", None, None),+ ("Transfer out", Decimal("200.00"), today, "debit", None, pair_id),+ ("Transfer in", Decimal("200.00"), today, "credit", None, pair_id),+ ]+ for desc, amount, dt, typ, cat_id, transfer_id in data:+ txn = Transaction(+ id=uuid.uuid4(),+ user_id=test_user.id,+ account_id=test_account.id,+ category_id=cat_id,+ description=desc,+ amount=amount,+ date=dt,+ type=typ,+ source="transfer" if transfer_id else "manual",+ transfer_pair_id=transfer_id,+ created_at=datetime.now(timezone.utc),+ )+ session.add(txn)+ transactions.append(txn)+ await session.commit()+ for txn in transactions:+ await session.refresh(txn)+ return transactions+++async def test_list_transactions_includes_transfers_by_default(+ client: AsyncClient, auth_headers, test_transactions_with_transfers,+):+ """Without exclude_transfers, all transactions including transfers are returned."""+ response = await client.get("/api/transactions", headers=auth_headers)+ assert response.status_code == 200+ data = response.json()+ assert data["total"] == 4+ descriptions = [item["description"] for item in data["items"]]+ assert "Transfer out" in descriptions+ assert "Transfer in" in descriptions+++async def test_list_transactions_exclude_transfers(+ client: AsyncClient, auth_headers, test_transactions_with_transfers,+):+ """With exclude_transfers=true, transfer transactions are hidden."""+ response = await client.get(+ "/api/transactions?exclude_transfers=true", headers=auth_headers+ )+ assert response.status_code == 200+ data = response.json()+ assert data["total"] == 2+ descriptions = [item["description"] for item in data["items"]]+ assert "GROCERIES" in descriptions+ assert "SALARY" in descriptions+ assert "Transfer out" not in descriptions+ assert "Transfer in" not in descriptions+++async def test_exclude_transfers_false_includes_all(+ client: AsyncClient, auth_headers, test_transactions_with_transfers,+):+ """Explicitly setting exclude_transfers=false still includes transfers."""+ response = await client.get(+ "/api/transactions?exclude_transfers=false", headers=auth_headers+ )+ assert response.status_code == 200+ data = response.json()+ assert data["total"] == 4diff --git a/backend/tests/test_transfer_detection.py b/backend/tests/test_transfer_detection.pyindex d4e1bd5e..f5b6e1b1 100644--- a/backend/tests/test_transfer_detection.py+++ b/backend/tests/test_transfer_detection.py@@ -254,3 +254,111 @@ async def test_unlink_nonexistent_pair(session: AsyncSession, test_user):"""Unlinking a nonexistent pair returns 0."""unlinked = await unlink_transfer_pair(session, test_user.id, uuid.uuid4())assert unlinked == 0+++# ---------------------------------------------------------------------------+# Reverse-direction candidate_ids detection+# ---------------------------------------------------------------------------+++async def test_candidate_credit_matches_existing_debit(session: AsyncSession, test_user):+ """When candidate_ids contains only a credit, it pairs with an existing debit.++ Simulates: Account A synced first (debit already exists), then Account B+ syncs and imports the matching credit.+ """+ acc1 = await _make_account(session, test_user.id, "Rev A")+ acc2 = await _make_account(session, test_user.id, "Rev B")+ today = date.today()++ # Existing debit (from a previous sync)+ debit = await _add_txn(session, test_user.id, acc1.id, 750, "debit", today)++ # New credit just imported+ credit = await _add_txn(session, test_user.id, acc2.id, 750, "credit", today)++ # Only the credit is in candidate_ids (second sync)+ pairs = await detect_transfer_pairs(session, test_user.id, candidate_ids=[credit.id])+ await session.commit()+ assert pairs == 1++ await session.refresh(debit)+ await session.refresh(credit)+ assert debit.transfer_pair_id is not None+ assert debit.transfer_pair_id == credit.transfer_pair_id+++async def test_candidate_debit_matches_existing_credit(session: AsyncSession, test_user):+ """When candidate_ids contains only a debit, it pairs with an existing credit.++ Simulates: Account B synced first (credit already exists), then Account A+ syncs and imports the matching debit.+ """+ acc1 = await _make_account(session, test_user.id, "Fwd A")+ acc2 = await _make_account(session, test_user.id, "Fwd B")+ today = date.today()++ # Existing credit (from a previous sync)+ credit = await _add_txn(session, test_user.id, acc2.id, 600, "credit", today)++ # New debit just imported+ debit = await _add_txn(session, test_user.id, acc1.id, 600, "debit", today)++ # Only the debit is in candidate_ids (second sync)+ pairs = await detect_transfer_pairs(session, test_user.id, candidate_ids=[debit.id])+ await session.commit()+ assert pairs == 1++ await session.refresh(debit)+ await session.refresh(credit)+ assert debit.transfer_pair_id is not None+ assert debit.transfer_pair_id == credit.transfer_pair_id+++async def test_reverse_detection_does_not_pair_two_old_transactions(session: AsyncSession, test_user):+ """Reverse detection must not pair two transactions that are both outside candidate_ids."""+ acc1 = await _make_account(session, test_user.id, "Guard A")+ acc2 = await _make_account(session, test_user.id, "Guard B")+ acc3 = await _make_account(session, test_user.id, "Guard C")+ today = date.today()++ # Two old unpaired transactions that could match each other+ old_debit = await _add_txn(session, test_user.id, acc1.id, 300, "debit", today)+ old_credit = await _add_txn(session, test_user.id, acc2.id, 300, "credit", today)++ # A new unrelated credit (different amount) triggers detection+ new_credit = await _add_txn(session, test_user.id, acc3.id, 999, "credit", today)++ pairs = await detect_transfer_pairs(session, test_user.id, candidate_ids=[new_credit.id])+ await session.commit()+ assert pairs == 0++ # Old transactions must remain unpaired+ await session.refresh(old_debit)+ await session.refresh(old_credit)+ assert old_debit.transfer_pair_id is None+ assert old_credit.transfer_pair_id is None+++async def test_both_sides_imported_together(session: AsyncSession, test_user):+ """When both debit and credit are new (same sync), both are in candidate_ids."""+ acc1 = await _make_account(session, test_user.id, "Both A")+ acc2 = await _make_account(session, test_user.id, "Both B")+ today = date.today()++ debit = await _add_txn(session, test_user.id, acc1.id, 200, "debit", today)+ credit = await _add_txn(session, test_user.id, acc2.id, 200, "credit", today)++ pairs = await detect_transfer_pairs(+ session, test_user.id, candidate_ids=[debit.id, credit.id],+ )+ await session.commit()+ assert pairs == 1++ await session.refresh(debit)+ await session.refresh(credit)+ assert debit.transfer_pair_id == credit.transfer_pair_iddiff --git a/frontend/src/components/transaction-dialog.tsx b/frontend/src/components/transaction-dialog.tsxindex f605e338..4c5bf676 100644--- a/frontend/src/components/transaction-dialog.tsx+++ b/frontend/src/components/transaction-dialog.tsx@@ -438,8 +438,11 @@ function TransactionForm({</div>)}{!!transaction?.transfer_pair_id && (- <div className="flex items-center gap-2 p-3 text-sm bg-blue-50 dark:bg-blue-950 border border-blue-200 dark:border-blue-800 rounded-md text-blue-700 dark:text-blue-300">- {t('transactions.transferInfo')}+ <div className="p-3 text-sm bg-blue-50 dark:bg-blue-950 border border-blue-200 dark:border-blue-800 rounded-md text-blue-700 dark:text-blue-300 space-y-1">+ <div className="flex items-center gap-2">+ {t('transactions.transferInfo')}+ </div>+ <p className="text-xs text-blue-500 dark:text-blue-400">{t('transactions.transferTooltip')}</p></div>)}{recurringMatch && (diff --git a/frontend/src/components/transaction-drill-down.tsx b/frontend/src/components/transaction-drill-down.tsxindex bc8d94fd..abb24dad 100644--- a/frontend/src/components/transaction-drill-down.tsx+++ b/frontend/src/components/transaction-drill-down.tsx@@ -65,6 +65,7 @@ export function TransactionDrillDown({from: filter?.from,to: filter?.to,limit: 200,+ exclude_transfers: true,}),enabled: !!filter,})diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.tsindex 81043471..cc3fc626 100644--- a/frontend/src/lib/api.ts+++ b/frontend/src/lib/api.ts@@ -240,6 +240,7 @@ export const transactions = {page?: numberlimit?: numberinclude_opening_balance?: boolean+ exclude_transfers?: boolean}): Promise<PaginatedResponse<Transaction>> => {const { data } = await api.get('/transactions', { params })return datadiff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.jsonindex 08f75089..b28e3c53 100644--- a/frontend/src/locales/en.json+++ b/frontend/src/locales/en.json@@ -177,7 +177,8 @@"transferSameAccount": "Source and destination must be different","transferDescription": "Description","transferNotes": "Notes",- "transferInfo": "This is a transfer — changes to description, date, and notes will apply to both sides"+ "transferInfo": "This is a transfer — changes to description, date, and notes will apply to both sides",+ "transferTooltip": "Transfers are excluded from report and dashboard totals"},"accounts": {"title": "Accounts",diff --git a/frontend/src/locales/pt-BR.json b/frontend/src/locales/pt-BR.jsonindex 3038ad96..fb4cec88 100644--- a/frontend/src/locales/pt-BR.json+++ b/frontend/src/locales/pt-BR.json@@ -177,7 +177,8 @@"transferSameAccount": "Origem e destino devem ser diferentes","transferDescription": "Descrição","transferNotes": "Notas",- "transferInfo": "Esta é uma transferência — alterações na descrição, data e notas serão aplicadas em ambos os lados"+ "transferInfo": "Esta é uma transferência — alterações na descrição, data e notas serão aplicadas em ambos os lados",+ "transferTooltip": "Transferências são excluídas dos totais de relatórios e dashboard"},"accounts": {"title": "Contas",diff --git a/frontend/src/pages/account-detail.tsx b/frontend/src/pages/account-detail.tsxindex ae68d8d7..a75e5abd 100644--- a/frontend/src/pages/account-detail.tsx+++ b/frontend/src/pages/account-detail.tsx@@ -8,7 +8,7 @@ import { toast } from 'sonner'import type { Transaction } from '@/types'import { Skeleton } from '@/components/ui/skeleton'import { Button } from '@/components/ui/button'-import { ArrowLeft, ArrowLeftRight, Clock, Paperclip, X } from 'lucide-react'+import { ArrowLeft, ArrowLeftRight, Clock, HelpCircle, Paperclip, X } from 'lucide-react'import { CategoryIcon } from '@/components/category-icon'import { TransactionDialog, extractApiError } from '@/components/transaction-dialog'import { TransferDialog } from '@/components/transfer-dialog'@@ -474,6 +474,7 @@ export default function AccountDetailPage() {<span className="ml-2 inline-flex items-center gap-1 text-xs text-blue-600 font-normal bg-blue-50 border border-blue-200 rounded px-1.5 py-0.5"><ArrowLeftRight className="h-3 w-3" />{t('transactions.transfer')}+ <span title={t('transactions.transferTooltip')}><HelpCircle className="h-3 w-3 text-blue-400" /></span></span>)}{isPending && (diff --git a/frontend/src/pages/dashboard.tsx b/frontend/src/pages/dashboard.tsxindex fe20b299..e3f323b6 100644--- a/frontend/src/pages/dashboard.tsx+++ b/frontend/src/pages/dashboard.tsx@@ -118,6 +118,7 @@ export default function DashboardPage() {from: `${selectedMonth}-01`,to: `${selectedMonth}-${String(monthLastDay(selectedMonth)).padStart(2, '0')}`,limit: 500,+ exclude_transfers: true,}),})diff --git a/frontend/src/pages/transactions.tsx b/frontend/src/pages/transactions.tsxindex 09a48b2e..9a7f42c9 100644--- a/frontend/src/pages/transactions.tsx+++ b/frontend/src/pages/transactions.tsx@@ -15,7 +15,7 @@ import {} from '@/components/ui/table'import { Input } from '@/components/ui/input'import { Skeleton } from '@/components/ui/skeleton'-import { AlertTriangle, ArrowLeftRight, Check, Download, Paperclip, Search, X } from 'lucide-react'+import { AlertTriangle, ArrowLeftRight, Check, Download, HelpCircle, Paperclip, Search, X } from 'lucide-react'import type { Transaction } from '@/types'import { PageHeader } from '@/components/page-header'import { CategoryIcon } from '@/components/category-icon'@@ -426,6 +426,7 @@ export default function TransactionsPage() {<span className="inline-flex items-center gap-1 text-[10px] font-semibold uppercase tracking-wide text-blue-600 bg-blue-50 border border-blue-200 px-1.5 py-0.5 rounded-full"><ArrowLeftRight className="h-3 w-3" />{t('transactions.transfer')}+ <span title={t('transactions.transferTooltip')}><HelpCircle className="h-3 w-3 text-blue-400" /></span></span>)}{recurringList?.some(r => r.description === tx.description && r.type === tx.type) && (