feat: backend read api for all entities (messages/groups/calls/sms/org/sync)

Adds the read-only API surface the upcoming Vue frontend needs to browse all
mirrored entities. Follows the existing customer-router pattern: Annotated
deps, Page[T] envelope, select+where+order_by, count() for total.

Endpoints (all GET):
* /api/departments          -> list[DepartmentOut] (path-ordered, plain list)
* /api/staff                -> Page[StaffOut] (department_id, is_on_job filters)
* /api/accounts             -> Page[AccountOut] (channel filter; unified
                             wechat+whatsapp projection built in memory)
* /api/messages             -> Page[MessageOut] (channel/owner/talker/room/
                             [start,end] filters; ordered timestamp asc)
* /api/groups               -> Page[GroupOut] (channel/owner filters)
* /api/groups/{id}/members  -> list[GroupMemberOut] (404 on unknown room)
* /api/calls                -> Page[PhoneCallOut] (channel/user/time window;
                             ordered start_call_time desc)
* /api/sms                  -> Page[SmsOut] (user/time window; create_time desc)
* /api/sync/status          -> {states, recent_runs} monitor payload

Schemas (Pydantic v2, from_attributes=True): MessageOut, GroupOut,
GroupMemberOut, PhoneCallOut, SmsOut, DepartmentOut, StaffOut, AccountOut
(unified across two tables), SyncStateOut, SyncRunOut, SyncStatusOut.
Only human-relevant fields per entity are exposed.

Tests: per-router TDD via httpx ASGITransport against an in-memory SQLite
override of get_session. A shared make_client factory in conftest.py builds
the seeded client, deduping the ~40-line fixture across the six new files.
41 new tests cover shape + every documented filter + pagination + ordering
(nulls-last verified on all desc/asc time columns).

Suite: 226 -> 267 passing. ruff check clean.

Co-Authored-By: Claude <noreply@anthropic.com>

yunke-server/app/api/main.py

@@ -8,6 +8,14 @@ Includes:
 * ``GET /api/health``  -> ``{"status": "ok"}`` liveness probe.
 * ``GET /api/customers`` (see :mod:`app.api.routers.customer`).
 * ``GET /api/media/{media_hash}`` (see :mod:`app.api.routers.media`).
+* ``GET /api/departments`` / ``/api/staff`` / ``/api/accounts``
+  (see :mod:`app.api.routers.organization`).
+* ``GET /api/messages`` (see :mod:`app.api.routers.messages`).
+* ``GET /api/groups`` / ``/api/groups/{room_id}/members``
+  (see :mod:`app.api.routers.groups`).
+* ``GET /api/calls`` (see :mod:`app.api.routers.calls`).
+* ``GET /api/sms`` (see :mod:`app.api.routers.sms`).
+* ``GET /api/sync/status`` (see :mod:`app.api.routers.sync`).
 
 CORS is configured permissively (wildcard origin, no credentials) so the local
 frontend can call the API during development.
@@ -26,7 +34,16 @@ from fastapi import Depends, FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
 from app.api.auth import require_auth
-from app.api.routers import customer, media
+from app.api.routers import (
+    calls,
+    customer,
+    groups,
+    media,
+    messages,
+    organization,
+    sms,
+    sync,
+)
 
 app = FastAPI(title="yunke data mirror", dependencies=[Depends(require_auth)])
 
