msgexchange-v2/docs/requirements.md

需求与验收目标

本文件定义阶段 A 的范围、非目标与验收口径：需求定义要交付什么，验收标准定义怎样证明完成。以下事实以本文件为唯一出处：

• US-01～US-15（三级标题定义）、OPS-1～OPS-4（注册表定义）；
• 需求覆盖与依赖关系。

代码入口与参数取值不在本文件：前者见 reference.md「模块与代码入口」，后者见其参数表。前提、不变量、契约与偏差见 specification.md；机制与航班域见 implementation.md。工程纪律（工具链、测试设施、提交规范）以根 AGENTS.md 为唯一出处。

1. 范围与非目标

阶段 A 闭合：US-01～US-14、OPS-1～OPS-4。

非目标：

• 航班当前态只存自有 PG；不引入 Redis、阶段 A 的 ES 投影、新业务库、并行主泵或分布式锁。
• 共享 MySQL 只做契约内读写与回填；不建表、不增列、不迁移、不写共享历史表（C-14）。
• 生产保持单活动实例；不承诺端到端恰好一次、跨 FLID 顺序或未经验证的 Oracle 11g 支持。
• US-15 未启用前遵守 D1：历史写入未确认成功时航班清场删除 0 条。
• 不生成上游业务报文，不替代 CIIMS/AODB，不提供 AODB 主数据编辑能力。

2. 阶段 A 用户故事

US-01 可靠采集共享信箱

目标：上游继续向 CMINMSGS 落信，本系统持续、可恢复地采集，不要求上游改投递方式。

验收标准

1. 按配置周期、ID 升序、有限批次采集信箱行；扫描谓词以 implementation.md「收报与水位」为准（按 ID 区间，不以处理标记为谓词）。接收层只入队，不解析业务、不回填已处理标记。
2. 按信箱 ID 幂等建立 PG PENDING；重复扫描、并发兼容入队和进程重启都不能重置已有终态。
3. 快路径用持久水位，本批 PG 入队全部确认后才推进水位。
4. PG 不可用或批次中途失败时不改信箱标记；恢复后补建遗漏，记录失败次数与扫描进度。
5. 较小 ID 迟提交、ID 有空洞、兼容入口先入队较大 ID 时，必须遵守经 Q2 确认的发现与顺序协议；不能用「最终会重扫」冒充严格 FIFO。

前置：共享库读契约；Q2 决定严格顺序的端到端验收；水位与扫描谓词口径以 implementation.md「收报与水位」为准。

US-02 兼容 HTTP 注入报文（KEEP）

目标：联调工具通过 POST /cminmsgs/send 提交 XML，得到真实的信箱接收结果。

验收标准

1. 支持 text/xml、application/xml、text/plain，默认 UTF-8；空报文、超过请求体上限（见 C-28）的请求和畸形 XML 返回规范错误，不落信。XML 校验禁用 DTD、外部实体与外部资源访问。
2. 信箱确认落信后返回 ID；PG 入队失败不把已落信伪装成未接收，由 US-01 补建。信箱写入未确认时不返回成功。
3. 目标为兼容 ResponseDto；固定成功/失败样例、HTTP 状态码、响应媒体类型和错误码表后加入契约测试，见 Q3。成功只承诺信箱落信，不承诺业务处理或下游完成。
4. 生产保持内网信任边界，由网关限制来源并审计；外露或跨网络必须先落实认证，不能把免密入口直接暴露。

目标响应体示例（数字和错误码仅作示例，错误码表见 Q3）：

{"is_success": true, "body": 12345}
{"is_success": false, "err_code": "<code>", "err_msg": "<detail>"}

前置：US-01 补建能力；Q3。HTTP 基础格式校验不替代 US-03 的业务解码。

US-03 严格按序、幂等地执行管道

目标：报文失败和重试不造成航班状态倒序，也不重复产生副作用。

实施拆分：调度与时钟 → 安全解码及路由 → 身份绑定 → 状态应用与 PG 提交。先用假处理器验证管道，不等 US-05 全部实现。

验收标准

