参考：企微/飞书/钉钉 通知对接实现指南

整理时间：2026-10-13 目标：三平台「应用机器人对指定人推送」+「群机器人 Webhook 推送」 性质：实现参考文档，对接前以各平台官方文档最新版为准。

一、总体结构

每个平台两条通道，建议都接：

统一抽象：NotificationChannel 接口（send_text/send_markdown/send_card），三平台各实现一个适配器；token 统一缓存+提前刷新；发送走 Celery 队列并限流。

二、企业微信

A. 自建应用推送（对人）

1. 创建应用：企业微信管理后台 → 应用管理 → 创建自建应用，拿到三样：corpid（企业 ID）、agentid、corpsecret（应用 Secret）。设置「可见范围」（要发给谁就把谁加进来）。
2. 拿凭证： GET https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid={corpid}&corpsecret={corpsecret} 返回 access_token，7200 秒有效，需缓存+提前刷新。
3. 发消息： POST https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token={token}

   {"touser":"zhangsan","msgtype":"markdown","agentid":1000002,
    "markdown":{"content":"## 审批待办\n> 销售订单 SAL-xxx 待您审批"}}
   

   touser 为成员 userid（可用 @all 发可见范围全员）。支持 text/markdown/图文/模板卡片（按钮交互型可用于“通过/退回”快捷审批）。
4. 用户 ID 映射：手机号换 userid：POST /cgi-bin/user/getuserid（传 mobile）。

文档：developer.work.weixin.qq.com/document/path/90236

B. 群机器人 Webhook

1. 群聊 → 右上角 → 群机器人 → 添加 → 得到 Webhook URL。
2. 发送： POST https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key={key}

   {"msgtype":"markdown","markdown":{"content":"今日经营日报\n> 订单 12 单"}}
   

3. 限制：每个机器人 20 条/分钟。markdown 支持 <@userid> @群成员（企微 5.0.6+）。

文档：消息推送（原“群机器人”）配置说明 path/91770

三、飞书

A. 自建应用推送（对人）

1. 创建应用：飞书开发者后台 → 创建企业自建应用 → 添加「机器人」能力。
2. 权限：权限管理勾选 im:message（发送消息）、contact:user.id:readonly 等；设置可用范围（给全员发就设为全体员工）。
3. 拿凭证： POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal {"app_id":"...","app_secret":"..."} → tenant_access_token（2 小时有效，需定时刷新）。
4. 发消息： POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id Header: Authorization: Bearer {tenant_access_token}

   {"receive_id":"ou_xxx","msg_type":"text","content":"{\"text\":\"销售订单 SAL-xxx 待审批\"}"}
   

   注意：receive_id_type 可选 open_id / user_id / union_id / email / chat_id（chat_id 可发群）；推荐 open_id；用户必须在机器人可用范围内。
5. 用户 ID 映射：手机号换 open_id：POST /open-apis/contact/v3/users/batch_get_id（需对应权限）。

文档：open.feishu.cn → 服务端 API → 消息 → 发送消息（im/v1/message/create）

B. 群机器人 Webhook

1. 群聊 → 设置 → 群机器人 → 添加「自定义机器人」→ 得 Webhook URL。
2. 发送： POST https://open.feishu.cn/open-apis/bot/v2/hook/{token}

   {"msg_type":"text","content":{"text":"今日经营日报..."}}
   

3. 安全设置（建机器人时三选一）：自定义关键词 / IP 白名单 / 加签（timestamp + HMAC-SHA256 签名，body 带 timestamp 和 sign）。建议用加签。

四、钉钉

A. 企业内部应用「工作通知」（对人）

1. 创建应用：钉钉开发者后台 → 创建企业内部应用，拿到 AppKey / AppSecret / AgentId；开通「工作通知」权限。
2. 拿凭证： POST https://oapi.dingtalk.com/gettoken?appkey={key}&appsecret={secret}（或新版 https://api.dingtalk.com/v1.0/oauth2/accessToken）
3. 发工作通知： POST https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_token={token}

   {"agent_id":123456,"userid_list":"user123,user456","to_all_user":false,
    "msg":{"msgtype":"text","text":{"content":"销售订单 SAL-xxx 待审批"}}}
   

   返回 task_id，可用「获取工作通知发送结果」接口查失败名单。
4. 限制：同一员工一天最多 500 条/应用；相同内容一天只推一次；每分钟最多 5000 人；userid_list 单次最多 100 人。
5. 用户 ID 映射：手机号换 userid：POST /topapi/v2/user/getbymobile。

文档：open.dingtalk.com/document/orgapp/asynchronous-sending-of-enterprise-session-messages

B. 群机器人 Webhook

1. 群聊 → 群设置 → 机器人 → 添加「自定义」机器人 → 得 Webhook URL（含 access_token）。
2. 发送： POST https://oapi.dingtalk.com/robot/send?access_token={token}

   {"msgtype":"markdown","markdown":{"title":"经营日报","text":"## 今日经营日报\n- 订单 12 单"}}
   

3. 安全设置（三选一，建机器人时配）：自定义关键词（消息必须含关键词）/ 加签（timestamp&secret 做 HmacSHA256 → sign 参数）/ IP 白名单。建议加签。
4. 限制：20 条/分钟/机器人。

五、实施要点（对接到织枢 ERP）

1. 通道适配器：backend/app/modules/notifications/channels/ 下每平台一个适配器（wecom_app / wecom_webhook / feishu_app / feishu_webhook / dingtalk_app / dingtalk_webhook），统一 send() 接口。
2. token 管理：三平台凭证都有有效期，统一做内存/Redis 缓存 + 提前 5 分钟刷新，不要每次现取。
3. 发送队列：走 Celery，按平台限流（群机器人 20 条/分钟硬限制，超限排队）。
4. 用户绑定：im_identity 映射表（内部 user_id ↔ 平台 + 平台 userid/open_id），手机号匹配作为兜底绑定手段。
5. 失败处理：钉钉用发送结果查询接口找失败名单；企微看 errcode；失败的写日志 + 可重试。
6. 配置入口：各平台凭证进系统配置（后台可配，加密存储），群机器人 webhook 支持按群配置多个。
7. 权限纪律：消息内容过数据权限——金额/成本类内容只对授权角色推送。