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

4.3 KiB

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