feat(avatar): add BOXIM chat takeover

digital-avatar-app/backend/services/boxim_client.py

@@ -1,76 +1,178 @@
-"""盒子 IM 客户端 — 封装网易云信 IM 接口调用"""
+"""Client for Huihui's self-hosted BOXIM production APIs."""
+
 import hashlib
 import random
+import secrets
 import string
-from datetime import datetime
-from typing import Optional
+import time
+from datetime import datetime, timedelta, timezone
+from typing import Any
 
 import httpx
 
 
+_CN_TZ = timezone(timedelta(hours=8))
+
+
+class BoxIMError(RuntimeError):
+    def __init__(self, message: str, *, code: Any = None, auth_error: bool = False):
+        super().__init__(message)
+        self.code = code
+        self.auth_error = auth_error
+
+
 class BoxIMClient:
-    """盒子 IM 客户端，通过会会平台网关调用网易云信 IM"""
+    """Exchange Huihui credentials and call BOXIM's private-message API."""
 
     def __init__(self, config: dict):
-        self.base_url = config.get("HUIHUI_IM_BASE_URL", "http://192.168.1.200:60040")
+        self.platform_base_url = config.get(
+            "HUIHUI_PLATFORM_BASE_URL", "https://open.99hui.com/api"
+        ).rstrip("/")
+        self.im_base_url = config.get(
+            "BOXIM_API_BASE_URL", "https://im.99hui.com/api"
+        ).rstrip("/")
         self.app_id = config.get("HUIHUI_APP_ID", "")
         self.access_id = config.get("HUIHUI_ACCESS_ID", "")
         self.access_secret = config.get("HUIHUI_ACCESS_SECRET", "")
+        self.timeout = float(config.get("BOXIM_TIMEOUT_SECONDS", 20))
 
-    def _build_sign_params(self, extra: dict) -> dict:
-        """构建带签名的请求参数（复用 news_service 签名模式）"""
-        nonce = "".join(random.choices(string.ascii_lowercase + string.digits, k=12))
-        timestamp = datetime.now().strftime("%Y%m%d%H%M%S")  # 24小时制
+    def _build_sign_params(self, extra: dict | None = None) -> dict:
+        """Build the same signed form used by Huihui's current production app."""
         params = {
             "appId": self.app_id,
             "accessId": self.access_id,
-            "nonce": nonce,
-            "timestamp": timestamp,
-            **extra,
+            "nonce": "".join(random.choices(string.ascii_lowercase + string.digits, k=12)),
+            "timestamp": datetime.now(_CN_TZ).strftime("%Y%m%d%H%M%S"),
+            "signType": "MD5",
+            "signVersion": "1.0",
+            **(extra or {}),
         }
-        # 计算签名 — 排序 key, 过滤空值, 拼接后加 accessSecret, MD5 大写
-        keys = sorted(params.keys())
+        params.pop("accessSecret", None)
+        params.pop("signature", None)
         sign_parts = []
-        for k in keys:
-            if k in ("signature", "accessSecret"):
+        for key in sorted(params):
+            value = params[key]
+            if value in (None, "", []):
                 continue
-            v = params.get(k)
-            if v and v != "" and v != []:
-                sign_parts.append(f"{k}={v}")
-        sign_str = "&".join(sign_parts) + f"&accessSecret={self.access_secret}"
-        signature = hashlib.md5(sign_str.encode("utf-8")).hexdigest().upper()
-        params["signature"] = signature
-        params["signType"] = "MD5"
-        params["signVersion"] = "1.0"
+            if isinstance(value, list):
+                continue
+            sign_parts.append(f"{key}={value}")
+        sign_source = "&".join(sign_parts) + f"&accessSecret={self.access_secret}"
+        params["signature"] = hashlib.md5(sign_source.encode("utf-8")).hexdigest().upper()
         return params
 
-    async def get_credentials(self, user_id: str) -> Optional[dict]:
-        """获取用户的网易云信 IM 凭证 (accid, token)"""
-        params = self._build_sign_params({"userId": user_id})
-        async with httpx.AsyncClient(timeout=10) as client:
-            r = await client.post(
-                f"{self.base_url}/box/netease",
-                params=params,
-            )
-        data = r.json()
-        if data.get("code") in (0, 200):
-            return data.get("data", {})
-        return None
+    @staticmethod
+    def _response_payload(response: httpx.Response) -> dict:
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise BoxIMError("BOXIM 返回了无效响应") from exc
+        if not isinstance(payload, dict):
+            raise BoxIMError("BOXIM 返回格式不正确")
+        return payload
 
