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

企微 API 能力目录

文档状态：当前企微 API 调研与本项目使用事实源。 分类：集成事实源 / API 能力目录。 适用时间：WAPI / WAPC1 / WAPC2 / WPROC1 / WPROC2 / WAPC2F / WAPC2FLIVE / WCBK1 / WEGOV1 / WACP3 之后。 关联 Issue：WAPI,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WACP3。 最近核对：2026-05-19。 不得误读：本文只记录本项目会用到的企业微信官方 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 默认测试链为申请人 SMOKE002、审批人 SMOKE101，两者必须 active、已绑定企微、可见、不是同一 OA 员工且不是同一企微 userid。若 SMOKE101 不可用，不自动换人，返回配置缺口并问答确认。
• WEGOV1 后不假设企业微信自建应用存在完整隔离 sandbox；企微开发默认使用真实企业内受控测试域、本地 synthetic 自动测试、公网 live runner 和少量真机确认。
• OA 自建留存策略优先保存规范化业务数据、完整外部关联键和必要快照；报告和日志只输出脱敏前缀，不保存 Secret、token、EncodingAESKey、原始密文或无治理原始 payload。

2. Secret 矩阵

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

3. 能力目录

能力	官方文档	关键接口	方法	Secret	当前项目状态	本项目使用决策
基础 token	获取 access_token	/cgi-bin/gettoken	GET	按能力域选择对应 Secret	CAN_REUSE_NOW	所有服务端 API 的前置；日志只记录 token source，不输出 token。
回调配置	回调配置	企业微信后台配置 URL、Token、EncodingAESKey	GET/POST 验证事件	按回调所属应用	NEEDS_CONFIG	考勤/审批镜像前必须先证明真实回调可达、可验签、可解密、可幂等入库。
企业微信接口 IP	获取企业微信接口 IP 段	/cgi-bin/get_api_domain_ip	GET	WECOM_AGENT_SECRET	CAN_REUSE_NOW	只作为运维排障和防火墙/可信 IP 核对参考。
企业微信回调 IP	获取企业微信回调 IP 段	/cgi-bin/getcallbackip	GET	WECOM_AGENT_SECRET	CAN_REUSE_NOW	用于回调入口放行和安全审计，不进入业务数据。
网页授权链接	构造网页授权链接	connect/oauth2/authorize	浏览器跳转	WECOM_AGENT_SECRET 所属应用	CAN_REUSE_NOW	企业微信工作台入口和 deeplink 回 OA 使用；只改变登录体验，不改变 OA 权限。
访问用户身份	获取访问用户身份	/cgi-bin/auth/getuserinfo	GET	WECOM_AGENT_SECRET	CAN_REUSE_NOW	获取当前企业微信 userid 后匹配 OA 绑定；不能仅靠手机号/邮箱授权登录。
应用消息	发送应用消息	/cgi-bin/message/send	POST	WECOM_AGENT_SECRET	CAN_REUSE_NOW	OA 主办审批只发脱敏标题、类型、编号、状态和 OA deeplink；不发送高敏附件。
通讯录概述	通讯录管理	通讯录成员、部门、回调和导入导出	混合	WECOM_CONTACT_SECRET	CAN_REUSE_NOW_PARTIAL	通讯录是单独 Secret 域，和工作台应用 Secret 分开管理。
成员 ID 清单	获取成员 ID 列表	/cgi-bin/user/list_id	POST	WECOM_CONTACT_SECRET	CAN_REUSE_NOW	WOUA/WHMS 全量候选必须走该接口，请求体只使用 cursor/limit，返回用户-部门关系后本地按 userid 去重；不再用旧 /cgi-bin/user/list 做全量读取。
读取成员	读取成员	/cgi-bin/user/get	GET	WECOM_CONTACT_SECRET	OPTIONAL_ENRICHMENT	用于补齐 userid 对应的通讯录详情；若 list_id 与人事助手花名册可读，详情权限不足不阻断 WOUA，只降低可富化字段完整度。
获取部门成员	获取部门成员	/cgi-bin/user/simplelist	GET	WECOM_CONTACT_SECRET	LEGACY_NOT_DEFAULT	仅作历史参考，当前全量读取不依赖它。
获取部门成员详情	获取部门成员详情	/cgi-bin/user/list	GET	WECOM_CONTACT_SECRET	LEGACY_NOT_DEFAULT	当前部署曾返回权限错误，不再作为 WOUA/WHMS 全量入口。
获取部门列表	获取部门列表	/cgi-bin/department/list	GET	WECOM_CONTACT_SECRET	OPTIONAL_ENRICHMENT	只用于部门名富化；失败不得阻断 userid 清单读取和只读对账。
创建成员	创建成员	/cgi-bin/user/create	POST	WECOM_CONTACT_SECRET	DONE_LIVE_VERIFIED	已由 HRWD/HCLT 验证公网 create；仅作为管理员修复/迁移能力，不作为默认入职主流程。
更新成员	更新成员	/cgi-bin/user/update	POST	WECOM_CONTACT_SECRET	DONE_LIVE_VERIFIED	仅在明确合同下做受控更新；不得静默覆盖企微资料。
删除/禁用成员	删除成员	/cgi-bin/user/delete 或更新启用状态	GET/POST	WECOM_CONTACT_SECRET	DONE_LIVE_VERIFIED_FOR_DISABLE	本项目离职默认禁用成员，不删除成员；历史业务和绑定审计保留。
人事助手概述	人事助手	字段配置、花名册读取、花名册更新	混合	WECOM_AGENT_SECRET	CAN_REUSE_NOW_FOR_READ	人事助手产品 UI 功能很多，但当前 API 只按官方开放接口使用。
员工字段配置	获取员工字段配置	/cgi-bin/hr/get_fields	GET	WECOM_AGENT_SECRET	CAN_REUSE_NOW	作为花名册字段解释和后续字段映射依据。
花名册读取	获取员工花名册信息	/cgi-bin/hr/get_staff_info	POST	WECOM_AGENT_SECRET	CAN_REUSE_NOW	WHMS/WOUA 读取员工在职资料；不使用 WECOM_HR_ASSISTANT_SECRET。
花名册更新	更新员工花名册信息	/cgi-bin/hr/update_staff_info	POST	WECOM_AGENT_SECRET	NEEDS_API_POC_WRITE	写接口，后续需单独低风险 POC 和人工批准；本轮不调用。
打卡概述	打卡	记录、规则、日报、月报、排班	混合	WECOM_AGENT_SECRET 或显式 WECOM_CHECKIN_SECRET	CAN_REUSE_NOW_FOR_READ_PARTIAL	企业微信继续做原始采集和风控，OA 只读同步摘要和解释。
打卡记录	获取打卡记录数据	/cgi-bin/checkin/getcheckindata	POST	WECOM_AGENT_SECRET 或显式 WECOM_CHECKIN_SECRET	CAN_REUSE_NOW_FOR_READ	已用于考勤同步 V1；不保存完整位置、人脸、设备明文或原始 payload。
员工打卡规则	获取员工打卡规则	/cgi-bin/checkin/getcheckinoption	POST	WECOM_AGENT_SECRET 或显式 WECOM_CHECKIN_SECRET	CAN_REUSE_NOW_FOR_READ	可作为后续考勤解释和规则快照依据。
打卡日报/月报/排班	日报、月报、排班	官方打卡扩展接口	POST 为主	WECOM_AGENT_SECRET 或显式 WECOM_CHECKIN_SECRET	NEEDS_API_POC	不进入当前运行优先主线；后续考勤镜像合同时再做只读 POC。
审批概述	审批	模板、实例、回调、假期	混合	WECOM_AGENT_SECRET	PARTIAL_NEEDS_CONFIG	HR/考勤员工日常审批可优先在企微处理，但 OA 镜像尚未实现。
审批模板详情	获取审批模板详情	/cgi-bin/oa/gettemplatedetail	POST	WECOM_AGENT_SECRET	CAN_REUSE_NOW_FOR_POC_FIXTURES	WAPC2 runner 已可读模板详情；WAPC2FLIVE 已自动创建 OA-POC 请假/补卡测试模板并复跑得到 PASS_APPROVAL_POC。正式模板和外出/加班仍需单独配置或 POC。
审批申请详情	获取审批申请详情	/cgi-bin/oa/getapprovaldetail	POST	WECOM_AGENT_SECRET	CAN_REUSE_NOW_FOR_POC_FIXTURES	WAPC2 runner 已可读审批详情；WAPC2FLIVE 已提交低风险请假/补卡测试审批单并自动复跑通过。测试单不得包含采购、合同、报销、发票、银行回单或高敏附件。
审批状态回调	审批申请状态变化回调通知	事件回调	GET URL 验证 / POST 事件	自建应用回调 Token/EncodingAESKey	CAN_REUSE_NOW_FOR_CALLBACK_POC	WCBK1 已部署只读 GET/POST /api/wecom/approval/callback 和 check:wecom-approval-callback-poc；公网 synthetic 验签/解密/解析通过后，远端配置真实回调并完成 URL 验证，报告 /app/artifacts/qa-flow/wecom-approval-callback-poc-20260519T083422Z/summary.json 为 PASS_CALLBACK_URL_VERIFIED；SMOKE101 同意现有 OA-POC 补卡测试单后，报告 /app/artifacts/qa-flow/wecom-approval-callback-poc-20260519T092648Z/summary.json 为 PASS_CALLBACK_EVENT_CONFIRMED。该能力仅证明只读回调链路和脱敏证据，不代表镜像入库已实现。
批量获取审批单号	批量获取审批单号	/cgi-bin/oa/getapprovalinfo	POST	WECOM_AGENT_SECRET	PARTIAL_COMPENSATION_NEEDS_CONFIG	WACP3 已新增 check:wecom-approval-compensation-poc，按时间窗口和 template_id filters 拉审批单号，再用 getapprovaldetail 拉详情并与 WCBK1 回调证据比对；公网报告 /app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T112117Z/summary.json 显示 Secret 可用，但缺完整请假/补卡模板 ID 环境变量，暂未证明 live 拉取通过。
提交审批申请	提交审批申请	/cgi-bin/oa/applyevent	POST	WECOM_AGENT_SECRET	DONE_LIVE_VERIFIED_FOR_OA_POC_FIXTURES	已接入 WAPC2F QA-only runner；仅可用于 OA-POC 低风险请假/补卡测试审批单自动样件。默认 dry-run 不获取写入 token、不提交审批；live 写入需显式 CLI、WECOM_APPROVAL_FIXTURE_WRITE=1 和人工批准，申请人/审批人必须非自审。WAPC2FLIVE 已提交请假/补卡测试审批单并保留审计；OA 主办报销、采购、合同、项目不迁到企微原生审批。
假期余额	获取成员假期余额	/cgi-bin/oa/vacation/getuservacationquota	POST	WECOM_AGENT_SECRET	CAN_REUSE_NOW_OR_NEEDS_PERMISSION	WCPC 已证明可读但历史有权限错误；后续作为考勤镜像的只读项。
审批模板创建/更新	创建审批模板、更新审批模板	/cgi-bin/oa/approval/create_template 等官方模板写接口	POST	WECOM_AGENT_SECRET	DONE_LIVE_VERIFIED_FOR_OA_POC_FIXTURES	WAPC2FLIVE 已用 template_name + property controls 结构创建 OA-POC 请假/补卡测试模板并保留审计。正式模板更新、外出/加班模板、RuleOps 写入仍留后期合同。

