docs(order-v3): §1 changelog 补 §1B + §1C 共 5 接口，§1 模块 15 接口一次推全
按用户反馈，§1B 取消订单 + §1C 状态机+锁单 与 §1A 一起推送（不分批）：
新增接口：
- §3.11 §1.5.0 GET /v3/admin/order/{id}/cancel-preview 取消预览（只读）
- §3.12 §1.5.1 POST /v3/admin/order/{id}/cancel/pre-trip 取消出行前（企微 OA + 退款）
- §3.13 §1.5.2 POST /v3/admin/order/{id}/cancel/on-trip 取消出行中（仅登记返还）
- §3.14 §1.7 POST /v3/admin/order/{id}/transition 状态机通用入口
- §3.15 §1.8 GET /v3/admin/order/{id}/confirm-checklist 锁单前置 5 项校验
每个接口按"自含"结构：使用场景 / 认证 / 入参 / 出参 / 错误码 / 业务边界 / 示例（请求+响应）。
§6 枚举新增：
- §6.17 transition eventCode 9 个状态机事件
- §6.18 transition triggeredEvents 6 个副作用事件
- §6.19 checklist item code 5 项前置校验
- §6.20 customerChannel 通知渠道 3 值
§0 / §2 / §11 / §12 同步更新："待补" 移除，全部 ✅；变更清单加 5 行；注意事项加取消订单分支说明 + CONFIRM 锁单约束。
文件从 1235 行 → 1730 行（diff +506 / -11）。
这个提交包含在：
yaosutu
父节点
bb18e4fac8
当前提交
172ab44800
@ -8,13 +8,12 @@
|
|||||||
|
|
||||||
## 0. 模块全貌
|
## 0. 模块全貌
|
||||||
|
|
||||||
| 子模块 | 含接口 | 接口数 | 推送状态 |
|
| 子模块 | 含接口 | 接口数 | 状态 |
|
||||||
|---|---|---|---|
|
|---|---|---|---|
|
||||||
| **§1A 订单 CRUD + 详情** | §1.1 创建 / §1.2 列表 / §1.3.1 详情主聚合 / §1.3.2~§1.3.7 6 Tab 子接口 / §1.4 修改 | **10** | ✅ **本次推送** |
|
| **§1A 订单 CRUD + 详情** | §1.1 创建 / §1.2 列表 / §1.3.1 详情主聚合 / §1.3.2~§1.3.7 6 Tab 子接口 / §1.4 修改 | **10** | ✅ |
|
||||||
| §1B 取消订单 | §1.5.0 预览 / §1.5.1 出行前 / §1.5.2 出行中 | 3 | 📝 待补 |
|
| **§1B 取消订单** | §1.5.0 预览 / §1.5.1 出行前 / §1.5.2 出行中 | **3** | ✅ |
|
||||||
| §1C 状态机 + 锁单 | §1.7 transition / §1.8 confirm-checklist | 2 | 📝 待补 |
|
| **§1C 状态机 + 锁单** | §1.7 transition / §1.8 confirm-checklist | **2** | ✅ |
|
||||||
|
| **§1 合计** | — | **15** | ✅ 本次推送 |
|
||||||
> 📌 本文件为 §1 模块**累计** changelog，后续 §1B / §1C 落地时通过追加 commit 扩充同一文件。
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -22,7 +21,7 @@
|
|||||||
|
|
||||||
订单服务 v3（hl-order-service-v3 全新二期）的订单核心模块 §1 core 提供订单管理基础能力，覆盖定制师 B 端代下单 / 多维度筛选列表 / 订单详情（首屏主聚合 + 6 个 Tab 独立懒加载）/ 非关键字段修改。
|
订单服务 v3（hl-order-service-v3 全新二期）的订单核心模块 §1 core 提供订单管理基础能力，覆盖定制师 B 端代下单 / 多维度筛选列表 / 订单详情（首屏主聚合 + 6 个 Tab 独立懒加载）/ 非关键字段修改。
|
||||||
|
|
||||||
本次（§1A）推送 10 个接口，对应管理后台原型 F8-F20（订单列表+创建+详情主体）、F22-F26（详情各 Tab 单刷新）、F37（修改订单字段）。
|
本次推送 §1 模块**全 15 个接口**，对应管理后台原型 F8-F20（订单列表+创建+详情主体）、F22-F26（详情各 Tab 单刷新）、F37（修改订单字段）、F30-F32（取消订单弹框+出行前/出行中）、F33-F34（确认锁单 checklist + 状态机操作）。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -40,6 +39,11 @@
|
|||||||
| 8 | 1.3.6 | 退款明细 Tab | GET | `/v3/admin/order/{id}/refund` |
|
| 8 | 1.3.6 | 退款明细 Tab | GET | `/v3/admin/order/{id}/refund` |
|
||||||
| 9 | 1.3.7 | 服务标准 Tab | GET | `/v3/admin/order/{id}/service-standard` |
|
| 9 | 1.3.7 | 服务标准 Tab | GET | `/v3/admin/order/{id}/service-standard` |
|
||||||
| 10 | 1.4 | 修改订单字段 | PUT | `/v3/admin/order/{id}` |
|
| 10 | 1.4 | 修改订单字段 | PUT | `/v3/admin/order/{id}` |
|
||||||
|
| 11 | 1.5.0 | 取消订单预览 | GET | `/v3/admin/order/{id}/cancel-preview` |
|
||||||
|
| 12 | 1.5.1 | 取消订单（出行前） | POST | `/v3/admin/order/{id}/cancel/pre-trip` |
|
||||||
|
| 13 | 1.5.2 | 取消订单（出行中） | POST | `/v3/admin/order/{id}/cancel/on-trip` |
|
||||||
|
| 14 | 1.7 | 状态变更操作（状态机） | POST | `/v3/admin/order/{id}/transition` |
|
||||||
|
| 15 | 1.8 | 确认锁单前置 Checklist | GET | `/v3/admin/order/{id}/confirm-checklist` |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -1011,6 +1015,443 @@ Content-Type: application/json
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
### 3.11 §1.5.0 取消订单预览（只读）
|
||||||
|
|
||||||
|
**路径**：`GET /v3/admin/order/{id}/cancel-preview`
|
||||||
|
**使用场景**：定制师点击「取消订单」按钮，弹框打开瞬间调用，展示退款金额 + 扣费 + 退款政策
|
||||||
|
**认证**：JWT（admin 角色） | **幂等性**：是（只读不入库） | **限流**：无
|
||||||
|
**金额规则**：严格按订单创建时冻结的 `RefundPolicy` 快照计算，不接受人工覆盖
|
||||||
|
|
||||||
|
#### 入参
|
||||||
|
|
||||||
|
`id` (path, Long) — 订单 ID
|
||||||
|
|
||||||
|
#### 出参（`Result<OrderCancelPreviewRespVO>`）
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| `refundAmount` | BigDecimal | 退款金额（按 RefundPolicy 计算） |
|
||||||
|
| `paidAmount` | BigDecimal | 客户已付金额 |
|
||||||
|
| `deductAmount` | BigDecimal | 扣费金额 = `paidAmount - refundAmount` |
|
||||||
|
| `daysToDeparture` | Integer | 距出发天数（今天 - 出发日；负数表已过出发日） |
|
||||||
|
| `refundPolicy` | RefundPolicyVO | 退款政策快照（结构同 §3.9 `refundPolicy`） |
|
||||||
|
|
||||||
|
#### 错误码
|
||||||
|
|
||||||
|
| code | 含义 |
|
||||||
|
|------|------|
|
||||||
|
| `581020` | 订单不存在 |
|
||||||
|
| `581021` | 无权访问该订单 |
|
||||||
|
| `581050` | 订单状态不允许取消（已取消 / 已完成 / 退款中等） |
|
||||||
|
|
||||||
|
#### 业务边界
|
||||||
|
|
||||||
|
- ✅ **适用**：订单粗状态 ∈ {待支付, 待完善, 定制中, 已确认, 待出行}
|
||||||
|
- ❌ **拒绝**：已取消 / 已完成 / 退款中 → `581050`
|
||||||
|
- ⚠️ **`daysToDeparture` 负数**：已过出发日，前端应引导走 §3.13 出行中取消（on-trip）而非本接口预览
|
||||||
|
|
||||||
|
#### 示例
|
||||||
|
|
||||||
|
**典型（出行前 12 天） - 请求**：
|
||||||
|
|
||||||
|
```http
|
||||||
|
GET /v3/admin/order/60123456789012/cancel-preview
|
||||||
|
Authorization: Bearer {admin_jwt}
|
||||||
|
```
|
||||||
|
|
||||||
|
**典型 - 响应**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"data": {
|
||||||
|
"refundAmount": 6864.00,
|
||||||
|
"paidAmount": 8580.00,
|
||||||
|
"deductAmount": 1716.00,
|
||||||
|
"daysToDeparture": 12,
|
||||||
|
"refundPolicy": {
|
||||||
|
"policyId": 50001,
|
||||||
|
"policyName": "标准退改政策",
|
||||||
|
"tiers": [
|
||||||
|
{"minDays": 15, "refundRatio": 100, "label": "出发前 15 天 100%退"},
|
||||||
|
{"minDays": 7, "refundRatio": 80, "label": "出发前 7-14 天 80%退"},
|
||||||
|
{"minDays": 3, "refundRatio": 50, "label": "出发前 3-6 天 50%退"},
|
||||||
|
{"minDays": 0, "refundRatio": 0, "label": "出发前 2 天内不退"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"msg": "success"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.12 §1.5.1 取消订单 - 出行前（pre-trip）
|
||||||
|
|
||||||
|
**路径**：`POST /v3/admin/order/{id}/cancel/pre-trip`
|
||||||
|
**使用场景**：定制师代客取消出行前订单。走企微 OA 审批 + 通道退款
|
||||||
|
**认证**：JWT（admin 角色） | **幂等性**：否（提交企微 OA + 创建退款申请） | **限流**：无
|
||||||
|
**金额规则**：严格按 `RefundPolicy` 计算，不接受人工覆盖（金额由 §3.11 预览给定）
|
||||||
|
|
||||||
|
#### 入参（`OrderCancelPreTripReqVO`）
|
||||||
|
|
||||||
|
| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|
||||||
|
|------|------|:----:|------|----------|
|
||||||
|
| `cancelReason` | String | ✅ | 取消原因（前端可选下拉 + 自由填写） | `@NotBlank` |
|
||||||
|
| `cancelDetail` | String | ❌ | 详细说明 | — |
|
||||||
|
|
||||||
|
#### 出参（`Result<OrderCancelPreTripRespVO>`）
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| `refundApplicationId` | Long | 退款申请 ID（已提企微 OA） |
|
||||||
|
| `refundAmount` | BigDecimal | 退款金额（按 RefundPolicy 政策计算） |
|
||||||
|
| `pendingApprovalMsg` | String | 审批中提示文案 |
|
||||||
|
| `newStatus` | String | 取消后订单状态（如 `退款中`） |
|
||||||
|
|
||||||
|
#### 错误码
|
||||||
|
|
||||||
|
| code | 含义 |
|
||||||
|
|------|------|
|
||||||
|
| `581020` | 订单不存在 |
|
||||||
|
| `581021` | 无权访问该订单 |
|
||||||
|
| `581050` | 订单状态不允许取消（已取消 / 已完成 / 退款中） |
|
||||||
|
| `581051` | 订单已过出发日，需走 §3.13 on-trip 取消 |
|
||||||
|
| `581052` | 企微 OA 提交失败 |
|
||||||
|
|
||||||
|
#### 业务边界
|
||||||
|
|
||||||
|
- ✅ **适用**：订单状态可取消 + `daysToDeparture` ≥ 0
|
||||||
|
- ❌ **拒绝**：出发日过 / 状态不可取消
|
||||||
|
- ⚠️ **不可重复提交**：同一订单存在 PENDING 退款申请时第二次调用返 `581050`
|
||||||
|
|
||||||
|
#### 示例
|
||||||
|
|
||||||
|
**典型 - 请求**：
|
||||||
|
|
||||||
|
```http
|
||||||
|
POST /v3/admin/order/60123456789012/cancel/pre-trip
|
||||||
|
Authorization: Bearer {admin_jwt}
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"cancelReason": "客户临时有事无法出行",
|
||||||
|
"cancelDetail": "客户家属突发疾病需照顾"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**典型 - 响应**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"data": {
|
||||||
|
"refundApplicationId": 95001234567890,
|
||||||
|
"refundAmount": 6864.00,
|
||||||
|
"pendingApprovalMsg": "已提交企微审批，预计 2 小时内完成",
|
||||||
|
"newStatus": "退款中"
|
||||||
|
},
|
||||||
|
"msg": "success"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.13 §1.5.2 取消订单 - 出行中（on-trip）
|
||||||
|
|
||||||
|
**路径**：`POST /v3/admin/order/{id}/cancel/on-trip`
|
||||||
|
**使用场景**：定制师代客取消出行中订单。**仅登记返还金额**，不走支付通道（返还金额在核单 Step 5 自动拉取结算）
|
||||||
|
**认证**：JWT（admin 角色）
|
||||||
|
|
||||||
|
#### 入参（`OrderCancelOnTripReqVO`）
|
||||||
|
|
||||||
|
| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|
||||||
|
|------|------|:----:|------|----------|
|
||||||
|
| `cancelReason` | String | ✅ | 取消原因 | `@NotBlank` |
|
||||||
|
| `returnAmount` | BigDecimal | ✅ | 定制师手填的返还金额（不走政策算） | `@NotNull` `@DecimalMin(0, exclusive)` |
|
||||||
|
| `returnRemark` | String | ✅ | 返还金额备注（说明已用成本扣除项） | `@NotBlank` |
|
||||||
|
|
||||||
|
#### 出参（`Result<OrderCancelOnTripRespVO>`）
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| `settlementRefundId` | Long | 返还登记 ID |
|
||||||
|
| `returnAmount` | BigDecimal | 已登记的返还金额（= 入参回显） |
|
||||||
|
| `newStatus` | String | 取消后状态（`已取消`） |
|
||||||
|
|
||||||
|
#### 错误码
|
||||||
|
|
||||||
|
| code | 含义 |
|
||||||
|
|------|------|
|
||||||
|
| `581020` | 订单不存在 |
|
||||||
|
| `581021` | 无权访问该订单 |
|
||||||
|
| `581053` | 订单未出发，不能走 on-trip 取消 |
|
||||||
|
| `581054` | 订单已完成，不能取消 |
|
||||||
|
| `581055` | `returnAmount` 大于 `paidAmount` |
|
||||||
|
|
||||||
|
#### 业务边界
|
||||||
|
|
||||||
|
- ✅ **适用**：订单粗状态 = `出行中` 或 `已确认` 但已过出发日
|
||||||
|
- ❌ **拒绝**：未出发 → `581053`；已完成 → `581054`；返还金额超额 → `581055`
|
||||||
|
- ⚠️ **不走支付通道**：本接口**只登记**返还金额，不发起实退；实退在核单 Step 5 走
|
||||||
|
|
||||||
|
#### 示例
|
||||||
|
|
||||||
|
**典型 - 请求**：
|
||||||
|
|
||||||
|
```http
|
||||||
|
POST /v3/admin/order/60123456789012/cancel/on-trip
|
||||||
|
Authorization: Bearer {admin_jwt}
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"cancelReason": "客户中途突发疾病",
|
||||||
|
"returnAmount": 2500.00,
|
||||||
|
"returnRemark": "已用 2 天住宿+用车+导游，扣除 5880 元"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**典型 - 响应**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"data": {
|
||||||
|
"settlementRefundId": 96001234567890,
|
||||||
|
"returnAmount": 2500.00,
|
||||||
|
"newStatus": "已取消"
|
||||||
|
},
|
||||||
|
"msg": "success"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.14 §1.7 状态变更操作（通用状态机）
|
||||||
|
|
||||||
|
**路径**：`POST /v3/admin/order/{id}/transition`
|
||||||
|
**使用场景**：所有由状态机驱动的操作统一走此接口。例如「确认锁单」「关闭订单」「触发尾款支付」等
|
||||||
|
**认证**：JWT（admin 角色） | **幂等性**：否（写 `order_status_log`）
|
||||||
|
**副作用**：根据 `eventCode` 触发不同副作用（生成合同 / 投保 / 通知司机等），副作用列表在响应 `triggeredEvents` 中返回
|
||||||
|
|
||||||
|
#### 入参（`OrderTransitionReqVO`）
|
||||||
|
|
||||||
|
| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|
||||||
|
|------|------|:----:|------|----------|
|
||||||
|
| `eventCode` | String | ✅ | 状态机事件代码（枚举见 §6.17） | `@NotBlank` |
|
||||||
|
| `reason` | String | ❌ | 操作原因（按 event 强制要求时必填） | — |
|
||||||
|
| `payload` | Map\<String, Object\> | ❌ | 事件相关额外数据（不同 event 含义不同） | — |
|
||||||
|
|
||||||
|
#### 出参（`Result<OrderTransitionRespVO>`）
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| `success` | Boolean | 是否成功 |
|
||||||
|
| `oldStatus` | String | 变更前粗状态 |
|
||||||
|
| `newStatus` | String | 变更后粗状态 |
|
||||||
|
| `oldFlowStatus` | String | 变更前细状态 |
|
||||||
|
| `newFlowStatus` | String | 变更后细状态 |
|
||||||
|
| `triggeredEvents` | List\<String\> | 副作用事件列表（枚举见 §6.18） |
|
||||||
|
|
||||||
|
#### 错误码
|
||||||
|
|
||||||
|
| code | 含义 |
|
||||||
|
|------|------|
|
||||||
|
| `581020` | 订单不存在 |
|
||||||
|
| `581021` | 无权访问该订单 |
|
||||||
|
| `581060` | `eventCode` 枚举非法 |
|
||||||
|
| `581061` | 当前状态不允许该 event（状态机迁移非法） |
|
||||||
|
| `581062` | `reason` 必填但未传（如 `CANCEL` event） |
|
||||||
|
| `581063` | 前置 checklist 未全通过（如 `CONFIRM` event 时需 §3.15 全 ✅） |
|
||||||
|
|
||||||
|
#### 业务边界
|
||||||
|
|
||||||
|
- ✅ **状态机驱动**：触发条件由后端状态机定义，前端只传 `eventCode`，不需要懂迁移规则
|
||||||
|
- ⚠️ **`CONFIRM` event 强约束**：调用前必须先调 §3.15 confirm-checklist 且 `allPassed=true`，否则返 `581063`
|
||||||
|
- ⚠️ **副作用异步**：`triggeredEvents` 中 `ASYNC_*` 前缀的事件是异步执行的，本接口返回时副作用可能未完成（用 status-log Tab §3.7 跟踪）
|
||||||
|
|
||||||
|
#### 示例
|
||||||
|
|
||||||
|
**典型（确认锁单） - 请求**：
|
||||||
|
|
||||||
|
```http
|
||||||
|
POST /v3/admin/order/60123456789012/transition
|
||||||
|
Authorization: Bearer {admin_jwt}
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"eventCode": "CONFIRM",
|
||||||
|
"reason": "定制师确认所有前置条件已完成",
|
||||||
|
"payload": {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**典型 - 响应**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"data": {
|
||||||
|
"success": true,
|
||||||
|
"oldStatus": "定制中",
|
||||||
|
"newStatus": "待出行",
|
||||||
|
"oldFlowStatus": "待确认",
|
||||||
|
"newFlowStatus": "待出行",
|
||||||
|
"triggeredEvents": ["ASYNC_CONTRACT_GENERATE", "ASYNC_INSURANCE_ISSUE"]
|
||||||
|
},
|
||||||
|
"msg": "success"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**异常（checklist 未通过 581063） - 请求**：（同上 `eventCode=CONFIRM`，但订单存在未完善出行人）
|
||||||
|
|
||||||
|
**异常 - 响应**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "code": 581063, "data": null, "msg": "前置 checklist 未全通过：出行人信息未完善 1/3" }
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.15 §1.8 确认锁单前置 Checklist
|
||||||
|
|
||||||
|
**路径**：`GET /v3/admin/order/{id}/confirm-checklist`
|
||||||
|
**使用场景**：定制师点击「确认订单」按钮时调用。
|
||||||
|
- 返回 5 项前置校验明细（决定按钮是否可点）
|
||||||
|
- 通过时返回"确认行程"弹框预览数据（行程概览 + 自动副作用 + 通知项）
|
||||||
|
- 不通过时 `preview=null`，前端展示 5 项 `failReason` 列表 + `actionPath` 跳转引导
|
||||||
|
|
||||||
|
**认证**：JWT（admin 角色） | **幂等性**：是（只读不入库）
|
||||||
|
|
||||||
|
#### 入参
|
||||||
|
|
||||||
|
`id` (path, Long) — 订单 ID
|
||||||
|
|
||||||
|
#### 出参（`Result<ConfirmChecklistRespVO>`）
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| `allPassed` | Boolean | 是否全部通过（任一项不通过则 false） |
|
||||||
|
| `items` | List\<ChecklistItemVO\> | 5 项详细结果 |
|
||||||
|
| `preview` | PreviewVO? | 确认行程弹框预览（仅 `allPassed=true` 时返回） |
|
||||||
|
|
||||||
|
`ChecklistItemVO`：
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| `code` | String | 检查项代码（枚举见 §6.19） |
|
||||||
|
| `passed` | Boolean | 是否通过 |
|
||||||
|
| `failReason` | String? | 未通过原因（通过时 null） |
|
||||||
|
| `actionPath` | String? | 引导操作路径（如配房页跳转；通过时 null） |
|
||||||
|
|
||||||
|
`PreviewVO`（仅 `allPassed=true` 时存在）：
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| `departureDate` | LocalDate | 出发日期 |
|
||||||
|
| `totalPeopleCount` | Integer | 总出行人数（4 类相加） |
|
||||||
|
| `driverName` | String | 司机姓名 |
|
||||||
|
| `driverPhoneMasked` | String | 司机手机（脱敏） |
|
||||||
|
| `hotels` | List\<{cityName, hotelName}\> | 酒店列表（按行程城市分组） |
|
||||||
|
| `contractAutoAction.planName` | String | 合同方案名（产品快照） |
|
||||||
|
| `contractAutoAction.autoSign` | Boolean | 是否自动发送给客户线上签署 |
|
||||||
|
| `insuranceAutoAction.planName` | String | 保险产品名 |
|
||||||
|
| `insuranceAutoAction.peopleCount` | Integer | 投保人数（= `totalPeopleCount`） |
|
||||||
|
| `insuranceAutoAction.effectiveDescription` | String | 生效时间描述 |
|
||||||
|
| `notifications.notifyDriver` | Boolean | 是否通知司机 |
|
||||||
|
| `notifications.notifyHotel` | Boolean | 是否通知酒店确认房态 |
|
||||||
|
| `notifications.notifyCustomer` | Boolean | 是否向客户发送出行提醒 |
|
||||||
|
| `notifications.customerChannel` | String | 客户通知渠道（`WX` / `SMS` / `MIXED`） |
|
||||||
|
|
||||||
|
#### 错误码
|
||||||
|
|
||||||
|
| code | 含义 |
|
||||||
|
|------|------|
|
||||||
|
| `581020` | 订单不存在 |
|
||||||
|
| `581021` | 无权访问该订单 |
|
||||||
|
|
||||||
|
#### 业务边界
|
||||||
|
|
||||||
|
- ✅ **前置校验**：5 项 checklist 用于阻止用户点【确认订单】按钮在前置条件未满足时
|
||||||
|
- ⚠️ **`actionPath` 引导**：前端建议按字面值跳转（如 `/admin/order/orders/{id}?tab=overview`），不是后端约定渲染
|
||||||
|
- ⚠️ **`preview` 条件返回**：`allPassed=false` 时 `preview` 为 null，前端不渲染预览区
|
||||||
|
- ⚠️ **`preview` 数据是预演**：本接口返回的合同方案 / 保险方案是「点击确认后会执行什么」的预演，**不**意味着已经执行（实际执行由 §3.14 `eventCode=CONFIRM` 触发）
|
||||||
|
|
||||||
|
#### 示例
|
||||||
|
|
||||||
|
**典型（未通过） - 请求**：
|
||||||
|
|
||||||
|
```http
|
||||||
|
GET /v3/admin/order/60123456789012/confirm-checklist
|
||||||
|
Authorization: Bearer {admin_jwt}
|
||||||
|
```
|
||||||
|
|
||||||
|
**典型（未通过） - 响应**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"data": {
|
||||||
|
"allPassed": false,
|
||||||
|
"items": [
|
||||||
|
{"code": "TRAVELER_COMPLETE", "passed": false, "failReason": "出行人信息未完善 1/3 (小明缺证件号)", "actionPath": "/admin/order/orders/60123456789012?tab=overview"},
|
||||||
|
{"code": "PAYMENT_OK", "passed": true, "failReason": null, "actionPath": null},
|
||||||
|
{"code": "HOTEL_DONE", "passed": true, "failReason": null, "actionPath": null},
|
||||||
|
{"code": "VEHICLE_DONE", "passed": true, "failReason": null, "actionPath": null},
|
||||||
|
{"code": "CONTRACT_TEMPLATE_OK", "passed": true, "failReason": null, "actionPath": null}
|
||||||
|
],
|
||||||
|
"preview": null
|
||||||
|
},
|
||||||
|
"msg": "success"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**典型（全通过） - 请求**：（同上）
|
||||||
|
|
||||||
|
**典型（全通过） - 响应**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"data": {
|
||||||
|
"allPassed": true,
|
||||||
|
"items": [
|
||||||
|
{"code": "TRAVELER_COMPLETE", "passed": true, "failReason": null, "actionPath": null},
|
||||||
|
{"code": "PAYMENT_OK", "passed": true, "failReason": null, "actionPath": null},
|
||||||
|
{"code": "HOTEL_DONE", "passed": true, "failReason": null, "actionPath": null},
|
||||||
|
{"code": "VEHICLE_DONE", "passed": true, "failReason": null, "actionPath": null},
|
||||||
|
{"code": "CONTRACT_TEMPLATE_OK", "passed": true, "failReason": null, "actionPath": null}
|
||||||
|
],
|
||||||
|
"preview": {
|
||||||
|
"departureDate": "2026-05-30",
|
||||||
|
"totalPeopleCount": 14,
|
||||||
|
"driverName": "扎西师傅",
|
||||||
|
"driverPhoneMasked": "1398761****",
|
||||||
|
"hotels": [
|
||||||
|
{"cityName": "拉萨", "hotelName": "瑞吉度假酒店"},
|
||||||
|
{"cityName": "林芝", "hotelName": "悦榕庄"}
|
||||||
|
],
|
||||||
|
"contractAutoAction": {
|
||||||
|
"planName": "标准跟团方案 v3.2",
|
||||||
|
"autoSign": true
|
||||||
|
},
|
||||||
|
"insuranceAutoAction": {
|
||||||
|
"planName": "安联境内旅行险 · 尊享版",
|
||||||
|
"peopleCount": 14,
|
||||||
|
"effectiveDescription": "出发前 24h 内生效"
|
||||||
|
},
|
||||||
|
"notifications": {
|
||||||
|
"notifyDriver": true,
|
||||||
|
"notifyHotel": true,
|
||||||
|
"notifyCustomer": true,
|
||||||
|
"customerChannel": "WX"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"msg": "success"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 6. 枚举 / 数据字典
|
## 6. 枚举 / 数据字典
|
||||||
|
|
||||||
> 跨接口共享枚举集中列出，按字段分组，标注「使用字段在哪里」。
|
> 跨接口共享枚举集中列出，按字段分组，标注「使用字段在哪里」。
|
||||||
@ -1201,13 +1642,66 @@ Content-Type: application/json
|
|||||||
|
|
||||||
`OrderMainVO.exceptionBadges` 9 类布尔标识 / `progressStepper.nodes[].key` / `progressStepper.nodes[].status` 字段含义已在 §3.3 出参说明中列出。
|
`OrderMainVO.exceptionBadges` 9 类布尔标识 / `progressStepper.nodes[].key` / `progressStepper.nodes[].status` 字段含义已在 §3.3 出参说明中列出。
|
||||||
|
|
||||||
|
### 6.17 transition eventCode（状态机事件代码）
|
||||||
|
|
||||||
|
**使用字段**：§3.14 入参 `eventCode`
|
||||||
|
|
||||||
|
| 值 | 说明 |
|
||||||
|
|----|------|
|
||||||
|
| `PAY_DEPOSIT` | 客户支付订金 |
|
||||||
|
| `PAY_FULL` | 客户支付全款 |
|
||||||
|
| `SET_PENDING_BALANCE` | 切到「待支付尾款」细状态 |
|
||||||
|
| `SET_PENDING_DEPARTURE` | 切到「待出行」细状态（系统时机到达） |
|
||||||
|
| `CONFIRM` | 定制师确认锁单（需先通过 §3.15 checklist） |
|
||||||
|
| `INITIATE_REFUND` | 发起退款 |
|
||||||
|
| `CANCEL` | 取消订单 |
|
||||||
|
| `DEPART` | 标记出发（订单进入「出行中」） |
|
||||||
|
| `FINISH` | 标记完成 |
|
||||||
|
|
||||||
|
### 6.18 transition triggeredEvents（状态机副作用事件）
|
||||||
|
|
||||||
|
**使用字段**：§3.14 出参 `triggeredEvents[]`
|
||||||
|
|
||||||
|
| 值 | 说明 |
|
||||||
|
|----|------|
|
||||||
|
| `ASYNC_CONTRACT_GENERATE` | 异步生成电子合同 |
|
||||||
|
| `ASYNC_INSURANCE_ISSUE` | 异步出保单 |
|
||||||
|
| `NOTIFY_DRIVER` | 通知司机 |
|
||||||
|
| `NOTIFY_HOTEL` | 通知酒店确认房态 |
|
||||||
|
| `NOTIFY_CUSTOMER` | 向客户发出行提醒 |
|
||||||
|
| `ASYNC_REFUND_APPLY` | 异步发起退款申请 |
|
||||||
|
|
||||||
|
> 副作用异步执行，本接口返回时可能未完成；用 §3.7 status-log Tab 跟踪进度。
|
||||||
|
|
||||||
|
### 6.19 checklist item code（确认锁单前置 5 项）
|
||||||
|
|
||||||
|
**使用字段**：§3.15 出参 `items[].code`
|
||||||
|
|
||||||
|
| 值 | 说明 |
|
||||||
|
|----|------|
|
||||||
|
| `TRAVELER_COMPLETE` | 出行人信息完整（姓名 + 证件 + 手机 + 证件类型齐） |
|
||||||
|
| `PAYMENT_OK` | 支付状态满足（订金或全款到账） |
|
||||||
|
| `HOTEL_DONE` | 配房完成（hotel_stage = DONE） |
|
||||||
|
| `VEHICLE_DONE` | 配车完成（vehicle_stage = DONE） |
|
||||||
|
| `CONTRACT_TEMPLATE_OK` | 合同模板就绪（产品快照含合同方案） |
|
||||||
|
|
||||||
|
### 6.20 customerChannel（客户通知渠道）
|
||||||
|
|
||||||
|
**使用字段**：§3.15 出参 `preview.notifications.customerChannel`
|
||||||
|
|
||||||
|
| 值 | 说明 |
|
||||||
|
|----|------|
|
||||||
|
| `WX` | 仅企微 / 微信 |
|
||||||
|
| `SMS` | 仅短信 |
|
||||||
|
| `MIXED` | 双通道（企微 + 短信） |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 11. 影响评估
|
## 11. 影响评估
|
||||||
|
|
||||||
- **是否破坏向后兼容**：否（v3 全新二期，前端 v3 项目仓库首次消费）
|
- **是否破坏向后兼容**：否（v3 全新二期，前端 v3 项目仓库首次消费）
|
||||||
- **前端是否必须同步上线**：是
|
- **前端是否必须同步上线**：是
|
||||||
- **本次推送范围**：§1A 10 接口；§1B 取消订单 / §1C 状态机后续 commit 追加
|
- **本次推送范围**：§1 模块全 15 接口（§1A 10 接口 + §1B 取消 3 接口 + §1C 状态机+锁单 2 接口），覆盖订单核心全生命周期入口
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -1217,6 +1711,8 @@ Content-Type: application/json
|
|||||||
- **§3.8 / §3.9 条件显示**：`data=null` 时前端不渲染对应 Tab
|
- **§3.8 / §3.9 条件显示**：`data=null` 时前端不渲染对应 Tab
|
||||||
- **首屏 vs 单 Tab 刷新**：详情页打开用 §3.3 主聚合（一次拿 main + tags + overview）；Tab 切换 / 单 Tab 操作完按需调 §3.4 ~ §3.9
|
- **首屏 vs 单 Tab 刷新**：详情页打开用 §3.3 主聚合（一次拿 main + tags + overview）；Tab 切换 / 单 Tab 操作完按需调 §3.4 ~ §3.9
|
||||||
- **公司隔离 581021**：所有 §1 接口均带跨公司隔离校验，前端无需自行过滤
|
- **公司隔离 581021**：所有 §1 接口均带跨公司隔离校验，前端无需自行过滤
|
||||||
|
- **取消订单分支**：出行前走 §3.12 走政策算金额 + 企微 OA 审批；出行中走 §3.13 仅登记返还金额（核单 Step 5 自动拉取实退）；前端按 §3.11 预览的 `daysToDeparture` 决定走哪个入口
|
||||||
|
- **CONFIRM 锁单**：前端点【确认订单】按钮**必须**先调 §3.15 checklist 拿 `allPassed=true` 再调 §3.14 `eventCode=CONFIRM`，否则后端拒绝（`581063`）
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -1229,7 +1725,6 @@ Content-Type: application/json
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📝 §1B / §1C 推送计划
|
## 📝 后续追加计划
|
||||||
|
|
||||||
- **§1B 取消订单**（§1.5.0 + §1.5.1 + §1.5.2）：业务联调通过后 commit 追加本文件
|
§1 模块 15 接口全部首推完毕。后续若有接口字段调整 / 错误码新增 / 业务边界变化，通过追加 commit 扩充本文件。
|
||||||
- **§1C 状态机 + 锁单**（§1.7 + §1.8）：状态机完整测试通过后 commit 追加
|
|
||||||
|
|||||||
正在加载...
x
在新工单中引用
屏蔽一个用户