docs(acm2-75): 清理空转待决项并对齐全仓旧编号引用
- 删 Q2/Q15/Q19/Q20：时钟偏斜不进判据、实现自定已是结论、原文留存已定、 运营日冲突处置已由 DEAD(PROTOCOL) 定 - Q6 的 abdg 定案本版不提供；Q22 改为 13 类报文到 admin-api 实体表组的映射 （REF_MASTER 单表口径退位）；Q23 收窄为 SODT+FLID 幂等重试 - C-1 自清口径四方同步（requirements 非目标、US-03 AC2、architecture §6） - INV-2 吸收回填只写空值；§7 恢复 G-RESP-GUARD - architecture/implementation/README/V1/oracle/Kotlin/seed 中 40+ 处旧编号 按映射重指，check-docs 全绿
This commit is contained in:
windyboy
+16
-16
@@ -8,12 +8,12 @@ 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`；`INV-2b`）。
|
||||
- **主要入口**：轮询共享 MySQL 入站表 `CMINMSGS`，只取处理时间为空的行，按编号升序、每批有上限（`US-01`；`INV-1`）。
|
||||
- **兼容入口**：`POST /cminmsgs/send` 供联调工具把报文写进信箱，与上游投递走同一条处理路径；返回的编号只表示已进信箱，不代表已处理或下游已收到（`US-02`）。
|
||||
- **查询入口**：`GET /all/flights` 返回当前全部动态航班（不含共享航班），读 Redis，与网页客户端同源（`US-12`；`INV-24`）。
|
||||
- **查询入口**：`GET /all/flights` 返回当前全部动态航班（不含共享航班），读 Redis，与网页客户端同源（`US-12`；`INV-11`）。
|
||||
- **出站**：只向 AODB 发参考数据请求 `RQRD` 和日计划请求 `RQFD`，经共享 MySQL 出站表 `COUTMSGS`，由 CIIMS adapter 消费；只保证请求写入信箱，不保证 AODB 收到（`US-09`；`C-4`）。
|
||||
- **输出**：Kafka 主题 `msg` 发单条航班变更、`schd` 定时发批量最新状态；Redis 存航班投影；静态参考数据表供 admin-api 只读（`US-08`、`US-13`）。
|
||||
- **权威**：航班当前态的权威是自有 PostgreSQL（`FLIGHT_SCHD`、资源明细表、`FLIGHT_ROUTE_POINT`）；信箱、Redis、Kafka、展示视图都不是（`INV-11b`）。
|
||||
- **权威**：航班当前态的权威是自有 PostgreSQL（`FLIGHT_SCHD`、资源明细表、`FLIGHT_ROUTE_POINT`）；信箱、Redis、Kafka、展示视图都不是（`INV-5`）。
|
||||
- **航班历史**：已结束航班先写入 Elasticsearch 历史库，成功后才从实时数据删除（`US-14`；`D1`）。
|
||||
|
||||
测试环境用 PostgreSQL；生产环境用 PostgreSQL 还是 Oracle 11g 尚未确定，Oracle 适配验证通过前不作支持承诺（生产库选型见 `Q14`）。
|
||||
@@ -41,7 +41,7 @@ delivery 投递 jobs 作业：回填 / 出站重试 / 历史清理 /
|
||||
|
||||
四组线程在同一进程、互不调用，协作只经自有 PG 的持久记录交接；HTTP 接口走事件循环，不占这四组线程。重启后各段从记录接着做，不依赖内存进度（`US-01` AC4、`US-03` AC3、`US-10` AC2）。
|
||||
|
||||
线程之间不加锁，靠幂等写入：收报按信箱编号只登记一次（`US-01` AC2）、回填只写空标记（`C-15`）、记录清理只删已回填且超过保留期的行（`US-11`）；发生竞争时后到的操作复查状态并重试。主泵与航班历史清理对实时航班表的互斥是实现手段，用以落实「正在被消息处理的航班跳过」（`US-14` AC4）。
|
||||
线程之间不加锁，靠幂等写入：收报按信箱编号只登记一次（`US-01` AC2）、回填只写空标记（`INV-2`）、记录清理只删已回填且超过保留期的行（`US-11`）；发生竞争时后到的操作复查状态并重试。主泵与航班历史清理对实时航班表的互斥是实现手段，用以落实「正在被消息处理的航班跳过」（`US-14` AC4）。
|
||||
|
||||
运行边界：同一时刻只允许一个实例处理消息（`OPS-1`）；切换与回退以信箱处理标记交接，本系统内部处理和回填进度保存在自有 PG 的 `PROC_STATE`，停旧启新时未处理的消息由旧系统继续（`OPS-4`）；积压、处理失败、投递失败、回填失败各有指标与告警（`OPS-2`）。
|
||||
|
||||
@@ -54,7 +54,7 @@ delivery 投递 jobs 作业：回填 / 出站重试 / 历史清理 /
|
||||
| `ingress` | 轮询信箱、登记入队、兼容入口落信（`US-01`、`US-02`）；不解析业务报文。 |
|
||||
| `codec` | XML 解码，区分非法报文与可修复的解码失败（`US-03`）。 |
|
||||
| `processing` | FIFO 调度、业务身份绑定与去重、领域决策与落库（`SCHD`/`FLOP`/`FDEL`/`ADFT`/静态参考数据），航班类写 Redis 投影，未落到航班当前态的字段写 `UNMAPPED_FIELD`。 |
|
||||
| `delivery` | 读待发事件投 Kafka：按 `FLID` 保序、`schd` 聚合、失败重试（`US-08`；`C-29`）。 |
|
||||
| `delivery` | 读待发事件投 Kafka：按 `FLID` 保序、`schd` 聚合、失败重试（`US-08`；`C-9`）。 |
|
||||
| `jobs` | 回填扫描、出站请求重试、航班历史清理，以及 `PROC_STATE`、`MSG_EVENT`、`SCHD_SNAP_LOG`、`REQ_TRACK` 的到期清理；单独线程、不进 FIFO（与主泵的协作见 `US-14` AC4）。 |
|
||||
| `domain` / `config` | 领域状态、事件和决策模型，以及运行参数。 |
|
||||
| `infra` | 仓储（JDBC/stub）、外部适配器（共享信箱、Kafka、Redis、航班历史存储、AODB 出站）、重试、健康检查与日志；对其他模块只暴露接口。 |
|
||||
@@ -63,10 +63,10 @@ delivery 投递 jobs 作业：回填 / 出站重试 / 历史清理 /
|
||||
|
||||
航班动态消息走满全链，其余类别只换其中几步：
|
||||
|
||||
1. **收报**：按「处理时间为空」发现信箱行，登记入队（`INV-2b`）。
|
||||
1. **收报**：按「处理时间为空」发现信箱行，登记入队（`INV-1`）。
|
||||
2. **主泵**：按最小未完成 `MSG_ID` 取队头，解码，按业务身份去重（`US-03` AC1；implementation「消息、身份与决策」）；非法或不支持的报文无副作用，终态留档（`US-03`）。
|
||||
3. **事务一**：持 `PIPELINE_LOCK`，领域变更、未映射字段记录与待发事件一起提交。
|
||||
4. **投影**：写 Redis，写成功才算处理完成（`INV-23`）；失败保持未完成、下轮重写投影，业务效果幂等（`US-03` AC3）。
|
||||
4. **投影**：写 Redis，写成功才算处理完成（`INV-10`）；失败保持未完成、下轮重写投影，业务效果幂等（`US-03` AC3）。
|
||||
5. **事务二**：处理终态与回填意图一起提交。
|
||||
6. **回填**：作业把处理标记写回共享信箱（`US-10`）；写不上的记录在案并告警。
|
||||
7. **投递**：读待发事件发 `KAFKA:msg` / `KAFKA:schd`，至少一次（`C-9`）；一直失败的记录保留可查并告警（`US-08`）。
|
||||
@@ -86,14 +86,14 @@ delivery 投递 jobs 作业：回填 / 出站重试 / 历史清理 /
|
||||
|
||||
以下约束不得违反：
|
||||
|
||||
- 只跑一个实例；主泵写航班当前态，历史清理作物理删除；正在被消息处理的航班清理时跳过（`OPS-1`、`PRE-5`、`US-14` AC4）。
|
||||
- 按顺序处理、只处理一次：每次只取编号最小的未完成消息（`US-03` AC1），重复扫描、失败重处理与兼容入口并发都只登记一次、生效一次（`INV-2b`）；不丢消息依赖「编号即到达顺序」且编号不复用、不回退（`PRE-2`、`PRE-3`）。
|
||||
- Redis 写成功才算处理完成；查询接口与网页客户端读同一份 Redis，出问题时报错，不返回空列表假装正常（`INV-23`、`INV-24`；`US-05`、`US-06`、`US-12`）。
|
||||
- 日计划快照以 AODB 下发为准：快照里没有的航班删除，未携带的字段清除；增量报文按携带字段更新、未携带的不清空（`INV-15b`；`US-07`；`US-04` AC2）。
|
||||
- 只跑一个实例；主泵写航班当前态，历史清理作物理删除；正在被消息处理的航班清理时跳过（`OPS-1`、`US-14` AC4）。
|
||||
- 按顺序处理、只处理一次：每次只取编号最小的未完成消息（`US-03` AC1），重复扫描、失败重处理与兼容入口并发都只登记一次、生效一次（`INV-1`）；不丢消息依赖「编号即到达顺序」且编号不复用、不回退（`Q7`）。
|
||||
- Redis 写成功才算处理完成；查询接口与网页客户端读同一份 Redis，出问题时报错，不返回空列表假装正常（`INV-10`、`INV-11`；`US-05`、`US-06`、`US-12`）。
|
||||
- 日计划快照以 AODB 下发为准：快照里没有的航班删除，未携带的字段清除；增量报文按携带字段更新、未携带的不清空（`INV-7`；`US-07`；`US-04` AC2）。
|
||||
- 对外投递至少一次，跨航班不承诺顺序（`C-9`；`US-08`）。
|
||||
- 航班只在历史写入成功后删除，历史库还没接通时一条也不删（`D1`；`US-14`）。
|
||||
- 静态参考数据一类校验失败只停这一类，其他类照常；空值是「当前没有值」，不是删除（`US-13`）。
|
||||
- 航班唯一：`FLID` 唯一（`INV-12`）。
|
||||
- 航班唯一：`FLID` 唯一（`INV-6`）。
|
||||
|
||||
这些约束是拿速度换来的：单活动主泵一次只推进一条，前一条没处理完，后面都得等。要提速、要多实例，光加线程没有用——得先重新设计消息顺序和数据由谁写，多实例还得补上可靠的互斥保护。
|
||||
|
||||
@@ -101,14 +101,14 @@ 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-2`）；原文保留与清除见 `C-1`（`Q9`）。出站请求写进去就算交付（`C-4`）。 |
|
||||
| 自有 PostgreSQL | 处理锁 `PIPELINE_LOCK`、消息处理状态与回填意图 `PROC_STATE`、待发事件 `MSG_EVENT`、出站请求跟踪 `REQ_TRACK`、航班当前态 `FLIGHT_SCHD`、资源明细表、`FLIGHT_ROUTE_POINT`、未映射字段长期记录表 `UNMAPPED_FIELD`、静态参考数据表组（admin-api 实体对齐，`Q22`）、日计划快照留痕 `SCHD_SNAP_LOG` | 本系统唯一的业务数据库，也是航班当前态的唯一权威（`INV-5`）；本地事务只发生在这里，事务怎么分段见「主流程」。`UNMAPPED_FIELD` 不随 `PROC_STATE` 到期清理。 |
|
||||
| Redis | 航班查询投影 | 只作查询，不是权威，也不存处理状态（`INV-5`）；只由本系统写入和移除（`INV-11`），内容来自 PG 当前态；`GET /all/flights` 与网页客户端读的就是它。 |
|
||||
| 共享 MySQL | `CMINMSGS` 入站信箱、`COUTMSGS` 出站信箱 | 信箱归外部系统所有。本系统只读写消息、回写处理标记，不建表、不改表结构、不写历史表（`C-2`）；已回填的入站行按保留期自清（`C-1`、`Q9`）。出站请求写进去就算交付（`C-4`）。 |
|
||||
| 航班历史存储（Elasticsearch） | 已结束航班的历史副本 | 已结束航班写入这里作历史副本；写入确认成功后才删实时数据，写不成一条也不删（`D1`、`US-14` AC3）。保留期与容量上限未定（`G-FLIGHT-HIST-RETENTION`）。 |
|
||||
|
||||
**PG 的事务只管自己库。** Redis 写没写成、信箱标记写没写上、Kafka 发没发出，PG 事务都管不着；这些步骤各自可重试，重做多少遍结果都一样，重启后从 PG 记录接着走。
|
||||
|
||||
对外投递只承诺至少一次（`C-29`）：应用重启、待发事件重发都可能让同一条消息多发一次，Kafka 的生产端幂等挡不住这种重复。
|
||||
对外投递只承诺至少一次（`C-9`）：应用重启、待发事件重发都可能让同一条消息多发一次，Kafka 的生产端幂等挡不住这种重复。
|
||||
|
||||
## 7. 关键决策
|
||||
|
||||
|
||||
Reference in New Issue
Block a user