windyboy
8c8d2613c2
消除 doc/ vs docs/ 双目录混淆（git mv 保留历史）： - doc/msgexchange-api-legacy-user-stories.md → docs/legacy/ - doc/unisysaodbsis.xsd → docs/legacy/ - SIS_AODB_RMS-V0.1.md（根目录 703KB）→ docs/legacy/ - 删除空 doc/ 目录；README「文档」导航补充 docs/legacy/（外部参考/基线材料， 非本系统文档）；更新 README/architecture 与基线文档自引的路径引用。 docs/ 现为：architecture.md、design.md（自产）+ legacy/（legacy 拷贝参考）。
109 lines
7.6 KiB
Markdown
109 lines
7.6 KiB
Markdown
# msgexchange-v2（新一代消息交换服务）
|
||
|
||
依据 **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 系构件（如 micronaut-http-server-netty:5.1.10）
|
||
> 要求 JVM 25+，计划原定 JDK 21 不可行；工程已按 **JDK 25** 配置（ACMA-9 记录）。
|
||
|
||
## 包结构 → ACMA-8 架构映射
|
||
|
||
| 包 | 职责 | 对应 ACMA-8 |
|
||
|---|---|---|
|
||
| `ingress/` | Ingress & Inbox：收报（共享信箱落信 → 自有 PG 入队，ACM2-12），不解析报文 | 流程 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 装载、配置 | 数据模型节 |
|
||
|
||
## 资源
|
||
|
||
- `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 数据层实装**（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 入队」与处理回填的
|
||
外部副作用/补偿模型属 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`、出站写 `COUTMSGS`（他人读取发送）；表结构与保留策略归库方管理。收报前需确认
|
||
共享库 CMINMSGS 已存在（他人系统提供）；本仓库不声明其 schema。
|
||
|
||
- **事务模型**：与共享库交互均为外部副作用（ACM2-12）——收报=信箱落信成功（返回
|
||
CMINMSGS_ID）→ 自有 PG 建 PENDING 入队；处理成功回填 DATE_PROCESSED/STATUS 为最终一致。
|
||
- **快照 gen**：随航班动态同在 Redis（gen→Redis 协议属 U09，当前为过渡占位）。
|
||
- **阶段 B（FLIGHT_STATE）**：缓做不落表。
|
||
- 影子对拍：自有 PG 开独立 schema；共享信箱为单信箱无法双写，影子输入=只读水位/回放口径。
|
||
|
||
## 构建
|
||
|
||
```bash
|
||
./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` **无需任何环境变量/外部依赖**即可启动，
|
||
> `POST /cminmsgs/send`（application/json）返回记录 ID，`/health` UP。
|
||
> 已知边界：text/plain 收报 415 属 U16 缺口（契约对拍后固化）；测试侧端到端语义由
|
||
> PipelineSmokeTest（内嵌上下文）覆盖。
|
||
|
||
> 注解处理：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](docs/architecture.md)：架构速览——总体拓扑、模块职责、关键决策、
|
||
数据边界、部署与安全姿态、可观测性、就绪度（与代码同步维护）。
|
||
- [docs/design.md](docs/design.md)：设计细节——状态机与错误分类、数据模型、核心流程语义、
|
||
失败/重试/重放统一设计、不变量落点、参数表、测试策略、已知缺口（对照 ACM2-10）。
|
||
- [docs/legacy/](docs/legacy/)：外部参考/基线材料（自 legacy 仓库拷贝，非本系统文档）——
|
||
`msgexchange-api-legacy-user-stories.md`（行为对拍基线，ACMA-4）、`unisysaodbsis.xsd`、
|
||
`SIS_AODB_RMS-V0.1.md`（消息结构唯一事实源）。
|
||
|
||
## 关联
|
||
|
||
Plane `airport_chengdu_msgexchange_api`（**ACM2 为现行入口**）：ACM2-3（综合架构 v4，
|
||
架构权威，存储边界按 ACM2-11/12 修订）、ACM2-4（脚手架跟踪）、ACM2-10（评审与实施计划
|
||
U01–U30）、ACM2-11/12（存储边界与共享信箱决策）；ACMA 系列仅作归档历史/迁移来源
|
||
（ACMA-8 v4 / ACMA-6 选型 / ACMA-9 JDK 口径在归档中可溯）。
|