wangsli/hyb-oa
1
0
派生 0
代码 工单 合并请求 工作流 8 软件包 项目 发布 百科 活动
文件
dcb6913e2fbc073aa536565d6cf6f1311952c7ce
hyb-oa/docs/企微优先开发路线图.md
T

66 KiB
原始文件 Blame 文件历史

企微优先开发路线图

文档状态：当前开发路线图事实源。
分类：开发治理 / 路线图。
适用时间：WDRG / WCP1 / WHMSLIVE / WOUA / WAPI / WRRA / WOUA-FIX / WRV1 / WRA1 / WMSG1 / WAPC1 / WAPC2 / WPROC1 / WPROC2 / WAPC2F / WAPC2FLIVE / WCBK1 / WEGOV1 / WACP3 / WACP3R / WREAD1 / WREAD1F / WADM1 / WARCH1 / WARCH2 / WROAD2 / WARCH3 / WCHECK1 / WEXT1 / WOPS1 / WROAD2-CLOSEOUT / WROAD2-BIZ1 / WAPPR1 / WAUTO1 / WEXT1LD / WREAL1-PREP / WEXT1-LIVE 路线选择之后。 关联 Issue：WDRG,WCP1,WHMS,WHMSLIVE,WOUA,WAPI,WRRA,WOUAFIX,WRV1,WRA1,WMSG1,WAPC1,WAPC2,WPROC1,WPROC2,WAPC2F,WAPC2FLIVE,WCBK1,WEGOV1,WACP3,WACP3R,WREAD1,WREAD1F,WADM1,WARCH1,WARCH2,WROAD2,WARCH3,WCHECK1,WEXT1,WOPS1,WROAD2C,WROAD2B,WAPPR1,WAUTO1,WEXT1LD,WREAL1P。 最近审计：2026-05-20。 不得误读：本文只控制后续开发节奏、阶段顺序和门禁。WHMSLIVE 后只代表企微 HR 主数据镜像已部署并受控验证；WAPI 后进一步固定企微 API/Secret 口径并转为运行优先；WRRA 后明确 PASS_WITH_FINDINGS 只代表只读对账成功且存在差异，不代表企微考勤/审批镜像、OA 应急接管、恢复回写或 RuleOps 已完成运行时实现。WMSG1 只证明企业微信应用消息可达和 Deeplink 可回到 OA；WAPC1 只固化审批配置准备清单；WAPC2 只新增请假/补卡模板详情和低风险 sp_no 审批详情只读 POC，不代表真实回调或镜像能力已完成。WPROC1 后，WAPC2 不直接放行深度镜像，必须先完成自动样件、回调、补偿拉取和镜像数据模型设计门禁。WPROC2 只新增可执行 process gate。WAPC2FLIVE 已创建 OA-POC 请假/补卡测试模板和低风险测试审批单，并自动复跑 WAPC2 得到 PASS_APPROVAL_POC。WCBK1 已完成真实回调 URL 验证和一条现有 OA-POC 测试审批单事件确认，公网报告为 PASS_CALLBACK_EVENT_CONFIRMED；WEGOV1 后路线明确为“企微成熟功能优先上线，OA 做自建留存、审计、入口、消息和应急兜底”。WACP3R 已将补偿拉取复跑修正为自动按 SMOKE002 creator 发现 OA-POC 请假/补卡模板，公网报告 /app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T115944Z/summary.json 为 PASS_WITH_FINDINGS。WREAD1F 新样例后，审批人真机确认请假和补卡消息卡片、列表、详情页均可看清；远端人工结果报告 /app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json 为 PASS_READABLE。但同意按钮单击即通过仍是操作风险，需在 WARCH1/WARCH2 的留存、审计、提示或操作规程中继续处理。WADM1 只完成自建留存/镜像数据模型设计；WARCH1 只实现请假/补卡最小审批历史留存、回调事件入库、补偿拉取入库和 QA-only 离线读取证明；WARCH2 只提供 OA DB 只读查询 API 和 PC/移动历史页，不调用企微 API、不读取企微 Secret、不代表完整镜像、外出/加班、应急接管、恢复回写或 RuleOps 已完成。WROAD2 后当前策略是测试账号受控上线和每日脚本化巡检，允许补偿归档写 OA 自建留存库，但不写企业微信、不扩大真实员工范围；WARCH3 将每日巡检升级为服务器 systemd timer 与脱敏企微告警，WCHECK1 增加打卡规范化明细、日/月摘要和规则快照留存，WEXT1 只完成外出/加班 dry-run 支持。WOPS1 已公网验证巡检告警降噪：HYD000006 是管理员 wangshunli 的 employee_no，脚本不再把姓名字符串当员工号；已知 finding 不重复发送，只有阻断、脚本失败、新增 finding 或状态恶化才告警。WROAD2-BIZ1 在三天内补充测试账号人工业务冒烟；WAPPR1 将申请人任意选择审批人列为真实试用前阻断 finding。WAUTO1 只做只读证据汇总，WEXT1LD 只做外出/加班 live 前 dry-run，均不授权 live 创建。WREAL1-PREP 只准备真实小范围试用清单，不启用真实员工；后续顺序收紧为 WROAD2-CLOSEOUT 三天验收 -> WROAD2-BIZ1 三天业务冒烟 -> WAPPR1 审批规则规范化 -> WAUTO1 自动证据汇总 -> WEXT1LD 外出/加班 live 前 dry-run -> WEXT1-LIVE 外出/加班测试号 live POC -> 请假/补卡/外出/加班四类测试号证据和审批规则门禁通过后再问真实小范围试用。上述阶段仍不代表完整深度镜像、应急接管、恢复回写或 RuleOps 已完成。

1. 路线图原则

  • 采用“路线图门禁 + 单功能 Issue CSV”的工程流程；路线图管顺序和边界，具体实现仍以每个功能的 Issue CSV 为准。
  • 当前路线只覆盖企微优先 HR/考勤域改造：人事助手、通讯录、打卡、HR/考勤审批、OA 自建留存、OA 镜像、OA 应急接管、恢复回写和 RuleOps。
  • 采购、费用、合同、项目、报销、付款批次、AP、代账交接、审计和高敏附件继续 OA 主办；企业微信只做脱敏消息、deeplink、入口和成熟能力参考。
  • WEGOV1 后固定四域边界：企微主办域为打卡、请假、补卡、外出、加班、假期余额和人事助手；OA 主办域为报销、采购、合同、项目、付款、发票、银行回单、高敏附件和经营审计；OA 留存域保存企微关键历史和完整外部关联键；OA 应急域只在企微不可用时由管理员人工开启。
  • OA 不重造企业微信完整打卡、考勤和 HR 产品；V1 目标是企微不可用时可以查看已保存历史，不是完整替代企微继续办理。
  • WROAD2 后“可受控使用”和“完整镜像增强”分离：请假/补卡已归档历史可在 OA 查询，先用测试账号做 3 天每日脚本化巡检；完整镜像、应急接管、恢复回写和 RuleOps 继续后置。
  • 外出/加班不作为当前受控上线阻断；WEXT1 dry-run 已完成，live 创建必须在 WROAD2-CLOSEOUT、WROAD2-BIZ1、WAPPR1、WAUTO1 和 WEXT1LD 结论可接受后另建 WEXT1-LIVE 合同并再次人工确认。
  • WOPS1 后巡检告警采用“状态记忆 + 新增异常”策略：既有 PASS_WITH_FINDINGS observation 进入基线后不重复发企微消息；只有 SKIP/BLOCKED_BY_EXTERNAL_CONFIG、脚本失败、新增 finding、状态恶化或人工 --force 才发送脱敏告警。
  • WAUTO1 把三天受控试用证据汇总脚本化：只复检 /ready、读取既有 WROAD2/WARCH3/WCHECK1/WEXT1 报告、执行只读/离线 runner 和外出/加班 dry-run，不触发 WROAD2 补偿归档写库路径，不写企微、不创建模板或审批单。
  • WEXT1LD 是外出/加班 live 前 dry-run gate：远端只执行 npm run check:wecom-approval-fixtures -- --format=json --target=outing --target=overtime，不设置 WECOM_APPROVAL_FIXTURE_WRITE=1，不带 --live/--create-templates/--submit-test-approvals；通过后仍只进入人工问答。
  • WREAL1-PREP 只做真实小范围试用准备，当前继续测试账号；真实员工名单、试用周期、回滚联系人和验收标准必须等 WROAD2-CLOSEOUT、WROAD2-BIZ1、WAPPR1、WAUTO1/WEXT1LD、WEXT1-LIVE、四类测试号证据和审批规则门禁通过后再通过问答确认。
  • 企业微信自建应用不按完整隔离 sandbox 处理；后续默认使用真实企业内受控测试域、本地 synthetic 自动测试、公网 live runner 和少量真机确认。
  • 阶段未满足退出条件前不得跳阶段。线上缺陷、安全风险、正式使用阻断或真实反馈可以另开独立 Issue CSV，但不得混入企微 HR/考勤主路线。
  • ERP 未来不接入 OA；真实支付、图片 OCR、银行流水导入、复杂 BPM、审批设计器、重预算和其他 P2 大功能继续冻结，试用期只处理阻断和真实反馈。
  • WAPI 后所有企微开发必须先读 企微 API 能力目录，先确认官方 API、Secret、权限、可信 IP、回调/模板和读写边界；运行时代码不得靠多个 Secret 试错。

