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 跳过）。
2026-09-10 10:59:58 +08:00
parent ffd3abd655
commit 09b53c77bb
32 changed files with 1402 additions and 548 deletions
@@ -0,0 +1,74 @@
+package com.gzzn.omms.msgexchange.processing
+
+import com.gzzn.omms.msgexchange.config.MailboxProps
+import com.gzzn.omms.msgexchange.config.PipelineProps
+import com.gzzn.omms.msgexchange.infra.persistence.CminmsgInboxRepository
+import com.gzzn.omms.msgexchange.infra.persistence.ProcStateRepository
+import jakarta.inject.Singleton
+import java.time.Clock
+import java.time.Duration
+import java.time.Instant
+
+/**
+ * 信箱处理标记回填（docs/message-lifecycle.md §3/§4/§5.2）。
+ *
+ * 回填意图（`BACKFILL_NEXT_AT`）由处理器在终态事务内登记，与业务写入同提交同回滚，
+ * 因此不存在"业务已提交、待办未记"的窗口；本服务只做两件事：
+ * 1. [attempt]：终态提交后立即尝试一次（低延迟，失败静默留给扫描）；
+ * 2. [sweep]：到期或已达超期期限 R 的记录批量补写（§5.2），指数退避 30s 起步、封顶 15 分钟。
+ *
+ * 回填失败绝不重放业务变更，也绝不回改终态（§11）；写入侧只把空标写为已处理，
+ * 重复执行无副作用。
+ */
+@Singleton
+class BackfillService(
+    private val procState: ProcStateRepository,
+    private val mailbox: CminmsgInboxRepository,
+    private val mailboxProps: MailboxProps,
+    private val props: PipelineProps,
+    private val clock: Clock,
+) {
+    private val log = org.slf4j.LoggerFactory.getLogger(BackfillService::class.java)
+
+    companion object {
+        private val INITIAL_BACKOFF: Duration = Duration.ofSeconds(30)
+        private val MAX_BACKOFF: Duration = Duration.ofMinutes(15)
+
+        fun backoffDelayFor(attempts: Int): Duration {
+            val shift = (attempts - 1).coerceIn(0, 20)
+            return INITIAL_BACKOFF.multipliedBy(1L shl shift).coerceAtMost(MAX_BACKOFF)
+        }
+    }
+
+    /** 单条最佳努力回填；失败只登记退避（异常不外抛，不阻塞提交后的处理路径）。 */
+    fun attempt(msgId: Long, now: Instant = clock.instant()) {
+        record(msgId, attempts = 0, now = now)?.let {
+            log.warn("backfill failed msgId={} error={} (sweep will retry)", msgId, it)
+        }
+    }
+
+    /**
+     * 批量补写（JobRunner 每 30s 触发；重启即继续，不依赖内存状态）。
+     * @return 本批检查条数
+     */
+    fun sweep(now: Instant = clock.instant()): Int {
+        val due = procState.findBackfillDue(now, now.minus(props.pipeline.overdueBackfill), props.pipeline.backfillBatch)
+        due.forEach { record(it.msgId, it.attempts, now) }
+        return due.size
+    }
+
+    /** @return 失败原因；null = 已确认标记（含"已被其他路径标记"的幂等成功） */
+    private fun record(msgId: Long, attempts: Int, now: Instant): String? =
+        try {
+            // 影响 0 行 = 已有标记；按幂等成功处理（§11 标记单调：不回撤、不覆盖）
+            mailbox.markProcessedIfUnmarked(msgId, mailboxProps.processedValue)
+            procState.markBackfilled(msgId, now)
+            null
+        } catch (e: Exception) {
+            val reason = e.message ?: e.javaClass.simpleName
+            runCatching {
+                procState.recordBackfillFailure(msgId, reason, attempts + 1, now.plus(backoffDelayFor(attempts + 1)), now)
+            }.onFailure { log.error("record backfill failure failed msgId={}", msgId, it) }
+            reason
+        }
+}