wecom-approval-notify-design.md 13 KB
企业微信应用消息推送「审核通知」设计方案
版本：v0.1（评审稿，已按官方文档核验） 日期：2026-09-11 范围：后端自动推送 · 企微自建应用消息 · 集团单一企微（单 corpId）
1. 背景与目标
项目（养老院管理系统，若依 RuoYi 体系：前端 kyj-yanglao-web-new + Java 服务端）当前的审核/审批：
- 流程由 BPM 工作流引擎驱动，前端通过
/bpm/task/approve、/bpm/task/reject、/bpm/task/return触发「通过/拒绝/退回」。 - 已有站内通知中心：前端读取未读数
/system/notify-message/getBpmListCount、标记已读/system/notify-message/updateReadById。
问题：站内通知仅在 Web 端可见，审核通过/拒绝/待办变更无法及时触达相关人员（经办人、发起人、审批人）。
目标：在审核结果产生时（后端），通过企业微信自建应用消息，将审核通知实时推送到关联人员的企业微信；采用后端自动推送，不依赖前端唤起页面。
关键前提：集团为单一企业微信（单 corpId），userid 全集团唯一，因此可按 userid 精准推送给对应人员，一套 corpId/secret/agentId 全局复用，无需按租户/机构拆分多套企微配置。
2. 现状梳理
| 能力 | 现状 | 位置（前端） |
|---|---|---|
| 审核动作入口 | 通过/拒绝/退回 | src/views/bpm/processInstance/detail/ProcessInstanceOperationButton.vue（handleAudit） |
| 审核接口 | /bpm/task/approve、/bpm/task/reject、/bpm/task/return |
src/api/bpm/task/index.ts |
| 待办/已办列表 | 是 | src/views/bpm/task/todo/index.vue |
| 站内通知 | 未读数 + 已读 | /system/notify-message/* |
| 后端技术栈 | 若依 RuoYi（Spring Boot） | 不在本仓库 |
前端审核动作只是把结果提交给后端，最终的审批状态流转和通知都在服务端。因此企微推送必须落在后端。
3. 总体架构
申请人 审批人 企微 App（单 corpId）
│ │ │
│ 提交单据(BPM启动) │ │
│ ───────────────────► │ │
│ │ │
│ 审批通过/拒绝 │ │
│ │ ─────────────────► │
│ 审核结果完成 │
│ └── 后端流程引擎触发通知
│ │
│ ▼
│ ┌─────────────────────────┐
│ │ NotifyMessage 记录站内通知│
│ └─────────────────────────┘
│ │
│ ▼
│ ┌─────────────────────────┐
│ │ QyWeixinClient │
│ │ - 取 access_token(缓存) │
│ │ - 按 userid 精准发应用消息 │
│ └─────────────────────────┘
│ │
│ ▼
│ 企微 App 推给对应人员
最优挂接点（推荐）
不直接改 approve/reject 各自的方法，而是在审核完成时统一产生的通知出口处理，做到一次接入、覆盖所有审核场景：
- 方案 A（推荐）：在服务端「审核通知落地」的公共位置挂接发送逻辑 —— 即当前 BPM 审批完成后写站内通知（
notify-message）的地方，追加企微推送。所有通过/拒绝/退回都经过此处。 - 方案 B：在 BPM 流程事件监听器上挂接（例如审批任务完成 / 流程实例结束事件），事件驱动，与通知中心解耦。
两种方案都满足「后端自动推送、前端零改动」。方案 A 复用既有通知点位更简单；方案 B 更符合流程事件化、可扩展（未来其它消息也可复用）。
4. 企业微信应用消息机制（前置说明）
4.1 三要素（一套，全局复用）
| 配置项 | 含义 | 获取位置 |
|---|---|---|
corpId |
企业 ID（全集团唯一） | 企微管理后台 → 我的企业 → 企业信息 |
corpSecret |
自建应用的密钥 | 应用管理 → 目标应用 → Secret |
agentId |
应用 AgentId | 应用管理 → 目标应用 → AgentId |
4.2 调用链路（两步）
- 获取 access_token（有效期 7200s，需缓存复用，勿每次请求）：
GET https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid={corpid}&corpsecret={secret} 发送应用消息（给指定 userid，可多选）：
POST https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token={token}body：{ "touser": "zhangsan|lisi", "msgtype": "markdown", "agentid": 1000002, "markdown": { "content": "..." }, "safe": 0 }4.3 前置条件（必须满足，否则发不出去）
- 目标用户必须是企微通讯录成员，且
touser用其 userid（非手机号/姓名）。 - 服务端出口 IP 需加入该应用「企业可信 IP」白名单，否则 gettoken 失败。
- 自建应用需勾选「消息发送」权限；接收人需在该应用可见范围内。
- 应用可见范围至少要覆盖需要被通知的人员（经办人/审批人）。
- 集团为单一企微（单 corpId）：
userid全集团唯一，可直接按 userid 精准推送给对应人员，一套配置全局有效，无需按租户/机构拆分。
5. 后端改动点（若依 RuoYi / Spring Boot）
后端不在本仓库，此处给出落地清单；实际编码在拿到后端仓库后进行。
5.1 配置
application.ymlwecom: app: enabled: true corp-id: wx1234567890abcdef agent-id: 1000002 corp-secret: YOUR_CORP_SECRET # userid 前缀/映射可选，若系统用户表存的是手机号而非 userid user-id-fallback: mobile- 目标用户必须是企微通讯录成员，且
5.2 新增 QyWeixinClient
@Component
public class QyWeixinClient {
// 1. getAccessToken()：按 agentId 维度 Redis 缓存 7200s，失效再拉取（单 corpId 下基本一份 token）
// 2. sendMarkdown(targetUseridSet, mdContent)：非空 userid 才发，多个用 "|" 拼接
// 3. 记录返回的 invaliduser/unlicenseduser 日志，便于排查 userid 映射
// 异常处理：RestClientException 记日志，不向上抛，保证不影响主审批流程
}
5.3 通知条件判断与接收人计算
- 仅当审核结果产生（通过/拒绝/退回）且配置
enabled=true、存在接收人 userid 时才发送。 - 接收人=申请人（单据发起人）+ 上一审批人。userid 来源（单 corpId 下 userid 全集团唯一，直接可用于
touser）：- 用户表若有 userid 字段直接取；
- 否则按配置
user-id-fallback: mobile，用手机号在企微通讯录换取 userid（/cgi-bin/user/getuserid）。手机号必须开通并唯一。
- 由于单 corpId，无需按租户/机构维护多套企微参数与 user↔corpId 映射。
5.4 挂接点（方案 A：通知出口处）
在服务端「BPM 审批写站内通知（notify-message）」的方法内，审批结果确定后追加：
// 伪代码
notifyMessageService.createBpm(...); // 既有站内通知，保留不动
if (wecomProperties.getApp().isEnabled()) {
Set<String> userIds = resolveReceiverUserIds(instance, task);
if (!userIds.isEmpty()) {
wecomClient.sendMarkdown(userIds, buildApprovalMd(instance, task, result));
}
}
5.5 消息模板（Markdown，示例）
**养老院审批通知**
> 单据：退住申请
> 编号：DS-2026-0001
> 发起人：张三
> 审批人：李四
> 结果：✅ 已通过 / ❌ 已拒绝 / ↩️ 已退回
审批意见：……
时间：2026-09-11 14:30
5.6 幂等与失败处理
- token 按 agentId 缓存且处理并发，避免重复获取。
- 发送失败（网络/接口返回 errcode）仅记录日志并告警，不影响主审批事务（异步或非事务内同步发送，推荐用
@Async）。 - 可选开启
enable_duplicate_check=1防重复推送（默认 1800s 内同内容去重）。 - 支持开关
enabled:false一键关闭，灰度可配置按 tenant 或单据类型白名单。
6. 配置清单（供实施联调用）
| 步骤 | 内容 | 负责人 |
|---|---|---|
| 1 | 企微后台创建自建应用，取得 corpId / agentId / secret | 企微管理员 |
| 2 | 应用可见范围勾选需被通知人员 | 企微管理员 |
| 3 | 服务器出口 IP 加入「企业可信 IP」 | 运维 + 企微管理员 |
| 4 | 确认用户表具备 userid（或手机号可映射） | 后端开发 |
| 5 | 后端接配置 + QyWeixinClient + 通知出口挂接 | 后端开发 |
| 6 | 联调：发起一单审批，验证审批人/申请人企微能收消息 | 后端 + 测试 |
| 7 | 灰度与开关 | 运维 |
7. 边界与风险
- userid 准确性是本方案最大风险：userid 与实际用户不匹配、接收人不在应用可见范围，会导致个别用户收不到（响应
invaliduser）。需在联调阶段核对映射。单 corpId 下全集团 userid 唯一，映射相对清晰。 - token 需按应用缓存且处理并发；Redis 或本地内存皆可，过期自动刷新。
- 大量审批并发时，企微频率限制（每应用对同一成员 ≤30 次/分、≤1000 次/时）需留意，必要时异步排队；建议避开整点 0/30 分调用。
- markdown 消息需企微客户端 2.4.5+；若应用开启「在微工作台中始终进入主页」，非文本消息会被转成文本并截断（≤20 字节）。
- 后端自动推送意味着后端仓库需要新代码；本前端仓库无需改动（除非未来要提供"审核通知开关/接收人配置"页面）。
- 敏感信息：secret、access_token 不可落入前端仓库或日志（官方明确要求 token 仅存后端）。
8. 官方文档核验结论（2025/09/24 版）
已根据企微官方开发文档逐项核对，当前方案整体无误，并补充以下细节：
8.1 已确认与方案一致
| 方案写法 | 官方结论 | 是否一致 |
|---|---|---|
gettoken?corpid=&corpsecret= 取 token |
GET https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRET，需应用为启用状态 |
✅ |
| access_token 有效期 7200s，需缓存复用 | expires_in: 7200（2 小时），须缓存、不能频繁调用否则被频率拦截 |
✅ |
message/send?access_token= 发消息 |
POST https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=ACCESS_TOKEN |
✅ |
touser 用 userid，多个用 \| 分隔 |
最多 1000 个；也支持 toparty/totag/@all |
✅ |
agentid 为整型必填 |
企业内部应用在设置页查看 | ✅ |
msgtype: markdown |
官方支持 markdown 消息（有语法子集） | ✅ |
| 后端自动推送 | 官方明示「请勿将 access_token 返回给前端，全部由后台发起企微 API 请求」——印证后端方案正确 | ✅ |
8.2 需补充的细节
- token 缓存：单 corpId 下应用仅一个，
access_token全局一份即可（仍按 agentId 语义缓存，便于扩展）。多企业场景才需按企业隔离。 - 接收人必须在应用可见范围：否则该 userid 返回在
invaliduser；若全部无权限则 errcode=81013。发送方法需记录invaliduser/unlicenseduser便于排查。 - markdown 客户端要求：需企微客户端 2.4.5+；若应用设为「在微工作台中始终进入主页」，会转纯文本（≤20 字节截断）。
- 频率与错峰：每应用对同一成员 ≤30 次/分、≤1000 次/时；建议避开每小时 0/30 分整点调用。
- 防重复：可开
enable_duplicate_check=1（默认 1800s 同内容去重），避免重复推送。 - 返回大小写：返回包 userid 统一转小写，接收人分派时按小写处理更稳妥。
- secret 需应用启用状态：配置联调前确认自建应用为「已启用」。
9. 待确认问题（评审后）
- 接收人集合：只推给申请人？还是申请人 + 全部历史审批人？是否包含"当前待办审批人"？
- 推送事件范围：仅「通过/拒绝/退回」这类结果，还是也要「新待办提醒」？
- 是否需要在 Web 端提供一个"审核通知设置"（接收人、开关）页面？
- 后端仓库位置：评审通过后请提供后端 Git 地址或本地路径，以便直接实现。