docs(acm2-75): 按需求与架构收口契约和规范
补齐接口契约的入站、Redis 与出站边界,规范对齐已定语义并作废过期条款;Kafka 生产端约束编号改为 D2。 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -8,7 +8,7 @@ msgexchange-v2 是 OMMS H5 查询系统的消息网关,替换旧版 `msgexchan
|
||||
|
||||
功能需求是 [requirements.md](requirements.md) 的十四条用户故事(采集、处理、投递、查询、维护,`US-01`~`US-14`),运行需求是四条验收(单实例、可观测、测试隔离、切换回退,`OPS-1`~`OPS-4`)。不生成航班/业务数据类报文,不替代 CIIMS/AODB,不调用 admin-api;完整非目标见同文件「范围与非目标」。
|
||||
|
||||
- **主要入口**:轮询共享 MySQL 入站表 `CMINMSGS`,只取处理标记为空的行,按编号升序、每批有上限(`US-01`;`C-30`)。
|
||||
- **主要入口**:轮询共享 MySQL 入站表 `CMINMSGS`,只取处理时间为空的行,按编号升序、每批有上限(`US-01`;`C-30`)。
|
||||
- **兼容入口**:`POST /cminmsgs/send` 供联调工具把报文写进信箱,与上游投递走同一条处理路径;返回的编号只表示已进信箱,不代表已处理或下游已收到(`US-02`)。
|
||||
- **查询入口**:`GET /all/flights` 返回当前全部动态航班(不含共享航班),读 Redis,与网页客户端同源(`US-12`;`INV-24`)。
|
||||
- **出站**:只向 AODB 发参考数据请求 `RQRD` 和日计划请求 `RQFD`,经共享 MySQL 出站表 `COUTMSGS`,由 CIIMS adapter 消费;只保证请求写入信箱,不保证 AODB 收到(`US-09`;`C-24`)。
|
||||
@@ -41,7 +41,7 @@ delivery 投递 jobs 作业:回填 / 出站重试 / 历史清理 /
|
||||
|
||||
四组线程在同一进程、互不调用,协作只经自有 PG 的持久记录交接;HTTP 接口走事件循环,不占这四组线程。重启后各段从记录接着做,不依赖内存进度(`US-01` AC4、`US-03` AC3、`US-10` AC2)。
|
||||
|
||||
线程之间不加锁,靠幂等写入:收报按信箱编号只登记一次(`US-01` AC2)、回填只写空标记(`C-5`)、记录清理只删已回填且超过保留期的行(`INV-25`);发生竞争时后到的操作复查状态并重试。唯一的例外是处理消息的主循环(主泵)与航班历史清理之间要加锁(`INV-18`)。
|
||||
线程之间不加锁,靠幂等写入:收报按信箱编号只登记一次(`US-01` AC2)、回填只写空标记(`C-15`)、记录清理只删已回填且超过保留期的行(`INV-25`);发生竞争时后到的操作复查状态并重试。唯一的例外是处理消息的主循环(主泵)与航班历史清理之间要加锁(`INV-18`)。
|
||||
|
||||
运行边界:同一时刻只允许一个实例处理消息(`OPS-1`);切换与回退以信箱处理标记交接,本系统内部处理和回填进度保存在自有 PG 的 `PROC_STATE`,停旧启新时未处理的消息由旧系统继续(`OPS-4`);积压、处理失败、投递失败、回填失败各有指标与告警(`OPS-2`)。
|
||||
|
||||
@@ -63,7 +63,7 @@ delivery 投递 jobs 作业:回填 / 出站重试 / 历史清理 /
|
||||
|
||||
航班动态消息走满全链,其余类别只换其中几步:
|
||||
|
||||
1. **收报**:按「处理标记为空」发现信箱行,登记入队(`INV-2b`)。
|
||||
1. **收报**:按「处理时间为空」发现信箱行,登记入队(`INV-2b`)。
|
||||
2. **主泵**:按最小未完成 `MSG_ID` 取队头,解码,按业务身份去重(`INV-3`、`INV-9`);非法或不支持的报文无副作用,终态留档(`US-03`)。
|
||||
3. **事务一**:持 `PIPELINE_LOCK`,领域变更、未映射字段记录与待发事件一起提交。
|
||||
4. **投影**:写 Redis,写成功才算处理完成(`INV-23`);失败保持未完成、下轮重写投影,业务效果幂等(`US-03` AC3)。
|
||||
@@ -103,7 +103,7 @@ delivery 投递 jobs 作业:回填 / 出站重试 / 历史清理 /
|
||||
|---|---|---|
|
||||
| 自有 PostgreSQL | 处理锁 `PIPELINE_LOCK`、消息处理状态与回填意图 `PROC_STATE`、待发事件 `MSG_EVENT`、出站请求跟踪 `REQ_TRACK`、航班当前态 `FLIGHT_SCHD`、资源明细表、`FLIGHT_ROUTE_POINT`、未映射字段长期记录表 `UNMAPPED_FIELD`、静态参考数据 `REF_MASTER`、日计划快照留痕 `SCHD_SNAP_LOG` | 本系统唯一的业务数据库,也是航班当前态的唯一权威(`INV-11b`);本地事务只发生在这里,事务怎么分段见「主流程」。`UNMAPPED_FIELD` 不随 `PROC_STATE` 到期清理。 |
|
||||
| Redis | 航班查询投影 | 只作查询,不是权威,也不存处理状态(`INV-11b`);只由本系统写入和移除(`INV-24`),内容来自 PG 当前态;`GET /all/flights` 与网页客户端读的就是它。 |
|
||||
| 共享 MySQL | `CMINMSGS` 入站信箱、`COUTMSGS` 出站信箱 | 信箱归外部系统所有。本系统只读写消息、回写处理标记,不建表、不改表结构、不清数据、不写历史表(`C-14`);原文保留多久、何时清除由库方定(`C-5`~`C-12`、`Q7`、`Q9`)。出站请求写进去就算交付(`C-24`)。 |
|
||||
| 共享 MySQL | `CMINMSGS` 入站信箱、`COUTMSGS` 出站信箱 | 信箱归外部系统所有。本系统只读写消息、回写处理标记,不建表、不改表结构、不清数据、不写历史表(`C-14`);原文保留多久、何时清除由库方定(`C-6`~`C-9`、`Q7`、`Q9`)。出站请求写进去就算交付(`C-24`)。 |
|
||||
| 航班历史存储(Elasticsearch) | 已结束航班的历史副本 | 已结束航班写入这里作历史副本;写入确认成功后才删实时数据,写不成一条也不删(`D1`、`INV-28`)。保留期与容量上限未定(`G-FLIGHT-HIST-RETENTION`)。 |
|
||||
|
||||
**PG 的事务只管自己库。** Redis 写没写成、信箱标记写没写上、Kafka 发没发出,PG 事务都管不着;这些步骤各自可重试,重做多少遍结果都一样,重启后从 PG 记录接着走。
|
||||
|
||||
Reference in New Issue
Block a user