hyb-oa/docs/requirements-specification.md

海音达 OA 系统 - 需求规格说明书

版本：1.4
日期：2026-02-06
范围：报销系统及其依赖模块（员工/权限/工作流/附件）

相关文档：

• 技术栈与复用报告
• 实施计划

---

1. 项目概述

1.1 背景

海音达科技需要一套独立的 OA 系统，用于内部办公管理。Phase 1 聚焦报销系统及其依赖（员工管理、权限、工作流、附件/发票）。

1.2 目标（Phase 1）

• 实现完整的费用报销流程：草稿 → 提交 → 审批（工作流任务）→ 通过 → 付款标记 → 完成
• 审批规则可配置（金额区间 → 多级审批角色），P0 预置 3 条默认规则
• 审批引擎采用通用 4 表式工作流（Definition/Instance/Task/History），后续扩展到请假/采购无需重构
• 支持行政代提交（需授权）、发票附件上传、双策略判重、离线打款标记
• 响应式 Web（PC/移动端）

1.3 技术栈（定案）

层级	选型
前端（OA）	React + Vite + Tailwind
后端（OA API）	Fastify + Prisma
数据库	PostgreSQL

1.4 复用资产（来自 shenzhou-business-suite）

目的：减少踩坑与重复造轮子。本文档的表结构/枚举/约束均以该项目的已验证实现为基线，再按 hyb-oa 目标做裁剪与补齐。

资产	来源路径（参考）	在 hyb-oa 的复用方式
工作流 4 表结构 + approval_rules/approval_transfers/document_sequences	shenzhou-business-suite/supabase/schema/70_workflow/01_workflow_02_tables.sql	转为 Prisma schema；服务端实现工作流事务与权限校验
工作流类型定义（assignee_rule 等）	shenzhou-business-suite/src/types/workflow.ts	作为工作流 JSON 配置与服务层契约参考
权限码体系	shenzhou-business-suite/src/types/permissions.ts	复用命名与粒度；补齐行政代提交权限码
报销表结构参考（forms/items/attachments）	shenzhou-business-suite/supabase/schema/20_finance/06_reimbursement_01_tables.sql	字段设计参考；按 hyb-oa 简化并补齐 file_sha256 等字段
默认费用类型 seed（35 启用 + 3 legacy 禁用）	shenzhou-business-suite/supabase/seed.sql	作为系统默认费用类型基线；hyb-oa 额外启用 utilities/rent 形成 37 启用
存储安全基线思路（类型/大小/访问控制）	shenzhou-business-suite/supabase/migrations/20260131175000_storage_security_baseline.sql	落到本地存储 + 签名 URL 的约束与鉴权规则

---

2. 用户角色与权限模型

2.1 角色（role_code）与职责边界（P0）

角色（展示）	role_code	职责/范围
普通员工	employee	创建/提交报销，查看/编辑本人草稿与记录
部门经理	manager	审批直属下属报销（工作流任务）；可查看直属下属报销（P0：不递归）
总经理	ceo	审批大额报销（工作流任务），查看全公司数据（只读）
财务专员	finance	财务复核（工作流任务）、付款标记、票据管理（全量）
财务主管	finance_mgr	大额复核、发票判重例外、审批规则维护（P1 UI）
行政	administration	代提交（授权由 principal 本人或 hr/admin 维护；不含审批/付款）
人事	hr	员工与组织维护（不含财务/审批）
系统管理员	admin	系统设置、用户、审计（可授予 *）

说明：一个员工可同时拥有多个 role_code（例如 finance + admin），权限按并集生效。

2.2 权限码（Permission Codes，P0 必需）

命名规则：domain.action[_scope]。后端接口必须声明所需权限码并统一校验。

permission	说明
expense.create	创建报销单（草稿）
expense.view_own	查看自己的报销单
expense.view_all	查看所有报销单（数据范围由角色决定：manager=直属下属（owner.direct_manager_id = me，不递归）；ceo/finance/finance_mgr=全公司；hr=全公司只读）
expense.edit_own	编辑自己的报销单（仅草稿/驳回）
expense.delete_own	删除自己的报销单（仅草稿）
expense.submit	提交报销单（发起工作流）
expense.withdraw	撤回报销单（将流程取消并回到草稿）
expense.approve	审批报销单（处理工作流任务）
expense.transfer	转审（转交当前待办任务）
expense.finance.pay	付款标记（approved → paid）
expense.finance.override_duplicate	发票重复例外（需填原单号+原因）
expense.proxy_submit	行政代提交
expense.proxy_manage	代提交授权管理（Delegation Grants：本人可管自己的授权；hr/admin 可代维护）
invoice.upload	上传发票/附件
invoice.view_own	查看自己的发票/附件
invoice.manage	票据中心管理（可查看全量附件/发票信息）
system.settings	系统设置（含费用类型/单号规则/审批规则等配置入口）
system.users	用户与组织管理
system.audit	审计日志查看
*	超级权限（仅 admin 可授予）

2.3 角色默认权限映射（P0 定案）

• employee：expense.create/view_own/edit_own/delete_own/submit/withdraw + invoice.upload/invoice.view_own + expense.proxy_manage（仅管自己的授权）
• manager：在 employee 基础上 + expense.approve/expense.transfer（仅对其审批范围内单据）+ expense.view_all（数据范围=直属下属，owner.direct_manager_id = me，不递归）
• ceo：expense.approve/expense.transfer（仅对其审批范围内单据）+ expense.view_all（数据范围=全公司）
• finance：invoice.manage + expense.approve（财务复核任务）+ expense.finance.pay + expense.view_all（数据范围=全公司）
• finance_mgr：在 finance 基础上 + expense.finance.override_duplicate（判重例外）+ system.settings（审批规则/费用类型配置，P1 提供 UI）
• administration：expense.proxy_submit + expense.view_own（不含审批/付款；授权管理由 principal 本人或 hr/admin 执行）
• hr：system.users（仅员工/组织域）+ expense.view_all（数据范围=全公司只读）
• admin：*

2.4 权限校验原则（实现约束）

• 后端为单一事实源：所有关键动作必须在服务端做权限码校验（前端仅用于 UI 隐藏）。
• *_own 语义（P0 定案）：
  • 对报销单（reimbursement），own 定义为：owner_id = me OR submitter_id = me（代提交场景）。
  • 因此 expense.view_own/edit_own/delete_own/withdraw 均按该规则判定（另受状态约束：edit 仅 draft/rejected；delete 仅 draft；withdraw 仅“审批人未处理前”）。
  • administration 持有 expense.view_own 的目的，是允许其查看“自己代提交”的单据（submitter 维度），不代表可查看全公司。
• “审批范围”由工作流任务的 assignee_id/assignee_role 决定：只有当前待办任务的处理人/处理角色可执行审批/转审。
• “财务例外”必须写入审计日志（见第 12 章），且需要 expense.finance.override_duplicate。

---

3. 组织架构与部门模型

3.1 组织架构示例

总经理
├── 部门经理 A
│   ├── 员工 A1
│   └── 员工 A2
└── 部门经理 B
    ├── 员工 B1
    └── 员工 B2

• 普通员工的直属上级 = 部门经理
• 部门经理的直属上级 = 总经理

3.2 部门模型（P0）

• 支持多级部门（parent_id）。
• 部门归档约束（禁止硬删除）：
  • 有子部门：禁止归档
  • 有在职员工：禁止归档
  • 归档后不可再分配新员工；组织树默认隐藏归档部门（可筛选查看）

---

4. 功能需求

4.1 员工管理

4.1.1 员工信息字段（核心）

字段	类型	必填	说明
工号	String	✅	唯一标识
姓名	String	✅
手机号	String	✅	登录标识（identifier 之一）
邮箱	String	✅	登录标识（identifier 之一）/通知
部门	FK	✅	关联部门表
职位	String	✅
直属上级 direct_manager_id	FK	✅（顶层可空）	审批链与 department_manager 解析依赖；顶层角色（如 CEO）可为空
入职日期	Date	✅
状态	Enum	✅	在职/离职
角色集合	M2M	✅	通过 employee_roles(employee_id, role_code) 维护；权限按并集生效
银行卡号	String	✅	敏感字段：加密存储/脱敏展示（见第 12 章）
开户行	String	✅
身份证号	String	❌	敏感字段：加密存储/脱敏展示（见第 12 章）

