feat: implement contact management features including repository, service, and API endpoints; add unit and integration tests

app/api/deps.py

@@ -11,12 +11,14 @@ from app.core.database import get_session
 from app.core.security import jwt_service, password_hasher
 from app.models.user import User
 from app.repositories.activity_repo import ActivityRepository
+from app.repositories.contact_repo import ContactRepository
 from app.repositories.deal_repo import DealRepository
 from app.repositories.org_repo import OrganizationRepository
 from app.repositories.task_repo import TaskRepository
 from app.repositories.user_repo import UserRepository
 from app.services.auth_service import AuthService
 from app.services.activity_service import ActivityService
+from app.services.contact_service import ContactService
 from app.services.deal_service import DealService
 from app.services.organization_service import (
     OrganizationAccessDeniedError,
@@ -48,6 +50,10 @@ def get_deal_repository(session: AsyncSession = Depends(get_db_session)) -> Deal
     return DealRepository(session=session)
 
 
+def get_contact_repository(session: AsyncSession = Depends(get_db_session)) -> ContactRepository:
+    return ContactRepository(session=session)
+
+
 def get_task_repository(session: AsyncSession = Depends(get_db_session)) -> TaskRepository:
     return TaskRepository(session=session)
 
@@ -86,6 +92,12 @@ def get_activity_service(
     return ActivityService(repository=repo)
 
 
+def get_contact_service(
+    repo: ContactRepository = Depends(get_contact_repository),
+) -> ContactService:
+    return ContactService(repository=repo)
+
+
 def get_task_service(
     task_repo: TaskRepository = Depends(get_task_repository),
     activity_repo: ActivityRepository = Depends(get_activity_repository),

app/api/v1/contacts.py

@@ -1,10 +1,20 @@
-"""Contact API stubs and schemas."""
+"""Contact API endpoints."""
 from __future__ import annotations
 
-from fastapi import APIRouter, Depends, Query, status
-from pydantic import BaseModel, EmailStr
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, ConfigDict, EmailStr
 
-from app.api.deps import get_organization_context
+from app.api.deps import get_contact_service, get_organization_context
+from app.models.contact import ContactCreate, ContactRead
+from app.services.contact_service import (
+    ContactDeletionError,
+    ContactForbiddenError,
+    ContactListFilters,
+    ContactNotFoundError,
+    ContactOrganizationError,
+    ContactService,
+    ContactUpdateData,
+)
 from app.services.organization_service import OrganizationContext
 
 
@@ -12,33 +22,106 @@ class ContactCreatePayload(BaseModel):
     name: str
     email: EmailStr | None = None
     phone: str | None = None
+    owner_id: int | None = None
+
+    def to_domain(self, *, organization_id: int, fallback_owner: int) -> ContactCreate:
+        return ContactCreate(
+            organization_id=organization_id,
+            owner_id=self.owner_id or fallback_owner,
+            name=self.name,
+            email=self.email,
+            phone=self.phone,
+        )
+
+
+class ContactUpdatePayload(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str | None = None
+    email: EmailStr | None = None
+    phone: str | None = None
+
+    def to_update_data(self) -> ContactUpdateData:
+        dump = self.model_dump(exclude_unset=True)
+        return ContactUpdateData(
+            name=dump.get("name"),
+            email=dump.get("email"),
+            phone=dump.get("phone"),
+        )
 
 
 router = APIRouter(prefix="/contacts", tags=["contacts"])
 
 
-def _stub(endpoint: str) -> dict[str, str]:
-    return {"detail": f"{endpoint} is not implemented yet"}
-
-
-@router.get("/", status_code=status.HTTP_501_NOT_IMPLEMENTED)
+@router.get("/", response_model=list[ContactRead])
 async def list_contacts(
     page: int = Query(1, ge=1),
     page_size: int = Query(20, ge=1, le=100),
-    search: str | None = None,
+    search: str | None = Query(default=None, min_length=1),
     owner_id: int | None = None,
     context: OrganizationContext = Depends(get_organization_context),
-) -> dict[str, str]:
-    """Placeholder list endpoint supporting the required filters."""
-    _ = context
-    return _stub("GET /contacts")
+    service: ContactService = Depends(get_contact_service),
+) -> list[ContactRead]:
+    filters = ContactListFilters(
+        page=page,
+        page_size=page_size,
+        search=search,
+        owner_id=owner_id,
+    )
+    try:
+        contacts = await service.list_contacts(filters=filters, context=context)
+    except ContactForbiddenError as exc:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(exc)) from exc
+    return [ContactRead.model_validate(contact) for contact in contacts]
 
 
-@router.post("/", status_code=status.HTTP_501_NOT_IMPLEMENTED)
+@router.post("/", response_model=ContactRead, status_code=status.HTTP_201_CREATED)
 async def create_contact(
     payload: ContactCreatePayload,
     context: OrganizationContext = Depends(get_organization_context),
-) -> dict[str, str]:
-    """Placeholder for creating a contact within the current organization."""
-    _ = (payload, context)
-    return _stub("POST /contacts")
+    service: ContactService = Depends(get_contact_service),
+) -> ContactRead:
+    data = payload.to_domain(organization_id=context.organization_id, fallback_owner=context.user_id)
+    try:
+        contact = await service.create_contact(data, context=context)
+    except ContactForbiddenError as exc:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(exc)) from exc
+    except ContactOrganizationError as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+    return ContactRead.model_validate(contact)
+
+
+@router.patch("/{contact_id}", response_model=ContactRead)
+async def update_contact(
+    contact_id: int,
+    payload: ContactUpdatePayload,
+    context: OrganizationContext = Depends(get_organization_context),
+    service: ContactService = Depends(get_contact_service),
+) -> ContactRead:
+    try:
+        contact = await service.get_contact(contact_id, context=context)
+        updated = await service.update_contact(contact, payload.to_update_data(), context=context)
+    except ContactNotFoundError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+    except ContactForbiddenError as exc:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(exc)) from exc
+    except ContactOrganizationError as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+    return ContactRead.model_validate(updated)
+
+
+@router.delete("/{contact_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_contact(
+    contact_id: int,
+    context: OrganizationContext = Depends(get_organization_context),
+    service: ContactService = Depends(get_contact_service),
+) -> None:
+    try:
+        contact = await service.get_contact(contact_id, context=context)
+        await service.delete_contact(contact, context=context)
+    except ContactNotFoundError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+    except ContactForbiddenError as exc:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(exc)) from exc
+    except ContactDeletionError as exc:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(exc)) from exc

