hyb-oa/docs/需求-企业微信基础设施规约.md

需求 - 企业微信基础设施规约

版本：1.0 日期：2026-05-09 状态：模块级开发规约 上级事实源：海音达OA-MVP需求规格说明书 相关事实源：需求 - 统一审批中心规约

本规约细化企业微信在 hyb-oa 中的基础设施边界、入口、免登/绑定、通讯录身份、消息通知、deeplink、打卡、人事助手、原生审批、OA 镜像、人工接管和恢复回写要求。WFOC 起产品方向调整为“企微优先 + OA 无痛接管”；DBWFOC 后进一步固定为：HR/考勤员工日常审批优先使用企业微信，OA 做按域镜像、备份接管、财务闭环和审计中台；采购、合同、项目、财务和高敏附件继续由 OA 主办。后续企业微信相关开发必须先从本规约拆分 Issue CSV，再进入技术方案和代码实现。

---

1. 模块目标与边界

1.1 目标

• 企业微信作为 hyb-oa 的手机工作台入口、通讯录账号、身份辅助、消息通知、打卡、人事助手和 HR/考勤员工日常审批主操作端。
• 员工在手机企业微信中进入唯一自建应用 海音达工作台，默认落到 OA 移动端。
• OA 主办的报销、财务、采购、合同和项目类审批仍由企业微信消息提醒并 deeplink 回 OA 处理。
• HR/考勤员工日常审批优先复用企业微信原生审批和打卡能力，OA 同步按域镜像、附件、审批历史、规则快照和审计记录。
• 企业微信不可用时，由管理员人工开启 OA HR/考勤应急模式；企微恢复后，OA 对应急数据执行 dry-run、自动回写、失败重试和冲突清单。

1.2 不做范围

• 不把企业微信聊天、文件或审批记录作为财务附件主库、报销 OCR 主库、付款批次主库或代账交接主库。
• 不把采购单、合同正文、供应商报价、项目敏感资料、发票原件、银行回单或代账资料上传到企业微信原生审批或企业微信附件。
• OA 不重造企业微信打卡采集和风控；ATTV1 起只同步企微打卡摘要并做 OA 考勤解释。
• 首批不在 OA 内重造企业微信打卡的定位、人脸识别、Wi-Fi、排班、设备和防作弊规则；长期无痛接管目标也不要求复刻所有企微风控细节。
• 不接入飞书、钉钉或其他办公平台作为首批入口。

1.3 WFOC 能力分层

能力	企微能力	OA 使用程度	当前状态
通讯录	成员创建、读取、更新、禁用或删除	近期已验证 OA 写企微；后续改为企微主源同步 OA，OA 保留修复和审计	CAN_REUSE_NOW：HCLT create/update/disable、部门读取和 WCPC 既有在职测试号 contact.member_read 均已通过
人事助手	员工字段配置、花名册读取、花名册更新	作为员工主数据源，驱动 OA 员工、账号、角色、绑定和状态镜像	LOCAL_IMPLEMENTED_FOR_READ_SYNC：字段配置和既有在职测试号花名册读取已通过；WHMS 已本地实现只读同步到 OA；资料更新写接口仍需单独 POC
打卡	打卡记录、员工规则、日报、月报、排班、补卡、规则管理	企微主办规则和采集，OA 同步按域镜像和应急对账	CAN_REUSE_NOW_FOR_READ：WCPC 短窗口打卡记录和规则读取通过；日报/月报/排班等细项留到考勤镜像合同继续验证
审批	模板详情、提交审批、审批状态回调、审批详情、模板创建/更新、假期余额	HR/考勤员工日常审批企微主办，OA 同步镜像；OA 主办财务、采购、合同、项目和报销审批不迁移	PARTIAL_NEEDS_CONFIG：假期余额读取通过；审批模板 ID、测试审批单号和回调配置仍需在考勤/审批镜像前补齐
工作台和消息	自建应用入口、应用消息、deeplink	继续作为 OA 移动入口和通知渠道	CAN_REUSE_NOW
财务/报销	企微不提供本项目需要的 PDF OCR、付款批次、银行回单和代账闭环	OA 主办	KEEP_OA_PRIMARY
真实支付、ERP、图片 OCR、银行流水导入	非本路线目标	不进入当前路线	NOT_IN_SCOPE

