WFOC 重构企微优先与OA接管需求口径

2026-05-18 10:44:30 +08:00
@@ -7,7 +7,7 @@
 **相关事实源**：[需求 - 统一审批中心规约](./需求-统一审批中心规约.md)、[需求 - 企业微信基础设施规约](./需求-企业微信基础设施规约.md)
 **体验总依据**：[产品设计规则基线](./产品设计规则.md)

-本规约细化请假、补卡、外出、加班与考勤修正的产品要求。正式审批记录以 OA 为准；企业微信打卡只作为原始采集来源，不直接决定最终考勤结论。PC 和移动页面体验以产品设计规则基线为依据，不重复定义通用审批链和移动导航规则。
+本规约细化请假、补卡、外出、加班与考勤修正的产品要求。WFOC 起，企业微信作为 HR/考勤/行政审批和打卡规则主操作端；OA 负责完整镜像、应急接管、恢复回写、查询导出和审计。PC 和移动页面体验以产品设计规则基线为依据，不重复定义通用审批链和移动导航规则。

 ---

@@ -15,10 +15,11 @@

 ### 1.1 目标

- 员工能在 OA PC 或移动端提交请假、补卡、外出、加班申请。
- 主管、HR/管理员在 OA 内审批并留痕。
- 已通过的考勤修正影响团队状态、日历展示和后续正式考勤口径。
- 企业微信打卡原始记录由 OA 按摘要同步，必须结合 OA 审批结果解释。
+- 员工正常在企业微信提交请假、补卡、外出、加班申请，并继续使用企业微信打卡。
+- 主管、HR/管理员正常在企业微信处理 HR/考勤审批；OA 同步审批单、审批历史、附件、状态回调、假期余额和打卡数据。
+- OA 保存完整原始归档和规范化镜像，用于团队状态、日历展示、考勤解释、审计和导出。
+- 企业微信不可用时，管理员可人工开启 OA 应急模式，临时开放请假、补卡、外出、加班提交和审批。
+- 企微恢复后，OA 对应急单据执行 dry-run、自动回写、失败重试和冲突清单。

 ### 1.2 适用对象

@@ -30,11 +31,11 @@

 ### 1.3 不做范围

- 不使用企业微信原生审批处理请假、补卡、外出、加班。
+- 不在企微正常可用时引导员工绕开企业微信到 OA 提交 HR/考勤新单。
 - 首批不重造企业微信打卡的定位、人脸识别、Wi-Fi、排班和防作弊规则。
- 不在 OA 内重造企业微信打卡采集和风控；OA 只同步摘要并做审批解释。
+- 不在 OA 内重造企业微信打卡采集和风控；OA 同步记录、规则、日报、月报和异常摘要并做镜像解释。
 - 首批不做复杂假期余额、调休余额、薪资计算、排班引擎和法定节假日自动规则。
- 不把企业微信打卡异常直接作为 OA 最终考勤结论。
+- 不把企业微信打卡异常直接作为 OA 最终考勤结论；最终解释需结合企微审批、OA 应急单和恢复对账结果。

 ### 1.4 当前实现状态

@@ -42,14 +43,17 @@ REQAUD 复核后，ATTV1 已完成统一入口实现，当前运行时完成度

 | 能力 | 状态 | 当前口径 |
 | --- | --- | --- |
-| 请假申请、审批、撤回、编辑、移动查看 | `DONE` | 已接入统一审批中心和 PC/移动页面。 |
+| 请假申请、审批、撤回、编辑、移动查看 | `DONE_AS_OA_FALLBACK` | 当前已接入统一审批中心和 PC/移动页面；WFOC 后默认转为历史查询和应急接管能力。 |
 | 请假对团队状态/日历的影响 | `DONE` | 已批准请假可作为团队状态和日历依据。 |
 | 企业微信打卡作为原始采集 | `DONE` | 由企业微信侧承载定位、人脸、Wi-Fi、设备和防作弊能力；OA 不重造。 |
 | 企业微信打卡 API 同步 | `PARTIAL` | 已新增同步批次和企微打卡摘要表；有已授权调用打卡 API 的自建应用 Secret 和企微权限时同步，缺配置时记录 `SKIP`。`WECOM_CHECKIN_SECRET` 可作为单独考勤同步应用的显式覆盖；未配置时复用已授权工作台应用的 `WECOM_AGENT_SECRET`。 |
