112 行
12 KiB
Markdown
112 行
12 KiB
Markdown
# 详情页结构统一与付款处理时间线
|
|
|
|
## Goal
|
|
|
|
让员工、审批人和财务在报销详情与付款批次详情中按同一认知顺序查看“当前到哪、谁处理、下一步做什么”，并让高频主操作在 PC 和移动端持续可达，不再因页面不同而重新理解同一付款事实或来回滚动。
|
|
|
|
## Background
|
|
|
|
- 报销详情 PC 当前顺序为“概况 → 明细 → 材料 → 处理进度”，移动端同样要滚过不定长材料后才能看到进度；PC 还有三个用于跳转到底部进度的入口，其中 `#reimbursement-workflow-progress-panel` 没有目标元素，另两个入口在进度前移后也不再有价值。
|
|
- 报销详情把付款批次状态投影为时间线，付款批次详情却在“当前处理”事实卡中独立维护另一套状态、责任与下一步文案。同一付款事实已有两种表达和两条判定路径。
|
|
- 报销进度从单笔 `paymentBatchItem` 视角说明“这一笔在批次中的位置”；付款批次详情从整个 `paymentBatch` 视角说明“整批走到哪”。两者不能共用一个大 DTO 构建函数，但付款阶段标签和状态判定必须同源。
|
|
- PC 报销详情使用顶部 hero 动作加底部手写“可执行动作”卡；付款批次详情把动作放在顶部摘要卡。项目已有 `BusinessDetailActionPanel`，但其工作区和 sticky 均只在 `xl` 生效。移动端已有 safe-area 固定底部操作模式。
|
|
- 当前生产没有真实 `executed` 付款批次；这不应阻塞任务完成，五种状态由合成数据自动化覆盖，生产只验收届时真实存在的状态。
|
|
|
|
## Scope
|
|
|
|
- 调整报销详情 PC/移动端与付款批次响应式详情的信息顺序和操作区，但不扩展到其他业务详情页重构。
|
|
- 新增共享的只读付款阶段语义和付款批次三阶段 DTO，报销与付款分别保留自己的视图组装层。
|
|
- 收敛通用时间线组件、详情工作区 `lg` 断点及 PC/移动动作派生，回归既有共享组件消费者。
|
|
- 更新合成自动化、稳定工程规约和下一笔制单的安全操作说明；不执行部署、生产配置、网银导入或真实付款。
|
|
|
|
## Requirements
|
|
|
|
### R1 详情信息顺序
|
|
|
|
- 报销详情 PC 和移动端均调整为“概况 → 处理进度 → 报销明细 → 报销材料”；移动端底部“操作”段仍留在业务内容之后。
|
|
- 删除 PC 的三个进度锚点动作，包括一个死链和两个指向现有处理进度面板的自指入口；返回、打印、催办、提交、撤回等真实动作保持可达。
|
|
- 付款批次详情按“批次概况 → 处理进度 → 报销明细 → 银行回单”组织主内容。
|
|
|
|
### R2 付款处理语义单一事实源
|
|
|
|
- 建立共享付款阶段语义层，唯一维护阶段 key、标签及 `completed/current/pending/exception/terminated` 判定；“付款复核”“付款完成”及其状态条件不得在报销路由和付款批次路由各写一套。
|
|
- 共享语义层按批次状态和时间戳判断阶段；两个调用方仅负责各自视角的 DTO 组装、责任人姓名解析、权限链接和报销历史兼容信息。
|
|
- 报销视角继续保留提交、真实审批任务和两个付款阶段；付款批次视角展示“批次创建 → 付款复核 → 付款完成”三阶段。
|
|
- `draft`、`reviewed`、`executed`、`failed`、`cancelled` 五种付款批次状态必须有明确投影。`failed` 的付款阶段为 `exception`；`cancelled` 根据是否已有复核时间终止在复核或付款阶段，后续阶段为 `terminated`，不得显示仍待处理。
|
|
- 共享语义层必须接收与执行门禁同源的 `requiresBankReceipt`，不能仅凭回单数判断下一步。`reviewed` 且不需要回单时直接显示等待登记付款完成；需要回单且尚未上传时才按制单次数区分：未导出显示“等待财务线下付款并上传回单”，已导出显示“已生成银行制单，等待付款完成并上传回单”；需要回单且已有回单时显示等待登记付款完成。
|
|
- 制单中间态只适用于需要银行回单的渠道；现金等不需要回单的批次不得出现上传银行回单或已生成银行制单的下一步文案。
|
|
- 付款批次处理进度显示已有的真实创建人、复核人、执行人或取消人及时间；不得猜测未来责任人。
|
|
|
|
### R3 共享时间线表现
|
|
|
|
- 将现有 `ReimbursementProcessingProgress` 收敛为共享进度组件；保留当前数据驱动渲染，不重做成带大量配置项的新组件。
|
|
- 共享组件使用通用阶段类型，并参数化 `aria-label`、测试标识和目标链接文案；PC 与移动端继续使用相同渲染逻辑。
|
|
- `terminated` 使用中性终止视觉和“已终止”状态，不表现为错误、完成或待处理；`exception` 继续用于失败和发生取消动作的终止节点。
|
|
|
|
### R4 响应式操作区
|
|
|
|
- PC 报销与付款批次详情收敛到 `BusinessDetailWorkspace/Main/Aside + BusinessDetailActionPanel`；hero/概况卡不再保留第二套业务主操作。
|
|
- 详情工作区双栏和操作面板 sticky 从 `xl` 调整到 `lg`，并回归现有 `AssetRegistryPage` 与 `WorkflowTaskDetailPage` 消费方，确保笔记本宽度可见且不遮挡内容。
|
|
- 付款批次的 PC 粘性面板与移动端固定底栏必须消费同一份动作可见性/主次级模型，不能各自重复判断状态和权限。
|
|
- 移动端只在固定底栏展示一个当前主操作；取消、重新下载等次要或破坏性动作进入“更多”并保留既有原因输入、风险提示和二次确认。
|
|
- 上传银行回单成功后，当前主操作在原可视区域切换为“登记付款完成”，用户无需滚回页面顶部。不得通过同时渲染两个同名主按钮来实现就近入口。
|
|
- 所有异步动作在执行中保持禁用和加载反馈；高风险付款、复核、取消及重新下载制单的既有确认合同不放宽。
|
|
|
|
### R5 兼容与边界
|
|
|
|
- 本任务只增加只读处理进度投影和调整页面布局/动作呈现，不改变付款批次写状态机、权限、maker-checker、回单门禁、快照、加密或审计合同。
|
|
- 不新增数据库字段或迁移；服务端普通响应不得新增完整账号、密文、原始快照或批次相邻敏感数据。
|
|
- 历史已付款但无付款批次的报销继续可读；无批次、无工作流、无回单或责任人记录缺失时，只降级对应阶段，不使整个详情失败。
|
|
|
|
### R6 下一笔制单安全说明
|
|
|
|
- 等下一张报销自然形成新快照批次，不取消重建杨俊当前已复核的旧批次。
|
|
- 下一笔新批次的“验证制单”和“使用制单付款”是两步：若建设银行网银没有明确的“仅校验、不提交”环节，只做导出、Excel 打开和固定版本 `xlrd` 读回的离线验证，实际付款仍走人工；不得因文件生成成功直接导入提交。
|
|
|
|
## Test Plan
|
|
|
|
- 服务端纯语义单元测试用合成数据覆盖 `draft/reviewed/executed/failed/cancelled`，以及取消前后是否已有复核时间、需要/不需要回单、未制单/已制单/已有回单分支。
|
|
- 扩展报销详情路由测试，证明其付款阶段与共享语义一致、无批次和历史已付款兼容不回退；扩展付款批次详情测试，证明三阶段 DTO、真实 actor name/time 和普通 DTO 隐私边界。
|
|
- 前端类型检查与构建；共享时间线覆盖五种状态与 `terminated` 表现。
|
|
- Playwright 使用合成响应覆盖付款批次五种状态、需要/不需要回单、PC/移动端动作唯一性、上传回单后主操作切换、报销 PC/移动端四段顺序、三个旧锚点消失，以及 `lg` sticky 相关消费者回归。
|
|
- 报销动作迁移必须分别保留提交、打印、催办、撤回、删除的权限/状态可见性、确认或原因交互、成功 mutation 与刷新结果断言；不能只检查操作面板里出现了按钮。
|
|
- 实施后按项目约束启动只读 reviewer，重点审查状态机投影、权限/隐私、PC/移动动作一致性，不允许 reviewer 修改代码。
|
|
- 运行 Trellis、流程、文档、敏感内容和 `git diff --check` 门禁；用户可测试前仍须另行批准部署并通过公网检查。
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [x] 报销 PC 与移动端均按“概况 → 处理进度 → 明细 → 材料”展示，PC 三个旧进度锚点全部消失，移动端操作仍在底部。
|
|
- [x] 付款批次详情用三阶段时间线替换“当前处理”事实卡，标题统一为“处理进度”，并显示真实已有责任人和时间。
|
|
- [x] 两个服务端调用方共同使用唯一付款阶段语义层；阶段标签和五状态判定不存在第二份实现，结构测试能阻止重新分叉。
|
|
- [x] `draft/reviewed/executed/failed/cancelled` 均由合成测试覆盖；失败显示 exception，取消在正确节点结束且后续显示 terminated，不再挂待处理。
|
|
- [x] reviewed 需要回单时的未制单、已制单、已有回单三种文案与既定口径一致；不需要回单时直接等待登记完成且不出现银行回单/制单引导。
|
|
- [x] 共享时间线同时服务报销 PC、报销移动端和付款批次，保留无障碍名称、稳定 testid、目标链接及中止态视觉。
|
|
- [x] PC 报销与付款批次详情使用标准右侧操作面板，`lg` 笔记本宽度可粘性跟随；资产与审批任务详情无布局回退。
|
|
- [x] 付款批次移动端使用 safe-area 固定底栏，PC/移动动作来自同一模型；每个视口只有一个当前主操作。
|
|
- [x] 上传回单成功后无需滚动即可点击“登记付款完成”，且继续使用现有二次确认和回单硬门禁。
|
|
- [x] 报销提交、打印、催办、撤回、删除迁移后各自的权限/状态可见性、确认或原因交互、成功刷新合同均有 E2E 回归，尤其锁定仅 reviewing 可撤回、仅 draft 可删除。
|
|
- [x] 无数据库迁移、权限扩大或付款写状态机变化，普通响应不泄露银行敏感字段。
|
|
- [x] 管理员手册明确下一笔制单仅在网银有“仅校验、不提交”环节时才进入网银，否则只做离线验证并人工付款。
|
|
- [x] 自动化验收覆盖全部五状态；生产验收只覆盖当时已有真实状态（预计 draft/reviewed），缺少 executed/failed/cancelled 真实数据不阻塞任务完成，后续真实 executed 仅作补充验收。
|
|
|
|
## Out of Scope
|
|
|
|
- 取消或重建杨俊当前付款批次、执行真实付款、上传真实回单或写入任何生产银行数据。
|
|
- 等待下一笔真实付款完成后再结束本任务，或把生产 `executed` 数据设为本任务验收门槛。
|
|
- 企业网银导入、提交、放款、银行 API 直连或跨行制单能力。
|
|
- 修改付款状态转换、maker-checker、回单要求、银行账户/快照模型、制单格式或导出权限。
|
|
- 统一所有业务详情页、列表页、编辑页或重新设计视觉体系。
|
|
- 新建数据库迁移、补写历史付款快照或为测试制造生产业务数据。
|
|
|
|
## Risks And Deferred Items
|
|
|
|
- `detail-workspace-grid` 与 `BusinessDetailActionPanel` 的断点是共享合同，调整时必须回归资产和审批任务详情；若 `lg` 宽度不足，应通过列宽/间距收敛解决，不退回页面私有 sticky。
|
|
- 当前生产缺少后三种真实状态，自动化是本任务的完成证据；真实 `executed` 批次出现后可追加一次生产观察，但不重新打开本任务。
|
|
- 建设银行网银是否存在安全的仅校验步骤仍未知；这只决定后续是否做网银格式确认，不改变本任务产品行为。
|
|
|
|
## Notes
|
|
|
|
- Keep `prd.md` focused on requirements, constraints, and acceptance criteria.
|
|
- Lightweight tasks can remain PRD-only.
|
|
- For complex tasks, add `design.md` for technical design and `implement.md` for execution planning before `task.py start`.
|