官方能力依据包括企业微信开发者中心及文档路径：通讯录创建成员 90195，打卡概述 90261，获取打卡记录 90262，获取员工打卡规则 90263，审批概述 91854，提交审批申请 91853，获取审批详情 91983，人事助手概述 99130，员工字段配置 99131，花名册读取 99132，花名册更新 99133。真实接口权限、回调配置和可调用应用范围必须在后续 POC 合同中以 NEEDS_CONFIG 或 SKIP/BLOCKED_BY_EXTERNAL_CONFIG 记录。

---

2. 角色与权限

角色	使用目标	可做动作	权限边界
员工	从手机进入 OA、接收提醒、完成绑定	进入移动工作台、绑定企业微信身份、点击消息 deeplink、查看本人相关业务	不能通过企业微信绕过 OA 权限
审批人	在手机端处理企微主办审批或从消息回 OA 处理 OA 主办审批	请假、补卡、外出、加班等 HR/考勤员工日常审批在企微处理；财务、报销、采购、合同、项目等 OA 主办审批回 OA 处理	不得把企微 HR 审批结果当作财务付款或报销依据，必须等 OA 镜像和财务规则确认
管理员/HR	管理入口、人员、通讯录同步、绑定异常、离职停用和应急接管	配置可见范围、协助绑定、同步企微主数据、查看镜像状态、人工开启/关闭 OA 应急模式	不得手工把一个企业微信身份绑定到多个员工；不得无审计开启应急入口或静默覆盖企微数据
系统管理员	维护企业微信应用配置、消息通道、回调和 RuleOps	配置 CorpID、AgentID、Secret、回调、可信域名、消息开关、重试策略和规则写入权限	不处理业务审批，不暴露 secret；AI 规则建议必须人工确认后才能写入企微
财务/老板	接收关键待办或状态提醒	点击 deeplink 回 OA 查看或处理	消息中不得出现完整发票、合同正文、敏感报价、银行卡、身份证

WFOC 后，企微/人事助手是 HR 员工主数据源；OA 是员工镜像、账号权限、OA 主办业务、接管状态、审计和导出事实源。企业微信身份和通讯录账号服务于入口、通知、打卡采集、HR/考勤审批和移动工作台，但 OA 仍负责自己的权限判断、采购/合同/项目/财务动作和审计边界。

---

3. 自建应用与入口

场景	入口	默认落点	要求
手机企业微信工作台	海音达工作台 自建应用	/mobile	已绑定用户直达移动工作台；未绑定用户进入绑定或账号密码回退路径
企业微信消息 deeplink	消息卡片或文本链接	业务详情或审批页	保留目标页面，不只跳首页
手机普通浏览器	OA 移动端 URL	/mobile 或登录后移动页	不依赖企业微信身份，仍可账号密码登录
PC 浏览器	OA Web URL	/portal	PC 用户直接访问 OA，不强制从企业微信进入
入口失败	登录页或错误页	账号密码回退	提示清晰，不让员工反复重试

入口识别应区分企业微信 WebView、普通移动浏览器和 PC 浏览器。企业微信入口只改变登录和跳转体验，不改变业务权限。

---

4. 免登与绑定

4.1 身份字段

字段	用途	要求
企业微信 userId	企业微信成员身份主键	与员工绑定时必须唯一
企业微信手机号	辅助匹配员工	只能作为候选，不可单独作为登录授权
企业微信邮箱	辅助匹配员工	只能作为候选，不可单独作为登录授权
OA employee_id	OA 员工主键	权限和业务数据以此为准
绑定时间	审计	必须记录
绑定人/解绑人	审计	自助绑定和管理员处理都必须记录

4.2 绑定规则

