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

2026-05-08 16:23:22 +08:00

17 KiB

原始文件 Blame 文件历史

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	批量提交的批次必须同一方向（到达或返程）

响应示例（错误）：

{
  "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

响应示例（完整）：

{
  "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 人，必须属于本订单

请求示例（到达+飞机）：

{
  "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
  ]
}

响应示例（完整）：

{
  "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，数组）：字段同上面单条接口，外层包数组
请求示例（多批返程）：

[
  {
    "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
    ]
  }
]

响应示例（完整）：

{
  "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 混用（本次新增）

业务规则 / 校验规则

POST /arrival（单数）：提交即清空同 direction 旧批次，再插入 1 条。最终该方向只有 1 条批次，mode 固定为 TOGETHER。
POST /arrival/batch：提交即清空同 direction 旧批次，再批量插入。有 2 条及以上时 mode 为 SEPARATE；仅 1 条时 mode 也是 SEPARATE（因为用户选择了「多批」入口）。
两个接口只影响自己提交的 direction，不互相干扰（本次 bug 修复要点）。
PUT /arrival/plan/{planId} 修改单条，不影响其他批次，不改变 mode。
DELETE /arrival/plan/{planId} 只软删单条。
以上操作均需订单处于可编辑状态，否则返回 580001。

前端实现建议

补充说明

GET 接口新增 mode/modeLabel 字段，向后兼容（纯新增，无删改名），已有代码不受影响
POST 单数接口语义变更属于破坏性变更，旧版用多次调单数接口实现分批的需改用 batch
服务重启：需重启 hl-order-service-v2 和 hl-mp-service 后生效

17 KiB 原始文件 Blame 文件历史 Unescape Escape