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/specification.md
+35 -30
View File
@@ -42,21 +42,21 @@
### 2.2 上游（AODB / SIS）
- **C-3** 业务身份由 `SNDR`、`TYPE`、`STYP`、`SEQN` 四字段组合；`SEQN` 自增，极少重置（消息服务器重启），重置后不会与旧消息冲突。
- **C-4** 出站请求写入 `COUTMSGS`；交付承诺止于落信。编码：`SNDR=OMMS`；`SEQN` 本系统自建序列；`DTTM` 北京时间 `YYYYMMDDHHMMSS`；`RQRD` 子类型以 SIS 为准共 14 类；`RQFD` 为 `STYP=NONE`，全量同步不带 `STDB`/`STDE` 等筛选（`Q25`）。
- **C-4** 出站请求写入 `COUTMSGS`；交付承诺止于落信。编码：`SNDR=OMMS`；`SEQN` 本系统自建序列；`DTTM` 北京时间 `YYYYMMDDHHMMSS`；`RQRD` 子类型以 SIS 为准共 14 类；`RQFD` 为 `STYP=NONE`，全量同步不带 `STDB`/`STDE` 等筛选（`Q13`）。
- **C-5** 航班删除为标记删除，主航班与共享航班各自独立标记。
- **C-6** 日计划快照里没有携带的字段视为 AODB 已删除该值，本地同步清除（`US-07` AC3）。
### 2.3 HTTP 入口
- **C-7** `POST /cminmsgs/send`：把 XML 写进入站信箱，与 adapter 投递走同一套处理。成功返回消息编号（仅表示已入库、未处理）；失败不返回编号。支持 `text/xml`、`application/xml`、`text/plain`（UTF-8）；空、超长、格式错的不写；解析不拉外部资源。内网，访问由网络配置控制。仅内部联调；长度上限与失败响应实现时自定（`Q3`）。
- **C-7** `POST /cminmsgs/send`：把 XML 写进入站信箱，与 adapter 投递走同一套处理。成功返回消息编号（仅表示已入库、未处理）；失败不返回编号。支持 `text/xml`、`application/xml`、`text/plain`（UTF-8）；空、超长、格式错的不写；解析不拉外部资源。内网，访问由网络配置控制。仅内部联调；长度上限与失败响应实现时自定（`Q15`）。
- **C-8** `POST /schd/sync`：向出站表写入一条日计划请求。
待确认：请求参数、HTTP 响应（`Q17`）。
待确认：请求参数、HTTP 响应（`Q16`）。
### 2.4 下游（admin-api、网页客户端与运营航班显示界面）
- **C-9** 航班变更发到 Kafka 主题 `msg`（单条）和 `schd`（批量）。同一条可能发多次。
- **C-9** 航班变更发到 Kafka 主题 `msg`（单条）和 `schd`（批量）；`schd` 每条为运营航班 JSON；不设消息键。同一条可能发多次。
- **C-10** 静态参考数据写入本系统数据库，供 admin-api 只读；本系统不调用 admin-api。
- **C-11** 航班投影写入 Redis，供读取全体动态航班；`GET /all/flights` 与网页客户端读同一份；返回 JSON 由消息文档中的 XML 结构转换而来（`Q20`、`Q24`）。
- **C-11** 航班投影写入 Redis，供读取全体动态航班；`GET /all/flights` 与网页客户端读同一份；返回 JSON 由消息文档中的 XML 结构转换而来（`Q6`、`Q21`）。
## 3. 前提
@@ -104,7 +104,14 @@
### 6.1 待对方确认
（无）
| 编号 | 事项 | 当前假定 | 影响 |
|---|---|---|---|
| Q1 | `schd` 的 value 字段与类型、删除航班的表达方式、批次边界、消费者去重规则 | 每条 record 为一条运营航班 JSON（`C-9`）；批次边界按定时窗口 | 消费方读取契约无法定稿 |
| Q2 | 请求与应答按时间匹配时的时钟偏斜容忍判据 | 比较前统一时区与单位（implementation.md「上游请求与静态数据」） | 容忍判据未定前，降级匹配不得描述为精确关联 |
| Q3 | 现场会发但 SIS 未定义的子类型（靠桥、延误等）的报文形态与逐类终态 | 按现有处理逻辑延续，不得因 SIS 未记载就丢掉（`US-05` AC1） | 逐类终态与幂等规则未定（`G-FLOP-SEMANTICS`） |
| Q4 | 上游重发时是否可能改发正文 | 报文不可变，绑定身份后不比对内容（implementation.md「消息、身份与决策」） | 改发正文的重发会被判为重复并跳过 |
| Q5 | `msg` 的版本与去重标识是否直接采用航班当前态的版本号 | 可用依据是航班当前态的版本规则（implementation.md「航班域：权威模型与合并写入语义」） | 消费方去重规则未定（与 `Q1` 衔接） |
| Q6 | 网页客户端读取 Redis 投影的约定 | 沿用旧系统的 hash `flightInfo`：field 为 `FLID`，value 为完整航班对象的带类型 JSON，不设过期；写入与移除时机见 `INV-7`、`INV-8`、`INV-10`；派生字段 `MAFL`、`abdg` 是否随投影提供仍未定；只作查询、不是权威；与 `GET /all/flights` 同一份（`C-11`；接口契约「Redis：航班查询投影」） | 消费方读取契约无法定稿 |
答复就地更新结论，并按 [README.md](README.md)「维护清单」落到对应条款。
@@ -112,17 +119,13 @@
| 编号 | 事项 | 结论 |
|---|---|---|
| Q2 | 信箱编号的单调、不复用、不回退 | 已定案：编号即入库行号，单调递增、不复用、不回退；按编号升序处理即按到达顺序（`US-01` AC3、`CLM-2`） |
| Q4 | `schd` 载荷 | 已定案：`schd` 每条为运营航班 JSON（`C-9`、`US-08`） |
| Q7 | 入站处理时间列 | 已定案：与旧系统相同，列名为 `CMINMSGS_DATE_PROCESSED`；空为未处理，回填写入完成时刻（`US-10`） |
| Q8 | 现场有、文档没有的报文 | 已定案：仍须想办法处理，不得因 SIS 未记载就丢掉（`US-05` AC1）；具体形态与落库规则随对拍补齐 |
| Q7 | 信箱编号的单调、不复用、不回退 | 已定案：编号即入库行号，单调递增、不复用、不回退；按编号升序处理即按到达顺序（`US-01` AC3、`CLM-2`） |
| Q8 | 入站处理时间列 | 已定案：与旧系统相同，列名为 `CMINMSGS_DATE_PROCESSED`；空为未处理，回填写入完成时刻（`US-10`） |
| Q9 | 入站信箱行（MySQL `CMINMSGS`）清除 | 已定案：本系统回填后自清（`C-1`）；保留期可配置，按约 1 个月 |
| Q11 | 上游 `SEQN` 的重置周期与身份是否加日期边界 | 已定案：`SEQN` 自增，极少重置，重置后不与旧消息冲突，不加日期边界（`C-3`） |
| Q13 | 日计划未携带字段的删除语义 | 见 `C-6` |
| Q14 | 主/共享删除顺序 | 已定案：标记删除，各自独立（`C-5`） |
| Q20 | Redis 投影用途 | 已定案：供读取全体动态航班；与 `GET /all/flights`、网页客户端同一份（`C-11`、`US-12`） |
| Q24 | `GET /all/flights` 返回体结构 | 已定案：JSON 由消息文档中的 XML 结构转换而来；读 Redis、返回全体动态航班、不分页（`C-11`、`US-12`） |
| Q25 | `RQRD` / `RQFD` 编码字段 | 已定案：`SNDR=OMMS`；`SEQN` 本系统自建序列；`DTTM` 为北京时间 `YYYYMMDDHHMMSS`（SIS META）；`RQRD` 子类型以 SIS 为准共 14 类（含 `RSTA`，其可选 `RTYP`）；`RQFD` 的 `STYP=NONE`，`STDB`/`STDE` 等筛选可选，全量同步不带筛选（SIS：无参数则返回当天全部，对齐 `US-07`）（`C-4`） |
| Q10 | 上游 `SEQN` 的重置周期与身份是否加日期边界 | 已定案：`SEQN` 自增，极少重置，重置后不与旧消息冲突，不加日期边界（`C-3`） |
| Q11 | 日计划未携带字段的删除语义 | 见 `C-6` |
| Q12 | 主/共享删除顺序 | 已定案：标记删除，各自独立（`C-5`） |
| Q13 | `RQRD` / `RQFD` 编码字段 | 已定案：`SNDR=OMMS`；`SEQN` 本系统自建序列；`DTTM` 为北京时间 `YYYYMMDDHHMMSS`（SIS META）；`RQRD` 子类型以 SIS 为准共 14 类（含 `RSTA`，其可选 `RTYP`）；`RQFD` 的 `STYP=NONE`，`STDB`/`STDE` 等筛选可选，全量同步不带筛选（SIS：无参数则返回当天全部，对齐 `US-07`）（`C-4`） |
### 6.3 本系统与需求方待决
@@ -130,16 +133,18 @@
| 编号 | 事项 | 当前假定 | 影响 |
|---|---|---|---|
| Q1 | 生产库选型 | 自有 PG 是唯一权威；生产环境用 PostgreSQL 还是 Oracle 11g 不能从三份依据确定，Oracle 适配验证通过前不作支持承诺 | 生产部署验收 |
| Q3 | `POST /cminmsgs/send` 的长度上限与失败响应 | 仅内部联调、无外部引用；成功返回编号等行为见 `C-7`；上限与失败格式现阶段不定，实现时在代码里自定 | 不阻塞对外契约 |
| Q17 | `POST /schd/sync` 的请求字段与时间格式、成功响应表示已登记还是已落信、状态码与错误响应 | 交付承诺止于落信（`C-4`）；旧系统线索为 `{startDate, endDate}` 与 12 小时制时间（接口契约「HTTP」） | 响应契约无法定稿（`C-8`） |
| Q18 | 人工发起 `RQRD` 的方式 | `US-09` 要求人工发起，HTTP 接口清单没有对应入口 | 参考数据请求无法人工触发 |
| Q21 | 回退时在途消息（已提交业务变更、未到处理完成）的处置 | 回填了结后切换（`OPS-4`）；在途消息无跨系统幂等保障 | 回退演练的验收口径（`OPS-4`） |
| Q22 | 是否在自有 PG 留存入站原文副本，及原文提前清除时已登记消息的处置 | 不留存，原文只从信箱读取 | 提前清除的消息不可恢复，处置未定 |
| Q23 | 日计划中运营日冲突的处置 | 未定 | 冲突场景无法验收 |
| Q26 | `REF_MASTER` 的物理列、唯一键、空值存储与写入后可见时点 | 记录用类别码加识别标签识别（接口契约「静态参考数据类别与编号来源」） | admin-api 读取契约无法定稿（`C-10`） |
| Q27 | Elasticsearch 历史索引、文档 ID、字段映射、成功判据、保留期与容量上限、写入结果不明的对账与幂等策略 | 历史写入确认成功才删实时数据（`D1`、`US-14` AC3） | 历史链路无法验收（`US-14`；`G-FLIGHT-HIST-RETENTION`） |
| Q28 | `REQ_TRACK` 已结案记录的保留期取值 | 到期清理没有可依据的窗口（`G-REQ-TRACK-RETENTION`） | 请求历史清理无法实现（`US-09`） |
| Q14 | 生产库选型 | 自有 PG 是唯一权威；生产环境用 PostgreSQL 还是 Oracle 11g 不能从三份依据确定，Oracle 适配验证通过前不作支持承诺 | 生产部署验收 |
| Q15 | `POST /cminmsgs/send` 的长度上限与失败响应 | 仅内部联调、无外部引用；成功返回编号等行为见 `C-7`；上限与失败格式现阶段不定，实现时在代码里自定 | 不阻塞对外契约 |
| Q16 | `POST /schd/sync` 的请求字段与时间格式、成功响应表示已登记还是已落信、状态码与错误响应 | 交付承诺止于落信（`C-4`）；旧系统线索为 `{startDate, endDate}` 与 12 小时制时间（接口契约「HTTP」） | 响应契约无法定稿（`C-8`） |
| Q17 | 人工发起 `RQRD` 的方式 | `US-09` 要求人工发起，HTTP 接口清单没有对应入口 | 参考数据请求无法人工触发 |
| Q18 | 回退时在途消息（已提交业务变更、未到处理完成）的处置 | 回填了结后切换（`OPS-4`）；在途消息无跨系统幂等保障 | 回退演练的验收口径（`OPS-4`） |
| Q19 | 是否在自有 PG 留存入站原文副本，及原文提前清除时已登记消息的处置 | 不留存，原文只从信箱读取 | 提前清除的消息不可恢复，处置未定 |
| Q20 | 日计划中运营日冲突的处置 | 未定 | 冲突场景无法验收 |
| Q21 | `GET /all/flights` 的状态码、错误响应样例、外层包装是否沿用旧 `ResponseDto` | 返回体是消息文档中的 XML 结构转换出的 JSON；读 Redis、返回全体动态航班、不分页（`C-11`） | 查询契约无法定稿 |
| Q22 | `REF_MASTER` 的物理列、唯一键、空值存储与写入后可见时点 | 记录用类别码加识别标签识别（接口契约「静态参考数据类别与编号来源」） | admin-api 读取契约无法定稿（`C-10`） |
| Q23 | Elasticsearch 历史索引、文档 ID、字段映射、成功判据、保留期与容量上限、写入结果不明的对账与幂等策略 | 历史写入确认成功才删实时数据（`D1`、`US-14` AC3） | 历史链路无法验收（`US-14`；`G-FLIGHT-HIST-RETENTION`） |
| Q24 | `REQ_TRACK` 已结案记录的保留期取值 | 到期清理没有可依据的窗口（`G-REQ-TRACK-RETENTION`） | 请求历史清理无法实现（`US-09`） |
| Q25 | 季度计划的数据来源与归属：admin-api 从本系统库读季度计划，而 SIS 只有日计划事件（`SIS:3.16`、`SIS:3.17`、`SIS:4.7`） | 应由 AODB 下发，报文形态待确认；旧系统读 Oracle 的 `FIMS_FLIGHTSCHD_SEASON` | admin-api 的季度计划查询没有供数方 |
## 7. 当前已知偏差
@@ -149,8 +154,8 @@
|---|---|---|
| `G-REQ-TRACK` | 出站请求没有跟踪：登记、编码、超时与应答匹配都没有实现 | `US-09` |
| `G-REQ-OPEN-UNIQUE` | 同一报文类型同时最多一条已落信、未结案请求的限制没有实现；待发送登记不算占用该名额 | `US-09` |
| `G-REQ-TRACK-RETENTION` | `REQ_TRACK` 已结案记录的保留期取值未定，到期清理作业没有可依据的窗口（取值待 `Q28`） | `US-09` |
| `G-FLIGHT-HIST-RETENTION` | 历史存储的保留期与容量上限未定（取值待 `Q27`） | `US-14`；实时数据删除后历史是唯一副本 |
| `G-REQ-TRACK-RETENTION` | `REQ_TRACK` 已结案记录的保留期取值未定，到期清理作业没有可依据的窗口（取值待 `Q24`） | `US-09` |
| `G-FLIGHT-HIST-RETENTION` | 历史存储的保留期与容量上限未定（取值待 `Q23`） | `US-14`；实时数据删除后历史是唯一副本 |
| `G-FLOP-IDEMPOTENT` | 逐类幂等规则未补齐 | `US-03`；`CLM-1` |
| `G-FLOP-SEMANTICS` | `STYP` 没有白名单，`ROUT` 未限制 4 条，运行状态落点与已删除航班的处理与 `US-05` 不符 | `US-05` |
| `G-FLOP-UNMAPPED` | [XSD](legacy/unisysaodbsis.xsd)「FLOP 元素」里有些字段没有解码或映射错了，会被静默丢掉 | `US-05` |
@@ -181,7 +186,7 @@
| US-14 AC4 | `US-14` AC4 | 历史清理跳过正在被消息处理的航班 |
| INV-4 | `US-07` AC1 | 校验失败后本地数据与版本不变 |
| INV-9 | `US-07` AC4/AC5 | 分批失败后整包重处理收敛到同一目标（`G-SCHD-SNAPSHOT` 闭合前无法验证）；Redis 在整包写入完成后按快照刷新，成功即与快照一致 |
| CLM-1 | `US-03` | 同一消息不产生两次效果；逐子类型规则与幂等矩阵在 `Q8`、`G-FLOP-IDEMPOTENT`、`G-FLOP-SEMANTICS` 闭合前无法验证 |
| CLM-1 | `US-03` | 同一消息不产生两次效果；逐子类型规则与幂等矩阵在 `Q3`、`G-FLOP-IDEMPOTENT`、`G-FLOP-SEMANTICS` 闭合前无法验证 |
| INV-8 | `US-06` AC1 | 航班标记删除后从投影移除；移除失败时下轮重做 |
| US-14、D1 | `US-14` AC3 | 历史写入成功才删实时数据；删除事件在实时数据删除前登记（`D1`） |
| US-06 AC2 | `US-06` AC2 | 删共享联动主航班；删主航班级联删共享 |
@@ -193,6 +198,6 @@
| CLM-4 | `US-09` AC1～AC3 | 出站请求写入 `COUTMSGS` |
| CLM-5（不承诺完成时限） | — | 需求未定完成时限；现场一般为即时处理 |
| CLM-6（容量） | — | 现场量级暂无；有数据后再估 |
| OPS-4 | `OPS-4` | 回退演练：回填了结后切回，旧系统不重处理已产生业务效果的消息；在途窗口处置见 `Q21` |
| OPS-4 | `OPS-4` | 回退演练：回填了结后切回，旧系统不重处理已产生业务效果的消息；在途窗口处置见 `Q18` |
| CLM-7 | `OPS-1` | 配置错误启动失败测试可验收 |
| PRE-1（测试隔离） | `OPS-3` | 测试环境配置核对：独立的数据库、Redis 与 Kafka 主题，不连接生产信箱 |