Skip to content

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

feat(rules): apply a new rule to existing transactions on creation (#310)

Tássio Noronha5eca42e2dbb6
diff --git a/backend/app/api/rules.py b/backend/app/api/rules.py
index 9ebb8ac2..18924a92 100644
--- a/backend/app/api/rules.py
+++ b/backend/app/api/rules.py
@@ -9,7 +9,7 @@ from app.core.workspace_context import (
current_workspace,
current_writable_workspace,
)
-from app.schemas.rule import RuleCreate, RuleRead, RuleUpdate
+from app.schemas.rule import RuleCreate, RuleCreateResponse, RuleRead, RuleUpdate
from app.services import rule_service
from app.services.rule_service import DuplicateRuleError
@@ -24,19 +24,25 @@ async def list_rules(
return await rule_service.get_rules(session, ctx.workspace.id)
[email protected]("", response_model=RuleRead, status_code=status.HTTP_201_CREATED)
[email protected]("", response_model=RuleCreateResponse, status_code=status.HTTP_201_CREATED)
async def create_rule(
data: RuleCreate,
ctx: WorkspaceContext = Depends(current_writable_workspace),
session: AsyncSession = Depends(get_async_session),
):
try:
- return await rule_service.create_rule(session, ctx.workspace.id, ctx.user_id, data)
+ rule = await rule_service.create_rule(session, ctx.workspace.id, ctx.user_id, data)
except DuplicateRuleError:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="A rule with this name already exists",
)
+ # Apply the new rule to existing transactions so it takes effect on history
+ # immediately, and report how many were touched for a transparent toast.
+ applied_count = await rule_service.apply_single_rule(session, ctx.workspace.id, rule)
+ response = RuleCreateResponse.model_validate(rule)
+ response.applied_count = applied_count
+ return response
@router.patch("/{rule_id}", response_model=RuleRead)
diff --git a/backend/app/schemas/rule.py b/backend/app/schemas/rule.py
index c1373447..1404ae72 100644
--- a/backend/app/schemas/rule.py
+++ b/backend/app/schemas/rule.py
@@ -45,3 +45,9 @@ class RuleRead(BaseModel):
is_active: bool
model_config = ConfigDict(from_attributes=True)
+
+
+class RuleCreateResponse(RuleRead):
+ """A created rule plus how many existing transactions it just affected."""
+
+ applied_count: int = 0
diff --git a/backend/app/services/rule_service.py b/backend/app/services/rule_service.py
index 21ba9aae..77a0bf44 100644
--- a/backend/app/services/rule_service.py
+++ b/backend/app/services/rule_service.py
@@ -866,6 +866,46 @@ async def apply_rules_to_transaction(
category_set = apply_rule_actions(actions, transaction, category_set)
+async def apply_single_rule(
+ session: AsyncSession, workspace_id: uuid.UUID, rule: Rule
+) -> int:
+ """Apply one rule to all existing workspace transactions. Returns the number
+ of transactions actually modified.
+
+ Used right after a rule is created so it takes effect on history without the
+ user having to hit "Reapply all". Unlike `apply_all_rules` this is
+ non-destructive: a transaction that already has a category keeps it (same
+ semantics used when new transactions arrive), so creating a rule never
+ silently overwrites manual categorizations. Payee/notes/ignore actions still
+ apply on a match. Only transactions whose fields actually change are counted.
+ """
+ if not rule.is_active:
+ return 0
+
+ result = await session.execute(
+ select(Transaction).where(
+ Transaction.workspace_id == workspace_id,
+ Transaction.source != "opening_balance",
+ )
+ )
+ transactions = result.scalars().all()
+
+ conditions = rule.conditions or []
+ actions = rule.actions or []
+
+ count = 0
+ for tx in transactions:
+ if not evaluate_conditions(rule.conditions_op, conditions, tx):
+ continue
+ before = (tx.category_id, tx.payee_id, tx.notes, tx.is_ignored)
+ apply_rule_actions(actions, tx, category_already_set=tx.category_id is not None)
+ if before != (tx.category_id, tx.payee_id, tx.notes, tx.is_ignored):
+ count += 1
+
+ await session.commit()
+ return count
+
+
async def apply_all_rules(session: AsyncSession, workspace_id: uuid.UUID) -> int:
"""Re-apply all active rules to all workspace transactions. Returns count of affected transactions."""
from app.models.account import Account
diff --git a/backend/tests/test_new_rules_api.py b/backend/tests/test_new_rules_api.py
index 02422772..7b7665a9 100644
--- a/backend/tests/test_new_rules_api.py
+++ b/backend/tests/test_new_rules_api.py
@@ -54,6 +54,79 @@ async def test_create_rule(client: AsyncClient, auth_headers, test_categories):
data = response.json()
assert data["name"] == "Test Rule"
assert data["conditions"][0]["value"] == "IFOOD"
+ assert "applied_count" in data
+
+
+async def test_create_rule_applies_to_existing_transactions(
+ client: AsyncClient, auth_headers, test_transactions, test_categories,
+):
+ """Creating a rule immediately applies it to existing transactions and
+ reports how many were affected, without needing apply-all.
+
+ NETFLIX starts uncategorised in the fixture, so the new rule categorises it.
+ """
+ cat_food = str(test_categories[0].id)
+ payload = {
+ "name": "Netflix",
+ "conditions_op": "and",
+ "conditions": [{"field": "description", "op": "contains", "value": "NETFLIX"}],
+ "actions": [{"op": "set_category", "value": cat_food}],
+ "priority": 5,
+ "is_active": True,
+ }
+ response = await client.post("/api/rules", json=payload, headers=auth_headers)
+ assert response.status_code == 201
+ assert response.json()["applied_count"] >= 1
+
+ # The matching transaction is categorised without an explicit apply-all call.
+ items = (await client.get("/api/transactions", headers=auth_headers)).json()["items"]
+ netflix = {t["description"]: t for t in items}.get("NETFLIX")
+ assert netflix is not None
+ assert netflix["category_id"] == cat_food
+
+
+async def test_create_rule_does_not_overwrite_existing_category(
+ client: AsyncClient, auth_headers, test_transactions, test_categories,
+):
+ """Auto-apply on create is non-destructive: an already-categorised
+ transaction keeps its category instead of being clobbered."""
+ original = str(test_categories[0].id) # IFOOD RESTAURANTE is pre-set to this
+ other = str(test_categories[1].id)
+ payload = {
+ "name": "iFood recat",
+ "conditions_op": "and",
+ "conditions": [{"field": "description", "op": "contains", "value": "IFOOD"}],
+ "actions": [{"op": "set_category", "value": other}],
+ "priority": 5,
+ "is_active": True,
+ }
+ response = await client.post("/api/rules", json=payload, headers=auth_headers)
+ assert response.status_code == 201
+ assert response.json()["applied_count"] == 0
+
+ items = (await client.get("/api/transactions", headers=auth_headers)).json()["items"]
+ ifood = {t["description"]: t for t in items}.get("IFOOD RESTAURANTE")
+ assert ifood["category_id"] == original
+
+
+async def test_create_rule_no_match_reports_zero(
+ client: AsyncClient, auth_headers, test_transactions, test_categories,
+):
+ """A rule that matches nothing reports applied_count == 0."""
+ payload = {
+ "name": "No match",
+ "conditions_op": "and",
+ "conditions": [{"field": "description", "op": "contains", "value": "ZZZ_NOMATCH"}],
+ "actions": [{"op": "set_category", "value": str(test_categories[0].id)}],
+ "priority": 5,
+ "is_active": True,
+ }
+ response = await client.post("/api/rules", json=payload, headers=auth_headers)
+ assert response.status_code == 201
+ assert response.json()["applied_count"] == 0
@pytest.mark.asyncio
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index bdf8987f..43d79106 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -728,7 +728,7 @@ export const rules = {
const { data } = await api.get('/rules')
return data
},
- create: async (rule: Omit<Rule, 'id' | 'user_id'>): Promise<Rule> => {
+ create: async (rule: Omit<Rule, 'id' | 'user_id'>): Promise<Rule & { applied_count: number }> => {
const { data } = await api.post('/rules', rule)
return data
},
diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.json
index 4ebee429..3e0673a5 100644
--- a/frontend/src/locales/en.json
+++ b/frontend/src/locales/en.json
@@ -710,6 +710,7 @@
"reapplyAll": "Reapply all",
"add": "Add",
"created": "Rule created",
+ "createdAndApplied": "Rule created and applied to {{count}} transactions",
"updated": "Rule updated",
"deleted": "Rule deleted",
"applied": "Rules applied to {{count}} transactions",
diff --git a/frontend/src/locales/es.json b/frontend/src/locales/es.json
index 79c3b81a..9235d8c2 100644
--- a/frontend/src/locales/es.json
+++ b/frontend/src/locales/es.json
@@ -708,6 +708,7 @@
"reapplyAll": "Reaplicar todo",
"add": "Agregar",
"created": "Regla creada",
+ "createdAndApplied": "Regla creada y aplicada a {{count}} transacciones",
"updated": "Regla actualizada",
"deleted": "Regla eliminada",
"applied": "Reglas aplicadas a {{count}} transacciones",
diff --git a/frontend/src/locales/it.json b/frontend/src/locales/it.json
index a753ddc3..a2c54b74 100644
--- a/frontend/src/locales/it.json
+++ b/frontend/src/locales/it.json
@@ -683,6 +683,7 @@
"reapplyAll": "Riapplica tutte",
"add": "Aggiungi",
"created": "Regola creata",
+ "createdAndApplied": "Regola creata e applicata a {{count}} transazioni",
"updated": "Regola aggiornata",
"deleted": "Regola eliminata",
"applied": "Regole applicate a {{count}} transazioni",
diff --git a/frontend/src/locales/pl.json b/frontend/src/locales/pl.json
index 946fabcf..c8502f80 100644
--- a/frontend/src/locales/pl.json
+++ b/frontend/src/locales/pl.json
@@ -761,6 +761,7 @@
"reapplyAll": "Zastosuj ponownie wszystkie",
"add": "Dodaj",
"created": "Utworzono regułę",
+ "createdAndApplied": "Utworzono regułę i zastosowano do {{count}} transakcji",
"updated": "Zaktualizowano regułę",
"deleted": "Usunięto regułę",
"applied_one": "Zastosowano reguły do {{count}} transakcji",
diff --git a/frontend/src/locales/pt-BR.json b/frontend/src/locales/pt-BR.json
index 585547c4..62e604f4 100644
--- a/frontend/src/locales/pt-BR.json
+++ b/frontend/src/locales/pt-BR.json
@@ -710,6 +710,7 @@
"reapplyAll": "Reaplicar todas",
"add": "Adicionar",
"created": "Regra criada",
+ "createdAndApplied": "Regra criada e aplicada a {{count}} transações",
"updated": "Regra atualizada",
"deleted": "Regra excluída",
"applied": "Regras aplicadas a {{count}} transações",
diff --git a/frontend/src/pages/rules.tsx b/frontend/src/pages/rules.tsx
index 98e2d1e4..41a6637b 100644
--- a/frontend/src/pages/rules.tsx
+++ b/frontend/src/pages/rules.tsx
@@ -160,11 +160,19 @@ export default function RulesPage() {
const createMutation = useMutation({
mutationFn: (data: Omit<Rule, 'id' | 'user_id'>) => rulesApi.create(data),
- onSuccess: () => {
+ onSuccess: (result) => {
queryClient.invalidateQueries({ queryKey: ['rules'] })
queryClient.invalidateQueries({ queryKey: ['rule-packs'] })
setDialogOpen(false)
- toast.success(t('rules.created'))
+ // The rule was applied to existing transactions on creation; refresh
+ // financial views and report how many were affected for transparency.
+ const applied = result.applied_count ?? 0
+ if (applied > 0) {
+ invalidateFinancialQueries(queryClient)
+ toast.success(t('rules.createdAndApplied', { count: applied }))
+ } else {
+ toast.success(t('rules.created'))
+ }
},
onError: (error: unknown) => {
const err = error as { response?: { status?: number } }