windyboy
f0411da5fa
- architecture.md：系统定位与双跑策略、技术栈、总体拓扑（两条单线程管道）、 模块职责、关键决策 D1–D8、数据边界（六辅助表 vs legacy 旧表）、两阶段权威 与就绪度（诚实口径：生产默认不可服务，前置 U05/U07/U09/U13/U15）、 部署与安全姿态、可观测性。 - design.md：状态机与错误分类（含重放白名单）、六表数据模型（含 U18 已知缺口）、 流程 1–4 与泵作业语义、失败/重试统一设计（U08）、不变量 I1–I5 落点、 参数表、测试策略、可观测性、缺口清单对照 ACM2-10 U01–U30。 - README：新增文档导航；关联节按 ACM2-10 T16 修正改为 ACM2 现行入口 （ACM2-3 架构权威 / ACM2-4 脚手架 / ACM2-10 评审），ACMA 仅归档。
84 lines
5.4 KiB
Markdown
84 lines
5.4 KiB
Markdown
# msgexchange-v2（新一代消息交换服务）
|
||
|
||
依据 **ACMA-8 v4 综合架构**（单写者严格 FIFO 管道 + 两阶段权威）与 **ACMA-6 技术选型**
|
||
（Micronaut 5.1 + Kotlin 2.3）搭建的新一代消息交换服务工程。本仓库独立于 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：接收事务（事务1），不解析报文 | 流程 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 装载、配置 | 数据模型节 |
|
||
|
||
## 资源
|
||
|
||
- `SIS_AODB_RMS-V0.1.md` + `doc/unisysaodbsis.xsd`：**消息结构唯一事实源**（wire 契约冻结，
|
||
自 legacy 仓库复制以自包含；codec 实装依据，ACM2-2/ACM2-3）。
|
||
- `db/migration/V2.0.0__aux_tables.sql`：六表 DDL（PROC_STATE / MSG_EVENT / REF_DATA /
|
||
REQ_TRACK / PUMP_JOB / FLIGHT_STATE），与 ACMA-8 v4 数据模型节逐字一致；影子实例在
|
||
独立 schema 执行同一脚本。
|
||
- `lua/snapshot_replace.lua`：同一 hash 原子“覆盖新代 + 按代差删”（流程 4，I4/I5）。
|
||
- `lua/batch_delete.lua`：3:30 清场批量删除（仅 ES 写成功集，I4）。
|
||
- `application.yml`：口令全部环境变量外置（零入库）；`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. **仓储实装**：`infra/persistence/Repositories.kt` 目前是接口（Micronaut Data JDBC
|
||
实装属阶段 1 后续），主泵/调度循环以接口驱动，纯逻辑已抽离可单测。
|
||
|
||
## 数据库初始化（U04/R01，务必先读）
|
||
|
||
`db/migration/V2.0.0__aux_tables.sql` **只建六张辅助表**（PROC_STATE / MSG_EVENT / REF_DATA /
|
||
REQ_TRACK / PUMP_JOB / FLIGHT_STATE），并假定 `CMINMSGS`（及其历史表）等 legacy 旧表已存在——
|
||
迁移集是「现网 legacy 库的演进」而非「全新库初始化」。因此：
|
||
|
||
- **现网/影子演进**：在既有 `cdairport` 库（含 CMINMSGS）上执行即可，Flyway 会补跑 V2.0.0。
|
||
- **全新空库（本机/CI/演练/灾备重建）**：需先按 legacy 仓库（`airport_chengdu_msgexchange_api`）
|
||
建好 CMINMSGS/CMINMSGS_HST/COUTMSGS 等旧表（或从现网导出 schema），再启动本服务；否则
|
||
收报第一句 SQL 即报「表不存在」。影子实例在独立 schema 执行同一脚本时同样先建旧表。
|
||
- 为什么没有 CMINMSGS 的 V1 迁移：六表之外的旧 schema 归 legacy 仓库维护（冻结期），
|
||
本仓库不重复声明；若未来要求空库一键初始化，再补 V1 基线快照（见 ACM2-10 U04）。
|
||
|
||
## 构建
|
||
|
||
```bash
|
||
./gradlew build # 需网络拉取依赖；内网环境见 gradle.properties 注释
|
||
./gradlew test # 纯逻辑单测（identity / schd 聚合 / 配置绑定 / 管道语义）
|
||
MICRONAUT_ENVIRONMENTS=dev ./gradlew run # dev stub 冒烟：内存仓储 + 启动主泵/投递（无需 DB/Redis/Kafka）
|
||
```
|
||
|
||
> 注解处理：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）。
|
||
|
||
## 关联
|
||
|
||
Plane `airport_chengdu_msgexchange_api`（**ACM2 为现行入口**）：ACM2-3（综合架构 v4，
|
||
架构权威）、ACM2-4（脚手架跟踪）、ACM2-10（评审与实施计划 U01–U30）；ACMA 系列仅作
|
||
归档历史/迁移来源（ACMA-8 v4 / ACMA-6 选型 / ACMA-9 JDK 口径在归档中可溯）。
|