From 050eadc1a2f3934ca155aacb7872edf4da381f76 Mon Sep 17 00:00:00 2001 From: windyboy Date: Sun, 20 Sep 2026 09:43:23 +0800 Subject: [PATCH] =?UTF-8?q?docs(acm2):=20spec=20=E5=AF=B9=E9=BD=90?= =?UTF-8?q?=E4=B8=89=E6=96=87=E6=A1=A3=E2=80=94=E2=80=94C-8=20=E7=99=BB?= =?UTF-8?q?=E8=AE=B0=E8=AF=AD=E4=B9=89=E3=80=81C-7/CLM-3/=E6=9C=AF?= =?UTF-8?q?=E8=AF=AD=E5=AF=B9=E9=BD=90=E3=80=81=E5=88=A0=E6=81=92=E7=AD=89?= =?UTF-8?q?=E6=98=A0=E5=B0=84=E4=B8=8E=E5=A4=8D=E8=BF=B0=E8=A1=8C=E3=80=81?= =?UTF-8?q?Q25=20=E6=94=B9=E5=B0=8F=E8=8A=82=E5=90=8D=E5=BC=95=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/specification.md | 83 ++++++++++++++++++++----------------------- 1 file changed, 39 insertions(+), 44 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index 6197bbe..6be814b 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -30,7 +30,7 @@ | 出站请求 | 经 `COUTMSGS` 发向 AODB 的 `RQRD` 参考数据请求与 `RQFD` 日计划请求，消费方为 CIIMS adapter。 | | 运营航班显示界面 | 需求所称网页客户端：Kafka 侧称运营航班显示界面，查询侧称网页客户端（`GET /all/flights` / Redis）。 | | 航班历史 | 已结束航班写入 Elasticsearch 后的副本；写成功后才从实时数据删除。 | -| 静态参考数据 | 13 类基础数据与资源状态，写自有 PG 的独立数据表，admin-api 直接只读。 | +| 静态参考数据 | 13 类基础数据与资源状态，写自有 PG 的独立数据表组（逻辑视图 `REF_MASTER`，物理形态由内部迁移确定），admin-api 直接只读。 | ## 2. 约定 @@ -48,9 +48,8 @@ ### 2.3 HTTP 入口 -- **C-7** `POST /cminmsgs/send`：把 XML 写进入站信箱，与 adapter 投递走同一套处理。成功返回消息编号（仅表示已入库、未处理）；失败不返回编号。支持 `text/xml`、`application/xml`、`text/plain`（UTF-8）；空、超长、格式错的不写；解析不拉外部资源。内网，访问由网络配置控制。仅内部联调；长度上限与失败响应由实现自定。 -- **C-8** `POST /schd/sync`：向出站表写入一条日计划请求。 - 待确认：请求参数、HTTP 响应（`Q16`）。 +- **C-7** `POST /cminmsgs/send`：把 XML 写进入站信箱，与 adapter 投递走同一套处理。成功返回消息编号（仅表示已入库、未处理）；失败不返回编号。支持 `text/xml`、`application/xml`、`text/plain`（UTF-8）；空、超长、格式错的不写；解析不拉外部资源。内网，访问由网络配置控制。仅内部联调。大小上限、HTTP 状态码、成功/失败响应体字段及样例属接口契约「HTTP」，尚未确定。 +- **C-8** `POST /schd/sync`：登记一次 `RQFD` 日计划请求；同子类型已有在途时新请求不落信，待在途结案后再写入 `COUTMSGS`（架构「主流程」、`US-09` AC1）。请求参数与 HTTP 响应待 `Q16`。 ### 2.4 下游（admin-api、网页客户端与运营航班显示界面） @@ -94,10 +93,10 @@ |---|---|---|---|---| | CLM-1 | 同一消息再处理不会多出一份业务效果 | `US-03` | 不能 | 各类报文的细则未补齐（`G-FLOP-IDEMPOTENT`） | | CLM-2 | 按信箱编号升序处理 | `US-03` AC1 | 能 | — | -| CLM-3 | 主题 `msg` 上同一 `FLID` 内按发送顺序保序 | `US-08` AC2、`C-9` | 能 | `msg` 单分区；至少一次重发时消费者仍可能见到乱序 | +| CLM-3 | 主题 `msg` 上同一 `FLID` 内按发送顺序保序 | `US-08` AC2、`C-9` | 能 | `msg` 单分区；至少一次投递时重发可能重复（`D2`） | | CLM-4 | 出站请求写入共享出站表 `COUTMSGS` | `C-4` | 能 | 只保证写入信箱，不保证 AODB 收到 | -| CLM-5 | 消息在固定时限内处理完 | — | 不能 | 需求未定完成时限；现场一般为即时处理，但不作时限保证 | -| CLM-6 | 容量与吞吐量级 | — | 不能 | 现场量级暂无；有日量、峰值等数据后再估 | +| CLM-5 | 消息在固定时限内处理完 | — | 不能 | 需求未定完成时限 | +| CLM-6 | 容量与吞吐量级 | — | 不能 | 需求未给日量与峰值，有数据后再估 | | CLM-7 | 配置不完整时拒绝启动 | `OPS-1` | 能 | — | ## 6. 待确认事项台账 @@ -110,7 +109,7 @@ | Q3 | 现场会发但 SIS 未定义的子类型（靠桥、延误等）的报文形态与逐类终态 | 按现有处理逻辑延续，不得因 SIS 未记载就丢掉（`US-05` AC1） | 逐类终态与幂等规则未定（`G-FLOP-SEMANTICS`） | | Q4 | 上游重发时是否可能改发正文 | 报文不可变，绑定身份后不比对内容（implementation.md「消息、身份与决策」） | 改发正文的重发会被判为重复并跳过 | | 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：航班查询投影」） | 消费方读取契约无法定稿 | +| Q6 | 网页客户端读取 Redis 投影的约定 | 读写边界见接口契约「Redis：航班查询投影」与 `C-11`；`MAFL` 是否随投影提供仍未定 | 消费方读取契约无法定稿 | 答复就地更新结论，并按 [README.md](README.md)「维护清单」落到对应条款。 @@ -118,13 +117,13 @@ | 编号 | 事项 | 结论 | |---|---|---| -| Q7 | 信箱编号的单调、不复用、不回退 | 已定案：编号即入库行号，单调递增、不复用、不回退；按编号升序处理即按到达顺序（`US-01` AC3、`CLM-2`） | -| Q8 | 入站处理时间列 | 已定案：与旧系统相同，列名为 `CMINMSGS_DATE_PROCESSED`；空为未处理，回填写入完成时刻（`US-10`） | -| Q9 | 入站信箱行（MySQL `CMINMSGS`）清除 | 已定案：本系统回填后自清（`C-1`）；保留期可配置，按约 1 个月 | -| Q10 | 上游 `SEQN` 的重置周期与身份是否加日期边界 | 已定案：`SEQN` 自增，极少重置，重置后不与旧消息冲突，不加日期边界（`C-3`） | -| Q11 | 日计划未携带字段的删除语义 | 见 `C-6` | -| Q12 | 主/共享删除顺序 | 已定案：标记删除，各自独立（`C-5`） | -| Q13 | `RQRD` / `RQFD` 编码字段 | 已定案：`SNDR=OMMS`；`SEQN` 本系统自建序列；`DTTM` 为北京时间 `YYYYMMDDHHMMSS`（SIS META）；`RQRD` 子类型以 SIS 为准共 14 类（含 `RSTA`，其可选 `RTYP`）；`RQFD` 的 `STYP=NONE`，`STDB`/`STDE` 等筛选可选，全量同步不带筛选（SIS：无参数则返回当天全部，对齐 `US-07`）（`C-4`） | +| Q7 | 信箱编号的单调、不复用、不回退 | 已定案（`US-01` AC3、`CLM-2`） | +| Q8 | 入站处理时间列 | 已定案：列名 `CMINMSGS_DATE_PROCESSED`（`US-10`） | +| Q9 | 入站信箱行（MySQL `CMINMSGS`）清除 | 已定案（`C-1`） | +| Q10 | 上游 `SEQN` 的重置周期与身份是否加日期边界 | 已定案（`C-3`） | +| Q11 | 日计划未携带字段的删除语义 | 已定案：未携带字段本地清除（`C-6`） | +| Q12 | 主/共享删除顺序 | 已定案（`C-5`） | +| Q13 | `RQRD` / `RQFD` 编码字段 | 已定案（`C-4`） | ### 6.3 本系统与需求方待决 @@ -140,29 +139,29 @@ | Q22 | 13 类报文与资源状态如何映射到 admin-api 实体对齐的基础数据表组（联调栈 `basicdata` schema 为承载） | 表与列直接取 admin-api 实体注解，不改名、不合并（接口契约「自有 PostgreSQL：内部存储与 admin-api 只读」）；类别码与识别标签见接口契约「静态参考数据类别与编号来源」；表组物理形态属内部迁移 DDL，不作待决 | admin-api 读取契约无法定稿（`C-10`） | | Q23 | Elasticsearch 历史索引、文档 ID、字段映射、成功判据、保留期与容量上限 | 文档 ID 沿用旧系统 `SODT + FLID` 幂等 upsert，写入结果不明时重试同一写入（接口契约「Elasticsearch 航班历史写入」）；历史写入确认成功才删实时数据（`D1`、`US-14` AC3） | 历史链路无法验收（`US-14`；`G-FLIGHT-HIST-RETENTION`） | | Q24 | `REQ_TRACK` 已结案记录的保留期取值 | 到期清理没有可依据的窗口（`G-REQ-TRACK-RETENTION`） | 请求历史清理无法实现（`US-09`） | -| Q25 | 季度计划的数据来源与归属：admin-api 从本系统库读季度计划，而 SIS 只有日计划事件（`SIS:3.16`、`SIS:3.17`、`SIS:4.7`） | 应由 AODB 下发，报文形态待确认；旧系统读 Oracle 的 `FIMS_FLIGHTSCHD_SEASON` | admin-api 的季度计划查询没有供数方 | +| Q25 | 季度计划的数据来源与归属：admin-api 从本系统库读季度计划，而 SIS 只有日计划事件（`SIS_AODB_RMS-V0.1.md`「AODB daily flight schedule event」「AODB daily schedule response to RMS event」「RMS daily schedule request event」） | 应由 AODB 下发，报文形态待确认；旧系统读 Oracle 的 `FIMS_FLIGHTSCHD_SEASON` | admin-api 的季度计划查询没有供数方 | ## 7. 当前已知偏差 本表是偏差标记的唯一出处，其他文档只写 `G-NAME`。闭合时删除本行与全仓引用。 -| 偏差 | 缺什么，会怎样 | 影响 | +| 偏差 | 缺口（交付状态见 Plane） | 影响 | |---|---|---| -| `G-REQ-TRACK` | 出站请求没有跟踪：登记、编码、超时与应答匹配都没有实现 | `US-09` | -| `G-REQ-OPEN-UNIQUE` | 同一报文类型同时最多一条已落信、未结案请求的限制没有实现；待发送登记不算占用该名额 | `US-09` | -| `G-REQ-TRACK-RETENTION` | `REQ_TRACK` 已结案记录的保留期取值未定，到期清理作业没有可依据的窗口（取值待 `Q24`） | `US-09` | -| `G-FLIGHT-HIST-RETENTION` | 历史存储的保留期与容量上限未定（取值待 `Q23`） | `US-14`；实时数据删除后历史是唯一副本 | +| `G-REQ-TRACK` | 出站请求跟踪未交付 | `US-09` | +| `G-REQ-OPEN-UNIQUE` | 同类型在途唯一限制未交付 | `US-09` | +| `G-REQ-TRACK-RETENTION` | `REQ_TRACK` 已结案保留期取值未定（`Q24`） | `US-09` | +| `G-FLIGHT-HIST-RETENTION` | 历史保留期与容量上限未定（`Q23`） | `US-14`；实时数据删除后历史是唯一副本 | | `G-FLOP-IDEMPOTENT` | 逐类幂等规则未补齐 | `US-03`；`CLM-1` | -| `G-FLOP-SEMANTICS` | `STYP` 没有白名单，`ROUT` 未限制 4 条，运行状态落点与已删除航班的处理与 `US-05` 不符 | `US-05` | -| `G-FLOP-UNMAPPED` | [XSD](legacy/unisysaodbsis.xsd)「FLOP 元素」里有些字段没有解码或映射错了，会被静默丢掉 | `US-05` | -| `G-MAFL` | 主航班的共享航班列表未实现 | `US-06` AC2；`C-5` | -| `G-SRVT-VIPF` | `SRVT`、`VIPF` 两个集合没有落到持久化明细 | `US-05` | -| `G-SCAN-PREDICATE` | 收报仍按水位扫描，不是按「处理时间为空」读取 | `US-01`；`INV-1` | -| `G-REDIS-PROJECTION` | Redis 投影没有写入与移除路径 | `US-05`、`US-06`、`US-07`、`US-12` | -| `G-SCHD-SNAPSHOT` | 日计划快照不删除缺席航班、不清除未携带字段，也没有分批；逐航班重写幂等未补齐 | `INV-7`；`INV-3`；`INV-9` | -| `G-RESP-GUARD` | `SCHD-RESP` 没有过期判断，晚到的应答也会更新本地数据 | `US-07` | -| `G-PROC-CLEANUP` | 处理记录的到期清理作业未实现 | `US-11` | -| `G-REF-DATA` | 静态参考数据没有处理，当前按「合法但不支持」跳过并回填；参考数据表与 admin-api 直读未落地 | `US-13`；`US-03` | +| `G-FLOP-SEMANTICS` | 动态报文语义与 `US-05` 的差距未闭合 | `US-05` | +| `G-FLOP-UNMAPPED` | [XSD](legacy/unisysaodbsis.xsd)「FLOP 元素」字段映射缺口未闭合 | `US-05` | +| `G-MAFL` | 主航班共享列表未交付 | `US-06` AC2；`C-5` | +| `G-SRVT-VIPF` | `SRVT`、`VIPF` 持久化明细未交付 | `US-05` | +| `G-SCAN-PREDICATE` | 按「处理时间为空」读取未交付 | `US-01`；`INV-1` | +| `G-REDIS-PROJECTION` | Redis 投影写/移除未交付 | `US-05`、`US-06`、`US-07`、`US-12` | +| `G-SCHD-SNAPSHOT` | 日计划快照删除/清空/分批未交付 | `INV-7`；`INV-3`；`INV-9` | +| `G-RESP-GUARD` | `SCHD-RESP` 过期判断未交付 | `US-07` | +| `G-PROC-CLEANUP` | 处理记录到期清理未交付 | `US-11` | +| `G-REF-DATA` | 静态参考数据处理与 admin-api 直读未交付 | `US-13`；`US-03` | ## 8. 验证映射 @@ -171,30 +170,26 @@ | INV-1 | `US-01` AC1/AC2/AC4 | 扫描重来与重启后登记数不变、行不丢；同一编号重复出现时处理记录数不增加 | | INV-1、C-7 | `US-02` AC1～AC5 | 兼容入口接受三种媒体类型、默认 UTF-8；空报文、超上限、非法 XML 不落信并返回错误，解析禁用外部实体与外部资源；成功返回编号且只表示落信；内网来源由网络层配置核对；写入的行与上游投递同路径被发现、登记 | | CLM-2（升序） | `US-01` AC3、`US-03` AC1 | 按编号升序处理；队头未完成时后面的消息不被处理 | -| US-03 AC2/AC5 | `US-03` AC2/AC5 | 死信与跳过留档且无业务副作用；错误在对应处理记录上可查 | -| US-03 AC3 | `US-03` AC3 | 失败回滚后消息仍在未完成；已提交结果不被写信箱处理时间或发 Kafka 失败回滚 | | INV-2 | `US-10` AC1/AC2 | 终态后才回填；重启后继续，写不上的有记录与告警 | | C-9 | `US-08` AC1/AC2/AC3 | `msg` 单条变更、`schd` 批量；失败重试后仍能投出；一直失败的记录保留可查并告警；`msg` 同一 `FLID` 按发送顺序保序（`CLM-3`）；同一条可能多发（`C-9`） | | INV-5 | 架构「数据归属与一致性」 | 航班当前态的权威写入只在自有 PG | | INV-6 | implementation.md「权威模型」 | `FLID` 唯一 | -| US-04 AC2 | `US-04` AC2 | 未携带的字段保持原值 | | INV-7 | `US-07` AC2/AC3 | 缺席的航班在 PG 标为已删除并从 Redis 投影移除；未携带的字段被清空 | +| US-04（ADFT 更新） | `US-04` AC2 | 未携带的字段保持原值 | | INV-3 | `US-03` AC4、`US-05` AC4、`US-06` AC1 | 投影写失败时，没有终态与回填意图落库；处理完成前事件不可投递 | -| US-14 AC4 | `US-14` AC4 | 历史清理跳过正在被消息处理的航班 | | 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` 闭合前无法验证 | +| CLM-1（幂等收敛） | `US-03` AC2/AC3/AC5 | 死信与跳过留档且无业务副作用；错误在对应处理记录上可查；失败回滚后消息仍在未完成；已提交结果不被写信箱处理时间或发 Kafka 失败回滚；同一消息不产生两次效果须等 `Q3`、`G-FLOP-IDEMPOTENT`、`G-FLOP-SEMANTICS` 闭合 | | INV-8 | `US-06` AC1 | 航班标记删除后从投影移除；移除失败时下轮重做 | -| US-14、D1 | `US-14` AC3 | 历史写入成功才删实时数据；删除事件在实时数据删除前登记（`D1`） | -| US-06 AC2 | `US-06` AC2 | 删共享联动主航班；删主航班级联删共享 | +| US-14、D1 | `US-14` AC3/AC4 | 历史写入成功才删实时数据；删除事件在实时数据删除前登记（`D1`）；清理跳过正在被消息处理的航班 | +| C-5 | `US-06` AC2 | 删共享联动主航班；删主航班级联删共享 | | INV-10 | `US-05` AC4、`US-06` AC1 | 投影写失败的消息下轮仍被处理 | | INV-11 | `US-12` AC1/AC2 | 返回全部非共享航班，且与 Redis 一致；Redis 故障时返回错误 | -| US-11 | `US-11` AC1/AC2 | 未完成的记录不被删除 | -| US-13 | `US-13` AC1～AC4 | 全量整体替换、增删改逐条；空值是「没有值」不是删除；一类校验失败只停该类；参考数据落独立表供 admin-api 只读（`C-10`） | -| US-10 AC2 | `US-10` AC2 | 写失败重试与告警可观测 | -| CLM-4（止于落信） | `US-09` AC1～AC3 | 出站请求写入 `COUTMSGS` | -| CLM-5（不承诺完成时限） | — | 需求未定完成时限；现场一般为即时处理 | -| CLM-6（容量） | — | 现场量级暂无；有数据后再估 | +| G-PROC-CLEANUP（未完成不删） | `US-11` AC1/AC2 | 未完成的记录不被删除 | +| C-10 | `US-13` AC1～AC4 | 全量整体替换、增删改逐条；空值是「没有值」不是删除；一类校验失败只停该类；参考数据落独立表组供 admin-api 只读 | +| CLM-4（止于落信） | `US-09` AC1～AC3 | 出站请求写入 `COUTMSGS`；接口触发先登记，在途结案后才落信（`C-8`） | +| CLM-5（不承诺完成时限） | — | 需求未定完成时限 | +| CLM-6（容量） | — | 需求未给容量数据 | | OPS-4（切换与回退） | `OPS-4` | 回退演练：回填了结后切回，旧系统不重处理已产生业务效果的消息；在途窗口处置见 `Q18` | | CLM-7（启动拒绝） | `OPS-1` | 配置错误启动失败测试可验收 | | PRE-1（测试隔离） | `OPS-3` | 测试环境配置核对：独立的数据库、Redis 与 Kafka 主题，不连接生产信箱 |