hyb-oa/docs/企微优先开发路线图.md

# 企微优先开发路线图

**文档状态**：当前开发路线图事实源。  
**分类**：开发治理 / 路线图。  
**适用时间**：WDRG / WCP1 / WHMSLIVE / WOUA / WAPI 之后。
**关联 Issue**：`WDRG,WCP1,WHMS,WHMSLIVE,WOUA,WAPI`。
**最近审计**：2026-05-18。  
**不得误读**：本文只控制后续开发节奏、阶段顺序和门禁。WHMSLIVE 后只代表企微 HR 主数据镜像已部署并受控验证；WAPI 后进一步固定企微 API/Secret 口径并转为运行优先，不代表企微考勤/审批镜像、OA 应急接管、恢复回写或 RuleOps 已完成运行时实现。

## 1. 路线图原则

- 采用“路线图门禁 + 单功能 Issue CSV”的工程流程；路线图管顺序和边界，具体实现仍以每个功能的 Issue CSV 为准。
- 当前路线只覆盖企微优先 HR/考勤域改造：人事助手、通讯录、打卡、HR/考勤审批、OA 镜像、OA 应急接管、恢复回写和 RuleOps。
- 采购、费用、合同、项目、报销、付款批次、AP、代账交接、审计和高敏附件继续 OA 主办；企业微信只做脱敏消息、deeplink、入口和成熟能力参考。
- 阶段未满足退出条件前不得跳阶段。线上缺陷、安全风险、正式使用阻断或真实反馈可以另开独立 Issue CSV，但不得混入企微 HR/考勤主路线。
- ERP 未来不接入 OA；真实支付、图片 OCR、银行流水导入、复杂 BPM、审批设计器和重预算继续不进入当前路线。
- WAPI 后所有企微开发必须先读 [企微 API 能力目录](./企微API能力目录.md)，先确认官方 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、人事助手读取和打卡读取。 |

## 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 结论为 `PASS_NO_DRIFT`、`PASS_WITH_FINDINGS` 或可解释阻断；后续按差异决定 WOUA-FIX、WHMS 批量同步窗口或进入考勤/审批镜像准备。 |
| 4 | `wecom_attendance_approval_mirror_v1` | 企微打卡、请假、补卡、外出、加班、假期余额和审批历史镜像到 OA。 | 运行优先门禁完成；审批模板、测试审批单号 `sp_no`、真实回调配置、打卡规则和只读 POC 均明确。 | OA 可查询企微 HR/考勤镜像、附件摘要、审批历史、考勤解释和审计；不把 OA 主办高敏审批迁到企微。 |
| 5 | `oa_hr_emergency_mode_v1` | 企业微信不可用时，由管理员人工开启 OA HR/考勤应急接管。 | 企微镜像数据可支撑对账；OA 应急入口、权限和审计方案明确。 | 管理员可填写原因、范围、预计结束时间和责任人后开启/关闭；应急单据带 `EMERGENCY` 标记。 |
| 6 | `wecom_recovery_writeback_v1` | 企微恢复后，OA 应急数据先 dry-run，再回写企微。 | 应急接管模式完成；企微写回接口、冲突规则和回滚策略已单独批准。 | 系统生成成功、失败、跳过和冲突清单；无冲突项可自动回写，冲突进入人工确认。 |
| 7 | `wecom_ruleops_v1` | AI 草拟企微规则、生成差异报告和 dry-run，人工确认后写入企微。 | 前述同步/回写链路稳定；企微规则 API 能力和权限已验证。 | 每次写入保存前后快照、确认人、API `errcode`、失败原因、回滚建议和审计记录。 |

## 4. 每阶段固定门禁

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

- 需求边界：本阶段做什么、不做什么、涉及哪些角色和业务流程。
- 接口边界：新增或复用的企微 API、OA API、schema、feature flag、配置和权限；企微接口必须引用 [企微 API 能力目录](./企微API能力目录.md) 的对应能力行。
- 数据边界：主事实源、镜像方向、附件归属、脱敏字段和审计责任。
- 失败处理：缺 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 已承接该阶段，完成本地实现、部署和受控公网验证；考勤/审批镜像仍需先补审批模板、审批单、回调配置并另建 `wecom_attendance_approval_mirror_v1` 合同，不得把 WCPC 或 WHMS 误读为考勤/审批运行时迁移已完成。

## 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 用户一致性差异或明确 WHMS 批量同步窗口；`wecom_attendance_approval_mirror_v1` 暂缓到审批模板、测试审批单号、真实回调配置和打卡细项 POC 明确后再另建合同。