docs: 统一中间件定位与 JDBC 轮询主路径口径

Align README, architecture, design, config comments, and ingress docs with the upstream message-processing middleware model: external CIIMS write to CMINMSGS, JDBC poll as production ingress, HTTP /cminmsgs/send as compat. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 10:27:44 +08:00
parent 8c8d2613c2
commit 7ccdd00a31
13 changed files with 198 additions and 94 deletions
@@ -1,26 +1,42 @@
-# msgexchange-v2（新一代消息交换服务）
+# msgexchange-v2（机场上游报文处理中间件）
+
+**系统角色**：消费 CIIMS/AODB 等上游经共享 MySQL 信箱（`CMINMSGS`）投递的 XML 报文，
+解析处理后维护 Redis 航班动态并向 Kafka / 出站信箱投递——**中间件**，非报文源系统。

 依据 **ACMA-8 v4 综合架构**（单写者严格 FIFO 管道）与 **ACMA-6 技术选型**
-（Micronaut 5.1 + Kotlin 2.3）搭建的新一代消息交换服务工程；**存储边界与阶段 B 按
-ACM2-11/ACM2-12 定案**（自有 PostgreSQL 全内部状态 + 共享 MySQL 仅信箱 + Redis 动态/gen，
-阶段 B 缓做）。本仓库独立于 legacy `msgexchange-api`（Java 8 / Spring Boot 1.5 / Maven）——
+（Micronaut 5.1 + Kotlin 2.3）搭建；**存储边界与阶段 B 按 ACM2-11/ACM2-12 定案**
+（自有 PostgreSQL 全内部状态 + 共享 MySQL 仅信箱 + Redis 动态/gen，阶段 B 缓做）。
+本仓库独立于 legacy `msgexchange-api`（Java 8 / Spring Boot 1.5 / Maven）——
 过渡期两套系统并存（影子对拍→切流→旧仓库冻结），legacy 维护不受本仓库影响。

-> **JDK 口径实测修正**：Micronaut 5.1 系构件（如 micronaut-http-server-netty:5.1.10）
-> 要求 JVM 25+，计划原定 JDK 21 不可行；工程已按 **JDK 25** 配置（ACMA-9 记录）。
+> **JDK 口径实测修正**：Micronaut 5.1 系构件要求 **JVM 25+**（`./gradlew :dependencies` 实测
+> core 系解析 **5.1.13**，platform BOM **5.1.3**，classpath 混用）；计划原定 JDK 21 不可行；
+> 工程已按 **JDK 25** 配置（ACMA-9 记录）。
+
+## 系统边界
+
+| 方向 | 机制 | 说明 |
+|---|---|---|
+| **入站（主路径）** | JDBC 轮询共享 `CMINMSGS` | 上游经 CIIMS 等**外部系统**写信箱；本系统 1s 轮询 `DATE_PROCESSED IS NULL` 发现新信 → 自有 PG 入队（`InboxPoller`，U05） |
+| **入站（compat）** | HTTP `POST /cminmsgs/send` | 手工注入/影子对拍；写信箱 + PG 入队，**非**生产主拓扑 |
+| **处理** | 主泵 FIFO 管道 | 解码 → identity → Handler 决策 → Redis 动态权威态 |
+| **出站** | Kafka + `COUTMSGS` | 向下游推送 msg/schd；请求类报文写出站信箱 |
+
+与 SIS / legacy 一致：本系统**不**替代 CIIMS 落信，**不**生成原始 AODB 业务报文。

 ## 包结构 → ACMA-8 架构映射

 | 包 | 职责 | 对应 ACMA-8 |
 |---|---|---|
-| `ingress/` | Ingress & Inbox：收报（共享信箱落信 → 自有 PG 入队，ACM2-12），不解析报文 | 流程 1，I3 |
+| `ingress/` | Ingress & Inbox：JDBC 轮询共享信箱发现新信 → 自有 PG 入队（+ HTTP compat 写路径），不解析报文 | 流程 1，I3 |
 | `processing/` | Processing 主泵：严格 FIFO 领取、identity 绑定、纯函数决策、事务2 | 流程 2/4，I1/I2/I5 |
 | `delivery/` | Delivery & Projection：每 target 严格 FIFO 投递、schd 聚合 | 流程 3 |
 | `reference/` | Reference & Query：21 类同步 + 15 类请求状态机 | 流程 6 |
 | `jobs/` | 泵作业：ARCHIVE / HISTORY_SWEEP / PROJECTION_REBUILD | 流程 4/5/7，I4 |
 | `codec/` | XML codec（阶段 1 先 vendor 复用 legacy POJO，见 ACMA-6 选型） | 决策 4 前置 |
 | `domain/` | 领域模型：Decision、事件、状态机枚举、Phase 开关 | I1–I5 |
