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。
2026-09-10 11:09:19 +08:00
parent d475feb790
commit 6e7d819034
15 changed files with 154 additions and 114 deletions
@@ -78,7 +78,7 @@ class FdelProcessor(
        val deleted = flightState.markDeleted(payload.flid, msgId = head.msgId, now = Instant.now())
        if (deleted) {
            val current = flightState.loadFullSnapshot(payload.flid)
-            // tombstone 仅在 ACTIVE→DELETED 时登记（§3.3/§5），与删除同事务
+            // 只有"在用 → 删除"这一步才发删除通知，而且和状态变更写在同一个事务里
            msgEvents.insertAll(
                listOf(
                    MsgEvent(
@@ -105,7 +105,7 @@ class FdelProcessor(
                ),
            )
        }
-        procState.markTerminal(head.msgId, ProcStatus.SUCCEEDED)   // 未命中 = 迟到/重复，幂等成功（§3.3）
+        procState.markTerminal(head.msgId, ProcStatus.SUCCEEDED)   // 没删到东西说明是迟到或重复报文，照样算成功
        ApplyResult.Succeeded
    }
 }
@@ -137,7 +137,7 @@ class AdftProcessor(
            lock.lock()
            val main = flightState.findMainRow(record.flid)
            if (main != null && main.state == FlightState.DELETED) {
-                // §3.3 重激活：DELETED → ACTIVE，推进版本，登记状态事件
+                // 已删除的航班重新激活：状态改回 ACTIVE、版本号加一，并登记状态事件
                if (flightState.revive(record.flid, msgId = head.msgId, now = Instant.now())) {
                    val current = flightState.loadFullSnapshot(record.flid)
                    if (current != null) {
@@ -152,11 +152,11 @@ class AdftProcessor(

            val current = flightState.loadFullSnapshot(record.flid)
            val next: FlightSnapshot = if (current == null) {
-                // 新实例建立：ADFT 含 SODT 时直接计算运营日（§2.1），不可算则置 null 待日计划收录
+                // 新建航班：带了计划时间就算出运营日，算不出来先留空，等日计划报文来收录
                val day = opDay.compute(record.scalars["SODT"])
                FlightSnapshot(
                    flid = record.flid,
-                    operationDay = day,   // §2.1：不可算时不得默认写接收日
+                    operationDay = day,   // 算不出来就留空，不能默认拿收报当天顶上
                    state = FlightState.ACTIVE,
                    stateVersion = 1L,
                    scalars = record.scalars,
@@ -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,
@@ -76,7 +76,7 @@ class ScheduleProcessor(
        val body = msg.body as? ScheduleBody ?: return ApplyResult.DeadProtocol("missing-schd-body")
        val started = System.nanoTime()

-        // 重放判定：MSG_ID 已有成功终态 → 幂等成功（flight-state.md §4），重放也记留痕
+        // 这条消息以前处理成功过：直接算成功，不重复写数据（留痕照样记一条）
        if (procState.findSuccessTerminal(head.msgId)) {
            logSnapshot(head, body, SnapshotResult.REPLAY_SKIPPED, upserted = 0, flags = emptySet(), started)
            return ApplyResult.ReplaySkipped
@@ -123,7 +123,7 @@ class ScheduleProcessor(
                    val record = body.records.first { it.flid == flid }
                    val existingMain = mains[flid]
                    val keepDeleted = existingMain?.state == FlightState.DELETED
-                    if (keepDeleted) flags.add(SnapshotFlag.SCHD_REVIVE_CONFLICT)   // §3.3：日计划不复活 DELETED
+                    if (keepDeleted) flags.add(SnapshotFlag.SCHD_REVIVE_CONFLICT)   // 日计划不会让已删除的航班复活
                    val current = if (existingMain != null) flightState.loadFullSnapshot(flid) else null
                    val next = FlightStateEngine.snapshotState(
                        current = current,
@@ -151,7 +151,7 @@ class ScheduleProcessor(
        }
    }

-    /** 状态事件：KAFKA_SCHD 整态 + KAFKA_MSG 变化通知（flight-state.md §3.1 登记、§5 语义）。 */
+    /** 每次航班状态变化登记两个事件：KAFKA_SCHD 发完整状态，KAFKA_MSG 发一条变更通知。 */
    private fun snapshotEvents(next: FlightSnapshot): List<MsgEvent> {
        val payload = linkedMapOf<String, Any>(
            "flid" to next.flid,