"""企业微信 API HTTP 客户端。 通过 httpx.AsyncClient 调用企业微信开放平台 API，封装 access_token 管理、通用请求与 IM / 通讯录 / 客户联系 / 微信客服 / OAuth API。HTTP 异常与企业微信业务错误码通过 error_translator 转换为契约层异常，不向外 抛原生异常。token 通过 CachePort 缓存，客户端本身不持有 mutable 状态。 企业微信多 Secret 权限隔离： - ``corp_secret``: 自建应用 Secret（应用消息、通讯录） - ``external_contact_secret``: 客户联系 Secret（外部联系人、客户群） - ``kf_secret``: 微信客服 Secret（客服会话） 各 Secret 独立获取 token，独立缓存。 连接池由 lifecycle 统一管理（onInit 创建 / onUnload 关闭），通过 ``attach_http_client`` 注入；未注入时降级为每请求独立 client。 依赖方向：仅 import yuxi.channels.contract.* 与标准库 / httpx，不污染 框架层。 """ from __future__ import annotations import time from typing import Any import httpx from yuxi.channels.contract.dtos.config import ConfigScope from yuxi.channels.contract.errors import AuthError, DependencyError, Error from yuxi.channels.contract.ports.driven.cache_port import CachePort from yuxi.channels.contract.ports.driven.config_port import ConfigPort from yuxi.channels.contract.ports.driven.logger_port import LoggerPort from . import error_translator from ._constants import ( CHANNEL_TARGET, TOKEN_REFRESH_LEAD_TIME_SEC, ) # Token 类型标识 TOKEN_TYPE_APP = "app" TOKEN_TYPE_EXTERNAL_CONTACT = "external_contact" TOKEN_TYPE_KF = "kf" _TOKEN_CACHE_KEY_PREFIX = "wecom:token:" class WecomClient: """企业微信 API HTTP 客户端。 通过 DI 接收 ConfigPort / CachePort / LoggerPort，不访问全局 settings 或 logger。token 通过 CachePort 缓存，客户端不持有 mutable 状态。所有 方法为 async，HTTP 异常通过 error_translator.wrap_http_exception 转换， 企业微信业务错误码非 0 通过 error_translator.translate_wecom_error 转换。 连接池由 lifecycle 统一管理（onInit 创建 / onUnload 关闭），通过 ``attach_http_client`` 注入；未注入时降级为每请求独立 client。 """ def __init__( self, config_port: ConfigPort, cache_port: CachePort, logger_port: LoggerPort, ) -> None: self._config = config_port self._cache = cache_port self._logger = logger_port self._http_client: httpx.AsyncClient | None = None # ------------------------------------------------------------------ # 连接池管理 # ------------------------------------------------------------------ def attach_http_client(self, client: httpx.AsyncClient) -> None: """注入 lifecycle 管理的共享 httpx 连接池。""" self._http_client = client def detach_http_client(self) -> None: """解除共享连接池引用（由 lifecycle 在 onUnload 关闭前调用）。""" self._http_client = None # ------------------------------------------------------------------ # 内部辅助 # ------------------------------------------------------------------ async def _get_account_config(self, account_id: str) -> dict[str, Any]: """读取账户级配置。""" cv_corp_id = await self._config.get( "corp_id", scope=ConfigScope.ACCOUNT, target=account_id, ) cv_corp_secret = await self._config.get( "corp_secret", scope=ConfigScope.ACCOUNT, target=account_id, ) cv_agent_id = await self._config.get( "agent_id", scope=ConfigScope.ACCOUNT, target=account_id, ) return { "corp_id": cv_corp_id.value, "corp_secret": cv_corp_secret.value, "agent_id": cv_agent_id.value, } async def _get_optional_account_config(self, account_id: str, key: str) -> str | None: """读取账户级可选配置（如 external_contact_secret / kf_secret）。 @return 配置值（空字符串视为未配置返回 None）；key 不存在返回 None。 @failure 配置系统故障（如 ConfigPort 不可用）向上抛 DependencyError， 不静默吞错以掩盖系统故障。 """ try: cv = await self._config.get( key, scope=ConfigScope.ACCOUNT, target=account_id, ) value = cv.value return value if value else None except KeyError: # key 不存在视为未配置 return None except DependencyError: raise except Error: raise except Exception as exc: raise DependencyError( dep="wecom_api", cause=exc, ) from exc async def _get_channel_config(self, key: str) -> Any: """读取渠道级配置。""" cv = await self._config.get( key, scope=ConfigScope.CHANNEL, target=CHANNEL_TARGET, ) return cv.value async def _get_request_timeout_seconds(self) -> float: """从配置读取请求超时（秒）。""" timeout_ms = await self._get_channel_config("request_timeout_ms") return float(timeout_ms) / 1000.0 def _token_cache_key(self, account_id: str, token_type: str) -> str: return f"{_TOKEN_CACHE_KEY_PREFIX}{account_id}:{token_type}" async def _get_token(self, account_id: str, token_type: str) -> str: """获取指定类型的 access_token。 企业微信多 Secret 权限隔离，各 Secret 独立获取 token： - ``app``: corp_secret（自建应用） - ``external_contact``: external_contact_secret（客户联系） - ``kf``: kf_secret（微信客服） """ cache_key = self._token_cache_key(account_id, token_type) cached = await self._cache.get(cache_key) if cached.is_some(): token, expires_at = cached.unwrap() if expires_at > time.time(): return token account_config = await self._get_account_config(account_id) corp_id = account_config["corp_id"] if token_type == TOKEN_TYPE_APP: secret = account_config["corp_secret"] elif token_type == TOKEN_TYPE_EXTERNAL_CONTACT: secret = await self._get_optional_account_config(account_id, "external_contact_secret") if not secret: raise DependencyError( dep="wecom_api", cause=ValueError("external_contact_secret not configured"), ) elif token_type == TOKEN_TYPE_KF: secret = await self._get_optional_account_config(account_id, "kf_secret") if not secret: raise DependencyError( dep="wecom_api", cause=ValueError("kf_secret not configured"), ) else: raise DependencyError( dep="wecom_api", cause=ValueError(f"unknown token type: {token_type}"), ) token, expires_in = await self._fetch_token(corp_id, secret) expires_at = time.time() + expires_in ttl = max(expires_in - TOKEN_REFRESH_LEAD_TIME_SEC, 1) await self._cache.set( cache_key, (token, expires_at), ttl_seconds=ttl, ) await self._logger.debug( "Wecom access_token refreshed", account_id=account_id, token_type=token_type, expires_in=expires_in, ) return token async def _fetch_token(self, corp_id: str, secret: str) -> tuple[str, int]: """调用企业微信 gettoken API 获取 access_token。""" api_base_url = await self._get_channel_config("api_base_url") url = f"{api_base_url}/cgi-bin/gettoken" params = {"corpid": corp_id, "corpsecret": secret} resp = await self._execute_http("GET", url, params=params) data = self._parse_json_response(resp) token = data.get("access_token", "") expires_in = int(data.get("expires_in", 0)) if not token or expires_in <= 0: raise DependencyError( dep="wecom_api", cause=ValueError(f"invalid token response: {data}"), ) return token, expires_in async def _execute_http( self, method: str, url: str, *, headers: dict[str, str] | None = None, params: dict | None = None, json_body: dict | None = None, data: dict | None = None, files: dict | None = None, ) -> httpx.Response: """执行 HTTP 请求，HTTP 异常转换为契约异常。""" timeout = await self._get_request_timeout_seconds() try: if self._http_client is not None: resp = await self._http_client.request( method, url, json=json_body, params=params, data=data, files=files, headers=headers, timeout=timeout, ) else: async with httpx.AsyncClient(timeout=timeout) as client: resp = await client.request( method, url, json=json_body, params=params, data=data, files=files, headers=headers, ) resp.raise_for_status() except httpx.HTTPError as exc: await self._logger.exception( "Wecom HTTP request failed", exc_info=exc, method=method, url=url, ) raise error_translator.wrap_http_exception( exc, timeout_ms=int(timeout * 1000), ) from exc return resp @staticmethod def _parse_json_response(resp: httpx.Response) -> dict: """解析 JSON 响应，校验企业微信业务错误码。 企业微信响应格式：``{"errcode": 0, "errmsg": "ok", ...}``。 errcode 非 0 时通过 error_translator.translate_wecom_error 转换。 """ data = resp.json() errcode = data.get("errcode", 0) if errcode != 0: raise error_translator.translate_wecom_error( errcode, data.get("errmsg", ""), ) from None return data async def _request_json( self, method: str, path: str, account_id: str, *, token_type: str = TOKEN_TYPE_APP, json_body: dict | None = None, params: dict | None = None, data: dict | None = None, files: dict | None = None, ) -> dict: """发起带 access_token 的请求并返回校验后的 JSON。""" token = await self._get_token(account_id, token_type) api_base_url = await self._get_channel_config("api_base_url") url = f"{api_base_url}{path}" all_params: dict[str, Any] = {"access_token": token} if params: all_params.update(params) resp = await self._execute_http( method, url, params=all_params, json_body=json_body, data=data, files=files, ) return self._parse_json_response(resp) # ------------------------------------------------------------------ # Token 管理 # ------------------------------------------------------------------ async def get_access_token( self, account_id: str, token_type: str = TOKEN_TYPE_APP, ) -> str: """获取指定类型的 access_token（带缓存）。""" return await self._get_token(account_id, token_type) async def verify_token(self, account_id: str) -> bool: """验证 token 有效性（调用 gettoken API）。 用于主动探测场景，强制刷新 token 以反映企业微信侧真实可用性， **不** 走缓存。``AuthError`` 视为 token 无效返回 False；其他异常 （网络故障 / 限流 / 权限不足）向上抛，由调用方处理。 """ try: account_config = await self._get_account_config(account_id) corp_id = account_config["corp_id"] secret = account_config["corp_secret"] await self._fetch_token(corp_id, secret) return True except AuthError: return False async def get_token_with_credentials( self, corp_id: str, corp_secret: str, ) -> tuple[str, int]: """使用指定凭证直接获取 access_token（不走缓存）。 用于 ``applyAccountConfig`` / ``validateCredentials`` 预取 token 验证 凭证有效性（账户配置尚未落库时无法走 ``get_access_token``）。直接 调用 ``_fetch_token``，**不** 写入缓存，仅返回 token 与 expires_in。 @failure 凭证无效抛 ``AuthError``；企业可信 IP 未配置抛 ``PermissionDeniedError``；网络故障抛 ``DependencyError``。 """ return await self._fetch_token(corp_id, corp_secret) # ------------------------------------------------------------------ # 应用消息 API # ------------------------------------------------------------------ async def send_message( self, account_id: str, msg_body: dict[str, Any], ) -> dict: """发送应用消息。 企业微信 ``POST /cgi-bin/message/send``，请求体含 ``touser`` / ``msgtype`` / 消息内容 / ``agentid``。 """ account_config = await self._get_account_config(account_id) body = dict(msg_body) body["agentid"] = int(account_config["agent_id"]) return await self._request_json( "POST", "/cgi-bin/message/send", account_id, json_body=body, ) async def recall_message( self, account_id: str, msg_id: str, ) -> dict: """撤回应用消息。""" return await self._request_json( "POST", "/cgi-bin/message/recall", account_id, json_body={"msgid": msg_id}, ) async def update_template_card( self, account_id: str, response_code: str, card_data: dict[str, Any], ) -> dict: """更新模板卡片（通过 response_code）。""" body = { "response_code": response_code, "template_card": card_data, } return await self._request_json( "POST", "/cgi-bin/message/update_template_card", account_id, json_body=body, ) # ------------------------------------------------------------------ # 媒体上传/下载 API # ------------------------------------------------------------------ async def upload_media( self, account_id: str, media_type: str, filename: str, file_data: bytes, ) -> dict: """上传临时素材。""" return await self._request_json( "POST", "/cgi-bin/media/upload", account_id, params={"type": media_type}, files={"media": (filename, file_data)}, ) async def download_media( self, account_id: str, media_id: str, ) -> bytes: """下载临时素材。 企业微信媒体下载失败时返回 HTTP 200 + JSON 错误体（如 ``{"errcode": 40007, "errmsg": "invalid media_id"}``），需校验 ``Content-Type`` 头：为 ``application/json`` 时解析并抛契约异常， 避免将错误 JSON 当作媒体字节返回（INV-7）。 """ token = await self._get_token(account_id, TOKEN_TYPE_APP) api_base_url = await self._get_channel_config("api_base_url") url = f"{api_base_url}/cgi-bin/media/get" params = {"access_token": token, "media_id": media_id} resp = await self._execute_http("GET", url, params=params) content_type = resp.headers.get("Content-Type", "") if "application/json" in content_type: # JSON 响应意味着下载失败（media_id 无效 / 过期） self._parse_json_response(resp) return resp.content # ------------------------------------------------------------------ # 通讯录 API # ------------------------------------------------------------------ async def get_user( self, account_id: str, user_id: str, ) -> dict: """读取成员信息。""" return await self._request_json( "GET", "/cgi-bin/user/get", account_id, params={"userid": user_id}, ) async def list_user_ids( self, account_id: str, *, cursor: str = "", limit: int = 10000, ) -> dict: """获取成员 ID 列表。 企业微信 ``POST /cgi-bin/user/list_id`` 不支持按部门过滤（按部门 列出成员需用 ``/cgi-bin/user/simplelist?department_id=...``）。 ``cursor`` / ``limit`` 透传至 API 用于分页。 """ return await self._request_json( "POST", "/cgi-bin/user/list_id", account_id, json_body={"cursor": cursor, "limit": limit}, ) async def convert_to_openid( self, account_id: str, user_id: str, ) -> dict: """userid 转 openid。""" return await self._request_json( "POST", "/cgi-bin/user/convert_to_openid", account_id, json_body={"userid": user_id}, ) # ------------------------------------------------------------------ # 客户联系 API（需 external_contact_secret） # ------------------------------------------------------------------ async def get_external_contact( self, account_id: str, external_userid: str, ) -> dict: """获取外部联系人详情。""" return await self._request_json( "GET", "/cgi-bin/externalcontact/get", account_id, token_type=TOKEN_TYPE_EXTERNAL_CONTACT, params={"external_userid": external_userid}, ) async def list_external_contacts( self, account_id: str, ) -> dict: """获取外部联系人列表。""" return await self._request_json( "GET", "/cgi-bin/externalcontact/list", account_id, token_type=TOKEN_TYPE_EXTERNAL_CONTACT, ) async def list_group_chats( self, account_id: str, *, limit: int = 100, cursor: str = "", ) -> dict: """获取客户群列表。""" return await self._request_json( "POST", "/cgi-bin/externalcontact/groupchat/list", account_id, token_type=TOKEN_TYPE_EXTERNAL_CONTACT, json_body={"limit": limit, "cursor": cursor}, ) async def get_group_chat( self, account_id: str, chat_id: str, ) -> dict: """获取客户群详情。""" return await self._request_json( "POST", "/cgi-bin/externalcontact/groupchat/get", account_id, token_type=TOKEN_TYPE_EXTERNAL_CONTACT, json_body={"chat_id": chat_id}, ) async def unionid_to_external_userid( self, account_id: str, unionid: str, ) -> dict: """UnionID 转外部联系人 userid。""" return await self._request_json( "POST", "/cgi-bin/externalcontact/unionid_to_external_userid", account_id, token_type=TOKEN_TYPE_EXTERNAL_CONTACT, json_body={"unionid": unionid}, ) # ------------------------------------------------------------------ # 微信客服 API（需 kf_secret） # ------------------------------------------------------------------ async def send_kf_message( self, account_id: str, msg_body: dict[str, Any], ) -> dict: """发送微信客服消息。""" return await self._request_json( "POST", "/cgi-bin/kf/send_msg", account_id, token_type=TOKEN_TYPE_KF, json_body=msg_body, ) async def list_kf_accounts( self, account_id: str, ) -> dict: """获取客服账号列表。""" return await self._request_json( "GET", "/cgi-bin/kf/account/list", account_id, token_type=TOKEN_TYPE_KF, ) # ------------------------------------------------------------------ # OAuth API # ------------------------------------------------------------------ async def get_oauth_user_info( self, account_id: str, code: str, ) -> dict: """OAuth 授权获取访问用户身份。""" token = await self._get_token(account_id, TOKEN_TYPE_APP) api_base_url = await self._get_channel_config("api_base_url") url = f"{api_base_url}/cgi-bin/auth/getuserinfo" params = {"access_token": token, "code": code} resp = await self._execute_http("GET", url, params=params) return self._parse_json_response(resp) async def get_user_detail( self, account_id: str, user_ticket: str, ) -> dict: """获取访问用户敏感信息（snsapi_privateinfo 模式）。""" token = await self._get_token(account_id, TOKEN_TYPE_APP) api_base_url = await self._get_channel_config("api_base_url") url = f"{api_base_url}/cgi-bin/auth/getuserdetail" resp = await self._execute_http( "POST", url, params={"access_token": token}, json_body={"user_ticket": user_ticket}, ) return self._parse_json_response(resp) async def get_oauth_user_info_with_credentials( self, corp_id: str, corp_secret: str, code: str, ) -> dict: """OAuth 授权获取访问用户身份（凭证直传，用于 wizard 流程）。 wizard 流程中账户尚未创建，无法通过 ``account_id`` 从 ConfigPort 读取 凭证，故直接接收 ``corp_id`` / ``corp_secret`` 获取 token 后调用 ``/cgi-bin/auth/getuserinfo``。凭证来源为 ``applied_config``。 """ token, _ = await self._fetch_token(corp_id, corp_secret) api_base_url = await self._get_channel_config("api_base_url") url = f"{api_base_url}/cgi-bin/auth/getuserinfo" params = {"access_token": token, "code": code} resp = await self._execute_http("GET", url, params=params) return self._parse_json_response(resp) async def get_user_detail_with_credentials( self, corp_id: str, corp_secret: str, user_ticket: str, ) -> dict: """获取访问用户敏感信息（凭证直传，用于 wizard snsapi_privateinfo 流程）。 与 ``get_user_detail`` 一致，但凭证直传以支持 wizard 流程（账户尚未 创建）。在 ``get_oauth_user_info_with_credentials`` 返回含 ``user_ticket`` 时调用以获取完整身份信息。 """ token, _ = await self._fetch_token(corp_id, corp_secret) api_base_url = await self._get_channel_config("api_base_url") url = f"{api_base_url}/cgi-bin/auth/getuserdetail" resp = await self._execute_http( "POST", url, params={"access_token": token}, json_body={"user_ticket": user_ticket}, ) return self._parse_json_response(resp) async def get_api_domain_ip(self, account_id: str) -> dict: """获取企业微信 API 域名 IP 段（防火墙配置辅助）。""" return await self._request_json( "GET", "/cgi-bin/get_api_domain_ip", account_id, ) __all__ = ["WecomClient"]