-    async def send_p2p_message(
-        self, from_accid: str, to_accid: str, content: str
-    ) -> bool:
-        """发送单聊消息（文本）"""
-        params = self._build_sign_params({
-            "from": from_accid,
-            "to": to_accid,
-            "msgType": "text",
-            "content": content,
-        })
-        async with httpx.AsyncClient(timeout=10) as client:
-            r = await client.post(
-                f"{self.base_url}/box/message/send/p2p",
-                params=params,
+    async def exchange_access_token(self, huihui_token: str) -> dict:
+        """Exchange a production Huihui token for a BOXIM access token."""
+        if not huihui_token:
+            raise BoxIMError("缺少会会登录凭证", auth_error=True)
+        if not (self.app_id and self.access_id and self.access_secret):
+            raise BoxIMError("会会开放平台凭证未配置", auth_error=True)
+
+        headers = {
+            "Authorization": f"Bearer {huihui_token}",
+            "appId": self.app_id,
+            "windowAppId": self.app_id,
+        }
+        async with httpx.AsyncClient(timeout=self.timeout, follow_redirects=True) as client:
+            response = await client.post(
+                f"{self.platform_base_url}/im/box/netease",
+                headers=headers,
+                data=self._build_sign_params(),
             )
-        data = r.json()
-        return data.get("code") in (0, 200)
+        payload = self._response_payload(response)
+        data = payload.get("data") or {}
+        code = payload.get("code")
+        if response.status_code >= 400 or code not in (0, 200, "0", "200"):
+            raise BoxIMError(
+                payload.get("message") or "BOXIM 授权失败",
+                code=code or response.status_code,
+                auth_error=response.status_code in (400, 401, 403)
+                or code in (400, 401, 40100, 403, "400", "401", "40100", "403"),
+            )
+        if not data.get("accessToken"):
+            raise BoxIMError("会会未返回 BOXIM 访问凭证", auth_error=True)
+        return data
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        access_token: str,
+        *,
+        params: dict | None = None,
+        json: dict | None = None,
+    ) -> Any:
+        headers = {"accessToken": access_token}
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.request(
+                method,
+                f"{self.im_base_url}{path}",
+                headers=headers,
+                params=params,
+                json=json,
+            )
+        payload = self._response_payload(response)
+        code = payload.get("code")
+        if response.status_code >= 400 or code not in (200, "200"):
+            raise BoxIMError(
+                payload.get("message") or "BOXIM 请求失败",
+                code=code or response.status_code,
+                auth_error=response.status_code in (400, 401, 403)
+                or code in (400, 401, 403, "400", "401", "403"),
+            )
+        return payload.get("data")
+
+    async def get_self(self, access_token: str) -> dict:
+        data = await self._request("GET", "/user/self", access_token)
+        if not isinstance(data, dict) or data.get("id") is None:
+            raise BoxIMError("BOXIM 未返回当前用户信息")
+        return data
+
+    async def fetch_private_messages(self, access_token: str, min_id: str = "0") -> list[dict]:
+        data = await self._request(
+            "GET",
+            "/message/private/loadOfflineMessage",
+            access_token,
+            params={"minId": str(min_id or "0")},
+        )
+        if data is None:
+            return []
+        if not isinstance(data, list):
+            raise BoxIMError("BOXIM 私聊消息格式不正确")
+        return [item for item in data if isinstance(item, dict)]
+
+    async def send_private_message(
+        self,
+        access_token: str,
+        peer_id: str,
+        content: str,
+        *,
+        local_id: int | str | None = None,
+    ) -> dict:
+        local_id = int(local_id or (int(time.time() * 1000) * 1000 + secrets.randbelow(1000)))
+        data = await self._request(
+            "POST",
+            "/message/private/send",
+            access_token,
+            json={
+                "localId": local_id,
+                "recvId": int(peer_id) if str(peer_id).isdigit() else peer_id,
+                "content": content,
+                "type": 0,
+                "receipt": False,
+                "atUserIds": [],
+            },
+        )
+        if not isinstance(data, dict):
+            raise BoxIMError("BOXIM 未返回发送结果")
+        return data