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

fix(processing): 落地 D1/D5/D6 三项裁决，删除 head-deadline 参数

Browse Source 
D5（终态判据只保留尝试上限）：
- Pump.tick 内联 attempts 判定，删除 head-deadline 相关的毒丸分支与滞留告警代码
- 删除配置项 head-deadline（PipelineProps / application.yml）与 PumpDeadlineTest
- PROCESSING_STARTED_AT 变为只写，注释如实说明当前无判据消费它

D1（回填放弃判据改为时间）：
- 暂时性故障在 R 之前只退避重试，不再按尝试次数放弃；到 R 才放弃并记 TRANSIENT_DEADLINE
- backfill-max-attempts 降级为单行重试的告警阈值

D6（超期判据改用本地入队时间）：
- 新增 V6 迁移：PROC_STATE 加 ENQUEUED_AT（回填存量后置为非空 + 默认）
- findBackfillDue 的谓词与 overdue 标记改比较 enqueued_at，不再用库方时钟的 received_at
- BackfillDue 增加 overdue；收报与兼容入口显式写入本地入队时间

文档同步：
- 清理 4 处 message-lifecycle.md 章节号死链（Pump/InboxService/PipelineProps/application.yml）
- 关闭 G-HEAD-DEADLINE、G-BACKFILL-ABANDON-BYTIME、G-ENQUEUED-AT 三条缺口登记
- reference/user-stories/README 与实现对齐

验证：./gradlew test ⇒ 122 tests, 0 failures, 1 skipped

