51 lines
3.3 KiB
Markdown
51 lines
3.3 KiB
Markdown
## Context
|
||
|
||
退款审批提交由后端和企业微信协同完成。网络超时或异步任务异常时,本地不能仅凭旧字段判断提交结果:已有 `sp_no` 需要同步,结果未知需要先确认,明确失败才允许恢复原提交事件。恢复必须绑定当前最新审批尝试,避免重复创建审批实例或覆盖历史材料。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
- Goals: 为可恢复的退款提供一个安全、可追踪的恢复入口;展示提交状态和最近恢复结果;在列表和详情保持一致。
|
||
- Goals: 将资格判断、数据范围和并发冲突交给后端,前端只消费后端返回的可恢复标记。
|
||
- Non-Goals: 不实现审批引擎、企业微信调用、自动重试调度或新的审批流程。
|
||
|
||
## Decisions
|
||
|
||
- Decision: 新增独立的 `recoverApproval` API,而不是复用历史 `triggerApproval`。
|
||
- Rationale: `trigger-approval` 面向没有审批状态的历史记录;恢复接口面向已有审批尝试的同步/结果确认/原事件恢复,两者的幂等语义和审计含义不同。
|
||
- Decision: 以 `approval_recoverable` 作为按钮展示条件,后端作为最终授权和状态校验方。
|
||
- Rationale: 前端无法可靠重建“结果未知”和“明确失败”等状态,且状态可能在页面打开后发生变化。
|
||
- Decision: 恢复接口只接收路径中的退款 ID,响应返回完整退款详情。
|
||
- Rationale: 防止客户端篡改审批实例、材料或单号;一次响应即可刷新列表/详情所需字段。
|
||
- Decision: 将 `submission_status`、失败摘要和最近恢复时间作为普通退款响应字段展示。
|
||
- Rationale: 列表需要快速筛选/判断,详情需要审计和排障;字段由后端脱敏并保持一致。
|
||
|
||
## State and Concurrency
|
||
|
||
1. 若最新尝试已有 `sp_no`,后端执行原审批单同步。
|
||
2. 若提交结果未知,后端先确认结果;确认成功或已存在时不得再次提交。
|
||
3. 若结果明确提交失败,后端恢复原提交事件;不得创建新的尝试或审批实例。
|
||
4. 若资格在请求期间失效,接口返回状态冲突;前端提示固定文案并刷新详情/列表。
|
||
5. 后端应保证重复请求幂等,前端按钮在请求期间置为 loading,避免重复点击。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- Risk: 列表数据在恢复完成前已过期。
|
||
- Mitigation: 成功和状态冲突都强制重新请求后端;不在前端乐观修改审批状态。
|
||
- Risk: 失败摘要包含凭证或个人信息。
|
||
- Mitigation: 仅展示后端提供的脱敏 `approval_failure_summary`,前端不拼接原始异常。
|
||
- Risk: 新入口与旧历史补发入口混淆。
|
||
- Mitigation: 使用“恢复审批”文案和独立 API,保留两种入口各自的资格条件与说明。
|
||
|
||
## Migration Plan
|
||
|
||
1. 扩展退款响应类型与 API service。
|
||
2. 在列表和详情接入恢复按钮、确认/加载/错误处理和刷新逻辑。
|
||
3. 增加 API、资格显示、冲突刷新和字段展示测试。
|
||
4. 与后端联调已有单号、未知结果、明确失败和不可恢复四类状态。
|
||
|
||
## Open Questions
|
||
|
||
- `submission_status` 的完整枚举值及名称由后端提供,前端是否需要筛选取决于最终列表需求。
|
||
- 状态冲突错误是否有稳定错误码;在未确定前以前端按错误消息或统一冲突码兼容处理。
|
||
|