• 已绑定且 OA 员工账号正常：从企业微信进入后直达 /mobile 或 deeplink 目标页。
• 未绑定：提示“当前企业微信账号尚未绑定”，允许账号密码登录后在个人设置完成绑定。
• 一个企业微信身份只能绑定一个员工。
• 一个员工原则上只绑定一个当前有效企业微信身份；更换账号必须先解绑并留痕。
• 员工离职、账号停用或组织权限移除后，企业微信入口不得继续进入 OA 业务页面。
• 绑定、解绑、绑定失败、停用拦截都必须写入审计日志。

4.3 状态与记录

对象	状态	含义	记录要求
入口配置	未启用	企业微信入口不展示或提示不可用	记录配置状态，不影响账号密码登录
入口配置	已启用	企业微信工作台可进入 OA	记录启用人、启用时间和可见范围
绑定关系	未绑定	企业微信身份尚未关联 OA 员工	可回退账号密码登录
绑定关系	已绑定	企业微信身份已关联有效 OA 员工	记录绑定时间、绑定方式和员工 ID
绑定关系	已解绑	绑定关系被员工或管理员解除	记录解绑人、解绑时间和原因
绑定关系	已停用	员工离职、停用或组织权限移除	阻断企业微信入口进入业务页面
通知记录	待发送	主业务已产生通知任务	不阻断主业务
通知记录	已发送	企业微信消息发送成功	记录接收人和 deeplink
通知记录	发送失败	企业微信消息发送失败	记录失败原因和重试次数
通知记录	已放弃	达到重试上限或配置不可用	管理员可查看原因

状态变更必须写入审计或操作日志。入口、绑定和通知状态不得替代 OA 业务单据状态。

4.4 异常规则

异常	处理规则	用户提示
未绑定	回退账号密码登录，登录后可自助绑定	“当前企业微信账号尚未绑定，请先使用 OA 账号登录并完成绑定”
重复绑定	阻断，并提示联系管理员	“该企业微信账号已绑定其他员工”
OA 账号停用	阻断进入业务页面	“账号已停用，请联系管理员”
企业微信回调失败	不创建会话，回退登录页	“企业微信登录失败，请重试或使用账号密码登录”
回跳地址不允许	阻断并记录安全日志	“回跳地址无效，请从工作台重新进入”
配置缺失	企业微信入口显示不可用或 SKIP	“企业微信入口暂未启用，请使用账号密码登录”

---

5. 消息通知与 deeplink

5.1 通知边界

• 企业微信消息只发送脱敏提醒，不承载正式审批动作。
• 消息内容只包含：标题、业务类型、业务编号、状态、处理入口。
• 消息不得包含完整发票图片、合同正文、敏感报价、银行卡、身份证、大段业务说明或密钥。
• OA 主办域的附件不通过企业微信原生审批或企业微信附件承载；员工点击消息后必须回到 OA 目标页按 OA 权限查看。
• 发送失败不阻断主业务提交、审批、付款或归档；失败记录进入可重试状态。

5.2 Deeplink 目标

业务场景	Deeplink 目标	要求
OA 主办审批待办	/mobile/approvals 或具体任务详情	点击后在 OA 内处理报销、采购、合同和财务类审批
企微主办 HR 审批	企业微信原生审批页	请假、补卡、外出、加班优先在企业微信处理，OA 同步镜像
报销提醒	移动报销详情或审批任务	展示脱敏摘要，附件和发票需按 OA 权限加载
请假/补卡/外出/加班	移动申请详情或审批任务	支持查看状态和处理待办
移动工作台	/mobile	作为兜底入口
绑定入口	个人设置或绑定页	仅在已账号密码登录后完成绑定

deeplink 必须校验目标地址白名单，避免跳转到非 OA 域名或未授权页面。

5.3 通知验收

• OA 主办待办产生后，目标审批人能收到脱敏提醒。
• OA 主办消息点击后进入 OA 对应移动页面；企微主办 HR/考勤审批在企业微信处理，OA 后续同步结果。
• 未登录或会话过期时，完成登录后应尽量回到原 deeplink 目标。
• 通知失败时业务流程仍成功，管理员可查看失败原因和重试状态。

