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

docs(acm2-75): 重排 Q 序号并补齐 Redis 投影与查询侧边界

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
windyboy
2026-09-17 13:06:59 +08:00
co-authored by Cursor
parent 2a06c42993
commit c63d6d4dce
17 changed files with 480 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contracts/interface-contract.md
+12 -7
View File
@@ -11,8 +11,8 @@
| 接口 | 请求契约 | 成功响应契约 | 失败契约 | 尚需确定 |
|---|---|---|---|---|
| `POST /cminmsgs/send` | 请求体是 XML 原文；接受 `text/xml`、`application/xml`、`text/plain`，默认 UTF-8；仅限内网，网络层限制来源。 | 报文写入 `CMINMSGS` 后返回信箱编号；写入的报文与上游投递走同一条处理路径、效果一致；该响应只证明已落信，不证明业务处理或下游投递（`US-02`）。 | 空报文、超大小上限、非法 XML 不落信并返回错误；写信失败不返回编号；XML 解析禁用外部实体和外部资源访问。 | 大小上限、请求编码与 `Content-Type` 的精确处理规则、HTTP 状态码、成功/失败响应体字段及样例。 |
| `POST /schd/sync` | 触发一次 `RQFD` 日计划请求；请求字段尚未定义，登记与落信规则见「在途与作废」。 | 响应内容尚未定义；无论表示登记还是落信，都不代表 AODB 已收到。 | 错误响应尚未定义。 | 请求字段与时间格式、成功响应表示已登记还是已落信（`Q17`）、状态码、响应字段及样例。 |
| `GET /all/flights` | 无已定义的请求字段；从 Redis 投影读取当前全部动态航班，不含共享航班，与网页客户端同源（`US-12`）。 | 返回查询到的全部航班，不分页；JSON 由消息文档中的 XML 结构转换而来（`Q24`）。 | Redis 异常时返回错误，不能返回空列表伪装成功。 | 状态码和错误响应样例；外层包装是否沿用旧 `ResponseDto`。 |
| `POST /schd/sync` | 触发一次 `RQFD` 日计划请求；请求字段尚未定义，登记与落信规则见「在途与作废」。 | 响应内容尚未定义；无论表示登记还是落信，都不代表 AODB 已收到。 | 错误响应尚未定义。 | 请求字段与时间格式、成功响应表示已登记还是已落信（`Q16`）、状态码、响应字段及样例。 |
| `GET /all/flights` | 无已定义的请求字段；从 Redis 投影读取当前全部动态航班，不含共享航班，与网页客户端同源（`US-12`）。 | 返回查询到的全部航班，不分页；JSON 由消息文档中的 XML 结构转换而来（`Q21`）。 | Redis 异常时返回错误，不能返回空列表伪装成功。 | 状态码和错误响应样例；外层包装是否沿用旧 `ResponseDto`。 |
旧系统线索（来源：旧项目用户故事「HTTP 接口清单」「日计划请求」）：
@@ -43,8 +43,8 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定
| 主题 | 已确定的消息语义 | 尚需确定 |
|---|---|---|
| `msg` | 单条航班变更通知；航班动态与删除处理完成后投递；发送失败自动重试，一直失败的记录保留可查并告警（`US-08`）；同一 `FLID` 的变更保序，对外按至少一次投递。删除通知的来源有三处：`FDEL` 删除（`US-06`）、日计划快照缺席删除（`US-07`）、历史清理在物理删除前必要时登记（架构 `D1`）。 | Kafka key、value 的字段与类型、变更和删除的区分方式、版本与去重标识（`Q19`；可用依据是航班当前态的版本规则，见 `FLIGHT_SCHD` 行）、编码方式、分区规则、消费者处理重复和乱序的规则。 |
| `schd` | 定时批量发送最新航班状态；发送失败自动重试；对外按至少一次投递。 | “批量”对应的 Kafka record 粒度、key/value 字段与类型、删除航班的表达方式、批次边界、编码方式、消费者去重规则。 |
| `msg` | 单条航班变更通知；航班动态与删除处理完成后投递；发送失败自动重试，一直失败的记录保留可查并告警（`US-08`）；同一 `FLID` 的变更保序，对外按至少一次投递。删除通知的来源有三处：`FDEL` 删除（`US-06`）、日计划快照缺席删除（`US-07`）、历史清理在物理删除前必要时登记（架构 `D1`）。 | Kafka value 的字段与类型、变更和删除的区分方式、版本与去重标识（`Q5`；可用依据是航班当前态的版本规则，见 `FLIGHT_SCHD` 行）、编码方式、分区规则、消费者处理重复和乱序的规则。 |
| `schd` | 定时批量发送最新航班状态；发送失败自动重试；对外按至少一次投递。 | “批量”对应的 Kafka record 粒度、value 字段与类型、删除航班的表达方式、批次边界、编码方式、消费者去重规则。 |
旧系统线索（来源：旧项目用户故事「前端通知」「动态类（FLOP-*）处理」）：
@@ -78,9 +78,14 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定
| 存储 | 承载内容 | 边界 | 尚需确定 |
|---|---|---|---|
| Redis | 航班查询投影 | 只作查询，不是权威，也不存处理状态；只由本系统写入和移除，网页客户端与 `GET /all/flights` 读同一份，内容来自自有 PostgreSQL 的航班当前态；写投影成功、删除时移除成功，才算对应消息处理完成（架构「数据归属与一致性」；`US-05`、`US-06`）。 | key 与 value 结构及序列化方式、网页客户端读取约定（`Q20`）、每次处理后刷新哪些航班。 |
| Redis | 航班查询投影 | 只作查询，不是权威，也不存处理状态；只由本系统写入和移除，网页客户端与 `GET /all/flights` 读同一份，内容来自自有 PostgreSQL 的航班当前态；写投影成功、删除时移除成功，才算对应消息处理完成（架构「数据归属与一致性」；`US-05`、`US-06`）。 | 网页客户端读取约定（`Q6`）。 |
旧系统线索：投影是 Redis hash `flightInfo`，field 为 `FLID`、value 为 `SCHD.FLTR` 的带类型 JSON（旧项目用户故事「Redis key 汇总」「术语与数据语义」）。
旧系统线索（来源：旧项目用户故事「Redis key 汇总」「术语与数据语义」「动态航班转历史」）：
- 投影是 hash `flightInfo`：field 为 `FLID`，value 为完整 `SCHD.FLTR` 对象的带类型 JSON，不设过期；Redis 里没有名为 `schd` 的 key，`schd` 只是 Kafka 主题。
- 写入路径：日计划下载（`DNLD`／`RESP`）整体写入当天航班，单条变更（`ADFT`、`FLOP`）只写对应的一条，转历史时按 `FLID` 逐条移除。整体写入不删除本次映射中缺席的航班，与 `US-07` AC5 相反，新版按 `US-07` AC5 刷新。
- 写入前生成主航班的共享航班列表 `MAFL`（`G-MAFL`）并拼出登机桥字段 `abdg`，两者是否为网页客户端所需仍未定（`Q6`）。
- 旧系统 Redis 另有两条机位基础数据缓存，都由本系统调用 admin-api 填充、过期 3600 秒：`orms_stand`（field 为机位代码，value 为 `OrmsStand` 对象的带类型 JSON）；`orms_stand_airbridge`（field 为机位代码，value 为登机桥代码数组的 JSON 字符串，不是对象）。这两条是旧系统按计划机位拼 `abdg` 的数据来源，本版不交付（需求「范围与非目标」）。
### 自有 PostgreSQL：内部存储与 admin-api 只读
@@ -135,7 +140,7 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定
2. 运营航班显示界面的 `msg`、`schd` 消费样例和字段要求，特别是变更、删除、重复投递的处理方式。
3. CIIMS adapter 方提供的 `CMINMSGS`、`COUTMSGS` 现行 DDL、读写样例和写权限说明，核对旧系统实体映射列名，并确认信箱编号单调递增、不复用、不回退。
4. 13 类参考数据与资源状态的编号规则，以及自有 PostgreSQL 的迁移 DDL。
5. Redis 投影的 key 与 value 结构、序列化方式及网页客户端读取约定。
5. 网页客户端读取 Redis 投影的约定，含它需要哪些字段（`Q6`）。
6. AODB 应答与 `EROR` 样例，含请求与应答的对应字段、超时判定依据。
7. Elasticsearch 历史索引映射、文档样例、逐条或批量写入响应、索引保留期与容量上限，以及写入结果不明时的对账规则。