Open-source personal finance manager. Self-hosted, privacy-first.
feat: add payee/entity tracking (#50)
Tássio Noronha03c2894d1013
diff --git a/backend/alembic/versions/019_payees.py b/backend/alembic/versions/019_payees.pynew file mode 100644index 00000000..122fb5f8--- /dev/null+++ b/backend/alembic/versions/019_payees.py@@ -0,0 +1,66 @@+"""add payees and payee_mapping tables, add payee_id to transactions++Revision ID: 019+Revises: 018+Create Date: 2026-04-01+"""++from typing import Sequence, Union++import sqlalchemy as sa+from alembic import op+from sqlalchemy.dialects.postgresql import UUID++revision: str = "019"+down_revision: Union[str, None] = "018"+branch_labels: Union[str, Sequence[str], None] = None+depends_on: Union[str, Sequence[str], None] = None+++def upgrade() -> None:+ # Create payees table+ op.create_table(+ "payees",+ sa.Column("id", UUID(as_uuid=True), primary_key=True),+ sa.Column("user_id", UUID(as_uuid=True), sa.ForeignKey("users.id"), nullable=False),+ sa.Column("name", sa.String(255), nullable=False),+ sa.Column("type", sa.String(20), server_default="merchant", nullable=False),+ sa.Column("is_favorite", sa.Boolean, server_default=sa.text("false"), nullable=False),+ sa.Column("notes", sa.String(1000), nullable=True),+ sa.Column(+ "created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False+ ),+ )+ op.create_index("ix_payees_user_id", "payees", ["user_id"])+ op.create_unique_constraint("uq_payees_user_id_name", "payees", ["user_id", "name"])++ # Create payee_mapping table (for merge/dedup)+ op.create_table(+ "payee_mapping",+ sa.Column("id", UUID(as_uuid=True), primary_key=True),+ sa.Column("user_id", UUID(as_uuid=True), sa.ForeignKey("users.id"), nullable=False),+ sa.Column(+ "target_id",+ UUID(as_uuid=True),+ sa.ForeignKey("payees.id", ondelete="CASCADE"),+ nullable=False,+ ),+ )+ op.create_index("ix_payee_mapping_user_id_target_id", "payee_mapping", ["user_id", "target_id"])++ # Add payee_id FK to transactions+ op.add_column(+ "transactions",+ sa.Column("payee_id", UUID(as_uuid=True), sa.ForeignKey("payees.id", ondelete="SET NULL"), nullable=True),+ )+ op.create_index("ix_transactions_payee_id", "transactions", ["payee_id"])+++def downgrade() -> None:+ op.drop_index("ix_transactions_payee_id", table_name="transactions")+ op.drop_column("transactions", "payee_id")+ op.drop_index("ix_payee_mapping_user_id_target_id", table_name="payee_mapping")+ op.drop_table("payee_mapping")+ op.drop_constraint("uq_payees_user_id_name", "payees", type_="unique")+ op.drop_index("ix_payees_user_id", table_name="payees")+ op.drop_table("payees")diff --git a/backend/app/api/payees.py b/backend/app/api/payees.pynew file mode 100644index 00000000..1528873d--- /dev/null+++ b/backend/app/api/payees.py@@ -0,0 +1,109 @@+import uuid+from datetime import date+from typing import Optional++from fastapi import APIRouter, Depends, HTTPException, Query, status+from sqlalchemy.ext.asyncio import AsyncSession++from app.core.auth import current_active_user+from app.core.database import get_async_session+from app.models.user import User+from app.schemas.payee import PayeeCreate, PayeeMergeRequest, PayeeRead, PayeeSummary, PayeeUpdate+from app.schemas.category import CategoryRead+from app.services import payee_service++router = APIRouter(prefix="/api/payees", tags=["payees"])++[email protected]("", response_model=list[PayeeRead])+async def list_payees(+ session: AsyncSession = Depends(get_async_session),+ user: User = Depends(current_active_user),+):+ return await payee_service.get_payees(session, user.id)++[email protected]("/{payee_id}", response_model=PayeeRead)+async def get_payee(+ payee_id: uuid.UUID,+ session: AsyncSession = Depends(get_async_session),+ user: User = Depends(current_active_user),+):+ payee = await payee_service.get_payee(session, payee_id, user.id)+ if not payee:+ raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Payee not found")+ return payee++[email protected]("/{payee_id}/summary", response_model=PayeeSummary)+async def get_payee_summary(+ payee_id: uuid.UUID,+ start_date: Optional[date] = Query(None, alias="from"),+ end_date: Optional[date] = Query(None, alias="to"),+ session: AsyncSession = Depends(get_async_session),+ user: User = Depends(current_active_user),+):+ try:+ result = await payee_service.get_payee_summary(session, payee_id, user.id, start_date, end_date)+ return PayeeSummary(+ payee=PayeeRead.model_validate(result["payee"], from_attributes=True),+ total_spent=result["total_spent"],+ total_received=result["total_received"],+ transaction_count=result["transaction_count"],+ most_common_category=CategoryRead.model_validate(result["most_common_category"], from_attributes=True) if result["most_common_category"] else None,+ last_transaction_date=result["last_transaction_date"],+ )+ except ValueError as e:+ raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(e))++[email protected]("", response_model=PayeeRead, status_code=status.HTTP_201_CREATED)+async def create_payee(+ data: PayeeCreate,+ session: AsyncSession = Depends(get_async_session),+ user: User = Depends(current_active_user),+):+ try:+ return await payee_service.create_payee(session, user.id, data)+ except ValueError as e:+ raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))++[email protected]("/{payee_id}", response_model=PayeeRead)+async def update_payee(+ payee_id: uuid.UUID,+ data: PayeeUpdate,+ session: AsyncSession = Depends(get_async_session),+ user: User = Depends(current_active_user),+):+ try:+ payee = await payee_service.update_payee(session, payee_id, user.id, data)+ except ValueError as e:+ raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))+ if not payee:+ raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Payee not found")+ return payee++[email protected]("/{payee_id}", status_code=status.HTTP_204_NO_CONTENT)+async def delete_payee(+ payee_id: uuid.UUID,+ session: AsyncSession = Depends(get_async_session),+ user: User = Depends(current_active_user),+):+ deleted = await payee_service.delete_payee(session, payee_id, user.id)+ if not deleted:+ raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Payee not found")++[email protected]("/merge")+async def merge_payees(+ data: PayeeMergeRequest,+ session: AsyncSession = Depends(get_async_session),+ user: User = Depends(current_active_user),+):+ try:+ reassigned = await payee_service.merge_payees(session, user.id, data.target_id, data.source_ids)+ return {"merged": len(data.source_ids), "transactions_reassigned": reassigned}+ except ValueError as e:+ raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))diff --git a/backend/app/api/transactions.py b/backend/app/api/transactions.pyindex 23ddf56a..49d74287 100644--- a/backend/app/api/transactions.py+++ b/backend/app/api/transactions.py@@ -36,6 +36,7 @@ class PaginatedTransactions(BaseModel):async def list_transactions(account_id: Optional[uuid.UUID] = Query(None),category_id: Optional[uuid.UUID] = Query(None),+ payee_id: Optional[uuid.UUID] = Query(None),from_date: Optional[date] = Query(None, alias="from"),to_date: Optional[date] = Query(None, alias="to"),q: Optional[str] = Query(None),@@ -48,7 +49,7 @@ async def list_transactions(user: User = Depends(current_active_user),):transactions, total = await transaction_service.get_transactions(- session, user.id, account_id, category_id, from_date, to_date, page, limit,+ session, user.id, account_id, category_id, payee_id, from_date, to_date, page, limit,include_opening_balance, search=q, uncategorized=uncategorized, txn_type=type,)primary_currency = user.primary_currency@@ -60,6 +61,7 @@ async def list_transactions(async def export_transactions(account_id: Optional[uuid.UUID] = Query(None),category_id: Optional[uuid.UUID] = Query(None),+ payee_id: Optional[uuid.UUID] = Query(None),from_date: Optional[date] = Query(None, alias="from"),to_date: Optional[date] = Query(None, alias="to"),q: Optional[str] = Query(None),@@ -69,14 +71,14 @@ async def export_transactions(user: User = Depends(current_active_user),):transactions, _ = await transaction_service.get_transactions(- session, user.id, account_id, category_id, from_date, to_date,+ session, user.id, account_id, category_id, payee_id, from_date, to_date,search=q, uncategorized=uncategorized, txn_type=type, skip_pagination=True,)output = io.StringIO()output.write("\ufeff") # UTF-8 BOM for Excelwriter = csv.writer(output)- writer.writerow(["date", "description", "amount", "type", "currency", "category", "account", "payee", "notes", "status", "source", "amount_primary", "fx_rate_used"])+ writer.writerow(["date", "description", "amount", "type", "currency", "category", "account", "payee", "payee_name", "notes", "status", "source", "amount_primary", "fx_rate_used"])for tx in transactions:writer.writerow([tx.date.isoformat(),@@ -87,6 +89,7 @@ async def export_transactions(tx.category.name if tx.category else "",tx.account.name if tx.account else "",tx.payee or "",+ getattr(tx, "payee_name", "") or "",tx.notes or "",tx.status,tx.source,diff --git a/backend/app/main.py b/backend/app/main.pyindex 06a98148..1a03b25e 100644--- a/backend/app/main.py+++ b/backend/app/main.py@@ -21,6 +21,7 @@ from app.api.currencies import router as currencies_routerfrom app.api.export import router as export_routerfrom app.api.fx_rates import router as fx_rates_routerfrom app.api.attachments import router as attachments_router+from app.api.payees import router as payees_routerfrom app.api.settings import router as settings_routerfrom app.api.transactions import router as transactions_routerfrom app.core.auth import auth_backend, fastapi_users@@ -100,6 +101,7 @@ app.include_router(currencies_router)app.include_router(fx_rates_router)app.include_router(export_router)app.include_router(attachments_router)+app.include_router(payees_router)app.include_router(settings_router)diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.pyindex 0671c0fa..306da326 100644--- a/backend/app/models/__init__.py+++ b/backend/app/models/__init__.py@@ -12,6 +12,7 @@ from app.models.asset import Assetfrom app.models.asset_value import AssetValuefrom app.models.fx_rate import FxRatefrom app.models.transaction_attachment import TransactionAttachment+from app.models.payee import Payee, PayeeMapping__all__ = ["User",@@ -28,4 +29,6 @@ __all__ = ["AssetValue","FxRate","TransactionAttachment",+ "Payee",+ "PayeeMapping",]diff --git a/backend/app/models/payee.py b/backend/app/models/payee.pynew file mode 100644index 00000000..a585760c--- /dev/null+++ b/backend/app/models/payee.py@@ -0,0 +1,38 @@+import uuid+from datetime import datetime, timezone+from typing import TYPE_CHECKING, Optional++from sqlalchemy import Boolean, DateTime, ForeignKey, String+from sqlalchemy.dialects.postgresql import UUID+from sqlalchemy.orm import Mapped, mapped_column, relationship++from app.core.database import Base++if TYPE_CHECKING:+ from app.models.transaction import Transaction+ from app.models.user import User+++class Payee(Base):+ __tablename__ = "payees"++ 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"))+ name: Mapped[str] = mapped_column(String(255))+ type: Mapped[str] = mapped_column(String(20), default="merchant")+ is_favorite: Mapped[bool] = mapped_column(Boolean, default=False)+ notes: Mapped[Optional[str]] = mapped_column(String(1000), nullable=True)+ created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))++ user: Mapped["User"] = relationship()+ transactions: Mapped[list["Transaction"]] = relationship(back_populates="payee_entity")+++class PayeeMapping(Base):+ __tablename__ = "payee_mapping"++ 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"))+ target_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("payees.id", ondelete="CASCADE"))++ target: Mapped["Payee"] = relationship()diff --git a/backend/app/models/transaction.py b/backend/app/models/transaction.pyindex 3dc20d2c..fd38ad16 100644--- a/backend/app/models/transaction.py+++ b/backend/app/models/transaction.py@@ -13,6 +13,7 @@ if TYPE_CHECKING:from app.models.account import Accountfrom app.models.category import Categoryfrom app.models.import_log import ImportLog+ from app.models.payee import Payeefrom app.models.transaction_attachment import TransactionAttachment@@ -32,6 +33,7 @@ class Transaction(Base):source: Mapped[str] = mapped_column(String(20)) # sync, ofx, csv, manualstatus: Mapped[str] = mapped_column(String(10), default="posted") # posted, pendingpayee: Mapped[Optional[str]] = mapped_column(String(500), nullable=True)+ payee_id: Mapped[Optional[uuid.UUID]] = mapped_column(UUID(as_uuid=True), ForeignKey("payees.id", ondelete="SET NULL"), nullable=True)notes: Mapped[Optional[str]] = mapped_column(String(1000), nullable=True)raw_data: Mapped[Optional[dict]] = mapped_column(JSON, nullable=True)import_id: Mapped[Optional[uuid.UUID]] = mapped_column(UUID(as_uuid=True), ForeignKey("import_logs.id"), nullable=True)@@ -42,6 +44,7 @@ class Transaction(Base):account: Mapped["Account"] = relationship(back_populates="transactions")category: Mapped[Optional["Category"]] = relationship()+ payee_entity: Mapped[Optional["Payee"]] = relationship(back_populates="transactions")import_log: Mapped[Optional["ImportLog"]] = relationship(back_populates="transactions")attachments: Mapped[list["TransactionAttachment"]] = relationship(back_populates="transaction", cascade="all, delete-orphan"diff --git a/backend/app/schemas/payee.py b/backend/app/schemas/payee.pynew file mode 100644index 00000000..b170b842--- /dev/null+++ b/backend/app/schemas/payee.py@@ -0,0 +1,48 @@+import uuid+from datetime import date as _Date, datetime+from decimal import Decimal+from typing import Optional++from pydantic import BaseModel, ConfigDict++from app.schemas.category import CategoryRead+++class PayeeCreate(BaseModel):+ name: str+ type: str = "merchant"+ notes: Optional[str] = None+++class PayeeUpdate(BaseModel):+ name: Optional[str] = None+ type: Optional[str] = None+ is_favorite: Optional[bool] = None+ notes: Optional[str] = None+++class PayeeRead(BaseModel):+ id: uuid.UUID+ user_id: uuid.UUID+ name: str+ type: str+ is_favorite: bool+ notes: Optional[str] = None+ created_at: datetime+ transaction_count: int = 0++ model_config = ConfigDict(from_attributes=True)+++class PayeeSummary(BaseModel):+ payee: PayeeRead+ total_spent: Decimal = Decimal("0")+ total_received: Decimal = Decimal("0")+ transaction_count: int = 0+ most_common_category: Optional[CategoryRead] = None+ last_transaction_date: Optional[_Date] = None+++class PayeeMergeRequest(BaseModel):+ source_ids: list[uuid.UUID]+ target_id: uuid.UUIDdiff --git a/backend/app/schemas/transaction.py b/backend/app/schemas/transaction.pyindex 538339f0..65b550a8 100644--- a/backend/app/schemas/transaction.py+++ b/backend/app/schemas/transaction.py@@ -16,11 +16,13 @@ class TransactionBase(BaseModel):external_id: Optional[str] = Nonecurrency: Optional[str] = Nonefx_rate: Optional[Decimal] = None+ payee_raw: Optional[str] = None # raw payee string from import (OFX/QIF)class TransactionCreate(TransactionBase):account_id: uuid.UUIDcategory_id: Optional[uuid.UUID] = None+ payee_id: Optional[uuid.UUID] = Nonecurrency: Optional[str] = Nonenotes: Optional[str] = Noneamount_primary: Optional[Decimal] = None@@ -34,6 +36,7 @@ class TransactionUpdate(BaseModel):type: Optional[str] = Nonecurrency: Optional[str] = Nonecategory_id: Optional[uuid.UUID] = None+ payee_id: Optional[uuid.UUID] = Nonenotes: Optional[str] = Noneamount_primary: Optional[Decimal] = Nonefx_rate_used: Optional[Decimal] = None@@ -49,6 +52,8 @@ class TransactionRead(TransactionBase):source: strstatus: str = "posted"payee: Optional[str] = None+ payee_id: Optional[uuid.UUID] = None+ payee_name: Optional[str] = Nonenotes: Optional[str] = Nonetransfer_pair_id: Optional[uuid.UUID] = Noneamount_primary: Optional[float] = Nonediff --git a/backend/app/services/connection_service.py b/backend/app/services/connection_service.pyindex dd883d15..0077604e 100644--- a/backend/app/services/connection_service.py+++ b/backend/app/services/connection_service.py@@ -16,6 +16,7 @@ from app.providers import get_providerfrom app.services.rule_service import apply_rules_to_transactionfrom app.services.transfer_detection_service import detect_transfer_pairsfrom app.services.fx_rate_service import stamp_primary_amount+from app.services.payee_service import get_or_create_payeesettings = get_settings()@@ -160,6 +161,12 @@ async def handle_oauth_callback(category_id = await _match_pluggy_category(session, user_id, txn_data.pluggy_category)+ # Resolve payee entity from raw payee text+ payee_id = None+ if txn_data.payee:+ payee_entity = await get_or_create_payee(session, user_id, txn_data.payee)+ payee_id = payee_entity.id+transaction = Transaction(user_id=user_id,account_id=account.id,@@ -172,6 +179,7 @@ async def handle_oauth_callback(source="sync",status=txn_data.status,payee=txn_data.payee,+ payee_id=payee_id,raw_data=txn_data.raw_data,category_id=category_id,)@@ -340,6 +348,13 @@ async def sync_connection(category_id = await _match_pluggy_category(session, user_id, txn_data.pluggy_category)++ # Resolve payee entity from raw payee text+ sync_payee_id = None+ if txn_data.payee:+ sync_payee_entity = await get_or_create_payee(session, user_id, txn_data.payee)+ sync_payee_id = sync_payee_entity.id+transaction = Transaction(user_id=user_id,account_id=account.id,@@ -352,6 +367,7 @@ async def sync_connection(source="sync",status=txn_data.status,payee=txn_data.payee,+ payee_id=sync_payee_id,raw_data=txn_data.raw_data,category_id=category_id,)diff --git a/backend/app/services/import_service.py b/backend/app/services/import_service.pyindex 22e4c8ca..0588caf4 100644--- a/backend/app/services/import_service.py+++ b/backend/app/services/import_service.py@@ -16,6 +16,7 @@ from app.models.transaction import Transactionfrom app.schemas.transaction import TransactionBasefrom app.services.rule_service import apply_rules_to_transactionfrom app.services.fx_rate_service import stamp_primary_amount+from app.services.payee_service import get_or_create_payeedef parse_ofx(content: bytes) -> list[TransactionBase]:@@ -25,12 +26,14 @@ def parse_ofx(content: bytes) -> list[TransactionBase]:for account in ofx.accounts:for txn in account.statement.transactions:+ raw_payee = getattr(txn, 'payee', None) or Nonetransactions.append(TransactionBase(description=txn.memo or txn.payee or "Unknown",amount=abs(Decimal(str(txn.amount))),date=txn.date.date() if hasattr(txn.date, 'date') else txn.date,type="credit" if txn.amount > 0 else "debit",external_id=getattr(txn, 'id', None),+ payee_raw=raw_payee,))return transactions@@ -93,6 +96,7 @@ def parse_qif(content: bytes) -> list[TransactionBase]:amount=abs(amount),date=txn_date,type="credit" if amount > 0 else "debit",+ payee_raw=payee,))return transactions@@ -399,6 +403,13 @@ async def import_transactions(skipped += 1continue+ # Resolve payee entity from raw payee text (OFX/QIF)+ import_payee_id = None+ import_payee_raw = getattr(txn_data, "payee_raw", None)+ if import_payee_raw:+ import_payee_entity = await get_or_create_payee(session, user_id, import_payee_raw)+ import_payee_id = import_payee_entity.id+transaction = Transaction(user_id=user_id,account_id=account_id,@@ -410,6 +421,8 @@ async def import_transactions(import_id=import_log.id,external_id=txn_data.external_id,currency=txn_currency,+ payee=import_payee_raw,+ payee_id=import_payee_id,)# If CSV provided an fx_rate, use it directlydiff --git a/backend/app/services/payee_service.py b/backend/app/services/payee_service.pynew file mode 100644index 00000000..32a5e291--- /dev/null+++ b/backend/app/services/payee_service.py@@ -0,0 +1,263 @@+import uuid+from datetime import date+from decimal import Decimal+from typing import Optional++from sqlalchemy import case, select, func, update, delete+from sqlalchemy.ext.asyncio import AsyncSession++from app.models.payee import Payee, PayeeMapping+from app.models.transaction import Transaction+from app.models.category import Category+from app.schemas.payee import PayeeCreate, PayeeUpdate+++async def get_payees(session: AsyncSession, user_id: uuid.UUID) -> list[Payee]:+ """List all payees for a user with transaction counts."""+ count_subq = (+ select(+ Transaction.payee_id,+ func.count(Transaction.id).label("tx_count"),+ )+ .where(Transaction.payee_id.isnot(None))+ .group_by(Transaction.payee_id)+ .subquery()+ )+ result = await session.execute(+ select(Payee, func.coalesce(count_subq.c.tx_count, 0).label("transaction_count"))+ .outerjoin(count_subq, Payee.id == count_subq.c.payee_id)+ .where(Payee.user_id == user_id)+ .order_by(Payee.name)+ )+ payees = []+ for row in result.all():+ payee = row[0]+ payee.transaction_count = row[1]+ payees.append(payee)+ return payees+++async def get_payee(session: AsyncSession, payee_id: uuid.UUID, user_id: uuid.UUID) -> Optional[Payee]:+ result = await session.execute(+ select(Payee).where(Payee.id == payee_id, Payee.user_id == user_id)+ )+ return result.scalar_one_or_none()+++async def get_or_create_payee(session: AsyncSession, user_id: uuid.UUID, name: str) -> Payee:+ """Find a payee by name (case-insensitive) or create a new one."""+ name = name.strip()+ if not name:+ raise ValueError("Payee name cannot be empty")++ result = await session.execute(+ select(Payee).where(Payee.user_id == user_id, func.lower(Payee.name) == name.lower())+ )+ payee = result.scalar_one_or_none()+ if payee:+ return payee++ payee = Payee(user_id=user_id, name=name)+ session.add(payee)+ await session.flush()+ return payee+++async def create_payee(session: AsyncSession, user_id: uuid.UUID, data: PayeeCreate) -> Payee:+ # Check uniqueness+ existing = await session.execute(+ select(Payee).where(Payee.user_id == user_id, func.lower(Payee.name) == data.name.strip().lower())+ )+ if existing.scalar_one_or_none():+ raise ValueError("A payee with this name already exists")++ payee = Payee(user_id=user_id, **data.model_dump())+ session.add(payee)+ await session.flush()++ # Self-mapping for merge tracking+ mapping = PayeeMapping(id=payee.id, user_id=user_id, target_id=payee.id)+ session.add(mapping)++ await session.commit()+ await session.refresh(payee)+ payee.transaction_count = 0+ return payee+++async def update_payee(+ session: AsyncSession, payee_id: uuid.UUID, user_id: uuid.UUID, data: PayeeUpdate+) -> Optional[Payee]:+ payee = await get_payee(session, payee_id, user_id)+ if not payee:+ return None++ update_data = data.model_dump(exclude_unset=True)++ # Check name uniqueness if name is being changed+ if "name" in update_data and update_data["name"]:+ existing = await session.execute(+ select(Payee).where(+ Payee.user_id == user_id,+ func.lower(Payee.name) == update_data["name"].strip().lower(),+ Payee.id != payee_id,+ )+ )+ if existing.scalar_one_or_none():+ raise ValueError("A payee with this name already exists")++ for key, value in update_data.items():+ setattr(payee, key, value)++ await session.commit()+ await session.refresh(payee)+ return payee+++async def delete_payee(session: AsyncSession, payee_id: uuid.UUID, user_id: uuid.UUID) -> bool:+ payee = await get_payee(session, payee_id, user_id)+ if not payee:+ return False++ # Null out transaction references+ await session.execute(+ update(Transaction)+ .where(Transaction.payee_id == payee_id)+ .values(payee_id=None)+ )++ # Delete mappings pointing to this payee+ await session.execute(+ delete(PayeeMapping).where(PayeeMapping.target_id == payee_id)+ )++ await session.delete(payee)+ await session.commit()+ return True+++async def merge_payees(+ session: AsyncSession,+ user_id: uuid.UUID,+ target_id: uuid.UUID,+ source_ids: list[uuid.UUID],+) -> int:+ """Merge source payees into target. Returns number of transactions reassigned."""+ # Validate target+ target = await get_payee(session, target_id, user_id)+ if not target:+ raise ValueError("Target payee not found")++ # Validate sources+ for source_id in source_ids:+ if source_id == target_id:+ continue+ source = await get_payee(session, source_id, user_id)+ if not source:+ raise ValueError(f"Source payee {source_id} not found")++ # Reassign transactions+ result = await session.execute(+ update(Transaction)+ .where(Transaction.payee_id.in_(source_ids))+ .values(payee_id=target_id)+ )+ reassigned = result.rowcount++ # Update mappings: point source mappings to target+ for source_id in source_ids:+ if source_id == target_id:+ continue+ await session.execute(+ update(PayeeMapping)+ .where(PayeeMapping.target_id == source_id)+ .values(target_id=target_id)+ )++ # Delete source payees+ for source_id in source_ids:+ if source_id == target_id:+ continue+ source = await get_payee(session, source_id, user_id)+ if source:+ await session.delete(source)++ await session.commit()+ return reassigned+++async def get_payee_summary(+ session: AsyncSession,+ payee_id: uuid.UUID,+ user_id: uuid.UUID,+ start_date: Optional[date] = None,+ end_date: Optional[date] = None,+) -> dict:+ """Return spending analytics for a payee."""+ payee = await get_payee(session, payee_id, user_id)+ if not payee:+ raise ValueError("Payee not found")++ base = select(Transaction).where(+ Transaction.payee_id == payee_id,+ Transaction.user_id == user_id,+ )+ if start_date:+ base = base.where(Transaction.date >= start_date)+ if end_date:+ base = base.where(Transaction.date <= end_date)++ # Totals+ totals = await session.execute(+ select(+ func.coalesce(func.sum(+ case(+ (Transaction.type == "debit", Transaction.amount),+ else_=Decimal("0"),+ )+ ), Decimal("0")).label("total_spent"),+ func.coalesce(func.sum(+ case(+ (Transaction.type == "credit", Transaction.amount),+ else_=Decimal("0"),+ )+ ), Decimal("0")).label("total_received"),+ func.count(Transaction.id).label("count"),+ func.max(Transaction.date).label("last_date"),+ )+ .where(+ Transaction.payee_id == payee_id,+ Transaction.user_id == user_id,+ )+ )+ row = totals.one()++ # Most common category+ cat_result = await session.execute(+ select(Transaction.category_id, func.count(Transaction.id).label("cnt"))+ .where(+ Transaction.payee_id == payee_id,+ Transaction.user_id == user_id,+ Transaction.category_id.isnot(None),+ )+ .group_by(Transaction.category_id)+ .order_by(func.count(Transaction.id).desc())+ .limit(1)+ )+ cat_row = cat_result.first()+ most_common_category = None+ if cat_row:+ cat = await session.execute(+ select(Category).where(Category.id == cat_row[0])+ )+ most_common_category = cat.scalar_one_or_none()++ payee.transaction_count = row.count+ return {+ "payee": payee,+ "total_spent": row.total_spent,+ "total_received": row.total_received,+ "transaction_count": row.count,+ "most_common_category": most_common_category,+ "last_transaction_date": row.last_date,+ }diff --git a/backend/app/services/rule_engine.py b/backend/app/services/rule_engine.pyindex 000e8f5b..0f68e0d2 100644--- a/backend/app/services/rule_engine.py+++ b/backend/app/services/rule_engine.py@@ -98,6 +98,12 @@ def apply_rule_actions(except (ValueError, AttributeError):pass+ elif op == "set_payee":+ try:+ tx.payee_id = uuid.UUID(str(value))+ except (ValueError, AttributeError):+ pass+elif op == "append_notes":new_tags = str(value or "").strip()if not new_tags:diff --git a/backend/app/services/transaction_service.py b/backend/app/services/transaction_service.pyindex 55b7b96e..6be04156 100644--- a/backend/app/services/transaction_service.py+++ b/backend/app/services/transaction_service.py@@ -10,6 +10,7 @@ from app.models.transaction import Transactionfrom app.models.transaction_attachment import TransactionAttachmentfrom app.models.account import Accountfrom app.models.bank_connection import BankConnection+from app.models.payee import Payeefrom app.schemas.transaction import TransactionCreate, TransactionUpdate, TransferCreatefrom app.services.rule_service import apply_rules_to_transactionfrom app.services.fx_rate_service import stamp_primary_amount, convert as fx_convert@@ -46,6 +47,7 @@ async def get_transactions(user_id: uuid.UUID,account_id: Optional[uuid.UUID] = None,category_id: Optional[uuid.UUID] = None,+ payee_id: Optional[uuid.UUID] = None,from_date: Optional[date] = None,to_date: Optional[date] = None,page: int = 1,@@ -61,13 +63,14 @@ async def get_transactions(select(Transaction).outerjoin(Account).outerjoin(BankConnection)+ .outerjoin(Payee, Transaction.payee_id == Payee.id).where(or_(Transaction.user_id == user_id,BankConnection.user_id == user_id,))- .options(selectinload(Transaction.category), selectinload(Transaction.account))+ .options(selectinload(Transaction.category), selectinload(Transaction.account), selectinload(Transaction.payee_entity)))# Exclude opening_balance transactions from the normal list unless explicitly requested@@ -79,6 +82,8 @@ async def get_transactions(base_query = base_query.where(Transaction.account_id == account_id)if category_id:base_query = base_query.where(Transaction.category_id == category_id)+ if payee_id:+ base_query = base_query.where(Transaction.payee_id == payee_id)if uncategorized:base_query = base_query.where(Transaction.category_id == None,@@ -97,6 +102,7 @@ async def get_transactions(Transaction.description.ilike(term),Transaction.payee.ilike(term),Transaction.notes.ilike(term),+ Payee.name.ilike(term),))@@ -126,6 +132,7 @@ async def get_transactions(counts = dict(count_rows.all())for tx in transactions:tx.attachment_count = counts.get(tx.id, 0)+ tx.payee_name = tx.payee_entity.name if tx.payee_entity else Nonereturn transactions, total or 0@@ -144,7 +151,7 @@ async def get_transaction(BankConnection.user_id == user_id,),)- .options(selectinload(Transaction.category))+ .options(selectinload(Transaction.category), selectinload(Transaction.payee_entity)))transaction = result.scalar_one_or_none()if transaction:@@ -154,6 +161,7 @@ async def get_transaction())transaction.attachment_count = count_result.scalar_one()+ transaction.payee_name = transaction.payee_entity.name if transaction.payee_entity else Nonereturn transaction@@ -183,6 +191,7 @@ async def create_transaction(user_id=user_id,account_id=data.account_id,category_id=data.category_id, # use provided category if given+ payee_id=data.payee_id,description=data.description,amount=data.amount,currency=currency,diff --git a/backend/tests/conftest.py b/backend/tests/conftest.pyindex 5ae3c66c..682cbff0 100644--- a/backend/tests/conftest.py+++ b/backend/tests/conftest.py@@ -21,6 +21,7 @@ from app.models.rule import Rulefrom app.models.asset import Asset # noqa: F401from app.models.asset_value import AssetValue # noqa: F401from app.models.transaction_attachment import TransactionAttachment # noqa: F401+from app.models.payee import Payee, PayeeMapping # noqa: F401# Use SQLite for tests — fast, no external dependencyTEST_DATABASE_URL = "sqlite+aiosqlite:///./test.db"diff --git a/backend/tests/test_payee_service.py b/backend/tests/test_payee_service.pynew file mode 100644index 00000000..d9e2a535--- /dev/null+++ b/backend/tests/test_payee_service.py@@ -0,0 +1,362 @@+import uuid+from datetime import date, datetime, timezone+from decimal import Decimal++import pytest+from sqlalchemy.ext.asyncio import AsyncSession++from app.models.payee import PayeeMapping+from app.models.transaction import Transaction+from app.models.account import Account+from app.models.user import User+from app.schemas.payee import PayeeCreate, PayeeUpdate+from app.services.payee_service import (+ create_payee,+ delete_payee,+ get_or_create_payee,+ get_payee,+ get_payees,+ get_payee_summary,+ merge_payees,+ update_payee,+)+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++async def _make_account(session: AsyncSession, user: User) -> Account:+ account = Account(+ id=uuid.uuid4(),+ user_id=user.id,+ name="Test Account",+ type="checking",+ balance=Decimal("1000.00"),+ currency="BRL",+ )+ session.add(account)+ await session.flush()+ return account+++# ---------------------------------------------------------------------------+# create_payee+# ---------------------------------------------------------------------------+++async def test_create_payee(session: AsyncSession, test_user):+ data = PayeeCreate(name="Starbucks", type="merchant")+ payee = await create_payee(session, test_user.id, data)++ assert payee.name == "Starbucks"+ assert payee.type == "merchant"+ assert payee.is_favorite is False+ assert payee.transaction_count == 0+ assert payee.user_id == test_user.id+++async def test_create_payee_with_notes(session: AsyncSession, test_user):+ data = PayeeCreate(name="Coffee Shop", type="merchant", notes="Morning coffee")+ payee = await create_payee(session, test_user.id, data)++ assert payee.notes == "Morning coffee"+++async def test_create_payee_duplicate_name_rejected(session: AsyncSession, test_user):+ await create_payee(session, test_user.id, PayeeCreate(name="Starbucks"))+ with pytest.raises(ValueError, match="already exists"):+ await create_payee(session, test_user.id, PayeeCreate(name="starbucks")) # case-insensitive+++async def test_create_payee_creates_self_mapping(session: AsyncSession, test_user):+ payee = await create_payee(session, test_user.id, PayeeCreate(name="Mapped"))+ from sqlalchemy import select+ result = await session.execute(+ select(PayeeMapping).where(PayeeMapping.id == payee.id)+ )+ mapping = result.scalar_one_or_none()+ assert mapping is not None+ assert mapping.target_id == payee.id+++# ---------------------------------------------------------------------------+# get_payee / get_payees+# ---------------------------------------------------------------------------+++async def test_get_payee(session: AsyncSession, test_user):+ created = await create_payee(session, test_user.id, PayeeCreate(name="Target"))+ fetched = await get_payee(session, created.id, test_user.id)++ assert fetched is not None+ assert fetched.id == created.id+ assert fetched.name == "Target"+++async def test_get_payee_not_found(session: AsyncSession, test_user):+ result = await get_payee(session, uuid.uuid4(), test_user.id)+ assert result is None+++async def test_get_payees_empty(session: AsyncSession, test_user):+ payees = await get_payees(session, test_user.id)+ assert payees == []+++async def test_get_payees_with_transaction_counts(session: AsyncSession, test_user):+ p1 = await create_payee(session, test_user.id, PayeeCreate(name="Payee A"))+ p2 = await create_payee(session, test_user.id, PayeeCreate(name="Payee B"))++ account = await _make_account(session, test_user)++ # Add 2 transactions for p1, 1 for p2+ for i in range(2):+ session.add(Transaction(+ id=uuid.uuid4(), user_id=test_user.id, account_id=account.id,+ description=f"Tx {i}", amount=Decimal("10"), date=date.today(),+ type="debit", source="manual", payee_id=p1.id,+ created_at=datetime.now(timezone.utc),+ ))+ session.add(Transaction(+ id=uuid.uuid4(), user_id=test_user.id, account_id=account.id,+ description="Tx single", amount=Decimal("5"), date=date.today(),+ type="debit", source="manual", payee_id=p2.id,+ created_at=datetime.now(timezone.utc),+ ))+ await session.commit()++ payees = await get_payees(session, test_user.id)+ payees_by_name = {p.name: p for p in payees}++ assert payees_by_name["Payee A"].transaction_count == 2+ assert payees_by_name["Payee B"].transaction_count == 1+++async def test_get_payees_ordered_by_name(session: AsyncSession, test_user):+ await create_payee(session, test_user.id, PayeeCreate(name="Zebra"))+ await create_payee(session, test_user.id, PayeeCreate(name="Apple"))+ await create_payee(session, test_user.id, PayeeCreate(name="Mango"))++ payees = await get_payees(session, test_user.id)+ names = [p.name for p in payees]+ assert names == sorted(names)+++# ---------------------------------------------------------------------------+# get_or_create_payee+# ---------------------------------------------------------------------------+++async def test_get_or_create_payee_creates_new(session: AsyncSession, test_user):+ payee = await get_or_create_payee(session, test_user.id, "New Payee")+ assert payee.name == "New Payee"+ assert payee.user_id == test_user.id+++async def test_get_or_create_payee_returns_existing(session: AsyncSession, test_user):+ original = await create_payee(session, test_user.id, PayeeCreate(name="Existing"))+ found = await get_or_create_payee(session, test_user.id, "existing") # case-insensitive+ assert found.id == original.id+++async def test_get_or_create_payee_strips_whitespace(session: AsyncSession, test_user):+ payee = await get_or_create_payee(session, test_user.id, " Trimmed ")+ assert payee.name == "Trimmed"+++async def test_get_or_create_payee_empty_raises(session: AsyncSession, test_user):+ with pytest.raises(ValueError, match="cannot be empty"):+ await get_or_create_payee(session, test_user.id, " ")+++# ---------------------------------------------------------------------------+# update_payee+# ---------------------------------------------------------------------------+++async def test_update_payee(session: AsyncSession, test_user):+ payee = await create_payee(session, test_user.id, PayeeCreate(name="Old Name"))+ updated = await update_payee(+ session, payee.id, test_user.id,+ PayeeUpdate(name="New Name", is_favorite=True),+ )++ assert updated is not None+ assert updated.name == "New Name"+ assert updated.is_favorite is True+ assert updated.type == "merchant" # unchanged+++async def test_update_payee_not_found(session: AsyncSession, test_user):+ result = await update_payee(+ session, uuid.uuid4(), test_user.id, PayeeUpdate(name="Nope")+ )+ assert result is None+++async def test_update_payee_duplicate_name_rejected(session: AsyncSession, test_user):+ await create_payee(session, test_user.id, PayeeCreate(name="A"))+ b = await create_payee(session, test_user.id, PayeeCreate(name="B"))++ with pytest.raises(ValueError, match="already exists"):+ await update_payee(session, b.id, test_user.id, PayeeUpdate(name="A"))+++# ---------------------------------------------------------------------------+# delete_payee+# ---------------------------------------------------------------------------+++async def test_delete_payee(session: AsyncSession, test_user):+ payee = await create_payee(session, test_user.id, PayeeCreate(name="ToDelete"))+ assert await delete_payee(session, payee.id, test_user.id) is True+ assert await get_payee(session, payee.id, test_user.id) is None+++async def test_delete_payee_not_found(session: AsyncSession, test_user):+ assert await delete_payee(session, uuid.uuid4(), test_user.id) is False+++async def test_delete_payee_nulls_transaction_refs(session: AsyncSession, test_user):+ payee = await create_payee(session, test_user.id, PayeeCreate(name="Linked"))+ account = await _make_account(session, test_user)++ tx = Transaction(+ id=uuid.uuid4(), user_id=test_user.id, account_id=account.id,+ description="Linked Tx", amount=Decimal("50"), date=date.today(),+ type="debit", source="manual", payee_id=payee.id,+ created_at=datetime.now(timezone.utc),+ )+ session.add(tx)+ await session.commit()++ await delete_payee(session, payee.id, test_user.id)++ await session.refresh(tx)+ assert tx.payee_id is None+++# ---------------------------------------------------------------------------+# merge_payees+# ---------------------------------------------------------------------------+++async def test_merge_payees(session: AsyncSession, test_user):+ target = await create_payee(session, test_user.id, PayeeCreate(name="Target"))+ source1 = await create_payee(session, test_user.id, PayeeCreate(name="Source1"))+ source2 = await create_payee(session, test_user.id, PayeeCreate(name="Source2"))++ account = await _make_account(session, test_user)++ # Create transactions assigned to source payees+ for p in [source1, source2]:+ session.add(Transaction(+ id=uuid.uuid4(), user_id=test_user.id, account_id=account.id,+ description=f"Tx for {p.name}", amount=Decimal("10"), date=date.today(),+ type="debit", source="manual", payee_id=p.id,+ created_at=datetime.now(timezone.utc),+ ))+ await session.commit()++ reassigned = await merge_payees(+ session, test_user.id, target.id, [source1.id, source2.id]+ )++ assert reassigned == 2++ # Sources should be deleted+ assert await get_payee(session, source1.id, test_user.id) is None+ assert await get_payee(session, source2.id, test_user.id) is None++ # Target should still exist+ assert await get_payee(session, target.id, test_user.id) is not None+++async def test_merge_payees_target_not_found(session: AsyncSession, test_user):+ source = await create_payee(session, test_user.id, PayeeCreate(name="Source"))+ with pytest.raises(ValueError, match="Target payee not found"):+ await merge_payees(session, test_user.id, uuid.uuid4(), [source.id])+++async def test_merge_payees_source_not_found(session: AsyncSession, test_user):+ target = await create_payee(session, test_user.id, PayeeCreate(name="Target"))+ with pytest.raises(ValueError, match="Source payee"):+ await merge_payees(session, test_user.id, target.id, [uuid.uuid4()])+++# ---------------------------------------------------------------------------+# get_payee_summary+# ---------------------------------------------------------------------------+++async def test_get_payee_summary(session: AsyncSession, test_user, test_categories):+ payee = await create_payee(session, test_user.id, PayeeCreate(name="Summary"))+ account = await _make_account(session, test_user)+ cat = test_categories[0]++ today = date.today()+ # 2 debits, 1 credit+ for desc, amount, typ in [+ ("Buy 1", Decimal("100"), "debit"),+ ("Buy 2", Decimal("50"), "debit"),+ ("Refund", Decimal("30"), "credit"),+ ]:+ session.add(Transaction(+ id=uuid.uuid4(), user_id=test_user.id, account_id=account.id,+ description=desc, amount=amount, date=today,+ type=typ, source="manual", payee_id=payee.id,+ category_id=cat.id, created_at=datetime.now(timezone.utc),+ ))+ await session.commit()++ summary = await get_payee_summary(session, payee.id, test_user.id)++ assert summary["total_spent"] == Decimal("150")+ assert summary["total_received"] == Decimal("30")+ assert summary["transaction_count"] == 3+ assert summary["last_transaction_date"] == today+ assert summary["most_common_category"] is not None+ assert summary["most_common_category"].name == cat.name+++async def test_get_payee_summary_not_found(session: AsyncSession, test_user):+ with pytest.raises(ValueError, match="Payee not found"):+ await get_payee_summary(session, uuid.uuid4(), test_user.id)+++async def test_get_payee_summary_no_transactions(session: AsyncSession, test_user):+ payee = await create_payee(session, test_user.id, PayeeCreate(name="Empty"))+ summary = await get_payee_summary(session, payee.id, test_user.id)++ assert summary["total_spent"] == Decimal("0")+ assert summary["total_received"] == Decimal("0")+ assert summary["transaction_count"] == 0+ assert summary["last_transaction_date"] is None+ assert summary["most_common_category"] is Nonediff --git a/backend/tests/test_payees_api.py b/backend/tests/test_payees_api.pynew file mode 100644index 00000000..4bb2695f--- /dev/null+++ b/backend/tests/test_payees_api.py@@ -0,0 +1,264 @@+import uuid+from datetime import date, datetime, timezone+from decimal import Decimal++import pytest+from httpx import AsyncClient+from sqlalchemy.ext.asyncio import AsyncSession++from app.models.account import Account+from app.models.transaction import Transaction+from app.models.user import User+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++async def _create_payee(client: AsyncClient, auth_headers: dict, name: str, **kwargs) -> dict:+ resp = await client.post(+ "/api/payees", headers=auth_headers,+ json={"name": name, **kwargs},+ )+ assert resp.status_code == 201+ return resp.json()+++async def _make_account_and_tx(+ session: AsyncSession, user: User, payee_id: str,+ amount: Decimal = Decimal("10"), tx_type: str = "debit",+) -> None:+ # Reuse existing account if possible, otherwise create+ from sqlalchemy import select+ result = await session.execute(+ select(Account).where(Account.user_id == user.id).limit(1)+ )+ account = result.scalar_one_or_none()+ if not account:+ account = Account(+ id=uuid.uuid4(), user_id=user.id,+ name="API Test Account", type="checking",+ balance=Decimal("1000"), currency="BRL",+ )+ session.add(account)+ await session.flush()++ session.add(Transaction(+ id=uuid.uuid4(), user_id=user.id, account_id=account.id,+ description="API Test Tx", amount=amount, date=date.today(),+ type=tx_type, source="manual", payee_id=uuid.UUID(payee_id),+ created_at=datetime.now(timezone.utc),+ ))+ await session.commit()+++# ---------------------------------------------------------------------------+# List+# ---------------------------------------------------------------------------+++async def test_list_payees_empty(client: AsyncClient, auth_headers):+ resp = await client.get("/api/payees", headers=auth_headers)+ assert resp.status_code == 200+ assert resp.json() == []+++async def test_list_payees(client: AsyncClient, auth_headers):+ await _create_payee(client, auth_headers, "Alpha")+ await _create_payee(client, auth_headers, "Beta")++ resp = await client.get("/api/payees", headers=auth_headers)+ assert resp.status_code == 200+ data = resp.json()+ assert len(data) == 2+ names = {p["name"] for p in data}+ assert names == {"Alpha", "Beta"}+++# ---------------------------------------------------------------------------+# Create+# ---------------------------------------------------------------------------+++async def test_create_payee(client: AsyncClient, auth_headers):+ resp = await client.post(+ "/api/payees", headers=auth_headers,+ json={"name": "Starbucks", "type": "merchant", "notes": "Coffee"},+ )+ assert resp.status_code == 201+ data = resp.json()+ assert data["name"] == "Starbucks"+ assert data["type"] == "merchant"+ assert data["notes"] == "Coffee"+ assert data["is_favorite"] is False+ assert data["transaction_count"] == 0+ assert "id" in data+++async def test_create_payee_duplicate(client: AsyncClient, auth_headers):+ await _create_payee(client, auth_headers, "Unique")+ resp = await client.post(+ "/api/payees", headers=auth_headers,+ json={"name": "unique"}, # case-insensitive duplicate+ )+ assert resp.status_code == 400+++# ---------------------------------------------------------------------------+# Get single+# ---------------------------------------------------------------------------+++async def test_get_payee(client: AsyncClient, auth_headers):+ created = await _create_payee(client, auth_headers, "Single")+ resp = await client.get(f"/api/payees/{created['id']}", headers=auth_headers)+ assert resp.status_code == 200+ assert resp.json()["name"] == "Single"+++async def test_get_payee_not_found(client: AsyncClient, auth_headers):+ resp = await client.get(+ f"/api/payees/{uuid.uuid4()}", headers=auth_headers,+ )+ assert resp.status_code == 404+++# ---------------------------------------------------------------------------+# Update+# ---------------------------------------------------------------------------+++async def test_update_payee(client: AsyncClient, auth_headers):+ created = await _create_payee(client, auth_headers, "OldName")+ resp = await client.patch(+ f"/api/payees/{created['id']}", headers=auth_headers,+ json={"name": "NewName", "is_favorite": True},+ )+ assert resp.status_code == 200+ data = resp.json()+ assert data["name"] == "NewName"+ assert data["is_favorite"] is True+ assert data["type"] == "merchant" # unchanged+++async def test_update_payee_not_found(client: AsyncClient, auth_headers):+ resp = await client.patch(+ f"/api/payees/{uuid.uuid4()}", headers=auth_headers,+ json={"name": "Nope"},+ )+ assert resp.status_code == 404+++# ---------------------------------------------------------------------------+# Delete+# ---------------------------------------------------------------------------+++async def test_delete_payee(client: AsyncClient, auth_headers):+ created = await _create_payee(client, auth_headers, "ToDelete")+ resp = await client.delete(+ f"/api/payees/{created['id']}", headers=auth_headers,+ )+ assert resp.status_code == 204++ # Confirm gone+ resp = await client.get(f"/api/payees/{created['id']}", headers=auth_headers)+ assert resp.status_code == 404+++async def test_delete_payee_not_found(client: AsyncClient, auth_headers):+ resp = await client.delete(+ f"/api/payees/{uuid.uuid4()}", headers=auth_headers,+ )+ assert resp.status_code == 404+++# ---------------------------------------------------------------------------+# Merge+# ---------------------------------------------------------------------------+++async def test_merge_payees(+ client: AsyncClient, auth_headers, session: AsyncSession, test_user,+):+ target = await _create_payee(client, auth_headers, "MergeTarget")+ source = await _create_payee(client, auth_headers, "MergeSource")++ # Create a transaction linked to source+ await _make_account_and_tx(session, test_user, source["id"])++ resp = await client.post(+ "/api/payees/merge", headers=auth_headers,+ json={"target_id": target["id"], "source_ids": [source["id"]]},+ )+ assert resp.status_code == 200+ data = resp.json()+ assert data["transactions_reassigned"] == 1++ # Source should be gone+ resp = await client.get(f"/api/payees/{source['id']}", headers=auth_headers)+ assert resp.status_code == 404+++async def test_merge_payees_invalid_target(client: AsyncClient, auth_headers):+ source = await _create_payee(client, auth_headers, "SrcOnly")+ resp = await client.post(+ "/api/payees/merge", headers=auth_headers,+ json={"target_id": str(uuid.uuid4()), "source_ids": [source["id"]]},+ )+ assert resp.status_code == 400+++# ---------------------------------------------------------------------------+# Summary+# ---------------------------------------------------------------------------+++async def test_get_payee_summary(+ client: AsyncClient, auth_headers, session: AsyncSession, test_user,+):+ payee = await _create_payee(client, auth_headers, "SummaryPayee")+ await _make_account_and_tx(session, test_user, payee["id"], Decimal("100"), "debit")+ await _make_account_and_tx(session, test_user, payee["id"], Decimal("30"), "credit")++ resp = await client.get(+ f"/api/payees/{payee['id']}/summary", headers=auth_headers,+ )+ assert resp.status_code == 200+ data = resp.json()+ assert data["transaction_count"] == 2+ assert float(data["total_spent"]) == 100.0+ assert float(data["total_received"]) == 30.0+++async def test_get_payee_summary_not_found(client: AsyncClient, auth_headers):+ resp = await client.get(+ f"/api/payees/{uuid.uuid4()}/summary", headers=auth_headers,+ )+ assert resp.status_code == 404+++# ---------------------------------------------------------------------------+# Auth+# ---------------------------------------------------------------------------+++async def test_payees_unauthenticated(client: AsyncClient, clean_db):+ resp = await client.get("/api/payees")+ assert resp.status_code == 401diff --git a/backend/tests/test_rule_engine.py b/backend/tests/test_rule_engine.pyindex 125a0492..3aea6c52 100644--- a/backend/tests/test_rule_engine.py+++ b/backend/tests/test_rule_engine.py@@ -304,3 +304,37 @@ def test_rule_priority_ordering():category_set = apply_rule_actions(actions_high, tx, category_already_set=category_set)assert tx.category_id == cat_low+++# --- set_payee action tests ---+++def test_set_payee_action():+ payee_id = uuid.uuid4()+ actions = [{"op": "set_payee", "value": str(payee_id)}]+ tx = make_tx()+ tx.payee_id = None+ apply_rule_actions(actions, tx, category_already_set=False)+ assert tx.payee_id == payee_id+++def test_set_payee_invalid_uuid_ignored():+ actions = [{"op": "set_payee", "value": "not-a-uuid"}]+ tx = make_tx()+ tx.payee_id = None+ apply_rule_actions(actions, tx, category_already_set=False)+ assert tx.payee_id is None+++def test_set_payee_combined_with_category():+ cat_id = uuid.uuid4()+ payee_id = uuid.uuid4()+ actions = [+ {"op": "set_category", "value": str(cat_id)},+ {"op": "set_payee", "value": str(payee_id)},+ ]+ tx = make_tx()+ tx.payee_id = None+ apply_rule_actions(actions, tx, category_already_set=False)+ assert tx.category_id == cat_id+ assert tx.payee_id == payee_iddiff --git a/frontend/src/App.tsx b/frontend/src/App.tsxindex 02b6b040..a0423557 100644--- a/frontend/src/App.tsx+++ b/frontend/src/App.tsx@@ -21,6 +21,7 @@ const BudgetsPage = lazy(() => import('@/pages/budgets'))const RecurringPage = lazy(() => import('@/pages/recurring'))const AssetsPage = lazy(() => import('@/pages/assets'))const ReportsPage = lazy(() => import('@/pages/reports'))+const PayeesPage = lazy(() => import('@/pages/payees'))const queryClient = new QueryClient({defaultOptions: {@@ -68,6 +69,7 @@ function App() {<Route path="/recurring" element={<RecurringPage />} /><Route path="/assets" element={<AssetsPage />} /><Route path="/reports" element={<ReportsPage />} />+ <Route path="/payees" element={<PayeesPage />} /></Route></Routes></Suspense>diff --git a/frontend/src/components/app-layout.tsx b/frontend/src/components/app-layout.tsxindex b9b64e12..8e13909d 100644--- a/frontend/src/components/app-layout.tsx+++ b/frontend/src/components/app-layout.tsx@@ -34,6 +34,7 @@ import {EyeOff,Repeat,Landmark,+ Users,BarChart3,Sun,Moon,@@ -60,6 +61,7 @@ const navItems: NavItem[] = [{ type: 'link', key: 'budgets', path: '/budgets', icon: PiggyBank },{ type: 'link', key: 'recurring', path: '/recurring', icon: Repeat },{ type: 'link', key: 'categories', path: '/categories', icon: Tag },+ { type: 'link', key: 'payees', path: '/payees', icon: Users },{ type: 'link', key: 'rules', path: '/rules', icon: SlidersHorizontal },]diff --git a/frontend/src/components/transaction-dialog.tsx b/frontend/src/components/transaction-dialog.tsxindex b7bad8a7..f605e338 100644--- a/frontend/src/components/transaction-dialog.tsx+++ b/frontend/src/components/transaction-dialog.tsx@@ -2,7 +2,7 @@ import { useState, useEffect, useCallback, useRef } from 'react'import { useTranslation } from 'react-i18next'import { useQuery } from '@tanstack/react-query'import { useAuth } from '@/contexts/auth-context'-import { currencies as currenciesApi, transactions as transactionsApi, settings as settingsApi } from '@/lib/api'+import { currencies as currenciesApi, transactions as transactionsApi, settings as settingsApi, payees as payeesApi } from '@/lib/api'import { cn } from '@/lib/utils'import { Button } from '@/components/ui/button'import { Input } from '@/components/ui/input'@@ -279,12 +279,17 @@ function TransactionForm({queryFn: currenciesApi.list,staleTime: Infinity,})+ const { data: payeesList } = useQuery({+ queryKey: ['payees'],+ queryFn: payeesApi.list,+ })const [description, setDescription] = useState(transaction?.description ?? '')const [amount, setAmount] = useState(transaction?.amount?.toString() ?? '')const [date, setDate] = useState(transaction?.date ?? new Date().toISOString().split('T')[0])const [type, setType] = useState<'debit' | 'credit'>(transaction?.type ?? 'debit')const [currency, setCurrency] = useState(transaction?.currency ?? userCurrency)const [categoryId, setCategoryId] = useState(transaction?.category_id ?? '')+ const [payeeId, setPayeeId] = useState(transaction?.payee_id ?? '')const [accountId, setAccountId] = useState(transaction?.account_id ?? accounts[0]?.id ?? '')const [notes, setNotes] = useState(transaction?.notes ?? '')const [convertedAmount, setConvertedAmount] = useState(@@ -395,6 +400,7 @@ function TransactionForm({const txData = isSynced? {category_id: categoryId || null,+ payee_id: payeeId || null,notes: notes.trim() || undefined,} as Partial<Transaction>: {@@ -404,6 +410,7 @@ function TransactionForm({type,currency,category_id: categoryId || null,+ payee_id: payeeId || null,account_id: accountId || undefined,notes: notes.trim() || undefined,...fxFields,@@ -554,21 +561,39 @@ function TransactionForm({</select></div></div>- {!isSynced && (+ <div className={cn("grid gap-4", isSynced ? "grid-cols-1" : "grid-cols-2")}><div className="space-y-2">- <Label>{t('transactions.account')}</Label>+ <Label>{t('payees.payee')}</Label><selectclassName="w-full border border-border rounded-md px-3 py-2 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"- value={accountId}- onChange={(e) => setAccountId(e.target.value)}- required+ value={payeeId}+ onChange={(e) => setPayeeId(e.target.value)}>- {accounts.map((acc) => (- <option key={acc.id} value={acc.id}>{acc.name}</option>+ <option value="">{t('payees.noPayee')}</option>+ {(payeesList ?? []).map((p) => (+ <option key={p.id} value={p.id}>{p.name}</option>))}</select>+ {isSynced && transaction?.payee && (+ <p className="text-xs text-muted-foreground">{t('payees.rawPayee')}: {transaction.payee}</p>+ )}</div>- )}+ {!isSynced && (+ <div className="space-y-2">+ <Label>{t('transactions.account')}</Label>+ <select+ className="w-full border border-border rounded-md px-3 py-2 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"+ value={accountId}+ onChange={(e) => setAccountId(e.target.value)}+ required+ >+ {accounts.map((acc) => (+ <option key={acc.id} value={acc.id}>{acc.name}</option>+ ))}+ </select>+ </div>+ )}+ </div><div className="space-y-2"><Label>{t('transactions.notes')} <span className="text-muted-foreground font-normal text-xs">({t('transactions.notesHint')})</span></Label>diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.tsindex 2b57d876..9c470319 100644--- a/frontend/src/lib/api.ts+++ b/frontend/src/lib/api.ts@@ -8,6 +8,8 @@ import type {Account,AccountSummary,Transaction,+ Payee,+ PayeeSummary,RecurringTransaction,ProjectedTransaction,Budget,@@ -212,6 +214,7 @@ export const transactions = {list: async (params?: {account_id?: stringcategory_id?: string+ payee_id?: stringuncategorized?: booleantype?: stringfrom?: string@@ -324,6 +327,37 @@ export const transactions = {},}+// Payees+export const payees = {+ list: async (): Promise<Payee[]> => {+ const { data } = await api.get('/payees')+ return data+ },+ get: async (id: string): Promise<Payee> => {+ const { data } = await api.get(`/payees/${id}`)+ return data+ },+ summary: async (id: string, from?: string, to?: string): Promise<PayeeSummary> => {+ const { data } = await api.get(`/payees/${id}/summary`, { params: { from, to } })+ return data+ },+ create: async (payee: { name: string; type?: string; notes?: string }): Promise<Payee> => {+ const { data } = await api.post('/payees', payee)+ return data+ },+ update: async (id: string, payee: Partial<Payee>): Promise<Payee> => {+ const { data } = await api.patch(`/payees/${id}`, payee)+ return data+ },+ delete: async (id: string): Promise<void> => {+ await api.delete(`/payees/${id}`)+ },+ merge: async (targetId: string, sourceIds: string[]): Promise<{ merged: number; transactions_reassigned: number }> => {+ const { data } = await api.post('/payees/merge', { target_id: targetId, source_ids: sourceIds })+ return data+ },+}+// Categorization Rulesexport const rules = {list: async (): Promise<Rule[]> => {diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.jsonindex 3b3a0a8c..74ff3dff 100644--- a/frontend/src/locales/en.json+++ b/frontend/src/locales/en.json@@ -13,6 +13,7 @@"settings": "Settings","recurring": "Recurring","assets": "Assets",+ "payees": "Payees","reports": "Reports","groupAnalysis": "Analysis","groupSetup": "Setup",@@ -318,6 +319,8 @@"addCondition": "Add condition","addAction": "Add action","setCategory": "Set category",+ "setPayee": "Set payee",+ "selectPayee": "Select payee...","appendNotes": "Append tags/notes","selectCategory": "Select category...","selectAccount": "Select account...",@@ -510,6 +513,38 @@"uncategorized": "Uncategorized","categoryTrends": "Category Trends"},+ "payees": {+ "title": "Payees",+ "section": "Setup",+ "payee": "Payee",+ "noPayee": "No payee",+ "rawPayee": "Original payee",+ "name": "Name",+ "type": "Type",+ "notes": "Notes",+ "add": "Add Payee",+ "edit": "Edit Payee",+ "created": "Payee created",+ "updated": "Payee updated",+ "deleted": "Payee deleted",+ "empty": "No payees yet",+ "searchPlaceholder": "Search payees...",+ "transactionCount": "Transactions",+ "totalSpent": "Total Spent",+ "totalReceived": "Total Received",+ "lastTransaction": "Last Transaction",+ "topCategory": "Top Category",+ "viewAllTransactions": "View all {{count}} transactions",+ "merge": "Merge",+ "mergeTitle": "Merge Payees",+ "mergeDescription": "All transactions from the selected payees will be reassigned to the target payee. The other payees will be deleted.",+ "mergeTarget": "Merge into",+ "selectTarget": "Select target payee...",+ "merged": "Payees merged ({{count}} transactions reassigned)",+ "typeMerchant": "Merchant",+ "typePerson": "Person",+ "typeCompany": "Company"+ },"common": {"save": "Save","cancel": "Cancel",diff --git a/frontend/src/locales/pt-BR.json b/frontend/src/locales/pt-BR.jsonindex 7b6dbe42..95415004 100644--- a/frontend/src/locales/pt-BR.json+++ b/frontend/src/locales/pt-BR.json@@ -13,6 +13,7 @@"settings": "Configurações","recurring": "Recorrentes","assets": "Patrimônio",+ "payees": "Beneficiários","reports": "Relatórios","groupAnalysis": "Análise","groupSetup": "Configuração",@@ -318,6 +319,8 @@"addCondition": "Adicionar condição","addAction": "Adicionar ação","setCategory": "Definir categoria",+ "setPayee": "Definir beneficiário",+ "selectPayee": "Selecionar beneficiário...","appendNotes": "Adicionar tags/notas","selectCategory": "Selecionar categoria...","selectAccount": "Selecionar conta...",@@ -510,6 +513,38 @@"uncategorized": "Sem categoria","categoryTrends": "Tendência por Categoria"},+ "payees": {+ "title": "Beneficiários",+ "section": "Configuração",+ "payee": "Beneficiário",+ "noPayee": "Sem beneficiário",+ "rawPayee": "Beneficiário original",+ "name": "Nome",+ "type": "Tipo",+ "notes": "Notas",+ "add": "Adicionar Beneficiário",+ "edit": "Editar Beneficiário",+ "created": "Beneficiário criado",+ "updated": "Beneficiário atualizado",+ "deleted": "Beneficiário excluído",+ "empty": "Nenhum beneficiário ainda",+ "searchPlaceholder": "Buscar beneficiários...",+ "transactionCount": "Transações",+ "totalSpent": "Total Gasto",+ "totalReceived": "Total Recebido",+ "lastTransaction": "Última Transação",+ "topCategory": "Categoria Principal",+ "viewAllTransactions": "Ver todas as {{count}} transações",+ "merge": "Mesclar",+ "mergeTitle": "Mesclar Beneficiários",+ "mergeDescription": "Todas as transações dos beneficiários selecionados serão reatribuídas ao beneficiário destino. Os demais serão excluídos.",+ "mergeTarget": "Mesclar em",+ "selectTarget": "Selecionar beneficiário destino...",+ "merged": "Beneficiários mesclados ({{count}} transações reatribuídas)",+ "typeMerchant": "Comerciante",+ "typePerson": "Pessoa",+ "typeCompany": "Empresa"+ },"common": {"save": "Salvar","cancel": "Cancelar",diff --git a/frontend/src/pages/account-detail.tsx b/frontend/src/pages/account-detail.tsxindex 010225bf..ae68d8d7 100644--- a/frontend/src/pages/account-detail.tsx+++ b/frontend/src/pages/account-detail.tsx@@ -486,8 +486,8 @@ export default function AccountDetailPage() {<Paperclip size={12} className="ml-2 inline text-muted-foreground" />)}</div>- {tx.payee && tx.payee !== tx.description && (- <p className="text-xs text-muted-foreground mt-0.5">{tx.payee}</p>+ {(tx.payee_name || tx.payee) && (tx.payee_name || tx.payee) !== tx.description && (+ <p className="text-xs text-muted-foreground mt-0.5">{tx.payee_name || tx.payee}</p>)}</td><td className="px-4 py-3 hidden md:table-cell">diff --git a/frontend/src/pages/payees.tsx b/frontend/src/pages/payees.tsxnew file mode 100644index 00000000..51250d90--- /dev/null+++ b/frontend/src/pages/payees.tsx@@ -0,0 +1,478 @@+import { useState } from 'react'+import { useTranslation } from 'react-i18next'+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'+import { useNavigate } from 'react-router-dom'+import { payees as payeesApi, transactions as transactionsApi } from '@/lib/api'+import { toast } from 'sonner'+import { Button } from '@/components/ui/button'+import { Input } from '@/components/ui/input'+import { Label } from '@/components/ui/label'+import { Skeleton } from '@/components/ui/skeleton'+import {+ Dialog,+ DialogContent,+ DialogHeader,+ DialogTitle,+ DialogFooter,+} from '@/components/ui/dialog'+import {+ Table,+ TableBody,+ TableCell,+ TableHead,+ TableHeader,+ TableRow,+} from '@/components/ui/table'+import { PageHeader } from '@/components/page-header'+import { Search, Star, Merge, Trash2, ArrowRight } from 'lucide-react'+import { usePrivacyMode } from '@/hooks/use-privacy-mode'+import { useAuth } from '@/contexts/auth-context'+import type { Payee } from '@/types'++function formatCurrency(value: number, currency = 'USD', locale = 'en-US') {+ return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(value)+}++export default function PayeesPage() {+ const { t, i18n } = useTranslation()+ const navigate = useNavigate()+ const locale = i18n.language === 'en' ? 'en-US' : i18n.language+ const { mask } = usePrivacyMode()+ const { user } = useAuth()+ const userCurrency = user?.preferences?.currency_display ?? 'USD'+ const queryClient = useQueryClient()+ const [search, setSearch] = useState('')+ const [dialogOpen, setDialogOpen] = useState(false)+ const [editingPayee, setEditingPayee] = useState<Payee | null>(null)+ const [summaryPayee, setSummaryPayee] = useState<string | null>(null)+ const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set())+ const [mergeDialogOpen, setMergeDialogOpen] = useState(false)+ const [mergeTargetId, setMergeTargetId] = useState<string>('')++ // Form state+ const [formName, setFormName] = useState('')+ const [formType, setFormType] = useState<string>('merchant')+ const [formNotes, setFormNotes] = useState('')++ const { data: payeesList, isLoading } = useQuery({+ queryKey: ['payees'],+ queryFn: payeesApi.list,+ })++ const { data: summaryData, isLoading: summaryLoading } = useQuery({+ queryKey: ['payees', summaryPayee, 'summary'],+ queryFn: () => payeesApi.summary(summaryPayee!),+ enabled: !!summaryPayee,+ })++ const { data: recentTxData } = useQuery({+ queryKey: ['payees', summaryPayee, 'recent-transactions'],+ queryFn: () => transactionsApi.list({ payee_id: summaryPayee!, limit: 5 }),+ enabled: !!summaryPayee,+ })++ const createMutation = useMutation({+ mutationFn: (data: { name: string; type?: string; notes?: string }) => payeesApi.create(data),+ onSuccess: () => {+ queryClient.invalidateQueries({ queryKey: ['payees'] })+ setDialogOpen(false)+ toast.success(t('payees.created'))+ },+ onError: () => toast.error(t('common.error')),+ })++ const updateMutation = useMutation({+ mutationFn: ({ id, ...data }: Partial<Payee> & { id: string }) => payeesApi.update(id, data),+ onSuccess: () => {+ queryClient.invalidateQueries({ queryKey: ['payees'] })+ setDialogOpen(false)+ setEditingPayee(null)+ toast.success(t('payees.updated'))+ },+ onError: () => toast.error(t('common.error')),+ })++ const deleteMutation = useMutation({+ mutationFn: (id: string) => payeesApi.delete(id),+ onSuccess: () => {+ queryClient.invalidateQueries({ queryKey: ['payees'] })+ queryClient.invalidateQueries({ queryKey: ['transactions'] })+ setDialogOpen(false)+ setEditingPayee(null)+ toast.success(t('payees.deleted'))+ },+ onError: () => toast.error(t('common.error')),+ })++ const favoriteMutation = useMutation({+ mutationFn: ({ id, is_favorite }: { id: string; is_favorite: boolean }) =>+ payeesApi.update(id, { is_favorite }),+ onSuccess: () => {+ queryClient.invalidateQueries({ queryKey: ['payees'] })+ },+ })++ const mergeMutation = useMutation({+ mutationFn: ({ targetId, sourceIds }: { targetId: string; sourceIds: string[] }) =>+ payeesApi.merge(targetId, sourceIds),+ onSuccess: (result) => {+ queryClient.invalidateQueries({ queryKey: ['payees'] })+ queryClient.invalidateQueries({ queryKey: ['transactions'] })+ setMergeDialogOpen(false)+ setSelectedIds(new Set())+ setMergeTargetId('')+ toast.success(t('payees.merged', { count: result.transactions_reassigned }))+ },+ onError: () => toast.error(t('common.error')),+ })++ const openCreate = () => {+ setEditingPayee(null)+ setFormName('')+ setFormType('merchant')+ setFormNotes('')+ setDialogOpen(true)+ }++ const openEdit = (payee: Payee) => {+ setEditingPayee(payee)+ setFormName(payee.name)+ setFormType(payee.type)+ setFormNotes(payee.notes ?? '')+ setDialogOpen(true)+ }++ const handleSave = () => {+ if (editingPayee) {+ updateMutation.mutate({ id: editingPayee.id, name: formName, type: formType as Payee['type'], notes: formNotes || undefined })+ } else {+ createMutation.mutate({ name: formName, type: formType, notes: formNotes || undefined })+ }+ }++ const toggleSelect = (id: string) => {+ setSelectedIds(prev => {+ const next = new Set(prev)+ if (next.has(id)) next.delete(id)+ else next.add(id)+ return next+ })+ }++ const filtered = (payeesList ?? []).filter(p =>+ !search || p.name.toLowerCase().includes(search.toLowerCase())+ )++ return (+ <div>+ <PageHeader+ section={t('payees.section')}+ title={t('payees.title')}+ action={+ <div className="flex items-center gap-2">+ {selectedIds.size >= 2 && (+ <Button variant="outline" onClick={() => { setMergeTargetId(''); setMergeDialogOpen(true) }}>+ <Merge size={16} className="mr-1.5" />+ {t('payees.merge')} ({selectedIds.size})+ </Button>+ )}+ <Button onClick={openCreate}>+ + {t('payees.add')}+ </Button>+ </div>+ }+ />++ {/* Search */}+ <div className="bg-card rounded-xl border border-border shadow-sm p-3 md:p-4 mb-4">+ <div className="relative w-full md:w-auto">+ <Search className="absolute left-3 top-1/2 -translate-y-1/2 text-muted-foreground" size={16} />+ <Input+ type="text"+ placeholder={t('payees.searchPlaceholder')}+ value={search}+ onChange={(e) => setSearch(e.target.value)}+ className="pl-9 w-full md:w-[300px] h-[38px] text-sm"+ />+ </div>+ </div>++ {/* Table */}+ <div className="bg-card rounded-xl border border-border shadow-sm overflow-hidden mb-4">+ {isLoading ? (+ <div className="p-6 space-y-3">+ {Array.from({ length: 5 }).map((_, i) => (+ <Skeleton key={i} className="h-14 w-full" />+ ))}+ </div>+ ) : (+ <Table>+ <TableHeader>+ <TableRow className="border-b border-border hover:bg-transparent">+ <TableHead className="w-[40px] py-3 pl-4 pr-0" />+ <TableHead className="text-xs font-medium text-muted-foreground py-3 w-[32px]" />+ <TableHead className="text-xs font-medium text-muted-foreground py-3">{t('payees.name')}</TableHead>+ <TableHead className="hidden md:table-cell text-xs font-medium text-muted-foreground py-3 w-[120px]">{t('payees.type')}</TableHead>+ <TableHead className="text-xs font-medium text-muted-foreground py-3 text-right w-[120px]">{t('payees.transactionCount')}</TableHead>+ <TableHead className="w-[60px]" />+ </TableRow>+ </TableHeader>+ <TableBody>+ {filtered.map((payee) => (+ <TableRow+ key={payee.id}+ className={`cursor-pointer hover:bg-muted border-b border-border last:border-0 ${selectedIds.has(payee.id) ? 'bg-primary/5' : ''}`}+ onClick={() => {+ setSummaryPayee(summaryPayee === payee.id ? null : payee.id)+ }}+ >+ <TableCell className="py-2.5 pl-4 pr-0 w-[40px]">+ <input+ type="checkbox"+ checked={selectedIds.has(payee.id)}+ onChange={() => toggleSelect(payee.id)}+ onClick={(e) => e.stopPropagation()}+ className="h-4 w-4 rounded border-border accent-primary cursor-pointer"+ />+ </TableCell>+ <TableCell className="py-2.5 w-[32px]">+ <button+ onClick={(e) => {+ e.stopPropagation()+ favoriteMutation.mutate({ id: payee.id, is_favorite: !payee.is_favorite })+ }}+ className="p-1 rounded hover:bg-accent"+ >+ <Star+ size={14}+ className={payee.is_favorite ? 'fill-amber-400 text-amber-400' : 'text-muted-foreground'}+ />+ </button>+ </TableCell>+ <TableCell className="py-2.5">+ <span className="text-sm font-semibold text-foreground">{payee.name}</span>+ {payee.notes && (+ <p className="text-xs text-muted-foreground mt-0.5 truncate max-w-[300px]">{payee.notes}</p>+ )}+ </TableCell>+ <TableCell className="hidden md:table-cell py-2.5">+ <span className="text-xs bg-muted text-muted-foreground px-2 py-0.5 rounded-full capitalize">{payee.type}</span>+ </TableCell>+ <TableCell className="py-2.5 text-right">+ <span className="text-sm tabular-nums text-muted-foreground">{payee.transaction_count}</span>+ </TableCell>+ <TableCell className="py-2.5 pr-4">+ <Button+ variant="ghost"+ size="sm"+ onClick={(e) => { e.stopPropagation(); openEdit(payee) }}+ >+ {t('common.edit')}+ </Button>+ </TableCell>+ </TableRow>+ ))}+ {filtered.length === 0 && (+ <TableRow>+ <TableCell colSpan={6} className="text-center py-16 text-muted-foreground">+ {t('payees.empty')}+ </TableCell>+ </TableRow>+ )}+ </TableBody>+ </Table>+ )}+ </div>++ {/* Summary panel */}+ {summaryPayee && (+ <div className="bg-card rounded-xl border border-border shadow-sm p-5 mb-4">+ {summaryLoading ? (+ <Skeleton className="h-24 w-full" />+ ) : summaryData ? (+ <div className="space-y-3">+ <div className="flex items-center justify-between">+ <h3 className="text-lg font-bold">{summaryData.payee.name}</h3>+ <Button variant="ghost" size="sm" onClick={() => setSummaryPayee(null)}>+ ×+ </Button>+ </div>+ <div className="grid grid-cols-2 sm:grid-cols-4 gap-4">+ <div>+ <p className="text-xs text-muted-foreground">{t('payees.totalSpent')}</p>+ <p className="text-lg font-bold text-rose-500 tabular-nums">+ {mask(formatCurrency(summaryData.total_spent, userCurrency, locale))}+ </p>+ </div>+ <div>+ <p className="text-xs text-muted-foreground">{t('payees.totalReceived')}</p>+ <p className="text-lg font-bold text-emerald-600 tabular-nums">+ {mask(formatCurrency(summaryData.total_received, userCurrency, locale))}+ </p>+ </div>+ <div>+ <p className="text-xs text-muted-foreground">{t('payees.transactionCount')}</p>+ <p className="text-lg font-bold tabular-nums">{summaryData.transaction_count}</p>+ </div>+ <div>+ <p className="text-xs text-muted-foreground">{t('payees.lastTransaction')}</p>+ <p className="text-sm font-medium">+ {summaryData.last_transaction_date+ ? new Date(summaryData.last_transaction_date + 'T00:00:00').toLocaleDateString(locale)+ : '—'}+ </p>+ </div>+ </div>+ {summaryData.most_common_category && (+ <p className="text-xs text-muted-foreground">+ {t('payees.topCategory')}: <span className="font-medium text-foreground">{summaryData.most_common_category.name}</span>+ </p>+ )}++ {/* Recent transactions */}+ {recentTxData && recentTxData.items.length > 0 && (+ <div className="pt-3 border-t border-border space-y-2">+ <p className="text-xs font-medium text-muted-foreground">{t('dashboard.recentTransactions')}</p>+ <div className="divide-y divide-border rounded-lg border border-border overflow-hidden">+ {recentTxData.items.map((tx) => (+ <div key={tx.id} className="flex items-center justify-between px-3 py-2 bg-background text-sm">+ <div className="flex-1 min-w-0">+ <p className="text-sm font-medium text-foreground truncate">{tx.description}</p>+ <p className="text-xs text-muted-foreground">+ {new Date(tx.date + 'T00:00:00').toLocaleDateString(locale)}+ {tx.category?.name && <> · {tx.category.name}</>}+ </p>+ </div>+ <span className={`text-sm font-semibold tabular-nums ml-3 ${tx.type === 'debit' ? 'text-rose-500' : 'text-emerald-600'}`}>+ {mask(formatCurrency(tx.amount, tx.currency, locale))}+ </span>+ </div>+ ))}+ </div>+ {recentTxData.total > 5 && (+ <Button+ variant="ghost"+ size="sm"+ className="w-full text-xs text-muted-foreground hover:text-foreground gap-1"+ onClick={() => navigate(`/transactions?payee_id=${summaryPayee}`)}+ >+ {t('payees.viewAllTransactions', { count: recentTxData.total })}+ <ArrowRight size={12} />+ </Button>+ )}+ </div>+ )}+ </div>+ ) : null}+ </div>+ )}++ {/* Create/Edit Dialog */}+ <Dialog open={dialogOpen} onOpenChange={setDialogOpen}>+ <DialogContent className="sm:max-w-md">+ <DialogHeader>+ <DialogTitle>{editingPayee ? t('payees.edit') : t('payees.add')}</DialogTitle>+ </DialogHeader>+ <div className="space-y-4">+ <div className="space-y-2">+ <Label>{t('payees.name')}</Label>+ <Input value={formName} onChange={(e) => setFormName(e.target.value)} required />+ </div>+ <div className="space-y-2">+ <Label>{t('payees.type')}</Label>+ <select+ className="w-full border border-border rounded-md px-3 py-2 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"+ value={formType}+ onChange={(e) => setFormType(e.target.value)}+ >+ <option value="merchant">{t('payees.typeMerchant')}</option>+ <option value="person">{t('payees.typePerson')}</option>+ <option value="company">{t('payees.typeCompany')}</option>+ </select>+ </div>+ <div className="space-y-2">+ <Label>{t('payees.notes')}</Label>+ <textarea+ className="w-full border border-input rounded-md px-3 py-2 text-sm bg-background resize-none focus:outline-none focus:ring-2 focus:ring-ring"+ rows={2}+ value={formNotes}+ onChange={(e) => setFormNotes(e.target.value)}+ />+ </div>+ </div>+ <DialogFooter className={editingPayee ? 'flex justify-between sm:justify-between' : ''}>+ {editingPayee && (+ <Button+ variant="destructive"+ onClick={() => deleteMutation.mutate(editingPayee.id)}+ disabled={deleteMutation.isPending}+ >+ <Trash2 size={14} className="mr-1" />+ {t('common.delete')}+ </Button>+ )}+ <div className="flex gap-2">+ <Button variant="outline" onClick={() => setDialogOpen(false)}>+ {t('common.cancel')}+ </Button>+ <Button+ onClick={handleSave}+ disabled={!formName.trim() || createMutation.isPending || updateMutation.isPending}+ >+ {t('common.save')}+ </Button>+ </div>+ </DialogFooter>+ </DialogContent>+ </Dialog>++ {/* Merge Dialog */}+ <Dialog open={mergeDialogOpen} onOpenChange={setMergeDialogOpen}>+ <DialogContent className="sm:max-w-md">+ <DialogHeader>+ <DialogTitle>{t('payees.mergeTitle')}</DialogTitle>+ </DialogHeader>+ <div className="space-y-4">+ <p className="text-sm text-muted-foreground">{t('payees.mergeDescription')}</p>+ <div className="space-y-1">+ {Array.from(selectedIds).map(id => {+ const p = payeesList?.find(x => x.id === id)+ return p ? (+ <div key={id} className="text-sm py-1 px-2 rounded bg-muted">{p.name} ({p.transaction_count})</div>+ ) : null+ })}+ </div>+ <div className="space-y-2">+ <Label>{t('payees.mergeTarget')}</Label>+ <select+ className="w-full border border-border rounded-md px-3 py-2 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"+ value={mergeTargetId}+ onChange={(e) => setMergeTargetId(e.target.value)}+ >+ <option value="">{t('payees.selectTarget')}</option>+ {Array.from(selectedIds).map(id => {+ const p = payeesList?.find(x => x.id === id)+ return p ? <option key={id} value={id}>{p.name}</option> : null+ })}+ </select>+ </div>+ </div>+ <DialogFooter>+ <Button variant="outline" onClick={() => setMergeDialogOpen(false)}>+ {t('common.cancel')}+ </Button>+ <Button+ disabled={!mergeTargetId || mergeMutation.isPending}+ onClick={() => {+ const sourceIds = Array.from(selectedIds).filter(id => id !== mergeTargetId)+ mergeMutation.mutate({ targetId: mergeTargetId, sourceIds })+ }}+ >+ {t('payees.merge')}+ </Button>+ </DialogFooter>+ </DialogContent>+ </Dialog>+ </div>+ )+}diff --git a/frontend/src/pages/rules.tsx b/frontend/src/pages/rules.tsxindex 04e135a1..ee6bd305 100644--- a/frontend/src/pages/rules.tsx+++ b/frontend/src/pages/rules.tsx@@ -1,7 +1,7 @@import { useState, useMemo } from 'react'import { useTranslation } from 'react-i18next'import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'-import { categories as categoriesApi, rules as rulesApi, accounts as accountsApi } from '@/lib/api'+import { categories as categoriesApi, rules as rulesApi, accounts as accountsApi, payees as payeesApi } from '@/lib/api'import { toast } from 'sonner'import { Button } from '@/components/ui/button'import { Input } from '@/components/ui/input'@@ -13,7 +13,7 @@ import {DialogTitle,DialogFooter,} from '@/components/ui/dialog'-import type { Category, Rule, RuleCondition, RuleAction } from '@/types'+import type { Category, Payee, Rule, RuleCondition, RuleAction } from '@/types'import { Trash2, Plus, RefreshCw, X, Package, Check, ArrowUpDown, ArrowUp, ArrowDown } from 'lucide-react'import { cn } from '@/lib/utils'import { PageHeader } from '@/components/page-header'@@ -81,12 +81,16 @@ function conditionSummary(conditions: RuleCondition[], conditionsOp: string, t:return parts.join(` ${conditionsOp === 'or' ? t('rules.orOp') : t('rules.andOp')} `) || t('rules.noConditions')}-function actionSummary(actions: RuleAction[], categories: Category[], t: (key: string) => string): string {+function actionSummary(actions: RuleAction[], categories: Category[], payeesList: Payee[], t: (key: string) => string): string {return actions.map(a => {if (a.op === 'set_category') {const cat = categories.find(c => c.id === a.value)return cat ? `→ ${cat.name}` : `→ ${t('transactions.category')}`}+ if (a.op === 'set_payee') {+ const p = payeesList.find(p => p.id === a.value)+ return p ? `→ ${t('payees.payee')}: ${p.name}` : `→ ${t('payees.payee')}`+ }if (a.op === 'append_notes') return `→ ${t('rules.fieldNotes')}: ${a.value}`return a.op}).join(' ') || t('rules.noActions')@@ -114,6 +118,11 @@ export default function RulesPage() {queryFn: () => accountsApi.list(),})+ const { data: payeesList } = useQuery({+ queryKey: ['payees'],+ queryFn: payeesApi.list,+ })+const createMutation = useMutation({mutationFn: (data: Omit<Rule, 'id' | 'user_id'>) => rulesApi.create(data),onSuccess: () => {@@ -170,6 +179,7 @@ export default function RulesPage() {})const categories = categoriesList ?? []+ const payees = payeesList ?? []const [sortBy, setSortBy] = useState<'priority' | 'name' | 'category'>('priority')const [sortDir, setSortDir] = useState<'asc' | 'desc'>('asc')@@ -274,7 +284,7 @@ export default function RulesPage() {{conditionSummary(rule.conditions, rule.conditions_op, t)}</p><p className="text-xs text-emerald-600 font-medium mt-0.5">- {actionSummary(rule.actions, categories, t)}+ {actionSummary(rule.actions, categories, payees, t)}</p></div><div className="flex items-center gap-1 shrink-0">@@ -307,6 +317,7 @@ export default function RulesPage() {rule={editing}categories={categories}accounts={accountsList ?? []}+ payees={payees}onSave={(data) => {if (editing) {updateMutation.mutate({ id: editing.id, ...data })@@ -389,13 +400,14 @@ function RulePacksDialog({ open, onClose }: { open: boolean; onClose: () => void}function RuleDialog({- open, onClose, rule, categories, accounts, onSave, loading,+ open, onClose, rule, categories, accounts, payees, onSave, loading,}: {open: booleanonClose: () => voidrule: Rule | nullcategories: Category[]accounts: { id: string; name: string }[]+ payees: Payee[]onSave: (data: Partial<Rule>) => voidloading: boolean}) {@@ -562,6 +574,7 @@ function RuleDialog({onChange={(e) => updateAction(i, 'op', e.target.value)}><option value="set_category">{t('rules.setCategory')}</option>+ <option value="set_payee">{t('rules.setPayee')}</option><option value="append_notes">{t('rules.appendNotes')}</option></select>{action.op === 'set_category' ? (@@ -576,6 +589,18 @@ function RuleDialog({<option key={cat.id} value={cat.id}>{cat.name}</option>))}</select>+ ) : action.op === 'set_payee' ? (+ <select+ className={`${selectClass} flex-1`}+ value={action.value}+ onChange={(e) => updateAction(i, 'value', e.target.value)}+ required+ >+ <option value="">{t('rules.selectPayee')}</option>+ {payees.map(p => (+ <option key={p.id} value={p.id}>{p.name}</option>+ ))}+ </select>) : (<InputclassName="flex-1 h-8 text-sm"diff --git a/frontend/src/pages/transactions.tsx b/frontend/src/pages/transactions.tsxindex 66231262..09a48b2e 100644--- a/frontend/src/pages/transactions.tsx+++ b/frontend/src/pages/transactions.tsx@@ -1,7 +1,8 @@import { useState, useMemo, useEffect, useRef } from 'react'+import { useSearchParams } from 'react-router-dom'import { useTranslation } from 'react-i18next'import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'-import { transactions, categories as categoriesApi, accounts as accountsApi, recurring } from '@/lib/api'+import { transactions, categories as categoriesApi, accounts as accountsApi, recurring, payees as payeesApi } from '@/lib/api'import { toast } from 'sonner'import { Button } from '@/components/ui/button'import {@@ -36,6 +37,7 @@ function parseHashtags(notes: string | null): string[] {export default function TransactionsPage() {const { t, i18n } = useTranslation()+ const [searchParams] = useSearchParams()const locale = i18n.language === 'en' ? 'en-US' : i18n.languageconst { mask } = usePrivacyMode()const { user } = useAuth()@@ -50,6 +52,7 @@ export default function TransactionsPage() {const [searchQuery, setSearchQuery] = useState('')const [dialogOpen, setDialogOpen] = useState(false)const [editingTx, setEditingTx] = useState<Transaction | null>(null)+ const [filterPayee, setFilterPayee] = useState<string>(searchParams.get('payee_id') ?? '')const [tagFilter, setTagFilter] = useState<string | null>(null)const [exporting, setExporting] = useState(false)const [transferDialogOpen, setTransferDialogOpen] = useState(false)@@ -70,16 +73,17 @@ export default function TransactionsPage() {useEffect(() => {setSelectedIds(new Set())setBulkCategory('')- }, [page, filterAccount, filterCategory, filterFrom, filterTo, searchQuery])+ }, [page, filterAccount, filterCategory, filterPayee, filterFrom, filterTo, searchQuery])const { data, isLoading } = useQuery({- queryKey: ['transactions', page, filterAccount, filterCategory, filterFrom, filterTo, searchQuery],+ queryKey: ['transactions', page, filterAccount, filterCategory, filterPayee, filterFrom, filterTo, searchQuery],queryFn: () =>transactions.list({page,limit: 20,account_id: filterAccount || undefined,category_id: filterCategory === '__uncategorized__' ? undefined : (filterCategory || undefined),+ payee_id: filterPayee || undefined,uncategorized: filterCategory === '__uncategorized__' ? true : undefined,from: filterFrom || undefined,to: filterTo || undefined,@@ -97,6 +101,11 @@ export default function TransactionsPage() {queryFn: () => accountsApi.list(),})+ const { data: payeesList } = useQuery({+ queryKey: ['payees'],+ queryFn: payeesApi.list,+ })+const { data: recurringList } = useQuery({queryKey: ['recurring'],queryFn: recurring.list,@@ -311,6 +320,16 @@ export default function TransactionsPage() {<option key={cat.id} value={cat.id}>{cat.name}</option>))}</select>+ <select+ className="border border-border rounded-lg px-3 py-2 text-sm bg-card text-foreground focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px] min-w-0"+ value={filterPayee}+ onChange={(e) => { setFilterPayee(e.target.value); setPage(1) }}+ >+ <option value="">{t('payees.payee')}: {t('transactions.all')}</option>+ {payeesList?.map((p) => (+ <option key={p.id} value={p.id}>{p.name}</option>+ ))}+ </select></div><div className="grid grid-cols-2 gap-2 md:flex md:gap-3"><div className="flex items-center gap-2">@@ -330,12 +349,12 @@ export default function TransactionsPage() {/></div></div>- {(filterFrom || filterTo || filterAccount || filterCategory || searchInput) && (+ {(filterFrom || filterTo || filterAccount || filterCategory || filterPayee || searchInput) && (<Buttonvariant="ghost"size="sm"className="text-muted-foreground hover:text-foreground"- onClick={() => { setFilterFrom(''); setFilterTo(''); setFilterAccount(''); setFilterCategory(''); setSearchInput(''); setSearchQuery(''); setPage(1) }}+ onClick={() => { setFilterFrom(''); setFilterTo(''); setFilterAccount(''); setFilterCategory(''); setFilterPayee(''); setSearchInput(''); setSearchQuery(''); setPage(1) }}>{t('transactions.clearFilters')}</Button>diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.tsindex 7775ef0f..363badc2 100644--- a/frontend/src/types/index.ts+++ b/frontend/src/types/index.ts@@ -92,6 +92,8 @@ export interface Transaction {source: stringstatus: 'posted' | 'pending'payee: string | null+ payee_id: string | null+ payee_name: string | nullnotes: string | nulltransfer_pair_id: string | nullamount_primary: number | null@@ -100,6 +102,26 @@ export interface Transaction {attachment_count?: number}+export interface Payee {+ id: string+ user_id: string+ name: string+ type: 'merchant' | 'person' | 'company'+ is_favorite: boolean+ notes: string | null+ created_at: string+ transaction_count: number+}++export interface PayeeSummary {+ payee: Payee+ total_spent: number+ total_received: number+ transaction_count: number+ most_common_category: Category | null+ last_transaction_date: string | null+}+export interface RuleCondition {field: stringop: string