1. 只取最小未完成 ID，PENDING / FAILED 均占队头；退避未到期不得越过。维护作业由独立线程执行，不参与消息 FIFO；作业必须有界，且不得因争用资源使已到期消息无限饥饿。
2. 安全解码 XML，至少覆盖 META、SCHD、FLOP、参考应答与忽略类路由；合法但能力未支持是 UNSUPPORTED，不能一律归为非法报文。保留原文以支持诊断和回放。
3. 解码后首次绑定 SNDR|TYPE|STYP|SEQN；冲突转 SKIPPED 并记录原 ID；自身重试保留绑定。生产按 PARAM:msgx.identity.include-day-boundary 配置（当前口径不含日期边界）；更改算法须先确认 Q11。
4. MALFORMED 直接 DEAD；CODEC_ERROR / UNSUPPORTED / INFRA 按次数和退避处理，耗尽转 DEAD(EXHAUSTED)。不能无限重试未实现类型，也不能立即当非法报文丢弃。
5. 终态判据只有尝试上限（PARAM:msgx.pipeline.max-attempts），没有按时间的毒丸；调度判断注入 Clock。人工重放的可重放范围以 Q6 决定的 R_keep 下界为准。
6. 主泵在同一 PG 事务提交航班主表/明细、事件与处理结果；终态回填意图通过 US-09 同事务保存。任一步失败整体回滚；提交后只重试外部回填，不重复生成业务事件。
7. 领域决策逻辑只读取当前完整态与已解码报文，返回下一完整态和待发事件，不执行 I/O；Processor 作为事务协调器，将状态写入、事件、处理终态与回填意图收敛在同一事务边界内，不直接触碰 Kafka。失败只在持有消息上下文的边界落账，中断向上传递，不作为普通失败吞掉。
8. 权威存储不可用或未完成恢复时停止业务处理；不能把「整个状态丢失」误判为「单航班不存在」而批量成功结束增量报文。

前置：US-01；Q1 已定单库方向，Q6 决定 R_keep 下界（重放窗口）。数据库迁移只落自有库。

US-04 明确忽略非业务报文（KEEP）

目标：无需处理的报文有可追踪的终结结果，不制造无效重试与死信。

验收标准

1. 解码 META 后、处理器分派前，大小写不敏感匹配 TYPE-STYP 或 TYPE-*；基线为 LDM-* / REGN-* / RSTA-* / EROR-*，不混用 ERROR。转 SKIPPED 前必须已完成身份绑定（US-03、INV-9），忽略报文照常绑定身份。
2. 命中后转 SKIPPED，记录 ignored:<rule> 和计数；不更新航班、不创建业务通知。
3. 通过 US-09 保存回填意图；命中、未命中、大小写和重扫均有测试。合法忽略报文不应因 MsgKind 尚不能表达它而先解码失败。

前置：US-03 解码/终态接口、US-09。

US-05 应用 ADFT 与 29 类 FLOP（KEEP + FIX）

目标：增量报文正确更新航班及主/共享关系，并生成符合现役语义的通知。

验收标准

1. SCHD-ADFT 与 29 个 FLOP 子类型逐项列入覆盖矩阵，每项有对应的处理器规则与回归测试；未知类型可恢复失败。RESP/DNLD 不计入这批处理器，走 US-06。
2. 每类固定「输入与前态 → 后态 → msg → schd → 终态」五面样例；区分字段缺失、显式清空、重复报文和主/共享航班。清单和 golden 样例按 Q8 补齐，不以「已写 29 个类」替代验收。
3. 对按 KEEP 规则需忽略的不存在航班，以 SUCCEEDED 无副作用结束，并由 US-09 回填；ADFT 建航班等行为按各类型矩阵执行。航班当前态以自有 PG 为唯一权威，重启即恢复，不存在 Redis 全损后白名单无法找回的损坏路径。
4. 共享航班更新与删除级联语义以 implementation.md「删除与重建」为规范（共享航班通知、主航班 MAFL 更新、级联删除、原子变更；不出现主已删、子残留）；本条目验收实现不偏离该规范，目标不存在时幂等成功。
5. ADFT/FDEL 的值相等比较与半状态禁止规则见 implementation.md「删除与重建」。
6. PSDT 通过 US-14 的只读映射计算 abdg，处理器不直接调用 admin-api。

前置：US-03；PSDT 另依赖 US-14；Q1、Q8、Q14。