-| `infra/` | 仓储接口、Redis Lua 装载、配置 | 数据模型节 |
+| `config/` | `PipelineProps` 参数表（ACMA-8 参数初值，`msgx.*`） | — |
+| `infra/` | 仓储接口、Redis Lua 装载、stub、健康、重试策略 | 数据模型节 |

 ## 资源

@@ -43,11 +59,11 @@ ACM2-11/ACM2-12 定案**（自有 PostgreSQL 全内部状态 + 共享 MySQL 仅
   阶段 1 后续项。
 3. **依赖版本锁定**：`gradle/libs.versions.toml` 中版本为计划口径，需阶段 0
   「Micronaut×现网 Eureka 互操作冒烟 + logstash + ES REST」通过后固化。
-4. **自有 PG 数据层实装**（ACM2-12）：`infra/persistence/Repositories.kt` 目前是接口
-   （Micronaut Data JDBC on PG + 信箱适配层 CminmsgMailbox/OutboxMailbox 属 U05 批次），
-   主泵/调度循环以接口驱动，纯逻辑已抽离可单测。
-5. **信箱适配层与共享库边界**（ACM2-12）：CMINMSGS 收 / COUTMSGS 出为共享 MySQL 仅 DML
-   （mailbox.shared-mysql 配置段已占位）；收报「信箱落信 → PG 入队」与处理回填的
+4. **自有 PG 数据层 + InboxPoller**（ACM2-12）：`infra/persistence/Repositories.kt` 目前是接口
+   （Micronaut Data JDBC on PG + 信箱适配层 CminmsgMailbox/OutboxMailbox + JDBC 轮询入队
+   属 U05 批次），主泵/调度循环以接口驱动，纯逻辑已抽离可单测。
+5. **信箱适配层与共享库边界**（ACM2-12）：上游外部写 `CMINMSGS`；本系统 JDBC 轮询读 +
+   处理回填写；出站写 `COUTMSGS`（mailbox.shared-mysql 配置段已占位）；入队/回填的
   外部副作用/补偿模型属 U05 批次。

 ## 数据库初始化（ACM2-12 口径）
@@ -56,12 +72,13 @@ ACM2-11/ACM2-12 定案**（自有 PostgreSQL 全内部状态 + 共享 MySQL 仅
 PROC_STATE / MSG_EVENT / PUMP_JOB / REQ_TRACK / REF_MASTER（PG 方言）。全新库直接执行即可，
 无 legacy 前置。

-**共享 MySQL（cdairport，他人系统库）**：本系统**不建表/schema**，仅信箱 DML——收报写
-`CMINMSGS`、出站写 `COUTMSGS`（他人读取发送）；表结构与保留策略归库方管理。收报前需确认
-共享库 CMINMSGS 已存在（他人系统提供）；本仓库不声明其 schema。
+**共享 MySQL（cdairport，他人系统库）**：本系统**不建表/schema**，仅信箱 DML——上游外部写
+`CMINMSGS`；本系统 JDBC 轮询读 + 处理回填；出站写 `COUTMSGS`（他人读取发送）；表结构与
+保留策略归库方管理。部署前需确认共享库 CMINMSGS 已存在（他人系统提供）；本仓库不声明其 schema。

- **事务模型**：与共享库交互均为外部副作用（ACM2-12）——收报=信箱落信成功（返回
-  CMINMSGS_ID）→ 自有 PG 建 PENDING 入队；处理成功回填 DATE_PROCESSED/STATUS 为最终一致。
+- **事务模型**：与共享库交互均为外部副作用（ACM2-12）——主路径=上游外部写信箱 →
+  JDBC 轮询发现新信 → 自有 PG 建 PENDING 入队（失败重扫补建）；HTTP `/cminmsgs/send`
+  为 compat 写路径；处理成功回填 DATE_PROCESSED/STATUS 为最终一致。
 - **快照 gen**：随航班动态同在 Redis（gen→Redis 协议属 U09，当前为过渡占位）。
 - **阶段 B（FLIGHT_STATE）**：缓做不落表。
 - 影子对拍：自有 PG 开独立 schema；共享信箱为单信箱无法双写，影子输入=只读水位/回放口径。
