break
b063617153
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 9m35s
53 lines
3.8 KiB
Markdown
53 lines
3.8 KiB
Markdown
# 企业微信接入契约
|
||
|
||
## 元数据
|
||
|
||
- 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>
|
||
|
||
端点、模板字段、认证、回调加密或补偿语义变化时更新本文。
|