docs: 拆分契约/前提/参数文档,合并消息生命周期并收敛设计裁决
- design.md 合并 message-lifecycle.md(后者保留跳转 stub),去重并改用稳定 ID 引用 - 新增 invariants.md(前提/不变量/声明边界/验证映射)、contracts.md(对外条款与 Q 台账)、 reference.md(参数/指标/模块/错误分类) - architecture/flight-state/user-stories/README 同步重划引用;README 废止「引用章节号」 - 裁决收敛:R 按超期而非次数放弃、清除前提含放弃清单、航班表写者互斥、head-deadline 仅告警、 超期判据用本地入队时间、投递批次读取时刻冻结、schd 只进不退与条件标记、FLID 复用为前提 - 删除 runbooks 与 CI 防漂移校验:设计阶段不产出面向执行期的产物 Refs: ACM2-42..51
This commit is contained in:
+16
-14
@@ -12,7 +12,7 @@ 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),消息生命周期与信箱清除见 [message-lifecycle.md](message-lifecycle.md),需求见 [user-stories.md](user-stories.md)。历史报文契约仍以 [SIS 接口规范](legacy/SIS_AODB_RMS-V0.1.md) 和 [XSD](legacy/unisysaodbsis.xsd) 为兼容依据,其他 legacy 资料仅作参考,旧系统行为基线的职责见 [README](README.md) 职责表。
|
||||
本文描述架构约束,不代表所有能力已实现;实现缺口见 [invariants.md](invariants.md) 的声明边界与 Plane(ACM2)。模块交互、状态机与参数详见 [design.md](design.md),前提与不变量见 [invariants.md](invariants.md),对外契约见 [contracts.md](contracts.md),需求见 [user-stories.md](user-stories.md),参数与指标见 [reference.md](reference.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)。
|
||||
@@ -54,7 +54,7 @@ CIIMS / AODB 等上游
|
||||
| `codec` | XML 解码,区分非法报文与可修复的解码失败。 |
|
||||
| `processing` | FIFO 调度、业务身份绑定与去重、领域决策与落库(SCHD/FLOP/FDEL/ADFT):纯领域逻辑只返回决策;Processor 作为事务协调器,在锁事务内完成状态写入、事件与回填意图登记,不直接触碰 Kafka。 |
|
||||
| `delivery` | 消费待发事件,负责按目标保序、`schd` 聚合、投递和失败重试。 |
|
||||
| `jobs` | 回填补偿扫描、航班历史清理与留痕保留期清理;独立 job 线程执行(调度见 design.md §6.1,红线见 flight-state.md §6),不参与 FIFO。 |
|
||||
| `jobs` | 回填补偿扫描、航班历史清理与留痕保留期清理;独立 job 线程执行(调度见 design.md「维护作业与归档」,红线见 flight-state.md「生命周期与开放项」,与主泵的互斥见 `INV-18`),不参与 FIFO。 |
|
||||
| `domain` / `config` | 领域状态、事件和决策模型,以及运行参数。 |
|
||||
| `infra` | 仓储(JDBC/stub)、外部适配器、重试、健康检查与日志;通过接口隔离基础设施。 |
|
||||
|
||||
@@ -62,7 +62,7 @@ CIIMS / AODB 等上游
|
||||
|
||||
### 收报与处理
|
||||
|
||||
1. `InboxPoller` 默认每秒按 ID 区间扫描水位 `W` 之后的信箱记录(`ID > W`,**不以处理标记为谓词**),在自有 PG 中建立 `PROC_STATE(PENDING)`;水位与入队在同一事务推进。重复扫描不能重复入队,中断后由重扫补建。扫描谓词与水位的唯一口径见 message-lifecycle.md §5.1。
|
||||
1. `InboxPoller` 默认每秒按 ID 区间扫描水位 `W` 之后的信箱记录(`ID > W`,**不以处理标记为谓词**),在自有 PG 中建立 `PROC_STATE(PENDING)`;水位与入队在同一事务推进(`INV-2`)。重复扫描不能重复入队,中断后由重扫补建。扫描谓词与水位见 design.md「收报与水位」。
|
||||
2. 主泵只处理最小未完成 `MSG_ID`。解析报文、绑定业务身份并去重后,分派给 SCHD/FLOP/FDEL/ADFT 处理器。
|
||||
3. 在自有 PG 同一事务内(先取 `PIPELINE_LOCK`)保存航班状态变更(`FLIGHT_SCHD` 与明细表)、`MSG_EVENT` 待发事件、处理终态与回填意图。
|
||||
4. 事务提交后,补写共享信箱的处理标记(外部副作用,由回填退避重试与超期强制补写保障)。
|
||||
@@ -75,11 +75,13 @@ CIIMS / AODB 等上游
|
||||
|
||||
## 5. 必须保持的约束
|
||||
|
||||
- **消息严格 FIFO**:队头失败并退避时,后续消息仍不能越过它。只有队头完成或按失败策略进入终态后,队列才继续推进。收报重扫和水位设计必须防止较小 ID 漏入队而被后续消息越过。
|
||||
- **动态状态单写者**:`FLIGHT_SCHD` 及明细表只由主泵单线程写入。事务内第一步对 `PIPELINE_LOCK` 单行 `SELECT ... FOR UPDATE` 互斥;该方案不依赖数据库扩展或额外 DBA 特权;Oracle 11g 待适配时验证。不能通过增加实例或处理线程直接扩容。
|
||||
- **身份去重**:同一业务身份只能绑定一条有效处理记录,重复报文不应再次产生业务副作用。具体身份组成和重放规则见设计文档。
|
||||
- **快照可恢复**:快照以 `PROC_STATE` 成功终态判定重放;每次成功写入推进 `STATE_VERSION`;`OPERATION_DAY` 一经确定不可变(见 flight-state.md §2.1)。
|
||||
- **物理清除只发生在历史归档**:删除一律先标记(FDEL)或由生命周期清除;历史存储未接通时必须删 0 条(见 flight-state.md §6)。
|
||||
本节只列约束的**归属**;完整定义与验证映射见 [invariants.md](invariants.md),实现与演进不得违反:
|
||||
|
||||
- 消息严格 FIFO:`INV-3`、`INV-4`、`INV-5`(发现完整性依赖 `PRE-2`/`PRE-3`,当前不可对外声明,见 CLM-1/CLM-2)。
|
||||
- 动态状态单写者与写者集合互斥:`INV-17`、`INV-18`。
|
||||
- 身份去重:`INV-9`(身份组成见 design.md「消息、身份与决策」)。
|
||||
- 快照可恢复与运营日不可变:`INV-12`、`INV-13`。
|
||||
- 物理清除只发生在历史归档之后:`INV-15`(红线见 flight-state.md「生命周期与开放项」)。
|
||||
|
||||
这些约束优先于吞吐量优化。单写者降低了并发复杂度,代价是队头阻塞和吞吐上限;如需并行化,必须先重新定义顺序与状态归属,不能只调整线程数。
|
||||
|
||||
@@ -88,9 +90,9 @@ CIIMS / AODB 等上游
|
||||
| 存储 | 承载内容 | 职责说明 |
|
||||
|---|---|---|
|
||||
| 自有 PostgreSQL | 单行锁 `PIPELINE_LOCK`、处理状态与回填事实 `PROC_STATE`、消费水位 `INBOX_CURSOR`、待发事件 `MSG_EVENT`、请求跟踪 `REQ_TRACK`、航班当前态 `FLIGHT_SCHD` + 8 张资源明细表 + `FLIGHT_ROUTE_POINT`、留痕 `SCHD_SNAP_LOG` | 本系统唯一业务数据库。消息处理、状态推进、处理终态、回填意图与待发事件在单事务内原子提交;本地事务只在此库。 |
|
||||
| 共享 MySQL | `CMINMSGS` 入站信箱、`COUTMSGS` 出站信箱 | 外部系统所有。本系统仅执行约定的信箱读写与处理标记回填,不建表、不迁移 schema、不写历史表;由库方按 Q9 执行的清除与历史归档见 message-lifecycle.md §6。兼容 HTTP 入口可按既有契约写入入站信箱。 |
|
||||
| 共享 MySQL | `CMINMSGS` 入站信箱、`COUTMSGS` 出站信箱 | 外部系统所有。本系统仅执行约定的信箱读写与处理标记回填,不建表、不迁移 schema、不写历史表;由库方按 `Q9` 执行的清除与历史归档见 contracts.md「保留与清除」。兼容 HTTP 入口可按既有契约写入入站信箱。 |
|
||||
|
||||
**不使用跨库事务。** PG 事务只能保证“处理结果与待发事件一起提交”,不能覆盖 MySQL 回填或 Kafka 发送等外部副作用。跨存储依靠幂等、重试和持久化补偿恢复;各中断位置的判定与恢复动作统一见 [message-lifecycle.md](message-lifecycle.md) §4,本文不重复。
|
||||
**不使用跨库事务。** PG 事务只能保证“处理结果与待发事件一起提交”(`INV-17`),不能覆盖 MySQL 回填或 Kafka 发送等外部副作用。跨存储依靠幂等、重试和持久化补偿恢复;各中断位置的判定与恢复动作见 design.md「中断恢复」。
|
||||
|
||||
对外投递按**至少一次**设计,不承诺端到端恰好一次。Kafka 生产者幂等不能消除应用重启或 outbox 重发带来的所有重复。
|
||||
|
||||
@@ -127,10 +129,10 @@ CIIMS / AODB 等上游
|
||||
|
||||
上线前必须完成并验证:
|
||||
|
||||
- 真实 PG + 共享 MySQL 信箱的端到端处理、补偿与投递,以及出站信箱适配;未闭合的缺口清单见 design.md §10。
|
||||
- 航班状态不变量与恢复证据:`STATE_VERSION` 推进、`OPERATION_DAY` 不可变、故障中断回滚(见 flight-state.md §3.1、§4、§7)。
|
||||
- FIFO 越序、身份去重、FDEL/ADFT、清场顺序与投递故障的回归测试(见 design.md §8)。
|
||||
- 真实 PG + 共享 MySQL 信箱的端到端处理、补偿与投递,以及出站信箱适配;未闭合的缺口与不可声明项见 [invariants.md](invariants.md) 的声明边界。
|
||||
- 航班状态不变量与恢复证据:`STATE_VERSION` 推进、`OPERATION_DAY` 不可变、故障中断回滚(`INV-12`–`INV-16`,语义见 flight-state.md)。
|
||||
- FIFO 越序、身份去重、FDEL/ADFT、清场顺序与投递故障的回归测试(见 [invariants.md](invariants.md) 验证映射)。
|
||||
- 单实例排他保护与启动校验、影子隔离、Kafka 生产配置约束——当前配置允许环境变量覆盖 `acks`/幂等/in-flight,且默认 in-flight 值与 D3 不同,切流前必须按 D3 收敛。
|
||||
- 死信与一致性异常的告警、可执行的人工重放流程、端到端追踪、积压指标与安全边界。
|
||||
|
||||
验收与进度由 Plane 跟踪,缺口逐项见 design.md §10 与 user-stories.md;航班状态规则统一以 flight-state.md 为准。
|
||||
验收与进度由 Plane 跟踪,缺口逐项见 [invariants.md](invariants.md) 的声明边界与 [user-stories.md](user-stories.md);航班状态规则统一以 flight-state.md 为准。
|
||||
|
||||
Reference in New Issue
Block a user