msgexchange-v2/docs/requirements.md

# 需求与验收目标

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

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

代码入口与参数取值不在本文件：前者见 [reference.md](reference.md)「模块与代码入口」，后者见其参数表。前提、不变量、契约与偏差见 [specification.md](specification.md)；机制、航班域与静态参考数据见 [implementation.md](implementation.md)。工程纪律（工具链、测试设施、提交规范）以根 `AGENTS.md` 为唯一出处。

## 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. 动态消息的子类型共 25 类，处理规则以 AODB 与本系统之间的消息接口规范（SIS）为准；规范里没有但现场会发的 7 类（靠桥、延误、计划机位等），按现有处理逻辑延续。
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 类参考数据 + 1 类日计划（请求类型以消息接口规范定义为准）。

**验收标准**

1. 同一类请求同时只有一个在等待；发新请求时旧请求作废。请求超过时限未等到应答，标记超时。
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 天；
   - 已取消超过 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）。 |