feat(calls): voice_clip 手动匹配(voice_clip↔customer 本地关联写操作)

- VoiceClip: 新增 matched_friend_id 列 (String(128), nullable) + alembic 迁移 b3c4d5e6f7a8
- PATCH /api/voice-clips/{id}/match: friend_id 关联 / null 取消 (本地写, 不回写云客)
- GET /api/voice-clips: 批量解析 matched_friend_name (remark>nickname>real>id)
- VoiceClipModal: 已匹配客户列 + 匹配/取消匹配按钮 + 嵌套客户选择 picker (默认按员工列客户, 名搜索走 /search)
- 测试: 17 passed (新增 7 个 match 用例覆盖 set/clear/name 解析/404)

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

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

@@ -1,9 +1,15 @@
-"""GET /api/voice-clips — 长语音 (voice_clip) list.
+"""GET /api/voice-clips + PATCH /api/voice-clips/{id}/match — 长语音 (voice_clip).
 
-Read-only query over the mirrored ``voice_clip`` table. Powers the
-``VoiceClipModal`` (微信长语音 / WA wavoicecalllist 共用的只读展示 modal).
+``GET /voice-clips`` is a read-only query over the mirrored ``voice_clip``
+table. Powers the ``VoiceClipModal`` (微信长语音 / WA wavoicecalllist 共用的
+只读展示 modal).
 
-Filters (all optional):
+``PATCH /voice-clips/{id}/match`` is the 手动匹配 local write — associates a
+clip with a customer (好友) by storing ``matched_friend_id``. Passing
+``{"friend_id": null}`` clears the association. The match lives only in our
+mirror; nothing is pushed back to 云客.
+
+GET filters (all optional):
 
 * ``user_id``         — exact employee-id match (modal opens from a CallList
   row keyed on the employee). Takes PRECEDENCE over ``user_real_name`` when
@@ -21,15 +27,16 @@ the 云客 modal's default ordering.
 
 from __future__ import annotations
 
-from typing import Annotated
+from typing import Annotated, Any
 
 import sqlalchemy as sa
-from fastapi import APIRouter, Depends, Query
+from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.deps import get_session
 from app.api.schemas import Page, VoiceClipOut
-from app.db.models import VoiceClip
+from app.db.models import Customer, VoiceClip
 
 router = APIRouter(prefix="/api", tags=["voice_clips"])
 
@@ -38,6 +45,42 @@ PageParam = Annotated[int, Query(ge=1)]
 PageSizeParam = Annotated[int, Query(ge=1, le=100)]
 
 
