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

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

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

本规约细化企业微信在 `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 保留修复和审计 | `PARTIAL_CAN_REUSE`：HCLT create/update/disable 和部门读取可用，测试成员读取待配置 |
| 人事助手 | 员工字段配置、花名册读取、花名册更新 | 作为员工主数据源，驱动 OA 员工、账号、角色、绑定和状态镜像 | `PARTIAL_NEEDS_CONFIG`：字段配置可读，测试员工花名册读取待配置，更新接口需单独写入 POC |
| 打卡 | 打卡记录、员工规则、日报、月报、排班、补卡、规则管理 | 企微主办规则和采集，OA 同步按域镜像和应急对账 | `NEEDS_CONFIG`：WCP1 远端只读 POC 显示当前未开启打卡同步配置 |
| 审批 | 模板详情、提交审批、审批状态回调、审批详情、模板创建/更新、假期余额 | HR/考勤员工日常审批企微主办，OA 同步镜像；OA 主办财务、采购、合同、项目和报销审批不迁移 | `NEEDS_CONFIG`：缺模板、测试审批单、假期权限和回调配置 |
| 工作台和消息 | 自建应用入口、应用消息、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 | `PLANNED_BY_WFOC` | 后续以 `wecom_hr_master_sync_v1` 拆实现合同，员工主数据从企微/人事助手同步到 OA。 |
| 企业微信原生审批 | `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”，路线图事实源为 [企微优先开发路线图](./企微优先开发路线图.md)。
- 阶段顺序固定为 `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`。

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`。在 `contact.member_read` 和 `hr.staff_read` 至少对一个在职测试成员通过、审批/打卡/回调关键配置有清晰处理方式，并复跑 POC 得到准入结论前，不得启动 `wecom_hr_master_sync_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。
- 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，必须在技术方案中写明配置项、回滚路径和无法自动化时的人工验收步骤。