Open-source personal finance manager. Self-hosted, privacy-first.
fix: scope payee name uniqueness to the workspace (#616) (#629)
Tássio Noronha87d4d340200e
diff --git a/backend/alembic/versions/072_payee_unique_per_workspace.py b/backend/alembic/versions/072_payee_unique_per_workspace.pynew file mode 100644index 00000000..40eb68f3--- /dev/null+++ b/backend/alembic/versions/072_payee_unique_per_workspace.py@@ -0,0 +1,126 @@+"""scope the payee name uniqueness to the workspace instead of the user++Revision ID: 072+Revises: 071+Create Date: 2026-08-19++`uq_payees_user_id_name` was created in 019, back when a payee belonged to+a user. Migration 052 moved payees onto workspaces and the query layer+followed, but the constraint stayed user-scoped, so the database kept+enforcing a rule the application no longer believes in: one name per user,+across every workspace they touch.++The visible symptom is a bank connection failing with a duplicate key+error. Sync resolves a counterparty with a workspace-scoped lookup, finds+nothing in *this* workspace, inserts, and collides with a row the same+person created in a different one — commonly a counterparty they already+have in their personal workspace and now meet again in a shared one, or a+leftover from a connection that was removed earlier.++Existing rows can violate the new constraint where two members of one+workspace each created the same name (the old constraint allowed it,+because their user ids differ), so duplicates are merged into the oldest+row before the constraint goes on.+"""++from typing import Sequence, Union++import sqlalchemy as sa+from alembic import op++revision: str = "072"+down_revision: Union[str, None] = "071"+branch_labels: Union[str, Sequence[str], None] = None+depends_on: Union[str, Sequence[str], None] = None+++# The oldest row of each (workspace_id, name) group wins; every other row+# in the group is a duplicate that has to be folded into it.+DUPLICATES = """+ SELECT+ p.id AS dup_id,+ first_value(p.id) OVER (+ PARTITION BY p.workspace_id, p.name+ ORDER BY p.created_at, p.id+ ) AS keeper_id+ FROM payees p+"""+++def _constraint_exists(name: str) -> bool:+ return bool(+ op.get_bind()+ .execute(+ sa.text(+ "SELECT 1 FROM information_schema.table_constraints "+ "WHERE table_name = 'payees' AND constraint_name = :name"+ ),+ {"name": name},+ )+ .scalar()+ )+++def upgrade() -> None:+ # Transactions and merge mappings follow the keeper.+ op.execute(+ f"""+ UPDATE transactions t+ SET payee_id = d.keeper_id+ FROM ({DUPLICATES}) d+ WHERE t.payee_id = d.dup_id AND d.dup_id <> d.keeper_id+ """+ )+ op.execute(+ f"""+ UPDATE payee_mapping m+ SET target_id = d.keeper_id+ FROM ({DUPLICATES}) d+ WHERE m.target_id = d.dup_id AND d.dup_id <> d.keeper_id+ """+ )+ # Fiscal documents would cascade away with the duplicate row, so move+ # the ones the keeper has no answer for. A kind the keeper already+ # carries is left behind: two CNPJs on one counterparty is not+ # something a migration should pick a winner for.+ op.execute(+ f"""+ UPDATE payee_tax_ids ti+ SET payee_id = d.keeper_id+ FROM ({DUPLICATES}) d+ WHERE ti.payee_id = d.dup_id+ AND d.dup_id <> d.keeper_id+ AND NOT EXISTS (+ SELECT 1 FROM payee_tax_ids keep+ WHERE keep.payee_id = d.keeper_id AND keep.kind = ti.kind+ )+ """+ )+ op.execute(+ f"""+ DELETE FROM payees p+ USING ({DUPLICATES}) d+ WHERE p.id = d.dup_id AND d.dup_id <> d.keeper_id+ """+ )++ if _constraint_exists("uq_payees_user_id_name"):+ op.drop_constraint("uq_payees_user_id_name", "payees", type_="unique")+ op.create_unique_constraint(+ "uq_payees_workspace_id_name", "payees", ["workspace_id", "name"]+ )+++def downgrade() -> None:+ # Going back cannot recreate the user-scoped constraint unconditionally:+ # the rows this migration made legal are exactly the ones it forbade.+ op.drop_constraint("uq_payees_workspace_id_name", "payees", type_="unique")+ duplicated_per_user = op.get_bind().execute(+ sa.text(+ "SELECT 1 FROM payees GROUP BY user_id, name HAVING count(*) > 1 LIMIT 1"+ )+ ).scalar()+ if not duplicated_per_user:+ op.create_unique_constraint(+ "uq_payees_user_id_name", "payees", ["user_id", "name"]+ )diff --git a/backend/app/models/payee.py b/backend/app/models/payee.pyindex 911a5272..fa849c99 100644--- a/backend/app/models/payee.py+++ b/backend/app/models/payee.py@@ -15,6 +15,15 @@ if TYPE_CHECKING:class Payee(Base):__tablename__ = "payees"+ __table_args__ = (+ # Scoped to the workspace, not to the user. A payee belongs to a+ # workspace and every lookup in the service layer says so, so the+ # same counterparty legitimately exists once per workspace a person+ # is a member of. The user-scoped constraint this replaces made+ # that a duplicate key error, surfacing as a bank connection that+ # refuses to sync a name the user already has somewhere else.+ UniqueConstraint("workspace_id", "name", name="uq_payees_workspace_id_name"),+ )id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)user_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"))diff --git a/backend/tests/test_payee_workspace_scope.py b/backend/tests/test_payee_workspace_scope.pynew file mode 100644index 00000000..8a59bed2--- /dev/null+++ b/backend/tests/test_payee_workspace_scope.py@@ -0,0 +1,257 @@+"""A payee name is unique inside a workspace, not inside a user account.++Regression cover for #616. Payees moved onto workspaces in migration 052+and the service layer moved with them, but the database kept the unique+constraint written back when a payee belonged to a user+(`uq_payees_user_id_name`). Sync then looked for a counterparty in *this*+workspace, correctly found nothing, inserted, and hit a row the same+person owned in a *different* workspace. The bank connection failed with a+duplicate key error naming a counterparty the user could not see from+where they were standing.++The rule these tests pin: the same name may exist once per workspace, and+twice in one workspace it may not.+"""+import uuid+from datetime import date, datetime, timezone+from decimal import Decimal+from unittest.mock import AsyncMock, patch++import pytest+from sqlalchemy import UniqueConstraint, select+from sqlalchemy.exc import IntegrityError+from sqlalchemy.ext.asyncio import AsyncSession++from app.models.bank_connection import BankConnection+from app.models.payee import Payee+from app.models.workspace import Workspace, WorkspaceMember+from app.providers.base import AccountData, ConnectionData, TransactionData+from app.schemas.payee import PayeeCreate+from app.services.connection_service import handle_oauth_callback, sync_connection+from app.services.payee_service import create_payee, get_or_create_payee+++# A CPF-shaped name, because that is what the bank sends as the+# counterparty on a Pix transfer and what the reported failures collided on.+COUNTERPARTY = "12345678901"+++async def _second_workspace(session: AsyncSession, user_id: uuid.UUID) -> Workspace:+ """A second workspace the same user belongs to — a shared household+ workspace, or one they were added to. The single-workspace assumption+ is exactly what the old constraint encoded."""+ ws = Workspace(+ id=uuid.uuid4(), name="Shared", kind="personal",+ created_by_user_id=user_id, default_currency="BRL",+ )+ session.add(ws)+ await session.flush()+ session.add(+ WorkspaceMember(+ id=uuid.uuid4(), workspace_id=ws.id, user_id=user_id, role="owner",+ )+ )+ await session.commit()+ await session.refresh(ws)+ return ws+++# ---------------------------------------------------------------------------+# the constraint itself+# ---------------------------------------------------------------------------+def test_uniqueness_is_scoped_to_the_workspace():+ """Asserted on the model because the test database is built from it:+ a constraint that lives only in a migration is invisible here, which+ is how the user-scoped one survived the move to workspaces unnoticed."""+ scopes = {+ tuple(col.name for col in constraint.columns)+ for constraint in Payee.__table_args__+ if isinstance(constraint, UniqueConstraint)+ }+ assert ("workspace_id", "name") in scopes+ assert ("user_id", "name") not in scopes+++async def test_the_same_name_twice_in_one_workspace_is_rejected(+ session: AsyncSession, test_user, test_workspace+):+ """The half of the old rule that was right, and has to stay enforced by+ the database rather than only by the service's pre-check."""+ session.add(+ Payee(id=uuid.uuid4(), user_id=test_user.id,+ workspace_id=test_workspace.id, name=COUNTERPARTY)+ )+ await session.commit()++ session.add(+ Payee(id=uuid.uuid4(), user_id=test_user.id,+ workspace_id=test_workspace.id, name=COUNTERPARTY)+ )+ with pytest.raises(IntegrityError):+ await session.commit()+ await session.rollback()+++# ---------------------------------------------------------------------------+# the reported failure+# ---------------------------------------------------------------------------+async def test_same_counterparty_can_exist_in_two_workspaces(+ session: AsyncSession, test_user, test_workspace+):+ """One person, two workspaces, one counterparty they transact with from+ both. Two rows, because a payee belongs to a workspace."""+ other = await _second_workspace(session, test_user.id)++ first = await create_payee(+ session, test_workspace.id, test_user.id, PayeeCreate(name=COUNTERPARTY)+ )+ second = await create_payee(+ session, other.id, test_user.id, PayeeCreate(name=COUNTERPARTY)+ )++ assert first.id != second.id+ assert {first.workspace_id, second.workspace_id} == {test_workspace.id, other.id}+++async def test_sync_creates_the_counterparty_in_its_own_workspace(+ session: AsyncSession, test_user, test_workspace+):+ """`get_or_create_payee` is the bulk path sync uses, and the one that+ raised the duplicate key: it looks the name up in the workspace being+ synced, so a hit in another workspace must not stop the insert."""+ other = await _second_workspace(session, test_user.id)+ await create_payee(+ session, test_workspace.id, test_user.id, PayeeCreate(name=COUNTERPARTY)+ )++ synced = await get_or_create_payee(+ session, test_user.id, COUNTERPARTY, workspace_id=other.id+ )+ await session.commit()++ assert synced.workspace_id == other.id+ rows = await session.execute(select(Payee).where(Payee.name == COUNTERPARTY))+ assert len(rows.scalars().all()) == 2+++async def test_get_or_create_reuses_the_row_inside_one_workspace(+ session: AsyncSession, test_user, test_workspace+):+ """The other side of the same call: within a workspace it still returns+ the existing row instead of racing the constraint."""+ existing = await create_payee(+ session, test_workspace.id, test_user.id, PayeeCreate(name=COUNTERPARTY)+ )++ found = await get_or_create_payee(+ session, test_user.id, COUNTERPARTY.lower(), workspace_id=test_workspace.id+ )++ assert found.id == existing.id+++async def test_connecting_a_bank_succeeds_with_the_name_already_used_elsewhere(+ session: AsyncSession, test_user, test_workspace+):+ """The user's story end to end: a counterparty already recorded in the+ personal workspace, and a bank connected in the shared one whose+ transactions name the same counterparty. The sync used to abort with+ `duplicate key value violates unique constraint "uq_payees_user_id_name"`+ and the connection reported "fail to connect"."""+ other = await _second_workspace(session, test_user.id)+ await create_payee(+ session, test_workspace.id, test_user.id, PayeeCreate(name=COUNTERPARTY)+ )++ conn = BankConnection(+ id=uuid.uuid4(), user_id=test_user.id, workspace_id=other.id,+ provider="test", external_id=f"ext-{uuid.uuid4().hex[:8]}",+ institution_name="Banco do Brasil", credentials={"token": "fake"},+ status="active", last_sync_at=datetime.now(timezone.utc),+ created_at=datetime.now(timezone.utc),+ )+ session.add(conn)+ await session.commit()++ mock_provider = AsyncMock()+ mock_provider.refresh_credentials = AsyncMock(return_value={"token": "refreshed"})+ mock_provider.get_accounts = AsyncMock(return_value=[+ AccountData(+ external_id="bb-acc-1", name="Conta Corrente",+ type="checking", balance=Decimal("100"), currency="BRL",+ ),+ ])+ mock_provider.get_transactions = AsyncMock(return_value=[+ TransactionData(+ external_id="bb-tx-1", description="PIX ENVIADO",+ amount=Decimal("50"), date=date.today(), type="debit",+ currency="BRL", payee=COUNTERPARTY,+ ),+ ])++ with patch("app.services.connection_service.get_provider", return_value=mock_provider), \+ patch("app.services.connection_service.detect_transfer_pairs", new_callable=AsyncMock), \+ patch("app.services.connection_service.stamp_primary_amount", new_callable=AsyncMock), \+ patch("app.services.connection_service.apply_rules_to_transaction", new_callable=AsyncMock):+ result_conn, _ = await sync_connection(+ session, conn.id, other.id, test_user.id+ )++ assert result_conn.status == "active"+ synced = await session.scalar(+ select(Payee).where(Payee.workspace_id == other.id, Payee.name == COUNTERPARTY)+ )+ assert synced is not None+++async def test_connecting_the_bank_succeeds_on_the_callback_itself(+ session: AsyncSession, test_user, test_workspace+):+ """The endpoint the report died on: `POST /api/connections/oauth/callback`+ imports the first batch of transactions inline, so the connection is+ what fails, not a later sync. Same counterparty, already recorded in+ another workspace."""+ other = await _second_workspace(session, test_user.id)+ await create_payee(+ session, test_workspace.id, test_user.id, PayeeCreate(name=COUNTERPARTY)+ )++ mock_provider = AsyncMock()+ mock_provider.handle_oauth_callback = AsyncMock(return_value=ConnectionData(+ external_id="ext-bb",+ institution_name="Banco do Brasil",+ credentials={"token": "x"},+ accounts=[+ AccountData(+ external_id="bb-acc-1", name="Conta Corrente",+ type="checking", balance=Decimal("100"), currency="BRL",+ ),+ ],+ ))+ mock_provider.get_transactions = AsyncMock(return_value=[+ TransactionData(+ external_id="bb-tx-1", description="PIX ENVIADO",+ amount=Decimal("50"), date=date.today(), type="debit",+ currency="BRL", payee=COUNTERPARTY,+ ),+ ])++ with patch("app.services.connection_service.get_provider", return_value=mock_provider), \+ patch("app.services.connection_service.detect_transfer_pairs", new_callable=AsyncMock), \+ patch("app.services.connection_service.stamp_primary_amount", new_callable=AsyncMock), \+ patch("app.services.connection_service.apply_rules_to_transaction", new_callable=AsyncMock):+ connection = await handle_oauth_callback(+ session, other.id, test_user.id, "code", "pluggy", sync_assets=False,+ )++ assert connection is not None+ synced = await session.scalar(+ select(Payee).where(Payee.workspace_id == other.id, Payee.name == COUNTERPARTY)+ )+ assert synced is not None