4.1.2 功能点

• 员工 CRUD（system.users，通常由 hr/admin 执行）
• 组织架构树展示（含归档部门过滤）
• 离职员工归档：离职后禁止登录并强制下线（见第 11 章 tokenVersion）

---

4.2 报销系统

4.2.1 报销单（Reimbursement Form）

字段	说明
报销单号 form_number	由单号规则生成（见第 8 章）
申请人 submitter_id	当前登录用户或代提交人
实际报销人 owner_id	费用归属人
部门 department_id	默认取 owner_id 所属部门
费用明细 items[]	多条，见下表
总金额 total_amount	自动汇总
报销日期 reimbursement_date	业务发生日期（整单）
状态 status	固定 6 状态（见 4.3.3）
备注 description	可选

4.2.2 报销明细（Reimbursement Item）

字段	说明
费用类型 expense_type_id	关联 expense_types（见第 9 章）
发生日期 expense_date	日期
金额 amount	数值
说明 description	必填（用于审计与复核）

附件（发票池条目）与明细的关联由 invoice_pool.linked_item_id 实现（可选），详见第 10 章。

费用类型不再是“21 种硬编码”，改为动态 expense_types；系统默认启用 37 项（见附录 A）。

4.2.3 代提交（Proxy Submit，P0）

• 允许角色：administration（需权限 expense.proxy_submit）
• 约束：代提交必须存在有效授权（由 delegation_grants 控制；授权由本人或 hr/admin 维护），否则拒绝提交/创建
• 记录要求：
  • 报销单必须同时记录 submitter_id（代提交人）与 owner_id（实际报销人）
  • 审批与通知以 owner_id 为主，同时抄送 submitter_id

4.2.4 代提交授权（Delegation Grants，P0）

用于控制“行政可以为哪些员工代提交”，避免权限过大。P0 默认“创建即生效”，无需被授权人二次确认。

delegation_grants 表（建议字段）：

字段	类型	说明
id	UUID	主键
principal_employee_id	UUID	被代提交人（员工）
delegate_employee_id	UUID	代办人（行政）
scope	String	reimbursement_submit | all（P0；P1+ 可扩展其他 scope）
valid_from/valid_to	DateTime	生效/失效时间（valid_to 可空表示长期）
revoked_at	DateTime	撤销时间（可空）
created_at/created_by	DateTime/UUID	创建时间/操作者

授权规则（P0 定案）：

• delegate_employee_id 必须包含 administration 角色
• 授权生效条件：revoked_at is null 且当前时间在 [valid_from, valid_to] 范围内
• 授权管理权限：
  • 员工本人可对“授予给行政的授权”执行创建/撤销（UI：个人设置 → 授权管理）
  • hr/admin 可代维护（用于补录/紧急处理），所有变更必须进入 audit_logs

---

4.3 审批与流程（业务视角）

4.3.1 默认审批链（P0 预置规则）

审批链不再硬编码在业务代码里，而是由 approval_rules 匹配得到（见第 6 章）。P0 预置 3 条规则：

• 小额：[0, 500) → manager → finance
• 中额：[500, 5000) → manager → finance_mgr
• 大额：[5000, +∞) → manager → ceo → finance_mgr

4.3.2 审批操作（P0）

操作	触发者	结果
提交 submit	申请人/代提交人	生成单号，发起工作流实例与首个任务
通过 approve	当前任务处理人	完成当前任务并推进到下一任务/流程结束
驳回 reject	当前任务处理人	流程终止（instance=rejected），报销单状态变为 rejected（可编辑后再次 submit 进入新一轮）
退回 return	当前任务处理人	终止当前流程实例（instance=terminated），报销单回到 draft（可修改后重新 submit）
撤回 withdraw	申请人	取消当前流程实例（instance=cancelled），报销单回到 draft（仅在审批人未处理前）
转审 transfer	当前任务处理人	将当前任务转交他人；需记录原因（≥10 字）
付款标记 pay	财务	流程通过后，将 approved 标记为 paid

4.3.3 报销单数据状态机（固定 6 状态）

“待部门审批/待财务复核”等是任务节点文案，由工作流当前待办任务决定，不作为数据状态写入 DB。

draft
  └─ submit → reviewing
reviewing
  ├─ approve(最终) → approved
  ├─ reject → rejected
  ├─ return → draft
  └─ withdraw → draft
approved
  └─ pay → paid
paid (终态)
rejected (可由申请人编辑后再 submit 进入新一轮)
cancelled (作废/终止，终态)

4.3.4 return vs reject vs withdraw（P0 定案）

• return（退回）：用于“需要申请人修改后再提交”的场景。动作发生后：
  • 当前 workflow_instances 必须结束并标记为 terminated
  • 报销单状态回到 draft；申请人修改后需再次 submit 才会进入新一轮审批
  • 所有未完成任务必须被取消（workflow_tasks.status=cancelled），并写入 workflow_history(action=return)
• reject（驳回）：用于“本轮不通过”的场景。动作发生后：
  • 当前 workflow_instances 必须结束并标记为 rejected
  • 报销单状态变为 rejected（保留驳回意见）；申请人可编辑后再次 submit 进入新一轮审批
  • 写入 workflow_history(action=reject)
• withdraw（撤回）：由申请人发起的“主动取消”。动作发生后：
  • 当前 workflow_instances 必须结束并标记为 cancelled
  • 报销单状态回到 draft
  • 约束：仅允许在审批人尚未处理前撤回（即当前实例内不存在已完成的审批任务）
  • 写入 workflow_history(action=withdraw)

---

4.4 发票池（Invoice Pool）与 OCR（P0）

目的：把“票据文件 + OCR 结果 + 发票元数据 + 绑定关系 + 生命周期状态”从报销单附件中解耦出来，形成可复用、可审计、可判重的单一事实源。

4.4.1 模块定位（P0）

• invoice_pool 是票据/附件的单一事实源（含发票、行程单、火车票、出租车票等图片/PDF）。
• 报销单不再直接管理“附件文件”，而是绑定 invoice_pool 条目（见 4.4.6）。
• 判重与例外属于“使用/报销”层面的合规约束：P0 允许先入池，在绑定/提交阶段做硬校验（见 4.4.7）。

4.4.2 生命周期状态机（5 态，P0）

invoice_pool.status：

• pending_ocr：已上传，OCR 未完成（或排队中）
• ocr_failed：OCR 失败（可重试，或人工修正后转为 available）
• available：可绑定（OCR 成功或人工确认/修正后）
• bound：已绑定到某报销单（1:1）
• archived：已归档（不可再绑定；P0 不提供恢复）

不变量（P0，必须由 DB + 服务端共同保证）：

• status = bound ⇒ linked_reimbursement_id is not null
• status in (pending_ocr, ocr_failed, available) ⇒ linked_reimbursement_id is null
• status = archived ⇒ 不允许再执行 bind
• status = archived AND archived_reason = used_complete ⇒ linked_reimbursement_id is not null（用于追溯）
• status = archived AND archived_reason in (unused_timeout, manual) ⇒ linked_reimbursement_id is null

4.4.3 归档原因（用于判重口径，P0）

invoice_pool.archived_reason（仅当 status=archived 时有意义）：

• used_complete：已被报销使用且流程完成后归档
• unused_timeout：90 天未绑定自动归档（从未被使用）
• manual：人工归档（清理/隐藏；从未被使用或不再使用）

判重口径（P0 定案）：

• 只有 status=bound 与 status=archived AND archived_reason=used_complete 的记录参与“全局判重历史”。
• unused_timeout/manual 的归档记录不参与全局判重（避免“未使用的旧票据”阻塞新票据入库）。

4.4.4 90 天未绑定自动归档（P0）