US-06 导入 RESP/DNLD 日计划快照

目标：主动下发和请求应答使用同一套全量计划处理，迟到应答不覆盖新状态。

报文	路由	请求状态	无匹配时
SCHD-DNLD	ScheduleProcessor	不更新请求	不要求开放请求
SCHD-RESP	匹配守卫后进入 ScheduleProcessor	成功提交时匹配 RQFD → DONE	SKIPPED、审计，禁止更新快照
SCHD-ADFT	US-05 增量处理器	不更新请求	不适用

验收标准

1. RESP/DNLD 共用流式解析、整包校验和规范化；校验失败不发布半包，旧快照保持可用。
2. RESP 仅匹配未过期、已发送的开放 RQFD；DTTM < SENT_AT、已过期、已被替代或无匹配时，不写业务状态，记录跳过原因。
3. 在自有 PG 单事务内，批处理写入已校验的 FLIGHT_SCHD 航班状态与资源明细；本次日计划中未出现的航班不因此被删除。
4. 在同一 PG 事务中提交 FLIGHT_SCHD 变更、MSG_EVENT 待发通知与 PROC_STATE(SUCCEEDED)；匹配 RESP 同事务完成请求并置 DONE；提交后信箱回填由扫描承接。
5. 相同报文重放不二次写入或重复发事件；单事务崩溃整体回滚，重放幂等。

前置：US-03、US-08 请求登记/匹配基础；Q1、Q5、Q13。

US-07 可靠、有序地投递 Kafka

目标：状态应用完成后投递通知；重试可识别、不乱序、不静默丢失。

验收标准

1. KAFKA:msg 按目标内 EVENT_ID 顺序发送，确认后才标 SENT；队头退避时不跳过，发送有超时上限。
2. KAFKA:schd 只通过 flushSchd 聚合，聚合周期与批上限见 reference；同一 FLID 取批内最新状态，成功确认覆盖对应原事件，失败保持批次可恢复并退避，耗尽可见为 DEAD。
3. 外部接收成功、本地确认失败或进程重启后允许重发；事件标识跨重发稳定，消费者有去重约定，不宣称端到端恰好一次。
4. 当前 KAFKA:msg 与 KAFKA:schd 的分区键均为 FLID，schd 逐 FLID 发送最新状态，不再是 legacy 的多航班数组。msg 是否需按 SNDR 分区、发送粒度与去重标识的放置以 Q4 定案为准；定案前不宣称单分区之外的顺序保证。
5. 生产强制 acks=all、enable.idempotence=true、max.in.flight.requests.per.connection=1；Broker 支持幂等生产协议并完成实际验证，不允许非幂等降级通过验收。
6. 普通/聚合发送失败、确认丢失、批次标记中断和目标阻塞均有测试；DEAD 保留记录并告警。

前置：US-03 事件提交；Q4、现网 Broker 验证。wire 不兼容的标识字段不能直接加到现役载荷。

US-08 发起并跟踪 15 类 AODB 请求

目标：区分请求登记、出站落信、等待、完成与超时，不把过期应答应用到新请求。

实施拆分：请求登记/出站补偿 → 匹配/超时 → 14 类参考应答；RQFD 快照效果由 US-06 集成验收。

验收标准

1. 覆盖 14 类 RQRD 参考请求和 1 类 RQFD-NONE；逐类名称、编码和映射见 Q8，不与 admin-api 的 21 类混算。
2. 先持久化 PENDING 与出站意图；COUTMSGS 确认落信后关联其 ID 并标 SENT，不宣称对方已发送。落信成功而 PG 未确认时可恢复，不能盲目重发。
3. 同类开放请求最多一个，新请求使旧请求 EXPIRED，并发登记不产生两个开放请求。从确认落信的发送时间起算，超时值按 Q5；PENDING/SENT 均不得成为永不超时的死分支。
4. 优先按已确认的 SEQN 回显匹配；无回显的降级匹配按 Q5 明确风险，只接受已发送开放请求且 DTTM ≥ SENT_AT。统一转换为可比较的时间，不能把报文日期数字直接与 epoch 毫秒比较。
5. 迟到、无匹配或已关闭请求的应答不得更新数据，转 SKIPPED 并审计。参考应答成功写入 REF_MASTER 后，与请求完成、处理终态和事件在 PG 边界内保持所需原子性。
6. POST /schd/sync 复用请求入口，采用 24 小时制和非空/区间校验；响应明确已登记还是已落信，不承诺计划已更新。

