windyboy
f3b791712b
- "自有业务数据库" → "自有 PG"，与 specification/architecture 统一 - US-05 AC1 钉死现场 7 类子类型，白名单其余待 Q3 确认后增补 - US-05 AC3 恢复未映射字段唯一键（信箱编号+路径+出现序号） - US-09 AC1 恢复旧请求作废可观察约束 - implementation.md VIPP/未映射字段去掉误引 Q3（不在 Q3 范围） - 精简 architecture/requirements 系统定位复述与实现机制泄漏
191 lines
11 KiB
Markdown
191 lines
11 KiB
Markdown
# 需求与验收目标
|
||
|
||
本文件定义交付范围、非目标与验收口径。
|
||
|
||
## 1. 范围与非目标
|
||
|
||
**系统定位**：OMMS H5 查询系统的消息网关。收取 CIIMS adapter 信箱中 AODB 下发的 XML 报文，处理航班动态与静态参考数据；出站仅向 AODB 发参考数据类请求和日计划请求。
|
||
|
||
**交付范围**：`US-01`～`US-14`、`OPS-1`～`OPS-4`。
|
||
|
||
**非目标**：
|
||
|
||
- 航班当前态权威只在自有 PG，开发测试用 PostgreSQL；生产物理选型待 `Q14`，验证通过前不承诺 Oracle 兼容；Redis 仅作查询投影，不作权威或处理状态。
|
||
- 共享 MySQL 只做读写消息和写回处理标记，不改表结构、不建表；已回填的入站行超过保留期后由本系统清理（specification.md 的 `C-1`）。
|
||
- 本消息网关只有一个实例。
|
||
- 对外投递只承诺至少一次；同一航班（`FLID`）内保序，不同航班之间不承诺顺序。
|
||
- 已结束的航班写入 Elasticsearch 历史库后从实时数据删除。
|
||
- 不生成航班/业务数据类报文，不提供 AODB 主数据编辑能力。
|
||
- 不调用 admin-api，不从 admin-api 拉取、补全或合并任何数据。
|
||
- 不在 Redis 缓存机位基础数据与登机桥映射，本版不交付（`C-10`）。
|
||
|
||
**查询侧（admin-api）**：admin-api 从本系统数据库只读基础数据与季度计划（供数方待 `Q25`）；历史航班检索读 Elasticsearch（`Q23`）。其余能力（航班动态导出、字典）不由本系统提供。
|
||
|
||
## 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. 报文不合法：进死信。报文合法但本系统不支持该类型：跳过留档，按已处理写回标记。原始报文留在信箱，已回填的行由本系统按保留期清理（`C-1`）。
|
||
3. 处理或提交失败：失败的事务回滚，消息保持未完成，下一轮自动重新处理。
|
||
4. 发 Kafka 和回填信箱在处理完成之后做；下游失败不影响消息处理结果。
|
||
5. 错误必须记录到对应消息的处理记录上，不能被外层吞掉。
|
||
|
||
### US-04 处理计划外航班（ADFT）
|
||
|
||
**目标**：AODB 计划外新增的航班（临时加班、ATC 指定）建立到本系统。
|
||
|
||
**验收标准**
|
||
|
||
1. 航班不存在：创建，字段按报文内容落库；带了计划时间则算出运营日，没带则留空等日计划收录。
|
||
2. 航班已存在：按报文更新携带的字段，未携带的不清空。
|
||
3. 航班处于已删除状态时收到 ADFT：按报文内容恢复航班。
|
||
|
||
### US-05 应用运营航班动态（FLOP）
|
||
|
||
**目标**：运营航班的动态消息（时间、资源、状态变化）如实落到航班数据上，并发 Kafka 消息通知网页客户端。
|
||
|
||
**验收标准**
|
||
|
||
1. 处理 7 类 FLOP 动态消息：靠桥（`ABTM`）、延误（`DELY`）、计划机位（`PSDT`）、柜台（`CKDT`）、转盘（`CLDT`）、滑槽（`CHDT`）、登机门（`GTDT`）；未知子类型按不支持类型跳过留档（`US-03` AC2）。白名单其余子类型待 `Q3` 以真实报文确认后增补。
|
||
2. 每个子类型有明确的处理规则：更新哪些字段；报文里字段为空表示清除还是撤销；航班不存在时怎么办。
|
||
3. 五类资源分配报文（`CKDT`、`CLDT`、`CHDT`、`GTDT`、`PSDT`）正常接收处理；航线路线最多保留 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 异常时报错，不返回空列表假装正常。
|
||
3. 投影长期保留、不设过期时间，只在航班被删除或转入历史时移除。
|
||
|
||
### US-13 同步静态参考数据
|
||
|
||
**目标**：接收 AODB 通过信箱下发的机场基础数据（国家、机场、航空公司、机型、登机口、机位等 13 类）和资源状态，保存到数据库，供查询系统使用。
|
||
|
||
**验收标准**
|
||
|
||
1. 数据按类别和编号保存，新消息覆盖旧记录。
|
||
2. 一类数据校验不通过就不更新这一类，其他类照常；已有数据不动。
|
||
3. 全量消息整体替换，增删改消息逐条处理。
|
||
4. 消息里字段为空表示「当前没有值」，不是删除。
|
||
|
||
### 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` | 切换与回退：停旧系统、启新系统完成切换；出问题回退时停新、启旧，未处理的消息由旧系统继续，数据不丢。 | 切换与回退演练记录。 |
|