feat(api): /api/customers 加 q 文本搜索(昵称/备注/ID/手机号,LIKE转义) + /api/groups 加 q 群名搜索

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

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

@@ -2,10 +2,11 @@
 
 Read-only query over the mirrored ``customer`` table. Supports filtering by
 ``channel``, ``owner_account_id``, ``user_id``, ``add_time_since`` and
-``last_chat_since`` (direct columns) and ``department_id`` (resolved through
-``customer.user_id`` -> ``staff.dept_id``). Results are ordered by
-``last_chat_time desc`` (nulls last) then ``friend_id`` so the
-most-recently-active contacts surface first.
+``last_chat_since`` (direct columns), ``department_id`` (resolved through
+``customer.user_id`` -> ``staff.dept_id``) and ``q`` (substring match on
+nickname / remark / friend_id / phone, ``%``/``_`` escaped as literals — the
+通讯录 search box). Results are ordered by ``last_chat_time desc`` (nulls
+last) then ``friend_id`` so the most-recently-active contacts surface first.
 """
 
 from __future__ import annotations
@@ -72,6 +73,7 @@ async def list_customers(
     user_id: Annotated[str | None, Query()] = None,
     add_time_since: Annotated[int | None, Query(ge=0)] = None,
     last_chat_since: Annotated[int | None, Query(ge=0)] = None,
+    q: Annotated[str | None, Query()] = None,
 ) -> Page[CustomerOut]:
     """List customers with optional filters and pagination."""
     conditions = []
@@ -79,6 +81,19 @@ async def list_customers(
         conditions.append(Customer.channel == channel)
     if owner_account_id is not None:
         conditions.append(Customer.owner_account_id == owner_account_id)
+    if q:
+        # LIKE 通配符转义: %/_ 按字面匹配(镜像 messages.py 的 q 处理)。
+        # 对齐云客通讯录搜索:昵称/微信号/备注名/手机号四列任一含词即命中。
+        escaped = q.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+        like = f"%{escaped}%"
+        conditions.append(
+            sa.or_(
+                Customer.friend_nickname.like(like, escape="\\"),
+                Customer.friend_remark.like(like, escape="\\"),
+                Customer.friend_id.like(like, escape="\\"),
+                Customer.phone.like(like, escape="\\"),
+            )
+        )
     if department_id is not None:
         # Customer has no dept column; resolve via the owning staff member.
         dept_user_ids = sa.select(Staff.user_id).where(