---

6. 通讯录身份边界

• HRWD 已证明 OA 驱动企业微信通讯录成员创建、更新和禁用可行；WFOC 起后续主方向调整为企微/人事助手作为员工主数据源，OA 同步员工镜像、账号、角色、绑定和审计。
• HCLT 已完成公网真实写入验证：测试员工 HRWDTEST-20260517214548 已完成企业微信通讯录 create/update/disable，三次同步均为 wecom_contact_synced 且 errcode=0。
• 新员工后续目标流程为先在企微/人事助手创建，OA 通过 wecom_hr_master_sync_v1 同步后自动生成员工档案、账号、默认角色和 wecom_identity_bindings.external_user_id。OA 创建企微成员能力保留为管理员修复或迁移工具，不作为默认入职入口。
• OA 调岗、部门、职位、手机号、邮箱变化后，可触发企业微信成员更新；历史审批和历史业务单据不因调岗被改写。
• 离职完成后默认禁用企业微信成员，不删除成员；绑定关系和历史业务记录保留审计。
• 企业微信通讯录同步使用独立通讯录 Secret：WECOM_CONTACT_SYNC_ENABLED、WECOM_CONTACT_SECRET、WECOM_CONTACT_DEFAULT_DEPARTMENT_ID。不得默认复用应用消息 Secret，除非企业微信后台明确该 Secret 具备通讯录写权限。
• 缺 Secret、缺默认部门或缺通讯录 API 权限时，OA 人事流程照常完成，通讯录同步记录为 SKIP/BLOCKED_BY_EXTERNAL_CONFIG 或失败可重试，不伪造成成功。
• 通讯录同步记录只保存 employeeId、脱敏 externalUserId、操作、状态、错误码、重试次数和脱敏摘要；不得保存 access token、Secret、完整手机号、原始 payload 或敏感身份信息。

当前完成度：

项目	状态	当前口径
OA 员工生命周期	DONE	支持入职、转正、调岗、离职 checklist、账号禁用、会话失效和审计。
OA 驱动企微通讯录创建/更新/禁用	DONE_LIVE_VERIFIED	代码、同步记录、员工管理状态和重试入口已部署；HCLT 公网真实写入闭环通过，HRWDTEST-20260517214548 create/update/disable 均返回 errcode=0。其他环境缺 Secret、默认部门或通讯录 API 权限时仍按 SKIP/BLOCKED_BY_EXTERNAL_CONFIG 或失败可重试处理。
企微 HR 主数据同步 OA	LOCAL_IMPLEMENTED_PENDING_DEPLOY	wecom_hr_master_sync_v1 已本地实现：读取企微通讯录/人事助手，支持 dry-run/apply、同步记录、审计、People 管理入口和 QA-only runner；默认 force_off，尚未部署公网，未执行生产真实员工批量 apply。
企业微信原生审批	PARTIAL_REUSE_BY_WFOC	HR/考勤员工日常审批优先复用企业微信，OA 同步按域镜像；报销、财务、采购、合同、项目等 OA 主办审批不迁移。

---

7. 打卡原始采集边界

• 企业微信打卡用于原始采集和规则执行，保留其定位、人脸识别、Wi-Fi、排班、设备和防作弊能力。
• OA 不重造打卡定位、人脸识别、Wi-Fi、排班、设备绑定、防作弊和异常判断引擎；长期无痛接管目标优先保障关键申请和审计，不复刻企微所有风控能力。
• ATTV1 新增企微打卡摘要同步、同步批次和 raw hash 留痕；WFOC/DBWFOC 后后续目标扩展为打卡规则、排班、记录、日报、月报和异常摘要按域镜像。
• 请假、补卡、外出、加班优先走企业微信原生审批；OA 同步企微审批结果并形成考勤解释。
• 企业微信不可用时，管理员人工开启 oa_hr_emergency_mode_v1，OA 应急单据带 EMERGENCY 标记；企微恢复后由 wecom_recovery_writeback_v1 执行 dry-run、自动回写和冲突清单。

