From c5d7a260d03c446ab8fcaac9a4d765c2ca725362 Mon Sep 17 00:00:00 2001 From: luo Date: Sun, 20 Sep 2026 18:13:14 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20=E6=81=A2=E5=A4=8D=E9=80=80=E6=AC=BE?= =?UTF-8?q?=E5=8E=9F=E5=AE=A1=E6=89=B9=E6=8F=90=E4=BA=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../add-refund-approval-recovery/design.md | 50 ++++++++++ .../add-refund-approval-recovery/proposal.md | 37 +++++++ .../specs/refund-management/spec.md | 86 ++++++++++++++++ .../add-refund-approval-recovery/tasks.md | 22 +++++ src/api/modules/refund.ts | 13 ++- src/types/api/refund.ts | 7 +- src/views/finance/refund/detail.vue | 91 ++++++++++++++++- src/views/finance/refund/index.vue | 98 ++++++++++++++++++- 8 files changed, 400 insertions(+), 4 deletions(-) create mode 100644 openspec/changes/add-refund-approval-recovery/design.md create mode 100644 openspec/changes/add-refund-approval-recovery/proposal.md create mode 100644 openspec/changes/add-refund-approval-recovery/specs/refund-management/spec.md create mode 100644 openspec/changes/add-refund-approval-recovery/tasks.md diff --git a/openspec/changes/add-refund-approval-recovery/design.md b/openspec/changes/add-refund-approval-recovery/design.md new file mode 100644 index 0000000..6244757 --- /dev/null +++ b/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` 的完整枚举值及名称由后端提供,前端是否需要筛选取决于最终列表需求。 +- 状态冲突错误是否有稳定错误码;在未确定前以前端按错误消息或统一冲突码兼容处理。 + diff --git a/openspec/changes/add-refund-approval-recovery/proposal.md b/openspec/changes/add-refund-approval-recovery/proposal.md new file mode 100644 index 0000000..2c70a85 --- /dev/null +++ b/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` 历史审批补发。 + diff --git a/openspec/changes/add-refund-approval-recovery/specs/refund-management/spec.md b/openspec/changes/add-refund-approval-recovery/specs/refund-management/spec.md new file mode 100644 index 0000000..957f2bc --- /dev/null +++ b/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 + diff --git a/openspec/changes/add-refund-approval-recovery/tasks.md b/openspec/changes/add-refund-approval-recovery/tasks.md new file mode 100644 index 0000000..ca967a1 --- /dev/null +++ b/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`。 + diff --git a/src/api/modules/refund.ts b/src/api/modules/refund.ts index d6e999e..d037ef3 100644 --- a/src/api/modules/refund.ts +++ b/src/api/modules/refund.ts @@ -83,4 +83,15 @@ export class RefundService extends BaseService { static triggerApproval(id: number): Promise> { return this.post>(`/api/admin/refunds/${id}/trigger-approval`) } -} \ No newline at end of file + + /** + * 恢复退款原审批提交 + * + * 后端负责同步已有审批单、确认未知提交结果或恢复明确失败的原提交事件。 + * 此操作不接收审批实例 ID、审批材料或企业微信单号,也不会创建新的审批尝试。 + * @param id 退款申请ID + */ + static recoverApproval(id: number): Promise> { + return this.post>(`/api/admin/refunds/${id}/recover-approval`) + } +} diff --git a/src/types/api/refund.ts b/src/types/api/refund.ts index cab95f6..4895ed6 100644 --- a/src/types/api/refund.ts +++ b/src/types/api/refund.ts @@ -140,6 +140,11 @@ export interface Refund { approval_source?: 'none' | 'legacy' | 'wecom' | null // 审批来源 approval_status?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | null // 审批状态 approval_status_name?: string | null // 审批状态名称 + submission_status?: number | null // 企业微信审批提交状态 + submission_status_name?: string | null // 企业微信审批提交状态名称 + approval_recoverable?: boolean // 是否允许恢复原审批提交 + approval_failure_summary?: string | null // 脱敏审批失败摘要 + approval_last_recovery_at?: string | null // 最近一次审批恢复时间 current_approver_summary?: string | null // 当前审批人摘要 processing_status?: string | null // 业务处理状态 processing_status_name?: string | null // 业务处理状态名称 @@ -210,4 +215,4 @@ export interface RejectRefundRequest { // 退回退款申请请求 export interface ReturnRefundRequest { remark?: string -} \ No newline at end of file +} diff --git a/src/views/finance/refund/detail.vue b/src/views/finance/refund/detail.vue index c26045a..467ade2 100644 --- a/src/views/finance/refund/detail.vue +++ b/src/views/finance/refund/detail.vue @@ -17,6 +17,14 @@ > 重新申请 + + 恢复审批 +