@@ -81,9 +98,11 @@ MICRONAUT_ENVIRONMENTS=dev ./gradlew run   # dev stub 冒烟：内存 stub，无
 > /health 拖成 500（dev 关闭 redis.health/kafka.health，健康由自定义指示器承担）；管理端点前缀误用
 > `micronaut.endpoints.*`（正确为顶层 `endpoints.*`，/env、/beans 这才真正放开）；另关闭 eureka
 > discovery。当前 `MICRONAUT_ENVIRONMENTS=dev ./gradlew run` **无需任何环境变量/外部依赖**即可启动，
-> `POST /cminmsgs/send`（application/json）返回记录 ID，`/health` UP。
-> 已知边界：text/plain 收报 415 属 U16 缺口（契约对拍后固化）；测试侧端到端语义由
-> PipelineSmokeTest（内嵌上下文）覆盖。
+> compat HTTP `POST /cminmsgs/send`（application/json）返回记录 ID，`/health` UP。
+> 已知边界：text/plain compat 写 415 属 U16 缺口（契约对拍后固化）；`application-dev.yml` 中
+> `datasources.default.url` 仍为 MySQL 占位（ACM2-12 前残留，stub 下 `enabled=false` 不建连，
+> U05 清理为 PG 口径）；测试侧端到端语义由 PipelineSmokeTest（内嵌上下文，compat 写路径）覆盖。
+> **生产主路径**（JDBC 轮询 `InboxPoller`）属 U05，dev stub 尚未覆盖。

 > 注解处理：Kotlin 侧经 KSP（`kotlin-ksp` + `micronaut-inject-kotlin`）生成 Micronaut
 > BeanDefinition（U01）；若 build 产物缺少 `*$Definition` 类，先检查 KSP 是否生效。
@@ -92,17 +111,17 @@ MICRONAUT_ENVIRONMENTS=dev ./gradlew run   # dev stub 冒烟：内存 stub，无

 ## 文档

- [docs/architecture.md](docs/architecture.md)：架构速览——总体拓扑、模块职责、关键决策、
-  数据边界、部署与安全姿态、可观测性、就绪度（与代码同步维护）。
- [docs/design.md](docs/design.md)：设计细节——状态机与错误分类、数据模型、核心流程语义、
-  失败/重试/重放统一设计、不变量落点、参数表、测试策略、已知缺口（对照 ACM2-10）。
+- [docs/architecture.md](docs/architecture.md)：架构速览——**中间件定位**、总体拓扑（JDBC 轮询主路径）、
+  上下游边界、模块职责、关键决策、数据边界、部署与安全姿态、可观测性、就绪度。
+- [docs/design.md](docs/design.md)：设计细节——系统边界、状态机与错误分类、数据模型、
+  核心流程语义（流程 1 主/compath 分述）、失败/重试/重放、不变量落点、参数表、已知缺口。
 - [docs/legacy/](docs/legacy/)：外部参考/基线材料（自 legacy 仓库拷贝，非本系统文档）——
-  `msgexchange-api-legacy-user-stories.md`（行为对拍基线，ACMA-4）、`unisysaodbsis.xsd`、
-  `SIS_AODB_RMS-V0.1.md`（消息结构唯一事实源）。
+  `msgexchange-api-legacy-user-stories.md`（legacy 行为对拍基线，ACMA-4）、`unisysaodbsis.xsd`、
+  `SIS_AODB_RMS-V0.1.md`（消息结构唯一事实源；CIIMS 中间件交换模型）。

 ## 关联

-Plane `airport_chengdu_msgexchange_api`（**ACM2 为现行入口**）：ACM2-3（综合架构 v4，
-架构权威，存储边界按 ACM2-11/12 修订）、ACM2-4（脚手架跟踪）、ACM2-10（评审与实施计划
-U01–U30）、ACM2-11/12（存储边界与共享信箱决策）；ACMA 系列仅作归档历史/迁移来源
+Plane **`airport_chengdu_msgexchange_v2`（ACM2，现行入口）**：ACM2-3（综合架构 v4，
+架构权威，存储边界按 ACM2-12 修订；ACM2-11 为决策史）、ACM2-4（脚手架跟踪）、ACM2-10（评审与实施计划
+U01–U30）、ACM2-12（存储边界与共享信箱决策）；ACMA 系列仅作归档历史/迁移来源
 （ACMA-8 v4 / ACMA-6 选型 / ACMA-9 JDK 口径在归档中可溯）。