feat(ingress): 实现 JDBC 信箱轮询、入站持久化与对拍测试 (U05)

2026-09-07 15:11:33 +08:00
parent dc68f1e1f8
commit c7b4b527ef
51 changed files with 1005 additions and 235 deletions
@@ -0,0 +1,163 @@
+package com.gzzn.omms.msgexchange.delivery
+
+import com.fasterxml.jackson.databind.ObjectMapper
+import com.gzzn.omms.msgexchange.config.PipelineProps
+import com.gzzn.omms.msgexchange.domain.ErrorClass
+import com.gzzn.omms.msgexchange.domain.EventStatus
+import com.gzzn.omms.msgexchange.domain.MsgEvent
+import com.gzzn.omms.msgexchange.domain.Targets
+import com.gzzn.omms.msgexchange.infra.persistence.MsgEventRepository
+import com.gzzn.omms.msgexchange.infra.retry.FailureScheduler
+import jakarta.inject.Singleton
+import java.time.Duration
+import java.time.Instant
+
+/** 对外投递端口（Kafka 同步确认；阶段 B 追加 ES/Redis 投影写入）。 */
+interface DeliveryPort {
+    /** Kafka 发送（同步确认，at-least-once）。topic 由 target 映射：KAFKA:msg→"msg"，KAFKA:schd→"schd"。 */
+    fun sendKafka(topic: String, payloadJson: String)
+
+    /** 阶段 B：ES flight_hts 写入。 */
+    fun indexFlightHts(payloadJson: String)
+
+    /** 阶段 B：Redis 投影写（仅阶段 B；I5：Delivery 阶段 A 不写 Redis）。 */
+    fun projectRedis(payloadJson: String)
+
+    /** 连通性探测（健康检查用）；默认 true，真实 Kafka 实装时覆写为 producer metadata 校验。 */
+    fun ping(): Boolean = true
+}
+
+/**
+ * ACMA-8 流程 3：投递调度——每 target 严格 FIFO（I1 双层同策略）。
+ * N03（U06）：KAFKA_SCHD 不走逐条循环（唯一出口是 flushSchd 批量聚合），逐条循环显式排除。
+ * U08 闭环：逐条与批量失败都在持有具体事件/批次的边界完成状态迁移——
+ *   · 逐条：scheduleRetry(attempts+1, backoff) / 达上限 markDead(EXHAUSTED)（DLQ 保留行）；
+ *   · 批量（flushSchd）：整批退避，队首 nextAttemptAt 未到不 claim；达上限整批 DEAD/DLQ；
+ *   · loop 只作最后防线，不吞 InterruptedException（致命/中断错误不被普通恢复吞掉）。
+ */
+@Singleton
+class Dispatcher(
+    private val msgEvents: MsgEventRepository,
+    private val port: DeliveryPort,
+    private val props: PipelineProps,
+    private val scheduler: FailureScheduler,
+) {
+    private val log = org.slf4j.LoggerFactory.getLogger(Dispatcher::class.java)
+
+    @Volatile
+    private var running = true
+
+    private var lastFlush: Instant = Instant.EPOCH
+
+    /** 优雅停机：loop 收尾后退出；线程中断由 Runner 负责。 */
+    fun stop() {
+        running = false
+    }
+
+    fun loop() {
+        while (running) {
+            try {
+                tick()
+            } catch (e: InterruptedException) {
+                Thread.currentThread().interrupt()
+                return
+            } catch (e: Exception) {
+                // U08：投递循环只作最后防线；致命 Error 不吞。tick 内失败迁移已完成。
+                sleepQuietly(props.pipeline.pollInterval)
+            }
+            // N18：轮询间隔取参数表（下限 50ms，避免退避节律被吞）
+            sleepQuietly(props.pipeline.pollInterval.coerceAtLeast(Duration.ofMillis(50)))
+        }
+    }
+
+    internal fun tick() {
+        val targets = if (props.phase == PipelineProps.Phase.A) Targets.phaseA else Targets.phaseB
+        for (t in targets) {
+            if (t == Targets.KAFKA_SCHD) continue        // N03：schd 唯一出口 flushSchd
+            val head = msgEvents.headUnsent(t) ?: continue
+            if (head.state == EventStatus.PENDING && head.nextAttemptAt != null && head.nextAttemptAt > scheduler.now()) {
+                // 队头退避未到期：等待，不跳过（保序）；超时升级归 U13（WP2）
+                continue
+            }
+            try {
+                deliver(t, head)
+                msgEvents.markSent(head.eventId!!)
+                log.debug("sent target={} eventId={}", t, head.eventId)
+                if (t == Targets.ES_FLIGHT_HTS && props.phase == PipelineProps.Phase.B) {
+                    // 定案 2：ES 投递成功 → 同线程同步 enqueue 删除事件（不轮询 ack）
+                    msgEvents.insertSync(listOf(MsgEvent(target = Targets.REDIS_FLIGHT_INFO, payloadJson = deleteOf(head))))
+                }
+            } catch (e: Exception) {
+                retryOrDead(head, e.message ?: "unknown")
+            }
+        }
+        if (flushDue()) {
+            flushSchd()
+        }
+    }
+
+    private fun flushDue(): Boolean =
+        Duration.between(lastFlush, scheduler.now()) >= props.schd.flushPeriod
+
+    /** 单条事件失败迁移：attempts+1；达上限 DEAD(EXHAUSTED)（DLQ，attempts 落库审计），否则退避重试。 */
+    private fun retryOrDead(e: MsgEvent, lastError: String) {
+        val attempts = e.attempts + 1
+        if (scheduler.exhausted(attempts)) {
+            log.error("event DEAD(DLQ) eventId={} attempts={} lastError={}", e.eventId, attempts, lastError)
+            msgEvents.markDead(e.eventId!!, ErrorClass.EXHAUSTED, lastError, attempts)
+        } else {
+            log.warn("event retry scheduled eventId={} attempts={} nextAttemptAt={}", e.eventId, attempts, scheduler.nextAttemptAt(attempts))
+            msgEvents.scheduleRetry(e.eventId!!, scheduler.nextAttemptAt(attempts), attempts)
+        }
+    }
+
+    private fun deliver(target: String, e: MsgEvent) = when (target) {
+        Targets.KAFKA_MSG -> port.sendKafka("msg", e.payloadJson)
+        Targets.KAFKA_SCHD -> error("KAFKA_SCHD must go through flushSchd (N03)")
+        Targets.ES_FLIGHT_HTS -> port.indexFlightHts(e.payloadJson)
+        Targets.REDIS_FLIGHT_INFO -> port.projectRedis(e.payloadJson)
+        else -> error("unknown target $target")
+    }
+
+    private val jsonMapper = ObjectMapper()
+
+    /**
+     * U14：删除事件 wire JSON 结构化序列化——refs 可空，产出必须恒为合法 JSON
+     * （null → null 字面量；非空 → 带引号并转义）。禁止字符串模板拼接。
+     */
+    private fun deleteOf(e: MsgEvent): String =
+        jsonMapper.writeValueAsString(linkedMapOf("op" to "delete", "refs" to e.partitionKey))
+
+    /**
+     * 流程 3 flushSchd：批上限 + 每 FLID 最新一态聚合（topic "schd"，wire=FLTR JSON 数组）。
+     * U08 批量闭环：队首退避未到期不 claim；发送失败 → 整批 attempts+1（退避）或达上限整批 DEAD/DLQ；
+     * lastFlush 仅在成功（含空批）后推进。
+     */
+    internal fun flushSchd() {
+        val pending = msgEvents.claimBatch(Targets.KAFKA_SCHD, limit = props.schd.flushLimit)
+        if (pending.isEmpty()) {
+            lastFlush = scheduler.now()
+            return
+        }
+        val due = pending.first()
+        if (due.nextAttemptAt != null && due.nextAttemptAt > scheduler.now()) {
+            return                                   // 队首仍在退避：整批等待，不推进 lastFlush（到期再试）
+        }
+        val payload = SchdAggregation.latestPerFlight(pending).joinToString(",", "[", "]")
+        log.debug("flushSchd batch size={} payloadLen={}", pending.size, payload.length)
+        try {
+            port.sendKafka("schd", payload)
+        } catch (e: Exception) {
+            log.warn("flushSchd send failed batch={} -> batch retryOrDead: {}", pending.size, e.message)
+            pending.forEach { retryOrDead(it, "schd-send: ${e.message ?: "unknown"}") }
+            return                                   // 不推进 lastFlush：整批退避（含 DEAD 出队）后到期重试
+        }
+        msgEvents.markAllSent(pending.mapNotNull { it.eventId })
+        log.info("flushSchd sent batch={}", pending.size)
+        lastFlush = scheduler.now()
+    }
+
+    private fun sleepQuietly(d: Duration) {
+        if (!d.isNegative && !d.isZero) Thread.sleep(d.toMillis().coerceAtLeast(1))
+    }
+}