3.6 KiB
3.6 KiB
订单取消（出行前）新增 3 种退款模式（管理后台）
端类型：管理后台（v3）｜变更类型：修改接口｜服务：hl-order-service-v3 Epic #3540 ｜ PR #3550 ｜日期：2026-06-06
接口地址
POST /v3/admin/order/{id}/cancel/pre-trip
接口介绍
定制师在后台对出行前订单（PENDING_PAY / CUSTOMIZING / PENDING_DEPARTURE）执行取消。取消后订单进入 CANCELLED 终态，已付金额按所选退款模式发起退款。
本次修改点
入参 OrderCancelPreTripReqVO 新增 2 个字段 refundMode + refundAmount，支持 3 种退款模式：
POLICY（默认）：按退款政策阶梯（距出发天数）计算退款金额。FULL_DEPOSIT：订金全额退，无视政策。PARTIAL：部分退，金额由refundAmount指定。
定制师操作即放行退款（无二级审批），退款单据自动进入执行。出参结构 OrderCancelPreTripRespVO 不变。新增错误码 581038 / 581039。
入参
路径参数：id（Long，订单 ID，必填）
请求体 OrderCancelPreTripReqVO：
| 字段 | 类型 | 必填 | 含义 |
|---|---|---|---|
| cancelReason | String | 是 | 取消原因（前端可下拉 + 自由填写） |
| cancelDetail | String | 否 | 详细说明 |
| refundMode | String 枚举 | 否（默认 POLICY） | 退款模式：POLICY / FULL_DEPOSIT / PARTIAL |
| refundAmount | BigDecimal | PARTIAL 时必填 | 部分退金额，须 0 < refundAmount ≤ 已付金额 |
入参示例
按政策退（默认）：
{ "cancelReason": "客户临时有事无法出行", "refundMode": "POLICY" }
订金全额退：
{ "cancelReason": "我方资源无法满足", "refundMode": "FULL_DEPOSIT" }
部分退：
{ "cancelReason": "协商部分退款", "refundMode": "PARTIAL", "refundAmount": 500.00 }
出参
Result<OrderCancelPreTripRespVO>
| 字段 | 类型 | 含义 |
|---|---|---|
| refundApplicationId | Long | 退款申请 ID |
| refundAmount | BigDecimal | 本次退款金额（按所选模式算定） |
| pendingApprovalMsg | String | 提示文案 |
| newStatus | String | 取消后订单状态，固定 CANCELLED |
出参示例
{
"code": 200, "message": "成功", "success": true,
"data": {
"refundApplicationId": 2063151109765050369,
"refundAmount": 500.00,
"pendingApprovalMsg": "退款已发起",
"newStatus": "CANCELLED"
}
}
枚举
| 枚举 | 取值 | 含义 |
|---|---|---|
| refundMode | POLICY | 按退款政策阶梯计算 |
| refundMode | FULL_DEPOSIT | 订金全额退（无视政策） |
| refundMode | PARTIAL | 部分退（用 refundAmount） |
| newStatus | CANCELLED | 已取消（终态） |
错误码
| code | message | 触发 |
|---|---|---|
| 581017 | 当前订单状态不允许取消 | 非出行前状态（出行中 / 已完成 / 已取消）调用 |
| 581038 | 退款模式非法，仅支持 POLICY/FULL_DEPOSIT/PARTIAL | refundMode 传了非法值 |
| 581039 | 部分退金额非法：须 > 0 且 ≤ 已付金额 | PARTIAL 缺金额 / ≤0 / 超过已付金额 |
修改前后对比
| 修改前 | 修改后 | |
|---|---|---|
| refundMode | 无此入参，固定按政策退 | 新增，可选 POLICY / FULL_DEPOSIT / PARTIAL |
| refundAmount | 无此入参 | 新增，PARTIAL 模式必填 |
| 出参 | 同 | 不变 |
兼容性：
refundMode不传等价于POLICY，旧调用方零改动可继续工作。
关联
- Epic：wx/HL#3540
- PR：wx/HL#3550
- 后端负责人：腰苏图（订单 v3）