hyb-oa/.trellis/tasks/09-04-reimbursement-state-gap-finance-view/prd.md

报销状态空隙与财务处理视角

Goal

消除报销从审批通过到付款批次创建之间、以及报销回到草稿状态之后的两个运营空隙：财务应能在付款页直接发现并处理尚未组批的已通过报销，同时“全范围”不得暴露他人从未提交的私人草稿，但必须保留对已经进入过流程的退回或撤回草稿的追踪能力。

本任务来自真实业务单据 0014 的首次使用反馈。两个 Requirement 共享“状态空隙必须有明确责任人和可见入口”的产品原则，但必须保持代码边界、测试证据和回滚点独立，不能因一项回滚而被迫撤销另一项。

Scope

• R1 覆盖付款页待组批视图、报销详情下一步深链及报销处理进度中的组批/复核阶段区分。
• R2 覆盖报销列表、详情、材料、提交前检查、全局搜索、导出和报销统计的“本人草稿或已进入流程”服务端读取边界。
• 两项分别实施、分别测试、分别提交和回滚；具体行为以 Requirements 为准，排除项以 Out of Scope 为准。

Background

• 2026-09-04 对生产做了只读核验：目标单据唯一匹配，状态为 approved、未付款、无任何付款批次关联，payment_batch_v1 为 force_on/global，满足现有 /payment-batches/candidates 候选合同；未创建批次或改动单据。
• 同次脱敏统计显示：生产当前只有 1 张 approved 且未付款、未被活动批次占用的报销，即本次目标单据；当前 1 张 draft 从未产生 workflow 实例，暂无“有历史 workflow 的 draft”。这些计数只用于评估本次行为，不作为测试 fixture 或实现常量。
• 付款首页只查询已经创建的 PaymentBatch；候选报销仅在财务点击“新建批次”后才加载。待我审批 查询 workflow task，而付款批次复核不是报销 workflow task；组批前也不存在可复核的付款批次。
• 报销详情目前把无批次的 approved 投影为“付款复核 / 待安排 / 待财务安排付款”，同时页面下一步仅写“等待财务处理”。批次 draft 才真正表示“已创建并提交付款复核”。当前投影把批次级阶段提前套在尚未组批的报销上。
• 报销列表的状态与范围相互独立。具备 expense.view_all 的财务、财务负责人、CEO、HR、管理员可在 草稿 + 全范围 查看全公司的草稿；经理可查看本人、代填及直属下属草稿。现有详情和材料读取辅助函数也对 expense.view_all 无条件放行。
• 报销 return 和申请人 withdraw 都会把业务状态改回 draft，并保留 workflow 实例；从未提交的草稿没有 workflow 实例。仓库统计查询已使用 workflow 实例创建时间作为提交事实，因此“是否存在 workflow 实例”是现有、可推导且无需 schema 变更的“是否进入过流程”判据。

Requirements

R1：已通过但未组批的报销必须成为财务可见、可执行的队列

1. 报销 approved 且未付款、未进入任何非取消付款批次、付款能力对其部门有效时，必须出现在付款页一级“待组批”视图；候选资格继续由服务端现有候选合同决定，前端不得自行复制状态或部门门禁。
2. “待组批”只对具备 payment.batch.manage 的人员显示和查询；仅具备 payment.batch.review 的复核人继续查看已创建的付款批次，不获得组批候选或创建能力。
3. 付款页在无批次详情参数时提供“待组批”和“付款批次”两个明确视图。对组批管理员默认进入“待组批”，标签显示服务端返回的候选总数；复核只读角色默认进入“付款批次”。URL 必须可表达当前视图并支持刷新、返回和报销详情深链。
4. “待组批”复用现有候选 API、搜索、分页和创建合同，显示单号、报销人、报销日期、权威总额及摘要。它不是第二套候选计算，也不得同时保留一份隐藏在“新建批次”里的重复候选列表。
5. 财务可从待组批列表选择一张或多张报销并进入现有“创建并提交复核”流程；创建成功后候选立即从待组批队列消失，付款批次视图出现新批次，其状态为“待付款复核”。不得自动组批、自动选择、自动复核或改动 maker-checker 规则。
6. 报销详情在无批次的 approved 状态下，把下一步明确写为“等待财务组建付款批次”。具备 payment.batch.manage 时提供进入付款页待组批视图的单一入口，并以当前报销编号预置搜索；其他用户只看到状态说明，不暴露付款管理能力。
7. 报销处理进度必须区分“组建付款批次”和“付款复核”：
   • 无批次的 approved：组批阶段为当前，说明“待财务组建付款批次”；付款复核仍为待处理。
   • 已有 draft 批次：组批阶段已完成，付款复核为当前，继续使用“待付款复核”。
   • 后续 reviewed/executed/failed/cancelled 继续由共享付款阶段语义投影，不改变付款写状态机。