+class MatchBody(BaseModel):
+    """Body for PATCH /voice-clips/{id}/match.
+
+    ``friend_id`` is the customer.friend_id to associate, or ``None`` to clear
+    the existing match. A non-null id that doesn't reference an existing
+    customer row is accepted (no FK is enforced across the mirror tables —
+    ``matched_friend_name`` will simply resolve to the id itself, same fallback
+    as a customer whose name columns are all NULL).
+    """
+
+    friend_id: str | None = None
+
+
+async def _resolve_friend_names(
+    session: AsyncSession, friend_ids: list[str]
+) -> dict[str, str]:
+    """Batch-resolve display names for a set of customer.friend_ids.
+
+    Returns ``{friend_id: name}`` keyed by id. Name precedence matches the rest
+    of the app (see staff_chat_stats): ``remark > nickname > real_name > friend_id``.
+    Empty input -> empty dict (callers default to ``None``).
+    """
+    if not friend_ids:
+        return {}
+    stmt = sa.select(
+        Customer.friend_id,
+        Customer.friend_remark,
+        Customer.friend_nickname,
+        Customer.real_name,
+    ).where(Customer.friend_id.in_(friend_ids))
+    names: dict[str, str] = {}
+    for fid, remark, nick, real in (await session.execute(stmt)).all():
+        names[fid] = remark or nick or real or fid
+    return names
+
+
 @router.get("/voice-clips")
 async def list_voice_clips(
     session: SessionDep,
@@ -85,5 +128,45 @@ async def list_voice_clips(
         .offset((page - 1) * page_size)
     )
     rows = (await session.execute(list_stmt)).scalars().all()
-    items = [VoiceClipOut.model_validate(row) for row in rows]
+
+    # Resolve the matched-customer display names for this page in a single
+    # batched query (one extra round-trip per page, not per row).
+    matched_ids = [r.matched_friend_id for r in rows if r.matched_friend_id]
+    name_map = await _resolve_friend_names(session, matched_ids)
+
+    items = []
+    for row in rows:
+        out = VoiceClipOut.model_validate(row)
+        if row.matched_friend_id:
+            # name_map always has an entry when matched_friend_id was non-null,
+            # but guard anyway: fall back to the id itself when the customer
+            # row was deleted after the match was recorded.
+            out.matched_friend_name = name_map.get(
+                row.matched_friend_id, row.matched_friend_id
+            )
+        items.append(out)
     return Page(items=items, total=total, page=page, page_size=page_size)
+
+
+@router.patch("/voice-clips/{voice_clip_id}/match")
+async def match_voice_clip(
+    session: SessionDep,
+    voice_clip_id: int,
+    body: MatchBody,
+) -> dict[str, Any]:
+    """Associate (or clear) the customer match on a voice_clip.
+
+    LOCAL write only — ``matched_friend_id`` is stored in the mirror's
+    ``voice_clip`` row and never pushed to 云客. ``friend_id=None`` clears an
+    existing match.
+    """
+    clip = await session.get(VoiceClip, voice_clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="voice_clip not found")
+    clip.matched_friend_id = body.friend_id  # None clears the match
+    await session.commit()
+
+    return {
+        "voice_clip_id": voice_clip_id,
+        "matched_friend_id": body.friend_id,
+    }

yunke-server/app/api/schemas.py

@@ -277,6 +277,13 @@ class VoiceClipOut(BaseModel):
     oss_file_name: str | None = None
     mp3_duration: int | None = None
     duration_format: str | None = None
+    # LOCAL-only 手动匹配 (spec §7): the customer.friend_id this clip has been
+    # associated with, or None when unmatched. ``matched_friend_name`` is NOT a
+    # stored column — it's resolved by the GET handler via a Customer lookup
+    # (remark > nickname > real_name > friend_id) so the modal can render the
+    # 「已匹配客户」 column without a second round-trip per row.
+    matched_friend_id: str | None = None
+    matched_friend_name: str | None = None
     raw_json: dict[str, Any] | None = None
 
 

yunke-server/app/db/models.py

@@ -516,6 +516,12 @@ class VoiceClip(Base):
     duration_format: Mapped[str | None] = mapped_column(String(32), nullable=True)
     channel: Mapped[str] = mapped_column(String(16), nullable=False)
 
+    # LOCAL-only manual match: references customer.friend_id when an operator
+    # has associated this clip with a specific customer (好友). NULL = unmatched.
+    # The mirror never pushes this back to 云客 — it's our own bookkeeping for
+    # the 手动匹配 UI (spec §7). Read paths resolve the customer name via join.
+    matched_friend_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
+
     raw_json: Mapped[dict[str, Any] | None] = mapped_column(JSON, nullable=True)
     fetched_at: Mapped[dt.datetime] = _fetched_at()
     updated_at: Mapped[dt.datetime] = _updated_at()

yunke-server/migrations/versions/b3c4d5e6f7a8_voice_clip_matched_friend_id.py

@@ -0,0 +1,35 @@
+"""voice_clip matched_friend_id
+
+Revision ID: b3c4d5e6f7a8
+Revises: a1b2c3d4e5f6
+Create Date: 2026-08-10 00:00:00.000000
+
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b3c4d5e6f7a8'
+down_revision: str | Sequence[str] | None = 'a1b2c3d4e5f6'
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # LOCAL-only 手动匹配 column: references customer.friend_id. NULL = unmatched.
+    # batch_alter_table keeps this portable across SQLite (dev/test, table-recreate)
+    # and MySQL (prod, direct ALTER). See env.py render_as_batch wiring.
+    with op.batch_alter_table('voice_clip', schema=None) as batch_op:
+        batch_op.add_column(
+            sa.Column('matched_friend_id', sa.String(length=128), nullable=True)
+        )
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    with op.batch_alter_table('voice_clip', schema=None) as batch_op:
+        batch_op.drop_column('matched_friend_id')

yunke-server/tests/test_api_voice_clips.py

@@ -1,15 +1,16 @@
-"""Tests for GET /api/voice-clips — 长语音 (voice_clip) list.
+"""Tests for GET /api/voice-clips + PATCH /voice-clips/{id}/match.
 
 Seeds 3 clips (2 wechat for user u1 at end_time 1000/3000, 1 whatsapp for u2
-at end_time 2000) and asserts filters + ordering (``end_time desc``) +
-pagination + the ``user_id``-beats-``user_real_name`` precedence rule.
+at end_time 2000) and asserts GET filters + ordering (``end_time desc``) +
+pagination + the ``user_id``-beats-``user_real_name`` precedence rule, plus
+the 手动匹配 PATCH (set + clear + name resolution + 404 path).
 """
 
 from __future__ import annotations
 
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.db.models import VoiceClip
+from app.db.models import Customer, VoiceClip
 
 
 async def _seed(session: AsyncSession) -> None:
@@ -237,3 +238,122 @@ async def test_raw_json_serializes_verbatim(make_client):
     r_all = await client.get("/api/voice-clips")
     by_id = {it["voice_clip_id"]: it for it in r_all.json()["items"]}
     assert by_id[1]["raw_json"] is None
+
+
+# ---------------------------------------------------------------------------
+# 手动匹配 — PATCH /api/voice-clips/{id}/match
+# ---------------------------------------------------------------------------
+
+
+async def _seed_with_customer(session: AsyncSession) -> None:
+    """Seed 1 clip + 1 matched customer (remark='张三')."""
+    await _seed(session)
+    session.add(
+        Customer(
+            friend_id="fid_remark",
+            channel="wechat",
+            owner_account_id="wx1",
+            friend_remark="张三",
+            friend_nickname="三三",
+            real_name="张三真名",
+        )
+    )
+    await session.commit()
+
+
+async def test_match_returns_payload_and_persists(make_client):
+    """PATCH /match sets matched_friend_id; payload echoes it; GET sees it."""
+    client = await make_client(_seed_with_customer)
+
+    r = await client.patch("/api/voice-clips/1/match", json={"friend_id": "fid_remark"})
+    assert r.status_code == 200
+    body = r.json()
+    assert body == {"voice_clip_id": 1, "matched_friend_id": "fid_remark"}
+
+    # The GET list now reflects the match (cross-request persistence —
+    # requires the PATCH to commit, not just flush).
+    r2 = await client.get("/api/voice-clips", params={"user_id": "u1"})
+    by_id = {it["voice_clip_id"]: it for it in r2.json()["items"]}
+    assert by_id[1]["matched_friend_id"] == "fid_remark"
+    # Resolved via Customer lookup: remark > nickname > real_name > friend_id.
+    assert by_id[1]["matched_friend_name"] == "张三"
+    # The other wechat clip for u1 is still unmatched.
+    assert by_id[3]["matched_friend_id"] is None
+    assert by_id[3]["matched_friend_name"] is None
+
+
+async def test_match_name_falls_back_through_nickname_real_name(make_client):
+    """Name resolution: no remark -> nickname; no nickname -> real_name."""
+
+    async def seed(session: AsyncSession) -> None:
+        await _seed(session)
+        session.add_all(
+            [
+                Customer(
+                    friend_id="fid_nick",
+                    channel="wechat",
+                    friend_nickname="尼克",
+                ),
+                Customer(
+                    friend_id="fid_real",
+                    channel="wechat",
+                    real_name="王五",
+                ),
+            ]
+        )
+        await session.commit()
+
+    client = await make_client(seed)
+    await client.patch("/api/voice-clips/1/match", json={"friend_id": "fid_nick"})
+    await client.patch("/api/voice-clips/3/match", json={"friend_id": "fid_real"})
+
+    r = await client.get("/api/voice-clips", params={"user_id": "u1"})
+    by_id = {it["voice_clip_id"]: it for it in r.json()["items"]}
+    assert by_id[1]["matched_friend_name"] == "尼克"
+    assert by_id[3]["matched_friend_name"] == "王五"
+
+
+async def test_match_with_unknown_friend_id_falls_back_to_id(make_client):
+    """A match pointing at a deleted/unknown customer shows the id as name."""
+    client = await make_client(_seed)
+    await client.patch(
+        "/api/voice-clips/1/match", json={"friend_id": "ghost_customer"}
+    )
+    r = await client.get("/api/voice-clips", params={"user_id": "u1"})
+    by_id = {it["voice_clip_id"]: it for it in r.json()["items"]}
+    assert by_id[1]["matched_friend_id"] == "ghost_customer"
+    assert by_id[1]["matched_friend_name"] == "ghost_customer"
+
+
+async def test_unmatch_clears_friend_id(make_client):
+    """PATCH with friend_id=null clears an existing match."""
+    client = await make_client(_seed_with_customer)
+    await client.patch("/api/voice-clips/1/match", json={"friend_id": "fid_remark"})
+    # Now clear it.
+    r = await client.patch("/api/voice-clips/1/match", json={"friend_id": None})
+    assert r.status_code == 200
+    assert r.json() == {"voice_clip_id": 1, "matched_friend_id": None}
+
+    r2 = await client.get("/api/voice-clips", params={"user_id": "u1"})
+    by_id = {it["voice_clip_id"]: it for it in r2.json()["items"]}
+    assert by_id[1]["matched_friend_id"] is None
+    assert by_id[1]["matched_friend_name"] is None
+
+
+async def test_match_missing_clip_returns_404(make_client):
+    """PATCH on a non-existent voice_clip_id -> 404."""
+    client = await make_client(_seed)
+    r = await client.patch(
+        "/api/voice-clips/999999/match", json={"friend_id": "fid_remark"}
+    )
+    assert r.status_code == 404
+
+
+async def test_match_default_null_body_is_treated_as_unmatch(make_client):
+    """Omitting friend_id from the body clears the match (default None)."""
+    client = await make_client(_seed_with_customer)
+    await client.patch("/api/voice-clips/1/match", json={"friend_id": "fid_remark"})
+    # Empty body -> body.friend_id defaults to None -> unmatch.
+    r = await client.patch("/api/voice-clips/1/match", json={})
+    assert r.status_code == 200
+    assert r.json()["matched_friend_id"] is None