msgexchange-v2/docs/requirements.md

# 需求与验收目标

本文件定义交付范围、非目标与验收口径：**需求定义要交付什么，验收标准定义怎样证明完成**。以下事实以本文件为唯一出处：

- `US-01`～`US-14`（三级标题定义）、`OPS-1`～`OPS-4`（注册表定义）。

本文件只写交付范围与验收口径，不重复代码入口、参数取值和实现机制。

## 1. 范围与非目标

**系统定位**：OMMS H5 查询系统的消息网关。收取 CIIMS adapter 信箱中 AODB 下发的 XML 报文：航班动态写入数据库并同步写 Redis，运营航班的动态消息经 Kafka 发给运营航班显示界面实现同步；静态参考数据写入数据库，供 admin-api 只读。出站仅向 AODB 发参考数据类请求和日计划请求（经 `COUTMSGS`，消费方为 CIIMS adapter）。

**交付范围**：`US-01`～`US-14`、`OPS-1`～`OPS-4`。

**本版本主要新增能力**：静态参考数据同步（`US-13`）。

**非目标**：

- 航班当前态权威只在自有 PG；Redis 仅作查询投影，不作权威或处理状态。不引入并行主泵或分布式锁。
- 共享 MySQL 只做读写消息和写回处理标记，不改表结构、不建表、不清数据。
- 本消息网关只有一个实例，暂不考虑多实例运行方案。
- 对外投递只承诺至少一次；同一航班（`FLID`）内保序，不同航班之间不承诺顺序。
- 测试环境用 PostgreSQL；生产环境尚未决定用 PostgreSQL 还是 Oracle 11g，Oracle 适配验证通过前不构成支持承诺。
- 已结束的航班写入 Elasticsearch 历史库后从实时数据删除。
- 不生成航班/业务数据类报文，不替代 CIIMS/AODB，不提供 AODB 主数据编辑能力。
- 不调用 admin-api，不从 admin-api 拉取、补全或合并任何数据。

## 2. 用户故事

### US-01 可靠采集共享信箱

**目标**：本系统持续、可恢复地从共享 MySQL 信箱读取上游写入的消息，不丢、不漏。

**验收标准**

1. 按配置周期查信箱中「处理时间为空」的消息，每次一批有上限；已处理的消息不再重复采集。
2. 同一条消息只会被登记和处理一次：扫描重来、重启恢复都不会造成重复处理。
3. 消息按到达顺序处理（信箱编号即到达顺序）。
4. 本系统故障期间信箱消息不受影响；恢复后从「处理时间为空」的消息继续，不丢、不漏。

### US-02 兼容 HTTP 注入报文

**目标**：提供 HTTP 接口 `POST /cminmsgs/send`，联调工具可把 XML 报文直接写进信箱，效果与上游投递一致。

**验收标准**

1. 报文为 XML，支持 `text/xml`、`application/xml`、`text/plain`，默认 UTF-8。
2. 空报文、超大小上限、格式错误的 XML：返回错误，不写入信箱；解析禁用外部实体与外部资源访问。
3. 写入成功返回信箱编号；写入失败返回失败，不返回编号。
4. 成功只表示报文已进信箱，不代表已处理或下游已收到。
5. 仅限内网使用，由网络层限制来源。

### US-03 按顺序、不重复地处理消息

**目标**：消息按到达顺序逐条处理；同一条消息不会产生两次效果。

**验收标准**

1. 一次只处理一条消息，取编号最小的未完成消息；处理中的消息不让后面的越过。
2. 报文不合法：进死信。报文合法但本系统不支持该类型：跳过留档，按已处理写回标记。原始报文留在信箱，保留期由库方决定。
3. 处理或提交失败：失败的事务回滚，消息保持未完成，下一轮自动重新处理。
4. 处理只动本系统数据库；发 Kafka、回填信箱在处理完成之后单独做。
5. 错误必须记录到对应消息的处理记录上，不能被外层吞掉。

### US-04 处理计划外航班（ADFT）

**目标**：AODB 计划外新增的航班（临时加班、ATC 指定）建立到本系统。