• 目标：控制“孤儿发票/票据”堆积。
• 规则：对 status in (available, ocr_failed) 且未绑定的条目，超过 90 天自动转 archived 且 archived_reason=unused_timeout。
• pending_ocr 超时策略（建议）：先转 ocr_failed 再进入自动归档规则（超时阈值由实现配置）。

4.4.5 OCR（腾讯云，P0）

• OCR 提供方：腾讯云（参考既有项目实现）。
• OCR 结果必须持久化（用于复核/搜索/审计/复用）；P0 不落库保存腾讯云 rawResponse（仅日志）。
• ocr_type（P0 枚举）：
  • vat（增值税发票；覆盖专票/普票/数电票，细分类型体现在标准化结果中）
  • train（火车票）
  • flight（机票行程单）
  • taxi（出租车票）
  • general（其他通用票据，默认值）
• 交互策略：用户可选 ocr_type；默认 general。
• 提交不阻塞：OCR 失败/未完成时，允许用户人工补齐关键字段后继续（UI 提示即可，不让流程卡死）。
• 发票验真（税局/验真接口）：P2，P0/P1 不做。

4.4.6 绑定/解绑规则（P0）

• 绑定关系：一张 invoice_pool 条目只能绑定一个报销单（1:1）。
• 绑定前置条件：status=available 且未绑定。
• 绑定后：status=bound，写入 linked_reimbursement_id（可选 linked_item_id）。
• 解绑后：清空 linked_reimbursement_id/linked_item_id，回到 available（P0 不自动恢复到 ocr_failed）。

与报销流程的联动（P0 定案）：

• 报销草稿被删除（仅 draft）：必须自动解绑其绑定的发票池条目并回到 available。
• 报销单进入 paid（完成节点）：其绑定的发票池条目自动归档为 archived 且 archived_reason=used_complete。

4.4.7 判重与例外（P0）

• 全局双策略判重（公司级）：
  1. invoice_code + invoice_number（齐全时）
  2. file_sha256
• 生效点：不阻塞“入池上传”；在 bind/submit 阶段做硬校验。
• 例外（允许重复）：仅 finance_mgr，必填原单号 + 原因（≥10 字），并写入审计；当原单处于 approved 或 paid 时禁止例外（见错误码 VALID_004）。

存储与签名 URL 访问规则见第 10 章；接口契约见第 13 章。

---

4.5 支付管理

• 打款方式：线下打款，系统仅做“付款标记”
• 付款状态：approved → paid
• 付款记录：付款时间、操作人、银行流水号（可选）、备注

---

4.6 通知系统（P0）

场景	通知方式
待审批提醒	站内 + 邮件（P1：企微/钉钉）
审批结果	站内 + 邮件
付款完成	站内 + 邮件

---

5. 工作流引擎（Workflow，P0 采用）

采用 4 表式通用工作流，审批任务由 workflow_tasks 表驱动。P0 仅用线性审批链，但表结构支持后续扩展为条件分支/动作节点。

5.1 表结构（核心四表）

5.1.1 workflow_definitions（流程定义）

字段	类型	说明
id	UUID	主键
name	String	流程名称（如“报销审批流程”）
entity_type	String	实体类型（如 reimbursement）
definition_json	JSON	流程配置（见 5.2）
version	Int	版本号（递增）
is_active	Bool	是否启用

5.1.2 workflow_instances（流程实例）

字段	类型	说明
id	UUID	主键
workflow_id	UUID	关联 workflow_definitions
entity_type	String	实体类型（reimbursement）
entity_id	UUID	业务实体 ID（报销单 ID）
submitter_id	UUID	发起人（提交者）
current_status	String	pending/approved/rejected/cancelled/terminated
current_step_id	String	当前步骤 ID（与任务 step_id 对齐）
context_data	JSON	实体快照（必须包含 owner_id、department_id；如 total_amount、命中 rule_id、审批链等）
started_at/completed_at	DateTime	开始/结束时间

5.1.3 workflow_tasks（审批任务）

字段	类型	说明
id	UUID	主键
instance_id	UUID	关联 workflow_instances
step_id/step_name	String	步骤标识与名称
assignee_id	UUID	指派到具体人（可空）
assignee_role	String	指派到角色（可空）
status	String	pending/completed/rejected/cancelled/skipped
outcome	String	approved/rejected/returned/start/transfer/skipped
comment	String	审批意见/原因
due_date	DateTime	截止时间（Phase 2 可启用超时）
created_at/completed_at	DateTime	创建/完成时间
completed_by	UUID	完成人

5.1.4 workflow_history（流程历史）

字段	类型	说明
id	UUID	主键
instance_id	UUID	关联实例（必填）
task_id	UUID	关联任务（可空）
actor_id	UUID	操作人（必填）
action	String	动作（approve/reject/return/transfer/start/withdraw 等）
comment	String	说明
payload	JSON	扩展信息（如转审 from/to、判重例外引用原单号等）
created_at	DateTime	时间戳（高精度）

5.2 流程定义 JSON 规范（WorkflowConfig）

参考 shenzhou-business-suite/src/types/workflow.ts。

{
  "steps": [
    {
      "id": "dept_manager",
      "name": "部门经理审批",
      "type": "approval",
      "assignee_rule": { "type": "department_manager" }
    },
    {
      "id": "ceo",
      "name": "总经理审批",
      "type": "approval",
      "assignee_rule": { "type": "role", "value": "ceo" }
    },
    {
      "id": "finance",
      "name": "财务复核",
      "type": "approval",
      "assignee_rule": { "type": "role", "value": "finance" }
    },
    {
      "id": "finance_mgr",
      "name": "财务主管复核",
      "type": "approval",
      "assignee_rule": { "type": "role", "value": "finance_mgr" }
    }
  ]
}

5.3 指派规则（assignee_rule）解析（P0）

支持类型：

• specific_user：指派到指定用户 ID
• role：指派到指定 role_code
• department_manager：对报销（entity_type=reimbursement），必须基于 owner_id（费用归属人）的直属上级链向上寻找经理（最多 10 层；若经理=owner 本人则继续向上；找不到则该步骤可被跳过并写入 history）
• submitter_manager：基于 submitter_id 的直属上级链向上寻找经理（为未来其他流程预留；报销流程默认不使用该规则）

5.4 一致性与并发要求（实现约束）

• 任务处理必须加锁：完成 workflow_tasks 时必须对该任务行做行级锁（防止重复审批）。
• 单实例串行：同一个 workflow_instances 在任意时刻最多只有 1 条 pending 任务。
• 幂等提交：同一 entity_type+entity_id 若存在未结束实例（非 approved/rejected/cancelled/terminated），再次提交应返回同一实例或拒绝重复提交。
• 状态同步：
  • 创建首个任务后，报销单状态应进入 reviewing
  • 实例 approved → 报销单状态 approved
  • 实例 rejected → 报销单状态 rejected
  • 实例 cancelled（撤回）→ 报销单状态回到 draft
  • 实例 terminated（退回）→ 报销单状态回到 draft

5.5 动作→状态对照表（消歧义）

用于避免 workflow_tasks.status / outcome / workflow_instances.current_status / 报销 status 之间的实现分歧。

动作	workflow_tasks.status	workflow_tasks.outcome	workflow_instances.current_status	报销 status
提交 submit	首个 task=pending	start	pending	reviewing
通过 approve（非最终）	当前=completed；下一=pending	approved	pending	保持 reviewing
通过 approve（最终）	当前=completed	approved	approved	approved
驳回 reject	当前=rejected	rejected	rejected	rejected
退回 return	当前=completed；其余 pending=cancelled	returned	terminated	draft
撤回 withdraw	所有 pending=cancelled	N/A	cancelled	draft
转审 transfer	保持 pending；assignee_id 更新	transfer	保持 pending	保持 reviewing
跳过（无审批人）	当前=skipped	skipped	pending（推进到下一）	保持 reviewing

---

6. 审批规则（Approval Rules，P0 可配置）

用于决定报销审批链的层级与角色，不在业务代码中硬编码金额阈值。

6.1 approval_rules 表（字段）

