windyboy
d475feb790
原有注释大量引用 §5.1/§5.2/Q2/US-01 这类文档编号和内部简称，跳过了"这段代码在做什么、 为什么这么做"，没有读过设计文档的人基本读不懂。本次统一改成先讲清这件事本身、 再说为什么要这样做，编号只在末尾留一处指路。 覆盖本次改动涉及的 24 个 Kotlin 文件（生产 16 个 + 测试 8 个）： - 领域与端口：ProcState（补齐全量字段说明与状态/错误分类逐项注释）、 ProcStateRepository / InboxCursorRepository / CminmsgInboxRepository 及 MailboxRow / BackfillDue / Backlog； - 收报：InboxPoller（把"水位连续、遇缺口停下、缺口老化"用大白话讲透）、 InboxService、JdbcCminmsgInboxRepository； - 处理：Pump / MessageProcessor、ScheduleProcessor、DynamicProcessors、 ProcFailure、JdbcProcStateRepository 与游标实现； - 回填与观测：BackfillService、InboxLifecycleHealthIndicator、JobRunner； - 配置与 stub：PipelineProps（三个新增参数说清取值理由）、MailboxProps、 StubRepositories； - 测试：8 个测试类改为"这些用例在守哪几条规矩"，并保留 H2 不覆盖 ON CONFLICT 的说明。 术语统一按第一次出现就地解释：水位、处理标记、回填、死信、队头、终态。 纯注释改动；除拆分枚举时按仓库风格补的两个行尾逗号外无代码变更 （已用剥离注释后比对 HEAD 的方式逐文件核对）。测试仍为 78 passed / 1 skipped。
72 lines
3.1 KiB
Kotlin
72 lines
3.1 KiB
Kotlin
package com.gzzn.omms.msgexchange.config
|
||
|
||
import io.micronaut.context.annotation.ConfigurationProperties
|
||
import java.time.Duration
|
||
|
||
/**
|
||
* 管道运行参数，对应配置文件里的 `msgx.*`。
|
||
*
|
||
* 注意：嵌套的配置类也必须标 `@ConfigurationProperties`，否则 Micronaut 不会绑定
|
||
* 里面的键，配置会静默失效、悄悄用回代码里的默认值。
|
||
*/
|
||
@ConfigurationProperties("msgx")
|
||
class PipelineProps {
|
||
var serviceName: String = "msgexchangeapi"
|
||
var registerEureka: Boolean = true
|
||
var pipeline: Pipeline = Pipeline()
|
||
var schd: Schd = Schd()
|
||
var identity: Identity = Identity()
|
||
|
||
@ConfigurationProperties("pipeline")
|
||
class Pipeline {
|
||
var pollInterval: Duration = Duration.ofSeconds(1) // KEEP 现役节奏
|
||
var claimBatch: Int = 50
|
||
var maxAttempts: Int = 5 // 处理/投递同值
|
||
var backoffMs: List<Long> = listOf(1000, 2000, 4000, 8000, 16000)
|
||
var backoffCapMs: Long = 60_000
|
||
var headDeadline: Duration = Duration.ofMinutes(10) // 最坏 HOL 上界（毒丸升级）
|
||
|
||
/**
|
||
* 缺口等待时长：水位后面缺了一个 ID 时，等这么久还没出现就认定它永远不会来了，
|
||
* 跳过缺口继续推进水位。
|
||
*
|
||
* 取值应该等于库方承诺的"上游提交到消息可见的最长时间"。设太小，可能把一条
|
||
* 迟到的消息误判成永久缺失，导致它排到后面的消息之后；设太大，收报会在缺口上白等。
|
||
*/
|
||
var maxCommitDelay: Duration = Duration.ofMinutes(5)
|
||
|
||
/**
|
||
* 超期补写期限：一条消息处理完之后，如果过了这么久还是没能把处理标记写回信箱
|
||
* （比如回填一直失败），就直接强制补写一次，不再等退避。
|
||
*
|
||
* 这是保证库方能清理信箱的兜底期限，必须覆盖人工重放所需的保留期，
|
||
* 确认之前不要调小，否则还在重放窗口内的消息会先被库方清掉。
|
||
*/
|
||
var overdueBackfill: Duration = Duration.ofDays(30)
|
||
|
||
/** 每次回填扫描最多处理多少条。 */
|
||
var backfillBatch: Int = 100
|
||
|
||
/** U07：启动即拉起 Pump/Dispatcher 循环（默认关——需要真实仓储或 msgx.stubs=true 才可安全开启）。 */
|
||
var autostart: Boolean = false
|
||
|
||
/** N28：attempt ≤ 0（如 FAILED 未递增 attempts 的行）不得抛异常，取下界=首档退避。 */
|
||
fun backoffFor(attempt: Int): Long {
|
||
val index = (attempt - 1).coerceAtLeast(0)
|
||
return backoffMs.getOrNull(index)?.coerceAtMost(backoffCapMs) ?: backoffCapMs
|
||
}
|
||
}
|
||
|
||
@ConfigurationProperties("schd")
|
||
class Schd {
|
||
var flushPeriod: Duration = Duration.ofSeconds(3) // KEEP 现役节律
|
||
var flushLimit: Int = 500
|
||
}
|
||
|
||
@ConfigurationProperties("identity")
|
||
class Identity {
|
||
/** CONFIRM（矩阵 #11）：SEQN 重置作用域确认前保持 false，计算集中此处（I3）。 */
|
||
var includeDayBoundary: Boolean = false
|
||
}
|
||
}
|