hl-api-changelog/changelogs/2026-04/2026-04-21_mp-order-arrival.md

微信小程序 · 订单到达/离开信息接口(5 个 CRUD)

日期:2026-04-21 影响:微信小程序 行程前·出发准备页(原型 ew2Kk)、订单详情到达信息弹窗(原型 6pfmI / uq0UL / K2s5H / L4xYN / oVMYy / AQ21V / amizC) PR:#1000(Closes #998)

---

概述

订单"分批到达/离开"模型,用户在行程前填写:

• 到达(ARRIVAL):从住所抵达目的地
• 离开(DEPARTURE):从目的地返程

每个订单可有多批(带小孩/家人分几趟飞),每批一条 MpArrivalPlanRespVO 记录,包含交通方式、班次、站点、时间、本批涉及的出行人。

共 5 个 CRUD 接口:查全量、新增、全量替换、修改、删除。

---

1. 查全量批次

GET /mp/order/{orderId}/arrival

鉴权:Bearer token。

入参

参数	位置	类型	必填
orderId	Path	Long	✅

出参 Result<MpArrivalListRespVO>

字段	类型	说明
orderId	Long	订单ID
arrivals	List<MpArrivalPlanRespVO>	到达批次列表
departures	List<MpArrivalPlanRespVO>	离开批次列表

MpArrivalPlanRespVO 字段见第 2 节出参。

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "orderId": 700001,
    "arrivals": [
      {
        "planId": 800001,
        "orderId": 700001,
        "direction": "ARRIVAL",
        "directionLabel": "到达",
        "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"}
        ]
      }
    ],
    "departures": []
  },
  "success": true
}

---

2. 新增批次

POST /mp/order/{orderId}/arrival

鉴权:Bearer token。 创建者类型:creatorType=USER(用户自填)。

入参

参数	位置	类型	必填
orderId	Path	Long	✅

Body MpArrivalPlanSaveReqVO:

字段	类型	必填	约束	说明
direction	String	✅	-	ARRIVAL / DEPARTURE(字典 transport_direction)
transportType	String	✅	-	FLIGHT / TRAIN / SELF_DRIVE(字典 transport_type 子集)
transportNo	String	FLIGHT/TRAIN 必填	≤32	航班号/车次号,如 CZ6255
carrier	String	否	≤64	航司/铁路公司,如 南方航空
departStation	String	否	≤64	出发站/机场
arriveStation	String	否	≤64	到达站/机场
departTime	LocalDateTime	否	-	出发时间
arriveTime	LocalDateTime	否	-	到达时间
selfDrivePeriod	String	SELF_DRIVE 必填	-	MORNING / AFTERNOON / EVENING(字典 self_drive_period)
selfDriveEta	LocalDateTime	否	-	自驾预计到达精确时间
remark	String	否	≤255	用户备注
travelerIds	List<Long>	✅ 非空	-	本批次涉及的出行人 ID 列表;必须属于本订单

出参 Result<MpArrivalPlanRespVO>

字段	类型	说明
planId	Long	批次ID
orderId	Long	订单ID
direction	String	方向
directionLabel	String	方向中文标签
transportType	String	交通方式
transportTypeLabel	String	交通方式中文标签
transportNo	String	航班号/车次号
carrier	String	航司/铁路公司
departStation	String	出发站
arriveStation	String	到达站
departTime	LocalDateTime	出发时间
arriveTime	LocalDateTime	到达时间
selfDrivePeriod	String	自驾时段
selfDrivePeriodLabel	String	自驾时段中文标签,如 下午(12:00-18:00)
selfDriveEta	LocalDateTime	自驾预计到达
remark	String	备注
creatorType	String	USER(用户自填)/ADMIN(定制师代录)(字典 creator_type)
createTime	LocalDateTime	创建时间
travelers	List<MpArrivalPlanTravelerSimpleVO>	本批次涉及的出行人(脱敏)

MpArrivalPlanTravelerSimpleVO:

字段	类型	说明
travelerId	Long	出行人ID
name	String	姓名
travelerType	String	ADULT / CHILD / YOUNG_CHILD / BABY(字典 traveler_type)

请求示例

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

---

3. 全量替换

POST /mp/order/{orderId}/arrival/batch

鉴权:Bearer token。

先软删当前所有批次,再按请求体批量创建。空数组 [] = 清空订单的所有到达/离开批次。

入参

参数	位置	类型	必填
orderId	Path	Long	✅

Body:List<MpArrivalPlanSaveReqVO>(每项结构同第 2 节)。

出参

Result<MpArrivalListRespVO> — 替换完成后的全量数据,结构同第 1 节。

---

4. 修改批次

PUT /mp/order/{orderId}/arrival/plan/{planId}

鉴权:Bearer token。

覆盖语义:按字段全量覆盖,包括 travelerIds(替换旧关联)。

入参

参数	位置	类型	必填
orderId	Path	Long	✅
planId	Path	Long	✅

Body:MpArrivalPlanSaveReqVO(同第 2 节)。

出参

Result<MpArrivalPlanRespVO> — 修改后的批次,结构同第 2 节。

---

5. 删除批次

DELETE /mp/order/{orderId}/arrival/plan/{planId}

鉴权:Bearer token。

级联:软删关联的出行人绑定行。

入参

参数	位置	类型	必填
orderId	Path	Long	✅
planId	Path	Long	✅

出参

Result<Void>:

{ "code": 200, "message": "成功", "data": null, "success": true }

---

边界行为

• 字段校验:transportType=FLIGHT/TRAIN 时 transportNo 必填;transportType=SELF_DRIVE 时 selfDrivePeriod 必填
• 出行人校验:travelerIds 中的 ID 必须属于本订单,否则 400
• 订单不存在/无权限:500,message 含 orderId
• 用户填的批次 creatorType=USER;定制师后台代录的 creatorType=ADMIN

---

辅助接口(填写表单时用,来自同一批交付)

GET /mp/transport/flight?flightNo=CZ6255&date=2026-07-10    按航班号查航班动态
GET /mp/transport/train?trainNo=G71&date=2026-07-10         按车次号查火车

出参 Result<List<MpFlightInfoVO>> / Result<List<MpTrainInfoVO>>,字段:flightNo/trainNo / airline / departAirport / arriveAirport / scheduledDepartTime / scheduledArriveTime / flightStatus / remark。

---

字典依赖

字典类型	说明
transport_direction	ARRIVAL / DEPARTURE
transport_type	FLIGHT / TRAIN / SELF_DRIVE(本场景只用这 3 个子集)
self_drive_period	MORNING / AFTERNOON / EVENING
creator_type	USER / ADMIN
traveler_type	ADULT / CHILD / YOUNG_CHILD / BABY

所有 xxxLabel 字段均由 BFF 透传自 order-v2,已经是中文展示值。