feat(codec): 观测未落库的 SRVT/VIPF 集合
SRVT/VIPF 只保留在 wire/domain 并计数告警，不落明细表、不参与合并： 出现事实不再被静默丢弃，为 Q13 定案提供真实流量证据（[G-SRVT-VIPF]）。 - wire DTO：SRVT/SERVICEDATA、VIPF/VIPDATA 与嵌套 VIPT（OPER 为元素属性） - 出现即留键：缺席与"出现但为空"不再等价；已落库 10 类集合语义不变 - 新增 msgx.pipeline.codec.srvt_seen.total / vipf_seen.total（reference.md 已登记） - 一并提交此前的 MAFL 文档改动（INV-21/INV-22、flight-state §2.3、G-MAFL 措辞）
This commit is contained in:
windyboy
+14
-2
@@ -33,7 +33,7 @@
|
||||
|
||||
### 2.2 字段与集合
|
||||
|
||||
标量与异常对象前缀字段存于主表。协议中的 `SRVT`、`VIPF` 是无界集合，目标形态必须按集合完整保存到专用明细表示；当前 wire mapper 与持久化尚未实现 `[G-SRVT-VIPF]`。`MAFL` 不是 SIS/XML 入站字段，而是由共享航班的 `MAID`、`FLID`、`FLNO` 生成的主航班派生投影；当前尚未实现 `[G-MAFL]`。
|
||||
标量与异常对象前缀字段存于主表。协议中的 `SRVT`、`VIPF` 是无界集合，目标形态必须按集合完整保存到专用明细表示；当前只在 wire/domain 保留其出现事实与原始内容，专用明细、合并与投递尚未实现 `[G-SRVT-VIPF]`。`MAFL` 不是 SIS/XML 入站字段，而是由共享航班的 `MAID`、`FLID`、`FLNO` 生成的主航班派生投影；当前尚未实现 `[G-MAFL]`。
|
||||
|
||||
- `ORDINAL` 是持久化顺序，从 1 开始；`SOURCE_SEQ` 是上游序号，允许为空或重复。
|
||||
- 相同资源号不代表同一条分配，禁止按资源号去重。
|
||||
@@ -41,6 +41,17 @@
|
||||
- ROUT 与 ERUT 是两类独立集合，不能因相同序号覆盖彼此。
|
||||
- 主/共享关系以主表的 `MAID` 为事实来源：`MAID` 是共享航班指向主航班 `FLID` 的引用（非共享航班为 `NULL`）；`MAFL` 只在读取和事件投影时从子航班事实派生，不按入站标量解析或保存。
|
||||
|
||||
### 2.3 主/共享投影（`MAFL`）
|
||||
|
||||
`MAFL` 是主航班的派生集合，元素为子航班的 `FLID` 与 `FLNO`；内容与变更传播分别由 `INV-21`、`INV-22` 保证。
|
||||
|
||||
- 子航班集合 = `STATE = ACTIVE` 且 `MAID = 主航班 FLID` 的 `FLIGHT_SCHD` 行；已 FDEL 的子航班（`STATE = DELETED`）自然退出投影，不需要改写主航班行。
|
||||
- 只有 `MAID` 为空的主航班携带 `MAFL`；共享航班只携带自身 `MAID`、`CSOP`、`CSFT`，不携带 `MAFL`，避免下游双向合并。
|
||||
- 投影按 `FLID` 升序，与到达顺序及 `FLNO` 变更无关：同一 `STATE_VERSION` 的投影逐字节稳定，重发与消费端比对才有意义。
|
||||
- `MAID = FLID` 的自引用行不进入任何 `MAFL`；`MAID` 指向不存在主航班的悬挂引用不阻断该子航班自身处理，只是不产生投影。
|
||||
- 子航班集合变化（新增、删除、`MAID` 迁移）必须让涉及的主航班在同一事务内推进 `STATE_VERSION` 并登记主航班事件（`KAFKA:msg` + `KAFKA:schd`）；否则整态投影的只进不退写入会丢弃它（`design.md`「`schd` 聚合」）。共享航班自身不单独发通知。
|
||||
- 派生主航班投影与产生它的状态写入必须同一事务或一致读快照；按 `MAID` 取子航班要求该列有索引（`INV-17`）。
|
||||
|
||||
## 3. 合并与写入语义
|
||||
|
||||
领域决策逻辑（如 `FlightStateEngine` 及各类 Handler 规则）保持纯粹：它根据当前完整态和已解码报文，返回下一完整态与待发事件，不执行数据库或 Kafka I/O。`ScheduleProcessor` / `FlopProcessor` / `FdelProcessor` / `AdftProcessor` 是事务协调器，负责在统一事务边界内调用决策逻辑并持久化结果。
|
||||
@@ -71,7 +82,7 @@ FDEL 是业务删除入口：仅在 `ACTIVE → DELETED` 时推进版本、保
|
||||
|
||||
ADFT 的字段缺失语义尚待上游确认。在确认前采用保守的 Set-only 规则：出现字段可更新，缺失字段不清空；不得把它当成日计划或动态全量替换。新建 ADFT 若带可解析的 `SODT`，按同一运营日规则计算 `OPERATION_DAY`；否则保留为 `NULL`。
|
||||
|
||||
主/共享航班级联：删除共享航班时更新主航班 `MAFL` 并向主航班通知；删除主航班时级联删除其子共享关联并发出删除通知；主/共享关系必须一次原子变更，不出现主已删、子残留的半状态。共享航班增量通常只更新并通知主航班，不直接发共享通知。这些语义同样约束 FDEL 之外的生命周期清理。主/共享关联的增删按 `FLID` 做值比较，不使用引用比较。
|
||||
主/共享航班级联：删除共享航班时重算主航班 `MAFL`（见「主/共享投影」）并向主航班通知；删除主航班时级联删除其子共享关联并发出删除通知；主/共享关系必须一次原子变更，不出现主已删、子残留的半状态。共享航班增量通常只更新并通知主航班，不直接发共享通知。这些语义同样约束 FDEL 之外的生命周期清理。主/共享关联的增删按 `FLID` 做值比较，不使用引用比较。
|
||||
|
||||
SIS 规定删除主航班时必须先删子共享航班、再删主航班，顺序不符时 RMS 应向 AODB 回发 EROR（`SIS_AODB_RMS-V0.1.md` §1.6.1-1.d，事件定义见 SIS §4.8）。本文的原子级联不发该回报，两者取舍见 Q14。
|
||||
|
||||
@@ -106,6 +117,7 @@ SIS 规定删除主航班时必须先删子共享航班、再删主航班，顺
|
||||
- ADFT 缺失字段和 `FLID` 重用的上游语义（`FLID` 复用见 `Q16`）；
|
||||
- 日计划缺失可选字段的删除语义（与 SIS 的冲突见本文件「合并与写入语义」，`Q13`）；
|
||||
- 主/共享删除顺序与 EROR 回报义务（Q14）；
|
||||
- `MAFL` 投影是否出现在查询视图，随 `Q3`；字段名与空集合表示随 `Q4`；
|
||||
- 未归属 `OPERATION_DAY` 航班的终止与保留策略；
|
||||
- ROUT/ERUT 联合主键迁移；
|
||||
- 批量一致性读取，以及动态事件仅在事务内计算一次的收敛。
|
||||
|
||||
+6
-2
@@ -48,6 +48,8 @@
|
||||
- **INV-18** 航班表的写者集合是「主泵处理器」与「历史清理」；两者必须互斥（同一 `PIPELINE_LOCK`，或清理在同一事务内复查判据后再删除），不得出现清理删除与处理器更新同一 `FLID` 的竞态。
|
||||
- **INV-19** 整包校验失败或运营日冲突时整包不落地，既有状态与版本保持不变。
|
||||
- **INV-20** 处理器幂等：同一消息重复执行只产生一次业务效果。身份唯一只防「重复记录」，不防「重新执行」；29 类 FLOP 幂等矩阵补全前，本条**不可声明**。`[G-FLOP-IDEMPOTENT]`
|
||||
- **INV-21** `MAFL` 是派生投影：内容恒等于「`STATE = ACTIVE` 且 `MAID = 主航班 FLID`」的子航班集合（元素 `FLID` + `FLNO`，按 `FLID` 升序），不落库、不从入站解析；自引用与悬挂引用不入投影。
|
||||
- **INV-22** 子航班集合变化必须使涉及的主航班在同一事务内推进 `STATE_VERSION` 并登记主航班事件；投影只进不退，版本不推进即被下游丢弃。
|
||||
|
||||
## 3. 声明边界
|
||||
|
||||
@@ -92,6 +94,8 @@
|
||||
| INV-17 | 业务型终态四件套同事务 | 待核对；真实 PG 用例待补（ACM2-39） |
|
||||
| INV-18 | 清理与处理并发 | `HistorySweepJobTest`（归档后被主泵更新的航班不删除、不发 tombstone）+ `HistorySweepPurgePgTest`（删除阶段失败时 tombstone 与删除整体回滚） |
|
||||
| INV-20 / CLM-3 | 重放同一条消息 | 缺口：29 类 FLOP 幂等矩阵未补全 |
|
||||
| INV-21 | `MAFL` 投影与 `ACTIVE` 子航班集合一致（子航班删除后退出、自引用与悬挂引用不入、顺序确定） | 缺口：投影未实现（`[G-MAFL]`） |
|
||||
| INV-22 | 子航班新增、删除、`MAID` 迁移时主航班版本与事件 | 缺口：主/共享级联未实现（`[G-MAFL]`） |
|
||||
| CLM-4 | 放弃行与清除前提 | 断言放弃行不写标记、不被当作已打标（关联 ACM2-36） |
|
||||
| CLM-9 | 回填/积压完成时限 | 指标已就位：`msgx.pipeline.job.heartbeat_age_seconds` / `ticks.total` / `failures.total` / `last_sweep_selected` 与 `msgx.pipeline.backfill.oldest_unmarked_seconds`（关联 ACM2-38）；实际延迟仍需现场数据，CLM-9 不可声明 |
|
||||
| — | 请求超时、无匹配 RESP、时间单位不一致 | 不误用迟到应答、不提前完成请求 |
|
||||
@@ -112,8 +116,8 @@
|
||||
| `G-BACKFILL-BACKOFF` | 回填独立退避键（`backfill-backoff-ms` / `-cap-ms`）未实现，当前为代码内硬编码（取值见 reference） | 回填重试节奏 |
|
||||
| `G-KAFKA-D3` | `kafka.producers.default.max-in-flight` 与 D3 要求的 1 不一致（取值见 reference） | 投递幂等前提 |
|
||||
| `G-REPLAY-CHANNEL` | 「打标即清除」语义下的独立原文保留通道未设计 | CLM-5 |
|
||||
| `G-MAFL` | 主航班 `MAFL` 派生投影及主/共享原子级联未实现；`MAFL` 不是 SIS/XML 入站字段 | 航班完整态；删除与重建 |
|
||||
| `G-SRVT-VIPF` | SIS/XML 的 `SRVT`、`VIPF` 无界集合尚未映射到 wire/domain/持久化明细 | 航班完整态；无损字段保存 |
|
||||
| `G-MAFL` | 主航班 `MAFL` 派生投影及主/共享原子级联未实现（规则见 `INV-21`/`INV-22`）；`MAFL` 不是 SIS/XML 入站字段 | 航班完整态；删除与重建 |
|
||||
| `G-SRVT-VIPF` | SIS/XML 的 `SRVT`、`VIPF` 无界集合尚未映射到持久化明细；wire/domain 只保留出现事实与原始内容，不参与合并与投递（清空语义见 `Q13`） | 航班完整态；无损字段保存 |
|
||||
| `G-COMPAT-HTTP` | compat 入口仍未实现 Q3 定案后的 ResponseDto、媒体类型、字符集、失败响应与请求体上限 | `C-28`；US-02 |
|
||||
| `G-REQ-OPEN-UNIQUE` | `REQ_TRACK` 尚无约束开放态 `(REQ_TYPE, OPERATION_DAY, SENDER)` 唯一性的部分索引 | US-08；`G-REQ-TRACK` |
|
||||
|
||||
|
||||
+3
-1
@@ -83,8 +83,10 @@
|
||||
| `msgx.pipeline.job.ticks.total` | 作业 tick 完成次数 | 不增长 → 作业停摆 |
|
||||
| `msgx.pipeline.job.failures.total` | 作业 tick 抛错次数 | 增长 → 扫描/历史作业异常 |
|
||||
| `msgx.pipeline.job.last_sweep_selected` | 上一轮回填扫描选中的待办条数（扫描积压） | 持续顶到批次上限 → 扫描吃不消 |
|
||||
| `msgx.pipeline.codec.srvt_seen.total` | 入站记录中出现 `SRVT` 段的条数（尚未落明细表，`[G-SRVT-VIPF]`） | > 0 → 真实流量确有该段，按真实报文定案 `Q13` |
|
||||
| `msgx.pipeline.codec.vipf_seen.total` | 入站记录中出现 `VIPF` 段的条数（尚未落明细表，`[G-SRVT-VIPF]`） | 同上 |
|
||||
|
||||
取数规则：统一走 `BacklogSnapshotProvider`（`PARAM:msgx.health.backlog-cache-ttl-ms`），`/health` 与 `/metrics` 共用同一快照——`backlog()` 是 `PROC_STATE` 的全表聚合，不能被高频抓取打穿；**无法取数上报 `NaN`，无可比记录的年龄/滞后类仪表上报 `-1`，都不伪造 0**。日志出口故障不得阻塞业务线程。
|
||||
取数规则：统一走 `BacklogSnapshotProvider`（`PARAM:msgx.health.backlog-cache-ttl-ms`），`/health` 与 `/metrics` 共用同一快照——`backlog()` 是 `PROC_STATE` 的全表聚合，不能被高频抓取打穿；**无法取数上报 `NaN`，无可比记录的年龄/滞后类仪表上报 `-1`，都不伪造 0**。日志出口故障不得阻塞业务线程。进程内计数类指标不经快照，重启归零。
|
||||
|
||||
作业健康：回填的唯一驱动是扫描作业，因此作业存活必须独立可观测——`msgx.pipeline.job.heartbeat_age_seconds` / `ticks.total` / `failures.total` 是作业心跳，`msgx.pipeline.job.last_sweep_selected` 是扫描积压，`msgx.pipeline.backfill.oldest_unmarked_seconds` 是实际回填延迟；作业线程停摆由 `/health` 的作业指示器判 `DOWN`（心跳超过 `3 × 扫描周期`，周期是代码常量）。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user