fix: 恢复退款原审批提交

openspec/changes/add-refund-approval-recovery/design.md

@@ -0,0 +1,50 @@
+## 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` 的完整枚举值及名称由后端提供，前端是否需要筛选取决于最终列表需求。
+- 状态冲突错误是否有稳定错误码；在未确定前以前端按错误消息或统一冲突码兼容处理。
+

openspec/changes/add-refund-approval-recovery/proposal.md

@@ -0,0 +1,37 @@
+# Change: 增加退款原审批恢复
+
+## Why
+
+退款审批提交可能出现企业微信单号已生成但本地结果未知、原提交事件明确失败，或需要重新同步已有审批单的情况。当前退款页面只有历史记录的“补发审批”能力，无法安全地恢复同一审批尝试；运营人员也缺少提交状态、失败摘要和最近恢复时间，难以判断是否可以处理。
+
+## What Changes
+
+- 新增 `POST /api/admin/refunds/{id}/recover-approval`，无请求体，调用后恢复原审批提交事件或确认未知结果。
+- 新增 `RefundService.recoverApproval(id)`，成功响应解析为更新后的退款详情。
+- 扩展退款列表和详情模型，支持 `submission_status`、`submission_status_name`、`approval_recoverable`、`approval_failure_summary`、`approval_last_recovery_at`。
+- 在退款列表和详情中，仅当后端返回 `approval_recoverable = true` 且当前账号具备退款管理权限及数据范围时显示“恢复审批”。
+- 恢复成功后刷新当前列表/详情；遇到状态冲突时提示“当前退款审批状态不允许恢复”并重新加载后端状态。
+- 恢复动作沿用退款管理权限和数据范围，不新增审批实例、审批尝试、审批材料、审批实例 ID 或企业微信单号输入，也不替代现有历史审批“补发”能力。
+
+## Impact
+
+- Affected specs:
+  - `refund-management`
+- Affected code:
+  - `src/api/modules/refund.ts`
+  - `src/types/api/refund.ts`
+  - `src/views/finance/refund/index.vue`
+  - `src/views/finance/refund/detail.vue`
+- API contract:
+  - `POST /api/admin/refunds/{id}/recover-approval`
+  - `GET /api/admin/refunds`
+  - `GET /api/admin/refunds/{id}`
+- Dependencies:
+  - 后端返回 `approval_recoverable` 的最终资格判断，并在服务端保证幂等、并发状态校验和数据范围校验。
+  - 后端成功响应包含完整退款详情，失败响应遵循现有统一错误结构。
+- Out of scope:
+  - 创建新的审批尝试或审批实例。
+  - 前端直接调用企业微信、传入审批实例 ID、审批材料或 `sp_no`。
+  - 修改退款金额、退款方式、审批结果或渠道退款流程。
+  - 批量恢复、自动轮询恢复或替代 `trigger-approval` 历史审批补发。
+

openspec/changes/add-refund-approval-recovery/specs/refund-management/spec.md

