junhong_cmp_fiber/docs/integrations/wecom/README.md

企业微信接入契约

元数据

• Owner：企业微信审批维护人
• 实现：internal/infrastructure/wecom/
• 官方来源：企业微信开发者中心对应接口页；仓库仅保留当前调用交集
• 核验日期：2026-08-07

当前实际使用范围

系统使用 access_token、部门与成员简表、审批模板详情、审批提交、审批详情/列表、临时素材上传，以及加密回调后的权威状态同步。未在代码调用链出现的企业微信接口不视为系统能力。

端点与方法

• GET /cgi-bin/gettoken
• GET /cgi-bin/department/list
• GET /cgi-bin/user/simplelist
• POST /cgi-bin/oa/gettemplatedetail
• POST /cgi-bin/oa/applyevent
• POST /cgi-bin/oa/getapprovaldetail
• POST /cgi-bin/oa/getapprovalinfo
• POST /cgi-bin/media/upload

基础地址来自 wecom.base_url；HTTP 超时来自 wecom.timeout，未配置时为 10 秒。CorpID 与应用 Secret 用于换取 access_token；审批控件 ID、类型和选项 Key 必须来自当前模板详情，不能由本系统猜测。

回调、终态与补偿

回调入口校验企业微信签名并进行 AES 解密，再按审批单号获取权威详情。回调并非唯一事实来源：审批列表/详情查询用于轮询补偿。提交 Consumer 区分 SafeToRetry：附件准备、取 token、构造请求或调用前的安全失败可释放实例等待重试；已无法确认是否提交成功的结果不得盲目重复创建审批。

业务以本地审批实例和企业微信审批单号去重，终态只推进一次；errcode/errmsg 保存到集成日志并映射项目错误，不能直接暴露凭证或底层报文。

安全与验证

Secret、access_token、回调 AES Key、成员敏感字段、审批正文与附件 URL 必须脱敏。可信 IP、应用可见范围、模板、回调 URL 和素材权限属于部署侧人工配置。

可复现静态证据：internal/infrastructure/wecom/token_provider.go、directory_client.go、template_client.go、approval_submission_client.go、approval_detail_client.go、approval_info_client.go、approval_attachment_uploader.go、approval_submission_consumer.go。真实验收需测试企业覆盖提交、加密回调、漏回调补偿、重复事件和未知提交结果；本次不访问真实企业。

官方参考：https://developer.work.weixin.qq.com/document/path/91902

端点、模板字段、认证、回调加密或补偿语义变化时更新本文。