fix(pipeline): 修复取报-处理-回填链路的超时、吞吐、回填与 FIFO 问题

外部调用（ACM2-33） - 共享 MySQL 与自有 PG 全部补有界超时：驱动 connect/socket 超时 + Hikari 池超时（注意 Micronaut 的 Hikari 项是毫秒数，不是 Duration 字面量） - 删除主泵/毒丸路径的 inline 回填：跨库写不再占用 FIFO 关键路径，回填统一由扫描驱动 - 游标自愈：save() 改为「先 UPDATE、缺行 INSERT」，缺行只记一次 ERROR - Pump/Dispatcher 外层 catch 补 error 日志与失败计数投递吞吐（ACM2-34） - Dispatcher 改批量领取；队头退避未到期或首条发送失败即停止本轮（保持目标内保序） - 有活不再 sleep；删除不可达的 state==SENT 死条件；markSent 移入分支； superseded 清理加轮数上限与空 eventId 保护回填闭环（ACM2-36，V4） - MISSING（运行时确认行不存在）立即放弃自动重试并告警；暂时性故障达上限后停止自动重试 - 新增 reopen 人工恢复入口；放弃 ≠ 标记已确认（BACKFILL_AT 仍为空，清除前提不成立） - 扫描改 (BACKFILL_ATTEMPTS, MSG_ID) 公平轮转并排除放弃行，消除全局回填饥饿 - V4 只加字段与必要索引，不按年龄做任何存量推断切流播种（ACM2-35，V5） - cutover-watermark 四模式（min/zero/max/显式 ID），默认不播种、代码不做默认选择 - 升级实例拒绝重新播种（SEEDED_AT 为 NULL ≠ 从未消费）；播种与水位同语句落库 - 非法取值由启动自检挡下错误分类与入口契约（ACM2-37） - 未知 SCHD 子类型改为 UNSUPPORTED，不再静默当全量日计划合并 - ADFT 运营日冲突改走 ProtocolViolation → DEAD(PROTOCOL) - 兼容入口 receivedAt 缺失回退到注入 Clock；MessageLifecycleGate 强制注入 + 装配断言 - FIFO：主泵只领取 msgId ≤ W，兼容入口登记的行在水位追平前不被领取时间源与可观测（ACM2-38 / ACM2-41 阶段 0） - 仓储/处理器/作业全部经注入 Clock；移除 markTerminal/markBackfilled 的 Instant.now() 默认值 - 退避表档位与 max-attempts 对齐并加启动自检 - Micrometer 7 个 gauge（@Context 急切注册）+ /health 与 /metrics 共用积压快照缓存 - 只读迟到检测：监视被放行的空洞 ID 是否后来真的出现，只计数告警、不补入队 Plane: ACM2-33 ACM2-34 ACM2-35 ACM2-36 ACM2-37 ACM2-38 ACM2-41 Tests: 88 → 120（1 skipped 需真实 PG）
2026-09-11 08:08:35 +08:00
parent b65728f312
commit 1e75a81107
42 changed files with 1745 additions and 168 deletions
@@ -0,0 +1,37 @@
+package com.gzzn.omms.msgexchange.infra.metrics
+
+import jakarta.inject.Singleton
+import java.util.concurrent.atomic.AtomicLong
+
+/**
+ * 管道运行期的**进程内**计数。
+ *
+ * 存在的意义是让业务模块（如收报）能零依赖地上报事实：模块只依赖本类，
+ * 不直接依赖 Micrometer；指标如何在 `/metrics` 上暴露由 [PipelineMetrics] 决定。
+ *
+ * 注意：计数在重启后归零。需要跨重启的累计值应由指标后端聚合，不在这里做持久化。
+ */
+@Singleton
+class PipelineCounters {
+    private val holeAgedOut = AtomicLong(0)
+    private val lateArrivalDetected = AtomicLong(0)
+
+    /** 水位因空洞超过老化阈值而放行（判定为永久空洞）的次数。 */
+    fun holeAgedOutIncrement() {
+        holeAgedOut.incrementAndGet()
+    }
+
+    fun holeAgedOutCount(): Long = holeAgedOut.get()
+
+    /**
+     * "迟到到达"检测命中的**不同**消息 ID 数（ACM2-41 阶段 0）。
+     *
+     * 含义：该 ID 曾被判定为永久空洞并放行，之后却真的出现在信箱里——即上游提交晚于水位推进。
+     * 阶段 0 只计数与告警，**不会**补入队；因此这个值 > 0 表示"确有迟到发生，需要与库方对契约"。
+     */
+    fun lateArrivalDetectedIncrement() {
+        lateArrivalDetected.incrementAndGet()
+    }
+
+    fun lateArrivalDetectedCount(): Long = lateArrivalDetected.get()
+}
@@ -0,0 +1,84 @@
+package com.gzzn.omms.msgexchange.infra.metrics
+
+import com.gzzn.omms.msgexchange.infra.health.BacklogSnapshotProvider
+import com.gzzn.omms.msgexchange.infra.persistence.CminmsgInboxRepository
+import com.gzzn.omms.msgexchange.infra.persistence.InboxCursorRepository
+import io.micronaut.context.BeanProvider
+import io.micronaut.context.annotation.Context
+import io.micronaut.context.annotation.Requires
+import io.micrometer.core.instrument.Gauge
+import io.micrometer.core.instrument.MeterRegistry
+import jakarta.annotation.PostConstruct
+import java.time.Clock
+import java.time.Duration
+
+/**
+ * 把管道的可观测事实暴露成 Micrometer 指标（默认经 `/metrics` 抓取）。
+ *
+ * 只暴露规范里要求观测的量：
+ * - `msgx.pipeline.backlog.unfinished`：还没处理完的消息条数
+ * - `msgx.pipeline.backlog.oldest_unprocessed_seconds`：最老未处理消息的信龄
+ * - `msgx.pipeline.backfill.unmarked_terminal`：已终态但未打标的条数
+ * - `msgx.pipeline.backfill.abandoned`：已放弃自动回填的条数（**非 0 需人工对账**）
+ * - `msgx.pipeline.backfill.oldest_unmarked_seconds`：最老一条仍待自动回填的年龄
+ * - `msgx.pipeline.watermark.lag`：水位落后信箱最新 ID 的距离
+ * - `msgx.pipeline.hole.aged_out.total`：永久空洞放行次数
+ *
+ * 取数统一走 [BacklogSnapshotProvider]（30 秒 TTL），因此指标抓取不会打穿数据库。
+ * 无法取数时以 `NaN` 上报（Micrometer 的惯例表示"本次无值"），而不是伪造 0。
+ *
+ * `Gauge` 默认对目标对象持**弱引用**，这里显式 `strongReference(true)`：
+ * 单例被容器持有本不会被回收，但显式声明可避免将来重构踩坑。
+ *
+ * 用 `@Context` 而不是 `@Singleton`：没有任何 bean 依赖它，惰性单例永远不会被创建，
+ * 指标也就注册不上。指标装配必须在启动时急切完成。
+ */
+@Context
+@Requires(beans = [MeterRegistry::class])
+class PipelineMetrics(
+    private val registry: MeterRegistry,
+    private val backlogs: BacklogSnapshotProvider,
+    private val cursor: BeanProvider<InboxCursorRepository>,
+    private val mailbox: BeanProvider<CminmsgInboxRepository>,
+    private val counters: PipelineCounters,
+    private val clock: Clock,
+) {
+
+    @PostConstruct
+    fun bind() {
+        backlogGauge("msgx.pipeline.backlog.unfinished") { it.unfinished.toDouble() }
+        backlogGauge("msgx.pipeline.backlog.oldest_unprocessed_seconds") { snapshot ->
+            snapshot.oldestReceivedAt
+                ?.let { Duration.between(it, clock.instant()).seconds.toDouble() }
+                ?: -1.0
+        }
+        backlogGauge("msgx.pipeline.backfill.unmarked_terminal") { it.unmarkedTerminal.toDouble() }
+        backlogGauge("msgx.pipeline.backfill.abandoned") { it.abandonedBackfill.toDouble() }
+        backlogGauge("msgx.pipeline.backfill.oldest_unmarked_seconds") { snapshot ->
+            snapshot.oldestUnmarkedAt
+                ?.let { Duration.between(it, clock.instant()).seconds.toDouble() }
+                ?: -1.0
+        }
+
+        Gauge.builder("msgx.pipeline.watermark.lag", backlogs) { _ ->
+            val watermark = if (cursor.isPresent) cursor.get().load().committedUpTo else null
+            val maxId = if (mailbox.isPresent) runCatching { mailbox.get().maxId() }.getOrNull() else null
+            if (watermark != null && maxId != null) (maxId - watermark).toDouble() else -1.0
+        }.strongReference(true).register(registry)
+
+        Gauge.builder("msgx.pipeline.hole.aged_out.total", counters) { it.holeAgedOutCount().toDouble() }
+            .strongReference(true)
+            .register(registry)
+
+        // 迟到到达检测命中数（阶段 0 只观测）：> 0 表示上游提交确实晚于水位推进，需要与库方对契约。
+        Gauge.builder("msgx.pipeline.late_arrival.detected.total", counters) { it.lateArrivalDetectedCount().toDouble() }
+            .strongReference(true)
+            .register(registry)
+    }
+
+    private fun backlogGauge(name: String, value: (com.gzzn.omms.msgexchange.infra.persistence.Backlog) -> Double) {
+        Gauge.builder(name, backlogs) { provider ->
+            provider.snapshot()?.let(value) ?: Double.NaN
+        }.strongReference(true).register(registry)
+    }
+}