docs: 二轮审查文档收敛 ACM2-23～27（Kafka/依赖/ResponseDto/STATUS/格式）
This commit is contained in:
windyboy
@@ -83,6 +83,57 @@ PROC_STATE / MSG_EVENT / PUMP_JOB / REQ_TRACK / REF_MASTER（PG 方言）。全
|
||||
- **阶段 B（FLIGHT_STATE）**：缓做不落表。
|
||||
- 影子对拍：自有 PG 开独立 schema；共享信箱为单信箱无法双写，影子输入=只读水位/回放口径。
|
||||
|
||||
|
||||
## 本地开发依赖中间件栈（Podman / Docker Compose，ACM2-13）
|
||||
|
||||
仓库根目录提供兼容 Podman Compose 与 Docker Compose 的开发中间件栈 `compose.yaml`，包含：
|
||||
- **共享信箱 MySQL**（`mysql:8.4` LTS，端口 3306，库 `cdairport`）：容器启动时自动执行 `deploy/dev/mysql-init/01-mailbox.sql` 创建本地联调所需的 `CMINMSGS`、`CMINMSGS_HST`、`COUTMSGS` 模拟表。
|
||||
- **自有 PostgreSQL**（`postgres:17-alpine`，端口 5432，库 `msgx`）：容器提供干净数据库，应用启动时由 Flyway（`db/migration/V1.0.0__own_pg_pipeline.sql`）自动建自有表。
|
||||
- **Redis / 动态与快照**（开源分叉 `valkey/valkey:8-alpine`，端口 6379）：100% 兼容 Redis 7.2+ 协议与 Lua 脚本，支持 `--appendonly yes`。
|
||||
- **Kafka**（`apache/kafka:3.8.0` KRaft 单节点，端口 9092）：listener `PLAINTEXT://localhost:9092`，`default.replication.factor=1`，已预配幂等生产者与 acks=all 所需的单节点参数。
|
||||
|
||||
### 快速启动
|
||||
|
||||
```bash
|
||||
# 1. 复制环境变量示例（可按需修改口令与端口）
|
||||
cp .env.example .env
|
||||
|
||||
# 2. 启动开发依赖栈（支持 docker compose 或 podman compose）
|
||||
docker compose up -d
|
||||
|
||||
# 3. 检查各服务健康状态（均为 healthy）
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
### 环境变量与应用映射
|
||||
|
||||
| 环境变量 | 说明 | 示例默认值 | 应用配置映射（application.yml） |
|
||||
|---|---|---|---|
|
||||
| `MSGX_MAILBOX_URL` | 共享信箱 MySQL JDBC URL | `jdbc:mysql://localhost:3306/cdairport?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai&characterEncoding=utf8mb4` | `mailbox.shared-mysql.url` |
|
||||
| `MSGX_MAILBOX_USER` | 共享信箱 MySQL 用户名 | `msgx_dev` | `mailbox.shared-mysql.username` |
|
||||
| `MSGX_MAILBOX_PASSWORD` | 共享信箱 MySQL 密码 | `msgx_dev_pass` | `mailbox.shared-mysql.password` |
|
||||
| `MSGX_PG_URL` | 自有 PostgreSQL JDBC URL | `jdbc:postgresql://localhost:5432/msgx` | `datasources.default.url` |
|
||||
| `MSGX_PG_USER` | 自有 PostgreSQL 用户名 | `msgx_dev` | `datasources.default.username` |
|
||||
| `MSGX_PG_PASSWORD` | 自有 PostgreSQL 密码 | `msgx_dev_pass` | `datasources.default.password` |
|
||||
| `MSGX_REDIS_URI` | Redis/Valkey 连接串 | `redis://localhost:6379` | `redis.uri` |
|
||||
| `MSGX_KAFKA_SERVERS` | Kafka bootstrap brokers | `localhost:9092` | `kafka.bootstrap.servers` |
|
||||
| `MSGX_KAFKA_ACKS` | 生产确认级别 | `all` | `kafka.producers.default.acks` |
|
||||
| `MSGX_KAFKA_IDEMPOTENCE` | 幂等生产者开关 | `true` | `kafka.producers.default.enable-idempotence` |
|
||||
| `MSGX_KAFKA_MAX_IN_FLIGHT` | 单连接最大在途请求数 | `1` | `kafka.producers.default.max-in-flight-requests-per-connection` |
|
||||
|
||||
### 切流前 Kafka Broker 版本确认
|
||||
|
||||
生产契约以 `user-stories.md` US-07 / §7-6 为准：对接 Kafka 2.8+ / 3.x+，生产者强制 `acks=all`、`enable.idempotence=true` 与 `max.in.flight.requests.per.connection=1`，**严禁非幂等降级**。README 不提供生产降级环境变量组合。
|
||||
|
||||
旧系统 `msgexchange-api` 底层依赖 `kafka-clients:0.10.1.1`；现网 Broker 确切版本须在切流前实测确认：
|
||||
|
||||
1. **版本探测**：切流前通过本栈工具探测目标集群 API 能力：
|
||||
```bash
|
||||
docker exec msgx-dev-kafka /opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server <TARGET_IP>:9092
|
||||
```
|
||||
2. **门禁判定**：若输出中 `InitProducerId(22)` 为 **可用** → 保持现代高可靠默认（`acks=all`、`idempotence=true`、`max.in.flight=1`）。
|
||||
3. **阻塞切流**：若 `InitProducerId(22)` 为 **UNSUPPORTED**（Broker < 0.11）→ **阻塞切流**，须升级 Broker 或经架构豁免（ACM2-1 基础设施升级门禁）；降级参数仅可作为经批准的 runbook 附录，**不得**作为生产验收口径与 README 默认配置并存。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
@@ -99,10 +150,9 @@ MICRONAUT_ENVIRONMENTS=dev ./gradlew run # dev stub 冒烟：内存 stub，无
|
||||
> `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 尚未覆盖。
|
||||
> 已知边界：text/plain compat 写 415 属 U16 缺口（契约对拍后固化）；`application-dev.yml` 数据源配置
|
||||
> 已对齐为自有 PG 与共享 MySQL 信箱（ACM2-12/13）；测试侧端到端语义由 PipelineSmokeTest
|
||||
> （内嵌上下文，compat 写路径）覆盖。**生产主路径**（JDBC 轮询 `InboxPoller`）属 U05，dev stub 尚未覆盖。
|
||||
|
||||
> 注解处理：Kotlin 侧经 KSP（`kotlin-ksp` + `micronaut-inject-kotlin`）生成 Micronaut
|
||||
> BeanDefinition（U01）；若 build 产物缺少 `*$Definition` 类，先检查 KSP 是否生效。
|
||||
@@ -114,7 +164,11 @@ MICRONAUT_ENVIRONMENTS=dev ./gradlew run # dev stub 冒烟：内存 stub，无
|
||||
- [docs/architecture.md](docs/architecture.md)：架构速览——**中间件定位**、总体拓扑（JDBC 轮询主路径）、
|
||||
上下游边界、模块职责、关键决策、数据边界、部署与安全姿态、可观测性、就绪度。
|
||||
- [docs/design.md](docs/design.md)：设计细节——系统边界、状态机与错误分类、数据模型、
|
||||
核心流程语义（流程 1 主/compath 分述）、失败/重试/重放、不变量落点、参数表、已知缺口。
|
||||
核心流程语义（流程 1 主路径/compat 分述）、失败/重试/重放、不变量落点、参数表、已知缺口。
|
||||
- [docs/user-stories.md](docs/user-stories.md)：阶段 A US-01～US-14、延后清场 US-15、上线 Epic、
|
||||
legacy HTTP 去留及逐项文档 TODO；包含验收标准、依赖、实现差距与待确认问题。
|
||||
- [docs/user-stories-todo.md](docs/user-stories-todo.md)：ACM2-15～22 对应的文档整改清单、
|
||||
已完成落点、待 Plane/产品确认事项与验证门禁。
|
||||
- [docs/legacy/](docs/legacy/)：外部参考/基线材料（自 legacy 仓库拷贝，非本系统文档）——
|
||||
`msgexchange-api-legacy-user-stories.md`（legacy 行为对拍基线，ACMA-4）、`unisysaodbsis.xsd`、
|
||||
`SIS_AODB_RMS-V0.1.md`（消息结构唯一事实源；CIIMS 中间件交换模型）。
|
||||
|
||||
Reference in New Issue
Block a user