Files

T

windyboyandCursor c63d6d4dce docs(acm2-75): 重排 Q 序号并补齐 Redis 投影与查询侧边界

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-09-17 13:06:59 +08:00

14 KiB

Raw Permalink Blame History

航班及相关接口说明

本文整理 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（或昨天）做 SODT range。
若再传 startSODT / endSODT，再叠一条 SODT range（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 后重新生成。

14 KiB Raw Permalink Blame History Unescape Escape