Skip to content

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.py
new file mode 100644
index 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.py
index 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.py
new file mode 100644
index 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