Open-source personal finance manager. Self-hosted, privacy-first.
fix: rule pack robustness for users without complete defaults (#154) (#165)
Tássio Noronha665e2f5dd6ff
diff --git a/backend/app/api/rules.py b/backend/app/api/rules.pyindex 624b2a78..4d5a24a2 100644--- a/backend/app/api/rules.py+++ b/backend/app/api/rules.py@@ -88,15 +88,30 @@ async def list_rule_packs(@router.post("/packs/{pack_code}/install", response_model=dict)async def install_rule_pack(pack_code: str,+ create_missing_categories: bool = False,session: AsyncSession = Depends(get_async_session),user: User = Depends(current_active_user),):- """Install a country-specific rule pack."""+ """Install a country-specific rule pack.++ `create_missing_categories=true` opts into seeding any default+ categories the pack needs that the user doesn't already have.+ """if pack_code not in rule_service.RULE_PACKS:raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Rule pack not found")lang = (user.preferences or {}).get("language", "pt-BR")- rules = await rule_service.install_rule_pack(session, user.id, pack_code, lang)- return {"installed": len(rules)}+ result = await rule_service.install_rule_pack(+ session,+ user.id,+ pack_code,+ lang,+ create_missing_categories=create_missing_categories,+ )+ return {+ "installed": len(result.rules),+ "unresolved": result.unresolved,+ "categories_created": result.categories_created,+ }@router.post("/apply-all", response_model=dict)diff --git a/backend/app/services/admin_service.py b/backend/app/services/admin_service.pyindex b33e1078..04deffc5 100644--- a/backend/app/services/admin_service.py+++ b/backend/app/services/admin_service.py@@ -44,8 +44,14 @@ async def create_user(user_manager: UserManager,data: AdminUserCreate,) -> User:+ from decimal import Decimal+from fastapi_users.schemas import BaseUserCreate+ from app.models.account import Account+ from app.services.category_service import create_default_categories+ from app.services.rule_service import create_default_rules+create_schema = BaseUserCreate(email=data.email,password=data.password,@@ -66,6 +72,25 @@ async def create_user(await session.commit()await session.refresh(user)+ # Seed default wallet, categories, and rules. The on_after_register+ # hook (auth.py) short-circuits when called programmatically with+ # request=None — which is exactly this path — so admin-created users+ # would otherwise land with no defaults and a broken UX.+ lang = (user.preferences or {}).get("language", "en")+ wallet_name = "Carteira" if lang.startswith("pt") else "Wallet"+ wallet = Account(+ user_id=user.id,+ name=wallet_name,+ type="checking",+ balance=Decimal("0.00"),+ currency=user.primary_currency,+ )+ session.add(wallet)+ await session.commit()++ await create_default_categories(session, user.id, lang)+ await create_default_rules(session, user.id, lang)+return userdiff --git a/backend/app/services/rule_service.py b/backend/app/services/rule_service.pyindex e41c4e0c..3a7aabc1 100644--- a/backend/app/services/rule_service.py+++ b/backend/app/services/rule_service.py@@ -453,30 +453,64 @@ CURRENCY_TO_PACK = {}-def _resolve_category_name(internal_key: str, lang: str) -> str:- """Resolve internal category key to the localized name."""- data = DEFAULT_CATEGORIES_I18N.get(internal_key, {})- return data.get(lang, data.get("en", internal_key))---def _build_rules_from_templates(templates: list[dict], categories: dict[str, str], lang: str) -> list[dict]:- """Convert rule templates (with internal keys) to rules with resolved category UUIDs."""- resolved = []+def _resolve_categories_by_internal_key(+ categories_by_name: dict[str, str],+) -> dict[str, str]:+ """Map default-category internal keys (e.g. 'transport') to the user's actual+ category UUID by matching against any language variant of the default name.++ Rule templates reference categories by their internal key, but the user's+ categories are stored under a localized name. If we resolve the key using+ only the language passed in, an "en"-named category ("Transport") won't+ match a "pt-BR" lookup ("Transporte"), so every rule gets silently+ dropped. Walking all language variants makes pack install work no matter+ which language the user's categories were created in.+ """+ key_to_id: dict[str, str] = {}+ non_name_fields = {"icon", "color", "treat_as_transfer"}+ for internal_key, data in DEFAULT_CATEGORIES_I18N.items():+ for field, value in data.items():+ if field in non_name_fields:+ continue+ cat_id = categories_by_name.get(value)+ if cat_id:+ key_to_id[internal_key] = cat_id+ break+ return key_to_id+++def _build_rules_from_templates(+ templates: list[dict], key_to_category_id: dict[str, str]+) -> tuple[list[dict], int]:+ """Convert rule templates (with internal keys) to rules with resolved category UUIDs.++ Returns (resolved_rules, unresolved_count) — unresolved is how many+ templates were dropped because their `set_category` target category+ doesn't exist for this user. Callers use it to distinguish "pack+ already installed" (every rule skipped because the name already+ exists) from "pack can't be installed" (rules skipped because the+ user has no matching category).+ """+ resolved: list[dict] = []+ unresolved = 0for rule_data in templates:actions = []+ dropped_for_missing_category = Falsefor action in rule_data["actions"]:if action["op"] == "set_category":- cat_name = _resolve_category_name(action["value"], lang)- cat_id = categories.get(cat_name)+ cat_id = key_to_category_id.get(action["value"])if not cat_id:+ dropped_for_missing_category = Truecontinueactions.append({"op": "set_category", "value": cat_id})else:actions.append(action)if not actions:+ if dropped_for_missing_category:+ unresolved += 1continueresolved.append({**rule_data, "actions": actions})- return resolved+ return resolved, unresolvedasync def _get_existing_rule_names(session: AsyncSession, user_id: uuid.UUID) -> set[str]:@@ -488,11 +522,17 @@ async def _get_existing_rule_names(session: AsyncSession, user_id: uuid.UUID) ->async def create_default_rules(session: AsyncSession, user_id: uuid.UUID, lang: str = "pt-BR") -> list[Rule]:- """Create universal default categorization rules for a new user."""+ """Create universal default categorization rules for a new user.++ `lang` is accepted for backwards compatibility but no longer affects+ category resolution — categories are matched by internal key across all+ language variants.+ """result = await session.execute(select(Category).where(Category.user_id == user_id))categories = {cat.name: str(cat.id) for cat in result.scalars().all()}+ key_to_id = _resolve_categories_by_internal_key(categories)- resolved = _build_rules_from_templates(UNIVERSAL_RULES, categories, lang)+ resolved, _unresolved = _build_rules_from_templates(UNIVERSAL_RULES, key_to_id)rules = []for rule_data in resolved:@@ -512,20 +552,159 @@ async def create_default_rules(session: AsyncSession, user_id: uuid.UUID, lang:return rules-async def install_rule_pack(session: AsyncSession, user_id: uuid.UUID, pack_code: str, lang: str = "pt-BR") -> list[Rule]:- """Install a country-specific rule pack for a user. Skips rules whose name already exists."""+class RulePackInstallResult:+ """Outcome of installing a country-specific rule pack."""++ __slots__ = ("rules", "unresolved", "categories_created")++ def __init__(+ self,+ rules: list[Rule],+ unresolved: int,+ categories_created: int = 0,+ ) -> None:+ self.rules = rules+ self.unresolved = unresolved+ self.categories_created = categories_created+++def _required_internal_keys(pack: dict) -> set[str]:+ """Return the set of category internal keys referenced by a pack's rules."""+ keys: set[str] = set()+ for rule in pack["rules"]:+ for action in rule["actions"]:+ if action["op"] == "set_category":+ keys.add(action["value"])+ return keys+++async def _ensure_categories_for_keys(+ session: AsyncSession,+ user_id: uuid.UUID,+ internal_keys: set[str],+ lang: str,+) -> int:+ """Create any default categories from `internal_keys` that the user is missing.++ Idempotent — categories are matched across language variants, so a+ user with English defaults won't get Portuguese duplicates if `lang`+ happens to be pt-BR. Returns the count of newly-created categories.+ """+ from app.models.category_group import CategoryGroup+ from app.services.category_group_service import (+ CATEGORY_TO_GROUP,+ DEFAULT_GROUPS_I18N,+ )+ from app.services.category_service import DEFAULT_CATEGORIES_I18N++ non_name_fields = {"icon", "color", "treat_as_transfer", "position"}++ def variants(data: dict) -> set[str]:+ return {v for k, v in data.items() if k not in non_name_fields}++ existing_cats = list(+ (+ await session.execute(+ select(Category).where(Category.user_id == user_id)+ )+ ).scalars().all()+ )+ existing_cat_names = {c.name for c in existing_cats}++ missing_keys = [+ key+ for key in internal_keys+ if (data := DEFAULT_CATEGORIES_I18N.get(key))+ and not (variants(data) & existing_cat_names)+ ]+ if not missing_keys:+ return 0++ existing_groups = list(+ (+ await session.execute(+ select(CategoryGroup).where(CategoryGroup.user_id == user_id)+ )+ ).scalars().all()+ )++ needed_group_keys = {+ gk for gk in (CATEGORY_TO_GROUP.get(k) for k in missing_keys) if gk+ }+ groups_by_key: dict[str, CategoryGroup] = {}+ for gkey in needed_group_keys:+ gdata = DEFAULT_GROUPS_I18N.get(gkey)+ if not gdata:+ continue+ match = next(+ (g for g in existing_groups if g.name in variants(gdata)), None+ )+ if match:+ groups_by_key[gkey] = match+ continue+ group = CategoryGroup(+ user_id=user_id,+ name=gdata.get(lang, gdata["en"]),+ icon=gdata["icon"],+ color=gdata["color"],+ position=gdata["position"],+ is_system=True,+ )+ session.add(group)+ groups_by_key[gkey] = group+ await session.flush()++ for key in missing_keys:+ data = DEFAULT_CATEGORIES_I18N[key]+ target_group = groups_by_key.get(CATEGORY_TO_GROUP.get(key))+ cat = Category(+ user_id=user_id,+ name=data.get(lang, data["en"]),+ icon=data["icon"],+ color=data["color"],+ is_system=True,+ group_id=target_group.id if target_group else None,+ treat_as_transfer=data.get("treat_as_transfer", False),+ )+ session.add(cat)+ await session.commit()+ return len(missing_keys)+++async def install_rule_pack(+ session: AsyncSession,+ user_id: uuid.UUID,+ pack_code: str,+ lang: str = "pt-BR",+ create_missing_categories: bool = False,+) -> RulePackInstallResult:+ """Install a country-specific rule pack for a user. Skips rules whose name already exists.++ When `create_missing_categories=True`, creates any default categories+ referenced by the pack that the user is missing — so users in a+ degenerate state (or who never had defaults seeded) can opt into+ "install pack, fill in what's needed". `lang` controls the names of+ any newly-created categories.+ """pack = RULE_PACKS.get(pack_code)if not pack:- return []+ return RulePackInstallResult([], 0)++ categories_created = 0+ if create_missing_categories:+ categories_created = await _ensure_categories_for_keys(+ session, user_id, _required_internal_keys(pack), lang+ )result = await session.execute(select(Category).where(Category.user_id == user_id))categories = {cat.name: str(cat.id) for cat in result.scalars().all()}+ key_to_id = _resolve_categories_by_internal_key(categories)- resolved = _build_rules_from_templates(pack["rules"], categories, lang)+ resolved, unresolved = _build_rules_from_templates(pack["rules"], key_to_id)existing_names = await _get_existing_rule_names(session, user_id)- rules = []+ rules: list[Rule] = []for rule_data in resolved:if rule_data["name"] in existing_names:continue@@ -542,7 +721,7 @@ async def install_rule_pack(session: AsyncSession, user_id: uuid.UUID, pack_coderules.append(rule)await session.commit()- return rules+ return RulePackInstallResult(rules, unresolved, categories_created)async def get_installed_packs(session: AsyncSession, user_id: uuid.UUID) -> dict[str, bool]:diff --git a/backend/tests/test_admin_api.py b/backend/tests/test_admin_api.pyindex 58bf291a..a2b25bb1 100644--- a/backend/tests/test_admin_api.py+++ b/backend/tests/test_admin_api.py@@ -50,6 +50,38 @@ class TestAdminUserCRUD:assert data["is_active"] is Trueassert data["is_superuser"] is False+ async def test_create_user_seeds_defaults(+ self, client: AsyncClient, admin_auth_headers: dict, test_superuser: User+ ):+ # Regression for #154: admin-created users were left without default+ # categories, rules, or a wallet because on_after_register bails when+ # called programmatically (request=None).+ create_resp = await client.post(+ "/api/admin/users",+ json={+ "email": "[email protected]",+ "password": "password123",+ "preferences": {"language": "en", "currency_display": "USD"},+ },+ headers=admin_auth_headers,+ )+ assert create_resp.status_code == 201++ login_resp = await client.post(+ "/api/auth/login",+ data={"username": "[email protected]", "password": "password123"},+ )+ token = login_resp.json()["access_token"]+ user_headers = {"Authorization": f"Bearer {token}"}++ cats = (await client.get("/api/categories", headers=user_headers)).json()+ rules = (await client.get("/api/rules", headers=user_headers)).json()+ accounts = (await client.get("/api/accounts", headers=user_headers)).json()++ assert len(cats) > 0, "admin-created user should have default categories"+ assert len(rules) > 0, "admin-created user should have default rules"+ assert len(accounts) == 1, "admin-created user should have a default wallet"+async def test_create_duplicate_user(self, client: AsyncClient, admin_auth_headers: dict, test_superuser: User):# Create firstawait client.post(diff --git a/backend/tests/test_rule_service.py b/backend/tests/test_rule_service.pyindex 30c08ab6..aa60622d 100644--- a/backend/tests/test_rule_service.py+++ b/backend/tests/test_rule_service.py@@ -10,6 +10,7 @@ from app.models.transaction import Transactionfrom app.schemas.rule import RuleAction, RuleCondition, RuleCreate, RuleUpdatefrom app.services.rule_service import (DuplicateRuleError,+ RULE_PACKS,apply_all_rules,apply_rules_to_transaction,create_default_rules,@@ -476,10 +477,11 @@ async def test_create_default_rules(session: AsyncSession, test_user):async def test_install_rule_pack_br(session: AsyncSession, test_user):await create_default_categories(session, test_user.id, lang="pt-BR")- rules = await install_rule_pack(session, test_user.id, "BR", lang="pt-BR")- assert len(rules) > 0+ result = await install_rule_pack(session, test_user.id, "BR", lang="pt-BR")+ assert len(result.rules) > 0+ assert result.unresolved == 0- names = {r.name for r in rules}+ names = {r.name for r in result.rules}assert "iFood / Rappi" in names@@ -490,14 +492,69 @@ async def test_install_rule_pack_skips_duplicates(session: AsyncSession, test_usfirst = await install_rule_pack(session, test_user.id, "BR", lang="pt-BR")second = await install_rule_pack(session, test_user.id, "BR", lang="pt-BR")- assert len(first) > 0- assert len(second) == 0 # all already installed+ assert len(first.rules) > 0+ # All rules already installed — distinct from "couldn't install" because+ # nothing was unresolvable.+ assert len(second.rules) == 0+ assert second.unresolved == 0+++async def test_install_rule_pack_works_across_languages(session: AsyncSession, test_user):+ # Regression for #154: user registers in English, switches UI to pt-BR,+ # then installs the BR pack. Categories ("Transport") and template+ # language ("pt-BR" → "Transporte") would mismatch — install should+ # still resolve the category by internal key.+ await create_default_categories(session, test_user.id, lang="en")++ result = await install_rule_pack(session, test_user.id, "BR", lang="pt-BR")++ # Every BR rule's set_category action should have resolved to a real+ # English category UUID, so the pack installs in full.+ assert len(result.rules) == len(RULE_PACKS["BR"]["rules"])+ assert result.unresolved == 0+++async def test_install_rule_pack_reports_unresolved_when_categories_missing(+ session: AsyncSession, test_user+):+ # User in a degenerate state with no default categories — every pack+ # rule's set_category target is missing, so the install can't actually+ # write any rules. The result must surface this so the frontend can+ # tell the user "missing categories" instead of the misleading+ # "pack already installed" toast.+ result = await install_rule_pack(session, test_user.id, "BR", lang="pt-BR")++ assert len(result.rules) == 0+ assert result.unresolved == len(RULE_PACKS["BR"]["rules"])+++async def test_install_rule_pack_creates_missing_categories_when_opted_in(+ session: AsyncSession, test_user+):+ # Same degenerate user, but they tick the "create missing categories"+ # checkbox in the modal. Pack must seed the categories it needs and+ # then install the full rule set.+ result = await install_rule_pack(+ session,+ test_user.id,+ "BR",+ lang="pt-BR",+ create_missing_categories=True,+ )++ assert len(result.rules) == len(RULE_PACKS["BR"]["rules"])+ assert result.unresolved == 0+ assert result.categories_created > 0@pytest.mark.asyncioasync def test_install_rule_pack_unknown_returns_empty(session: AsyncSession, test_user):result = await install_rule_pack(session, test_user.id, "ZZ")- assert result == []+ assert result.rules == []+ assert result.unresolved == 0@pytest.mark.asynciodiff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.tsindex 0e86068e..384d1c3b 100644--- a/frontend/src/lib/api.ts+++ b/frontend/src/lib/api.ts@@ -631,8 +631,13 @@ export const rules = {const { data } = await api.get('/rules/packs')return data},- installPack: async (packCode: string): Promise<{ installed: number }> => {- const { data } = await api.post(`/rules/packs/${packCode}/install`)+ installPack: async (+ packCode: string,+ createMissingCategories = false,+ ): Promise<{ installed: number; unresolved: number; categories_created: number }> => {+ const { data } = await api.post(`/rules/packs/${packCode}/install`, null, {+ params: { create_missing_categories: createMissingCategories },+ })return data},}diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.jsonindex 64e196ba..670f0354 100644--- a/frontend/src/locales/en.json+++ b/frontend/src/locales/en.json@@ -512,6 +512,9 @@"packInstalled": "{{count}} rules installed","installed": "Installed","packAlreadyInstalled": "Pack already installed",+ "packMissingCategories": "This pack needs default categories you don't have. Enable \"Create missing categories\" and try again.",+ "packInstalledWithCategories": "{{rules}} rules installed and {{categories}} categories created",+ "createMissingCategories": "Also create default categories the pack needs","duplicateName": "A rule with this name already exists","sectionTitle": "Categorization Rules","reapplyAll": "Reapply all",diff --git a/frontend/src/locales/pt-BR.json b/frontend/src/locales/pt-BR.jsonindex ea73425f..6f7d8fcd 100644--- a/frontend/src/locales/pt-BR.json+++ b/frontend/src/locales/pt-BR.json@@ -512,6 +512,9 @@"packInstalled": "{{count}} regras instaladas","installed": "Instalado","packAlreadyInstalled": "Pacote já instalado",+ "packMissingCategories": "Este pacote precisa de categorias padrão que você não tem. Marque \"Criar categorias ausentes\" e tente novamente.",+ "packInstalledWithCategories": "{{rules}} regras instaladas e {{categories}} categorias criadas",+ "createMissingCategories": "Criar também as categorias padrão que o pacote precisa","duplicateName": "Já existe uma regra com este nome","sectionTitle": "Regras de Categorização","reapplyAll": "Reaplicar todas",diff --git a/frontend/src/pages/rules.tsx b/frontend/src/pages/rules.tsxindex c8ddc563..569b0d1a 100644--- a/frontend/src/pages/rules.tsx+++ b/frontend/src/pages/rules.tsx@@ -348,6 +348,7 @@ export default function RulesPage() {function RulePacksDialog({ open, onClose }: { open: boolean; onClose: () => void }) {const { t } = useTranslation()const queryClient = useQueryClient()+ const [createMissingCategories, setCreateMissingCategories] = useState(true)const { data: rulePacks } = useQuery({queryKey: ['rule-packs'],@@ -356,12 +357,26 @@ function RulePacksDialog({ open, onClose }: { open: boolean; onClose: () => void})const installPackMutation = useMutation({- mutationFn: (code: string) => rulesApi.installPack(code),+ mutationFn: (code: string) => rulesApi.installPack(code, createMissingCategories),onSuccess: (data) => {queryClient.invalidateQueries({ queryKey: ['rules'] })queryClient.invalidateQueries({ queryKey: ['rule-packs'] })+ if (data.categories_created > 0) {+ queryClient.invalidateQueries({ queryKey: ['categories'] })+ }if (data.installed === 0) {- toast.info(t('rules.packAlreadyInstalled'))+ if (data.unresolved > 0) {+ toast.error(t('rules.packMissingCategories'))+ } else {+ toast.info(t('rules.packAlreadyInstalled'))+ }+ } else if (data.categories_created > 0) {+ toast.success(+ t('rules.packInstalledWithCategories', {+ rules: data.installed,+ categories: data.categories_created,+ }),+ )} else {toast.success(t('rules.packInstalled', { count: data.installed }))}@@ -375,6 +390,21 @@ function RulePacksDialog({ open, onClose }: { open: boolean; onClose: () => void<DialogHeader><DialogTitle>{t('rules.packs')}</DialogTitle></DialogHeader>+ <div className="flex items-center gap-2 px-1">+ <input+ type="checkbox"+ id="create-missing-categories"+ checked={createMissingCategories}+ onChange={(e) => setCreateMissingCategories(e.target.checked)}+ className="rounded border-border text-primary focus:ring-primary"+ />+ <Label+ htmlFor="create-missing-categories"+ className="text-xs text-muted-foreground cursor-pointer"+ >+ {t('rules.createMissingCategories')}+ </Label>+ </div><div className="space-y-2">{rulePacks?.map((pack) => (<div