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 筛选。
• 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 日计划请求。同类型若还有未处理完的请求，新请求先不写信箱，等旧的处理完再写 COUTMSGS（US-09 AC1）。
  • 待确认：请求参数与 HTTP 响应 → Q16。

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

• C-9 航班变更发 Kafka：msg 一条变更一条消息；schd 把两轮采集之间积累的变化合成一条消息，内容是 SCHD.FLTR JSON 数组。空字段不输出，没变化不发；删航班只走 msg；不设 message key；可能重复投递（待确认 Q1）。
• C-10 静态参考数据写本系统库，admin-api 只读；本系统不调用 admin-api。
• C-11 航班快照写 Redis；GET /all/flights 与网页客户端读同一份；JSON 由报文 XML 转换。
  • 待确认：MAFL 是否一并提供（Q6）；状态码与响应包装（Q21）。

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 日计划：覆盖范围内快照里没有的航班打删除标记、记删除事件、从 Redis 删掉；覆盖范围外的航班不受本报文影响；快照没带的字段本地清掉（US-07 AC2/AC3）。
• 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 消息里装多少变更	见 C-9
Q2	待对方	FLOP 里 SRVT/VIPF 等集合段缺席是否等于删除	见 G-SRVT-VIPF
Q3	待对方	SIS 没写明的 FLOP 子类型怎么解析、处理完算啥	按现有逻辑处理（US-05 AC1）；见 G-FLOP-SEMANTICS、CLM-1
Q4	待对方	上游重发时会不会改正文	假定内容不变，只认身份；改正文会被当重复跳过
Q5	待对方	msg 消息体格式、变更与删除怎么区分	沿用旧系统 JSON（接口契约「Kafka」）
Q6	待对方	网页客户端怎么读 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
Q16	本系统	POST /schd/sync 请求与响应	见 C-8
Q17	本系统	人工发 RQRD 的入口	US-09 要求能人工发，HTTP 清单里没有
Q18	本系统	回退时正在处理的消息怎么办	见 OPS-4
Q19	—	（未分配）	—
Q20	—	（未分配）	—
Q21	本系统	GET /all/flights HTTP 约定	见 C-11
Q22	本系统	静态参考数据对应哪些表	见 C-10、接口契约
Q23	本系统	Elasticsearch 历史怎么写、保留多久	见 US-14、G-FLIGHT-HIST-RETENTION
Q24	本系统	REQ_TRACK 已结案记录保留多久	见 G-REQ-TRACK-RETENTION
Q25	本系统	季度计划从哪来、什么格式	SIS 只有日计划；旧系统读 Oracle 季度表

状态说明：待对方 = 需对接方确认；已定 = 结论已写入 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-PROC-CLEANUP	处理记录到期清理未做	US-11
G-REDIS-PROJECTION	Redis 快照写入与删除未做	US-05、US-06、US-07、US-12
G-REF-DATA	静态参考数据处理与 admin-api 直读未做	US-13
G-REQ-OPEN-UNIQUE	同类型未处理完时不允许再发，未做	US-09
G-REQ-TRACK	出站请求跟踪未做	US-09
G-REQ-TRACK-RETENTION	REQ_TRACK 已结案保留期未定（Q24）	US-09
G-RESP-GUARD	SCHD-RESP 过期判断未做	US-07
G-SCHD-SNAPSHOT	日计划快照删除、清空、分批未做	INV-7、INV-9
G-SRVT-VIPF	SRVT、VIPF 明细未入库（Q2）	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-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	分批失败全部重来（G-SCHD-SNAPSHOT 做完前不可验）；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	历史写入成功才删实时数据；删事件先于实时删除登记
G-PROC-CLEANUP（未完成不删）	US-11 AC1/AC2	未处理完的记录不清理
OPS-4（切换与回退）	OPS-4	写回处理时间后再切回；在途消息见 Q18
PRE-1（测试隔离）	OPS-3	测试环境独立 DB、Redis、Kafka，不连生产信箱