junhong_cmp_fiber/openspec/specs/refund-api/spec.md

ADDED Requirements

Requirement: 发起退款申请接口

POST /api/admin/refunds SHALL 创建退款申请。请求体 MUST 包含 order_id、actual_received_amount、requested_refund_amount、refund_reason。可选 package_usage_id。仅平台用户（user_type IN 1,2）可调用。

Scenario: 成功创建退款申请

• WHEN 平台管理员提交合法的退款申请（关联已支付套餐订单且无进行中的退款记录）
• THEN 系统 SHALL 返回创建成功的退款记录，状态为待审批

Scenario: 订单不可退款

• WHEN 管理员对非已支付订单、充值订单或已有进行中退款记录的订单发起退款
• THEN 系统 SHALL 返回对应错误

Requirement: 退款列表查询接口

GET /api/admin/refunds SHALL 返回分页退款列表，支持按 status、order_id、shop_id 筛选。自动应用数据权限过滤（通过 shop_id 字段）。

Scenario: 按状态筛选退款列表

• WHEN 管理员查询 status=1 的退款列表
• THEN 系统 SHALL 返回所有待审批的退款记录，支持分页

Requirement: 退款详情查询接口

GET /api/admin/refunds/:id SHALL 返回退款单详情，包含关联订单信息。

Scenario: 查询退款详情

• WHEN 管理员查询某退款单详情
• THEN 系统 SHALL 返回退款单完整信息（含 commission_deducted 和 asset_reset 标记状态，其中 asset_reset 表示退款后资产处理是否完成）

Requirement: 审批通过接口

POST /api/admin/refunds/:id/approve SHALL 审批通过退款。请求体可选 approved_refund_amount（不填则等于 requested_refund_amount）和 remark。审批通过后异步触发资产处理和佣金全额回扣。

Scenario: 审批通过并触发副作用

• WHEN 审批人通过退款申请
• THEN 退款状态 SHALL 变为已通过，记录审批人和审批时间，并同步将订单状态更新为已退款
• AND 系统 SHALL 异步执行：精准失效本次退款关联套餐 → 尝试接续待生效主套餐 → 必要时停机 → 标记 asset_reset=true
• AND 系统 SHALL 异步执行：全额回扣该订单所有佣金 → 标记 commission_deducted=true

Requirement: 审批拒绝接口

POST /api/admin/refunds/:id/reject SHALL 拒绝退款。请求体 MUST 包含 reject_reason。

Scenario: 拒绝退款

• WHEN 审批人拒绝退款且填写了拒绝原因
• THEN 退款状态 SHALL 变为已拒绝

Requirement: 退回申请接口

POST /api/admin/refunds/:id/return SHALL 退回退款申请。请求体可选 remark。

Scenario: 退回退款申请

• WHEN 审批人退回退款申请
• THEN 退款状态 SHALL 变为已退回，申请人可重新提交

Requirement: 重新提交接口

POST /api/admin/refunds/:id/resubmit SHALL 重新提交被退回的退款申请。请求体可修改 actual_received_amount、requested_refund_amount、refund_reason。

Scenario: 重新提交退款申请

• WHEN 申请人重新提交被退回的退款
• THEN 退款状态 SHALL 从已退回变回待审批