diff --git a/changelogs/2026-04/2026-04-20_order-v2_arrival.md b/changelogs/2026-04/2026-04-20_order-v2_arrival.md new file mode 100644 index 0000000..cb8705e --- /dev/null +++ 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)