@@ -39,6 +56,12 @@ app.add_middleware(
 
 app.include_router(customer.router)
 app.include_router(media.router)
+app.include_router(organization.router)
+app.include_router(messages.router)
+app.include_router(groups.router)
+app.include_router(calls.router)
+app.include_router(sms.router)
+app.include_router(sync.router)
 
 
 @app.get("/api/health")

yunke-server/app/api/routers/calls.py

@@ -0,0 +1,68 @@
+"""GET /api/calls — phone-call / voice-call log list.
+
+Read-only query over the mirrored ``phone_call`` table. ``channel`` here is the
+**call-type** in {``phone_call``, ``voice_call``} (calls are not tied to a
+messaging channel). Filters: ``channel``, ``user_id``, and a ms-epoch
+``[start, end]`` window compared against ``start_call_time`` (inclusive).
+Ordered by ``start_call_time desc`` (nulls last) — most recent calls first.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import sqlalchemy as sa
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_session
+from app.api.schemas import Page, PhoneCallOut
+from app.db.models import PhoneCall
+
+router = APIRouter(prefix="/api", tags=["calls"])
+
+SessionDep = Annotated[AsyncSession, Depends(get_session)]
+PageParam = Annotated[int, Query(ge=1)]
+PageSizeParam = Annotated[int, Query(ge=1, le=100)]
+
+
+@router.get("/calls")
+async def list_calls(
+    session: SessionDep,
+    page: PageParam = 1,
+    page_size: PageSizeParam = 20,
+    channel: Annotated[str | None, Query()] = None,
+    user_id: Annotated[str | None, Query()] = None,
+    start: Annotated[int | None, Query(ge=0)] = None,
+    end: Annotated[int | None, Query(ge=0)] = None,
+) -> Page[PhoneCallOut]:
+    """List phone/voice calls with optional filters, newest first."""
+    conditions = []
+    if channel is not None:
+        conditions.append(PhoneCall.channel == channel)
+    if user_id is not None:
+        conditions.append(PhoneCall.user_id == user_id)
+    if start is not None:
+        conditions.append(PhoneCall.start_call_time >= start)
+    if end is not None:
+        conditions.append(PhoneCall.start_call_time <= end)
+
+    total_stmt = sa.select(sa.func.count()).select_from(PhoneCall)
+    if conditions:
+        total_stmt = total_stmt.where(*conditions)
+    total = (await session.execute(total_stmt)).scalar_one()
+
+    list_stmt = sa.select(PhoneCall)
+    if conditions:
+        list_stmt = list_stmt.where(*conditions)
+    list_stmt = (
+        list_stmt.order_by(
+            sa.nullslast(PhoneCall.start_call_time.desc()),
+            PhoneCall.call_id.asc(),
+        )
+        .limit(page_size)
+        .offset((page - 1) * page_size)
+    )
+    rows = (await session.execute(list_stmt)).scalars().all()
+    items = [PhoneCallOut.model_validate(row) for row in rows]
+    return Page(items=items, total=total, page=page, page_size=page_size)

yunke-server/app/api/routers/groups.py

@@ -0,0 +1,91 @@
+"""GET /api/groups, /api/groups/{room_id}/members — chat-group browse endpoints.
+
+* ``GET /api/groups`` -> ``Page[GroupOut]`` filtered by ``channel`` /
+  ``owner_account_id``, ordered by ``last_chat_time desc`` (nulls last) so
+  recently-active groups surface first.
+* ``GET /api/groups/{room_id}/members`` -> ``list[GroupMemberOut]`` — the
+  members of a single group (small set, no pagination needed).
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import sqlalchemy as sa
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_session
+from app.api.schemas import GroupMemberOut, GroupOut, Page
+from app.db.models import ChatGroup, GroupMember
+
+router = APIRouter(prefix="/api", tags=["groups"])
+
+SessionDep = Annotated[AsyncSession, Depends(get_session)]
+PageParam = Annotated[int, Query(ge=1)]
+PageSizeParam = Annotated[int, Query(ge=1, le=100)]
+
+
+@router.get("/groups")
+async def list_groups(
+    session: SessionDep,
+    page: PageParam = 1,
+    page_size: PageSizeParam = 20,
+    channel: Annotated[str | None, Query()] = None,
+    owner_account_id: Annotated[str | None, Query()] = None,
+) -> Page[GroupOut]:
+    """List chat groups with optional ``channel`` / ``owner_account_id`` filters."""
+    conditions = []
+    if channel is not None:
+        conditions.append(ChatGroup.channel == channel)
+    if owner_account_id is not None:
+        conditions.append(ChatGroup.owner_account_id == owner_account_id)
+
+    total_stmt = sa.select(sa.func.count()).select_from(ChatGroup)
+    if conditions:
+        total_stmt = total_stmt.where(*conditions)
+    total = (await session.execute(total_stmt)).scalar_one()
+
+    list_stmt = sa.select(ChatGroup)
+    if conditions:
+        list_stmt = list_stmt.where(*conditions)
+    list_stmt = (
+        list_stmt.order_by(
+            sa.nullslast(ChatGroup.last_chat_time.desc()),
+            ChatGroup.room_id.asc(),
+        )
+        .limit(page_size)
+        .offset((page - 1) * page_size)
+    )
+    rows = (await session.execute(list_stmt)).scalars().all()
+    items = [GroupOut.model_validate(row) for row in rows]
+    return Page(items=items, total=total, page=page, page_size=page_size)
+
+
+@router.get("/groups/{room_id}/members")
+async def list_group_members(
+    room_id: str, session: SessionDep
+) -> list[GroupMemberOut]:
+    """Return the members of a single group (plain list).
+
+    Ordered by ``member_id`` for stable rendering. Returns ``404`` when no such
+    group exists so the frontend can distinguish "missing room" from "empty
+    room".
+    """
+    exists = (
+        await session.execute(
+            sa.select(sa.func.count())
+            .select_from(ChatGroup)
+            .where(ChatGroup.room_id == room_id)
+        )
+    ).scalar_one()
+    if not exists:
+        raise HTTPException(status_code=404, detail="group not found")
+
+    stmt = (
+        sa.select(GroupMember)
+        .where(GroupMember.room_id == room_id)
+        .order_by(GroupMember.member_id.asc())
+    )
+    rows = (await session.execute(stmt)).scalars().all()
+    return [GroupMemberOut.model_validate(row) for row in rows]

yunke-server/app/api/routers/messages.py

@@ -0,0 +1,81 @@
+"""GET /api/messages — chat timeline list (WeChat + WhatsApp).
+
+Read-only query over the mirrored ``message`` table. Filters:
+
+* ``channel``              — ``wechat`` / ``whatsapp``.
+* ``owner_account_id``     — owning staff account (wxId / uid).
+* ``talker_id`` (1:1) OR ``room_id`` (group) — the conversation anchor. Both
+  may be supplied (AND), but typically the frontend sends exactly one.
+* ``start`` / ``end``      — ms-epoch window compared against ``timestamp``
+  (inclusive on both ends).
+
+Ordered by ``timestamp asc`` so the timeline renders oldest-first. The index
+``ix_message_channel_owner_talker_time`` covers the hot path
+``(channel, owner_account_id, talker_id, timestamp)``.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import sqlalchemy as sa
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_session
+from app.api.schemas import MessageOut, Page
+from app.db.models import Message
+
+router = APIRouter(prefix="/api", tags=["messages"])
+
+SessionDep = Annotated[AsyncSession, Depends(get_session)]
+PageParam = Annotated[int, Query(ge=1)]
+PageSizeParam = Annotated[int, Query(ge=1, le=100)]
+
+
+@router.get("/messages")
+async def list_messages(
+    session: SessionDep,
+    page: PageParam = 1,
+    page_size: PageSizeParam = 50,
+    channel: Annotated[str | None, Query()] = None,
+    owner_account_id: Annotated[str | None, Query()] = None,
+    talker_id: Annotated[str | None, Query()] = None,
+    room_id: Annotated[str | None, Query()] = None,
+    start: Annotated[int | None, Query(ge=0)] = None,
+    end: Annotated[int | None, Query(ge=0)] = None,
+) -> Page[MessageOut]:
+    """List messages for a timeline (ordered by ``timestamp asc``)."""
+    conditions = []
+    if channel is not None:
+        conditions.append(Message.channel == channel)
+    if owner_account_id is not None:
+        conditions.append(Message.owner_account_id == owner_account_id)
+    if talker_id is not None:
+        conditions.append(Message.talker_id == talker_id)
+    if room_id is not None:
+        conditions.append(Message.room_id == room_id)
+    if start is not None:
+        conditions.append(Message.timestamp >= start)
+    if end is not None:
+        conditions.append(Message.timestamp <= end)
+
+    total_stmt = sa.select(sa.func.count()).select_from(Message)
+    if conditions:
+        total_stmt = total_stmt.where(*conditions)
+    total = (await session.execute(total_stmt)).scalar_one()
+
+    list_stmt = sa.select(Message)
+    if conditions:
+        list_stmt = list_stmt.where(*conditions)
+    list_stmt = (
+        list_stmt.order_by(
+            sa.nullslast(Message.timestamp.asc()),
+            Message.msg_id.asc(),
+        )
+        .limit(page_size)
+        .offset((page - 1) * page_size)
+    )
+    rows = (await session.execute(list_stmt)).scalars().all()
+    items = [MessageOut.model_validate(row) for row in rows]
+    return Page(items=items, total=total, page=page, page_size=page_size)

yunke-server/app/api/routers/organization.py

@@ -0,0 +1,137 @@
+"""GET /api/departments, /api/staff, /api/accounts — organization browse endpoints.
+
+Read-only queries over the mirrored ``department``, ``staff``,
+``wechat_account`` and ``whatsapp_account`` tables.
+
+* ``GET /api/departments`` -> ``list[DepartmentOut]`` ordered by ``path`` so
+  the frontend can assemble the tree with a stable traversal order.
+* ``GET /api/staff`` -> ``Page[StaffOut]`` with optional ``department_id``
+  and ``is_on_job`` filters.
+* ``GET /api/accounts`` -> ``Page[AccountOut]`` projecting both staff-messaging
+  account tables onto a unified shape (see :class:`AccountOut`). The optional
+  ``channel`` filter restricts to one of ``wechat`` / ``whatsapp``; when
+  omitted, both tables are unioned in memory. Staff-account volumes are modest
+  (tens to low hundreds of rows), so the in-memory merge is cheap and keeps
+  the API contract simple.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import sqlalchemy as sa
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_session
+from app.api.schemas import AccountOut, DepartmentOut, Page, StaffOut
+from app.db.models import Department, Staff, WechatAccount, WhatsappAccount
+
+router = APIRouter(prefix="/api", tags=["organization"])
+
+SessionDep = Annotated[AsyncSession, Depends(get_session)]
+PageParam = Annotated[int, Query(ge=1)]
+PageSizeParam = Annotated[int, Query(ge=1, le=100)]
+
+
+@router.get("/departments")
+async def list_departments(session: SessionDep) -> list[DepartmentOut]:
+    """Return every department ordered by ``path`` (nulls last).
+
+    A plain list — not paginated — because the frontend rebuilds the tree from
+    ``parent_id``/``path`` and pagination would split the topology awkwardly.
+    """
+    stmt = sa.select(Department).order_by(
+        sa.nullslast(Department.path.asc()), Department.dept_id.asc()
+    )
+    rows = (await session.execute(stmt)).scalars().all()
+    return [DepartmentOut.model_validate(row) for row in rows]
+
+
+@router.get("/staff")
+async def list_staff(
+    session: SessionDep,
+    page: PageParam = 1,
+    page_size: PageSizeParam = 20,
+    department_id: Annotated[str | None, Query()] = None,
+    is_on_job: Annotated[bool | None, Query()] = None,
+) -> Page[StaffOut]:
+    """List staff with optional ``department_id`` / ``is_on_job`` filters."""
+    conditions = []
+    if department_id is not None:
+        conditions.append(Staff.dept_id == department_id)
+    if is_on_job is not None:
+        conditions.append(Staff.is_on_job.is_(is_on_job))
+
+    total_stmt = sa.select(sa.func.count()).select_from(Staff)
+    if conditions:
+        total_stmt = total_stmt.where(*conditions)
+    total = (await session.execute(total_stmt)).scalar_one()
+
+    list_stmt = sa.select(Staff)
+    if conditions:
+        list_stmt = list_stmt.where(*conditions)
+    list_stmt = (
+        list_stmt.order_by(Staff.user_id.asc())
+        .limit(page_size)
+        .offset((page - 1) * page_size)
+    )
+    rows = (await session.execute(list_stmt)).scalars().all()
+    items = [StaffOut.model_validate(row) for row in rows]
+    return Page(items=items, total=total, page=page, page_size=page_size)
+
+
+@router.get("/accounts")
+async def list_accounts(
+    session: SessionDep,
+    page: PageParam = 1,
+    page_size: PageSizeParam = 20,
+    channel: Annotated[str | None, Query()] = None,
+) -> Page[AccountOut]:
+    """List staff messaging accounts (WeChat / WhatsApp) in a unified shape.
+
+    ``channel`` optional; one of ``wechat`` / ``whatsapp``. When omitted, both
+    tables are merged in memory. Pagination is applied after the merge using a
+    stable ``(channel, account_id)`` ordering.
+    """
+    selected_channels = [channel] if channel else ["wechat", "whatsapp"]
+
+    rows: list[AccountOut] = []
+    if "wechat" in selected_channels:
+        result = (await session.execute(sa.select(WechatAccount))).scalars().all()
+        for r in result:
+            rows.append(
+                AccountOut(
+                    channel="wechat",
+                    account_id=r.wx_id,
+                    nickname=r.nick_name,
+                    user_id=r.user_id,
+                    user_name=r.user_name,
+                    phone=r.phone,
+                    contacts_num=r.contacts_num,
+                    group_num=r.group_num,
+                    is_on_job=r.is_on_job,
+                )
+            )
+    if "whatsapp" in selected_channels:
+        result = (await session.execute(sa.select(WhatsappAccount))).scalars().all()
+        for r in result:
+            rows.append(
+                AccountOut(
+                    channel="whatsapp",
+                    account_id=r.uid,
+                    nickname=r.nick_name,
+                    user_id=r.user_id,
+                    user_name=r.user_name,
+                    phone=r.phone,
+                    contacts_num=r.contacts_num,
+                    group_num=r.group_num,
+                    is_on_job=r.is_on_job,
+                )
+            )
+
+    rows.sort(key=lambda a: (a.channel, a.account_id))
+    total = len(rows)
+    start = (page - 1) * page_size
+    items = rows[start : start + page_size]
+    return Page(items=items, total=total, page=page, page_size=page_size)

yunke-server/app/api/routers/sms.py

@@ -0,0 +1,63 @@
+"""GET /api/sms — SMS log list.
+
+Read-only query over the mirrored ``sms`` table. Filters: ``user_id`` and a
+ms-epoch ``[start, end]`` window compared against ``create_time`` (inclusive).
+Ordered by ``create_time desc`` (nulls last) — newest first.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import sqlalchemy as sa
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_session
+from app.api.schemas import Page, SmsOut
+from app.db.models import Sms
+
+router = APIRouter(prefix="/api", tags=["sms"])
+
+SessionDep = Annotated[AsyncSession, Depends(get_session)]
+PageParam = Annotated[int, Query(ge=1)]
+PageSizeParam = Annotated[int, Query(ge=1, le=100)]
+
+
+@router.get("/sms")
+async def list_sms(
+    session: SessionDep,
+    page: PageParam = 1,
+    page_size: PageSizeParam = 20,
+    user_id: Annotated[str | None, Query()] = None,
+    start: Annotated[int | None, Query(ge=0)] = None,
+    end: Annotated[int | None, Query(ge=0)] = None,
+) -> Page[SmsOut]:
+    """List SMS rows with optional filters, newest first."""
+    conditions = []
+    if user_id is not None:
+        conditions.append(Sms.user_id == user_id)
+    if start is not None:
+        conditions.append(Sms.create_time >= start)
+    if end is not None:
+        conditions.append(Sms.create_time <= end)
+
+    total_stmt = sa.select(sa.func.count()).select_from(Sms)
+    if conditions:
+        total_stmt = total_stmt.where(*conditions)
+    total = (await session.execute(total_stmt)).scalar_one()
+
+    list_stmt = sa.select(Sms)
+    if conditions:
+        list_stmt = list_stmt.where(*conditions)
+    list_stmt = (
+        list_stmt.order_by(
+            sa.nullslast(Sms.create_time.desc()),
+            Sms.sms_id.asc(),
+        )
+        .limit(page_size)
+        .offset((page - 1) * page_size)
+    )
+    rows = (await session.execute(list_stmt)).scalars().all()
+    items = [SmsOut.model_validate(row) for row in rows]
+    return Page(items=items, total=total, page=page, page_size=page_size)

yunke-server/app/api/routers/sync.py

@@ -0,0 +1,52 @@
+"""GET /api/sync/status — sync monitor (cursors + recent runs).
+
+Returns the current :class:`SyncState` cursors and the most recent N
+:class:`SyncRun` audit rows (default 20). Read-only — purely for the operator
+dashboard.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import sqlalchemy as sa
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_session
+from app.api.schemas import SyncRunOut, SyncStateOut, SyncStatusOut
+from app.db.models import SyncRun, SyncState
+
+router = APIRouter(prefix="/api/sync", tags=["sync"])
+
+SessionDep = Annotated[AsyncSession, Depends(get_session)]
+RecentLimitParam = Annotated[int, Query(ge=1, le=200)]
+
+
+@router.get("/status")
+async def sync_status(
+    session: SessionDep,
+    recent: RecentLimitParam = 20,
+) -> SyncStatusOut:
+    """Return sync cursors plus the most recent ``recent`` runs."""
+    state_rows = (
+        await session.execute(
+            sa.select(SyncState).order_by(
+                SyncState.entity_type.asc(),
+                sa.nullslast(SyncState.channel.asc()),
+                sa.nullslast(SyncState.scope_id.asc()),
+            )
+        )
+    ).scalars().all()
+    states = [SyncStateOut.model_validate(row) for row in state_rows]
+
+    run_rows = (
+        await session.execute(
+            sa.select(SyncRun)
+            .order_by(SyncRun.started_at.desc(), SyncRun.run_id.desc())
+            .limit(recent)
+        )
+    ).scalars().all()
+    recent_runs = [SyncRunOut.model_validate(row) for row in run_rows]
+
+    return SyncStatusOut(states=states, recent_runs=recent_runs)

yunke-server/app/api/schemas.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import datetime as dt
 from typing import Generic, TypeVar
 
 from pydantic import BaseModel, ConfigDict
@@ -41,3 +42,182 @@ class Page(BaseModel, Generic[T]):
     total: int
     page: int
     page_size: int
+
+
+# ---------------------------------------------------------------------------
+# Organization & people
+# ---------------------------------------------------------------------------
+
+
+class DepartmentOut(BaseModel):
+    """云客 department node — frontend builds the tree from ``parent_id``/``path``."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    dept_id: str
+    parent_id: str | None = None
+    name: str | None = None
+    path: str | None = None
+
+
+class StaffOut(BaseModel):
+    """Staff member (employee) row."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    user_id: str
+    name: str | None = None
+    phone: str | None = None
+    sale_phone: str | None = None
+    dept_id: str | None = None
+    is_on_job: bool | None = None
+
+
+class AccountOut(BaseModel):
+    """Unified staff messaging account (WeChat or WhatsApp).
+
+    The two source tables (:class:`WechatAccount`, :class:`WhatsappAccount`)
+    have different PK / column names; this view projects both onto a single
+    shape keyed by ``channel`` + ``account_id`` so the frontend can render one
+    list. Built explicitly in the route handler (not via ``from_attributes``)
+    because no single ORM row carries this schema.
+    """
+
+    channel: str
+    account_id: str
+    nickname: str | None = None
+    user_id: str | None = None
+    user_name: str | None = None
+    phone: str | None = None
+    contacts_num: int | None = None
+    group_num: int | None = None
+    is_on_job: bool | None = None
+
+
+# ---------------------------------------------------------------------------
+# Communication entities
+# ---------------------------------------------------------------------------
+
+
+class MessageOut(BaseModel):
+    """Chat timeline row — a single message (text/media/voice/...)."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    msg_id: str
+    channel: str
+    owner_account_id: str | None = None
+    talker_id: str | None = None
+    room_id: str | None = None
+    is_send: bool | None = None
+    type: str | None = None
+    type_raw: int | None = None
+    text: str | None = None
+    file_url: str | None = None
+    sender_name: str | None = None
+    sender_head_url: str | None = None
+    timestamp: int | None = None
+
+
+class GroupOut(BaseModel):
+    """Chat group summary row."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    room_id: str
+    channel: str
+    room_name: str | None = None
+    owner_account_id: str | None = None
+    owner_account_nickname: str | None = None
+    member_count: int | None = None
+    message_count: int | None = None
+    last_chat_time: int | None = None
+
+
+class GroupMemberOut(BaseModel):
+    """Member of a chat group (composite PK: channel + room_id + member_id)."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    channel: str
+    room_id: str
+    member_id: str
+    nickname: str | None = None
+    display_name: str | None = None
+    avatar: str | None = None
+
+
+class PhoneCallOut(BaseModel):
+    """Phone / voice call record. ``channel`` is the call-type."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    call_id: str
+    channel: str
+    start_call_time: int | None = None
+    call_duration: int | None = None
+    call_status: int | None = None
+    incoming_call: int | None = None
+    user_id: str | None = None
+    user_id_name: str | None = None
+    call_number: str | None = None
+    sim_phone: str | None = None
+
+
+class SmsOut(BaseModel):
+    """SMS log row."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    sms_id: str
+    customer_phone: str | None = None
+    content_preview: str | None = None
+    sender: str | None = None
+    direction: int | None = None
+    user_id: str | None = None
+    receive_name: str | None = None
+    create_time: int | None = None
+    sim_phone: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Sync monitor
+# ---------------------------------------------------------------------------
+
+
+class SyncStateOut(BaseModel):
+    """Resumable sync cursor (one per entity/channel/scope)."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    state_id: int
+    entity_type: str
+    channel: str | None = None
+    scope_id: str | None = None
+    last_version: str | None = None
+    last_timestamp: int | None = None
+    last_synced_at: dt.datetime | None = None
+
+
+class SyncRunOut(BaseModel):
+    """Audit row for a single sync execution."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    run_id: int
+    entity_type: str
+    channel: str | None = None
+    scope_id: str | None = None
+    status: str
+    started_at: dt.datetime
+    finished_at: dt.datetime | None = None
+    records_fetched: int
+    records_upserted: int
+    error: str | None = None
+
+
+class SyncStatusOut(BaseModel):
+    """Aggregate monitor payload — current cursors plus recent runs."""
+
+    states: list[SyncStateOut]
+    recent_runs: list[SyncRunOut]