字段	类型	说明
id	UUID	主键
name	String	规则名（如“小额/中额/大额”）
min_amount	Decimal	最小金额（含）
max_amount	Decimal	最大金额（不含；NULL 表示无上限）
level1_role	String	一级审批角色（role_code）
level2_role	String	二级审批角色（可空）
level3_role	String	三级审批角色（可空）
enabled	Bool	启用
priority	Int	优先级（越小越优先）

6.2 匹配算法（P0 定案）

• amount >= min_amount
• max_amount is null OR amount < max_amount
• ORDER BY priority ASC, min_amount ASC LIMIT 1
• 若无匹配：fallback 到“默认小额规则”

6.3 P0 预置 3 条规则（默认值）

name	min_amount	max_amount	level1_role	level2_role	level3_role	priority
小额	0	500	manager	finance	NULL	10
中额	500	5000	manager	finance_mgr	NULL	20
大额	5000	NULL	manager	ceo	finance_mgr	30

6.4 审批角色 → 指派规则映射（消歧义，P0 定案）

approval_rules.level*_role 存的是 role_code；工作流落到 workflow_tasks 时，需要把部分 role_code 映射为“解析规则”（assignee_rule），避免把 manager 误解为“一个静态角色池”。

approval_rules.level*_role（role_code）	生成的工作流指派规则	workflow_tasks 落地形态
manager	assignee_rule.type=department_manager（以 owner_id 为基准解析直属经理）	写入 assignee_id（解析到具体人）；若找不到则该步骤可跳过并写入 history
其他 role_code（如 finance/finance_mgr/ceo）	assignee_rule.type=role，value=role_code	写入 assignee_role=role_code（允许该角色下任一成员处理；行级锁保证只完成一次）

---

7. 转审（Transfer，P0）

7.1 approval_transfers 表（字段）

字段	类型	说明
id	UUID	主键
reimbursement_id	UUID	关联报销单
from_approver_id	UUID	原审批人
to_approver_id	UUID	新审批人
reason	String	转审原因（至少 10 字）
status	String	active/cancelled
created_at/created_by	DateTime/UUID	创建时间/操作者

7.2 业务规则（P0 定案）

• 仅当前 workflow_tasks.status=pending 的实际处理人可转审
• 转审后原审批人失去操作权（只读），新审批人成为任务 assignee_id
• 转审链最大次数：3（超过需 admin 介入）
• 转审必须落 3 处证据：
  1. 更新 workflow_tasks.assignee_id
  2. 插入 approval_transfers
  3. 插入 workflow_history，action=transfer，payload 含 from/to/reason

---

8. 单据编号规则（Document Sequences，P0）

8.1 document_sequences 表（字段）

字段	类型	说明
document_type	String	文档类型（如 reimbursement）
prefix	String	前缀（如 BX）
date_format	String	日期格式（如 YYYYMMDD）
separator	String	分隔符（如 -）
number_length	Int	流水号长度（默认 4）
reset_period	String	none/daily/monthly/yearly
current_number	Int	当前序号（原子递增）
last_reset_date	DateTime	上次重置时间

约束：document_type 必须唯一（避免多条序列配置导致重复单号）。

8.2 P0 默认报销单号格式

• document_type=reimbursement
• prefix=BX
• date_format=YYYYMMDD
• separator=-
• number_length=4
• reset_period=daily

示例：BX-20260205-0001

8.3 并发安全要求（实现约束）

• 编号生成必须数据库原子递增（等价于 UPDATE ... RETURNING），并在同一事务内写入报销单
• form_number 必须全局唯一；失败必须回滚，禁止出现重复编号或“跳号后写入失败但编号已占用”的不可追溯状态
• daily reset 的日期边界以公司本地时区为准（默认 Asia/Shanghai）；实现时应统一使用显式时区计算，禁止依赖数据库/容器时区的隐式行为

---

9. 费用类型与科目映射（Expense Types，P0）

9.1 expense_types（动态费用类型）

字段至少包含：

• code（全局唯一、不可修改）
• name
• description
• category（用于 UI 分组；系统默认使用 travel/rd/production/office/business/assets/other）
• sort_order
• account_code_default（默认会计科目，可配置）
• is_system_default（系统内置：不可删除、仅可禁用）
• enabled（软禁用：不在录入下拉显示，但历史可展示）

9.2 系统默认费用类型（P0：37 项启用）

• 基线：复用 shenzhou-business-suite/supabase/seed.sql 中已启用的 35 项
• 补齐：启用 utilities（水电费）与 rent（房租租赁费）两项高频类型
• 兼容预留：保留 3 个 legacy 类型（transport/meal/rd）为禁用状态，不在 P0 下拉显示

详见附录 A（37 项启用）与附录 B（legacy 禁用）。

---

10. 发票池与文件存储（P0：本地 + 签名 URL）

关键原则：文件与票据元数据以 invoice_pool 为单一事实源；报销单通过“绑定”使用发票池条目（见 4.4）。

10.1 P0 存储方案（本地存储）

• 存储介质：本地磁盘（Docker volume）
• DB 仅保存 storage_path，不保存公网 URL
• 访问方式：后端生成签名 URL（TTL=10 分钟）用于浏览器预览/下载

10.2 安全基线（P0）

• 文件类型白名单：application/pdf、image/jpeg、image/png、image/webp
• 单文件大小：≤ 10MB
• 权限：
  • 未绑定时：owner_employee_id、uploaded_by_employee_id、finance/finance_mgr、admin 可访问
  • 绑定后：除以上人员外，报销相关人员（owner/submitter/审批链/财务/admin）可访问
• 文件元数据（用于判重/审计）：
  • file_sha256（必填）
  • invoice_number/invoice_code（可选；齐全时参与判重）

10.3 P2 迁移（MinIO/OSS）

• 替换为对象存储（S3 pre-signed URL）
• 接口与 DB 字段保持不变（storage_path 语义不变）

10.4 invoice_pool 表结构（P0）

字段	类型	说明
id	UUID	主键
owner_employee_id	UUID	费用归属人（决定可见范围与绑定归属）
uploaded_by_employee_id	UUID	上传人（可能是行政代上传）
storage_path	String	本地存储路径（相对路径）
original_name	String	原始文件名
mime_type	String	MIME 类型
file_size	Int	文件大小（字节）
file_sha256	String	文件哈希（必填；用于判重与 OCR 去重）
status	String	pending_ocr/ocr_failed/available/bound/archived
archived_reason	String	used_complete/unused_timeout/manual（仅 archived 有意义）
archived_at	DateTime	归档时间（可空）
linked_reimbursement_id	UUID	绑定到报销单（可空；status=bound 必填）
linked_item_id	UUID	绑定到费用明细（可空）
remarks	String	备注/人工说明（可空）
ocr_provider	String	OCR 提供方（P0 固定 tencent）
ocr_type	String	vat/train/flight/taxi/general
ocr_result_id	UUID	关联 ocr_results（可空）
ocr_attempts	Int	OCR 重试次数（默认 0）
ocr_last_error	String	OCR 最近一次错误（可空）
ocr_completed_at	DateTime	OCR 完成时间（可空）
invoice_code	String	发票代码（可空）
invoice_number	String	发票号码（可空）
invoice_date	Date	开票日期（可空）
seller_name	String	销售方名称（可空）
buyer_name	String	购买方名称（可空）
amount	Decimal	不含税金额（可空）
tax_amount	Decimal	税额（可空）
total_amount	Decimal	价税合计（可空）
is_duplicate_override	Bool	是否为判重例外（默认 false）
override_ref_form_number	String	例外引用的原单号（is_duplicate_override=true 时必填）
override_reason	String	例外原因（is_duplicate_override=true 时必填，≥10 字）
overridden_by	UUID	谁批准的例外（finance_mgr）
created_at/created_by	DateTime/UUID	创建时间/操作者
updated_at/updated_by	DateTime/UUID	更新时间/操作者

10.5 ocr_results（去重 OCR 结果表，P0）

目的：避免同一文件重复计费调用 OCR，同时持久化标准化结果用于复核与复用。

