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/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