-| 员工补卡申请审批 | `DONE` | 员工可在 OA 提交补卡修正，进入统一审批；通过后用于月度考勤解释，不写回企业微信。 |
-| 外出申请审批 | `DONE` | 员工可在 OA 提交外出修正，记录地点摘要和事由，审批后用于月度解释。 |
-| 加班申请审批 | `DONE` | 员工可在 OA 提交加班修正，记录时间、原因和补偿口径，审批后用于月度解释。 |
+| 企微 HR/考勤审批镜像 | `PLANNED_BY_WFOC` | 后续通过 `wecom_native_approval_mirror_v1` 同步企微请假、补卡、外出、加班审批详情、历史、附件和状态。 |
+| 员工补卡申请审批 | `DONE_AS_OA_FALLBACK` | 当前 OA 能提交补卡修正；WFOC 后正常入口迁往企微，OA 仅在应急模式开放并进入恢复回写。 |
+| 外出申请审批 | `DONE_AS_OA_FALLBACK` | 当前 OA 能提交外出修正；WFOC 后正常入口迁往企微，OA 仅在应急模式开放并进入恢复回写。 |
+| 加班申请审批 | `DONE_AS_OA_FALLBACK` | 当前 OA 能提交加班修正；WFOC 后正常入口迁往企微，OA 仅在应急模式开放并进入恢复回写。 |
 | 历史 OA 极简打卡 `attendance_v1` | `FROZEN_CLOSED` | 自建上下班打卡、管理员补卡和自建月度统计已关闭正式入口；旧表保留，旧写接口返回可解释 409。 |
+| OA 应急模式 | `PLANNED_BY_WFOC` | `oa_hr_emergency_mode_v1` 默认关闭，企微不可用时由管理员人工开启。 |
+| 恢复回写 | `PLANNED_BY_WFOC` | `wecom_recovery_writeback_v1` 在企微恢复后 dry-run 并自动回写应急数据，冲突转人工确认。 |

 ---

@@ -57,9 +61,9 @@ REQAUD 复核后，ATTV1 已完成统一入口实现，当前运行时完成度

 | 角色 | 可做动作 | 权限边界 |
 | --- | --- | --- |
-| 申请人 | 新建草稿、提交、撤回、查看自己的申请、按退回意见修改重提 | 只能编辑本人草稿、已退回或允许重提的申请 |
-| 主管/审批人 | 查看分配给自己的待办，通过、驳回、退回、转审 | 只能处理当前分配给自己的 OA 审批任务 |
-| HR/管理员 | 复核请假、补卡、外出、加班，维护基础假别和考勤口径 | 不能绕过流程直接改审批结果；必要修正必须审计 |
+| 申请人 | 正常在企业微信提交和查看请假、补卡、外出、加班；应急模式下在 OA 提交 | OA 应急提交必须在管理员开启窗口内，且单据带 `EMERGENCY` 标记 |
+| 主管/审批人 | 正常在企业微信处理 HR/考勤审批；OA 主办或应急待办在 OA 处理 | 只能处理分配给自己的待办；企微和 OA 结果必须可对账 |
+| HR/管理员 | 配置企微 HR/考勤规则，查看 OA 镜像，开启/关闭应急模式，处理恢复回写冲突 | 不能绕过流程直接改业务结果；应急开启、回写和人工修正必须审计 |
 | 老板/总经理 | 处理长假、高风险或特殊事项 | 操作仍需写入审批历史和审计日志 |
 | 系统管理员 | 维护权限、通知、入口、基础配置 | 默认不具备业务审批权 |

@@ -71,9 +75,9 @@ REQAUD 复核后，ATTV1 已完成统一入口实现，当前运行时完成度

 | 入口 | 场景 | 要求 |
 | --- | --- | --- |
-| PC 请假/考勤修正页 | 批量查看、较复杂申请、管理员复核 | 可查看完整字段、审批历史和团队影响 |
-| 移动工作台 | 员工日常提交请假、补卡、外出、加班 | 操作路径短，适合手机填写 |
-| 移动审批 | 主管或 HR 处理待办 | 进入 OA 审批页处理，不进入企业微信原生审批 |
+| PC 请假/考勤修正页 | 查看企微镜像、历史 OA 单据、应急单和恢复回写状态 | 默认不作为新单日常入口；应急模式开启时才开放提交 |
+| 移动工作台 | 查看镜像状态、历史和应急入口提示 | 企微正常时引导员工到企业微信处理日常 HR/考勤申请 |
+| 移动审批 | 主管或 HR 处理 OA 主办或应急待办 | 企微主办 HR 审批在企业微信处理，OA 只显示镜像 |
 | 团队状态页 | 查看今天谁在岗、请假、外出、出差 | 使用已批准申请影响展示 |
 | 日历视图 | 查看请假和外出安排 | 首批可轻量展示，不做复杂排班 |
 | 企业微信 deeplink | 通知提醒和跳转 | 点击后回 OA 页面 |
