windy/msgexchange-v2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(acm2-75): 精简术语表并顺化表达；校验器兼容约定小节名

Browse Source
This commit is contained in:
windyboy
2026-09-16 11:34:54 +08:00
parent 56ad8c9220
commit 8a690705e3
2 changed files with 18 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/specification.md
+17 -14
View File
@@ -1,35 +1,38 @@
# 规范：术语、契约、前提、不变量与声明边界 # 规范：术语、约定、前提、不变量与能力边界
本文定义 msgexchange-v2 的术语、外部契约 `C-x`、前提 `PRE-x`、不变量 `INV-x`、声明边界 `CLM-x`、待确认 `Qn`、当前已知偏差 `G-NAME` 与验证映射。 本文整理 msgexchange-v2 对外接口约定（`C-x`）、前提条件（`PRE-x`）、系统不变量（`INV-x`）、能力边界（`CLM-x`）、待确认事项（`Qn`）与已知偏差（`G-NAME`），并统一给出术语。条款依据 [requirements.md](requirements.md) 与 [architecture.md](architecture.md) 编写；字段联调草案另见 [contracts/interface-contract.md](contracts/interface-contract.md)，对外承诺以本文件为准。
内容取自 [requirements.md](requirements.md)、[architecture.md](architecture.md) 与 [contracts/interface-contract.md](contracts/interface-contract.md)。机制与数据模型见 [implementation.md](implementation.md)，参数与指标见 [reference.md](reference.md)。 约定条目的标记：
`C-x`、`PRE-x`、`INV-x`、`CLM-x`、`Qn`、`G-NAME` 只在本文件定义；ID 语法见 [README.md](README.md)。 - 需要对方确认的，末尾标 `（待确认 Qn）`。
- 内容已定、个别字段未定的，另起一行以「待确认：」列出并指向 `Qn`。
- 本系统单方遵守、不依赖对方认可的，末尾标 `（本系统单方承诺）`。
- 未标注的，表示需求或架构已定，本系统按此执行。
契约条目的写法：整条口径还需对方确认的，末尾标 `（待确认 Qn）`；正文已定、只有个别字段未定的，另起一行以「待确认：」列出并指向 `Qn`。未标注的，是本系统自己遵守或已由需求与架构定下。作废条款集中放在各节末尾，保留原文与作废标记。 作废条款集中放在各节末尾，保留原文与作废标记。
## 1. 术语 ## 1. 术语
| 术语 | 含义 | | 术语 | 含义 |
|---|---| |---|---|
| 上游 | 产生报文的 AODB；报文由 CIIMS adapter 写入信箱。 | | 上游 | 产生报文的 AODB，报文经 CIIMS adapter 写入信箱。 |
| 信箱 | 共享 MySQL 的 `CMINMSGS`（入站）与 `COUTMSGS`（出站）；归库方所有，本系统只读写消息、回写处理标记。 | | 信箱 | 共享 MySQL 的 `CMINMSGS`（入站）与 `COUTMSGS`（出站），归库方所有；本系统只读写消息、回写处理标记，不改表结构。 |
| 库方 | 信箱所在的共享 MySQL 管理方，即 CIIMS adapter 方。 | | 库方 | 信箱所在的共享 MySQL 管理方，即 CIIMS adapter 方。 |
| 处理标记 | 信箱行上表示已处理的值。读取条件是「处理时间为空」；处理完成时写入完成时刻。本系统只填空值，不回撤、不覆盖。 | | 处理标记 | 信箱行上的时间戳字段：为空表示未处理，处理完成时写入完成时刻；只填空值，不回撤、不覆盖。 |
| 落信 | 报文写入信箱成为一行；入站由 CIIMS adapter 或兼容入口写入，出站由本系统写入 `COUTMSGS`；入站报文写进信箱后可能尚未登记。 | | 落信 | 报文写入信箱成为一行；入站由 CIIMS adapter 或兼容入口写入，出站由本系统写入 `COUTMSGS`；入站报文写进信箱后可能尚未登记。 |
| 登记 | 本系统在自有 PG 为这条报文建立处理记录，排队等待处理。 | | 登记 | 本系统在自有 PG 为这条报文建立处理记录，排队等待处理。 |
| 处理完成 | 该消息的全部本地副作用已持久化、对外投影（若有）已写成功；此后才允许回填与投递（`US-03` AC4）。判据按类别：航班增量与删除＝写入自有 PG 且 Redis 投影成功（`US-05` AC4、`US-06` AC1）；日计划＝整包写入完成且按快照刷新 Redis（`INV-31`）；静态参考数据＝该类落库成功，无投影步骤（架构「主流程」）；非法或不支持的报文＝终态留档，无业务副作用（`US-03` AC2）。 | | 处理完成 | 该消息的全部本地副作用已持久化、对外投影（若有）已写成功，此后才允许回填与投递（`US-03` AC4）；各类别的判据见 `INV-23`、`INV-31` 与架构「主流程」。 |
| 回填 | 把处理标记写回信箱行。 | | 回填 | 把处理标记写回信箱行。 |
| 投递 | 读待发事件发 Kafka。 | | 投递 | 读待发事件发 Kafka。 |
| Redis 投影 | 供页面与 `GET /all/flights` 查询的航班数据；只由本系统写入和移除，不作权威。 | | Redis 投影 | 供页面与 `GET /all/flights` 查询的航班数据；只由本系统写入和移除，不作权威。 |
| 自有 PG | 本系统唯一的业务数据库；航班当前态、管道记录与静态参考数据都在这里。 | | 自有 PG | 本系统唯一的业务数据库；航班当前态、管道记录与静态参考数据都在这里。 |
| 权威 | 航班当前态以自有 PG 为准；信箱、Redis、Kafka 与展示视图都不是。 | | 权威 | 航班当前态以自有 PG 为唯一权威，信箱、Redis、Kafka 与展示视图均不作权威。 |
| 出站请求 | 经 `COUTMSGS` 发向 AODB 的 `RQRD` 参考数据请求与 `RQFD` 日计划请求；交付承诺止于落信。 | | 出站请求 | 经 `COUTMSGS` 发向 AODB 的 `RQRD` 参考数据请求与 `RQFD` 日计划请求。 |
| 运营航班显示界面 | Kafka 主题 `msg` 与 `schd` 的消费方，即需求所称网页客户端：变更通知走 Kafka（`US-08`），航班查询与 `GET /all/flights` 同源读 Redis 投影（`INV-24`）。 | | 运营航班显示界面 | Kafka 主题 `msg` 与 `schd` 的消费方，即需求所称网页客户端。 |
| 航班历史 | 已结束航班写入 Elasticsearch 后的副本；写成功后才从实时数据删除。 | | 航班历史 | 已结束航班写入 Elasticsearch 后的副本；写成功后才从实时数据删除。 |
| 静态参考数据 | 13 类基础数据与资源状态，写自有 PG 的独立数据表，admin-api 直接只读。 | | 静态参考数据 | 13 类基础数据与资源状态，写自有 PG 的独立数据表，admin-api 直接只读。 |
## 2. 契约 ## 2. 约定
### 2.1 共享信箱（库方） ### 2.1 共享信箱（库方）
@@ -131,7 +134,7 @@
- **INV-21** 主航班与其共享航班不出现只删一半的状态：删除共享航班时联动更新其主航班，删除主航班级联删除其共享航班（`US-06` AC2）。 - **INV-21** 主航班与其共享航班不出现只删一半的状态：删除共享航班时联动更新其主航班，删除主航班级联删除其共享航班（`US-06` AC2）。
- **INV-22** 主航班与共享航班的删除在同一 PG 事务内提交。被删除的航班从 Redis 投影移除；删除共享航班时，主航班的投影随更新结果刷新。移除与刷新都成功后才算这次处理完成（`INV-17b`、`INV-23`）；任一失败即未完成，下轮重做两步——移除可重复执行，刷新以重做时的结果为准。共享航班在 Redis 投影中的呈现方式、删除通知使用共享还是主航班 `FLID`，待 `Q20`、`Q4`。 - **INV-22** 主航班与共享航班的删除在同一 PG 事务内提交。被删除的航班从 Redis 投影移除；删除共享航班时，主航班的投影随更新结果刷新。移除与刷新都成功后才算这次处理完成（`INV-17b`、`INV-23`）；任一失败即未完成，下轮重做两步——移除可重复执行，刷新以重做时的结果为准。共享航班在 Redis 投影中的呈现方式、删除通知使用共享还是主航班 `FLID`，待 `Q20`、`Q4`。
- **INV-29** 已删除航班收到 `ADFT` 时按报文内容恢复为有效航班（`US-04` AC3）：恢复走正常处理路径，推进版本、刷新投影并登记事件，不因已删除而跳过或拒绝。 - **INV-29** 已删除航班收到 `ADFT` 时按报文内容恢复为有效航班（`US-04` AC3）：恢复走正常处理路径，推进版本、刷新投影并登记事件，不因已删除而跳过或拒绝。
- **INV-31** 日计划以整包为完成单位：每批提交只是持久化进度，处理完成在整包写入完成且 Redis 按快照刷新成功后判定（`US-07` AC4/AC5）；刷新在整包写入完成后才开始（架构「主流程」）。刷新期间查询可见的投影状态不设契约，是否提供原子切换视图取决于 `Q20`。失败后整包重处理，收敛依赖版本只进不退与逐航班重写幂等（`INV-13`）；日计划的逐航班重写幂等未补齐（`G-SCHD-SNAPSHOT`），闭合前收敛不可声明。 - **INV-31** 日计划以整包为完成单位：每批提交只是持久化进度，处理完成在整包写入完成且 Redis 按快照刷新成功后判定（`US-07` AC4/AC5）；刷新在整包写入完成后才开始（架构「主流程」）。刷新期间查询可见的投影状态不作承诺，是否提供原子切换视图取决于 `Q20`。失败后整包重处理，收敛依赖版本只进不退与逐航班重写幂等（`INV-13`）；日计划的逐航班重写幂等未补齐（`G-SCHD-SNAPSHOT`），闭合前收敛不可声明。
### 4.3 投影、投递、历史与参考数据 ### 4.3 投影、投递、历史与参考数据
scripts/check-docs.py
+1 -1
View File
@@ -202,7 +202,7 @@ def main() -> int:
"US": ("requirements.md", ["用户故事"]), "US": ("requirements.md", ["用户故事"]),
"OPS": ("requirements.md", ["运行验收", "运行与切流验收", "需求覆盖与依赖"]), "OPS": ("requirements.md", ["运行验收", "运行与切流验收", "需求覆盖与依赖"]),
"D": ("architecture.md", ["关键决策"]), "D": ("architecture.md", ["关键决策"]),
"C": ("specification.md", ["契约"]), "C": ("specification.md", ["契约", "约定"]),
"PRE": ("specification.md", ["前提"]), "PRE": ("specification.md", ["前提"]),
"INV": ("specification.md", ["不变量"]), "INV": ("specification.md", ["不变量"]),
"CLM": ("specification.md", ["声明边界"]), "CLM": ("specification.md", ["声明边界"]),