feat(contacts): add contacts module with backend APIs and web tab

- add user_contacts table and migration

- expose /users/contacts list/add/remove endpoints

- add Contacts tab in chat list with add/remove actions

app/users/models.py

@@ -53,3 +53,13 @@ class BlockedUser(Base):
     user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
     blocked_user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+
+class UserContact(Base):
+    __tablename__ = "user_contacts"
+    __table_args__ = (UniqueConstraint("user_id", "contact_user_id", name="uq_user_contacts_pair"),)
+
+    id: Mapped[int] = mapped_column(primary_key=True, index=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    contact_user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)

app/users/repository.py

@@ -3,7 +3,7 @@ from datetime import datetime, timezone
 from sqlalchemy import and_, func, or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.users.models import BlockedUser, User
+from app.users.models import BlockedUser, User, UserContact
 
 
 async def create_user(db: AsyncSession, *, email: str, name: str, username: str, password_hash: str) -> User:
@@ -107,3 +107,40 @@ async def list_blocked_users(db: AsyncSession, *, user_id: int) -> list[User]:
     )
     result = await db.execute(stmt)
     return list(result.scalars().all())
+
+
+async def add_contact(db: AsyncSession, *, user_id: int, contact_user_id: int) -> UserContact:
+    existing = await get_contact_relation(db, user_id=user_id, contact_user_id=contact_user_id)
+    if existing:
+        return existing
+    relation = UserContact(user_id=user_id, contact_user_id=contact_user_id)
+    db.add(relation)
+    await db.flush()
+    return relation
+
+
+async def remove_contact(db: AsyncSession, *, user_id: int, contact_user_id: int) -> None:
+    relation = await get_contact_relation(db, user_id=user_id, contact_user_id=contact_user_id)
+    if relation:
+        await db.delete(relation)
+
+
+async def get_contact_relation(db: AsyncSession, *, user_id: int, contact_user_id: int) -> UserContact | None:
+    result = await db.execute(
+        select(UserContact).where(
+            UserContact.user_id == user_id,
+            UserContact.contact_user_id == contact_user_id,
+        )
+    )
+    return result.scalar_one_or_none()
+
+
+async def list_contacts(db: AsyncSession, *, user_id: int) -> list[User]:
+    stmt = (
+        select(User)
+        .join(UserContact, UserContact.contact_user_id == User.id)
+        .where(UserContact.user_id == user_id)
+        .order_by(User.username.asc())
+    )
+    result = await db.execute(stmt)
+    return list(result.scalars().all())

app/users/router.py

@@ -6,10 +6,14 @@ from app.database.session import get_db
 from app.users.models import User
 from app.users.schemas import UserProfileUpdate, UserRead, UserSearchRead
 from app.users.service import (
+    add_contact,
     block_user,
     get_user_by_id,
     get_user_by_username,
     list_blocked_users,
+    list_contacts,
+    has_block_relation_between_users,
+    remove_contact,
     search_users_by_username,
     unblock_user,
     update_user_profile,
@@ -72,6 +76,42 @@ async def read_blocked_users(
     return await list_blocked_users(db, user_id=current_user.id)
 
 
+@router.get("/contacts", response_model=list[UserSearchRead])
+async def read_contacts(
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> list[UserSearchRead]:
+    return await list_contacts(db, user_id=current_user.id)
+
+
+@router.post("/{user_id}/contacts", status_code=status.HTTP_204_NO_CONTENT)
+async def add_contact_endpoint(
+    user_id: int,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> None:
+    if user_id == current_user.id:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail="Cannot add yourself")
+    target = await get_user_by_id(db, user_id)
+    if not target:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+    is_blocked = await has_block_relation_between_users(db, user_a_id=current_user.id, user_b_id=user_id)
+    if is_blocked:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Cannot add contact while blocked")
+    await add_contact(db, user_id=current_user.id, contact_user_id=user_id)
+
+
+@router.delete("/{user_id}/contacts", status_code=status.HTTP_204_NO_CONTENT)
+async def remove_contact_endpoint(
+    user_id: int,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> None:
+    if user_id == current_user.id:
+        return
+    await remove_contact(db, user_id=current_user.id, contact_user_id=user_id)
+
+
 @router.post("/{user_id}/block", status_code=status.HTTP_204_NO_CONTENT)
 async def block_user_endpoint(
     user_id: int,

app/users/service.py

@@ -73,3 +73,17 @@ async def has_block_relation_between_users(db: AsyncSession, *, user_a_id: int,
 
 async def list_blocked_users(db: AsyncSession, *, user_id: int) -> list[User]:
     return await repository.list_blocked_users(db, user_id=user_id)
+
+
+async def add_contact(db: AsyncSession, *, user_id: int, contact_user_id: int) -> None:
+    await repository.add_contact(db, user_id=user_id, contact_user_id=contact_user_id)
+    await db.commit()
+
+
+async def remove_contact(db: AsyncSession, *, user_id: int, contact_user_id: int) -> None:
+    await repository.remove_contact(db, user_id=user_id, contact_user_id=contact_user_id)
+    await db.commit()
+
+
+async def list_contacts(db: AsyncSession, *, user_id: int) -> list[User]:
+    return await repository.list_contacts(db, user_id=user_id)