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(

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

@@ -2,8 +2,9 @@
 
 * ``GET /api/groups`` -> ``Page[GroupOut]`` filtered by ``channel`` /
   ``owner_account_id`` / ``user_id`` (the latter mapping to the
-  ``owner_user_id`` column), ordered by ``last_chat_time desc`` (nulls last)
-  so recently-active groups surface first.
+  ``owner_user_id`` column) and ``q`` (substring match on ``room_name``,
+  ``%``/``_`` escaped as literals — the 通讯录群 tab search box), ordered by
+  ``last_chat_time desc`` (nulls last) so recently-active groups surface first.
 * ``GET /api/groups/{room_id}/members`` -> ``list[GroupMemberOut]`` — the
   members of a single group (small set, no pagination needed).
 """
@@ -36,20 +37,26 @@ async def list_groups(
     owner_account_id: Annotated[str | None, Query()] = None,
     user_id: Annotated[str | None, Query()] = None,
     room_id: Annotated[str | None, Query()] = None,
+    q: Annotated[str | None, Query()] = None,
 ) -> Page[GroupOut]:
     """List chat groups with optional ``channel`` / ``owner_account_id`` /
-    ``user_id`` / ``room_id`` filters.
+    ``user_id`` / ``room_id`` / ``q`` filters.
 
     ``user_id`` maps to the ``ChatGroup.owner_user_id`` column (the staff
     ``userId`` who owns the chatroom account), mirroring the ``user_id``
     filter on ``GET /api/customers``. ``room_id`` is an exact-match single-
-    row lookup (chat page group-name resolution).
+    row lookup (chat page group-name resolution). ``q`` is a substring match
+    on ``room_name``.
     """
     conditions = []
     if channel is not None:
         conditions.append(ChatGroup.channel == channel)
     if owner_account_id is not None:
         conditions.append(ChatGroup.owner_account_id == owner_account_id)
+    if q:
+        # LIKE 通配符转义: %/_ 按字面匹配(镜像 customers/messages 的 q 处理)
+        escaped = q.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+        conditions.append(ChatGroup.room_name.like(f"%{escaped}%", escape="\\"))
     if room_id is not None:
         conditions.append(ChatGroup.room_id == room_id)
     if user_id is not None: