102 lines
11 KiB
Markdown
102 lines
11 KiB
Markdown
# 接口契约草案
|
||
|
||
本文记录 msgexchange-v2 与联调工具、运营航班显示界面、CIIMS adapter、admin-api、Elasticsearch 航班历史存储之间需要共同遵守的接口。范围由 [requirements.md](../requirements.md) 的 `US-02`、`US-08`、`US-09`、`US-12`、`US-13`、`US-14` 和 [architecture.md](../architecture.md)「系统定位与范围」「数据归属与一致性」确定；下表没有给出字段的地方，不能作为字段级联调依据。
|
||
|
||
《msgexchange-api 旧项目业务逻辑与用户故事文档》只提供现役行为基线。下文的“现役候选”是待对拍的字段线索；旧系统未校验收报 XML、Kafka 批次可能丢失、航班从 Redis 转历史的做法不改变本文件的目标边界。
|
||
|
||
## HTTP
|
||
|
||
| 接口 | 请求契约 | 成功响应契约 | 失败契约 | 尚需确定 |
|
||
|---|---|---|---|---|
|
||
| `POST /cminmsgs/send` | 请求体是 XML 原文；接受 `text/xml`、`application/xml`、`text/plain`，默认 UTF-8；仅限内网，网络层限制来源。 | 报文写入 `CMINMSGS` 后返回信箱编号；该响应只证明已落信，不证明业务处理或下游投递。 | 空报文、超大小上限、非法 XML 不落信并返回错误；写信失败不返回编号；XML 解析禁用外部实体和外部资源访问。 | 大小上限、请求编码与 `Content-Type` 的精确处理规则、HTTP 状态码、成功/失败响应体字段及样例。 |
|
||
| `POST /schd/sync` | 触发向 AODB 请求日计划的 `RQFD` 请求。 | 响应内容尚未定义。 | 错误响应尚未定义。 | 请求字段、重复调用语义、请求登记或落信与响应之间的关系、状态码、响应字段及样例。 |
|
||
| `GET /all/flights` | 无已定义的请求字段；从 Redis 查询投影读取当前全部动态航班，不含共享航班。 | 返回查询到的航班集合。 | Redis 异常时返回错误，不能返回空列表伪装成功。 | 查询参数、分页规则、航班字段与类型、集合外层结构、状态码和错误响应样例。 |
|
||
|
||
现役候选：三个接口使用 `ResponseDto`，字段为 `is_success`、`err_code`、`err_msg`、`body`（旧项目用户故事「HTTP 接口清单」）。`POST /cminmsgs/send` 的成功 `body` 是 `CMINMSGS_ID`，旧样例为 `{is_success: true, body: <ID>}`；`GET /all/flights` 的 `body` 是非共享航班的 `SCHD.FLTR` 列表。`POST /schd/sync` 的旧请求体是 `{startDate, endDate}`，旧格式 `yyyy-MM-dd hh:mm` 使用无 AM/PM 的 12 小时制，存在时间歧义；字段是否沿用、时间改用何种无歧义格式、响应是否沿用封装，都需对拍后定稿。
|
||
|
||
旧 `/schd/sync` 把日期范围编码为 `RQFD.STDB` / `STDE`，旧出站报文使用 `TYPE=RQFD`、`STYP=NONE`、`SNDR=OSH5`（旧项目用户故事「日计划请求」）。这些是报文构造线索，发送方取值、时间格式与新版请求跟踪语义仍需对接方确认。
|
||
|
||
## Kafka
|
||
|
||
| 主题 | 已确定的消息语义 | 尚需确定 |
|
||
|---|---|---|
|
||
| `msg` | 单条航班变更通知；处理航班动态与删除后投递，发送失败自动重试；同一 `FLID` 的变更保序，对外按至少一次投递。 | Kafka key、value 的字段与类型、变更和删除的区分方式、版本与去重标识、编码方式、分区规则、消费者处理重复和乱序的规则。 |
|
||
| `schd` | 定时批量发送最新航班状态；发送失败自动重试；对外按至少一次投递。 | “批量”对应的 Kafka record 粒度、key/value 字段与类型、删除航班的表达方式、批次边界、编码方式、消费者去重规则。 |
|
||
|
||
现役候选：`msg` 的 value 是 `MSG` 的 JSON，包含 `META` 与对应业务体；日计划到达通知只有 `META`。`schd` 每次把窗口内航班组成 `SCHD.FLTR` 数组 JSON，队列为空时不发送（旧项目用户故事「前端通知」）；这能提供消费者样例，仍不能确定新版的 Kafka key、最新状态聚合粒度或去重标识。
|
||
|
||
跨航班顺序不构成契约；测试环境须使用独立 Kafka 主题。
|
||
|
||
## 数据库读写边界
|
||
|
||
### 共享 MySQL：外部信箱
|
||
|
||
| 表 | 本系统的操作 | 需要对接方提供的物理契约 |
|
||
|---|---|---|
|
||
| `CMINMSGS` | 按信箱编号升序、分批读取处理标记为空的报文；兼容 HTTP 入口写入 XML 原文；处理完成后仅将空处理标记写成库方认可的已处理值。 | 表 DDL、信箱编号及报文原文字段、处理标记与处理时间字段、列类型与可空性、写入必需列、标记允许值、原文保留期和索引。 |
|
||
| `COUTMSGS` | 写入 `RQRD` 参考数据请求与 `RQFD` 日计划请求；CIIMS adapter 消费。交付承诺止于请求落信。 | 表 DDL、请求原文字段、写入必需列、编号生成方式、ACK/错误列的写入责任、重复落信的识别规则。 |
|
||
|
||
共享 MySQL 归 CIIMS adapter 方所有；本系统不建表、不改表结构、不清除数据，也不写共享历史表。外部表的物理字段必须以对接方提供的现行 DDL 与读写样例核对，不能由本文件推造。
|
||
|
||
旧项目用户故事「数据表列清单」提供以下**实体映射列名**，不是现场 DDL、可空性或写权限的证明：
|
||
|
||
| 表 | 现役实体映射列名 | 现役写入线索 |
|
||
|---|---|---|
|
||
| `CMINMSGS` | `CMINMSGS_ID`、`CMINMSGS_CLOB_MSG`、`CMINMSGS_DATE_RECEIVED`、`CMINMSGS_DATE_PROCESSED`、`CMINMSGS_STATUS`、`CMINMSGS_SUBSYSTEM_DATE_SENT`、`CMINMSGS_SUBSYSTEM_NAME`、`CMINMSGS_SUBSYSTEM_SEQUENCE`、`CMINMSGS_SUBSYSTEM_SUBTYPE`、`CMINMSGS_SUBSYSTEM_TYPE` | 兼容入口写原始 XML 与接收时间，处理时间为空；新版必须先按 `US-02` 校验 XML。 |
|
||
| `COUTMSGS` | `COUTMSGS_ID`、`COUTMSGS_ACK_DATE_RECV`、`COUTMSGS_ACK_REQD`、`COUTMSGS_ACK_RESEND_TIMES`、`COUTMSGS_CLOB_MSG`、`COUTMSGS_DATE_INSERTED`、`COUTMSGS_DATE_SENT`、`COUTMSGS_ENCRYPT`、`COUTMSGS_ERROR`、`COUTMSGS_FINAL_GROUP_IND`、`COUTMSGS_GROUP_ID`、`COUTMSGS_GROUP_ORDER`、`COUTMSGS_NO_MESSAGES`、`COUTMSGS_TRUEFALS_GROUP`、`ROUTINGID` | 旧 `/schd/sync` 写报文 XML、插入时间与 `ROUTINGID=OSH5RQFD`；ACK/错误列的写入责任仍未确认。 |
|
||
|
||
### 自有 PostgreSQL：内部存储与下游读取
|
||
|
||
| 表或表组 | 边界 | 尚需确定的字段级契约 |
|
||
|---|---|---|
|
||
| `REF_MASTER` | 静态参考数据与资源状态按类别、编号保存在独立数据表，admin-api 直接只读；新消息覆盖旧记录，全量消息整体替换，增删改消息逐条处理。 | 类别和编号的物理列、各类别字段及类型、主键/唯一键、空值表示、更新可见性。类别范围与消息中的识别标签见下表。 |
|
||
| `FLIGHT_SCHD`、资源明细表、`FLIGHT_ROUTE_POINT` | 航班当前态的唯一权威；Redis 和 Kafka 从处理结果派生，不反向覆盖这些表。 | 主键、字段与类型、资源明细表清单、外键/索引、版本字段及迁移 DDL。 |
|
||
| `PROC_STATE`、`MSG_EVENT`、`REQ_TRACK`、`SCHD_SNAP_LOG`、`PIPELINE_LOCK`、`UNMAPPED_FIELD` | 管道处理、待发事件、请求跟踪、留痕、互斥及未映射字段由本系统维护；不对外提供直接读写接口。 | 字段、约束、索引与迁移 DDL 由内部实现设计确定；若其他系统需读取，须另立读取契约。 |
|
||
|
||
自有 PostgreSQL 的物理表结构由本系统的迁移 DDL 定稿。生产环境若改用 Oracle 11g，字段类型与迁移方案需先完成适配验证。
|
||
|
||
### 静态参考数据类别与编号来源
|
||
|
||
类别码与识别标签来自架构引用的 [SIS 接口规范](../legacy/SIS_AODB_RMS-V0.1.md)；每条普通参考记录以对应类别码和识别标签值组成逻辑身份。标签值的格式、唯一范围和 `REF_MASTER` 中的物理存储方式，仍需在本系统的表结构中明确。
|
||
|
||
| 类别码 | 类别 | 消息中的识别标签 | SIS 依据 |
|
||
|---|---|---|---|
|
||
| `COUL` | 国家代码 | `COUC` | `SIS:3.1` |
|
||
| `ARPT` | 机场代码 | `ITCD` | `SIS:3.2` |
|
||
| `AIRL` | 航空公司代码 | `ITOP` | `SIS:3.3` |
|
||
| `AIRC` | 机型代码 | `ITAT` | `SIS:3.4` |
|
||
| `REGN` | 注册号 | `RNUM` | `SIS:3.5` |
|
||
| `ORGN` | 机构代码 | `OGID` | `SIS:3.6` |
|
||
| `FLTL` | 航班类型代码 | `FTYP` | `SIS:3.7` |
|
||
| `TLST` | 航站楼代码 | `TCOD` | `SIS:3.8` |
|
||
| `GLST` | 登机门代码 | `GCOD` | `SIS:3.9` |
|
||
| `SLST` | 机位代码 | `SCOD` | `SIS:3.10` |
|
||
| `CLST` | 值机柜台代码 | `CCOD` | `SIS:3.11` |
|
||
| `BLST` | 行李转盘代码 | `BCOD` | `SIS:3.12` |
|
||
| `CHLT` | 行李滑槽代码 | `CCOD` | `SIS:3.13` |
|
||
|
||
资源状态是第十四类消息，类别码为 `RSTA`（`SIS:3.14`），识别一条资源状态时须同时使用资源类型 `RTYP` 和资源编号 `RSID`；`CLST` 与 `CHLT` 都使用 `CCOD` 标签，因此不能脱离类别码识别记录。
|
||
|
||
## Elasticsearch 航班历史写入
|
||
|
||
| 契约项 | 已确定的边界 | 尚需确定 |
|
||
|---|---|---|
|
||
| 写入对象 | 满足 `US-14` 已结束判据的航班从自有业务数据库写入 Elasticsearch 历史库，作为历史查询副本。 | 历史索引名称、文档 ID、写入字段及类型、嵌套资源结构、字段缺失与删除状态的表达方式。 |
|
||
| 成功确认 | 只有该航班的历史写入成功，才允许从实时数据物理删除；删除前按 `D1` 必要时登记待发删除事件。 | Elasticsearch 写入响应中何种结果算成功、成功是否要求可查询、批量响应如何逐项确认。 |
|
||
| 写入粒度 | 单个航班写入失败不影响其他航班。 | 使用逐条请求还是批量请求、批量大小、部分成功时的确认与继续处理规则。 |
|
||
| 失败与重试 | 写入失败的航班保持在实时数据中，下次运行再试；已写入的航班不重复写入；正在被消息处理的航班跳过，下轮再处理。 | 超时或响应不明时的对账方式、可重试错误分类、重试间隔、文档 ID 和覆盖策略如何保证幂等。 |
|
||
|
||
Elasticsearch 的接口样例与映射确认前，不得以“请求已发送”代替逐航班的成功确认，也不得清除写入结果不明的实时数据。
|
||
|
||
现役候选：旧项目逐航班查询 `flight_hts` 中的 `SODT + FLID` 组合，存在则更新，不存在则新增；写入内容是 `SCHD.FLTR` 序列化后的 JSON，单条写入失败跳过该航班（旧项目用户故事「动态航班转历史」）。`flight_hts` 是旧索引名，`SODT + FLID` 是旧查询条件；新版索引、文档 ID、字段集合和 Elasticsearch 响应的逐航班成功判据仍需确定。
|
||
|
||
## 定稿所需证据
|
||
|
||
1. 对拍三个 HTTP 接口的现役候选字段，取得成功和失败响应样例、实际状态码及 `/schd/sync` 的无歧义时间格式。
|
||
2. 运营航班显示界面的 `msg`、`schd` 消费样例和字段要求，特别是变更、删除、重复投递的处理方式。
|
||
3. CIIMS adapter 方提供的 `CMINMSGS`、`COUTMSGS` 现行 DDL、读写样例和写权限说明，并核对现役实体映射列名。
|
||
4. 13 类参考数据与资源状态的编号规则，以及自有 PostgreSQL 的迁移 DDL。
|
||
5. Elasticsearch 历史索引映射、文档样例、逐条或批量写入响应，以及写入结果不明时的对账规则。
|
||
|
||
只有上述证据核对完成后，待定字段才能转为字段级契约；任何新增字段、默认值或错误码都需写明其来源与对接方。
|