msgexchange-v2/docs/flight-state.md

航班运行数据接入与当前状态管理设计

本模块从共享 MySQL 信箱接收 AODB 报文，在本地库维护航班当前态，再通过 Kafka 发布变化。

未标注内容即规范要求；开放与待定项汇总在 §10。

1. 目标与边界

1. 当前态唯一：AODB 是业务事实来源，本地库是本模块唯一查询源。
2. 严格有序：单活动主泵按信箱 FIFO 处理消息。
3. 原子提交：航班状态、处理结果、待发事件在同一事务提交。
4. 可恢复：信箱回填与 Kafka 投递可独立重试，不重算业务。
5. 完整保存：变长资源用明细表，不用固定槽位截断。

边界：只同步报文、维护当前态，不推导取消、延误、备降等业务状态。PIPELINE_LOCK 只串行化数据库事务，不能代替消息认领、选主与故障切换。

2. 数据来源与语义

来源	作用
SCHD DNLD/RESP	按 FLID upsert 完整航班基准状态，字段完整替换（§5）；不做名单比对或差删
SCHD ADFT	新增或更新单个临时航班（§2.1）
FLOP	更新单个航班运行变化，增量合并，不改运营日
FDEL	终止航班实例，标记删除（§6.2）
历史任务	归档已结束航班并物理清除（§8）

字段缺失两种含义：

• 完整快照：未出现 = AODB 已无该数据，清除本地旧值。
• 增量（FLOP）：未出现 = 本次没改，保留本地值。

2.1 ADFT 语义待确认

ADFT 的字段缺失语义尚需按 SIS 条款及真实报文确认，确认前不得直接沿用 FLOP 的增量合并规则。若 ADFT 含足以确定运营日的 SODT，应据此设置 OPERATION_DAY，不得默认留 NULL。

3. 数据模型

3.1 航班实例身份

• FLID：AODB 分配的实例 ID（Number(1-12)，SIS §3.16.2），全部表的唯一关联键。
• FLNO：展示用航班号，可重复，不参与身份判定。
• OPERATION_DAY：所属运营日，一经确定不可变（§3.5、§5.3）。
• STATE：ACTIVE / DELETED。所有删除先标记；物理清除只发生在历史归档成功之后，归档结果记录在历史存储，不在当前态保留 ARCHIVED 状态。

同一航班号不同运营日 = 不同 FLID。

身份属性变更由 AODB 通过 FDEL 后续接 ADFT 表达。两条消息的 FLID 可能相同，也可能不同，本模块不得预设一定产生新 FLID：

• FLID 相同：按同一标识下的生命周期重激活处理（FDEL 置 DELETED，ADFT 恢复 ACTIVE）；
• FLID 不同：按旧实例终止、新实例建立处理。

本模块不得合并实例，也不得由航班号或日期推断两个 FLID 是同一实例。

3.2 表职责

表	粒度	职责
FLIGHT_SCHD	每 FLID 一行	标量当前态、OPERATION_DAY、STATE、STATE_VERSION、最近消息 ID
8 张资源明细表	每 FLID 多行	登机门、值机柜台、行李转盘、计划机位、滑槽、延误、靠撤桥、轮挡
FLIGHT_ROUTE_POINT	每 FLID 多行	ROUT/ERUT 路线点，ROUTE_KIND 区分
PIPELINE_LOCK	单行	串行化状态写事务
PROC_STATE	每消息一行	处理状态与重试结果；兼作快照重放判定（§5.1）
MSG_EVENT（outbox）	每事件一行	状态、变更、删除通知
REQ_TRACK / COUTMSGS	每请求一行	请求状态与出站
BACKFILL_TODO	每待补偿一行	共享信箱回填任务
SCHD_SNAP_LOG	每快照一行	只追加留痕，不参与决策（§5.5）

明细表共 9 张、承载 10 类集合（ROUT 与 ERUT 共用路线表）；ORDINAL 保留输入顺序，SOURCE_SEQ 只存上游序号。

分层：决策层（FLIGHT_SCHD 与各运行表）承担正确性；留痕层（SCHD_SNAP_LOG）只追加、可重建；证据层（报文归档）冷路径、仅用于重演审计，尚未交付。

3.3 完整当前态

主行 + 全部明细 = 完整当前态。写入前在内存生成完整新状态再落库，明细集合按组先删后插。展示视图是投影，不是权威。

3.4 代码共享与过站

