docs: 文档整理——统一 KAFKA 事件名与运营日术语，链接文字对齐标题，修复两处空行格式，README 补旧行为基线索引；主/共享级联语义上移至 flight-state §3.3 并增补 STATE_VERSION 不变量（architecture §9 引用同步改为 §3.1/§4/§7）
This commit is contained in:
windyboy
@@ -8,6 +8,7 @@
|
||||
| [design.md](design.md) | 管道流程、处理/投递状态、恢复与运行配置。 |
|
||||
| [flight-state.md](flight-state.md) | 航班设计的唯一现行规范：当前态、表关系、事务流程和开放问题。 |
|
||||
| [user-stories.md](user-stories.md) | US/OPS 验收目标，不能用“当前基础”替代完成证据。 |
|
||||
| [旧系统行为基线](legacy/msgexchange-api-legacy-user-stories.md) | msgexchange-api 现役行为基线与 KEEP/FIX 来源，Q8 对拍参考；不作为 v2 设计依据。 |
|
||||
| [legacy/decision-flight-state-history.md](legacy/decision-flight-state-history.md) | 已撤销方案的存档说明；现行规则仍以 `flight-state.md` 为准。 |
|
||||
| [SIS 规范](legacy/SIS_AODB_RMS-V0.1.md) / [XSD](legacy/unisysaodbsis.xsd) | 外部协议事实；即使在 legacy 目录仍是兼容依据。 |
|
||||
|
||||
|
||||
@@ -12,10 +12,10 @@ msgexchange-v2 是机场 OMMS 的上游报文处理中间件，用于替换旧
|
||||
- **输出**：Kafka 的 `msg` / `schd` 消息、共享 MySQL 的 `COUTMSGS` 出站信箱，以及查询 HTTP 接口；不直接推送前端。
|
||||
- **当前范围（阶段 A）**：航班当前态落自有 PostgreSQL（`FLIGHT_SCHD` + 资源明细表 + `FLIGHT_ROUTE_POINT`，权威口径见 [flight-state.md](flight-state.md)）。无 Redis 依赖；ES 历史投影属暂缓的阶段 B。
|
||||
|
||||
本文描述架构约束，不代表所有能力已实现；实现缺口见第 9 节。模块交互、状态机和参数详见 [design.md](design.md)，需求见 [user-stories.md](user-stories.md)。历史报文契约仍以 [SIS 接口规范](legacy/SIS_AODB_RMS-V0.1.md) 和 [XSD](legacy/unisysaodbsis.xsd) 为兼容依据，其他 legacy 资料仅作参考。
|
||||
本文描述架构约束，不代表所有能力已实现；实现缺口见第 9 节。模块交互、状态机和参数详见 [design.md](design.md)，需求见 [user-stories.md](user-stories.md)。历史报文契约仍以 [SIS 接口规范](legacy/SIS_AODB_RMS-V0.1.md) 和 [XSD](legacy/unisysaodbsis.xsd) 为兼容依据，其他 legacy 资料仅作参考，旧系统行为基线的职责见 [README](README.md) 职责表。
|
||||
|
||||
现场供库时目标为 Oracle 11g，否则自建 PostgreSQL；当前只有 PG 实现可运行，Oracle 不是已支持的平台。
|
||||
航班表结构和处理逻辑见 [航班状态设计](flight-state.md)。
|
||||
航班表结构和处理逻辑见 [运营航班状态设计](flight-state.md)。
|
||||
|
||||
## 2. 总体架构
|
||||
|
||||
@@ -89,6 +89,7 @@ CIIMS / AODB 等上游
|
||||
|---|---|---|
|
||||
| 自有 PostgreSQL | 单行锁 `PIPELINE_LOCK`、处理状态 `PROC_STATE`、待发事件 `MSG_EVENT`、请求跟踪 `REQ_TRACK`、回填待办 `BACKFILL_TODO`、航班当前态 `FLIGHT_SCHD` + 9 张明细表、留痕 `SCHD_SNAP_LOG` | 本系统唯一业务数据库。消息处理、状态推进与待发事件在单事务内原子提交；本地事务只在此库。 |
|
||||
| 共享 MySQL | `CMINMSGS` 入站信箱、`COUTMSGS` 出站信箱 | 外部系统所有。仅执行约定的信箱读写和处理标记回填，不建表、不迁移 schema、不写历史表。兼容 HTTP 入口可按既有契约写入入站信箱。 |
|
||||
|
||||
**不使用跨库事务。** PG 事务只能保证“处理结果与待发事件一起提交”，不能覆盖 MySQL 回填或 Kafka 发送等外部副作用。跨存储依靠幂等、重试和持久化补偿恢复：
|
||||
|
||||
| 中断位置 | 恢复要求 |
|
||||
@@ -134,7 +135,7 @@ CIIMS / AODB 等上游
|
||||
上线前必须完成并验证：
|
||||
|
||||
- 真实 PG + 共享 MySQL 信箱的端到端处理、补偿与投递，以及出站信箱适配；未闭合的缺口清单见 design.md §10。
|
||||
- 航班状态不变量与恢复证据：`STATE_VERSION` 推进、`OPERATION_DAY` 不可变、故障中断回滚（见 flight-state.md §7）。
|
||||
- 航班状态不变量与恢复证据：`STATE_VERSION` 推进、`OPERATION_DAY` 不可变、故障中断回滚（见 flight-state.md §3.1、§4、§7）。
|
||||
- FIFO 越序、身份去重、FDEL/ADFT、清场顺序与投递故障的回归测试（见 design.md §8）。
|
||||
- 单实例排他保护与启动校验、影子隔离、Kafka 生产配置约束——当前配置允许环境变量覆盖 `acks`/幂等/in-flight，且默认 in-flight 值与 D3 不同，切流前必须按 D3 收敛。
|
||||
- 死信与一致性异常的告警、可执行的人工重放流程、端到端追踪、积压指标与安全边界。
|
||||
|
||||
+2
-2
@@ -7,7 +7,7 @@
|
||||
运营航班权威状态只落自有 PostgreSQL（`FLIGHT_SCHD` 及资源明细表），Redis 已彻底退出动态权威与全部写路径；ES 历史投影属暂缓范围，不参与当前设计。
|
||||
|
||||
本文描述处理机制与流程；尚未交付的能力在本文件中明确标注，并以 §10 差异为准。航班状态规则统一由
|
||||
[航班状态设计](flight-state.md) 维护。
|
||||
[运营航班状态设计](flight-state.md) 维护。
|
||||
|
||||
## 2. 数据与领域模型
|
||||
|
||||
@@ -20,7 +20,7 @@
|
||||
| `PROC_STATE` | 入站消息的处理状态、身份、重试次数和错误原因 | `MSG_ID = CMINMSGS_ID` 主键防止重复入队；`IDENTITY_KEY` 唯一约束防止业务重复；按最小未完成消息 ID 取队头。 |
|
||||
| `MSG_EVENT` | 等待投递的事件（outbox） | `EVENT_ID` 决定投递顺序；`TARGET` 区分 `KAFKA:msg` / `KAFKA:schd`；`PARTITION_KEY` 恒为 `FLID`；`EVENT_TYPE` 区分 UPSERT 与 TOMBSTONE。 |
|
||||
| `REQ_TRACK` | 上游请求及应答关联 | 保存请求类型、覆盖运营日、发送方、出站信箱 ID 与发送/完成时间；同类只允许一个开放请求。登记、超时与应答匹配尚未实现（§10）。 |
|
||||
| `REF_MASTER` | 静态参考数据（目标表） | `(RTYPE, RKEY)` 唯一；尚未建表，客户端与刷新流程见 user-stories.md US-13/US-14。 |
|
||||
| `REF_MASTER` | 静态参考数据（目标表） | `(RTYPE, RKEY)` 唯一；尚未建表，客户端与刷新流程见 user-stories.md US-13/US-14（US-14 两类映射的存储落点未定）。 |
|
||||
| `FLIGHT_SCHD` | 航班标量及单值异常字段 | `FLID` 主键；`OPERATION_DAY` 一经确定不可变；版本与最近消息 ID 用于追踪。变长资源集合存于 9 张明细表，规则见 [flight-state.md](flight-state.md) §2，不在此重复。 |
|
||||
| `BACKFILL_TODO` | 共享信箱回填重试 | 回填意图与业务终态同事务预登记，提交后回填成功即删除；待办再次落账失败的崩溃窗口仍在（§10）。 |
|
||||
| `PROC_STATE_HST` | 终态处理记录的归档目标 | 尚未建表；不得改写为共享库历史表。 |
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## 1. 目标与边界
|
||||
|
||||
系统从共享 MySQL 信箱接收 SIS/AODB 报文，把结果合并到自有 PostgreSQL 中的航班当前态，再通过 outbox 投递 Kafka。共享信箱和 Kafka 都不是状态权威，也不参与本地事务的分布式提交。
|
||||
系统从共享 MySQL 信箱接收 SIS/AODB 报文，把结果合并到自有 PostgreSQL 中的航班当前态，再通过 outbox 投递 Kafka。共享信箱和 Kafka 都不是状态权威，也不在本地事务的提交范围内。
|
||||
|
||||
- `FLID` 是航班实例的唯一标识；不得由航班号、日期或资源号推断身份。
|
||||
- `FLIGHT_SCHD` 及其明细表是唯一权威当前态；展示视图只读，不能作为写入或对账来源。
|
||||
@@ -29,7 +29,7 @@
|
||||
|
||||
`FLID` 是主键。`OPERATION_DAY` 从 SCHD 记录的 `SODT` 按配置的机场时区和切日规则推导；它不是消息接收日或落库日。
|
||||
|
||||
一旦已写入非空 `OPERATION_DAY`，同一 `FLID` 不得改到另一个运营日。遇到冲突，整包日计划按协议错误拒绝，既有状态保持不变。尚未由日计划收录的航班可以为 `NULL`；这不表示该航班没有运行日，只表示当前模型无法为它确定归属日。
|
||||
一旦已写入非空 `OPERATION_DAY`，同一 `FLID` 不得改到另一个运营日。遇到冲突，整包日计划按协议错误拒绝，既有状态保持不变。尚未由日计划收录的航班可以为 `NULL`；这不表示该航班没有运营日，只表示当前模型无法为它确定归属日。
|
||||
|
||||
### 2.2 字段与集合
|
||||
|
||||
@@ -48,7 +48,7 @@
|
||||
|
||||
SCHD DNLD/RESP 在整包校验通过后，逐条将报文携带的航班写入当前态。日计划只更新或创建其携带的 `FLID`，**不会因其他航班未出现在本次报文中而删除任何记录**。
|
||||
|
||||
日计划在重叠字段上可以覆盖当前动态值；未携带的字段按合并规则保留，显式清空才清除。每个成功写入的航班推进 `STATE_VERSION`，并在同一事务登记 `KAFKA_SCHD` 与 `KAFKA_MSG` 事件。
|
||||
日计划在重叠字段上可以覆盖当前动态值；未携带的字段按合并规则保留，显式清空才清除。每个成功写入的航班推进 `STATE_VERSION`，并在同一事务登记 `KAFKA:schd` 与 `KAFKA:msg` 事件。
|
||||
|
||||
消息重放由 `PROC_STATE` 的消息 ID 与 `identity_key` 控制；已成功提交的消息不得再次写入或重复登记事件。整包校验失败或运营日冲突时，整包不落地。
|
||||
|
||||
@@ -68,6 +68,8 @@ FDEL 是业务删除入口：仅在 `ACTIVE → DELETED` 时推进版本、保
|
||||
|
||||
ADFT 的字段缺失语义尚待上游确认。在确认前采用保守的 Set-only 规则：出现字段可更新，缺失字段不清空；不得把它当成日计划或动态全量替换。新建 ADFT 若带可解析的 `SODT`，按同一运营日规则计算 `OPERATION_DAY`；否则保留为 `NULL`。
|
||||
|
||||
主/共享航班级联：删除共享航班时更新主航班 `MAFL` 并向主航班通知；删除主航班时级联删除其子共享关联并发出删除通知；主/共享关系必须一次原子变更，不出现主已删、子残留的半状态。共享航班增量通常只更新并通知主航班，不直接发共享通知。这些语义同样约束 FDEL 之外的生命周期清理。
|
||||
|
||||
## 4. 处理事务与失败规则
|
||||
|
||||
所有状态处理遵循下列顺序：
|
||||
@@ -82,9 +84,9 @@ ADFT 的字段缺失语义尚待上游确认。在确认前采用保守的 Set-o
|
||||
|
||||
## 5. Kafka 与读取
|
||||
|
||||
`KAFKA_SCHD` 是按 `FLID` 的完整状态投影。Dispatcher 可以合并同一 `FLID` 尚未投递的中间版本，只发最新状态；消费端用 `(FLID, STATE_VERSION, UPDATED_AT)` 防止旧投影覆盖新状态。
|
||||
`KAFKA:schd` 是按 `FLID` 的完整状态投影。Dispatcher 可以合并同一 `FLID` 尚未投递的中间版本，只发最新状态；消费端用 `(FLID, STATE_VERSION, UPDATED_AT)` 防止旧投影覆盖新状态。
|
||||
|
||||
`KAFKA_MSG` 只通知变化，不承载权威状态；两个 topic 不承诺顺序。FDEL 和必要的生命周期清理使用 tombstone：键为 `FLID`，删除记录以 null 值投递，通知下游移除旧状态。
|
||||
`KAFKA:msg` 只通知变化，不承载权威状态；两个 topic 不承诺顺序。FDEL 和必要的生命周期清理使用 tombstone：键为 `FLID`，删除记录以 null 值投递，通知下游移除旧状态。
|
||||
|
||||
读取完整航班需要读取主表和全部明细。当前逐航班读取有多次查询，尚未保证跨表一致性快照；批量加载与明确的一致性读边界是后续优化项。
|
||||
|
||||
@@ -105,6 +107,7 @@ ADFT 的字段缺失语义尚待上游确认。在确认前采用保守的 Set-o
|
||||
|
||||
- 本地 PostgreSQL 当前态是唯一权威；信箱、Kafka、Redis 和展示视图不是权威。
|
||||
- 同一时刻只有一个主泵推进 FIFO 状态；状态、事件、终态和回填意图原子提交。
|
||||
- 每个航班每次成功状态写入单调推进 `STATE_VERSION`；重复消息不重复推进。
|
||||
- `FLID` 唯一，已确定的 `OPERATION_DAY` 不可改变。
|
||||
- 报文未携带的字段不会被隐式清空；集合按完整合并结果写入。
|
||||
- 缺席于某个日计划不构成删除理由；删除只由 FDEL 或受控历史清理触发。
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
- 所有内部迁移只落自有 PG；共享 MySQL 不建表、不增列、不写历史表。本文用 `DATE_PROCESSED / STATUS` 表示逻辑字段，实际列名以库方契约为准。
|
||||
- 验收条目可按 `US-xx/条目号` 引用。故事较大时按下文子范围拆成小 PR，不把一个故事等同于一个提交。
|
||||
|
||||
**存储基线**：当前 PG 主表与明细表是状态权威，Redis 不参与动态写路径。Oracle 11g 是尚待完整适配的部署目标。航班状态设计和当前缺口见 [flight-state.md](flight-state.md)。
|
||||
**存储基线**：当前 PG 主表与明细表是状态权威，Redis 不参与动态写路径。Oracle 11g 是尚待完整适配的部署目标。航班状态设计和当前缺口见 [运营航班状态设计](flight-state.md)。
|
||||
|
||||
## 2. 建议实施顺序
|
||||
|
||||
@@ -112,8 +112,8 @@
|
||||
1. `SCHD-ADFT` 与 29 个 FLOP 子类型逐项列入覆盖矩阵，每项有对应的处理器规则与回归测试；未知类型可恢复失败。RESP/DNLD 不计入这批处理器，走 US-06。
|
||||
2. 每类固定“输入与前态 → 后态 → msg → schd → 终态”五面样例；区分字段缺失、显式清空、重复报文和主/共享航班。清单和 golden 样例按 Q8 补齐，不以“已写 29 个类”替代验收。
|
||||
3. 对按 KEEP 规则需忽略的不存在航班，以 `SUCCEEDED` 无副作用结束，并由 US-09 回填；ADFT 建航班等行为按各类型矩阵执行。航班当前态以自有 PG 为唯一权威，重启即恢复，不存在 Redis 全损后白名单无法找回的损坏路径。
|
||||
4. 共享航班通常更新并通知主航班，不直接发共享通知。FDEL 删除共享航班时更新主航班 MAFL 并通知；删除主航班时删除主航班及其子共享关联并发删除通知；目标不存在幂等成功。
|
||||
5. ADFT/FDEL 使用值相等比较；主/共享关系一次原子变更，不出现主已删、子残留等半状态。
|
||||
4. 共享航班更新与删除级联语义以 flight-state.md §3.3 为唯一规范（共享航班通知、主航班 `MAFL` 更新、级联删除、原子变更；不出现主已删、子残留）；本条目验收实现不偏离该规范，目标不存在时幂等成功。
|
||||
5. ADFT/FDEL 的值相等比较与半状态禁止规则见 flight-state.md §3.3。
|
||||
6. PSDT 通过 US-14 的只读映射计算 `abdg`，处理器不直接调用 admin-api。
|
||||
|
||||
**当前基础与落点**：落点已变为 `processing/DynamicProcessors.kt`（`FlopProcessor`/`FdelProcessor`/`AdftProcessor`）与 `domain/flight/FlightStateEngine`、`FlightStateRepository`。FDEL/ADFT 与通用 FLOP 处理器已接入（含 DELETED 幂等与重激活、tombstone 同事务登记）；29 类逐类语义矩阵与 golden 样例仍未补全，不能因处理器存在就视为覆盖完成。
|
||||
@@ -137,6 +137,7 @@
|
||||
3. 在自有 PG 单事务内，批处理写入已校验的 `FLIGHT_SCHD` 航班状态与资源明细；本次日计划中未出现的航班不因此被删除。
|
||||
4. 在同一 PG 事务中提交 `FLIGHT_SCHD` 变更、`MSG_EVENT` 待发通知与 `PROC_STATE(SUCCEEDED)`；匹配 RESP 同事务完成请求并置 `DONE`；事务提交后执行信箱回填。
|
||||
5. 相同报文重放不二次写入或重复发事件；单事务崩溃整体回滚，重放幂等。
|
||||
|
||||
**当前基础与落点**：DNLD 与 RESP 已共同路由到 `processing/ScheduleProcessor.applyScheduleRecords`，整包校验、归属日冲突整包拒绝与单事务写入已实现；`REQ_TRACK` 表与 `ReqTrackRepository` 已建。仍需补 RESP 应答守卫（开放 RQFD 匹配、时间比对）与请求完成关联逻辑。
|
||||
|
||||
**前置**：US-03、US-08 请求登记/匹配基础；Q1、Q5。
|
||||
|
||||
Reference in New Issue
Block a user