Skip to content

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.py
index b6f6c934..6e488d52 100644
--- a/backend/app/api/admin.py
+++ b/backend/app/api/admin.py
@@ -18,7 +18,11 @@ from app.services import admin_service
router = 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.py
index 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.value
return "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 True
diff --git a/backend/app/services/connection_service.py b/backend/app/services/connection_service.py
index 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 Transaction
from app.models.user import User
from app.providers import get_provider
from app.providers.base import HoldingData
+from app.services import admin_service
from app.services.account_service import sync_opening_balance_for_connected_account
from app.services.asset_group_service import ensure_group_for_connection
from 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_currency
new_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 text
payee_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(
continue
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 text
diff --git a/backend/tests/test_admin_api.py b/backend/tests/test_admin_api.py
index 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 == 400
assert "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 == 403
diff --git a/backend/tests/test_admin_service.py b/backend/tests/test_admin_service.py
index 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, cl
result = await is_registration_enabled(session)
# Should not raise; returns the env default
assert 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 False
diff --git a/backend/tests/test_connection_service.py b/backend/tests/test_connection_service.py
index 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.asyncio
async 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.json
index 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.json
index 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.tsx
index 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">