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.pyindex 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, RuleUpdatefrom app.services import rule_servicefrom 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.pyindex c1373447..1404ae72 100644--- a/backend/app/schemas/rule.py+++ b/backend/app/schemas/rule.py@@ -45,3 +45,9 @@ class RuleRead(BaseModel):is_active: boolmodel_config = ConfigDict(from_attributes=True)+++class RuleCreateResponse(RuleRead):+ """A created rule plus how many existing transactions it just affected."""++ applied_count: int = 0diff --git a/backend/app/services/rule_service.py b/backend/app/services/rule_service.pyindex 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 Accountdiff --git a/backend/tests/test_new_rules_api.py b/backend/tests/test_new_rules_api.pyindex 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.asynciodiff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.tsindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.tsxindex 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 } }