feat(order-v2): 到达信息接口 changelog (#990/#992 + #998/#1000)

新增 /mp/order/{orderId}/arrival 5 接口 + /mp/transport 2 接口。覆盖原型 8 个到达信息弹窗,支持分批到达、全量替换、航班/火车实时查询。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-20 18:31:21 +08:00 · 2026-04-20 18:31:21 +08:00 · 8dafe1b9cb
--- a/changelogs/2026-04/2026-04-20_order-v2_arrival.md
+++ b/changelogs/2026-04/2026-04-20_order-v2_arrival.md
@ -0,0 +1,119 @@
+# 到达信息接口新增 — 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）