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 类别；资产事实源要求“资产候选 + 管理员人工建卡”，不得因报销提交、审批或付款自动生成资产卡。
• 本轮讨论已决定不增加“历史费用补报”标识。票据新旧由费用日期、发票日期和提交日期推导。
• 后续真实使用复核发现：差旅报销同时展示整单“报销事由”和“出差事由”；有权限用户在付款复核与付款完成两个阶段都看到同一付款批次链接；付款批次的“报销明细”实际只有报销单级付款摘要；银行回单只有强制下载路径。
• 代码核实确认上述四项均由当前实现稳定产生，并非截图或浏览器偶发现象：前两项属于展示条件/阶段链接组装问题，后两项分别存在详情 API 数据缺口和附件查看能力缺口。

Scope

• 报销详情 PC、手机的明细合计和普通报销事由/日期编辑。
• 报销明细正金额校验、提交时权威总额重算。
• 180/365 天票据时效配置及超期、跨年度非阻断提示。
• 明细发票关联、整单附件数量的材料完整性提示。
• assets 类别的人工资产建卡提醒和授权入口。
• 所需的前后端类型、聚焦测试、现有事实源/spec 更新及部署配置说明。
• 报销详情、付款批次详情和银行回单之间的只读信息展示与交互复核；不改变付款写状态机、maker-checker 或真实付款边界。

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

R7 差旅报销事由单一主语义

• 普通报销继续展示并编辑“报销事由”。
• 差旅报销以“出差事由”为唯一面向用户的主事由，不在同一区域重复展示空泛的“报销事由”。
• 既有 description 与 travel_purpose 数据暂不迁移、不互相覆盖；打印、搜索、通知标题等非详情消费者需在设计阶段核对兼容语义。

R8 付款批次入口只出现一次

• 有付款批次读取权限且报销已进入批次时，处理进度中只显示一个“查看所在付款批次”入口。
• 入口随批次状态挂到实际承载当前或最终结果的阶段：待复核挂在“付款复核”，复核后、付款失败或付款完成挂在“付款完成”；取消状态挂在实际终止阶段。
• 普通员工仍不获得付款批次读取权限或内部批次入口。

R9 付款批次区分报销单与费用明细

• 付款批次中的一张卡片首先表示一张待付款报销单，应使用“本批次报销单”或同等准确标题，不把收款账户摘要冒充费用明细。
• 每张报销单展示其费用明细的只读摘要，至少包含费用类型、发生日期、说明和金额，并显示明细合计；同时保留收款人、开户银行、脱敏账号、付款渠道和付款结果。
• 付款批次提供返回原报销详情的入口；不在付款页复制发票、补充附件编辑和完整报销操作。
• 费用明细只加入付款批次详情 DTO，列表响应继续保持轻量；不得返回完整银行账号、加密值或原始快照。

R10 银行回单在线查看与用途治理

• PDF 和支持的图片回单在付款批次详情中提供在线查看；不再要求用户必须先下载到本地才能核对。
• 在线查看继续经过服务端权限、批次数据范围、文件类型/大小/隔离状态校验，并写审计；不得直接暴露存储路径。
• 回单继续标记为“保密”。授权人员在批次上下文内在线查看时使用系统固定用途并自动审计，不要求重复手填；下载到本地仍要求手填用途并写审计。
• “需填用途”若仅针对下载，应改为更准确的“下载需说明用途”，避免误解为回单本身资料不完整。

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：若改动面向公网用户，部署、公网冒烟和关键页面检查通过后才告知可以测试。
• AC11：普通报销显示“报销事由”，差旅报销详情只显示一个主事由入口且沿用“出差事由”；既有差旅数据不丢失。
• AC12：同一报销的处理进度最多出现一个付款批次入口，五种批次状态及取消前后分支均落在正确阶段，权限边界不放宽。
• AC13：付款批次明确区分报销单、费用明细和付款信息；费用明细金额合计与报销单金额一致，并可返回原报销详情。
• AC14：PDF/图片银行回单可在授权页面在线查看且自动记录固定用途；下载到本地仍要求手填用途，隔离、作废、超限和无权限文件不可查看或下载。

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。
• Follow-up focused：差旅/普通报销事由显示、付款批次入口五状态矩阵、付款批次详情 DTO 隐私负向断言、费用明细合计、回单 PDF/图片在线查看及用途/审计/隔离回归。