企业微信渠道（WeCom）规划：配置模型、目标管理与发送流程
我把企业微信渠道当作“新架构的第一块试金石”。
原因很现实：它和公众号同属 Token 管理型渠道，但用户体系、消息类型、鉴权字段都不一样。
- 微信公众号：
appId/appSecret+OpenID - 企业微信：
corpId/corpSecret/agentId+userId/departmentId
如果新架构能把这些差异隔离住，那以后接钉钉/飞书/自定义 webhook 才会轻松。
目标：先做“可用的 MVP”，再补齐复杂能力
这份规划明确走 MVP：
- 先支持 文本消息（
text） - 再支持 文本卡片（
textcard） - 目标管理先走“简化版”：
- 直接在 App 里配置
userIds/departmentIds - 不做企业微信通讯录同步
- 直接在 App 里配置
配置模型：Channel 放凭证，App 放目标
Channel 配置（企业微信）
企业微信渠道配置需要三项：
corpIdcorpSecretagentId
flowchart LR
CH["Channel
enterprise-wechat"] --> CFG[config] CFG --> A[corpId] CFG --> B[corpSecret] CFG --> C[agentId]
enterprise-wechat"] --> CFG[config] CFG --> A[corpId] CFG --> B[corpSecret] CFG --> C[agentId]
App 配置（企业微信简化版）
App 配置偏“业务面”，主要是：
pushMode:unicast/broadcastmessageType:text/textcardtargetUsers?: string[]targetDepartments?: string[]
这里的一个设计取舍：
- 我不强求 pushMode 和 target 的组合完全互斥
- 而是允许“混用”，最终在发送时组合成
touser/toparty
这样 UX 会更接近“你填了什么，我就按你填的发”。
发送流程：复用 TokenSendTemplate，只替换三处差异
企业微信属于 Token 管理型，所以它应该严格走同一个模板流程：
- 参数校验
- 获取 token
- 构建消息
- 发送
- 解析返回
它的“渠道差异”只应该体现在：
- token endpoint
- send endpoint + payload
- 错误码映射
sequenceDiagram
autonumber
participant C as Caller
participant S as /send/appKey
participant P as push.service
participant EW as enterprise-wechat.service
participant QY as WeCom API
C->>S: GET/POST /send/appKey
S->>P: push(appKey, message)
P->>EW: getAccessToken(corpId, corpSecret)
EW->>QY: GET /cgi-bin/gettoken
QY-->>EW: {access_token, expires_in}
P->>EW: sendMessage(agentId, touser/toparty, text/textcard)
EW->>QY: POST /cgi-bin/message/send
QY-->>EW: {errcode, errmsg, msgid, invaliduser, invalidparty}
EW-->>P: SendResult
P-->>S: PushResult
API：只需要两类对接点
- 获取 token
https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid={CORPID}&corpsecret={CORPSECRET}
- 发送消息
https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token={ACCESS_TOKEN}
（MVP 阶段不做通讯录拉取、部门成员枚举等能力。）
失败语义：把“部分失败”当成一等公民
企业微信的一个坑是：即使 errcode=0，也可能存在：
invaliduserinvalidparty
这类结果如果不向上透传，就会出现一种很难排障的状态：
系统显示“成功”，但某些人永远收不到。
所以我计划在 PushResult 里显式保留 per-target 结果，至少能：
- 在消息历史里看到哪些 userId/deptId 失败
- 给管理员一个明确的“是配置错还是平台拒绝”
渠道验证：保存配置前做一次“最小验证”
企业微信渠道配置保存时，应当至少验证：
- corpId/corpSecret 是否能换到 token
- agentId 是否是数字（或可被安全转换）
这可以挡住 80% 的“保存成功但永远发不出去”。
启发：企业微信的“目标模型”比公众号更像真实业务
公众号推送的目标往往就是 OpenID 列表（单一维度）。
企业微信的目标是：
- 人（userId）
- 组织（departmentId）
这迫使我在系统里更认真地区分：
- “渠道能力”（token + API）
- “应用目标”（谁该收到）
也正好检验了桥接设计到底有没有起效。