hyb-oa/.trellis/tasks/archive/2026-08/08-03-detail-page-structure-progress-actions/implement.md

详情页结构统一与付款处理时间线实施计划

1. 开发前

• 用户审查并明确批准本 PRD、设计和实施清单后，运行 task.py start；批准前不修改产品代码。
• 使用 trellis-before-dev 读取 backend、frontend、hyb-oa 相关规约与当前任务合同。
• 记录基线：聚焦报销/付款路由测试、前端 typecheck/build 和相关 Playwright 当前结果。

2. 服务端语义与 DTO

• 先提取与执行门禁同源的 requiresBankReceipt 渠道判断，再新增共享付款阶段语义模块及表驱动单元测试，覆盖五状态、取消前后复核、需要/不需要回单、制单/回单分支和 actorSource。
• 报销 buildProcessingProgress 改为消费共享语义，保留无批次、权限链接和历史 paid 兼容；更新既有详情路由测试。
• 付款批次详情组装 actor names 与三阶段 processingProgress；列表映射保持轻量，新增隐私负向断言。
• 更新客户端付款详情 API 类型，明确列表/详情字段边界。

3. 共享前端组件

• 将报销专用进度组件收敛为共享组件，参数化无障碍名称、testid、目标链接文案并增加 terminated 状态。
• 更新 PC/移动报销调用方与相关 fixture，保持动态阶段数量和链接权限行为。
• 将详情工作区双栏、操作面板 sticky 及页面覆盖断点统一为 lg，先回归资产与审批任务详情。

4. 报销详情

• PC 迁移到标准 Main/Aside 操作区，主内容按概况、处理进度、明细、材料排列；移除 hero 动作重复、旧手写动作卡和三个进度锚点。
• 移动端把处理进度移到概况之后，保持操作 section 在底部和现有 safe-area 固定提交动作。
• 补 PC/移动四段顺序、锚点删除和无重复主操作回归；逐项覆盖提交、打印、催办、撤回、删除的权限/状态可见性、原因/确认、请求与刷新结果。

5. 付款批次详情

• 建立单一派生 paymentActionModel，沿用现有权限、原因、确认、loading 和 mutation handler。
• 主内容改为概况、共享三阶段时间线、明细、回单，删除“当前处理”事实卡及页面内状态文案矩阵。
• lg+ 使用标准粘性操作面板；移动端使用 safe-area 固定底栏，一个 primary 加“更多”。
• 验证上传回单成功后原地切换为“登记付款完成”，没有第二个同名主按钮。
• 更新既有付款 E2E locator，使其按当前 viewport/操作区作用域断言；合成覆盖全部五状态和需要/不需要回单渠道，非银行批次不得出现回单/制单引导。

6. 文档与稳定规约

• 确认管理员手册已区分“制单离线验证”和“使用制单付款”，无安全仅校验环节时仍人工付款。
• 将共享付款进度的稳定状态/终止态合同更新到 .trellis/spec/hyb-oa/approval-workflow.md；不把页面实现细节复制到业务文档。
• 如未发现新的稳定通用规则，不新建额外文档。

7. 验证与只读审查

• cd server && node --check src/services/paymentProcessingProgress.js && node --check src/routes/reimbursements.js && node --check src/routes/paymentBatches.js
• 运行新增纯函数测试、reimbursements.detail.test.js 和付款批次聚焦路由测试。
• cd server && npm run prisma:validate
• cd client && npm run typecheck && npm run build
• 运行相关 Playwright：报销 PC/移动详情、付款批次五状态/动作确认、资产与审批任务详情 lg 回归。
• 因涉及付款状态投影，启动只读 reviewer 审查状态语义、权限/隐私、双视角 DTO 和 PC/移动动作一致性；reviewer 不修改代码。
• 修正 findings 后重跑受影响检查，再执行 bash scripts/check-minimal.sh（若耗时门禁适用）。
• node scripts/qa/check-process-contract.mjs --baseline --json
• node scripts/qa/audit-docs.mjs --check-registry
• node scripts/qa/check-trellis-governance.mjs
• git diff --check

8. 提交、部署与验收

• 质量检查通过后按 Trellis finish 流程更新必要 spec/docs，使用中文 commit message 并引用 detail-page-structure-progress-actions。
• 未经单独批准不部署；批准后走标准部署聚合体检、公网 ready/build 检查。
• 公网通过后只通知用户验收真实可见状态；记录生产缺少 executed/failed/cancelled 的限制，后续真实 executed 仅作补充观察。

验证记录（2026-08-03）

• bash scripts/check-minimal.sh 在固定 BIFF8 Python 依赖环境下通过：服务端 177 个测试文件、1213 个用例全部通过，Prisma、前端 typecheck/build 与其余聚合步骤通过。
• 聚焦服务端共享语义、报销详情、付款详情与制单回归通过；普通付款进度 DTO 无账号、密文、原始快照或 actor ID。
• 聚焦 Playwright 覆盖报销动作、付款五状态、银行/非银行渠道、PC/移动唯一主操作、上传后原地切换和 lg sticky 合同。审查 finding 修复后，制单可用且未导出时仍以“上传银行回单”为主操作，首次制单进入“更多”。
• 只读 reviewer 首轮发现“制单被误设为强制主路径”的 High finding；修复及 PC/移动回归后复核 PASS，reviewer 未修改代码。
• 文档审计 errors=0，保留仓库既有的 22 个未注册文档 warning；Trellis、流程、敏感内容与 git diff --check 门禁通过。

回滚点

• 服务端共享投影与前端 DTO/UI 同一提交批次回滚，避免新前端依赖旧 DTO。
• 若共享 lg 断点导致现有资产/审批详情无法接受，先修正共享列宽和 top offset；不得用页面私有断点重新制造第二事实源。
• 本任务无迁移、无生产数据回填、无付款状态写入，代码回滚不需要数据库操作。