4. WAPC1 审批配置准备清单

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

准备项：

• 首批模板：请假、补卡、外出、加班。
• 每个模板需记录：模板 ID、适用范围、字段项、审批人规则、可见范围、所属自建应用权限。
• 测试审批单 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 补偿拉取 POC -> WREAD1 审批可读性与误审批防护门禁 -> WADM1 自建留存/镜像数据模型设计 -> WARCH1 最小自建历史留存实现 -> 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 应急域只在企微不可用时人工开启。
• WACP3 已实现补偿拉取 runner，但当前公网只读复跑为 PARTIAL_COMPENSATION_NEEDS_CONFIG，原因是远端缺 WECOM_APPROVAL_LEAVE_TEMPLATE_ID 和 WECOM_APPROVAL_MISSED_PUNCH_TEMPLATE_ID；后续补齐完整模板 ID 后复跑，必须真实输出 PASS_COMPENSATION_POC、PASS_WITH_FINDINGS 或 SKIP/BLOCKED_BY_EXTERNAL_CONFIG，不得无过滤拉取高风险业务审批详情。
• WREAD1 必须用真机或代表设备确认审批消息、审批列表和详情页的可读性；若快捷同意/驳回容易误操作，则模板调整或该模板回退 OA 主办。
• WADM1 必须先设计自建留存和镜像字段、状态机、幂等键、索引、隐私保留和迁移回滚方案，再进入 schema 或业务代码实现。
• WARCH1 必须先实现最小自建历史留存，让 OA 在企微 API 不可用时仍可查看已保存历史，再进入完整镜像增强。

7. 运行优先结论

• 近期优先利用：企业微信工作台入口、OAuth/免登、绑定、个人应用消息、OA deeplink、通讯录 userid 清单、可选成员详情、人事助手花名册读取、打卡记录和打卡规则读取。
• 暂缓深度镜像：wecom_attendance_approval_mirror_v1、oa_hr_emergency_mode_v1、wecom_recovery_writeback_v1、wecom_ruleops_v1 均等 WEGOV1 路线治理后的 WACP3 补偿拉取 POC、WREAD1 可读性门禁、WADM1 自建留存/镜像模型设计、WARCH1 最小历史留存、外出/加班模板测试和打卡细项明确后再拆；WOUA-FIX、WAPC2FLIVE 和 WCBK1 只作为已完成前置证据，不直接放行深度镜像。
• OA 主办边界不变：报销、采购、费用、合同、项目、付款批次、AP、代账交接、审计和高敏附件继续在 OA 内完成，只向企业微信发送脱敏提醒和 OA 链接。

8. 后续使用要求

• 新增企微能力前，先在本文补一行能力记录，再写 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。