8. 列表必须有加载、错误、空态和分页反馈；空态只说明当前没有待组批报销，不把“系统正常”写成解释性噪音。PC 与现有响应式付款页保持同一数据源，移动端不新建第二套付款状态机。

R2：全范围只展示已经成为业务事实的他人草稿

1. “业务事实”判据固定为：报销单至少存在一个 entity_type=reimbursement 的 workflow 实例。不得用当前 workflow 状态、最后一次 outcome、页面标签、单号是否为空或更新时间猜测。
2. 报销人为本人或提交人为本人时，仍可查看自己的全部草稿，不要求存在 workflow 实例。
3. 对他人的 draft：
   • 从未进入流程、无 workflow 实例：从全范围列表、全局搜索、导出和按报销聚合的统计中排除，直接访问详情或材料接口返回无权限。
   • 曾经进入流程、有 workflow 实例：继续按既有全范围角色边界可见，包括审批人退回和申请人撤回后回到 draft 的记录。
4. 非 draft 状态的既有可见性不变；经理仍限本人、提交人及直属下属，财务/财务负责人/CEO/HR/管理员仍限现有全局范围。本任务不新增角色、不授予 expense.view_all、不改变编辑权限。
5. 服务端必须统一强制该判据。前端可以隐藏不可见记录，但不得作为授权边界；详情、普通附件下载、附件预览 URL、完整材料预览和 POST /reimbursements/:id/precheck 必须共同收紧，避免通过已知 ID 绕过列表。precheck 返回的预算提示、费用标准、审批规则和风险标记同样属于受保护的报销内容。
6. 报销统计与导出不得把他人从未提交的草稿当作正式台账事实；本人草稿是否进入个人视角统计沿用既有行为。付款候选只接受 approved，不受本条授权筛选影响。
7. 被排除的记录对无权读取者使用既有自然中文无权限合同，不泄露“该 ID 存在但尚未提交”、workflow 计数或内部判据。

Acceptance Criteria

