文档：退款政策与原因管理接口 v2->v3 路径对照与算法差异说明（管理后台）
这个提交包含在：
yaosutu
父节点
8f9153e630
当前提交
3c50202413
@ -0,0 +1,235 @@
|
||||
# 退款政策与退款原因管理接口 v2->v3 迁移说明（管理后台）
|
||||
|
||||
- **端类型**：管理后台
|
||||
- **日期**：2026-06-22
|
||||
- **服务**：hl-order-service-v3（端口 8086）
|
||||
- **接口路径前缀**：`/v3/admin/order/refund-policy`
|
||||
|
||||
---
|
||||
|
||||
## 1. 接口背景
|
||||
|
||||
退款政策与退款原因管理功能已在 v3 就绪，与 v2 功能一致，路径整体由
|
||||
`/admin/order/refund-policy` 升版为 `/v3/admin/order/refund-policy`。
|
||||
本文档补充 v2→v3 完整路径对照表与退款金额计算算法差异，供前端迁移核对。
|
||||
|
||||
---
|
||||
|
||||
## 2. 变更清单
|
||||
|
||||
| 类型 | 描述 |
|
||||
|------|------|
|
||||
| 路径变更 | 退款政策 7 个端点：/admin/order/refund-policy/* 统一升为 /v3/admin/order/refund-policy/* |
|
||||
| 路径变更 | 退款原因 3 个端点：/admin/order/refund-policy/reason/* 统一升为 /v3/admin/order/refund-policy/reason/* |
|
||||
| 无字段变更 | 入参/出参/枚举全部与 v2 一致 |
|
||||
| 算法差异 | 退款金额计算：v3 区间判定与舍入方式与 v2 不同（详见第 12 节） |
|
||||
|
||||
---
|
||||
|
||||
## 3. 接口详情
|
||||
|
||||
- **认证**：需携带管理端 JWT（Authorization: Bearer token），Gateway 注入 adminId
|
||||
- **幂等性**：GET 天然幂等；POST/PUT 非幂等，重复提交会新建或覆盖
|
||||
- **限流**：走 Gateway 全局策略，无独立限流
|
||||
- **Content-Type**：application/json
|
||||
|
||||
---
|
||||
|
||||
## 4. 入参
|
||||
|
||||
### 4.1 路径参数 / Query 参数
|
||||
|
||||
| 接口 | 参数名 | 类型 | 必填 | 说明 |
|
||||
|------|--------|------|------|------|
|
||||
| GET /enabled | payType | String | 否 | FULL 或 DEPOSIT；不传返回全部启用政策 |
|
||||
| GET /{policyId} | policyId | Long | 是 | 路径参数 |
|
||||
| PUT /{policyId} | policyId | Long | 是 | 路径参数 |
|
||||
| DELETE /{policyId} | policyId | Long | 是 | 路径参数 |
|
||||
| PUT /{policyId}/toggle | policyId | Long | 是 | 路径参数 |
|
||||
| PUT /{policyId}/toggle | enabled | Boolean | 是 | Query 参数，true=启用 |
|
||||
| PUT /reason/{reasonId} | reasonId | Long | 是 | 路径参数 |
|
||||
| DELETE /reason/{reasonId} | reasonId | Long | 是 | 路径参数 |
|
||||
|
||||
### 4.2 请求体字段
|
||||
|
||||
#### 退款政策请求 RefundPolicyRequest（创建/修改通用）
|
||||
|
||||
| 字段 | 类型 | 必填 | 校验 | 说明 |
|
||||
|------|------|------|------|------|
|
||||
| policyName | String | 是 | 非空，<=100 字 | 政策名称 |
|
||||
| remark | String | 否 | <=500 字 | 备注说明 |
|
||||
| applyPayType | String | 否 | FULL/DEPOSIT/BOTH | 适用支付类型；不传后端默认 BOTH |
|
||||
| rules | Array | 是 | 非空，至少 1 条 | 退款规则阶梯列表 |
|
||||
| rules[].minDays | Integer | 是 | >=0 | 距出发最少天数（含当天） |
|
||||
| rules[].refundRatio | Integer | 是 | 0~100 | 退款比例（百分比） |
|
||||
|
||||
#### 退款原因请求 RefundReasonRequest（创建/修改通用）
|
||||
|
||||
| 字段 | 类型 | 必填 | 校验 | 说明 |
|
||||
|------|------|------|------|------|
|
||||
| reasonText | String | 是 | 非空，<=200 字 | C 端可见原因文本 |
|
||||
| reasonCode | String | 否 | <=64 字 | 机器可读编码，如 TIME_CONFLICT/OTHER |
|
||||
| category | String | 否 | <=50 字 | 分类，取值来自字典 refund_reason_category |
|
||||
| sortOrder | Integer | 否 | — | 排序号，越小越靠前 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 出参字段
|
||||
|
||||
### RefundPolicyVO（退款政策）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| policyId | String（Long 序列化） | 政策 ID（雪花） |
|
||||
| policyName | String | 政策名称 |
|
||||
| enabled | Boolean | 是否启用 |
|
||||
| applyPayType | String | 适用支付类型（FULL/DEPOSIT/BOTH） |
|
||||
| remark | String | 备注，可为 null |
|
||||
| createdBy | String（Long 序列化） | 创建人 adminId |
|
||||
| createTime | String（ISO 8601） | 创建时间 |
|
||||
| updateTime | String（ISO 8601） | 更新时间 |
|
||||
| rules | Array | 退款规则阶梯列表，按 minDays 升序 |
|
||||
| rules[].ruleId | String（Long 序列化） | 规则 ID |
|
||||
| rules[].minDays | Integer | 距出发最少天数 |
|
||||
| rules[].refundRatio | Integer | 退款比例（百分比） |
|
||||
|
||||
> VO 不返回 maxDays（区间上界由后端按规则集排序推导），前端只需展示 minDays + refundRatio。
|
||||
|
||||
### RefundReasonVO（退款原因）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| reasonId | String（Long 序列化） | 原因 ID（雪花） |
|
||||
| reasonText | String | 原因描述（C 端展示文本） |
|
||||
| reasonCode | String | 业务编码，可为 null |
|
||||
| category | String | 分类（字典 refund_reason_category 值） |
|
||||
| sortOrder | Integer | 排序号 |
|
||||
| enabled | Boolean | 是否启用 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 枚举 / 数据字典
|
||||
|
||||
### applyPayType（字典 payment_type）
|
||||
|
||||
| 值 | 含义 |
|
||||
|----|------|
|
||||
| FULL | 仅适用全款支付产品 |
|
||||
| DEPOSIT | 仅适用定金支付产品 |
|
||||
| BOTH | 全款与定金均适用（默认值） |
|
||||
|
||||
> GET /enabled 的 payType Query 参数只接受 FULL 或 DEPOSIT（不接受 BOTH）。
|
||||
> 传 FULL 返回 applyPayType 为 FULL 或 BOTH 的政策；传 DEPOSIT 同理。
|
||||
|
||||
### category（字典 refund_reason_category）
|
||||
|
||||
退款原因分类，取值由系统数据字典 refund_reason_category 维护。
|
||||
创建/修改时传字典中已有的 key，后端不做枚举校验，建议与字典保持一致。
|
||||
|
||||
---
|
||||
|
||||
## 7. 错误码
|
||||
|
||||
| 错误码 | 说明 | 触发条件 |
|
||||
|--------|------|----------|
|
||||
| 200 | 成功 | — |
|
||||
| 400 | 参数校验失败 | policyName 为空/rules 为空/refundRatio 超出 0~100/applyPayType 非法值 |
|
||||
| 530209 | 退款政策阶梯天数重复或重叠 | rules 中有相同 minDays |
|
||||
| 1002 | 资源不存在 | policyId/reasonId 不存在或已软删除 |
|
||||
| 401 | 未认证 | 未携带或 JWT 失效 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 示例
|
||||
|
||||
### 8.1 典型成功：创建退款政策（3 档阶梯）
|
||||
|
||||
请求：POST /v3/admin/order/refund-policy
|
||||
|
||||
|
||||
|
||||
响应：
|
||||
|
||||
|
||||
|
||||
### 8.2 边界情况：单档不可退政策（refundRatio=0，minDays=0）
|
||||
|
||||
请求：POST /v3/admin/order/refund-policy
|
||||
|
||||
|
||||
|
||||
响应结构同 8.1，rules 只有一条，remark 为 null。
|
||||
|
||||
### 8.3 业务失败：policyName 为空触发 400
|
||||
|
||||
请求体缺少 policyName 字段，响应：
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 9. 业务边界
|
||||
|
||||
**适用**
|
||||
- 管理员维护全局退款政策库和退款原因选项
|
||||
- 产品编排时从 GET /enabled 拉取可选政策列表（可按 payType 过滤）绑定到产品
|
||||
- 软删除：DELETE 政策/原因后数据保留，C 端不再展示
|
||||
|
||||
**不适用**
|
||||
- 接口仅管理端可用，不开放给小程序 C 端
|
||||
- 删除/禁用政策后，已绑定该政策的产品申请退款时降级使用默认政策
|
||||
|
||||
**特殊边界**
|
||||
- PUT 修改规则时全量替换原有规则列表，需携带完整规则集
|
||||
- 历史退款申请已快照政策信息，修改政策不影响已有退款申请金额
|
||||
- 退款原因无独立启停端点，通过 DELETE 软删下线
|
||||
|
||||
---
|
||||
|
||||
## 10. v2→v3 路径对照表
|
||||
|
||||
| 功能 | v2 路径 | v3 路径 | 契约变化 |
|
||||
|------|---------|---------|----------|
|
||||
| 退款政策列表（含禁用） | GET /admin/order/refund-policy/list | GET /v3/admin/order/refund-policy/list | 无 |
|
||||
| 启用的退款政策列表 | GET /admin/order/refund-policy/enabled | GET /v3/admin/order/refund-policy/enabled | 无 |
|
||||
| 退款政策详情 | GET /admin/order/refund-policy/{policyId} | GET /v3/admin/order/refund-policy/{policyId} | 无 |
|
||||
| 创建退款政策 | POST /admin/order/refund-policy | POST /v3/admin/order/refund-policy | 无 |
|
||||
| 修改退款政策 | PUT /admin/order/refund-policy/{policyId} | PUT /v3/admin/order/refund-policy/{policyId} | 无 |
|
||||
| 删除退款政策 | DELETE /admin/order/refund-policy/{policyId} | DELETE /v3/admin/order/refund-policy/{policyId} | 无 |
|
||||
| 启用/禁用退款政策 | PUT /admin/order/refund-policy/{policyId}/toggle | PUT /v3/admin/order/refund-policy/{policyId}/toggle | 无 |
|
||||
| 创建退款原因 | POST /admin/order/refund-policy/reason | POST /v3/admin/order/refund-policy/reason | 无 |
|
||||
| 修改退款原因 | PUT /admin/order/refund-policy/reason/{reasonId} | PUT /v3/admin/order/refund-policy/reason/{reasonId} | 无 |
|
||||
| 删除退款原因 | DELETE /admin/order/refund-policy/reason/{reasonId} | DELETE /v3/admin/order/refund-policy/reason/{reasonId} | 无 |
|
||||
|
||||
v2 旧路径在 v2 服务下线后返回 404，v3 路径为新基线。
|
||||
|
||||
---
|
||||
|
||||
## 11. 影响评估 / 回滚
|
||||
|
||||
- **影响**：前端需将 base URL 切换至 v3 服务（端口 8086），路径前缀由 /admin/ 改为 /v3/admin/，字段契约不变
|
||||
- **回滚方案**：前端回退 base URL 至 v2 服务即可，v3 与 v2 数据库独立互不影响
|
||||
|
||||
---
|
||||
|
||||
## 12. 注意事项
|
||||
|
||||
**退款金额计算算法差异（v2 vs v3）—— 存量政策迁移与对账时必须核对**
|
||||
|
||||
| 项目 | v2 | v3 |
|
||||
|------|----|----|
|
||||
| 区间判定 | minDays 单边匹配（>=minDays 命中最小 minDays 规则） | [minDays, maxDays) 双边区间，maxDays 由后端按规则集排序推导 |
|
||||
| 舍入模式 | HALF_EVEN（银行家舍入） | DOWN（向下截断） |
|
||||
| 结果差异 | 边界天数处两版计算结果可能不同 | 同政策同天数下，v3 退款金额 <= v2 退款金额 |
|
||||
|
||||
相同 minDays/refundRatio 配置，v2 和 v3 实际退款金额可能不同。
|
||||
若迁移存量政策并对历史退款金额做对账，需按上表核对两版计算结果。
|
||||
|
||||
---
|
||||
|
||||
## 13. 关联 / 联系人
|
||||
|
||||
- **后端负责人**：腰苏图（yaosutu）
|
||||
- **服务**：hl-order-service-v3，退款域 com.hulalv.refund
|
||||
- **Controller**：AdminRefundPolicyController，路径前缀 /v3/admin/order/refund-policy
|
||||
- **Gitea 项目**：https://git.1814.love:8443/wx/HL
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户