changelog(mp): 修订到达信息辅助接口字段表(非常准航班/火车)

- 补全 /mp/transport/flight 3 个查询接口(by-airport/by-city)
- 补全 /mp/transport/train 4 个查询接口(by-station/by-city/by-train-no-stations)
- 修正字段名:scheduledDepartTime/flightStatus → planDepartTime/status
- 按 MpFlightInfoVO / MpTrainInfoVO 实际字段列完整(22+14 个)
- 标注哪些字段仅在特定查询下返回(stops / departStatus)
- 补边界行为(空结果/上游异常/日期校验)

changelogs/2026-04/2026-04-21_mp-order-arrival.md

@@ -252,14 +252,151 @@ DELETE /mp/order/{orderId}/arrival/plan/{planId}
 
 ---
 
-## 辅助接口(填写表单时用,来自同一批交付)
+## 辅助接口 · 航班/火车动态查询(填写表单时用,来自同一批交付)
 
-```
+数据源:飞常准官方 API,resource-service 侧做 Redis 缓存后透传。返回为**列表**(同航班号可能有共享航班、同车次日间可能多班次)。
-GET /mp/transport/flight?flightNo=CZ6255&date=2026-07-10    按航班号查航班动态
+
-GET /mp/transport/train?trainNo=G71&date=2026-07-10         按车次号查火车
+### 航班查询(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<List<MpFlightInfoVO>>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| 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<List<MpFlightInfoVO>>` / `Result<List<MpTrainInfoVO>>`,字段:`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<List<MpTrainInfoVO>>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| 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<MpTrainStopVO>` | 经停站列表(仅按车次号 `/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`)
 
 ---