msgexchange-v2/docs/specification.md

规范：术语、约定、前提、不变量与承诺范围

本文列出 msgexchange-v2 与外部系统的约定（C-x）、运行前提（PRE-x）、必须始终成立的规则（INV-x）、能对外承诺的内容（CLM-x）、待定事项（Qn）和已知缺口（G-NAME）。依据 requirements.md 与 architecture.md；HTTP/Kafka/Redis 字段草案见 contracts/interface-contract.md。

各编号只在本文件定义；编号稳定、不重排，规则见 README.md。

标注 （待确认 Qn） 需对方确认；标注 （本系统承诺） 不依赖对方同意；未标注视为已定。字段未定另起「待确认：」并指向 Qn。

编号一览

族	所在小节	含义
C-1～C-11	约定	对外约定
PRE-x	前提	运行前提
INV-1～INV-11	不变量	必须始终成立的规则
CLM-1～CLM-7	声明边界	能否对外承诺
Q1～Q25	待确认事项台账	待定事项（Q19、Q20 未分配）
G-*	当前已知偏差	已知实现缺口

1. 术语

术语	含义
上游	发报文的 AODB；报文经 CIIMS adapter 进信箱。
信箱	共享 MySQL 的 CMINMSGS（入站）与 COUTMSGS（出站）；归库方管理，边界见 C-2。
库方	管理共享 MySQL 信箱的一方（CIIMS adapter）。
处理标记	列 CMINMSGS_DATE_PROCESSED：空=未处理，有值=已处理时间。
写入信箱	报文存成信箱里的一行。入站由 adapter 或 POST /cminmsgs/send 写入；出站由本系统写 COUTMSGS。写入后未必马上开始处理。
建立处理记录	本系统在自有 PG 记一条待处理记录并排进队列。
处理完成	结果已定（已改库、明确跳过、或无法处理并归档）；之后才写处理标记并发 Kafka。
写回处理时间	处理完成后，把时刻写入 CMINMSGS_DATE_PROCESSED。
发到 Kafka	把待发送的变更事件写入 Kafka。
网页客户端	读 Kafka（msg/schd）或调 GET /all/flights（Redis）的前端。
Redis 航班快照	网页客户端查询用的航班数据，从自有 PG 同步；规则见 INV-11。
自有 PG	本系统主库：航班、处理记录、静态参考数据。
出站请求	本系统经 COUTMSGS 向 AODB 发 RQRD（参考数据）或 RQFD（日计划）。
航班历史	已结束航班写入 Elasticsearch；写入成功后才从实时库删除。
静态参考数据	13 类基础数据与资源状态；存自有 PG，admin-api 只读。

2. 约定

2.1 共享信箱（库方）

• C-1 本系统不删除入站行（CMINMSGS）：处理完成后只写回处理标记，原文保留与清除由库方负责，保留期不早于该行的写回完成时刻。
• C-2 共享 MySQL 不改表结构；本系统只读写 CMINMSGS 与 COUTMSGS。

2.2 上游（AODB / SIS）

• C-3 一条报文的身份 = SNDR + TYPE + STYP + SEQN。SEQN 自增，极少在消息服务器重启时重置；重置后不与历史冲突。
• C-4 出站请求写入 COUTMSGS；本系统只保证写入信箱，不保证 AODB 收到。编码：SNDR=OMMS；SEQN 本系统生成；DTTM 北京时间 YYYYMMDDHHMMSS；RQRD 共 14 种子类型（以 SIS 为准）；RQFD 的 STYP=NONE。日计划请求的时间条件由网页传入，本系统不补、不改。STDB、STDE 按计划到港或计划离港时间筛，ETDB、ETDE 按预计到港或预计离港时间筛；带 B 的是大于等于该时刻，带 E 的是小于等于该时刻；多个条件同时成立。时刻格式为 DDMONYYHHMM（见 SIS「RMS 日航班计划请求事件」）。没传的条件不写入报文。四个都不传时不带筛选，AODB 返回当天全部记录，与它主动下发的日计划同一范围，这份回信是完整名单。带了任一时间条件时，回信只是筛选出来的一部分，不是完整名单。回信里的每一班整份替换本地同一班（C-6、US-07 AC3）。只有完整名单才删除范围内缺席的航班；带了时间条件时不删除回信里没有的航班（US-07 AC2）。季度计划不属本系统出站范围（Q25）。
• C-5 删航班只打删除标记；主航班与共享航班各自独立标记。
• C-6 日计划快照里没带的字段，视为 AODB 已删掉该值，本地也清掉（US-07 AC3）。

2.3 HTTP 入口

• C-7 POST /cminmsgs/send：XML 写进入站信箱，与 adapter 走同一套处理。成功返回消息编号（只表示已写入、尚未处理）；失败不返回编号。接受 text/xml、application/xml、text/plain（UTF-8）；拒收空报文、超长、非法 XML；解析禁止访问外部资源。内网访问由网络层控制；仅供内部联调。
  • 待确认：大小上限、HTTP 状态码与响应体 → Q15。
• C-8 POST /schd/sync：登记一次 RQFD 日计划请求。请求体是网页选定的时间条件，写入规则见 C-4；成功返回请求编号，已有未结案请求时返回 409（Q16）。同类型若还有未处理完的请求，新请求先不写信箱，等旧的处理完再写 COUTMSGS（US-09 AC1）。
• C-12 POST /refdata/sync：登记一次 RQRD 参考数据请求。请求体携带网页选定的类别码 STYP（取值见 C-4，以 SIS 为准）；STYP=RSTA 时须带资源类型 RTYP，其余类别不得带；成功返回请求编号，已有未结案请求时返回 409（Q17）。登记后等在途请求结案再写 COUTMSGS（US-09 AC1）。

2.4 下游（admin-api、网页客户端）

• C-9 航班变更发 Kafka：msg 一条变更一条消息，消息体是整条 MSG 的 JSON（META 加对应业务体），变更与删除由 META 的类型与子类型区分（Q5）；schd 把积累的变化按批发出，每批一条消息、内容是 SCHD.FLTR JSON 数组，单批条数上限见 PARAM:msgx.schd.flush-limit，超限部分留待后续轮次发出。空字段不输出，没变化不发；删航班只走 msg；不设 message key；可能重复投递。
• C-10 静态参考数据写本系统库，admin-api 只读；本系统不调用 admin-api。
• C-11 航班快照写 Redis；网页客户端经 GET /all/flights 读这一份，不直连 Redis；共享航班（MAID 非空）不单列返回（是否以主航班 MAFL 提供见 Q6）。成功 HTTP 200 返回裸 JSON 数组（不套旧 ResponseDto），不分页；失败 HTTP 503，JSON 对象 {"error":"FLIGHT_PROJECTION_UNAVAILABLE","reason":"<细节>"}；投影读失败不得返回 200 空数组（INV-11）。投影 value、KAFKA:schd 数组元素与查询成功体元素同形：都是日计划一条 FLTR 转成的 JSON（字段名与 XSD FLTR 一致，空字段不输出，与 C-9 相同）；由自有 PG 当前态重建，不是另起包装。

3. 前提

前提不成立时，下文规则需整体重评。

编号	前提	若不成立
PRE-1	测试与生产隔离：各自独立的 DB、Redis、Kafka 主题，测试不连生产信箱	OPS-3 验收无效

4. 不变量

4.1 消息处理

• INV-1 处理标记为空的信箱行会被建立处理记录；同一编号只建一次。重扫或重启不重复、不遗漏。
• INV-2 只有本地处理结束后才写回处理时间；标记「处理结束」时必须同一次记下「还要写回信箱」。只填空的处理标记，不覆盖已有值（本系统承诺）。
• INV-3 航班增量与删除：改库与记「待发 Kafka」同一次提交；「处理结束」与「还要写回信箱」在 Redis 写成功后再记一次。处理完成前不发 Kafka（US-03 AC4）。日计划与静态参考数据见架构「主流程」。
• INV-4 日计划整报校验失败时，本地航班数据不改（US-07 AC1）。

4.2 航班

• INV-5 航班当前数据以自有 PG 为准。
• INV-6 FLID 全局唯一。
• INV-7 日计划报文里的航班整份替换，没带的字段清掉（US-07 AC3、C-6）。完整名单（DNLD，以及没带时间条件的 RESP）在覆盖范围内把快照里没有的航班打删除标记、记删除事件、从 Redis 删掉；范围外的航班不受本报文影响。带了时间条件的 RESP 不因缺席删除（US-07 AC2）。
• INV-8 已打删除标记的航班必须从 Redis 删掉；删掉才算这条消息处理完成（US-06 AC1）。
• INV-9 日计划可以分批写 PG，但整份 PG 写完且 Redis 按快照刷完才算完成；失败则全部重来（US-07 AC4/AC5）。

4.3 Redis 航班快照

• INV-10 Redis 写成功才算处理完成；失败则不写回处理时间、不发 Kafka、下轮重试（US-05 AC4）。已写入 PG 的不因 Redis 失败而撤销（US-03 AC3）。
• INV-11 Redis 航班快照只由本系统维护；查询与网页客户端同源；Redis 出错时返回错误，不能用空列表假装成功（US-12）。