字段	类型	说明
id	UUID	主键
file_sha256	String	文件哈希（与 invoice_pool.file_sha256 对齐）
ocr_provider	String	提供方（P0 固定 tencent）
ocr_type	String	vat/train/flight/taxi/general
result_json	JSON	标准化 OCR 结果（必须保存）
confidence	Int	置信度（可空）
created_at	DateTime	创建时间

唯一约束（P0 定案）：

• UNIQUE (file_sha256, ocr_provider, ocr_type)

10.6 索引与约束（P0 定案）

Prisma Schema 不能直接表达 partial unique index，需要通过 自定义 SQL migration 创建（prisma migrate dev --create-only 后编辑迁移 SQL）。

并发绑定保护（实现约束）：

• POST /api/invoice-pool/:id/bind 必须对目标 invoice_pool 行加行级锁（SELECT ... FOR UPDATE），避免并发双绑。

全局双策略判重（只对已使用历史生效，P0 定案）：

• UNIQUE (file_sha256) WHERE (status = 'bound' OR (status = 'archived' AND archived_reason = 'used_complete')) AND is_duplicate_override = false
• UNIQUE (invoice_code, invoice_number) WHERE invoice_code IS NOT NULL AND invoice_number IS NOT NULL AND (status = 'bound' OR (status = 'archived' AND archived_reason = 'used_complete')) AND is_duplicate_override = false

例外字段完整性（DB check，防漏填）：

• 当 is_duplicate_override = true 时，override_ref_form_number、override_reason、overridden_by 必填，且 char_length(override_reason) >= 10

10.7 API 约定（P0）

• 上传：POST /api/invoice-pool/upload（multipart；入参 file + 可选 owner_employee_id + 可选 ocr_type；默认 ocr_type=general）
  • 上传即创建 invoice_pool 记录并返回 invoice_pool_id
  • OCR 结果命中 ocr_results 时应复用（不重复计费）
• 签名 URL：POST /api/invoice-pool/:id/signed-url（TTL=10m；服务端按 10.2 的规则鉴权）

---

11. 认证与会话（P0）

11.1 登录方式（P0）

• 支持 手机号/邮箱 + 密码 登录
• 验证码仅用于“找回/重置密码”（P0：邮件验证码；短信验证码/SSO 放 P1/P2）

11.2 密码策略（P0）

• 长度：≥12
• 复杂度：必须同时包含 大写 + 小写 + 数字（允许特殊字符但不强制）
• 弱密码拦截：禁止命中弱密码库（Top 10k）
• 错误次数锁定：15 分钟内失败 5 次 → 锁定 30 分钟；管理员可解锁
• 首次登录：必须修改初始密码

11.3 Token 与会话（JWT + Refresh Rotation）

• Access Token：
  • 过期：15 分钟
  • 传输：Authorization: Bearer <token>
  • 存储：仅内存（禁止 localStorage/sessionStorage）
• Refresh Token：
  • 过期：7 天
  • 客户端存储：HttpOnly + Secure + SameSite=Strict Cookie
  • 轮换：每次 refresh 都签发新 refresh，旧 refresh 立即失效
  • 服务端存储：数据库保存 refresh 的哈希（不可明文），并绑定设备信息（deviceFingerprint/ipAddress/userAgent）
• 强制下线：员工 tokenVersion + 1（密码重置/离职/管理员强制下线）使旧 access 立即失效

实现约束（P0 定案）：

• tokenVersion 立即失效机制：
  • Access Token 载荷必须包含 tokenVersion
  • 每次请求服务端必须校验 tokenVersion（从 DB 或缓存读取当前值）
  • 若 Token 中 tokenVersion < DB tokenVersion，立即返回 AUTH_004
• Refresh 重放检测（防止 refresh 泄漏后被持续利用）：
  • 每次 refresh 成功后，旧 refresh 的 hash 必须标记为已使用或直接删除
  • 若检测到"已使用的旧 refresh 被重放"，说明可能存在泄漏：
    • 立即撤销该员工所有有效会话（revoked_at = now()）
    • 员工 tokenVersion + 1
    • 写入 audit_logs（action=REFRESH_REUSE_DETECTED）
    • 返回 AUTH_005 并要求用户重新登录
• Refresh 同站校验（额外防线）：
  • POST /api/auth/refresh 若请求携带 Origin/Referer，则必须与本站域名匹配（按服务端配置的 APP_ORIGIN）
  • 不匹配则拒绝该请求并返回 AUTH_005，同时写入 audit_logs（action=AUTH_REFRESH_ORIGIN_MISMATCH）

11.4 Auth API（P0）

• POST /api/auth/login → 返回 access；refresh 通过 Set-Cookie
• POST /api/auth/refresh → 从 cookie 轮换 refresh，返回新 access
• POST /api/auth/logout → 撤销当前会话并清 cookie
• POST /api/auth/forgot-password（邮件验证码）
• POST /api/auth/reset-password

11.5 auth_sessions（Refresh 会话表，P0）

目的：服务端可撤销 refresh、限制并发会话数、绑定设备信息以支持 Phase 2 异常登录检测。

字段	类型	说明
id	UUID	主键
employee_id	UUID	所属员工
refresh_token_hash	String	refresh 的哈希（不可明文）
device_fingerprint	String	设备指纹（必填）
ip_address	String	登录 IP（必填）
user_agent	String	UA（必填）
created_at	DateTime	创建时间
last_seen_at	DateTime	最近活跃时间（refresh 时更新）
expires_at	DateTime	过期时间（= 7 天）
revoked_at	DateTime	撤销时间（可空）

会话规则（P0 定案）：

• 同一员工最多 5 个有效会话（revoked_at is null AND expires_at > now()）；超过时撤销最旧会话
• 退出登录：撤销当前会话（写 revoked_at）
• 密码重置/离职/管理员强制下线：撤销该员工所有有效会话 + tokenVersion + 1

---

12. 数据安全与审计（P0）

12.1 敏感字段清单

• 员工：银行卡号、身份证号
• 报销：发票/附件文件（可能包含敏感信息）

12.2 脱敏展示规则

• 银行卡：仅显示后 4 位（例：**** **** **** 1234）
• 身份证：前 3 位 + 后 4 位（例：310***********1234）

12.3 加密存储（应用层加密）

• 算法：AES-256-GCM
• 每条记录随机 nonce
• 密钥来自服务端环境变量（P0）；后续可迁移 KMS
• 明确：加密字段不支持按明文检索（禁止为“搜索”而明文存储）

12.4 审计分层（必须写清楚）

• workflow_history：审批链路与流程动作的权威记录（谁在何时对哪个任务做了什么）
• audit_logs（系统审计）：登录/锁定/重置/敏感字段明文查看/权限配置变更/判重例外等安全关键事件

audit_logs 表（建议字段）：

字段	类型	说明
id	UUID	主键
request_id	String	关联请求 ID
actor_id	UUID	操作人
action	String	动作码（如 AUTH_LOGIN_SUCCESS/INVOICE_DUPLICATE_OVERRIDE）
target_type	String	目标类型（如 employee/reimbursement/attachment）
target_id	UUID	目标 ID（可空）
ip/user_agent	String	来源信息
extra	JSON	扩展信息（含变更快照）
created_at	DateTime	时间戳

对“敏感字段变更/授权变更/关键配置变更”，extra.changes 必须包含脱敏前后快照： { changes: { field: { before: masked, after: masked } } }（禁止记录明文）

保留期：至少 1 年。

12.5 审计动作码（P0 最小集）

目的：把“高风险动作”与“关键链路”落到可检索的审计事件上，便于排查与合规追溯。

OCR（发票识别）

• OCR_REQUESTED：发起 OCR 请求（含 ocr_type、file_sha256）
• OCR_SUCCEEDED：OCR 成功（含 ocr_result_id、confidence 摘要）
• OCR_FAILED：OCR 失败（含错误摘要；禁止记录 rawResponse）
• OCR_RETRIED：OCR 重试（含 attempts 与节流结果）

发票池（Invoice Pool）

