hyb-oa/.trellis/tasks/08-04-reimbursement-small-team-form-validation/prd.md

小团队报销填报与校验完善

Goal

面向公司内部 5–10 人使用场景，在不扩展为通用费控产品的前提下，完善普通报销填报、提交预检和证据提示，使员工容易填写、审批人看得懂、财务能够核对、付款后能够追溯。

Background and confirmed facts

• 系统已有报销单、明细、PDF 发票、补充附件、审批、付款批次和资产台账主链路。
• ReimbursementForm.total_amount 已由明细新增、修改、删除操作自动重算；打印页已有明细合计，但 PC 和手机详情的明细区域没有就地合计。
• 普通报销 PATCH 已支持修改 reimbursementDate 和 description，前端目前没有通用的事由/日期编辑入口。
• 当前提交只校验总金额非负和整单至少一张发票，不能在服务端可靠阻止空明细、零金额明细或陈旧总额进入审批。
• 发票已有可选明细关联；补充附件当前属于整单。本任务不引入发票多对多关系或附件明细关联。
• 费用类型已有 assets 类别；资产事实源要求“资产候选 + 管理员人工建卡”，不得因报销提交、审批或付款自动生成资产卡。
• 本轮讨论已决定不增加“历史费用补报”标识。票据新旧由费用日期、发票日期和提交日期推导。

Scope

• 报销详情 PC、手机的明细合计和普通报销事由/日期编辑。
• 报销明细正金额校验、提交时权威总额重算。
• 180/365 天票据时效配置及超期、跨年度非阻断提示。
• 明细发票关联、整单附件数量的材料完整性提示。
• assets 类别的人工资产建卡提醒和授权入口。
• 所需的前后端类型、聚焦测试、现有事实源/spec 更新及部署配置说明。

Requirements

R1 明细合计就地展示

• PC 报销明细表尾显示明细数量和报销合计。
• 手机报销明细卡片列表底部显示明细数量和报销合计。
• 概况区将含糊的“金额”统一为“报销总额”或“合计金额”。
• 展示使用服务端返回的 totalAmount，不增加可编辑总额字段。

R2 普通报销正金额与提交一致性

• 员工手工新增或修改普通报销明细时，金额必须大于零。
• 提交时服务端必须确认至少一条明细，且不存在零金额或负金额明细。
• 提交事务内重新按明细汇总并持久化总金额，审批规则、预算检查和工作流快照使用该权威金额。
• 差旅申请或模板创建阶段产生的零金额占位明细仍可保存为草稿，但补齐正金额前不得提交。
• 错误返回可定位到明细或总金额，前端保留已填内容并给出中文提示。

R3 普通报销事由和报销日期编辑

• 草稿和驳回状态的参与人可在 PC、手机详情编辑“报销事由”和“报销日期”。
• 复用现有报销 PATCH 和权限/状态约束，不新增独立保存接口。
• 事由不是“历史费用”分类；员工按真实用途填写，例如设备采购、办公网络或办公用品采购。

R4 票据时效提示

• 服务端配置 REIMBURSEMENT_MAX_AGE_DAYS，默认 365，只允许 180 或 365，部署时可调整。
• 以每条明细的费用发生日期为主计算距当前业务日期的天数；发票日期只作为已有材料摘要，不替代费用日期。
• 超过配置期限或费用日期与提交日期跨自然年度时，在预检中产生中文警告，但本任务不自动阻断提交。
• 页面说明实际天数、当前期限和需要财务确认的下一步，不出现“历史费用补报”标签。
• 日期计算使用 APP_TIMEZONE 和 date-only 语义，不因 UTC 转换偏移一天。

R5 明细材料完整性提示

• 预检返回整单发票数、整单补充附件数，以及每条明细已关联发票数。
• PC、手机详情明确区分“已关联发票”“待关联发票”和“整单补充材料”。
• 普通员工文案不显示 invoice pool、OCR 内部码、UUID 或数据库字段。
• 本任务保持现有“整单至少一张发票”提交门禁；缺少某条明细关联发票先作为可确认警告，不新建费用材料政策中心。
• 本任务不改变 PDF 发票、补充附件、付款回单和资产材料的既有上传边界。

R6 设备资产登记提醒

• 报销包含 assets 类别明细时，PC、手机详情和提交预检显示“可能形成资产，报销完成后由管理员核对并手动建卡”的非阻断提醒。
• 不自动创建资产卡、不自动判断会计固定资产、不复制资产建卡表单到报销页。
• 有资产台账查看权限的用户可从提醒进入资产模块；其他用户只看到下一步说明。

Acceptance Criteria

• AC1：PC 和手机的报销明细区域均显示与服务端 totalAmount 一致的明细数量和合计；新增、修改、删除后自动刷新。
• AC2：手工新增/修改 0 金额明细被服务端拒绝；空明细或含非正金额明细的报销无法提交；模板零金额草稿仍可创建和编辑。
• AC3：提交事务重新汇总权威总额，审批规则和后续提交结果不使用陈旧总额。
• AC4：草稿/驳回报销可在 PC 和手机编辑报销事由和日期；其他状态不可编辑，权限边界不放宽。
• AC5：默认 365 天配置有效，可切换为 180 天；超期和跨年度产生可理解警告但不阻断，date-only 边界无偏移。
• AC6：预检及详情能显示每条明细的发票关联状态和整单附件数；现有整单发票门禁、OCR、查重和附件权限不回归。
• AC7：assets 类别触发人工资产登记提醒，不产生任何资产卡写入；无权限用户不会获得资产数据或管理入口。
• AC8：PC、手机和打印页使用一致的金额语义；普通用户页面不出现内部技术术语。
• AC9：相关后端测试、前端 typecheck/build、PC/移动报销 E2E、Trellis 治理和 git diff --check 全部通过。
• AC10：若改动面向公网用户，部署、公网冒烟和关键页面检查通过后才告知可以测试。

Out of Scope

• “历史费用补报”字段、标识、筛选或独立流程。
• 通用费用政策中心、复杂预算、银企直连、自动付款、自动记账或完整电子会计档案系统。
• 发票与明细多对多、补充附件关联具体明细、发票验真能力扩展。
• 自动创建资产卡、折旧/残值/会计科目判断。
• 改造采购流程、付款状态机、审批角色或权限模型。

Test Plan

• Backend：Prisma validate、node --check、报销详情/创建/费用标准相关 Vitest，并补充本任务聚焦用例。
• Frontend：npm run typecheck、npm run build、PC 和 mobile/wecom 报销详情 E2E。
• Process：Trellis task validate、流程合同、治理、文档注册审计和 git diff --check。