wx/hl-api-changelog

派生 0

yaosutu 77a1c4a780 docs: 新增 order-v3 退款域管理后台接口说明（政策/原因/申请管理，共 21 个接口）

2026-06-22 00:26:20 +08:00

11 KiB

原始文件 永久链接 Blame 文件历史

退款政策与退款原因管理接口说明（管理后台）

日期: 2026-06-22
端类型: 管理后台
接口路径前缀: /v3/admin/order/refund-policy
服务: hl-order-service-v3（端口 8086，网关前缀 /v3）
说明: 本文档为现有已上线接口的对接说明，非新版本改动

1. 接口背景

退款政策模块支持按「距出发天数」设置分阶梯退款比例，产品设计时可绑定指定政策；退款原因模块维护 C 端用户申请退款时可选择的原因选项。两个模块均由管理后台维护，不开放给小程序。

2. 变更清单

类型	接口	说明
接口说明	GET /v3/admin/order/refund-policy/list	退款政策全量列表（含禁用）
接口说明	GET /v3/admin/order/refund-policy/enabled	启用政策列表（含 payType 过滤）
接口说明	GET /v3/admin/order/refund-policy/{policyId}	退款政策详情（含阶梯规则）
接口说明	POST /v3/admin/order/refund-policy	创建退款政策
接口说明	PUT /v3/admin/order/refund-policy/{policyId}	修改退款政策
接口说明	DELETE /v3/admin/order/refund-policy/{policyId}	删除退款政策（软删）
接口说明	PUT /v3/admin/order/refund-policy/{policyId}/toggle	启用/禁用退款政策
接口说明	POST /v3/admin/order/refund-policy/reason	创建退款原因
接口说明	PUT /v3/admin/order/refund-policy/reason/{reasonId}	修改退款原因
接口说明	DELETE /v3/admin/order/refund-policy/reason/{reasonId}	删除退款原因（软删）

3. 接口详情（通用）

认证: JWT，Header Authorization: Bearer token，需管理员身份（adminId 从 token 解析）
幂等性: 创建/修改无幂等 header，前端需防止重复点击
Content-Type: application/json
响应格式: 统一 { "code": 200, "data": ..., "msg": "success" }

4. 接口入参

4.1 政策列表

GET /v3/admin/order/refund-policy/list

无入参，返回全量政策列表（含禁用），按创建时间倒序。

GET /v3/admin/order/refund-policy/enabled

参数	位置	类型	必填	说明
payType	Query	String	否	按支付类型过滤。传 FULL 返回 FULL+BOTH 的政策；传 DEPOSIT 返回 DEPOSIT+BOTH 的政策；不传返回全部启用政策

GET /v3/admin/order/refund-policy/{policyId}

参数	位置	类型	必填	说明
policyId	Path	Long(String)	是	退款政策 ID

4.2 创建/修改退款政策（请求体）

POST /v3/admin/order/refund-policy 和 PUT /v3/admin/order/refund-policy/{policyId} 共用同一请求体结构：

字段	类型	必填	校验	说明
policyName	String	是	最大 100 字	政策名称，如「国内游退款政策」
remark	String	否	最大 500 字	备注说明
applyPayType	String	否	FULL/DEPOSIT/BOTH	适用支付类型；不传默认 BOTH
rules	Array	是	不能为空	退款规则阶梯
rules[].minDays	Integer	是	>= 0	距出发最少天数（含当天）。例如 minDays=7 表示出发前 7 天及以上适用此规则
rules[].refundRatio	Integer	是	0~100	退款比例（百分比）。0=不可退；100=全退

PUT 时额外路径参数：

参数	位置	类型	必填	说明
policyId	Path	Long(String)	是	退款政策 ID

4.3 删除退款政策

DELETE /v3/admin/order/refund-policy/{policyId}

参数	位置	类型	必填	说明
policyId	Path	Long(String)	是	退款政策 ID

4.4 启用/禁用退款政策

PUT /v3/admin/order/refund-policy/{policyId}/toggle

参数	位置	类型	必填	说明
policyId	Path	Long(String)	是	退款政策 ID
enabled	Query	Boolean	是	true=启用；false=禁用

4.5 创建/修改退款原因（请求体）

POST /v3/admin/order/refund-policy/reason 和 PUT /v3/admin/order/refund-policy/reason/{reasonId} 共用：

