hyb-oa/docs/企微API能力目录.md

# 企微 API 能力目录

**文档状态**：当前企微 API 调研与本项目使用事实源。
**分类**：集成事实源 / API 能力目录。
**适用时间**：WAPI / WAPC1 / WAPC2 / WPROC1 / WPROC2 / WAPC2F / WAPC2FLIVE / WCBK1 / WEGOV1 / WACP3 / WACP3R / WREAD1 / WADM1 / WARCH1 / WARCH2 / WROAD2 / WARCH3 / WCHECK1 / WEXT1 / WOPS1 / WROAD2-CLOSEOUT / WROAD2-BIZ1 / WAPPR1 / WAUTO1 / WEXT1LD / WFULLSMOKE1 / WROUTE2 / WRULE1 / WREAL1-PREP 之后。
**关联 Issue**：`WAPI,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WACP3,WACP3R,WREAD1,WADM1,WARCH1,WARCH2,WROAD2,WARCH3,WCHECK1,WEXT1,WOPS1,WROAD2C,WROAD2B,WAPPR1,WAUTO1,WEXT1LD,WFULLSMOKE1,WROUTE2,WRULE1,WREAL1P`。
**最近核对**：2026-07-26（Trellis task `07-26-internal-ops-recovery-baseline`）。
**不得误读**：本文只记录本项目会用到的企业微信官方 API 摘要、链接和项目决策，不复制官方文档全文，不保存 Secret、access token、完整 userid、手机号、邮箱或企微原始 payload。官方文档和企业微信后台权限配置始终是最终依据。

## 1. 固定规则

- 任何企微能力不清楚时，先查企业微信官方开发者文档，再进入 Issue CSV；不得在运行时代码里靠轮询多个 Secret 试错。
- 每个企微 Issue 必须明确接口路径、请求方法、Secret 来源、应用可见范围、可信 IP、回调/模板要求、读写边界、脱敏输出和 `SKIP/BLOCKED_BY_EXTERNAL_CONFIG` 语义。
- 产品 UI 支持不等于开放 API 支持。入职、转正、离职、工资条确认、考勤确认等人事助手产品能力，只有在官方 API 明确支持并通过 POC 后才能进入自动化实现。
- 生产写接口、真实员工批量同步、企微规则写入、应急模式开启和恢复回写都必须另建合同并获得明确批准。
- WPROC1 后默认自动化优先：能用 runner 自动生成、自动检查、自动复跑的，不要求人工手动操作；人工只处理写入批准、Secret/Token/EncodingAESKey 配置、企微后台无法 API 化配置、真机确认和风险拍板。
- WPROC2 后，企微高风险合同必须先通过 `node scripts/qa/check-process-contract.mjs --baseline` 和对应 profile 的 process gate；WAPC2F 使用 `wecom-approval-fixture` profile。
- 审批类 POC 默认禁止自审；WAPC2F/WAPPR1 默认测试链为申请人 `SMOKE002`、审批人 `SMOKE101`，两者必须 active、已绑定企微、可见、不是同一 OA 员工且不是同一企微 userid。若 `SMOKE101` 不可用，不自动换人，返回配置缺口并问答确认。正式模板不得让申请人任意选择审批人，必须按直属主管、部门负责人或指定审批角色自动带出审批人；规则缺口在真实试用前按 `NEEDS_CONFIG` 或 `SKIP/BLOCKED_BY_EXTERNAL_CONFIG` 处理。
- WAPPR1 官方 API 边界：企微审批模板详情接口只返回模板控件，审批申请详情接口只返回已提交后的实际流程节点；当前未发现只读接口可读取原生审批模板的“申请人是否可手选审批人/审批规则配置”。审批规则门禁必须保留后台人工确认和真机提交页确认，API 只做提交后的实际审批链校验。
- WEGOV1 后不假设企业微信自建应用存在完整隔离 sandbox；企微开发默认使用真实企业内受控测试域、本地 synthetic 自动测试、公网 live runner 和少量真机确认。
- OA 自建留存策略优先保存规范化业务数据、完整外部关联键和必要快照；报告和日志只输出脱敏前缀，不保存 Secret、token、EncodingAESKey、原始密文或无治理原始 payload。
- WROAD2 后每日巡检只允许写 OA 自建留存库，不写企业微信；补偿归档写入必须同时具备进程级 `WECOM_ARCHIVE_WRITE=1` 和 runner 的 `--persist-to-db`，并固定使用 `WECOM_AGENT_SECRET`。

## 2. Secret 矩阵