• 主航班与共享航班是独立实例，各有 FLID；共享航班用 CSOP/CSFT 指向主航班，MAFL 存共享列表。
• TAOP/TAFL/TAID 是过站关联，不是代码共享。
• 删除时共享航班 FDEL 先于主航班；按 FLID 各自处理，不做级联推断。

3.5 运营日

OPERATION_DAY 是运行保障日期，不是接收日或落库日。

计算规则：按机场运营日规则，由计划运行时间字段（SODT）与机场时区（Asia/Shanghai）计算；切日边界由业务配置，不得假设等于接收日期或自然日零点。单日请求范围到运营日的映射、多日窗口中每条记录的归日，均按此规则执行。

快照取覆盖日；FLOP 保留当前值；ADFT 或先于快照的 FLOP 暂为 NULL，被快照收录时补齐（ADFT 含 SODT 时直接计算，见 §2.1）。

延误跨日仍是同一 FLID、运营日不变——SIS §3.16 注释 1 明确日计划不含前日延误航班，保留与清理由本模块负责。

4. 更新模型

以 FLID 为唯一边界：

SCHD       → 完整基准（字段替换，upsert；不改变 DELETED 状态）
FLOP/ADFT  → 增量合并
FDEL       → 标记删除（DELETED）
ADFT       → 生命周期重激活（同 FLID）或新实例建立（不同 FLID）
历史任务   → 归档后物理清除（内部清理，不发业务删除事件）

• 每次成功写入推进 STATE_VERSION；状态、事件、处理终态同事务提交。
• 主链路无集合删除；删除入口只有 FDEL 与历史归档，均先标记后清除。
• 普通 SCHD 不承担恢复语义：DELETED 航班被快照收录时保持 DELETED 并记录冲突告警（§5.1）；恢复入口只有 ADFT（§6.3）。

5. SCHD 处理

设消息 M，记录集 R。身份前提：同一 FLID 属于唯一运营日；FLID 不跨日迁移。

主链路入口为 applyScheduleRecords，对单日快照与滚动窗口统一适用；对单日快照不做任何名单层面的处理。

5.1 applyScheduleRecords（同一事务）

1. 锁定 PIPELINE_LOCK。
2. M 在 PROC_STATE 已有成功终态 → 重放，直接记幂等成功。
3. 校验报文完整性（§5.2），任一失败整包不落地。
4. 对每条记录按 §3.5 确定其 OPERATION_DAY。
5. 校验每个 FLID 的既有 OPERATION_DAY（§5.3）。
6. 按完整快照语义 upsert 每个航班（§5.4）；DELETED 航班保持 DELETED，记录冲突告警 SCHD_REVIVE_CONFLICT，不恢复 ACTIVE。
7. 逐航班推进 STATE_VERSION，登记状态事件与处理终态。

任一步失败整体回滚。

5.2 报文完整性

五项校验：RECS 0–9999 且等于实收 FLTR 数；每条记录含合法数字型 FLID；快照内不重复；每条记录的运营日可计算且在报文覆盖范围内。

记录完整与成员完整必须分开：

• 记录完整：某 FLID 的字段是该航班的完整状态 → 允许覆盖字段。48 小时滚动窗口满足此维度。
• 成员完整：报文含某运营日全部 FLID。主链路不使用成员完整性；若将来引入名单对账，需另行设计并单独定案。

5.3 航班归属

主行情况	处理
不存在	创建，OPERATION_DAY 按记录计算，STATE = ACTIVE
NULL	首次确定
与记录计算值相同	按快照更新状态
与记录计算值不同	违反身份约束：不改写、整包拒绝 DEAD(PROTOCOL)、告警 SAME_FLID_ACROSS_OPERATION_DAYS

第四行意味着串日、错发或数据污染：不静默保留，不迁移归属，整包拒绝后交人工确认。

5.4 字段语义

输入	字段缺失含义
DNLD/RESP	AODB 已无该数据 → 清除本地旧值
FLOP	本次没改 → 保留本地值
KAFKA_SCHD	当前态没有该字段 → 消费者删除旧值

标量出现 Set、缺失 Clear；集合出现 Replace、缺失 Replace 空集。清除只覆盖正式映射的字段。

5.5 时序约束与留痕

快照与 FLOP 的覆盖顺序是核心时序问题。 SEQN 重启后不可比、不表达业务新旧，因此不启用陈旧拦截，只承诺按信箱接收顺序形成当前态。“快照比 FLOP 权威”不成立，不得对外承诺。较旧的 SCHD 晚于 FLOP 到达可能把新动态改回旧值——接收序模型的已知代价，靠上游顺序保证或下一次 FLOP 纠正。SEQN 仅用于同会话顺序观测（下降记 SEQN_REGRESSION 并告警）。

事务外追加一条 SCHD_SNAP_LOG：

字段	说明
MSG_ID / RECV_AT	消息 ID、接收时刻（UTC）
SCOPE_START / SCOPE_END	报文覆盖的运营日范围（单日时两者相等）
RECS / UPSERTED / DURATION_MS	规模、写入数、耗时
RESULT	COMMITTED / REPLAY_SKIPPED / ROLLED_BACK
FLAGS	EMPTY / RECS_DROP / SEQN_REGRESSION / DAY_MISMATCH / SCHD_REVIVE_CONFLICT
ARCHIVE_KEY	原文归档引用

规则：RESULT 与 FLAGS 分列（可“成功且告警”）；一行 = 一次尝试，重放也记；留痕不参与决策，写失败只记指标；保留 90 天，按 (SCOPE_END, RECV_AT) 清理。

6. 动态事件与删除

6.1 FLOP

读取完整当前态 → 合并变化 → 保留运营日 → STATE_VERSION 加一 → 同事务登记 KAFKA_MSG、KAFKA_SCHD 与处理结果。

6.2 FDEL

同一事务内：

1. 按 FLID 定位。
2. STATE = ACTIVE：置 DELETED，推进 STATE_VERSION，明细保留，发布删除事件。
3. STATE = DELETED：记幂等成功，不推进 STATE_VERSION，不重复发布删除事件。
4. 不存在：记幂等成功（迟到、重复不报错）。

删除一律标记，不物理清除：FLID 复用未确认（§10）、删除与更新事件可能乱序（§7.3），物理清除统一由历史归档执行（§8.2）。共享航班 FDEL 先于主航班，各自处理，不做级联推断。

6.3 ADFT 恢复

ADFT 到达且 FLID 已存在、STATE = DELETED：这是同 FLID 生命周期重激活（§3.1），恢复 ACTIVE，推进 STATE_VERSION，登记状态事件。FLID 不存在则按新实例建立。

7. 对外处理

7.1 请求

经 REQ_TRACK 登记、COUTMSGS 发出；同类请求只留一条有效，新请求置旧为 EXPIRED。只有 RESP 完成 RQFD 请求，按（运营日、发送方、请求类型）匹配最新一条 PENDING；DNLD 是主动下发，独立处理，除现场确认的扩展规则外不得用于完成请求。协议无请求关联号，匹配规则待验收。

主链路不依赖逐日请求；当前只收定时下发的 48 小时窗口即为主链路的正常输入。

7.2 回填

提交后回填共享信箱；回填失败不得把已提交的 SUCCEEDED 改回 FAILED。

7.3 Kafka

KAFKA_SCHD 发整态：Dispatcher 合并同一 FLID 未发事件，按最新 STATE_VERSION 输出。KAFKA_MSG 只通知变化。两主题间不保证顺序；整态键缺失表示删除旧值。

判旧：消费端 (FLID, STATE_VERSION, UPDATED_AT)。

删除用 tombstone：载荷至少含 FLID、STATE_VERSION、DELETED；仅在 ACTIVE → DELETED 时发布，与删除同事务登记，投递失败持续重试。物理清除（§8.2）是内部清理，不再发布业务删除事件；仅对未经 FDEL、由生命周期直接清除的航班，在清除前补发一次删除事件。即使确认 FLID 永不复用，STATE_VERSION 也不能省——更新与删除事件仍会乱序；FLID 复用风险与 GENERATION 方案见 §10。

7.4 身份不变量

• FLID 是主键；一个 FLID 最多一个非空 OPERATION_DAY，一经确定不可改。
• 同 FLNO 不同运营日 = 不同 FLID。
• 身份变更时 FDEL 与 ADFT 的 FLID 可能相同也可能不同（§3.1）；不得由航班号或日期推断实例；FLID 不同时是终止与新建，不是主键变更。

OPERATION_DAY 不可变由应用层在快照入口校验；需数据库层强化可加触发器或 WHERE operation_day IS NULL OR operation_day = :d。

8. 生命周期与清理

运营日过去不等于航班结束，不能按日期删除。

8.1 历史判定

单一时间窗不构成删除依据；须同时满足“超过配置时间窗”且有终态证据或足够长的静默期：

• 已取消（CNCL 非空）超过 48 小时；
• 已完成离港/到港终态（NAAT/NEAT，字段含义与来源系统需在术语表确认，§10）超过 48 小时；
• STATE = DELETED 超过 48 小时；
• 无终态字段时，最后一次有效更新超过兜底期限（默认 7 天）。

