WHMS 实现企微HR主数据镜像同步

docs/管理员手册.md

@@ -1,6 +1,6 @@
 # hyb-oa 管理员手册（10 人以下团队版）
 
-**当前状态（2026-05-18 / WCPC）**：R7E、PRELAUNCH、CASHIER-VOUCHER-V1、LAUNCH-DEPLOY-FINANCE、FIN-PROD-ENABLE、ACCOUNTING-HANDOFF-V1、ATTV1、HR-WECOM-DIRECTORY-V1、HRWD-CONTACT-LIVE-TEST、DBWFOC、WFDG、WDRG 和 WCPC 均已收口；SYSTEM-COMPLETE-GATE 结论为 `GO_TO_USE`。WCP1 历史结论为 `PAUSE_FOR_CONFIG`，WCPC 已使用既有在职测试号 `SMOKE002/测试员工`（报告只记录 `oa_smoke***`）复跑通过，结论为 `GO_TO_HR_MASTER_SYNC`。后续“路线图门禁 + 单功能 Issue CSV”的开发节奏保持不变：下一步只允许规划 `wecom_hr_master_sync_v1`；HR/考勤员工日常审批优先复用企业微信，OA 做按域镜像、人工接管、恢复回写、财务闭环和审计中台；采购、费用、合同、项目、报销、付款、AP、代账交接和高敏附件继续 OA 主办，企业微信只做脱敏提醒和 OA deeplink。本轮不代表运行时代码已完成迁移。公网 `payment_batch_v1=force_on`，`erp_sync=force_off`。公司当前无 ERP/独立财务系统，且 ERP 未来不接入 OA；财务闭环以 OA 内审批、台账、付款批次、银行对公付款回单和月度代账交接为准。
+**当前状态（2026-05-18 / WHMS）**：R7E、PRELAUNCH、CASHIER-VOUCHER-V1、LAUNCH-DEPLOY-FINANCE、FIN-PROD-ENABLE、ACCOUNTING-HANDOFF-V1、ATTV1、HR-WECOM-DIRECTORY-V1、HRWD-CONTACT-LIVE-TEST、DBWFOC、WFDG、WDRG、WCPC 均已收口；SYSTEM-COMPLETE-GATE 结论为 `GO_TO_USE`。WCP1 历史结论为 `PAUSE_FOR_CONFIG`，WCPC 已使用既有在职测试号 `SMOKE002/测试员工`（报告只记录 `oa_smoke***`）复跑通过，结论为 `GO_TO_HR_MASTER_SYNC`。WHMS 已本地实现 `wecom_hr_master_sync_v1`：企微/人事助手 HR 主数据可 dry-run/apply 到 OA 员工镜像、账号、角色、绑定和审计；默认 `force_off`，尚未部署公网，未对真实员工执行生产批量 apply。后续“路线图门禁 + 单功能 Issue CSV”的开发节奏保持不变：下一阶段为 `wecom_attendance_approval_mirror_v1`，但必须在 WHMS 部署和受控验证后另建合同；HR/考勤员工日常审批优先复用企业微信，OA 做按域镜像、人工接管、恢复回写、财务闭环和审计中台；采购、费用、合同、项目、报销、付款、AP、代账交接和高敏附件继续 OA 主办，企业微信只做脱敏提醒和 OA deeplink。公网 `payment_batch_v1=force_on`，`erp_sync=force_off`。公司当前无 ERP/独立财务系统，且 ERP 未来不接入 OA；财务闭环以 OA 内审批、台账、付款批次、银行对公付款回单和月度代账交接为准。
 
 ## 1. 适用范围
 - 适用于 `small_team_internal` 工作区模式。
@@ -24,7 +24,8 @@
 5. 检查功能开关：
    - 建议开启：`portal_home_v1`、企业微信入口相关开关、报销/OCR、审批待办、请假、项目基础能力和 `payment_batch_v1`。
    - 按需开启：`announcements_v1`、`presence_board_v1`、`weekly_report_v1`、`employee_lifecycle_v1`、`hr_wecom_directory_sync_v1`、`todo_board_v1`、`global_search_v1`。
-   - 后续按独立合同评估：`wecom_hr_master_sync_v1`、`wecom_attendance_approval_mirror_v1`（承接旧口径 `wecom_native_approval_mirror_v1`）、`oa_hr_emergency_mode_v1`、`wecom_recovery_writeback_v1`、`wecom_ruleops_v1`。
+   - 本地已实现待部署：`wecom_hr_master_sync_v1`，默认 `force_off`；启用和生产 apply 需单独确认。
+   - 后续按独立合同评估：`wecom_attendance_approval_mirror_v1`（承接旧口径 `wecom_native_approval_mirror_v1`）、`oa_hr_emergency_mode_v1`、`wecom_recovery_writeback_v1`、`wecom_ruleops_v1`。
    - 建议保留备用：`cutover_console_v1`、预算、AI 和完整差旅相关开关；`erp_sync` 保持关闭且不再作为后续接入目标。
 
 ### 3.1 ORG8 组织账号与角色边界
