windy/msgexchange-v2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
7e3bf383a558cbc6247718820a0f5969b06e5f4b
msgexchange-v2/README.md
T
windyboy 7e3bf383a5 docs+fix: 文档回到代码事实；修复 dev 冒烟使其真正可跑（ACM2-10 复核意见落地） 
实测过程发现并修复四层问题，随后全部按实测结果校订文档：

- build.gradle.kts：补 application.mainClass（Kotlin 顶层 main → ApplicationKt）。
  此前 ./gradlew run 报 "No main class specified"，installDist 启动脚本主类为空（Dockerfile 不可运行）。
- application-dev.yml：stub 模式真正免基础设施——
  * datasources.default.enabled=false（micronaut-jdbc JdbcDataSourceEnabled 条件排除 DataSource，
    原注释"stub 不建连"意图未实现，DataSource eager 强制连 MySQL 导致启动失败）；
  * 关闭 micronaut 自带 Redis/Kafka 健康指示器（无 broker 时装配即把 /health 打成 500）；
  * 端点配置前缀修正：micronaut.endpoints.* 是死配置（/env 404、/beans 401 实测），
    正确为顶层 endpoints.*（env 默认禁用 / beans 默认 enabled+sensitive 一并注明）；
  * 关闭 eureka discovery，避免无注册中心时 /health 变 DOWN。
  验证：MICRONAUT_ENVIRONMENTS=dev ./gradlew run 无任何 env/外部依赖启动 → POST /cminmsgs/send
  200 返回 ID → /health UP；text/plain 415（U16 缺口实证）。37 测试全绿未受影响。
- README/docs/architecture.md/docs/design.md：按实测与复核意见校订——
  * README：dev 冒烟命令恢复为"无需 DB/Redis/Kafka"，记录修复缘由；
  * architecture：U17 服务名未落地（注册名仍取 micronaut.application.name=msgexchange-nextgen，
    msgx.service-name 无消费方）、三层隔离为目标态（仅 register-eureka=false 生效）、
    管理端点 5.1 实际口径（/env 默认禁用、/beans 默认 enabled+sensitive）、就绪度口径更新；
  * design：§9 补 U17 行；smoke 路径 UNSUPPORTED→CODEC_ERROR 修正；毒丸 head-deadline 判据不可达、
    快照 CAS 崩溃重放二次自增版本等"代码行为≠文档声明"处加实现注；I1 状态行同步。
- gradle/libs.versions.toml + gradle.properties：版本矩阵注释按依赖解析实测修正
  （platform 5.1.3 生效但 core 系解析 5.1.13，classpath 混用；原"5.1.10 无平台 BOM"说法与观测不符）。

未提交内容：无。代码级缺陷（毒丸判据、CAS 重放、DNLD 路由顺序、identity 键释放等）仍属
ACM2-10 排期，本次仅按文档职责如实标注，未改动实现。
2026-09-07 07:39:57 +08:00

95 lines
6.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 冒烟：内存 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）。
## 关联
Plane `airport_chengdu_msgexchange_api`（**ACM2 为现行入口**）：ACM2-3（综合架构 v4，
架构权威）、ACM2-4（脚手架跟踪）、ACM2-10（评审与实施计划 U01–U30）；ACMA 系列仅作
归档历史/迁移来源（ACMA-8 v4 / ACMA-6 选型 / ACMA-9 JDK 口径在归档中可溯）。
Reference in New Issue View Git Blame Copy Permalink