窗口按机场时区（Asia/Shanghai）计算。

8.2 归档与清除（顺序不可颠倒）

1. HISTORY_SWEEP 选出满足 §8.1 的航班（含 DELETED）。
2. 写入历史存储。
3. 历史存储返回成功的 FLID 集合，对应行物理删除主行与明细；归档结果只记录在历史存储，当前态不保留归档状态。
4. 未经 FDEL 的航班在清除前补发一次删除事件（§7.3）；其余不发。
5. 失败或不明确的保留重试。

历史存储未接通时必须删 0 条；绝不允许先删当前态再补历史。物理清除只发生在本步骤。

8.3 保留期

对象	默认保留	前置条件
留痕 SCHD_SNAP_LOG	90 天	按 (SCOPE_END, RECV_AT) 清理
OPERATION_DAY = NULL 航班	7 天	仍未被快照收录；终止规则未定前只增不删

9. 失败与读取

错误	处理	队头行为
非法报文、数量不符、容量超限	DEAD，不重试	立即释放
未支持类型	FAILED(UNSUPPORTED)	达阈值转 DEAD
数据库或内部故障	FAILED(INFRA)，退避重试	成功或超限前阻塞
快照含归属日不符的 FLID	整包拒绝 DEAD(PROTOCOL)，留痕告警	立即释放，交人工确认
SEQN 回退 / SCHD_REVIVE_CONFLICT	只记 FLAGS 并告警	不阻塞
留痕写失败	只记 error 指标	不阻塞

读取：完整航班状态须在一致性读事务中读主表与全部明细，且过滤 STATE = ACTIVE。当前逐航班读取有 N+1 问题，主表与明细可能不在同一快照——批量加载与一致性读边界待补。

10. 未定事项

由 ACM2-31 跟踪：快照与动态事件顺序、FLOP 集合语义、删除事件版本、幂等键生命周期、FIFO 参数、一致性读取、快照完整性校验、Oracle 适配。

事项	状态
SCHD 按 FLID upsert 且不恢复 DELETED；删除一律标记，物理清除由历史归档执行	已定案（§4、§5.1、§6.2、§8.2）
FDEL + ADFT 的 FLID 可能相同或不同	已定案为处理规则（§3.1、§6.3）；上游实际行为待 SIS 条款核对
OPERATION_DAY 按机场运营日规则由 SODT 与机场时区计算，切日边界业务配置	已定案（§3.5）；边界值待业务确认
ADFT 字段缺失语义	待确认（§2.1）；确认前不得沿用 FLOP 合并规则
FLID 是否会被复用	待上游书面确认；确认前保持 DELETED 中间态。若不能保证永不复用，需引入生命周期表 FLIGHT_ID_LIFECYCLE(FLID, GENERATION, LAST_VERSION)，对外版本升级为 (FLID, GENERATION, STATE_VERSION)
上游取消是否必然伴随 FDEL	待上游确认；确认前不做任何基于名单缺席的删除
旧快照晚于 FLOP 的覆盖风险	接收序模型的已知代价；上游顺序保证待确认（ACM2-31#8）
NAAT / NEAT 的业务含义与来源系统	待术语表确认（§8.1）
逐运营日请求完整日计划	未完成；主链路不依赖，是否需要待上游 FDEL 可靠性确认后再评估

当前偏差：GTDT 按 Replace 处理但 FLOP 集合语义未确认；动态事件在锁外预览、事务内重算，目标只算一次；回填待办提交后写，崩溃窗口不可恢复，目标事务内预登记。

规则 M：快照与动态事件的应用顺序

当前实现按信箱接收顺序应用 SCHD 与 FLOP。SCHD 处理时完整替换对应字段，因此接收顺序上后到的 SCHD 会覆盖先到的 FLOP——这只是当前实现结果，不代表 SCHD 在业务时间上优先，不得对外承诺快照权威（ACM2-31#8）。

规范依据（SIS）

结论	出处
以 AODB 最新数据覆盖本地	§1.6.2
P 标签为空 = 删除该值；O 标签仅在有值时出现	§1.6.3
日计划是完整快照；未发送字段表示 AODB 已无该数据，应删除	§3.16 注释 2、4
子系统不消费的字段可忽略	§3.16 注释 3
日计划不含前日延误航班，保留与清理由子系统负责	§3.16 注释 1
主动下发为约 48 小时窗口，请求应答按请求范围	§3.16 Data Range
代码共享为独立实例，删除时共享先于主航班	§1.6.5