admin-api/docs/flight-apis.md

航班及相关接口说明

本文覆盖 README 第 5 节中与航班相关的业务接口和码表接口：数据源（哪侧库 / ES）、请求参数、返回字段与码表。统一响应包装 ResponseDto（err_code / err_msg / data）见 README 第 5 节，不再重复。

数据源总览

接口	数据源	说明
GET /schedule/flightSchdSeasons	Oracle（Secondary）	DAO domain.secondary.dao.basicdata.FimsFlightschdSeasonDao
GET /schedule/flightSchdSeason/years	Oracle（Secondary）	同上
GET /basicdata/sysFlightStatus 等 4 个航班码表	Oracle（Secondary）	DAO 均在 domain.secondary.dao.basicdata
POST /hitFlightData/list	Elasticsearch	索引 flight_hts（type _doc），非 JPA
POST /fltrs/toExcel	不查库	前端把要导出的列与数据 POST 过来，服务端只负责生成 Excel

双数据源绑定机制见 双数据源说明。

---

航班季度计划 — schedule/FlightSchdSeasonController

GET /schedule/flightSchdSeasons

查询参数（query，均可选）：

参数	格式	说明
startDate	年份字符串，如 2018	按该自然年过滤：{year}-01-01 00:00:00 ~ {year}-12-31 23:59:59 区间内 startDate 命中的记录。不传则返回全量。注意 Swagger 上的 example 是完整日期，实际按年份使用

返回 data：List<FimsFlightschdSeasonDto>（季度计划航班记录，全量无分页）：

字段	说明
seasonflightId	季度计划航班 ID
aircraftTypeCode	机型代码
airlineId	航空公司 ID
subAirlineId	二级承运航空公司 ID
arriOrDept	到达/出发标志，A-到达、D-出发
arrivalTime / departureTime	到达 / 出发时间，hhmm
startAirport / endAirport	航线起点 / 终点机场（如 CAN、CTU）
startDate / endDate	季度计划生效起止日期
flightNumber	航班号（如 3U8692）
flightTask	航班任务：S正班、N包机、E急救、B专机、G通用、J加班、M军用、Q补班、X其他、A计划外
flightTypeCode	航班类别：P客机、F货机、B专机、O公务机、M军机、X其他
flyingDistance	飞行距离（千米）
flyingTime	飞行时间（分钟）
internationalCode	航班国际代码
operationDays	运营日（周一至周日），1234567，非运营日该位为 -，如周三、五停：12-4-67
routeType	航线类别：I国际、D国内、M混合
seasonName	季度名称（如 2012XIAQIU）
seasonRecId	航班季度定义表记录 ID
remarks	备注说明
fimsMidairportsSeasons	航班经停站列表（嵌套 FimsMidairportsSeason 集合）

GET /schedule/flightSchdSeason/years

无参数。返回季度计划表中出现过的年份集合 Set<String>（供前端做年份下拉）。

---

历史航班检索 — history/HistoryFlightDataController

POST /hitFlightData/list

请求体（JSON，HistoryFilghtConditionDto，字段均可选）：

字段	格式	说明
MVIN	A / D	A-到达、D-出发；不传则到离港都返回
startSODT	yyyy-MM-dd HH:mm	计划时间下界
endSODT	yyyy-MM-dd HH:mm	计划时间上界
hstFLightTime	yyyy-MM-dd	要查询的历史日期；不传默认查昨天（按服务器当前时间前一天）

查询行为：

1. ES 索引 flight_hts，时间字段 SODT 存储为 ddMMMyyHHmm 英文格式（如 01Jan181200），入参由服务端转换。
2. 先把范围限定到某一天（hstFLightTime 或昨天全天），startSODT/endSODT 在此基础上进一步收窄（两者可只传其一）。
3. MVIN 非空时按 term 精确过滤。
4. 按 SODT 升序排序；单次最多返回 elasticsearch.maxSize 条（各环境配置均为 10000）。
5. 只返回非共享航班：MAID（代码共享主航班 AODB ID）为空的记录才进结果。

返回 data：List<SCHD.FLTR>，字段名即 ES 索引字段名（AODB SCHD 报文定义，JAXB 生成）：

