msgexchange-v2/docs/specification.md

# 规范：术语、约定、前提、不变量与承诺范围

本文列出 msgexchange-v2 与外部系统的约定（`C-x`）、运行前提（`PRE-x`）、必须始终成立的规则（`INV-x`）、能对外承诺的内容（`CLM-x`）、待定事项（`Qn`）和已知缺口（`G-NAME`）。依据 [requirements.md](requirements.md) 与 [architecture.md](architecture.md)；HTTP/Kafka/Redis 字段草案见 [contracts/interface-contract.md](contracts/interface-contract.md)。

各编号只在本文件定义；编号稳定、不重排，规则见 [README.md](README.md)。

标注 `（待确认 Qn）` 需对方确认；标注 `（本系统承诺）` 不依赖对方同意；未标注视为已定。字段未定另起「待确认：」并指向 `Qn`。

## 编号一览

| 族 | 所在小节 | 含义 |
|---|---|---|
| `C-1`～`C-11` | 约定 | 对外约定 |
| `PRE-x` | 前提 | 运行前提 |
| `INV-1`～`INV-11` | 不变量 | 必须始终成立的规则 |
| `CLM-1`～`CLM-7` | 声明边界 | 能否对外承诺 |
| `Q1`～`Q25` | 待确认事项台账 | 待定事项（`Q19`、`Q20` 未分配） |
| `G-*` | 当前已知偏差 | 已知实现缺口 |

## 1. 术语

| 术语 | 含义 |
|---|---|
| 上游 | 发报文的 AODB；报文经 CIIMS adapter 进信箱。 |
| 信箱 | 共享 MySQL 的 `CMINMSGS`（入站）与 `COUTMSGS`（出站）；归库方管理，边界见 `C-2`。 |
| 库方 | 管理共享 MySQL 信箱的一方（CIIMS adapter）。 |
| 处理标记 | 列 `CMINMSGS_DATE_PROCESSED`：空=未处理，有值=已处理时间。 |
| 写入信箱 | 报文存成信箱里的一行。入站由 adapter 或 `POST /cminmsgs/send` 写入；出站由本系统写 `COUTMSGS`。写入后未必马上开始处理。 |
| 建立处理记录 | 本系统在自有 PG 记一条待处理记录并排进队列。 |
| 处理完成 | 结果已定（已改库、明确跳过、或无法处理并归档）；之后才写处理标记并发 Kafka。 |
| 写回处理时间 | 处理完成后，把时刻写入 `CMINMSGS_DATE_PROCESSED`。 |
| 发到 Kafka | 把待发送的变更事件写入 Kafka。 |
| 网页客户端 | 读 Kafka（`msg`/`schd`）或调 `GET /all/flights`（Redis）的前端。 |
| Redis 航班快照 | 网页客户端查询用的航班数据，从自有 PG 同步；规则见 `INV-11`。 |
| 自有 PG | 本系统主库：航班、处理记录、静态参考数据。 |
| 出站请求 | 本系统经 `COUTMSGS` 向 AODB 发 `RQRD`（参考数据）或 `RQFD`（日计划）。 |
| 航班历史 | 已结束航班写入 Elasticsearch；写入成功后才从实时库删除。 |
| 静态参考数据 | 13 类基础数据与资源状态；存自有 PG，admin-api 只读。 |

## 2. 约定

### 2.1 共享信箱（库方）

- **C-1** 删除已处理完毕的入站行（`CMINMSGS`）：处理标记已写入，且超过保留期（可配置，默认约 1 个月）。未处理完或未写回处理时间的行不删。
- **C-2** 共享 MySQL 不改表结构；本系统只读写 `CMINMSGS` 与 `COUTMSGS`。

### 2.2 上游（AODB / SIS）

- **C-3** 一条报文的身份 = `SNDR` + `TYPE` + `STYP` + `SEQN`。`SEQN` 自增，极少在消息服务器重启时重置；重置后不与历史冲突。
- **C-4** 出站请求写入 `COUTMSGS`；本系统只保证写入信箱，不保证 AODB 收到。编码：`SNDR=OMMS`；`SEQN` 本系统生成；`DTTM` 北京时间 `YYYYMMDDHHMMSS`；`RQRD` 共 14 种子类型（以 SIS 为准）；`RQFD` 的 `STYP=NONE`，全量不带 `STDB`/`STDE` 筛选。
- **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）；拒收空报文、超长、非法 XML；解析禁止访问外部资源。内网访问由网络层控制；仅供内部联调。
  - 待确认：大小上限、HTTP 状态码与响应体 → `Q15`。
