cdia/msgexchange-v2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix(acm2-107): finalize /all/flights contract and FLTR JSON payload

Browse Source 
Close Q21 into C-11 and emit day-schedule FLTR-shaped JSON for Redis, schd, and query responses.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
windyboy
2026-09-23 11:23:37 +08:00
co-authored by Cursor
parent 43bb561f47
commit f45a0ac898
10 changed files with 103 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contracts/interface-contract.md
+12 -12
View File
@@ -11,17 +11,17 @@
| 接口 | 请求契约 | 成功响应契约 | 失败契约 | 尚需确定 |
|---|---|---|---|---|
| `POST /cminmsgs/send` | 请求体是 XML 原文；接受 `text/xml`、`application/xml`、`text/plain`，默认 UTF-8；仅限内网，网络层限制来源。 | 报文写入 `CMINMSGS` 后返回信箱编号；写入的报文与上游投递走同一条处理路径、效果一致；该响应只证明已落信，不证明业务处理或下游投递（`US-02`）。 | 空报文、超大小上限、非法 XML 不落信并返回错误；写信失败不返回编号；XML 解析禁用外部实体和外部资源访问。 | 大小上限、请求编码与 `Content-Type` 的精确处理规则、HTTP 状态码、成功/失败响应体字段及样例（`Q15`）。 |
| `POST /schd/sync` | 触发一次 `RQFD` 日计划请求；请求字段尚未定义，登记与落信规则见「在途与作废」。 | 响应内容尚未定义；无论表示登记还是落信，都不代表 AODB 已收到。 | 错误响应尚未定义。 | 请求字段与时间格式、成功响应表示已登记还是已落信（`Q16`）、状态码、响应字段及样例。 |
| `GET /all/flights` | 无已定义的请求字段；从 Redis 投影读取当前全部动态航班，不含共享航班，与网页客户端同源（`US-12`）。 | HTTP 200；响应体是裸 JSON 数组（不套旧 `ResponseDto`），元素为与 `KAFKA:schd` 同形的航班 JSON；共享航班（标量 `MAID` 非空）不出现在数组里；不分页（`Q21` 暂定）。 | HTTP 503；JSON 对象 `{"error":"FLIGHT_PROJECTION_UNAVAILABLE","reason":"<细节>"}`；Redis 或投影读失败时不得返回 200 空数组。 | 数组元素字段是否与旧 `SCHD.FLTR` 逐字一致的对拍样例。 |
| `POST /schd/sync` | 触发一次 `RQFD` 日计划请求；请求体为空、请求全量（`C-4`）；登记与落信规则见「在途与作废」。 | HTTP 200，返回请求编号；只表示已登记，不代表已落信、更不代表 AODB 已收到。 | 已有未结案请求时 HTTP 409，响应体 `open-request-exists`。 | — |
| `GET /all/flights` | 无已定义的请求字段；从 Redis 投影读取当前全部动态航班，不含共享航班，与网页客户端同源（`US-12`）。 | HTTP 200；响应体是裸 JSON 数组（不套旧 `ResponseDto`），元素为日计划 `SCHD.FLTR` 转成的 JSON，与 `KAFKA:schd` 数组元素同形（`C-9`、`C-11`）；共享航班（`MAID` 非空）不出现在数组里；不分页。 | HTTP 503；JSON 对象 `{"error":"FLIGHT_PROJECTION_UNAVAILABLE","reason":"<细节>"}`；Redis 或投影读失败时不得返回 200 空数组（`INV-11`）。 | — |
旧系统线索（来源：旧项目用户故事「HTTP 接口清单」「日计划请求」）：
- 三个接口共用 `ResponseDto`，字段为 `is_success`、`err_code`、`err_msg`、`body`。
- `POST /cminmsgs/send` 的成功 `body` 是 `CMINMSGS_ID`，样例为 `{is_success: true, body: <ID>}`。
- 旧 `GET /all/flights` 用 `ResponseDto`，`body` 是非共享航班的 `SCHD.FLTR` 列表；新版暂定直接返回该列表对应的 JSON 数组（`Q21`）。
- `POST /schd/sync` 的请求体是 `{startDate, endDate}`，时间格式 `yyyy-MM-dd hh:mm` 用无 AM/PM 的 12 小时制。
- 旧 `GET /all/flights` 用 `ResponseDto`，`body` 是非共享航班的 `SCHD.FLTR` 列表（对象即日计划 XML 解码后的 `FLTR`，再序列化为 JSON）；新版成功体直接返回该列表对应的裸 JSON 数组（`C-11`），元素形状不变。
- `POST /schd/sync` 的请求体是 `{startDate, endDate}`，时间格式 `yyyy-MM-dd hh:mm` 用无 AM/PM 的 12 小时制，解析结果写进 `RQFD` 的 `STDB`/`STDE`（`ddMMMyyHHmm`，大写）。
这些字段是否沿用、时间改用何种无歧义格式，都要核对后定稿。新版日计划是 AODB 当前时刻的完整航班列表（`US-07`），出站编码已定（`C-4`），不带日期筛选。
旧系统的 `{startDate, endDate}` 与 `RQFD` 的 `STDB`/`STDE` 均不沿用：新版日计划是 AODB 当前时刻的完整航班列表（`US-07`），出站编码已定（`C-4`），不带日期筛选；`POST /schd/sync` 请求与响应口径见 `Q16`。旧系统响应体是否能作为 `POST /cminmsgs/send` 的定稿样例，见 `Q15`。
## 入站报文与请求应答
@@ -40,8 +40,8 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定
| 主题 | 已确定的消息语义 | 尚需确定 |
|---|---|---|
| `msg` | 单条航班变更通知；航班动态与删除处理完成后投递；发送失败自动重试，一直失败的记录保留可查并告警（`US-08`）；同一 `FLID` 的变更保序，对外按至少一次投递（`CLM-3`，单分区）。删除通知的来源有三处：`FDEL` 删除（`US-06`）、日计划快照覆盖范围内缺席删除（`US-07`）、历史清理在物理删除前必要时登记（架构 `D1`）。 | Kafka value 的字段与类型、变更和删除的区分方式（`Q5`）、编码方式。 |
| `schd` | 定时批量发送最新航班状态；两次 tick 之间积累的航班组成 `SCHD.FLTR` 数组 JSON，整批作为单条 record 发出（沿用旧系统，`Q1`）；空字段不输出，字段与类型见 [XSD](../legacy/unisysaodbsis.xsd) 的 `FLTR`；没有变化不发；删除航班不进入本主题，由 `msg` 发一条删除通知；发送失败自动重试，对外按至少一次投递（`US-08`）。 | 消费方按数组格式解析的确认（`Q1`）。 |
| `msg` | 单条航班变更通知；Kafka value 是整条 `MSG` 的 JSON（`META` 加对应业务体，空字段不输出），变更与删除由 `META` 的类型与子类型区分（`Q5`）；航班动态与删除处理完成后投递；发送失败自动重试，一直失败的记录保留可查并告警（`US-08`）；同一 `FLID` 的变更保序，对外按至少一次投递（`CLM-3`，单分区）。删除通知的来源有三处：`FDEL` 删除（`US-06`）、日计划快照覆盖范围内缺席删除（`US-07`）、历史清理在物理删除前必要时登记（架构 `D1`）。 | 编码方式（JSON 之外的压缩或封装是否引入）。 |
| `schd` | 定时批量发送最新航班状态；两次 tick 之间积累的航班组成 `SCHD.FLTR` 数组 JSON，整批作为单条 record 发出，条数不设上限（沿用旧系统，`Q1`）；空字段不输出，字段与类型见 [XSD](../legacy/unisysaodbsis.xsd) 的 `FLTR`；没有变化不发；删除航班不进入本主题，由 `msg` 发一条删除通知；发送失败自动重试，对外按至少一次投递（`US-08`）。 | — |
旧系统线索（来源：旧项目用户故事「前端通知」「动态类（FLOP-*）处理」）：
@@ -75,13 +75,13 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定
| 存储 | 承载内容 | 边界 | 尚需确定 |
|---|---|---|---|
| Redis | 航班查询投影 | 只作查询，不是权威，也不存处理状态；只由本系统写入和移除，网页客户端与 `GET /all/flights` 读同一份，内容来自自有 PostgreSQL 的航班当前态；写投影成功、删除时移除成功，才算对应消息处理完成（架构「数据归属与一致性」；`US-05`、`US-06`）。 | 网页客户端读取约定（`Q6`）。 |
| Redis | 航班查询投影 | 只作查询，不是权威，也不存处理状态；只由本系统写入和移除，网页客户端经 `GET /all/flights` 读同一份、不直连 Redis，内容来自自有 PostgreSQL 的航班当前态；投影 value 与 `KAFKA:schd` 数组元素、查询成功体元素同形，均为日计划 `FLTR` 转成的 JSON（`C-9`、`C-11`）；写投影成功、删除时移除成功，才算对应消息处理完成（架构「数据归属与一致性」；`US-05`、`US-06`）。 | — |
旧系统线索（来源：旧项目用户故事「Redis key 汇总」「术语与数据语义」「动态航班转历史」）：
- 投影是 hash `flightInfo`：field 为 `FLID`，value 为完整 `SCHD.FLTR` 对象的带类型 JSON，不设过期；Redis 里没有名为 `schd` 的 key，`schd` 只是 Kafka 主题。
- 投影是 hash `flightInfo`：field 为 `FLID`，value 为完整 `SCHD.FLTR` 对象的带类型 JSON，不设过期；Redis 里没有名为 `schd` 的 key，`schd` 只是 Kafka 主题。新版 value 仍是 `FLTR` 转 JSON，但不使用旧系统的 Jackson 默认类型标注。
- 写入路径：日计划下载（`DNLD`／`RESP`）整体写入当天航班，单条变更（`ADFT`、`FLOP`）只写对应的一条，转历史时按 `FLID` 逐条移除。整体写入不删除本次映射中缺席的航班，与 `US-07` AC5 相反，新版按 `US-07` AC5 在覆盖范围内刷新。
- 写入前生成主航班的共享航班列表 `MAFL`（`G-MAFL`），是否为网页客户端所需仍未定（`Q6`）；登机桥字段 `abdg` 本版不提供——旧系统拼它的数据源是机位与登机桥映射缓存，已列入需求「范围与非目标」不交付。
- 写入前生成主航班的共享航班列表 `MAFL`，共享航班不单列、随主航班下发（`Q6`）；旧系统在日计划下载时按 `MAID` 把共享航班挂进主航班 `MAFL`，登机桥字段 `abdg` 本版不提供——旧系统拼它的数据源是机位与登机桥映射缓存，已列入需求「范围与非目标」不交付。
### 自有 PostgreSQL：内部存储与 admin-api 只读
@@ -91,7 +91,7 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定
| 航班当前态表 | 航班当前态的唯一权威；`FLID` 唯一（`INV-6`）；Redis 和 Kafka 从处理结果派生，不反向覆盖这些表。 | 主键、字段与类型、外键/索引。 |
| 内部处理表 | 管道处理、请求跟踪、留痕与互斥由本系统维护；不对外提供直接读写接口。 | 字段与约束由内部实现设计确定。 |
admin-api 还从本系统数据库只读季度计划；供数方与报文形态待 `Q25` 确定。
季度计划不属本系统边界：admin-api 直接读 Oracle `FIMS_FLIGHTSCHD_SEASON`（`Q25`、[legacy/flight-apis.md](../legacy/flight-apis.md)），本系统只提供日计划请求。
自有 PostgreSQL 的物理表结构由本系统的迁移定稿。生产环境若改用 Oracle 11g，字段类型需先完成适配验证。
@@ -130,4 +130,4 @@ admin-api 还从本系统数据库只读季度计划；供数方与报文形态
## 待决事项
由本系统与需求方确定的事项见 [specification.md](../specification.md)「本系统与需求方待决」。
由本系统与需求方确定的事项见 [specification.md](../specification.md)「待确认事项台账」。