feat(calls): 微信语音列表加今日统计卡片+通话时间范围筛选+客户跳转带通话时间定位(对齐云客)

- GET /api/calls/stats:今日(Asia/Shanghai)好友呼入/外呼量+群量+时长聚合(@chatroom判群)
- CallList:5张统计卡片(仅微信语音tab)+datetimerange筛选(服务端start/end)+viewCallCustomer带?start定位
- TDD新增stats聚合测试,全量绿

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

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

@@ -9,6 +9,7 @@ Ordered by ``start_call_time desc`` (nulls last) — most recent calls first.
 
 from __future__ import annotations
 
+import datetime as dt
 from typing import Annotated, Literal
 
 import sqlalchemy as sa
@@ -16,7 +17,7 @@ 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.api.schemas import CallStatsOut, Page, PhoneCallOut
 from app.db.models import PhoneCall
 
 router = APIRouter(prefix="/api", tags=["calls"])
@@ -26,6 +27,42 @@ PageParam = Annotated[int, Query(ge=1)]
 PageSizeParam = Annotated[int, Query(ge=1, le=100)]
 
 
+@router.get("/calls/stats")
+async def call_stats(session: SessionDep) -> CallStatsOut:
+    """今日(Asia/Shanghai)微信语音统计卡片 — 对齐云客语音列表顶部。
+
+    好友/群按 ``call_number`` 是否以 ``@chatroom`` 结尾(与 ``scope`` 同判据,
+    与云客 isRoom 实测等价);呼入/出按 ``incoming_call``(1=呼入/0=呼出,
+    None 不计)。
+    """
+    # Asia/Shanghai (UTC+8) 的今日 00:00 → ms epoch,与 /api/sessions 的
+    # today_start 同一约定(部署时区无关)
+    shanghai_now = dt.datetime.now(dt.UTC) + dt.timedelta(hours=8)
+    shanghai_midnight = shanghai_now.replace(hour=0, minute=0, second=0, microsecond=0)
+    today_start_ms = int((shanghai_midnight - dt.timedelta(hours=8)).timestamp() * 1000)
+
+    is_room = PhoneCall.call_number.endswith("@chatroom")
+    base = [PhoneCall.channel == "voice_call", PhoneCall.start_call_time >= today_start_ms]
+
+    async def _count(*extra) -> int:
+        stmt = sa.select(sa.func.count()).select_from(PhoneCall).where(*base, *extra)
+        return (await session.execute(stmt)).scalar_one()
+
+    async def _duration(*extra) -> int:
+        stmt = sa.select(sa.func.coalesce(sa.func.sum(PhoneCall.call_duration), 0)).where(*base, *extra)
+        return (await session.execute(stmt)).scalar_one()
+
+    friend = ~is_room
+    return CallStatsOut(
+        friend_incoming=await _count(friend, PhoneCall.incoming_call == 1),
+        friend_outgoing=await _count(friend, PhoneCall.incoming_call == 0),
+        group_count=await _count(is_room),
+        friend_incoming_duration=await _duration(friend, PhoneCall.incoming_call == 1),
+        friend_outgoing_duration=await _duration(friend, PhoneCall.incoming_call == 0),
+        group_duration=await _duration(is_room),
+    )
+
+
 @router.get("/calls")
 async def list_calls(
     session: SessionDep,

yunke-server/app/api/schemas.py

@@ -194,6 +194,20 @@ class GroupMemberOut(BaseModel):
     avatar: str | None = None
 
 
+class CallStatsOut(BaseModel):
+    """今日微信语音统计卡片(GET /api/calls/stats,对齐云客语音列表顶部)。
+
+    好友呼入/外呼量与时长、群语音量与群录音时长;时长单位秒(call_duration 累加)。
+    """
+
+    friend_incoming: int
+    friend_outgoing: int
+    group_count: int
+    friend_incoming_duration: int
+    friend_outgoing_duration: int
+    group_duration: int
+
+
 class PhoneCallOut(BaseModel):
     """Phone / voice call record. ``channel`` is the call-type.
 

yunke-server/tests/test_api_calls.py

@@ -347,3 +347,37 @@ async def test_scope_invalid_value_rejected(make_client):
     client = await make_client(_seed_voice_scopes)
     r = await client.get("/api/calls", params={"scope": "bogus"})
     assert r.status_code == 422
+
+
+# ---------------------------------------------------------------------------
+# GET /api/calls/stats — 微信语音列表顶部统计卡片(今日,对齐云客)
+# ---------------------------------------------------------------------------
+
+async def _seed_voice_stats(session: AsyncSession) -> None:
+    """今日(按 Asia/Shanghai)语音:好友呼入2/呼出1/群1,呼出接通时长60s。"""
+    import datetime as dt
+
+    # today_start 计算依赖时区,直接用一个肯定在"今天"的远未来时间戳构造会跨天;
+    # 改用相对 now 的 ms —— 种子用比 now 晚 1ms 保证落进今天窗口。
+    soon = int(dt.datetime.now(dt.UTC).timestamp() * 1000) + 1000
+    session.add_all([
+        PhoneCall(call_id="s1", channel="voice_call", start_call_time=soon, incoming_call=1, call_duration=30, call_number="q1"),
+        PhoneCall(call_id="s2", channel="voice_call", start_call_time=soon, incoming_call=1, call_duration=10, call_number="q2"),
+        PhoneCall(call_id="s3", channel="voice_call", start_call_time=soon, incoming_call=0, call_duration=60, call_number="q3"),
+        PhoneCall(call_id="s4", channel="voice_call", start_call_time=soon, incoming_call=1, call_duration=5, call_number="r@chatroom"),
+        PhoneCall(call_id="s5_old", channel="voice_call", start_call_time=1000, incoming_call=1, call_duration=99, call_number="q_old"),
+    ])
+    await session.commit()
+
+
+async def test_calls_stats_today_aggregation(make_client):
+    client = await make_client(_seed_voice_stats)
+    r = await client.get("/api/calls/stats")
+    assert r.status_code == 200
+    s = r.json()
+    assert s["friend_incoming"] == 2
+    assert s["friend_outgoing"] == 1
+    assert s["group_count"] == 1
+    assert s["friend_outgoing_duration"] == 60
+    assert s["friend_incoming_duration"] == 40
+    assert s["group_duration"] == 5