hl-api-changelog/changelogs/2026-04/2026-04-20_order-v2_arrival.md

到达信息接口新增 — 2026-04-20

服务 hl-order-service-v2（端口 8094）· 类型 feat · 关联 Issue #990 / PR #992 + Issue #998 / PR #1000 前端调用路径: 网关(8080) → hl-mp-service(8085) → hl-order-service-v2(8094) / hl-resource-service(8082) 前端实际请求前缀: /mp/order/{orderId}/arrival（5 接口）+ /mp/transport/{flight|train}（2 接口）

---

一、能力概述

订单出行前/后，用户可填写接送机信息。一个订单可分多个批次（每批一套交通方案 + 多个出行人），天然支持"一家分两批到达"。覆盖原型 8 个到达弹窗：

原型节点	功能	主要接口
6pfmI	填写到达·单批	POST /arrival
uq0UL	分批到达列表	GET /arrival + POST /arrival/batch
K2s5H	添加批次弹窗	POST /arrival
L4xYN	已识别航班回显	GET /transport/flight → POST /arrival
oVMYy	选择航班	GET /transport/flight
AQ21V	空态	GET /transport/flight（结果空）
amizC	手动填写	POST /arrival（最小字段）
Bf9jC	添加人员	（出行人接口，另 Issue）

---

二、接口清单

鉴权：user token（登录态）

方法	路径	用途
GET	/mp/order/{orderId}/arrival	查全量批次（按方向分组）
POST	/mp/order/{orderId}/arrival	新增一个批次
POST	/mp/order/{orderId}/arrival/batch	一次性提交多个批次（全量替换，空数组=清空）
PUT	/mp/order/{orderId}/arrival/plan/{planId}	修改批次（全量覆盖）
DELETE	/mp/order/{orderId}/arrival/plan/{planId}	删除批次
GET	/mp/transport/flight?flightNo=&date=	按航班号+日期查航班动态
GET	/mp/transport/train?trainNo=&date=	按车次号+日期查火车动态

---

三、请求体

{
  "direction":       "ARRIVAL",       // ARRIVAL 到达 / DEPARTURE 离开
  "transportType":   "FLIGHT",        // FLIGHT / TRAIN / SELF_DRIVE
  "transportNo":     "CZ6255",
  "carrier":         "南方航空",
  "departStation":   "北京首都T3",
  "arriveStation":   "海拉尔东山",
  "departTime":      "2026-07-10 08:30:00",
  "arriveTime":      "2026-07-10 11:00:00",
  "selfDrivePeriod": "AFTERNOON",     // MORNING / AFTERNOON / EVENING
  "selfDriveEta":    "2026-07-10 15:30:00",
  "remark":          "带小孩,需婴儿座椅",
  "travelerIds":     [10001, 10002]
}

字段必填矩阵（前端表单校验对齐）：

字段	ARRIVAL + FLIGHT/TRAIN	DEPARTURE + FLIGHT/TRAIN	SELF_DRIVE
transportNo	✅	✅	—
arriveStation	✅	选	—
arriveTime	✅	选	—
departStation	选	✅	—
departTime	选	✅	—
carrier	选	选	—
selfDrivePeriod	—	—	✅
travelerIds	✅（≥1）	✅（≥1）	✅（≥1）

原则：司机接机只看到达、送机只看出发。amizC 手动填只 4 字段就是这个设计。

---

四、响应体

{
  "code": 200,
  "data": {
    "orderId": "2046159434324783106",       // String 防大数精度丢失
    "arrivals": [                            // ARRIVAL 批次列表
      {
        "planId": "2046165477229555714",
        "direction": "ARRIVAL",
        "directionLabel": "到达",
        "transportType": "FLIGHT",
        "transportTypeLabel": "飞机",
        "transportNo": "CZ6255",
        "arriveStation": "海拉尔东山",
        "arriveTime": "2026-07-10 15:30:00",
        "creatorType": "USER",
        "travelers": [
          {"travelerId": "10001", "name": "张三", "travelerType": "ADULT"},
          {"travelerId": "10002", "name": "李四", "travelerType": "ADULT"}
        ]
      }
    ],
    "departures": []                         // DEPARTURE 批次列表，同结构
  }
}

约定：

• 所有 ID 是 String（雪花 ID 防大数精度丢失）
• 未传字段返回 null，列表空返回 []
• 时间统一 yyyy-MM-dd HH:mm:ss
• 所有枚举字段配 xxxLabel 中文标签

---

五、关联

• Issue: wx/HL#990 / wx/HL#998
• PR: wx/HL#992 / wx/HL#1000（均已合并到 dev）