feat: 新增退款凭证

openspec/changes/update-refund-order-voucher/proposal.md

@@ -0,0 +1,21 @@
+# Change: Update Refund Order Voucher Requirements
+
+## Why
+
+退款管理的创建订单流程需要记录退款凭证图片，便于财务审核和后续追溯。用户也需要在退款订单列表和详情中像订单列表的支付凭证一样直接查看退款凭证。
+
+## What Changes
+
+- Add required `refund_voucher_key` to refund order creation payload, sourced from `/storage/upload-url` image upload result.
+- Add a "查看退款凭证" action in refund order list operations when the order has `refund_voucher_key`.
+- Display refund voucher directly in refund order details when `refund_voucher_key` exists.
+
+## Impact
+
+- Affected specs: `order-management`
+- Affected code:
+  - Refund management create order dialog/form and API payload typing
+  - Refund order list action column
+  - Refund order detail view
+  - Shared voucher preview/upload utilities if reused from order payment voucher flow
+- Breaking changes: Existing refund order creation now requires `refund_voucher_key`.

openspec/changes/update-refund-order-voucher/specs/order-management/spec.md

@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: Refund Order Voucher Upload
+
+The system SHALL require a refund voucher file key when creating a refund order in refund management.
+
+#### Scenario: Create refund order with uploaded voucher
+
+- **GIVEN** 用户正在退款管理中创建退款订单
+- **WHEN** 用户通过 `/storage/upload-url` 上传退款凭证图片并获得 `file_key`
+- **AND** 用户提交创建退款订单表单
+- **THEN** 系统 MUST 将该 `file_key` 作为 `refund_voucher_key` 提交
+- **AND** `refund_voucher_key` MUST be a non-empty string
+
+#### Scenario: Block refund order creation without voucher
+
+- **GIVEN** 用户正在退款管理中创建退款订单
+- **WHEN** 用户未上传退款凭证图片或未获得 `file_key`
+- **AND** 用户尝试提交创建退款订单表单
+- **THEN** 系统 MUST prevent submission
+- **AND** 系统 MUST 提示用户上传退款凭证
+
+### Requirement: Refund Voucher Viewing
+
+The system SHALL allow users to view refund vouchers from refund order list operations and refund order details when `refund_voucher_key` exists.
+
+#### Scenario: View refund voucher from refund order list action
+
+- **GIVEN** 用户正在查看退款订单列表
+- **WHEN** 某条退款订单存在 `refund_voucher_key`
+- **THEN** 系统 MUST 在操作列提供查看退款凭证入口
+- **AND** 该入口的查看体验 MUST be consistent with the existing order list payment voucher preview behavior
+
+#### Scenario: Hide refund voucher action when no voucher exists
+
+- **GIVEN** 用户正在查看退款订单列表
+- **WHEN** 某条退款订单不存在 `refund_voucher_key`
+- **THEN** 系统 MUST NOT display an enabled refund voucher preview action for that order
+
+#### Scenario: Display refund voucher in refund order detail
+
+- **GIVEN** 用户打开退款订单详情
+- **WHEN** 详情数据包含 `refund_voucher_key`
+- **THEN** 系统 MUST directly display the refund voucher image or preview entry in the detail content
+- **AND** 用户 MUST NOT need to return to the list to view the voucher

openspec/changes/update-refund-order-voucher/tasks.md

@@ -0,0 +1,9 @@
+## 1. Implementation
+
+- [x] 1.1 Update refund order creation request type to include required `refund_voucher_key: string`.
+- [x] 1.2 Add refund voucher image upload to the refund order creation form using `/storage/upload-url`, storing the returned file key.
+- [x] 1.3 Validate that refund voucher is uploaded before allowing refund order creation.
+- [x] 1.4 Submit `refund_voucher_key` in the create refund order payload.
+- [x] 1.5 Add a list operation to view the refund voucher when `refund_voucher_key` exists, matching the existing order list payment voucher behavior.
+- [x] 1.6 Show the refund voucher directly in refund order details when `refund_voucher_key` exists.
+- [x] 1.7 Verify create, list preview, and detail display flows manually or with existing tests.