**验收标准**

1. 航班不存在：创建，字段按报文内容落库；带了计划时间则算出运营日，没带则留空等日计划收录。
2. 航班已存在：按报文更新携带的字段，未携带的不清空。
3. 航班处于已删除状态时收到 ADFT：按报文内容恢复航班。

### US-05 应用运营航班动态（FLOP）

**目标**：运营航班的动态消息（时间、资源、状态变化）如实落到航班数据上，并发 Kafka 消息通知网页客户端。

**验收标准**

1. SIS 的 FLOP 部分列有 25 个动态消息子类型；现场需处理的 7 类为靠桥（`ABTM`）、延误（`DELY`）、计划机位（`PSDT`）、柜台（`CKDT`）、转盘（`CLDT`）、滑槽（`CHDT`）、登机门（`GTDT`）。其中五类资源分配子类型已包含在上述 25 类中，但 SIS 注明 AODB 发来时 RMS 拒收；靠桥、延误在 SIS 的日计划字段中有定义，不属于上述 25 个 FLOP 子类型。现场报文按现有处理逻辑延续。
2. 每个子类型有明确的处理规则：更新哪些字段；报文里字段为空表示清除还是撤销；航班不存在时怎么办。
3. 柜台、转盘、滑槽、登机门、机位五类资源分配报文，现场 AODB 实际会发，照常接收处理（消息接口规范写的是相反方向，与 AODB 核对确认）；航线路线最多保留 4 条；未落到航班当前态的字段，按信箱编号、路径和出现序号唯一记入自有数据库长期记录，保存原值，不随处理记录到期清理。
4. 数据写入 Redis 成功，这条消息才算处理完成；写失败不标记已处理，下轮重新处理。

### US-06 删除航班（FDEL）

**目标**：按 AODB 指令删除航班；共享航班与主航班联动删除，不允许删了一半。

**验收标准**

1. 删除航班：标记已删除、从 Redis 移除、发 Kafka 删除消息通知网页客户端；Redis 移除成功才算处理完成，失败下轮重新处理。
2. 删除共享航班时联动更新其主航班；删除主航班时级联删除其共享航班。

### US-07 导入日计划（DNLD / RESP）

**目标**：日计划是 AODB 当前时刻的完整航班列表：AODB 主动下发（DNLD）或本系统请求后应答（RESP），收到后分批同步本地数据；整包成功时本地航班当前态与快照一致——请求日计划就是主动与 AODB 全量同步一次。

| 报文 | 说明 |
|---|---|
| `SCHD-DNLD` | AODB 主动下发，直接处理。 |
| `SCHD-RESP` | 本系统请求后的应答，只在请求未过期时生效；迟到的应答不更新数据。 |

**验收标准**

1. 报文整体校验（声明的航班数、航班标识等）通过才处理；校验失败整包拒绝，本地数据不变。
2. 报文里的航班逐条写入或更新；快照里没有的航班，在本地标记已删除，并登记待发删除消息。
3. 以 AODB 下发的数据为准：日计划里某航班没携带的字段，视为 AODB 已删除该值，本地同步清掉。
4. 航班量大，分批写入数据库，每批一个事务；处理失败不标记已处理，下轮整包重新处理。
5. 按快照结果刷新 Redis：报文里的航班写入，缺席的航班移除。

### US-08 通知网页客户端（Kafka）

**目标**：航班数据变化后发 Kafka 消息，网页客户端据此刷新显示。

**验收标准**

1. 两个 Kafka 主题：`msg` 发单条航班变更，`schd` 定时批量发最新状态。
2. 发送失败自动重试；同一航班的变更按顺序发送。
3. 发送一直失败的记录保留并可查，有告警。

### US-09 向 AODB 请求数据

**目标**：本系统可以主动向 AODB 要数据：14 类参考数据（`RQRD`）+ 1 类日计划（`RQFD`），子类型以消息接口规范为准。参考数据请求由人工发起，日计划请求由 `POST /schd/sync` 触发。

**验收标准**