2. 当前阶段

阶段 状态 结论
DBWFOC 已完成 固定数据边界：HR/考勤员工日常审批企微优先，OA 主办高敏业务不进企微原生审批或企微附件。
WFDG 已完成 固定设计门禁：先判定主办方、数据边界、入口交互、隐私消息、同步审计、应急接管、恢复回写和 RuleOps 边界。
WDRG 已完成 固定开发路线图和节奏；其下一步 WECOM-CAPABILITY-POC-V1 已由 WCP1/WCPC 执行并收口。
WCP1 已完成 已完成只读 POC runner 和远端只读探测，历史结论为 PAUSE_FOR_CONFIG；后续由 WCPC 复跑收口。
WCPC 已完成 已使用既有在职低风险测试号 SMOKE002/测试员工（报告只记录 oa_smoke***）完成远端只读复跑，结论 GO_TO_HR_MASTER_SYNC；该准入已由 WHMS 承接，不得直接跳到考勤/审批镜像、应急、回写或 RuleOps。
WHMSLIVE 已部署并受控公网验证 已部署 wecom_hr_master_sync_v1，应用 migration，公网对 SMOKE002/测试员工（脱敏 oa_smoke***）执行 dry-run 和显式 userids apply；因企微侧缺手机号、邮箱和部门按 missing_required_field 跳过，未写 OA 主数据；普通员工权限负例 403；最终 force_off，未执行生产真实员工批量 apply。
WOUA 已执行并由 WAPI 新口径复跑 初始报告因旧读取路径阻断；WAPI 后远端只读复跑为 PASS_WITH_FINDINGS：OA active 12、企微 active 5、匹配 5、OA active 缺企微 7、已归档仍有绑定 1、缺必填字段 5。该结论明确当前 OA/企微用户不一致，也不批准真实员工批量 apply。
WAPI 已固化运行优先门禁 新增本地企微 API 能力目录和 Secret 矩阵：通讯录使用 WECOM_CONTACT_SECRET，人事助手/打卡/消息/OAuth 使用 WECOM_AGENT_SECRET；WOUA/WHMS 读取改为 user/list_id + 可选成员详情 + 花名册读取；后续先利用入口、通知、通讯录 userid、人事助手读取和打卡读取。
WRRA 已固化路线修正 收紧运行优先退出门禁：PASS_WITH_FINDINGS 不能直接放行深度镜像；下一步默认先做 WOUA-FIX / WECOM-RUNTIME-READY-V1，收口用户一致性差异或明确 WHMS 同步窗口后再判断是否进入考勤/审批镜像准备。
WOUA-FIX 已受控执行并公网复检 按用户确认将 7 个 OA active 缺企微测试账号软归档，修正 T0000 seed 复活问题，并转交 SMOKE201 归档后遗留的测试主管/待办副作用；复检 OA active 5、企微 active 5、匹配 5、OA active 缺企微 0。剩余 5 个企微缺字段先接受不补，1 个归档绑定保留审计，不写企微资料、不执行真实员工 WHMS 批量 apply。
WRV1 已部署并公网只读验证 新增 QA-only runner server/src/scripts/check-wecom-runtime-ready.js 和 npm run check:wecom-runtime-ready。公网 live 报告 /app/artifacts/qa-flow/wecom-runtime-ready-20260518T173402Z/summary.json 为 SKIP/BLOCKED_BY_EXTERNAL_CONFIG：入口/OAuth、Secret 矩阵、OA active 绑定、通讯录 user/list_id、人事助手 get_staff_info 和消息 dry-run 均通过；打卡读取因 WECOM_CHECKIN_SYNC_ENABLED=true 未启用而阻断；审批模板、测试 sp_no、真实回调配置仍为 NEEDS_CONFIG。不补企微资料、不发默认真实消息、不写 OA/企微用户资料。
WRA1 已部署并公网复跑 修正 WRV1 门禁误判：WECOM_CHECKIN_SYNC_ENABLED 保留为正式考勤同步开关，但 QA-only 运行验收打卡只读探测显式使用 requireSyncEnabled=false。公网报告 /app/artifacts/qa-flow/wecom-runtime-ready-20260518T180506Z/summary.json 为 PASS_WITH_CONFIG_GAPS：打卡 API 只读可读且记录 readable_sync_disabled，审批模板、测试 sp_no 和真实回调仍为 NEEDS_CONFIG。
WMSG1 已完成真机确认 使用现有 check:wecom-runtime-ready runner 单次发送脱敏企微应用消息；报告 /app/artifacts/qa-flow/wecom-runtime-ready-20260518T234431Z/summary.json 显示 checks.message.status=OK、errcode=0、recipientCount=1，用户确认收到“OA 运行就绪检查”并可点击进入 OA 通知页面。
WAPC1 配置准备清单已固化 WMSG1 后的下一步改为审批配置准备清单：首批关注请假、补卡、外出、加班模板；准备模板 ID、低风险测试 sp_no、真实回调 URL/Token/EncodingAESKey 和后续 POC 准入项。本阶段不接真实回调、不调用写接口、不进入深度镜像。
WAPC2 已部署并公网只读复跑 新增 QA-only npm run check:wecom-approval-poc，范围先锁定请假和补卡；固定 WECOM_AGENT_SECRET 调用 POST /cgi-bin/oa/gettemplatedetail 与 POST /cgi-bin/oa/getapprovaldetail，报告只输出脱敏模板 ID/sp_no 前缀、字段/节点计数和错误分类。公网报告 /app/artifacts/qa-flow/wecom-approval-poc-20260519T020429Z/summary.json 为 PARTIAL_APPROVAL_POC_NEEDS_CONFIG：Secret 可用，但缺请假/补卡模板 ID 和两条低风险 sp_no，未伪造成 PASS。
WPROC1 路线与流程门禁已修正 固化三层门禁、Definition of Ready、Definition of Done、自动化优先和非自审规则。WAPC2F 默认测试链为 SMOKE002 -> SMOKE101，若 SMOKE101 不可用，不自动换人，先问答确认；后续当前顺序以 WEGOV1 行和阶段表为准。
WPROC2 流程自动化门禁已新增 新增 scripts/qa/check-process-contract.mjs，把 WPROC1 的三层门禁、DoR/DoD、自动化优先、非自审、Secret 固定、live 写入开关、缺配置分类和脱敏边界升级为可执行 process gate；WAPC2F 实施前必须先通过 baseline gate 和 wecom-approval-fixture profile。
WAPC2F 已实现并公网 dry-run 通过 新增 QA-only npm run check:wecom-approval-fixtures，固定 WECOM_AGENT_SECRET 构建 OA-POC 请假/补卡最小通用模板和低风险审批申请 payload；默认 dry-run 不获取写入 token、不调用企微写接口。公网报告 /app/artifacts/qa-flow/wecom-approval-fixtures-20260519T045001Z/summary.json 为 PASS_FIXTURE_DRY_RUN_READY：SMOKE002 -> SMOKE101 active、已绑定、非自审。
WAPC2FLIVE 已完成 live 创建与 WAPC2 自动复跑 用户批准后执行一次 live 创建窗口：第一次旧 payload 返回 301086 且未创建任何模板或审批单；修正为官方 template_name + property controls 后，远端报告 /app/artifacts/qa-flow/wecom-approval-fixtures-20260519T053400Z/summary.json 为 PASS_FIXTURE_CREATED，已创建 OA-POC 请假/补卡测试模板和低风险测试审批单，checks.autoRerun.status=OK 且 PASS_APPROVAL_POC。测试模板和测试审批记录保留审计，不自动删除；仍不放行深度镜像。
WCBK1 真实回调 URL 与事件已确认 新增只读 GET/POST /api/wecom/approval/callback、npm run check:wecom-approval-callback-poc 和 wecom-callback process gate。远端配置回调 URL、Token 和 EncodingAESKey 后，live runner 报告 /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，脱敏证据记录 eventCount=1、状态 已通过。
WEGOV1 路线和治理已调整 明确混合架构：企微成熟功能优先上线，OA 做自建数据留存、审计、入口、消息和应急兜底；固化受控测试域、自动化优先和人工边界；后续顺序调整为 WACP3、WREAD1、WADM1、WARCH1 后再评估深度镜像。
WACP3/WACP3R 已实现并公网只读复跑，有 findings 新增 QA-only npm run check:wecom-approval-compensation-poc 和 POST /cgi-bin/oa/getapprovalinfo 只读封装，固定 WECOM_AGENT_SECRET。WACP3R 改为按 SMOKE002 creator 自动发现 OA-POC 请假/补卡模板 ID，再按模板过滤拉审批单号并用 getapprovaldetail 拉详情；公网报告 /app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T115944Z/summary.json 为 PASS_WITH_FINDINGS：请假/补卡各拉到 1 条详情，发现回调证据文件未持久化导致当前无法跨部署比对历史回调。未写 OA/企微数据，未保存完整模板 ID。
WREAD1/WREAD1F 请假/补卡真机确认已通过 新增 QA-only npm run check:wecom-approval-readability-gate，只读汇总 OA-POC 请假/补卡证据并输出人工确认清单。WREAD1F 重新生成新样例后，审批人真机确认请假和补卡均可看清；远端报告 /app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json 为 PASS_READABLE。风险记录：驳回有二次确认，但同意单击即通过，后续 WADM1/WARCH1 需纳入提示、审计或操作规程。
WADM1 自建留存/镜像模型设计已固化 docs-only 固定 OA 留存域数据模型：企微审批主表、参与人/节点/动作、字段摘要、附件摘要、回调事件、补偿拉取 run/item、对账 finding、打卡/人事快照边界、隐私保留、权限和 WARCH1 最小实现切片。WADM1 解决 WACP3R “回调证据文件未持久化”的模型设计缺口，但不创建迁移、不写入业务数据、不放行完整镜像。
WARCH1 最小审批历史留存已实现并公网验证 新增 WecomApprovalArchive 等审批留存表、回调事件表、补偿拉取 run/item/finding 表；回调 POST 默认写 OA DB，失败返回非 200 让企微重试；补偿 runner 支持 --persist-to-db + WECOM_ARCHIVE_WRITE=1 双开关写 OA 留存；新增 npm run check:wecom-approval-archive 离线读取 OA DB 历史摘要。公网报告 /app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T160306Z/summary.json 与 /app/artifacts/qa-flow/wecom-approval-archive-20260519T160330Z/summary.json 均为 PASS_WITH_FINDINGS：请假/补卡 2 条历史可离线读取，finding 是 WARCH1 前旧回调未入 DB 的历史 gap，已作为对账 finding 留存。范围仅请假/补卡，不写企微、不做完整镜像、不做应急接管或恢复回写。
WARCH2 已部署并公网只读验证 新增只读 GET /api/wecom/approval-archive 和 GET /api/wecom/approval-archive/:id，以及 PC/移动共用历史页 /wecom-approval-archive、/mobile/wecom-approval-archive。查询只读 OA DB，不调用企微 API、不读取企微 Secret；权限固定为本人相关、直属下属和 HR/admin/* 全量，leave.view_all / attendance.view_all 不单独代表全量企微归档权限；申请人未映射、callback-only、外部-only 记录只允许 HR/admin/* 查看。页面文案固定“企业微信主办，OA 自建留存”“仅已归档记录”，不提供审批动作。公网 SYNC_ENV=0 部署已完成，/ready 正常，新 API 未登录返回 401；远端离线归档报告 /app/artifacts/qa-flow/wecom-approval-archive-20260520T013610Z/summary.json 为 PASS_WITH_FINDINGS，可读 2 条请假/补卡历史，finding 仍是 WARCH1 前旧回调未入库历史 gap。
WROAD2+OPS 受控上线和每日巡检 Day 0 已完成 当前进入测试账号受控上线：范围固定 SMOKE002 -> SMOKE101，管理员观察和告警员工号固定 HYD000006，即管理员 wangshunli 的 employee_no；脚本不再把姓名字符串 wangshunli 当员工号。试用 3 天，每日触发一键巡检脚本。巡检复用 /ready、live smoke、feature flag、企微 runtime、审批补偿和 OA 归档离线读取；仅补偿归档步骤可用进程级 WECOM_ARCHIVE_WRITE=1 写 OA 自建留存库，不写企业微信、不创建模板或审批单。Day 0 报告 /app/artifacts/qa-flow/wroad2-ops-20260520-041941/summary.json 为 PASS_WITH_FINDINGS，finding 为缺 live smoke 登录凭据/pending OCR 子检查异常以及历史 callback gap，按已知 observation 不阻断测试账号受控试用。
WARCH3 归档稳定化自动巡检已实现 新增 scripts/qa/run-warch3-ops-daily.sh 聚合 WROAD2 子报告、归类 observation/finding、解释历史 callback gap，并新增 deploy/trialrun/install-warch3-ops-timer.sh 安装服务器 systemd service/timer，每天 07:30 触发；WOPS1 后巡检告警默认只发 HYD000006，由 npm run send:wecom-ops-alert 读取状态文件判断新增 finding 或状态恶化，已知 finding 不重复告警。仍只允许补偿归档写 OA DB，不写企业微信、不创建模板或审批单。
WCHECK1 打卡摘要留存已实现 新增打卡日/月摘要和规则快照留存表、wecomCheckinArchive 服务和 npm run check:wecom-checkin-summary-archive runner。保存规范化打卡明细、日/月摘要、异常摘要、规则快照摘要和 hash；报告只输出计数、状态、异常摘要和脱敏 userid 前缀，不保存完整位置、人脸、设备明文或原始 payload。
WEXT1 外出/加班 dry-run 已实现 扩展 npm run check:wecom-approval-fixtures 支持 --target=outing --target=overtime，只构建 OA-POC 外出/加班最小通用模板和低风险审批申请 payload，仍默认 dry-run。已锁定后续 live 范围为外出+加班两类一起创建、样件保留审计、SMOKE101 真机确认，但必须等 WROAD2-CLOSEOUT、WROAD2-BIZ1、WAPPR1、WAUTO1/WEXT1LD 可解释通过后另起 WEXT1-LIVE 合同。
WOPS1 巡检告警降噪已公网验证 将 WARCH3 告警从“有 finding 就发”改为“阻断、失败、新增 finding 或状态恶化才发”；默认收件员工号 HYD000006。远端二次触发报告 /app/artifacts/qa-flow/wecom-ops-alert-20260520T070740Z/summary.json 为 PASS_ALERT_SKIPPED_NO_FINDINGS，原因 no_new_findings_or_status_worsening；状态文件只保存脱敏状态、finding 摘要和报告路径。
WROAD2-CLOSEOUT 三天验收采集中 Day 1/2/3 继续由 WARCH3 timer 采集；已知 observation（live smoke 凭据、pending OCR、历史 callback gap）可接受但要保留趋势；三天结束后只在异常或验收点问答，若通过则进入 WEXT1-LIVE 合同，不直接启用真实员工。
WROAD2-BIZ1 三天人工业务冒烟已建档 三天内并行补充测试账号业务动作：SMOKE002 每天按规则尝试企微打卡，提交低风险请假/补卡；SMOKE101 先看详情再审批；HYD000006 每天查看 OA 归档历史和打卡摘要。人工业务冒烟不替代 WARCH3 自动巡检，不写企业微信，不启用真实员工。
WAPPR1 审批规则规范化门禁已建档 用户发现补卡申请需要手动选择审批人后，正式把“申请人不得任意选择审批人”列为真实试用前门禁。测试模板固定 SMOKE002 -> SMOKE101；正式模板必须按直属主管、部门负责人或指定审批角色自动带出审批人；审批人缺失、停用、未绑定、不可见或自审时阻断。
WAUTO1 自动证据汇总已实现 新增 scripts/qa/collect-wecom-controlled-trial-evidence.sh，只读汇总 WROAD2/WARCH3/WCHECK1/WROAD2-BIZ1/WAPPR1/WEXT1 dry-run 证据，并复跑 /ready、审批补偿只读、审批归档离线、打卡摘要 offline、外出/加班 dry-run 和隐私扫描。脚本默认不写 OA DB、不写企业微信、不创建模板或审批单，结论限定为 PASS_AUTO_EVIDENCE_READY、PASS_WITH_FINDINGS、PAUSED_MANUAL_CONFIRMATION 或 SKIP/BLOCKED_BY_EXTERNAL_CONFIG。
WEXT1LD 外出/加班 live 前 dry-run gate 已实现 新增独立 dry-run 合同，远端只执行外出+加班 payload dry-run；固定 SMOKE002 -> SMOKE101 和 WECOM_AGENT_SECRET，不尝试其他 Secret，不设置写入双开关。dry-run 通过后仍必须问答选择是否一次性 live 创建样件、只保留 dry-run 或移出 V1。
WREAL1-PREP 真实小范围试用准备已固化 只固化候选员工条件、非自审审批人条件、回滚联系人、允许流程、暂停条件和验收标准；当前继续测试账号，四类测试号证据和 WAPPR1 审批规则门禁通过后才问是否启动真实小范围试用。

3. 阶段路线

顺序 阶段 目标 进入条件 退出条件
1 WECOM-CAPABILITY-POC-V1 只读或低风险探测企微 API 能力，输出能力矩阵。 WDRG 完成；企微后台权限、Secret、可信 IP、模板和可见范围按现状记录。 人事助手、通讯录、打卡、审批、假期余额、回调和权限配置均有 CAN_REUSE_NOW、NEEDS_CONFIG、NEEDS_API_POC、KEEP_OA_PRIMARY 或 NOT_SUPPORTED_BY_API 结论。
2 wecom_hr_master_sync_v1 企微/人事助手员工、部门、主管、职位、联系方式和在职状态镜像到 OA。 POC 证明人事助手/通讯录读取和回调能力可用，或明确缺口处理方式。 WHMSLIVE 后已完成本地门禁、部署和受控公网验证；OA 可自动创建/更新员工档案、账号、角色、企微绑定和审计；最终 force_off，真实员工批量 apply 仍需单独批准；缺配置时记录 SKIP/BLOCKED_BY_EXTERNAL_CONFIG。
3 runtime_first_wecom_enablement 先把已可用企微能力用于系统运行：入口、免登/绑定、脱敏消息、deeplink、通讯录 userid 清单、人事助手读取、打卡读取和只读对账。 WAPI API 目录和 Secret 矩阵完成；WOUA 按新读取策略复跑。 WOUA-FIX 后 OA active 缺企微已清零；WRV1/WRA1 通过 check:wecom-runtime-ready 给出运行优先结论；WMSG1 已证明真实消息和 Deeplink 可用。PASS_WITH_CONFIG_GAPS 只允许继续入口、免登、消息和只读读取主链路，不放行深度镜像；审批模板、测试 sp_no、真实回调仍阻断 wecom_attendance_approval_mirror_v1。
4 WAPC1 / WAPC2 审批配置准备和请假/补卡模板详情、低风险审批详情只读 POC。 运行优先门禁完成；WMSG1 消息和 Deeplink 已确认。 WAPC2 runner 已部署，缺模板 ID 或 sp_no 时真实记录 PARTIAL_APPROVAL_POC_NEEDS_CONFIG，不放行深度镜像。
5 WAPC2F 自动生成 POC 样件 尽量用 QA-only runner 自动创建 OA-POC 请假/补卡测试模板和低风险测试审批单。 WAPC2 已证明 Secret 可用但缺模板或 sp_no；WPROC2 baseline gate 和 WAPC2F profile gate 通过；dry-run 先通过；live 写入需用户批准。 已完成：PASS_FIXTURE_CREATED。创建使用显式 --live --create-templates --submit-test-approvals 和单次进程 WECOM_APPROVAL_FIXTURE_WRITE=1；申请人 SMOKE002、审批人 SMOKE101 通过 active、绑定、可见和非自审预检；报告只记录脱敏模板 ID / sp_no 前缀。
6 WAPC2 自动复跑 使用 WAPC2F 生成的脱敏模板 ID 和 sp_no 自动复跑只读 POC。 WAPC2F live 写入生成全部或部分样件。 已完成：live 报告中 checks.autoRerun.status=OK，请假/补卡模板详情与审批详情可读，结论 PASS_APPROVAL_POC。
7 WCBK1 回调只读 POC 证明真实回调 URL 验证、验签、解密、幂等键和重复投递处理。 回调 URL、Token、EncodingAESKey 由部署环境配置；不得写入仓库或聊天。 已完成：PASS_CALLBACK_EVENT_CONFIRMED。远端 live URL 验证通过后，由 SMOKE101 处理现有 OA-POC 补卡测试单触发真实事件；报告只记录脱敏事件类型、状态、sp_no/模板前缀和幂等键摘要。
8 WEGOV1 企微主办治理与自建留存路线修正 固化混合主办边界、OA 自建留存策略、受控测试域和后续顺序。 WCBK1 已确认真实回调事件；用户选择优先利用企微成熟功能并要求 OA 保存关键历史。 docs-only 收口；文档明确企微主办域、OA 主办域、OA 留存域、OA 应急域、自动化与人工边界。
9 WACP3 补偿拉取 POC 证明按时间窗口批量获取审批单号并可拉取审批详情，作为回调丢失补偿。 WEGOV1 完成；WAPC2/WAPC2FLIVE/WCBK1 已提供低风险样例、详情读取和真实事件证据；官方 API 和权限明确。 WACP3R 已自动发现 OA-POC 请假/补卡模板并复跑到 PASS_WITH_FINDINGS：补偿拉取和详情读取可用；findings 为当前回调证据文件未持久化，需在 WADM1/WARCH1 设计留存模型时解决。
10 WREAD1 企微审批可读性与误审批防护门禁 真机确认请假、补卡、外出、加班在企微里是否看得清再批，评估快捷同意/驳回误操作风险。 WACP3 完成或并行准备低风险样例；审批模板可在企微手机端由代表审批人查看。 请假/补卡已由 WREAD1F 真机确认 PASS_READABLE；驳回有二次确认，同意单击即通过，后续作为操作风险进入 WADM1/WARCH1 设计。外出/加班仍需后续样例或处理决策；不可读模板不得进入正式镜像。
11 WADM1 自建留存/镜像数据模型设计 先设计 OA 留存字段、状态机、幂等键、索引、隐私保留、审计和迁移回滚方案。 WACP3 证明补偿拉取可用；WREAD1 明确模板可读性或回退策略。 已完成 docs-only 设计：模型覆盖审批、打卡、人事关键快照、回调事件和补偿拉取记录；只允许在单独 WARCH1 合同批准后进入 schema 或业务代码实现。
12 WARCH1 最小自建历史留存实现 先保存企微审批最小历史，满足企微 API 不可用时可查看已保存请假/补卡摘要。 WADM1 完成并批准 schema/接口实现。 已新增 OA DB 审批留存、回调事件、补偿 run/item/finding、双开关补偿入库和离线读取 runner；公网已持久化现有请假/补卡详情并离线读取 2 条已通过历史。报告和日志只输出脱敏前缀；不保存 Secret、token、EncodingAESKey、原始密文或无治理原始 payload。
13 WARCH2 正式只读历史查询 把 WARCH1 runner 级离线证明升级为正式 OA API 和 PC/移动历史页。 WARCH1 已持久化请假/补卡历史；权限与脱敏合同批准。 已完成：查询 API、PC/移动页面、SYNC_ENV=0 公网部署、/ready、未登录 401、离线归档 runner 均通过。V1 仍只覆盖请假/补卡，不调用企微 API，不提供审批动作。
14 WROAD2+OPS 受控上线与每日巡检 把 WARCH2 后的能力先放入测试账号受控使用，用每日脚本化巡检验证入口、运行、补偿归档和 OA 离线查询稳定性。 WARCH2 公网验证完成；用户选择先受控上线、不直接深镜像；允许 SYNC_ENV=0 部署和补偿归档写 OA DB。 Day 0 公网巡检已生成 /app/artifacts/qa-flow/wroad2-ops-20260520-041941/summary.json，结论 PASS_WITH_FINDINGS；后续以 WARCH3 systemd timer 承接每日巡检。脚本不写企业微信、不创建样件；发现缺配置时真实记录 SKIP/BLOCKED_BY_EXTERNAL_CONFIG。
15 WARCH3 归档稳定化 稳定每日补偿、归档对账 finding、历史查询可用性、旧 callback gap 解释和报告趋势。 WROAD2+OPS Day 0 和用户批准 systemd timer。 已新增 WARCH3 汇总脚本、脱敏企微告警和 07:30 systemd timer 安装脚本；WOPS1 后默认收件员工号为 HYD000006，已知 finding 不重复告警；每日归档报告可解释，live smoke/OCR 仅作 observation。公网安装和 Day 1/2/3 汇总仍按 WARCH3/WROAD2 证据回填。
16 WCHECK1 打卡摘要留存 保存规范化打卡明细、日/月摘要、异常摘要和规则快照。 WROAD2+OPS 或 WARCH3 证明审批归档稳定；打卡只读 API 和权限仍可用。 已新增摘要表、规则快照、归档服务和 QA runner；OA 可查看必要打卡摘要和异常摘要；不保存完整位置、人脸、设备明文或原始 payload。
17 WEXT1 外出/加班 dry-run 自动生成外出/加班低风险 POC 样件 payload，但不 live 创建。 用户批准先做 dry-run。 已扩展 WAPC2F runner 支持 outing、overtime dry-run；非自审、Secret 固定和脱敏报告沿用既有门禁。live 创建模板/审批单前必须再次问答批准。
18 WOPS1 巡检告警降噪 修正管理员告警收件人和重复 finding 告警策略。 WARCH3 已公网验证，用户要求告警只报新增异常。 已公网验证：/app/artifacts/qa-flow/warch3-ops-20260520-070731/summary.json 为 PASS_WITH_FINDINGS，告警 /app/artifacts/qa-flow/wecom-ops-alert-20260520T070740Z/summary.json 为 PASS_ALERT_SKIPPED_NO_FINDINGS；默认收件员工号 HYD000006，重复已知 finding 不发送。
19 WROAD2-CLOSEOUT 三天验收 汇总 Day 0/1/2/3 巡检报告，决定是否进入外出/加班 live POC。 WOPS1 本地和公网验证通过；WARCH3 timer 正常。 输出 PASS_CONTROLLED_OPS_READY、PASS_WITH_FINDINGS、PAUSED_MANUAL_CONFIRMATION 或 SKIP/BLOCKED_BY_EXTERNAL_CONFIG，并结合 WROAD2-BIZ1 人工业务冒烟结果问答确认。
20 WROAD2-BIZ1 三天业务冒烟 在测试账号范围补充真实业务动作：打卡、请假、补卡、OA 离线查看，并为外出/加班 live POC 准备人工验收清单。 用户选择三天内测试更多业务；仍限定测试账号。 输出 PASS_BUSINESS_SMOKE_READY、PASS_WITH_FINDINGS、PAUSED_MANUAL_CONFIRMATION 或 SKIP/BLOCKED_BY_EXTERNAL_CONFIG；不写企微、不创建外出/加班样件。
21 WAPPR1 审批规则规范化门禁 统一企微 HR/考勤审批人规则，禁止申请人任意选择审批人。 发现补卡申请需要手动选择审批人；用户要求审批规则按规范自动化。 四类模板按模板给出 PASS_APPROVER_RULES_READY、PASS_WITH_TEMPLATE_ADJUSTMENTS、FAIL_KEEP_OA_PRIMARY_FOR_THIS_TEMPLATE 或 SKIP/BLOCKED_BY_EXTERNAL_CONFIG；规则不通过不得进入真实试用。
22 WAUTO1 受控试用证据自动汇总 自动汇总三天受控试用证据，准备 WAPPR1 人工确认和 WEXT1-LIVE 问答。 WROAD2-BIZ1/WAPPR1 已建档，用户要求能自动执行的全部脚本化。 新脚本默认只读，不触发补偿归档写库，不写企微；输出脱敏 summary 和 WAPPR1 人工清单。
23 WEXT1LD 外出/加班 live 前 dry-run gate 在 live 创建前远端只执行外出/加班 dry-run。 WEXT1 dry-run runner 已存在；用户要求 live 前先自动 dry-run。 不带 live 写入参数；通过后只进入问答，不自动创建模板或审批单。
24 WREAL1-PREP 真实试用准备 固化候选员工、审批人、允许流程、暂停条件、回滚联系人和验收标准，不启用真实员工。 用户选择可以并行准备但暂不引入真实员工。 文档和合同明确真实试用需等四类测试号证据和 WAPPR1 审批规则门禁通过后再问；当前继续测试账号。
25 WEXT1-LIVE 外出/加班测试号 live POC 单次创建外出+加班 OA-POC 模板和低风险测试审批单，并做真机可读性和审批规则确认。 WROAD2-CLOSEOUT/WROAD2-BIZ1/WAPPR1/WAUTO1/WEXT1LD 可解释通过；新建独立 Issue CSV；再次说明会留下的企微记录并取得人工确认。 两类样件保留审计；固定 SMOKE002 -> SMOKE101、WECOM_AGENT_SECRET 和双开关；只保存脱敏 template/sp_no/userid 前缀；SMOKE101 真机确认消息、列表、详情、按钮风险和审批人是否自动带出。
26 WREAL1 小范围真实试用 在 1-2 名真实员工范围验证企微主办 HR/考勤和 OA 留存。 请假、补卡、外出、加班四类测试号证据通过；WAPPR1 规则门禁通过；用户通过问答提供真实员工、审批人、试用周期、暂停条件和回滚联系人。 试用报告可解释通过或暂停；仍不直接全员推广。
27 wecom_attendance_approval_mirror_v1 企微打卡、请假、补卡、外出、加班、假期余额和审批历史镜像到 OA。 WREAL1 通过后再规划；不得仅凭测试号证据进入。 OA 可查询企微 HR/考勤镜像、附件摘要、审批历史、考勤解释和审计；不把 OA 主办高敏审批迁到企微。
26 oa_hr_emergency_mode_v1 企业微信不可用时，由管理员人工开启 OA HR/考勤应急接管。 自建历史留存和镜像数据可支撑对账；OA 应急入口、权限和审计方案明确。 管理员可填写原因、范围、预计结束时间和责任人后开启/关闭；应急单据带 EMERGENCY 标记。
27 wecom_recovery_writeback_v1 企微恢复后，OA 应急数据先 dry-run，再回写企微。 应急接管模式完成；企微写回接口、冲突规则和回滚策略已单独批准。 系统生成成功、失败、跳过和冲突清单；无冲突项可自动回写，冲突进入人工确认。
28 wecom_ruleops_v1 AI 草拟企微规则、生成差异报告和 dry-run，人工确认后写入企微。 前述同步/回写链路稳定；企微规则 API 能力和权限已验证。 每次写入保存前后快照、确认人、API errcode、失败原因、回滚建议和审计记录。

4. 每阶段固定门禁

每个正式阶段必须单独建立 Issue CSV，并至少包含：

  • 需求边界：本阶段做什么、不做什么、涉及哪些角色和业务流程。
  • 接口边界：新增或复用的企微 API、OA API、schema、feature flag、配置和权限；企微接口必须引用 企微 API 能力目录 的对应能力行。
  • 数据边界：主事实源、镜像方向、附件归属、脱敏字段和审计责任。
  • 失败处理：缺 Secret、权限、模板、可信 IP、回调、外部配置时必须记录 SKIP/BLOCKED_BY_EXTERNAL_CONFIG，不得伪造成成功。
  • 测试门禁：本地静态检查、focused 单测、必要 Playwright、权限负例、文档审计和公网复检。
  • 部署规则：本地全测通过后才能部署；生产写接口、企微规则写入、应急模式开启或恢复回写必须单独批准。

5. 并行工作规则

  • 可以并行：线上缺陷修复、首周运营保障、真实反馈扫尾、QA-only 脚本维护、文档审计修正。
  • 必须另开合同：OA 主办域的采购、合同、报销、付款、AP、代账、审计和高敏附件功能变更。
  • 不允许混入：在 API 目录和 Secret 矩阵未明确前开发新企微能力；在 WOUA 差异分类和处理决策未收口前推进深度考勤/审批镜像；在 HR 主数据未稳定前开发恢复回写；在应急接管未完成前开发 RuleOps 正式写入。
  • 不允许把企业微信原生审批用于报销、采购、合同、项目、财务付款或高敏附件审批。

6. POC 验收口径

WECOM-CAPABILITY-POC-V1 必须输出能力矩阵：

状态 含义
CAN_REUSE_NOW 当前配置和 API 能力足以进入正式实现设计。
NEEDS_CONFIG 需要企微后台配置、授权、可信 IP、模板、可见范围或 Secret 后再测。
NEEDS_API_POC 文档显示可能支持，但需 QA-only 探测脚本确认。
KEEP_OA_PRIMARY 该能力继续由 OA 主办，企微只做入口、消息或参考。
NOT_SUPPORTED_BY_API 企业微信 API 不支持或风险过高，不进入自动化实现。

POC 默认只读或低风险探测。任何生产写操作、企微规则写入、真实员工批量变更、恢复回写或应急切换都必须另建合同并获得明确批准。

7. WCP1 POC 结果

2026-05-18 已执行 WECOM-CAPABILITY-POC-V1，本轮新增 QA-only runner scripts/qa/check-wecom-capability-poc.mjs。本地不开启 live read 时报告为可解释 PAUSE_FOR_API_POC，本地开启 live read 但无真实企微 env 时报告为可解释 PAUSE_FOR_CONFIG；部署服务器容器内使用现有远端 env 执行 live 只读探测，报告目录为远端 /tmp/wecom-capability-poc-wcp1/summary.json，结论同为 PAUSE_FOR_CONFIG。

当前可复用能力：

  • 工作台应用 access token 可获取，核心 CorpID/Agent/Secret/OAuth 配置存在。
  • HCLT 已作为历史证据纳入：HRWDTEST-20260517214548 已完成企微通讯录 create/update/disable，errcode=0。
  • 通讯录部门读取曾通过工作台应用 token fallback 验证；该历史口径已被 WAPI supersede，后续通讯录读取固定使用 WECOM_CONTACT_SECRET，部门列表和成员详情只作可选富化，user/list_id 缺权限才阻断全量候选读取。
  • 人事助手字段配置读取可用。
  • 审批 access token 可获取，但模板、实例、假期余额和回调配置尚未满足镜像开发准入。

当前阻断：

  • contact.member_read：测试成员详情读取历史返回 wecom_errcode_48009；WAPI 后该接口降级为可选富化，WOUA/WHMS 必需链路改为 user/list_id + 人事助手花名册。
  • hr.staff_read：测试成员花名册读取返回 wecom_errcode_60021，需要把可用于 POC 的测试成员纳入应用/人事助手权限范围，或改用在职测试成员复跑。
  • checkin.records_read / checkin.rules_read：远端 WECOM_CHECKIN_SYNC_ENABLED 未开启，打卡短窗口和规则读取按 NEEDS_CONFIG 记录。
  • approval.template_detail / approval.instance_detail：缺审批模板 ID 和测试审批单号。
  • approval.vacation_quota：假期余额读取返回 wecom_errcode_301062，缺假期权限。
  • callback.config：回调 URL、Token、AESKey 未作为可读配置注入，本轮不能证明回调链路。

上述 WCP1 阻断已由 WCPC 使用既有在职测试号完成复跑收口。WCP1 历史报告仍保留为配置缺口证据，但当前阶段准入以 WCPC 结论为准。

8. WCPC 配置收口状态

2026-05-18 已建立并完成 WCP1-CONFIG-CLOSEOUT-V1 合同。用户要求改用已有账户后，已通过远端只读候选扫描选用 SMOKE002/测试员工 作为既有在职低风险测试号；报告、文档和 Issue 只记录脱敏企业微信 userid 前缀 oa_smoke***。本轮不开发业务功能、不部署、不持久修改服务器 .env，服务器复跑只使用临时环境变量和既有容器配置。

当前已完成：

  • 建立 WCPC Issue CSV。
  • 使用现有远端配置和历史 HRWDTEST-20260517214548 做基线复跑，报告目录为远端 /tmp/wecom-capability-poc-wcpc-baseline。
  • 基线结论仍为 PAUSE_FOR_CONFIG，contact.member_read=wecom_errcode_48009，hr.staff_read=wecom_errcode_60021。
  • 使用 SMOKE002/测试员工 复跑既有测试号只读 POC，报告为远端 /tmp/wecom-capability-poc-wcpc-smoke002/summary.json。
  • 复跑结果：status=PASS，conclusion=GO_TO_HR_MASTER_SYNC，nextStageAllowed=true，blockingCapabilities=[]，状态计数为 CAN_REUSE_NOW=15、NEEDS_CONFIG=3、NEEDS_API_POC=1、KEEP_OA_PRIMARY=1。
  • HR 主数据镜像准入项已通过：contact.member_read=CAN_REUSE_NOW、hr.staff_read=CAN_REUSE_NOW；打卡记录/规则和假期余额只读能力也已返回可复用状态。

剩余非阻断配置项：

  • approval.template_detail=NEEDS_CONFIG：缺少本轮可用审批模板 ID。
  • approval.instance_detail=NEEDS_CONFIG：缺少本轮可用审批单号 sp_no。
  • callback.config=NEEDS_CONFIG：本轮只读报告未证明真实回调配置存在。
  • hr.staff_update_classification=NEEDS_API_POC：人事助手资料更新属于写接口，需单独批准后再做低风险 POC。

WCPC 已允许进入 wecom_hr_master_sync_v1。WHMS 已承接该阶段，完成本地实现、部署和受控公网验证；考勤/审批镜像仍需先完成回调证据、补偿拉取、审批可读性、自建留存模型、最小历史留存和正式只读查询。当前请假/补卡已完成 WACP3/WREAD1/WADM1/WARCH1/WARCH2，但下一步先做 WROAD2+OPS 受控上线和每日巡检；不得把 WCPC、WHMS、WAPC2FLIVE、WCBK1、WREAD1、WARCH1 或 WARCH2 误读为完整考勤/审批镜像已完成。

9. WHMS HR 主数据镜像状态

2026-05-18 已建立 WECOM-HR-MASTER-SYNC-V1 合同，范围限定为企业微信通讯录/人事助手只读主数据同步到 OA。该阶段不做考勤/审批镜像、审批回调、恢复回写、RuleOps、HR 写企微接口、采购/合同/财务迁移。

已实现内容：

  • 新增 feature flag wecom_hr_master_sync_v1，默认 force_off；WAPI 后读取口径修正为通讯录使用 WECOM_CONTACT_SECRET、人事助手/花名册使用 WECOM_AGENT_SECRET，WECOM_HR_ASSISTANT_SECRET 仅保留为历史兼容项且不参与默认读取。
  • 新增管理 API：POST /api/employees/wecom-hr-master-sync/runs、GET /api/employees/wecom-hr-master-sync/runs、GET /api/employees/wecom-hr-master-sync/runs/:id。
  • 新增同步批次和逐员工记录，支持 dry_run 不写主数据、apply 写入 OA 员工、部门映射、默认 employee 角色、企业微信绑定、主管关系和审计。
  • People/人员管理页新增“企微 HR 主数据镜像”管理卡片，管理员可执行预检、确认写入并查看最近同步摘要；普通员工不可见入口。
  • 新增 QA-only runner scripts/qa/check-wecom-hr-master-sync.mjs，默认不做 live 写入；apply 必须显式传入 userids 并设置批准环境变量。

数据策略：

  • 匹配优先级：wecom_identity_bindings.external_user_id -> 企微 userid/工号 -> 手机号 -> 邮箱。
  • 新员工创建要求姓名、手机号、邮箱和部门；缺字段时 SKIP missing_required_field，不生成占位邮箱或占位部门。
  • 企微不在职或禁用状态记录 needs_offboarding_confirmation，不自动禁用 OA 账号；离职仍走 OA checklist。
  • 已有 OA 员工只更新安全主数据字段：姓名、部门、职位、直属主管、手机号、邮箱和企微绑定；不覆盖银行账户、身份证、工资、合同附件或历史审批。

当前状态：

  • 已通过 WHMSLIVE 部署到 https://oa.hyinda.com，远端已应用 migration 20260518184319_wecom_hr_master_sync_v1。
  • 公网验证窗口中临时将 wecom_hr_master_sync_v1 设为 force_on，对既有低风险测试号 SMOKE002/测试员工（脱敏 oa_smoke***）执行 dry-run 和显式 userids apply；企微读取链路通过，因企微侧缺手机号、邮箱和部门，按规则记录 missing_required_field 并跳过，未写入 OA 主数据。
  • 已验证普通员工访问同步 API 返回 403；验证结束后 wecom_hr_master_sync_v1 已恢复为 force_off。
  • 未执行生产真实员工批量 apply；后续若要正式批量同步真实员工，必须另行批准并先处理企微必填字段质量。
  • 当前 WOUA 用户一致性差异已由 WOUA-FIX 收口，WAPC2FLIVE 自动样件、WAPC2 自动复跑、WCBK1 真实回调事件确认、WACP3R 补偿拉取、WREAD1 请假/补卡可读性门禁、WADM1 模型、WARCH1 最小历史留存和 WARCH2 正式只读查询已完成；wecom_attendance_approval_mirror_v1 仍暂缓到 WROAD2+OPS 受控上线、WARCH3 归档稳定化、WCHECK1 打卡摘要留存、外出/加班处理决策和打卡细项明确后再另建合同。

10. WRRA 路线修正与下一阶段

WRRA 将 WAPI/WOUA 后的路线门禁修正为“运行优先 + 差异收口先行”。WOUA-FIX 已按用户确认完成第一轮写入收口：7 个 OA active 缺企微测试账号软归档，复检 oaActiveMissingInWecom=0；5 个企微缺字段先接受不补；HRWDTEST-20260517214548 归档绑定保留为审计项。该结果让运行优先能力可以继续推进，但仍不等于考勤/审批深度镜像准入。

WECOM-RUNTIME-READY-V1 执行口径：

  • 工作台入口、OAuth/免登绑定、脱敏应用消息、OA deeplink、通讯录 userid 清单、人事助手花名册读取和打卡短窗口读取先做运行就绪门禁；本轮不配置审批模板、测试 sp_no 或真实回调。
  • runner 为 server/src/scripts/check-wecom-runtime-ready.js / npm run check:wecom-runtime-ready；默认只构建脱敏消息 payload，真实低风险消息必须同时指定 --send-test-message 和 WECOM_RUNTIME_TEST_SEND=1。
  • WRA1 后，WECOM_CHECKIN_SYNC_ENABLED 只作为正式考勤同步开关；QA-only 打卡短窗口读取可以显式绕过该开关做只读探测，报告记录 readable_sync_disabled，但不得启动正式同步批次。
  • 报告输出到 artifacts/qa-flow/wecom-runtime-ready-<timestamp>/summary.json，结论限定为 PASS_RUNTIME_READY、PASS_WITH_CONFIG_GAPS 或 SKIP/BLOCKED_BY_EXTERNAL_CONFIG。
  • 对剩余企微缺字段保持 accepted finding，不补企微资料；如后续要补字段或 WHMS 真实员工批量 apply，必须另建写入合同。
  • wecom_attendance_approval_mirror_v1 继续暂缓，直到真实回调配置、回调验签/解密/幂等、补偿拉取、镜像数据模型和打卡细项 POC 明确。WAPC2FLIVE 已解决请假/补卡低风险模板 ID 与 sp_no 样例来源，但不替代回调、补偿和模型门禁。

11. WAPC1 审批配置准备清单

WMSG1 已证明企业微信应用消息和 OA Deeplink 能真实到达，但这只清除通知链路证据，不清除审批镜像前置配置。WAPC1 固定下一步只做配置准备，不开发真实回调接收端，不接企微写接口，不进入 wecom_attendance_approval_mirror_v1。

首批模板范围：

  • 请假。
  • 补卡。
  • 外出。
  • 加班。

每个模板进入后续 POC 前必须准备：

  • 企业微信审批模板 ID。
  • 模板适用范围和可见范围。
  • 字段项清单和 OA 需要镜像的字段映射意图。
  • 审批人规则、转审/撤回/退回等模板能力边界。
  • 所属自建应用是否具备 WECOM_AGENT_SECRET 对应读取权限。

后续 POC 准入项：

  • 使用 POST /cgi-bin/oa/gettemplatedetail 读取模板详情。
  • 使用低风险测试 sp_no 调用 POST /cgi-bin/oa/getapprovaldetail 读取审批详情；测试审批单不得包含采购、合同、报销、发票、银行回单、高敏附件或真实敏感业务资料。
  • 真实回调 URL、Token、EncodingAESKey 由运维在部署环境配置；文档和报告只记录配置项名称，不保存密钥值。
  • 回调接入前必须明确验签、解密、幂等键、企业微信重试语义、失败重试和补偿拉取方案。
  • 批量获取审批单号先作为补偿拉取候选，标记 NEEDS_API_POC，不得在镜像合同前假定可用。

12. WAPC2 审批模板与低风险 sp_no 只读 POC

WAPC2 承接 WAPC1 的配置准备清单，但范围先收窄到请假和补卡。该阶段只证明企业微信审批模板详情和审批申请详情可被自建应用只读获取，不开发真实回调、不创建 OA 镜像表、不导入审批历史、不调用企微写接口。

执行口径：

  • runner 为 server/src/scripts/check-wecom-approval-poc.js / npm run check:wecom-approval-poc。
  • 模板详情固定调用 POST /cgi-bin/oa/gettemplatedetail；审批详情固定调用 POST /cgi-bin/oa/getapprovaldetail。
  • Secret 固定为 WECOM_AGENT_SECRET；不得 fallback 到 WECOM_CONTACT_SECRET、WECOM_CHECKIN_SECRET 或 WECOM_HR_ASSISTANT_SECRET。
  • 支持 --template=leave:<id>、--template=missed_punch:<id>、--sp-no=leave:<sp_no>、--sp-no=missed_punch:<sp_no>，也支持同义临时 env。
  • 报告输出到 artifacts/qa-flow/wecom-approval-poc-<timestamp>/summary.json，只记录类型、配置状态、脱敏 ID 前缀、字段类型计数、审批节点计数和错误分类。
  • 若缺模板 ID 或低风险测试 sp_no，结论必须为 PARTIAL_APPROVAL_POC_NEEDS_CONFIG；若权限、可信 IP、可见范围、Secret 或企微 API 错误阻断，结论必须为 SKIP/BLOCKED_BY_EXTERNAL_CONFIG。

WAPC2 通过后，下一步不是直接进入 wecom_attendance_approval_mirror_v1。WPROC1/WAPC2F/WCBK1/WEGOV1 固定后续必须先做：

  1. WAPC2F 自动生成 POC 样件：dry-run 已通过；默认申请人 SMOKE002、审批人 SMOKE101，两者必须 active、已绑定企微、可见、不是同一 OA 员工且不是同一企微 userid；WAPC2FLIVE 已在用户批准后创建 OA-POC 请假/补卡测试模板和低风险测试审批单，记录脱敏报告 /app/artifacts/qa-flow/wecom-approval-fixtures-20260519T053400Z/summary.json。
  2. WAPC2 自动复跑：已由 WAPC2FLIVE 自动传入生成的模板 ID 和 sp_no，只读复跑结论为 PASS_APPROVAL_POC。
  3. WCBK1 回调只读 POC：已证明 URL 验证、验签、解密、幂等摘要和真实审批状态事件脱敏留证，结论 PASS_CALLBACK_EVENT_CONFIRMED。
  4. WEGOV1 企微主办治理与自建留存路线修正：已明确企微主办域、OA 主办域、OA 留存域、OA 应急域和受控测试域。
  5. WACP3 补偿拉取 POC：已证明按时间窗口拿到审批单号并可拉取审批详情。
  6. WREAD1 审批可读性与误审批防护门禁：已完成请假/补卡真机确认。
  7. WADM1 自建留存/镜像数据模型设计：已设计字段、状态机、幂等键、索引和隐私保留边界。
  8. WARCH1 最小自建历史留存实现：已保存请假/补卡企微审批历史、回调事件和补偿拉取记录。
  9. WARCH2 正式只读历史查询：已提供 OA DB 只读 API 和 PC/移动历史页。
  10. WROAD2+OPS 受控上线与每日巡检：先做测试账号 3 天脚本化巡检，沉淀 Day 0/Day 1/Day 2/Day 3 脱敏报告。
  11. WARCH3 / WCHECK1 / WEXT1 / WOPS1：已补归档稳定化自动巡检、打卡摘要留存、外出/加班 dry-run 和告警降噪。
  12. WROAD2-CLOSEOUT / WROAD2-BIZ1 / WAPPR1 / WAUTO1 / WEXT1LD / WEXT1-LIVE / WREAL1：三天验收期间并行完成人工业务冒烟、审批规则规范化和自动证据汇总；先完成外出/加班 live 前 dry-run，再问答进入外出/加班测试号 live POC；请假、补卡、外出、加班四类测试号证据和审批规则门禁通过后，再问真实小范围试用。

WROAD2-CLOSEOUT、WROAD2-BIZ1、WAPPR1、WAUTO1/WEXT1LD、WEXT1-LIVE、四类测试号证据和 WREAL1 通过或明确批准前，不拆 wecom_attendance_approval_mirror_v1。

13. WADM1 自建留存/镜像数据模型设计

WADM1 是 WARCH1 前的设计门禁，只定义数据模型、状态机、幂等键、隐私和迁移回滚策略，不创建 Prisma migration、不改业务代码、不部署。

模型按四域边界拆分：

模型域 设计对象 WARCH1 V1 取舍
企微审批留存 WecomApprovalArchive 主表、WecomApprovalParticipant 参与人/节点快照、WecomApprovalAction 审批动作、WecomApprovalFieldSummary 字段摘要、WecomApprovalAttachmentSummary 附件摘要 先覆盖请假和补卡；保存完整 sp_no、template_id、申请/审批人外部键到受权限保护的 OA DB；报告和日志只输出脱敏前缀。
回调与补偿证据 WecomApprovalCallbackEvent、WecomApprovalCompensationRun、WecomApprovalCompensationItem、WecomApprovalReconcileFinding 解决 WACP3R finding：回调证据不能再只落到易丢失文件；DB 内保存完整 sp_no/template_id/approval_archive_id 用于稳定关联，日志和报告只输出脱敏前缀；未来回调和补偿拉取均入库后再比对漏回调、重复回调和状态不一致。
打卡与人事快照 复用 WecomCheckinSyncRun、WecomCheckinRecord、WecomHrMasterSyncRun、WecomHrMasterSyncItem、WecomIdentityBinding，后续按缺口补规则快照、假期余额摘要或花名册快照 WARCH1 不重造企微打卡风控；先保存已可读摘要和必要快照，排班、日报、月报、假期余额细项按后续 POC 再扩展。
OA 应急衔接 应急单据与企微镜像单据通过外部键、状态和恢复队列关联 WADM1 只预留字段和状态，不开启 oa_hr_emergency_mode_v1，不做恢复回写。

审批留存主表建议字段：

  • 业务键：sp_no 唯一、template_id、template_type（leave、missed_punch、后续 outing、overtime）、corp_id_hash 或租户标识、企微状态码和 OA 规范化状态。
  • 人员键：申请人 OA employee_id、申请人企微 userid、审批人/抄送人企微 userid、通过 WecomIdentityBinding 映射到 OA 员工；映射失败时保留外部键并标记 unmatched_user。
  • 时间键：申请时间、提交时间、最后状态时间、完成时间、最近回调时间、最近补偿拉取时间。
  • 来源键：last_source 为 callback、compensation_pull、manual_import 或 synthetic_fixture；source_priority 规则为回调和补偿互补，不以文件报告替代数据库事实。
  • 风险键：readability_status、single_tap_approve_risk、template_adjustment_required、external_config_status。

审批状态机建议规范化为：pending、approved、rejected、revoked、terminated、changed、unknown、sync_failed。企微原始状态码只作为枚举/字符串字段保存，不保存原始 payload；状态推进采用“同一 sp_no 幂等 upsert + 最新状态时间优先 + 保留全部动作历史”的规则。回调和补偿状态冲突时不覆盖为成功，而是生成 WecomApprovalReconcileFinding，等待后续 runner 或人工解释。

回调和补偿合并语义：

  • getapprovaldetail 详情快照作为业务状态最终校准来源；回调作为低延迟事件来源。两者都必须持久化，不能以 runner 文件报告替代数据库事实。
  • 主表保存 status_observed_at、last_source 和 last_detail_digest；只有更晚的事件时间或变化的详情 digest 才能推进主状态。
  • 较旧的 pending、unknown 或失败事件不得覆盖较新的终态；不同终态冲突写入 WecomApprovalReconcileFinding(status_mismatch)，不静默改成成功。
  • 回调重试以事件幂等键 upsert 并累加重试计数；补偿拉取以 run_id + sp_no 唯一，详情 digest 未变化时不重复写动作。
  • DB 业务表保存完整外部键，默认 UI、导出、日志、报告、文档和 Issue 只显示脱敏前缀。

幂等键建议：

  • 审批主表：sp_no 唯一。
  • 回调事件：sha256(corp + event_type + sp_no + template_id + normalized_status + node_user + event_time + normalized_digest)；保存 digest，不保存原始 XML、密文或原始 payload。
  • 补偿拉取 run：source + start_time + end_time + template_filter + cursor。
  • 补偿 item：run_id + sp_no 唯一，并记录详情拉取状态和错误分类。
  • 审批动作：sp_no + action_type + operator_userid + action_time + node_index。

隐私和保留策略：

  • OA DB 可保存完整外部关联键和业务必要字段，用于补偿、历史查看、恢复和审计；日志、报告、Issue CSV 和文档只保存脱敏前缀。
  • 表单字段默认只保存规范化业务字段和摘要。请假/补卡至少保存申请类型、时间范围、时长或补卡时间、原因摘要、审批状态和审批历史；不保存无治理的整包 payload。
  • 附件 V1 只保存数量、类型和外部引用摘要；不下载采购、合同、报销、发票、银行回单或高敏附件。
  • 原始 XML、密文、Token、EncodingAESKey、access token、Secret 和完整回调密文永不入库。若后续确需原始 payload，必须另开加密存储、字段级访问审计和保留期限合同。
  • 普通员工只能查看本人历史；审批人查看自己处理链路；HR/管理员按部门或系统权限查看；导出默认脱敏。

WARCH1 最小实现切片：

  1. 新增只写不读的审批留存、回调事件、补偿拉取和对账 finding 表，migration 可回滚。
  2. 修改 WCBK1 回调路径和 WACP3 补偿 runner，把请假/补卡的规范化详情幂等写入 OA DB。
  3. 增加 QA-only backfill/verify runner：断开企微 API 时仍能从 OA DB 读取已保存的请假/补卡历史摘要。
  4. 再做只读查询 API 或管理页入口；不在 WARCH1 内开启完整镜像增强、外出/加班正式样例、应急接管、恢复回写或 RuleOps。该正式查询切片已由 WARCH2 承接。

WARCH1 已按独立 Issue CSV 进入最小实现。当前实现边界：

  • Prisma 新增 WecomApprovalArchive、WecomApprovalParticipant、WecomApprovalAction、WecomApprovalFieldSummary、WecomApprovalAttachmentSummary、WecomApprovalCallbackEvent、WecomApprovalCompensationRun、WecomApprovalCompensationItem 和 WecomApprovalReconcileFinding，migration 只新增表、索引和外键。
  • GET /POST /api/wecom/approval/callback 继续只读接收企微回调；POST 验签、解密、规范化后默认写入 OA DB，DB 写入失败返回非 200，让企业微信按官方机制重试；配置文件证据仅作为无 Prisma 时的 fallback。
  • npm run check:wecom-approval-compensation-poc 默认仍只读不写库；只有同时传 --persist-to-db 且进程环境 WECOM_ARCHIVE_WRITE=1 时，才把现有请假/补卡补偿详情写入 OA 自建留存表。该路径不写企微、不创建模板、不提交审批。
  • npm run check:wecom-approval-archive -- --offline --format=json 是 QA-only 离线证明：不调用企微 API，只从 OA DB 读取已保存历史摘要，并只输出脱敏 sp_no、template、userid 前缀、计数、字段类型和 finding 类型。
  • 公网验证已执行 SYNC_ENV=0 部署并应用 migration；补偿持久化报告 /app/artifacts/qa-flow/wecom-approval-compensation-poc-20260519T160306Z/summary.json 为 PASS_WITH_FINDINGS，archivePersistence.status=OK、storedCount=2；离线读取报告 /app/artifacts/qa-flow/wecom-approval-archive-20260519T160330Z/summary.json 为 PASS_WITH_FINDINGS，可读 2 条已通过历史。finding 是 WARCH1 前旧回调未持久化到 DB 的历史 gap，已记录为 callback_missing_for_pulled_detail，不是当前写入链路阻断。
  • WARCH1 仍不新增正式管理页，不开发外出/加班，不开启 wecom_attendance_approval_mirror_v1、oa_hr_emergency_mode_v1、wecom_recovery_writeback_v1 或 wecom_ruleops_v1。WARCH2 已在此基础上实现并部署正式只读查询 API 和 PC/移动历史页。

6.2 WARCH2 正式只读查询边界

WARCH2 把 WARCH1 的离线 runner 证明升级为 OA 内可查历史，但仍是只读留存查询，不是审批镜像或应急办理：

  • API：GET /api/wecom/approval-archive 和 GET /api/wecom/approval-archive/:id 只读 OA DB；不调用企微 API、不获取 access token、不读取 WECOM_AGENT_SECRET、WECOM_CALLBACK_TOKEN 或 WECOM_CALLBACK_ENCODING_AES_KEY。
  • 权限：普通员工只看本人作为申请人、参与人或动作处理人的已归档历史；主管可看直属下属申请和本人相关记录；HR/admin/* 可看全量。leave.view_all / attendance.view_all 只满足入口权限，不单独代表全量企微归档权限。
  • 未映射边界：callback-only、申请人未映射、参与人未映射或仅外部 userid 的记录默认只允许 HR/admin/* 查看；普通员工和主管不得靠参与人/动作关系看到申请人未映射记录。
  • 脱敏：API 和页面只返回脱敏 sp_no / template 前缀、字段名/字段类型/敏感级别、动作类型/时间/来源和 finding 摘要；不返回完整外部键、手机号、邮箱、原因全文、附件、评论、原始 XML、密文、token 或 Secret。
  • 页面：PC /wecom-approval-archive 与移动 /mobile/wecom-approval-archive 固定文案“企业微信主办，OA 自建留存”“仅已归档记录”，入口在备用模块或考勤历史语境，不进入 /workflow/tasks 待办语境，不展示审批按钮或 pending 待办暗示。

6.3 WROAD2+OPS 受控上线边界

WROAD2+OPS 把 WARCH2 后的可用能力先进入测试账号受控使用，不等同于完整镜像增强：

  • 范围：测试账号 SMOKE002 -> SMOKE101，管理员观察和告警员工号 HYD000006（wangshunli 的员工号），3 天试用，每日一次触发 scripts/qa/run-wroad2-ops-daily.sh 或 WARCH3 systemd timer。
  • 巡检：复用公网 /ready、live smoke、feature flag、企微 runtime、审批补偿拉取和 OA 归档离线读取 runner，输出 artifacts/qa-flow/wroad2-ops-<timestamp>/summary.json。
  • 写入边界：巡检默认只读；仅审批补偿归档步骤可用进程级 WECOM_ARCHIVE_WRITE=1 与 --persist-to-db 写 OA 自建留存库。不写企业微信、不创建模板、不提交审批单。
  • 结果边界：结论只允许 PASS_CONTROLLED_OPS_READY、PASS_WITH_FINDINGS、PAUSED_MANUAL_CONFIRMATION 或真实 SKIP/BLOCKED_BY_EXTERNAL_CONFIG。
  • 后续顺序：WROAD2+OPS 后优先 WARCH3 归档稳定化，再做 WCHECK1 打卡摘要留存；外出/加班进入 WEXT1 dry-run。上述阶段完成前，不启动完整深度镜像、应急接管、恢复回写或 RuleOps。
  • 业务冒烟：WROAD2-BIZ1 在三天内补充人工业务动作，不替代自动巡检。SMOKE002 每天按企微规则尝试上/下班打卡，提交低风险请假和补卡；SMOKE101 必须先打开详情再审批；HYD000006 每天查看 OA 企微审批归档和打卡摘要。无法打卡、无法审批或仍需手选审批人时按 finding 记录，不伪造成通过。
  • 审批规则：WAPPR1 把“申请人不得任意选择审批人”列为真实试用前门禁。测试模板固定 SMOKE002 -> SMOKE101；正式模板必须按直属主管、部门负责人或指定审批角色自动带出审批人；审批人缺失、停用、未绑定、不可见或等于申请人本人时阻断。
  • 自动证据：WAUTO1 使用 scripts/qa/collect-wecom-controlled-trial-evidence.sh 只读汇总三天证据，读取既有 WROAD2/WARCH3/WCHECK1/WEXT1 报告并复跑只读/离线 runner；该脚本不设置 WECOM_ARCHIVE_WRITE=1、WECOM_CHECKIN_ARCHIVE_WRITE=1 或 WECOM_APPROVAL_FIXTURE_WRITE=1，不替代 WARCH3 定时巡检和人工业务冒烟。

6.4 WARCH3 / WCHECK1 / WEXT1 当前边界

  • WARCH3：scripts/qa/run-warch3-ops-daily.sh 聚合 WROAD2 子报告并输出 artifacts/qa-flow/warch3-ops-<timestamp>/summary.json；deploy/trialrun/install-warch3-ops-timer.sh 安装 hyb-oa-warch3-ops.service/timer，每日 07:30 触发。巡检失败或 finding 可用 npm run send:wecom-ops-alert 发脱敏企微应用消息，双开关为 --send + WARCH3_OPS_ALERT_SEND=1。
  • WCHECK1：WecomCheckinRecord 继续作为规范化明细；新增日摘要、月摘要和规则快照。npm run check:wecom-checkin-summary-archive 默认离线只读；写 OA 留存必须同时具备 --persist-to-db + WECOM_CHECKIN_ARCHIVE_WRITE=1。报告不输出完整 userid、位置、人脸、设备明文或原始 payload。
  • WEXT1：npm run check:wecom-approval-fixtures -- --target=outing --target=overtime 只做 dry-run。外出/加班 live 创建仍需新 Issue CSV 和人工批准，不因请假/补卡已验证而自动放行。
  • WEXT1LD：live 前 dry-run gate 只执行 npm run check:wecom-approval-fixtures -- --format=json --target=outing --target=overtime，不带 live 写入参数；通过后问答选项为批准一次 live 创建外出+加班 OA-POC 样件、只保留 dry-run、或将外出/加班移出 V1。
在新工单中引用 查看 Git Blame 复制永久链接