16 KiB
接口契约草案
本文记录 msgexchange-v2 与联调工具、运营航班显示界面、CIIMS adapter、admin-api、Elasticsearch 航班历史存储之间需要共同遵守的接口：收报、出站请求与应答、Kafka 通知、Redis 查询投影、共享信箱、参考数据与航班历史。
范围由 requirements.md 与 architecture.md 确定，出处随各条标注；未列出的字段不能作为字段级联调依据。
旧项目用户故事文档（legacy/）只供字段核对，不作为新版契约的依据。
HTTP
| 接口 | 请求契约 | 成功响应契约 | 失败契约 | 尚需确定 |
|---|---|---|---|---|
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 日计划请求；请求体是网页选定的时间条件，写入规则见 C-4；登记与落信规则见「在途与作废」。 |
HTTP 200，返回请求编号；只表示已登记，不代表已落信、更不代表 AODB 已收到。 | 已有未结案请求时 HTTP 409，响应体 open-request-exists。 |
— |
POST /refdata/sync |
触发一次 RQRD 参考数据请求；请求体携带网页选定的类别码 STYP；STYP=RSTA 时须带资源类型 RTYP，其余类别不得带；STYP 取值见 C-4，RTYP 取值见 implementation.md「静态参考数据」；登记与落信规则见「在途与作废」。 |
HTTP 200，返回请求编号；只表示已登记，不代表已落信、更不代表 AODB 已收到。 | 非法 STYP 时 HTTP 400，响应体 unknown-styp；RSTA 缺 RTYP 时 HTTP 400，响应体 missing-rtyp；非 RSTA 带 RTYP 时 HTTP 400，响应体 unexpected-rtyp；已有未结案请求时 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列表（对象即日计划 XML 解码后的FLTR，再序列化为 JSON）；新版成功体直接返回该列表对应的裸 JSON 数组（C-11），元素形状不变。 POST /schd/sync的请求体是{startDate, endDate}，时间格式yyyy-MM-dd hh:mm用无 AM/PM 的 12 小时制，解析结果写进RQFD的STDB/STDE（ddMMMyyHHmm，大写）。
旧系统只把 startDate、endDate 写成 STDB、STDE，时间格式是无 AM/PM 的 12 小时制，新版不沿用这套入参。新版由网页选择时间条件，四个筛选都可传，格式与含义见 C-4；POST /schd/sync 请求与响应口径见 Q16。旧系统响应体是否能作为 POST /cminmsgs/send 的定稿样例，见 Q15。
入站报文与请求应答
AODB 经 CIIMS adapter 把 XML 报文写入 CMINMSGS，格式以架构指定的 SIS 接口规范 与 XSD 为依据。
入站报文按类型处理：ADFT 建立计划外航班，FLOP 改航班动态，FDEL 删航班，SCHD-DNLD 与 SCHD-RESP 同步日计划快照，参考数据写入自有 PG 的 schema basicdata 表组（逻辑视图 REF_MASTER，物理多表映射见 implementation.md「静态参考数据」、Q22 已定；联调栈同 schema 对齐 admin-api 实体注解；US-04～US-07、US-13）；报文不合法进死信，合法但本系统不支持的类型跳过留档并按已处理写回信箱（US-03）。
| 环节 | 已确定的边界 | 尚需确定 |
|---|---|---|
| 出站请求 | 本系统只发 RQRD 参考数据请求与 RQFD 日计划请求，经 COUTMSGS 落信，交付承诺止于落信（US-09、C-4）。 |
超时的时限取值。 |
| 在途与作废 | RQRD 与 RQFD 各自同时最多一条已落信、未结案的请求；同一子类型发新请求时旧请求作废，新请求登记为待发送，等该报文类型的在途请求收到应答、失败或超时后再落信；请求超过时限未等到应答标记超时（US-09）。 |
超时的时限取值。 |
| 应答匹配 | 应答按报文类型对应到等待中的请求；AODB 发错或迟到的应答不更新数据，记录后跳过（US-09）；SCHD-RESP 只在请求未过期时生效，迟到的应答不更新数据（US-07）。 |
请求与应答的对应字段、过期判定的依据字段。 |
| 错误回报 | 收到 EROR 时定位到本系统发出的请求，标记失败并告警（US-09）。 |
EROR 与请求的对应字段。 |
Kafka
| 主题 | 已确定的消息语义 | 尚需确定 |
|---|---|---|
msg |
单条航班变更通知；Kafka value 是整条 MSG 的 JSON（META 加对应业务体，空字段不输出），变更与删除由 META 的类型与子类型区分（Q5）；航班动态与删除处理完成后投递；发送失败自动重试，一直失败的记录保留可查并告警（US-08）；同一 FLID 的变更保序，对外按至少一次投递（CLM-3，单分区）。删除通知的来源有三处：FDEL 删除（US-06）、日计划完整名单覆盖范围内缺席删除（US-07）、历史清理在物理删除前必要时登记（架构 D1）。 |
编码方式（JSON 之外的压缩或封装是否引入）。 |
schd |
定时批量发送最新航班状态；待发航班按单批上限聚成 SCHD.FLTR 数组 JSON，每批作为单条 record 发出，超限部分后续轮次发出（C-9、Q1）；空字段不输出，字段与类型见 XSD 的 FLTR；没有变化不发；删除航班不进入本主题，由 msg 发一条删除通知；发送失败自动重试，对外按至少一次投递（US-08）。 |
— |
旧系统线索（来源：旧项目用户故事「前端通知」「动态类（FLOP-*）处理」）：
msg的 value 是MSG的 JSON，含META与对应业务体；日计划到达通知只有META。- 只对非共享航班的变更单条下发，共享航班随主航班下发；例外是删除，共享航班被删时也单独发一条
msg删除消息。 schd把窗口内航班组成SCHD.FLTR数组 JSON，队列为空时不发送。
两个主题均不设消息键（C-9）；跨航班顺序不构成契约。
测试环境与生产隔离的前提见 specification.md 的 PRE-1（OPS-3）。
存储读写边界
共享 MySQL：外部信箱
| 表 | 本系统的操作 | 需要对接方提供的物理契约 |
|---|---|---|
CMINMSGS |
按信箱编号升序、分批读取未处理的报文，扫描与回写用同一处理时间列（CMINMSGS_DATE_PROCESSED，Q8）；兼容 HTTP 入口写入 XML 原文；处理完成后写入处理完成时刻，只填空值、不覆盖已有值；写回失败由后台任务重试，一直写不上的记录保留在案并告警（US-01、US-02、US-10）。信箱编号即入库行号，单调递增、不复用、不回退（Q7）。 |
表 DDL、信箱编号与报文原文字段、处理时间列的类型与可空性及写入样例（处理标记即该处理时间列，见 specification.md「术语」的处理标记；回填只填空值）、状态列 CMINMSGS_STATUS 的取值集与写权限（Q8 未确认）、写入必需列、原文保留期与清除协议（C-1）和索引。 |
COUTMSGS |
写入 RQRD 参考数据请求与 RQFD 日计划请求；CIIMS adapter 消费。交付承诺止于请求落信；写入结果不明时记录并告警，不直接重发（架构「主流程」）。 |
表 DDL、请求原文字段、写入必需列、编号生成方式、重复落信的识别规则。 |
共享 MySQL 归 CIIMS adapter 方所有；本系统不建表、不改表结构，也不写共享历史表。入站行只写回处理标记，原文保留与清除由库方负责（C-1）。外部表的物理字段必须以对接方提供的现行 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 与接收时间，处理时间为空；旧系统的扫描与回写都落在 CMINMSGS_DATE_PROCESSED（旧项目用户故事「术语与数据语义」）；新版必须先按 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/错误列的写入责任仍未确认。 |
Redis：航班查询投影
| 存储 | 承载内容 | 边界 | 尚需确定 |
|---|---|---|---|
| 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 主题。新版 value 仍是FLTR转 JSON，但不使用旧系统的 Jackson 默认类型标注。 - 写入路径：日计划下载（
DNLD／RESP）写入报文里的航班，单条变更（ADFT、FLOP）只写对应的一条，转历史时按FLID逐条移除。旧系统整体写入不删除本次映射中缺席的航班。新版按US-07AC5：完整名单在覆盖范围内移除缺席航班；带了时间条件的RESP只替换回信里的航班，不因缺席移除其他航班。 - 写入前生成主航班的共享航班列表
MAFL，共享航班不单列、随主航班下发（Q6）；旧系统在日计划下载时按MAID把共享航班挂进主航班MAFL，登机桥字段abdg本版不提供——旧系统拼它的数据源是机位与登机桥映射缓存，已列入需求「范围与非目标」不交付。
自有 PostgreSQL：内部存储与 admin-api 只读
| 表或表组 | 边界 | 尚需确定的字段级契约 |
|---|---|---|
| 静态参考数据表组 | 静态参考数据与资源状态保存在 schema basicdata（逻辑视图 REF_MASTER；RTYPE→表映射见 implementation.md「静态参考数据」、Q22 已定）；表与列取 admin-api 实体注解；全量 DNLD/RESP 整类替换，增量 ADD/UPD/DEL 逐条；单类校验失败不写入该类；空标签表示无值非删除（US-13）。 |
admin-api 生产只读接入与字段裁剪需求。类别码与识别标签见下表。 |
| 航班当前态表 | 航班当前态的唯一权威；FLID 唯一（INV-6）；Redis 和 Kafka 从处理结果派生，不反向覆盖这些表。 |
主键、字段与类型、外键/索引。 |
| 内部处理表 | 管道处理、请求跟踪、留痕与互斥由本系统维护；不对外提供直接读写接口。 | 字段与约束由内部实现设计确定。 |
季度计划不属本系统边界：admin-api 直接读 Oracle FIMS_FLIGHTSCHD_SEASON（Q25、legacy/flight-apis.md），本系统只提供日计划请求。
自有 PostgreSQL 的物理表结构由本系统的迁移定稿。生产环境若改用 Oracle 11g，字段类型需先完成适配验证。
静态参考数据类别与编号来源
类别码与识别标签来自 SIS 接口规范；识别同一条参考记录时用类别码加识别标签值。报文到 basicdata 列的映射见 implementation.md「静态参考数据」。
| 类别码 | 类别 | 消息中的识别标签 | SIS 依据 |
|---|---|---|---|
COUL |
国家代码 | COUC |
「AODB country codes event」 |
ARPT |
机场代码 | ITCD |
「AODB airport codes event」 |
AIRL |
航空公司代码 | ITOP |
「AODB airline codes event」 |
AIRC |
机型代码 | ITAT |
「AODB aircraft codes event」 |
REGN |
注册号 | RNUM |
「AODB registration codes event」 |
ORGN |
机构代码 | OGID |
「AODB organization codes event」 |
FLTL |
航班类型代码 | FTYP |
「AODB flight type codes event」 |
TLST |
航站楼代码 | TCOD |
「AODB terminal codes event」 |
GLST |
登机门代码 | GCOD |
「AODB gate codes event」 |
SLST |
机位代码 | SCOD |
「AODB stand codes event」 |
CLST |
值机柜台代码 | CCOD |
「AODB check in counter codes event」 |
BLST |
行李转盘代码 | BCOD |
「AODB carousel codes event」 |
CHLT |
行李滑槽代码 | CCOD |
「AODB chute codes event」 |
资源状态是第十四类消息，类别码为 RSTA（SIS 接口规范「AODB resource status event」），识别一条资源状态时须同时使用资源类型 RTYP 和资源编号 RSID；CLST 与 CHLT 都使用 CCOD 标签，因此不能脱离类别码识别记录。
Elasticsearch 航班历史写入
| 契约项 | 已确定的边界 | 尚需确定 |
|---|---|---|
| 写入对象 | 满足 US-14 已结束判据的航班从自有 PG 写入 Elasticsearch 历史库，作为历史查询副本。 |
历史索引名称、文档 ID、写入字段及类型、嵌套资源结构、字段缺失与删除状态的表达方式、索引保留期与容量上限（G-FLIGHT-HIST-RETENTION）。 |
| 成功确认 | 只有该航班的历史写入成功，才允许从实时数据物理删除；删除前按 D1 必要时登记待发删除事件。 |
Elasticsearch 写入响应中何种结果算成功、成功是否要求可查询。 |
| 写入粒度 | 单个航班写入失败不影响其他航班。 | 部分成功时的确认与继续处理规则。 |
| 失败与重试 | 写入失败的航班保持在实时数据中，下次运行再试；已写入的航班不重复写入；正在被消息处理的航班跳过，下轮再处理。文档 ID 按旧系统线索为 SODT + FLID 幂等 upsert，写入结果不明时重试同一写入。 |
重试间隔。 |
旧系统线索：逐航班按 SODT + FLID 查询旧索引 flight_hts，存在则更新、不存在则新增；写入内容是 SCHD.FLTR 序列化后的 JSON，单条写入失败跳过该航班（旧项目用户故事「动态航班转历史」）。
待决事项
由本系统与需求方确定的事项见 specification.md「待确认事项台账」。