From 9e9b240e68ffa89739550fec573478348119ea33 Mon Sep 17 00:00:00 2001 From: shunli Date: Sat, 9 May 2026 16:23:31 +0800 Subject: [PATCH] =?UTF-8?q?A1-A5=20=E7=BB=86=E5=8C=96=E5=AE=A1=E6=89=B9?= =?UTF-8?q?=E4=B8=AD=E5=BF=83=E4=B8=8E=E6=8A=A5=E9=94=80OCR=E9=9C=80?= =?UTF-8?q?=E6=B1=82=E8=A7=84=E7=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/reimbursement-invoice-rules.md | 2 + docs/文档索引.md | 11 +- docs/海音达OA-MVP需求规格说明书.md | 6 + docs/需求-报销发票OCR规约.md | 276 ++++++++++++++++++ docs/需求-统一审批中心规约.md | 220 ++++++++++++++ ...oval-reimbursement-requirements-detail.csv | 6 + 6 files changed, 517 insertions(+), 4 deletions(-) create mode 100644 docs/需求-报销发票OCR规约.md create mode 100644 docs/需求-统一审批中心规约.md create mode 100644 issues/2026-05-09_16-15-23-approval-reimbursement-requirements-detail.csv diff --git a/docs/reimbursement-invoice-rules.md b/docs/reimbursement-invoice-rules.md index 07ef85d7..478b8f25 100644 --- a/docs/reimbursement-invoice-rules.md +++ b/docs/reimbursement-invoice-rules.md @@ -2,6 +2,8 @@ 本文是 hyb-oa 报销主链路的业务事实源,面向 10 人以下国内科技公司。目标是让员工少选项、财务少核错、管理员少配置。 +当前报销、发票、OCR、附件、付款和导出开发以 [需求 - 报销发票 OCR 规约](./需求-报销发票OCR规约.md) 为模块级开发规约;本文保留为报销细则来源。如两者有重复,以新规约整合后的口径为准。 + ## 总原则 - PC 与手机功能一致,只允许布局和控件形态不同。 diff --git a/docs/文档索引.md b/docs/文档索引.md index 5529221a..0af7203a 100644 --- a/docs/文档索引.md +++ b/docs/文档索引.md @@ -10,6 +10,8 @@ | 文档 | 用途 | 注意 | | --- | --- | --- | | [海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md) | 当前 PRD 主事实源,回答做什么、先做什么、不做什么、如何验收 | 后续需求变更先改这里或对应规则文档,再拆 Issue CSV | +| [需求 - 统一审批中心规约](./需求-统一审批中心规约.md) | 统一审批中心模块级开发规约 | 审批相关开发拆 Issue CSV 前必须参考 | +| [需求 - 报销发票 OCR 规约](./需求-报销发票OCR规约.md) | 报销、发票、OCR、附件、付款和导出模块级开发规约 | 报销主链路开发拆 Issue CSV 前必须参考 | | [产品口径文档](./product-decisions.md) | 已拍板的产品边界和业务规则 | 与 PRD 冲突时,以更新后的 PRD 和最新 Issue CSV 为准 | | [报销、发票与附件规则](./reimbursement-invoice-rules.md) | 报销、发票、OCR、附件的细则 | 报销相关开发必须同时参考 | | [产品设计规则基线](./product-design-rules.md) | PC、移动、企业微信 WebView 的视觉和交互规则 | 页面调整必须参考 | @@ -61,10 +63,11 @@ ## 阅读顺序 1. 要看“现在到底做什么”:读 [海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md)。 -2. 要看“某个业务规则为什么这么定”:读 [产品口径文档](./product-decisions.md) 和对应规则文档。 -3. 要开新开发任务:先更新需求或规则文档,再新建 `issues/*.csv`。 -4. 要判断功能是否已经做过:读 [实现状态矩阵](./feature-matrix.md) 和最新相关 Issue CSV。 -5. 要上线或真机验收:读 [试运行与自动化验证 Runbook](./trialrun-runbook.md)、live smoke 清单和最新部署结果。 +2. 要细化审批或报销开发任务:读对应模块规约,再拆 `issues/*.csv`。 +3. 要看“某个业务规则为什么这么定”:读 [产品口径文档](./product-decisions.md) 和对应规则文档。 +4. 要开新开发任务:先更新需求或规则文档,再新建 `issues/*.csv`。 +5. 要判断功能是否已经做过:读 [实现状态矩阵](./feature-matrix.md) 和最新相关 Issue CSV。 +6. 要上线或真机验收:读 [试运行与自动化验证 Runbook](./trialrun-runbook.md)、live smoke 清单和最新部署结果。 ## 明确废弃或不进入首批 diff --git a/docs/海音达OA-MVP需求规格说明书.md b/docs/海音达OA-MVP需求规格说明书.md index 6a2d28d9..18b51179 100644 --- a/docs/海音达OA-MVP需求规格说明书.md +++ b/docs/海音达OA-MVP需求规格说明书.md @@ -12,6 +12,8 @@ - [管理员手册](./admin-handbook.md):试运行配置、企业微信入口和上线操作。 - [员工快速开始](./employee-quickstart.md):员工侧使用说明。 - [报销与发票规则](./reimbursement-invoice-rules.md):报销、发票、OCR、附件的细则。 +- [需求 - 统一审批中心规约](./需求-统一审批中心规约.md):审批中心模块级开发规约。 +- [需求 - 报销发票 OCR 规约](./需求-报销发票OCR规约.md):报销、发票、OCR、附件模块级开发规约。 - `issues/*.csv`:每轮开发执行合同;需求确认后必须拆 Issue CSV 再开发。 --- @@ -85,6 +87,8 @@ ## 5. 统一审批中心需求 +本章保留总纲口径。审批中心的角色、入口、状态、动作、权限、异常、留痕和验收细节,以 [需求 - 统一审批中心规约](./需求-统一审批中心规约.md) 作为后续开发拆分依据。 + ### 5.1 范围 OA 是公司唯一正式审批中心。以下审批必须在 OA 内提交、审批、留痕、归档: @@ -122,6 +126,8 @@ OA 是公司唯一正式审批中心。以下审批必须在 OA 内提交、审 ## 6. 报销、发票、OCR、附件与财务导出 +本章保留总纲口径。报销、发票、OCR、附件、查重、财务复核、付款和导出的细化要求,以 [需求 - 报销发票 OCR 规约](./需求-报销发票OCR规约.md) 作为后续开发拆分依据;历史细则继续参考 [报销与发票规则](./reimbursement-invoice-rules.md)。 + ### 6.1 用户流程 1. 员工在 PC 或手机端创建报销草稿。 diff --git a/docs/需求-报销发票OCR规约.md b/docs/需求-报销发票OCR规约.md new file mode 100644 index 00000000..da8cc95c --- /dev/null +++ b/docs/需求-报销发票OCR规约.md @@ -0,0 +1,276 @@ +# 需求 - 报销发票 OCR 规约 + +**版本**:1.0 +**日期**:2026-05-09 +**状态**:模块级开发规约 +**上级事实源**:[海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md) +**细则来源**:[报销、发票与附件规则](./reimbursement-invoice-rules.md) + +本规约细化报销、发票、OCR、附件、查重、财务复核、付款和导出的产品要求。后续报销主链路开发必须先从本规约拆分 Issue CSV,再进入技术方案和代码实现。 + +--- + +## 1. 模块目标与边界 + +### 1.1 目标 + +- 员工能在 PC、手机和企业微信入口快速创建报销、上传发票和附件、提交审批。 +- 系统负责 OCR 识别、发票查重、发票与明细匹配、审批流接入和付款归档。 +- 财务能复核发票、处理重复例外、标记付款并导出财务台账。 +- 报销审批必须进入 OA 统一审批中心,正式记录以 OA 为准。 + +### 1.2 暂不做范围 + +- 不使用企业微信原生审批处理报销。 +- 不接入飞书报销、飞书审批或飞书文档归档。 +- 首批不做银行自动付款、企业卡自动对账、ERP 自动入账。 +- 首批不做复杂预算占用和多币种核算。 +- 首批不把企业微信文件作为发票或附件长期主库。 + +--- + +## 2. 角色与入口 + +### 2.1 角色 + +| 角色 | 可做动作 | 权限边界 | +| --- | --- | --- | +| 员工/申请人 | 创建草稿、上传发票、上传附件、编辑明细、提交审批、查看自己的报销状态 | 只能操作本人可见的报销单和本人上传或授权使用的发票 | +| 审批人 | 查看待办、查看发票和附件摘要、通过、驳回、退回、转审 | 只能处理分配给自己的 OA 审批任务 | +| 财务 | 查看审批通过的报销、复核发票、处理重复例外、标记付款、导出 | 不默认拥有系统管理权限;例外动作必须审计 | +| 财务主管 | 审核高风险或大额报销、审批重复例外、复核付款批次 | 权限应通过角色配置,不硬编码到个人 | +| 管理员 | 维护费用类型、项目、部门、OCR 配置、权限和基础字典 | 不能绕过流程直接替员工完成正式审批 | + +### 2.2 入口 + +| 入口 | 适用场景 | 要求 | +| --- | --- | --- | +| PC 报销列表/详情 | 明细编辑、批量查看、财务复核、导出 | 可查看完整字段、审批历史、发票和附件 | +| 手机报销页 | 拍照上传、继续草稿、补充附件、提交审批、查状态 | 不使用桌面宽表,操作路径短 | +| 企业微信自建应用 | 手机工作台入口和消息 deeplink | 默认进入 OA 移动端,审批动作仍在 OA 内完成 | +| 票据或发票添加弹窗 | 从报销草稿中添加发票 | 普通员工只看到“添加发票”,不暴露“发票池”等内部概念 | +| 财务导出页 | 财务按期间、人员、项目、状态导出 | 导出前必须校验财务权限 | + +--- + +## 3. 报销单对象与字段 + +| 字段 | 含义 | 必填规则 | +| --- | --- | --- | +| 报销单号 | OA 生成的唯一业务编号 | 提交前或首次保存时生成,必须唯一 | +| 申请人 | 创建报销单的人 | 必填 | +| 实际报销人 | 款项实际归属人员 | 默认等于申请人,可按权限调整 | +| 部门 | 申请人或实际报销人所属部门 | 必填或由系统带出 | +| 项目 | 关联项目、合同或内部事项 | 项目费用建议必填 | +| 费用明细 | 费用类型、日期、金额、说明、关联发票 | 至少一条有效明细 | +| 报销总金额 | 明细金额合计 | 系统计算,用户不可直接篡改 | +| 发生日期 | 费用发生日期或期间 | 明细级必填 | +| 说明 | 报销原因、用途、备注 | 按费用类型决定是否必填 | +| 发票 | 增值税发票、数电票、普通发票等凭证 | 需报销发票的费用必填 | +| 附件 | 支付截图、订单、合同、聊天记录、情况说明等 | 按费用类型或审批要求决定 | +| 审批状态 | 草稿、审批中、已通过等 | 系统维护 | +| 付款状态 | 未付款、已付款、无需付款等 | 财务维护 | +| 审批历史 | 提交、通过、驳回、退回、转审等记录 | 系统维护 | + +--- + +## 4. 状态模型 + +### 4.1 报销状态 + +| 状态 | 含义 | 主要动作 | +| --- | --- | --- | +| 草稿 | 员工编辑中,未提交 | 编辑、上传、删除草稿、提交 | +| 审批中 | 已提交 OA 审批 | 审批人处理;申请人按规则撤回 | +| 已通过 | 审批完成,等待财务后处理 | 财务复核、付款标记、导出 | +| 已驳回 | 审批否决 | 查看原因、复制重提或新建 | +| 已退回 | 需要申请人修改 | 修改后重提、撤回 | +| 已付款 | 财务已完成付款 | 查看、导出;普通用户不可修改 | +| 已完成 | 报销归档完成 | 查看、归档、导出 | + +### 4.2 发票状态 + +| 状态 | 含义 | 前端展示 | +| --- | --- | --- | +| `pending_ocr` | 已上传,正在识别 | 识别中 | +| `available` | 可加入报销单 | 可添加 | +| `bound` | 已加入报销单或明细 | 已添加 | +| `ocr_failed` | 识别失败,需要重试或人工处理 | 识别失败 | +| `archived` | 已归档,不可再添加 | 已归档或已报销 | + +### 4.3 附件状态 + +| 状态 | 含义 | 规则 | +| --- | --- | --- | +| 已上传 | 文件已存储并关联报销单 | 草稿和退回态可删除 | +| 已提交 | 报销提交后随单据进入审批 | 审批人和财务可查看 | +| 已归档 | 报销完成后归档 | 普通员工不可删除 | + +附件不是发票,不参与 OCR,不参与发票查重。 + +--- + +## 5. 发票与明细关系 + +### 5.1 匹配规则 + +- 报销单只有一条明细时,发票自动加入该明细。 +- 报销单有多条明细时,优先按发票金额唯一匹配明细金额。 +- 金额无法唯一匹配但发票金额存在时,可自动创建一条新明细,并提示用户确认费用类型和说明。 +- 发票金额缺失时,不自动创建明细,提示用户先补全发票信息或手工创建明细。 +- 一张发票可按业务规则关联一条或多条明细;首批优先支持一张发票绑定一条明细,复杂拆分后续单独设计。 + +### 5.2 校验规则 + +- 报销总金额必须等于有效明细金额合计。 +- 发票金额与对应明细金额不一致时,应提示用户确认差额原因。 +- 无发票费用必须有业务规则允许,并通过附件或说明补足依据。 +- 已归档或已报销的发票不能再加入新的报销单。 + +--- + +## 6. OCR 规则 + +### 6.1 上传与识别 + +- 支持图片和 PDF 上传;支持类型以当前 OCR provider 和文件处理能力为准。 +- 上传成功后必须展示明确状态,不允许长期停留在“上传中”。 +- OCR 识别字段至少包括:发票代码、发票号码、数电票号码或等效唯一号、金额、税额、价税合计、开票日期、销方、购方。 +- OCR 完成后,添加发票区域自动刷新,并尝试按规则加入报销明细。 +- OCR 失败时保留失败原因,允许重试和人工修正。 + +### 6.2 人工修正 + +- 申请人可在草稿或退回态修正自己发票的识别结果。 +- 财务可在复核阶段修正关键字段。 +- 修正发票代码、号码、金额、开票日期等关键字段必须写入审计日志。 +- 修正后必须重新触发查重校验。 + +### 6.3 PDF 与图片口径 + +- 图片直接进入 OCR 队列。 +- PDF 可按 provider 能力直接识别或先转图片后识别。 +- 多页 PDF 首批按一份文件处理;若包含多张发票,后续单独拆分能力。 +- 文件原件必须保留,OCR 结果只是结构化识别数据。 + +--- + +## 7. 查重规则 + +### 7.1 查重维度 + +公司级查重按以下优先级执行: + +1. 文件 `file_sha256` 相同。 +2. OCR 后 `invoice_code + invoice_number` 相同。 +3. 数电票号码或其他官方唯一号码相同。 +4. 后续接入电子发票验真时,使用官方验真结果补充判断。 + +### 7.2 不可添加场景 + +- 同一公司已有相同可用发票。 +- 同一公司已有相同发票正在识别。 +- 同一公司已有相同发票识别失败。 +- 同一公司已有相同发票被他人上传。 +- 同一公司已有相同发票处于已添加、已归档或已报销状态。 +- 发票已经被其他报销单、差旅单或归档流程占用。 + +### 7.3 重复例外 + +- 普通员工不能强制添加重复发票。 +- 确需例外时,只能由授权财务或财务主管处理。 +- 例外必须记录原报销单号、重复原因、处理人、处理时间和附件依据。 +- 例外处理不得绕过 OA 审批和财务复核。 + +--- + +## 8. 附件规则 + +附件用于补充业务事实,包括支付截图、订单、合同、聊天记录、情况说明、验收材料等。 + +- 支持 PDF、JPG、PNG、WEBP。 +- 支持多文件上传。 +- 不参与 OCR。 +- 不参与发票查重。 +- 草稿和已退回状态允许上传、查看、删除。 +- 审批中、已通过、已付款、已完成状态原则上不允许普通员工删除。 +- 审批人和财务在处理报销时可查看附件。 +- 涉密合同正文、敏感报价、身份证、银行卡等高敏材料不得随意进入公网 OA;确需上传时必须另行定义脱敏和权限规则。 + +--- + +## 9. 财务动作 + +| 动作 | 前置条件 | 结果 | +| --- | --- | --- | +| 财务复核 | 报销已通过或进入财务复核节点 | 检查发票、附件、金额、项目和审批历史 | +| 重复例外 | 发现重复但业务确需报销 | 记录原单号、原因和处理人,写入审计 | +| 付款标记 | 审批通过且复核通过 | 写入付款时间、付款人、付款备注和状态 | +| 取消付款标记 | 发现误操作且有权限 | 必须填写原因并审计,首批可只允许管理员或财务主管 | +| 导出 | 有财务导出权限 | 按期间、人员、项目、状态导出报销和发票摘要 | + +导出字段至少包括:报销单号、申请人、实际报销人、部门、项目、费用类型、明细金额、发票号码、开票日期、审批状态、付款状态、提交时间、通过时间、付款时间。 + +--- + +## 10. 异常规则 + +| 异常 | 处理规则 | 用户提示 | +| --- | --- | --- | +| 无发票 | 按费用类型判断是否允许;不允许则阻断提交 | “该费用类型需要添加发票” | +| 重复发票 | 普通流程阻断;财务例外需留痕 | “该发票已存在或已报销,不能重复添加” | +| 他人上传发票 | 阻断普通员工使用 | “该发票已被其他人员上传,请联系财务确认” | +| 金额不一致 | 提示差额,必要时阻断提交 | “发票金额与明细金额不一致,请确认” | +| OCR 失败 | 允许重试或人工录入;提交前必须满足关键字段要求 | “识别失败,请重试或手工补全信息” | +| 识别中提交 | 若关键字段未完成,不允许提交 | “发票仍在识别中,请稍后再提交” | +| 附件缺失 | 按费用类型、金额或审批要求判断 | “请补充必要附件” | +| 已付款后修改 | 普通用户不可修改;财务修正必须审计 | “已付款报销单不可修改” | +| 文件上传失败 | 不生成空附件或空发票记录 | “上传失败,请重新上传” | +| 通知失败 | 不影响报销提交或审批结果 | 管理员在通知记录中查看失败原因 | + +--- + +## 11. 审批与通知边界 + +- 报销提交后进入 OA 统一审批中心。 +- 审批动作包括通过、驳回、退回、撤回、转审和查看历史,规则以 [需求 - 统一审批中心规约](./需求-统一审批中心规约.md) 为准。 +- 企业微信消息只包含脱敏标题、报销单号、状态和 OA deeplink。 +- 消息中不得包含完整发票图片、合同正文、银行卡、身份证、敏感报价或大段说明。 +- 企业微信通知失败不阻断报销提交、审批或付款标记。 + +--- + +## 12. 验收场景 + +| 场景 | 步骤 | 预期结果 | +| --- | --- | --- | +| 上传 OCR 并添加 | 员工创建草稿,上传发票图片,等待 OCR 完成 | 发票从识别中变为可添加或已添加,识别字段可查看 | +| PDF 上传 | 员工上传 PDF 发票 | 文件保留,OCR 状态明确,失败时可重试或人工修正 | +| 单明细自动匹配 | 草稿只有一条明细,添加发票 | 发票自动绑定该明细 | +| 多明细金额匹配 | 草稿有多条明细,发票金额唯一匹配其中一条 | 发票自动绑定匹配明细 | +| 无法匹配创建明细 | 发票金额存在但无唯一明细 | 系统创建新明细或提示用户确认 | +| 提交审批 | 员工补齐明细、发票、附件后提交 | 报销进入 OA 审批中,生成审批历史和待办 | +| 审批通过到付款 | 审批人通过,财务复核并标记付款 | 报销状态进入已通过或已付款,付款记录可追溯 | +| 财务导出 | 财务按期间和状态导出 | 导出包含报销、发票、审批和付款摘要字段 | +| 重复阻断 | 员工上传已报销发票 | 系统阻断添加并显示可理解原因 | +| 重复例外 | 财务主管处理特殊重复票据 | 记录原单号、原因、处理人和审计日志 | +| OCR 失败处理 | 上传无法识别文件 | 显示失败原因,允许重试或人工补全 | +| 附件上传查看 | 员工上传支付截图,审批人查看 | 附件不参与 OCR 和查重,审批人可查看 | +| 移动端上传 | 企业微信或手机浏览器上传发票和附件 | 移动端无桌面宽表,上传、OCR、提交路径可用 | + +--- + +## 13. 后续开发拆分建议 + +后续实现时建议按以下 Issue 拆分: + +- A1:报销单字段与状态收口,覆盖草稿、提交、退回、驳回、已通过、已付款、已完成。 +- A2:发票上传、OCR 状态刷新和失败重试。 +- A3:发票查重与重复例外处理,覆盖 `file_sha256`、发票代码号码、数电票号码。 +- A4:发票与明细自动匹配、金额不一致提示和人工修正。 +- A5:附件上传、查看、删除和归档权限。 +- A6:报销接入统一审批中心,覆盖 PC、移动端、企业微信 deeplink。 +- A7:财务复核、付款标记、取消付款标记和导出。 +- A8:报销主链路回归脚本和 Playwright PC/移动/企业微信 UA 验证。 + +涉及发票唯一性、付款状态、审批状态机、财务权限或文件存储规则的 Issue,必须在技术方案中写明回滚策略、数据修复策略和回归范围。 diff --git a/docs/需求-统一审批中心规约.md b/docs/需求-统一审批中心规约.md new file mode 100644 index 00000000..a9dac76c --- /dev/null +++ b/docs/需求-统一审批中心规约.md @@ -0,0 +1,220 @@ +# 需求 - 统一审批中心规约 + +**版本**:1.0 +**日期**:2026-05-09 +**状态**:模块级开发规约 +**上级事实源**:[海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md) + +本规约细化 `hyb-oa` 统一审批中心的产品边界、角色权限、状态模型、异常规则、留痕要求和验收场景。后续审批相关开发必须先从本规约拆分 Issue CSV,再进入技术方案和代码实现。 + +--- + +## 1. 模块目标与边界 + +### 1.1 目标 + +- `hyb-oa` 是公司唯一业务主系统和唯一正式审批中心。 +- 所有正式审批在 OA 内提交、审批、留痕、归档。 +- PC、移动端和企业微信入口看到的是同一批审批任务和同一套审批记录。 +- 企业微信只做入口、身份、通知和 deeplink;审批动作必须回到 OA 页面完成。 + +### 1.2 适用对象 + +首批及后续默认纳入 OA 审批中心的正式审批包括: + +- 报销审批。 +- 请假、补卡、外出、加班、出差等考勤相关审批。 +- 采购审批。 +- 费用审批。 +- 合同审批、合同变更审批和合同归档相关审批。 +- 资产领用、归还、调拨、盘点中需要正式留痕的动作。 +- 后续新增业务审批,除非另有明确产品决策,否则默认接入统一审批中心。 + +### 1.3 暂不做范围 + +- 不使用企业微信原生审批作为公司正式审批流。 +- 不接入飞书登录、飞书审批、飞书通知或飞书项目管理。 +- 首批不做复杂 BPM 设计器、自由拖拽流程、并行会签、条件分支可视化建模。 +- 首批不做跨公司多租户审批市场化配置。 +- 首批不做审批动作离线处理;移动端必须在线提交动作。 + +--- + +## 2. 角色与权限 + +| 角色 | 典型用户 | 可做动作 | 权限边界 | +| --- | --- | --- | --- | +| 申请人 | 普通员工、主管、财务、HR | 创建草稿、提交、查看自己的单据、撤回允许撤回的单据、按退回意见修改后重提 | 只能编辑草稿、已退回、已驳回且规则允许重提的本人单据;不能审批自己的待办,除非后续明确自审例外规则 | +| 审批人 | 主管、项目负责人、老板、被转审人 | 查看分配给自己的待办,通过、驳回、退回、转审、查看审批历史 | 只能处理当前分配给自己的任务;不能越权处理他人待办 | +| 财务 | 财务人员、财务主管 | 处理报销复核、付款标记、财务导出、重复发票例外审批中与财务相关的动作 | 不默认拥有系统管理权限;财务例外动作必须留痕 | +| HR/管理员 | HR、行政管理员 | 处理请假、补卡、外出、加班等行政审批或复核;维护基础人员与组织配置 | 不能绕过审批流直接改业务结果,必要修正必须审计 | +| 老板/总经理 | 公司负责人 | 处理大额、高风险或最终节点审批,查看公司级待办和摘要 | 操作仍需写入审批历史和审计日志 | +| 系统管理员 | 运维或系统负责人 | 配置角色、权限、企业微信入口、通知、基础字典和功能开关 | 不自动获得业务单据审批权;直接数据修复必须另有运维流程和审计 | + +权限判定以服务端为准,前端按钮显隐只是体验优化,不作为授权依据。 + +--- + +## 3. 入口与任务视图 + +### 3.1 入口 + +| 入口 | 路径或位置 | 用途 | 要求 | +| --- | --- | --- | --- | +| PC 审批待办 | `/workflow/tasks` | 审批人集中处理待办、已办、抄送或历史任务 | 应在 PC 主导航清晰可达 | +| 移动审批 | `/mobile/approvals` | 手机端处理待办和查看审批历史 | 应适配企业微信 WebView 和普通手机浏览器 | +| 业务详情页 | 报销、请假、采购、合同等详情页 | 从具体单据查看审批流和执行动作 | 状态、当前节点、历史记录必须与待办一致 | +| 企业微信消息 | deeplink 到 OA 页面 | 只做提醒和跳转 | 不在企业微信原生审批里完成正式审批 | +| Portal 待办摘要 | `/portal` 或首页卡片 | 提醒当前待处理数量 | 点击后进入 `/workflow/tasks` 或对应详情页 | + +### 3.2 任务列表要求 + +- 待办列表至少展示:业务类型、业务编号、标题或摘要、申请人、金额或天数等关键值、当前节点、到达时间、状态。 +- 移动端列表应优先展示业务类型、编号、申请人、状态和主要金额/天数,不展示桌面宽表。 +- 已办或历史列表应能查看处理结果和处理时间,但首批不要求复杂筛选。 +- 待办数量、单据详情状态、审批历史必须一致。 + +--- + +## 4. 审批对象与字段 + +统一审批中心对所有业务单据抽象以下通用字段,具体业务可扩展自己的字段。 + +| 字段 | 含义 | 要求 | +| --- | --- | --- | +| `business_type` | 业务类型,如报销、请假、采购、合同 | 必填,用于路由、权限和列表展示 | +| `business_id` | 业务单据主键 | 必填,与业务表关联 | +| `business_no` | 业务编号,如报销单号、采购单号 | 必填,OA 生成或校验唯一 | +| `title` | 审批摘要标题 | 必填,用于待办和通知 | +| `applicant_id` | 申请人 | 必填 | +| `department_id` | 申请人所属部门 | 可空但推荐保留 | +| `project_id` | 关联项目 | 业务需要时填写 | +| `amount` | 金额类摘要 | 报销、采购、费用、合同等需要 | +| `current_status` | 当前业务状态 | 必须与工作流状态同步 | +| `current_task_id` | 当前待办任务 | 审批中必须存在 | +| `submitted_at` | 提交时间 | 提交后必填 | +| `completed_at` | 审批完成时间 | 通过、驳回终止、撤回终止或完成时填写 | + +--- + +## 5. 状态模型 + +### 5.1 通用状态 + +| 状态 | 含义 | 允许的主要动作 | +| --- | --- | --- | +| 草稿 | 申请人正在编辑,未进入审批 | 保存、提交、删除草稿 | +| 审批中 | 已提交,存在当前审批任务 | 审批人通过、驳回、退回、转审;申请人在规则允许时撤回 | +| 已通过 | 所有审批节点通过,进入业务后处理 | 财务付款、合同归档、考勤生效等业务动作 | +| 已驳回 | 审批人否决,流程终止或允许复制重提 | 查看历史、按业务规则重新发起 | +| 已退回 | 审批人要求申请人修改 | 申请人修改后重提、撤回 | +| 已撤回 | 申请人撤回,流程终止 | 查看历史、按业务规则复制重提 | +| 已完成 | 审批通过后的业务处理完成 | 查看、归档、导出 | +| 已付款 | 报销或费用类单据已付款 | 查看、导出;普通用户不可修改 | + +`已付款` 是报销、费用等财务类业务的完成状态之一;非财务业务可使用 `已完成`。 + +### 5.2 状态转换规则 + +- 草稿只能由申请人或授权代填人提交。 +- 提交成功后生成工作流实例、当前节点和第一条待办。 +- 当前审批人通过后,系统按规则推进到下一节点;无下一节点时进入 `已通过`。 +- 驳回默认终止当前流程,是否允许复制重提由业务模块决定。 +- 退回回到申请人修改态,重提后应保留同一业务单号和完整历史。 +- 撤回只允许在流程未完成且规则允许时发生。 +- 转审只改变当前任务处理人,不改变业务单据申请人。 +- 已完成、已付款、已归档类状态原则上不允许普通用户修改核心字段。 + +--- + +## 6. 审批动作 + +| 动作 | 发起人 | 前置条件 | 结果与留痕 | +| --- | --- | --- | --- | +| 保存草稿 | 申请人 | 有创建权限 | 写入业务草稿,不生成审批任务 | +| 提交 | 申请人 | 必填字段、附件、金额、发票等业务校验通过 | 生成工作流实例、待办、提交历史和通知 | +| 通过 | 当前审批人 | 任务未处理且权限匹配 | 当前任务完成,进入下一节点或业务通过 | +| 驳回 | 当前审批人 | 必填驳回原因 | 流程终止或进入业务定义的驳回态 | +| 退回 | 当前审批人 | 必填退回原因 | 任务回到申请人修改态,保留历史 | +| 撤回 | 申请人 | 流程未完成且业务允许撤回 | 流程终止或回到草稿,写入撤回原因 | +| 转审 | 当前审批人 | 目标人具备处理资格,未超过转审限制 | 当前任务转给目标人,记录转审链路和原因 | +| 批量审批 | 审批人 | 多个任务均可被当前人处理 | 每个任务独立校验、独立成功或失败 | +| 查看历史 | 相关人员 | 对单据有查看权限 | 展示提交、审批、退回、转审、通知和关键业务动作 | + +批量审批不得绕过单条任务的权限、状态和业务校验。 + +--- + +## 7. 异常规则 + +| 异常 | 处理规则 | 用户提示 | +| --- | --- | --- | +| 无审批人 | 提交时阻断,不生成半截流程;管理员可修正规则后重试 | “当前审批规则未找到审批人,请联系管理员” | +| 权限不足 | 服务端拒绝,记录必要安全日志 | “无权处理该审批任务” | +| 任务已处理 | 并发点击或重复提交时返回当前最新状态 | “该任务已处理,请刷新查看最新结果” | +| 并发审批 | 以服务端事务和任务版本为准,只允许一个处理结果生效 | “处理失败,任务状态已变化” | +| 转审超限 | 超过次数、转给无权限人员或形成循环时阻断 | “无法转审给该人员,请选择具备审批权限的人” | +| 审批人离职或停用 | 待办不能继续由停用账号处理;管理员按规则改派或转审 | “当前审批人不可用,请联系管理员处理” | +| 业务单据被删除或归档 | 不允许继续处理孤立待办 | “关联单据不可处理,请刷新或联系管理员” | +| 通知发送失败 | 不阻断主业务,进入可重试状态 | 业务页面不报错;管理员可在通知日志查看 | + +--- + +## 8. 留痕与一致性 + +### 8.1 必须留痕的记录 + +- 工作流历史:提交、通过、驳回、退回、撤回、转审、批量审批结果。 +- 审计日志:权限变更、审批规则变更、管理员改派、敏感附件查看、财务例外动作。 +- 通知记录:发送渠道、接收人、发送状态、失败原因、重试次数、deeplink。 +- 业务状态记录:业务单据状态与工作流状态变更必须能追溯。 + +### 8.2 一致性要求 + +- 审批动作成功后,业务单据状态、当前任务、审批历史必须在同一事务或等效一致性边界内更新。 +- 通知失败不回滚审批动作,但必须可重试。 +- 同一任务不能出现两个最终处理结果。 +- 业务详情页展示的审批历史与 `/workflow/tasks` 的任务状态必须一致。 + +--- + +## 9. 企业微信边界 + +- 企业微信自建应用只作为 `海音达工作台` 手机入口。 +- 企业微信消息只发送脱敏提醒:标题、业务编号、状态、处理入口。 +- 企业微信 deeplink 必须指向 OA 审批页或业务详情页。 +- 用户点击消息后,在 OA 内查看详情并执行审批动作。 +- 企业微信原生审批不参与正式审批流,不生成公司认可的正式审批记录。 + +--- + +## 10. 验收场景 + +| 场景 | 步骤 | 预期结果 | +| --- | --- | --- | +| 正常审批通过 | 申请人提交报销或请假;审批人在 PC 通过;查看业务详情 | 单据从草稿到审批中再到已通过;历史、当前状态、通知记录一致 | +| 移动端审批 | 申请人提交单据;审批人从 `/mobile/approvals` 打开待办并通过 | 移动端可完成审批;PC 待办同步消失或进入已办 | +| 企业微信通知回 OA | 待办产生后发送企业微信提醒;审批人点击 deeplink | 打开 OA 对应审批页;不能在企业微信原生审批完成动作 | +| 驳回重提 | 审批人填写原因驳回;申请人查看原因后复制或重建申请 | 原流程留痕完整;新流程有新的提交记录 | +| 退回修改 | 审批人退回;申请人修改后重提 | 保留同一业务单号和退回历史;重新进入审批中 | +| 撤回 | 申请人在未完成前撤回 | 流程终止或回到草稿;审批人待办失效 | +| 转审 | 当前审批人填写原因并转给有权限人员 | 原审批人待办关闭;目标审批人产生新待办;历史显示转审链路 | +| 无审批人阻断 | 提交时审批规则找不到审批人 | 提交失败,无半截流程,提示联系管理员 | +| 并发处理 | 两个窗口同时处理同一任务 | 只有一个结果生效,另一个提示任务已变化 | +| 通知失败不阻断 | 模拟企业微信通知发送失败 | 审批提交或处理成功,通知记录进入失败可重试 | + +--- + +## 11. 后续开发拆分建议 + +后续实现时建议按以下 Issue 拆分,不直接跳到大改代码: + +- A1:审批任务列表与入口收口,覆盖 PC `/workflow/tasks`、移动 `/mobile/approvals` 和 Portal 待办摘要。 +- A2:通用状态转换与并发保护,覆盖提交、通过、驳回、退回、撤回、转审。 +- A3:审批权限与当前处理人校验,覆盖越权、自审、停用账号和角色待办。 +- A4:审批历史、审计日志和通知记录一致性。 +- A5:企业微信通知 deeplink 回 OA 验证,不新增企业微信原生审批。 +- A6:报销、请假、采购等业务模块逐个接入统一审批验收。 +- A7:审批回归脚本与 Playwright PC/移动/企业微信 UA 验证。 + +涉及状态机、权限模型、数据库迁移或审批规则调整的 Issue,必须在技术方案中写明回滚策略和回归范围。 diff --git a/issues/2026-05-09_16-15-23-approval-reimbursement-requirements-detail.csv b/issues/2026-05-09_16-15-23-approval-reimbursement-requirements-detail.csv new file mode 100644 index 00000000..4a12e679 --- /dev/null +++ b/issues/2026-05-09_16-15-23-approval-reimbursement-requirements-detail.csv @@ -0,0 +1,6 @@ +ID,Title,Description,Acceptance,Test_Method,Tools,Dev_Status,Review1_Status,Regression_Status,Files,Dependencies,Notes +A1,细化执行合同与事实源确认,"建立统一审批中心与报销发票 OCR 需求细化执行合同,并确认本轮只做文档不改业务代码。","1) 新 Issue CSV 校验通过;2) 范围固定为统一审批中心与报销/发票/OCR/附件;3) 明确主 PRD 保持总纲,模块规约作为开发拆分依据;4) 不部署、不修改 server/client 业务代码。","命令:python3 /home/shunli/.codex/skills/plan/scripts/validate_issues_csv.py issues/2026-05-09_16-15-23-approval-reimbursement-requirements-detail.csv;人工步骤:确认本轮文件范围为 docs 与本 Issue CSV。",python3,DONE,DONE,DONE,issues/2026-05-09_16-15-23-approval-reimbursement-requirements-detail.csv,"[]","不改业务代码、不部署。" +A2,统一审批中心模块规约,"新增统一审批中心模块级中文规约,细化角色、入口、状态、动作、权限、异常、留痕和验收。","1) docs/需求-统一审批中心规约.md 存在;2) 规约覆盖适用对象、角色权限、状态模型、审批动作、待办入口、异常规则、留痕要求和验收场景;3) 明确企业微信 deeplink 只能回 OA,不使用企业微信原生审批。","人工步骤:阅读 docs/需求-统一审批中心规约.md,确认可直接指导后续审批相关 Issue 拆分。",manual,DONE,DONE,DONE,docs/需求-统一审批中心规约.md,"[""A1""]","涉及状态机和权限,仅做需求规约,不改运行时。" +A3,报销发票OCR模块规约,"新增报销/发票/OCR/附件模块级中文规约,细化角色、入口、字段、状态、匹配、查重、财务动作、异常和验收。","1) docs/需求-报销发票OCR规约.md 存在;2) 规约覆盖报销单字段、报销状态、发票状态、发票与明细关系、OCR、查重、附件、财务复核、付款导出、异常和验收;3) 普通员工文案不暴露内部发票池概念。","人工步骤:阅读 docs/需求-报销发票OCR规约.md,确认可直接指导后续报销、发票、OCR、附件、付款和导出 Issue 拆分。",manual,DONE,DONE,DONE,docs/需求-报销发票OCR规约.md,"[""A1"",""A2""]","报销细则与 docs/reimbursement-invoice-rules.md 对齐。" +A4,主PRD与文档索引挂接,"更新主 PRD、文档索引和报销规则文档,将两份模块规约加入当前事实源和开发依据。","1) 主 PRD 关联两份模块规约;2) docs/文档索引.md 将两份模块规约列入当前事实源;3) docs/reimbursement-invoice-rules.md 说明与新规约的关系。","命令:rg -n ""需求-统一审批中心规约|需求-报销发票OCR规约|海音达OA-MVP需求规格说明书|文档索引"" docs issues/2026-05-09_16-15-23-approval-reimbursement-requirements-detail.csv;人工检查链接可读。",ripgrep|manual,DONE,DONE,DONE,docs/海音达OA-MVP需求规格说明书.md|docs/文档索引.md|docs/reimbursement-invoice-rules.md,"[""A2"",""A3""]","不改变既有文档历史状态,只增加当前引用。" +A5,需求验收用例与后续开发拆分建议,"在模块规约中补齐需求验收用例和后续开发拆分建议,确保后续开发不直接跳代码。","1) 两份模块规约都有验收场景;2) 两份模块规约都有后续 Issue 拆分建议;3) 文档没有重新引入飞书路线或企业微信原生审批;4) 每个模块至少包含角色、入口、字段/对象、状态、权限、异常、验收。","命令:git diff --check && rg -n ""飞书|企业微信原生审批|后续开发拆分|验收场景|异常"" docs/需求-统一审批中心规约.md docs/需求-报销发票OCR规约.md;人工判断命中内容与当前路线一致。",git|ripgrep|manual,DONE,DONE,DONE,docs/需求-统一审批中心规约.md|docs/需求-报销发票OCR规约.md,"[""A2"",""A3"",""A4""]","完成后回填本 CSV 状态并提交中文 commit。"