需求 - 请假考勤修正规约
版本：1.0
日期：2026-05-09
状态：模块级开发规约
上级事实源：海音达OA-MVP需求规格说明书
相关事实源：需求 - 统一审批中心规约、需求 - 企业微信基础设施规约
体验总依据：产品设计规则基线
本规约细化请假、补卡、外出、加班与考勤修正的产品要求。WFOC 起，企业微信作为 HR/考勤员工日常审批和打卡规则主操作端；OA 负责按域镜像、应急接管、恢复回写、查询导出和审计。PC 和移动页面体验以产品设计规则基线为依据，不重复定义通用审批链和移动导航规则。
1. 模块目标与边界
1.1 目标
- 员工正常在企业微信提交请假、补卡、外出、加班申请，并继续使用企业微信打卡。
- 主管、HR/管理员正常在企业微信处理 HR/考勤审批；OA 同步审批单、审批历史、附件、状态回调、假期余额和打卡数据。
- OA 保存完整原始归档和规范化镜像，用于团队状态、日历展示、考勤解释、审计和导出。
- 企业微信不可用时，管理员可人工开启 OA 应急模式，临时开放请假、补卡、外出、加班提交和审批。
- 企微恢复后，OA 对应急单据执行 dry-run、自动回写、失败重试和冲突清单。
- WFDG 后，正常页面和接口必须区分企微主办镜像、历史 OA fallback 和 OA 应急接管；缺企微 Secret、审批模板、回调或 API 权限时记录
SKIP/BLOCKED_BY_EXTERNAL_CONFIG，不得伪造成同步成功。
1.2 适用对象
- 请假：年假、事假、病假、调休、其他假别。
- 补卡：漏打卡、忘打卡、设备异常、外勤导致未打卡等修正。
- 外出：工作时间内外勤、客户拜访、项目现场、临时外出。
- 加班：工作日加班、周末加班、节假日加班。
- 出差：首批只保留后续扩展边界，不在本规约内做完整差旅单。
1.3 不做范围
- 不在企微正常可用时引导员工绕开企业微信到 OA 提交 HR/考勤新单。
- 首批不重造企业微信打卡的定位、人脸识别、Wi-Fi、排班和防作弊规则。
- 不在 OA 内重造企业微信打卡采集和风控；OA 同步记录、规则、日报、月报和异常摘要并做镜像解释。
- 首批不做复杂假期余额、调休余额、薪资计算、排班引擎和法定节假日自动规则。
- 不把企业微信打卡异常直接作为 OA 最终考勤结论；最终解释需结合企微审批、OA 应急单和恢复对账结果。
- 本规约只覆盖 HR/考勤员工日常审批，不改变采购、费用、合同、项目、报销和财务审批继续 OA 主办的边界。
1.4 当前实现状态
REQAUD 复核后，ATTV1 已完成统一入口实现，当前运行时完成度如下：
| 能力 |
状态 |
当前口径 |
| 请假申请、审批、撤回、编辑、移动查看 |
DONE_AS_OA_FALLBACK |
当前已接入统一审批中心和 PC/移动页面；WFOC 后默认转为历史查询和应急接管能力。 |
| 请假对团队状态/日历的影响 |
DONE |
已批准请假可作为团队状态和日历依据。 |
| 企业微信打卡作为原始采集 |
DONE |
由企业微信侧承载定位、人脸、Wi-Fi、设备和防作弊能力；OA 不重造。 |
| 企业微信打卡 API 同步 |
PARTIAL |
已新增同步批次和企微打卡摘要表；有已授权调用打卡 API 的自建应用 Secret 和企微权限时同步，缺配置时记录 SKIP。WECOM_CHECKIN_SECRET 可作为单独考勤同步应用的显式覆盖；未配置时复用已授权工作台应用的 WECOM_AGENT_SECRET。 |
| 企微 HR/考勤审批镜像 |
PLANNED_BY_WFOC |
后续通过 wecom_attendance_approval_mirror_v1 同步企微请假、补卡、外出、加班审批详情、历史、附件和状态；该命名承接旧口径 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 并自动回写应急数据，冲突转人工确认。 |
2. 角色与权限
| 角色 |
可做动作 |
权限边界 |
| 申请人 |
正常在企业微信提交和查看请假、补卡、外出、加班；应急模式下在 OA 提交 |
OA 应急提交必须在管理员开启窗口内，且单据带 EMERGENCY 标记 |
| 主管/审批人 |
正常在企业微信处理 HR/考勤审批；OA 主办或应急待办在 OA 处理 |
只能处理分配给自己的待办；企微和 OA 结果必须可对账 |
| HR/管理员 |
配置企微 HR/考勤规则，查看 OA 镜像，开启/关闭应急模式，处理恢复回写冲突 |
不能绕过流程直接改业务结果；应急开启、回写和人工修正必须审计 |
| 老板/总经理 |
处理长假、高风险或特殊事项 |
操作仍需写入审批历史和审计日志 |
| 系统管理员 |
维护权限、通知、入口、基础配置 |
默认不具备业务审批权 |
审批动作、转审、撤回、退回、驳回和历史留痕以 需求 - 统一审批中心规约 为总依据。
3. 入口与对象
| 入口 |
场景 |
要求 |
| PC 请假/考勤修正页 |
查看企微镜像、历史 OA 单据、应急单和恢复回写状态 |
默认不作为新单日常入口；应急模式开启时才开放提交 |
| 移动工作台 |
查看镜像状态、历史和应急入口提示 |
企微正常时引导员工到企业微信处理日常 HR/考勤申请 |
| 移动审批 |
主管或 HR 处理 OA 主办或应急待办 |
企微主办 HR 审批在企业微信处理，OA 只显示镜像 |
| 团队状态页 |
查看今天谁在岗、请假、外出、出差 |
使用已批准申请影响展示 |
| 日历视图 |
查看请假和外出安排 |
首批可轻量展示，不做复杂排班 |
| 企业微信 deeplink |
通知提醒和跳转 |
点击后回 OA 页面 |
4. 申请字段
4.1 通用字段
| 字段 |
含义 |
要求 |
| 申请编号 |
OA 生成的唯一编号 |
提交前或首次保存时生成，必须唯一 |
| 申请类型 |
请假、补卡、外出、加班 |
必填 |
| 申请人 |
发起人 |
必填 |
| 部门 |
申请人所属部门 |
系统带出 |
| 开始时间 |
申请开始时间 |
请假、外出、加班必填 |
| 结束时间 |
申请结束时间 |
请假、外出、加班必填 |
| 时长 |
小时或天 |
系统计算，允许按业务规则人工修正并留痕 |
| 原因 |
申请说明 |
必填 |
| 附件 |
病假证明、外出证明、加班依据等 |
按类型和规则决定 |
| 关联项目/客户 |
项目现场、客户拜访、项目加班等 |
外出、加班、项目相关请假建议填写 |
| 审批状态 |
草稿、审批中、已通过等 |
系统维护 |
| 生效状态 |
是否已影响团队状态或考勤口径 |
系统维护 |
4.2 类型专属字段
| 类型 |
专属字段 |
要求 |
| 请假 |
假别、请假时段、是否半天、是否需证明 |
病假或特殊假别可要求附件 |
| 补卡 |
补卡日期、补卡时间点、上班/下班卡、异常原因 |
必须指向具体缺失或异常打卡时间点 |
| 外出 |
外出地点、外出事由、客户/项目、预计返回时间 |
应说明是否影响当天在岗状态 |
| 加班 |
加班日期、加班开始/结束、加班原因、补偿口径 |
补偿口径首批仅记录：无补偿、调休、加班费待定 |
| 出差预留 |
出差地点、开始/结束、交通住宿 |
首批只保留后续扩展，不作为完整差旅验收 |
5. 审批规则与状态
5.1 审批规则
WFOC 后，正常审批规则优先以企业微信审批模板和打卡/假期配置为准；OA 中以下规则保留为应急接管建议值，不等于最终公司制度。正式制度可由管理员配置调整，并通过 wecom_ruleops_v1 先 dry-run、人工确认后写入企微。
| 类型 |
阈值 |
默认审批链 |
HR/管理员复核 |
兜底审批人 |
| 请假 |
<=1 天 |
直属主管 |
无 |
HR/管理员 |
| 请假 |
>1 天 |
直属主管 |
HR/管理员复核 |
老板/总经理 |
| 补卡 |
所有 |
直属主管 |
HR/管理员复核 |
HR/管理员 |
| 外出 |
所有 |
直属主管 |
HR/管理员按需复核 |
HR/管理员 |
| 加班 |
所有 |
直属主管 |
HR/管理员复核 |
HR/管理员 |
若找不到审批人，提交必须阻断，不生成半截流程。审批规则与通用状态转换以统一审批中心规约为准。
5.2 状态模型
| 状态 |
含义 |
允许动作 |
| 草稿 |
申请人编辑中 |
编辑、提交、删除 |
| 审批中 |
已提交，等待审批 |
审批人通过、驳回、退回、转审；申请人按规则撤回 |
| 已通过 |
审批完成 |
生效到团队状态、日历或考勤解释 |
| 已驳回 |
审批否决 |
查看原因、复制重提或新建 |
| 已退回 |
需要申请人修改 |
修改后重提、撤回 |
| 已撤回 |
申请人撤回 |
查看历史、复制重提 |
| 已生效 |
已影响团队状态或考勤口径 |
查看、审计 |
| 已取消 |
已批准后由授权人员取消影响 |
必须填写原因并审计 |
已通过不等于一定已生效；若团队状态或日历更新失败，审批记录仍保持已通过，生效失败应进入可重试或管理员处理状态。
6. 考勤口径
6.1 基本原则
- 企业微信打卡记录、打卡规则和 HR/考勤审批是正常情况下的原始业务事实。
- OA 镜像记录、历史 OA 单据和应急单据是审计、查询、接管和恢复对账事实。
- 最终正式考勤口径应由企业微信打卡原始记录、企微审批结果、OA 应急单和恢复回写结果共同形成。
- 企业微信打卡异常不直接等于最终考勤异常。
- OA 首批不重造定位、人脸识别、Wi-Fi、排班和防作弊规则。
6.2 口径示例
| 场景 |
原始打卡 |
OA 审批 |
正式解释 |
| 已批准请假 |
无打卡或不完整 |
企微请假已通过，OA 已同步镜像 |
按请假处理，不直接记异常 |
| 忘打卡 |
缺少上班或下班卡 |
企微补卡已通过，OA 已同步镜像 |
按补卡修正解释 |
| 客户现场 |
打卡地点异常或无办公室打卡 |
企微外出已通过，OA 已同步镜像 |
按外出处理 |
| 晚间工作 |
正常下班后继续工作 |
企微加班已通过，OA 已同步镜像 |
记录加班事实，补偿另按制度处理 |
| 企微故障应急 |
无法提交企微审批 |
OA EMERGENCY 应急单已通过，恢复后已回写或待对账 |
按 OA 应急单和回写结果解释 |
| 无审批异常 |
缺卡或迟到 |
无有效 OA 审批 |
保持异常待处理或人工复核 |
7. 团队状态与日历
- 已批准请假应影响对应日期的团队状态，展示为
请假。
- 已批准外出应在对应时段展示为
外出，必要时显示项目或客户摘要。
- 已批准加班可进入团队日历或个人记录，首批不强制进入工资计算。
- 补卡审批通过后影响考勤解释，不一定展示在团队状态中。
- 团队状态和日历更新失败不得回滚审批结果，应记录失败原因并允许重试。
- 普通员工只能查看自己和授权范围内的团队状态；HR/管理员和老板按权限查看更大范围。
8. 异常规则
| 异常 |
处理规则 |
用户提示 |
| 时间不合法 |
结束时间早于开始时间、跨区间异常时阻断 |
“请检查开始和结束时间” |
| 时长为 0 |
阻断提交 |
“申请时长必须大于 0” |
| 重复申请 |
同一时间段已有有效申请时提示或阻断 |
“该时间段已有申请，请确认” |
| 无审批人 |
阻断提交，不生成半截流程 |
“当前审批规则未找到审批人，请联系管理员” |
| 权限不足 |
服务端拒绝 |
“无权处理该申请” |
| 团队状态更新失败 |
审批保持成功，生效状态进入失败可重试 |
“申请已审批通过，状态同步稍后重试” |
| 已生效后取消 |
仅授权 HR/管理员处理，必须填写原因 |
“已生效申请取消需管理员处理” |
| 企业微信打卡或审批未同步 |
不影响企微已完成事实；OA 镜像进入可重试或待配置状态 |
“企业微信数据暂未同步，稍后重试或联系管理员” |
9. 验收场景
| 场景 |
步骤 |
预期结果 |
| 企微请假镜像 |
员工在企业微信提交 0.5 天请假；主管通过；OA 同步 |
OA 可查看审批详情、历史、附件和团队状态影响 |
| 企微补卡镜像 |
员工在企业微信提交缺失下班卡补卡；主管或 HR 通过；OA 同步 |
补卡记录影响考勤解释 |
| 企微外出镜像 |
员工在企业微信提交客户现场外出；主管通过；OA 同步 |
团队状态显示外出或相关摘要 |
| 企微加班镜像 |
员工在企业微信提交晚间加班；主管或 HR 通过；OA 同步 |
加班记录留痕，补偿口径被记录 |
| OA 应急提交 |
管理员开启 oa_hr_emergency_mode_v1 后员工在 OA 提交 HR/考勤应急单 |
单据带 EMERGENCY 标记并进入恢复回写队列 |
| 恢复回写 |
企业微信恢复后，OA 对应急单 dry-run 并回写 |
成功、失败、冲突和人工确认项均可追溯 |
| 退回修改 |
企微审批或 OA 应急审批退回后，员工按对应入口修改重提 |
保留退回历史，重新进入审批 |
| 撤回 |
员工在审批完成前撤回 |
审批待办失效，历史保留 |
| 无审批人阻断 |
企业微信模板或 OA 应急规则找不到审批人 |
提交失败，不生成半截流程 |
| OA 主办提醒回 OA |
报销、采购、合同或财务待办产生后发送企业微信提醒 |
点击 deeplink 回 OA 审批页处理 |
| 团队状态失败不破坏审批 |
模拟团队状态更新失败 |
审批保持已通过，生效状态可重试 |
10. 后续开发拆分建议
- 已完成：OA 侧补卡/外出/加班申请对象、统一审批接入、月度考勤解释页、移动入口和企业微信 deeplink 回 OA；WFOC 后这些能力默认作为历史查询和应急接管基础。
- WAPI/WRRA/WOUA-FIX 后：后续开发先读 企微优先开发路线图 和 企微 API 能力目录，阶段未退出前不得跳阶段；WOUA-FIX 已完成测试账号差异收口，但
PASS_WITH_FINDINGS 剩余缺字段/归档绑定不能直接放行深度镜像。
- 当前 A0：
WECOM-RUNTIME-READY-V1，用 npm run check:wecom-runtime-ready 先完成工作台入口、OAuth/绑定、脱敏消息、OA deeplink、通讯录 userid 清单、人事助手读取和打卡读取门禁；审批模板、测试 sp_no 和真实回调只记 NEEDS_CONFIG，继续阻断 A1。
- 后续 A1：
wecom_attendance_approval_mirror_v1，同步企微请假、补卡、外出、加班审批、附件、历史和状态回调；该命名承接旧口径 wecom_native_approval_mirror_v1。正式开发前必须补齐审批模板 ID、测试 sp_no、真实回调配置、回调验签/解密/幂等和必要打卡细项 POC。
- 后续 A2：企微打卡规则、排班、记录、日报、月报按域镜像，覆盖 Secret/API 权限、短窗口同步、错误码和脱敏证据。
- 后续 A3：
oa_hr_emergency_mode_v1，管理员人工接管、应急提交、应急审批和恢复队列。
- 后续 A4：
wecom_recovery_writeback_v1，企微恢复后 dry-run、自动回写、失败重试和冲突清单。
- 后续 A5：团队状态和日历按企微镜像、OA 应急单和回写结果统一解释。
- 后续 A6：出差完整流程专项，不进入当前正式首批能力。
涉及审批状态、团队状态、生效记录或后续打卡同步的 Issue，必须写明失败重试、回滚策略和人工修正路径。