@@ -190,12 +191,12 @@ RuleOps：
 - 正式写入前必须人工确认；每次写入保存前后快照、确认人、API `errcode`、失败原因、回滚建议和审计记录。
 - 不得在报告、日志或截图中暴露 Secret、access token、完整位置、人脸数据、身份证号、完整手机号或原始密钥材料。
 
-WCP1/WCPC 后续推进：
+WCP1/WCPC/WHMS 后续推进：
 
 1. 继续先读取 [企微优先开发路线图](./企微优先开发路线图.md) 和 WCP1 报告，再判断能否进入下一阶段。
 2. WCP1 历史结论为 `PAUSE_FOR_CONFIG`；WCPC 已用既有在职测试号完成远端只读复跑，报告 `/tmp/wecom-capability-poc-wcpc-smoke002/summary.json`，结论 `GO_TO_HR_MASTER_SYNC`。
 3. WCPC 已证明 HR 主数据镜像准入项可用：通讯录成员读取、人事助手花名册读取、打卡短窗口记录/规则读取和假期余额读取均达到可复用状态；审批模板、审批实例和回调配置仍是后续考勤/审批镜像前置项。
-4. 允许下一步另建 `wecom_hr_master_sync_v1` 方案和 Issue CSV；不得直接开发考勤/审批镜像、OA 应急接管、恢复回写或 RuleOps。
+4. WHMS 已本地实现 `wecom_hr_master_sync_v1`，包括同步批次、逐员工结果、dry-run/apply、People 管理入口和 QA-only runner；当前尚未部署公网。
 5. 正式开发仍按 `wecom_hr_master_sync_v1` -> `wecom_attendance_approval_mirror_v1` -> `oa_hr_emergency_mode_v1` -> `wecom_recovery_writeback_v1` -> `wecom_ruleops_v1` 分合同实施；阶段未退出前禁止跳阶段。
 6. 任何生产写接口、企微规则写入、应急模式开启或恢复回写都必须有单独批准、dry-run 或可审计记录。
 
@@ -203,10 +204,19 @@ WCPC 配置复跑清单：
 
 1. 已完成：自动查找并指定已有在职测试号 `SMOKE002/测试员工`；未使用已离职/禁用的 `HRWDTEST-20260517214548` 作为主测试成员。
 2. 已完成：服务器复跑采用临时环境变量和既有容器配置，不持久写入 `.env`，不重启服务；报告落到远端 `/tmp/wecom-capability-poc-wcpc-smoke002/summary.json`。
-3. 已完成：复跑结论 `GO_TO_HR_MASTER_SYNC`，允许进入 `wecom_hr_master_sync_v1` 规划。
+3. 已完成：复跑结论 `GO_TO_HR_MASTER_SYNC`，该准入已由 WHMS 承接并完成本地实现。
 4. 后续考勤/审批镜像前仍需补齐：审批模板 ID、审批单号 `sp_no`、真实回调 URL/Token/EncodingAESKey 配置和 HR 写接口单独 POC。
 5. 测试审批单不得上传采购、合同、报销、发票、银行回单或其他敏感附件；Secret、Token、EncodingAESKey 不在聊天中明文发送。
 
+WHMS 管理操作口径：
+
+1. 部署并开启 `wecom_hr_master_sync_v1` 前，先确认 `WECOM_HR_MASTER_SYNC_ENABLED`、`WECOM_HR_ASSISTANT_SECRET` 或已验证 fallback Secret 可用。
+2. 在 `人员管理` 的“企微 HR 主数据镜像”卡片先执行 `同步预检`；预检只生成差异和同步记录，不写员工主数据。
+3. 确认差异后再执行 `确认写入`；生产真实员工批量 apply 必须另有批准，不在日常巡检中自动触发。
+4. 缺姓名、手机号、邮箱或部门时系统跳过并记录 `missing_required_field`，管理员应先回企微/人事助手补齐，不在 OA 造占位数据。
+5. 企微不在职或禁用状态只记录 `needs_offboarding_confirmation`，管理员按 OA 离职 checklist 处理，不由同步任务静默禁用账号。
+6. 同步报告、日志和审计只看脱敏摘要；不得导出完整手机号、邮箱、userid、Secret、access token 或企微原始 payload。
+
 ### 3.3 正式财务闭环与代账交接
 
 公司当前没有 ERP 或独立财务系统，OA 不生成 ERP 实时凭证，也不接真实支付接口。正式财务闭环如下：