字段	类型	说明
FLID	BigInteger	航班 id
ALCD	String	航空公司代码
ALSC	String	航空公司子公司代码
FLNO	String	航班号
MVIN	String	运行标识，A-到达、D-离港
SODT	String	计划日期/时间（到港 STA / 离港 STD），ddMMMyyHHmm
FLTY	String	航班类型（客机、货机、军用、VIP 等）
FLIN	String	航班标识
ROUT	List	航线（嵌套 ROUTEDAILY）
ACFT	String	机型
RENO / LRENO	String	注册号/尾号（LRENO 为上一次的值）
TAOP	String	承运人
TAFL	String	承运航班号
TAID	BigInteger	后接飞航班唯一的 AODB ID
TRML	String	航站楼
MAXP	BigInteger	最大载客数
CSOP	String	共享航班主航班承运人代码
CSFT	String	共享航班主航班号
MAID	BigInteger	代码共享主航班 AODB ID（本接口结果中恒为空）
ESTT / ACTT	String	预计 / 实际时间
CHDT	List	行李传送带数据（CHUTEDATA）
GTDT	List	登机门数据（GATEDATA）
STND	String	当前停机位
PSDT	List	计划机位数据（STANDDATA）
LPSDT	String	上次机位，逗号分隔
CKDT	List	值机柜台数据（DESKDATA）
PHAG	BigInteger	旅客处理代理
CNCL	String	取消日期时间
DELY	List	延误信息数据（DELAYDATA）
REMC	String	文本备注
CLDT	List	行李转盘数据（BELTDATA）
BOTM	String	离港登机开始时间
LACL	String	离港最后通知时间（last call）
FINT	String	最终时间
CHOT	List	轮挡时间数据（CHOCKSDATA）
APPT	String	批准离港时间
EGSR / EGST	String	离港引擎发动请求 / 发动时间
FHAG / MHAG	BigInteger	机坪（外场）/ 维护处理代理
VIPP / VIPR	BigInteger	VIP 旅客数 / VIP 等级标志
FDIV	Object	转场数据（DIVERSIONDATA）
FRET	Object	航班返航原因（RETURNDATA）
ABTM	List	登机桥时间数据（BRIDGEDATA）
ABDG	String	登机桥数据，逗号分隔
FLAB	Object	着陆中止原因（ABORTDATA）
SRVT	List	服务数据（SERVICEDATA）
VIPF	List	VIP 数据（VIPDATA）
LBNO / LBWT	BigInteger / BigDecimal	离港本地值机行李件数 / 总重量
PAXC	BigInteger	旅客总数
ERUT	List	完整航线细节（ROUTEDAILY，与 ROUT 的区别在于是否含经停展开）
EXSC / EXSR	String	航班外部状态代码 / 备注
FTSS	String	航班状态（参照码表）
PEDT / NEAT / NAAT	String	AODB 报文原始字段（源码无注释）
PADT	String	前站实际起飞时间
ABN	List	异常状态信息列表（ABNDATA：DLY、RTN、CAN、ALT）
MAFL	List	共享航班数据信息（MAFLDATA）

嵌套子结构（ROUTEDAILY、GATEDATA、DESKDATA 等）均为 AODB SCHD 报文的 JAXB 定义，字段与报文一一对应，需要时直接看 entity/msg/SCHD.java 内部类。

---

航班动态导出 — fltrs/FltrController

POST /fltrs/toExcel

服务端不查任何库：前端把已经查好、筛选好的数据 POST 过来，服务端按给定列序生成 xlsx 并以附件流返回（文件名前缀 航班动态）。

请求体（ExportToExcelDto）：

字段	类型	说明
columns	List<ExcelHeaderDto>	要导出的列；每列 { key: 字段key, name: 表头显示名 }
data	List<Map>	要导出的数据行；每行是 key → 值 的 Map，key 与 columns[].key 对应，缺失或 null 的单元格输出空字符串

正常返回 Excel 文件内容（Content-Type 由 Excel 工具类设置）；生成失败抛 RuntimeException → HTTP 500 + SYSTEM_INNER_ERROR。

---

航班相关码表 — controller/basicdata（Oracle，全量返回无分页）

端点	用途	主要返回字段
GET /basicdata/sysFlightStatus	航班外部状态代码	sttc 状态代码；abns 英文描述；stdc 中文描述；sttd 是否异常状态（Y/N）
GET /basicdata/sysFlightTypes	航班类型代码	flightTypeCode 类型代码；flightTypeCaaCode CAA 代码；flightTypeName/flightTypeNameCn 英文/中文描述；cTag 是否商务航班；vipTag 是否 VIP 航班；operate 操作标识（1 使用、0 删除）
GET /basicdata/sysFlightAgents	航班代理单位	flightAgentId 代理 ID；flightAgentName 中文名称；oGId 代理机构标识
GET /basicdata/flmsFlightStatusDefinition	航班状态/延误代码定义	flifhtStatusDefRecId 记录 ID；flightStatus 具体状态；flightStatusType 状态类别（null 正常、DELY 延误、CNCL 取消、FDIV 备降、MERG 合并、GRTN 地返、OTHR 其他）；flightStatusDesc 状态描述；enableFlag 记录可用标志（Enabled/Disabled）；dcod/dcdn 延误代码及数字代号；ddes/ddsc 延误描述英文/中文；operate 操作标识

历史航班返回里的 FTSS（航班状态）、EXSC（外部状态代码）取值参照 sysFlightStatus 与 flmsFlightStatusDefinition 码表；FLTY 航班类型参照 sysFlightTypes。