@@ -0,0 +1,86 @@
+## ADDED Requirements
+
+### Requirement: Refund Approval Recovery API
+
+The refund service SHALL expose `POST /api/admin/refunds/{id}/recover-approval` with no request body. The operation SHALL use the existing refund-management permission and data scope, and SHALL return the updated complete refund record on success.
+
+#### Scenario: Recover an existing approval submission
+
+- **GIVEN** a refund record is marked `approval_recoverable = true`
+- **WHEN** the client posts to `/api/admin/refunds/{id}/recover-approval`
+- **THEN** the request MUST contain only the refund ID path parameter and no body
+- **AND** a successful response MUST contain the updated refund detail, including the latest submission and approval fields
+
+#### Scenario: Reject unauthorized or out-of-scope recovery
+
+- **GIVEN** the current account lacks refund-management permission or data scope for the refund
+- **WHEN** the client calls the recovery endpoint
+- **THEN** the service MUST reject the request using the existing authentication/authorization error contract
+
+### Requirement: Recovery Preserves the Original Approval Attempt
+
+The recovery operation SHALL synchronize an existing approval identified by `sp_no`, confirm an unknown submission result before retrying, or restore the original submission event after an explicit submission failure. It MUST NOT create a new approval attempt or approval instance.
+
+#### Scenario: Existing WeCom approval number
+
+- **GIVEN** the latest approval attempt already has an `sp_no`
+- **WHEN** recovery is requested
+- **THEN** the service MUST trigger synchronization of that original approval
+- **AND** MUST preserve the existing approval attempt and instance
+
+#### Scenario: Unknown submission result
+
+- **GIVEN** the submission result is unknown
+- **WHEN** recovery is requested
+- **THEN** the service MUST confirm the submission result before any resubmission
+- **AND** MUST NOT create a duplicate approval when the original submission is found
+
+#### Scenario: Explicit submission failure
+
+- **GIVEN** the original submission is explicitly known to have failed
+- **WHEN** recovery is requested
+- **THEN** the service MUST restore the original submission event
+- **AND** MUST NOT create a new approval attempt or approval instance
+
+### Requirement: Refund Approval Recovery Fields
+
+Refund list and detail responses SHALL expose `submission_status`, `submission_status_name`, `approval_recoverable`, `approval_failure_summary`, and `approval_last_recovery_at`. The failure summary MUST be a redacted diagnostic value supplied by the backend.
+
+#### Scenario: Display recovery metadata
+
+- **GIVEN** a refund response contains recovery metadata
+- **WHEN** the list or detail page renders the record
+- **THEN** it MUST display the submission status name, redacted failure summary when present, and the latest recovery time
+- **AND** it MUST use `approval_recoverable` from the response without deriving eligibility from stale local fields
+
+### Requirement: Refund Approval Recovery Entry
+
+The refund list and detail pages SHALL show a “恢复审批” action only when the backend returns `approval_recoverable = true` and the existing refund-management permission and data scope allow access.
+
+#### Scenario: Show recovery action for an eligible record
+
+- **GIVEN** `approval_recoverable` is `true`
+- **AND** the current account can access the refund under existing permission and data scope
+- **WHEN** the page renders the record
+- **THEN** the page MUST show the “恢复审批” action
+
+#### Scenario: Hide recovery action for an ineligible record
+
+- **GIVEN** `approval_recoverable` is `false`, absent, or the account cannot access the refund
+- **WHEN** the page renders the record
+- **THEN** the page MUST NOT show the “恢复审批” action
+
+#### Scenario: Recovery succeeds
+
+- **GIVEN** the user confirms recovery for an eligible record
+- **WHEN** the recovery endpoint succeeds
+- **THEN** the page MUST show a success message and reload the list or detail from the backend
+- **AND** the refreshed record MUST show the latest submission and approval state
+
+#### Scenario: Recovery conflicts with a concurrent state change
+
+- **GIVEN** the record becomes non-recoverable before the request is processed
+- **WHEN** the endpoint returns a status conflict
+- **THEN** the page MUST show “当前退款审批状态不允许恢复”
+- **AND** MUST reload the current record instead of applying an optimistic state
+

openspec/changes/add-refund-approval-recovery/tasks.md

@@ -0,0 +1,22 @@
+## 1. Contract And Types
+
+- [ ] 1.1 在 `Refund` 列表/详情类型中增加 `submission_status`、`submission_status_name`、`approval_recoverable`、`approval_failure_summary`、`approval_last_recovery_at`。
+- [ ] 1.2 在 `RefundService` 增加 `recoverApproval(id)`，调用无请求体的 `POST /api/admin/refunds/{id}/recover-approval` 并返回完整 `Refund`。
+- [ ] 1.3 补充 API 注释和统一错误响应处理，明确不传审批实例 ID、材料或企业微信单号。
+
+## 2. Refund List And Detail
+
+- [ ] 2.1 列表展示提交状态名称、脱敏失败摘要和最近恢复时间（按页面现有字段展示约定接入）。
+- [ ] 2.2 仅在 `approval_recoverable === true` 且通过现有退款管理权限/数据范围校验时显示“恢复审批”操作。
+- [ ] 2.3 恢复操作增加确认和请求中 loading，成功后刷新列表并展示最新响应数据。
+- [ ] 2.4 详情页展示上述字段和“恢复审批”操作；成功后刷新详情。
+- [ ] 2.5 处理状态冲突：提示“当前退款审批状态不允许恢复”，并刷新当前数据；其他后端错误沿用统一错误提示。
+
+## 3. Verification
+
+- [ ] 3.1 测试已有 `sp_no`、提交结果未知、明确提交失败和不可恢复记录的入口展示与刷新行为。
+- [ ] 3.2 测试无退款权限、越权数据和 `approval_recoverable = false` 时不显示按钮。
+- [ ] 3.3 测试重复点击被 loading 阻止，且请求体为空、不携带审批材料或实例 ID。
+- [ ] 3.4 运行相关单元测试、类型检查、lint 和构建。
+- [ ] 3.5 运行 `openspec.cmd validate add-refund-approval-recovery --strict`。
+