fix: some

openspec/changes/update-refund-management/specs/refund-api/spec.md

@@ -0,0 +1,59 @@
+## ADDED Requirements
+
+### Requirement: 退款状态与退款方式等枚举
+前端 MUST 定义并导出 `RefundStatus`（1 待审批、2 已通过、3 已拒绝、4 已退回、5 原路退款处理中、6 原路退款失败）、`RefundMethod`（`original_route`/`customer_account`/`asset_wallet`/`agent_wallet`）、`channel_refund_status`（0 未发起或不适用、1 处理中、2 已成功、3 已失败）与 `failure_reason`（`channel_rejected`/`credential_invalid`/`insufficient_balance`/`timeout_unknown`/`approval_rejected`/`revoked_after_approved`/`payment_fact_invalid`）枚举，并提供状态名/Tag 映射与可重提规则。
+
+#### Scenario: 状态 5/6 正常展示
+- **GIVEN** 退款申请状态为 5 或 6
+- **WHEN** 列表/详情渲染状态
+- **THEN** 前端 MUST 展示「原路退款处理中」或「原路退款失败」，不得回退为默认样式
+
+#### Scenario: 原路退款失败可重提规则
+- **GIVEN** 退款申请状态为 6（原路退款失败）
+- **WHEN** `anomaly_flag` 为 1
+- **THEN** 前端 MUST 禁止重提并隐藏/禁用重提入口
+
+### Requirement: 退款响应新增字段
+`Refund` 列表项与详情 MUST 支持 `method`、`method_name`、`frozen_actual_received_amount`、`customer_account_info`、`channel_refund_status`、`channel_refund_status_name`、`channel_refund_no`、`channel_refund_request_no`、`channel_refund_amount`、`channel_refunded_at`、`failure_reason`、`failure_reason_name`、`failure_message`、`anomaly_flag`、`anomaly_reason`、`latest_attempt_id`、`latest_approval_instance_id`、`refund_package_used_mb`、`refund_package_total_mb`（单位 MB，解析不到套餐为 0）与 `attempts[]`。
+
+#### Scenario: 列表展示渠道退款与失败分类
+- **GIVEN** 列表接口返回新增字段
+- **WHEN** 渲染列
+- **THEN** 前端 MUST 展示退款方式、冻结实收金额、渠道退款状态、渠道退款流水号、渠道退款金额、失败分类与异常标记
+
+### Requirement: 审批尝试历史
+详情响应 MUST 支持 `attempts[]`，子字段为 `id`、`attempt_no`、`method`、`method_name`、`refund_amount`、`frozen_actual_received_amount`、`refund_reason`、`customer_account_info`、`customer_voucher_key`、`channel_refund_request_no`、`submitted_by_account_id`、`approval_instance_id`、`approval_status`、`approval_status_name`、`created_at`；详情页 MUST 按时间倒序展示尝试记录。
+
+#### Scenario: 展示多次尝试记录
+- **GIVEN** 详情返回多条 attempts 记录
+- **WHEN** 渲染尝试历史
+- **THEN** 前端 MUST 展示每条尝试的编号、退款方式、金额、审批状态与时间
+
+### Requirement: 创建退款请求契约
+`POST /api/admin/refunds` 请求体 MUST 携带 `method`（必填）、`order_id`、`requested_refund_amount`、`package_usage_id`、`refund_reason`，可选 `customer_account_info` 与 `refund_voucher_key`；MUST NOT 再提交 `actual_received_amount`（已废弃）。
+
+#### Scenario: 客户收款信息方式校验
+- **GIVEN** 退款方式选择 `customer_account`
+- **WHEN** `customer_account_info` 为空或凭证数量为 0
+- **THEN** 前端 MUST 阻止提交并提示同时填写客户收款信息与至少 1 个凭证
+
+#### Scenario: 非客户收款方式
+- **GIVEN** 退款方式为 `original_route`/`asset_wallet`/`agent_wallet`
+- **WHEN** 提交创建申请
+- **THEN** 客户收款信息与凭证 MUST 允许为空
+
+### Requirement: 重提退款请求契约与可重提规则
+`POST /api/admin/refunds/{id}/resubmit` 请求体 MUST 支持可选 `method`、`customer_account_info`（不传沿用原值）、`requested_refund_amount`、`refund_reason`、`refund_voucher_key`；可重提状态 MUST 为 3（已拒绝）/4（已退回）/6（原路退款失败），`anomaly_flag=1` 的申请必须禁止重提。
+
+#### Scenario: 已拒绝申请允许重提
+- **GIVEN** 退款申请状态为 3（已拒绝）且 `anomaly_flag` 不为 1
+- **WHEN** 用户点击重新提交
+- **THEN** 前端 MUST 允许重提并支持可选携带 `method` / `customer_account_info`
+
+### Requirement: 审批接口封装与按钮保护
+`RefundService` MUST 提供 `approveRefund`（`approved_refund_amount`、`remark`）、`rejectRefund`（`reject_reason`）、`returnRefund`（`remark`）；列表/详情审批按钮 MUST 在 `approval_instance_id` 存在时隐藏/禁用，仅存量无审批实例的申请可用。
+
+#### Scenario: 已关联企微审批实例不可审批
+- **GIVEN** 退款申请已关联 `approval_instance_id`
+- **WHEN** 渲染审批操作
+- **THEN** 通过/拒绝/退回按钮 MUST 隐藏或禁用