14 KiB
航班及相关接口说明
本文整理 admin-api 中与航班有关的接口：数据从哪来、路径与参数、返回字段、码表含义。
本服务是只读数据层。不生产航班动态，不保存实时航班。实时推送、保障流程、报文收发与解析落库由 AODB / 消息中间件负责。
判定数据源：Controller 注入的 DAO 在 domain.secondary 包 → Oracle；历史航班走 ES；字典走 MySQL。双数据源原理见 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 导出除外）：
{ "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 |
flightTypeCode |
航班类别，见 §5.2 |
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 离港；不传则进出港都查 |
查询逻辑：
- 先按
hstFLightTime（或昨天）做SODTrange。 - 若再传
startSODT/endSODT，再叠一条SODTrange（AND）。 - 时间经
DateUtils.swichTimeToEn_ddMMMyyHHmm转成 ES 存的ddMMMyyHHmm再查。 - 按
SODT升序，条数上限elasticsearch.maxSize（各环境 10000）。 - 映射为
SCHD.FLTR，丢掉共享航班（MAID != null）。
请求示例：
{
"hstFLightTime": "2026-09-16",
"MVIN": "A",
"startSODT": "2026-09-16 08:00",
"endSODT": "2026-09-16 12:00"
}
body 为 SCHD.FLTR[]，字段见 §6。
查不到数据时核对：flight_hts 别名是否存在、当天是否已同步、SODT 是否为 ddMMMyyHHmm。索引与 mapping 需手工创建，脚本在 src/main/resources/es/。
3.2 航班动态导出 Excel — 前端回传
POST /fltrs/toExcel
不查库。前端把当前页列定义和行数据回传，服务端按 columns 顺序用 Apache POI 拼 xlsx，直接写 HttpServletResponse。成功是文件流，失败才是 JSON。无条数上限，超大导出可能内存与超时。Controller：fltrs/FltrController。
{
"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 |
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 后重新生成。