| Secret | 当前标准用途 | 禁止或限制 |
| --- | --- | --- |
| `WECOM_CONTACT_SECRET` | 当前只用于 `/user/list_id` 获取成员 userid 清单。 | 不用于 `/user/get`、部门、工作台消息、人事助手、打卡或审批；运行时代码不得 fallback 到 `WECOM_AGENT_SECRET`。 |
| `WECOM_AGENT_SECRET` | 工作台自建应用和多数开放 API：OAuth/免登、`/user/get`、`/department/list`、应用消息、人事助手/花名册、打卡、审批读取。 | 不用于 `/user/list_id`；缺权限时记录阻断，不换 Secret 试错。 |
| `WECOM_CHECKIN_SECRET` | 仅作为专用打卡应用的显式 override；为空时使用 `WECOM_AGENT_SECRET`。 | 不要求为了打卡重复维护 Secret；只有后台单独建打卡应用时才配置。 |
| `WECOM_HR_ASSISTANT_SECRET` | 当前不作为标准配置，历史兼容项。 | 默认不参与人事助手读取；后续若确需启用，必须先更新本文和 Issue CSV。 |

## 3. 能力目录

| 能力 | 官方文档 | 关键接口 | 方法 | Secret | 当前项目状态 | 本项目使用决策 |
| --- | --- | --- | --- | --- | --- | --- |
| 基础 token | [获取 access_token](https://developer.work.weixin.qq.com/document/path/91039) | `/cgi-bin/gettoken` | `GET` | 按能力域选择对应 Secret | `CAN_REUSE_NOW` | 所有服务端 API 的前置；日志只记录 token source，不输出 token。 |
| 回调配置 | [回调配置](https://developer.work.weixin.qq.com/document/path/90930) | 企业微信后台配置 URL、Token、EncodingAESKey | `GET/POST` 验证事件 | 按回调所属应用 | `NEEDS_CONFIG` | 考勤/审批镜像前必须先证明真实回调可达、可验签、可解密、可幂等入库。 |
| 企业微信接口 IP | [获取企业微信接口 IP 段](https://developer.work.weixin.qq.com/document/path/92520) | `/cgi-bin/get_api_domain_ip` | `GET` | `WECOM_AGENT_SECRET` | `CAN_REUSE_NOW` | 只作为运维排障和防火墙/可信 IP 核对参考。 |
| 企业微信回调 IP | [获取企业微信回调 IP 段](https://developer.work.weixin.qq.com/document/path/92521) | `/cgi-bin/getcallbackip` | `GET` | `WECOM_AGENT_SECRET` | `CAN_REUSE_NOW` | 用于回调入口放行和安全审计，不进入业务数据。 |
| 网页授权链接 | [构造网页授权链接](https://developer.work.weixin.qq.com/document/path/91022) | `connect/oauth2/authorize` | 浏览器跳转 | `WECOM_AGENT_SECRET` 所属应用 | `CAN_REUSE_NOW` | 企业微信工作台入口和 deeplink 回 OA 使用；只改变登录体验，不改变 OA 权限。 |
| 访问用户身份 | [获取访问用户身份](https://developer.work.weixin.qq.com/document/path/91023) | `/cgi-bin/auth/getuserinfo` | `GET` | `WECOM_AGENT_SECRET` | `CAN_REUSE_NOW` | 获取当前企业微信 userid 后匹配 OA 绑定；不能仅靠手机号/邮箱授权登录。 |
| 成员本人敏感资料授权 | [网页授权链接](https://developer.work.weixin.qq.com/document/path/91022)、[访问用户身份](https://developer.work.weixin.qq.com/document/path/91023)、[访问用户敏感信息](https://developer.work.weixin.qq.com/document/path/95833) | `snsapi_privateinfo` + `/cgi-bin/auth/getuserinfo` + `/cgi-bin/auth/getuserdetail` | 浏览器跳转 + `GET/POST` | `WECOM_AGENT_SECRET` 所属应用 | `LOCAL_IMPLEMENTED_EXTERNAL_CONFIG_PENDING` | 普通登录继续用 `snsapi_base`；仅默认关闭的一次性开通入口请求私密授权。成员同意后，服务端用短时 `user_ticket` 立即换取已授权字段；个人邮箱或企业邮箱仍是建档必填，手机号可暂缺，返回时才规范化并检查唯一。票据、code 和原始响应不落库、不写 Cookie、日志或审计。管理员仍需在应用详情选择相应敏感字段，成员需本人确认。 |
| 应用消息 | [发送应用消息](https://developer.work.weixin.qq.com/document/path/90236) | `/cgi-bin/message/send` | `POST` | `WECOM_AGENT_SECRET` | `CAN_REUSE_NOW` | OA 主办审批只发脱敏标题、类型、编号、状态和 OA deeplink；不发送高敏附件。 |
| 通讯录概述 | [通讯录管理](https://developer.work.weixin.qq.com/document/path/90193) | 通讯录成员、部门、回调和导入导出 | 混合 | `WECOM_CONTACT_SECRET` | `CAN_REUSE_NOW_PARTIAL` | 通讯录是单独 Secret 域，和工作台应用 Secret 分开管理。 |
| 管理后台通讯录导出 | 企业微信管理后台导出 XLSX | `npm run import:wecom-directory-export -- --input=- --dry-run` | 本地 stdin | 无 Secret | `LOCAL_IMPLEMENTED_NOT_DEPLOYED` | 作为批量 API 缺少敏感字段时的一次性管理员输入；只接受 stdin、默认 dry-run，真实 apply 需参数和环境变量双门及另行批准。企微账号和企业邮箱必填且唯一，手机号可暂缺并保存为 `NULL`；空来源不清除 OA 既有手机号，报告只输出计数和类别，原文件不入 Git。 |
| 成员 ID 清单 | [获取成员 ID 列表](https://developer.work.weixin.qq.com/document/path/96067) | `/cgi-bin/user/list_id` | `POST` | `WECOM_CONTACT_SECRET` | `CAN_REUSE_NOW` | WOUA/WHMS 全量候选必须走该接口，请求体只使用 `cursor`/`limit`，返回用户-部门关系后本地按 userid 去重；不再用旧 `/cgi-bin/user/list` 做全量读取。 |
| 读取成员 | [读取成员](https://developer.work.weixin.qq.com/document/path/90196) | `/cgi-bin/user/get` | `GET` | `WECOM_AGENT_SECRET` | `OPTIONAL_ENRICHMENT` | 用自建应用 token 补齐 userid 对应的姓名、状态和部门等可见资料。2022-06-20 后新建应用的手机、邮箱和企业邮箱不能以批量接口缺失推断为企微不支持；这些字段按成员本人敏感资料授权链路获取。 |
| 获取部门成员 | [获取部门成员](https://developer.work.weixin.qq.com/document/path/90200) | `/cgi-bin/user/simplelist` | `GET` | `WECOM_CONTACT_SECRET` | `LEGACY_NOT_DEFAULT` | 仅作历史参考，当前全量读取不依赖它。 |
| 获取部门成员详情 | [获取部门成员详情](https://developer.work.weixin.qq.com/document/path/90201) | `/cgi-bin/user/list` | `GET` | `WECOM_CONTACT_SECRET` | `LEGACY_NOT_DEFAULT` | 当前部署曾返回权限错误，不再作为 WOUA/WHMS 全量入口。 |
| 获取部门列表 | [获取部门列表](https://developer.work.weixin.qq.com/document/path/90208) | `/cgi-bin/department/list` | `GET` | `WECOM_AGENT_SECRET` | `OPTIONAL_ENRICHMENT` | 用自建应用 token 做部门名富化；失败不得把 userid 清单误判为空，也不得改用通讯录 token 试错。 |
| 创建成员 | [创建成员](https://developer.work.weixin.qq.com/document/path/90195) | `/cgi-bin/user/create` | `POST` | `WECOM_CONTACT_SECRET` | `DONE_LIVE_VERIFIED` | 已由 HRWD/HCLT 验证公网 create；仅作为管理员修复/迁移能力，不作为默认入职主流程。 |
| 更新成员 | [更新成员](https://developer.work.weixin.qq.com/document/path/90197) | `/cgi-bin/user/update` | `POST` | `WECOM_CONTACT_SECRET` | `DONE_LIVE_VERIFIED` | 仅在明确合同下做受控更新；不得静默覆盖企微资料。 |
| 删除/禁用成员 | [删除成员](https://developer.work.weixin.qq.com/document/path/90198) | `/cgi-bin/user/delete` 或更新启用状态 | `GET/POST` | `WECOM_CONTACT_SECRET` | `DONE_LIVE_VERIFIED_FOR_DISABLE` | 本项目离职默认禁用成员，不删除成员；历史业务和绑定审计保留。 |
| 人事助手概述 | [人事助手](https://developer.work.weixin.qq.com/document/path/99130) | 字段配置、花名册读取、花名册更新 | 混合 | `WECOM_AGENT_SECRET` | `CAN_REUSE_NOW_FOR_READ` | 人事助手产品 UI 功能很多，但当前 API 只按官方开放接口使用。 |
| 员工字段配置 | [获取员工字段配置](https://developer.work.weixin.qq.com/document/path/99131) | `/cgi-bin/hr/get_fields` | `GET` | `WECOM_AGENT_SECRET` | `CAN_REUSE_NOW` | 作为花名册字段解释和后续字段映射依据。 |
| 花名册读取 | [获取员工花名册信息](https://developer.work.weixin.qq.com/document/path/99132) | `/cgi-bin/hr/get_staff_info` | `POST` | `WECOM_AGENT_SECRET` | `CAN_REUSE_NOW` | WHMS/WOUA 读取员工在职资料；不使用 `WECOM_HR_ASSISTANT_SECRET`。 |
| 花名册更新 | [更新员工花名册信息](https://developer.work.weixin.qq.com/document/path/99133) | `/cgi-bin/hr/update_staff_info` | `POST` | `WECOM_AGENT_SECRET` | `NEEDS_API_POC_WRITE` | 写接口，后续需单独低风险 POC 和人工批准；本轮不调用。 |
| 打卡概述 | [打卡](https://developer.work.weixin.qq.com/document/path/90261) | 记录、规则、日报、月报、排班 | 混合 | `WECOM_AGENT_SECRET` 或显式 `WECOM_CHECKIN_SECRET` | `CAN_REUSE_NOW_FOR_READ_PARTIAL` | 企业微信继续做原始采集和风控，OA 只读同步摘要和解释。 |
| 打卡记录 | [获取打卡记录数据](https://developer.work.weixin.qq.com/document/path/90262) | `/cgi-bin/checkin/getcheckindata` | `POST` | `WECOM_AGENT_SECRET` 或显式 `WECOM_CHECKIN_SECRET` | `CAN_REUSE_NOW_FOR_ARCHIVE` | WCHECK1 复用该接口生成规范化明细、日/月摘要和异常摘要；写 OA 留存必须 `--persist-to-db` + `WECOM_CHECKIN_ARCHIVE_WRITE=1`，不写企业微信，不保存完整位置、人脸、设备明文或原始 payload。 |
| 员工打卡规则 | [获取员工打卡规则](https://developer.work.weixin.qq.com/document/path/90263) | `/cgi-bin/checkin/getcheckinoption` | `POST` | `WECOM_AGENT_SECRET` 或显式 `WECOM_CHECKIN_SECRET` | `CAN_REUSE_NOW_FOR_ARCHIVE` | WCHECK1 已新增只读规则快照能力，只保存规则摘要和 hash；报告只输出脱敏 userid 前缀、计数和状态，不保存原始 payload。 |
| 打卡日报/月报/排班 | [日报](https://developer.work.weixin.qq.com/document/path/93374)、[月报](https://developer.work.weixin.qq.com/document/path/93387)、[排班](https://developer.work.weixin.qq.com/document/path/93380) | 官方打卡扩展接口 | `POST` 为主 | `WECOM_AGENT_SECRET` 或显式 `WECOM_CHECKIN_SECRET` | `NEEDS_API_POC` | 不进入当前运行优先主线；后续考勤镜像合同时再做只读 POC。 |
| 审批概述 | [审批](https://developer.work.weixin.qq.com/document/path/91854) | 模板、实例、回调、假期 | 混合 | `WECOM_AGENT_SECRET` | `PARTIAL_NEEDS_CONFIG` | HR/考勤员工日常审批可优先在企微处理，但 OA 镜像尚未实现。 |
| 审批模板详情 | [获取审批模板详情](https://developer.work.weixin.qq.com/document/path/91982) | `/cgi-bin/oa/gettemplatedetail` | `POST` | `WECOM_AGENT_SECRET` | `CAN_REUSE_NOW_FOR_POC_FIXTURES` | WAPC2 runner 已可读模板详情；WAPC2FLIVE 已自动创建 OA-POC 请假/补卡测试模板并复跑得到 `PASS_APPROVAL_POC`。该接口只返回模板控件和字段结构，不返回审批流程规则，也不能证明申请人是否可改审批人。正式模板和外出/加班仍需单独配置或 POC。 |
| 审批申请详情 | [获取审批申请详情](https://developer.work.weixin.qq.com/document/path/91983) | `/cgi-bin/oa/getapprovaldetail` | `POST` | `WECOM_AGENT_SECRET` | `CAN_REUSE_NOW_FOR_ARCHIVE` | WAPC2 runner 已可读审批详情；WAPC2FLIVE 已提交低风险请假/补卡测试审批单并自动复跑通过。该接口可校验已提交审批单的实际审批节点、审批人和状态，但不能证明申请页是否允许手选或修改审批人。WARCH1 复用该接口作为补偿拉取详情最终校准来源，可在 `--persist-to-db` + `WECOM_ARCHIVE_WRITE=1` 双开关下写 OA 自建留存表；WROAD2 每日巡检只通过该路径补齐 OA 留存，不写企业微信。测试单不得包含采购、合同、报销、发票、银行回单或高敏附件。 |
| 审批状态回调 | [审批申请状态变化回调通知](https://developer.work.weixin.qq.com/document/path/91815) | 事件回调 | `GET` URL 验证 / `POST` 事件 | 自建应用回调 Token/EncodingAESKey | `CAN_REUSE_NOW_FOR_ARCHIVE` | WCBK1 已部署只读 `GET/POST /api/wecom/approval/callback` 和 `check:wecom-approval-callback-poc`；公网真实事件已确认。WARCH1 后 POST 回调默认把规范化事件写入 `WecomApprovalCallbackEvent` 和 `WecomApprovalArchive`，DB 写入失败返回非 200 触发企微重试；不保存 Token、EncodingAESKey、原始 XML、密文或原始 payload。 |
| 批量获取审批单号 | [批量获取审批单号](https://developer.work.weixin.qq.com/document/path/91816) | `/cgi-bin/oa/getapprovalinfo` | `POST` | `WECOM_AGENT_SECRET` | `CAN_REUSE_NOW_FOR_ARCHIVE` | WACP3/WACP3R 已新增 `check:wecom-approval-compensation-poc`，支持按 `creator` 自动发现 OA-POC 模板，再按 `template_id` filters 拉审批单号，并用 `getapprovaldetail` 拉详情；WARCH1 增加 OA DB 持久化双开关、补偿 run/item 和对账 finding，用于解决回调证据文件跨部署丢失问题。WROAD2+OPS 每日巡检复用该 runner；只允许以 `WECOM_ARCHIVE_WRITE=1` + `--persist-to-db` 写 OA 留存库，不写企微、不无过滤拉取高风险业务单据。 |
| 提交审批申请 | [提交审批申请](https://developer.work.weixin.qq.com/document/path/91853) | `/cgi-bin/oa/applyevent` | `POST` | `WECOM_AGENT_SECRET` | `DONE_LIVE_VERIFIED_FOR_OA_POC_FIXTURES` | 已接入 WAPC2F QA-only runner；请假/补卡已完成一次 live 创建并保留审计。`use_template_approver=1` 可使用管理后台设置的模板流程，但这是写入型验证，会创建审批单；且官方文档限制部分模板不能通过接口提交，不能作为 WAPPR1 通用只读门禁。WEXT1 扩展外出/加班 payload，但当前后续路线不再自动创建外出/加班 OA-POC 模板，改为 WEXT1-FORMAL 正式模板人工提交 + 系统只读校验。OA 主办报销、采购、合同、项目不迁到企微原生审批。 |
| 审批规则配置读取 | 审批模板详情、审批申请详情、提交审批申请、[审批流程引擎](https://developer.work.weixin.qq.com/document/path/90269) | 无原生审批规则只读接口 | N/A | N/A | `NOT_SUPPORTED_BY_API / NEEDS_MANUAL_GATE` | 当前未发现官方只读 API 可读取企微原生审批模板的“申请人自选节点”“是否允许改审批人”或后台审批规则配置。WAPPR1 必须用管理后台人工确认 + 真机提交页确认 + `getapprovaldetail` 实际审批链校验；审批流程引擎面向自建/第三方应用流程，不等同于读取或修改企业微信原生审批应用规则。 |
| 审批链规则校验 | OA 归档审批详情 + OA 员工主管链/角色 | `npm run check:wecom-approval-rule-validator` | QA-only 本地/远端脚本 | 上游审批详情固定 `WECOM_AGENT_SECRET`；脚本默认只读 OA DB | `CAN_REUSE_NOW_FOR_RULE_POC` | WRULE1 采用“单一组织规则，两个执行域”：OA 维护员工直属主管、业务审批角色和管理员兜底事实，企业微信执行 HR/考勤审批。脚本读取已归档企微审批详情，对比理论审批人和实际审批链，输出 `PASS_RULE_MATCH`、`PASS_WITH_ADMIN_FALLBACK`、`FAIL_APPLICANT_CAN_CHOOSE`、`FAIL_SELF_APPROVAL`、`FAIL_APPROVER_MISMATCH`、`PAUSED_MANUAL_CONFIRMATION` 或 `SKIP/BLOCKED_BY_EXTERNAL_CONFIG`。脚本不读取企微后台规则、不写企微、不替代 WAPPR1 人工门禁。 |
| 假期余额 | [获取成员假期余额](https://developer.work.weixin.qq.com/document/path/93376) | `/cgi-bin/oa/vacation/getuservacationquota` | `POST` | `WECOM_AGENT_SECRET` | `CAN_REUSE_NOW_OR_NEEDS_PERMISSION` | WCPC 已证明可读但历史有权限错误；后续作为考勤镜像的只读项。 |
| 审批模板创建/更新 | [创建审批模板](https://developer.work.weixin.qq.com/document/path/97437)、[更新审批模板](https://developer.work.weixin.qq.com/document/path/97438) | `/cgi-bin/oa/approval/create_template` 等官方模板写接口 | `POST` | `WECOM_AGENT_SECRET` | `DONE_LIVE_VERIFIED_FOR_OA_POC_FIXTURES` | WAPC2FLIVE 已用 `template_name` + `property` controls 结构创建 OA-POC 请假/补卡测试模板并保留审计。WEXT1 只为外出/加班构建 dry-run payload；WREMOTE1 后外出/加班测试改走现有正式模板人工提交，不再自动创建 OA-POC 外出/加班模板；正式模板更新和 RuleOps 写入仍留后期合同。 |

## 4. WAPC1 审批配置准备清单

WAPC1 后，企微审批相关能力进入“配置准备”状态。该状态只说明需要准备哪些后台配置和低风险样例，不代表 OA 已具备审批镜像、回调接收、应急接管、恢复回写或 RuleOps 写入能力。

准备项：

- 首批模板：请假、补卡、外出、加班。
- 每个模板需记录：模板 ID、适用范围、字段项、审批人规则、可见范围、所属自建应用权限。
- 审批人规则属于企微后台配置事实，当前不能用 `gettemplatedetail` 只读拉取；必须由管理员后台确认并在真机提交页复核。
- 测试审批单 `sp_no`：必须为低风险样例，不含采购、合同、报销、发票、银行回单、高敏附件或真实敏感业务资料。
- 回调配置：公网 Callback URL、Token、EncodingAESKey 只进入部署环境；本地文档只记录 `WECOM_APPROVAL_CALLBACK_URL`、`WECOM_CALLBACK_TOKEN`、`WECOM_CALLBACK_ENCODING_AES_KEY` 变量名和配置状态。
- 后续 POC：模板详情读取、审批详情读取、回调验签/解密、事件幂等、重试语义和补偿拉取方案。

## 5. WAPC2 请假/补卡只读 POC

WAPC2 将 WAPC1 的准备项先落为可运行的 QA-only 只读 POC，范围只包括请假和补卡。

- runner：`server/src/scripts/check-wecom-approval-poc.js` / `npm run check:wecom-approval-poc`。
- 模板参数：`--template=leave:<id>`、`--template=missed_punch:<id>` 或同义临时 env。
- 审批单参数：`--sp-no=leave:<sp_no>`、`--sp-no=missed_punch:<sp_no>` 或同义临时 env。
- Secret：固定 `WECOM_AGENT_SECRET`；不使用通讯录、打卡或历史 HR assistant Secret 兜底。
- 报告：只输出模板类型、配置状态、脱敏模板 ID/`sp_no` 前缀、字段类型计数、审批节点计数和错误分类；不输出表单值、附件、评论、完整 `sp_no` 或原始 payload。
- 结论：全部可读为 `PASS_APPROVAL_POC`；缺模板或 `sp_no` 为 `PARTIAL_APPROVAL_POC_NEEDS_CONFIG`；权限、可信 IP、可见范围、Secret 或企微 API 错误为 `SKIP/BLOCKED_BY_EXTERNAL_CONFIG`。

WAPC2 不代表真实回调、审批镜像、应急接管、恢复回写或 RuleOps 已实现。

## 6. WPROC1 后续门禁

WPROC1 将 WAPC2 之后的审批路线固定为：

`WAPC2 -> WAPC2F 自动生成 POC 样件 -> WAPC2FLIVE live 创建与 WAPC2 自动复跑 -> WCBK1 回调只读 POC -> WEGOV1 企微主办治理与自建留存路线修正 -> WACP3/WACP3R 补偿拉取 POC -> WREAD1 审批可读性与误审批防护门禁 -> WADM1 自建留存/镜像数据模型设计 -> WARCH1 最小自建历史留存实现 -> WARCH2 正式只读历史查询 -> WROAD2+OPS 受控上线与每日巡检 -> WARCH3 归档稳定化自动巡检 -> WCHECK1 打卡摘要留存 -> WEXT1 外出/加班 dry-run -> WOPS1 巡检告警降噪 -> WROAD2-CLOSEOUT 三天验收 -> WROAD2-BIZ1 三天业务冒烟 -> WAPPR1 审批规则规范化 -> WRULE1 审批链校验器 POC -> WAUTO1 自动证据汇总 -> WEXT1LD 外出/加班 live 前 dry-run -> WFULLSMOKE1 三天全域最终目标测试 -> WROUTE2 测试号收口到最小镜像路线锁定 -> WTCLOSE2/WTCLOSE2F 远端可信 IP 执行口径修正 -> WREMOTE1/WFULLSMOKE2 远端收口 -> WEXT1-FORMAL 正式模板外出/加班测试 -> 四类测试号证据和审批规则门禁通过后问答 WREAL1 小范围真实试用（首批 1 名真实员工 + 1 名审批人/管理员观察） -> wecom_attendance_approval_mirror_v1 最小完整镜像`

门禁要求：

- `WAPC2F` 已新增 `npm run check:wecom-approval-fixtures`，公网 dry-run 报告 `/app/artifacts/qa-flow/wecom-approval-fixtures-20260519T045001Z/summary.json` 为 `PASS_FIXTURE_DRY_RUN_READY`；它证明 OA-POC 请假/补卡最小通用模板和低风险审批申请 payload 可构建、非自审预检通过。
- `WAPC2FLIVE` 已在用户批准后创建 OA-POC 请假/补卡测试模板和测试审批单，报告 `/app/artifacts/qa-flow/wecom-approval-fixtures-20260519T053400Z/summary.json` 为 `PASS_FIXTURE_CREATED`，自动复跑 WAPC2 为 `PASS_APPROVAL_POC`。首次旧 payload 返回 `301086` 且未创建任何模板或审批单；已修正为官方 `template_name` + `property` controls 结构。
- `WAPC2F/WAPC2FLIVE` 只允许创建 OA-POC 前缀低风险测试模板和测试审批单；默认 dry-run 不获取写入 token、不调用企微写接口，live 写入必须同时具备 CLI 写入参数、`WECOM_APPROVAL_FIXTURE_WRITE=1` 和人工批准。
- `WAPC2F` 固定 `WECOM_AGENT_SECRET`，不得 fallback 到通讯录、打卡或历史 HR assistant Secret。
- `WAPC2F` 默认申请人 `SMOKE002`、审批人 `SMOKE101`；命中自审、同一企微 userid、不可见、未绑定或 inactive 时硬阻断。
- `WCBK1` 必须先证明真实回调 URL 验证、验签、解密、幂等键和重复投递，不保存 Token、EncodingAESKey 或原始密文。
- `WCBK1` 已完成真实回调 POC：`npm run check:wecom-approval-callback-poc -- --live` 先达到 `PASS_CALLBACK_URL_VERIFIED`，随后由 `SMOKE101` 同意一条现有 OA-POC 补卡测试审批单并复跑达到 `PASS_CALLBACK_EVENT_CONFIRMED`。报告只记录事件类型、审批类型、状态、脱敏 `sp_no`/模板前缀和幂等键摘要，不保存 Token、EncodingAESKey、原始 XML、密文、完整 `sp_no`、完整 userid、表单值、附件或评论。
- `WEGOV1` 固定混合架构：企微主办域为 HR/考勤成熟功能，OA 主办域为财务经营和高敏业务，OA 留存域保存企微关键历史和完整外部关联键，OA 应急域只在企微不可用时人工开启。
- `WACP3R` 已把补偿拉取复跑改为自动发现：先按 `SMOKE002` creator 获取 OA-POC 审批单号和详情，识别请假/补卡模板，再按模板过滤拉取详情；公网报告 `/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T115944Z/summary.json` 为 `PASS_WITH_FINDINGS`。finding 是回调证据文件未持久化，不得误读为镜像入库或自建留存已完成。
- `WREAD1/WREAD1F` 已新增只读可读性 runner 并完成请假/补卡真机确认，最终公网报告 `/app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json`，结论 `PASS_READABLE`。用户确认审批消息、审批列表和详情页可看清；驳回有二次确认，同意单击即通过，后续在 WADM1/WARCH1 中处理提示和审计留存风险。
- `WADM1` 必须先设计自建留存和镜像字段、状态机、幂等键、索引、隐私保留和迁移回滚方案，再进入 schema 或业务代码实现。
- `WARCH1` 已把最小自建历史留存落到代码并完成公网验证：回调事件和补偿拉取可写 OA DB，离线 runner 可不调用企微 API 读取已保存历史。公网补偿持久化报告 `/app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T160306Z/summary.json` 为 `PASS_WITH_FINDINGS`，离线读取报告 `/app/artifacts/qa-flow/wecom-approval-archive-20260519T160330Z/summary.json` 为 `PASS_WITH_FINDINGS`；finding 是 WARCH1 前旧回调未入 DB 的历史 gap。该阶段仍只覆盖请假/补卡，不等于完整镜像增强。
- `WARCH2` 在 WARCH1 基础上新增 OA 正式只读历史查询：`GET /api/wecom/approval-archive` 和详情接口只读 OA DB，不调用企业微信 API、不读取企微 Secret、不新增企微写入。权限以 OA employee 关系为准：本人相关、直属下属、HR/admin/*；`leave.view_all` / `attendance.view_all` 不单独代表全量企微归档权限；申请人未映射或 callback-only 记录只允许 HR/admin/* 查看。
- `WROAD2+OPS` 把 WARCH2 后能力先进入测试账号受控上线和 3 天每日巡检，使用 `scripts/qa/run-wroad2-ops-daily.sh` 编排现有 live runner。Day 0 公网报告 `/app/artifacts/qa-flow/wroad2-ops-20260520-041941/summary.json` 为 `PASS_WITH_FINDINGS`：企微 runtime、补偿归档、离线归档读取和隐私扫描通过；finding 为缺 live smoke 登录凭据/pending OCR 子检查异常以及历史 callback gap，不阻断测试账号受控试用。
- `WARCH3` 新增 `scripts/qa/run-warch3-ops-daily.sh`、`deploy/trialrun/install-warch3-ops-timer.sh` 和 `npm run send:wecom-ops-alert`，把巡检升级为服务器 07:30 systemd timer，并在 finding/失败时给 `wangshunli/HYD000006` 发送脱敏企微告警；告警只含阶段、状态、finding 数、报告路径和下一步建议。
- `WCHECK1` 新增 `npm run check:wecom-checkin-summary-archive`，用 `getcheckindata` 和 `getcheckinoption` 生成打卡摘要与规则快照；默认离线只读，写 OA 留存需 `WECOM_CHECKIN_ARCHIVE_WRITE=1`。
- `WEXT1` 扩展 `npm run check:wecom-approval-fixtures` 支持 `--target=outing --target=overtime`，本轮只 dry-run，不 live 创建外出/加班模板或审批单。
- `WROAD2-BIZ1` 补充测试账号人工业务冒烟：打卡、低风险请假/补卡、审批详情查看和 OA 离线历史查看；它不新增企微 API，不替代 WARCH3 自动巡检。
- `WAPPR1` 不新增写接口；它是审批模板配置门禁，要求申请人不得任意选择审批人，正式模板必须自动带出审批人，规则未通过不得进入真实员工试用。由于官方 API 不支持只读读取原生审批规则，WAPPR1 结论必须由后台人工确认、真机提交页确认和 `getapprovaldetail` 提交后实际审批链校验共同组成。
- `WRULE1` 不新增企微 API；它复用 OA 已归档的企微审批详情和 OA 组织事实源，自动校验理论审批人是否匹配实际审批链。WRULE1 可发现自审、实际审批人不符和管理员兜底，但不能证明申请页是否允许手选审批人，仍必须保留 WAPPR1 人工 A/B/C/D 门禁。

### 6.1 WADM1 数据留存与 API 结果边界

WADM1/WARCH1 将已验证的审批能力固定为“可读可留存”的实现输入，但不新增企微 API：

- 模板详情、审批详情、审批状态回调和批量获取审批单号仍全部固定使用 `WECOM_AGENT_SECRET` 或自建应用回调 Token/EncodingAESKey；不得改为多 Secret 试错。
- `getapprovaldetail` 和回调解密结果进入 OA DB 前必须先规范化，保存业务必要字段、完整 `sp_no`、完整 `template_id`、企微 userid、`approval_archive_id` 和摘要 digest；报告和日志只输出脱敏前缀。
- WACP3R 的 `PASS_WITH_FINDINGS` 表明补偿拉取可用，但当时回调证据文件未持久化。WARCH1 已新增 `WecomApprovalCallbackEvent`、`WecomApprovalCompensationRun`、`WecomApprovalCompensationItem` 和 `WecomApprovalReconcileFinding`，用于支撑跨部署比对。
- 不保存原始 XML、密文、access token、Secret、Token、EncodingAESKey 或无治理原始 payload。若后续业务要求保存原始 payload，必须另开加密存储和访问审计合同。
- WARCH1 的 QA-only 离线读取命令为 `npm run check:wecom-approval-archive -- --offline --format=json`；该命令只读 OA DB，不调用企微 API。当前公网离线报告可读取 2 条已通过请假/补卡历史，报告只含脱敏前缀、计数、状态和 finding 类型。WARCH2 的正式查询 API 和页面沿用同一数据边界：DB 内保留完整外部键用于补偿和审计，API/页面只输出脱敏前缀和白名单字段摘要。
- 请假/补卡已通过 WREAD1 真机可读性；外出/加班仍需后续样例或处理决策，不能因接口相同而自动放行。

## 7. 运行优先结论

- 近期优先利用：企业微信工作台入口、OAuth/免登、绑定、个人应用消息、OA deeplink、通讯录 userid 清单、可选成员详情、人事助手花名册读取、打卡记录和打卡规则读取，以及 WROAD2/WARCH3 测试账号受控上线巡检。
- 暂缓深度镜像：WREAD1、WADM1、WARCH1、WARCH2 已完成请假/补卡可读性、模型设计、最小历史留存和正式只读查询；WARCH3/WCHECK1/WEXT1/WOPS1/WROAD2-BIZ1/WAPPR1/WRULE1/WAUTO1/WEXT1LD/WFULLSMOKE1/WROUTE2/WTCLOSE2/WREMOTE1 本轮只解决巡检稳定、打卡摘要留存、外出/加班 dry-run、告警降噪、测试账号业务冒烟、审批规则门禁、理论审批人自动校验、自动证据汇总、全域测试、路线锁定和远端收口；`wecom_attendance_approval_mirror_v1` 最小完整镜像仍需等 WEXT1-FORMAL、四类测试号证据和 WREAL1 小范围真实试用通过后再优先规划；`oa_hr_emergency_mode_v1`、`wecom_recovery_writeback_v1`、`wecom_ruleops_v1` 后置，或你明确批准后再拆。
- OA 主办边界不变：报销、采购、费用、合同、项目、付款批次、AP、代账交接、审计和高敏附件继续在 OA 内完成，只向企业微信发送脱敏提醒和 OA 链接。

## 8. 后续使用要求

- 新增企微能力前，先在本文补一行能力记录，并从当前 Trellis task 组织需求、实现和验证；历史 Issue CSV 仅用于追溯或明确要求的外部导出。
- POC 输出统一使用 `CAN_REUSE_NOW`、`NEEDS_CONFIG`、`NEEDS_API_POC`、`KEEP_OA_PRIMARY`、`NOT_SUPPORTED_BY_API`、`SKIP/BLOCKED_BY_EXTERNAL_CONFIG`。
- 公网验证报告只允许输出脱敏 userid 前缀、计数、错误码、token source 和结论，不得输出 Secret、token、完整 userid、手机号、邮箱或原始 payload。