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）—— 过渡期两套系统并存（影子对拍→切流→旧仓库冻结），legacy 维护不受本仓库影响。

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：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
config/	PipelineProps 参数表（ACMA-8 参数初值，msgx.*）	—
infra/	仓储接口、Redis Lua 装载、stub、健康、重试策略	数据模型节

资源

• docs/legacy/SIS_AODB_RMS-V0.1.md + docs/legacy/unisysaodbsis.xsd：消息结构唯一事实源 （wire 契约冻结，自 legacy 仓库复制以自包含；codec 实装依据，ACM2-2/ACM2-3）。
• db/migration/V1.0.0__own_pg_pipeline.sql：自有 PostgreSQL（唯一自有库）表结构 （PROC_STATE / MSG_EVENT / PUMP_JOB / REQ_TRACK / REF_MASTER，PG 方言），ACM2-12 定案； 共享 MySQL（CMINMSGS/COUTMSGS）仅信箱 DML 不建表；快照 gen 与航班动态在 Redis。
• lua/snapshot_replace.lua：同一 hash 原子“覆盖新代 + 按代差删”（流程 4，I4/I5； 随 gen→Redis 协议（U09）扩展版本推进）。
• lua/batch_delete.lua：3:30 清场批量删除（仅 ES 写成功集，I4）。
• application.yml：口令全部环境变量外置（零入库）；datasources.default=自有 PG（enabled=false 待 U05）、mailbox.shared-mysql=共享信箱；msgx.phase 权威口径（A 现役；B 缓做）； pipeline 参数 = ACMA-8 参数表初值。

未完成（按计划属于后续阶段，不是本脚手架遗漏）

1. Handler 业务（3+29）：processing/HandlerRegistry 仅注册骨架，翻译属阶段 2/3。
2. codec 实装：vendor 复用 legacy entity/msg POJO + Jackson XML（ACMA-6 选型）， 阶段 1 后续项。
3. 依赖版本锁定：gradle/libs.versions.toml 中版本为计划口径，需阶段 0 「Micronaut×现网 Eureka 互操作冒烟 + logstash + ES REST」通过后固化。
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 口径）

自有 PostgreSQL（唯一自有库）：db/migration/V1.0.0__own_pg_pipeline.sql 建 PROC_STATE / MSG_EVENT / PUMP_JOB / REQ_TRACK / REF_MASTER（PG 方言）。全新库直接执行即可， 无 legacy 前置。

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

• 事务模型：与共享库交互均为外部副作用（ACM2-12）——主路径=上游外部写信箱 → JDBC 轮询发现新信 → 自有 PG 建 PENDING 入队（失败重扫补建）；HTTP /cminmsgs/send 为 compat 写路径；处理成功回填 DATE_PROCESSED/STATUS 为最终一致。
• 快照 gen：随航班动态同在 Redis（gen→Redis 协议属 U09，当前为过渡占位）。
• 阶段 B（FLIGHT_STATE）：缓做不落表。
• 影子对拍：自有 PG 开独立 schema；共享信箱为单信箱无法双写，影子输入=只读水位/回放口径。

构建

./gradlew build          # 需网络拉取依赖；内网环境见 gradle.properties 注释
./gradlew test           # 纯逻辑单测（identity / schd 聚合 / 配置绑定 / 管道语义）
MICRONAUT_ENVIRONMENTS=dev ./gradlew run   # dev stub 冒烟：内存 stub，无需 DB/Redis/Kafka/Eureka

进程级 dev 冒烟（2026-09-07 修复并实测通过）：此前 ./gradlew run 因未声明 application.mainClass 报 "No main class specified"（已补，见 build.gradle.kts）；随后实测又暴露 dev profile 三处装配问题并已修复（application-dev.yml）：stub 模式未排除 DataSource （datasources.default.enabled=false）；micronaut 自带 Redis/Kafka 健康指示器在无 broker 时把 /health 拖成 500（dev 关闭 redis.health/kafka.health，健康由自定义指示器承担）；管理端点前缀误用 micronaut.endpoints.*（正确为顶层 endpoints.*，/env、/beans 这才真正放开）；另关闭 eureka discovery。当前 MICRONAUT_ENVIRONMENTS=dev ./gradlew run 无需任何环境变量/外部依赖即可启动， 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 是否生效。 dev/shadow 冒烟装配：msgx.stubs=true（内存仓储/适配层，见 infra/stub）+ msgx.pipeline.autostart=true（PipelineLifecycle 拉起专用线程，U07）；生产默认两者关闭。

文档

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

关联

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 口径在归档中可溯）。