app/repositories/contact_repo.py

@@ -0,0 +1,137 @@
+"""Repository helpers for contacts with role-aware access."""
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from sqlalchemy import Select, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.contact import Contact, ContactCreate
+from app.models.organization_member import OrganizationRole
+
+
+class ContactAccessError(Exception):
+    """Raised when attempting operations without sufficient permissions."""
+
+
+@dataclass(slots=True)
+class ContactQueryParams:
+    """Filters accepted by contact list queries."""
+
+    organization_id: int
+    page: int = 1
+    page_size: int = 20
+    search: str | None = None
+    owner_id: int | None = None
+
+
+class ContactRepository:
+    """Provides CRUD helpers for Contact entities."""
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    @property
+    def session(self) -> AsyncSession:
+        return self._session
+
+    async def list(
+        self,
+        *,
+        params: ContactQueryParams,
+        role: OrganizationRole,
+        user_id: int,
+    ) -> Sequence[Contact]:
+        stmt: Select[tuple[Contact]] = select(Contact).where(Contact.organization_id == params.organization_id)
+        stmt = self._apply_filters(stmt, params, role, user_id)
+        offset = (max(params.page, 1) - 1) * params.page_size
+        stmt = stmt.order_by(Contact.created_at.desc()).offset(offset).limit(params.page_size)
+        result = await self._session.scalars(stmt)
+        return result.all()
+
+    async def get(
+        self,
+        contact_id: int,
+        *,
+        organization_id: int,
+        role: OrganizationRole,
+        user_id: int,
+    ) -> Contact | None:
+        stmt = select(Contact).where(Contact.id == contact_id, Contact.organization_id == organization_id)
+        stmt = self._apply_role_clause(stmt, role, user_id)
+        result = await self._session.scalars(stmt)
+        return result.first()
+
+    async def create(
+        self,
+        data: ContactCreate,
+        *,
+        role: OrganizationRole,
+        user_id: int,
+    ) -> Contact:
+        if role == OrganizationRole.MEMBER and data.owner_id != user_id:
+            raise ContactAccessError("Members can only create contacts they own")
+        contact = Contact(**data.model_dump())
+        self._session.add(contact)
+        await self._session.flush()
+        return contact
+
+    async def update(
+        self,
+        contact: Contact,
+        updates: Mapping[str, Any],
+        *,
+        role: OrganizationRole,
+        user_id: int,
+    ) -> Contact:
+        if role == OrganizationRole.MEMBER and contact.owner_id != user_id:
+            raise ContactAccessError("Members can only modify their own contacts")
+        for field, value in updates.items():
+            if hasattr(contact, field):
+                setattr(contact, field, value)
+        await self._session.flush()
+        await self._session.refresh(contact)
+        return contact
+
+    async def delete(
+        self,
+        contact: Contact,
+        *,
+        role: OrganizationRole,
+        user_id: int,
+    ) -> None:
+        if role == OrganizationRole.MEMBER and contact.owner_id != user_id:
+            raise ContactAccessError("Members can only delete their own contacts")
+        await self._session.delete(contact)
+        await self._session.flush()
+
+    def _apply_filters(
+        self,
+        stmt: Select[tuple[Contact]],
+        params: ContactQueryParams,
+        role: OrganizationRole,
+        user_id: int,
+    ) -> Select[tuple[Contact]]:
+        if params.search:
+            pattern = f"%{params.search.lower()}%"
+            stmt = stmt.where(
+                func.lower(Contact.name).like(pattern)
+                | func.lower(func.coalesce(Contact.email, "")).like(pattern)
+            )
+        if params.owner_id is not None:
+            if role == OrganizationRole.MEMBER:
+                raise ContactAccessError("Members cannot filter by owner")
+            stmt = stmt.where(Contact.owner_id == params.owner_id)
+        return self._apply_role_clause(stmt, role, user_id)
+
+    def _apply_role_clause(
+        self,
+        stmt: Select[tuple[Contact]],
+        role: OrganizationRole,
+        user_id: int,
+    ) -> Select[tuple[Contact]]:
+        if role == OrganizationRole.MEMBER:
+            return stmt.where(Contact.owner_id == user_id)
+        return stmt

