docs(changelog): 订单取消3退款模式(管理后台)+C端自主取消(小程序) 接口契约 (#3550 #3549)

2026-06-06 18:56:58 +08:00 · 2026-06-06 18:56:58 +08:00 · d5f234455c
--- a/changelogs-v2-mp/2026-06/06_3549_C端自主取消订单-新增接口-小程序端.md
+++ b/changelogs-v2-mp/2026-06/06_3549_C端自主取消订单-新增接口-小程序端.md
@ -0,0 +1,73 @@
+# C 端用户自主取消订单（小程序端）
+
+> 端类型：**小程序端**（v3）｜变更类型：**新增接口**｜服务：hl-mp-service（Feign → hl-order-service-v3）
+> Epic #3540 ｜ PR #3549 ｜日期：2026-06-06
+
+## 接口地址
+
+`POST /mp/order/{orderId}/cancel`
+
+## 接口介绍
+
+小程序 C 端用户自主取消**自己**的订单。仅出行前可取消，按退款政策（距出发天数阶梯）退款，取消后订单进入 `CANCELLED` 终态、不可恢复。
+
+## 本次修改点
+
+新增接口。此前小程序无自主取消能力（取消只能走后台定制师）。本接口固定 `POLICY` 退款模式（C 端不暴露退款模式选择），并校验订单归属当前登录用户。
+
+## 入参
+
+- 路径参数：`orderId`（Long，订单 ID，必填）
+- 请求头：`Authorization`（登录 token，必填）
+- 请求体（可选，可不传）：
+
+| 字段 | 类型 | 必填 | 含义 |
+|---|---|---|---|
+| reason | String | 否 | 取消原因 |
+
+**入参示例**
+```
+POST /mp/order/2063151085698134017/cancel
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{ "reason": "行程有变，需要取消" }
+```
+（body 也可整体不传。）
+
+## 出参
+
+`Result<Void>`
+
+**出参示例**
+```json
+{ "code": 200, "message": "成功", "success": true, "data": null }
+```
+
+## 可取消状态（调用约束）
+
+| 订单状态 | 是否可取消 |
+|---|---|
+| PENDING_PAY 待支付 | ✅ |
+| CUSTOMIZING 定制中 | ✅ |
+| PENDING_DEPARTURE 待出行 | ✅ |
+| TRAVELLING 出行中 | ❌（行程中只能联系客服终止行程） |
+| COMPLETED 已完成 | ❌ |
+| CANCELLED 已取消 | ❌ |
+
+- 退款模式固定 `POLICY`，按退款政策阶梯计算退款金额（已付订金时退款，未支付时无退款）。
+- 仅可取消归属当前登录用户的订单（非本人订单返回 581037）。
+
+## 错误码
+
+| code | message | 触发 |
+|---|---|---|
+| 581017 | 当前订单状态不允许取消 | 出行中 / 已完成 / 已取消订单调用 |
+| 581037 | 无权取消该订单 | 取消非本人（userId 不匹配）订单 |
+| 401 | 缺少有效的 Authorization 头 | 未携带 token |
+
+## 关联
+
+- Epic：https://git.1814.love:8443/wx/HL/issues/3540
+- PR：https://git.1814.love:8443/wx/HL/pulls/3549
+- 后端负责人：腰苏图（订单 v3）
--- a/changelogs-v2/2026-06/06_3550_订单取消3退款模式-修改接口-管理后台.md
+++ b/changelogs-v2/2026-06/06_3550_订单取消3退款模式-修改接口-管理后台.md
@ -0,0 +1,107 @@
+# 订单取消（出行前）新增 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）