# 到达信息接口新增 — 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=` | 按车次号+日期查火车动态 |

---

## 三、请求体

```jsonc
{
  "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 字段就是这个设计。

---

## 四、响应体

```jsonc
{
  "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](https://git.1814.love:8443/wx/HL/issues/990) / [wx/HL#998](https://git.1814.love:8443/wx/HL/issues/998)
- PR: [wx/HL#992](https://git.1814.love:8443/wx/HL/pulls/992) / [wx/HL#1000](https://git.1814.love:8443/wx/HL/pulls/1000)（均已合并到 dev）
