文件
hyb-oa/docs/需求-请假考勤修正规约.md
T

24 KiB
原始文件 Blame 文件历史

需求 - 请假考勤修正规约

版本:1.0 日期:2026-05-09 状态:模块级开发规约 上级事实源:海音达OA-MVP需求规格说明书 相关事实源:需求 - 统一审批中心规约、需求 - 企业微信基础设施规约 体验事实依据:产品体验事实源;视觉与交互裁决以 frontend-design 为准。

本规约细化请假、补卡、外出、加班与考勤修正的产品要求。WFOC 起,企业微信作为 HR/考勤员工日常审批和打卡规则主操作端;OA 负责按域镜像、应急接管、恢复回写、查询导出和审计。WEGOV1 后进一步明确:企微成熟 HR/考勤功能优先上线,OA 不重造企业微信完整打卡/考勤/HR 产品,但必须做自建历史留存、审计、入口、消息和应急兜底。WAPC2 后,请假和补卡先通过 QA-only runner 只读验证模板详情与低风险 sp_no 审批详情;WAPC2FLIVE 已生成 OA-POC 样件并复跑通过;WCBK1 已完成真实回调 URL 验证和一条测试审批事件确认;WACP3R 已自动发现模板并证明补偿拉取和详情读取可用。WREAD1F 后,用户真机确认请假/补卡在企业微信消息卡片、列表和详情页均可看清,远端报告 /app/artifacts/qa-flow/wecom-approval-readability-gate-20260519T133628Z/summary.json 为 PASS_READABLE;驳回有二次确认,同意单击即通过。WARCH1 已实现请假/补卡最小审批历史留存、回调事件入库、补偿拉取入库和离线读取证明;WARCH2 已提供正式只读历史查询。WROAD2 后进入测试账号受控上线;WARCH3 已新增 07:30 systemd 自动巡检和脱敏企微告警;WCHECK1 已新增打卡规范化明细、日/月摘要和规则快照留存;WEXT1 已支持外出/加班 dry-run,但未 live 创建模板或审批单。WOPS1 后告警默认发给 HYD000006(wangshunli 的员工号)且只报新增异常;WROAD2-BIZ1 在三天内补充测试账号打卡、请假、补卡和 OA 离线查看人工业务冒烟;WAPPR1 把“申请人不得任意选择审批人、必须自动带出审批人、禁止自审”列为真实试用前门禁。WROAD2-CLOSEOUT/WROAD2-BIZ1/WAPPR1/WRULE1/WTCLOSE2/WREMOTE1 完成前不启用真实员工;外出/加班下一步改为 WEXT1-FORMAL 正式模板人工提交 + 系统只读校验,不再自动创建 OA-POC 外出/加班模板;四类测试号证据与审批规则门禁通过后才问真实小范围试用。当前仍不代表完整审批镜像、外出/加班正式模板证据、应急接管或恢复回写已实现。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/考勤审批镜像 CONTROLLED_OPS_READY WAPC2 已新增请假/补卡模板详情和低风险 sp_no 审批详情只读 POC;WAPC2FLIVE 已完成自动样件与 WAPC2 自动复跑;WCBK1 已完成真实回调 URL 验证和一条测试审批事件确认;WACP3R 已证明请假/补卡补偿拉取和详情读取可用;WREAD1F 已完成请假/补卡模板级真机确认,结论 PASS_READABLE。WARCH1 已实现请假/补卡最小历史留存和离线读取,WARCH2 已实现正式只读历史查询。WROAD2+OPS 做测试账号巡检,WARCH3 已升级自动巡检,WCHECK1 已补打卡摘要留存,WEXT1 只完成外出/加班 dry-run,WOPS1 修正告警降噪和管理员员工号;后续 wecom_attendance_approval_mirror_v1 仍需 WROAD2-CLOSEOUT、WROAD2-BIZ1、WAPPR1、WRULE1、WTCLOSE2/WREMOTE1、WEXT1-FORMAL、四类测试号证据、WREAL1 小范围真实试用或明确批准。
员工补卡申请审批 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 已由 WRV1/WRA1/WMSG1 验证工作台入口、OAuth/绑定、脱敏消息、OA deeplink、通讯录 userid 清单、人事助手读取、打卡读取和真实消息回流;审批模板、测试 sp_no 和真实回调仍只记 NEEDS_CONFIG,继续阻断 A1。
  • 当前 A0.5:WAPC1 审批配置准备,先准备请假、补卡、外出、加班模板 ID、适用范围、字段项、审批人规则、可见范围、低风险测试 sp_no 和真实回调配置项;本阶段不接真实回调、不调用写接口、不进入镜像。
  • 当前 A0.6:WAPC2 请假/补卡只读 POC 已实现 runner;缺模板 ID 或低风险 sp_no 时保持 PARTIAL_APPROVAL_POC_NEEDS_CONFIG。
  • 已完成 A0.7/A0.8/A0.9:WAPC2F、WAPC2FLIVE、WAPC2 自动复跑 和 WCBK1 回调只读 POC 已证明请假/补卡 OA-POC 样件、只读审批详情、真实回调 URL、验签/解密和一条真实事件脱敏留证。
  • 当前 A0.10:WEGOV1 企微主办治理与自建留存路线修正,固定企微主办域、OA 主办域、OA 留存域、OA 应急域、受控测试域和自动化/人工边界。
  • 已完成 A0.11:WACP3/WACP3R 补偿拉取 POC,已证明按时间窗口获取审批单号并用 getapprovaldetail 拉详情;当时 finding 是 WCBK1 回调证据文件未持久化,已由 WADM1 设计和 WARCH1 最小留存入库路径承接。
  • 已完成 A0.12:WREAD1 审批可读性与误审批防护门禁,已新增只读 runner 并在 WREAD1F 新样例后完成人工真机确认;请假、补卡在企业微信消息、列表和详情页中均可看清,远端报告为 PASS_READABLE。风险记录:驳回有二次确认,同意单击即通过;外出/加班仍需后续样例或处理决策。
  • 已完成 A0.13:WADM1 自建留存/镜像数据模型设计,已固定请假/补卡审批留存主表、参与人/动作/字段摘要、回调事件、补偿拉取 run/item、对账 finding、隐私保留、迁移回滚,以及同意单击风险对应的审计和提示策略。
  • 已完成 A0.14:WARCH1 最小自建历史留存实现,已保存请假/补卡企微审批历史、回调事件、补偿拉取记录和对账 finding,并新增离线读取 runner。打卡和人事快照先复用既有表,后续按缺口扩展。
  • 已完成 A0.15:WARCH2 正式只读历史查询,已新增请假/补卡企微审批历史查询 API 和 PC/移动历史页。本阶段只读 OA DB,不调用企微 API;普通员工看本人相关,主管看直属下属和本人相关,HR/admin/* 看全量;页面固定“企业微信主办,OA 自建留存”“仅已归档记录”,不提供审批动作。公网已部署并通过 /ready、未登录 401 和远端离线归档复跑。
  • 已完成 A0.16:WROAD2+OPS 受控上线与每日巡检,先用测试账号 SMOKE002 -> SMOKE101 + wangshunli 做 3 天每日脚本化巡检。巡检只允许补偿归档写 OA 留存库,不写企业微信、不创建模板或审批单。
  • 已完成 A0.17:WARCH3 归档稳定化自动巡检,新增每日补偿、归档对账 finding、历史查询可用性、旧 callback gap 解释、报告趋势、07:30 systemd timer 和脱敏企微告警。
  • 已完成 A0.18:WCHECK1 打卡摘要留存,保存规范化打卡明细、日/月摘要、异常摘要和规则快照;不保存完整位置、人脸、设备明文或原始 payload。
  • 已完成 A0.19:WEXT1 外出/加班 dry-run,支持外出/加班低风险 POC payload 构建;live 创建模板或审批单前必须再次问答批准。
  • 后续 A0.20:WROAD2-BIZ1 三天业务冒烟,在测试账号范围补充真实业务动作:SMOKE002 每天按企微规则尝试上/下班打卡并提交低风险请假/补卡,SMOKE101 先打开详情再审批,HYD000006 每天查看 OA 企微审批归档和打卡摘要;无法打卡、无法审批或需要手选审批人时记录 finding。
  • 后续 A0.21:WAPPR1 审批规则规范化门禁,请假、补卡、外出、加班正式模板必须按直属主管、部门负责人或指定审批角色自动带出审批人;申请人不得任意选择审批人;审批人缺失、停用、未绑定、不可见或自审时阻断,未通过模板不得进入真实试用。
  • 后续 A0.22:WTCLOSE2/WREMOTE1/WFULLSMOKE2 远端收口,仅在 WAPPR1=A、WRULE1 可解释通过后,从部署服务器可信 IP 复跑测试号收口和全域 smoke;本地只做静态门禁,不作为企微业务证据。
  • 后续 A0.23:WEXT1-FORMAL 正式模板外出/加班测试,仅在远端收口可解释通过后再次问答确认;由 SMOKE002 在现有正式模板提交低风险外出/加班测试单,SMOKE101 先看详情再审批,系统只读补偿、归档和审批链校验;不自动创建 OA-POC 外出/加班模板或审批单。
  • 后续 A0.24:WREAL1 小范围真实试用,仅在请假、补卡、外出、加班四类测试号证据和 WAPPR1/WRULE1 审批规则门禁通过后启动,首批固定为 1 名真实员工 + 1 名审批人/管理员观察,届时再确认试用周期、回滚联系人和验收标准。
  • 后续 A1:wecom_attendance_approval_mirror_v1 最小完整镜像,同步企微请假、补卡、外出、加班审批、附件摘要、历史、状态回调、打卡摘要、必要假期/人事快照;该命名承接旧口径 wecom_native_approval_mirror_v1。正式开发前仍必须完成 WREAL1 或获得明确批准,并保留打卡细项、假期余额和四类测试号证据边界;应急接管、恢复回写和 RuleOps 后置。
  • 后续 A2:oa_hr_emergency_mode_v1,管理员人工接管、应急提交、应急审批和恢复队列。
  • 后续 A3:wecom_recovery_writeback_v1,企微恢复后 dry-run、自动回写、失败重试和冲突清单。
  • 后续 A4:团队状态和日历按企微镜像、OA 应急单和回写结果统一解释。
  • 后续 A6:出差完整流程专项,不进入当前正式首批能力。

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