docs(lifecycle): 补齐清除生命周期与逐对象归档边界
- design.md 9.3 扩为「生命周期与清除」：清除通则、逐对象生命周期表、 处理终态归档判据（终态 ∧ 回填了结 ∧ 终局后到期）与时间常数排序 - contracts.md 新增 C-16：回填放弃清单在对应信箱边界清除前必须保持可查 - invariants.md 缺口索引新增 G-HST-RETENTION、G-FLIGHT-HIST-RETENTION、 G-REQ-TRACK-RETENTION - flight-state.md 补航班历史存储保留期开放项 - 同步 architecture.md / user-stories.md 的 9.3 交叉引用
This commit is contained in:
windyboy
@@ -54,7 +54,7 @@ CIIMS / AODB 等上游
|
||||
| `codec` | XML 解码，区分非法报文与可修复的解码失败。 |
|
||||
| `processing` | FIFO 调度、业务身份绑定与去重、领域决策与落库（SCHD/FLOP/FDEL/ADFT）：纯领域逻辑只返回决策；Processor 作为事务协调器，在锁事务内完成状态写入、事件与回填意图登记，不直接触碰 Kafka。 |
|
||||
| `delivery` | 消费待发事件，负责按目标保序、`schd` 聚合、投递和失败重试。 |
|
||||
| `jobs` | 回填补偿扫描、航班历史清理与留痕保留期清理；独立 job 线程执行（调度见 design.md「维护作业与归档」，红线见 flight-state.md「生命周期与开放项」，与主泵的互斥见 `INV-18`），不参与 FIFO。 |
|
||||
| `jobs` | 回填补偿扫描、航班历史清理与留痕保留期清理；独立 job 线程执行（调度见 design.md「生命周期与清除」，红线见 flight-state.md「生命周期与开放项」，与主泵的互斥见 `INV-18`），不参与 FIFO。 |
|
||||
| `domain` / `config` | 领域状态、事件和决策模型，以及运行参数。 |
|
||||
| `infra` | 仓储（JDBC/stub）、外部适配器、重试、健康检查与日志；通过接口隔离基础设施。 |
|
||||
|
||||
@@ -93,7 +93,7 @@ CIIMS / AODB 等上游
|
||||
|
||||
| 编号 | 决策及理由 | 证据 / 缺口 |
|
||||
|---|---|---|
|
||||
| D1 | 航班清场只在历史写入成功后进行，未接通时删 0 条；未经 FDEL 的清场须先补发删除事件。ES 历史投影（阶段 B）暂缓。 | 红线见 flight-state.md「生命周期与开放项」；历史写入与删除事件之间仍无恢复方案（见 design.md「维护作业与归档」） |
|
||||
| D1 | 航班清场只在历史写入成功后进行，未接通时删 0 条；未经 FDEL 的清场须先补发删除事件。ES 历史投影（阶段 B）暂缓。 | 红线见 flight-state.md「生命周期与开放项」；历史写入与删除事件之间仍无恢复方案（见 design.md「生命周期与清除」） |
|
||||
| D2 | 动态状态单写者，生产只允许一个活动实例；多实例必须先具备可靠的排他保护。 | 事务行锁见 design.md「事务边界」；实例级排他属部署前提 `PRE-5`，可声明性见 `CLM-6` |
|
||||
| D3 | Kafka 生产要求 `acks=all`、`enable.idempotence=true`、`max.in.flight=1`；不允许通过关闭幂等来满足生产接入。 | 参数默认值与 D3 不一致 `[G-KAFKA-D3]`（取值见 reference 参数表） |
|
||||
| D4 | 自有库终态记录只归档到 `PROC_STATE_HST`，不侵入共享库的表结构或保留策略。 | 目标表未建 `[G-PROC-HST]` |
|
||||
|
||||
@@ -50,6 +50,7 @@
|
||||
- **C-13** 只读约定区间的信箱行（`ID > W`），单活动实例运行，不引入并行消费者。`[我们单方承诺]`
|
||||
- **C-14** 不建表、不改表结构、不迁移 schema、不写共享历史表；兼容 HTTP 入口按既有契约写入入站信箱。`[我们单方承诺]`
|
||||
- **C-15** 处理标记只写 `C-5` 认可的值，不回撤、不覆盖已有非空标记。`[我们单方承诺]`
|
||||
- **C-16** 回填放弃清单在对应信箱边界被清除前必须保持可查：`C-8` 以本清单作为清除授权证据之一，该证据不得随处理记录的归档或清除而消失。`[我们单方承诺][待确认 Q7][待确认 Q9]`
|
||||
|
||||
## B. 上游（SIS / AODB）
|
||||
|
||||
|
||||
+43
-4
@@ -30,7 +30,7 @@
|
||||
| `FLIGHT_SCHD` | 航班标量及单值异常字段 | `FLID` 主键；`OPERATION_DAY` 一经确定不可变；版本与最近消息 ID 用于追踪。现有变长集合存于 8 张资源明细表与 `FLIGHT_ROUTE_POINT`；`SRVT`/`VIPF` 专用明细尚未实现 `[G-SRVT-VIPF]`，规则见 flight-state.md。 |
|
||||
| `INBOX_CURSOR` | 消费水位 `W`、空洞计时 `holeSince`、播种事实 `SEEDED_AT` | 单行游标；`W` 只随新 ID 成功入队推进，遇空洞即停；`HOLE_SINCE` 持久化空洞观测时刻，进程重启不丢计时。`SEEDED_AT IS NULL` **不等于**从未消费（已有库新增列后同样为 NULL）。 |
|
||||
| `SCHD_SNAP_LOG` | 日计划处理留痕 | 只追加、可重建，不参与状态决策；保留期见 reference。 |
|
||||
| `PROC_STATE_HST` | 终态处理记录的归档目标 | 尚未建表 `[G-PROC-HST]`；只归档到自有 PG 的目标表，不落共享库历史表。 |
|
||||
| `PROC_STATE_HST` | 终态处理记录的归档目标 | 尚未建表 `[G-PROC-HST]`；只归档到自有 PG 的目标表，不落共享库历史表；自身保留期与清除作业未定义 `[G-HST-RETENTION]`。 |
|
||||
|
||||
字段与索引以 `src/main/resources/db/migration/` 的迁移链为准（Oracle 11g 目录为占位，未接入 Flyway）。报文原文仍从共享信箱读取，原文保留期必须覆盖处理与重放窗口（`C-7`）。
|
||||
|
||||
@@ -316,13 +316,52 @@ PENDING → SENT → DONE
|
||||
| 投递目标已接受、`SENT` 未置 | 事件仍 `PENDING` | 允许重发，消费方按事件身份去重 |
|
||||
| PG 从备份恢复 | 终态与事件回退到备份点 | 按至少一次接受重复；不重放业务、不据此改写航班 |
|
||||
|
||||
### 9.3 维护作业与归档
|
||||
### 9.3 生命周期与清除
|
||||
|
||||
`JobRunner` 用独立 daemon 线程按周期触发回填扫描、航班历史清理与留痕清理；作业不参与消息 FIFO，也不使到期消息饥饿。`INV-18` 要求历史清理的删除与主泵处理互斥。
|
||||
`JobRunner` 用独立 daemon 线程按周期触发回填扫描、航班历史清理与留痕清理（终态归档为待交付项 `[G-PROC-HST]`）；作业不参与消息 FIFO，也不使到期消息饥饿。`INV-18` 要求历史清理的删除与主泵处理互斥。
|
||||
|
||||
**通则**（对本系统所有持久对象适用）
|
||||
|
||||
- **时间不构成清除依据**：到期只是必要条件，**终局证据才是充分条件**（共享库见 `C-8`，航班见 `D1`）。
|
||||
- **归档不是终点**：归档目标是新的无界集合，必须有独立保留期与清除作业 `[G-HST-RETENTION]`，否则只是把容量问题从热表移到冷表。
|
||||
- **证据不随清除消失**：清除所依赖的证据（如 `C-8` 引用的回填放弃清单，本期承诺见 `C-16`）在其覆盖的信箱边界被清除前必须保持可查。
|
||||
- **证据缺失或结果不明时按最保守处置**：航班清理为删 0 条（`D1`）。
|
||||
|
||||
**逐对象生命周期**（保留期取值一律见 reference）
|
||||
|
||||
| 对象 | 终局判据 | 归档目标 | 清除证据 | 执行方 | 缺口 |
|
||||
|---|---|---|---|---|---|
|
||||
| 共享信箱 `CMINMSGS` 原文 | 处理标记 / 回填放弃清单 | 库方历史表（`C-9` 方案 B） | `C-8` | 库方 | 契约未确认（`Q6`/`Q7`/`Q9`） |
|
||||
| `FLIGHT_SCHD` + 资源明细 | 判史规则 | 历史存储 | 归档确认 + 版本复查 | 我们 | — |
|
||||
| 航班历史存储 | 保留期 | — | — | 我们 | `[G-FLIGHT-HIST-RETENTION]` |
|
||||
| `SCHD_SNAP_LOG` | 保留期 | 无（本地可重建） | 无 | 我们 | — |
|
||||
| `MSG_EVENT` 已发送行 | `SENT` | 无 | 无 | 我们 | `[G-EVENT-RETENTION]` |
|
||||
| `PROC_STATE` 终态行 | 见下 | `PROC_STATE_HST` | 回填了结 | 我们 | `[G-PROC-HST]` |
|
||||
| `PROC_STATE_HST` | 保留期 | — | — | 我们 | `[G-HST-RETENTION]` |
|
||||
| `REQ_TRACK` 关闭态行 | 保留期 | 无 | 无 | 我们 | `[G-REQ-TRACK-RETENTION]` |
|
||||
|
||||
原文副本是**条件对象**：仅当库方清除语义不满足 `C-6` 时才成立（`[G-REPLAY-CHANNEL]`、`CLM-5`），窗口与 `R_keep` 相同，落在自有 PG。
|
||||
|
||||
**处理终态归档**（`PROC_STATE` → `PROC_STATE_HST`）
|
||||
|
||||
候选 = 终态 **且** 回填已了结 **且** 终局后经过归档阈值。两处不可省：
|
||||
|
||||
- **回填已了结** = `BACKFILL_AT` 非空，或已放弃 **且经人工对账**。放弃行不写标记，是 `C-8` 的清除授权证据，未对账前不得归档。
|
||||
- **删除前复查** = `DEAD` 可被人工重放改回 `PENDING`，故必须在 `PIPELINE_LOCK` 内复查 `STATE` 未变再删，与航班历史清理同形（`INV-18`）。
|
||||
|
||||
归档范围只含终态；归档后仍须保留业务去重能力（`INV-9`）——去重记忆期长于工作状态在线期，两者同行时只能二选一。
|
||||
|
||||
**时间常数排序**（取值见 contracts.md）
|
||||
|
||||
1. `R ≤ R_keep`（`C-7`）。
|
||||
2. 去重记忆期 ≥ `R_keep`；否则「归档后重复」不成立（`INV-9`）。
|
||||
3. 回填放弃清单可见期 ≥ `R_keep`；否则库方清除缺 `C-8` 依据（`C-16`）。
|
||||
4. 归档阈值计的是**终局之后**的时间，不是入队之后：终态行未了结回填时不进入候选。
|
||||
|
||||
**其余清理**
|
||||
|
||||
- **航班历史清理**：按 reference 的历史判据选候选（含 `DELETED`），先成功归档再删除；未经 FDEL 的生命周期清除需先补发删除事件。语义与红线见 flight-state.md。
|
||||
- **留痕清理**：`SCHD_SNAP_LOG` 按保留期与 `(SCOPE_END, RECV_AT)` 删除，不依赖历史存储开关。
|
||||
- **处理终态归档**：`PROC_STATE` 终态记录归档至 `PROC_STATE_HST`（尚未建表 `[G-PROC-HST]`）。归档范围只含终态；归档后仍须保留业务去重能力。
|
||||
- **出站事件清理**：见投递清理规则。
|
||||
|
||||
共享信箱保留策略由库方管理（contracts「保留与清除」）。历史写入与删除事件入队之间仍需恢复方案；顺序调用不构成原子提交。
|
||||
|
||||
@@ -119,6 +119,7 @@ SIS 规定删除主航班时必须先删子共享航班、再删主航班，顺
|
||||
- 主/共享删除顺序与 EROR 回报义务（Q14）；
|
||||
- `MAFL` 投影是否出现在查询视图，随 `Q3`；字段名与空集合表示随 `Q4`；
|
||||
- 未归属 `OPERATION_DAY` 航班的终止与保留策略；
|
||||
- 航班历史存储自身的保留期与容量上限：`FLIGHT_SCHD` 物理清除后它是唯一副本 `[G-FLIGHT-HIST-RETENTION]`；
|
||||
- ROUT/ERUT 联合主键迁移；
|
||||
- 批量一致性读取，以及动态事件仅在事务内计算一次的收敛。
|
||||
|
||||
|
||||
@@ -120,5 +120,8 @@
|
||||
| `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` |
|
||||
| `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 |
|
||||
|
||||
缺口标记与 Plane 工作项的对应关系在 Plane 侧维护。
|
||||
|
||||
@@ -223,7 +223,7 @@
|
||||
|
||||
**当前基础与落点**：`PROC_STATE_HST` 未建表，也没有归档处理记录的作业；先确定去重记录保留与关联策略，再补迁移与归档中断测试。航班历史清理（`HistorySweepJob`，属 US-15 红线范围）与本文档处理记录归档不是同一件事，不能混为一谈。
|
||||
|
||||
**前置**：US-03、US-09；US-07 提供事件终态规则，US-10 提供恢复保留要求。不依赖 US-15。自有记录归档见 [design.md](design.md)「维护作业与归档」，重放与原文可用性见 [design.md](design.md)「失败、重试与重放」。
|
||||
**前置**：US-03、US-09；US-07 提供事件终态规则，US-10 提供恢复保留要求。不依赖 US-15。自有记录归档见 [design.md](design.md)「生命周期与清除」，重放与原文可用性见 [design.md](design.md)「失败、重试与重放」。
|
||||
|
||||
### US-12 查询实时航班（KEEP）
|
||||
|
||||
|
||||
Reference in New Issue
Block a user