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 排期,本次仅按文档职责如实标注,未改动实现。
This commit is contained in:
windyboy
2026-09-07 07:39:57 +08:00
parent f0411da5fa
commit 7e3bf383a5
7 changed files with 99 additions and 29 deletions
+10 -5
View File
@@ -28,7 +28,7 @@
| 权威存储 | Redis(阶段 A | flightInfo hash;仅主泵线程写(I5);Lua 脚本原子覆盖 |
| 投递 | Kafkaacks=all + 幂等) | outbox 模式,经 MSG_EVENT 表中转 |
| 投影(阶段 B | Elasticsearch + Redis 投影 + FLIGHT_STATE | 仅阶段 B 启用(`msgx.phase` |
| 注册中心 | EurekaMicronaut 原生键) | 服务名契约 `msgexchangeapi`(影子 `msgexchangeapi-shadow` |
| 注册中心 | EurekaMicronaut 原生键) | 服务名契约 `msgexchangeapi`(影子 `msgexchangeapi-shadow`——**U17 未落地**:当前注册名仍取 `micronaut.application.name`=msgexchange-nextgen),`msgx.service-name` 无运行时消费方(见 §8 与 design.md §9 |
| 可观测 | logstash TCPAsync 包装)+ MDC traceId + 自定义健康指示器 | 见 [design.md §8](design.md) |
## 3. 总体拓扑
@@ -117,7 +117,8 @@
| A`msgx.phase=A` | Redis flightInfo | KAFKA:msg、KAFKA:schd | 管道骨架+重试闭环已实装;Redis Lua/实仓储属 U05/U09 |
| B`msgx.phase=B` | FLIGHT_STATE + 投影 | + ES:flight_hts、REDIS:flightInfo | 未实施(阶段 2 后) |
**就绪度(诚实口径,2026-09-06**:可编译、可测试(37 测试全绿、dev stub 冒烟可端到端
**就绪度(2026-09-07 复核口径**:可编译、37 测试全绿、**dev stub 进程级冒烟实测可端到端**
`./gradlew run` 无外部依赖启动 → 收报 200 → `/health` UP,修复记录见 README「进程级 dev 冒烟」);
生产默认配置**不可对外服务**——`autostart=false` 且生产(stubs=false)下仓储无实装、DI 装配
即失败。生产就绪前置:U05(数据层+事务)、U07 fail-fast 定案、U09(快照恢复协议)、
U13(投递毒丸补全)、U15(统一序号)。逐项状态见 ACM2-10「定稿实施计划」。
@@ -125,11 +126,15 @@ U13(投递毒丸补全)、U15(统一序号)。逐项状态见 ACM2-10「
## 8. 部署与安全姿态
- **实例数 = 1**(主泵单写者前提);双实例误配当前无运行期防护(U26:租约/DB 锁 + 拒启,未实装)。
- **影子隔离**:服务名(`msgexchangeapi-shadow`+ 独立 schema + Redis key 前缀 + 独立 topic
三层隔离;`msgx.register-eureka=false` 可脱离注册中心对拍。
- **影子隔离(目标态;U17/U26 未落地,勿按现状引用)**:服务名(`msgexchangeapi-shadow`+ 独立
schema + Redis key 前缀 + 独立 topic 三层隔离;当前代码仅 `msgx.register-eureka=false` 生效——
Kafka topic 写死字面量 `"msg"`/`"schd"`Dispatcher)、`FlightRedisClient.eval` 无 key 前缀参数、
服务名未接 `msgx.service-name`(§2)。
- **网络信任模型**`/cminmsgs/send` 无鉴权(沿用现役内网信任姿态);eureka default-zone
回退 `127.0.0.1:8761`;口令/端点全部环境变量外置(零入库)。安全节细化属 U28。
- **管理端点**`/env``/beans` 默认 sensitive,仅 dev/影子环境放开(`application-dev.yml`)。
- **管理端点**Micronaut 5.1 下 `/env` 默认**禁用**`/beans` 默认 enabled+sensitivedev/影子
顶层 `endpoints.*`**非** `micronaut.endpoints.*`——实测前缀错误时不生效)放开 `/env``/beans`
与 health 明细。工程未引入 micronaut-securitysensitive 的实际拦截行为待 U28 定案。
- **同名单风险**:影子与生产同名同路径会互相收报——切流前必须核对服务名三隔离。
## 9. 可观测性