Skip to content

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

fix: stop persisting 1:1 FX fallback and self-heal affected transactions (#353) (#382)

Tássio Noronha8039db1618d1
diff --git a/backend/app/api/transactions.py b/backend/app/api/transactions.py
index 318f3e92..0f5fff1b 100644
--- a/backend/app/api/transactions.py
+++ b/backend/app/api/transactions.py
@@ -23,8 +23,17 @@ router = APIRouter(prefix="/api/transactions", tags=["transactions"])
def _tag_fx_fallback(tx: TransactionRead, primary_currency: str) -> TransactionRead:
- """Set fx_fallback=True when a cross-currency tx used 1:1 fallback rate."""
- if tx.currency != primary_currency and tx.fx_rate_used is not None and tx.fx_rate_used == 1.0:
+ """Set fx_fallback=True when a cross-currency tx isn't backed by a real rate.
+
+ Covers both the legacy 1:1 fallback rate and rows left unconverted (NULL)
+ because no rate was available at stamp time (issue #353). The UI uses this
+ to warn the user and offer a manual rate.
+ """
+ if tx.currency != primary_currency and (
+ tx.amount_primary is None
+ or tx.fx_rate_used is None
+ or tx.fx_rate_used == 1.0
+ ):
tx.fx_fallback = True
return tx
diff --git a/backend/app/services/fx_rate_service.py b/backend/app/services/fx_rate_service.py
index 164fa823..5b22bd34 100644
--- a/backend/app/services/fx_rate_service.py
+++ b/backend/app/services/fx_rate_service.py
@@ -58,16 +58,22 @@ async def sync_rates(
return count
-async def get_rate(
+async def _resolve_rate(
session: AsyncSession,
from_currency: str,
to_currency: str,
target_date: Optional[date] = None,
-) -> Decimal:
- """Get FX rate from from_currency to to_currency.
+ *,
+ allow_fetch: bool = True,
+) -> Optional[Decimal]:
+ """Resolve the true FX rate, or None when no rate can be found.
Uses cross-rate through USD: rate = usd_to_target / usd_to_source.
- Priority: exact date → on-demand fetch → closest available → fallback 1:1.
+ Priority: exact date → on-demand fetch → closest available.
+ Returns None (not a fake 1:1) when no rate is available, so callers that
+ persist a conversion can honestly leave it NULL instead of storing a wrong
+ amount (issue #353). Pass ``allow_fetch=False`` to skip the on-demand
+ provider call and rely only on already-stored rates.
"""
if from_currency == to_currency:
return Decimal("1")
@@ -79,7 +85,7 @@ async def get_rate(
usd_to_target = await _get_exact_date_rate(session, to_currency, target)
# Step 2: If missing, fetch from provider for exact date
- if usd_to_source is None or usd_to_target is None:
+ if allow_fetch and (usd_to_source is None or usd_to_target is None):
try:
synced = await sync_rates(session, target)
if synced > 0:
@@ -102,17 +108,37 @@ async def get_rate(
if to_currency == "USD":
usd_to_target = Decimal("1")
- if usd_to_source is None or usd_to_target is None:
+ if usd_to_source is None or usd_to_target is None or usd_to_source == 0:
+ return None
+
+ return usd_to_target / usd_to_source
+
+
+async def get_rate(
+ session: AsyncSession,
+ from_currency: str,
+ to_currency: str,
+ target_date: Optional[date] = None,
+ *,
+ allow_fetch: bool = True,
+) -> Decimal:
+ """Get FX rate from from_currency to to_currency.
+
+ Uses cross-rate through USD. When no rate can be resolved, returns a 1:1
+ fallback so live reads (balances, dashboards) still render a number. This
+ fallback is NOT meant to be persisted — persisting paths use
+ :func:`_resolve_rate` directly and leave the value NULL instead (issue #353).
+ """
+ rate = await _resolve_rate(
+ session, from_currency, to_currency, target_date, allow_fetch=allow_fetch
+ )
+ if rate is None:
logger.warning(
"No FX rate found for %s -> %s on %s, returning 1",
- from_currency, to_currency, target,
+ from_currency, to_currency, target_date or date.today(),
)
return Decimal("1")
-
- if usd_to_source == 0:
- return Decimal("1")
-
- return usd_to_target / usd_to_source
+ return rate
async def _get_exact_date_rate(session: AsyncSession, currency: str, target: date) -> Optional[Decimal]:
@@ -162,63 +188,27 @@ async def _get_closest_rate(session: AsyncSession, currency: str, target: date)
return result
-async def _get_latest_rate(session: AsyncSession, currency: str) -> Optional[Decimal]:
- """Get the most recent rate for a currency vs USD."""
- if currency == "USD":
- return Decimal("1")
- result = await session.scalar(
- select(FxRate.rate)
- .where(
- FxRate.base_currency == "USD",
- FxRate.quote_currency == currency,
- )
- .order_by(desc(FxRate.date))
- .limit(1)
- )
- return result
-
-
-async def _get_month_closing_rate(
- session: AsyncSession, currency: str, target: date
-) -> Optional[Decimal]:
- """Get the last available rate within the target's month."""
- if currency == "USD":
- return Decimal("1")
- month_start = target.replace(day=1)
- if month_start.month == 12:
- month_end = month_start.replace(year=month_start.year + 1, month=1)
- else:
- month_end = month_start.replace(month=month_start.month + 1)
-
- result = await session.scalar(
- select(FxRate.rate)
- .where(
- FxRate.base_currency == "USD",
- FxRate.quote_currency == currency,
- FxRate.date >= month_start,
- FxRate.date < month_end,
- )
- .order_by(desc(FxRate.date))
- .limit(1)
- )
- return result
-
-
async def convert(
session: AsyncSession,
amount: Decimal,
from_currency: str,
to_currency: str,
target_date: Optional[date] = None,
+ *,
+ allow_fetch: bool = True,
) -> tuple[Decimal, Decimal]:
"""Convert an amount from one currency to another.
- Returns (converted_amount, rate_used).
+ Returns (converted_amount, rate_used). Uses the 1:1 fallback from
+ :func:`get_rate` when no rate is available, so this is for live reads, not
+ for persisting a stored conversion.
"""
if from_currency == to_currency:
return amount, Decimal("1")
- rate = await get_rate(session, from_currency, to_currency, target_date)
+ rate = await get_rate(
+ session, from_currency, to_currency, target_date, allow_fetch=allow_fetch
+ )
converted = amount * rate
return converted.quantize(Decimal("0.01")), rate
@@ -232,10 +222,21 @@ async def stamp_primary_amount(
rate_field: str = "fx_rate_used",
date_field: str = "date",
currency_field: str = "currency",
+ *,
+ allow_fetch: bool = True,
) -> None:
"""Set obj's primary amount and fx_rate_used based on user's primary currency.
Works for Transaction, RecurringTransaction, etc.
+
+ When the object is in a foreign currency and no real FX rate is available,
+ the fields are left untouched instead of persisting a fake 1:1 conversion
+ (issue #353). A brand-new object therefore stays NULL (honest "not converted",
+ reads fall back to the native amount via ``COALESCE(amount_primary, amount)``),
+ while an already-stamped row keeps its current value — so re-stamping never
+ pushes a visible transaction into limbo. The row heals on a later pass once a
+ rate for its date lands. Pass ``allow_fetch=False`` to avoid the on-demand
+ provider call (used by the healer to stay frugal).
"""
user = await session.get(User, user_id)
if not user:
@@ -248,9 +249,27 @@ async def stamp_primary_amount(
if obj_amount is None:
return
+ amount_dec = Decimal(str(obj_amount))
+
+ # Genuine same-currency 1:1 — always safe to persist.
+ if obj_currency == primary_currency:
+ setattr(obj, primary_field, amount_dec.quantize(Decimal("0.01")))
+ if hasattr(obj, rate_field):
+ setattr(obj, rate_field, Decimal("1"))
+ return
+
obj_date = getattr(obj, date_field, None)
- converted, rate = await convert(session, Decimal(str(obj_amount)), obj_currency, primary_currency, obj_date)
+ rate = await _resolve_rate(
+ session, obj_currency, primary_currency, obj_date, allow_fetch=allow_fetch
+ )
+
+ if rate is None:
+ # No real rate available yet. Leave the fields untouched: a brand-new
+ # object stays NULL (honest "not converted"), an existing row keeps its
+ # current value. Either way we never persist a fake 1:1, and never push a
+ # visible transaction into limbo. It heals on a later pass once a rate lands.
+ return
- setattr(obj, primary_field, converted)
+ setattr(obj, primary_field, (amount_dec * rate).quantize(Decimal("0.01")))
if hasattr(obj, rate_field):
setattr(obj, rate_field, rate)
diff --git a/backend/app/tasks/fx_backfill_tasks.py b/backend/app/tasks/fx_backfill_tasks.py
index a75fc31e..8ecb8656 100644
--- a/backend/app/tasks/fx_backfill_tasks.py
+++ b/backend/app/tasks/fx_backfill_tasks.py
@@ -1,9 +1,9 @@
import asyncio
import logging
-from datetime import date
+from datetime import date, timedelta
from decimal import Decimal
-from sqlalchemy import select, func, distinct
+from sqlalchemy import select, or_
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
from app.worker import celery_app
@@ -23,23 +23,46 @@ def _make_session_maker():
async def _backfill_primary_amounts() -> dict:
- """One-time backfill: stamp amount_primary on all rows where it's NULL."""
- from app.services.fx_rate_service import sync_rates, convert
+ """One-time backfill / heal of amount_primary.
+
+ Targets cross-currency rows that were never stamped (``amount_primary`` NULL)
+ or that were stamped with the legacy 1:1 fallback rate (issue #353), and
+ re-stamps them once a real rate is resolvable. Genuine same-currency 1:1 rows
+ are left untouched.
+ """
+ from app.services.fx_rate_service import sync_rates, convert, _resolve_rate
engine, session_maker = _make_session_maker()
try:
stats = {"transactions": 0, "recurring": 0, "assets": 0, "rates_synced": 0}
async with session_maker() as session:
- # 1. Collect all unique (year, month) pairs from transactions needing backfill
- month_result = await session.execute(
- select(distinct(func.to_char(Transaction.date, "YYYY-MM"))).where(
- Transaction.amount_primary.is_(None)
+ # 1. Get all users up front so we can tell cross-currency rows apart.
+ users_result = await session.execute(select(User))
+ settings = get_settings()
+ users = {u.id: u.primary_currency for u in users_result.scalars().all()}
+
+ def _primary(user_id) -> str:
+ return users.get(user_id, settings.default_currency)
+
+ # 2. Collect candidate transactions: never stamped OR stamped with the
+ # 1:1 fallback. Same-currency rows are filtered out so we never
+ # re-touch legitimate 1:1 conversions.
+ tx_result = await session.execute(
+ select(Transaction).where(
+ or_(
+ Transaction.amount_primary.is_(None),
+ Transaction.fx_rate_used == 1,
+ )
)
)
- months = [row[0] for row in month_result.all()]
+ candidate_txs = [
+ tx for tx in tx_result.scalars().all()
+ if tx.currency != _primary(tx.user_id)
+ ]
- # Sync historical rates for each month
+ # 3. Sync one historical rate per month that has candidates.
+ months = {tx.date.strftime("%Y-%m") for tx in candidate_txs}
for month_str in months:
try:
year, mon = month_str.split("-")
@@ -48,49 +71,49 @@ async def _backfill_primary_amounts() -> dict:
target = date(int(year) + 1, 1, 1)
else:
target = date(int(year), int(mon) + 1, 1)
- from datetime import timedelta
-
target = target - timedelta(days=1)
- count = await sync_rates(session, target)
- stats["rates_synced"] += count
+ stats["rates_synced"] += await sync_rates(session, target)
except Exception:
logger.exception("Failed to sync rates for %s", month_str)
- # 2. Get all users
- users_result = await session.execute(select(User))
- settings = get_settings()
- users = {u.id: (u.preferences or {}).get("currency_display", settings.default_currency) for u in users_result.scalars().all()}
-
- # 3. Backfill transactions
- tx_result = await session.execute(
- select(Transaction).where(Transaction.amount_primary.is_(None))
- )
- for tx in tx_result.scalars().all():
- primary_currency = users.get(tx.user_id, settings.default_currency)
+ # 4. Re-stamp candidates only when a real rate is now resolvable.
+ for tx in candidate_txs:
+ primary_currency = _primary(tx.user_id)
try:
- converted, rate = await convert(
- session, Decimal(str(tx.amount)),
- tx.currency, primary_currency, tx.date,
+ rate = await _resolve_rate(
+ session, tx.currency, primary_currency, tx.date,
)
- tx.amount_primary = converted
+ if rate is None:
+ continue # still no rate — leave as-is, heal next run
+ tx.amount_primary = (Decimal(str(tx.amount)) * rate).quantize(Decimal("0.01"))
tx.fx_rate_used = rate
stats["transactions"] += 1
except Exception:
logger.exception("Failed to backfill tx %s", tx.id)
await session.commit()
- # 4. Backfill recurring transactions
+ # 5. Backfill recurring transactions (same NULL-or-1:1 heal).
rec_result = await session.execute(
- select(RecurringTransaction).where(RecurringTransaction.amount_primary.is_(None))
+ select(RecurringTransaction).where(
+ or_(
+ RecurringTransaction.amount_primary.is_(None),
+ RecurringTransaction.fx_rate_used == 1,
+ )
+ )
)
- for rec in rec_result.scalars().all():
- primary_currency = users.get(rec.user_id, settings.default_currency)
+ candidate_recs = [
+ rec for rec in rec_result.scalars().all()
+ if rec.currency != _primary(rec.user_id)
+ ]
+ for rec in candidate_recs:
+ primary_currency = _primary(rec.user_id)
try:
- converted, rate = await convert(
- session, Decimal(str(rec.amount)),
- rec.currency, primary_currency, rec.start_date,
+ rate = await _resolve_rate(
+ session, rec.currency, primary_currency, rec.start_date,
)
- rec.amount_primary = converted
+ if rate is None:
+ continue
+ rec.amount_primary = (Decimal(str(rec.amount)) * rate).quantize(Decimal("0.01"))
rec.fx_rate_used = rate
stats["recurring"] += 1
except Exception:
diff --git a/backend/app/tasks/fx_rate_tasks.py b/backend/app/tasks/fx_rate_tasks.py
index a50ef748..50537ac9 100644
--- a/backend/app/tasks/fx_rate_tasks.py
+++ b/backend/app/tasks/fx_rate_tasks.py
@@ -62,6 +62,57 @@ async def _restamp_recurring_fx() -> int:
return count
+async def _restamp_fallback_transactions() -> int:
+ """Heal cross-currency transactions that lack a real FX rate.
+
+ Targets rows left NULL or stamped with the legacy 1:1 fallback (issue #353)
+ and *upgrades* them once a real rate for their date is available. Uses only
+ already-stored rates (``allow_fetch=False``) so a large heal never hammers
+ the FX provider — the daily ``sync_fx_rates`` task keeps rates fresh.
+
+ Conservative by construction: ``stamp_primary_amount`` only writes when a real
+ rate resolves and leaves the fields untouched otherwise, so an existing row is
+ never overwritten with NULL. A transaction that is currently visible in totals
+ (even with a stale 1:1 value) is never pushed into a "not converted" limbo — it
+ stays as-is until a real rate lets us fix it for good.
+ """
+ from sqlalchemy import or_, select
+
+ from app.models.transaction import Transaction
+ from app.models.user import User
+ from app.services.fx_rate_service import stamp_primary_amount
+
+ settings = get_settings()
+ engine, session_maker = _make_session_maker()
+ try:
+ async with session_maker() as session:
+ users = {
+ u.id: u.primary_currency
+ for u in (await session.execute(select(User))).scalars().all()
+ }
+ result = await session.execute(
+ select(Transaction).where(
+ or_(
+ Transaction.amount_primary.is_(None),
+ Transaction.fx_rate_used == 1,
+ )
+ )
+ )
+ count = 0
+ for tx in result.scalars().all():
+ primary = users.get(tx.user_id, settings.default_currency)
+ if tx.currency == primary:
+ continue # genuine same-currency row — never touch
+ before = (tx.amount_primary, tx.fx_rate_used)
+ await stamp_primary_amount(session, tx.user_id, tx, allow_fetch=False)
+ if (tx.amount_primary, tx.fx_rate_used) != before:
+ count += 1
+ await session.commit()
+ finally:
+ await engine.dispose()
+ return count
+
+
@celery_app.task(name="app.tasks.fx_rate_tasks.sync_fx_rates")
def sync_fx_rates() -> dict:
"""Celery task: sync latest FX rates from provider. Skips if fx_sync_mode != scheduled."""
@@ -84,3 +135,16 @@ def restamp_recurring_fx() -> dict:
count = asyncio.run(_restamp_recurring_fx())
logger.info("Recurring FX re-stamp complete: %d records updated", count)
return {"restamped": count}
+
+
+@celery_app.task(name="app.tasks.fx_rate_tasks.restamp_fallback_fx")
+def restamp_fallback_fx() -> dict:
+ """Celery task: heal cross-currency transactions stamped with the 1:1 fallback
+ (or left NULL) once real rates are available. Skips if fx_sync_mode != scheduled."""
+ settings = get_settings()
+ if settings.fx_sync_mode != "scheduled":
+ logger.debug("Fallback FX heal skipped (fx_sync_mode=%s)", settings.fx_sync_mode)
+ return {"skipped": True, "reason": "fx_sync_mode is not scheduled"}
+ count = asyncio.run(_restamp_fallback_transactions())
+ logger.info("Fallback FX heal complete: %d transactions healed", count)
+ return {"restamped": count}
diff --git a/backend/app/worker.py b/backend/app/worker.py
index 9dbbb00c..930fc475 100644
--- a/backend/app/worker.py
+++ b/backend/app/worker.py
@@ -47,6 +47,12 @@ celery_app.conf.beat_schedule = {
"task": "app.tasks.fx_rate_tasks.restamp_recurring_fx",
"schedule": 60 * 60 * 12, # twice daily, after FX rate sync
},
+ "restamp-fallback-fx-daily": {
+ "task": "app.tasks.fx_rate_tasks.restamp_fallback_fx",
+ # Twice daily, after FX rate sync — heals transactions that were
+ # stamped with the 1:1 fallback (or left NULL) once real rates land.
+ "schedule": 60 * 60 * 12,
+ },
}
celery_app.conf.include = [
diff --git a/backend/tests/test_fx_rates.py b/backend/tests/test_fx_rates.py
index 1aef615f..f729aa26 100644
--- a/backend/tests/test_fx_rates.py
+++ b/backend/tests/test_fx_rates.py
@@ -179,6 +179,41 @@ class TestGetRate:
assert rate == expected
+class TestResolveRate:
+ """Tests for fx_rate_service._resolve_rate() (returns None, no fake 1:1)."""
+
+ @pytest.mark.asyncio
+ async def test_returns_none_when_no_rate(self, session: AsyncSession):
+ from app.services.fx_rate_service import _resolve_rate
+
+ rate = await _resolve_rate(session, "JPY", "CHF", allow_fetch=False)
+ assert rate is None
+
+ @pytest.mark.asyncio
+ async def test_same_currency_returns_one(self, session: AsyncSession):
+ from app.services.fx_rate_service import _resolve_rate
+
+ rate = await _resolve_rate(session, "EUR", "EUR", allow_fetch=False)
+ assert rate == Decimal("1")
+
+ @pytest.mark.asyncio
+ async def test_resolves_real_rate(self, session: AsyncSession, fx_rates):
+ from app.services.fx_rate_service import _resolve_rate
+
+ rate = await _resolve_rate(session, "USD", "BRL", allow_fetch=False)
+ assert rate == Decimal("5.0000000000")
+
+ @pytest.mark.asyncio
+ async def test_get_rate_still_falls_back_to_one_for_live_reads(
+ self, session: AsyncSession
+ ):
+ """get_rate keeps the 1:1 fallback so balances/dashboards still render."""
+ from app.services.fx_rate_service import get_rate
+
+ rate = await get_rate(session, "JPY", "CHF", allow_fetch=False)
+ assert rate == Decimal("1")
+
+
class TestConvert:
"""Tests for fx_rate_service.convert()."""
@@ -267,6 +302,85 @@ class TestStampPrimaryAmount:
assert txn.amount_primary == Decimal("250.00") # 50 * 5.0
assert txn.fx_rate_used == Decimal("5.0000000000")
+ @pytest.mark.asyncio
+ async def test_no_rate_leaves_null_not_fake_1to1(
+ self, session: AsyncSession, test_user: User, test_account: Account
+ ):
+ """Cross-currency tx with no rate available → amount_primary/fx stay NULL (issue #353)."""
+ from app.services.fx_rate_service import stamp_primary_amount
+
+ txn = Transaction(
+ user_id=test_user.id,
+ account_id=test_account.id,
+ description="No rate USD",
+ amount=Decimal("50.00"),
+ currency="USD", # user primary is BRL, no fx_rates fixture
+ date=date.today(),
+ type="debit",
+ source="manual",
+ )
+ session.add(txn)
+ await session.flush()
+
+ await stamp_primary_amount(session, test_user.id, txn, allow_fetch=False)
+ # No fake 1:1 persisted — honestly NULL so it can self-heal later.
+ assert txn.amount_primary is None
+ assert txn.fx_rate_used is None
+
+ @pytest.mark.asyncio
+ async def test_heals_legacy_1to1_fallback_row(
+ self, session: AsyncSession, test_user: User, test_account: Account, fx_rates
+ ):
+ """A row wrongly stamped 1:1 gets re-stamped with the real rate once available."""
+ from app.services.fx_rate_service import stamp_primary_amount
+
+ # Simulate a legacy fallback row: USD amount stamped 1:1 into BRL.
+ txn = Transaction(
+ user_id=test_user.id,
+ account_id=test_account.id,
+ description="Legacy fallback",
+ amount=Decimal("100.00"),
+ currency="USD",
+ date=date.today(),
+ type="debit",
+ source="manual",
+ amount_primary=Decimal("100.00"),
+ fx_rate_used=Decimal("1"),
+ )
+ session.add(txn)
+ await session.flush()
+
+ # fx_rates fixture has USD→BRL = 5.0; heal without hitting the provider.
+ await stamp_primary_amount(session, test_user.id, txn, allow_fetch=False)
+ assert txn.amount_primary == Decimal("500.00") # 100 * 5.0
+ assert txn.fx_rate_used == Decimal("5.0000000000")
+
+ @pytest.mark.asyncio
+ async def test_same_currency_1to1_preserved(
+ self, session: AsyncSession, test_user: User, test_account: Account
+ ):
+ """Genuine same-currency 1:1 row is never nulled by re-stamping."""
+ from app.services.fx_rate_service import stamp_primary_amount
+
+ txn = Transaction(
+ user_id=test_user.id,
+ account_id=test_account.id,
+ description="BRL 1:1",
+ amount=Decimal("100.00"),
+ currency="BRL", # matches user primary
+ date=date.today(),
+ type="debit",
+ source="manual",
+ amount_primary=Decimal("100.00"),
+ fx_rate_used=Decimal("1"),
+ )
+ session.add(txn)
+ await session.flush()
+
+ await stamp_primary_amount(session, test_user.id, txn, allow_fetch=False)
+ assert txn.amount_primary == Decimal("100.00")
+ assert txn.fx_rate_used == Decimal("1")
+
@pytest.mark.asyncio
async def test_stamps_with_no_user_returns_early(self, session: AsyncSession):
"""Non-existent user → does nothing."""
@@ -664,10 +778,11 @@ class TestStampEdgeCases:
assert obj.purchase_price_primary == Decimal("500.00")
@pytest.mark.asyncio
- async def test_missing_currency_field_defaults_brl(
- self, session: AsyncSession, test_user: User
+ async def test_missing_currency_field_defaults_to_default_currency(
+ self, session: AsyncSession, test_user: User, fx_rates
):
- """Object without currency field defaults to BRL (user primary=BRL → rate 1)."""
+ """Object without a currency field falls back to the default currency (USD)
+ and converts to the user's primary (BRL) at the real rate."""
from app.services.fx_rate_service import stamp_primary_amount
class FakeObj:
@@ -675,12 +790,13 @@ class TestStampEdgeCases:
amount_primary = None
fx_rate_used = None
date = date.today()
- # No 'currency' attribute
+ # No 'currency' attribute → defaults to settings.default_currency (USD)
obj = FakeObj()
- await stamp_primary_amount(session, test_user.id, obj)
- assert obj.amount_primary == Decimal("100.00")
- assert obj.fx_rate_used == Decimal("1")
+ await stamp_primary_amount(session, test_user.id, obj, allow_fetch=False)
+ # USD→BRL at 5.0
+ assert obj.amount_primary == Decimal("500.00")
+ assert obj.fx_rate_used == Decimal("5.0000000000")
# ═══════════════════════════════════════════════════════════════════════════
@@ -1041,6 +1157,91 @@ class TestBackfillTask:
# Our stamped transaction should not appear
assert txn.id not in [t.id for t in null_txns]
+ @pytest.mark.asyncio
+ async def test_heal_selection_covers_1to1_fallback_rows(
+ self,
+ session: AsyncSession,
+ test_user: User,
+ test_account: Account,
+ ):
+ """The widened heal query (NULL OR fx_rate_used==1, cross-currency) picks up
+ legacy 1:1 fallback rows but skips genuine same-currency 1:1 rows (issue #353)."""
+ from sqlalchemy import or_, select
+
+ primary = test_user.primary_currency # BRL
+
+ # (a) cross-currency row wrongly stamped 1:1 → should be selected
+ fallback = Transaction(
+ user_id=test_user.id, account_id=test_account.id,
+ description="USD fallback", amount=Decimal("100.00"), currency="USD",
+ date=date.today(), type="debit", source="manual",
+ amount_primary=Decimal("100.00"), fx_rate_used=Decimal("1"),
+ )
+ # (b) never-stamped cross-currency row → should be selected
+ null_row = Transaction(
+ user_id=test_user.id, account_id=test_account.id,
+ description="EUR null", amount=Decimal("10.00"), currency="EUR",
+ date=date.today(), type="debit", source="manual",
+ amount_primary=None, fx_rate_used=None,
+ )
+ # (c) genuine same-currency 1:1 row → must NOT be selected/healed
+ same_ccy = Transaction(
+ user_id=test_user.id, account_id=test_account.id,
+ description="BRL 1:1", amount=Decimal("50.00"), currency="BRL",
+ date=date.today(), type="debit", source="manual",
+ amount_primary=Decimal("50.00"), fx_rate_used=Decimal("1"),
+ )
+ session.add_all([fallback, null_row, same_ccy])
+ await session.commit()
+
+ result = await session.execute(
+ select(Transaction).where(
+ or_(
+ Transaction.amount_primary.is_(None),
+ Transaction.fx_rate_used == 1,
+ )
+ )
+ )
+ candidates = [
+ tx for tx in result.scalars().all() if tx.currency != primary
+ ]
+ ids = {tx.id for tx in candidates}
+ assert fallback.id in ids
+ assert null_row.id in ids
+ assert same_ccy.id not in ids
+
+ @pytest.mark.asyncio
+ async def test_healer_never_nulls_existing_row_without_rate(
+ self,
+ session: AsyncSession,
+ test_user: User,
+ test_account: Account,
+ ):
+ """Re-stamping must NEVER downgrade an existing 1:1 row to NULL when no real
+ rate is available — that would push a visible transaction into limbo
+ (issue #353). stamp_primary_amount only upgrades; otherwise it leaves the
+ row exactly as-is (this is what makes the periodic healer safe)."""
+ from decimal import Decimal as D
+
+ from app.services.fx_rate_service import stamp_primary_amount
+
+ # USD row stamped 1:1 (legacy fallback). No fx_rates fixture → no rate.
+ tx = Transaction(
+ user_id=test_user.id, account_id=test_account.id,
+ description="USD legacy 1:1", amount=D("100.00"), currency="USD",
+ date=date.today(), type="debit", source="manual",
+ amount_primary=D("100.00"), fx_rate_used=D("1"),
+ )
+ session.add(tx)
+ await session.flush()
+
+ # Re-stamp with no rate available — must leave the row untouched.
+ await stamp_primary_amount(session, test_user.id, tx, allow_fetch=False)
+
+ # Still visible with its previous value, not NULL.
+ assert tx.amount_primary == D("100.00")
+ assert tx.fx_rate_used == D("1")
+
# ═══════════════════════════════════════════════════════════════════════════
# 12. RECURRING FX RE-STAMP
@@ -1341,7 +1542,7 @@ class TestFxFallbackFlag:
test_user: User,
session: AsyncSession,
):
- """Cross-currency transaction with no FX rates → fx_fallback=True."""
+ """Cross-currency transaction with no FX rates → left NULL, fx_fallback=True (issue #353)."""
usd_account = await _make_account(session, test_user, currency="USD")
resp = await client.post(
@@ -1358,8 +1559,10 @@ class TestFxFallbackFlag:
)
assert resp.status_code == 201
data = resp.json()
- # No FX rates in DB → falls back to 1:1
- assert data["fx_rate_used"] == 1.0
+ # No FX rate available → we honestly leave it unconverted (NULL) rather
+ # than persisting a fake 1:1 conversion that would never self-heal.
+ assert data["amount_primary"] is None
+ assert data["fx_rate_used"] is None
assert data["fx_fallback"] is True
@pytest.mark.asyncio
@@ -1431,7 +1634,7 @@ class TestFxFallbackFlag:
"""GET /api/transactions tags fx_fallback on listed items."""
usd_account = await _make_account(session, test_user, currency="USD")
- # Create a transaction that will fall back to 1:1 (no rates)
+ # Create a cross-currency transaction with no rates → left unconverted
resp = await client.post(
"/api/transactions",
headers=auth_headers,
@@ -1452,4 +1655,5 @@ class TestFxFallbackFlag:
items = resp2.json()["items"]
fallback_items = [i for i in items if i["description"] == "Fallback in list"]
assert len(fallback_items) == 1
+ assert fallback_items[0]["amount_primary"] is None
assert fallback_items[0]["fx_fallback"] is True