• INVOICE_POOL_UPLOADED：文件入池（owner/uploaded_by、mime/size/hash）
• INVOICE_POOL_EDITED：人工修正关键字段（extra.changes 记录脱敏前后快照）
• INVOICE_POOL_BOUND：绑定到报销单
• INVOICE_POOL_UNBOUND：从报销单解绑
• INVOICE_POOL_ARCHIVED：人工归档（archived_reason=manual）
• INVOICE_POOL_AUTO_ARCHIVED：系统自动归档（archived_reason=unused_timeout/used_complete）

判重与例外

• INVOICE_DUPLICATE_OVERRIDE：判重例外（必须包含引用原单号 + 原因摘要）

---

13. API 契约与错误码（P0）

本章为 API 契约唯一权威（P0 定案）。目的：前后端联调与测试可直接以此为准，不在实现阶段临场补协议。

13.1 通用响应结构（P0）

• 所有响应必须返回 requestId（可放在响应头 x-request-id，并在 body 同步返回）
• 失败响应结构：

{
  "requestId": "01J....",
  "error": {
    "code": "AUTH_001",
    "message": "用户名或密码错误",
    "details": {}
  }
}

• 成功响应结构（对象）：

{
  "requestId": "01J....",
  "data": {}
}

• 成功响应结构（列表 + 分页）：

{
  "requestId": "01J....",
  "data": [],
  "pageInfo": {
    "page": 1,
    "pageSize": 20,
    "total": 0,
    "totalPages": 0
  }
}

13.1.1 分页 / 排序 / 筛选约定（P0）

目的：前后端统一口径，避免“边开发边发明 query 参数”。

• page：页码（从 1 开始；默认 1）
• pageSize：每页数量（默认 20；最大 100）
• sort：排序（格式：field:asc|desc；多个排序用逗号分隔，例如 sort=created_at:desc,total_amount:desc）
• q：可选的关键字搜索（各接口自行决定是否支持）
• 过滤参数：按接口逐项定义（P0 不引入通用 filter DSL）

13.1.2 字段类型约定（P0）

• UUID：JSON 中一律为 string
• Date：YYYY-MM-DD（业务日期）
• DateTime：ISO 8601（建议带时区，例如 2026-02-06T09:00:00+08:00）
• Decimal/Money：JSON 中一律为 string（禁止用 number，避免精度丢失）

13.2 核心业务 API（P0）

13.2.1 报销单（Reimbursements）CRUD

方法	路径	权限码	说明
POST	/api/reimbursements	expense.create	创建报销草稿（默认 owner_id=me, submitter_id=me；代提交场景可指定 owner，但必须存在有效授权）
GET	/api/reimbursements	expense.view_own（或 expense.view_all）	报销列表（分页/筛选/排序）；服务端按权限自动收敛数据范围
GET	/api/reimbursements/:id	expense.view_own（或 expense.view_all）	报销详情（含 items + 已绑定的发票池条目摘要；可包含当前 pending task 用于“节点文案”展示）
PATCH	/api/reimbursements/:id	expense.edit_own	更新草稿/驳回单（仅允许 status in (draft, rejected)）
DELETE	/api/reimbursements/:id	expense.delete_own	删除草稿（仅允许 status=draft；需删除 items；并自动解绑其绑定的发票池条目（回到 available；不删除发票池文件））

列表筛选建议（P0）：

• status：draft/reviewing/approved/paid/rejected/cancelled
• formNumber：精确匹配
• ownerId / submitterId / departmentId
• reimbursementDateFrom / reimbursementDateTo（业务日期）
• createdAtFrom / createdAtTo（时间戳）

13.2.2 审批待办（Workflow Tasks）

方法	路径	权限码	说明
GET	/api/workflow/tasks	登录即可（服务端鉴权）	待办/已办列表（分页/筛选/排序）；默认只返回“我可处理”的任务（assignee_id=me 或 assignee_role in myRoles）

列表筛选建议（P0）：

• status：默认 pending；可选 completed/rejected/cancelled/skipped
• entityType：默认 reimbursement
• reimbursementId（便于从报销详情页拉取当前任务/历史）

13.2.3 流程动作（Workflow / Reimbursement Actions）

方法	路径	权限码	说明
POST	/api/reimbursements/:id/submit	expense.submit	提交报销并发起工作流（生成单号、创建 instance/task/history）
POST	/api/reimbursements/:id/withdraw	expense.withdraw	撤回：取消流程实例并回到草稿（仅审批人未处理前）
POST	/api/workflow/tasks/:taskId/approve	expense.approve	通过当前任务并推进
POST	/api/workflow/tasks/:taskId/reject	expense.approve	驳回并终止流程
POST	/api/workflow/tasks/:taskId/return	expense.approve	退回：终止当前实例（instance=terminated）并回到草稿；申请人修改后需重新 submit 才会进入新一轮
POST	/api/workflow/tasks/:taskId/transfer	expense.transfer	转审（reason≥10，链≤3）
POST	/api/reimbursements/:id/pay	expense.finance.pay	付款标记（approved → paid）

13.2.4 员工与组织（Employees / Departments，P0）

方法	路径	权限码	说明
GET	/api/me	登录即可	获取当前登录员工信息（含 role_codes；前端用于菜单与数据范围判断）
GET	/api/employees	system.users	员工列表（分页/筛选/排序）
GET	/api/employees/:id	system.users（或 expense.view_own 仅本人）	员工详情
POST	/api/employees	system.users	创建员工（初始密码策略见第 11 章；首次登录强制改密）
PATCH	/api/employees/:id	system.users	更新员工信息（敏感字段加密/脱敏与审计见第 12 章）
POST	/api/employees/:id/archive	system.users	员工离职/归档（禁止登录并强制下线，见 4.1.2/11.3）
GET	/api/departments	登录即可	部门树/列表（默认隐藏归档部门，可通过 query 开启）
POST	/api/departments	system.users	创建部门
PATCH	/api/departments/:id	system.users	更新部门
POST	/api/departments/:id/archive	system.users	归档部门（归档约束见 3.2）

13.2.5 认证（Auth，P0）

方法	路径	权限码	说明
POST	/api/auth/login	N/A	登录：返回 access token；refresh token 通过 Set-Cookie 写入 HttpOnly cookie（见 11.3）
POST	/api/auth/refresh	N/A	刷新：轮换 refresh cookie，返回新 access token（refresh rotation + 重放检测见 11.3）
POST	/api/auth/logout	登录即可	退出：撤销当前会话并清 cookie
POST	/api/auth/forgot-password	N/A	忘记密码：发送邮件验证码（P0）
POST	/api/auth/reset-password	N/A	重置密码：验证码校验 + tokenVersion + 1 强制下线（见 11.3）

13.2.6 发票池（Invoice Pool）+ OCR（P0）

方法	路径	权限码	说明
POST	/api/invoice-pool/upload	invoice.upload	上传票据文件入池（multipart；入参 file + 可选 owner_employee_id + 可选 ocr_type；默认 ocr_type=general；返回 invoice_pool_id + 初始 status）
GET	/api/invoice-pool	登录即可（服务端鉴权）	发票池列表（分页/筛选/排序）；默认只返回与本人相关（owner 或 uploaded_by），finance/admin 可查看全量
GET	/api/invoice-pool/:id	登录即可（服务端鉴权）	发票池详情（含 OCR 摘要字段）
PATCH	/api/invoice-pool/:id	登录即可（服务端鉴权）	更新备注/人工修正关键字段（如 invoice_code/number/date/amount）；允许将 ocr_failed 条目“人工确认”转为 available
POST	/api/invoice-pool/:id/retry-ocr	登录即可（服务端鉴权）	重试 OCR（仅 status=ocr_failed；次数/频控见下）
POST	/api/invoice-pool/:id/bind	登录即可（服务端鉴权）	绑定到报销单（1:1；并发与判重硬校验在此发生）
POST	/api/invoice-pool/:id/unbind	登录即可（服务端鉴权）	从报销单解绑（仅草稿/驳回可解绑；解绑后回到 available）
POST	/api/invoice-pool/:id/archive	登录即可（服务端鉴权）	手工归档（仅未绑定；归档为 archived_reason=manual）
POST	/api/invoice-pool/:id/signed-url	登录即可（服务端鉴权）	获取票据文件签名 URL（TTL=10m；服务端按第 10 章规则鉴权）

