docs(kdoc): V2 迁移与处理/持久化层剩余注释改为直白说明

接上一提交,把本次工作范围内还没改到的注释补齐:V2 迁移脚本的注释原文几乎全是
段落编号引用,处理层与持久化层还留着一批 `(§3.3/§5)` 形式的行内注释。

V2__inbox_lifecycle.sql:文件头改为先讲清这次迁移解决的三个问题(记住收报读到哪里、
回填记录并进 PROC_STATE 而不是单开一张表、记下收信时间做什么用),再落到每个字段;
字段级注释补上"这个值非空代表什么"。SQL 语句一字未动(已用去注释后比对确认)。

processing:Pump 的分派与终态注释、ScheduleProcessor 的重放判定与运营日冲突、
DynamicProcessors 的删除通知与重新激活,都改成说明白"这一步在做什么、为什么这么做"。
infra/persistence:Repositories.kt 的仓储约定、航班状态读写、待发事件与请求跟踪接口,
JdbcPgRepositories 的锁、整态合并、历史清理判据、明细表映射,StubRepositories 的
对应实现,一律先说清用途再谈规则。
测试:8 个测试类里的行内引用改为说明这条断言在守什么。

注释里保留的文档指向只在需要延伸阅读时出现,不再作为解释本身。
全部为注释改动,测试仍为 78 passed / 1 skipped。
This commit is contained in:
windyboy
2026-09-10 11:09:19 +08:00
parent d475feb790
commit 6e7d819034
15 changed files with 154 additions and 114 deletions
@@ -129,8 +129,8 @@ class MessageProcessor(
log.warn("processOne unexpected failure msgId={} ec=INFRA msg={}", head.msgId, e.message ?: e.javaClass.simpleName)
procFailure.fail(head, ErrorClass.INFRA, e.message ?: e.javaClass.simpleName)
}
// 终态已提交:立即尝试一次回填;失败留待回填扫描按退避重试(意图已在终态事务内登记)。
// 中间态(PENDING/FAILED)不适用(message-lifecycle §5.2
// 终态已经写好了,马上试一次回填;写不进去也没关系,回填扫描按退避继续重试
// (待办在写终态时就一起登记了)。还没处理完的消息不打标记
if (terminal) backfill.attempt(head.msgId)
}
}
@@ -178,7 +178,7 @@ class MessageProcessor(
}
}
// 处理器分派:SCHD 日计划主链路(§3.1)/ FLOP / FDEL / ADFT;缺载荷按 MALFORMED 终态
// 按报文类型分派:日计划走 SCHD,其余走 FLOP / FDEL / ADFT报文缺载荷直接判为非法报文的死信
val result: ApplyResult = when (val kind = decoded.kind) {
is MsgKind.Schd -> {
val body = decoded.body as? ScheduleBody
@@ -204,14 +204,14 @@ class MessageProcessor(
flopProcessor.apply(head, decoded, payload)
}
is MsgKind.Unsupported -> {
// design.md §2.3:未支持类型 → FAILED(UNSUPPORTED) 退避重试,达阈值转 DEAD;绝不写终态
// 还没有对应处理器的报文类型:先按可重试的失败处理,等能力补齐,不直接判死
log.warn("unsupported type -> FAILED(UNSUPPORTED) msgId={} tag={}", head.msgId, kind.tag)
return procFailure.fail(head, ErrorClass.UNSUPPORTED, "no-handler:${kind.tag}")
}
}
if (result is ApplyResult.DeadProtocol) {
// design.md §2.3整包拒绝 DEAD(PROTOCOL),立即释放队头,人工确认
// 整包拒绝:不重试、立刻放掉队头,人工确认
log.error("DEAD(PROTOCOL) msgId={} reason={} flags={}", head.msgId, result.reason, result.flags)
procState.markTerminal(
head.msgId, ProcStatus.DEAD,