Open-source personal finance manager. Self-hosted, privacy-first.
Fix/125 bank sync categories (#135)
Tássio Noronha498f9ac871a8
diff --git a/backend/app/api/admin.py b/backend/app/api/admin.pyindex b6f6c934..6e488d52 100644--- a/backend/app/api/admin.py+++ b/backend/app/api/admin.py@@ -18,7 +18,11 @@ from app.services import admin_servicerouter = APIRouter(prefix="/api/admin", tags=["admin"])-ALLOWED_SETTINGS = {"registration_enabled", "credit_card_accounting_mode"}+ALLOWED_SETTINGS = {+ "registration_enabled",+ "credit_card_accounting_mode",+ "use_provider_categories",+}@router.get("/users", response_model=AdminUserList)@@ -119,6 +123,7 @@ async def update_setting(SETTING_VALIDATORS = {"registration_enabled": {"true", "false"},"credit_card_accounting_mode": {"cash", "accrual"},+ "use_provider_categories": {"true", "false"},}if key in SETTING_VALIDATORS and data.value not in SETTING_VALIDATORS[key]:raise HTTPException(diff --git a/backend/app/services/admin_service.py b/backend/app/services/admin_service.pyindex 56bae6dc..b33e1078 100644--- a/backend/app/services/admin_service.py+++ b/backend/app/services/admin_service.py@@ -221,3 +221,17 @@ async def get_credit_card_accounting_mode(session: AsyncSession) -> str:if setting and setting.value in ("cash", "accrual"):return setting.valuereturn "cash"+++async def use_provider_categories(session: AsyncSession) -> bool:+ """Whether sync should map provider-supplied categories (e.g. Pluggy's+ `category` field) onto the user's seeded categories via PLUGGY_CATEGORY_MAP.++ Global app setting — affects every connection's sync. Defaults to True+ (preserves current behavior). Admins can flip it off when the provider's+ classification is consistently wrong and they'd rather have everything+ arrive uncategorized so user-defined Rules are the only source of truth."""+ setting = await get_app_setting(session, "use_provider_categories")+ if setting:+ return setting.value.lower() == "true"+ return Truediff --git a/backend/app/services/connection_service.py b/backend/app/services/connection_service.pyindex cdf2e71e..73809d86 100644--- a/backend/app/services/connection_service.py+++ b/backend/app/services/connection_service.py@@ -18,6 +18,7 @@ from app.models.transaction import Transactionfrom app.models.user import Userfrom app.providers import get_providerfrom app.providers.base import HoldingData+from app.services import admin_servicefrom app.services.account_service import sync_opening_balance_for_connected_accountfrom app.services.asset_group_service import ensure_group_for_connectionfrom app.services.credit_card_service import apply_effective_date@@ -299,9 +300,16 @@ async def _upsert_asset_value_for_today(async def _match_pluggy_category(- session: AsyncSession, user_id: uuid.UUID, pluggy_category: Optional[str]+ session: AsyncSession,+ user_id: uuid.UUID,+ pluggy_category: Optional[str],+ enabled: bool = True,) -> Optional[uuid.UUID]:- if not pluggy_category:+ # `enabled` is the resolved value of the global `use_provider_categories`+ # admin setting. Off = sync skips the provider->user category mapping+ # entirely so transactions arrive uncategorized and Rules are the only+ # source of truth. Default keeps the historical behavior.+ if not enabled or not pluggy_category:return None# Try exact match first, then prefix before " - " (e.g. "Transfer - PIX" → "Transfer")app_name = PLUGGY_CATEGORY_MAP.get(pluggy_category)@@ -392,6 +400,8 @@ async def handle_oauth_callback(user_currency = user.primary_currency if user else get_settings().default_currencynew_tx_ids: list[uuid.UUID] = []+ use_provider_cats = await admin_service.use_provider_categories(session)+for acc_data in connection_data.accounts:is_cc = acc_data.type == "credit_card"account = Account(@@ -418,7 +428,7 @@ async def handle_oauth_callback()for txn_data in transactions_data:category_id = await _match_pluggy_category(- session, user_id, txn_data.pluggy_category+ session, user_id, txn_data.pluggy_category, enabled=use_provider_cats)# Resolve payee entity from raw payee textpayee_id = None@@ -603,6 +613,7 @@ async def sync_connection(conn_settings = connection.settings or {}payee_source = conn_settings.get("payee_source", "auto")import_pending = conn_settings.get("import_pending", True)+ use_provider_cats = await admin_service.use_provider_categories(session)try:provider = get_provider(connection.provider)@@ -719,7 +730,7 @@ async def sync_connection(continuecategory_id = await _match_pluggy_category(- session, user_id, txn_data.pluggy_category+ session, user_id, txn_data.pluggy_category, enabled=use_provider_cats)# Resolve payee entity from raw payee textdiff --git a/backend/tests/test_admin_api.py b/backend/tests/test_admin_api.pyindex d7eb7f9e..58bf291a 100644--- a/backend/tests/test_admin_api.py+++ b/backend/tests/test_admin_api.py@@ -348,3 +348,92 @@ class TestRegistrationToggle:)assert response.status_code == 400assert "invalid value" in response.json()["detail"].lower()+++class TestUseProviderCategoriesToggle:+ """Admin-scope toggle that controls whether sync auto-maps provider+ (e.g. Pluggy) categories onto the user's seeded categories. Default is+ on; flipping off makes synced transactions arrive uncategorized so user+ Rules are the only source of truth."""++ async def test_get_unset_returns_404(+ self, client: AsyncClient, admin_auth_headers: dict, test_superuser: User+ ):+ # Defaults are not seeded as DB rows — they're returned by the helper.+ # The raw GET /settings/{key} endpoint reflects DB state so an unset+ # key is a 404. The frontend handles this and falls back to "true".+ response = await client.get(+ "/api/admin/settings/use_provider_categories", headers=admin_auth_headers+ )+ assert response.status_code == 404++ async def test_patch_to_false_persists(+ self, client: AsyncClient, admin_auth_headers: dict, test_superuser: User+ ):+ response = await client.patch(+ "/api/admin/settings/use_provider_categories",+ json={"value": "false"},+ headers=admin_auth_headers,+ )+ assert response.status_code == 200+ assert response.json()["key"] == "use_provider_categories"+ assert response.json()["value"] == "false"++ # Round-trip+ get_resp = await client.get(+ "/api/admin/settings/use_provider_categories", headers=admin_auth_headers+ )+ assert get_resp.status_code == 200+ assert get_resp.json()["value"] == "false"++ async def test_patch_invalid_value_rejected(+ self, client: AsyncClient, admin_auth_headers: dict, test_superuser: User+ ):+ response = await client.patch(+ "/api/admin/settings/use_provider_categories",+ json={"value": "maybe"},+ headers=admin_auth_headers,+ )+ assert response.status_code == 400+ # Allowed values appear in the error message so callers can self-correct+ body = response.json()["detail"].lower()+ assert "true" in body and "false" in body++ async def test_patch_back_to_true(+ self, client: AsyncClient, admin_auth_headers: dict, test_superuser: User+ ):+ # Disable first, then re-enable+ await client.patch(+ "/api/admin/settings/use_provider_categories",+ json={"value": "false"},+ headers=admin_auth_headers,+ )+ response = await client.patch(+ "/api/admin/settings/use_provider_categories",+ json={"value": "true"},+ headers=admin_auth_headers,+ )+ assert response.status_code == 200+ assert response.json()["value"] == "true"++ async def test_non_admin_cannot_read(+ self, client: AsyncClient, auth_headers: dict, test_user: User, session: AsyncSession+ ):+ # Seed so a 200 would be possible if RBAC were broken+ setting = AppSetting(key="use_provider_categories", value="true")+ await session.merge(setting)+ await session.commit()+ response = await client.get(+ "/api/admin/settings/use_provider_categories", headers=auth_headers+ )+ assert response.status_code == 403++ async def test_non_admin_cannot_write(+ self, client: AsyncClient, auth_headers: dict, test_user: User+ ):+ response = await client.patch(+ "/api/admin/settings/use_provider_categories",+ json={"value": "false"},+ headers=auth_headers,+ )+ assert response.status_code == 403diff --git a/backend/tests/test_admin_service.py b/backend/tests/test_admin_service.pyindex 382b20e7..87b92ccc 100644--- a/backend/tests/test_admin_service.py+++ b/backend/tests/test_admin_service.py@@ -27,6 +27,7 @@ from app.services.admin_service import (list_users,set_app_setting,update_user,+ use_provider_categories,)from app.schemas.admin import AdminUserUpdate@@ -359,3 +360,41 @@ async def test_is_registration_enabled_fallback_to_env(session: AsyncSession, clresult = await is_registration_enabled(session)# Should not raise; returns the env defaultassert isinstance(result, bool)+++# ---------------------------------------------------------------------------+# use_provider_categories+# ---------------------------------------------------------------------------+++async def test_use_provider_categories_default_true(session: AsyncSession, clean_db):+ """Unset = on, so existing installs keep the historical sync behavior."""+ assert await use_provider_categories(session) is True+++async def test_use_provider_categories_explicit_false(session: AsyncSession, clean_db):+ await set_app_setting(session, "use_provider_categories", "false")+ assert await use_provider_categories(session) is False+++async def test_use_provider_categories_explicit_true(session: AsyncSession, clean_db):+ await set_app_setting(session, "use_provider_categories", "true")+ assert await use_provider_categories(session) is True+++async def test_use_provider_categories_case_insensitive(session: AsyncSession, clean_db):+ """Tolerate 'TRUE'/'False' in case the value is set via DB tooling."""+ await set_app_setting(session, "use_provider_categories", "TRUE")+ assert await use_provider_categories(session) is True+ await set_app_setting(session, "use_provider_categories", "False")+ assert await use_provider_categories(session) is False+++async def test_use_provider_categories_unknown_value_falls_back_to_false(+ session: AsyncSession, clean_db,+):+ """Defensive: anything not 'true' (case-insensitive) is treated as off.+ Prevents a stray 'maybe' / '1' from quietly turning provider mapping back+ on when the admin meant to disable it."""+ await set_app_setting(session, "use_provider_categories", "maybe")+ assert await use_provider_categories(session) is Falsediff --git a/backend/tests/test_connection_service.py b/backend/tests/test_connection_service.pyindex aad386b8..f5c61329 100644--- a/backend/tests/test_connection_service.py+++ b/backend/tests/test_connection_service.py@@ -129,6 +129,26 @@ async def test_match_pluggy_none(session: AsyncSession, test_user):assert cat_id is None+async def test_match_pluggy_disabled_short_circuits(session: AsyncSession, test_user):+ """When the global use_provider_categories flag is off, the matcher returns+ None even on inputs that would otherwise resolve. This is the contract+ sync_connection / handle_oauth_callback rely on to leave transactions+ uncategorized so user Rules are the only source of truth."""+ await _make_category(session, test_user.id, "Alimentação")+ # Sanity: enabled=True still matches.+ enabled_match = await _match_pluggy_category(+ session, test_user.id, "Eating out", enabled=True+ )+ assert enabled_match is not None++ # enabled=False short-circuits before any DB lookup.+ disabled_match = await _match_pluggy_category(+ session, test_user.id, "Eating out", enabled=False+ )+ assert disabled_match is None++@pytest.mark.asyncioasync def test_match_pluggy_user_has_no_category(session: AsyncSession, test_user):"""Pluggy category maps but user doesn't have the target category."""diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.jsonindex ad6ae726..114ac386 100644--- a/frontend/src/locales/en.json+++ b/frontend/src/locales/en.json@@ -879,6 +879,9 @@"accountingCashDesc": "Credit card purchases count on the day they happen (default).","accountingAccrual": "Accrual basis","accountingAccrualDesc": "Credit card purchases count on the bill's due date — reflects actual cash flow.",+ "providerCategoriesTitle": "Categories",+ "providerCategories": "Use integration categories",+ "providerCategoriesDesc": "When off, synced transactions arrive uncategorized so only your Rules apply.","updated": "Setting updated"}},diff --git a/frontend/src/locales/pt-BR.json b/frontend/src/locales/pt-BR.jsonindex a362f316..e2c6512d 100644--- a/frontend/src/locales/pt-BR.json+++ b/frontend/src/locales/pt-BR.json@@ -879,6 +879,9 @@"accountingCashDesc": "Compras no cartão contam no dia em que acontecem (padrão).","accountingAccrual": "Regime de competência","accountingAccrualDesc": "Compras no cartão contam na data de vencimento da fatura — reflete o fluxo de caixa real.",+ "providerCategoriesTitle": "Categorias",+ "providerCategories": "Usar categorias da integração",+ "providerCategoriesDesc": "Quando desativado, as transações sincronizadas chegam sem categoria, apenas suas Regras se aplicam.","updated": "Configuração atualizada"}},diff --git a/frontend/src/pages/admin/settings.tsx b/frontend/src/pages/admin/settings.tsxindex f0c88e5d..e1bad5d8 100644--- a/frontend/src/pages/admin/settings.tsx+++ b/frontend/src/pages/admin/settings.tsx@@ -19,7 +19,7 @@ import {DialogDescription,} from '@/components/ui/dialog'import { PageHeader } from '@/components/page-header'-import { Search, Plus, Trash2, Shield, ShieldOff, UserCog, Users, Scale } from 'lucide-react'+import { Search, Plus, Trash2, Shield, ShieldOff, UserCog, Users, Scale, Tag } from 'lucide-react'import type { AdminUser } from '@/types'export default function AdminSettingsPage() {@@ -124,6 +124,27 @@ export default function AdminSettingsPage() {const accountingMode = (ccModeSetting?.value === 'accrual' ? 'accrual' : 'cash') as 'cash' | 'accrual'+ // Provider categories: returns 404 when unset → defaults to "true" so+ // existing installs keep the historical sync behavior.+ const { data: providerCatsSetting } = useQuery({+ queryKey: ['admin', 'settings', 'use_provider_categories'],+ queryFn: () => adminApi.getSetting('use_provider_categories').catch(() => null),+ retry: false,+ })++ const updateProviderCatsMutation = useMutation({+ mutationFn: (value: string) => adminApi.updateSetting('use_provider_categories', value),+ onSuccess: () => {+ queryClient.invalidateQueries({ queryKey: ['admin', 'settings', 'use_provider_categories'] })+ toast.success(t('admin.settings.updated'))+ },+ onError: () => {+ toast.error(t('common.error'))+ },+ })++ const useProviderCats = providerCatsSetting?.value !== 'false'+function resetCreateForm() {setFormEmail('')setFormPassword('')@@ -276,6 +297,31 @@ export default function AdminSettingsPage() {</div></div>+ {/* Provider categories toggle */}+ <div className="rounded-xl border border-border/60 bg-card overflow-hidden mb-8">+ <div className="px-5 py-4 border-b border-border/40">+ <div className="flex items-center gap-2 mb-0.5">+ <Tag size={15} className="text-muted-foreground" />+ <h3 className="text-sm font-semibold text-foreground">{t('admin.settings.providerCategoriesTitle')}</h3>+ </div>+ </div>+ <div className="px-5 py-4 flex items-center justify-between">+ <div>+ <p className="text-sm text-foreground">{t('admin.settings.providerCategories')}</p>+ <p className="text-xs text-muted-foreground mt-0.5">{t('admin.settings.providerCategoriesDesc')}</p>+ </div>+ <button+ onClick={() => updateProviderCatsMutation.mutate(useProviderCats ? 'false' : 'true')}+ disabled={updateProviderCatsMutation.isPending}+ className={`relative inline-flex h-6 w-11 shrink-0 items-center rounded-full transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring ${useProviderCats ? 'bg-primary' : 'bg-muted-foreground/20'}`}+ >+ <span+ className={`pointer-events-none inline-block h-4 w-4 rounded-full bg-white shadow-sm transition-transform ${useProviderCats ? 'translate-x-6' : 'translate-x-1'}`}+ />+ </button>+ </div>+ </div>+{/* Settings section */}<div className="rounded-xl border border-border/60 bg-card overflow-hidden"><div className="px-5 py-4 border-b border-border/40">