feat(scraper): WA 群 scraper(businessFriendList+type=1,待风控重置后实测)

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

yunke-server/app/scraper/whatsapp.py

@@ -9,6 +9,12 @@ Endpoints covered:
   and yields normalized dicts ready to be upserted into
   :class:`app.db.models.Customer` with ``channel="whatsapp"``. Page-number
   pagination.
+* :func:`scrape_whatsapp_groups` — wraps the SAME ``businessFriendList``
+  endpoint with ``type="1"`` to select WA chat-groups (``"0"`` selects
+  friends) and yields normalized :class:`app.db.models.ChatGroup` dicts with
+  ``channel="whatsapp"``. The ``type`` group switch is UNVERIFIED (see the
+  section docstring) — the structure is correct, only the param name may need
+  a post-risk-control adjustment.
 * :func:`scrape_whatsapp_messages` — wraps ``POST /qqweb/WhatsAppUser/chatRecords``
   and yields normalized chat-message dicts with ``channel="whatsapp"``.
   Backward-cursor pagination by timestamp (the same strategy as WeChat
@@ -34,13 +40,15 @@ from typing import Any
 
 from app.scraper.base import paginate_by_cursor, paginate_by_page
 from app.scraper.parsers import coerce_int_or_none, normalize_whatsapp_type, parse_datetime_to_ms
+from app.scraper.wechat import _normalize_chat_group
 from app.session.yunke_client import YunkeClient
 
 __all__ = [
+    "scrape_wa_voice_calls",
     "scrape_whatsapp_accounts",
     "scrape_whatsapp_friends",
+    "scrape_whatsapp_groups",
     "scrape_whatsapp_messages",
-    "scrape_wa_voice_calls",
 ]
 
 WHATSAPP_ACCOUNTS_PATH = "/qqweb/WhatsAppUser/businessSalesList"
@@ -317,6 +325,120 @@ async def scrape_whatsapp_friends(
         yield _normalize_whatsapp_friend(record)
 
 
+# ===========================================================================
+# Chat-group scraper — POST /qqweb/WhatsAppUser/businessFriendList
+# with ``type="1"`` (groups). ``type="0"`` selects friends (see above).
+#
+# UNVERIFIED (云客 risk-control blocking live API calls as of 2026-08-11):
+# the group-type body parameter is inferred, not captured. The WA friends
+# body sends ``type="0"`` and the WA CRM SPA exposes two parallel routes —
+# ``friendlist/0`` (friends) and ``friendlist/1`` (groups) — so by symmetry
+# ``type="1"`` is the most likely group selector. If the post-risk-control
+# smoke returns 0 rows, try alternative param names BEFORE concluding the
+# endpoint is wrong: ``friendType: "1"``, ``friendTypeYunke: "2"`` (the
+# WeChat switch value), or a sibling path entirely. The field mapping and
+# pagination structure here are correct regardless; only the switch param
+# name may need adjustment.
+# ===========================================================================
+
+
+def _build_wa_group_body(
+    page_num: int, page_size: int, *, department_id: str = ""
+) -> dict[str, Any]:
+    """Build the ``businessFriendList`` request body for chat-groups (type=1).
+
+    Identical to :func:`_build_wa_friend_body` except for ``type``: ``"1"``
+    selects groups (``"0"`` selects friends). UNVERIFIED — see the section
+    docstring above for the post-risk-control verification plan. ``departmentId``
+    is omitted when blank so a test/fixture call without one still forms a
+    valid body (the live endpoint requires it for non-empty results, same as
+    the friends variant).
+    """
+    body: dict[str, Any] = {
+        "searchInfo": "",
+        "friendSearchInfo": "",
+        "page": page_num,
+        "pageSize": page_size,
+        # UNVERIFIED group-type switch — see section docstring.
+        "type": "1",
+    }
+    if department_id:
+        body["departmentId"] = department_id
+    return body
+
+
+def _normalize_whatsapp_group(record: dict[str, Any]) -> dict[str, Any]:
+    """Map one WA ``businessFriendList`` group record to the ``ChatGroup`` shape.
+
+    Reuses :func:`app.scraper.wechat._normalize_chat_group` for the full field
+    mapping — the WA endpoint returns the SAME field names the WeChat
+    ``friend_list/es`` endpoint does for the group-type switch (``friendWxId``
+    is the ``@chatroom`` id, ``friendWxNickname`` is the group name,
+    ``friendNum`` is the member count, etc.) — then overrides ``channel`` to
+    ``"whatsapp"`` so WA groups are distinguishable from WeChat groups in the
+    shared :class:`app.db.models.ChatGroup` table.
+
+    Member ids are NOT surfaced by this endpoint (only the ``friendNum``
+    count); ``member_ids`` / ``member_ids_list`` are emitted as ``None`` /
+    ``[]`` by the shared WeChat normalizer and left untouched here.
+    """
+    out = _normalize_chat_group(record)
+    out["channel"] = "whatsapp"
+    return out
+
+
+async def scrape_whatsapp_groups(
+    client: YunkeClient,
+    *,
+    department_id: str = "",
+    page_size: int = 50,
+) -> AsyncIterator[dict[str, Any]]:
+    """Yield normalized WhatsApp chat-group records from ``businessFriendList``.
+
+    Mirrors :func:`scrape_whatsapp_friends` but sends ``type="1"`` in the body
+    to select groups (the WA CRM SPA's ``friendlist/1`` route). Shares the
+    friends endpoint's envelope (rows under ``data.overviews``, declared total
+    under ``data.totalCount``), so the same ``_parse_wa_friend_total`` /
+    ``_parse_wa_friend_rows`` helpers are reused.
+
+    Each record is mapped to the ``ChatGroup`` column shape with
+    ``channel="whatsapp"`` (via :func:`_normalize_whatsapp_group`, which reuses
+    the WeChat group normalizer for the field mapping) plus a verbatim
+    ``raw_json`` copy. Member ids are NOT available — ``member_ids`` /
+    ``member_ids_list`` are ``None`` / ``[]``.
+
+    .. note::
+
+       UNVERIFIED (2026-08-11, risk-control): the ``type="1"`` group switch is
+       inferred from the WA SPA's ``friendlist/0`` / ``friendlist/1`` routes,
+       not a live capture. If the post-risk-control smoke returns 0 rows, try
+       ``friendType`` / ``friendTypeYunke`` before concluding the endpoint is
+       wrong. See the section docstring above.
+
+    Parameters
+    ----------
+    client:
+        Authenticated :class:`YunkeClient`. Auth headers / 401 re-login are
+        handled by the client.
+    department_id:
+        Company-root dept id (the ``departmentId`` body field). Required by the
+        live endpoint for non-empty results (same as friends); resolved by the
+        orchestrator when omitted.
+    page_size:
+        Page size to request. Defaults to 50.
+    """
+    async for record in paginate_by_page(
+        client,
+        WHATSAPP_FRIENDS_PATH,
+        page_size=page_size,
+        parse_total=_parse_wa_friend_total,
+        parse_rows=_parse_wa_friend_rows,
+        build_body=_build_wa_group_body,
+        department_id=department_id,
+    ):
+        yield _normalize_whatsapp_group(record)
+
+
 # ===========================================================================
 # Message scraper (M3) — POST /qqweb/WhatsAppUser/chatRecords
 # ===========================================================================