5. 声明边界

编号	承诺	依赖	现在能否作出	限制或原因
CLM-1	同一条消息重复处理不会重复生效	US-03	不能	各类报文细则未写完（G-FLOP-IDEMPOTENT）
CLM-2	按信箱编号从小到大处理	US-03 AC1	能	只对已发现的待处理消息成立：较小编号晚提交时，它排在已经处理完的较大编号之后（implementation.md「收报」）
CLM-3	主题 msg 上，同一 FLID 内按发送顺序排列	US-08 AC2、C-9	能	msg 单分区；至少一次投递时可能重复（D2）
CLM-4	出站请求写入 COUTMSGS	C-4	能	只保证写入信箱，不保证 AODB 收到
CLM-5	消息在固定时间内处理完	—	不能	需求未定时限
CLM-6	容量与吞吐量级	—	不能	需求未给日量与峰值
CLM-7	配置不完整时拒绝启动	OPS-1	能	—

6. 待确认事项台账

Q1～Q25 按编号排列。答复后更新对应 C-x 或条款，步骤见 README.md「维护清单」。

编号	状态	事项	说明
Q1	已定	schd 一条 Kafka 消息里装多少变更	单批上限内的待发航班聚成一条 SCHD.FLTR JSON 数组，超限部分后续轮次发出（C-9）
Q2	待对方	FLOP 里 SRVT/VIPF 等集合段缺席是否等于删除	见 G-SRVT-VIPF；旧系统不解析这两段，无法对拍
Q3	待对方	SIS 没写明的 FLOP 子类型怎么解析、处理完算啥	按现有逻辑处理（US-05 AC1）；见 G-FLOP-SEMANTICS、CLM-1。旧系统找不到对应处理器时按失败兜底，仍写回处理时间且无业务改动
Q4	待对方	上游重发时会不会改正文	假定内容不变，只认身份；改正文会被当重复跳过。旧系统不比较正文
Q5	已定	msg 消息体格式、变更与删除怎么区分	整条 MSG 的 JSON，空字段不输出；删除由 META 的类型与子类型标识（C-9）
Q6	本系统	网页客户端怎么读 Redis 快照	经 GET /all/flights 读、不直连 Redis（C-11）；MAFL 是否随主航班返回仍待定，旧系统提供
Q7	已定	信箱编号只增不减、不重用	INV-1、CLM-2、US-01 AC3
Q8	已定	入站处理时间列名 CMINMSGS_DATE_PROCESSED	术语「处理标记」、US-10
Q9	已定	入站行删除条件与保留期	本系统只写回处理标记、不删除；清除与保留期由库方负责（C-1）
Q10	已定	SEQN 重置与身份规则	C-3
Q11	已定	日计划没带字段是否删除	C-6
Q12	已定	主航班与共享航班删除联动	US-06 AC2
Q13	已定	RQRD / RQFD 编码字段	C-4
Q14	本系统	生产用 PostgreSQL 还是 Oracle 11g	Oracle 未验证前不作支持承诺
Q15	本系统	POST /cminmsgs/send HTTP 约定	大小上限、状态码、最终响应体；见 C-7。旧系统成功响应是 ResponseDto（err_code=1，body 为信箱编号），且未配置大小上限
Q16	已定	POST /schd/sync 请求与响应	请求体携带网页选定的时间条件（C-4）；成功返回请求编号，开放请求未结案返回 409（C-8）
Q17	已定	人工发 RQRD 的入口	POST /refdata/sync 登记一次请求；请求体携带类别码 STYP（RSTA 时加带 RTYP）；成功返回请求编号，开放请求未结案返回 409（C-12）
Q18	已定	回退时正在处理的消息怎么办	未写回处理标记的消息仍算未处理，由旧系统继续；旧系统停机只等在途任务跑完（OPS-4）
Q19	—	（未分配）	—
Q20	—	（未分配）	—
Q21	已定	GET /all/flights HTTP 约定	成功裸数组、失败 503 与错误对象；见 C-11
Q22	已定	静态参考数据对应哪些表	C-10；物理为 schema basicdata 多表（非 REF_MASTER 单表），映射见 implementation.md「静态参考数据」
Q23	本系统	Elasticsearch 历史怎么写、保留多久	见 US-14、G-FLIGHT-HIST-RETENTION。旧系统按 SODT+FLID 写入 flight_hts，保留期未实现
Q24	本系统	REQ_TRACK 已结案记录保留多久	见 G-REQ-TRACK-RETENTION；旧系统没有对等记录，只有 COUTMSGS 的 ACK 列
Q25	已定	季度计划从哪来、什么格式	不属本系统范围：admin-api 从 Oracle FIMS_FLIGHTSCHD_SEASON 读（C-4）

