docs(kdoc): 重写信箱生命周期相关 KDoc,改为直白说明并去掉内部编号

原有注释大量引用 §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。
This commit is contained in:
windyboy
2026-09-10 11:05:55 +08:00
parent 8c6bb83b62
commit d475feb790
24 changed files with 332 additions and 186 deletions
@@ -4,9 +4,10 @@ import io.micronaut.context.annotation.ConfigurationProperties
import java.time.Duration
/**
* ACMA-8 参数表(v4)初值;阶段 0 现网基线校准
* U03N02):Micronaut 要求嵌套配置类同样标注 @ConfigurationProperties,否则
* msgx.pipeline/schd/identity.* 全部静默回落 Kotlin 默认值。
* 管道运行参数,对应配置文件里的 `msgx.*`
*
* 注意:嵌套的配置类也必须标 `@ConfigurationProperties`,否则 Micronaut 不会绑定
* 里面的键,配置会静默失效、悄悄用回代码里的默认值。
*/
@ConfigurationProperties("msgx")
class PipelineProps {
@@ -26,19 +27,24 @@ class PipelineProps {
var headDeadline: Duration = Duration.ofMinutes(10) // 最坏 HOL 上界(毒丸升级)
/**
* message-lifecycle §5.1 空洞老化:水位 W+1 处的空洞持续超过该时延即判定为永久并放行。
* 取值口径 = 库方承诺的最大提交时延(Q2);太小会把迟到消息判成永久空洞(FIFO 越序风险)
* 缺口等待时长:水位后面缺了一个 ID 时,等这么久还没出现就认定它永远不会来了,
* 跳过缺口继续推进水位
*
* 取值应该等于库方承诺的"上游提交到消息可见的最长时间"。设太小,可能把一条
* 迟到的消息误判成永久缺失,导致它排到后面的消息之后;设太大,收报会在缺口上白等。
*/
var maxCommitDelay: Duration = Duration.ofMinutes(5)
/**
* message-lifecycle §5.2 超期补写期限 R:终态后仍无处理标记的行到达该期限即强制补写,
* 保证库方清除前提「边界内无未标记行」在有限时间内成立
* R ≥ 人工重放期限 + 人工处置期限(Q6);确认前不得下调。
* 超期补写期限:一条消息处理完之后,如果过了这么久还是没能把处理标记写回信箱
* (比如回填一直失败),就直接强制补写一次,不再等退避
*
* 这是保证库方能清理信箱的兜底期限,必须覆盖人工重放所需的保留期,
* 确认之前不要调小,否则还在重放窗口内的消息会先被库方清掉。
*/
var overdueBackfill: Duration = Duration.ofDays(30)
/** 回填扫描单批条数。 */
/** 每次回填扫描最多处理多少条。 */
var backfillBatch: Int = 100
/** U07:启动即拉起 Pump/Dispatcher 循环(默认关——需要真实仓储或 msgx.stubs=true 才可安全开启)。 */