Skip to content

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.py
index 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.py
index 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 user
diff --git a/backend/app/services/rule_service.py b/backend/app/services/rule_service.py
index 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 = 0
for rule_data in templates:
actions = []
+ dropped_for_missing_category = False
for 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 = True
continue
actions.append({"op": "set_category", "value": cat_id})
else:
actions.append(action)
if not actions:
+ if dropped_for_missing_category:
+ unresolved += 1
continue
resolved.append({**rule_data, "actions": actions})
- return resolved
+ return resolved, unresolved
async 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_code
rules.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.py
index 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 True
assert 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 first
await client.post(
diff --git a/backend/tests/test_rule_service.py b/backend/tests/test_rule_service.py
index 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 Transaction
from app.schemas.rule import RuleAction, RuleCondition, RuleCreate, RuleUpdate
from 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_us
first = 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.asyncio
async 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.asyncio
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 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.json
index 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.json
index 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.tsx
index 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