hyb-oa/.trellis/tasks/08-01-reimbursement-notification-progress-clarity/design.md

报销通知与处理进度简化：设计

1. 设计目标

用最少改动恢复真实待办通知，并让员工看到职责清晰的报销全流程。工作流审批、付款批次和付款执行仍是三个独立状态源；页面只做汇总，不把它们合成一个状态机。

2. 通知只读诊断

按以下顺序诊断目标财务任务，任何一步都只记录布尔状态、计数、固定结果码和脱敏结论：

1. 从目标报销的最新工作流实例定位主管已完成任务与当前财务任务，不保存内部 ID 到仓库证据。
2. 以当前财务任务为 target_id 查询 workflow.task_assigned 站内通知，并确认收件人是否为预期财务人员。
3. 若通知不存在，回到主管审批后的下一任务创建/收件人解析路径；若存在，继续查询 delivery 状态与固定 result_code。
4. 只核对收件员工 active、notification_push_enabled、企微绑定是否存在，及启用渠道能否匹配 workflow 域和财务角色；不读取 userid、渠道 Secret、消息正文或响应原文。
5. 只读结论不足以授权配置修改、补发、重启或生产写入，后续动作单独申请。

3. 审批动作标签

• client/src/lib/approvalDisplay.ts 的 workflowActionLabel() 为唯一共享映射。
• PC WorkflowTaskDetailPage.tsx 和移动 MobileApprovalsPage.tsx 删除局部副本并导入共享函数。
• 保持未知动作的原值兜底用于诊断，但所有当前受支持动作必须有中文映射；测试覆盖 start 与 submit。

4. 员工进度表达

• 后端处理进度阶段键保持兼容，只把普通详情的标签调整为“付款复核”“付款完成”。
• 付款完成 当前节点/待处理说明明确“由财务登记，非审批环节”；已完成时继续显示付款人、时间及回单是否留存。
• “查看所在付款批次”只对已有批次读取权限的人显示，普通员工不接触内部批次对象名。
• 五阶段继续使用一条竖向进度线，因为它表达全流程进展；文案区分审批与付款，不另加 Tab、折叠或第二张流程图。

5. 付款阶段通知

本节实施以第 2 节诊断结论为前置门：若原链路是投递配置问题，付款阶段只新增复用既有 dispatcher 的发送点；若原链路是通知创建或 side-effect flush 的代码问题，先修复并用既有主管→财务通知证明公共路径，再让两个付款发送点复用同一修复。禁止在根因未定时并行新增后再混合排障。

5.1 批次创建后

• 新建批次事务内创建“待付款复核”站内通知，事务提交后走现有 IM dispatcher。
• 收件人由 active 员工的真实角色权限计算：必须有 payment.batch.review 且角色包含 manager 或 ceo，并排除批次创建人；不得写死姓名或向所有管理角色泛发。
• 通知目标是 payment_batch，deeplink 进入现有付款页面的目标批次。

5.2 批次复核后

• 复核事务内创建“待执行付款”通知，收件人优先为仍 active 且具备 payment.batch.manage 的批次创建人；创建人不可用时，才解析其他具备管理权限的 active 财务人员，并排除当前复核人。
• 不把付款动作通知给普通申请人；申请人在批次执行成功后继续收到既有 reimbursement.paid。

5.3 合同与幂等

• 新增明确的付款待办通知类型，不复用“报销已付款”或“工作流待审批”伪装语义。当前付款批次只开放报销实体，因此通知映射到既有 reimbursement domain，复用现有渠道配置；未来若重新开放其他实体付款，再按实体拆分 domain，不在本轮新建需要生产改配的 payment domain。
• 通知创建与业务状态变更在同一事务内；投递失败不回滚已完成业务动作，但保留 delivery 失败证据。
• 重复创建/复核请求由既有状态锁拒绝，测试证明不会产生重复通知。

6. 兼容与回滚

• 不修改数据库 schema、历史审批快照、既有通知记录或付款批次状态。
• 文案改动可直接回滚；共享映射回滚不会影响服务端事实。
• 付款通知若出现收件范围错误，关闭对应通知类型/代码路径即可，不撤销已经创建或复核的付款批次。
• 本轮不合并财务复核与组批；累计 5–10 张真实单后的用户访谈是重新立项条件，不是当前发布门禁。

7. 付款入口与正式常开防复发

7.1 已确认根因

• 当前生产库 payment_batch_v1 为版本 1，创建时间等于更新时间，updated_by 为空，且没有任何 FEATURE_FLAG_UPDATED 审计。
• 这证明当前库是在初始化时由 seed 首次创建默认 force_off，不是 seed 覆盖已有值，也不是 QA runner 或控制台在当前库执行了关闭。
• 当前运行环境同时为 PAYMENT_BATCH_ENABLED=false，因此数据库即使改成 force_on 也会被 env_hard_off 拦截。
• 当前唯一 active 财务人员具备 payment.batch.manage，但付款入口和已批准候选均因功能门控被隐藏；权限不是根因。

7.2 稳定基线

• 试运行正式基线把 PAYMENT_BATCH_ENABLED 设为 true，并把 seed 中 payment_batch_v1 的首次创建默认值设为全局 force_on；seed 继续只创建缺失记录，不更新已有记录。
• 部署/runtime smoke 明确断言付款批次有效开启，防止换库、换 .env 或恢复后再次静默关闭。
• QA 短窗口保存进入前完整快照并在 finally 恢复该快照；只有明确的正式启用流程在成功时保留 force_on，失败才恢复调用前状态。

7.3 入口规则

• PC 继续使用现有“付款”导航。
• 移动财务工作台在付款能力开启时固定显示财务卡片，不再要求先存在批次或异常；卡片进入受同一付款权限保护的 /mobile/payment-batches，复用现有响应式付款页，避免企微小屏把 PC 路径重定向回首页。
• 入口只对真实 finance/finance_mgr 且具备付款权限的人员显示；不向普通员工或仅审批人开放创建能力。
• 本轮不自动打开创建面板、不自动选择报销、不代替真实财务动作。