REQAUD 复核后，ATTV1 已完成统一入口实现，企业微信打卡边界进一步固定为：

项目	状态	当前口径
企业微信打卡运营使用	DONE	员工继续按公司要求使用企业微信打卡，定位、人脸、Wi-Fi、设备和防作弊由企业微信侧承担。
OA 同步企业微信打卡 API	PARTIAL	同步表、批次、摘要和脱敏错误码已实现；公网真实同步取决于已授权调用打卡 API 的自建应用 Secret 和企微打卡 API 权限。默认显式 WECOM_CHECKIN_SECRET 优先；未配置时复用已授权工作台应用的 WECOM_AGENT_SECRET。
OA 历史 attendance_v1 极简打卡	FROZEN_CLOSED	该模块已从正式入口关闭；旧表保留，旧写接口返回 409，不作为企微打卡能力。
正式考勤解释	REPLANNED_BY_WFOC	当前 OA 已支持请假、补卡、外出、加班审批和月度解释；后续目标改为企微审批主办、OA 按域镜像、应急接管和恢复回写。

7.5 接管、回写和 RuleOps

• oa_hr_emergency_mode_v1 默认关闭。企微不可用时，只允许管理员人工开启，并填写原因、范围、预计结束时间和责任人；系统不得因短时 API 异常完全自动切换。
• 应急模式只临时开放 HR/考勤类申请：请假、补卡、外出、加班。报销、PDF OCR、付款批次、银行回单、AP 台账和代账交接不受企微故障影响，继续由 OA 主办。
• wecom_recovery_writeback_v1 在企微恢复后先 dry-run，生成即将回写的审批、补卡、打卡或假期调整清单；无冲突项可自动回写，冲突、权限不足、API 不支持或风险过高时进入人工确认。
• wecom_ruleops_v1 允许 AI 读取 OA 制度和企微规则后生成建议配置、差异报告和风险提示；正式写入企微审批模板、打卡规则、排班、假期余额或人事字段前必须人工确认。
• 每次 RuleOps 写入必须保存前后快照、确认人、API errcode、失败原因、回滚建议和审计记录；不得保存 Secret、access token、完整位置、人脸数据或原始密钥材料。

7.6 DBWFOC 数据边界和按域镜像

• 企业微信成熟功能可作为 OA 流程、字段、交互和规则设计参考；参考不等于迁移数据主办方。
• 企业微信主办域镜像到 OA：通讯录/人事助手、打卡、请假、补卡、外出、加班、假期余额和 HR/考勤规则。
• OA 主办域不反向全量镜像到企业微信：报销、采购、费用、合同、项目、付款批次、AP、代账交接和审计只向企业微信发送脱敏提醒、状态和 OA 链接。
• 采购单附件、合同正文、报价、供应商资料、发票、银行回单和代账资料不进入企业微信原生审批或企业微信附件。
• 企业微信消息点击后进入 OA deeplink，完成企业微信免登录或账号绑定后回到目标页；审批动作仍在 OA 完成，服务端权限仍以 OA 为准。

7.7 WFDG 设计门禁与 POC 口径

• 企业微信/OA 后续改造必须先标注业务域主办方、主事实源、操作端、镜像方向、附件归属和审计责任。
• 企业微信同步必须具备幂等、重试、脱敏日志、审计记录和 SKIP/BLOCKED_BY_EXTERNAL_CONFIG 状态；缺 Secret、可信 IP、应用可见范围、模板或 API 权限时不得写成成功。
• WECOM-CAPABILITY-POC-V1 是正式开发前置，能力矩阵状态固定为 CAN_REUSE_NOW、NEEDS_CONFIG、NEEDS_API_POC、KEEP_OA_PRIMARY、NOT_SUPPORTED_BY_API。
• oa_hr_emergency_mode_v1 只能由管理员人工开启；恢复后由 wecom_recovery_writeback_v1 先 dry-run，再对无冲突项回写，冲突、权限不足或 API 不支持进入人工确认。
• wecom_ruleops_v1 中 AI 只负责草拟规则、差异报告和 dry-run；正式写入企微审批模板、打卡规则、排班、假期余额或人事字段前必须人工确认，并保存前后快照、确认人、API errcode、失败原因和回滚建议。

