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.infra.health
+
+import com.gzzn.omms.msgexchange.infra.persistence.CminmsgInboxRepository
+import com.gzzn.omms.msgexchange.infra.persistence.InboxCursorRepository
+import com.gzzn.omms.msgexchange.infra.persistence.ProcStateRepository
+import io.micronaut.context.BeanProvider
+import io.micronaut.core.async.publisher.Publishers
+import io.micronaut.health.HealthStatus
+import io.micronaut.management.health.indicator.HealthIndicator
+import io.micronaut.management.health.indicator.HealthResult
+import jakarta.inject.Singleton
+import org.reactivestreams.Publisher
+import java.time.Duration
+import java.time.Instant
+
+/**
+ * 信箱生命周期观测（docs/message-lifecycle.md §5.3 验收 / user-stories.md OPS-2）：
+ * 输出剩余积压、最老未处理信龄、未回填终态条数与水位滞后，供积压消化期间持续观察。
+ *
+ * 端口缺省（未接通共享信箱或自有 PG）时报告未绑定而不判 DOWN——可用性由各依赖自身的
+ * 健康指示器承担，本指示器只反映生命周期状态；端口查询失败判 DOWN。
+ */
+@Singleton
+class InboxLifecycleHealthIndicator(
+    private val procState: BeanProvider<ProcStateRepository>,
+    private val cursor: BeanProvider<InboxCursorRepository>,
+    private val mailbox: BeanProvider<CminmsgInboxRepository>,
+) : HealthIndicator {
+
+    override fun getResult(): Publisher<HealthResult> =
+        Publishers.just(
+            runCatching {
+                lifecycleHealth(
+                    procState = if (procState.isPresent) procState.get() else null,
+                    cursor = if (cursor.isPresent) cursor.get() else null,
+                    mailbox = if (mailbox.isPresent) mailbox.get() else null,
+                )
+            }.getOrElse { down(it) },
+        )
+}
+
+internal fun lifecycleHealth(
+    procState: ProcStateRepository?,
+    cursor: InboxCursorRepository?,
+    mailbox: CminmsgInboxRepository?,
+    now: Instant = Instant.now(),
+): HealthResult {
+    if (procState == null) {
+        return HealthResult.builder(NAME).status(HealthStatus.UP)
+            .details(mapOf("message" to "proc_state repository not bound (stub off, impl pending)"))
+            .build()
+    }
+    val backlog = procState.backlog()
+    val watermark = cursor?.load()?.committedUpTo
+    val maxId = runCatching { mailbox?.maxId() }.getOrNull()
+    return HealthResult.builder(NAME).status(HealthStatus.UP).details(
+        linkedMapOf<String, Any>(
+            "backlog" to backlog.unfinished,
+            "oldestUnprocessedSeconds" to (
+                backlog.oldestReceivedAt?.let { Duration.between(it, now).seconds } ?: -1L
+                ),
+            "unmarkedTerminal" to backlog.unmarkedTerminal,
+            "watermark" to (watermark ?: -1L),
+            "watermarkLag" to if (watermark != null && maxId != null) maxId - watermark else -1L,
+        ),
+    ).build()
+}
+
+private fun down(error: Throwable): HealthResult =
+    HealthResult.builder(NAME).status(HealthStatus.DOWN)
+        .details(mapOf("message" to (error.message ?: error.javaClass.simpleName)))
+        .build()
+
+private const val NAME = "inbox-lifecycle"