Skip to content

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

fix(recurring): let the workspace's amount rule match a recurring bill (#1213)

APenalba8a8e2bf688ea
diff --git a/backend/app/services/connection_service.py b/backend/app/services/connection_service.py
index 82805fda..d91e9938 100644
--- a/backend/app/services/connection_service.py
+++ b/backend/app/services/connection_service.py
@@ -34,6 +34,7 @@ from app.providers.base import (
ProviderRateLimited,
ProviderUserActionRequired,
SessionExpiredError,
+ TransactionData,
)
from app.services import oauth_state
from app.services import admin_service
@@ -848,6 +849,41 @@ async def _match_pluggy_category(
return result.scalars().first()
+def _bank_converted_amount(
+ txn_data: TransactionData, account_currency: str, user_currency: str
+) -> Optional[Decimal]:
+ """The bank's own conversion of a foreign charge into the primary currency.
+
+ Only when the account is held in the primary currency, so the figure the
+ bank charged the account is the primary amount. None otherwise.
+ """
+ if (
+ txn_data.amount_in_account_currency is not None
+ and txn_data.amount
+ and account_currency == user_currency
+ and txn_data.currency != account_currency
+ ):
+ return txn_data.amount_in_account_currency
+ return None
+
+
+async def _stamp_synced_primary_amount(
+ session: AsyncSession,
+ user_id: uuid.UUID,
+ transaction: Transaction,
+ converted: Optional[Decimal],
+) -> None:
+ """Prefer the bank's conversion (see _bank_converted_amount); else use our FX rates.
+
+ The transaction's amount must already be the charged amount.
+ """
+ if converted is not None:
+ transaction.amount_primary = converted
+ transaction.fx_rate_used = converted / transaction.amount
+ else:
+ await stamp_primary_amount(session, user_id, transaction)
+
+
async def _find_installment_category(
session: AsyncSession,
account_id: uuid.UUID,
@@ -1249,18 +1285,13 @@ async def handle_oauth_callback(
if transaction.category_id is None:
transaction.category_id = category_id
- # Prefer bank-provided conversion for international transactions
acct_currency = acc_data.currency or user_currency
- if (
- txn_data.amount_in_account_currency is not None
- and txn_data.amount
- and acct_currency == user_currency
- and txn_data.currency != acct_currency
- ):
- transaction.amount_primary = txn_data.amount_in_account_currency
- transaction.fx_rate_used = txn_data.amount_in_account_currency / txn_data.amount
- else:
- await stamp_primary_amount(session, user_id, transaction)
+ await _stamp_synced_primary_amount(
+ session,
+ user_id,
+ transaction,
+ _bank_converted_amount(txn_data, acct_currency, user_currency),
+ )
# After importing the initial batch, reconcile the opening balance so
# that SUM(all transactions) matches the provider-reported balance. Any
@@ -2334,6 +2365,10 @@ async def sync_connection(
incoming_currency = (
txn_data.currency or acc_data.currency or user_currency
)
+ acct_currency = acc_data.currency or user_currency
+ converted = _bank_converted_amount(
+ txn_data, acct_currency, user_currency
+ )
category_id = await _find_installment_category(
session, account.id, txn_data
)
@@ -2421,6 +2456,15 @@ async def sync_connection(
# win, the charge fills the empty ones, and only its
# provenance is recorded outright.
placeholder.original_description = txn_data.description
+ if placeholder.amount != txn_data.amount or converted is not None:
+ # Matched under a tolerance, or the bank said what the
+ # charge cost in the primary currency: the row now
+ # stands for what was actually charged, not for what
+ # the bill expected.
+ placeholder.amount = txn_data.amount
+ await _stamp_synced_primary_amount(
+ session, user_id, placeholder, converted
+ )
if placeholder.category_id is None:
placeholder.category_id = preview.category_id or category_id
if txn_data.payee and not placeholder.payee:
@@ -2461,18 +2505,9 @@ async def sync_connection(
if transaction.category_id is None:
transaction.category_id = category_id
- # Prefer bank-provided conversion for international transactions
- acct_currency = acc_data.currency or user_currency
- if (
- txn_data.amount_in_account_currency is not None
- and txn_data.amount
- and acct_currency == user_currency
- and txn_data.currency != acct_currency
- ):
- transaction.amount_primary = txn_data.amount_in_account_currency
- transaction.fx_rate_used = txn_data.amount_in_account_currency / txn_data.amount
- else:
- await stamp_primary_amount(session, user_id, transaction)
+ await _stamp_synced_primary_amount(
+ session, user_id, transaction, converted
+ )
# Reconcile the opening balance after any new transactions land so
# SUM(all txs) keeps matching account.balance from the provider.
diff --git a/backend/app/services/import_service.py b/backend/app/services/import_service.py
index 5de55ebf..b733f549 100644
--- a/backend/app/services/import_service.py
+++ b/backend/app/services/import_service.py
@@ -1158,6 +1158,16 @@ async def import_transactions(
# wins, the charge only fills what is still empty, and only its
# provenance is recorded outright.
placeholder.original_description = txn_data.description
+ if placeholder.amount != txn_data.amount or txn_data.fx_rate:
+ # Matched under a tolerance, or the file says what the charge
+ # cost in the primary currency: the row now stands for what was
+ # actually charged, not for what the bill expected.
+ placeholder.amount = txn_data.amount
+ if txn_data.fx_rate:
+ placeholder.fx_rate_used = txn_data.fx_rate
+ placeholder.amount_primary = txn_data.amount * txn_data.fx_rate
+ else:
+ await stamp_primary_amount(session, user_id, placeholder)
if placeholder.category_id is None:
placeholder.category_id = preview.category_id
if import_payee_raw and not placeholder.payee:
diff --git a/backend/app/services/reconciliation_rule_service.py b/backend/app/services/reconciliation_rule_service.py
index 3f57ec7d..fd9aa4d6 100644
--- a/backend/app/services/reconciliation_rule_service.py
+++ b/backend/app/services/reconciliation_rule_service.py
@@ -38,6 +38,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
from app.models.reconciliation import ReconciliationRule
from app.services import reconciliation_policy
+from app.services.reconciliation_engine import Decision
from app.services.module_service import ModuleId
#: The nodes a person is shown and may edit, and the module each needs.
@@ -445,6 +446,38 @@ def assert_safe_to_link(strategy: dict[str, Any]) -> None:
)
+def pick_linked(
+ linked: list[tuple[Any, Decision]], policy: dict[str, Any]
+) -> tuple[Any, list[tuple[Any, Decision]]]:
+ """Which of several candidates that each linked on their own wins.
+
+ For callers that ask the engine about one candidate at a time and so get
+ neither of the two guarantees it gives for a list. Strategies are ordered
+ and the first that matches wins, so a candidate that linked under an
+ earlier rule beats a better-scoring one under a later rule; within that
+ rule the best score wins, the first seen on a tie. And a rule that asks
+ for a single candidate (`unique_candidate`) is refused when it linked
+ more than one.
+
+ Returns the winner (None when refused or when nothing linked) and the
+ candidates that linked under the winning rule, which are the ones to put
+ to a person when it was refused.
+ """
+ if not linked:
+ return None, []
+ strategies = policy.get("strategies", [])
+ order = {strategy["id"]: index for index, strategy in enumerate(strategies)}
+ front = min(order.get(decision.strategy, len(order)) for _, decision in linked)
+ rivals = [
+ entry for entry in linked
+ if order.get(entry[1].strategy, len(order)) == front
+ ]
+ winning = next((s for s in strategies if s["id"] == rivals[0][1].strategy), {})
+ if winning.get("when", {}).get("unique_candidate", False) and len(rivals) > 1:
+ return None, rivals
+ return max(rivals, key=lambda entry: entry[1].score)[0], rivals
+
+
def _positive_number(value: Any, code: str, message: str) -> str:
try:
number = float(value)
diff --git a/backend/app/services/reconciliation_service.py b/backend/app/services/reconciliation_service.py
index 17eaa8d4..e55a0e85 100644
--- a/backend/app/services/reconciliation_service.py
+++ b/backend/app/services/reconciliation_service.py
@@ -38,6 +38,7 @@ of their own, and this module simply runs what comes back.
from __future__ import annotations
import uuid
+from dataclasses import replace
from datetime import timedelta
from decimal import Decimal
from typing import Optional
@@ -363,6 +364,10 @@ async def _suggest_recurring(
demotes the recurring rule from linking to suggesting. Without it that
setting would be a switch that quietly does nothing, and a
configuration screen whose switches do nothing is worse than no screen.
+
+ It also catches what the normalisation pass refused to guess: when
+ several bills fit a charge under a rule that asks for a single candidate,
+ each of them would link on its own, so each is offered instead.
"""
unexplained = [
transaction
@@ -395,6 +400,7 @@ async def _suggest_recurring(
if await _already_settles_something(session, transaction.id):
continue
movement = _as_movement(transaction)
+ decided: list[tuple[RecurringTransaction, Decision]] = []
for bill in bills:
if bill.account_id != transaction.account_id:
continue
@@ -420,15 +426,23 @@ async def _suggest_recurring(
),
base_currency=base_currency,
)
- if decision.port == "suggested":
- await reconciliation_suggestion_service.record(
- session,
- workspace_id,
- transaction.id,
- decision,
- movement,
- RECURRING_NODE,
- )
+ decided.append((bill, decision))
+ linked = [entry for entry in decided if entry[1].port == "linked"]
+ picked, rivals = reconciliation_rule_service.pick_linked(linked, composed)
+ offered = [
+ decision for _, decision in decided if decision.port == "suggested"
+ ]
+ if picked is None:
+ offered += [replace(decision, port="suggested") for _, decision in rivals]
+ for decision in offered:
+ await reconciliation_suggestion_service.record(
+ session,
+ workspace_id,
+ transaction.id,
+ decision,
+ movement,
+ RECURRING_NODE,
+ )
async def match_for_invoice(
diff --git a/backend/app/services/recurring_match_service.py b/backend/app/services/recurring_match_service.py
index 0722e702..1f68920e 100644
--- a/backend/app/services/recurring_match_service.py
+++ b/backend/app/services/recurring_match_service.py
@@ -22,6 +22,18 @@ started finding pairs it used to miss would be a behaviour change nobody asked
for. What is gained today is only that those numbers are now reachable: a
threshold buried in a module is a threshold no one can ever be shown or offered.
+The amount is part of that. The queries no longer filter on it, because a
+filter in SQL decides before the policy is consulted and so would silently
+defeat a workspace that allows a tolerance (a USD subscription on a EUR card
+is never the same figure twice). The shipped rule is still exact, so the
+engine rejects a different amount just as the query used to. Where a rule
+does link on an approximate amount it must say `unique_candidate`, and since
+these lookups ask the engine about one candidate at a time, that guard is
+enforced here instead: two fits under such a rule are a question, not a pick.
+Nor does this module pick the date range: the queries read it off the policy
+(`_date_reach`), so a window a workspace has widened reaches the candidates
+instead of being cut off before the policy sees them.
+
The queries stay here, because they are what differs: three lookups, in two
directions, over two tables. Only the verdict is shared.
@@ -33,11 +45,12 @@ identity.
import uuid
from datetime import date, timedelta
from decimal import Decimal
-from typing import Optional
+from typing import Any, Optional
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
+from app.models.account import Account
from app.models.recurring_transaction import RecurringTransaction
from app.models.transaction import Transaction
from app.services import reconciliation_policy, reconciliation_rule_service
@@ -47,12 +60,22 @@ from app.services.reconciliation_engine import Expectation, Movement, evaluate
# "recurring" itself: that is the generated placeholder, handled separately.
_REAL_SOURCES = ("sync", "ofx", "csv", "manual")
-#: The widest window any recurring policy uses, in days. Only the SQL date
-#: range is cut with it; the policy still decides, per candidate, whether a
-#: charge is close enough. Kept generous on purpose: narrowing the query to
-#: the exact window would silently re-implement the rule in a second place,
-#: and the two would drift.
-_QUERY_WINDOW_DAYS = 5
+
+def _date_reach(policy: dict[str, Any]) -> tuple[int, int]:
+ """How far before and after its expectation any rule lets a movement sit.
+
+ Only the SQL date range is cut with it; the policy still decides, per
+ candidate. Read off the policy itself, so the query can never be
+ narrower than a rule a workspace has widened, nor drift from it.
+ """
+ before = after = 0
+ for strategy in policy.get("strategies", []):
+ if not strategy.get("enabled", True):
+ continue
+ window = strategy.get("when", {}).get("date") or {}
+ before = max(before, int(window.get("before_days", 0)))
+ after = max(after, int(window.get("after_days", 0)))
+ return before, after
def _as_movement(transaction: Transaction) -> Movement:
@@ -97,25 +120,21 @@ def _best_movement(
"""The charge that best answers one expected occurrence.
The engine takes one movement and many promises; here it is the other way
- round, so it is asked once per candidate and the answers are ranked. Best
- score wins, exactly as before: two subscriptions of the same value on one
- account are told apart by their description, not refused.
+ round, so it is asked once per candidate and the answers are ranked: the
+ earlier rule first, then the best score. Two subscriptions of the same
+ value on one account are told apart by their description, not refused,
+ unless the rule that linked them asks for a single candidate. On an equal
+ score the first candidate passed in wins, and the callers pass them nearest
+ first.
"""
- best: Optional[Transaction] = None
- # Below the range a score can take, not at its floor: a rule whose
- # similarity threshold is 0 can link a candidate scoring exactly
- # 0.0, and a strict comparison against 0.0 would drop it.
- best_score = -1.0
+ linked = []
for candidate in candidates:
if candidate.is_ignored:
continue
decision = evaluate(_as_movement(candidate), [expectation], policy)
- if decision.port != "linked":
- continue
- if decision.score > best_score:
- best_score = decision.score
- best = candidate
- return best
+ if decision.port == "linked":
+ linked.append((candidate, decision))
+ return reconciliation_rule_service.pick_linked(linked, policy)[0]
async def find_real_tx_for_occurrence(
@@ -131,21 +150,31 @@ async def find_real_tx_for_occurrence(
policy = await reconciliation_rule_service.resolve_recurring(
session, recurring.workspace_id, recurring.frequency
)
+ # The charge is the movement and the occurrence the expectation, so the
+ # charge may be up to `before` days earlier than the occurrence, or `after`
+ # days later.
+ before, after = _date_reach(policy)
result = await session.execute(
select(Transaction).where(
Transaction.account_id == recurring.account_id,
Transaction.recurring_transaction_id.is_(None),
Transaction.source.in_(_REAL_SOURCES),
- Transaction.amount == recurring.amount,
Transaction.currency == recurring.currency,
Transaction.type == recurring.type,
- Transaction.date >= occurrence_date - timedelta(days=_QUERY_WINDOW_DAYS),
- Transaction.date <= occurrence_date + timedelta(days=_QUERY_WINDOW_DAYS),
+ Transaction.date >= occurrence_date - timedelta(days=before),
+ Transaction.date <= occurrence_date + timedelta(days=after),
)
)
- return _best_movement(
- result.scalars(), _as_occurrence(recurring, occurrence_date), policy
+ # The score only reads the description, so two charges can tie, and with a
+ # window as long as the billing period that is no rare thing. Looking at
+ # the nearest first makes the nearest win the tie rather than the database;
+ # at equal distance the earlier wins, a fixed order rather than the
+ # database's.
+ nearest = sorted(
+ result.scalars(),
+ key=lambda tx: (abs((tx.date - occurrence_date).days), tx.date, tx.id),
)
+ return _best_movement(nearest, _as_occurrence(recurring, occurrence_date), policy)
async def find_placeholder_for_incoming(
@@ -165,24 +194,61 @@ async def find_placeholder_for_incoming(
Inverted from the rest of the module: the placeholder is the thing being
searched for, so the incoming charge plays the part of the promise and each
- placeholder is scored against it. The window is symmetric here: a
+ placeholder is scored against it. The shipped window is symmetric here: a
placeholder was written for one specific occurrence, so unlike a bill it has
no neighbour to be confused with.
+
+ The shipped placeholder rule judges first and is exact. When it links
+ nothing, the placeholders are judged again the way the workspace's
+ recurring rule is written: the charge is the movement and each placeholder
+ the occurrence it answers, because the placeholder is an occurrence of its
+ bill. A workspace that lets the bill match a charge of a slightly
+ different amount means the placeholder too, or the charge would be written
+ next to it instead, and the rule's window and tolerance only mean what
+ they say read that way round.
+
+ The two passes read the window in opposite directions (the placeholder is
+ the movement in one, the expectation in the other), so the query reaches as
+ far as the wider of the two on each side and the policies decide from
+ there. The workspace's rule is resolved before the query for that reason.
"""
+ account = await session.get(Account, account_id)
+ if account is None:
+ return None
policy = reconciliation_policy.default_policy("reconciliation.match_placeholder")
+ composed = await reconciliation_rule_service.resolve(
+ session,
+ account.workspace_id,
+ reconciliation_policy.MATCH_RECURRING["node"],
+ )
+ # Narrowing for frequency only ever shrinks a window, so the unnarrowed
+ # rule is an upper bound for the query.
+ p_before, p_after = _date_reach(policy)
+ r_before, r_after = _date_reach(composed)
result = await session.execute(
- select(Transaction).where(
+ select(Transaction, RecurringTransaction.frequency)
+ .join(
+ RecurringTransaction,
+ RecurringTransaction.id == Transaction.recurring_transaction_id,
+ )
+ .where(
Transaction.account_id == account_id,
Transaction.source == "recurring",
Transaction.recurring_transaction_id.is_not(None),
Transaction.external_id.is_(None),
- Transaction.amount == amount,
Transaction.currency == currency,
Transaction.type == tx_type,
- Transaction.date >= tx_date - timedelta(days=_QUERY_WINDOW_DAYS),
- Transaction.date <= tx_date + timedelta(days=_QUERY_WINDOW_DAYS),
+ Transaction.date >= tx_date - timedelta(days=max(p_before, r_after)),
+ Transaction.date <= tx_date + timedelta(days=max(p_after, r_before)),
)
)
+ # The score only reads the description, so tied placeholders go to the
+ # nearest in date, which both passes honour by seeing it first; at equal
+ # distance the earlier wins, a fixed order rather than the database's.
+ rows = sorted(
+ result.all(),
+ key=lambda row: (abs((row[0].date - tx_date).days), row[0].date, row[0].id),
+ )
incoming = Expectation(
kind="recurring",
id=uuid.uuid4(),
@@ -193,7 +259,41 @@ async def find_placeholder_for_incoming(
description=description,
account_id=account_id,
)
- return _best_movement(result.scalars(), incoming, policy)
+ found = _best_movement([row[0] for row in rows], incoming, policy)
+ if found is not None or not rows:
+ return found
+
+ charge = Movement(
+ amount=amount,
+ currency=currency,
+ direction=tx_type,
+ when=tx_date,
+ description=description,
+ account_id=account_id,
+ )
+ linked = []
+ for placeholder, frequency in rows:
+ if placeholder.is_ignored:
+ continue
+ decision = evaluate(
+ charge,
+ [
+ Expectation(
+ kind="recurring",
+ id=placeholder.id,
+ amount=Decimal(placeholder.amount or 0),
+ currency=placeholder.currency,
+ direction=placeholder.type,
+ when=placeholder.date,
+ description=placeholder.description,
+ account_id=placeholder.account_id,
+ )
+ ],
+ reconciliation_rule_service.narrow_for_frequency(composed, frequency),
+ )
+ if decision.port == "linked":
+ linked.append((placeholder, decision))
+ return reconciliation_rule_service.pick_linked(linked, composed)[0]
async def find_bill_for_incoming(
@@ -223,7 +323,6 @@ async def find_bill_for_incoming(
RecurringTransaction.user_id == user_id,
RecurringTransaction.account_id == account_id,
RecurringTransaction.is_active.is_(True),
- RecurringTransaction.amount == amount,
RecurringTransaction.currency == currency,
RecurringTransaction.type == tx_type,
)
@@ -237,11 +336,7 @@ async def find_bill_for_incoming(
account_id=account_id,
)
- best: Optional[RecurringTransaction] = None
- # Below the range a score can take, not at its floor: a rule whose
- # similarity threshold is 0 can link a candidate scoring exactly
- # 0.0, and a strict comparison against 0.0 would drop it.
- best_score = -1.0
+ linked = []
# The workspace's rules are fetched once for the batch and then
# narrowed per bill, rather than queried per candidate: every bill here
# belongs to one account, so they share a workspace, and the only thing
@@ -264,10 +359,11 @@ async def find_bill_for_incoming(
composed, recurring.frequency
),
)
- if decision.port == "linked" and decision.score > best_score:
- best_score = decision.score
- best = recurring
- return best
+ if decision.port == "linked":
+ linked.append((recurring, decision))
+ if composed is None:
+ return None
+ return reconciliation_rule_service.pick_linked(linked, composed)[0]
def advance_past(recurring: RecurringTransaction, fulfilled_date: date) -> None:
diff --git a/backend/tests/test_reconciliation_service.py b/backend/tests/test_reconciliation_service.py
index 00be7967..3cf1d086 100644
--- a/backend/tests/test_reconciliation_service.py
+++ b/backend/tests/test_reconciliation_service.py
@@ -18,7 +18,14 @@ from app.models.account import Account
from app.models.invoice import Invoice, InvoiceAllocation
from app.models.payee import Payee
from app.models.transaction import Transaction
-from app.services import invoice_service, reconciliation_service
+from app.schemas.recurring_transaction import RecurringTransactionCreate
+from app.services import (
+ invoice_service,
+ reconciliation_policy,
+ reconciliation_rule_service,
+ reconciliation_service,
+)
+from app.services.recurring_transaction_service import create_recurring_transaction
TODAY = date.today()
@@ -573,3 +580,78 @@ async def test_linking_by_hand_answers_the_pending_suggestion(
queue = await client.get("/api/reconciliation/suggestions", headers=biz_headers)
assert queue.status_code == 200, queue.text
assert all(str(short_id) not in str(item) for item in queue.json())
+
+
+async def _tolerant_bills(session, account, test_user, descriptions: list[str]):
+ """Bills of about 18.43 on `account`, in a workspace that lets one match a
+ charge within 5% and link on it."""
+ await reconciliation_rule_service.upsert_override(
+ session, account.workspace_id, test_user.id,
+ reconciliation_policy.MATCH_RECURRING["node"], "same_account_exact",
+ {"when": {"amount": {"match": "tolerance", "percent": "5"},
+ "unique_candidate": True}},
+ )
+ return [
+ await create_recurring_transaction(
+ session, account.workspace_id, test_user.id,
+ RecurringTransactionCreate(
+ description=description, amount=Decimal("18.43") + Decimal(i) / 10,
+ currency="USD", type="debit", frequency="monthly",
+ start_date=TODAY, account_id=account.id,
+ ),
+ )
+ for i, description in enumerate(descriptions)
+ ]
+
+
+async def _pending_for(session, transaction_id):
+ from app.models.reconciliation import ReconciliationSuggestion
+
+ result = await session.execute(
+ select(ReconciliationSuggestion.expectation_id).where(
+ ReconciliationSuggestion.transaction_id == transaction_id,
+ ReconciliationSuggestion.status == "pending",
+ )
+ )
+ return set(result.scalars().all())
+
+
+async def test_several_bills_within_tolerance_become_a_question(
+ business_ws, session: AsyncSession, account, test_user
+):
+ """Each bill would link on its own, but the rule asks for a single
+ candidate and there are two. Nothing is linked, so the charge has to be
+ offered to the person rather than left unexplained."""
+ bills = await _tolerant_bills(
+ session, account, test_user, ["Hosting Plan", "Hosting Plan Pro"]
+ )
+ charge = await a_transaction(
+ session, account, test_user, amount=Decimal("18.71"), kind="debit",
+ description="HOSTING PLAN",
+ )
+ charge_id = charge.id
+
+ await reconciliation_service.match_incoming(session, account.workspace_id, [charge])
+ await session.commit()
+
+ assert await _pending_for(session, charge_id) == {bill.id for bill in bills}
+
+
+async def test_a_single_bill_within_tolerance_is_not_suggested(
+ business_ws, session: AsyncSession, account, test_user
+):
+ """One fit is not ambiguous: it is the linking pass's to make, and this
+ pass keeps leaving it alone."""
+ await _tolerant_bills(session, account, test_user, ["Hosting Plan"])
+ charge = await a_transaction(
+ session, account, test_user, amount=Decimal("18.71"), kind="debit",
+ description="HOSTING PLAN",
+ )
+ charge_id = charge.id
+
+ await reconciliation_service.match_incoming(session, account.workspace_id, [charge])
+ await session.commit()
+
+ assert await _pending_for(session, charge_id) == set()
diff --git a/backend/tests/test_recurring_match.py b/backend/tests/test_recurring_match.py
index eea5a13c..437ac858 100644
--- a/backend/tests/test_recurring_match.py
+++ b/backend/tests/test_recurring_match.py
@@ -12,7 +12,11 @@ from app.models.account import Account
from app.models.transaction import Transaction
from app.models.workspace import Workspace, WorkspaceMember
from app.schemas.recurring_transaction import RecurringTransactionCreate
-from app.services import recurring_match_service as rms
+from app.services import (
+ reconciliation_policy,
+ reconciliation_rule_service,
+ recurring_match_service as rms,
+)
from app.services.text_similarity import token_overlap
from app.services.recurring_transaction_service import (
create_recurring_transaction,
@@ -577,3 +581,434 @@ async def test_unlink_recurring_noop_when_not_linked(session, test_user, test_wo
session, tx.id, test_workspace.id
)
assert result is None # nothing to unlink → 404 at the API layer
+
+
+# ---------------------------------------------------------------------------
+# A workspace's amount rule (issue #1073)
+# ---------------------------------------------------------------------------
+
+
+async def _allow_tolerance(session, test_workspace, test_user, **config):
+ """A workspace that lets a bill match a charge within 5%, and link on it."""
+ await reconciliation_rule_service.upsert_override(
+ session,
+ test_workspace.id,
+ test_user.id,
+ reconciliation_policy.MATCH_RECURRING["node"],
+ "same_account_exact",
+ {
+ "when": {
+ "amount": {"match": "tolerance", "percent": "5"},
+ "unique_candidate": True,
+ },
+ **config,
+ },
+ )
+
+
+async def test_default_rule_still_needs_the_exact_amount(
+ session, test_user, test_workspace, account
+):
+ """A charge a few cents off the bill is still a different amount when the
+ workspace has not said otherwise: nothing links."""
+ bill = await _make_bill(
+ session, test_workspace, test_user, account, amount=Decimal("18.43")
+ )
+ await _add_tx(
+ session, test_user, test_workspace, account,
+ date=date(2025, 1, 10), source="recurring", external_id=None,
+ recurring_transaction_id=bill.id, description="Netflix Subscription",
+ amount=Decimal("18.43"),
+ )
+
+ assert await rms.find_bill_for_incoming(
+ session, test_user.id, account.id, Decimal("18.71"), "BRL", "debit",
+ date(2025, 1, 11), "NETFLIX SUBSCRIPTION",
+ ) is None
+ assert await rms.find_placeholder_for_incoming(
+ session, account.id, Decimal("18.71"), "BRL", "debit",
+ date(2025, 1, 11), "NETFLIX SUBSCRIPTION",
+ ) is None
+
+
+async def test_find_bill_honours_the_workspace_tolerance(
+ session, test_user, test_workspace, account
+):
+ bill = await _make_bill(
+ session, test_workspace, test_user, account, amount=Decimal("18.43")
+ )
+ await _allow_tolerance(session, test_workspace, test_user)
+
+ match = await rms.find_bill_for_incoming(
+ session, test_user.id, account.id, Decimal("18.71"), "BRL", "debit",
+ date(2025, 1, 11), "NETFLIX SUBSCRIPTION",
+ )
+ assert match is not None and match.id == bill.id
+
+ # Past the tolerance it is a different charge again.
+ assert await rms.find_bill_for_incoming(
+ session, test_user.id, account.id, Decimal("20.00"), "BRL", "debit",
+ date(2025, 1, 11), "NETFLIX SUBSCRIPTION",
+ ) is None
+
+
+async def test_find_bill_refuses_to_guess_between_bills_within_tolerance(
+ session, test_user, test_workspace, account
+):
+ """The rule asks for a single candidate, and two bills fit."""
+ await _make_bill(session, test_workspace, test_user, account, amount=Decimal("18.43"))
+ await _make_bill(
+ session, test_workspace, test_user, account,
+ amount=Decimal("18.60"), description="Netflix Subscription Family",
+ )
+ await _allow_tolerance(session, test_workspace, test_user)
+
+ assert await rms.find_bill_for_incoming(
+ session, test_user.id, account.id, Decimal("18.71"), "BRL", "debit",
+ date(2025, 1, 11), "NETFLIX SUBSCRIPTION",
+ ) is None
+
+
+async def test_find_bill_does_not_link_under_a_suggest_outcome(
+ session, test_user, test_workspace, account
+):
+ await _make_bill(session, test_workspace, test_user, account, amount=Decimal("18.43"))
+ await _allow_tolerance(session, test_workspace, test_user, outcome="suggest")
+
+ assert await rms.find_bill_for_incoming(
+ session, test_user.id, account.id, Decimal("18.71"), "BRL", "debit",
+ date(2025, 1, 11), "NETFLIX SUBSCRIPTION",
+ ) is None
+
+
+async def test_find_placeholder_honours_the_workspace_tolerance(
+ session, test_user, test_workspace, account
+):
+ bill = await _make_bill(
+ session, test_workspace, test_user, account, amount=Decimal("18.43")
+ )
+ placeholder = await _add_tx(
+ session, test_user, test_workspace, account,
+ date=date(2025, 1, 10), source="recurring", external_id=None,
+ recurring_transaction_id=bill.id, description="Netflix Subscription",
+ amount=Decimal("18.43"),
+ )
+ await _allow_tolerance(session, test_workspace, test_user)
+
+ found = await rms.find_placeholder_for_incoming(
+ session, account.id, Decimal("18.71"), "BRL", "debit",
+ date(2025, 1, 11), "NETFLIX SUBSCRIPTION",
+ )
+ assert found is not None and found.id == placeholder.id
+
+
+async def test_find_placeholder_reads_the_recurring_window_from_the_charge(
+ session, test_user, test_workspace, account
+):
+ """The recurring rule allows a charge to post late (five days) more than
+ early (three), measured from the occurrence: the placeholder."""
+ bill = await _make_bill(
+ session, test_workspace, test_user, account, amount=Decimal("18.43")
+ )
+ await _add_tx(
+ session, test_user, test_workspace, account,
+ date=date(2025, 1, 10), source="recurring", external_id=None,
+ recurring_transaction_id=bill.id, description="Netflix Subscription",
+ amount=Decimal("18.43"),
+ )
+ await _allow_tolerance(session, test_workspace, test_user)
+
+ late = await rms.find_placeholder_for_incoming(
+ session, account.id, Decimal("18.71"), "BRL", "debit",
+ date(2025, 1, 14), "NETFLIX SUBSCRIPTION",
+ )
+ early = await rms.find_placeholder_for_incoming(
+ session, account.id, Decimal("18.71"), "BRL", "debit",
+ date(2025, 1, 6), "NETFLIX SUBSCRIPTION",
+ )
+ assert late is not None
+ assert early is None
+
+
+async def test_find_bill_takes_the_first_rule_that_matches_over_a_better_score(
+ session, test_user, test_workspace, account
+):
+ """Rules are ordered and the first to match wins. The exact bill matches
+ under the shipped rule; the other only under the workspace's own looser
+ rule, with a better description, and must not overtake it."""
+ exact = await _make_bill(
+ session, test_workspace, test_user, account,
+ amount=Decimal("18.71"), description="Netflix Subscription Family",
+ )
+ await _make_bill(
+ session, test_workspace, test_user, account, amount=Decimal("18.43")
+ )
+ await reconciliation_rule_service.create_custom(
+ session, test_workspace.id, test_user.id,
+ reconciliation_policy.MATCH_RECURRING["node"], "Within five percent",
+ {
+ "outcome": "link",
+ "trigger": "money_arrives",
+ "when": {
+ "counterparty": "any",
+ "same_account": True,
+ "amount": {"match": "tolerance", "percent": "5"},
+ "date": {"before_days": 3, "after_days": 5},
+ "currency": {"conversion": "reject"},
+ "description_similarity": {"min": "0.6"},
+ "unique_candidate": True,
+ },
+ },
+ )
+
+ match = await rms.find_bill_for_incoming(
+ session, test_user.id, account.id, Decimal("18.71"), "BRL", "debit",
+ date(2025, 1, 11), "NETFLIX SUBSCRIPTION",
+ )
+ assert match is not None and match.id == exact.id
+
+
+async def test_generate_pending_links_a_charge_within_tolerance(
+ session, test_user, test_workspace, account
+):
+ bill = await _make_bill(
+ session, test_workspace, test_user, account, amount=Decimal("18.43")
+ )
+ await _allow_tolerance(session, test_workspace, test_user)
+ real = await _add_tx(
+ session, test_user, test_workspace, account,
+ date=date(2025, 1, 11), source="sync", external_id="bank-1",
+ amount=Decimal("18.71"),
+ )
+
+ count = await generate_pending(session, test_user.id, up_to=date(2025, 1, 20))
+
+ assert count == 0
+ await session.refresh(real)
+ assert real.recurring_transaction_id == bill.id
+ result = await session.execute(
+ select(Transaction).where(Transaction.account_id == account.id)
+ )
+ assert len(result.scalars().all()) == 1
+
+
+# ---------------------------------------------------------------------------
+# A workspace's date window
+# ---------------------------------------------------------------------------
+
+
+async def _widen_window(
+ session, test_workspace, test_user, *, before_days=3, after_days=10
+):
+ """A workspace whose bank is slow: a charge may post up to `after_days` late."""
+ await reconciliation_rule_service.upsert_override(
+ session,
+ test_workspace.id,
+ test_user.id,
+ reconciliation_policy.MATCH_RECURRING["node"],
+ "same_account_exact",
+ {"when": {"date": {"before_days": before_days, "after_days": after_days}}},
+ )
+
+
+async def _late_placeholder(session, test_user, test_workspace, account):
+ bill = await _make_bill(
+ session, test_workspace, test_user, account, amount=Decimal("18.43")
+ )
+ return await _add_tx(
+ session, test_user, test_workspace, account,
+ date=date(2025, 1, 10), source="recurring", external_id=None,
+ recurring_transaction_id=bill.id, description="Netflix Subscription",
+ amount=Decimal("18.43"),
+ )
+
+
+async def test_find_placeholder_reaches_as_far_as_the_workspace_window(
+ session, test_user, test_workspace, account
+):
+ placeholder = await _late_placeholder(session, test_user, test_workspace, account)
+ await _widen_window(session, test_workspace, test_user)
+
+ found = await rms.find_placeholder_for_incoming(
+ session, account.id, Decimal("18.43"), "BRL", "debit",
+ date(2025, 1, 18), "NETFLIX SUBSCRIPTION",
+ )
+ assert found is not None and found.id == placeholder.id
+
+
+async def test_find_placeholder_default_window_still_stops_at_five_days(
+ session, test_user, test_workspace, account
+):
+ await _late_placeholder(session, test_user, test_workspace, account)
+
+ found = await rms.find_placeholder_for_incoming(
+ session, account.id, Decimal("18.43"), "BRL", "debit",
+ date(2025, 1, 18), "NETFLIX SUBSCRIPTION",
+ )
+ assert found is None
+
+
+async def test_generate_pending_links_a_charge_inside_a_widened_window(
+ session, test_user, test_workspace, account
+):
+ bill = await _make_bill(
+ session, test_workspace, test_user, account, amount=Decimal("18.43")
+ )
+ await _widen_window(session, test_workspace, test_user)
+ real = await _add_tx(
+ session, test_user, test_workspace, account,
+ date=date(2025, 1, 18), source="sync", external_id="bank-1",
+ amount=Decimal("18.43"),
+ )
+
+ count = await generate_pending(session, test_user.id, up_to=date(2025, 1, 20))
+
+ assert count == 0
+ await session.refresh(real)
+ assert real.recurring_transaction_id == bill.id
+ result = await session.execute(
+ select(Transaction).where(Transaction.account_id == account.id)
+ )
+ assert len(result.scalars().all()) == 1
+
+
+async def test_generate_pending_default_window_does_not_link_a_late_charge(
+ session, test_user, test_workspace, account
+):
+ await _make_bill(
+ session, test_workspace, test_user, account, amount=Decimal("18.43")
+ )
+ real = await _add_tx(
+ session, test_user, test_workspace, account,
+ date=date(2025, 1, 18), source="sync", external_id="bank-1",
+ amount=Decimal("18.43"),
+ )
+
+ count = await generate_pending(session, test_user.id, up_to=date(2025, 1, 20))
+
+ assert count == 1
+ await session.refresh(real)
+ assert real.recurring_transaction_id is None
+
+
+async def test_find_placeholder_prefers_the_nearest_of_two_tied_placeholders(
+ session, test_user, test_workspace, account
+):
+ bill = await _make_bill(
+ session, test_workspace, test_user, account, amount=Decimal("18.43")
+ )
+ await _widen_window(session, test_workspace, test_user, after_days=40)
+ # The farther one goes in first, so insertion order would pick it.
+ far = await _add_tx(
+ session, test_user, test_workspace, account,
+ date=date(2025, 1, 10), source="recurring", external_id=None,
+ recurring_transaction_id=bill.id, description="Netflix Subscription",
+ amount=Decimal("18.43"),
+ )
+ near = await _add_tx(
+ session, test_user, test_workspace, account,
+ date=date(2025, 2, 10), source="recurring", external_id=None,
+ recurring_transaction_id=bill.id, description="Netflix Subscription",
+ amount=Decimal("18.43"),
+ )
+
+ found = await rms.find_placeholder_for_incoming(
+ session, account.id, Decimal("18.43"), "BRL", "debit",
+ date(2025, 2, 18), "NETFLIX SUBSCRIPTION",
+ )
+ assert found is not None and found.id == near.id
+ assert found.id != far.id
+
+
+async def test_find_real_tx_prefers_the_nearest_of_two_tied_charges(
+ session, test_user, test_workspace, account
+):
+ bill = await _make_bill(
+ session, test_workspace, test_user, account, amount=Decimal("18.43")
+ )
+ await _widen_window(session, test_workspace, test_user, after_days=40)
+ # The farther one goes in first, so insertion order would pick it.
+ far = await _add_tx(
+ session, test_user, test_workspace, account,
+ date=date(2025, 3, 12), source="sync", external_id="bank-far",
+ amount=Decimal("18.43"),
+ )
+ near = await _add_tx(
+ session, test_user, test_workspace, account,
+ date=date(2025, 2, 11), source="sync", external_id="bank-near",
+ amount=Decimal("18.43"),
+ )
+
+ found = await rms.find_real_tx_for_occurrence(session, bill, date(2025, 2, 10))
+ assert found is not None and found.id == near.id
+ assert found.id != far.id
+
+
+async def test_find_real_tx_breaks_an_equal_distance_tie_towards_the_earlier(
+ session, test_user, test_workspace, account
+):
+ bill = await _make_bill(
+ session, test_workspace, test_user, account, amount=Decimal("18.43")
+ )
+ # The later one goes in first, so insertion order would pick it.
+ later = await _add_tx(
+ session, test_user, test_workspace, account,
+ date=date(2025, 2, 13), source="sync", external_id="bank-later",
+ amount=Decimal("18.43"),
+ )
+ earlier = await _add_tx(
+ session, test_user, test_workspace, account,
+ date=date(2025, 2, 7), source="sync", external_id="bank-earlier",
+ amount=Decimal("18.43"),
+ )
+
+ found = await rms.find_real_tx_for_occurrence(session, bill, date(2025, 2, 10))
+ assert found is not None and found.id == earlier.id
+ assert found.id != later.id
+
+
+async def test_widened_window_weekly_clamp_still_wins(
+ session, test_user, test_workspace, account
+):
+ """A guard: the weekly clamp already held before the window followed the policy."""
+ bill = await _make_bill(
+ session, test_workspace, test_user, account,
+ amount=Decimal("18.43"), frequency="weekly",
+ )
+ await _widen_window(session, test_workspace, test_user, before_days=10, after_days=10)
+ await _add_tx(
+ session, test_user, test_workspace, account,
+ date=date(2025, 1, 14), source="sync", external_id="bank-1",
+ amount=Decimal("18.43"),
+ )
+
+ assert await rms.find_real_tx_for_occurrence(session, bill, date(2025, 1, 10)) is None
+
+
+def test_date_reach_reads_only_the_enabled_rules_windows():
+ policy = {
+ "strategies": [
+ {"enabled": True, "when": {"date": {"before_days": 3, "after_days": 5}}},
+ {"enabled": False, "when": {"date": {"before_days": 30, "after_days": 40}}},
+ {"enabled": True, "when": {}},
+ ]
+ }
+
+ assert rms._date_reach(policy) == (3, 5)
+ assert rms._date_reach({"strategies": []}) == (0, 0)
diff --git a/backend/tests/test_recurring_match_import.py b/backend/tests/test_recurring_match_import.py
index 40c8251a..a64223ce 100644
--- a/backend/tests/test_recurring_match_import.py
+++ b/backend/tests/test_recurring_match_import.py
@@ -14,6 +14,7 @@ from app.models.transaction import Transaction
from app.schemas.recurring_transaction import RecurringTransactionCreate
from app.schemas.rule import RuleAction, RuleCondition, RuleCreate
from app.schemas.transaction import TransactionImport
+from app.services import reconciliation_policy, reconciliation_rule_service
from app.services.import_service import import_transactions
from app.services.recurring_transaction_service import create_recurring_transaction
from app.services.rule_service import create_rule
@@ -32,14 +33,36 @@ async def _make_bill(session, test_workspace, test_user, account, **ov):
return await create_recurring_transaction(session, test_workspace.id, test_user.id, data)
-async def _run_import(session, test_workspace, test_user, account_id, txns, source="csv"):
- with patch("app.services.import_service.stamp_primary_amount", new_callable=AsyncMock), \
+async def _run_import(session, test_workspace, test_user, account_id, txns, source="csv",
+ stamp=None):
+ with patch("app.services.import_service.stamp_primary_amount",
+ new=stamp if stamp is not None else AsyncMock()), \
patch("app.services.import_service.apply_rules_to_transaction", new_callable=AsyncMock):
return await import_transactions(
session, test_workspace.id, test_user.id, account_id, txns, source,
)
+async def _usd_placeholder(session, test_workspace, test_user, account):
+ """A USD bill and its generated placeholder on the BRL account, stamped
+ with the estimate made when it was generated (4.8833 BRL per USD)."""
+ bill = await _make_bill(session, test_workspace, test_user, account,
+ amount=Decimal("18.43"), currency="USD",
+ start_date=date(2026, 1, 10))
+ bill.next_occurrence = date(2026, 2, 10)
+ placeholder = Transaction(
+ id=uuid.uuid4(), user_id=test_user.id, account_id=account.id,
+ workspace_id=test_workspace.id, description="Netflix Subscription",
+ amount=Decimal("18.43"), currency="USD", date=date(2026, 1, 10),
+ amount_primary=Decimal("90.00"), fx_rate_used=Decimal("4.8833"),
+ type="debit", source="recurring", status="posted",
+ recurring_transaction_id=bill.id, created_at=datetime.now(timezone.utc),
+ )
+ session.add(placeholder)
+ await session.commit()
+ return placeholder.id
+
+
async def _real_txs(session, account_id):
r = await session.execute(
select(Transaction).where(
@@ -522,3 +545,179 @@ async def test_import_amount_mismatch_not_linked(session, test_user, test_worksp
assert txs[0].recurring_transaction_id is None
refreshed = await session.get(RecurringTransaction, bill_id)
assert refreshed.next_occurrence == date(2026, 1, 10)
+
+
+async def test_import_merges_a_tolerated_amount_into_placeholder(
+ session, test_user, test_workspace, test_account
+):
+ """Issue #1073: the charge differs from the bill by cents. The workspace
+ allows 5%, so the placeholder becomes the charge, at the charged amount."""
+ account_id = test_account.id
+ await reconciliation_rule_service.upsert_override(
+ session, test_workspace.id, test_user.id,
+ reconciliation_policy.MATCH_RECURRING["node"], "same_account_exact",
+ {"when": {"amount": {"match": "tolerance", "percent": "5"},
+ "unique_candidate": True}},
+ )
+ bill = await _make_bill(session, test_workspace, test_user, test_account,
+ amount=Decimal("18.43"), start_date=date(2026, 1, 10))
+ bill_id = bill.id
+ bill.next_occurrence = date(2026, 2, 10)
+ placeholder = Transaction(
+ id=uuid.uuid4(), user_id=test_user.id, account_id=account_id,
+ workspace_id=test_workspace.id, description="Netflix Subscription",
+ amount=Decimal("18.43"), currency="BRL", date=date(2026, 1, 10),
+ amount_primary=Decimal("18.43"), fx_rate_used=Decimal("1"),
+ type="debit", source="recurring", status="posted",
+ recurring_transaction_id=bill_id, created_at=datetime.now(timezone.utc),
+ )
+ session.add(placeholder)
+ await session.commit()
+ placeholder_id = placeholder.id
+
+ txns = [TransactionImport(description="NETFLIX SUBSCRIPTION", amount=Decimal("18.71"),
+ date=date(2026, 1, 11), type="debit", currency="BRL")]
+ with patch("app.services.import_service.apply_rules_to_transaction",
+ new_callable=AsyncMock):
+ imported, _, _, _ = await import_transactions(
+ session, test_workspace.id, test_user.id, account_id, txns, "csv",
+ )
+
+ assert imported == 1
+ txs = await _real_txs(session, account_id)
+ assert len(txs) == 1
+ assert txs[0].id == placeholder_id
+ assert txs[0].amount == Decimal("18.71")
+ assert txs[0].source == "csv"
+ assert txs[0].recurring_transaction_id == bill_id
+ assert txs[0].amount_primary == Decimal("18.71")
+ assert txs[0].fx_rate_used == 1
+
+
+async def test_import_merges_a_late_charge_inside_a_widened_window(
+ session, test_user, test_workspace, test_account
+):
+ """The workspace's bank posts up to ten days late, so a charge eight days
+ after the placeholder still becomes the placeholder rather than a twin."""
+ account_id = test_account.id
+ await reconciliation_rule_service.upsert_override(
+ session, test_workspace.id, test_user.id,
+ reconciliation_policy.MATCH_RECURRING["node"], "same_account_exact",
+ {"when": {"date": {"before_days": 3, "after_days": 10}}},
+ )
+ bill = await _make_bill(session, test_workspace, test_user, test_account,
+ amount=Decimal("18.43"), start_date=date(2026, 1, 10))
+ bill_id = bill.id
+ bill.next_occurrence = date(2026, 2, 10)
+ placeholder = Transaction(
+ id=uuid.uuid4(), user_id=test_user.id, account_id=account_id,
+ workspace_id=test_workspace.id, description="Netflix Subscription",
+ amount=Decimal("18.43"), currency="BRL", date=date(2026, 1, 10),
+ type="debit", source="recurring", status="posted",
+ recurring_transaction_id=bill_id, created_at=datetime.now(timezone.utc),
+ )
+ session.add(placeholder)
+ await session.commit()
+ placeholder_id = placeholder.id
+
+ txns = [TransactionImport(description="NETFLIX SUBSCRIPTION", amount=Decimal("18.43"),
+ date=date(2026, 1, 18), type="debit", currency="BRL")]
+ imported, _, _, _ = await _run_import(
+ session, test_workspace, test_user, account_id, txns
+ )
+
+ assert imported == 1
+ txs = await _real_txs(session, account_id)
+ assert len(txs) == 1
+ assert txs[0].id == placeholder_id
+ assert txs[0].source == "csv"
+ assert txs[0].recurring_transaction_id == bill_id
+
+
+async def test_import_placeholder_takes_the_files_fx_rate(
+ session, test_user, test_workspace, test_account
+):
+ """The charge is exactly what the bill expected, but the file carries the
+ rate the bank applied: it replaces the estimate made at generation."""
+ account_id = test_account.id
+ placeholder_id = await _usd_placeholder(session, test_workspace, test_user, test_account)
+
+ txns = [TransactionImport(description="NETFLIX SUBSCRIPTION", amount=Decimal("18.43"),
+ date=date(2026, 1, 11), type="debit", currency="USD",
+ fx_rate=Decimal("5.28"))]
+ stamp = AsyncMock()
+ imported, _, _, _ = await _run_import(
+ session, test_workspace, test_user, account_id, txns, stamp=stamp
+ )
+
+ assert imported == 1
+ txs = await _real_txs(session, account_id)
+ assert len(txs) == 1
+ assert txs[0].id == placeholder_id
+ assert txs[0].amount == Decimal("18.43")
+ # 18.43 * 5.28 = 97.3104, and the amount_primary column keeps cents.
+ assert txs[0].amount_primary == Decimal("97.31")
+ assert txs[0].fx_rate_used == Decimal("5.28")
+ stamp.assert_not_awaited()
+
+
+async def test_import_placeholder_without_a_rate_is_not_restamped(
+ session, test_user, test_workspace, test_account
+):
+ """Same amount and no rate in the file: nothing new is known about the
+ primary-currency cost, so the placeholder keeps its estimate."""
+ account_id = test_account.id
+ placeholder_id = await _usd_placeholder(session, test_workspace, test_user, test_account)
+
+ txns = [TransactionImport(description="NETFLIX SUBSCRIPTION", amount=Decimal("18.43"),
+ date=date(2026, 1, 11), type="debit", currency="USD")]
+ stamp = AsyncMock()
+ imported, _, _, _ = await _run_import(
+ session, test_workspace, test_user, account_id, txns, stamp=stamp
+ )
+
+ assert imported == 1
+ txs = await _real_txs(session, account_id)
+ assert len(txs) == 1
+ assert txs[0].id == placeholder_id
+ assert txs[0].amount_primary == pytest.approx(Decimal("90.00"))
+ assert txs[0].fx_rate_used == pytest.approx(Decimal("4.8833"))
+ stamp.assert_not_awaited()
+
+
+async def test_import_tolerated_placeholder_takes_the_files_fx_rate(
+ session, test_user, test_workspace, test_account
+):
+ """Tolerated amount and a rate in the file: the row becomes the charge,
+ priced at the rate the bank applied rather than re-estimated."""
+ account_id = test_account.id
+ await reconciliation_rule_service.upsert_override(
+ session, test_workspace.id, test_user.id,
+ reconciliation_policy.MATCH_RECURRING["node"], "same_account_exact",
+ {"when": {"amount": {"match": "tolerance", "percent": "5"},
+ "unique_candidate": True}},
+ )
+ placeholder_id = await _usd_placeholder(session, test_workspace, test_user, test_account)
+
+ txns = [TransactionImport(description="NETFLIX SUBSCRIPTION", amount=Decimal("18.71"),
+ date=date(2026, 1, 11), type="debit", currency="USD",
+ fx_rate=Decimal("5.28"))]
+ stamp = AsyncMock()
+ imported, _, _, _ = await _run_import(
+ session, test_workspace, test_user, account_id, txns, stamp=stamp
+ )
+
+ assert imported == 1
+ txs = await _real_txs(session, account_id)
+ assert len(txs) == 1
+ assert txs[0].id == placeholder_id
+ assert txs[0].amount == Decimal("18.71")
+ # 18.71 * 5.28 = 98.7888, which the amount_primary column keeps as cents.
+ assert txs[0].amount_primary == Decimal("98.79")
+ assert txs[0].fx_rate_used == Decimal("5.28")
+ stamp.assert_not_awaited()
diff --git a/backend/tests/test_recurring_match_sync.py b/backend/tests/test_recurring_match_sync.py
index 667a8fe2..dfac5046 100644
--- a/backend/tests/test_recurring_match_sync.py
+++ b/backend/tests/test_recurring_match_sync.py
@@ -28,7 +28,9 @@ from app.models.recurring_transaction import RecurringTransaction
from app.models.transaction import Transaction
from app.schemas.recurring_transaction import RecurringTransactionCreate
from app.schemas.rule import RuleAction, RuleCondition, RuleCreate
+from app.services import reconciliation_policy, reconciliation_rule_service
from app.services.connection_service import sync_connection
+from app.services.fx_rate_service import stamp_primary_amount
from app.services.text_similarity import token_overlap
from app.services.recurring_transaction_service import (
create_recurring_transaction,
@@ -87,6 +89,7 @@ async def _run_sync(
provider,
*,
mock_rules=True,
+ stamp=None,
):
patches = [
patch("app.services.connection_service.get_provider", return_value=provider),
@@ -96,7 +99,7 @@ async def _run_sync(
),
patch(
"app.services.connection_service.stamp_primary_amount",
- new_callable=AsyncMock,
+ new=stamp if stamp is not None else AsyncMock(),
),
]
if mock_rules:
@@ -142,6 +145,20 @@ async def _all_txs(session, account_id):
return list(r.scalars().all())
+async def _usd_placeholder(session, test_workspace, test_user, account, bill_id):
+ placeholder = Transaction(
+ user_id=test_user.id, workspace_id=test_workspace.id,
+ account_id=account.id, description="Netflix Subscription",
+ amount=Decimal("18.43"), currency="USD", date=date(2025, 1, 10),
+ amount_primary=Decimal("90.00"), fx_rate_used=Decimal("4.8833"),
+ type="debit", source="recurring", status="posted",
+ recurring_transaction_id=bill_id,
+ )
+ session.add(placeholder)
+ await session.commit()
+ return placeholder.id
+
+
# ---------------------------------------------------------------------------
# Sync-first: incoming charge stamps the bill and advances it
# ---------------------------------------------------------------------------
@@ -704,3 +721,166 @@ async def test_resync_is_idempotent(session, test_user, test_workspace, conn_acc
assert txs[0].recurring_transaction_id == bill_id
refreshed = await session.get(RecurringTransaction, bill_id)
assert refreshed.next_occurrence == date(2025, 2, 10) # advanced once, not twice
+
+
+async def test_sync_merges_a_tolerated_amount_into_placeholder(
+ session, test_user, test_workspace, conn_account
+):
+ """Issue #1073: a charge a few cents off the bill still replaces the
+ placeholder when the workspace allows a tolerance; the amount and the
+ primary-currency amount become the charge's."""
+ conn, account = conn_account
+ conn_id, account_id = conn.id, account.id
+ await reconciliation_rule_service.upsert_override(
+ session, test_workspace.id, test_user.id,
+ reconciliation_policy.MATCH_RECURRING["node"], "same_account_exact",
+ {"when": {"amount": {"match": "tolerance", "percent": "5"},
+ "unique_candidate": True}},
+ )
+ bill = await _make_bill(session, test_workspace, test_user, account,
+ amount=Decimal("18.43"), start_date=date(2025, 1, 10))
+ bill_id = bill.id
+ bill.next_occurrence = date(2025, 2, 10)
+ placeholder = Transaction(
+ user_id=test_user.id, workspace_id=test_workspace.id,
+ account_id=account_id, description="Netflix Subscription",
+ amount=Decimal("18.43"), currency="BRL", date=date(2025, 1, 10),
+ type="debit", source="recurring", status="posted",
+ recurring_transaction_id=bill_id,
+ amount_primary=Decimal("18.43"), fx_rate_used=Decimal("1"),
+ )
+ session.add(placeholder)
+ await session.commit()
+ placeholder_id = placeholder.id
+ provider = _provider([_tx(external_id="s1", description="NETFLIX SUBSCRIPTION",
+ amount=Decimal("18.71"), date=date(2025, 1, 11))])
+
+ stamp = AsyncMock(wraps=stamp_primary_amount)
+
+ await _run_sync(
+ session, conn_id, test_workspace, test_user, provider, stamp=stamp
+ )
+
+ txs = await _all_txs(session, account_id)
+ assert len(txs) == 1
+ assert txs[0].id == placeholder_id
+ assert txs[0].amount == Decimal("18.71")
+ assert txs[0].amount_primary == Decimal("18.71")
+ assert txs[0].fx_rate_used == Decimal("1")
+ assert txs[0].source == "sync"
+ assert txs[0].external_id == "s1"
+ assert txs[0].recurring_transaction_id == bill_id
+ stamp.assert_awaited_once()
+
+
+async def test_sync_placeholder_keeps_the_banks_conversion(
+ session, test_user, test_workspace, conn_account
+):
+ """A USD bill on a BRL account: the placeholder takes the bank's own BRL
+ figure for the charge, not the estimate made when it was generated."""
+ conn, account = conn_account
+ conn_id, account_id = conn.id, account.id
+ bill = await _make_bill(session, test_workspace, test_user, account,
+ amount=Decimal("18.43"), currency="USD",
+ start_date=date(2025, 1, 10))
+ bill_id = bill.id
+ bill.next_occurrence = date(2025, 2, 10)
+ placeholder_id = await _usd_placeholder(
+ session, test_workspace, test_user, account, bill_id
+ )
+ provider = _provider([_tx(external_id="s1", description="NETFLIX SUBSCRIPTION",
+ amount=Decimal("18.43"), currency="USD",
+ amount_in_account_currency=Decimal("97.30"),
+ date=date(2025, 1, 11))])
+
+ stamp = AsyncMock()
+
+ await _run_sync(
+ session, conn_id, test_workspace, test_user, provider, stamp=stamp
+ )
+
+ txs = await _all_txs(session, account_id)
+ assert len(txs) == 1
+ assert txs[0].id == placeholder_id
+ assert txs[0].amount == Decimal("18.43")
+ assert txs[0].amount_primary == Decimal("97.30")
+ assert txs[0].fx_rate_used == pytest.approx(Decimal("97.30") / Decimal("18.43"))
+ stamp.assert_not_awaited()
+
+
+async def test_sync_tolerated_placeholder_keeps_the_banks_conversion(
+ session, test_user, test_workspace, conn_account
+):
+ """A USD charge a few cents off the bill, merged under the tolerance,
+ keeps its own amount and the bank's BRL conversion of it."""
+ conn, account = conn_account
+ conn_id, account_id = conn.id, account.id
+ await reconciliation_rule_service.upsert_override(
+ session, test_workspace.id, test_user.id,
+ reconciliation_policy.MATCH_RECURRING["node"], "same_account_exact",
+ {"when": {"amount": {"match": "tolerance", "percent": "5"},
+ "unique_candidate": True}},
+ )
+ bill = await _make_bill(session, test_workspace, test_user, account,
+ amount=Decimal("18.43"), currency="USD",
+ start_date=date(2025, 1, 10))
+ bill_id = bill.id
+ bill.next_occurrence = date(2025, 2, 10)
+ placeholder_id = await _usd_placeholder(
+ session, test_workspace, test_user, account, bill_id
+ )
+ provider = _provider([_tx(external_id="s1", description="NETFLIX SUBSCRIPTION",
+ amount=Decimal("18.71"), currency="USD",
+ amount_in_account_currency=Decimal("97.30"),
+ date=date(2025, 1, 11))])
+
+ stamp = AsyncMock()
+
+ await _run_sync(
+ session, conn_id, test_workspace, test_user, provider, stamp=stamp
+ )
+
+ txs = await _all_txs(session, account_id)
+ assert len(txs) == 1
+ assert txs[0].id == placeholder_id
+ assert txs[0].amount == Decimal("18.71")
+ assert txs[0].amount_primary == Decimal("97.30")
+ assert txs[0].fx_rate_used == pytest.approx(Decimal("97.30") / Decimal("18.71"))
+ stamp.assert_not_awaited()
+
+
+async def test_sync_placeholder_without_a_conversion_is_not_restamped(
+ session, test_user, test_workspace, conn_account
+):
+ """Without a bank conversion and with the same amount, the placeholder's
+ stamped primary amount is left alone."""
+ conn, account = conn_account
+ conn_id, account_id = conn.id, account.id
+ bill = await _make_bill(session, test_workspace, test_user, account,
+ amount=Decimal("18.43"), currency="USD",
+ start_date=date(2025, 1, 10))
+ bill_id = bill.id
+ bill.next_occurrence = date(2025, 2, 10)
+ placeholder_id = await _usd_placeholder(
+ session, test_workspace, test_user, account, bill_id
+ )
+ provider = _provider([_tx(external_id="s1", description="NETFLIX SUBSCRIPTION",
+ amount=Decimal("18.43"), currency="USD",
+ date=date(2025, 1, 11))])
+
+ stamp = AsyncMock()
+
+ await _run_sync(
+ session, conn_id, test_workspace, test_user, provider, stamp=stamp
+ )
+
+ txs = await _all_txs(session, account_id)
+ assert len(txs) == 1
+ assert txs[0].id == placeholder_id
+ assert txs[0].amount_primary == Decimal("90.00")
+ assert txs[0].fx_rate_used == Decimal("4.8833")
+ stamp.assert_not_awaited()