windy/msgexchange-v2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
c63d6d4dcec144d32eb4c686561688ca928d362f
msgexchange-v2/docs/legacy/flight-apis.md
T

407 lines
14 KiB
Markdown
Raw Normal View History

docs(acm2-75): 重排 Q 序号并补齐 Redis 投影与查询侧边界
2026-09-17 13:06:59 +08:00
# 航班及相关接口说明
本文整理 admin-api 中与航班有关的接口：数据从哪来、路径与参数、返回字段、码表含义。
本服务是**只读数据层**。不生产航班动态，不保存实时航班。实时推送、保障流程、报文收发与解析落库由 AODB / 消息中间件负责。
判定数据源：Controller 注入的 DAO 在 `domain.secondary` 包 → **Oracle**；历史航班走 ES；字典走 MySQL。双数据源原理见 [datasource.md](datasource.md)。
---
## 1. 数据从哪来
| 能力 | 接口 | 数据源 | 不可用时 |
|---|---|---|---|
| 航班季度计划 | `/schedule/flightSchdSeasons`、`/schedule/flightSchdSeason/years` | **Oracle** `FIMS_FLIGHTSCHD_SEASON` / `FIMS_MIDAIRPORTS_SEASON` | 500 |
| 航班基础数据 | `/basicdata/sysFlightStatus` 等 4 个 | **Oracle** | 500 |
| 配套基础数据 | `/basicdata/sysAirlines` 等 | **Oracle** | 500 |
| 历史航班检索 | `POST /hitFlightData/list` | Elasticsearch 别名 `flight_hts` | 500 |
| 航班动态导出 | `POST /fltrs/toExcel` | 前端回传，不查库 | 返回 JSON 错误 |
| 航班相关字典 | `GET /dictionary/datadicItems/{groupCode}` | MySQL | 500 |
这些接口都不读 `user` 头，可匿名访问，必须经网关暴露。
统一响应（Excel 导出除外）：
```json
{ "is_success": true, "err_code": 1, "err_msg": "成功", "body": {} }
```
成功 `err_code=1`。联调：`http://localhost:8080/doc.html`，标签为「历史航班数据」「航班季度计划」「航班动态」「基础数据」。
---
## 2. 从 Oracle 获取的接口
Secondary 数据源，当前业务只读。Oracle 不可用时本节全部 500。
### 2.1 航班季度计划
Controller：`schedule/FlightSchdSeasonController`。
#### `GET /schedule/flightSchdSeasons`
按可选年份查询季度计划，经停站一并返回。
| 查询参数 | 格式 | 说明 |
|---|---|---|
| `startDate` | 年份，如 `2018` | 过滤 `START_DATE` 落在该年 `01-01 00:00:00 ~ 12-31 23:59:59`。不传则全量。 |
`body` 为 `FimsFlightschdSeasonDto[]`：
| 字段 | 含义 |
|---|---|
| `seasonflightId` | 季度计划航班 ID |
| `flightNumber` | 航班号，如 `3U8692` |
| `airlineId` / `subAirlineId` | 承运 / 二级承运航司 ID |
| `aircraftTypeCode` | 机型代码 |
| `arriOrDept` | `A` 到达 / `D` 出发 |
| `startAirport` / `endAirport` | 航线起点 / 终点（IATA） |
| `arrivalTime` / `departureTime` | `hhmm` |
| `startDate` / `endDate` | 计划有效起止日期 |
| `operationDays` | 运营日 `1234567`；非运营日用 `-`，如周三、五休息为 `12-4-67` |
| `flightTask` | 航班任务，见 [§5.1](#51-航班任务-flighttask) |
| `flightTypeCode` | 航班类别，见 [§5.2](#52-航班类别-flighttypecode) |
| `routeType` | `I` 国际 / `D` 国内 / `M` 混合 |
| `flyingDistance` / `flyingTime` | 距离（千米）/ 时间（分钟） |
| `internationalCode` | 航班国际代码 |
| `seasonName` | 季度名称，如 `2012XIAQIU` |
| `seasonRecId` | 季度定义表记录 ID |
| `remarks` | 备注 |
| `fimsMidairportsSeasons` | 经停站列表，按 `orderno` 升序 |
经停站 `FimsMidairportsSeason`：
| 字段 | 含义 |
|---|---|
| `midairportsRecId` | 经停记录 ID |
| `seasonflightId` | 所属季度计划航班 ID |
| `airportId` | 经停机场 ID |
| `arrivalTime` / `departureTime` | 本站到离 `hhmm` |
| `orderno` | 航段顺序 |
表：`FIMS_FLIGHTSCHD_SEASON`（主）+ `FIMS_MIDAIRPORTS_SEASON`（`SEASONFLIGHT_ID` 关联，`FetchType.EAGER`）。
#### `GET /schedule/flightSchdSeason/years`
返回季度计划中出现过的年份集合，原生 SQL 按 `START_DATE` 的年份降序。
`body` 示例：`["2026", "2025", "2024"]`。
---
### 2.2 航班基础数据
全部 `GET`、全量、无分页。Controller 直接注入 DAO，无 Service 层。
#### `GET /basicdata/sysFlightStatus`
航班外部状态代码，对应历史航班 `EXSC` / `FTSS`。表 `SYS_FLIGHT_STATUS`。
| 字段 | 含义 |
|---|---|
| `sttc` | 状态代码，如 `EARR` |
| `abns` | 英文描述，如 `Estimated Arrive` |
| `stdc` | 中文描述，如 `预计到达` |
| `sttd` | 是否异常：`Y` / `N` |
#### `GET /basicdata/sysFlightTypes`
航班类型代码。表 `SYS_FLIGHT_TYPE`。
| 字段 | 含义 |
|---|---|
| `flightTypeCode` | 类型代码 |
| `flightTypeCaaCode` | CAA 代码 |
| `flightTypeName` / `flightTypeNameCn` | 描述 / 中文描述 |
| `cTag` | 是否商务航班 |
| `vipTag` | 是否 VIP 航班 |
| `operate` | `1` 使用 / `0` 删除 |
#### `GET /basicdata/sysFlightAgents`
航班代理单位，对应历史航班 `FHAG` / `MHAG`。表 `SYS_FLIGHTAGENT`。
| 字段 | 含义 |
|---|---|
| `flightAgentId` | 代理 ID |
| `flightAgentName` | 中文名称 |
| `oGId` | 机构标识 |
#### `GET /basicdata/flmsFlightStatusDefinition`
延误 / 异常状态定义，对应历史航班 `DELY.CODE`。表 `FIMS_FLIGHTSTATUS_DEFINITION`。
| 字段 | 含义 |
|---|---|
| `flifhtStatusDefRecId` | 记录 ID（字段名沿用历史拼写） |
| `flightStatus` | 明细状态，如气象延误、旅客延误 |
| `flightStatusType` | 类别，见下表 |
| `flightStatusDesc` | 描述 |
| `dcod` / `dcdn` | 延误代码 / 数字代号 |
| `ddes` / `ddsc` | 英文 / 中文延误描述 |
| `enableFlag` | `Enabled` / `Disabled` |
| `operate` | `1` 使用 / `0` 删除 |
`flightStatusType`：
| 值 | 含义 |
|---|---|
| `null` | 正常 |
| `DELY` | 延误 |
| `CNCL` | 取消 |
| `FDIV` | 备降 |
| `MERG` | 合并 |
| `GRTN` | 地返 |
| `OTHR` | 其他 |
---
### 2.3 航班配套基础数据（同样 Oracle）
历史航班 / 动态表上的航司、机场、机型、机位、登机口等，靠这些接口解码。全部 `GET`、全量、无分页。
| 接口 | Oracle 表 | 说明 |
|---|---|---|
| `/basicdata/sysAirlines` | `SYS_AIRLINE` | 航空公司 |
| `/basicdata/sysAirlineGroup` | `SYS_AIRLINEGROUP` | 航空集团 |
| `/basicdata/sysAirports` | `SYS_AIRPORT` | 机场 |
| `/basicdata/sysAirportGroups` | `SYS_AIRPORTGROUP` | 机场集团 |
| `/basicdata/sysCitys` | `SYS_CITY` | 城市 |
| `/basicdata/sysCountry` | `SYS_COUNTRY` | 国家 |
| `/basicdata/ormsTerminals` | `ORMS_TERMINAL` | 航站楼 |
| `/basicdata/ormsTerminalareas` | `ORMS_TERMINALAREA` | 航站楼区域 |
| `/basicdata/ormsStands` | `ORMS_STAND` | 机位 |
| `/basicdata/ormsStandTypes` | `ORMS_STANDTYPE` | 机位类型 |
| `/basicdata/ormsStands/{standCode}/airbridgeCode` | `ORMS_STAND_AIRBRIDGE` | 指定机位的廊桥号 |
| `/basicdata/ormsGates` | `ORMS_GATE` | 登机口 |
| `/basicdata/ormsChuts` | `ORMS_CHUT` | 行李滑槽 |
| `/basicdata/ormsCheckindesks` | `ORMS_CHECKINDESK` | 值机柜台 |
| `/basicdata/checkinGroups` | `ORMS_CHECKIN_GROUP` | 值机岛 |
| `/basicdata/ormsCarousels` | `ORMS_CAROUSEL` | 行李转盘 |
| `/basicdata/sysAircrafttypes` | `SYS_AIRCRAFTTYPE` | 机型 |
| `/basicdata/sysAircrafts` | `SYS_AIRCRAFT` | 机号 |
| `/basicdata/sysAircrafttypesGroup` | `SYS_AIRCRAFTTYPEGROUP` | 机型分组 |
---
## 3. 不是 Oracle 的航班接口
### 3.1 历史航班检索 — Elasticsearch
`POST /hitFlightData/list`
路径是 `hit` 不是 `hist`。查 ES 别名 `flight_hts`（指向索引 `flight_hts2`），不查数据库。Controller：`history/HistoryFlightDataController`。
请求体 `HistoryFilghtConditionDto`：
| 字段 | 格式 | 说明 |
|---|---|---|
| `hstFLightTime` | `yyyy-mm-dd` | 查哪一天；**不传则默认昨天** `00:00:00 ~ 23:59:59` |
| `startSODT` | `yyyy-mm-dd HH:mm` | 计划时间下界，可单独传 |
| `endSODT` | `yyyy-mm-dd HH:mm` | 计划时间上界，可单独传 |
| `MVIN` | `A` / `D` | `A` 到达，`D` 离港；不传则进出港都查 |
查询逻辑：
1. 先按 `hstFLightTime`（或昨天）做 `SODT` range。
2. 若再传 `startSODT` / `endSODT`，再叠一条 `SODT` range（AND）。
3. 时间经 `DateUtils.swichTimeToEn_ddMMMyyHHmm` 转成 ES 存的 `ddMMMyyHHmm` 再查。
4. 按 `SODT` 升序，条数上限 `elasticsearch.maxSize`（各环境 10000）。
5. 映射为 `SCHD.FLTR`，**丢掉共享航班**（`MAID != null`）。
请求示例：
```json
{
"hstFLightTime": "2026-09-16",
"MVIN": "A",
"startSODT": "2026-09-16 08:00",
"endSODT": "2026-09-16 12:00"
}
```
`body` 为 `SCHD.FLTR[]`，字段见 [§6](#6-历史航班-schdfltr-字段)。
查不到数据时核对：`flight_hts` 别名是否存在、当天是否已同步、`SODT` 是否为 `ddMMMyyHHmm`。索引与 mapping 需手工创建，脚本在 `src/main/resources/es/`。
### 3.2 航班动态导出 Excel — 前端回传
`POST /fltrs/toExcel`
不查库。前端把当前页列定义和行数据回传，服务端按 `columns` 顺序用 Apache POI 拼 xlsx，直接写 `HttpServletResponse`。成功是文件流，失败才是 JSON。无条数上限，超大导出可能内存与超时。Controller：`fltrs/FltrController`。
```json
{
"columns": [
{ "key": "FLNO", "name": "航班号" },
{ "key": "SODT", "name": "计划到达／出发" }
],
"data": [
{ "FLNO": "3U8692", "SODT": "16SEP260820" }
]
}
```
`key` 对应行对象字段名，`name` 是表头。工作表名：`航班动态`。
### 3.3 字典 — MySQL
`GET /dictionary/datadicItems/{groupCode}`
| groupCode | 用途 | 初始化情况 |
|---|---|---|
| `FLIGHT_TASK` | 季度计划 `flightTask` | 分组有，**无初始化项** |
| `FLIGHT_TYPE` | 季度计划 `flightTypeCode` | 分组有，**无初始化项** |
| `ROUTE_TYPE` | 航线类别 | 仅 `D` 国内、`I` 国际（没有 `M`） |
`FLIGHT_TASK` / `FLIGHT_TYPE` 的码值以 Oracle 字段注释为准，见第 5 节。`ROUTE_TYPE` 在季度计划里还有 `M` 混合，字典初始化未包含。
返回字段：`dataitemCode`、`dataitemName`、`dataitemDesc`。
---
## 4. 接口总表
| 方法 | 路径 | 数据源 | 说明 |
|---|---|---|---|
| `GET` | `/schedule/flightSchdSeasons` | Oracle | 季度计划列表 |
| `GET` | `/schedule/flightSchdSeason/years` | Oracle | 季度计划年份 |
| `GET` | `/basicdata/sysFlightStatus` | Oracle | 外部状态码 |
| `GET` | `/basicdata/sysFlightTypes` | Oracle | 航班类型 |
| `GET` | `/basicdata/sysFlightAgents` | Oracle | 代理单位 |
| `GET` | `/basicdata/flmsFlightStatusDefinition` | Oracle | 延误/异常码 |
| `GET` | `/basicdata/sysAirlines` 等 | Oracle | 配套基础数据，见 [§2.3](#23-航班配套基础数据同样-oracle) |
| `POST` | `/hitFlightData/list` | Elasticsearch | 历史航班 |
| `POST` | `/fltrs/toExcel` | 无 | 导出 Excel |
| `GET` | `/dictionary/datadicItems/{groupCode}` | MySQL | 字典 |
---
## 5. 码表
### 5.1 航班任务 `flightTask`
来源：`FIMS_FLIGHTSCHD_SEASON.FLIGHT_TASK` 字段注释。
| 码 | 含义 |
|---|---|
| `S` | 正班 |
| `N` | 包机 |
| `E` | 急救 |
| `B` | 专机 |
| `G` | 通用 |
| `J` | 加班 |
| `M` | 军用 |
| `Q` | 补班 |
| `X` | 其他 |
| `A` | 计划外 |
### 5.2 航班类别 `flightTypeCode`
来源：`FIMS_FLIGHTSCHD_SEASON.FLIGHT_TYPE_CODE` 字段注释。
| 码 | 含义 |
|---|---|
| `P` | 客机 |
| `F` | 货机 |
| `B` | 专机 |
| `O` | 公务机 |
| `M` | 军机 |
| `X` | 其他 |
### 5.3 进出港 / 航线类别
| 字段 | 码 | 含义 |
|---|---|---|
| `arriOrDept` / `MVIN` | `A` | 到达 |
| `arriOrDept` / `MVIN` | `D` | 离港 |
| `routeType` / `FLIN` | `D` | 国内 |
| `routeType` / `FLIN` | `I` | 国际 |
| `routeType` / `FLIN` | `M` | 混合 |
| `FLIN` | `R` | 地区（仅历史航班） |
---
## 6. 历史航班 `SCHD.FLTR` 字段
完整释义：`src/main/resources/es/v0.0.1_20181213_hisPlaneDataDesc.json`。Java 模型：`entity/msg/SCHD.FLTR`（JAXB 生成，勿手改）。
### 身份与计划
| 码 | 含义 | 码 | 含义 |
|---|---|---|---|
| `FLID` | 航班 ID | `FLNO` | 航班号 |
| `ALCD` | 航司代码 | `ALSC` | 子公司代码 |
| `MVIN` | `A` 到达 / `D` 离港 | `SODT` | 计划时间 |
| `FLTY` | 航班类型 | `FLIN` | 航线类别 |
| `ACFT` | 机型 | `RENO` | 机号 / 尾号 |
| `TRML` | 航站楼 | `STND` | 当前机位 |
| `MAXP` | 最大载客数 | `PAXC` | 旅客总数 |
### 时间与状态
| 码 | 含义 | 码 | 含义 |
|---|---|---|---|
| `ESTT` | 预计时间 | `ACTT` | 实际时间 |
| `PADT` | 前站起飞 | `NAAT` | 前站降落 |
| `FTSS` | 运营状态 | `EXSC` / `EXSR` | 外部状态码 / 备注 |
| `CNCL` | 取消时间 | `BOTM` | 登机开始 |
| `LACL` | 最后通知 | `FINT` | 最终时间 |
| `APPT` | 批准离港时间 | `EGSR` / `EGST` | 引擎发动请求 / 时间 |
### 共享 / 衔接
| 码 | 含义 |
|---|---|
| `CSOP` / `CSFT` / `MAID` | 共享主航班承运人 / 航班号 / AODB ID（`MAID` 非空会被历史查询丢掉） |
| `TAOP` / `TAFL` / `TAID` | 后接飞承运人 / 航班号 / ID |
### 嵌套资源（数组）
| 码 | 内容 |
|---|---|
| `ROUT` / `ERUT` | 航线：`APCD` 机场、`SCAT`/`SCDT` 计划到离、`RTNO` 顺序 |
| `GTDT` | 登机门：`GATE`、计划/实际开关门 |
| `CKDT` | 值机柜台：`CHKC`、计划/实际开关 |
| `PSDT` | 计划机位：`PSST`、占用起止 |
| `CHDT` | 离港行李滑槽 |
| `CLDT` | 到港行李转盘：`BELT`、首末件行李 |
| `CHOT` | 轮挡：`CHID`=`OFF` 上 / `ON` 下 |
| `ABTM` | 靠桥/撤桥：`ABOP`=`A` 链接 / `B` 断开 |
| `DELY` | 延误：`CODE`、开始时间、时长 |
| `FDIV` / `FRET` | 转场/备降原因 |
| `VIPF` | VIP 明细 |
| `SRVT` | 服务明细 |
### 前端派生列
UI 默认列（`adminapi_uisettings_default.userSettingCol`）里还有 ES 原文没有的字段，由前端从嵌套结构拆出：
| 码 | 含义 |
|---|---|
| `FLDT` | 航班日期 |
| `ARSF` | 到港共享航班 |
| `DESF` | 离港共享航班 |
| `AOTM_A` / `AOTM_D` | 靠桥 / 撤桥时间 |
| `CHTM_ON` / `CHTM_OFF` | 上轮挡 / 下轮挡 |
---
## 7. 职责边界与注意点
| 本服务做 | 本服务不做 |
|---|---|
| 季度计划只读（Oracle） | 日计划实时推送（告警码 `SCHD-DNLD` 由其它系统发） |
| 历史航班检索（ES） | 保障流程、报文收发落库 |
| 前端已有数据导出 Excel | 写航班、改机位/登机口 |
注意：
- 基础数据无分页，数据量增长后需改造。
- 历史检索路径拼写为 `/hitFlightData/list`。
- `startSODT`/`endSODT` 与 `hstFLightTime` 是 AND，不是替换。
- 共享航班（`MAID != null`）在历史查询中被过滤。
- Excel 导出无服务端上限。
- `entity/msg` 约 130 个类由 XSD 经 JAXB 生成，报文结构变更须改 Schema 后重新生成。
Reference in New Issue Copy Permalink