msgexchange-v2/docs/flight-state-semantics.md

运营航班字段语义矩阵（v2 权威口径）

状态：2026-09-08 实现核对；以下明确区分当前行为与待验收语义。 依据：航班状态设计、SIS 规范、FlightStateEngine 实现。 本文是字段语义入口；历史决策不覆盖本文。已发现的不一致和修正计划见 核查报告。

1. 命令模型

当前 Handler 返回字段集，FlightStateEngine 再解析为命令；仓储仍会解析异常/文本 JSON。显式命令尚未贯通所有边界：

命令	标量	集合
Unchanged（未出现）	不修改	不修改
Set(value)	覆盖	—
Clear	删除该键，物理列置 NULL	删除全部明细行
Replace(list)	—	同事务 DELETE + 批量 INSERT 整集合替换
Apply(item, sourceSeq)	—	引擎内预留，按首个 SOURCE_SEQ 匹配更新，否则追加；无生产调用方，尚非已确认业务协议。

• 序号属性为 "0" 的条目是协议显式清除标记：仅当集合内全部条目均为 0 时翻译为 Clear；与常规条目混排属非法结构，fail fast 拒绝。
• 空数组 [] = Replace(空集)：明细行清空（区别于 Unchanged 的键缺失）。
• 验收目标：非法 JSON、未知形状、超容输入不得截断后成功。当前 parseCollection 未校验数组元素必须是对象，仓储会忽略未知属性；该目标尚未完成。

2. 16 类结构映射

集合键	存储载体	序号属性	出现语义	显式清除	Apply
GTDT 登机口	flight_gate	GTNO	Replace	GTNO=0 全清	支持（GTNO 定位）
CKDT 值机柜台	flight_checkin	CKNO	Replace	CKNO=0 全清	支持；同 CHKC 多舱位分配按 CKNO 区分，不按资源号去重
CLDT 行李转盘	flight_belt	CLNO	Replace	CLNO=0 全清	支持
PSDT 计划机位	flight_stand_plan	PSNO	Replace	PSNO=0 全清	支持
CHDT 行李滑槽	flight_chute	CHNO	Replace	CHNO=0 全清	支持
DELY 延误	flight_delay	无（仓储残留 DLNO 映射待清理）	Replace（仅保存本次集合，不追加历史）	[] 清空	不支持（协议无定位键）
ABTM 靠撤桥	flight_bridge_op	ASNO	Replace（操作全集）	ASNO=0 全清	支持（ASNO 定位；多次靠/撤桥各占一行）
CHOT 轮挡	flight_chock_op	CSNO	Replace	CSNO=0 全清	支持（CHID=ON/OFF 为业务属性，非序号）
ROUT 计划航路	flight_route_point(route_kind=ROUT)	RTNO	Replace	RTNO=0 全清	支持
ERUT 扩展航路	flight_route_point(route_kind=ERUT)	RTNO	Replace	RTNO=0 全清	支持
FDIV 备降	主表前缀列 FDIV_*	—	Set（对象）	"null"/{}/空串 → Clear	—
FRET 返航	主表前缀列 FRET_*	—	Set	同上	—
FLAB 中止	主表前缀列 FLAB_*	—	Set	同上	—
SRVT 服务	主表 SRVT_TEXT	—	Set	当前字段转换器不将 null/{}/空串转 Clear；显式 ScalarCommand.Clear 可清列	—
VIPF 贵宾	主表 VIPF_TEXT	—	Set	同 SRVT	—
MAFL 共享航班	主表 MAFL_TEXT	—	Set	同 SRVT	无查询需求时维持现有载体

公共明细列：FLID（逻辑归属，当前没有数据库 FK）、ORDINAL（输入顺序，1 起）、SOURCE_SEQ（字符串、不唯一）、RECORD_VERSION、CREATED_AT/UPDATED_AT；当前 PK (FLID, ORDINAL)。路线表还需将 ROUTE_KIND 纳入主键，避免 ROUT/ERUT 冲突。相同资源号不代表同一条分配记录，禁止按资源号去重。表中“支持 Apply”仅指引擎分支，生产只生成 Replace/Clear。

3. 清除的库内与线上表达

• 库内：标量/异常/文本键 Clear → 对应列 NULL；集合键 Clear/Replace(空) → 明细行删除。
• 线上（KAFKA_SCHD）：Clear 会移除键；Replace(空集) 当前仍生成 []，数据库读回却缺键，尚未统一。下游清除契约必须固定黄金样例，再同时修正 nextState、落库读回与 wire；不得宣称已等值。
• 异常对象 Set 在增量 SQL 中只写出现的属性；旧对象被省略的属性可能残留。这与对象替换目标不一致，待回归修正。

4. 快照（DNLD）与增量（FLOP/ADFT）

• DNLD 事务内核：外层标量字段级合并；出现的集合 Replace；集合缺失 = Unchanged。删除走 SCHD_GEN 差集 + deleteDiffByDay（FDAY 域化）。真实 XML parser/生产路由仍未接通，不能视为端到端协议已验收。
• FLOP：字段级合并；Handler 产生的集合键出现即全量替换。
• 重放判定凭 schd_gen.last_message_id（快照）与 identity_key（消息去重）；版本号只是顺序令牌。锁内 CAS 失败一律回滚 FAILED(INFRA)。

5. 时区与空值

• SIS 时间串（DDMONYYHHMM 机场当地时）原值保存；类型化提升按查询需要另行定案（ACM2-29 遗留 3）。
• PG 当前保留字符串空值，集合 JSON null 属性会被解析为空串。Oracle 的空字符串/NULL 等价性还未在目标库验证；显式命令本身不能保证持久化往返保真。