wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

changelog(mp): PR#1878 到达/返程批次支持一起/多批两种模式 — POST /arrival 语义变更 + mode/modeLabel 新增 + batch bug 修复 + 错误码 580010

浏览代码
这个提交包含在：
yaosutu 2026-05-08 16:23:01 +08:00
父节点 7118f4f7ff
当前提交 4c65455726
共有 1 个文件被更改，包括 528 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

528
changelogs/2026-05/08_1500_arrival-mode.md 普通文件
查看文件

@ -0,0 +1,528 @@
# API 变更通知
**更新时间**: 2026-05-08 15:00
**PR**: #1878 feat(order-v2): 到达/返程信息支持区分一起/多批两种模式 + #1887 修正接口描述
---
## 破坏性变更：POST /mp/order/{orderId}/arrival 语义彻底变更
### 变了什么（前端视角）
**单数接口从「追加一条」变成「该方向全量替换 1 条」。**
| 行为 | 旧逻辑（PR 前） | 新逻辑（PR 后） |
|------|----------------|----------------|
| 连续调 2 次 | 产生 2 条批次（追加） | 第 2 次会把第 1 次清掉，只保留最新 1 条 |
| 想分批到达 | 多次调单数接口 | 必须改用 /arrival/batch（提交多元素数组） |
| 已有批次被覆盖范围 | 无此逻辑 | 只清同一 direction 的旧批次，不影响另一方向 |
如果小程序之前通过多次调 POST /arrival 实现「分批到达」，现在必须改为调 POST /arrival/batch。
---
## Bug 修复：POST /mp/order/{orderId}/arrival/batch 不再误删另一方向
| 行为 | 旧行为（有 bug） | 新行为（已修复） |
|------|----------------|----------------|
| 提交返程多批 | 把已填的到达批次也一起删掉 | 只删 direction=DEPARTURE 的旧批次，ARRIVAL 不受影响 |
| 提交到达多批 | 把已填的返程批次也一起删掉 | 只删 direction=ARRIVAL 的旧批次，DEPARTURE 不受影响 |
如果前端之前因为这个 bug 做了「先查再保」之类的 workaround，可以清理掉。
---
## 新增：GET 接口返回 mode + modeLabel 字段
GET /mp/order/{orderId}/arrival 返回的每个批次对象新增 2 个字段：
| 字段 | 类型 | 说明 |
|------|------|------|
| mode | String | 模式枚举：TOGETHER 或 SEPARATE |
| modeLabel | String | 按方向拼出的中文标签（见下表） |
modeLabel 的 4 种值：
| direction | mode | modeLabel |
|-----------|------|----------|
| ARRIVAL | TOGETHER | 一起到达 |
| ARRIVAL | SEPARATE | 多批到达 |
| DEPARTURE | TOGETHER | 一起返程 |
| DEPARTURE | SEPARATE | 多批返程 |
前端可以用 arrivals[0]?.mode（或 departures[0]?.mode）来判断该方向当前 tab 模式，决定进入页面时默认选中哪个选项卡。
---
## 新增错误码：580010 BATCH_DIRECTION_MIXED
POST /mp/order/{orderId}/arrival/batch 增加新校验：请求数组里所有元素的 direction 必须一致（不能同一次 batch 里混提 ARRIVAL 和 DEPARTURE）。
| 错误码 | message |
|--------|--------|
| 580010 | 批量提交的批次必须同一方向（到达或返程） |
响应示例（错误）：
```json
{
"code": 580010,
"message": "批量提交的批次必须同一方向（到达或返程）",
"data": null
}
```
---
## 涉及的接口汇总
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 查询订单全量批次 | GET | /mp/order/{orderId}/arrival | 字段新增 | 每个批次对象新增 mode + modeLabel |
| 2 | 新增交通批次 | POST | /mp/order/{orderId}/arrival | 语义破坏性变更 | 从追加改为该方向全量替换 1 条 |
| 3 | 全量替换批次(多批) | POST | /mp/order/{orderId}/arrival/batch | Bug 修复 + 新增校验 | 修方向隔离 bug；新增 direction 混用校验 |
| 4 | 修改交通批次 | PUT | /mp/order/{orderId}/arrival/plan/{planId} | 无变化 | - |
| 5 | 删除交通批次 | DELETE | /mp/order/{orderId}/arrival/plan/{planId} | 无变化 | - |
---
## 接口详细定义
### 1. GET /mp/order/{orderId}/arrival — 查询订单全量到达/离开批次
- **使用场景**：进入订单详情/行程页时查询，用返回的 arrivals[0]?.mode 和 departures[0]?.mode 决定各方向 tab 默认状态
- **路径参数**：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| orderId | Long | 是 | 订单 ID |
- **响应字段（data 对象）**：
| 字段 | 类型 | 说明 |
|------|------|------|
| orderId | Long | 订单 ID |
| arrivals | Array | direction=ARRIVAL 的批次列表 |
| departures | Array | direction=DEPARTURE 的批次列表 |
arrivals/departures 内每个批次对象字段（MpArrivalPlanRespVO）：
| 字段 | 类型 | 说明 |
|------|------|------|
| planId | Long | 批次 ID |
| orderId | Long | 订单 ID |
| direction | String | ARRIVAL/DEPARTURE |
| directionLabel | String | 到达/离开 |
| mode | String | **[本次新增]** TOGETHER/SEPARATE |
| modeLabel | String | **[本次新增]** 一起到达/多批到达/一起返程/多批返程 |
| transportType | String | FLIGHT/TRAIN/SELF_DRIVE |
| transportTypeLabel | String | 飞机/火车/自驾 |
| transportNo | String | 航班号/车次号（自驾为 null） |
| carrier | String | 航司/铁路公司 |
| departStation | String | 出发站/机场 |
| arriveStation | String | 到达站/机场 |
| departTime | String | 出发时间，格式 yyyy-MM-dd HH:mm:ss |
| arriveTime | String | 到达时间，格式 yyyy-MM-dd HH:mm:ss |
| selfDrivePeriod | String | 自驾时段（MORNING/AFTERNOON/EVENING），非自驾为 null |
| selfDrivePeriodLabel | String | 上午/下午/晚上，非自驾为 null |
| selfDriveEta | String | 自驾预计到达精确时间，非自驾为 null |
| remark | String | 用户备注 |
| creatorType | String | USER/ADMIN |
| createTime | String | 创建时间 |
| travelers | Array | 本批次出行人列表 |
travelers 内每个出行人字段：
| 字段 | 类型 | 说明 |
|------|------|------|
| travelerId | Long | 出行人 ID |
| name | String | 姓名 |
| travelerType | String | ADULT/CHILD/YOUNG_CHILD/BABY |
- **响应示例（完整）**：
```json
{
"code": 200,
"message": "success",
"data": {
"orderId": 700001,
"arrivals": [
{
"planId": 800001,
"orderId": 700001,
"direction": "ARRIVAL",
"directionLabel": "到达",
"mode": "TOGETHER",
"modeLabel": "一起到达",
"transportType": "FLIGHT",
"transportTypeLabel": "飞机",
"transportNo": "CZ6255",
"carrier": "南方航空",
"departStation": "北京首都T3",
"arriveStation": "海拉尔东山",
"departTime": "2026-07-10 08:30:00",
"arriveTime": "2026-07-10 11:00:00",
"selfDrivePeriod": null,
"selfDrivePeriodLabel": null,
"selfDriveEta": null,
"remark": "带小孩,需婴儿座椅",
"creatorType": "USER",
"createTime": "2026-07-01 10:00:00",
"travelers": [
{
"travelerId": 10001,
"name": "张三",
"travelerType": "ADULT"
}
]
}
],
"departures": [
{
"planId": 800002,
"orderId": 700001,
"direction": "DEPARTURE",
"directionLabel": "离开",
"mode": "SEPARATE",
"modeLabel": "多批返程",
"transportType": "TRAIN",
"transportTypeLabel": "火车",
"transportNo": "K209",
"carrier": null,
"departStation": "海拉尔",
"arriveStation": "北京",
"departTime": "2026-07-15 10:00:00",
"arriveTime": "2026-07-16 08:00:00",
"selfDrivePeriod": null,
"selfDrivePeriodLabel": null,
"selfDriveEta": null,
"remark": null,
"creatorType": "USER",
"createTime": "2026-07-02 09:00:00",
"travelers": [
{
"travelerId": 10001,
"name": "张三",
"travelerType": "ADULT"
}
]
}
]
}
}
```
---
### 2. POST /mp/order/{orderId}/arrival — 新增交通批次（单条，该方向全量替换）
- **使用场景**：用户在「一起到达」或「一起返程」tab 填写单条信息并提交
- **语义重申**：调用此接口会把同 direction 的所有旧批次软删，再插入 1 条新批次。最终该方向只剩 1 条，mode 固定为 TOGETHER
- **路径参数**：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| orderId | Long | 是 | 订单 ID |
- **请求参数（JSON Body）**：
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| direction | String | 是 | ARRIVAL=到达 / DEPARTURE=离开 |
| transportType | String | 是 | FLIGHT=飞机 / TRAIN=火车 / SELF_DRIVE=自驾 |
| transportNo | String | 条件必填 | 航班号/车次号；FLIGHT/TRAIN 必填，SELF_DRIVE 不填 |
| carrier | String | 否 | 航司/铁路公司，最长 64 字符 |
| departStation | String | 条件必填 | 出发站/机场；DEPARTURE+FLIGHT/TRAIN 必填；ARRIVAL 可选 |
| arriveStation | String | 条件必填 | 到达站/机场；ARRIVAL+FLIGHT/TRAIN 必填；DEPARTURE 可选 |
| departTime | String | 条件必填 | 出发时间；DEPARTURE+FLIGHT/TRAIN 必填；格式 yyyy-MM-dd HH:mm:ss |
| arriveTime | String | 条件必填 | 到达时间；ARRIVAL+FLIGHT/TRAIN 必填；格式 yyyy-MM-dd HH:mm:ss |
| selfDrivePeriod | String | 条件必填 | 自驾时段；SELF_DRIVE 必填；MORNING/AFTERNOON/EVENING |
| selfDriveEta | String | 否 | 自驾预计到达精确时间；SELF_DRIVE 可选；格式 yyyy-MM-dd HH:mm:ss |
| remark | String | 否 | 用户备注，最长 255 字符 |
| travelerIds | Array | 是 | 出行人 ID 列表，至少 1 人，必须属于本订单 |
- **请求示例（到达+飞机）**：
```json
{
"direction": "ARRIVAL",
"transportType": "FLIGHT",
"transportNo": "CZ6255",
"carrier": "南方航空",
"departStation": "北京首都T3",
"arriveStation": "海拉尔东山",
"departTime": "2026-07-10 08:30:00",
"arriveTime": "2026-07-10 11:00:00",
"remark": "带小孩,需婴儿座椅",
"travelerIds": [
10001,
10002
]
}
```
- **响应示例（完整）**：
```json
{
"code": 200,
"message": "success",
"data": {
"planId": 800001,
"orderId": 700001,
"direction": "ARRIVAL",
"directionLabel": "到达",
"mode": "TOGETHER",
"modeLabel": "一起到达",
"transportType": "FLIGHT",
"transportTypeLabel": "飞机",
"transportNo": "CZ6255",
"carrier": "南方航空",
"departStation": "北京首都T3",
"arriveStation": "海拉尔东山",
"departTime": "2026-07-10 08:30:00",
"arriveTime": "2026-07-10 11:00:00",
"selfDrivePeriod": null,
"selfDrivePeriodLabel": null,
"selfDriveEta": null,
"remark": "带小孩,需婴儿座椅",
"creatorType": "USER",
"createTime": "2026-07-01 10:00:00",
"travelers": [
{
"travelerId": 10001,
"name": "张三",
"travelerType": "ADULT"
},
{
"travelerId": 10002,
"name": "李四",
"travelerType": "CHILD"
}
]
}
}
```
---
### 3. POST /mp/order/{orderId}/arrival/batch — 全量替换批次（多批模式）
- **使用场景**：用户在「多批到达」或「多批返程」tab，一次性提交该方向所有批次
- **Bug 修复**：旧版本会把订单全部旧批次删掉（含另一方向），新版本只删 body 第一条元素对应的 direction
- **新增校验**：body 数组里所有元素的 direction 必须一致，混提返回 code=580010
- **路径参数**：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| orderId | Long | 是 | 订单 ID |
- **请求参数（JSON Body，数组）**：字段同上面单条接口，外层包数组
- **请求示例（多批返程）**：
```json
[
{
"direction": "DEPARTURE",
"transportType": "FLIGHT",
"transportNo": "CZ6256",
"carrier": "南方航空",
"departStation": "海拉尔东山",
"arriveStation": "北京首都T3",
"departTime": "2026-07-15 12:00:00",
"arriveTime": "2026-07-15 15:30:00",
"travelerIds": [
10001
]
},
{
"direction": "DEPARTURE",
"transportType": "TRAIN",
"transportNo": "K209",
"departStation": "海拉尔",
"arriveStation": "北京",
"departTime": "2026-07-15 10:00:00",
"arriveTime": "2026-07-16 08:00:00",
"travelerIds": [
10002
]
}
]
```
- **响应示例（完整）**：
```json
{
"code": 200,
"message": "success",
"data": {
"orderId": 700001,
"arrivals": [],
"departures": [
{
"planId": 800003,
"orderId": 700001,
"direction": "DEPARTURE",
"directionLabel": "离开",
"mode": "SEPARATE",
"modeLabel": "多批返程",
"transportType": "FLIGHT",
"transportTypeLabel": "飞机",
"transportNo": "CZ6256",
"carrier": "南方航空",
"departStation": "海拉尔东山",
"arriveStation": "北京首都T3",
"departTime": "2026-07-15 12:00:00",
"arriveTime": "2026-07-15 15:30:00",
"selfDrivePeriod": null,
"selfDrivePeriodLabel": null,
"selfDriveEta": null,
"remark": null,
"creatorType": "USER",
"createTime": "2026-07-01 11:00:00",
"travelers": [
{
"travelerId": 10001,
"name": "张三",
"travelerType": "ADULT"
}
]
},
{
"planId": 800004,
"orderId": 700001,
"direction": "DEPARTURE",
"directionLabel": "离开",
"mode": "SEPARATE",
"modeLabel": "多批返程",
"transportType": "TRAIN",
"transportTypeLabel": "火车",
"transportNo": "K209",
"carrier": null,
"departStation": "海拉尔",
"arriveStation": "北京",
"departTime": "2026-07-15 10:00:00",
"arriveTime": "2026-07-16 08:00:00",
"selfDrivePeriod": null,
"selfDrivePeriodLabel": null,
"selfDriveEta": null,
"remark": null,
"creatorType": "USER",
"createTime": "2026-07-01 11:00:00",
"travelers": [
{
"travelerId": 10002,
"name": "李四",
"travelerType": "CHILD"
}
]
}
]
}
}
```
---
## 枚举 / 字典值（完整）
### transport_direction（方向）
| 值 | 中文 | 说明 |
|----|------|------|
| ARRIVAL | 到达 | 游客到达目的地 |
| DEPARTURE | 离开 | 游客离开目的地（返程） |
### mode（模式，本次新增）
| 值 | 中文 | 说明 |
|----|------|------|
| TOGETHER | 一起 | 该方向所有出行人同一批次 |
| SEPARATE | 多批 | 该方向出行人分多个批次 |
### modeLabel（按 direction + mode 拼，本次新增）
| direction | mode | modeLabel |
|-----------|------|-----------|
| ARRIVAL | TOGETHER | 一起到达 |
| ARRIVAL | SEPARATE | 多批到达 |
| DEPARTURE | TOGETHER | 一起返程 |
| DEPARTURE | SEPARATE | 多批返程 |
### transport_type（交通方式）
| 值 | 中文 |
|----|------|
| FLIGHT | 飞机 |
| TRAIN | 火车 |
| SELF_DRIVE | 自驾 |
### self_drive_period（自驾时段）
| 值 | 中文 | 时间范围 |
|----|------|---------|
| MORNING | 上午 | 06:00-12:00 |
| AFTERNOON | 下午 | 12:00-18:00 |
| EVENING | 晚上 | 18:00 以后 |
### creator_type（创建者类型）
| 值 | 中文 |
|----|------|
| USER | 用户自填 |
| ADMIN | 定制师代录 |
### traveler_type（出行人类型）
| 值 | 中文 |
|----|------|
| ADULT | 成人 |
| CHILD | 儿童 |
| YOUNG_CHILD | 幼儿 |
| BABY | 婴儿 |
---
## 错误码（本模块完整）
| code | message | 触发场景 |
|------|---------|---------|
| 580001 | 订单当前状态不可修改交通信息: {状态} | 订单不在可编辑状态 |
| 580002 | 出行人列表不能为空 | travelerIds 为空 |
| 580003 | 以下出行人不属于本订单: {ids} | travelerIds 包含不属于此订单的 ID |
| 580004 | 航班号/车次号不能为空 | FLIGHT/TRAIN 时 transportNo 未填 |
| 580005 | 到达机场/车站不能为空 | ARRIVAL+FLIGHT/TRAIN 时 arriveStation 未填 |
| 580006 | 到达时间不能为空 | ARRIVAL+FLIGHT/TRAIN 时 arriveTime 未填 |
| 580007 | 出发机场/车站不能为空 | DEPARTURE+FLIGHT/TRAIN 时 departStation 未填 |
| 580008 | 出发时间不能为空 | DEPARTURE+FLIGHT/TRAIN 时 departTime 未填 |
| 580009 | 自驾时段不能为空 | SELF_DRIVE 时 selfDrivePeriod 未填 |
| 580010 | 批量提交的批次必须同一方向（到达或返程） | batch 接口 body 内 direction 混用（本次新增） |
---
## 业务规则 / 校验规则
1. POST /arrival（单数）：提交即清空同 direction 旧批次，再插入 1 条。最终该方向只有 1 条批次，mode 固定为 TOGETHER。
2. POST /arrival/batch：提交即清空同 direction 旧批次，再批量插入。有 2 条及以上时 mode 为 SEPARATE；仅 1 条时 mode 也是 SEPARATE（因为用户选择了「多批」入口）。
3. 两个接口只影响自己提交的 direction，不互相干扰（本次 bug 修复要点）。
4. PUT /arrival/plan/{planId} 修改单条，不影响其他批次，不改变 mode。
5. DELETE /arrival/plan/{planId} 只软删单条。
6. 以上操作均需订单处于可编辑状态，否则返回 580001。
---
## 前端实现建议
---
## 补充说明
- GET 接口新增 mode/modeLabel 字段，向后兼容（纯新增，无删改名），已有代码不受影响
- POST 单数接口语义变更属于破坏性变更，旧版用多次调单数接口实现分批的需改用 batch
- 服务重启：需重启 hl-order-service-v2 和 hl-mp-service 后生效