Refs: ACM2-45
This commit is contained in:
windyboy
2026-09-11 20:44:30 +08:00
parent 6eade95a97
commit 817236ca26
21 changed files with 217 additions and 152 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+1 -1
View File
@@ -34,7 +34,7 @@
| 保留期下界 `R_keep`、清除前置条件 | contracts「保留与清除」 | design 只引 `C-x`；执行步骤在上线前另立 |
| 处理标记值集与写权限 | contracts `C-5` | design 只写行为约束「只写空标记、不回撤、不覆盖」（`INV-6`） |
| 回填四结果、放弃语义、`R` 的作用 | design「回填」 | invariants 记结论与可声明性 |
| `head-deadline` / 退避 / `claim-batch` 等取值 | reference「参数」 | design 只引 `PARAM:x` |
| 退避 / `claim-batch` / 回填期限等取值 | reference「参数」 | design 只引 `PARAM:x` |
| 消费权排他、ID 不复位、报文不可变、时钟、单实例 | invariants「前提」 | 其他文档只引 `PRE-x` |
| 航班身份、合并语义、`STATE_VERSION`、`OPERATION_DAY` | flight-state.md | design 只引域规则 |
| 对外术语（落信 / 入站 / 库方 / 处理标记） | contracts「术语」 | — |
docs/design.md
+6 -6
View File
@@ -23,7 +23,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` 是本地入队时间、非空、是超期判据的唯一依据 `[G-ENQUEUED-AT]`。 |
| `PROC_STATE` | 入站消息的处理状态、身份、尝试次数、错误原因与回填事实 | `MSG_ID = CMINMSGS_ID` 主键防重复入队；`IDENTITY_KEY` 唯一约束防业务重复；按最小未完成 `MSG_ID` 取队头；`BACKFILL_NEXT_AT` 非空 = 还欠一次回填，`BACKFILL_AT` 非空 = 标记已确认，`BACKFILL_ABANDONED_AT/REASON` 非空 = 已停止自动重试（**不等于**标记已确认）；`RECEIVED_AT` 复制自信箱接收时间、**可能为 NULL**、仅用于对账与展示；`ENQUEUED_AT` 是本地入队时间、非空、是超期判据的唯一依据。 |
| `MSG_EVENT` | 等待投递的事件（outbox） | `EVENT_ID` 决定投递顺序（全局串行分配，见投递）；`TARGET` 区分 `KAFKA:msg` / `KAFKA:schd`；`PARTITION_KEY` 恒为 `FLID`；`EVENT_TYPE` 区分 UPSERT 与 TOMBSTONE。`KAFKA:schd` 按 `FLID` 单行 upsert，只保留最新 `STATE_VERSION`。 |
| `REQ_TRACK` | 上游请求及应答关联 | 状态 `PENDING / SENT / DONE / EXPIRED`；保存请求类型、覆盖运营日、发送方、出站信箱 ID 与发送/完成时间；**「同类只允许一个开放请求」的唯一键 = `(请求类型, 覆盖运营日, 发送方)`，且仅对开放状态生效**。登记、超时与应答匹配尚未实现 `[G-REQ-TRACK]`。 |
| `REF_MASTER` | 静态参考数据（目标表） | `(RTYPE, RKEY)` 唯一；尚未建表，客户端与刷新流程见 user-stories US-13/US-14，US-14 两类映射的存储落点未定。 |
@@ -126,7 +126,7 @@
4. 队头为 `FAILED` 且未到 `next_attempt_at`：休眠到可重试时刻，不处理后续消息。
5. 其余（新消息或退避到期的重试）：调用 `MessageProcessor.processOne`，失败迁移在该边界内完成。
**队头滞留只告警、不迁移状态**：`PARAM:msgx.pipeline.head-deadline` 用于 `msgloop` 健康告警（「队头滞留超阈值」），**不作为终态判据**。理由：按尝试上限与退避表，正常重试包络远小于该阈值，它只在单次处理长时间卡住时触发；而处理卡死应由外部调用的有界超时兜底，用超时把消息直接推入 `DEAD` 会绕过人工复核，并制造与人工重放并发的旁路写入者。
**终态判据只有尝试上限，没有按时间的毒丸**：处理卡死应由外部调用的有界超时兜底；用一个时间阈值把消息直接推入 `DEAD` 会绕过人工复核，并制造与人工重放并发的旁路写入者。队头年龄由 `msgx.pipeline.backlog.oldest_unprocessed_seconds` 观测，主泵不做这项判定。
**所有取时统一经注入 `Clock`**（收报空洞老化、主泵调度、处理器落库时间、回填重试、作业切日），不使用系统时钟。
@@ -177,7 +177,7 @@ processOne(head)：
- 顺序由 `MSG_ID` 决定，不由执行方式决定。入队与处理由不同线程驱动、可以并发，「先入队后处理」只是可选的运维规程，不是正确性前提；系统不提供「只入队」模式。
- 不加速、不分流、不走旁路：不允许并行队头，也不允许实时消息跳过积压。
- 尝试上限、退避与队头滞留告警对积压同样生效，不因积压而放宽。
- 尝试上限与退避对积压同样生效，不因积压而放宽。
- 经确认不再处理的行置 `SKIPPED` 并记录原因，到达终态后走回填通道；不存在「整段 DELETE」的快速通道（授权与留痕见 `C-27`／`Q12`）。
- 消化期间的可观测项与完成时限口径见 reference 与 CLM-9：**扫描周期不是完成时限**。
@@ -198,7 +198,7 @@ ORDER BY BACKFILL_ATTEMPTS ASC, MSG_ID ASC -- 公平轮转，永久失败
LIMIT PARAM:msgx.pipeline.backfill-batch
```
超期判据使用**本地入队时间**（`ENQUEUED_AT`），不使用信箱的 `RECEIVED_AT`：后者来自外部时钟，前偏会在「打标即清除」语义下造成提前清除（`PRE-4`）。`ENQUEUED_AT` 落地前，该分支沿用 `RECEIVED_AT` 并在声明边界标注时钟偏斜风险 `[G-ENQUEUED-AT]`。
超期判据使用**本地入队时间**（`ENQUEUED_AT`），不使用信箱的 `RECEIVED_AT`：后者来自外部时钟，前偏会在「打标即清除」语义下造成提前清除（`PRE-4`）。
### 6.2 四种结果与放弃
@@ -218,7 +218,7 @@ LIMIT PARAM:msgx.pipeline.backfill-batch
1. **取消退避**：已终态但超期未打标的行，每轮扫描都被尝试，不再等退避到期；
2. **暂时性故障的放弃期限**：超时、连接失败这类暂时性故障**在 `R` 之前只退避重试、不放弃**；到 `R` 仍未打标才停止自动重试、记入放弃清单并告警。
放弃判据用**时间**而不是**尝试次数**：按退避表（档位 ≤ 8 秒）与扫描周期，固定次数的实际上限只有几十分钟，一次小时级的共享库故障会把全部待回填行一次性判死，随后必须成批人工恢复——这是必须避免的失败模式。`PARAM:msgx.pipeline.backfill-max-attempts` 因此不再是放弃判据，只保留为单行重试的告警阈值 `[G-BACKFILL-ABANDON-BYTIME]`。
放弃判据用**时间**而不是**尝试次数**：按退避表（档位 ≤ 8 秒）与扫描周期，固定次数的实际上限只有几十分钟，一次小时级的共享库故障会把全部待回填行一次性判死，随后必须成批人工恢复——这是必须避免的失败模式。`PARAM:msgx.pipeline.backfill-max-attempts` 因此不再是放弃判据，只保留为单行重试的告警阈值。
关于「最终一定打标」，准确表述是三段，缺一不可：
@@ -314,7 +314,7 @@ PENDING → SENT → DONE
| 标记写入中途 | 标记仍为空 | 重新写入；重复写入同一值无副作用 |
| 兼容入口已入队、水位未追平 | PG 已有该 ID 的记录 | 轮询读到该行时主键幂等，水位照常推进 |
| 回填时信箱行已不存在 | 写入 0 行且信箱行不存在 | 立即放弃自动重试（`MISSING_ROW`）并告警；放弃不等于标记已确认，仍需人工对账 |
| `RECEIVED_AT` 为 NULL | 超期分支以 `ENQUEUED_AT` 判定，不再失效 | `[G-ENQUEUED-AT]` 落地前靠退避重试保证 |
| `RECEIVED_AT` 为 NULL | 超期分支以本地 `ENQUEUED_AT` 判定，不受库方时钟与 NULL 影响 | 按 `R` 超期强补写；未超期则按退避重试 |
| 投递目标已接受、`SENT` 未置 | 事件仍 `PENDING` | 允许重发，消费方按事件身份去重 |
| PG 从备份恢复 | 终态与事件回退到备份点 | 按至少一次接受重复；不重放业务、不据此改写航班 |
docs/invariants.md
+1 -4
View File
@@ -79,7 +79,7 @@
| INV-5 | 终态未回填不阻断发现 | 缺口（补齐后应断言发现谓词不引用处理状态） |
| INV-6 | 投递失败后终态不变 | 缺口 |
| INV-7 | 回填四种结果 | 写入成功 / 早已标记（不覆盖、记成功）/ 信箱行不存在（立即放弃并告警，不得视为已标记）/ 暂时故障持续到 `R` 仍未打标（停止自动重试，可人工恢复） |
| INV-7 | `RECEIVED_AT` 为 NULL | 超期兜底不生效的行为被显式验证，且不导致标记提前写入（`G-ENQUEUED-AT` 落地后改为覆盖该分支） |
| INV-7 | `RECEIVED_AT` 为 NULL | 超期分支仍成立且不导致标记提前写入——判据是本地 `ENQUEUED_AT`，与库方时钟及 NULL 无关 |
| INV-8 | PG 提交失败、信箱回填失败 | 事件、终态与回填意图一起回滚；已提交结果只补写标记，不重放业务；中间态永不补写 |
| INV-8 | 非业务型终态 | 不触碰航班表 / `MSG_EVENT`，只写 `PROC_STATE`，且终态与回填意图同语句生效 |
| INV-9 | 同身份多条记录、失败后重试、归档后重复 | 只产生一次有效业务处理，不把自身重试判为重复 |
@@ -107,12 +107,9 @@
| `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-ENQUEUED-AT` | `PROC_STATE` 尚无 `ENQUEUED_AT` 列，超期判据暂用 `RECEIVED_AT` | `INV-7` / CLM-4；跨系统时钟偏斜与 `RECEIVED_AT` 为 NULL |
| `G-FLOP-IDEMPOTENT` | 29 类 FLOP 幂等矩阵未补全 | `INV-20`、CLM-3 |
| `G-BACKFILL-ABANDON-BYTIME` | 回填放弃判据由「尝试次数」改为「`R` 超期」尚未落地 | `INV-7`、CLM-4 |
| `G-EVENT-RETENTION` | `MSG_EVENT` 已发送行的保留期与清理作业未实现 | outbox 有界性 |
| `G-BACKFILL-BACKOFF` | 回填独立退避键（`backfill-backoff-ms` / `-cap-ms`）未实现，暂沿用处理退避表 | 回填重试节奏 |
| `G-HEAD-DEADLINE` | `head-deadline` 已定为「仅告警」，代码注释与判据仍写「毒丸升级」 | design「主泵调度」的表述一致性 |
| `G-KAFKA-D3` | `kafka.producers.default.max-in-flight` 默认 5，与架构决策 D3 要求的 1 不一致 | 投递幂等前提 |
| `G-JOB-HEARTBEAT` | 作业心跳、扫描积压、实际回填延迟指标未实现 | CLM-9；回填可观测性 |
| `G-REPLAY-CHANNEL` | 「打标即清除」语义下的独立原文保留通道未设计 | CLM-5 |
docs/reference.md
+4 -5
View File
@@ -17,13 +17,12 @@
| `msgx.pipeline.max-attempts` | `5` | 次 | 假定 | 处理与投递共用；达到即转 `DEAD(EXHAUSTED)` |
| `msgx.pipeline.backoff-ms` | `[1000,2000,4000,8000]` | ms / 档 | 假定 | **档位数必须 = `max-attempts − 1`**，启动自检拦截错位 |
| `msgx.pipeline.backoff-cap-ms` | `60000` | ms | 假定 | 单档封顶；默认表内无档触及 |
| `msgx.pipeline.head-deadline` | `10m` | Duration | 假定 | **仅用于队头滞留告警**，不作终态判据（判据只由 `max-attempts`）。代码注释仍写「毒丸升级」，属待收敛的表述差 `[G-HEAD-DEADLINE]` |
| `msgx.pipeline.max-commit-delay` | `5m` | Duration | **假定（无依据）** | 空洞老化阈值；由 `C-2` 决定，**不可由 SIS `Expiry` 推导**（`Q2`） |
| `msgx.pipeline.overdue-backfill`（`R`） | `30d` | Duration | 契约（`R ≤ R_keep`） | 进入强补写窗口、**取消退避**的阈值；**不是兜底保证**，不保护重放窗口（`Q6`） |
| `msgx.pipeline.backfill-batch` | `100` | 条 | 假定 | 回填扫描单批条数 |
| `msgx.pipeline.backfill-max-attempts` | `100` | 次 | **改作告警阈值** | **不再是放弃判据**：暂时性故障按 `R` 超期放弃（见 design「回填」）。该键保留为单行重试的告警阈值 `[G-BACKFILL-ABANDON-BYTIME]` |
| `msgx.pipeline.backfill-backoff-ms` | 目标参数（未实现） | ms / 档 | 假定 | 回填独立退避表；**当前不存在，回填沿用 `backoff-ms`** `[G-BACKFILL-BACKOFF]` |
| `msgx.pipeline.backfill-backoff-cap-ms` | 目标参数（未实现） | ms | 假定 | 回填退避封顶；旧文档「封顶 15 分钟」无对应配置键，已作废 `[G-BACKFILL-BACKOFF]` |
| `msgx.pipeline.backfill-max-attempts` | `100` | 次 | 假定 | 单行重试的**告警阈值**；放弃判据是 `R` 超期，不是次数（见 design「回填」） |
| `msgx.pipeline.backfill-backoff-ms` | 目标参数（未实现） | ms / 档 | 假定 | 回填独立退避表；**当前不存在**，`BackfillService` 内硬编码 30 秒起步、封顶 15 分钟 `[G-BACKFILL-BACKOFF]` |
| `msgx.pipeline.backfill-backoff-cap-ms` | 目标参数（未实现） | ms | 假定 | 回填退避封顶；对应实现是代码内常量，尚无配置键 `[G-BACKFILL-BACKOFF]` |
| `msgx.pipeline.cutover-watermark` | 不设置 | `min\|zero\|max\|<id>` | 一次性运维决策 | 显式播种水位；非法值由启动自检挡下；升级实例拒绝重新播种 |
| `msgx.pipeline.late-detect-period` | `60s` | Duration | 假定 | 只读迟到检测周期；`≤0` 关闭；机制为临时观测（见 design 扫描路径） |
| `msgx.pipeline.late-detect-batch` | `200` | 条 | 假定 | 每轮复查的空洞 ID 上限 |
@@ -98,7 +97,7 @@
| 持久化与恢复 | `infra/persistence/`、`infra/retry/`（`ProcFailure` / `ReplayService` / `FailureScheduler`） |
| 启停与配置 | `PipelineLifecycle.kt`、`config/PipelineProps.kt`、`config/HistoryProps.kt` |
| 指标与健康 | `infra/metrics/PipelineMetrics.kt`、`infra/health/BacklogSnapshotProvider.kt` |
| 迁移 | `src/main/resources/db/migration/`（V1 基线、V2 生命周期、V3 HOL 起点、V4 回填闭环、V5 切流播种；`oracle11g/` 为占位） |
| 迁移 | `src/main/resources/db/migration/`（V1 基线、V2 生命周期、V3 稳定处理起点、V4 回填闭环、V5 切流播种、V6 本地入队时间；`oracle11g/` 为占位） |
## 4. 错误分类与重放白名单
docs/user-stories.md
+2 -2
View File
@@ -80,12 +80,12 @@
2. 安全解码 XML，至少覆盖 META、SCHD、FLOP、参考应答与忽略类路由；合法但能力未支持是 `UNSUPPORTED`，不能一律归为非法报文。保留原文以支持诊断和回放。
3. 解码后首次绑定 `SNDR|TYPE|STYP|SEQN`；冲突转 `SKIPPED` 并记录原 ID；自身重试保留绑定。生产 `include-day-boundary=false`，更改算法须另行评审上游序号规则。
4. `MALFORMED` 直接 `DEAD`；`CODEC_ERROR / UNSUPPORTED / INFRA` 按次数和退避处理，耗尽转 `DEAD(EXHAUSTED)`。不能无限重试未实现类型，也不能立即当非法报文丢弃。
5. HOL deadline 必须基于稳定起始时刻（`PROC_STATE.PROCESSING_STARTED_AT`），不能用每次重试刷新的 `updatedAt` 代替；调度判断注入 `Clock`。默认 5 次重试、10 分钟滞留限制；积压与人工重放的 deadline 边界按 Q6 验证。
5. 终态判据只有尝试上限（默认 5 次），**没有按时间的毒丸**；调度判断注入 `Clock`。积压与人工重放的边界按 Q6 验证。
6. 主泵在同一 PG 事务提交航班主表/明细、事件与处理结果；终态回填意图通过 US-09 同事务保存。任一步失败整体回滚；提交后只重试外部回填，不重复生成业务事件。
7. 领域决策逻辑只读取当前完整态与已解码报文，返回下一完整态和待发事件，不执行 I/O；Processor 作为事务协调器，将状态写入、事件、处理终态与回填意图收敛在同一事务边界内，不直接触碰 Kafka。失败只在持有消息上下文的边界落账，中断向上传递，不作为普通失败吞掉。
8. 权威存储不可用或未完成恢复时停止业务处理；不能把“整个状态丢失”误判为“单航班不存在”而批量成功结束增量报文。
**当前基础与落点**：`processing/Pump.kt`（含 `MessageProcessor`）、`DynamicProcessors.kt`、`Identity.kt`、`codec/JacksonXmlCodec.kt`、`infra/retry/`。严格 FIFO 主泵、SCHD（DNLD/RESP/ADFT）/FLOP/FDEL 处理器、PG 单事务（含回填意图预登记）、身份绑定与重试已实现；调度取时由可注入 `Clock` 提供，HOL deadline 以 `PROCESSING_STARTED_AT` 为稳定起点。尚未完成：忽略规则分支（US-04），以及逐类矩阵与 golden 样例（US-05）。长期积压和人工重放如何计算 deadline 仍由 Q6 定案。
**当前基础与落点**：`processing/Pump.kt`（含 `MessageProcessor`）、`DynamicProcessors.kt`、`Identity.kt`、`codec/JacksonXmlCodec.kt`、`infra/retry/`。严格 FIFO 主泵、SCHD（DNLD/RESP/ADFT）/FLOP/FDEL 处理器、PG 单事务（含回填意图预登记）、身份绑定与重试已实现；调度取时由可注入 `Clock` 提供。尚未完成：忽略规则分支（US-04），以及逐类矩阵与 golden 样例（US-05）。长期积压和人工重放如何计算边界仍由 Q6 定案。
**前置**：US-01；Q1 已定单库方向，Q6 决定 deadline 边界。数据库迁移只落自有库。