企业微信接入契约

元数据

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 保存到集成日志并映射项目错误，不能直接暴露凭证或底层报文。

退款审批模板上线前置

退款审批场景上线前，维护者 MUST 在当前企业微信模板中完成并核对以下控件映射：

固定必需：退款方式中文名称（单行文本），用于展示“原路退款”“客户收款信息退款”“退回资产钱包”“退回代理主钱包”。
条件必需：客户收款信息（多行文本）与客户收款凭证（附件）。仅当本次审批尝试冻结的退款方式为 customer_account 时，二者必须同时配置且本次值非空；其他退款方式不要求、不提交空白占位材料。

保存场景时系统会校验固定退款方式映射，并校验已配置条件控件的业务字段与控件类型；提交时按不可变审批尝试快照再次校验。模板缺少客户收款条件控件时，客户收款退款会明确失败并指出缺失字段/控件，不会创建第二张审批单；修复映射后可通过 POST /api/admin/refunds/{id}/recover-approval 恢复原审批实例。已有 sp_no 只查询同步，结果未知只确认，明确提交失败且无 sp_no 才恢复原提交事件。

本次发布不执行真实企业微信或支付调用；上线验收需由维护者在指定测试企业覆盖四种退款方式、条件材料缺失、模板修复后的原实例恢复、结果未知与重复/并发恢复，并核对审批尝试数、实例数和业务资金事实不变。

安全与验证

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

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

3.8 KiB Raw Blame History Unescape Escape