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:
@@ -32,7 +32,7 @@ class BackfillServiceTest {
|
||||
private val t0: Instant = Instant.parse("2026-09-08T03:00:00Z")
|
||||
private val props = PipelineProps()
|
||||
|
||||
/** 可注入故障的信箱:验证回填失败路径(§3 失败处理)。 */
|
||||
/** 可以人为制造故障的信箱,用来验证回填失败时怎么处理。 */
|
||||
private class FakeMailbox(var fail: Boolean = false) : CminmsgInboxRepository {
|
||||
val marked = linkedSetOf<Long>()
|
||||
override fun insertRaw(rawXml: String): Long = 1L
|
||||
@@ -76,7 +76,7 @@ class BackfillServiceTest {
|
||||
val id = inbox.insertRaw("<MSG/>")
|
||||
|
||||
assertTrue(inbox.markProcessedIfUnmarked(id, "PROCESSED"))
|
||||
assertFalse(inbox.markProcessedIfUnmarked(id, "OTHER")) // §11 只把空标写为已处理
|
||||
assertFalse(inbox.markProcessedIfUnmarked(id, "OTHER")) // 已经有标记了,不再写第二次
|
||||
assertEquals("PROCESSED", inbox.markOf(id))
|
||||
}
|
||||
|
||||
@@ -89,7 +89,7 @@ class BackfillServiceTest {
|
||||
|
||||
val backfill = service(proc, inbox)
|
||||
backfill.attempt(id)
|
||||
backfill.attempt(id) // 重复执行无副作用(§5.2 补写只针对空标记)
|
||||
backfill.attempt(id) // 重复补写没有副作用
|
||||
|
||||
assertNull(proc.find(id)!!.backfillError)
|
||||
assertEquals(0, proc.find(id)!!.backfillAttempts)
|
||||
@@ -104,7 +104,7 @@ class BackfillServiceTest {
|
||||
service(proc, mailbox).attempt(901L)
|
||||
|
||||
val row = proc.find(901L)!!
|
||||
assertEquals(ProcStatus.SUCCEEDED, row.state) // §11 终态不可逆
|
||||
assertEquals(ProcStatus.SUCCEEDED, row.state) // 回填失败不会把处理结果改回去
|
||||
assertEquals(1, row.backfillAttempts)
|
||||
assertEquals("mysql-down", row.backfillError)
|
||||
assertEquals(t0.plus(Duration.ofSeconds(30)), row.backfillNextAt)
|
||||
@@ -129,7 +129,7 @@ class BackfillServiceTest {
|
||||
assertNotNull(proc.find(901L)!!.backfillAt)
|
||||
}
|
||||
|
||||
/** §5.2:超期期限 R 覆盖退避,保证库方清除前提「边界内无未标记行」在有限时间内成立。 */
|
||||
/** 等得太久的消息不再等退避、直接补写:保证标记最终一定会写上。 */
|
||||
@Test
|
||||
fun `overdue rows bypass the retry backoff`() {
|
||||
val proc = StubProcState()
|
||||
@@ -145,7 +145,7 @@ class BackfillServiceTest {
|
||||
assertNotNull(proc.find(id)!!.backfillAt)
|
||||
}
|
||||
|
||||
/** §5.2:中间态(PENDING / FAILED)不适用超期补写——处理未完成时不打标。 */
|
||||
/** 还没处理完的消息(PENDING / FAILED)永远不打标,等再久也不行。 */
|
||||
@Test
|
||||
fun `mid states are never marked even when far past the deadline`() {
|
||||
val proc = StubProcState()
|
||||
|
||||
Reference in New Issue
Block a user