From 9909dbd7e0b6ad45685728157a12533fb5d9b16d Mon Sep 17 00:00:00 2001 From: windyboy Date: Fri, 18 Sep 2026 08:47:27 +0800 Subject: [PATCH] =?UTF-8?q?docs(acm2-75):=20=E6=94=B6=E6=95=9B=20Kafka=20?= =?UTF-8?q?=E5=8F=A3=E5=BE=84=E5=B9=B6=E6=B8=85=E6=8E=89=E8=88=AA=E7=8F=AD?= =?UTF-8?q?=E7=89=88=E6=9C=AC=E5=8F=B7=E6=AE=8B=E7=95=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Kafka「尚需确定」去掉消费者去重与版本标识，改为消费方的字段要求 - `schd` 落定内容（`SCHD.FLTR` JSON，空字段不输出）、删除不进本主题、批次边界为定时 tick - `Q1` 收窄为 record 粒度（`C-9` 每条一条 vs 旧系统整批一个数组） - `Q5` 由版本标识改为 `msg` 的字段、编码与删除区分 - 删除航班版本号表述：README 事实归属的 `STATE_VERSION`、契约 `FLIGHT_SCHD` 的版本字段、验证映射 `INV-4` - 删除 requirements 的「本版本主要新增能力」changelog 句 --- docs/README.md | 2 +- docs/contracts/interface-contract.md | 6 +++--- docs/requirements.md | 2 -- docs/specification.md | 8 ++++---- 4 files changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/README.md b/docs/README.md index cd00a1c..b539d43 100644 --- a/docs/README.md +++ b/docs/README.md @@ -33,7 +33,7 @@ | 回填四结果、放弃语义、`R` 的作用 | implementation.md「回填」 | specification.md 记结论与可声明性 | | 退避 / `claim-batch` / 回填期限等取值 | reference.md「参数」 | 其余文档只引 `PARAM:` | | 消费权排他、ID 不复位、报文不可变、时钟、单实例 | specification.md「前提」 | 其他文档只引 `PRE-x` | -| 航班身份、合并语义、`STATE_VERSION`、`OPERATION_DAY` | implementation.md「航班域」 | 其余文档只引域规则与 `INV-x` | +| 航班身份、合并语义、`OPERATION_DAY` | implementation.md「航班域」 | 其余文档只引域规则与 `INV-x` | | 航班动态逐类语义与空标签规则（FLOP） | implementation.md「动态运行事件」 | specification.md 记 `Q3` 与 `G-*`；requirements.md 写验收口径 | | SIS 消息中的参考数据类别、结构与资源状态 | implementation.md「静态参考数据」 | requirements.md 写取数与刷新验收；admin-api 只从处理后的业务数据库读取 | | 对外术语（落信 / 入站 / 库方 / 处理标记） | specification.md「术语」 | — | diff --git a/docs/contracts/interface-contract.md b/docs/contracts/interface-contract.md index 4e5cdcb..f1af31f 100644 --- a/docs/contracts/interface-contract.md +++ b/docs/contracts/interface-contract.md @@ -43,8 +43,8 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定 | 主题 | 已确定的消息语义 | 尚需确定 | |---|---|---| -| `msg` | 单条航班变更通知；航班动态与删除处理完成后投递；发送失败自动重试，一直失败的记录保留可查并告警（`US-08`）；同一 `FLID` 的变更保序，对外按至少一次投递。删除通知的来源有三处：`FDEL` 删除（`US-06`）、日计划快照缺席删除（`US-07`）、历史清理在物理删除前必要时登记（架构 `D1`）。 | Kafka value 的字段与类型、变更和删除的区分方式、版本与去重标识（`Q5`；可用依据是航班当前态的版本规则，见 `FLIGHT_SCHD` 行）、编码方式、分区规则、消费者处理重复和乱序的规则。 | -| `schd` | 定时批量发送最新航班状态；发送失败自动重试；对外按至少一次投递。 | “批量”对应的 Kafka record 粒度、value 字段与类型、删除航班的表达方式、批次边界、编码方式、消费者去重规则。 | +| `msg` | 单条航班变更通知；航班动态与删除处理完成后投递；发送失败自动重试，一直失败的记录保留可查并告警（`US-08`）；同一 `FLID` 的变更保序，对外按至少一次投递。删除通知的来源有三处：`FDEL` 删除（`US-06`）、日计划快照缺席删除（`US-07`）、历史清理在物理删除前必要时登记（架构 `D1`）。 | Kafka value 的字段与类型、变更和删除的区分方式（`Q5`）、编码方式、分区规则。 | +| `schd` | 定时批量发送最新航班状态；内容是 `SCHD.FLTR` 序列化出的 JSON，空字段不输出，字段与类型见 [XSD](../legacy/unisysaodbsis.xsd) 的 `FLTR`；边界是定时任务的一次 tick，两次 tick 之间积累的变化整批发一次，没有变化就不发；删除航班不进入本主题，由 `msg` 发一条删除通知；发送失败自动重试，对外按至少一次投递（`US-08`）。 | “批量”对应的 Kafka record 粒度（`Q1`）。 | 旧系统线索（来源：旧项目用户故事「前端通知」「动态类（FLOP-*）处理」）： @@ -92,7 +92,7 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定 | 表或表组 | 边界 | 尚需确定的字段级契约 | |---|---|---| | `REF_MASTER` | 静态参考数据与资源状态按类别、编号保存在独立数据表，admin-api 直接只读；新消息覆盖旧记录，全量消息整体替换，增删改消息逐条处理（`US-13`）；一类校验不通过只停这一类、其他类照常，校验失败类别的已有记录不变；字段为空表示「当前没有值」，不是删除（架构「必须保持的约束」）。 | 类别和编号的物理列、各类别字段及类型、主键/唯一键、空值在列中怎样保存、写入后何时可读。类别范围与消息中的识别标签见下表。 | -| `FLIGHT_SCHD`、资源明细表、`FLIGHT_ROUTE_POINT` | 航班当前态的唯一权威；`FLID` 唯一（架构「必须保持的约束」）；Redis 和 Kafka 从处理结果派生，不反向覆盖这些表。 | 主键、字段与类型、资源明细表清单、外键/索引、版本字段的物理列与迁移 DDL。 | +| `FLIGHT_SCHD`、资源明细表、`FLIGHT_ROUTE_POINT` | 航班当前态的唯一权威；`FLID` 唯一（架构「必须保持的约束」）；Redis 和 Kafka 从处理结果派生，不反向覆盖这些表。 | 主键、字段与类型、资源明细表清单、外键/索引与迁移 DDL。 | | `PROC_STATE`、`MSG_EVENT`、`REQ_TRACK`、`SCHD_SNAP_LOG`、`PIPELINE_LOCK`、`UNMAPPED_FIELD` | 管道处理、待发事件、请求跟踪、留痕、互斥及未映射字段由本系统维护；不对外提供直接读写接口。 | 字段、约束、索引与迁移 DDL 由内部实现设计确定；若其他系统需读取，须另立读取契约。 | 自有 PostgreSQL 的物理表结构由本系统的迁移 DDL 定稿。生产环境若改用 Oracle 11g，字段类型与迁移方案需先完成适配验证。 diff --git a/docs/requirements.md b/docs/requirements.md index 99936bc..2afe418 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -12,8 +12,6 @@ **交付范围**：`US-01`～`US-14`、`OPS-1`～`OPS-4`。 -**本版本主要新增能力**：静态参考数据同步（`US-13`）。 - **非目标**： - 航班当前态权威只在自有 PG；Redis 仅作查询投影，不作权威或处理状态。不引入并行主泵或分布式锁。 diff --git a/docs/specification.md b/docs/specification.md index 8447380..7681a6f 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -54,7 +54,7 @@ ### 2.4 下游（admin-api、网页客户端与运营航班显示界面） -- **C-9** 航班变更发到 Kafka 主题 `msg`（单条）和 `schd`（批量）；`schd` 每条为运营航班 JSON；不设消息键。同一条可能发多次。 +- **C-9** 航班变更发到 Kafka 主题 `msg`（单条）和 `schd`（批量）；`schd` 的内容是 `SCHD.FLTR` 序列化出的 JSON，空字段不输出，边界是定时任务的一次 tick——两次 tick 之间积累的变化整批发一次，没有变化就不发；删除航班不进 `schd`，只由 `msg` 发一条删除通知；不设消息键。同一条可能发多次。 - **C-10** 静态参考数据写入本系统数据库，供 admin-api 只读；本系统不调用 admin-api。 - **C-11** 航班投影写入 Redis，供读取全体动态航班；`GET /all/flights` 与网页客户端读同一份；返回 JSON 由消息文档中的 XML 结构转换而来（`Q6`、`Q21`）。 @@ -106,11 +106,11 @@ | 编号 | 事项 | 当前假定 | 影响 | |---|---|---|---| -| Q1 | `schd` 的 value 字段与类型、删除航班的表达方式、批次边界、消费者去重规则 | 每条 record 为一条运营航班 JSON（`C-9`）；批次边界按定时窗口 | 消费方读取契约无法定稿 | +| Q1 | `schd` 的 Kafka record 粒度 | 按 `C-9` 是每条 record 一条运营航班 JSON；旧系统相反，把两次定时 tick 之间积累的整批序列化成一个 JSON 数组作为单条 record 发出 | 消费方的解析方式与 `C-9` 二者只能取一 | | Q2 | 请求与应答按时间匹配时的时钟偏斜容忍判据 | 比较前统一时区与单位（implementation.md「上游请求与静态数据」） | 容忍判据未定前，降级匹配不得描述为精确关联 | | Q3 | 现场会发但 SIS 未定义的子类型（靠桥、延误等）的报文形态与逐类终态 | 按现有处理逻辑延续，不得因 SIS 未记载就丢掉（`US-05` AC1） | 逐类终态与幂等规则未定（`G-FLOP-SEMANTICS`） | | Q4 | 上游重发时是否可能改发正文 | 报文不可变，绑定身份后不比对内容（implementation.md「消息、身份与决策」） | 改发正文的重发会被判为重复并跳过 | -| Q5 | `msg` 的版本与去重标识是否直接采用航班当前态的版本号 | 可用依据是航班当前态的版本规则（implementation.md「航班域：权威模型与合并写入语义」） | 消费方去重规则未定（与 `Q1` 衔接） | +| Q5 | `msg` 的 value 字段与类型、编码方式、变更与删除的区分方式 | 沿用旧系统：value 是 `MSG` 的 JSON（`META` 加对应业务体），日计划到达通知只有 `META`（接口契约「Kafka」） | 消费方读取契约无法定稿 | | Q6 | 网页客户端读取 Redis 投影的约定 | 沿用旧系统的 hash `flightInfo`：field 为 `FLID`，value 为完整航班对象的带类型 JSON，不设过期；写入与移除时机见 `INV-7`、`INV-8`、`INV-10`；派生字段 `MAFL`、`abdg` 是否随投影提供仍未定；只作查询、不是权威；与 `GET /all/flights` 同一份（`C-11`；接口契约「Redis：航班查询投影」） | 消费方读取契约无法定稿 | 答复就地更新结论，并按 [README.md](README.md)「维护清单」落到对应条款。 @@ -184,7 +184,7 @@ | INV-7 | `US-07` AC2/AC3 | 缺席的航班在 PG 标为已删除并从 Redis 投影移除；未携带的字段被清空 | | INV-3 | `US-03` AC4、`US-05` AC4、`US-06` AC1 | 投影写失败时，没有终态与回填意图落库；处理完成前事件不可投递 | | US-14 AC4 | `US-14` AC4 | 历史清理跳过正在被消息处理的航班 | -| INV-4 | `US-07` AC1 | 校验失败后本地数据与版本不变 | +| INV-4 | `US-07` AC1 | 校验失败后本地数据不变 | | INV-9 | `US-07` AC4/AC5 | 分批失败后整包重处理收敛到同一目标（`G-SCHD-SNAPSHOT` 闭合前无法验证）；Redis 在整包写入完成后按快照刷新，成功即与快照一致 | | CLM-1 | `US-03` | 同一消息不产生两次效果；逐子类型规则与幂等矩阵在 `Q3`、`G-FLOP-IDEMPOTENT`、`G-FLOP-SEMANTICS` 闭合前无法验证 | | INV-8 | `US-06` AC1 | 航班标记删除后从投影移除；移除失败时下轮重做 |