# 企业微信接入契约

## 元数据

- 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>

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