one-pipe-system/openspec/changes/update-refund-voucher-multi-image/specs/order-management/spec.md at 0c3065f970763d21704c1b4483cf54e601aa712e

Files

构建并部署前端到测试环境 / build-and-deploy (push) Successful in 7m52s

Details

Constraint: 后端订单套餐作废接口使用 /api/admin/order-package-invalidate-tasks，上传
  purpose 只能使用 attachment。
  Rejected: 继续提交逗号拼接凭证字符串 | 新提交路径必须使用 string[]，历史字符串只做读取归一化。
  Confidence: high
  Scope-risk: broad
  Directive: 新增订单套餐作废权限时需同时配置菜单 URL 与
  order_package_invalidate_task:create/detail 按钮权限。
  Tested: bun run build；development 真实后端联调上传、创建、列表、详情通过；复机接口未触发。
  Not-tested: 未逐一手工覆盖所有历史凭证数据、全部角色权限组合和所有文件扩展名预览

2026-06-23 09:50:12 +08:00

5.3 KiB

Raw Blame History

ADDED Requirements

Requirement: Refund Detail Inline Voucher Preview

The system SHALL display refund voucher images directly in the refund detail page when voucher file keys exist, and each displayed image SHALL support click-to-enlarge preview. Refund voucher viewing from the refund list SHALL be controlled by the permission code refund:view_voucher.

Scenario: Display and enlarge refund voucher in detail

GIVEN 用户打开退款详情页
AND 退款详情数据包含一个或多个退款凭证文件 key
WHEN 页面渲染退款凭证区域
THEN 系统 MUST 直接展示对应的凭证图片
AND 用户点击任一凭证图片后，系统 MUST 放大预览该图片

Scenario: Hide voucher images when no voucher exists

GIVEN 用户打开退款详情页
WHEN 退款详情数据不包含退款凭证文件 key
THEN 系统 MUST NOT 展示空的凭证图片占位
AND 系统 MAY display - or equivalent empty-state text for the voucher field

Scenario: Show refund voucher list action with permission

GIVEN 用户正在查看退款管理列表
AND 某条退款记录存在 refund_voucher_key
AND 当前用户拥有 refund:view_voucher 权限编码
WHEN 系统渲染该行操作列
THEN 系统 MUST show the 查看退款凭证 action

Scenario: Hide refund voucher list action without permission

GIVEN 用户正在查看退款管理列表
AND 某条退款记录存在 refund_voucher_key
AND 当前用户不拥有 refund:view_voucher 权限编码
WHEN 系统渲染该行操作列
THEN 系统 MUST NOT show the 查看退款凭证 action

Requirement: Refund Application Paid Order Filtering

The system SHALL restrict the order number search/select request in create refund application to paid orders by including payment_status: 2 in the query parameters.

Scenario: Search selectable orders for refund application

GIVEN 用户正在创建退款申请
WHEN 用户通过订单号搜索/选择订单
THEN 系统 MUST call the order search/list API with payment_status: 2
AND 未支付、已取消或其他非已支付状态订单 MUST NOT be returned as selectable refund orders by the frontend query

Requirement: Refund Application Zero Amount

The system SHALL allow the requested refund amount in create refund application to be 0, while still preventing negative amounts and amounts greater than the actual received amount.

Scenario: Submit zero requested refund amount

GIVEN 用户正在创建退款申请
AND 用户已选择可退款订单
WHEN 用户输入申请退款金额 0
THEN 系统 MUST allow the amount validation to pass
AND 系统 MUST submit requested_refund_amount as 0

Scenario: Block negative requested refund amount

GIVEN 用户正在创建退款申请
WHEN 用户输入小于 0 的申请退款金额
THEN 系统 MUST prevent submission
AND 系统 MUST 提示申请退款金额不能小于 0

Scenario: Block requested refund amount above actual received amount

GIVEN 用户正在创建退款申请
AND 已选订单存在实收金额
WHEN 用户输入的申请退款金额大于实收金额
THEN 系统 MUST prevent submission
AND 系统 MUST 提示申请退款金额不能大于实收金额

Requirement: Refund Management Multi Image Voucher Upload

The system SHALL allow multiple refund voucher images in any browser-recognized image format to be uploaded in refund management and SHALL submit all uploaded file keys in the refund_voucher_key parameter as a string[]. The earlier comma-separated-string submission convention is superseded by ADR-0001; legacy single-key strings and comma-separated strings are only normalized when reading existing records for display.

Scenario: Submit multiple uploaded voucher images

GIVEN 用户正在退款管理中创建或提交退款相关记录
AND 用户上传了多张退款凭证图片
WHEN 每张图片上传成功并返回文件 key
AND 用户提交表单
THEN 系统 MUST put the uploaded file keys into refund_voucher_key as a string[]
AND refund_voucher_key MUST look like ["attachments/a.jpg", "attachments/b.jpg"] when multiple files exist
AND 系统 MUST NOT submit a comma-separated voucher string for new records

Scenario: Upload any image format refund voucher without frontend size limit

GIVEN 用户正在创建退款申请
WHEN 用户选择或拖入任意浏览器识别为图片类型的退款凭证
THEN 系统 MUST NOT reject the file based on frontend file size checks
AND 系统 MUST accept the file when its MIME type starts with image/

Scenario: Submit single uploaded voucher image

GIVEN 用户正在退款管理中创建或提交退款相关记录
AND 用户只上传了一张退款凭证图片
WHEN 用户提交表单
THEN 系统 MUST put that single file key into refund_voucher_key as a one-item string[]

Scenario: Block submission without required voucher image

GIVEN 退款管理表单要求上传退款凭证
WHEN 用户未上传任何凭证图片并尝试提交
THEN 系统 MUST prevent submission
AND 系统 MUST 提示用户上传退款凭证

5.3 KiB Raw Blame History