WCBK1 实现企微审批回调只读 POC

docs/管理员手册.md

@@ -1,6 +1,6 @@
 # hyb-oa 管理员手册（10 人以下团队版）
 
-**当前状态（2026-05-19 / WAPC2FLIVE）**：R7E、PRELAUNCH、财务闭环、ATTV1、HR-WECOM-DIRECTORY-V1、WAPI、WOUA-FIX、WRV1/WRA1、WMSG1、WAPC1/WAPC2、WPROC1/WPROC2、WAPC2F dry-run 和 WAPC2FLIVE 均已收口；SYSTEM-COMPLETE-GATE 结论为 `GO_TO_USE`。WAPI 后固定企微 API 能力目录和 Secret 矩阵：通讯录使用 `WECOM_CONTACT_SECRET`，人事助手/打卡/消息/OAuth/审批读取使用 `WECOM_AGENT_SECRET`，运行时代码不得靠多个 Secret 试错。WAPC2FLIVE 已创建 OA-POC 请假/补卡测试模板和低风险测试审批单，报告 `/app/artifacts/qa-flow/wecom-approval-fixtures-20260519T053400Z/summary.json` 为 `PASS_FIXTURE_CREATED`，自动复跑 WAPC2 为 `PASS_APPROVAL_POC`；测试模板和审批记录保留审计，不自动删除。WPROC1 明确下一步仍需 WCBK1 回调只读 POC、WACP3 补偿拉取 POC 和 WADM1 镜像数据模型设计，不能直接进入 `wecom_attendance_approval_mirror_v1`。采购、费用、合同、项目、报销、付款、AP、代账交接和高敏附件继续 OA 主办，企业微信只做脱敏提醒和 OA deeplink。公网 `payment_batch_v1=force_on`，`erp_sync=force_off`。公司当前无 ERP/独立财务系统，且 ERP 未来不接入 OA；财务闭环以 OA 内审批、台账、付款批次、银行对公付款回单和月度代账交接为准。
+**当前状态（2026-05-19 / WCBK1）**：R7E、PRELAUNCH、财务闭环、ATTV1、HR-WECOM-DIRECTORY-V1、WAPI、WOUA-FIX、WRV1/WRA1、WMSG1、WAPC1/WAPC2、WPROC1/WPROC2、WAPC2F dry-run、WAPC2FLIVE 和 WCBK1 代码部署均已收口；SYSTEM-COMPLETE-GATE 结论为 `GO_TO_USE`。WAPI 后固定企微 API 能力目录和 Secret 矩阵：通讯录使用 `WECOM_CONTACT_SECRET`，人事助手/打卡/消息/OAuth/审批读取使用 `WECOM_AGENT_SECRET`，运行时代码不得靠多个 Secret 试错。WAPC2FLIVE 已创建 OA-POC 请假/补卡测试模板和低风险测试审批单，报告 `/app/artifacts/qa-flow/wecom-approval-fixtures-20260519T053400Z/summary.json` 为 `PASS_FIXTURE_CREATED`，自动复跑 WAPC2 为 `PASS_APPROVAL_POC`；测试模板和审批记录保留审计，不自动删除。WCBK1 已部署只读回调端点和 synthetic runner，远端报告 `/app/artifacts/qa-flow/wecom-approval-callback-poc-20260519T065414Z/summary.json` 为 `PARTIAL_CALLBACK_NEEDS_CONFIG`，仍需管理员配置 `WECOM_APPROVAL_CALLBACK_URL`、`WECOM_CALLBACK_TOKEN`、`WECOM_CALLBACK_ENCODING_AES_KEY` 后做企微后台 URL 验证和真实事件确认。WPROC1 明确后续仍需 WACP3 补偿拉取 POC 和 WADM1 镜像数据模型设计，不能直接进入 `wecom_attendance_approval_mirror_v1`。采购、费用、合同、项目、报销、付款、AP、代账交接和高敏附件继续 OA 主办，企业微信只做脱敏提醒和 OA deeplink。公网 `payment_batch_v1=force_on`，`erp_sync=force_off`。公司当前无 ERP/独立财务系统，且 ERP 未来不接入 OA；财务闭环以 OA 内审批、台账、付款批次、银行对公付款回单和月度代账交接为准。
 
 ## 1. 适用范围
 - 适用于 `small_team_internal` 工作区模式。
@@ -237,6 +237,14 @@ WAPC1 审批配置准备清单：
 5. 后续进入 POC 前必须确认：模板详情读取、审批详情读取、回调 URL 验证、事件验签、解密、幂等键、重试语义和补偿拉取方案。
 6. 批量获取审批单号只作为补偿拉取候选，先标记 `NEEDS_API_POC`。
 
+WCBK1 回调只读 POC：
+
+1. 当前公网 Callback URL 应配置为 `https://oa.hyinda.com/api/wecom/approval/callback`。
+2. 部署环境变量只写名称，不在文档或聊天保存真实值：`WECOM_APPROVAL_CALLBACK_URL`、`WECOM_CALLBACK_TOKEN`、`WECOM_CALLBACK_ENCODING_AES_KEY`。
+3. `npm run check:wecom-approval-callback-poc` 当前远端结论为 `PARTIAL_CALLBACK_NEEDS_CONFIG`，synthetic 验签/解密/解析已通过。
+4. 配置完成后先复跑 live runner，预期 `PASS_CALLBACK_URL_VERIFIED`；随后由 `SMOKE101` 在企业微信处理一条现有 OA-POC 测试审批单，触发真实事件后复跑，预期 `PASS_CALLBACK_EVENT_CONFIRMED`。
+5. 报告只保存事件类型、审批类型、状态摘要、脱敏 `sp_no`/模板前缀和幂等键摘要；不得截图、转存或粘贴 Token、EncodingAESKey、原始 XML、密文、完整 `sp_no`、完整 userid、表单值、附件或评论。
+
 WAPC2 请假/补卡只读 POC 操作口径：
 
 1. 优先用 WAPC2F runner 自动生成 OA-POC 请假/补卡测试模板和低风险测试审批单；当前 dry-run 已通过，真实创建模板/审批单前仍需管理员批准单次 live 写入。