上传归属权限链（P0 定案）：

• 当 owner_employee_id != 当前登录用户 时：
  • 若当前登录用户持有 system.users（hr/admin）→ 允许
  • 若当前登录用户持有 expense.proxy_submit 且角色包含 administration → 必须存在有效 delegation_grants（principal=owner, delegate=当前用户, scope 包含 reimbursement_submit）
  • 否则拒绝（PERM_001）

绑定并发语义（P0 定案）：

• POST /api/invoice-pool/:id/bind 必须在事务内对目标 invoice_pool 行执行 SELECT ... FOR UPDATE（行级锁）。
• 若已是 bound 或 linked_reimbursement_id 非空：返回 409 VALID_005（发票已被其他报销单占用/绑定）。
• 若命中全局判重唯一约束：返回 409 VALID_003（发票判重命中）。

retry-ocr 次数与频控（P0 固定值）：

• 次数：ocr_attempts <= 3；超过返回 429 VALID_006（OCR 重试次数超限）。
• 间隔：同一条目两次重试间隔 >= 60s；过于频繁返回 429 VALID_007（OCR 重试过于频繁）。

13.3 配置读取 API（P0 只读）

方法	路径	权限码	说明
GET	/api/expense-types?enabled=true	登录即可	获取启用费用类型（下拉选项）
GET	/api/approval-rules?enabled=true	登录即可	获取启用审批规则（便于运维/排查）
GET	/api/document-sequences/reimbursement	system.settings（可选）	查看报销单号规则配置

13.4 文件与签名 URL（P0）

上传与文件预览/下载统一归口到“发票池”模块，避免 files 与 invoice_pool 双源。

方法	路径	权限码	说明
POST	/api/invoice-pool/upload	invoice.upload	上传票据文件入池（见 13.2.6）
POST	/api/invoice-pool/:id/signed-url	登录即可（服务端鉴权）	获取签名 URL（TTL=10m；服务端校验“是否与票据相关/是否有权限”）

13.5 Delegation Grants API（P0）

方法	路径	权限码	说明
GET	/api/delegation-grants	登录即可	默认返回与本人相关（principal/delegate）；system.users 可查询任意
POST	/api/delegation-grants	登录即可	本人创建：principal=自己；代维护需 system.users；所有变更写入 audit_logs
POST	/api/delegation-grants/:id/revoke	登录即可	本人撤销：principal=自己；代维护需 system.users；所有变更写入 audit_logs

实现约定（P0）：

• GET /api/delegation-grants 响应建议内嵌 principal/delegate 的员工摘要（如 id/employee_no/name/department_id），用于“行政代提交选择人员”场景，避免前端额外拉取员工目录。
• 默认只返回“当前仍有效”的授权（revoked_at is null 且时间在有效期内）；如需查看历史可通过 query 显式开启（例如 includeInactive=true）。

13.6 错误码（P0 最小集）

13.6.1 认证（Auth）

• AUTH_001：用户名或密码错误（401）
• AUTH_002：账号已锁定（423）
• AUTH_003：账号已离职/禁用（403）
• AUTH_004：Access Token 已过期/无效（401）
• AUTH_005：Refresh Token 无效/已撤销（401）

13.6.2 权限（Permission）

• PERM_001：无权限（403）
• PERM_002：不在审批范围/非当前处理人（403）

13.6.3 校验（Validation）

• VALID_001：参数校验失败（400）
• VALID_002：转审原因不足 10 字（400）
• VALID_003：发票判重命中（409）
• VALID_004：发票重复例外被禁止（原单已打款/待打款）（409）
• VALID_005：发票已被其他报销单占用/绑定（409）
• VALID_006：OCR 重试次数超限（429）
• VALID_007：OCR 重试过于频繁（429）

---

14. 非功能需求

类别	要求
响应式	PC + 移动端（响应式 Web）
性能	页面加载 <2s，API 响应 <500ms（P95）
安全	JWT（access+refresh rotation）、RBAC 权限码、审计日志、敏感字段加密与脱敏
部署	Docker + Nginx（反向代理），域名 oa.hyinda.com

---

15. 数据模型概览（高层）

