 windyboy
|
eea11203a2
|
fix(processing): 收紧消息生命周期与投递约束
|
2026-09-10 20:39:22 +08:00 |
|
|
windyboy
|
6e7d819034
|
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 |
|
|
windyboy
|
d475feb790
|
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。
|
2026-09-10 11:05:55 +08:00 |
|
|
windyboy
|
09b53c77bb
|
refactor(ingress): 信箱边界层契约重构——发现与处理标记解耦、回填事实并入 PROC_STATE
收报扫描不再以 DATE_PROCESSED 为谓词：终态而未回填的行（解码失败死信等）会永久占据
有限批次，累积到 claim-batch 后收报整体停摆（US-01 条目 3 / message-lifecycle §5.3）。
ingress/InboxPoller.kt：按 ID 区间升序有界读取（ID > W），水位落 INBOX_CURSOR 并与入队
同一 PG 事务推进（中断后重扫补建）；遇空洞即停，空洞超过 pipeline.max-commit-delay 判定
为永久并放行——否则水位永久停摆于一次自增回滚留下的空位。删除 InboxEnqueue（改由
insertIfAbsent 幂等入队）与 poller 内的回填扫描（消除 ingress→jobs 反向依赖）。
infra/persistence：端口按事实重画为 readRange/maxId/markProcessedIfUnmarked，标记 UPDATE
带 DATE_PROCESSED IS NULL 守卫，只把空标写为已处理（§11 单调，重复执行无副作用）。
回填事实并入 PROC_STATE（RECEIVED_AT/BACKFILL_AT/NEXT_AT/ATTEMPTS/ERROR），BACKFILL_TODO
随 V2 迁移下线；终态与回填意图是同一条 UPDATE，由处理器在自己的业务事务内落库，
message-lifecycle §4 登记的两个崩溃窗口（提交后回填前崩溃、待办二次落账失败）不再是缺口。
processing/BackfillService.kt（取代 BackfillSweepJob）：终态提交后立即尝试一次，失败按
30s→15min 指数退避重试；扫描条件「终态 + 未确认标记 +（已到期 或 接收时间早于 NOW − R）」
使 §5.2 的超期期限 R 覆盖退避，中间态永不补写。死信同样可补写——回填只需消息 ID，
不再依赖 META。Pump 改用可注入 Clock。
infra/health：InboxLifecycleHealthIndicator 输出积压条数、最老未处理信龄、未回填终态数与
水位滞后（OPS-2 / §5.3 验收）。预计消化时长需吞吐采样，留待接入指标注册表时补。
配置：pipeline.max-commit-delay / overdue-backfill / backfill-batch、mailbox.processed-value
（Q2/Q6/Q7 未书面确认前取保守初值，不得为提速下调）。
不变量回归测试：死信不阻断后续发现、水位遇空洞即停与老化放行、终态+意图同事务、
超期 R 覆盖退避、中间态不补写、标记单调；InboxLifecycleJdbcSqlTest 以 H2 的 PostgreSQL
兼容模式直连验证上述 SQL 语义（不依赖 docker）。libs.h2 由 testRuntimeOnly 提为
testImplementation 以支持该用例。
验证：gradle clean test --offline → 78 tests / 0 failures / 1 skipped
（PG Testcontainers 集成用例在本机无 docker 时按既有约定 assumeTrue 跳过）。
|
2026-09-10 10:59:58 +08:00 |
|