refactor(ingress): 信箱边界层契约重构——发现与处理标记解耦、回填事实并入 PROC_STATE

收报扫描不再以 DATE_PROCESSED 为谓词:终态而未回填的行(解码失败死信等)会永久占据
有限批次,累积到 claim-batch 后收报整体停摆(US-01 条目 3 / message-lifecycle §5.3)。

ingress/InboxPoller.kt:按 ID 区间升序有界读取(ID > W),水位落 INBOX_CURSOR 并与入队
同一 PG 事务推进(中断后重扫补建);遇空洞即停,空洞超过 pipeline.max-commit-delay 判定
为永久并放行——否则水位永久停摆于一次自增回滚留下的空位。删除 InboxEnqueue(改由
insertIfAbsent 幂等入队)与 poller 内的回填扫描(消除 ingress→jobs 反向依赖)。

infra/persistence:端口按事实重画为 readRange/maxId/markProcessedIfUnmarked,标记 UPDATE
带 DATE_PROCESSED IS NULL 守卫,只把空标写为已处理(§11 单调,重复执行无副作用)。
回填事实并入 PROC_STATE(RECEIVED_AT/BACKFILL_AT/NEXT_AT/ATTEMPTS/ERROR),BACKFILL_TODO
随 V2 迁移下线;终态与回填意图是同一条 UPDATE,由处理器在自己的业务事务内落库,
message-lifecycle §4 登记的两个崩溃窗口(提交后回填前崩溃、待办二次落账失败)不再是缺口。

processing/BackfillService.kt(取代 BackfillSweepJob):终态提交后立即尝试一次,失败按
30s→15min 指数退避重试;扫描条件「终态 + 未确认标记 +(已到期 或 接收时间早于 NOW − R)」
使 §5.2 的超期期限 R 覆盖退避,中间态永不补写。死信同样可补写——回填只需消息 ID,
不再依赖 META。Pump 改用可注入 Clock。

infra/health:InboxLifecycleHealthIndicator 输出积压条数、最老未处理信龄、未回填终态数与
水位滞后(OPS-2 / §5.3 验收)。预计消化时长需吞吐采样,留待接入指标注册表时补。

配置:pipeline.max-commit-delay / overdue-backfill / backfill-batch、mailbox.processed-value
(Q2/Q6/Q7 未书面确认前取保守初值,不得为提速下调)。

不变量回归测试:死信不阻断后续发现、水位遇空洞即停与老化放行、终态+意图同事务、
超期 R 覆盖退避、中间态不补写、标记单调;InboxLifecycleJdbcSqlTest 以 H2 的 PostgreSQL
兼容模式直连验证上述 SQL 语义(不依赖 docker)。libs.h2 由 testRuntimeOnly 提为
testImplementation 以支持该用例。

验证:gradle clean test --offline → 78 tests / 0 failures / 1 skipped
(PG Testcontainers 集成用例在本机无 docker 时按既有约定 assumeTrue 跳过)。
This commit is contained in:
windyboy
2026-09-10 10:59:58 +08:00
parent ffd3abd655
commit 09b53c77bb
32 changed files with 1402 additions and 548 deletions
@@ -1,10 +1,15 @@
package com.gzzn.omms.msgexchange.domain
import java.time.Instant
/**
* PROC_STATE 处理伴生状态(docs/design.md §2.1/§2.3):每消息一行,
* MSG_ID = 信箱 ID 主键防重复入队;IDENTITY_KEY 唯一约束防业务重复;
* 处理状态机与错误分类同设计文档 §2.3。SUCCEEDED 终态兼作 SCHD 快照
* 重放判定(docs/flight-state.md §4 步骤 / design.md §4.1)。
*
* 回填事实(message-lifecycle.md §5.2/§11)与处理事实同体同行:终态与回填意图
* 由同一条 UPDATE 落下,因此不存在"业务已提交、回填待办未记"的崩溃窗口。
*/
enum class ProcStatus { PENDING, FAILED, SUCCEEDED, SKIPPED, DEAD }
@@ -16,8 +21,16 @@ data class ProcState(
val state: ProcStatus,
val identityKey: String? = null, // SNDR|TYPE|STYP|SEQNdesign.md §2.2);decode 后首次绑定,FAILED 重试不重绑
val attempts: Int = 0,
val nextAttemptAt: java.time.Instant? = null,
val nextAttemptAt: Instant? = null,
val errorClass: ErrorClass? = null,
val lastError: String? = null,
val updatedAt: java.time.Instant = java.time.Instant.now(),
/** 信箱 CMINMSGS_DATE_RECEIVED:§5.2 超期补写的 R 判据与 OPS-2「最老未处理信龄」锚点。 */
val receivedAt: Instant? = null,
/** 非空 = 已确认信箱行持有处理标记(回填完成)。 */
val backfillAt: Instant? = null,
/** 非空 = 待回填;终态事务内登记为 now,失败按退避推后。 */
val backfillNextAt: Instant? = null,
val backfillAttempts: Int = 0,
val backfillError: String? = null,
val updatedAt: Instant = Instant.now(),
)