erDiagram
    departments ||--o{ employees : contains
    employees ||--o{ employee_roles : assigns
    employees ||--o{ delegation_grants : principal
    employees ||--o{ delegation_grants : delegate

    employees ||--o{ auth_sessions : has
    employees ||--o{ audit_logs : writes

    employees ||--o{ reimbursement_forms : submits
    employees ||--o{ reimbursement_forms : owns
    reimbursement_forms ||--|{ reimbursement_items : has
    reimbursement_items }o--|| expense_types : uses

    employees ||--o{ invoice_pool : owns
    employees ||--o{ invoice_pool : uploads
    ocr_results ||--o{ invoice_pool : caches
    reimbursement_forms ||--o{ invoice_pool : binds
    reimbursement_items ||--o{ invoice_pool : links

    workflow_definitions ||--o{ workflow_instances : defines
    reimbursement_forms ||--o{ workflow_instances : starts
    workflow_instances ||--o{ workflow_tasks : has
    workflow_instances ||--o{ workflow_history : logs

    reimbursement_forms ||--o{ approval_transfers : transfers

说明：上图为概念关系图，具体字段以各章节表结构为准。

---

16. 迭代计划

Phase 1（核心 / P0）

• 技术栈确定（Fastify + Prisma + PostgreSQL）
• 员工与组织（含归档约束、角色集合）
• 权限码体系与服务端校验（RBAC）
• 工作流引擎（4 表）落库与服务层事务
• approval_rules（预置 3 条）+ 审批链生效
• 转审（reason≥10，链路≤3）
• document_sequences 单号规则（BX-YYYYMMDD-0001）
• 费用类型 expense_types（默认启用 37 项）+ 下拉动态加载
• 发票池上传（本地存储 + 签名 URL）+ SHA256 + 腾讯云 OCR（结果持久化/去重/重试；不阻塞提交）+ 双策略判重（bind/submit 生效）+ 例外审计
• 报销单 CRUD + 提交/撤回/审批/付款标记
• 站内通知 + 邮件

Phase 2（扩展 / P1-P2）

• OCR 能力增强（更多票种/批量处理/队列与更完整的失败重试策略）
• 企微/钉钉通知
• 报表导出
• 对象存储（MinIO/OSS）
• 工作流扩展到其他实体（请假/采购等）

---

附录 A：系统默认费用类型（P0：37 项启用）

来源：shenzhou-business-suite/supabase/seed.sql（启用 35 项）+ hyb-oa 补齐启用 utilities/rent（2 项）。

code	name	category	sort_order	account_code_default	description
transport_long	长途交通费	travel	101	5102-01	飞机、火车、长途大巴等城市间交通费用
accommodation	住宿费	travel	102	5102-01	出差期间酒店、宾馆住宿费
meal_allowance	伙食补贴	travel	103	5102-01	出差期间伙食补助
transport_city	市内交通费	travel	104	5102-01	出差地或日常公事打车、公交费
rd_material	研发直接材料	rd	201	5102-07	研发专用的元器件、耗材、PCB打样等
rd_test	研发测试试验费	rd	202	5102-07	第三方检测、环境试验费
rd_service	研发技术服务费	rd	203	5102-07	外包开发、技术咨询服务
rd_sample	研发样品/样机费	rd	204	5102-07	原型机、模型制作费用
hydro_calibration	水声设备标定费	rd	205	5102-07	水听器、换能器等核心设备标定
test_site_rental	试验场地租赁费	rd	206	5102-07	水池、消声室、湖试场地租赁
rd_software	研发软件订阅	rd	207	5102-07	水声仿真、CAD设计软件(≤5000元)
rd_patent	专利申请/维护费	rd	208	5102-07	发明专利代理费、年费
raw_material	原材料	production	301	1403	生产用主材、辅材
prod_direct_material	生产成本-直接材料	production	302	5001-01	生产过程直接消耗的材料
mfg_consumable	制造费用-物料消耗	production	303	5101-02	车间消耗性物料
outsourcing	外协加工费	production	304	5001-03	外壳加工、组件代工等
mfg_repair	生产设备维修费	production	305	5101-03	车间仪器设备维修保养
office	办公费	office	401	5102-02	文具、纸张、打印耗材等
communication	通讯费	office	402	5102-03	话费、宽带、网络服务费
property	物业费	office	403	5102-15	物业管理、停车费
vehicle	车辆费	office	404	5102-10	油费、过路费、保养(私车公用需附协议)
welfare	福利费	office	405	5102-19	下午茶、团建、礼品(不超工资14%)
maintenance	维修费	office	406	5102-09	办公电脑、空调、设施维修
training	培训费	office	407	5102-05	员工外部培训、购书
software	软件服务费	office	408	5102-02	Office/Adobe/SaaS订阅(非研发)
express	快递物流费	office	409	5102-02	样品寄送、文件快递
utilities	水电费	office	410	5102-14	办公场地水电费、能耗费
rent	房租租赁费	office	411	5102-06	办公室/设备租赁费
entertainment	业务招待费	business	501	5102-04	客户宴请、礼品(注意限额)
meeting	会议费	business	502	5102-13	会议场地租赁、茶歇
marketing	市场推广费	business	503	5101-01	展会、画册制作、广告
consulting	咨询服务费	business	504	5102-08	法律顾问、咨询费
consulting_audit	代账/审计费	business	505	5102-08	记账报税、年度审计费
fixed_assets	固定资产	assets	601	1601	单价≥2000元 + 使用年限≥1年
low_value_consumables	低值易耗品	assets	602	1411	工具、小电器(<2000)
bank_fees	银行手续费	other	701	5103-01	转账手续费、账户维护费
other	其他合规费用	other	901	5102-99	无法归类的小额费用

附录 B：Legacy 费用类型（禁用，迁移预留）

code	name	enabled	note
meal	旧-餐费	❌	兼容历史/迁移预留，P0 不在下拉显示
rd	旧-研发费	❌	兼容历史/迁移预留，P0 不在下拉显示
transport	旧-交通费	❌	兼容历史/迁移预留，P0 不在下拉显示

附录 C：P0 验收用例（最小集）

每条用例需覆盖：输入 → 状态流转 → 权限结果 → 日志记录点（workflow_history / audit_logs）。

1. 审批规则匹配（3 档）

   • 输入：total_amount=100/1000/6000
   • 预期：分别命中“小额/中额/大额”规则，生成对应审批链（manager→finance / manager→finance_mgr / manager→ceo→finance_mgr）

2. 工作流实例与任务创建

   • 输入：员工提交草稿
   • 预期：创建 workflow_instances（pending）+ 首个 workflow_tasks（pending）+ workflow_history（start）；报销状态进入 reviewing

3. 任务推进（approve）

   • 输入：审批人执行 approve
   • 预期：当前 task completed；创建下一 task（若存在）；或实例 approved 并将报销状态置为 approved

4. 驳回（reject） vs 退回（return）

   • 输入：审批人执行 reject/return（带 comment）
   • 预期（reject）：实例 rejected；报销状态 rejected；history 记录 reject；申请人可编辑后再次 submit
   • 预期（return）：实例 terminated；报销状态回到 draft；所有 pending task cancelled；history 记录 return；申请人修改后再次 submit

5. 撤回（withdraw）

   • 输入：申请人在审批人未处理前撤回
   • 预期：实例 cancelled；所有 pending task cancelled；报销状态回到 draft；history 记录 withdraw

6. 转审（transfer）约束与证据

   • 输入：当前审批人转审（reason 少于/不少于 10 字）
   • 预期：不足 10 字返回 VALID_002；满足时：
     • workflow_tasks.assignee_id 更新
     • 插入 approval_transfers
     • 插入 workflow_history（action=transfer，payload 含 from/to/reason）

7. 状态 vs 节点一致性

   • 输入：报销单处于 reviewing
   • 预期：页面“当前节点文案”来自 workflow_tasks 的 pending 任务（而非 DB status 细分）

8. 费用类型启用/禁用语义

   • 输入：禁用某费用类型
   • 预期：新建报销下拉不再显示；历史报销仍可展示该类型名称（不回退为 code）

9. 发票池入池 + OCR 结果持久化 + 去重复用（ocr_results）

   • 输入：上传同一文件两次（同 file_sha256），OCR 类型相同
   • 预期：
     • 第二次上传命中 ocr_results（不重复计费调用 OCR）
     • invoice_pool 记录复用 ocr_result_id 并写入关键字段摘要（invoice_code/number/date/amount 等）
   • 日志：写 INVOICE_POOL_UPLOADED；如触发 OCR，写 OCR_REQUESTED/OCR_SUCCEEDED（禁止落库 rawResponse）

10. OCR 失败与重试（次数/频控）

• 输入：制造 OCR 失败 → 多次调用 POST /api/invoice-pool/:id/retry-ocr
• 预期：
  • ocr_attempts 递增；失败条目保持 status=ocr_failed
  • 超过 3 次返回 VALID_006（429）
  • 60 秒内重复重试返回 VALID_007（429）
• 日志：写 OCR_FAILED/OCR_RETRIED（错误摘要即可）

11. 发票池绑定并发冲突（行锁 + 409）

• 输入：两个报销草稿同时 bind 同一张发票池条目
• 预期：一个成功，一个返回 VALID_005（409）；服务端在 bind 事务内对 invoice_pool 行 SELECT ... FOR UPDATE

12. 全局判重与例外（绑定/提交阶段硬校验）

• 输入：已有“使用完成并归档”的发票（status=archived, archived_reason=used_complete），再尝试用相同 file_sha256 或相同 invoice_code+invoice_number 绑定/提交
• 预期：
  • 普通用户返回 VALID_003（409）
  • finance_mgr 可执行判重例外，必填原单号+原因（≥10）；若原单处于 approved/paid 则返回 VALID_004
• 日志：例外必须写 audit_logs（INVOICE_DUPLICATE_OVERRIDE）

13. 90 天游离自动归档不参与全局判重

• 输入：一张发票池条目 90 天未绑定自动归档（archived_reason=unused_timeout），再上传/绑定同一张文件
• 预期：不因“未使用的超期归档”触发全局判重拦截；仅当新条目被使用并进入 bound/used_complete 后才进入判重历史

14. 签名 URL 鉴权与过期

• 输入：非票据相关人员请求 POST /api/invoice-pool/:id/signed-url；或使用过期 URL
• 预期：无权获取（403/PERM_001）；过期访问失败；必要时写入 audit_logs

15. 行政代上传授权链（owner ≠ uploaded_by）

• 输入：行政为员工 A 上传票据（owner_employee_id=A, uploaded_by=行政）
• 预期：
  • 有有效 delegation_grants（principal=A, delegate=行政, scope 含 reimbursement_submit）时允许上传
  • 无授权时拒绝（403/PERM_001）
• 补充：hr/admin（持 system.users）可在无 delegation 的情况下代维护上传；所有代维护必须写入 audit_logs

16. 敏感字段脱敏（masking）

• 输入：读取/变更员工敏感字段（银行卡/身份证）并查看相关响应与审计
• 预期：对外响应仅返回脱敏格式；audit_logs.extra.changes 仅包含脱敏前后快照（禁止明文）

17. 代提交审批链解析（owner 基准）

• 输入：行政为员工 A 代提交报销单（submitter=行政，owner=A）
• 预期：首节点审批人按 A 的直属经理 解析（而非行政的直属经理）；workflow_instances.context_data 包含 owner_id/department_id

18. *_own 语义（owner 或 submitter）

• 输入：行政查看/协助处理其代提交的单据；owner 编辑草稿/驳回单
• 预期：当 owner_id=me OR submitter_id=me 时允许 view_own；draft/rejected 允许 edit_own；仅 draft 允许 delete_own；withdraw 仍需满足“审批人未处理前”等状态约束