108 行
3.6 KiB
Markdown
108 行
3.6 KiB
Markdown
# 订单取消（出行前）新增 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 ≤ 已付金额` |
|
||
|
||
**入参示例**
|
||
|
||
按政策退（默认）：
|
||
```json
|
||
{ "cancelReason": "客户临时有事无法出行", "refundMode": "POLICY" }
|
||
```
|
||
订金全额退：
|
||
```json
|
||
{ "cancelReason": "我方资源无法满足", "refundMode": "FULL_DEPOSIT" }
|
||
```
|
||
部分退：
|
||
```json
|
||
{ "cancelReason": "协商部分退款", "refundMode": "PARTIAL", "refundAmount": 500.00 }
|
||
```
|
||
|
||
## 出参
|
||
|
||
`Result<OrderCancelPreTripRespVO>`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| refundApplicationId | Long | 退款申请 ID |
|
||
| refundAmount | BigDecimal | 本次退款金额（按所选模式算定） |
|
||
| pendingApprovalMsg | String | 提示文案 |
|
||
| newStatus | String | 取消后订单状态，固定 `CANCELLED` |
|
||
|
||
**出参示例**
|
||
```json
|
||
{
|
||
"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：https://git.1814.love:8443/wx/HL/issues/3540
|
||
- PR：https://git.1814.love:8443/wx/HL/pulls/3550
|
||
- 后端负责人：腰苏图（订单 v3）
|