msgexchange-v2/docs/contracts/interface-contract.md

接口契约草案

本文记录 msgexchange-v2 与联调工具、运营航班显示界面、CIIMS adapter、admin-api、Elasticsearch 航班历史存储之间需要共同遵守的接口。范围由 requirements.md 的 US-02、US-08、US-09、US-12、US-13、US-14 和 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 接口规范；每条普通参考记录以对应类别码和识别标签值组成逻辑身份。标签值的格式、唯一范围和 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 历史索引映射、文档样例、逐条或批量写入响应，以及写入结果不明时的对账规则。

只有上述证据核对完成后，待定字段才能转为字段级契约；任何新增字段、默认值或错误码都需写明其来源与对接方。