Files
one-pipe-system/openspec/changes/add-refund-approval-recovery/specs/refund-management/spec.md
luo c5d7a260d0
All checks were successful
构建并部署前端到测试环境 / deploy (push) Successful in 55s
fix: 恢复退款原审批提交
2026-09-20 18:13:14 +08:00

87 lines
4.3 KiB
Markdown

## 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