• AC1（R1）：以 approved + unpaid + no active batch + gate enabled fixture 请求待组批视图，能看到目标报销；任一条件不满足时不出现。生产只读复核能在待组批视图搜索到 0014，但自动化不得创建真实付款批次。
• AC2（R1）：付款批次管理员默认看到“待组批”及准确总数，搜索/分页/空态/错误态可用；仅复核角色看不到待组批和创建入口，原有批次复核能力不变。
• AC3（R1）：从报销详情点击入口进入可刷新、可返回的待组批 URL，并预置当前单号；无管理权限时入口为 0，但“等待财务组建付款批次”仍准确显示。
• AC4（R1）：无批次时进度显示“组建付款批次”为当前且“付款复核”为待处理；创建批次后前者完成、后者当前。draft/reviewed/executed/failed/cancelled 付款批次的既有语义、通知、权限和写状态机回归通过。
• AC5（R1）：创建成功只刷新候选与批次查询，不出现重复候选列表，不自动执行任何付款写动作；PC 1280px 无横向溢出，移动端可完成搜索、选择和进入创建流程，交互目标不小于现有 44px 约束。
• AC6（R2）：表驱动服务端测试覆盖本人/提交人、全局角色、经理直属团队、无关人员 × draft 无 workflow、draft 有 returned workflow、draft 有 cancelled/withdrawn workflow、所有非 draft 状态；只有“他人且从未进入流程的 draft”被排除。另有负向保护证明当前或历史 workflow 审批人读取自己任务关联的报销不受新过滤误伤。
• AC7（R2）：同一未提交他人草稿在列表、全局搜索、CSV/XLSX 导出和报销统计中均不可见/不计入；直接详情、普通附件、预览 URL、完整材料预览和 precheck 均返回无权限。不得只做前端筛选。
• AC8（R2）：退回或撤回后为 draft 且有 workflow 实例的报销仍可由原授权范围内人员查看；既有审批历史、只读投影和申请人编辑重提/再次提交路径不变。
• AC9（独立性）：R1 与 R2 分成独立业务提交或至少独立可逆提交单元、独立 focused 测试组；分别回滚任一项时另一项仍可构建并通过自己的测试，不需要 schema、migration、seed、flag 或生产数据修正。
• AC10（门禁）：前后端 focused 测试、前端 typecheck/build、UI strict/self-test、Prisma validate、workflow/权限过程级回归、Trellis governance 和 git diff --check 通过；涉及权限和 workflow 投影，实施后必须进行只读 review。
• AC11（部署后）：/ready 与 bundle marker 等于候选短 SHA，公网文案扫描 findings=0；真实账号只读确认 0014 位于待组批且未被自动修改，未提交他人草稿不再可见，退回/撤回历史草稿 fixture 仍可见。真实组批、复核和付款仍由财务人工执行。

Test Plan

• R1 focused：付款候选资格、manage/review 权限矩阵、待组批 URL/搜索/分页/空态、创建后查询刷新，以及无批次到五种批次状态的进度投影。
• R2 focused：角色与归属 × draft/非 draft × workflow 无/有的表驱动矩阵，并覆盖列表、详情、材料、precheck、全局搜索、CSV/XLSX 和统计旁路；单列 workflow reviewer 待办读取的负向保护。
• 回归与门禁：付款 maker-checker、报销退回/撤回/重提、B1/B2、非报销 workflow、前端 typecheck/build、UI strict/self-test、Prisma validate、Trellis governance 和 git diff --check。
• 生产验收只读检查候选可见性和授权结果；不自动创建、复核或执行真实付款批次。

Out of Scope

• 不在本任务替财务创建 0014 的付款批次、复核或登记付款。
• 不修改 Prisma schema，不新增 submitted_at，不回写历史报销或 workflow 数据。
• 不合并报销 workflow 与付款批次状态机，不把付款复核塞进“待我审批”。
• 不修改 maker-checker、付款账号、回单、网银制单、B1/B2、预算、票据或通知 routing。
• 不改变采购、差旅、请假、补卡的列表、草稿权限或工作流。
• 不借本任务调整 expense.view_all 的角色授予；HR/CEO 是否应继续拥有该权限另行评估。
• 不新增批量自动组批、自动付款、真实支付接口或第二套移动付款页。

Risks and Deferred Items

• workflow 实例存在表示“曾进入流程”，因此会有意保留退回和撤回草稿的全范围可见性；若后续业务要求撤回后重新私有化，必须新增独立产品判据，不能悄悄改成 outcome 白名单。
• 当前数据库无 submitted_at；workflow 关系查询需要通过 focused 性能测试确认列表、搜索、导出和统计没有不可接受退化。本任务不以冗余字段或 migration 预优化。
• 全局搜索、导出和统计是列表之外的旁路；若实现评估发现某一旁路无法在本候选安全收紧，必须阻断 R2 发布或拆出明确依赖任务，不能把列表隐藏冒充权限修复完成。
• 真实付款批次创建属于财务业务动作，不作为自动化验收。部署后只证明候选可见、入口可用和数据未被自动修改。