diff --git a/docs/文档索引.md b/docs/文档索引.md index 079cee2d..74974730 100644 --- a/docs/文档索引.md +++ b/docs/文档索引.md @@ -12,6 +12,8 @@ | [海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md) | 当前 PRD 主事实源,回答做什么、先做什么、不做什么、如何验收,并固定标准软件开发流程 | 后续需求变更先改这里或对应规则文档,再拆 Issue CSV | | [需求 - 统一审批中心规约](./需求-统一审批中心规约.md) | 统一审批中心模块级开发规约,包含审批规则矩阵、状态流转和权限数据范围 | 审批相关开发拆 Issue CSV 前必须参考 | | [需求 - 报销发票 OCR 规约](./需求-报销发票OCR规约.md) | 报销、发票、OCR、附件、付款和导出模块级开发规约,包含费用类型矩阵、人工复核和验收数据集 | 报销主链路开发拆 Issue CSV 前必须参考 | +| [需求 - 企业微信基础设施规约](./需求-企业微信基础设施规约.md) | 企业微信入口、免登/绑定、通讯录身份、消息通知、deeplink 和打卡采集边界规约 | 企业微信相关开发拆 Issue CSV 前必须参考 | +| [需求 - 请假考勤修正规约](./需求-请假考勤修正规约.md) | 请假、补卡、外出、加班与考勤修正模块级开发规约 | 考勤修正相关开发拆 Issue CSV 前必须参考 | | [产品口径文档](./product-decisions.md) | 已拍板的产品边界和业务规则 | 与 PRD 冲突时,以更新后的 PRD 和最新 Issue CSV 为准 | | [报销、发票与附件规则](./reimbursement-invoice-rules.md) | 报销、发票、OCR、附件的细则 | 报销相关开发必须同时参考 | | [产品设计规则基线](./product-design-rules.md) | PC、移动、企业微信 WebView 的视觉和交互规则 | 页面调整必须参考 | @@ -64,7 +66,7 @@ ## 阅读顺序 1. 要看“现在到底做什么”:读 [海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md)。 -2. 要细化审批或报销开发任务:读对应模块规约,再拆 `issues/*.csv`。 +2. 要细化审批、报销、企业微信或考勤修正开发任务:读对应模块规约,再拆 `issues/*.csv`。 3. 要开新开发任务:先读 PRD 第 2 章的软件开发项目流程,再更新需求或规则文档,并新建 `issues/*.csv`。 4. 要看“某个业务规则为什么这么定”:读 [产品口径文档](./product-decisions.md) 和对应规则文档。 5. 要判断功能是否已经做过:读 [实现状态矩阵](./feature-matrix.md) 和最新相关 Issue CSV。 diff --git a/docs/海音达OA-MVP需求规格说明书.md b/docs/海音达OA-MVP需求规格说明书.md index c3fcf553..ffc9ce45 100644 --- a/docs/海音达OA-MVP需求规格说明书.md +++ b/docs/海音达OA-MVP需求规格说明书.md @@ -14,6 +14,8 @@ - [报销与发票规则](./reimbursement-invoice-rules.md):报销、发票、OCR、附件的细则。 - [需求 - 统一审批中心规约](./需求-统一审批中心规约.md):审批中心模块级开发规约。 - [需求 - 报销发票 OCR 规约](./需求-报销发票OCR规约.md):报销、发票、OCR、附件模块级开发规约。 +- [需求 - 企业微信基础设施规约](./需求-企业微信基础设施规约.md):企业微信入口、免登、绑定、通知、deeplink 和打卡采集边界规约。 +- [需求 - 请假考勤修正规约](./需求-请假考勤修正规约.md):请假、补卡、外出、加班与考勤修正模块级开发规约。 - `issues/*.csv`:每轮开发执行合同;需求确认后必须拆 Issue CSV 再开发。 --- @@ -177,6 +179,8 @@ OA 是公司唯一正式审批中心。以下审批必须在 OA 内提交、审 ## 7. 请假、补卡、外出、加班与考勤口径 +本章保留总纲口径。请假、补卡、外出、加班的角色、字段、状态、审批规则、团队状态、日历和考勤解释细节,以 [需求 - 请假考勤修正规约](./需求-请假考勤修正规约.md) 作为后续开发拆分依据。 + ### 7.1 边界 - 企业微信打卡用于原始采集,保留其定位、人脸、Wi-Fi、排班和设备能力。 @@ -231,6 +235,8 @@ OA 是公司唯一正式审批中心。以下审批必须在 OA 内提交、审 ## 9. 企业微信基础设施需求 +本章保留总纲口径。企业微信入口、免登/绑定、通讯录身份、消息通知、deeplink 和打卡原始采集边界,以 [需求 - 企业微信基础设施规约](./需求-企业微信基础设施规约.md) 作为后续开发拆分依据。 + ### 9.1 自建应用 - 公司只维护一个企业微信自建应用,建议命名为 `海音达工作台`。 diff --git a/docs/需求-企业微信基础设施规约.md b/docs/需求-企业微信基础设施规约.md new file mode 100644 index 00000000..914f25b3 --- /dev/null +++ b/docs/需求-企业微信基础设施规约.md @@ -0,0 +1,188 @@ +# 需求 - 企业微信基础设施规约 + +**版本**:1.0 +**日期**:2026-05-09 +**状态**:模块级开发规约 +**上级事实源**:[海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md) +**相关事实源**:[需求 - 统一审批中心规约](./需求-统一审批中心规约.md) + +本规约细化企业微信在 `hyb-oa` 中的基础设施边界、入口、免登/绑定、通讯录身份、消息通知、deeplink 和打卡原始采集要求。后续企业微信相关开发必须先从本规约拆分 Issue CSV,再进入技术方案和代码实现。 + +--- + +## 1. 模块目标与边界 + +### 1.1 目标 + +- 企业微信作为 `hyb-oa` 的手机工作台入口、身份辅助、消息通知和打卡原始采集底座。 +- 员工在手机企业微信中进入唯一自建应用 `海音达工作台`,默认落到 OA 移动端。 +- 企业微信消息只做提醒和跳转,审批动作、业务填写、附件查看和正式留痕都在 OA 内完成。 +- 企业微信打卡只作为原始采集来源,后续结合 OA 请假、补卡、外出、加班审批形成正式考勤口径。 + +### 1.2 不做范围 + +- 不使用企业微信原生审批作为公司正式审批流。 +- 不把企业微信聊天、文件或审批记录作为财务附件主库、业务单据主库或正式审计事实源。 +- 首批不新增企业微信打卡 API 同步实现。 +- 首批不在 OA 内重造企业微信打卡的定位、人脸识别、Wi-Fi、排班、设备和防作弊规则。 +- 不接入飞书、钉钉或其他办公平台作为首批入口。 + +--- + +## 2. 角色与权限 + +| 角色 | 使用目标 | 可做动作 | 权限边界 | +| --- | --- | --- | --- | +| 员工 | 从手机进入 OA、接收提醒、完成绑定 | 进入移动工作台、绑定企业微信身份、点击消息 deeplink、查看本人相关业务 | 不能通过企业微信绕过 OA 权限 | +| 审批人 | 在手机端收到待办提醒并回 OA 处理 | 点击通知进入 OA 审批页、在 OA 内审批 | 不能在企业微信原生审批里完成正式审批 | +| 管理员/HR | 管理入口、人员、绑定异常和离职停用 | 配置可见范围、协助绑定、处理离职停用、查看通知失败 | 不得手工把一个企业微信身份绑定到多个员工 | +| 系统管理员 | 维护企业微信应用配置和消息通道 | 配置 CorpID、AgentID、回调、可信域名、消息开关和重试策略 | 不处理业务审批,不暴露 secret | +| 财务/老板 | 接收关键待办或状态提醒 | 点击 deeplink 回 OA 查看或处理 | 消息中不得出现完整发票、合同正文、敏感报价、银行卡、身份证 | + +企业微信身份只是登录和通知辅助。后端 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 通知边界 + +- 企业微信消息只发送脱敏提醒,不承载正式审批动作。 +- 消息内容只包含:标题、业务类型、业务编号、状态、处理入口。 +- 消息不得包含完整发票图片、合同正文、敏感报价、银行卡、身份证、大段业务说明或密钥。 +- 发送失败不阻断主业务提交、审批、付款或归档;失败记录进入可重试状态。 + +### 5.2 Deeplink 目标 + +| 业务场景 | Deeplink 目标 | 要求 | +| --- | --- | --- | +| 审批待办 | `/mobile/approvals` 或具体任务详情 | 点击后在 OA 内处理审批 | +| 报销提醒 | 移动报销详情或审批任务 | 展示脱敏摘要,附件和发票需按 OA 权限加载 | +| 请假/补卡/外出/加班 | 移动申请详情或审批任务 | 支持查看状态和处理待办 | +| 移动工作台 | `/mobile` | 作为兜底入口 | +| 绑定入口 | 个人设置或绑定页 | 仅在已账号密码登录后完成绑定 | + +deeplink 必须校验目标地址白名单,避免跳转到非 OA 域名或未授权页面。 + +### 5.3 通知验收 + +- 待办产生后,目标审批人能收到脱敏提醒。 +- 点击消息后进入 OA 对应移动页面,而不是企业微信原生审批。 +- 未登录或会话过期时,完成登录后应尽量回到原 deeplink 目标。 +- 通知失败时业务流程仍成功,管理员可查看失败原因和重试状态。 + +--- + +## 6. 通讯录身份边界 + +- 企业微信通讯录可作为员工姓名、部门、手机号、邮箱、在职状态的辅助来源。 +- OA 员工表仍是权限、审批、业务数据和审计的主事实源。 +- 首批不要求自动全量同步通讯录;可先支持管理员手工维护员工和绑定关系。 +- 后续若接通讯录同步,必须处理新增、改名、调岗、离职、手机号变更和部门变更,并保留同步日志。 + +--- + +## 7. 打卡原始采集边界 + +- 企业微信打卡用于原始采集,保留其定位、人脸识别、Wi-Fi、排班和设备能力。 +- OA 首批不重造打卡定位、人脸识别、Wi-Fi、排班、设备绑定、防作弊和异常判断引擎。 +- 首批不新增企业微信打卡 API 同步实现,只固定后续集成边界。 +- 后续同步后,OA 应把企业微信打卡原始记录与 OA 请假、补卡、外出、加班审批结果合并,形成正式考勤口径。 +- 企业微信打卡异常不直接等于最终考勤异常;最终解释必须结合 OA 审批记录。 + +--- + +## 8. 验收场景 + +| 场景 | 步骤 | 预期结果 | +| --- | --- | --- | +| 已绑定用户直达 | 员工从手机企业微信进入 `海音达工作台` | 直达 `/mobile` 或 deeplink 目标页 | +| 未绑定回退 | 未绑定员工从企业微信进入 | 提示未绑定,可使用账号密码登录后绑定 | +| 重复绑定阻断 | 管理员或员工尝试把同一企业微信身份绑定多个员工 | 操作失败并留下审计记录 | +| 离职停用拦截 | 已停用员工从企业微信入口进入 | 不能进入 OA 业务页面 | +| 审批通知回 OA | 审批待办产生后发送企业微信提醒 | 点击消息进入 OA 审批页,审批动作在 OA 完成 | +| 报销通知脱敏 | 报销状态变化发送提醒 | 消息只有标题、编号、状态和入口,不含完整发票或附件 | +| 通知失败不阻断 | 模拟企业微信消息发送失败 | 主业务成功,通知进入失败可重试 | +| 打卡边界确认 | 员工使用企业微信打卡,OA 查看考勤相关说明 | 文档和界面不暗示 OA 已重造定位、人脸或排班 | + +--- + +## 9. 后续开发拆分建议 + +- A1:企业微信配置探活和入口开关,覆盖启用、禁用、缺配置和 SKIP。 +- A2:企业微信 WebView 识别和 `/mobile` 默认入口。 +- A3:企业微信 OAuth/免登与账号绑定、解绑、重复绑定阻断。 +- A4:离职停用、组织权限和绑定异常拦截。 +- A5:企业微信通知 provider 和失败重试,不阻断主业务。 +- A6:deeplink 白名单和移动目标页回跳。 +- A7:通讯录辅助字段和后续同步边界。 +- A8:企业微信打卡原始采集同步 backlog,不进入首批实现。 +- A9:企业微信真机 smoke 清单,覆盖工作台入口、绑定、通知和回跳。 + +涉及真实企业微信凭据、回调域名、可信域名、生产配置或真机验证的 Issue,必须在技术方案中写明配置项、回滚路径和无法自动化时的人工验收步骤。 diff --git a/docs/需求-请假考勤修正规约.md b/docs/需求-请假考勤修正规约.md new file mode 100644 index 00000000..74874674 --- /dev/null +++ b/docs/需求-请假考勤修正规约.md @@ -0,0 +1,208 @@ +# 需求 - 请假考勤修正规约 + +**版本**:1.0 +**日期**:2026-05-09 +**状态**:模块级开发规约 +**上级事实源**:[海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md) +**相关事实源**:[需求 - 统一审批中心规约](./需求-统一审批中心规约.md)、[需求 - 企业微信基础设施规约](./需求-企业微信基础设施规约.md) + +本规约细化请假、补卡、外出、加班与考勤修正的产品要求。正式审批记录以 OA 为准;企业微信打卡只作为原始采集来源,不直接决定最终考勤结论。 + +--- + +## 1. 模块目标与边界 + +### 1.1 目标 + +- 员工能在 OA PC 或移动端提交请假、补卡、外出、加班申请。 +- 主管、HR/管理员在 OA 内审批并留痕。 +- 已通过的考勤修正影响团队状态、日历展示和后续正式考勤口径。 +- 企业微信打卡原始记录后续可同步到 OA,但必须结合 OA 审批结果解释。 + +### 1.2 适用对象 + +- 请假:年假、事假、病假、调休、其他假别。 +- 补卡:漏打卡、忘打卡、设备异常、外勤导致未打卡等修正。 +- 外出:工作时间内外勤、客户拜访、项目现场、临时外出。 +- 加班:工作日加班、周末加班、节假日加班。 +- 出差:首批只保留后续扩展边界,不在本规约内做完整差旅单。 + +### 1.3 不做范围 + +- 不使用企业微信原生审批处理请假、补卡、外出、加班。 +- 首批不重造企业微信打卡的定位、人脸识别、Wi-Fi、排班和防作弊规则。 +- 首批不新增企业微信打卡 API 同步实现。 +- 首批不做复杂假期余额、调休余额、薪资计算、排班引擎和法定节假日自动规则。 +- 不把企业微信打卡异常直接作为 OA 最终考勤结论。 + +--- + +## 2. 角色与权限 + +| 角色 | 可做动作 | 权限边界 | +| --- | --- | --- | +| 申请人 | 新建草稿、提交、撤回、查看自己的申请、按退回意见修改重提 | 只能编辑本人草稿、已退回或允许重提的申请 | +| 主管/审批人 | 查看分配给自己的待办,通过、驳回、退回、转审 | 只能处理当前分配给自己的 OA 审批任务 | +| HR/管理员 | 复核请假、补卡、外出、加班,维护基础假别和考勤口径 | 不能绕过流程直接改审批结果;必要修正必须审计 | +| 老板/总经理 | 处理长假、高风险或特殊事项 | 操作仍需写入审批历史和审计日志 | +| 系统管理员 | 维护权限、通知、入口、基础配置 | 默认不具备业务审批权 | + +审批动作、转审、撤回、退回、驳回和历史留痕以 [需求 - 统一审批中心规约](./需求-统一审批中心规约.md) 为总依据。 + +--- + +## 3. 入口与对象 + +| 入口 | 场景 | 要求 | +| --- | --- | --- | +| PC 请假/考勤修正页 | 批量查看、较复杂申请、管理员复核 | 可查看完整字段、审批历史和团队影响 | +| 移动工作台 | 员工日常提交请假、补卡、外出、加班 | 操作路径短,适合手机填写 | +| 移动审批 | 主管或 HR 处理待办 | 进入 OA 审批页处理,不进入企业微信原生审批 | +| 团队状态页 | 查看今天谁在岗、请假、外出、出差 | 使用已批准申请影响展示 | +| 日历视图 | 查看请假和外出安排 | 首批可轻量展示,不做复杂排班 | +| 企业微信 deeplink | 通知提醒和跳转 | 点击后回 OA 页面 | + +--- + +## 4. 申请字段 + +### 4.1 通用字段 + +| 字段 | 含义 | 要求 | +| --- | --- | --- | +| 申请编号 | OA 生成的唯一编号 | 提交前或首次保存时生成,必须唯一 | +| 申请类型 | 请假、补卡、外出、加班 | 必填 | +| 申请人 | 发起人 | 必填 | +| 部门 | 申请人所属部门 | 系统带出 | +| 开始时间 | 申请开始时间 | 请假、外出、加班必填 | +| 结束时间 | 申请结束时间 | 请假、外出、加班必填 | +| 时长 | 小时或天 | 系统计算,允许按业务规则人工修正并留痕 | +| 原因 | 申请说明 | 必填 | +| 附件 | 病假证明、外出证明、加班依据等 | 按类型和规则决定 | +| 关联项目/客户 | 项目现场、客户拜访、项目加班等 | 外出、加班、项目相关请假建议填写 | +| 审批状态 | 草稿、审批中、已通过等 | 系统维护 | +| 生效状态 | 是否已影响团队状态或考勤口径 | 系统维护 | + +### 4.2 类型专属字段 + +| 类型 | 专属字段 | 要求 | +| --- | --- | --- | +| 请假 | 假别、请假时段、是否半天、是否需证明 | 病假或特殊假别可要求附件 | +| 补卡 | 补卡日期、补卡时间点、上班/下班卡、异常原因 | 必须指向具体缺失或异常打卡时间点 | +| 外出 | 外出地点、外出事由、客户/项目、预计返回时间 | 应说明是否影响当天在岗状态 | +| 加班 | 加班日期、加班开始/结束、加班原因、补偿口径 | 补偿口径首批仅记录:无补偿、调休、加班费待定 | +| 出差预留 | 出差地点、开始/结束、交通住宿 | 首批只保留后续扩展,不作为完整差旅验收 | + +--- + +## 5. 审批规则与状态 + +### 5.1 审批规则 + +以下是 10 人以下公司试运行建议值,不等于最终公司制度。正式制度可由管理员配置调整。 + +| 类型 | 阈值 | 默认审批链 | HR/管理员复核 | 兜底审批人 | +| --- | --- | --- | --- | --- | +| 请假 | `<=1` 天 | 直属主管 | 无 | HR/管理员 | +| 请假 | `>1` 天 | 直属主管 | HR/管理员复核 | 老板/总经理 | +| 补卡 | 所有 | 直属主管 | HR/管理员复核 | HR/管理员 | +| 外出 | 所有 | 直属主管 | HR/管理员按需复核 | HR/管理员 | +| 加班 | 所有 | 直属主管 | HR/管理员复核 | HR/管理员 | + +若找不到审批人,提交必须阻断,不生成半截流程。审批规则与通用状态转换以统一审批中心规约为准。 + +### 5.2 状态模型 + +| 状态 | 含义 | 允许动作 | +| --- | --- | --- | +| 草稿 | 申请人编辑中 | 编辑、提交、删除 | +| 审批中 | 已提交,等待审批 | 审批人通过、驳回、退回、转审;申请人按规则撤回 | +| 已通过 | 审批完成 | 生效到团队状态、日历或考勤解释 | +| 已驳回 | 审批否决 | 查看原因、复制重提或新建 | +| 已退回 | 需要申请人修改 | 修改后重提、撤回 | +| 已撤回 | 申请人撤回 | 查看历史、复制重提 | +| 已生效 | 已影响团队状态或考勤口径 | 查看、审计 | +| 已取消 | 已批准后由授权人员取消影响 | 必须填写原因并审计 | + +已通过不等于一定已生效;若团队状态或日历更新失败,审批记录仍保持已通过,生效失败应进入可重试或管理员处理状态。 + +--- + +## 6. 考勤口径 + +### 6.1 基本原则 + +- 企业微信打卡记录是原始采集事实。 +- OA 请假、补卡、外出、加班审批是考勤解释事实。 +- 最终正式考勤口径应由企业微信打卡原始记录加 OA 审批结果共同形成。 +- 企业微信打卡异常不直接等于最终考勤异常。 +- OA 首批不重造定位、人脸识别、Wi-Fi、排班和防作弊规则。 + +### 6.2 口径示例 + +| 场景 | 原始打卡 | OA 审批 | 正式解释 | +| --- | --- | --- | --- | +| 已批准请假 | 无打卡或不完整 | 请假已通过 | 按请假处理,不直接记异常 | +| 忘打卡 | 缺少上班或下班卡 | 补卡已通过 | 按补卡修正解释 | +| 客户现场 | 打卡地点异常或无办公室打卡 | 外出已通过 | 按外出处理 | +| 晚间工作 | 正常下班后继续工作 | 加班已通过 | 记录加班事实,补偿另按制度处理 | +| 无审批异常 | 缺卡或迟到 | 无有效 OA 审批 | 保持异常待处理或人工复核 | + +--- + +## 7. 团队状态与日历 + +- 已批准请假应影响对应日期的团队状态,展示为 `请假`。 +- 已批准外出应在对应时段展示为 `外出`,必要时显示项目或客户摘要。 +- 已批准加班可进入团队日历或个人记录,首批不强制进入工资计算。 +- 补卡审批通过后影响考勤解释,不一定展示在团队状态中。 +- 团队状态和日历更新失败不得回滚审批结果,应记录失败原因并允许重试。 +- 普通员工只能查看自己和授权范围内的团队状态;HR/管理员和老板按权限查看更大范围。 + +--- + +## 8. 异常规则 + +| 异常 | 处理规则 | 用户提示 | +| --- | --- | --- | +| 时间不合法 | 结束时间早于开始时间、跨区间异常时阻断 | “请检查开始和结束时间” | +| 时长为 0 | 阻断提交 | “申请时长必须大于 0” | +| 重复申请 | 同一时间段已有有效申请时提示或阻断 | “该时间段已有申请,请确认” | +| 无审批人 | 阻断提交,不生成半截流程 | “当前审批规则未找到审批人,请联系管理员” | +| 权限不足 | 服务端拒绝 | “无权处理该申请” | +| 团队状态更新失败 | 审批保持成功,生效状态进入失败可重试 | “申请已审批通过,状态同步稍后重试” | +| 已生效后取消 | 仅授权 HR/管理员处理,必须填写原因 | “已生效申请取消需管理员处理” | +| 企业微信打卡未同步 | 不影响 OA 申请审批 | “打卡原始记录暂未同步,审批结果已在 OA 留痕” | + +--- + +## 9. 验收场景 + +| 场景 | 步骤 | 预期结果 | +| --- | --- | --- | +| 请假主管审批 | 员工提交 `0.5` 天请假;主管通过 | 申请已通过,并影响团队状态 | +| 长假 HR 复核 | 员工提交 `2` 天请假;主管通过;HR 复核 | 审批链完整,HR 复核后生效 | +| 补卡审批 | 员工提交缺失下班卡补卡;主管和 HR 通过 | 补卡记录影响考勤解释 | +| 外出审批 | 员工提交客户现场外出;主管通过 | 团队状态显示外出或相关摘要 | +| 加班审批 | 员工提交晚间加班;主管和 HR 通过 | 加班记录留痕,补偿口径被记录 | +| 退回修改 | 审批人退回申请;员工修改后重提 | 保留退回历史,重新进入审批 | +| 撤回 | 员工在审批完成前撤回 | 审批待办失效,历史保留 | +| 无审批人阻断 | 删除或缺失主管后提交 | 提交失败,不生成半截流程 | +| 企业微信提醒回 OA | 待办产生后发送企业微信提醒 | 点击 deeplink 回 OA 审批页处理 | +| 团队状态失败不破坏审批 | 模拟团队状态更新失败 | 审批保持已通过,生效状态可重试 | + +--- + +## 10. 后续开发拆分建议 + +- A1:请假/补卡/外出/加班申请对象和字段收口。 +- A2:请假、补卡、外出、加班接入统一审批中心。 +- A3:审批规则配置,覆盖请假天数、补卡、外出、加班和兜底审批人。 +- A4:团队状态和日历生效逻辑,覆盖成功、失败重试和权限展示。 +- A5:考勤口径解释,预留企业微信打卡原始记录同步后的合并逻辑。 +- A6:企业微信通知 deeplink 回 OA,覆盖申请详情和审批待办。 +- A7:移动端提交与审批体验,覆盖普通手机和企业微信 WebView。 +- A8:请假考勤主链路回归脚本和人工验收数据集。 +- A9:出差完整流程后续专项,不进入本轮首批。 + +涉及审批状态、团队状态、生效记录或后续打卡同步的 Issue,必须写明失败重试、回滚策略和人工修正路径。 diff --git a/issues/2026-05-09_18-40-52-remaining-p0-requirements-detail.csv b/issues/2026-05-09_18-40-52-remaining-p0-requirements-detail.csv new file mode 100644 index 00000000..6c86bfd5 --- /dev/null +++ b/issues/2026-05-09_18-40-52-remaining-p0-requirements-detail.csv @@ -0,0 +1,6 @@ +ID,Title,Description,Acceptance,Test_Method,Tools,Dev_Status,Review1_Status,Regression_Status,Files,Dependencies,Notes +A1,剩余P0需求细化执行合同,"建立企业微信基础设施与请假考勤修正需求细化执行合同,并确认本轮只做文档不改业务代码。","1) 新 Issue CSV 校验通过;2) 范围固定为企业微信基础设施与请假/补卡/外出/加班考勤修正;3) 主 PRD 保持总纲,模块规约作为开发拆分依据;4) 不部署、不修改 server/client 业务代码。","命令:python3 /home/shunli/.codex/skills/plan/scripts/validate_issues_csv.py issues/2026-05-09_18-40-52-remaining-p0-requirements-detail.csv;人工步骤:确认 git status 仅包含 docs 与本 Issue CSV。",python3,DONE,DONE,DONE,issues/2026-05-09_18-40-52-remaining-p0-requirements-detail.csv,"[]","本轮为剩余 P0 需求细化,不改运行时。" +A2,企业微信基础设施模块规约,"新增企业微信基础设施模块级中文规约,细化入口、免登绑定、通讯录身份、消息通知、deeplink 和打卡原始采集边界。","1) docs/需求-企业微信基础设施规约.md 存在;2) 明确企业微信只做基础设施,不做正式审批;3) 覆盖一个自建应用、入口规则、免登绑定、通知、deeplink、打卡边界、异常和验收;4) 明确不重造定位、人脸、Wi-Fi、排班。","人工步骤:阅读 docs/需求-企业微信基础设施规约.md,确认可直接指导入口、免登、绑定、消息通知、deeplink 和打卡采集边界拆 Issue。",manual,DONE,DONE,DONE,docs/需求-企业微信基础设施规约.md,"[""A1""]","不实现企业微信接口,只固化需求规约。" +A3,请假考勤修正模块规约,"新增请假/补卡/外出/加班与考勤修正模块级中文规约,细化角色、字段、状态、审批规则、团队状态、日历和考勤口径。","1) docs/需求-请假考勤修正规约.md 存在;2) 覆盖请假、补卡、外出、加班,出差仅保留后续扩展;3) 覆盖角色、入口、字段、状态、权限、异常、验收;4) 明确企业微信打卡原始记录不是最终考勤结论。","人工步骤:阅读 docs/需求-请假考勤修正规约.md,确认可直接指导请假、补卡、外出、加班、团队状态、日历和考勤口径拆 Issue。",manual,DONE,DONE,DONE,docs/需求-请假考勤修正规约.md,"[""A1"",""A2""]","审批动作与状态机仍以 docs/需求-统一审批中心规约.md 为总依据。" +A4,主PRD与文档索引挂接,"更新主 PRD 和文档索引,将两份新增模块规约加入当前事实源和剩余 P0 开发依据。","1) 主 PRD 关联两份新增规约;2) docs/文档索引.md 将两份新增规约列入当前事实源;3) 保持统一审批中心规约作为审批动作和状态机总依据;4) 不新增其他专项文档。","命令:rg -n ""需求-企业微信基础设施规约|需求-请假考勤修正规约|海音达OA-MVP需求规格说明书|文档索引"" docs issues/2026-05-09_18-40-52-remaining-p0-requirements-detail.csv;人工检查链接可读。",ripgrep|manual,DONE,DONE,DONE,docs/海音达OA-MVP需求规格说明书.md|docs/文档索引.md,"[""A2"",""A3""]","主 PRD 保持总纲,只补开发依据链接。" +A5,验收场景开发拆分与文档校验,"在两份模块规约中补齐验收场景和后续开发拆分建议,并执行文档与路线口径校验。","1) 两份新增规约都有验收场景;2) 两份新增规约都有后续 Issue 拆分建议;3) 文档没有把企业微信原生审批、飞书或自研打卡定位/人脸识别纳入首批;4) A1-A5 状态回填 DONE。","命令:git diff --check;命令:rg -n ""企业微信原生审批|飞书|定位|人脸|打卡原始|正式考勤口径|deeplink|绑定"" docs/需求-企业微信基础设施规约.md docs/需求-请假考勤修正规约.md;人工判断命中内容与当前路线一致。",git|ripgrep|manual,DONE,DONE,DONE,docs/需求-企业微信基础设施规约.md|docs/需求-请假考勤修正规约.md|issues/2026-05-09_18-40-52-remaining-p0-requirements-detail.csv,"[""A2"",""A3"",""A4""]","完成后提交中文 commit,说明未部署。"