# 订单取消（出行前）新增 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）