字段	类型	必填	校验	说明
reasonText	String	是	最大 200 字	退款原因文本，展示给 C 端用户，如「行程有变」
reasonCode	String	否	最大 64 字	机器可读编码，如 TIME_CONFLICT / OTHER
category	String	否	最大 50 字	分类，走数据字典 refund_reason_category（见第 6 节）
sortOrder	Integer	否	-	排序号，数字越小越靠前

4.6 删除退款原因

DELETE /v3/admin/order/refund-policy/reason/{reasonId}

参数	位置	类型	必填	说明
reasonId	Path	Long(String)	是	退款原因 ID

5. 出参字段

5.1 RefundPolicyVO（退款政策）

字段	类型	说明
policyId	String	政策 ID（Long 序列化为 String，防 JS 精度丢失）
policyName	String	政策名称
enabled	Boolean	是否启用
applyPayType	String	适用支付类型：FULL/DEPOSIT/BOTH（见第 6 节）
remark	String	备注
createdBy	String	创建人 ID
createTime	String	创建时间 ISO 格式，如 2026-06-01T10:00:00
updateTime	String	更新时间
rules	Array	退款规则阶梯列表
rules[].ruleId	String	规则 ID
rules[].minDays	Integer	距出发最少天数
rules[].refundRatio	Integer	退款比例（百分比）

阶梯算法说明：规则按 minDays 降序排列，距出发天数 >= 当前规则 minDays 时命中。calculatedAmount = paidAmount x refundRatio / 100，向下取整保留 2 位小数。

5.2 RefundReasonVO（退款原因）

字段	类型	说明
reasonId	String	原因 ID
reasonText	String	原因描述，展示给 C 端
reasonCode	String	机器可读编码
category	String	分类（字典 refund_reason_category 的 key）
sortOrder	Integer	排序号
enabled	Boolean	是否启用

6. 枚举 / 数据字典

6.1 applyPayType（适用支付类型）—— 字典 payment_type

值	中文	说明
FULL	全款支付	仅适用于全款支付的订单
DEPOSIT	定金支付	仅适用于定金+尾款的订单
BOTH	两者均可	全款和定金订单均适用（不传默认值）

6.2 退款原因分类 —— 字典 refund_reason_category

category 字段存储字典 key，前端下拉展示时从数据字典接口获取标签。常见 key 示例（以实际字典表为准）：

key 示例	说明
USER_REASON	用户原因（行程变化/临时改变等）
SERVICE_REASON	服务原因（产品质量问题等）
OTHER	其他

字典实际值以管理后台数据字典模块配置为准，前端需从字典接口动态拉取。

7. 错误码

错误码	说明	触发场景
530209	退款政策阶梯天数重复或重叠	创建/修改政策时 rules 中有 minDays 重叠的规则
530210	退款政策正在被使用，无法删除	删除政策时有退款申请正在引用该政策
400	参数校验失败	policyName 为空、rules 为空、refundRatio 超范围等

8. 示例

8.1 典型成功：创建退款政策

请求：POST /v3/admin/order/refund-policy，请求体：

{
  "policyName": "国内游标准退款政策",
  "applyPayType": "FULL",
  "remark": "适用于所有国内游产品",
  "rules": [
    { "minDays": 30, "refundRatio": 90 },
    { "minDays": 15, "refundRatio": 70 },
    { "minDays": 7,  "refundRatio": 50 },
    { "minDays": 0,  "refundRatio": 0  }
  ]
}

响应：

{
  "code": 200,
  "data": {
    "policyId": "1234567890123456789",
    "policyName": "国内游标准退款政策",
    "enabled": true,
    "applyPayType": "FULL",
    "remark": "适用于所有国内游产品",
    "createTime": "2026-06-22T10:00:00",
    "rules": [
      { "ruleId": "111", "minDays": 30, "refundRatio": 90 },
      { "ruleId": "112", "minDays": 15, "refundRatio": 70 },
      { "ruleId": "113", "minDays": 7,  "refundRatio": 50 },
      { "ruleId": "114", "minDays": 0,  "refundRatio": 0  }
    ]
  },
  "msg": "success"
}

8.2 边界情况：不可退政策（仅一条 minDays=0, refundRatio=0）

请求体：

{
  "policyName": "不可退政策",
  "applyPayType": "BOTH",
  "rules": [ { "minDays": 0, "refundRatio": 0 } ]
}

响应结构同 8.1，rules 只有一条。

8.3 业务失败：阶梯天数重叠