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
@@ -52,14 +52,14 @@ class InboxPollerTest {
assertEquals(ProcStatus.PENDING, proc.find(second)!!.state)
assertEquals(second, cursor.cursor.committedUpTo)
assertNull(cursor.cursor.holeSince)
// §5.3:消化阶段只写自有 PG,不碰信箱标记
// 收报只写自有,不碰信箱的处理标记
assertFalse(inbox.isMarked(first))
assertEquals(0, poller.pollOnce(t0)) // 重复扫描幂等
}
/**
* 回归US-01 条目 3 / §5.3「积压挡批」):终态且永不回填的行(解码失败死信)曾占满
* 有限批次使收报整体停摆——发现必须与处理标记彻底解耦
* 回归用例:处理完却永远不会回填的行(典型是解码失败死信)曾占满每一批的名额,
* 导致收报整体停摆。取新消息这件事必须和"有没有处理标记"彻底分开
*/
@Test
fun `terminal rows without a mailbox mark do not block discovery of later messages`() {