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
@@ -20,9 +20,12 @@ import java.time.Instant
import java.time.ZoneOffset
/**
* 回填通道不变量(docs/message-lifecycle.md §3/§4/§5.2/§11
* 终态即刻补写、失败退避重试、超期期限 R 覆盖退避、标记单调只写空标、
* 中间态不适用、回填失败不回改终态、重启后扫描不依赖内存状态。
* 回填环节的规矩
* - 处理完马上写标记,写不进去就按退避重试,重启后接着重试(状态都在数据库里);
* - 等得太久的消息无视退避强制补写,保证标记最终一定会写上;
* - 只写还没有标记的行,已有的值不覆盖;
* - 还没处理完的消息(PENDING / FAILED)不许写标记;
* - 回填失败只是回填的事,不会把处理结果改回去。
*/
class BackfillServiceTest {
@@ -25,9 +25,9 @@ import org.junit.jupiter.api.Test
import java.time.LocalDate
/**
* FDELdocs/flight-state.md §3.3+ ADFT(§3.3/§2.1)不变量:
* ACTIVE→DELETED 发布一次 tombstone 且明细保留;重复/迟到 FDEL 幂等不推进版本;
* ADFT 重激活恢复 ACTIVE;新实例建立;缺失标量不误删(§3.3 保守 Set-only
* 删除与异常航班处理的规矩:删除在用航班时只发一次删除事件、明细保留;
* 重复迟到的删除报文算成功但不推进版本;ADFT 能把删除过的航班重新激活、
* 也能新建航班;报文没带的字段不会被清空
*/
class FdelAndAdftProcessorTest {
@@ -31,9 +31,9 @@ import org.junit.jupiter.api.Test
import java.time.LocalDate
/**
* 日计划主链路(docs/flight-state.md §3.1/§4)不变量:重放幂等、整包校验失败
* DEAD(PROTOCOL)、归属日冲突不落地、DELETED 不恢复且记冲突告警、
* 成功路径版本推进 + 事件 + 留痕 + 待办预登记
* 日计划处理的几条规矩:重复消息不重复写数据;整包校验不过就整包不落地;
* 航班运营日对不上时整包拒绝;已删除的航班不因为日计划又活过来;
* 正常路径要推进版本、发事件、留痕,并把终态和回填待办一起写在同一事务里
*/
class ScheduleProcessorTest {