前置：US-01、US-03；Q5、Q8、Q14、出站信箱去重契约。请求基础不依赖 US-06。

US-09 持久化补偿回填信箱

目标：本地处理终态最终反映到共享信箱，不因共享库故障回滚已完成业务。

验收标准

1. PG 终态与回填意图同事务保存；所有终态路径都经过统一提交边界，不只覆盖成功路径。事务回滚时不得留下可执行回填意图。
2. 提交后由后台执行回填，主泵不等待共享库；失败按持久记录退避，重启继续执行，不重新执行已完成业务。
3. SUCCEEDED、规则忽略、身份重复、DEAD 均需回填处理时间；PENDING/FAILED 禁止回填。具体 STATUS 编码按 Q7 确认，内部终态不能直接当作外部字段值。
4. 重复补偿效果幂等，保留稳定的完成时间与审计；重放后的新处理结果不能被旧回填任务覆盖。非法报文缺 META 时也有明确回填方式。
5. 影子模式禁写，双跑仅一个系统持有标记写权；暴露 PG 终态、回填状态、积压、最老年龄与持续失败告警。

前置：US-03 终态接口；Q7、共享库更新权限。覆盖四类终态、事务回滚、重复补偿和重放竞争；生命周期与超期补写以 implementation.md「中断恢复」「回填」为准，清除口径以 specification.md「契约」为准。

US-10 安全重放与故障处置

目标：运维能定位失败、限定恢复范围，并了解重放对当前航班状态的影响。

验收标准

1. 按 ID、错误类、时间查询次数、错误、关联事件与回填状态；重放前预览范围，记录操作者、原因和逐项结果。
2. 仅 CODEC_ERROR / UNSUPPORTED / INFRA / EXHAUSTED 的 FAILED/DEAD 允许申请重放；MALFORMED 与其他不允许项不改状态，返回跳过原因。
3. 重置 attempts/nextAttemptAt，保留身份、原始入队时间和错误审计；可重放范围受 Q6 决定的 R_keep 下界（原文保留窗口）约束。重新入队仍按 ID 处理，但不承诺已执行过的后续消息自动撤销。
4. DEAD 之后可能已有新状态，必须预检版本与覆盖风险；不安全时拒绝直接重放，改用经批准的隔离重建或恢复流程，禁止无保护的全量 replayAll 生产入口。
5. 操作有认证、授权、范围限制与审计；死信、持续补偿失败、队列年龄越界有告警和处理 Runbook。

前置：US-03、US-09 的恢复状态；Q6、OPS-1/OPS-2 的安全与可观测基础。

US-11 归档自有库终态记录

目标：控制自有 PG 在线表规模，不丢未完成工作、不破坏去重与恢复；不是清理共享信箱。

验收标准

1. 终态记录在了结后经过的时间（UPDATED_AT）达到 PARAM:msgx.proc-state.archive-after 时列为归档候选；PENDING/FAILED 禁止归档，回填未了结的终态行不进入候选。
2. 归档到自有 PG PROC_STATE_HST，主表保留 STATE='ARCHIVED' 的去重影子行（仅 IDENTITY_KEY 与 MSG_ID），使归档后同业务身份再次到达仍可去重；MSG_EVENT 的历史目标与保留规则由投递清理独立处理，不构成归档判据。
3. 归档写入与主行置 ARCHIVED 在同一自有库事务内完成，按候选时的状态条件复查，影响 0 行即整体回滚；重复执行幂等，失败保留源记录并报告计数。
4. 本系统不写共享 MySQL CMINMSGS_HST、不清理外部信箱；由库方按 Q9 执行的清除与历史归档见 specification.md「契约」。原文可用性与重放保留期由 Q6/Q7 关联确认。

前置：US-03、US-09；US-07 提供事件终态规则，US-10 提供恢复保留要求。不依赖 US-15。自有记录归档见 implementation.md「生命周期与清除」。

US-12 查询实时航班（KEEP）

