diff --git a/changelogs/2026-04/2026-04-21_mp-order-arrival.md b/changelogs/2026-04/2026-04-21_mp-order-arrival.md index 909c6fa..2691ae6 100644 --- a/changelogs/2026-04/2026-04-21_mp-order-arrival.md +++ b/changelogs/2026-04/2026-04-21_mp-order-arrival.md @@ -252,14 +252,151 @@ DELETE /mp/order/{orderId}/arrival/plan/{planId} --- -## 辅助接口(填写表单时用,来自同一批交付) +## 辅助接口 · 航班/火车动态查询(填写表单时用,来自同一批交付) -``` -GET /mp/transport/flight?flightNo=CZ6255&date=2026-07-10 按航班号查航班动态 -GET /mp/transport/train?trainNo=G71&date=2026-07-10 按车次号查火车 +数据源:飞常准官方 API,resource-service 侧做 Redis 缓存后透传。返回为**列表**(同航班号可能有共享航班、同车次日间可能多班次)。 + +### 航班查询(3 个) + +| 路径 | 入参 | 场景 | +|---|---|---| +| `GET /mp/transport/flight` | `flightNo`(如 `CA1133`)、`date`(`yyyy-MM-dd`) | 按航班号 + 日期查 | +| `GET /mp/transport/flight/by-airport` | `dep`、`arr`(机场三字码,如 `PEK`/`HLD`)、`date` | 按出发/到达机场三字码 + 日期查 | +| `GET /mp/transport/flight/by-city` | `depCity`、`arrCity`(城市三字码,如 `BJS`/`SHA`)、`date` | 按出发/到达城市 + 日期查(覆盖多机场) | + +**出参**:`Result>` + +| 字段 | 类型 | 说明 | +|---|---|---| +| flightNo | String | 航班号,如 `CA1133` | +| airline | String | 航空公司名称 | +| category | String | 航班属性:`国内`/`国际`/`地区` | +| departAirportCode | String | 出发机场三字码,如 `PEK` | +| arriveAirportCode | String | 到达机场三字码,如 `HLD` | +| departAirport | String | 出发机场名称,如 `北京首都` | +| arriveAirport | String | 到达机场名称,如 `呼伦贝尔海拉尔` | +| departCity | String | 出发城市,如 `北京` | +| arriveCity | String | 到达城市,如 `海拉尔` | +| planDepartTime | String | 计划起飞时间(`yyyy-MM-dd HH:mm:ss`) | +| planArriveTime | String | 计划到达时间(`yyyy-MM-dd HH:mm:ss`) | +| actualDepartTime | String | 实际起飞时间(未起飞为 null) | +| actualArriveTime | String | 实际到达时间(未到达为 null) | +| status | String | 航班状态:`计划`/`起飞`/`到达`/`延误`/`取消`/`返航`/`备降` 等 | +| stopFlag | String | 是否经停:`0`=不经停,`1`=经停 1 次,`n`=经停 n 次 | +| shareFlag | String | 是否共享航班:`0`=否,`1`=是 | +| shareFlightNo | String | 共享航班号(实际承运航班号) | +| departTerminal | String | 出发航站楼,如 `T2` | +| arriveTerminal | String | 到达航站楼 | +| boardGate | String | 登机口 | +| arriveExit | String | 到达出口 | +| departTimezone | String | 出发时区偏移(秒) | +| arriveTimezone | String | 到达时区偏移(秒) | + +**响应示例**: + +```json +{ + "code": 200, + "message": "成功", + "data": [ + { + "flightNo": "CA1133", + "airline": "中国国际航空股份有限公司", + "category": "国内", + "departAirportCode": "PEK", + "arriveAirportCode": "HLD", + "departAirport": "北京首都", + "arriveAirport": "呼伦贝尔海拉尔", + "departCity": "北京", + "arriveCity": "海拉尔", + "planDepartTime": "2026-07-10 06:45:00", + "planArriveTime": "2026-07-10 08:55:00", + "actualDepartTime": null, + "actualArriveTime": null, + "status": "计划", + "stopFlag": "0", + "shareFlag": "0", + "shareFlightNo": null, + "departTerminal": "T2", + "arriveTerminal": null, + "boardGate": null, + "arriveExit": null, + "departTimezone": "28800", + "arriveTimezone": "28800" + } + ], + "success": true +} ``` -出参 `Result>` / `Result>`,字段:`flightNo/trainNo / airline / departAirport / arriveAirport / scheduledDepartTime / scheduledArriveTime / flightStatus / remark`。 +### 火车查询(4 个) + +| 路径 | 入参 | 场景 | +|---|---|---| +| `GET /mp/transport/train` | `trainNo`(如 `G1`)、`date` | 按车次号查,返回含 `stops` 全部经停站 | +| `GET /mp/transport/train/by-train-no-stations` | `trainNo`、`dep`、`arr`(车站中文名)、`date` | 按车次 + 出发站 + 到达站,比按车次多返回 `departStatus`/`arriveStatus`,**不返回 `stops`** | +| `GET /mp/transport/train/by-station` | `dep`、`arr`(车站中文名)、`date` | 按出发站 + 到达站,返回经过该区间的所有车次 | +| `GET /mp/transport/train/by-city` | `depCity`、`arrCity`(城市中文名,如 `北京`)、`date` | 按出发城市 + 到达城市(含所有车站) | + +**出参**:`Result>` + +| 字段 | 类型 | 说明 | +|---|---|---| +| trainNo | String | 车次,如 `G1` | +| departStation | String | 出发车站,如 `北京南` | +| arriveStation | String | 到达车站,如 `上海虹桥` | +| shutdown | String | 是否停运:`0`=否,`1`=是 | +| planDepartTime | String | 计划出发时间 | +| planArriveTime | String | 计划到达时间 | +| estimatedDepartTime | String | 预计出发时间(仅 `by-train-no-stations` 返回) | +| estimatedArriveTime | String | 预计到达时间(仅 `by-train-no-stations` 返回) | +| actualDepartTime | String | 实际出发时间(仅 `by-train-no-stations` 返回) | +| actualArriveTime | String | 实际到达时间(仅 `by-train-no-stations` 返回) | +| departStatus | String | 出发状态:`计划`/`正点`/`晚点`/`出发`(仅 `by-train-no-stations` 返回) | +| arriveStatus | String | 到达状态:`计划`/`正点`/`晚点`/`到达`(仅 `by-train-no-stations` 返回) | +| duration | Integer | 运行时长(分钟) | +| stops | `List` | 经停站列表(仅按车次号 `/mp/transport/train` 返回) | + +**`MpTrainStopVO`**: + +| 字段 | 类型 | 说明 | +|---|---|---| +| stationName | String | 车站名称,如 `沧州西` | +| arriveTime | String | 到站时间 | +| departTime | String | 发车时间 | + +**响应示例**(按车次号): + +```json +{ + "code": 200, + "message": "成功", + "data": [ + { + "trainNo": "G1", + "departStation": "北京南", + "arriveStation": "上海虹桥", + "shutdown": "0", + "planDepartTime": "2026-07-10 06:30", + "planArriveTime": "2026-07-10 11:24", + "duration": 294, + "stops": [ + {"stationName": "北京南", "arriveTime": null, "departTime": "2026-07-10 06:30"}, + {"stationName": "沧州西", "arriveTime": "2026-07-10 07:18", "departTime": "2026-07-10 07:20"}, + {"stationName": "上海虹桥", "arriveTime": "2026-07-10 11:24", "departTime": null} + ] + } + ], + "success": true +} +``` + +### 边界 + +- 查不到数据(航班号无效/停运):返回 `data: []` +- 非常准上游异常/超时:返回 500,`message` 含上游错误码 +- 日期格式:`yyyy-MM-dd`,校验不通过返回 500 `日期格式错误,应为yyyy-MM-dd` +- 所有三字码/城市码/车站名不区分大小写(三字码内部自动 `toUpperCase`) ---