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 |

双数据源绑定机制见 [双数据源说明](datasource.md)。

---

## 航班季度计划 — `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`。