@@ -115,7 +119,7 @@ REQAUD 复核后，ATTV1 已完成统一入口实现，当前运行时完成度

 ### 5.1 审批规则

-以下是 10 人以下公司试运行建议值，不等于最终公司制度。正式制度可由管理员配置调整。
+WFOC 后，正常审批规则优先以企业微信审批模板和打卡/假期配置为准；OA 中以下规则保留为应急接管建议值，不等于最终公司制度。正式制度可由管理员配置调整，并通过 `wecom_ruleops_v1` 先 dry-run、人工确认后写入企微。

 | 类型 | 阈值 | 默认审批链 | HR/管理员复核 | 兜底审批人 |
 | --- | --- | --- | --- | --- |
@@ -148,9 +152,9 @@ REQAUD 复核后，ATTV1 已完成统一入口实现，当前运行时完成度

 ### 6.1 基本原则

- 企业微信打卡记录是原始采集事实。
- OA 请假、补卡、外出、加班审批是考勤解释事实。
- 最终正式考勤口径应由企业微信打卡原始记录加 OA 审批结果共同形成。
+- 企业微信打卡记录、打卡规则和 HR/考勤审批是正常情况下的原始业务事实。
+- OA 镜像记录、历史 OA 单据和应急单据是审计、查询、接管和恢复对账事实。
+- 最终正式考勤口径应由企业微信打卡原始记录、企微审批结果、OA 应急单和恢复回写结果共同形成。
 - 企业微信打卡异常不直接等于最终考勤异常。
 - OA 首批不重造定位、人脸识别、Wi-Fi、排班和防作弊规则。

@@ -158,10 +162,11 @@ REQAUD 复核后，ATTV1 已完成统一入口实现，当前运行时完成度

 | 场景 | 原始打卡 | OA 审批 | 正式解释 |
 | --- | --- | --- | --- |
-| 已批准请假 | 无打卡或不完整 | 请假已通过 | 按请假处理，不直接记异常 |
-| 忘打卡 | 缺少上班或下班卡 | 补卡已通过 | 按补卡修正解释 |
-| 客户现场 | 打卡地点异常或无办公室打卡 | 外出已通过 | 按外出处理 |
-| 晚间工作 | 正常下班后继续工作 | 加班已通过 | 记录加班事实，补偿另按制度处理 |
+| 已批准请假 | 无打卡或不完整 | 企微请假已通过，OA 已同步镜像 | 按请假处理，不直接记异常 |
+| 忘打卡 | 缺少上班或下班卡 | 企微补卡已通过，OA 已同步镜像 | 按补卡修正解释 |
+| 客户现场 | 打卡地点异常或无办公室打卡 | 企微外出已通过，OA 已同步镜像 | 按外出处理 |
+| 晚间工作 | 正常下班后继续工作 | 企微加班已通过，OA 已同步镜像 | 记录加班事实，补偿另按制度处理 |
+| 企微故障应急 | 无法提交企微审批 | OA `EMERGENCY` 应急单已通过，恢复后已回写或待对账 | 按 OA 应急单和回写结果解释 |
 | 无审批异常 | 缺卡或迟到 | 无有效 OA 审批 | 保持异常待处理或人工复核 |

 ---
@@ -188,7 +193,7 @@ REQAUD 复核后，ATTV1 已完成统一入口实现，当前运行时完成度
 | 权限不足 | 服务端拒绝 | “无权处理该申请” |
 | 团队状态更新失败 | 审批保持成功，生效状态进入失败可重试 | “申请已审批通过，状态同步稍后重试” |
 | 已生效后取消 | 仅授权 HR/管理员处理，必须填写原因 | “已生效申请取消需管理员处理” |
-| 企业微信打卡未同步 | 不影响 OA 申请审批 | “打卡原始记录暂未同步，审批结果已在 OA 留痕” |
+| 企业微信打卡或审批未同步 | 不影响企微已完成事实；OA 镜像进入可重试或待配置状态 | “企业微信数据暂未同步，稍后重试或联系管理员” |

 ---

@@ -196,26 +201,28 @@ REQAUD 复核后，ATTV1 已完成统一入口实现，当前运行时完成度

 | 场景 | 步骤 | 预期结果 |
 | --- | --- | --- |