app/services/contact_service.py

@@ -0,0 +1,155 @@
+"""Business logic for contact workflows."""
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from sqlalchemy import select
+
+from app.models.contact import Contact, ContactCreate
+from app.models.deal import Deal
+from app.repositories.contact_repo import ContactAccessError, ContactQueryParams, ContactRepository
+from app.services.organization_service import OrganizationContext
+
+
+class ContactServiceError(Exception):
+    """Base error for contact workflows."""
+
+
+class ContactNotFoundError(ContactServiceError):
+    """Raised when contact cannot be found within organization."""
+
+
+class ContactForbiddenError(ContactServiceError):
+    """Raised when user lacks permissions for the operation."""
+
+
+class ContactOrganizationError(ContactServiceError):
+    """Raised when attempting to operate outside current organization."""
+
+
+class ContactDeletionError(ContactServiceError):
+    """Raised when contact cannot be deleted due to business constraints."""
+
+
+@dataclass(slots=True)
+class ContactListFilters:
+    """Filters accepted by contact list endpoint."""
+
+    page: int = 1
+    page_size: int = 20
+    search: str | None = None
+    owner_id: int | None = None
+
+
+class _UnsetType:
+    __slots__ = ()
+
+
+UNSET = _UnsetType()
+
+
+@dataclass(slots=True)
+class ContactUpdateData:
+    """Subset of fields allowed during contact update."""
+
+    name: str | None | _UnsetType = UNSET
+    email: str | None | _UnsetType = UNSET
+    phone: str | None | _UnsetType = UNSET
+
+
+class ContactService:
+    """Encapsulates contact-specific business rules."""
+
+    def __init__(self, repository: ContactRepository) -> None:
+        self._repository = repository
+
+    async def list_contacts(
+        self,
+        *,
+        filters: ContactListFilters,
+        context: OrganizationContext,
+    ) -> Sequence[Contact]:
+        params = ContactQueryParams(
+            organization_id=context.organization_id,
+            page=filters.page,
+            page_size=filters.page_size,
+            search=filters.search,
+            owner_id=filters.owner_id,
+        )
+        try:
+            return await self._repository.list(params=params, role=context.role, user_id=context.user_id)
+        except ContactAccessError as exc:
+            raise ContactForbiddenError(str(exc)) from exc
+
+    async def create_contact(
+        self,
+        data: ContactCreate,
+        *,
+        context: OrganizationContext,
+    ) -> Contact:
+        self._ensure_same_organization(data.organization_id, context)
+        try:
+            return await self._repository.create(data, role=context.role, user_id=context.user_id)
+        except ContactAccessError as exc:
+            raise ContactForbiddenError(str(exc)) from exc
+
+    async def get_contact(
+        self,
+        contact_id: int,
+        *,
+        context: OrganizationContext,
+    ) -> Contact:
+        contact = await self._repository.get(
+            contact_id,
+            organization_id=context.organization_id,
+            role=context.role,
+            user_id=context.user_id,
+        )
+        if contact is None:
+            raise ContactNotFoundError("Contact not found")
+        return contact
+
+    async def update_contact(
+        self,
+        contact: Contact,
+        updates: ContactUpdateData,
+        *,
+        context: OrganizationContext,
+    ) -> Contact:
+        self._ensure_same_organization(contact.organization_id, context)
+        payload = self._build_update_mapping(updates)
+        if not payload:
+            return contact
+        try:
+            return await self._repository.update(contact, payload, role=context.role, user_id=context.user_id)
+        except ContactAccessError as exc:
+            raise ContactForbiddenError(str(exc)) from exc
+
+    async def delete_contact(self, contact: Contact, *, context: OrganizationContext) -> None:
+        self._ensure_same_organization(contact.organization_id, context)
+        await self._ensure_no_related_deals(contact_id=contact.id)
+        try:
+            await self._repository.delete(contact, role=context.role, user_id=context.user_id)
+        except ContactAccessError as exc:
+            raise ContactForbiddenError(str(exc)) from exc
+
+    def _ensure_same_organization(self, organization_id: int, context: OrganizationContext) -> None:
+        if organization_id != context.organization_id:
+            raise ContactOrganizationError("Contact belongs to another organization")
+
+    def _build_update_mapping(self, updates: ContactUpdateData) -> dict[str, str | None]:
+        payload: dict[str, str | None] = {}
+        if updates.name is not UNSET:
+            payload["name"] = updates.name
+        if updates.email is not UNSET:
+            payload["email"] = updates.email
+        if updates.phone is not UNSET:
+            payload["phone"] = updates.phone
+        return payload
+
+    async def _ensure_no_related_deals(self, contact_id: int) -> None:
+        stmt = select(Deal.id).where(Deal.contact_id == contact_id).limit(1)
+        result = await self._repository.session.scalar(stmt)
+        if result is not None:
+            raise ContactDeletionError("Contact has related deals and cannot be deleted")