docs(acm2-75): 按需求与架构收口契约和规范

补齐接口契约的入站、Redis 与出站边界,规范对齐已定语义并作废过期条款;Kafka 生产端约束编号改为 D2。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
windyboy
2026-09-16 08:49:19 +08:00
co-authored by Cursor
parent 7cd17409f5
commit fd65bb24fb
12 changed files with 327 additions and 266 deletions
+4 -4
View File
@@ -16,7 +16,7 @@
| 方向 | 机制 | 说明 |
|---|---|---|
| **入站(主路径)** | JDBC 轮询共享 `CMINMSGS` | 上游经 CIIMS 等**外部系统**写信箱;本系统按轮询间隔读取水位之后的记录(`ID > W`**不以处理标记为谓词**)→ 自有 PG 入队(`InboxPoller` |
| **入站(主路径)** | JDBC 轮询共享 `CMINMSGS` | 上游经 CIIMS 等**外部系统**写信箱;本系统按轮询间隔读取「处理时间为空」的行,按编号升序、每批有上限(`C-30`)→ 自有 PG 入队(`InboxPoller` |
| **入站(compat** | HTTP `POST /cminmsgs/send` | 手工注入/影子对拍;写信箱 + PG 入队,**非**生产主拓扑 |
| **处理** | 主泵 FIFO 管道 | 解码 → identity → Handler 决策 → PostgreSQL 航班当前态 / 静态参考数据 |
| **出站** | Kafka + `COUTMSGS` | 向下游推送 msg/schd;请求类报文写出站信箱 |
@@ -106,7 +106,7 @@ docker compose ps
### 切流前 Kafka Broker 版本确认
生产契约以 [requirements.md](docs/requirements.md) `US-07``D3` 为准(三项生产者约束的取值见 [reference.md](docs/reference.md) 参数表),**严禁非幂等降级**。README 不提供生产降级环境变量组合。
生产契约以 [requirements.md](docs/requirements.md) `US-08``D2` 为准(三项生产者约束的取值见 [reference.md](docs/reference.md) 参数表),**严禁非幂等降级**。README 不提供生产降级环境变量组合。
旧系统 `msgexchange-api` 底层依赖 `kafka-clients:0.10.1.1`;现网 Broker 确切版本须在切流前实测确认:
@@ -114,7 +114,7 @@ docker compose ps
```bash
docker exec msgx-dev-kafka /opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server <TARGET_IP>:9092
```
2. **门禁判定**:若输出中 `InitProducerId(22)` 为 **可用** → 保持 `D3` 的高可靠默认。
2. **门禁判定**:若输出中 `InitProducerId(22)` 为 **可用** → 保持 `D2` 的高可靠默认。
3. **阻塞切流**:若 `InitProducerId(22)` 为 **UNSUPPORTED**Broker &lt; 0.11)→ **阻塞切流**,须升级 Broker 或经架构豁免(ACM2-1 基础设施升级门禁);降级参数仅可作为经批准的 runbook 附录,**不得**作为生产验收口径与 README 默认配置并存。
## 构建
@@ -134,7 +134,7 @@ MICRONAUT_ENVIRONMENTS=dev ./gradlew run # dev stub 冒烟:内存 stub,无
`docs/` 是唯一设计依据;从 [设计文档入口](docs/README.md) 开始阅读(职责、事实归属、ID 语法与引用纪律都在那里)。顶层 6 个文件:
- [architecture.md](docs/architecture.md):系统边界、模块职责、存储归属、总体流程与 `D1``D4` 决策。
- [architecture.md](docs/architecture.md):系统边界、模块职责、存储归属、总体流程与 `D1``D2` 决策。
- [requirements.md](docs/requirements.md):阶段范围与非目标、`US-xx` / `OPS-x` 验收目标、需求覆盖与依赖。
- [specification.md](docs/specification.md):术语、契约 `C-x`、前提 `PRE-x`、不变量 `INV-x`、声明边界 `CLM-x`、待确认 `Q`、已知偏差 `G`、验证映射。
- [implementation.md](docs/implementation.md):管道机制、航班域与静态参考数据——数据模型、状态机、事务、投递、作业、恢复及合并语义。