7.8 WDRG 开发路线图门禁

• WDRG 后，企业微信相关运行时迁移采用“路线图门禁 + 单功能 Issue CSV”，路线图事实源为 企微优先开发路线图。
• 阶段顺序固定为 WECOM-CAPABILITY-POC-V1 -> wecom_hr_master_sync_v1 -> wecom_attendance_approval_mirror_v1 -> oa_hr_emergency_mode_v1 -> wecom_recovery_writeback_v1 -> wecom_ruleops_v1。
• WECOM-CAPABILITY-POC-V1 未完成前，不得直接开发人事助手主数据镜像、企微 HR/考勤审批镜像、OA 应急接管、恢复回写或 RuleOps 正式写入。
• 线上缺陷、正式使用阻断、真实反馈扫尾和 QA-only 脚本维护可另开合同并行；采购、合同、报销、付款、AP、代账和高敏附件继续 OA 主办，不混入企微 HR/考勤路线。
• 本路线图只代表开发节奏和门禁，不代表任何企微 HR/考勤镜像、OA 应急接管、恢复回写或 RuleOps 运行时能力已完成。

7.9 WCP1 企业微信能力 POC 结果

2026-05-18 已完成 WECOM-CAPABILITY-POC-V1。本轮新增 QA-only 只读脚本 scripts/qa/check-wecom-capability-poc.mjs，默认不写生产数据、不改企微规则、不批量读取真实员工明细，只输出脱敏能力矩阵。部署服务器容器内 live 只读初始探测结论为 PAUSE_FOR_CONFIG，报告目录为远端 /tmp/wecom-capability-poc-wcp1/summary.json；该历史阻断已由 WCPC 复跑收口。

WCP1 当前分类：

能力	WCP1 结论	说明
工作台应用 token 和核心配置	CAN_REUSE_NOW	CorpID、Agent、Secret、OAuth 等基础配置存在，access token 可获取。
通讯录 create/update/disable	CAN_REUSE_NOW	复用 HCLT 证据：HRWDTEST-20260517214548 create/update/disable 均 errcode=0。
通讯录部门读取	CAN_REUSE_NOW	工作台应用 token fallback 可读部门列表。
通讯录测试成员读取	NEEDS_CONFIG	contact.member_read 返回 wecom_errcode_48009，需核对通讯录读取权限、应用可见范围或测试成员状态。
人事助手字段配置读取	CAN_REUSE_NOW	hr.fields_read 可读。
人事助手测试员工花名册读取	NEEDS_CONFIG	hr.staff_read 返回 wecom_errcode_60021，需将测试成员纳入应用/人事助手权限范围，或改用在职测试员工复跑。
人事助手资料更新	NEEDS_API_POC	属生产写接口，本轮只分类，不调用。
打卡记录和规则读取	NEEDS_CONFIG	远端 WECOM_CHECKIN_SYNC_ENABLED 未开启，短窗口打卡和规则读取按配置阻断记录。
审批模板、审批详情、假期余额	NEEDS_CONFIG	缺审批模板 ID、测试审批单号，假期余额返回 wecom_errcode_301062。
回调配置	NEEDS_CONFIG	回调 URL、Token、AESKey 未作为可读配置注入，本轮不能证明回调链路。
采购/合同/报销/财务审批	KEEP_OA_PRIMARY	继续 OA 主办，企业微信只做脱敏消息和 OA deeplink。

WCP1 历史结论不是 GO_TO_HR_MASTER_SYNC，但该阻断已由 WCPC 复跑收口。WCP1 报告继续作为初始配置缺口证据保留，当前 HR 主数据镜像准入以 WCPC 结论为准。

7.10 WCPC 配置复跑口径