1. `RQRD` 与 `RQFD` 各自同时最多一条已落信、未结案的请求；同一子类型发新请求时旧请求作废，新请求登记为待发送，等同一报文类型的在途请求收到应答、失败或超时后再落信。请求超过时限未等到应答，标记超时。
2. 应答到达时按报文类型对应到等待中的请求；AODB 发错或迟到的应答不更新数据，记录后跳过。
3. 收到 EROR（AODB 错误回报）：定位到本系统发出的请求，标记失败并告警。

### US-10 回写信箱处理标记

**目标**：处理完消息，把信箱里对应消息标记上处理时间，保证信箱行最终全部有标记。

**验收标准**

1. 处理完成时在本地记录「待标记」，后台任务把它写到 MySQL 信箱。
2. 写失败自动重试，重启后继续；一直写不上的记录在案并告警。

### US-11 处理记录清理

**目标**：处理记录只用于追踪消息处理情况和排查问题，没有长期保留价值；定期删掉老记录，防止表无限增长。

**验收标准**

1. 处理完、标记也写回信箱的记录，超过保留期后删除；没处理完的不删。
2. 保留期可配置。

### US-12 查询全部航班

**目标**：提供查询接口 `GET /all/flights`，返回当前全部动态航班（不含共享航班）。

**验收标准**

1. 从 Redis 读取，与网页客户端查询同源。
2. Redis 异常时报错，不返回空列表假装正常。

### US-13 同步静态参考数据

**目标**：接收 AODB 通过信箱下发的机场基础数据（国家、机场、航空公司、机型、登机口、机位等 13 类）和资源状态，保存到数据库，供查询系统使用。

**验收标准**

1. 数据按类别和编号保存，新消息覆盖旧记录。
2. 一类数据校验不通过就不更新这一类，其他类照常；已有数据不动。
3. 全量消息整体替换，增删改消息逐条处理。
4. 消息里字段为空表示「当前没有值」，不是删除。
5. 参考数据保存在独立的数据表中，查询系统（admin-api）直接读取。

### US-14 航班历史与清理

**目标**：已结束运营的航班转入历史存储供历史查询使用，并从实时数据中删除，保持实时数据精简。

**验收标准**

1. 每天凌晨定时执行（每日 3:30）：读取全部实时航班，已结束的航班写入 Elasticsearch 历史库。
2. 满足任一条件即视为已结束：
   - 计划时间早于当前超过 3 天；
   - 取消时间（CNCL）早于当前超过 1 小时；
   - 备降：应降本场、实际降其他机场，且计划时间早于当前超过 1 小时；
   - 离港航班：计划时间早于当日、有实际起飞时间、且实际起飞不晚于当前；
   - 到港航班：计划时间早于当日、有实际到达时间、且实际到达时间早于当前超过 1 小时。
3. 只有历史写入成功的航班才从实时数据删除；写入失败下次重来，已写入的不重复写入。
4. 单个航班写入失败不影响其他航班；正在被消息处理的航班跳过，下轮再处理。

## 3. 运行验收

| 编号 | 要求 | 验证方式 |
|---|---|---|
| `OPS-1` | 单实例运行：系统配置不完整时拒绝启动；同一时刻只允许一个实例处理消息。 | 配置错误启动失败测试；双实例同时启动测试。 |
| `OPS-2` | 可观测：消息积压、处理失败、发送失败、标记写回失败都有监控指标和告警。 | 故障注入触发告警；检查监控面板。 |
| `OPS-3` | 测试隔离：测试环境的实例使用独立的数据库、Redis、Kafka 主题，不连接生产信箱。 | 配置检查。 |
| `OPS-4` | 切换与回退：停旧系统、启新系统完成切换；出问题回退时停新、启旧，未处理的消息由旧系统继续，数据不丢。 | 切换与回退演练记录。 |

## 4. HTTP 接口清单

| 接口 | 用途 |
|---|---|
| `POST /cminmsgs/send` | 联调工具写入报文（US-02）。 |
| `POST /schd/sync` | 发起日计划请求（US-09）。 |
| `GET /all/flights` | 查询全部动态航班（US-12）。 |