msgexchange-v2/docs/contracts.md

对外契约与待确认事项

本文件是本系统与外部对手方之间承诺与要求的唯一出处，也是待确认事项（Q）的唯一台账。条款编号 C-x、问题编号 Q-x 稳定不变；条款被取代时标 [作废 by C-y] 并保留原文，不静默改写。

读者：库方（共享 MySQL 管理方）接口人、上游（CIIMS / AODB / SIS）接口人、本系统开发与运维。

条款状态词只有三种：[待确认 Q-x]（未取得对方书面确认）、[已确认 YYYY-MM-DD]（对方书面确认且已回写）、[我们单方承诺]（不依赖对方，已生效）。

术语

术语	含义
上游	向信箱写入报文的源头系统（CIIMS、AODB 等）。
信箱	共享 MySQL 的入站表 CMINMSGS；出站方向为 COUTMSGS。
库方	共享 MySQL 的管理方；表结构变更与数据清除只能由库方执行或书面授权。
处理标记	信箱行上表示「本系统已处理」的约定字段；逻辑名 DATE_PROCESSED / STATUS，实际列名以库方契约为准。本系统只把空标记写成已处理值，不回撤、不覆盖。
落信	报文进入信箱（CMINMSGS 存在该行），执行方是上游。
入队	本系统在自有 PG 建立 PROC_STATE 记录，开始处理。
已回填	本系统已把处理标记写回该信箱行。
投递确认	投递目标已接受且本地 MSG_EVENT 已置 SENT；不表示业务消费者已消费。
自有 PG	本系统唯一的业务数据库 PostgreSQL；与信箱之间不存在跨库事务。

A. 共享信箱（库方）

A.1 ID 与可见性

• C-1 ID 单调：信箱 ID 按提交顺序分配，已发布水位之下不再出现更小的新 ID。[待确认 Q2]
• C-2 ID 分配 → 事务可见时延上界由库方直接给出。该值决定空洞老化阈值与补偿扫描窗口宽度；不可由 SIS 报文 Expiry 推导（Expiry 是报文保留与传输恢复口径，与「ID 分配后多久对读事务可见」不是同一个量）。[待确认 Q2]
• C-3 ID 空间不复位、不复用、不回退：含表轮换、备份恢复、AUTO_INCREMENT 归零。采用整表轮换方案时，新表种子必须 ≥ max(ID)+1，保证 ID 不断链；本系统的水位 W 是不可逆单游标，ID 回退会导致其后所有行永久不可见。[待确认 Q2]
• C-4 报文行不可变：同一业务身份（SNDR|TYPE|STYP|SEQN）的重发必为同一内容。若上游会以同一身份改发正文，需要另定识别规则（Q15）。[待确认 Q15]

A.2 保留与清除（标记、保留期、清除前提）

• C-5 处理标记值集与写权限：本系统只写入库方认可的 legacy 值集内的「已处理」值（默认 PROCESSED），只写空标记、不回撤、不覆盖；内部原因（死信、重复、放弃）记录在自有 PG，不在信箱新增枚举。[待确认 Q7]
• C-6 清除语义必须是「标记 + 保留期」：打标本身不触发清除，触发条件是「到达保留期 R_keep」且「边界内全部行已打标」。若库方语义是「打标即可清除」，则清除前置条件不成立，且增大 R 无法补救，必须另行约定保留期或引入独立原文保留通道。[待确认 Q7][待确认 Q9]
• C-7 保留期下界（本文件是唯一定义处）： R_keep ≥ max(人工重放期限 + 人工处置期限, 审计期限, 回填重试上限)。 这是「重放窗口内原文仍在」的唯一保证来源。报文在 CIIMS 的 Expiry（480 分钟量级，SIS §3.16）可作为原文保留期的参照，但它是报文有效期，不等于本处所需的保留期。[待确认 Q6][待确认 Q9]
• C-8 清除前置条件（本文件是唯一定义处）：执行清除时，边界内每行必须已有终局——即「已持有处理标记」或「已登记在本系统的回填放弃清单中且经人工对账确认」。放弃行不写标记，未达终态的行顺延至处理完成后清除；本系统不执行 DDL，也不写共享历史表。[待确认 Q7][待确认 Q9]
• C-9 清除执行方与方案：清除由库方执行或书面授权执行。方案 A（按 DATE_RECEIVED 日分区 + TRUNCATE/DROP PARTITION）为首选；方案 B（CREATE TABLE ... LIKE + 保留窗复制 + RENAME TABLE + 对账 + CMINMSGS_HST 归档 + DROP）为备选。现场 MySQL 版本与分区 DDL 能力待确认。[待确认 Q9]
• C-10 时间语义：时间比较与换算统一采用机场时区 Asia/Shanghai 及明确类型转换；DATE_RECEIVED 由上游/库方写入，其时钟基准需可解释（见 PRE-4）。[待确认 Q7]

A.3 原文保留与重放

• C-11 重放窗口内的原文必须可读：legacy 现役按接收超 1 天归档并删除 CMINMSGS；若沿用该窗口，则与 C-7 冲突，须以 C-7 为准。[待确认 Q9]
• C-12 若原文被提前清除（违反保留契约），本系统的死信处置不变，按契约违例走运维追责；该情形不改变 C-8 的清除前提。[我们单方承诺]

A.4 我们向库方的承诺

