兰 亭 墨 苑

标题 *

URL 别名 *

内容 * (支持 Markdown 格式) ### Gemini解读 我们来详细解读 learning/wechatpush/data_api.py 中与企业微信推送相关的功能与实现。该文件实现了一个基于企业微信 API 的双向通信网关： - 主动推送：提供 HTTP API（/weixinpush），供外部系统发送各类消息给企业微信用户或群聊。 - 接收回调：提供回调端点（/wechat/callback），用于接收企业微信服务器的事件与消息（如卡片按钮点击反馈）。 以下为两大核心模块的要点说明。 #### 1) 主动推送功能（/weixinpush） - 端点定义 - 路由：`@app.route('/weixinpush', methods=['POST'])` - 统一 JSON 请求体，通过 `msgtype` 分发消息类型。 - 分发机制 - 通过 `if/elif` 判断 `msgtype`，调用 `wechat_client`（来自 `from wechat import WeChat`）对应方法。 - `wechat_client` 封装了与企业微信官方 API 的交互（如 token 管理、请求拼装）。 - 支持的消息类型 - 文本消息：`text`（需 `content`） - 图片消息：`image`（需 `media_id`） - 图片文件：`image_file`（需 `file_name`，服务器本地路径） - 图文消息：`news` / `mpnews`（需 `articles` 数组） - 任务卡片：`task_card`（需 `task_card` 对象） - 模板卡片：`template_card`（需 `template_card` 对象） - 示例（伪代码） - 发送文本消息 ``` curl -X POST http://<your_server_ip>:5000/weixinpush \ -H "Content-Type: application/json" \ -d '{ "msgtype": "text", "content": "这是一条来自API的测试消息" }' ``` - 发送任务卡片 ``` curl -X POST http://<your_server_ip>:5000/weixinpush \ -H "Content-Type: application/json" \ -d '{ "msgtype": "task_card", "to_user": "user1|user2", "task_card": { "title": "审批任务", "desc": "来自系统的报销申请", "task_id": "task_12345", "button_list": [ {"text": "同意", "key": "approve"}, {"text": "驳回", "key": "reject"} ] } }' ``` #### 2) 接收回调功能（/wechat/callback） - 端点定义 - 路由：`@app.route('/wechat/callback', methods=['GET', 'POST', 'HEAD'])` - 需在企业微信后台配置为应用回调 URL。 - 验证（GET） - 使用 `WXBizMsgCrypt` 校验 `msg_signature` 等参数。 - 验证成功后返回 `echostr`，完成 URL 配置。 - 消息解密与处理（POST） - 企业微信以加密 POST 请求推送事件（如按钮点击）。 - 使用 `_wxcpt().DecryptMsg` 结合 Token 与 AES_KEY 解密。 - 通过 `xmltodict` 将 XML 转字典，解析 `MsgType`、`Event`。 - 已实现：`template_card_event` 处理流程 - 提取用户、任务 ID、按钮 Key 等关键字段。 - 调用 `wechat_client.updateTemplateCard` 更新原卡片（如将“同意/驳回”按钮卡片替换为“已响应”的文本通知卡片）。 #### 3) 配置 - 通过环境变量加载： - `WECHAT_CALLBACK_TOKEN`（回调校验 Token） - `WECHAT_CALLBACK_AES_KEY`（消息体加解密 AES Key） - `WECHAT_CORP_ID`（企业 ID） - `wechat.py` 内通常还需配置应用 `AgentId` 与 `Secret`，用于官方 API 调用。 #### 总结 - 架构清晰：发送（/weixinpush）与接收（/wechat/callback）职责分离。 - 功能全面：覆盖文本、图片、图文及各类卡片，支持交互事件闭环。 - 安全可靠：遵循企业微信加解密与签名验证规范。 - 高度封装：微信 API 细节下沉至 `wechat.py`，`data_api.py` 专注路由与分发，维护性强。 --- ### Qwen解读 基于对 `data_api.py` 与 `wechat.py` 的分析，总结微信推送的实现与能力如下。 #### 1) 核心模块（wechat.py） - WeChat 类职责 - 封装企业微信 API 交互与鉴权逻辑。 - 认证与 Token 管理 - 初始化参数：`corpid`、`secret`、`agentid`（通常来自环境变量）。 - `refreshToken()`：调用企业微信接口获取 `access_token`。 - `ensureToken()`：在发送请求前确保 token 有效，必要时自动刷新。 - `_post_with_retry()`：封装 POST 请求，内置 token 校验与失效重试。 - 消息发送能力 - `sendMsg(content, to_user)`：文本 - `sendPicture(media_id, to_user)`：图片（先行上传获取 `media_id`） - `sendPictureFile(file_name, to_user)`：本地文件直传并发送 - `sendNews(articles, to_user)`：图文（`news`） - `sendMpNews(articles, to_user)`：富图文（`mpnews`） - `sendTaskCard(...)`：任务卡片（交互按钮） - `sendTemplateCard(...)`：模板卡片（如 `text_notice`、`news_notice`、`button_interaction`） - `updateTemplateCard(replace_card)`：基于响应码/任务信息更新已发卡片 - 媒体上传 - `uploadPic(file_name)`：上传临时素材，返回 `media_id`（用于 `image`/`mpnews`） - `uploadImageGetUrl(file_name)`：上传到企业微信 CDN，返回 HTTPS `picurl`（用于 `news`） - 回调加解密辅助 - 使用官方 `WXBizMsgCrypt` 进行 URL 验证、消息加解密（`EncryptMsg`/`DecryptMsg`）。 #### 2) API 接口（data_api.py） - 外部推送（/weixinpush） - 以 `POST` + JSON 的统一入口对外暴露。 - 根据 `msgtype` 分派到 `wechat_client` 的对应方法。 - 支持字段：`content`、`media_id`、`file_name`、`articles`、`template_card`、`task_card`、`to_user` 等。 - 微信回调（/wechat/callback） - URL 验证（GET）：使用 `VerifyURL` 校验签名并返回 `echostr`。 - 事件接收（POST）： - 若启用 AES 模式（如 `WECHAT_CALLBACK_MODE == "aes"`），用 `DecryptMsg` 解密。 - 解析 XML 获取事件。 - 已实现 `template_card_event`：解析 `ResponseCode`、`TaskId`、`EventKey` 等，调用 `updateTemplateCard` 更新卡片状态。 - 响应：按规范返回 `success`（或加密后的 `success`），避免重复推送。 #### 功能总结 - 多类型消息推送：文本、图片、图文/富图文、任务卡片、模板卡片。 - 交互闭环：支持按钮点击事件，结合回调实现“发送—交互—更新”全链路。 - API 驱动：统一的 `/weixinpush` 使集成变得简单直接。 - 安全可靠：内置 token 自动刷新、消息加解密与重试机制。 - 易于集成：复杂调用细节封装为简洁的方法与标准 HTTP API，方便对接各类系统。

配图 (可多选)

标签