- **C-8** `POST /schd/sync`：登记一次 `RQFD` 日计划请求。同类型若还有未处理完的请求，新请求先不写信箱，等旧的处理完再写 `COUTMSGS`（`US-09` AC1）。
  - 待确认：请求参数与 HTTP 响应 → `Q16`。

### 2.4 下游（admin-api、网页客户端）

- **C-9** 航班变更发 Kafka：`msg` 一条变更一条消息；`schd` 把两轮采集之间积累的变化合成一条消息，内容是 `SCHD.FLTR` JSON 数组。空字段不输出，没变化不发；删航班只走 `msg`；不设 message key；可能重复投递（待确认 `Q1`）。
- **C-10** 静态参考数据写本系统库，admin-api 只读；本系统不调用 admin-api。
- **C-11** 航班快照写 Redis；`GET /all/flights` 与网页客户端读同一份；JSON 由报文 XML 转换。
  - 待确认：`MAFL` 是否一并提供（`Q6`）；状态码与响应包装（`Q21`）。

## 3. 前提

前提不成立时，下文规则需整体重评。

| 编号 | 前提 | 若不成立 |
|---|---|---|
| PRE-1 | 测试与生产隔离：各自独立的 DB、Redis、Kafka 主题，测试不连生产信箱 | `OPS-3` 验收无效 |

## 4. 不变量

### 4.1 消息处理

- **INV-1** 处理标记为空的信箱行会被建立处理记录；同一编号只建一次。重扫或重启不重复、不遗漏。
- **INV-2** 只有本地处理结束后才写回处理时间；标记「处理结束」时必须同一次记下「还要写回信箱」。只填空的处理标记，不覆盖已有值（本系统承诺）。
- **INV-3** 航班增量与删除：改库与记「待发 Kafka」同一次提交；「处理结束」与「还要写回信箱」在 Redis 写成功后再记一次。处理完成前不发 Kafka（`US-03` AC4）。日计划与静态参考数据见架构「主流程」。
- **INV-4** 日计划整报校验失败时，本地航班数据不改（`US-07` AC1）。

### 4.2 航班

- **INV-5** 航班当前数据以自有 PG 为准。
- **INV-6** `FLID` 全局唯一。
- **INV-7** 日计划：快照里没有的航班打删除标记、记删除事件、从 Redis 删掉；快照没带的字段本地清掉（`US-07` AC2/AC3）。
- **INV-8** 已打删除标记的航班必须从 Redis 删掉；删掉才算这条消息处理完成（`US-06` AC1）。
- **INV-9** 日计划可以分批写 PG，但整份 PG 写完且 Redis 按快照刷完才算完成；失败则全部重来（`US-07` AC4/AC5）。

### 4.3 Redis 航班快照

- **INV-10** Redis 写成功才算处理完成；失败则不写回处理时间、不发 Kafka、下轮重试（`US-05` AC4）。已写入 PG 的不因 Redis 失败而撤销（`US-03` AC3）。
- **INV-11** Redis 航班快照只由本系统维护；查询与网页客户端同源；Redis 出错时返回错误，不能用空列表假装成功（`US-12`）。

## 5. 声明边界

| 编号 | 承诺 | 依赖 | 现在能否作出 | 限制或原因 |
|---|---|---|---|---|
| CLM-1 | 同一条消息重复处理不会重复生效 | `US-03` | 不能 | 各类报文细则未写完（`G-FLOP-IDEMPOTENT`） |
| CLM-2 | 按信箱编号从小到大处理 | `US-03` AC1 | 能 | — |
| CLM-3 | 主题 `msg` 上，同一 `FLID` 内按发送顺序排列 | `US-08` AC2、`C-9` | 能 | `msg` 单分区；至少一次投递时可能重复（`D2`） |
| CLM-4 | 出站请求写入 `COUTMSGS` | `C-4` | 能 | 只保证写入信箱，不保证 AODB 收到 |
| CLM-5 | 消息在固定时间内处理完 | — | 不能 | 需求未定时限 |
| CLM-6 | 容量与吞吐量级 | — | 不能 | 需求未给日量与峰值 |
| CLM-7 | 配置不完整时拒绝启动 | `OPS-1` | 能 | — |

## 6. 待确认事项台账