状态说明：待对方 = 需对接方确认；已定 = 结论已写入 C-x/INV-x；本系统 = 由本系统与需求方决定；— = 编号保留未用。

7. 当前已知偏差

偏差标记只在本表定义；其他文档只写 G-NAME。解决后删本行及全仓引用。

偏差	缺什么（交付进度见 Plane）	影响
G-FLIGHT-HIST-RETENTION	历史保留期与容量上限未定（Q23）	US-14
G-FLOP-IDEMPOTENT	各类 FLOP 重复处理规则未写完	US-03；CLM-1
G-FLOP-SEMANTICS	动态报文处理与 US-05 要求不一致	US-05
G-FLOP-UNMAPPED	XSD FLOP 字段映射不全	US-05
G-MAFL	主航班共享列表未做	US-06 AC2
G-REF-DATA	admin-api 生产侧只读接入与联调验收未闭合	US-13；本网关落库与 ReferenceDataProcessor 已做（ACM2-93）
G-REQ-TRACK	RQRD 人工登记已落地（C-12）；子类型作废与等待投递未做	US-09
G-REQ-TRACK-RETENTION	REQ_TRACK 已结案保留期未定（Q24）	US-09
G-SRVT-VIPF	SRVT、VIPF 缺席是否清除待 Q2；段出现时已落 FLIGHT_SRVT/FLIGHT_VIPF	US-05

8. 验证映射

按条款编号排列。

条款	需求验收	要观察的结果
C-5、US-06 AC2	US-06 AC2	删共享联动主航班；删主级联删共享
C-7	US-02 AC1～AC5	三种 Content-Type、UTF-8；空/超长/非法 XML 不写入；禁外部资源；成功编号只表示已写入；与 adapter 同路径建记录
C-8、CLM-4	US-09 AC1～AC3	出站写入 COUTMSGS；HTTP 触发先登记，旧的处理完才写入信箱
C-12、CLM-4	US-09 AC1～AC3	RQRD 按类别登记并写入 COUTMSGS；非法类别或开放槽占用时拒绝
C-9、CLM-3	US-08 AC1～AC3	msg 单条、schd 批量；失败可重试；msg 同 FLID 保序；同条可能发多次
C-10	US-13 AC1～AC4	全量替换、增删改逐条；空值表示无值不是删除；单类校验失败只停该类
INV-1（建立处理记录）	US-01 AC1/AC2/AC4	重扫与重启后记录数不变、行不丢；同一编号重复出现时不新增记录
INV-2	US-10 AC1/AC2	处理结束后才写回；重启后继续；一直失败有记录可查
INV-3、INV-10	US-03 AC4、US-05 AC4、US-06 AC1	Redis 失败时不记「处理结束」与「还要写回」；完成前不发 Kafka
INV-4	US-07 AC1	校验失败后 PG 航班数据不变
INV-5	架构「数据归属与一致性」	航班数据只写入自有 PG
INV-6	implementation.md「数据模型」	FLID 唯一
INV-7	US-07 AC2/AC3	报文里的航班整份替换、未带字段清空；只有完整名单才在覆盖范围内把缺席航班标删并从 Redis 删
INV-8	US-06 AC1	标删后从 Redis 删；失败下轮重做
INV-9	US-07 AC4/AC5	分批失败全部重来；PG 整份写完后再刷 Redis
INV-11	US-12 AC1/AC2	返回全部非共享航班且与 Redis 一致；Redis 故障返回错误
CLM-1（重复不重复生效）	US-03 AC2/AC3/AC5	跳过/无法处理留档且无业务改动；失败可查；PG 已提交不因写回或 Kafka 失败撤销；待 Q3、G-FLOP-IDEMPOTENT、G-FLOP-SEMANTICS
CLM-2（升序）	US-01 AC3、US-03 AC1	按编号从小到大；最前面未完成时后面的不处理
CLM-7（启动拒绝）	OPS-1	配置错误时启动失败
US-04（ADFT 更新）	US-04 AC2	ADFT 未带字段保持原值
US-14、D1	US-14 AC3/AC4	历史写入成功才删实时数据；删事件先于实时删除登记
US-11（未完成不删）	US-11 AC1/AC2	未处理完的记录不清理
OPS-4（切换与回退）	OPS-4	写回处理时间后再切回；在途消息见 Q18
PRE-1（测试隔离）	OPS-3	测试环境独立 DB、Redis、Kafka，不连生产信箱