windy/msgexchange-v2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(acm2-75): align static reference data flow

Browse Source
This commit is contained in:
windyboy
2026-09-14 08:28:47 +08:00
parent 5b7938ac4b
commit 0fbdf381b2
6 changed files with 88 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+4 -3
View File
@@ -1,7 +1,7 @@
# msgexchange-v2（机场上游报文处理中间件）
**系统角色**：消费 CIIMS/AODB 等上游经共享 MySQL 信箱（`CMINMSGS`）投递的 XML 报文，
解析处理后维护自有 PostgreSQL 航班当前态并向 Kafka / 出站信箱投递——**中间件**，非报文源系统。
解析处理后维护业务数据库中的航班当前态与静态参考数据，并向 Kafka / 出站信箱投递——**独立消息网关**，非报文源系统。admin-api 是数据库的下游读取方，本网关不调用 admin-api。
现行设计依据是 [设计文档入口](docs/README.md) 的六份文档；早期方案 ACMA-8 / ACMA-6 只作历史记录，
不再作为设计或实现依据（自有 PostgreSQL 维护内部状态，共享 MySQL 仅作信箱边界）。
@@ -18,8 +18,9 @@
|---|---|---|
| **入站（主路径）** | JDBC 轮询共享 `CMINMSGS` | 上游经 CIIMS 等**外部系统**写信箱；本系统按轮询间隔读取水位之后的记录（`ID > W`，**不以处理标记为谓词**）→ 自有 PG 入队（`InboxPoller`） |
| **入站（compat）** | HTTP `POST /cminmsgs/send` | 手工注入/影子对拍；写信箱 + PG 入队，**非**生产主拓扑 |
| **处理** | 主泵 FIFO 管道 | 解码 → identity → Handler 决策 → PostgreSQL 航班当前态 |
| **处理** | 主泵 FIFO 管道 | 解码 → identity → Handler 决策 → PostgreSQL 航班当前态 / 静态参考数据 |
| **出站** | Kafka + `COUTMSGS` | 向下游推送 msg/schd；请求类报文写出站信箱 |
| **数据消费** | admin-api 只读数据库 | 从本网关处理后的 PostgreSQL（或通过适配验证的 Oracle）读取；不形成反向依赖 |
与 SIS / legacy 一致：本系统**不**替代 CIIMS 落信，**不**生成原始 AODB 业务报文。
@@ -136,7 +137,7 @@ MICRONAUT_ENVIRONMENTS=dev ./gradlew run # dev stub 冒烟：内存 stub，无
- [architecture.md](docs/architecture.md)：系统边界、模块职责、存储归属、总体流程与 `D1`–`D4` 决策。
- [requirements.md](docs/requirements.md)：阶段范围与非目标、`US-xx` / `OPS-x` 验收目标、需求覆盖与依赖。
- [specification.md](docs/specification.md)：术语、契约 `C-x`、前提 `PRE-x`、不变量 `INV-x`、声明边界 `CLM-x`、待确认 `Q`、已知偏差 `G`、验证映射。
- [implementation.md](docs/implementation.md)：管道机制与航班域——数据模型、状态机、事务、投递、作业与恢复，航班权威模型与合并语义。
- [implementation.md](docs/implementation.md)：管道机制、航班域与静态参考数据——数据模型、状态机、事务、投递、作业、恢复及合并语义。
- [reference.md](docs/reference.md)：参数 `PARAM:<key>`、指标与健康、模块与代码入口、错误分类。
- [legacy/](docs/legacy/)：外部协议与旧系统基线（`SIS_AODB_RMS-V0.1.md` 为消息结构唯一事实源、`unisysaodbsis.xsd`、legacy 行为对拍基线、历史决策记录）。
docs/README.md
+3 -3
View File
@@ -10,7 +10,7 @@
| [requirements.md](requirements.md) | 阶段范围与非目标、`US-xx` / `OPS-x` 验收目标、需求覆盖与依赖。 |
| [architecture.md](architecture.md) | 系统边界、模块职责、存储归属、总体流程与 `D1`–`D4` 决策。 |
| [specification.md](specification.md) | 术语、外部契约 `C-x`、前提 `PRE-x`、不变量 `INV-x`、声明边界 `CLM-x`、待确认 `Qn`、当前已知偏差 `G-NAME`、验证映射。 |
| [implementation.md](implementation.md) | 数据模型、状态机、管道机制、事务、投递、作业与恢复；航班域权威模型与合并语义。 |
| [implementation.md](implementation.md) | 数据模型、状态机、管道机制、事务、投递、作业与恢复；航班域与静态参考数据的权威模型和合并语义。 |
| [reference.md](reference.md) | 参数 `PARAM:<key>`、指标与健康、模块与代码入口、错误分类。 |
| [legacy/](legacy/) | 外部协议与旧系统基线：现役行为对拍、[SIS 规范](legacy/SIS_AODB_RMS-V0.1.md)、[XSD](legacy/unisysaodbsis.xsd)、[历史决策记录](legacy/decision-flight-state-history.md)。外部协议事实（报文结构、字段语义、上游行为）以 SIS/XSD 为准；legacy 现役行为只是基线，已知缺陷不作依据。 |
@@ -18,7 +18,7 @@
| 你是谁 | 从哪读起 |
|---|---|
| 新开发者 | [specification.md](specification.md)（前提 / 不变量 / 声明边界）→ [implementation.md](implementation.md)（机制与航班域）→ [reference.md](reference.md)（参数 / 指标 / 代码入口） |
| 新开发者 | [specification.md](specification.md)（前提 / 不变量 / 声明边界）→ [implementation.md](implementation.md)（机制、航班域与静态参考数据）→ [reference.md](reference.md)（参数 / 指标 / 代码入口） |
| 库方 / 上游接口人 | [specification.md](specification.md)（`C-x` 与 `Q`） |
| 值班主任 / 运维 | [reference.md](reference.md)（参数与指标）→ [specification.md](specification.md)（哪些主张当前不可声明）。执行规程在上线/切流前另立（`docs/runbooks/`），设计阶段只保留前置条件与红线 |
| 评审 / PR 作者 | [specification.md](specification.md) + 本文「维护清单」 |
@@ -35,7 +35,7 @@
| 消费权排他、ID 不复位、报文不可变、时钟、单实例 | specification.md「前提」 | 其他文档只引 `PRE-x` |
| 航班身份、合并语义、`STATE_VERSION`、`OPERATION_DAY` | implementation.md「航班域」 | 其余文档只引域规则与 `INV-x` |
| 航班动态逐类语义与空标签规则（FLOP） | implementation.md「动态运行事件」 | specification.md 记 `Q8` 与 `G-*`；requirements.md 写验收口径 |
| 参考数据类别、结构与资源状态 | implementation.md「静态参考数据」 | requirements.md 写取数与刷新验收；参数在 reference.md |
| SIS 消息中的参考数据类别、结构与资源状态 | implementation.md「静态参考数据」 | requirements.md 写取数与刷新验收；admin-api 只从处理后的业务数据库读取 |
| 对外术语（落信 / 入站 / 库方 / 处理标记） | specification.md「术语」 | — |
| 管道内部术语（`W` / 队头 / 终态 / 回填意图） | implementation.md「术语与持久化记录」 | — |
docs/architecture.md
+9 -8
View File
@@ -3,13 +3,13 @@
## 1. 系统定位与范围
msgexchange-v2 是机场 OMMS 的上游报文处理中间件，用于替换旧版 `msgexchange-api`。
它读取 CIIMS、AODB 等系统写入共享 MySQL 信箱的 XML 报文，按顺序更新航班动态，再将结果提供给下游。
它读取 CIIMS、AODB 等系统写入共享 MySQL 信箱的 XML 报文，按顺序更新航班动态与静态参考数据，再将结果提供给下游。静态参考数据由 SIS 消息获得，是本版本的主要新增能力之一。
本系统负责**收报、解析、状态更新和结果投递**，不生成上游业务报文；其余非目标见 [requirements.md](requirements.md)「范围与非目标」。
本系统负责**收报、解析、状态更新和结果投递**，不生成上游业务报文；admin-api 是处理结果的下游数据库读取方，本网关不调用 admin-api。其余非目标见 [requirements.md](requirements.md)「范围与非目标」。
- **主要入口**：轮询共享 MySQL 的 `CMINMSGS`。
- **兼容入口**：`POST /cminmsgs/send`，供现役兼容、手工工具和对拍使用；写入信箱后返回记录 ID，不是生产收报主路径。
- **输出**：Kafka 的 `msg` / `schd` 消息、共享 MySQL 的 `COUTMSGS` 出站信箱，以及查询 HTTP 接口；不直接推送前端。
- **输出**：Kafka 的 `msg` / `schd` 消息、共享 MySQL 的 `COUTMSGS` 出站信箱、供 admin-api 只读的业务数据库结果，以及查询 HTTP 接口；不直接推送前端。
- **当前范围（阶段 A）**：航班当前态落自有 PostgreSQL（`FLIGHT_SCHD` + 资源明细表 + `FLIGHT_ROUTE_POINT`，权威口径见 [implementation.md](implementation.md)「航班域」）。无 Redis 依赖；ES 历史投影属阶段 B。
现场供库时目标为 Oracle 11g，否则自建 PostgreSQL；Oracle 适配必须通过方言与集成验证后才能作为运行时选项。
@@ -29,16 +29,17 @@ CIIMS / AODB 等上游
│ ingress：发现报文 → PostgreSQL 持久化入队 │
│ │ │
│ processing：取 FIFO 队头 → 解析 / 去重 → 处理器决策 │
│ └─ PG 单事务：航班变更 + 终态 + 待发事件│
│ └─ PG 单事务：领域变更 + 终态 + 待发事件│
│ │
│ jobs：独立维护线程（回填补偿 / 历史归档 / 留痕清理） │
│ delivery：读取 PG 待发事件 → 投递 / 重试 │
└─────────────────────────┬──────────────────────────────┘
├─ Kafka：msg / schd
└─ 共享 MySQL：COUTMSGS
├─ 共享 MySQL：COUTMSGS
└─ 业务数据库 ──只读──▶ admin-api
处理结果提交后，再回填 CMINMSGS 的处理标记；失败需补偿。
查询接口读取航班动态，不参与状态写入。
查询接口与 admin-api 读取处理后的业务数据，不参与状态写入，也不向本网关提供参考数据。
```
收报、处理、投递与维护作业各使用独立线程，不占用 HTTP 事件循环。**航班当前态的写入只发生在持有 `PIPELINE_LOCK` 的事务内**，由主泵串行驱动。
@@ -51,7 +52,7 @@ CIIMS / AODB 等上游
|---|---|
| `ingress` | 轮询信箱、持久化入队及兼容 HTTP 写入；不解析业务报文。 |
| `codec` | XML 解码，区分非法报文与可修复的解码失败。 |
| `processing` | FIFO 调度、业务身份绑定与去重、领域决策与落库（SCHD/FLOP/FDEL/ADFT）；决策、事务与回填的职责边界见 [implementation.md](implementation.md)「消息、身份与决策」与 `INV-17`。 |
| `processing` | FIFO 调度、业务身份绑定与去重、领域决策与落库（SCHD/FLOP/FDEL/ADFT/静态参考数据）；决策、事务与回填的职责边界见 [implementation.md](implementation.md)「消息、身份与决策」与 `INV-17`。 |
| `delivery` | 消费待发事件，负责按目标保序、`schd` 聚合、投递和失败重试。 |
| `jobs` | 回填补偿扫描、航班历史清理与留痕保留期清理；独立 job 线程执行，不参与 FIFO（与主泵的互斥见 `INV-18`）。 |
| `domain` / `config` | 领域状态、事件和决策模型，以及运行参数。 |
@@ -81,7 +82,7 @@ CIIMS / AODB 等上游
| 存储 | 承载内容 | 职责说明 |
|---|---|---|
| 自有 PostgreSQL | 单行锁 `PIPELINE_LOCK`、处理状态与回填事实 `PROC_STATE`、消费水位 `INBOX_CURSOR`、待发事件 `MSG_EVENT`、请求跟踪 `REQ_TRACK`、航班当前态 `FLIGHT_SCHD` + 资源明细表 + `FLIGHT_ROUTE_POINT`、留痕 `SCHD_SNAP_LOG` | 本系统唯一业务数据库。消息处理、状态推进、处理终态、回填意图与待发事件在单事务内原子提交；本地事务只在此库。记录级定义见 [implementation.md](implementation.md)「持久化记录」。 |
| 自有 PostgreSQL | 单行锁 `PIPELINE_LOCK`、处理状态与回填事实 `PROC_STATE`、消费水位 `INBOX_CURSOR`、待发事件 `MSG_EVENT`、请求跟踪 `REQ_TRACK`、航班当前态 `FLIGHT_SCHD` + 资源明细表 + `FLIGHT_ROUTE_POINT`、静态参考数据有效视图（逻辑模型 `REF_MASTER`）、留痕 `SCHD_SNAP_LOG` | 本系统唯一业务数据库。消息处理、状态推进、处理终态、回填意图与待发事件在单事务内原子提交；本地事务只在此库。记录级定义见 [implementation.md](implementation.md)「持久化记录」。 |
| 共享 MySQL | `CMINMSGS` 入站信箱、`COUTMSGS` 出站信箱 | 外部系统所有。本系统仅执行约定的信箱读写与处理标记回填，不建表、不迁移 schema、不写历史表；由库方按 `Q9` 执行的清除与历史归档见 [specification.md](specification.md)「契约」。 |
**不使用跨库事务。** PG 事务只能保证「处理结果与待发事件一起提交」（`INV-17`），不能覆盖 MySQL 回填或 Kafka 发送等外部副作用。跨存储依靠幂等、重试和持久化补偿恢复；各中断位置的判定与恢复动作见 [implementation.md](implementation.md)「中断恢复」。
docs/implementation.md
+29 -29
View File
@@ -4,7 +4,7 @@
- **处理管道**章：记录模型、状态机、收报与水位、主泵与事务边界、回填、快照与请求、投递、失败恢复与维护作业；
- **航班域**章：航班当前态的权威模型、合并与写入语义、删除与重建；
- **静态参考数据**章：主数据类别与编码、`REF_MASTER` 结构与合并语义、资源状态与机位/登机桥映射。
- **静态参考数据**章：SIS 消息中的主数据类别与编码、`REF_MASTER` 结构与合并语义、资源状态，以及 admin-api 的下游读取边界。
正文描述**目标设计**，不标注交付状态：可声明性见 [specification.md](specification.md)「声明边界」与「当前已知偏差」，进度在 Plane（ACM2）。契约与不变量只引稳定 ID；参数取值只引 `PARAM:<完整键>`（见 [reference.md](reference.md)）。
@@ -28,7 +28,7 @@
| `PROC_STATE` | 入站消息的处理状态、身份、尝试次数、错误原因与回填事实 | `MSG_ID = CMINMSGS_ID` 主键防重复入队；`IDENTITY_KEY` 唯一约束防业务重复；按最小未完成 `MSG_ID` 取队头；`BACKFILL_NEXT_AT` 非空 = 还欠一次回填，`BACKFILL_AT` 非空 = 标记已确认，`BACKFILL_ABANDONED_AT/REASON` 非空 = 已停止自动重试（**不等于**标记已确认）；`RECEIVED_AT` 复制自信箱接收时间、**可能为 NULL**、仅用于对账与展示；`ENQUEUED_AT` 是本地入队时间、非空、是超期判据的唯一依据；归档后的去重影子行置 `STATE='ARCHIVED'`、只保留 `IDENTITY_KEY` 与 `MSG_ID`，不占队头、不触发回填、不参与积压聚合（`G-PROC-HST`）。 |
| `MSG_EVENT` | 等待投递的事件（outbox） | `EVENT_ID` 对 `KAFKA:msg` 是稳定事件身份并决定投递顺序；对 `KAFKA:schd` 是每次接受 upsert 时替换的写代次。`TARGET` 区分 `KAFKA:msg` / `KAFKA:schd`；`PARTITION_KEY` 当前取 `FLID`（`Q4` 定案前为假定，见 `C-29`）；`EVENT_TYPE` 区分 UPSERT 与 TOMBSTONE。`KAFKA:schd` 按 `FLID` 单行 upsert，只保留最新 `STATE_VERSION`；`SENT_AT` 在投递确认的同一条 UPDATE 内写入，是保留期判定的唯一基准。 |
| `REQ_TRACK` | 上游请求及应答关联 | 状态 `PENDING / SENT / DONE / EXPIRED`；保存请求类型、覆盖运营日、发送方、出站信箱 ID 与发送/完成时间；**「同类只允许一个开放请求」的唯一键 = `(请求类型, 覆盖运营日, 发送方)`，且仅对开放状态生效**。 |
| `REF_MASTER` | 静态参考数据与资源状态（目标表） | `(RTYPE, RKEY)` 唯一；`RTYPE` 类别、合并语义与资源状态见「静态参考数据」；取数路径见 [requirements.md](requirements.md) `US-13`/`US-14`。 |
| `REF_MASTER` | SIS 消息提供的静态参考数据与资源状态（目标表） | `(RTYPE, RKEY)` 唯一；`RTYPE` 类别、合并语义与资源状态见「静态参考数据」；取数路径见 [requirements.md](requirements.md) `US-13`。 |
| `FLIGHT_SCHD` | 航班标量及单值异常字段 | `FLID` 主键；`OPERATION_DAY` 一经确定不可变；版本与最近消息 ID 用于追踪。变长集合存于资源明细表与 `FLIGHT_ROUTE_POINT`，规则见「航班域」。 |
| `INBOX_CURSOR` | 消费水位 `W`、空洞计时 `holeSince`、播种事实 `SEEDED_AT` | 单行游标；`W` 只随新 ID 成功入队推进，遇空洞即停；`HOLE_SINCE` 持久化空洞观测时刻，进程重启不丢计时。`SEEDED_AT IS NULL` **不等于**从未消费（已有库新增列后同样为 NULL）。 |
| `SCHD_SNAP_LOG` | 日计划处理留痕 | 只追加、可重建，不参与状态决策；保留期见 [reference.md](reference.md)。 |
@@ -44,9 +44,9 @@
**身份绑定是独立的幂等单语句**（`WHERE IDENTITY_KEY IS NULL`），不参与业务事务。它的前提是「报文不可变」（`PRE-7`）：同一身份的重发不会被比对内容，若上游改发正文会被判为重复并跳过（`Q15`）。
分派与落库由 `MessageProcessor` 协调：按 `MsgKind` 把已绑定身份的队头消息交给对应事务协调器（DNLD/RESP → `ScheduleProcessor`，ADFT → `AdftProcessor`，FLOP → `FlopProcessor`，FDEL → `FdelProcessor`，其余 → `FAILED(UNSUPPORTED)`）。这些处理器在 `PIPELINE_LOCK` 事务内读取当前完整态，调用纯领域决策逻辑得到下一完整态与待发事件，再统一落库并登记回填意图；它们不直接触碰 Kafka。领域决策逻辑不执行 I/O。
分派与落库由 `MessageProcessor` 协调：按 `MsgKind` 把已绑定身份的队头消息交给对应事务协调器（SCHD-DNLD/RESP → `ScheduleProcessor`，ADFT → `AdftProcessor`，FLOP → `FlopProcessor`，FDEL → `FdelProcessor`，`SIS:3.1`～`SIS:3.14` 的静态参考数据消息 → `ReferenceDataProcessor`，其余 → `FAILED(UNSUPPORTED)`）。这些处理器在 `PIPELINE_LOCK` 事务内读取当前完整态，调用纯领域决策逻辑得到下一完整态与待发事件，再统一落库并登记回填意图；它们不直接触碰 Kafka。领域决策逻辑不执行 I/O。
忽略规则：解码后、分派前按大小写不敏感的 `TYPE-STYP` / `TYPE-*` 匹配忽略清单（基线 `LDM` / `REGN` / `RSTA` / `EROR`，不混用 `ERROR`），命中转 `SKIPPED` 并记录 `ignored:<rule>`；忽略报文照常绑定身份，但不更新航班、不创建业务通知（`US-04`）。
忽略规则：解码后、分派前按大小写不敏感的 `TYPE-STYP` / `TYPE-*` 匹配忽略清单（基线 `LDM` / `EROR`，不混用 `ERROR`），命中转 `SKIPPED` 并记录 `ignored:<rule>`；忽略报文照常绑定身份，但不更新航班、不创建业务通知（`US-04`）。`REGN` / `RSTA` 是静态参考数据消息，必须分派给 `US-13`，不得忽略。
## 3. 状态与错误分类
@@ -417,8 +417,8 @@ PENDING → SENT → DONE
| `CHDT` | `CHNO`、`CHUT`、`CCLS`、`PCBT`、`PCET`、`CBTM`、`CETM`、`CTYP` | 99 | `SIS:3.26` |
| `PSDT` | `PSNO`、`PSST`、`STST`、`STET` | 9 | `SIS:3.38` |
| `CHOT` | `CSNO`、`CHTM`、`CHID`、`CHST` | 99 | `SIS:3.22` |
| `DELY` | `CODE`、`STRT`、`DURA`、文本 | — | `XSD` `FLOP` 段 |
| `ABTM` | `ASNO`、`ABDG`、`ABOP`、`AOTM` | 99 | `XSD` `FLOP` 段 |
| `DELY` | `CODE`、`STRT`、`DURA`、文本 | — | [XSD](legacy/unisysaodbsis.xsd)「FLOP 元素」 |
| `ABTM` | `ASNO`、`ABDG`、`ABOP`、`AOTM` | 99 | [XSD](legacy/unisysaodbsis.xsd)「FLOP 元素」 |
| `ROUT` / `ERUT` | `RTNO`、`APCD`、`SCAT`、`SCDT` | 6 / 7（`ROUT` 只取 4） | `SIS:3.40` |
| `SRVT` | `OPER`、`SRTC`、`SRQT`、`SRST`、`SRET`、`SRPR`、`SANR`、`SARR` | 无界 | `G-SRVT-VIPF` |
| `VIPF` | `OPER`、`VPCD`、`VFES`、`VIPT/OPER`、`VIPT/VSCD`、`VIPT/VTQY`、`VIPT/VTST`、`VIPT/VTET` | 无界 | `G-SRVT-VIPF` |
@@ -429,7 +429,7 @@ PENDING → SENT → DONE
- 相同资源号不代表同一条分配，禁止按资源号去重。
- 每次持久化完整航班状态时，明细表按该 `FLID` 先删后插，以完整合并结果为准（`INV-14`）。
- ROUT 与 ERUT 是两类独立集合，不能因相同序号覆盖彼此。
- `CHDT` 的类字段在 SIS 正文写作 `CCLS`/`CTYP`、在 `XSD` 写作 `CHCLS`/`CHTYP`，**以 `XSD` 为准**。
- `CHDT` 的类字段固定为 `CCLS`/`CTYP`；当前 wire DTO 与持久化列误写成 `CHCLS`/`CHTYP`，见 `G-FLOP-UNMAPPED`。
- 主/共享关系以主表的 `MAID` 为事实来源：`MAID` 是共享航班指向主航班 `FLID` 的引用（非共享航班为 `NULL`）；`MAFL` 只在读取和事件投影时从子航班事实派生，不按入站标量解析或保存。
### 11.4 主/共享投影（`MAFL`）
@@ -459,13 +459,15 @@ SCHD DNLD/RESP 在整包校验通过后，逐条将报文携带的航班写入
### 12.2 动态运行事件（FLOP）
FLOP 只修改报文表达的字段或集合，其余状态保持不变；目标形态与合并规则见「字段与集合」。逐类语义**不靠处理器分支表达，而靠 SIS 的逐类字段表与空标签规则**：下表每一行都必须有一条回归用例钉住「输入 → 目标字段/集合 → 空标签结果」，不能只因报文已被路由就推定语义完整（`INV-20`）。
FLOP 只修改报文表达的字段或集合，其余状态保持不变；目标形态与合并规则见「字段与集合」。`STYP` 必须命中下表白名单，未知值转 `FAILED(UNSUPPORTED)`，不得进入通用合并。除表内方向拒绝项外，已确认的动态更新在同一事务推进 `STATE_VERSION`、登记 `KAFKA:msg` 与 `KAFKA:schd`、提交处理终态与回填意图；同一消息重试不得重复产生业务效果（`INV-17`、`INV-20`）。
逐类语义以 SIS 的字段表、空标签规则与 Processing Exceptions 为准；下表每一行都必须有一条回归用例钉住「输入与前态 → 目标状态 → 终态与事件」。
| SIS | STYP | 目标 | 空标签 / 缺失语义 |
|---|---|---|---|
| `SIS:3.19` | `ACFT` | `ACFT` 标量 | 字段为 M，未写明空语义 |
| `SIS:3.20` | `ACTT` | `ACTT` 标量 | 空 = 清除已有实际时间 |
| `SIS:3.21` | `BOTM` | `BOTM` 标量 | 空 = 清除登机时间 |
| `SIS:3.21` | `BOTM` | `BOTM` 标量；非空时设置登机状态 | 空 = 清除登机时间并重置登机状态 |
| `SIS:3.22` | `CHOT` | `CHOT` 集合 | 集合按完整结果替换；元素内 `CHTM` 空 = 删除该轮挡时间 |
| `SIS:3.23` | `FLTY` | `FLTY` 标量 | 字段为 M，未写明空语义 |
| `SIS:3.24` | `CKDT` | `CKDT` 集合 | 空 `<CKDT CKNO="0">` = 现无柜台分配；**AODB 方向报文必须拒绝** |
@@ -479,12 +481,12 @@ FLOP 只修改报文表达的字段或集合，其余状态保持不变；目标
| `SIS:3.32` | `FLIN` | `FLIN` 标量 | 字段为 M，未写明空语义 |
| `SIS:3.33` | `FRET` | `FRET`（`REID`），当前未映射（`G-FLOP-UNMAPPED`） | 空 = 清除返航标志 |
| `SIS:3.34` | `GTDT` | `GTDT` 集合 | 空 `<GTDT GTNO="0">` = 现无登机门分配；`GOTM`/`GCTM` 缺失 = 未分配开放/关闭时间；**AODB 方向报文必须拒绝** |
| `SIS:3.35` | `LACL` | `LACL` 标量 | 空 = 清除最后通知时间 |
| `SIS:3.35` | `LACL` | `LACL` 标量；非空时设置最后通知状态 | 空 = 清除最后通知时间并重置最后通知状态 |
| `SIS:3.36` | `MAXP` | `MAXP` 标量 | 空 = 删除最大载客数 |
| `SIS:3.37` | `HNAG` | `FHAG`/`PHAG`/`MHAG` 标量 | `FHAG` 空 = 删除该代理；`MHAG` 可缺席 |
| `SIS:3.38` | `PSDT` | `PSDT` 集合 | 空 `<PSDT PSNO="0">` = 现无机位分配；**AODB 方向报文必须拒绝** |
| `SIS:3.39` | `RENO` | `RENO` 标量 | 空 = 清除注册号 |
| `SIS:3.40` | `ROUT` | `ROUT` 集合 | `SCAT`/`SCDT` 分别对起点/终点缺席；只保留 4 条（离港取前 4、到港取后 4）且忽略 `SCAT`/`SCDT` |
| `SIS:3.40` | `ROUT` | `ROUT` 集合 | `SCAT`/`SCDT` 分别对起点/终点缺席；RMS 只保留 4 条（离港取前 4、到港取后 4）且不保存 `SCAT`/`SCDT` |
| `SIS:3.41` | `TAOP` | `TAOP`/`TAFL`/`TAID` 标量 | 任一为空 = 该到达航班的经停连接断开 |
| `SIS:3.42` | `TRML` | `TRML` 标量 | 空 = 删除航站楼 |
| `SIS:3.43` | `VIPP` | `VIPP`/`VIPR` 标量 | 空 = 删除；SIS 另要求 RMS 忽略 `VIPP`（忽略事件还是忽略字段，SIS 未写明，按 `Q8` 对拍确认） |
@@ -495,9 +497,9 @@ FLOP 只修改报文表达的字段或集合，其余状态保持不变；目标
**SIS 定义但 legacy 无处理器**：`CHDT`、`FINT`、`MAXP`。
**未映射字段**：`XSD` `FLOP` 段中尚未解码的字段见 `G-FLOP-UNMAPPED`；其中 `FRET`、`FDIV`、`BDPB` 在 legacy 有对应处理，逐项必须在 `Q8` 对拍时定案（补齐映射或明确声明忽略），不得静默丢弃。
**未映射字段**：[XSD](legacy/unisysaodbsis.xsd)「FLOP 元素」中尚未解码或错误映射的字段见 `G-FLOP-UNMAPPED`；其中 `FRET`、`FDIV`、`BDPB` 在 legacy 有对应处理，逐项必须在 `Q8` 对拍时定案（补齐映射或明确声明忽略），不得静默丢弃。
动态事件保留既有 `OPERATION_DAY`，也不基于接收时间重新推导它。航班不存在或已删除时按幂等成功处理——动态事件不创建航班（创建只发生在日计划与异常航班）。
动态事件保留既有 `OPERATION_DAY`，也不基于接收时间重新推导它。除 FDEL 外，SIS 未规定目标航班不存在或已删除时的结果；逐类终态必须经 `Q8` 定案，不能统一推定为成功。当前实现的白名单、`ROUT`、BOTM/LACL 状态与已删除航班行为偏差见 `G-FLOP-SEMANTICS`。
### 12.3 删除与重建
@@ -525,18 +527,15 @@ ADFT 的字段缺失语义尚待上游确认。在确认前采用保守的 Set-o
## 13. 静态参考数据
本章定义航班基础数据（参考主数据）的目标形态与合并语义。字段的值域、长度与业务含义以 [SIS 接口规范](legacy/SIS_AODB_RMS-V0.1.md) 对应节为准，本章只定义类别、结构与落库口径；取数路径与刷新责任见 [requirements.md](requirements.md) `US-13`/`US-14`。
本章定义由入站 SIS 消息获得的航班基础数据（静态参考数据）的目标形态与合并语义。字段的值域、长度与业务含义以 [SIS 接口规范](legacy/SIS_AODB_RMS-V0.1.md) 对应节为准，本章只定义类别、结构与落库口径；取数路径与刷新责任见 [requirements.md](requirements.md) `US-13`。**静态参考数据不得从 admin-api 拉取、补全或合并；admin-api 只读取本网关已经提交到业务数据库的数据。**
### 13.1 来源
| 来源 | 权威节 | 形态 |
|---|---|---|
| AODB 参考数据事件 | `SIS:3.1`～`SIS:3.13` | `META.TYPE` 即类别码；`STYP` ∈ `DNLD` / `RESP` / `ADD` / `UPD` / `DEL` |
| AODB 资源状态事件 | `SIS:3.14` | `TYPE=RSTA`；`STYP` 只有 `DNLD` / `RESP` |
| AODB 应答参考数据请求 | `SIS:3.15` | 复用上表格式，仅 `STYP=RESP`；**没有请求 ID 或关联字段**，配对只靠子类型 |
| admin-api 本地主数据 | 见 `US-13` | 21 类，清单与字段映射待 `Q8` 确认 |
同一类别可能由两条来源同时提供，覆盖优先级见 `US-13`。
| AODB 资源状态事件 | `SIS:3.14` | `TYPE=RSTA`；`DNLD` 是单条状态更新，`RESP` 才可包含多条 |
| AODB 应答参考数据请求 | `SIS:3.15` | 复用对应类别格式且 `STYP=RESP`；**没有请求 ID 或关联字段**，以响应 `TYPE` 匹配原请求 `STYP` |
### 13.2 类别
@@ -555,20 +554,21 @@ ADFT 的字段缺失语义尚待上游确认。在确认前采用保守的 Set-o
| `CLST` | 值机柜台代码 | `CCOD` | `SIS:3.11` |
| `BLST` | 行李转盘代码 | `BCOD` | `SIS:3.12` |
| `CHLT` | 行李滑槽代码 | `CCOD` | `SIS:3.13` |
| `RSTA` | 资源状态 | `RSID`（另存资源类型 `RTYP`） | `SIS:3.14` |
| `RSTA` | 资源状态 | (`RTYP`, `RSID`) | `SIS:3.14` |
`CLST` 与 `CHLT` 复用同名标签 `CCOD`、`CNMC`、`CTML`、`CCAT`，语义不同，只能靠 `RTYPE` 区分。
### 13.3 结构与合并语义
`REF_MASTER` 一行一个 `(RTYPE, RKEY)`，字段名取 SIS 对应节的标签名，另存 `SOURCE`（`AODB` / `ADMINAPI`）、刷新批次与刷新时间。
`REF_MASTER` 是对业务暴露的有效参考数据视图，逻辑身份为 `(RTYPE, RKEY)`；普通类别的 `RKEY` 见上表，`RSTA` 的身份必须同时包含 `RTYP` 与 `RSID`。记录保存消息来源、消息批次、刷新时间与按 SIS 标签名组织的字段载荷；重复字段保留输入顺序并表示为有序数组。物理列与批次暂存方式在 `Q8` 定案，定案前不得据本节新增 DDL。
- **list 模式 = 全量**：SIS 原文为一个 XML 含该类全部记录。整批校验通过后按类整体发布，失败不暴露半批（`US-13`）。
- **incremental 模式 = 单条全字段**：报文只含被改动的一条，但该条含全部字段；按 `(RTYPE, RKEY)` 整体覆盖该行。
- **13 类参考数据**：`DNLD`/`RESP` 是类别全量，整批校验通过后原子发布；`ADD`/`UPD`/`DEL` 是单条全字段增量，按 `(RTYPE, RKEY)` 处理。全量替换只作用于消息指定的同一 `RTYPE`。
- **资源状态**：`RSTA-DNLD` 是单条状态更新，按 (`RTYP`, `RSID`) 覆盖；`RSTA-RESP` 是请求返回的多条记录。两者都不以“本包未出现”为理由删除其他资源状态。
- **删除只由 `STYP=DEL` 表达**：参考数据**没有字段级删除语义**——可选字段的空标签表示「数据不可用」，不是删除。这与航班动态的空标签语义相反，两者不得套用同一套合并规则。
- **请求配对**：参考应答统一为 `STYP=RESP`，以响应 `TYPE` 对应原 `RQRD.STYP`；`RSTA` 的请求范围还要校验 `RTYP`，不能只按 `RESP` 或消息到达时间匹配。
- `SRVT`、`VIPF` 与参考数据无关；参考数据不参与航班状态推进，也不进入 `MSG_EVENT`。
SIS 声明的上游忽略与截断口径（`SIS:3.2`/`SIS:3.4`/`SIS:3.5`/`SIS:3.6`/`SIS:3.7`/`SIS:3.8`/`SIS:3.10`/`SIS:3.11`/`SIS:3.12`）：机场代码忽略 `ANAM`/`ACTY`/`ICCD`/`BDIS`/`ATYP`/`HAUL`；机型忽略 `DESC`/`CHAP`/`MFWT`/`MTWT`/`MHTM`/`MABR`；注册号忽略 `OWID`/`MFWT`/`MTWT`；机构忽略 `ONAM`，且 `OCAT` 只保留旅客/维护/地服代理；航班类型忽略 `FDES`/`FCML`/`CTYP`；航站楼忽略 `TNAM`/`TCAT`/`TPAX`；机位忽略 `STNM`/`MABS`/`FEPU` 并把 `STGP` 截断到 8 字符；值机柜台忽略 `CTNM`/`CCAT`；转盘忽略 `BTNM`/`BCAT`；国家代码只保留第一个 `REGC`。这些字段在未确认本地用途前不进入参考数据模型，需要时由 `US-13` 增补并说明用途。
SIS 声明的上游忽略与截断口径（`SIS:3.1`/`SIS:3.2`/`SIS:3.4`/`SIS:3.5`/`SIS:3.6`/`SIS:3.7`/`SIS:3.8`/`SIS:3.10`/`SIS:3.11`/`SIS:3.12`）：国家代码忽略 `COUN` 且只保留第一个 `REGC`；机场代码忽略 `ANAM`/`ACTY`/`ICCD`/`BDIS`/`ATYP`/`HAUL`；机型忽略 `DESC`/`CHAP`/`MFWT`/`MTWT`/`MHTM`/`MABR`；注册号忽略 `OWID`/`MFWT`/`MTWT`；机构忽略 `ONAM`，且 `OCAT` 只保留旅客/维护/地服代理；航班类型忽略 `FDES`/`FCML`/`CTYP`；航站楼忽略 `TNAM`/`TCAT`/`TPAX`；机位忽略 `STNM`/`MABS`/`FEPU` 并把 `STGP` 截断到 8 字符；值机柜台忽略 `CTNM`/`CCAT`；转盘忽略 `BTNM`/`BCAT`。这些字段在未确认本地用途前不进入参考数据模型，需要时由 `US-13` 增补并说明用途。
### 13.4 资源状态
@@ -579,9 +579,9 @@ SIS 声明的上游忽略与截断口径（`SIS:3.2`/`SIS:3.4`/`SIS:3.5`/`SIS:3.
- 结束时间缺失表示**一直禁用，直到该资源收到新的状态事件**。
- 重新启用只带起始时间，不带结束时间。
### 13.5 机位与登机桥映射
### 13.5 admin-api 下游读取边界
- 机位主数据即 `SLST`（`RKEY=SCOD`），机位性质由 `REMT` 表达：`N` = 近机位（默认）、`Y` = 远机位、`A` = 停机区；所属航站楼是 `STML`。机位可用性由 `RSTA`（`RTYP=STND`）表达。
- **机位→登机桥关系没有 SIS 来源**，只有 admin-api 提供；`US-14` 的映射因此依赖 admin-api 可用性，不可用时用最后可用版本。
- 协议内的登机桥编码是 `ABTM` 元素中的 `ABDG`（`SIS:3.16`、`XSD` `OPT_BRIDGEDATA`），**不是航班主表标量**；legacy 另有一个由 admin-api 派生的航班级 `abdg`。目标形态必须在两者间二选一并写进「字段与集合」，确认前不得把派生值当成协议字段。
- `PSDT` 的「空集合」与「未携带」含义不同：前者清空本地机位、后者保留原值（`INV-14`；空集合写法见「动态运行事件」）。
- 数据方向固定为「SIS 消息 → 本网关 → 业务数据库 → admin-api」；本网关不调用 admin-api，不读取其数据库或缓存。
- admin-api 只读取已提交的航班状态与 `REF_MASTER` 有效视图，不参与消息解码、合并、批次发布或处理终态判定。
- 开发运行时使用自有 PostgreSQL；Oracle 只有通过 `Q1` 要求的方言与集成验证后才可替代，单次部署不得同时把两库作为权威。
- admin-api 的物理读取契约在 `Q8` 定案；共享 MySQL 始终只是信箱边界，不承载该读取模型。
docs/requirements.md
+32 -29
View File
@@ -5,12 +5,14 @@
- `US-01`～`US-15`（三级标题定义）、`OPS-1`～`OPS-4`（注册表定义）；
- 需求覆盖与依赖关系。
代码入口与参数取值不在本文件：前者见 [reference.md](reference.md)「模块与代码入口」，后者见其参数表。前提、不变量、契约与偏差见 [specification.md](specification.md)；机制与航班域见 [implementation.md](implementation.md)。工程纪律（工具链、测试设施、提交规范）以根 `AGENTS.md` 为唯一出处。
代码入口与参数取值不在本文件：前者见 [reference.md](reference.md)「模块与代码入口」，后者见其参数表。前提、不变量、契约与偏差见 [specification.md](specification.md)；机制、航班域与静态参考数据见 [implementation.md](implementation.md)。工程纪律（工具链、测试设施、提交规范）以根 `AGENTS.md` 为唯一出处。
## 1. 范围与非目标
**阶段 A 闭合**：`US-01`～`US-14`、`OPS-1`～`OPS-4`。
**本版本主要新增能力**：从入站 SIS 消息解析、校验并发布静态参考数据（`US-13`），供 admin-api 从处理后的业务数据库读取（`US-14`）。
**非目标**：
- 航班当前态只存自有 PG；不引入 Redis、阶段 A 的 ES 投影、新业务库、并行主泵或分布式锁。
@@ -18,6 +20,7 @@
- 生产保持单活动实例；不承诺端到端恰好一次、跨 `FLID` 顺序或未经验证的 Oracle 11g 支持。
- `US-15` 未启用前遵守 `D1`：历史写入未确认成功时航班清场删除 0 条。
- 不生成上游业务报文，不替代 CIIMS/AODB，不提供 AODB 主数据编辑能力。
- 本网关不调用 admin-api，也不从 admin-api 拉取、补全或合并任何数据；admin-api 只从本网关处理后的 PostgreSQL（或通过适配验证的 Oracle）读取。
## 2. 阶段 A 用户故事
@@ -80,27 +83,27 @@
**验收标准**
1. 解码 META 后、处理器分派前，大小写不敏感匹配 `TYPE-STYP` 或 `TYPE-*`；基线为 `LDM-* / REGN-* / RSTA-* / EROR-*`，不混用 `ERROR`。转 `SKIPPED` 前必须已完成身份绑定（`US-03`、`INV-9`），忽略报文照常绑定身份。
1. 解码 META 后、处理器分派前，大小写不敏感匹配 `TYPE-STYP` 或 `TYPE-*`；基线为 `LDM-* / EROR-*`，不混用 `ERROR`。`REGN` 与 `RSTA` 属 `US-13` 的参考数据入口，不得按忽略规则截断。转 `SKIPPED` 前必须已完成身份绑定（`US-03`、`INV-9`），忽略报文照常绑定身份。
2. 命中后转 `SKIPPED`，记录 `ignored:<rule>` 和计数；不更新航班、不创建业务通知。
3. 通过 `US-09` 保存回填意图；命中、未命中、大小写和重扫均有测试。合法忽略报文不应因 `MsgKind` 尚不能表达它而先解码失败。
**前置**：`US-03` 解码/终态接口、`US-09`。
### US-05 应用 ADFT 与 29 类 FLOP（KEEP + FIX）
### US-05 应用 ADFT 与 FLOP（KEEP + FIX）
**目标**：增量报文正确更新航班及主/共享关系，并生成符合现役语义的通知。
**验收标准**
1. 动态子类型的清单以 SIS `SIS:3.19`～`SIS:3.43` 为权威（25 类），逐类映射、空标签语义与方向约束见 [implementation.md](implementation.md)「动态运行事件」；每类必须有回归用例。legacy 的「29 类」计数与 SIS 的 25 类不是同一集合：SIS 未定义而 legacy 处理的 7 类、SIS 定义而 legacy 无处理器的 3 类，必须逐条列出并以真实报文确认（`Q8`）。校验与合并是同一套通用逻辑，逐类差异只体现在规则与用例上。未知类型可恢复失败。RESP/DNLD 不计入这批，走 `US-06`。
2. 每类固定「输入与前态 → 目标字段/集合 → 空标签结果 → 终态与事件」样例；区分字段缺失、显式清空、撤销语义（如 `CNCL` 空标签是撤销而非清除）与重复报文。「空 = 清除」只适用于 SIS 逐类写明该语义的字段，不得统一套用。清单与 golden 样例按 `Q8` 补齐，不以「已写 29 个类」替代验收。
1. 动态子类型以 SIS `SIS:3.19`～`SIS:3.43` 的 25 类为权威；逐类字段、空标签、方向与处理例外见 [implementation.md](implementation.md)「动态运行事件」。SIS 未定义但 legacy 处理的类型只作待对拍候选，按 `Q8` 定案；RESP/DNLD 走 `US-06`。
2. 每个启用子类型必须有「输入与前态 → 目标状态 → 终态与事件」golden，并覆盖字段缺失、显式清空、重复报文和不存在/已删除航班。未知子类型必须按 `UNSUPPORTED` 失败，不能进入通用合并。
3. 对按 KEEP 规则需忽略的不存在航班，以 `SUCCEEDED` 无副作用结束，并由 `US-09` 回填；ADFT 建航班等行为按各类型矩阵执行。航班当前态以自有 PG 为唯一权威，重启即恢复，不存在 Redis 全损后白名单无法找回的损坏路径。
4. 共享航班更新与删除级联语义以 [implementation.md](implementation.md)「删除与重建」为规范（共享航班通知、主航班 `MAFL` 更新、级联删除、原子变更；不出现主已删、子残留）；本条目验收实现不偏离该规范，目标不存在时幂等成功。
5. ADFT/FDEL 的值相等比较与半状态禁止规则见 [implementation.md](implementation.md)「删除与重建」。
6. PSDT 通过 `US-14` 的只读映射计算 `abdg`，处理器不直接调用 admin-api。
7. 方向、截断与未映射字段以 SIS 为准：柜台、转盘、滑槽、登机门、计划机位五类的 AODB 方向报文必须拒绝（只从日计划快照接受）；`ROUT` 只保留 4 条并忽略 `SCAT`/`SCDT`；XSD `FLOP` 段中当前未映射的字段必须显式列出并逐项定案（补齐映射或声明忽略），不得静默丢弃。
6. PSDT 只更新消息携带的机位分配；登机桥编码只按 SIS 消息中的 `ABTM.ABDG` 处理，不从 admin-api 查询或派生。
7. 方向、截断与未映射字段必须符合「动态运行事件」；当前实现偏差由 `G-FLOP-DIRECTION`、`G-FLOP-UNMAPPED` 与 `G-FLOP-SEMANTICS` 统一登记，不得静默丢弃或误处理。
**前置**：`US-03`；PSDT 另依赖 `US-14`；`Q1`、`Q8`、`Q14`。
**前置**：`US-03`；`Q1`、`Q8`、`Q14`。
### US-06 导入 RESP/DNLD 日计划快照
@@ -145,7 +148,7 @@
**验收标准**
1. 覆盖 14 类 RQRD 参考请求和 1 类 RQFD-NONE；逐类名称、编码和映射见 `Q8`，不与 admin-api 的 21 类混算。
1. 覆盖 14 类 RQRD 参考请求和 1 类 RQFD-NONE；逐类名称、编码和映射见 `Q8`。
2. 先持久化 `PENDING` 与出站意图；COUTMSGS 确认落信后关联其 ID 并标 `SENT`，不宣称对方已发送。落信成功而 PG 未确认时可恢复，不能盲目重发。
3. 同类开放请求最多一个，新请求使旧请求 `EXPIRED`，并发登记不产生两个开放请求。从确认落信的发送时间起算，超时值按 `Q5`；`PENDING`/`SENT` 均不得成为永不超时的死分支。
4. 优先按已确认的 SEQN 回显匹配；无回显的降级匹配按 `Q5` 明确风险，只接受已发送开放请求且 `DTTM ≥ SENT_AT`。统一转换为可比较的时间，不能把报文日期数字直接与 epoch 毫秒比较。
@@ -207,32 +210,32 @@
**前置**：`Q1`、`Q3`；所查询的 `US-05`/`US-06` 状态发布能力。
### US-13 刷新参考主数据
### US-13 从 SIS 消息刷新静态参考数据
**目标**：业务使用来自 AODB 事件与 admin-api 的本地参考数据，刷新失败仍有上次可用版本。
**目标**：消费 AODB 经共享信箱投递的 SIS 消息，形成业务可用的本地静态参考数据；刷新失败仍保留上次可用版本。
**验收标准**
1. 覆盖 SIS `SIS:3.1`～`SIS:3.14` 的 13 类参考数据与资源状态（类别、`RTYPE`/`RKEY` 与结构见 [implementation.md](implementation.md)「静态参考数据」），以及 admin-api 的 21 类；两条来源的清单、字段映射与覆盖优先级按 `Q8` 确认。这是独立于 `US-08` 的数据入口，不另建「参考专用第二 PG」。
2. 按 `(RTYPE,RKEY)` 幂等写 `REF_MASTER`，记录 SOURCE、刷新时间和批次；单类完整校验后发布，失败不暴露半批。
3. 一类失败不破坏其他类或该类旧版本；同类由 AODB/admin-api 都提供时明确覆盖优先级，全量刷新时明确已删除项的处理，不能仅靠 SOURCE 日志解决冲突。
4. 影子默认不主动刷新生产数据；需要参考样本时显式导入隔离副本。
5. 入站按 `STYP` 区分全量与增量：全量报文按类整体发布，增量报文按 `(RTYPE,RKEY)` 整体覆盖，删除只由 `DEL` 表达；参考数据的空标签表示「数据不可用」而非删除，不得套用航班动态的空标签合并规则。
1. 通过 `CMINMSGS` 消费 SIS `SIS:3.1`～`SIS:3.14` 的 13 类参考数据与资源状态消息；类别、`RTYPE`/`RKEY` 与结构见 [implementation.md](implementation.md)「静态参考数据」。这是独立于 `US-08` 请求入口的消息处理能力，不另建「参考专用第二 PG」。
2. 静态参考数据只能来自上述 SIS 消息，禁止从 admin-api 拉取、补全或合并；admin-api 仅作为处理结果的下游读取方。
3. 按 `(RTYPE,RKEY)` 幂等写 `REF_MASTER`，记录消息来源、刷新时间和批次；单类完整校验后发布，失败不暴露半批。
4. 一类失败不破坏其他类或该类旧版本；`DNLD`/`RESP` 的全量替换与 `ADD`/`UPD`/`DEL` 的增量合并严格按消息语义执行。
5. 影子默认不主动刷新生产数据；需要参考样本时显式导入隔离副本。
6. `SIS:3.1`～`SIS:3.13` 按 `STYP` 区分全量与增量；`RSTA` 遵守 `SIS:3.14` 的单条 `DNLD` 与多条 `RESP` 语义，不把 `DNLD` 当作全量替换。参考数据的空标签表示「数据不可用」而非删除，不得套用航班动态的空标签合并规则。
**前置**：admin-api 访问契约、`Q8`。可独立于消息处理器开发。
**前置**：`US-01`、`US-03`、`Q8`。必须复用统一的入站消息管道、身份绑定和处理终态。
### US-14 提供机位与登机桥映射
### US-14 向 admin-api 提供数据库读取结果
**目标**：PSDT 在不调用外部 HTTP 的情况下得到完整映射，正确计算 `abdg`。
**目标**：admin-api 从本网关处理后的业务数据库读取航班状态与静态参考数据，网关与 admin-api 之间不存在反向调用。
**验收标准**
1. 机位主数据以 SIS `SLST` 为权威（机位性质取 `REMT`、可用性取 `RSTA`），登机桥关系只有 admin-api 来源（`ORMS_STAND / ORMS_STAND_AIRBRIDGE`），与 `US-13` 的类别分开统计；适配器拉取、完整校验后原子发布只读缓存。
2. 近机位产生登机桥值，远机位或清空机位时为空；一机位多桥、缺失映射与共享航班规则用 golden 固定。**登机桥编码的落点必须先定案**：协议内它是 `ABTM` 元素的 `ABDG`，legacy 另派生一个航班级 `abdg`；定案前不得把派生值当成协议字段处理。
3. admin-api 不可用时使用最后可用版本；无可用版本或映射不完整时明确失败，不用空映射冒充正常清空，也不发布半批。
4. 处理器输入包含所需只读参考视图，不允许其直接 HTTP 或写缓存。
1. 数据流固定为「SIS 消息 → 本网关处理 → PostgreSQL / 经验证的 Oracle → admin-api 只读」；禁止实现 admin-api → 本网关的 HTTP、数据库或缓存取数路径。
2. admin-api 只能读取已原子提交的航班状态与静态参考数据，不得看到参考数据半批，也不得成为网关处理成功的前置条件。
3. 对 admin-api 的物理表、视图和查询契约按 `Q8` 定案；不得据本需求改动共享 MySQL schema。
**前置**：机位/桥数据契约及 `Q8`；不要求 `US-13` 全部完成。
**前置**：`US-13`、`Q1`、`Q8`。
### US-15 历史航班清场（DEFERRED，阶段 B）
@@ -261,16 +264,16 @@
| `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、SIS 25 类 FLOP、完整航班态及主/共享关系 | `INV-11`～`INV-22`、`Q8`、`Q13`、`Q14`、`Q16`、`G-FLOP-IDEMPOTENT`、`G-FLOP-DIRECTION`、`G-FLOP-UNMAPPED`、`G-MAFL`、`G-SRVT-VIPF` |
| `US-05` | ADFT、FDEL、SIS 25 类 FLOP、完整航班态及主/共享关系 | `INV-11`～`INV-22`、`Q8`、`Q13`、`Q14`、`Q16`、`G-FLOP-IDEMPOTENT`、`G-FLOP-DIRECTION`、`G-FLOP-UNMAPPED`、`G-FLOP-SEMANTICS`、`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`、`G-DELIVERY-ORDER` |
| `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` | SIS 13 类参考数据与资源状态、admin-api 21 类：完整校验、原子发布、失败保旧 | `Q8`、`G-REF-DATA` |
| `US-14` | 机位/登机桥映射原子发布，PSDT 只读计算 | `Q8`、`G-REF-DATA` |
| `US-13` | SIS 消息中的 13 类参考数据与资源状态：完整校验、原子发布、失败保旧 | `Q8`、`G-REF-DATA` |
| `US-14` | admin-api 从本网关处理后的 PG / 经验证 Oracle 只读消费，不形成反向依赖 | `Q1`、`Q8`、`G-REF-DATA` |
| `US-15` | 阶段 B 历史归档成功后清场及删除事件恢复 | `D1`、`INV-18`、`Q9`、`G-FLIGHT-HIST-RETENTION` |
| `OPS-1` | 真实适配器、配置与单写者拒启，失权停写，安全停机 | `D2`、`PRE-5` |
| `OPS-2` | 真实健康、积压/失败指标、告警、受控处置与敏感信息保护 | reference.md |
@@ -282,7 +285,7 @@
`Q` 的定义与完整表述只在本文件之外一处：[specification.md](specification.md)「待确认事项台账」。此处只列与验收直接相关的依赖：
- `US-01` / `US-09` 的验收依赖 `Q2`（发现完整性）与 `C-8`（清除前提）；
- `US-06` / `US-13` / `US-14` 依赖 `Q8`（逐类清单）与 `Q13`（字段缺失语义）；
- `US-06` / `US-13` 依赖 `Q8`（逐类清单）与 `Q13`（字段缺失语义）；`US-14` 依赖 `Q1` 与 `Q8`（下游数据库读取契约）；
- `US-08` 依赖 `Q3`（HTTP 契约）、`Q4`（Kafka wire）、`Q5`（请求匹配）、`Q10`（出站契约）；
- `US-10` 依赖重放白名单与 `CLM-3`（重放安全）；
- `US-15` 依赖 `Q9`（清除授权与 DDL）。
docs/specification.md
+11 -10
View File
@@ -28,6 +28,7 @@
| 已回填 | 本系统已把处理标记写回该信箱行。 |
| 投递确认 | 投递目标已接受且本地 `MSG_EVENT` 已置 `SENT`；不表示业务消费者已消费。 |
| 自有 PG | 本系统唯一的业务数据库 PostgreSQL；与信箱之间不存在跨库事务。 |
| admin-api | 本网关处理结果的下游只读消费者；从选定的业务数据库读取，不向本网关提供数据。 |
管道内部术语（`W`、队头、终态、回填意图）定义在 [implementation.md](implementation.md)「术语与持久化记录」。
@@ -126,7 +127,7 @@
- **INV-17** 状态变更、待发事件、处理终态与回填意图在同一 PG 事务内原子提交。
- **INV-18** 航班表的写者集合是「主泵处理器」与「历史清理」；两者必须互斥（同一 `PIPELINE_LOCK`，或清理在同一事务内复查判据后再删除），不得出现清理删除与处理器更新同一 `FLID` 的竞态。
- **INV-19** 整包校验失败或运营日冲突时整包不落地，既有状态与版本保持不变。
- **INV-20** 处理器幂等：同一消息重复执行只产生一次业务效果。身份唯一只防「重复记录」，不防「重新执行」；29 类 FLOP 幂等矩阵补全前，本条**不可声明**（`G-FLOP-IDEMPOTENT`）。
- **INV-20** 处理器幂等：同一消息重复执行只产生一次业务效果。身份唯一只防「重复记录」，不防「重新执行」；SIS 25 类与经 `Q8` 定案启用的 legacy 子类型完成逐类幂等矩阵前，本条**不可声明**（`G-FLOP-IDEMPOTENT`）。
- **INV-21** `MAFL` 是派生投影：内容恒等于「`STATE = ACTIVE` 且 `MAID = 主航班 FLID`」的子航班集合（元素 `FLID` + `FLNO`，按 `FLID` 升序），不落库、不从入站解析；自引用与悬挂引用不入投影。
- **INV-22** 子航班集合变化必须使涉及的主航班在同一事务内推进 `STATE_VERSION` 并登记主航班事件；投影只进不退，版本不推进即被下游丢弃。
@@ -134,11 +135,11 @@
| 编号 | 主张 | 依赖 | 当前可否声明 | 挂起原因 |
|---|---|---|---|---|
| CLM-3 | 重放不产生重复业务副作用 | INV-20、`G-FLOP-IDEMPOTENT` | **不可** | 29 类 FLOP 幂等矩阵未补全；重放不恢复历史顺序 |
| CLM-3 | 重放不产生重复业务副作用 | INV-20、`G-FLOP-IDEMPOTENT` | **不可** | 启用的 FLOP 子类型幂等矩阵未补全；重放不恢复历史顺序 |
| CLM-4 | 回填不会被短暂故障放弃：最终打标，或进入可对账的放弃清单 | INV-8、`C-5`、`C-8` | **可声明（有条件）** | 条件：`R` 之前不放弃；`MISSING_ROW` 立即放弃并告警；放弃行须经人工对账才可用于清除判定（`C-8`）。原文保留另见 CLM-5 |
| CLM-5 | 重放窗口内原文仍可读 | `C-6`、`C-7`、`Q7`、`Q9` | **不可** | 清除语义与保留期未确认；「打标即清除」下无补救 |
| CLM-6 | 单实例内严格 FIFO | PRE-5、INV-3 | **可**（限于单活动实例） | — |
| CLM-7 | 事件投递在同一 `FLID` 内保序 | INV-10、投递设计 | **可**（跨 `FLID` 不承诺） | 只声明同一 `FLID` 内保序；按 `FLID` 的隔离边界与 `Q4` 定案、`G-DELIVERY-ORDER` 闭合一致 |
| CLM-7 | 事件投递在同一 `FLID` 内保序 | INV-10、投递设计 | **可**（跨 `FLID` 不承诺） | 实现当前按目标级全序投递，收敛到按 `FLID` 属投递改造 |
| CLM-8 | 出站交付承诺只到「落信」 | `C-24`、`Q10` | **可**（仅落信语义） | 消费方与 ACK 列语义未确认 |
| CLM-9 | 处理标记延迟由调度周期决定 | — | **不可** | 扫描周期不等于完成时限；批次积压、单行超时与历史作业都会延长实际延迟 |
| CLM-10 | 容量量级假设（单实例、入站日消息量千级到万级、单报文 ≤ 10⁴ 字节） | — | **不可** | 未实测，无生产负载数据；解除条件：取得现役信箱日量、峰值与单报文上限后重估 |
@@ -168,7 +169,7 @@
| INV-12 / INV-13 | PG 事务失败、快照重复或迟到 | 整体回滚重试、不重复推进版本、不回退状态、不误删增量航班 |
| INV-12 | 运营日冲突 | 整包 `DEAD(PROTOCOL)`，既有状态与版本不变 |
| INV-14 | 未携带字段保留、显式清空才清除；集合按完整合并结果写入 | `FlightStateEngineTest`「day plan merges scalars overwriting overlaps retaining absent and clearing on explicit empty」「flop merge retains absent scalars and collections」；`FdelAndAdftProcessorTest`「ADFT merge does not clear absent scalars」 |
| INV-14 | FLOP 逐类空标签语义（清除、撤销、集合清空）与「未携带不清空」的区分 | 逐类用例见 [implementation.md](implementation.md)「动态运行事件」；`G-FLOP-DIRECTION`、`G-FLOP-UNMAPPED` |
| INV-14 | FLOP 逐类空标签语义（清除、撤销、集合清空）与「未携带不清空」的区分 | 逐类用例见 [implementation.md](implementation.md)「动态运行事件」；`G-FLOP-DIRECTION`、`G-FLOP-UNMAPPED`、`G-FLOP-SEMANTICS` |
| INV-15 | 缺席不删除 | 需分别断言 FDEL 与清理路径 |
| INV-16 | 外部副作用失败后本地结果不变 | 需用例 |
| INV-17 | 业务型终态四件套同事务 | 需真实 PG 用例 |
@@ -176,7 +177,7 @@
| INV-19 | 整包协议拒绝（声明数不符、运营日冲突） | `DEAD(PROTOCOL)`，整包不落地、整体回滚、既有状态不变 |
| INV-21 | `MAFL` 投影与 `ACTIVE` 子航班集合一致（子航班删除后退出、自引用与悬挂引用不入、顺序确定） | `G-MAFL`：投影未实现 |
| INV-22 | 子航班新增、删除、`MAID` 迁移时主航班版本与事件 | `G-MAFL`：主/共享级联未实现 |
| INV-20 / CLM-3 | 重放同一条消息 | 阻塞于 29 类 FLOP 幂等矩阵 |
| INV-20 / CLM-3 | 重放同一条消息 | 阻塞于启用的 FLOP 子类型逐类幂等矩阵 |
| — | 请求超时、无匹配 RESP、时间单位不一致 | 不误用迟到应答、不提前完成请求 |
| — | stub 误配置、重复实例、停机中断 | 生产拒绝不安全启动，工作线程能正确退出 |
@@ -193,7 +194,7 @@
| `G-RESP-GUARD` | `RESP` 应答守卫未实现，当前与 `DNLD` 无差别进入快照写入 | 请求匹配闭环；`C-23` |
| `G-REQ-TRACK` | `REQ_TRACK` 无运行时协调器：出站适配、请求编码、超时与应答匹配未实现 | `US-08`；`C-24` |
| `G-PROC-HST` | `PROC_STATE_HST` 未建表，终态归档未落地 | `US-11`；归档能力 |
| `G-FLOP-IDEMPOTENT` | 29 类 FLOP 幂等矩阵未补全 | `INV-20`、`CLM-3` |
| `G-FLOP-IDEMPOTENT` | SIS 25 类与经 `Q8` 定案启用的 legacy 子类型尚无完整逐类幂等矩阵 | `INV-20`、`CLM-3` |
| `G-REPLAY-CHANNEL` | 「打标即清除」语义下的独立原文保留通道未设计 | `CLM-5` |
| `G-MAFL` | 主航班 `MAFL` 派生投影及主/共享原子级联未实现（规则见 `INV-21`/`INV-22`）；`MAFL` 不是 SIS/XML 入站字段 | 航班完整态；删除与重建 |
| `G-SRVT-VIPF` | SIS/XML 的 `SRVT`、`VIPF` 无界集合尚未映射到持久化明细；wire/domain 只保留出现事实与原始内容，不参与合并与投递（清空语义见 `Q13`） | 航班完整态；无损字段保存 |
@@ -202,10 +203,10 @@
| `G-HST-RETENTION` | 归档目标（`PROC_STATE_HST` 及后续归档表）的保留期与清除作业未定义 | 归档只转移不减少容量占用；`G-PROC-HST` |
| `G-FLIGHT-HIST-RETENTION` | 航班历史存储（外部）的保留期与容量上限未定义 | `D1`；`FLIGHT_SCHD` 物理清除后历史存储是唯一副本 |
| `G-REQ-TRACK-RETENTION` | `REQ_TRACK` 关闭态行（`DONE`/`EXPIRED`）的保留期与清除作业未定义 | 自有 PG 无界增长；`US-08` |
| `G-DELIVERY-ORDER` | 投递按目标级全序推进：一个 `FLID` 的队头失败会阻塞同目标其他 `FLID`，尚未收敛到按 `FLID` 隔离的保序边界 | 投递吞吐；`CLM-7`、`C-29` |
| `G-FLOP-DIRECTION` | 柜台、转盘、滑槽、登机门、计划机位五类的 FLOP 报文按 AODB→RMS 接收并落库，SIS 要求收到即拒绝（这些资源在 AODB 方向只随日计划下发） | `US-05`；`SIS:3.24`、`SIS:3.25`、`SIS:3.26`、`SIS:3.34`、`SIS:3.38` |
| `G-FLOP-UNMAPPED` | `XSD` `FLOP` 段的 `FFID`、`UNCL`、`CKOP`、`GTOP`、`CKCL`、`BDOP`、`LCTM`、`BDCL`、`FRET`、`FDIV`、`FLAB`、`RUNW`、`PXNO`、`FLBG`、`CKPB`、`BDPB` 未解码，解码即丢弃；其中 `FRET`、`FDIV`、`BDPB` 在 legacy 有对应处理 | `US-05`；无损字段保存 |
| `G-REF-DATA` | 参考数据入站（`SIS:3.1`～`SIS:3.14`）与 admin-api 刷新均未实现，`REF_MASTER` 只有目标表定义 | `US-13`、`US-14` |
| `G-FLOP-UNMAPPED` | [XSD](legacy/unisysaodbsis.xsd)「FLOP 元素」的 `FFID`、`UNCL`、`CKOP`、`GTOP`、`CKCL`、`BDOP`、`LCTM`、`BDCL`、`FRET`、`FDIV`、`FLAB`、`RUNW`、`PXNO`、`FLBG`、`CKPB`、`BDPB` 未解码；`CHDT.CCLS/CTYP` 被错误写成 `CHCLS/CHTYP`，均会静默丢失。其中 `FRET`、`FDIV`、`BDPB` 在 legacy 有对应处理 | `US-05`；无损字段保存 |
| `G-FLOP-SEMANTICS` | FLOP 未按 SIS 25 类建立 `STYP` 白名单；`ROUT` 未按方向截取 4 条且仍保存 `SCAT`/`SCDT`；BOTM/LACL 未同步设置或重置运行状态；除 FDEL 外，已删除航班仍会被合并、增版并发事件 | `US-05`、`INV-14`、`INV-20`；`Q8` |
| `G-REF-DATA` | SIS 静态参考数据消息处理（`SIS:3.1`～`SIS:3.14`）未实现；当前忽略规则还会直接跳过 `REGN`/`RSTA`，`REF_MASTER` 及 admin-api 下游读取契约均只有逻辑目标定义 | `US-04`、`US-13`、`US-14` |
## 8. 待确认事项台账
@@ -218,7 +219,7 @@
| Q5 | 请求匹配：回显字段可靠性与降级匹配 | `RQFD` 60 秒 / `RQRD` 30 秒超时 | 请求跟踪闭环 | 未确认 |
| Q6 | 重放期限与人工处置期限的取值（唯一作用是决定 `R_keep` 下界） | `R` = 30 天；重放/处置期限未定 | `R_keep` 取值 | 未确认 |
| Q7 | 处理标记值集与写权限、原文保留期、处理时间语义 | 写入 `PROCESSED` | 回填值集、保留期下界 | 未确认 |
| Q8 | 逐类覆盖清单：真实报文的子类型分布、SIS 未定义的 legacy 子类型（`ABTM`/`DELY`/`PADT`/`FTSS`/`STND`/`BDPB`/`REMC`）的报文形态、admin-api 21 类清单与字段映射、逐类 golden | 航班动态的字段语义与空标签规则已由 SIS `SIS:3.19`～`SIS:3.43` 给出，参考数据类别由 `SIS:3.1`～`SIS:3.14` 给出；`VIPP` 的忽略口径 SIS 未写明 | 积压处置与逐类矩阵的差异标注 | 暂缓（现阶段不处理） |
| Q8 | 逐类覆盖清单：真实报文的子类型分布、SIS 未定义的 legacy 子类型（`ABTM`/`DELY`/`PADT`/`FTSS`/`STND`/`BDPB`/`REMC`）的报文形态、逐类 golden、静态参考数据的批次暂存方式、admin-api 的数据库只读契约、除 FDEL 外目标航班不存在/已删除时的终态，以及 BOTM/LACL 运行状态的落点 | 航班动态的字段与空标签规则以 `SIS:3.19`～`SIS:3.43` 为准，静态参考数据以 `SIS:3.1`～`SIS:3.14` 的入站消息为准；SIS 未定义的行为不作统一推定 | 积压处置、逐类矩阵与参考数据发布、下游读取模型 | 暂缓（现阶段不处理） |
| Q9 | 清除执行方与 DDL 授权、方案 A/B 选型、分区能力 | 首选方案 A | `R_keep` 与清除边界 | 未确认 |
| Q10 | 出站消费方、ACK 列语义、出站清理与去重契约 | — | 出站信箱 | 未确认 |
| Q11 | 上游 `SEQN` 重置周期与业务身份的日期边界 | 不含日期边界 | 身份算法 | 未确认 |