-| 请假主管审批 | 员工提交 `0.5` 天请假；主管通过 | 申请已通过，并影响团队状态 |
-| 长假 HR 复核 | 员工提交 `2` 天请假；主管通过；HR 复核 | 审批链完整，HR 复核后生效 |
-| 补卡审批 | 员工提交缺失下班卡补卡；主管和 HR 通过 | 补卡记录影响考勤解释 |
-| 外出审批 | 员工提交客户现场外出；主管通过 | 团队状态显示外出或相关摘要 |
-| 加班审批 | 员工提交晚间加班；主管和 HR 通过 | 加班记录留痕，补偿口径被记录 |
-| 退回修改 | 审批人退回申请；员工修改后重提 | 保留退回历史，重新进入审批 |
+| 企微请假镜像 | 员工在企业微信提交 `0.5` 天请假；主管通过；OA 同步 | OA 可查看审批详情、历史、附件和团队状态影响 |
+| 企微补卡镜像 | 员工在企业微信提交缺失下班卡补卡；主管或 HR 通过；OA 同步 | 补卡记录影响考勤解释 |
+| 企微外出镜像 | 员工在企业微信提交客户现场外出；主管通过；OA 同步 | 团队状态显示外出或相关摘要 |
+| 企微加班镜像 | 员工在企业微信提交晚间加班；主管或 HR 通过；OA 同步 | 加班记录留痕，补偿口径被记录 |
+| OA 应急提交 | 管理员开启 `oa_hr_emergency_mode_v1` 后员工在 OA 提交 HR/考勤应急单 | 单据带 `EMERGENCY` 标记并进入恢复回写队列 |
+| 恢复回写 | 企业微信恢复后，OA 对应急单 dry-run 并回写 | 成功、失败、冲突和人工确认项均可追溯 |
+| 退回修改 | 企微审批或 OA 应急审批退回后，员工按对应入口修改重提 | 保留退回历史，重新进入审批 |
 | 撤回 | 员工在审批完成前撤回 | 审批待办失效，历史保留 |
-| 无审批人阻断 | 删除或缺失主管后提交 | 提交失败，不生成半截流程 |
-| 企业微信提醒回 OA | 待办产生后发送企业微信提醒 | 点击 deeplink 回 OA 审批页处理 |
+| 无审批人阻断 | 企业微信模板或 OA 应急规则找不到审批人 | 提交失败，不生成半截流程 |
+| OA 主办提醒回 OA | 报销、采购、合同或财务待办产生后发送企业微信提醒 | 点击 deeplink 回 OA 审批页处理 |
 | 团队状态失败不破坏审批 | 模拟团队状态更新失败 | 审批保持已通过，生效状态可重试 |

 ---

 ## 10. 后续开发拆分建议

- 已完成：补卡/外出/加班申请对象、统一审批接入、月度考勤解释页、移动入口和企业微信 deeplink 回 OA。
- 后续 A1：企微打卡 live 同步配置稳定化，覆盖 Secret/API 权限、短窗口同步、错误码和脱敏证据。
- 后续 A2：团队状态和日历生效逻辑增强，按真实使用反馈决定是否把外出/加班进一步展示到团队状态或日历。
- 后续 A3：移动端提交与审批体验优化，覆盖普通手机和企业微信 WebView 的真实反馈。
- 后续 A4：请假考勤主链路回归脚本和人工验收数据集。
- 后续 A5：出差完整流程专项，不进入当前正式首批能力。
+- 已完成：OA 侧补卡/外出/加班申请对象、统一审批接入、月度考勤解释页、移动入口和企业微信 deeplink 回 OA；WFOC 后这些能力默认作为历史查询和应急接管基础。
+- 后续 A1：`wecom_native_approval_mirror_v1`，同步企微请假、补卡、外出、加班审批、附件、历史和状态回调。
+- 后续 A2：企微打卡规则、排班、记录、日报、月报完整镜像，覆盖 Secret/API 权限、短窗口同步、错误码和脱敏证据。
+- 后续 A3：`oa_hr_emergency_mode_v1`，管理员人工接管、应急提交、应急审批和恢复队列。
+- 后续 A4：`wecom_recovery_writeback_v1`，企微恢复后 dry-run、自动回写、失败重试和冲突清单。
+- 后续 A5：团队状态和日历按企微镜像、OA 应急单和回写结果统一解释。
+- 后续 A6：出差完整流程专项，不进入当前正式首批能力。

 涉及审批状态、团队状态、生效记录或后续打卡同步的 Issue，必须写明失败重试、回滚策略和人工修正路径。