目标：调用方读取与当前权威状态一致的实时航班视图。

验收标准

1. 保留 GET /all/flights，直接从自有 PostgreSQL FLIGHT_SCHD 查询，排除共享航班（MAID != NULL，定义见 implementation.md「字段与集合」）；不改写业务状态。
2. 固定响应样例、空结果、排序、大小限制及一致性时点。现役未分页时不能无声改为只返回第一页；分页或响应结构变更按 Q3 决定。
3. 依赖异常不能伪装为空数组成功；影子只读影子状态，入口有约定的访问控制、限流与审计。

前置：Q1、Q3；所查询的 US-05/US-06 状态发布能力。

US-13 刷新 21 类参考主数据

目标：业务使用来自 admin-api 的本地参考数据，刷新失败仍有上次可用版本。

验收标准

1. 按 Q8 的 21 类清单配置端点、RTYPE/RKEY、字段映射；这是独立于 US-08 的数据入口，不另建「参考专用第二 PG」。
2. 按 (RTYPE,RKEY) 幂等写 REF_MASTER，记录 SOURCE、刷新时间和批次；单类完整校验后发布，失败不暴露半批。
3. 一类失败不破坏其他类或该类旧版本；同类由 AODB/admin-api 都提供时明确覆盖优先级，全量刷新时明确已删除项的处理，不能仅靠 SOURCE 日志解决冲突。
4. 影子默认不主动刷新生产数据；需要参考样本时显式导入隔离副本。

前置：admin-api 访问契约、Q8。可独立于消息处理器开发。

US-14 提供机位与登机桥映射

目标：PSDT 在不调用外部 HTTP 的情况下得到完整映射，正确计算 abdg。

验收标准

1. 保留 ORMS_STAND / ORMS_STAND_AIRBRIDGE 两类，与 US-13 的 21 类分开统计；适配器拉取、完整校验后原子发布只读缓存。
2. 近机位产生登机桥值，远机位或清空机位时 abdg 为空；一机位多桥、缺失映射与共享航班规则用 golden 固定。
3. admin-api 不可用时使用最后可用版本；无可用版本或映射不完整时明确失败，不用空映射冒充正常清空，也不发布半批。
4. 处理器输入包含所需只读参考视图，不允许其直接 HTTP 或写缓存。

前置：机位/桥数据契约及 Q8；不要求 US-13 全部完成。

US-15 历史航班清场（DEFERRED，阶段 B）

历史存储确认成功后，才允许删除对应实时航班；逐条隔离坏数据，不能删除写历史失败的集合。判史规则与保留期、业务时区、历史写入与删除事件之间的恢复协议需在启用前完成 golden 对拍。

阶段 A 不依赖 ES，不启用 PROJECTION_REBUILD。历史清理作业在历史存储未接通（或 PARAM:msgx.history.history-store-enabled=false）时删除 0 条；红线见 implementation.md「生命周期」。

3. 运行与切流验收

编号	必须交付的能力	验证证据
OPS-1 单写者与启动安全	生产缺真实适配器、误用 stub、未启用必需管道时拒启；第二活动写者不能启动，失去写权后不得继续写；中断与停机能正确退出。	配置拒启、双实例/失去写权及停机测试。单靠副本数配置不算运行期保护。
OPS-2 可观测与安全	真实依赖健康、队列/队头年龄、投递/回填滞后、积压与最老未处理信龄、DEAD 和一致性异常有指标、告警与处理入口；敏感管理操作有访问控制，日志不泄漏口令或完整敏感报文。	故障注入触发真实告警，消息到事件可关联；日志出口断开不阻塞业务。
OPS-3 影子隔离	自有数据库/schema、topic、服务注册身份隔离；输入只读水位或回放，禁生产回填、真实出站和误注册。	配置与集成测试证明生产信箱、状态、topic 未被影子修改。
OPS-4 切流与恢复	对拍不少于 7 天，未解释业务字段差异为 0，DLQ 积压为 0，MSG_EVENT 最老滞留 < 5 秒；切流后 48 小时观察，24 小时内具备经演练的回滚能力。	明确负载与统计口径的对拍报告；Runbook 含停写、排空/水位、状态恢复、写权交接和失败回退，不能只回滚程序版本。

