docs: 二轮审查文档收敛 ACM2-23～27（Kafka/依赖/ResponseDto/STATUS/格式）
This commit is contained in:
windyboy
+25
-24
@@ -2,10 +2,11 @@
|
||||
|
||||
> **系统角色**：机场 OMMS **上游报文处理中间件**——消费 CIIMS/AODB 等上游写入共享信箱的
|
||||
> XML 报文，经 FIFO 管道处理后向下游投递；**非**报文源系统。
|
||||
> 现行架构权威为 Plane **`airport_chengdu_msgexchange_v2`（ACM2）** 工作区的 **ACM2-3（综合架构 v4）**；
|
||||
> 架构基线为 Plane **`airport_chengdu_msgexchange_v2`（ACM2）** 项目的 **ACM2-3（综合架构 v4）**；
|
||||
> 脚手架跟踪 **ACM2-4**，评审与实施计划（U01–U30）**ACM2-10**。本文是仓库内的架构速览，
|
||||
> 与代码同步维护；两者冲突时以 ACM2-3 为准并回改本文。
|
||||
> **存储边界与阶段 B 以 ACM2-11/ACM2-12 决策为准**（自有 PostgreSQL + 共享 MySQL 信箱 +
|
||||
> 与代码同步维护。**有效口径 = ACM2-3 未被取代的内容 + 后续决策 ACM2-12**，不能只按
|
||||
> ACM2-3 的历史正文回改本文。
|
||||
> **存储边界与阶段 B 以 ACM2-12 为准**（ACM2-11 仅为决策史；自有 PostgreSQL + 共享 MySQL 信箱 +
|
||||
> Redis 动态/gen；阶段 B 缓做）——ACM2-3 中"同库事务锚 / MySQL 六辅助表 / 阶段 B"表述
|
||||
> 已被上述决策修订。
|
||||
> 配套设计细节见 [design.md](design.md)。
|
||||
@@ -47,9 +48,9 @@
|
||||
|---|---|---|
|
||||
| 语言/运行时 | Kotlin 2.3 + JDK 25 | JDK 21 不可行（Micronaut 5.1 系要求 JVM 25+，ACMA-9 实测） |
|
||||
| 框架 | Micronaut platform BOM **5.1.3**（core 系实际解析 **5.1.13**，classpath 混用；版本重钉属 U02/U05） | 编译期 DI：KSP（`kotlin-ksp` + `micronaut-inject-kotlin` **5.1.3**）生成 `*$Definition` |
|
||||
| 持久化 | **自有 PostgreSQL**（全部内部状态）+ 共享 MySQL 信箱 | 自有库：消息管道 PROC_STATE/MSG_EVENT + PUMP_JOB/REQ_TRACK + 21 类 REF_MASTER（迁移 `db/migration`）；共享库仅 CMINMSGS/COUTMSGS DML。Micronaut Data JDBC 实装属 U05（ACM2-12） |
|
||||
| 持久化 | **自有 PostgreSQL**（全部内部状态）+ 共享 MySQL 信箱 | 自有库：消息管道 PROC_STATE/MSG_EVENT + PUMP_JOB/REQ_TRACK + 21 类 REF_MASTER（迁移 `db/migration`）；共享库主契约为 CMINMSGS/COUTMSGS DML。JDBC 仓储与 InboxPoller 已有初版，事务/补偿/出站适配仍属 U05（ACM2-12） |
|
||||
| 权威存储 | Redis（航班动态 flightInfo + 快照 gen） | 仅主泵线程写（I5）；Lua 原子覆盖/版本推进（gen 协议重设计属 U09） |
|
||||
| 投递 | Kafka（acks=all + 幂等） | outbox 模式，经 MSG_EVENT 表中转 |
|
||||
| 投递 | Kafka（acks=all + 幂等；切流前须确认 Broker 支持 InitProducerId(22)，严禁非幂等降级） | outbox 模式，经 MSG_EVENT 表中转 |
|
||||
| 投影（阶段 B） | Elasticsearch（历史） | **阶段 B 缓做（ACM2-12）**：FLIGHT_STATE 不落表，Redis 永续动态权威；历史投影链路不变 |
|
||||
| 注册中心 | Eureka（Micronaut 原生键） | 服务名契约 `msgexchangeapi`（影子 `msgexchangeapi-shadow`）——**U17 未落地**：当前注册名仍取 `micronaut.application.name`（=msgexchange-nextgen），`msgx.service-name` 无运行时消费方（见 §8 与 design.md §9） |
|
||||
| 可观测 | logstash TCP（Async 包装）+ MDC traceId + 自定义健康指示器 | 见 [design.md §8](design.md) |
|
||||
@@ -75,7 +76,7 @@
|
||||
│ │ │ decode（XmlCodec） │
|
||||
│ │ │ identity 绑定（I3） │
|
||||
│ │ │ Handler.decide（纯函数） │
|
||||
│ │─Schd DNLD──▶ SnapshotFlow（流程4） │
|
||||
│ │─Schd RESP/DNLD▶ SnapshotFlow（流程4） │
|
||||
│ │─PUMP_JOB───▶ JobExecutor（作业窗口，决策1） │
|
||||
│ │ │
|
||||
│ ├────Redis Lua──▶ Redis flightInfo（A权威） │
|
||||
@@ -102,18 +103,15 @@
|
||||
PG 入队失败时以共享库水位**重扫补建**（U05）。`POST /cminmsgs/send` 为现役 HTTP
|
||||
**写**路径（手工/对拍），非上游报文到达的主拓扑。
|
||||
|
||||
- **两条专用 daemon 单线程**（`msgx-pump` / `msgx-dispatcher`）由 `PipelineLifecycle`
|
||||
- **三条专用 daemon 单线程**（`msgx-inbox-poller` / `msgx-pump` / `msgx-dispatcher`）由 `PipelineLifecycle`
|
||||
在 `ServerStartupEvent` 后拉起，不占用 Netty event loop；停机 `requestStop` +
|
||||
interrupt + join（U07）。仅当 `msgx.pipeline.autostart=true` 时装配——生产默认关，
|
||||
当前属**有意脚手架门禁**（生产可运行需先完成 U05 数据层实装，见 §7）。
|
||||
- **单写者约束（I5）**：阶段 A 全部 Redis 写集中在主泵线程；实例数必须为 1
|
||||
（运行期租约/选主保护属 U26，尚未实装，当前靠部署拓扑约束）。
|
||||
- **统一 FIFO（决策 1）**：定时作业（cron → PUMP_JOB 入队）与消息同队列，
|
||||
作业产物不绕过队头顺序。**当前实现**：`jobBefore` 为 **head-state 近似**（队头为空或
|
||||
FAILED 时作业先行），非入队时间排序，与「统一 FIFO」注释存在已知偏离（U15 未实装，
|
||||
见 design.md §9）。
|
||||
**ACM2-12 修订**：PUMP_JOB 在自有 PG，作业不插队、仅在消息队头空闲/退避窗口由主泵执行
|
||||
（作业窗口语义定稿属 ACM2-12 Checks ④）。
|
||||
- **消息严格 FIFO，作业采用窗口语义（决策 1 经 ACM2-12 修订）**：消息按最小未完成
|
||||
`CMINMSGS_ID` 保序；PUMP_JOB 不与消息构成统一全序，仅在无消息队头或队头处于退避窗口时执行。
|
||||
当前 `jobBefore` 的 head-state 判定已近似该语义，但窗口、饥饿边界和测试仍待 U15 固化。
|
||||
- **存储边界（ACM2-12）**：本框图内事务库为**自有 PostgreSQL**（PROC_STATE/MSG_EVENT/
|
||||
PUMP_JOB/REQ_TRACK/21 类）；CMINMSGS/COUTMSGS 在**共享 MySQL 信箱**（上游外部写、
|
||||
本系统 JDBC 轮询读 + 处理回填写）；Redis 除 flightInfo 还承载快照 gen。图中跨库步骤
|
||||
@@ -125,7 +123,7 @@
|
||||
| 包 | 职责 | 对应 ACMA-8 | 主要类 |
|
||||
|---|---|---|---|
|
||||
| `ingress/` | 收报：JDBC 轮询共享信箱发现新信 → 自有 PG 建 PENDING（+ 补偿重扫；HTTP 写路径 compat）；不解析报文 | 流程 1，I3 | `InboxPoller`（U05）`InboxController` `InboxService` |
|
||||
| `processing/` | 主泵：FIFO 领取、解码、identity 绑定、纯函数决策、自有 PG 事务2 | 流程 2/4，I1/I2/I5 | `Pump` `MessageProcessor` `SnapshotFlow` `Identity` `Handler(Registry)` |
|
||||
| `processing/` | 主泵：FIFO 领取、ignoreMsg、identity 绑定、纯函数决策、RESP/DNLD 快照、自有 PG 事务2 | 流程 2/4，I1/I2/I5 | `Pump` `MessageProcessor` `SnapshotFlow` `Identity` `Handler(Registry)` |
|
||||
| `delivery/` | 投递：每 target 严格 FIFO、schd 聚合 | 流程 3 | `Dispatcher` `SchdAggregation` |
|
||||
| `jobs/` | 泵作业：清场/归档/投影重建（PUMP_JOB 自有 PG，作业窗口执行） | 流程 4/5/7，I4 | `JobExecutor` `HistorySweepJob` `ArchiveJob` `ProjectionRebuildJob` |
|
||||
| `codec/` | XML 解码 + 失败分类（MALFORMED vs CODEC_ERROR） | 决策 4 前置 | `XmlCodec` `DecodeResult` |
|
||||
@@ -137,7 +135,7 @@
|
||||
|
||||
| # | 决策 | 落点 |
|
||||
|---|---|---|
|
||||
| D1 | 作业与消息同队列（cron 只经 PUMP_JOB 入队，产物不绕过队头）——**ACM2-12 修订**：PUMP_JOB 迁自有 PG 后不插队，仅队头空闲/退避窗口执行 | `Pump.tick` / `JobExecutor` |
|
||||
| D1 | 消息保持严格 FIFO；PUMP_JOB 为独立持久队列，不与消息组成统一全序，仅在无消息队头或队头退避窗口执行 | `Pump.tick` / `JobExecutor` |
|
||||
| D2 | 阶段 B（缓做，ACM2-12）：ES 投递成功后同线程同步 enqueue 删除事件（不轮询 ack） | `Dispatcher.tick`（定案 2；阶段 B 评估后启用） |
|
||||
| D3 | schd 唯一出口是 flushSchd 批量聚合（逐条循环显式排除 KAFKA_SCHD） | `Dispatcher.tick`（U06/N03） |
|
||||
| D4 | 未实装 ≠ 非法：无 handler / staging 未实装 → FAILED(UNSUPPORTED) 可重放，绝不写终态 | `MessageProcessor` `SnapshotFlow`（U10/N21） |
|
||||
@@ -157,25 +155,28 @@
|
||||
出站写 `COUTMSGS`（他人系统读取发送）。与信箱的交互是**外部副作用**，非本系统事务的一部分：
|
||||
收报主路径=JDBC 轮询发现新信 → 自有 PG 建 PENDING 入队；compat HTTP 写=
|
||||
信箱 insertRaw 成功（返回 CMINMSGS_ID）→ PG 入队；PG 建行失败以共享库
|
||||
`DATE_PROCESSED IS NULL` 重扫补建；回填 = 处理成功后异步/补偿，最终一致（ACM2-12 影响面）。
|
||||
`DATE_PROCESSED IS NULL` 重扫补建；回填 = 处理成功后 PG 本地事务外异步/持久化补偿，最终一致（ACM2-12 / ACM2-19）。
|
||||
- **Redis**：航班动态 flightInfo（阶段 A 权威，I5）+ 快照 **SCHD_GEN**（Lua 内原子
|
||||
「覆盖+按代差删+版本推进」，协议重设计属 U09）。
|
||||
- **阶段 B（FLIGHT_STATE）：缓做，不落表**；ES 仍承载历史航班（判史/查询），
|
||||
相关投影/删除事件链待阶段 B 重评估后启用。
|
||||
- legacy 旧表 schema 归 legacy 仓库维护；CMINMSGS/CMINMSGS_HST/COUTMSGS 结构与保留策略
|
||||
由共享库方管理，本系统只按契约读写（权限边界需与库方确认）。
|
||||
|
||||
- legacy 旧表 schema 归 legacy 仓库维护；CMINMSGS/COUTMSGS 的结构与保留策略由共享库方管理。
|
||||
**ARCHIVE 归档定案（ACM2-17）**：严禁向共享 MySQL 写入 `CMINMSGS_HST`（共享库严格保持 CMINMSGS 读/回填、
|
||||
COUTMSGS 写入两表契约）；终态入站消息归档目标确定为自有 PG `PROC_STATE_HST`。
|
||||
## 7. 权威（阶段 A Redis；阶段 B 缓做）与当前就绪度
|
||||
|
||||
| 阶段 | 权威 | 投递目标 | 状态 |
|
||||
|---|---|---|---|
|
||||
| A（`msgx.phase=A`） | Redis flightInfo（+ gen） | KAFKA:msg、KAFKA:schd | 管道骨架+重试闭环已实装；自有 PG 数据层/信箱适配层属 U05；gen→Redis 协议属 U09 |
|
||||
| B（`msgx.phase=B`） | —（缓做，ACM2-12） | ES 历史投影 | 不落表、不启用；Redis 永续动态权威，阶段 B 价值重评估后再定 |
|
||||
| A（`msgx.phase=A`） | Redis flightInfo（+ gen） | KAFKA:msg、KAFKA:schd | 管道骨架+重试闭环已实装；PG/JDBC 信箱轮询已有初版，但水位、事务、回填补偿与出站信箱尚未闭环；gen→Redis 协议属 U09 |
|
||||
| B（缓做，重新评估后命名/启用） | Redis 仍为动态权威 | ES 历史写入与成功集清场 | FLIGHT_STATE 不落表；HISTORY_SWEEP 标为 DEFERRED，不作为阶段 A 切流门禁 |
|
||||
|
||||
**就绪度（2026-09-07 复核口径）**：可编译、37 测试全绿、**dev stub 进程级冒烟实测可端到端**
|
||||
**就绪度（2026-09-07 文档审查口径）**：现有 JUnit XML 报告记录 39 项测试全绿，README 记录
|
||||
dev stub 进程级冒烟曾通过；
|
||||
本轮因沙箱无法写用户级 Gradle 缓存，未重新证明该结果。当前已有 JDBC PG 仓储、共享信箱适配器
|
||||
与 InboxPoller 初版，但没有覆盖跨库补偿和 PG 本地事务的集成验证。**dev stub 冒烟路径**可端到端
|
||||
（`./gradlew run` 无外部依赖启动 → compat HTTP 写路径返回 200 → `/health` UP，修复记录见 README「进程级 dev 冒烟」）；
|
||||
生产默认配置**不可对外服务**——`autostart=false` 且生产（stubs=false）下仓储无实装、DI 装配
|
||||
即失败。生产就绪前置：U05（数据层+事务）、U07 fail-fast 定案、U09（快照恢复协议）、
|
||||
生产默认配置**不会启动处理管道**（`autostart=false`，数据源/信箱也默认 disabled）。生产就绪前置：
|
||||
U05（事务、补偿、出站与集成验证）、U07 fail-fast 定案、U09（快照恢复协议）、
|
||||
U13（投递毒丸补全）、U15（统一序号）。逐项状态见 ACM2-10「定稿实施计划」。
|
||||
|
||||
## 8. 部署与安全姿态
|
||||
|
||||
Reference in New Issue
Block a user