`Q1`～`Q25` 按编号排列。答复后更新对应 `C-x` 或条款，步骤见 [README.md](README.md)「维护清单」。

| 编号 | 状态 | 事项 | 说明 |
|---|---|---|---|
| Q1 | 待对方 | `schd` 一条 Kafka 消息里装多少变更 | 见 `C-9` |
| Q2 | 待对方 | FLOP 里 `SRVT`/`VIPF` 等集合段缺席是否等于删除 | 见 `G-SRVT-VIPF` |
| Q3 | 待对方 | SIS 没写明的 FLOP 子类型怎么解析、处理完算啥 | 按现有逻辑处理（`US-05` AC1）；见 `G-FLOP-SEMANTICS`、`CLM-1` |
| Q4 | 待对方 | 上游重发时会不会改正文 | 假定内容不变，只认身份；改正文会被当重复跳过 |
| Q5 | 待对方 | `msg` 消息体格式、变更与删除怎么区分 | 沿用旧系统 JSON（接口契约「Kafka」） |
| Q6 | 待对方 | 网页客户端怎么读 Redis 快照 | 见 `C-11`；`MAFL` 是否提供未定 |
| Q7 | 已定 | 信箱编号只增不减、不重用 | `INV-1`、`CLM-2`、`US-01` AC3 |
| Q8 | 已定 | 入站处理时间列名 `CMINMSGS_DATE_PROCESSED` | 术语「处理标记」、`US-10` |
| Q9 | 已定 | 入站行删除条件与保留期 | `C-1` |
| Q10 | 已定 | `SEQN` 重置与身份规则 | `C-3` |
| Q11 | 已定 | 日计划没带字段是否删除 | `C-6` |
| Q12 | 已定 | 主航班与共享航班删除联动 | `US-06` AC2 |
| Q13 | 已定 | `RQRD` / `RQFD` 编码字段 | `C-4` |
| Q14 | 本系统 | 生产用 PostgreSQL 还是 Oracle 11g | Oracle 未验证前不作支持承诺 |
| Q15 | 本系统 | `POST /cminmsgs/send` HTTP 约定 | 大小上限、状态码、响应体；见 `C-7` |
| Q16 | 本系统 | `POST /schd/sync` 请求与响应 | 见 `C-8` |
| Q17 | 本系统 | 人工发 `RQRD` 的入口 | `US-09` 要求能人工发，HTTP 清单里没有 |
| Q18 | 本系统 | 回退时正在处理的消息怎么办 | 见 `OPS-4` |
| Q19 | — | （未分配） | — |
| Q20 | — | （未分配） | — |
| Q21 | 本系统 | `GET /all/flights` HTTP 约定 | 见 `C-11` |
| Q22 | 本系统 | 静态参考数据对应哪些表 | 见 `C-10`、接口契约 |
| Q23 | 本系统 | Elasticsearch 历史怎么写、保留多久 | 见 `US-14`、`G-FLIGHT-HIST-RETENTION` |
| Q24 | 本系统 | `REQ_TRACK` 已结案记录保留多久 | 见 `G-REQ-TRACK-RETENTION` |
| Q25 | 本系统 | 季度计划从哪来、什么格式 | SIS 只有日计划；旧系统读 Oracle 季度表 |

状态说明：**待对方** = 需对接方确认；**已定** = 结论已写入 `C-x`/`INV-x`；**本系统** = 由本系统与需求方决定；**—** = 编号保留未用。

## 7. 当前已知偏差

偏差标记只在本表定义；其他文档只写 `G-NAME`。解决后删本行及全仓引用。