WCP1-CONFIG-CLOSEOUT-V1 是 WCP1 后的配置收口合同。其目标不是开发运行时功能，而是补齐或确认企业微信后台配置后复跑只读 POC。2026-05-18 已按用户要求改用既有账户并完成远端只读复跑。

已完成结果：

• 使用已有在职低风险测试号 SMOKE002/测试员工，不使用已离职/禁用的 HRWDTEST-20260517214548 作为主测试对象。
• 报告、Issue 和文档只记录脱敏企业微信 userid 前缀 oa_smoke***，不打印完整手机号、位置、token、Secret 或原始 payload。
• 远端报告为 /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、NOT_SUPPORTED_BY_API=0。
• Secret、access token、回调 Token 和 EncodingAESKey 未写入仓库、未打印到报告、未在聊天中明文传递。
• 服务器侧复跑只做临时环境变量注入，不持久修改 .env，不重启服务。

复跑准入结果：

能力	结果
contact.member_read	CAN_REUSE_NOW，既有在职测试号读取通过。
hr.staff_read	CAN_REUSE_NOW，既有在职测试号花名册读取通过。
checkin.records_read / checkin.rules_read	CAN_REUSE_NOW，短窗口记录和规则读取通过；细分日报、月报、排班留到考勤镜像合同。
approval.vacation_quota	CAN_REUSE_NOW。
approval.template_detail / approval.instance_detail	NEEDS_CONFIG，缺审批模板 ID 和测试审批单号 sp_no；不阻断 HR 主数据镜像，但阻断考勤/审批镜像。
callback.config	NEEDS_CONFIG，本轮未证明真实事件回调配置存在；真实事件回调接收、解密、幂等和入库留到 wecom_attendance_approval_mirror_v1。
hr.staff_update_classification	NEEDS_API_POC，资料更新属于写接口，需单独批准后再做低风险 POC。
approval.oa_primary_sensitive_domains	KEEP_OA_PRIMARY，采购、合同、报销、财务等继续 OA 主办。

WCPC 已达到 GO_TO_HR_MASTER_SYNC。WHMS 已承接该结论并完成 wecom_hr_master_sync_v1 本地实现；不得直接开发考勤/审批镜像、OA 应急接管、恢复回写或 RuleOps。

7.11 WHMS 企微 HR 主数据同步 OA

WECOM-HR-MASTER-SYNC-V1 承接 WCPC 的 GO_TO_HR_MASTER_SYNC 结论，把企业微信/人事助手作为员工主数据源的读取能力落成 OA 镜像能力。本阶段仅同步 HR 主数据，不迁移考勤/审批镜像、审批回调、恢复回写、RuleOps、HR 写企微接口、采购/合同/财务流程。

本地实现范围：

• 新增 feature flag wecom_hr_master_sync_v1，默认 force_off。
• 新增配置 WECOM_HR_MASTER_SYNC_ENABLED、WECOM_HR_ASSISTANT_SECRET；WECOM_AGENT_SECRET 仅作为已验证授权应用的只读 fallback，并在同步批次中记录 token source，不输出 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。
• 新增 WecomHrMasterSyncRun、WecomHrMasterSyncItem，记录批次、逐员工动作、脱敏 externalUserId、字段差异、失败原因、重试次数和操作人。
• People/人员管理页新增“企微 HR 主数据镜像”卡片，管理员可执行 dry-run、确认 apply、查看最近同步和失败摘要；普通员工不可见。
• QA-only runner scripts/qa/check-wecom-hr-master-sync.mjs 默认只跑列表和 dry-run；apply 必须显式传入 userids 并设置批准环境变量。

同步规则：

