From 8749d83d83d54f2b11cc94613552b06adf0e28b8 Mon Sep 17 00:00:00 2001 From: windyboy Date: Sun, 20 Sep 2026 08:51:49 +0800 Subject: [PATCH] =?UTF-8?q?docs(acm2-75):=20=E7=B2=BE=E7=AE=80=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3=E5=A5=91=E7=BA=A6=E5=B9=B6=E5=AF=B9=E9=BD=90=E5=B7=B2?= =?UTF-8?q?=E5=AE=9A=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/contracts/interface-contract.md | 46 ++++++++++------------------ docs/implementation.md | 2 +- 2 files changed, 17 insertions(+), 31 deletions(-) diff --git a/docs/contracts/interface-contract.md b/docs/contracts/interface-contract.md index 7c9d909..2799dba 100644 --- a/docs/contracts/interface-contract.md +++ b/docs/contracts/interface-contract.md @@ -20,17 +20,14 @@ - `POST /cminmsgs/send` 的成功 `body` 是 `CMINMSGS_ID`，样例为 `{is_success: true, body: }`。 - `GET /all/flights` 的 `body` 是非共享航班的 `SCHD.FLTR` 列表。 - `POST /schd/sync` 的请求体是 `{startDate, endDate}`，时间格式 `yyyy-MM-dd hh:mm` 用无 AM/PM 的 12 小时制。 -- 出站报文用 `TYPE=RQFD`、`STYP=NONE`、`SNDR=OSH5`，日期范围编码为 `RQFD.STDB` / `STDE`。 -这些字段是否沿用、时间改用何种无歧义格式，都要核对后定稿。 - -新版日计划是 AODB 当前时刻的完整航班列表（`US-07`），请求是否仍带日期范围由这条全量语义判断。 +这些字段是否沿用、时间改用何种无歧义格式，都要核对后定稿。新版日计划是 AODB 当前时刻的完整航班列表（`US-07`），出站编码已定（`C-4`），不带日期筛选。 ## 入站报文与请求应答 AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定的 [SIS 接口规范](../legacy/SIS_AODB_RMS-V0.1.md) 与 [XSD](../legacy/unisysaodbsis.xsd) 为依据。 -入站报文按类型处理：`ADFT` 建立计划外航班，`FLOP` 改航班动态，`FDEL` 删航班，`SCHD-DNLD` 与 `SCHD-RESP` 同步日计划快照，参考数据写入 `REF_MASTER`（`US-04`～`US-07`、`US-13`）；报文不合法进死信，合法但本系统不支持的类型跳过留档并按已处理写回信箱（`US-03`）。 +入站报文按类型处理：`ADFT` 建立计划外航班，`FLOP` 改航班动态，`FDEL` 删航班，`SCHD-DNLD` 与 `SCHD-RESP` 同步日计划快照，参考数据写入自有 PG 的静态参考数据表组（逻辑视图 `REF_MASTER`，物理形态由内部迁移确定；报文到表的映射待 `Q22` 定稿；联调栈 `basicdata` schema 的基础数据表对齐 admin-api 实体注解，不预设 `REF_MASTER` 落表方式；`US-04`～`US-07`、`US-13`）；报文不合法进死信，合法但本系统不支持的类型跳过留档并按已处理写回信箱（`US-03`）。 | 环节 | 已确定的边界 | 尚需确定 | |---|---|---| @@ -43,7 +40,7 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定 | 主题 | 已确定的消息语义 | 尚需确定 | |---|---|---| -| `msg` | 单条航班变更通知；航班动态与删除处理完成后投递；发送失败自动重试，一直失败的记录保留可查并告警（`US-08`）；同一 `FLID` 的变更保序，对外按至少一次投递。删除通知的来源有三处：`FDEL` 删除（`US-06`）、日计划快照缺席删除（`US-07`）、历史清理在物理删除前必要时登记（架构 `D1`）。 | Kafka value 的字段与类型、变更和删除的区分方式（`Q5`）、编码方式、分区规则。 | +| `msg` | 单条航班变更通知；航班动态与删除处理完成后投递；发送失败自动重试，一直失败的记录保留可查并告警（`US-08`）；同一 `FLID` 的变更保序，对外按至少一次投递（`CLM-3`，单分区）。删除通知的来源有三处：`FDEL` 删除（`US-06`）、日计划快照缺席删除（`US-07`）、历史清理在物理删除前必要时登记（架构 `D1`）。 | Kafka value 的字段与类型、变更和删除的区分方式（`Q5`）、编码方式。 | | `schd` | 定时批量发送最新航班状态；两次 tick 之间积累的航班组成 `SCHD.FLTR` 数组 JSON，整批作为单条 record 发出（沿用旧系统，`Q1`）；空字段不输出，字段与类型见 [XSD](../legacy/unisysaodbsis.xsd) 的 `FLTR`；没有变化不发；删除航班不进入本主题，由 `msg` 发一条删除通知；发送失败自动重试，对外按至少一次投递（`US-08`）。 | 消费方按数组格式解析的确认（`Q1`）。 | 旧系统线索（来源：旧项目用户故事「前端通知」「动态类（FLOP-*）处理」）： @@ -52,7 +49,7 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定 - 只对非共享航班的变更单条下发，共享航班随主航班下发；例外是删除，共享航班被删时也单独发一条 `msg` 删除消息。 - `schd` 把窗口内航班组成 `SCHD.FLTR` 数组 JSON，队列为空时不发送。 -跨航班顺序不构成契约。 +两个主题均不设消息键（`C-9`）；跨航班顺序不构成契约。 测试环境与生产隔离的前提见 [specification.md](../specification.md) 的 `PRE-1`（`OPS-3`）。 @@ -62,10 +59,10 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定 | 表 | 本系统的操作 | 需要对接方提供的物理契约 | |---|---|---| -| `CMINMSGS` | 按信箱编号升序、分批读取未处理的报文，扫描与回写用同一处理时间列；兼容 HTTP 入口写入 XML 原文；处理完成后写入处理完成时刻，只填空值、不覆盖已有值；写回失败由后台任务重试，一直写不上的记录保留在案并告警（`US-01`、`US-02`、`US-10`）。 | 表 DDL、信箱编号与报文原文字段、处理时间列的列名、类型与可空性及写入样例（处理标记即该处理时间列，见 [specification.md](../specification.md)「术语」的处理标记；回填只填空值）、写入必需列、原文保留期和索引；信箱编号按到达顺序单调递增、不复用、不回退的保证（架构「必须保持的约束」）。 | +| `CMINMSGS` | 按信箱编号升序、分批读取未处理的报文，扫描与回写用同一处理时间列（`CMINMSGS_DATE_PROCESSED`，`Q8`）；兼容 HTTP 入口写入 XML 原文；处理完成后写入处理完成时刻，只填空值、不覆盖已有值；写回失败由后台任务重试，一直写不上的记录保留在案并告警（`US-01`、`US-02`、`US-10`）。信箱编号即入库行号，单调递增、不复用、不回退（`Q7`）。 | 表 DDL、信箱编号与报文原文字段、处理时间列的类型与可空性及写入样例（处理标记即该处理时间列，见 [specification.md](../specification.md)「术语」的处理标记；回填只填空值）、写入必需列、原文保留期和索引。 | | `COUTMSGS` | 写入 `RQRD` 参考数据请求与 `RQFD` 日计划请求；CIIMS adapter 消费。交付承诺止于请求落信；写入结果不明时记录并告警，不直接重发（架构「主流程」）。 | 表 DDL、请求原文字段、写入必需列、编号生成方式、重复落信的识别规则。 | -共享 MySQL 归 CIIMS adapter 方所有；本系统不建表、不改表结构、不清除数据，也不写共享历史表。外部表的物理字段必须以对接方提供的现行 DDL 与读写样例核对，不能由本文件推造。 +共享 MySQL 归 CIIMS adapter 方所有；本系统不建表、不改表结构，也不写共享历史表。已回填且超过保留期的入站行由本系统清理（`C-1`）。外部表的物理字段必须以对接方提供的现行 DDL 与读写样例核对，不能由本文件推造。 旧项目用户故事「数据表列清单」提供以下**旧系统实体映射列名**，不是现场 DDL、可空性或写权限的证明： @@ -85,21 +82,22 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定 - 投影是 hash `flightInfo`：field 为 `FLID`，value 为完整 `SCHD.FLTR` 对象的带类型 JSON，不设过期；Redis 里没有名为 `schd` 的 key，`schd` 只是 Kafka 主题。 - 写入路径：日计划下载（`DNLD`／`RESP`）整体写入当天航班，单条变更（`ADFT`、`FLOP`）只写对应的一条，转历史时按 `FLID` 逐条移除。整体写入不删除本次映射中缺席的航班，与 `US-07` AC5 相反，新版按 `US-07` AC5 刷新。 - 写入前生成主航班的共享航班列表 `MAFL`（`G-MAFL`），是否为网页客户端所需仍未定（`Q6`）；登机桥字段 `abdg` 本版不提供——旧系统拼它的数据源是机位与登机桥映射缓存，已列入需求「范围与非目标」不交付。 -- 旧系统 Redis 另有两条机位基础数据缓存，都由本系统调用 admin-api 填充、过期 3600 秒：`orms_stand`（field 为机位代码，value 为 `OrmsStand` 对象的带类型 JSON）；`orms_stand_airbridge`（field 为机位代码，value 为登机桥代码数组的 JSON 字符串，不是对象）。这两条是旧系统按计划机位拼 `abdg` 的数据来源，本版不交付（需求「范围与非目标」）。 ### 自有 PostgreSQL：内部存储与 admin-api 只读 | 表或表组 | 边界 | 尚需确定的字段级契约 | |---|---|---| -| 静态参考数据表组 | 静态参考数据与资源状态保存在独立数据表组，表与列直接取 admin-api 实体注解，不改名、不合并，admin-api 直接只读；新消息覆盖旧记录，全量消息整体替换，增删改消息逐条处理（`US-13`）；一类校验不通过只停这一类、其他类照常，校验失败类别的已有记录不变；字段为空表示「当前没有值」，不是删除（架构「必须保持的约束」）。 | 13 类报文与资源状态到表组的映射（`Q22`）；admin-api 需要哪些字段。类别码与消息中的识别标签见下表。 | -| `FLIGHT_SCHD`、资源明细表、`FLIGHT_ROUTE_POINT` | 航班当前态的唯一权威；`FLID` 唯一（架构「必须保持的约束」）；Redis 和 Kafka 从处理结果派生，不反向覆盖这些表。 | 主键、字段与类型、资源明细表清单、外键/索引与迁移 DDL。 | -| `PROC_STATE`、`MSG_EVENT`、`REQ_TRACK`、`SCHD_SNAP_LOG`、`PIPELINE_LOCK`、`UNMAPPED_FIELD` | 管道处理、待发事件、请求跟踪、留痕、互斥及未映射字段由本系统维护；不对外提供直接读写接口。 | 字段、约束、索引与迁移 DDL 由内部实现设计确定；若其他系统需读取，须另立读取契约。 | +| 静态参考数据表组 | 静态参考数据与资源状态保存在独立数据表组（逻辑视图 `REF_MASTER`，物理形态由内部迁移确定；报文到表的映射待 `Q22` 定稿；联调栈 `basicdata` schema 的基础数据表对齐 admin-api 实体注解，不预设 `REF_MASTER` 落表方式）；表与列直接取 admin-api 实体注解，不改名、不合并，admin-api 直接只读；新消息覆盖旧记录，全量消息整体替换，增删改消息逐条处理（`US-13`）；一类校验不通过只停这一类、其他类照常，校验失败类别的已有记录不变；字段为空表示「当前没有值」，不是删除（架构「必须保持的约束」）。 | 13 类报文与资源状态到表组的映射（`Q22`）；admin-api 需要哪些字段。类别码与消息中的识别标签见下表。 | +| 航班当前态表 | 航班当前态的唯一权威；`FLID` 唯一（架构「必须保持的约束」）；Redis 和 Kafka 从处理结果派生，不反向覆盖这些表。 | 主键、字段与类型、外键/索引。 | +| 内部处理表 | 管道处理、请求跟踪、留痕与互斥由本系统维护；不对外提供直接读写接口。 | 字段与约束由内部实现设计确定。 | -自有 PostgreSQL 的物理表结构由本系统的迁移 DDL 定稿。生产环境若改用 Oracle 11g，字段类型与迁移方案需先完成适配验证。 +admin-api 还从本系统数据库只读季度计划；供数方与报文形态待 `Q25` 确定。 + +自有 PostgreSQL 的物理表结构由本系统的迁移定稿。生产环境若改用 Oracle 11g，字段类型需先完成适配验证。 ### 静态参考数据类别与编号来源 -类别码与识别标签来自架构引用的 [SIS 接口规范](../legacy/SIS_AODB_RMS-V0.1.md)；识别同一条参考记录时，用类别码加识别标签值。标签值的格式、标签在哪个范围内唯一，以及保存到 `REF_MASTER` 的方式，仍需在本系统的表结构中明确。 +类别码与识别标签来自架构引用的 [SIS 接口规范](../legacy/SIS_AODB_RMS-V0.1.md)；识别同一条参考记录时，用类别码加识别标签值。标签值的格式、标签在哪个范围内唯一，以及报文到表的映射，仍需 `Q22` 定稿。 | 类别码 | 类别 | 消息中的识别标签 | SIS 依据 | |---|---|---|---| @@ -124,24 +122,12 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定 | 契约项 | 已确定的边界 | 尚需确定 | |---|---|---| | 写入对象 | 满足 `US-14` 已结束判据的航班从自有业务数据库写入 Elasticsearch 历史库，作为历史查询副本。 | 历史索引名称、文档 ID、写入字段及类型、嵌套资源结构、字段缺失与删除状态的表达方式、索引保留期与容量上限（架构「数据归属与一致性」列为未定）。 | -| 成功确认 | 只有该航班的历史写入成功，才允许从实时数据物理删除；删除前按 `D1` 必要时登记待发删除事件。 | Elasticsearch 写入响应中何种结果算成功、成功是否要求可查询、批量响应如何逐项确认。 | -| 写入粒度 | 单个航班写入失败不影响其他航班。 | 使用逐条请求还是批量请求、批量大小、部分成功时的确认与继续处理规则。 | -| 失败与重试 | 写入失败的航班保持在实时数据中，下次运行再试；已写入的航班不重复写入；正在被消息处理的航班跳过，下轮再处理。文档 ID 按旧系统线索为 `SODT + FLID` 幂等 upsert，写入结果不明时重试同一写入。 | 可重试错误分类、重试间隔。 | +| 成功确认 | 只有该航班的历史写入成功，才允许从实时数据物理删除；删除前按 `D1` 必要时登记待发删除事件。 | Elasticsearch 写入响应中何种结果算成功、成功是否要求可查询。 | +| 写入粒度 | 单个航班写入失败不影响其他航班。 | 部分成功时的确认与继续处理规则。 | +| 失败与重试 | 写入失败的航班保持在实时数据中，下次运行再试；已写入的航班不重复写入；正在被消息处理的航班跳过，下轮再处理。文档 ID 按旧系统线索为 `SODT + FLID` 幂等 upsert，写入结果不明时重试同一写入。 | 重试间隔。 | 旧系统线索：逐航班按 `SODT + FLID` 查询旧索引 `flight_hts`，存在则更新、不存在则新增；写入内容是 `SCHD.FLTR` 序列化后的 JSON，单条写入失败跳过该航班（旧项目用户故事「动态航班转历史」）。 ## 待决事项 由本系统与需求方确定的事项见 [specification.md](../specification.md)「本系统与需求方待决」。 - -## 定稿所需证据 - -1. 核对三个 HTTP 接口的旧系统线索，取得成功和失败响应样例、实际状态码及 `/schd/sync` 的无歧义时间格式。 -2. 运营航班显示界面的 `msg`、`schd` 消费样例和字段要求，特别是变更、删除、重复投递的处理方式。 -3. CIIMS adapter 方提供的 `CMINMSGS`、`COUTMSGS` 现行 DDL、读写样例和写权限说明，核对旧系统实体映射列名，并确认信箱编号单调递增、不复用、不回退。 -4. 13 类参考数据与资源状态的编号规则，以及自有 PostgreSQL 的迁移 DDL。 -5. 网页客户端读取 Redis 投影的约定，含它需要哪些字段（`Q6`）。 -6. AODB 应答与 `EROR` 样例，含请求与应答的对应字段、超时判定依据。 -7. Elasticsearch 历史索引映射、文档样例、逐条或批量写入响应、索引保留期与容量上限，以及写入结果不明时的对账规则。 - -只有上述证据核对完成后，待定字段才能转为字段级契约；任何新增字段、默认值或错误码都需写明其来源与对接方。 diff --git a/docs/implementation.md b/docs/implementation.md index c0b7c9d..c2bc006 100644 --- a/docs/implementation.md +++ b/docs/implementation.md @@ -263,7 +263,7 @@ PENDING → SENT → DONE 发送时： 1. 到期领取批次：按 `FLID` 取未发送行，批次大小受 `PARAM:msgx.schd.flush-limit` 约束； -2. 逐条发送：UPSERT 发送该 `FLID` 的最新整态（key = `FLID`）；TOMBSTONE 发送 null 值删除通知； +2. 整批发送：将批次内所有航班的最新整态序列化为 `SCHD.FLTR` 数组 JSON，作为单条 record 发出（`C-9`）；删除航班不进入 `schd`，只由 `msg` 发删除通知； 3. 成功后按上条规则标记完成并推进 `lastFlush`；失败按退避推后，达到上限转 `DEAD`。 聚合周期与批上限见 [reference.md](reference.md)。`KAFKA:msg` 与 `KAFKA:schd` 之间不承诺顺序。`schd` 行与 `msg` 行共用 `MSG_EVENT`，靠 `TARGET` 区分。