| 偏差 | 缺什么（交付进度见 Plane） | 影响 |
|---|---|---|
| `G-FLIGHT-HIST-RETENTION` | 历史保留期与容量上限未定（`Q23`） | `US-14` |
| `G-FLOP-IDEMPOTENT` | 各类 FLOP 重复处理规则未写完 | `US-03`；`CLM-1` |
| `G-FLOP-SEMANTICS` | 动态报文处理与 `US-05` 要求不一致 | `US-05` |
| `G-FLOP-UNMAPPED` | [XSD](legacy/unisysaodbsis.xsd) FLOP 字段映射不全 | `US-05` |
| `G-MAFL` | 主航班共享列表未做 | `US-06` AC2 |
| `G-PROC-CLEANUP` | 处理记录到期清理未做 | `US-11` |
| `G-REDIS-PROJECTION` | Redis 快照写入与删除未做 | `US-05`、`US-06`、`US-07`、`US-12` |
| `G-REF-DATA` | 静态参考数据处理与 admin-api 直读未做 | `US-13` |
| `G-REQ-OPEN-UNIQUE` | 同类型未处理完时不允许再发，未做 | `US-09` |
| `G-REQ-TRACK` | 出站请求跟踪未做 | `US-09` |
| `G-REQ-TRACK-RETENTION` | `REQ_TRACK` 已结案保留期未定（`Q24`） | `US-09` |
| `G-RESP-GUARD` | `SCHD-RESP` 过期判断未做 | `US-07` |
| `G-SCAN-PREDICATE` | 按「处理时间为空」扫描未做 | `US-01`；`INV-1` |
| `G-SCHD-SNAPSHOT` | 日计划快照删除、清空、分批未做 | `INV-7`、`INV-9` |
| `G-SRVT-VIPF` | `SRVT`、`VIPF` 明细未入库（`Q2`） | `US-05` |

## 8. 验证映射

按条款编号排列。

| 条款 | 需求验收 | 要观察的结果 |
|---|---|---|
| C-5、`US-06` AC2 | `US-06` AC2 | 删共享联动主航班；删主级联删共享 |
| C-7 | `US-02` AC1～AC5 | 三种 Content-Type、UTF-8；空/超长/非法 XML 不写入；禁外部资源；成功编号只表示已写入；与 adapter 同路径建记录 |
| C-8、CLM-4 | `US-09` AC1～AC3 | 出站写入 `COUTMSGS`；HTTP 触发先登记，旧的处理完才写入信箱 |
| C-9、CLM-3 | `US-08` AC1～AC3 | `msg` 单条、`schd` 批量；失败可重试；`msg` 同 `FLID` 保序；同条可能发多次 |
| C-10 | `US-13` AC1～AC4 | 全量替换、增删改逐条；空值表示无值不是删除；单类校验失败只停该类 |
| INV-1（建立处理记录） | `US-01` AC1/AC2/AC4 | 重扫与重启后记录数不变、行不丢；同一编号重复出现时不新增记录 |
| INV-2 | `US-10` AC1/AC2 | 处理结束后才写回；重启后继续；一直失败有记录与告警 |
| INV-3、INV-10 | `US-03` AC4、`US-05` AC4、`US-06` AC1 | Redis 失败时不记「处理结束」与「还要写回」；完成前不发 Kafka |
| INV-4 | `US-07` AC1 | 校验失败后 PG 航班数据不变 |
| INV-5 | 架构「数据归属与一致性」 | 航班数据只写入自有 PG |
| INV-6 | implementation.md「数据模型」 | `FLID` 唯一 |
| INV-7 | `US-07` AC2/AC3 | 快照缺席航班标删并从 Redis 删；未带字段清空 |
| INV-8 | `US-06` AC1 | 标删后从 Redis 删；失败下轮重做 |
| INV-9 | `US-07` AC4/AC5 | 分批失败全部重来（`G-SCHD-SNAPSHOT` 做完前不可验）；PG 整份写完后再刷 Redis |
| INV-11 | `US-12` AC1/AC2 | 返回全部非共享航班且与 Redis 一致；Redis 故障返回错误 |
| CLM-1（重复不重复生效） | `US-03` AC2/AC3/AC5 | 跳过/无法处理留档且无业务改动；失败可查；PG 已提交不因写回或 Kafka 失败撤销；待 `Q3`、`G-FLOP-IDEMPOTENT`、`G-FLOP-SEMANTICS` |
| CLM-2（升序） | `US-01` AC3、`US-03` AC1 | 按编号从小到大；最前面未完成时后面的不处理 |
| CLM-7（启动拒绝） | `OPS-1` | 配置错误时启动失败 |
| US-04（ADFT 更新） | `US-04` AC2 | ADFT 未带字段保持原值 |
| US-14、D1 | `US-14` AC3/AC4 | 历史写入成功才删实时数据；删事件先于实时删除登记 |
| G-PROC-CLEANUP（未完成不删） | `US-11` AC1/AC2 | 未处理完的记录不清理 |
| OPS-4（切换与回退） | `OPS-4` | 写回处理时间后再切回；在途消息见 `Q18` |
| PRE-1（测试隔离） | `OPS-3` | 测试环境独立 DB、Redis、Kafka，不连生产信箱 |