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

"""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).
* ``msg_type``             — normalized type label (``text`` / ``image`` / ...,
  see ``_MSG_TYPE_FILTER``). Unknown values are rejected with 422.
* ``q``                    — substring match on ``text`` (``%``/``_`` escaped
  as literals).
* ``order``                — ``asc`` (default, oldest-first timeline) /
  ``desc`` (newest-first; 聊天窗首屏「取最新一页」用它,反向索引扫描恒
  O(page_size),避开 ASC 深 OFFSET 逐行回表——2026-09-07 实测 1 万条对话
  末页 2.5s、4 万条群 10.7s 撞前端 15s 超时)。
* ``before_ts``/``before_id`` — keyset 游标(成对,可选):只取严格早于
  ``(before_ts, before_id)`` 的消息(排序列 (timestamp, msg_id) 全序,
  平手按 msg_id 决胜)。「加载更多」上翻历史用它,每页恒 O(page_size);
  两参必须成对,单传任一 422。

Ordered by ``(timestamp, msg_id)`` in the requested direction. The index
``ix_message_channel_owner_talker_time`` covers the 1:1 hot path
``(channel, owner_account_id, talker_id, timestamp)``; group queries filter
``channel + room_id`` without owner(群聊 owner 错位,见 ChatMain queryFor),
served by ``ix_message_channel_room_time``.
"""

from __future__ import annotations

from typing import Annotated, Literal

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 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)]

# msg_type 参数值 → 覆盖的 Message.type 标签集合(对齐云客 10 类下拉;
# mini_program 暂无样本行也保留, 查空是数据现实)
_MSG_TYPE_FILTER: dict[str, tuple[str, ...]] = {
    "text": ("text",),
    "image": ("image", "image_legacy"),
    "voice": ("voice",),
    "video": ("video",),
    "link": ("link",),
    "file": ("file",),
    "red_packet": ("red_packet",),
    "transfer": ("transfer",),
    "voice_call": ("voice_call",),
    "video_call": ("video_call",),
    "mini_program": ("mini_program",),
}

# 派生而非重复罗列:加一类只改上面的 dict,Literal 与 422 校验自动跟上
# (两处手写曾会漂移——漏一边即 500/422 不一致)
MsgTypeParam = Literal[tuple(_MSG_TYPE_FILTER)]


@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,
    msg_type: Annotated[MsgTypeParam | None, Query()] = None,
    q: Annotated[str | None, Query()] = None,
    order: Annotated[Literal["asc", "desc"], Query()] = "asc",
    before_ts: Annotated[int | None, Query(ge=0)] = None,
    before_id: Annotated[str | None, Query()] = None,
) -> Page[MessageOut]:
    """List messages for a timeline (ordered by ``(timestamp, msg_id)``)."""
    if (before_ts is None) != (before_id is None):
        raise HTTPException(
            status_code=422, detail="before_ts 与 before_id 必须成对使用"
        )

    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)
    if msg_type is not None:
        conditions.append(Message.type.in_(_MSG_TYPE_FILTER[msg_type]))
    if q:
        # LIKE 通配符转义: %/_ 按字面匹配
        escaped = q.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
        conditions.append(Message.text.like(f"%{escaped}%", escape="\\"))
    if before_ts is not None:
        # keyset 游标:严格早于 (before_ts, before_id) 的全序前缀,平手按
        # msg_id 决胜——与 order_by 同一全序,翻页无缝
        conditions.append(
            sa.or_(
                Message.timestamp < before_ts,
                sa.and_(Message.timestamp == before_ts, Message.msg_id < before_id),
            )
        )

    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()

    ts_order = (
        Message.timestamp.desc() if order == "desc" else Message.timestamp.asc()
    )
    id_order = Message.msg_id.desc() if order == "desc" else Message.msg_id.asc()
    list_stmt = sa.select(Message)
    if conditions:
        list_stmt = list_stmt.where(*conditions)
    list_stmt = (
        list_stmt.order_by(sa.nullslast(ts_order), id_order)
        .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)