9.3 KiB
9.3 KiB
报销费用口径与票据明细门禁
Goal
把现有自创或含糊的费用类型收敛为财务可理解的企业费用口径，明确发票要求和 assets 个人报销例外条件；同时建立可核验的票据—明细关系与申报金额门禁，避免多日期、多支出、多张发票被合并为无法复核的一条笼统明细，并通过默认关闭的双闸门保护现有唯一真实报销链路。
Background and Confirmed Facts
ExpenseType已有enabled、description、account_code_default，但没有requires_invoice；本任务必须新增 migration。- 当前种子费用类型的
account_code_default全部为空，不能由开发人员自行编造会计科目编码。 - 现有 feature flag 是 env、
FEATURE_FLAG_KEYS白名单和 DB 记录三件套；env 关闭时 DBforce_on也不能生效。 - 当前多明细发票匹配允许金额无法唯一匹配时自动创建明细；这与“员工明确选择明细、每张有效票据可核验”目标冲突。
- 伙食补助费和市内交通补助费按天包干且不要求发票；数量/天数乘算能力不在本任务内。
- assets 类当前只提示报销完成后人工登记资产，没有“事前批准”结构化证据。
Scope
- B1：费用类型 schema、历史兼容主数据、员工可读说明、
requires_invoice与 assets 事前批准依据。 - B2：明确票据—明细关系、停止静默自动建明细、按需票明细执行金额门禁，以及默认关闭的分级启用机制。
- PC、移动端、服务端、Prisma migration、种子/配置、测试与现有业务事实源同步纳入同一交付合同。
Requirements
R1 费用类型与历史兼容
business_client_meal保持 code 不变，将名称从“客户招待”改为“业务招待费”；历史单据追溯显示新名称，视为同一概念的术语纠正。- 停用
business_training“培训会议”，新建“会议费”和“培训费”两个独立类型；历史单据继续显示原类型，新报销不能再选择已停用类型。 - 停用
assets_it_hardware“IT 硬件”；低值配件使用既有“办公用品”，需登记资产的办公电子设备使用新类型“办公电子设备”。历史单据保持原类型名称。 - 停用均复用
enabled=false模式，不删除类型、不重写历史明细外键。 - 逐项补充面向员工的
description，说明适用范围和必要材料；不得把内部 category/code 当作员工文案。
R2 发票要求与会计科目
ExpenseType新增requires_invoice，默认true；“伙食补助费”和“市内交通补助费”明确为false，其余首期启用类型为true。requires_invoice=false只免除发票要求，不免除业务说明、补助算式、审批或其他必要附件。account_code_default不填猜测值。财务负责人应在 B1 生产启用前提供现行会计科目映射；若届时仍无法提供，本任务保留 null 并在同一 task 留下具名责任角色、缺口和回填日期，不以虚构编码阻塞材料门禁。
R3 assets 个人报销例外
- assets 类允许个人报销，但属于经事前批准的例外，不作为普通日常采购入口。
- 采用低成本方案：
ReimbursementItem增加单一结构化“事前批准依据”字段；选择 assets 类时必须填写批准人、批准时间和可核验的简短依据，服务端在保存和提交时校验，PC/移动端合同一致。 - 采购申请关联不纳入本任务；未来如需替代自由文本，另行设计与
PurchaseRequest的审计关联。 - 员工按单条明细金额区分“办公用品”和“办公电子设备”：
2,000 元及以上通常选择“办公电子设备”，低于2,000 元通常选择“办公用品”。该阈值只用于内部选类和资产登记提示，不等同于会计固定资产确认标准。 - 阈值同时写入费用类型
description和表单提示；在数量/单价模型暂缓期间，一条明细应是一件或一批同日、同类、同一业务支出的物品，多件同类物品应分开记载，以便按本条明细金额判断。 - 明细金额达到
2,000 元但选择“办公用品”时，员工端和财务审核视图均显示非阻断提示：“该金额通常应选择办公电子设备并填写事前批准依据”；提示不得自动改类型或阻断提交，财务仍按实际物品性质复核。
R4 票据—明细强关联
- 每张有效发票必须显式关联到一条费用明细；员工在上传/绑定时明确选择目标明细。
- B2 启用后关闭“无法唯一匹配时自动新建明细”；服务端不得在前端要求明确选择的同时继续静默建明细。
- 一条明细只表达同一费用类型、同一发生日期和同一业务支出；采购物品还应是一件或一批同类物品。不同日期、不同支出或需要分别判断
2,000 元设备提示的多件物品必须拆分。多张同日、同类型且同一业务支出的发票可以关联同一明细。 - 发票、明细及关联变更保留既有审计和权限边界；非参与人不得借新入口维护他人报销。
R5 申报金额门禁
- 仅对
requires_invoice=true的明细比较申报金额与其关联有效发票票面合计。 - 无票补助不参与票面金额比较，不得因票面合计为 0 阻断正数补助。
- 需票明细未关联有效发票，或申报金额高于关联票面合计时，B2 启用状态下阻断提交并返回逐条可操作提示。
- 申报金额低于票面合计允许提交，但必须保留现有差异说明/财务核验信息；退款、折扣、他人承担等不得重复报销。
- 历史草稿不批量改写；在 B2 开启后再次提交时按新门禁补齐关联、差异说明和 assets 批准依据。
R6 分级启用与回退
- B1 schema、主数据、字段和展示随代码部署生效，但不得主动阻断不涉及 assets 的既有提交路径。
- B2 的自动建明细关闭、强关联和金额提交门禁由新增 feature flag 控制，必须接入 env 配置、
FEATURE_FLAG_KEYS白名单和 DB 记录，初始保持 env hard-off / DB force-off。 - 开启前必须满足：owner 正常提交基线；两项无票补助不被阻断；多票关联正确；申报金额超票面能准确阻断；历史草稿可补齐后提交；关闭 flag 能立即恢复旧提交门禁；合成或专用账号验证无越权副作用。
- 关闭 flag 只回退提交门禁和自动匹配行为选择，不删除、不解绑、不回退已经建立的票据—明细关联数据。
- B2 的生产开启属于独立配置写入，必须单独批准并完成角色化公网检查。
Acceptance Criteria
- migration 安全新增
ExpenseType.requires_invoice和明细事前批准依据字段，既有数据有确定默认值且 Prisma validate/status 通过。 - 费用类型逐条按“改名”或“停用+新建”执行；历史单据无丢失，新建/编辑列表不显示停用类型。
- assets 明细在 PC、移动端和服务端均强制填写事前批准依据，提示明确
2,000 元/条明细是选类门槛而非会计固定资产标准。 - 办公用品明细金额达到
2,000 元时，员工端和财务审核视图均显示非阻断类型不一致提示，提交仍可继续且服务端不自动改类。 - 两项补助
requires_invoice=false，其他首期启用类型为 true；无票补助可提交且不会触发票面金额门禁。 - B2 flag 三件套完整、默认关闭；关闭状态保持当前提交兼容，开启状态关闭自动建明细并执行强关联/金额门禁。
- 每张有效发票关联一条明确明细，不同日期/支出必须拆分；同日同类型同一支出允许多票关联。
- 需票明细缺票或申报高于关联票面合计时逐条阻断，低于票面时保留差异核验信息。
- flag 关闭后既有关联数据保持不变，不进行数据回滚。
- owner、submitter、财务/管理员只读边界和
precheck对象授权不回归。 - 财务科目映射由财务负责人提供并在 task 内记录回填结果；没有正式科目表时保持 null，不虚构编码。
- 聚焦单测、API 集成、PC/移动 Playwright、Prisma validate、前后端类型/构建、Trellis governance 和 migration 静态/只读检查通过。
Out of Scope
- 数量、天数、单价自动乘算和差旅主线扩建。
- B3 财务一页式审批工作台及其行内费用标准提示恢复。
- 强制关联采购申请、自动建资产卡、会计凭证、总账或 ERP 对接。
- 处理
BX-20260828-0017真实单据或其他生产报销。 - 在本任务部署授权中推定 B2 flag 开启授权。
Test Plan
- Prisma：migration review、
npm run prisma:validate、existing-data migration fixture、pre/post migration status。 - 后端：费用类型映射、assets 字段校验、bind/submit 强关联、金额边界、无票补助、flag on/off、历史草稿和权限负例。
- 前端：PC/移动费用类型提示、事前批准依据、明确选择明细、逐条错误展示和非参与人只读回归。
- 回归：报销创建/编辑/提交、invoice pool bind/unbind、OCR 自动匹配、差旅补助、材料预览、付款准备相关聚焦套件。
- 全局：server/client typecheck/build、Trellis governance、docs audit、
git diff --check。