• dry_run 不创建或更新 OA 员工、账号、部门或绑定，只生成差异和同步记录。
• apply 写入 OA 员工档案、部门映射、默认 employee 角色、企业微信绑定和可解析主管关系，并记录审计。
• 匹配优先级：wecom_identity_bindings.external_user_id -> 企微 userid/工号 -> 手机号 -> 邮箱。
• 缺姓名、手机号、邮箱或部门时记录 SKIP missing_required_field，不自动生成占位数据。
• 企微不在职或禁用状态记录 needs_offboarding_confirmation，不自动禁用 OA 账号；离职仍必须走 OA checklist。
• 已有 OA 员工只更新安全主数据字段：姓名、部门、职位、直属主管、手机号、邮箱和企微绑定；不覆盖银行账户、身份证、工资、合同附件或历史审批。
• 日志、报告和审计不得输出完整手机号、邮箱、userid、Secret、access token 或企微原始 payload。

当前状态：

• WHMS 已本地实现并进入本轮门禁验证；尚未部署公网。
• 生产批量 apply、公网开启 wecom_hr_master_sync_v1、正式真实员工同步和部署复检必须另行确认或纳入部署/公网验证合同。
• WHMS 不解除考勤/审批镜像前置缺口；wecom_attendance_approval_mirror_v1 仍需另建合同补审批模板、审批单号和回调配置。

---

8. 验收场景

场景	步骤	预期结果
已绑定用户直达	员工从手机企业微信进入 海音达工作台	直达 /mobile 或 deeplink 目标页
未绑定回退	未绑定员工从企业微信进入	提示未绑定，可使用账号密码登录后绑定
重复绑定阻断	管理员或员工尝试把同一企业微信身份绑定多个员工	操作失败并留下审计记录
离职停用拦截	已停用员工从企业微信入口进入	不能进入 OA 业务页面
OA 主办审批通知回 OA	报销、采购、合同或财务待办产生后发送企业微信提醒	点击消息进入 OA 审批页，审批动作在 OA 完成
企微主办 HR 审批镜像	员工在企业微信提交请假、补卡、外出或加班	OA 同步审批单、审批历史、附件、状态回调和审计镜像
OA 应急接管	管理员人工开启应急模式后，员工在 OA 提交 HR/考勤应急申请	单据带 EMERGENCY 标记，进入恢复回写队列
恢复回写	企业微信恢复后执行 dry-run 和回写	成功、失败、冲突和人工确认项均可审计
报销通知脱敏	报销状态变化发送提醒	消息只有标题、编号、状态和入口，不含完整发票或附件
高敏附件边界	采购、合同、项目或财务事项产生企业微信提醒	企业微信只显示脱敏摘要和 OA 链接，不上传附件原文、不展示合同正文、报价、发票或银行回单
通知失败不阻断	模拟企业微信消息发送失败	主业务成功，通知进入失败可重试
打卡边界确认	员工使用企业微信打卡，OA 查看考勤相关说明	文档和界面不暗示 OA 已重造定位、人脸或排班

---

9. 后续开发拆分建议

• A1：企业微信配置探活和入口开关，覆盖启用、禁用、缺配置和 SKIP。
• A2：企业微信 WebView 识别和 /mobile 默认入口。
• A3：企业微信 OAuth/免登与账号绑定、解绑、重复绑定阻断。
• A4：离职停用、组织权限和绑定异常拦截。
• A5：企业微信通知 provider 和失败重试，不阻断主业务。
• A6：deeplink 白名单和移动目标页回跳。
• A7：wecom_hr_master_sync_v1，企微/人事助手员工主数据同步 OA；WHMS 已本地实现，待部署和受控公网验证。
• A8：wecom_attendance_approval_mirror_v1，企微请假、补卡、外出、加班审批和打卡数据按域镜像；该命名承接旧口径 wecom_native_approval_mirror_v1。
• A9：oa_hr_emergency_mode_v1，OA 人工接管 HR/考勤应急提交。
• A10：wecom_recovery_writeback_v1，企微恢复后 dry-run、自动回写、失败重试和冲突清单。
• A11：wecom_ruleops_v1，AI 草拟、人工确认、API 写入和配置快照审计。

涉及真实企业微信凭据、回调域名、可信域名、生产配置或真机验证的 Issue，必须在技术方案中写明配置项、回滚路径和无法自动化时的人工验收步骤。