• C-13 只读约定区间的信箱行（ID > W），单活动实例运行，不引入并行消费者。
• C-14 不建表、不改表结构、不迁移 schema、不写共享历史表；兼容 HTTP 入口按既有契约写入入站信箱。
• C-15 处理标记只写 C-5 认可的值，不回撤、不覆盖已有非空标记。

B. 上游（SIS / AODB）

• C-20 业务身份四元组 SNDR|TYPE|STYP|SEQN 的语义由上游定义；SEQN 的取值范围与回绕见 SIS §2.8.1。重置周期未知，它决定业务身份是否加入日期边界（默认不加）。SNDR 取值域也需对拍（SIS 为 AODB/RMS，legacy 实发 OSH5 等）。[待确认 Q11]
• C-21 FLID 在保留期内不复用。若复用，事件版本（STATE_VERSION）必须按 incarnation 作用域，否则「保留最新版本」的合并规则会把新航班的事件压掉，旧 tombstone 也可能删掉在用航班。[待确认 Q16]
• C-22 报文不可变（同 C-4）。
• C-23 请求/应答回显契约：目标优先按已确认的回显字段精确匹配；回显未确认时的降级匹配（同类开放请求且报文 DTTM ≥ sentAt）存在跨代误配风险，必须明确接受并审计，不得宣称精确关联。比较前统一时区与时间单位。[待确认 Q5]
• C-24 出站信箱 COUTMSGS：消费方与消费顺序、COUTMSGS_ACK_DATE_RECV / COUTMSGS_ACK_RESEND_TIMES / COUTMSGS_DATE_SENT / COUTMSGS_ERROR 各列语义与写入责任、出站行清除责任与保留期、落信成功但本地未置 SENT 时的重复写入风险及下游去重契约，均未确认。本系统对出站的交付承诺只到落信为止。[待确认 Q10]
• C-25 主 / 共享删除顺序与 EROR 回报：SIS 要求删主航班前先删子共享航班，顺序不符时 RMS 应向 AODB 回发 EROR（SIS §1.6.1-1.d，事件定义 SIS §4.8）；现行设计为幂等原子级联、不回发 EROR。二选一。[待确认 Q14]
• C-26 日计划缺失可选字段的语义：SIS 要求最新日计划中未发送的可选字段表示 AODB 已无该数据、子系统应删除本地值（SIS §3.16 注释 4，RESP 同格式见 §3.17），与现行「未携带字段保留」相反。[待确认 Q13]
• C-27 历史积压批次中「不再处理」的确认主体、审批留痕与跳过值集。[待确认 Q12]

B.1 我们向上游的承诺

• C-28 兼容 HTTP 入口的响应只表示接收结果（成功时为 text/plain 的信箱记录 ID），不表示业务处理成功；请求媒体类型、字符集与失败响应仍需与现役逐项对拍。[待确认 Q3]
• C-29 对外投递按至少一次设计，不承诺端到端恰好一次；Kafka 消息的 key 为 FLID，同一 FLID 内保序，跨 FLID 不承诺顺序。[待确认 Q4]

C. 待确认事项台账（Q）

编号	事项	当前假定	阻塞	状态
Q1	权威存储（内部方向）	自有 PG 单库权威 + 无损明细；现场供库目标 Oracle 11g	—	已定案（内部），Oracle 适配与部署验收另计
Q2	信箱 ID 单调、ID 分配→事务可见时延上界、ID 空间不复位；空洞与迟到处置	时延按 5 分钟 max-commit-delay（缺少依据的占位值，不可由 SIS Expiry 推导）	发现完整性声明、空洞老化阈值、补偿扫描窗口、水位不可逆性	未确认
Q3	HTTP 契约：媒体类型、字符集、错误码、查询接口对拍	成功为 text/plain 记录 ID	兼容入口验收	未确认
Q4	Kafka wire：发送粒度、key、去重标识、分区与批次确认	逐 FLID 发送，key=FLID	投递契约	未确认
Q5	请求匹配：回显字段可靠性与降级匹配	RQFD 60 秒 / RQRD 30 秒超时	请求跟踪闭环	未确认
Q6	重放期限与人工处置期限的取值（唯一作用是决定 R_keep 下界）	R = 30 天；重放/处置期限未定	R_keep 取值	未确认
Q7	处理标记值集与写权限、原文保留期、处理时间语义	写入 PROCESSED	回填值集、保留期下界	未确认
Q8	逐类覆盖清单（积压摸底的类型分布依据）	—	积压处置与逐类矩阵	未确认
Q9	清除执行方与 DDL 授权、方案 A/B 选型、分区能力	首选方案 A	R_keep 与清除边界	未确认
Q10	出站消费方、ACK 列语义、出站清理与去重契约	—	出站信箱	未确认
Q11	上游 SEQN 重置周期与业务身份的日期边界	不含日期边界	身份算法	未确认
Q12	积压批次「不再处理」的确认主体、审批留痕与跳过值集	—	积压跳过处置	未确认
Q13	日计划缺失可选字段的删除语义	保留未携带字段	快照合并	未确认
Q14	主/共享删除顺序与 EROR 回报义务	幂等原子级联	出站事件类型	未确认
Q15	上游是否会以同一业务身份改发正文（决定是否需要区分「重复」与「改发」）	假定期望不可变（C-4）	身份去重语义	未确认
Q16	FLID 重用语义（决定版本是否按 incarnation 作用域）	假定不复用（C-21）	事件合并与 tombstone	未确认

Q 的答复只在本表就地更新（补「结论」与日期），并触发 README.md「维护清单」的落地 4 步；不另开文件。