# 报销费用口径与票据明细门禁 ## Goal ### 当前交付口径（2026-09-09，最终自检收口） - 本次选票自动建明细与集中分类已在独立副本实现并完成分层本地验证；不是下文早期记录所述“尚未实现”。尚未独立复核、提交或部署。 - 已批准本地实现费用类型可空迁移，未知类型与空说明只用于可编辑草稿，提交前阻断；生产迁移仍须单独批准。最新接口与回滚合同见 design 的“最小实施与已批准的本地持久化合同”。 - assets 事前批准依据目前是字段与提示，不是保存/提交硬门禁。本次保持实际行为，不新增硬门禁。下文 R3、R5 及旧验收勾选中的硬门禁表述属于历史设计/记录，不能作为当前已实现或已验结论；本次批量分类验收是保留依据字段、不改金额及票据关系。 - 下文 B1/B2 历史清单不代表本次验收。当前证据分为真实隔离数据库/认证/队列/浏览器（OCR provider 为 mock），以及指定样票单独调用腾讯 OCR；没有同一次真实腾讯到候选浏览器的整链证据。付款和退回删除属于其他既有 task，未在此完成。 ### 2026-09-09 分类交互补充（用户已采纳） - 一事一单：同一次出差可在同一张报销单包含火车票和住宿，不为费用分类强制拆单。报销单场景与明细费用类型是不同层级，不把“日常报销”等宽泛场景当作精确费用类型。 - 后台保留逐明细费用类型，用于材料要求、费用标准与财务统计；前台不得要求每条明细重复手选，不让员工选择会计科目。 - 可靠识别的类型自动填入已启用类型，生成的明细可编辑，无逐条确认、整批二次确认或已确认标记。 - 无法确定的类型集中提示并支持对用户选中的同类明细一次批量设置。正常已分类明细不被未识别项拖入重复填写；用户手工修正后不被 OCR 回调、刷新或后续默认值覆盖。 - 只有用户明确选择的具体费用类型才可作为相应所选明细的默认值；不把“差旅”“日常”或销售方名称推断为精确费用类型，不因餐饮票面就直接判为业务招待。 - 添加与分类是不同动作：分类不得增加一次发票关联步骤，也不要求用户逐字段确认 OCR 已填值。提交前检查仍缺少的必要信息，保留原审批、费用标准、assets 批准依据字段/提示与票面金额门禁，不宣称 assets 已有硬门禁。 - 先落实交互再裁定持久化设计；撤回“先请用户批准类型可空迁移”的推进顺序。本次产品取向确认不是数据库迁移、生产写入或部署授权。 验收增加：同单火车票加住宿、同类多条一次设类、混合类型不整单覆盖、未知类型集中处理、手改类型刷新保留、已识别项零确认、停用类型与非参与人拒绝、批量改为 assets 时保留批准依据字段及实际提示规则。仍需验证刷新后的待处理信息与服务端提交阻断，不能仅有前端临时状态就宣称完整支持。 ### 2026-09-09 已确认后续流程：选票自动生成明细 用户明确选择省操作的默认流程，并已批准按确认范围实施。本节替换此前“待关联区域→手工建明细→再关联”的默认方案；不新建 task。当前产品代码尚未实现，提交、部署与生产写入不由此自动授权。下文原 B1/B2 要求与历史已验结果保留；涉及自动建明细的后续目标以本节及最新分类补充为准，不能拿旧禁令否定已确认的新交互，也不能恢复旧版按金额猜测的静默自动匹配。 - 报销页点击“添加发票”打开“我的发票”面板，桌面弹窗、手机全屏面板，不跳离报销单、不丢填写内容。票据中心/发票池是同一数据来源，不复制第二份资料；允许提前存票，报销时再选。 - 面板支持多选已有可用票、批量上传新 PDF；腾讯真实 OCR 默认启用，上传自动识别。新上传且识别成功、可用的票默认勾选，用户可取消；未点“添加到报销单”前不创建明细，不能因 OCR 后台完成或刷新自动提交选择。 - 从整单入口点击“添加到报销单”后，一张所选发票生成一条可编辑费用明细并自动关联；多选批量生成，不按相同金额或票面多行擅自合并/拆分，不让员工再手工关联一次。 - 用户补充确认：自动填充的明细直接保存为可编辑草稿，不增加逐条确认或整批二次确认，不设置“已确认”标记作为提交前置；用户可主动修正，只有必填缺失或现有业务校验不通过时提示处理。该要求不取消报销本身的“提交审批”动作。 - 价税合计预填报销金额；开票日期可作为发生日期的可编辑初值，不能假定必然相同；票面项目生成可编辑说明。费用类型仅可靠匹配启用类型时推荐，不确定时只要求补必要字段，不凭空填其他费用类型或编码，不强迫逐字段重复确认。 - 从已有明细入口添加发票时，明确目标，直接关联到该明细且不创建另一条明细；允许同一笔支出的多票关联一条明细，不把同一票分配多条明细，不擅自改写原明细日期/类型/申报金额。 - 正常页面在明细内显示“发票 N 张”和预览入口，不展示绑定/关联技术状态。只有识别异常、历史未关联、需票明细缺票等需要动作时显示具体提示和就地补救，手动修复不是默认必经步骤。 - 上传成功不等于 OCR 成功，OCR 成功不等于用户已把票加入报销。识别中/失败/缺字段/重复/占用均要逐票可恢复；刷新或返回能找到已上传票和本单已保存明细，不要求重传或重复 OCR。 - 归属、状态、查重、有效占用、明细归属、申报金额与原提交门禁保持服务端强约束。批量、双击、超时重试、跨单并发不得产生重复明细、孤立明细或一票多占用。 - OCR 关闭/误配视为需要处理的系统异常，不作为本轮正常交付路径；是否实际启用及识别成功须核配置和调用证据，不以用户陈述或旧数据库 provider 默认值冒充已验证。不自动启用 mock，不擅自变更生产密钥、开关或发送未经授权票据。 - 必测空单开始的“上传新票/选择旧票→自动生成明细并关联→核对补齐→提交”及提前存票、多选、刷新、已有明细加票、异常重试、退回修改、删除后重新使用；保留非参与人/重复票/已报销/并发等反例。 把现有自创或含糊的费用类型收敛为财务可理解的企业费用口径，明确发票要求和 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 关闭时 DB `force_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 通过。 - [x] 费用类型逐条按“改名”或“停用+新建”执行；历史单据无丢失，新建/编辑列表不显示停用类型。 - [x] assets 明细在 PC、移动端和服务端均强制填写事前批准依据，提示明确 `2,000 元/条明细`是选类门槛而非会计固定资产标准。 - [x] 办公用品明细金额达到 `2,000 元`时，员工端和财务审核视图均显示非阻断类型不一致提示，提交仍可继续且服务端不自动改类。 - [x] 两项补助 `requires_invoice=false`，其他首期启用类型为 true；无票补助可提交且不会触发票面金额门禁。 - [x] B2 flag 三件套完整、默认关闭；关闭状态保持当前提交兼容，开启状态关闭自动建明细并执行强关联/金额门禁。 - [x] 每张有效发票关联一条明确明细，不同日期/支出必须拆分；同日同类型同一支出允许多票关联。 - [x] 需票明细缺票或申报高于关联票面合计时逐条阻断，低于票面时保留差异核验信息。 - [x] flag 关闭后既有关联数据保持不变，不进行数据回滚。 - [x] owner、submitter、财务/管理员只读边界和 `precheck` 对象授权不回归。 - [ ] 财务科目映射由财务负责人提供并在 task 内记录回填结果；没有正式科目表时保持 null，不虚构编码。 - [x] 聚焦单测、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`。