3.9 KiB
3.9 KiB
Change: 退款管理契约适配（字段与状态枚举）
Why
后端按 docs/产品迭代8月份/refund-api-simple-2.md 调整退款管理契约：本次未新增任何路由，前端无需新增 URL，但创建/重提/审批的请求体、列表与详情的响应字段、状态枚举（1-6）、可重提规则、审批尝试历史（attempts[]）、退款方式与渠道退款/失败分类展示，以及支付商户/旧支付配置新增退款用 PEM 凭证字段均发生变化。后台前端现有 Refund 类型、创建/重提表单、列表/详情展示与审批入口尚未对齐，需按新文档适配。
What Changes
- 状态与枚举：
RefundStatus扩展 5（原路退款处理中）与 6（原路退款失败）；新增RefundMethod（original_route/customer_account/asset_wallet/agent_wallet）、channel_refund_status（0-3）与failure_reason枚举及名称映射。 - 响应字段：列表/详情
Refund补充method、method_name、frozen_actual_received_amount、customer_account_info、channel_refund_status(_name)、channel_refund_no、channel_refund_request_no、channel_refund_amount、channel_refunded_at、failure_reason(_name)、failure_message、anomaly_flag、anomaly_reason、latest_attempt_id、latest_approval_instance_id、attempts[]、refund_package_used_mb、refund_package_total_mb；attempts[]按文档定义 14 个子字段。 - 创建退款：请求体新增
method（必填）与可选customer_account_info；customer_account（客户收款信息）方式下 MUST 同时给customer_account_info与至少 1 个凭证；actual_received_amount废弃、不再提交。 - 重提退款：可重提状态扩为 3（已拒绝）/4（已退回）/6（原路退款失败），
anomaly_flag=1的申请禁止重提；请求体新增可选method、customer_account_info（不传沿用原值）；每次重提新建审批尝试与审批实例。 - 审批操作：补封装
approve/reject/return接口；已关联企微审批实例（approval_instance_id）的申请审批按钮隐藏/禁用，仅存量无实例可用。 - 页面：列表页新增状态 5/6 展示与退款方式、冻结实收金额、渠道退款状态/流水号/金额、失败分类、异常标记、套餐已用量/总量等列；详情页展示新字段与
attempts[]尝试历史；创建/重提弹窗支持退款方式与客户收款信息。 - 支付商户：
wechat_v2凭证模板 optional 新增wx_client_cert_content、wx_client_key_content（PEM 文本），不填不影响支付/查单/回调，仅原路退款按凭证不完整禁用并提示。 - 旧支付配置：
wechat-configs创建/更新/查询响应新增wx_client_cert_content、wx_client_key_content（可选），支付配置表单补齐两个可选 PEM 输入。 - 退款导出：无新接口，
scene=refund导出列由后端模板扩展（本轮 2 列 + 上一轮 7 列），前端导出任务列表维持复用，不新增列定义。 customer_account_info子字段结构以docs/admin-openapi.yaml为准；本提案先以宽松键值结构（Record<string, string>）承载与展示，表单按退款方式联动必填。- 不实现后端接口、数据库、渠道退款；不改动审批实例数据。
Impact
- Affected specs:
refund-api、refund-pages、payment-merchant-credentials、wechat-configs - Affected code:
src/types/api/refund.ts、src/api/modules/refund.ts、src/views/finance/refund/index.vue、src/views/finance/refund/detail.vue、src/components/business/CreateRefundDialog.vue、src/types/api/paymentMerchantPools.ts、src/views/settings/payment-merchant-pools/components/MerchantManagement.vue、src/types/api/paymentSettings.ts、src/views/settings/payment-settings/index.vue、src/views/settings/payment-settings/detail.vue - Dependencies:
docs/产品迭代8月份/refund-api-simple-2.md