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:
@@ -7,16 +7,20 @@ import com.gzzn.omms.msgexchange.infra.persistence.ProcStateRepository
|
||||
import jakarta.inject.Singleton
|
||||
|
||||
/**
|
||||
* ProcState 侧统一失败迁移(U08/U10):处理/快照路径共用——
|
||||
* attempts+1 后若 exhausted → DEAD(EXHAUSTED)(终态 + 回填意图,errorClass 规范化,原因保留在 lastError);
|
||||
* 否则 FAILED + attempts + nextAttemptAt(退避)(可重放)。任何“失败”都不得在无退避下直接终态化。
|
||||
* 处理失败时统一改状态,主泵和快照路径共用。
|
||||
*
|
||||
* 规则很简单:失败次数 +1 之后
|
||||
* - 还没到上限:改成 FAILED,并按退避表算好下次重试时间(这种记录以后可以重放);
|
||||
* - 已经到上限:改成 DEAD(EXHAUSTED) 终态,等人工复核,不再自动重试。
|
||||
*
|
||||
* 失败一定先退避、再重试,不允许一次失败就直接判死。
|
||||
*/
|
||||
@Singleton
|
||||
class ProcFailure(
|
||||
private val procState: ProcStateRepository,
|
||||
val scheduler: FailureScheduler,
|
||||
) {
|
||||
/** @return 是否已达终态(DEAD 才是终态;FAILED 仍可重放/重试) */
|
||||
/** @return 是否已经落到终态:DEAD 是终态,FAILED 还会再试 */
|
||||
fun fail(head: ProcState, ec: ErrorClass, reason: String): Boolean {
|
||||
val attempts = head.attempts + 1
|
||||
if (scheduler.exhausted(attempts)) {
|
||||
|
||||
Reference in New Issue
Block a user