上述阈值沿用既有需求基线，需在真实环境提供证据。自有库备份、报文保留和完整状态重建需要恢复演练；本地事务不能承诺任意数据库灾难下 RPO=0，也不承诺未经演练的「一键无损回滚」。

4. 需求覆盖与依赖

4.1 覆盖矩阵

需求	必须闭合的能力	约束 / 偏差锚点
US-01	按 ID 有限采集、持久水位、幂等入队、空洞与中断恢复	INV-2～INV-5、Q2
US-02	安全兼容注入，落信确认与业务完成分离	C-28、Q3、G-COMPAT-HTTP
US-03	严格 FIFO、安全解码、身份去重、事务提交与持久重试	INV-3、INV-6～INV-10、INV-17、Q6、Q11、Q15
US-04	忽略报文在身份绑定后无业务副作用终结并回填	INV-8、INV-9
US-05	ADFT、FDEL、29 类 FLOP、完整航班态及主/共享关系	INV-11～INV-22、Q8、Q13、Q14、Q16、G-FLOP-IDEMPOTENT、G-MAFL、G-SRVT-VIPF
US-06	DNLD/RESP 整包快照、请求守卫、迟到应答隔离	INV-12、INV-15、INV-19、Q5、Q13、G-RESP-GUARD
US-07	Kafka 至少一次投递、同 FLID 保序、schd 聚合、失败与清理	D3、INV-10、C-29、Q4
US-08	14 类 RQRD、1 类 RQFD、出站落信、开放请求唯一、匹配与超时	C-23、C-24、Q3～Q5、Q8、Q10、Q14、G-REQ-TRACK、G-REQ-OPEN-UNIQUE、G-REQ-TRACK-RETENTION
US-09	终态回填意图、后台补偿、四结果、放弃与人工恢复	INV-7、INV-8、C-5～C-8、Q7、Q9；C-6 不成立时闭合 G-REPLAY-CHANNEL
US-10	可查询、可预览、白名单重放、风险预检、授权与审计	CLM-3、Q6
US-11	已了结终态归档、去重影子、竞态复查及独立保留期	D4、C-14、C-16、G-PROC-HST、G-HST-RETENTION
US-12	从 PG 权威态查询实时主航班，固定契约且依赖失败不伪装为空	INV-11、Q3
US-13	21 类参考主数据完整校验、原子发布、失败保旧	Q8
US-14	机位/登机桥映射原子发布，PSDT 只读计算	Q8
US-15	阶段 B 历史归档成功后清场及删除事件恢复	D1、INV-18、Q9、G-FLIGHT-HIST-RETENTION
OPS-1	真实适配器、配置与单写者拒启，失权停写，安全停机	D2、PRE-5
OPS-2	真实健康、积压/失败指标、告警、受控处置与敏感信息保护	reference.md
OPS-3	影子数据库、topic、服务身份隔离并禁生产写	PRE-1
OPS-4	对拍、切流观察、恢复演练及完整回退规程	C-1～C-29

4.2 契约依赖索引

Q 的定义与完整表述只在本文件之外一处：specification.md「待确认事项台账」。此处只列与验收直接相关的依赖：

• US-01 / US-09 的验收依赖 Q2（发现完整性）与 C-8（清除前提）；
• US-06 / US-13 / US-14 依赖 Q8（逐类清单）与 Q13（字段缺失语义）；
• US-08 依赖 Q3（HTTP 契约）、Q4（Kafka wire）、Q5（请求匹配）、Q10（出站契约）；
• US-10 依赖重放白名单与 CLM-3（重放安全）；
• US-15 依赖 Q9（清除授权与 DDL）。

业务日期/日计划采用 Asia/Shanghai；持久化与比较使用明确的时间类型和转换规则，不靠服务器默认时区，也不直接比较不同单位的数字。

5. HTTP 工具边界

端点	范围
POST /cminmsgs/send	US-02，保留接收兼容性。
POST /schd/sync	US-08，保留并修正参数校验；不等同于同步完成快照。
GET /all/flights	US-12，保留查询语义。
POST /kafka/topics/{name}/msgs	不进生产；开发工具若保留，另行限制 topic allowlist。
GET /flights/migrate	不做，属于 legacy 一次性迁移工具。