cdia/msgexchange-v2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
170 Commits 1 Branch 0 Tags
2c3d6af30916ffafba54d60659221dfeb359db43
Commit Graph
71 Commits
Author SHA1 Message Date
windyboyandCursor 2c3d6af309 feat(processing): 领域/投影/终态三步提交与 FlightProjectionPort（ACM2-79） 
PIPELINE_LOCK 跨 Redis 写；MSG_EVENT HELD→PENDING；Redis 失败不终态不投递；V3 迁移。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-21 15:24:34 +08:00
windyboyandCursor 891088235c feat(ingress): 按处理时间为空扫描信箱，移除水位消费（ACM2-78） 
readUnprocessed 替代 ID 水位；去掉 INBOX_CURSOR/cutover-watermark/max-commit-delay 及相关健康与指标。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-21 14:49:40 +08:00
windyboyandCursor 23b74ed554 fix(processing): Wave1 — IgnoreRules/ROUT截断/Q9文档/schd FLTR 数组（ACM2-94/88/81/96） 
REGN/RSTA/EROR 退出忽略清单；ROUT/ERUT 升序留 4 且不落 SCAT/SCDT；C-1/Q9 统一库方清除；flushSchd 聚合成无 key 的 FLTR 数组。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-21 14:18:40 +08:00
windyboyandCursor d298fcc48f fix(delivery): claimBatch 排除已暂停 FLID，避免投递饿死（ACM2-95） 
同 FLID 事件占满 delivery-batch 时后续轮次不再重复领到同一批；补饥饿回归用例。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-21 14:11:53 +08:00
windyboy f9d51399da fix(flight): 历史清理判据对齐 US-14 AC2 五类已结束条件（ACM2-91） 
- HistoryRules.isEnded 共享求值器：计划超 3 天/取消超 1h/离港/到港；JDBC 与 stub 同源不漂移
- 删除无依据的 idle/deleted/terminal 三个窗口（reference.md 四行冲突参数重写为 AC2 口径）
- 备降条件依赖 FDIV（DDES/DDIR），落地（Q3、ACM2-100）前显式不命中，参数先行登记
- 修「当日」取系统时钟的缺陷，改由传入 now 推导（测试抓出）
- implementation.md 12.5 与配置、yml 同批对齐
 2026-09-21 13:39:18 +08:00
windyboy 1d95926e06 feat(jobs): PROC_STATE 终态行到期清理（ACM2-82） 
- 新增 deleteExpiredTerminal：仅删终态 + BACKFILL_AT 非空 + UPDATED_AT 超期的行（US-11）
- ProcStateCleanupJob 每轮 tick 执行，与人工重放共用 MessageLifecycleGate，不持 PIPELINE_LOCK
- 登记参数 msgx.pipeline.terminal-retention（默认 90d，暂定）进 reference.md
- Stub 与 JDBC 实现同口径；补四类候选条件回归
 2026-09-21 12:52:26 +08:00
windyboy 477f038cc1 feat(config): 配置值非法无条件拒启，登记启动必需配置清单（ACM2-97） 
- 新增 PipelineConfigCheck（@Context）：退避档位/播种取值校验不再等 autostart（CLM-7、OPS-1）
- OperationDayZoneCheck 扩展 cutoff-hour 0-23 校验
- reference.md 新增「启动必需配置与显式开关」：必需清单、缺值路径、显式开关与运行时故障的边界
- PipelinePropsBindingTest 补一致退避档位；补非法值/范围用例
 2026-09-21 12:46:47 +08:00
windyboy 9bf879ff76 feat(metrics): 投递失败与死信可观测指标，修 flushSchd 首次失败原因丢失（ACM2-98） 
- PipelineCounters 按 target 累计发送失败；Dispatcher.retryOrDead 记账（OPS-2）
- 新增 deadByTarget 查询与 DeliveryDeadSnapshotProvider（TTL 缓存），死信存量按 target 暴露
- /metrics 注册 send_failures.total{target} 与 dead{target}，登记进 reference.md「指标与健康」
- flushSchd 失败改记真实异常原因，不再退回固定 send-failed
 2026-09-21 12:40:53 +08:00
windyboy a1c56f546f fix(delivery): 删除通知只登记 KAFKA:msg，schd 不再发 tombstone（ACM2-87） 
- FdelProcessor 移除 schd TOMBSTONE，仅保留 msg 删除通知（C-9）
- HistorySweepJob 补发的清退通知由 schd TOMBSTONE 改为 msg 删除通知
- msg value 形态沿用现状（deleted:true JSON），待 Q5 定稿不改成 null tombstone
- 同步修订 FdelAndAdftProcessorTest / HistorySweepJobTest / HistorySweepPurgePgTest 断言
 2026-09-21 12:31:02 +08:00
windyboy df087c7933 fix(delivery): msg 队头失败或退避只暂停同 FLID，不阻塞其他航班（ACM2-95） 
- drainKafkaMsg 按分区键维护本轮暂停集：队头失败/退避未到期仅停该 FLID（D2）
- 同一 FLID 内仍严格按 EVENT_ID 保序不越队
- 补三条用例：失败仅停同 FLID、退避未到期仅停同 FLID、同 FLID 跨轮保序（TestClocks 无 sleep）
 2026-09-21 12:26:09 +08:00
windyboy 0e09365cf6 fix(codec): CHDT 类字段统一为 SIS 口径 CCLS/CTYP（ACM2-90） 
- ChdtXml wire 绑定与 SisWireMapper 映射键改为 CCLS/CTYP（implementation.md「动态运行事件」）
- 新增 V2 迁移将自有 PG FLIGHT_CHUTE 列 chcls/chtyp 更名为 ccls/ctyp，不动已发布的 V1
- FlywayMigrationTest 更新迁移链断言并校验更名后列；补 CHDT 解码→合并往返用例
 2026-09-21 12:20:50 +08:00
windyboy 29465e2131 fix(codec): FLOP 子类型白名单，白名单外 STYP 落 Unsupported（ACM2-84） 
- kindOf FLOP 分支仅放行现行七类（US-05 AC1），FDEL 独立分派不受影响
- 白名单外子类型（ACTT/CNCL 等 Q3 闭合目标）解码为 Unsupported，经 ACM2-83 路径记 SKIPPED、不改航班
- 补 codec 白名单回归与处理层「跳过且不触碰航班」用例
 2026-09-21 11:44:43 +08:00
windyboy 3c577b4d1e fix(processing): 合法不支持类型改记 SKIPPED 终态，参考数据单列 RefData（ACM2-83） 
- MsgKind.RefData 承接 SIS:3.1~3.14 类别码，白名单分派对齐 implementation.md
- Unsupported 由 FAILED(UNSUPPORTED) 重试改为 SKIPPED(unsupported) 终态（US-03 AC2）
- RefData 在 ReferenceDataProcessor 实装前保持可重试失败，不被吞为跳过
- 同步更新 IgnoreBranchTest / PipelineSmokeTest 旧断言，补 codec 分派回归
 2026-09-21 11:41:34 +08:00
windyboy 2bd650a551 docs(acm2-75): 清理空转待决项并对齐全仓旧编号引用 
- 删 Q2/Q15/Q19/Q20：时钟偏斜不进判据、实现自定已是结论、原文留存已定、
  运营日冲突处置已由 DEAD(PROTOCOL) 定
- Q6 的 abdg 定案本版不提供；Q22 改为 13 类报文到 admin-api 实体表组的映射
  （REF_MASTER 单表口径退位）；Q23 收窄为 SODT+FLID 幂等重试
- C-1 自清口径四方同步（requirements 非目标、US-03 AC2、architecture §6）
- INV-2 吸收回填只写空值；§7 恢复 G-RESP-GUARD
- architecture/implementation/README/V1/oracle/Kotlin/seed 中 40+ 处旧编号
  按映射重指，check-docs 全绿
 2026-09-20 07:13:20 +08:00
windyboyandCursor dc1c49af6e docs(acm2-75): 精简不变量与声明边界，去掉无依据条目 
审改 specification 管道/航班域/投影与 CLM：作废与需求重复或依据不足的 INV/CLM，白话重写保留条款，并同步架构、实现与引用注释。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-16 17:26:49 +08:00
windyboyandCursor fd65bb24fb docs(acm2-75): 按需求与架构收口契约和规范 
补齐接口契约的入站、Redis 与出站边界，规范对齐已定语义并作废过期条款；Kafka 生产端约束编号改为 D2。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-16 08:49:19 +08:00
windyboy cedd859bdf docs(acm2-74): consolidate design documentation 2026-09-13 20:31:13 +08:00
windyboy 800d7617f2 chore(db): 压缩 Flyway 迁移链为单基线 
原 V1–V10 的净结构全部合并进 V1__flight_state_baseline.sql，迁移链收敛为一条。
表集合、逐列类型/非空/默认值、表级约束、索引与种子行经重放比对与旧链条一致；
仅丢弃 5 条只对既有库有意义的存量数据语句（RECEIVED_AT/ENQUEUED_AT 回填、
schd 与开放请求去重、SENT_AT 回写）。

已按旧链迁移过的库版本链与校验和对不上，必须重建 schema 或删除数据卷后重跑，
禁止手工 repair 或改写 flyway_schema_history。

- 删除 V2–V10 共 9 个迁移文件
- 注释统一范式并改用稳定 ID（INV-x/C-x/G-x），修正 KAFKA_MSG/KAFKA_SCHD 与实际值不符
- 同步 docs/reference.md、docs/user-stories.md、oracle11g/README.md、README、application.yml、compose.yaml
- FlywayMigrationTest 改为断言单基线，并补 MSG_EVENT.SENT_AT 覆盖
 2026-09-13 16:31:14 +08:00
windyboy 62f61ad9e4 feat(delivery): 真实 Kafka 投递端口 + 闭合 G-BACKFILL-BACKOFF 配置缺口 
- 新增 KafkaDeliveryPort：ProducerRegistry + 同步 Future.get() 至少一次投递，
  闭合 OPS-1 真实适配器要求与 US-07 INV-10/C-29
- 回填退避从硬编码 30s/15min 提升为 backfill-backoff-ms / backfill-backoff-cap-ms
  配置绑定，闭合 [G-BACKFILL-BACKOFF]
- 删除死依赖 micronaut-redis-lettuce（代码零引用，ACM2-28 Redis 已退出阶段 A）
 2026-09-13 16:26:03 +08:00
windyboy fc744d0cfd feat(acm2): 闭合 G-KAFKA-D3 / G-IGNORE / G-EVENT-RETENTION 三个缺口 
- G-KAFKA-D3：max-in-flight 默认收敛到 1，KafkaD3Check 启动自检钉住三项联合满足 D3
- G-IGNORE：IgnoreRules 在身份绑定后精确匹配 TYPE 字段，命中写 SKIPPED + 回填意图
- G-EVENT-RETENTION：V10 迁移加 SENT_AT 列，投递原子写，EventCleanupJob 有界清理过期 SENT 行
 2026-09-13 15:48:16 +08:00
windyboy 17a4bfe91b feat(codec): 观测未落库的 SRVT/VIPF 集合 
SRVT/VIPF 只保留在 wire/domain 并计数告警，不落明细表、不参与合并：
出现事实不再被静默丢弃，为 Q13 定案提供真实流量证据（[G-SRVT-VIPF]）。

- wire DTO：SRVT/SERVICEDATA、VIPF/VIPDATA 与嵌套 VIPT（OPER 为元素属性）
- 出现即留键：缺席与"出现但为空"不再等价；已落库 10 类集合语义不变
- 新增 msgx.pipeline.codec.srvt_seen.total / vipf_seen.total（reference.md 已登记）
- 一并提交此前的 MAFL 文档改动（INV-21/INV-22、flight-state §2.3、G-MAFL 措辞）
 2026-09-13 09:21:51 +08:00
windyboy b8738554e6 refactor(ingress): 移除 G1 窗口补偿扫描与迟到到达检测 
实际负载不足 10 条/秒，G1 属过度防御。删除迟到到达检测机制、
existingIds 接口、PipelineCounters 字段、lateDetect 配置，
以及文档中 CLM-1/CLM-2 声明与 G1 缺口索引。
 2026-09-13 08:08:43 +08:00
windyboy 267eb20219 feat(jobs): expose last job failure time 
JobActivity 记录最近失败时刻并进入快照；JobRunner 失败时上报该时刻；新增指标 msgx.pipeline.job.last_failure_age_seconds 与健康明细 lastFailureAgeSeconds（对齐 reference 作业健康口径）。

验证：./gradlew test 145 tests / 0 fail / 0 skipped。
 2026-09-12 20:56:41 +08:00
windyboy 8a380c7646 refactor(config): drop system-time defaults from domain and entry points 
删除会被误用的系统时间默认值：MsgEvent.createdAt、ProcState.updatedAt、InboxPoller.pollOnce(now)、HistorySweepJob.run(now)、Identity.of(day)。Identity 的日期边界改由 MessageProcessor 按 PARAM:msgx.operation-day.zone 算出后传入（边界关闭时身份值不变）；StubProcState/StubInbox 改注入 Clock（测试可传假时钟），全部调用点显式传时间。

验证：./gradlew test 145 tests / 0 fail / 0 skipped。
 2026-09-12 20:56:41 +08:00
windyboy 4b71b5bb09 feat(jobs): expose job heartbeat and scan backlog 
新增 JobActivity 持有作业心跳与扫描积压，JobRunner 每轮 tick 上报（失败只计数、不刷新心跳），PipelineMetrics 注册 msgx.pipeline.job.heartbeat_age_seconds / ticks.total / failures.total / last_sweep_selected，新增 JobRunnerHealthIndicator（未启动 UP 并标 started=false；已启动但心跳缺失或超过 3×扫描周期 DOWN）。对应 reference 作业健康段与 [G-JOB-HEARTBEAT]。

验证：./gradlew test 145 tests / 0 fail / 0 skipped（新增 JobRunnerTest 2、JobRunnerHealthIndicatorTest 4、PipelineMetrics 指标注册 1）。
 2026-09-12 20:52:24 +08:00
windyboy ab18e4ec3f test(jobs): verify purge rollback on real postgres 
新增 HistorySweepPurgePgTest（Testcontainers 本地 PG）：归档确认后删除阶段注入失败，验证同事务登记的 tombstone 随事务回滚、当前态保留（INV-17/INV-18）。
 2026-09-12 20:45:41 +08:00
windyboy 15c035182f test(delivery): verify schd upsert on real postgres 
新增 JdbcMsgEventUpsertPgTest（Testcontainers 本地 PG）：单行只进不退、旧版本被拒、同版本 tombstone 胜出且不可复活、条件确认旧代次 0 行/当前代次 1 行、DEAD 行被更高代次替换后单行 PENDING 且错误清空。此前该 SQL 无任何执行覆盖。
 2026-09-12 20:45:41 +08:00
windyboy 5beb67dadb fix(ingress): preserve compat receipt semantics 
接收结果边界改为 insertRaw 是否返回 ID：接收时间读取失败回退注入 Clock 并留痕，PG insertIfAbsent 失败只记日志与 pgEnqueueFailures 计数，不再冒泡成 HTTP 失败（避免客户端重试多写信箱行）。缺的 PROC_STATE 由收报轮询按 US-01 补建且只建一条（INV-1），入口高 ID 仍等水位追平（INV-4）。

验证：./gradlew test 135 tests / 0 fail / 0 skipped（新增 InboxServiceTest 4 例：读时间失败+入队失败仍返回同一 ID、接收时间 NULL 回退时钟、真实插入失败仍失败且无伪造 ID、轮询对失败入队补建且仅一条）。
 2026-09-12 20:43:11 +08:00
windyboy 46e901fd44 fix(jobs): recheck archived flight version before purge 
HistorySweepJob 归档成功后进 PIPELINE_LOCK 事务，按 (FLID, STATE_VERSION) 用同一判据复查，仍合格才登记 tombstone 并删除；purgeArchived 改收候选而非裸 FLID 列表，并带 (flid, state_version) 删除守卫。事件与删除同事务提交或回滚（INV-17、INV-18）。

验证：./gradlew test 131 tests / 0 fail（新增「归档后主泵更新同一 FLID → 不删、不发 tombstone」用例）。tombstone 与删除的回滚原子性依赖真实 PG 事务，本机无 Docker 时无法执行。
 2026-09-12 20:40:32 +08:00
windyboy 592079055f fix(delivery): drop redundant schd event index 
V9 追加删除已无消费者的 idx_evt_flid（读端不再按 (PARTITION_KEY, STATE_VERSION) 合并），并在最终 schema 断言其不存在；新增用例覆盖 schd DEAD 行被更高合法代次替换为单行 PENDING、错误字段清空、旧代次不得复活。

验证：./gradlew test 130 tests / 0 fail。
 2026-09-12 20:39:15 +08:00
windyboy d21555091f fix(delivery): upsert latest schedule event 
KAFKA:schd 收敛为每 FLID 单行：V9 先按 (STATE_VERSION DESC, EVENT_ID DESC) 收敛存量再建部分唯一索引 uq_schd_event；写入走带谓词的单行 upsert（只进不退、同版本 tombstone 优先、接受新代次即换 EVENT_ID 并重置 PENDING/清旧错误）；读取不再 DISTINCT ON；成功确认改按 (EVENT_ID, STATE_VERSION, PENDING) 条件更新，删除 Dispatcher superseded 清理循环。msg 路径不变。

验证：全量 ./gradlew test 129 tests / 0 fail（新增 3 个用例：单行只进不退、同版本 tombstone 不可复活、发送期间新代次保持 PENDING）。V9 的存量收敛/索引与 upsert SQL 需真实 PG，本机无 Docker 时 FlywayMigrationTest 跳过。
 2026-09-12 20:38:18 +08:00
windyboy 21739a439d fix(infra): enforce one open request 
新增 V8 部分唯一索引 uq_req_open：(REQ_TYPE, OPERATION_DAY, SENDER) 仅在 PENDING/SENT 唯一；建索引前用 DO 块检测存量重复组并以带业务键的异常中止迁移，禁止静默删数据。保留 idx_req_open 服务含关闭态的查询；不引入运行时协调器（归 US-08）。

验证：全量 ./gradlew test 126 tests / 0 fail；索引与拒绝第二条开放请求的断言在 FlywayMigrationTest（需真实 PG，本机无 Docker 时按既有 assumeTrue 跳过）。
 2026-09-12 20:35:58 +08:00
windyboy 9554b1aae8 fix(config): fail fast on invalid operation-day zone 
运营日时区只认 PARAM:msgx.operation-day.zone：JobRunner、HistorySweepJob、JdbcSnapshotLogRepository.purgeBefore 改走注入的 OperationDayProps；ScheduleProcessor/AdftProcessor 删除「非法值回退字面量」；新增 @Context 启动自检 OperationDayZoneCheck，配置错位在启动时暴露。

验证：./gradlew test 126 tests / 0 fail（新增 OperationDayPropsTest 覆盖合法解析与非法即失败）。
 2026-09-12 20:34:56 +08:00
windyboy a89755c200 fix(processing): clear replay error state 
人工重放把 FAILED/DEAD 拨回 PENDING 时，与 attempts/next_attempt_at 一起清空 error_class 与 last_error，使活动状态不携带上一轮失败结论；identity_key、白名单与 MessageLifecycleGate 不变。

同语句同时改 JDBC 与内存实现，避免两套行为漂移。验证：ReplayServiceTest 3/0、InboxLifecycleJdbcSqlTest 8/0（H2 真实 SQL）。
 2026-09-12 20:32:27 +08:00
windyboy eb103d6244 refactor(processing): remove unused processing start field 
processing_started_at 没有任何判据消费（终态只看尝试上限），删除字段、仓储接口与方法、主泵写入、重放清理、SELECT/映射与 H2 fixture，并新增 V7 DROP COLUMN；V1–V6 历史迁移不动。

验证：./gradlew test 123 tests / 0 fail；V7 的 DROP 与最终 schema 断言需真实 PG，本机无 Docker 时 FlywayMigrationTest 按既有 assumeTrue 跳过。
 2026-09-12 20:31:23 +08:00
windyboy 161914eeb8 fix(processing): keep exhausted failures terminal 
ProcFailure.fail 在 markTerminal 后继续执行 update(FAILED)，把 DEAD(EXHAUSTED) 覆写回非终态。改为耗尽分支写完终态即返回，保持 INV-6 终态不可逆与 INV-8 回填意图同语句。

回归：ProcFailureTest 覆盖临界次数保持 DEAD、不可回退 FAILED，以及非耗尽退避。
 2026-09-12 20:29:23 +08:00
windyboy 817236ca26 fix(processing): 落地 D1/D5/D6 三项裁决，删除 head-deadline 参数 
D5（终态判据只保留尝试上限）：
- Pump.tick 内联 attempts 判定，删除 head-deadline 相关的毒丸分支与滞留告警代码
- 删除配置项 head-deadline（PipelineProps / application.yml）与 PumpDeadlineTest
- PROCESSING_STARTED_AT 变为只写，注释如实说明当前无判据消费它

D1（回填放弃判据改为时间）：
- 暂时性故障在 R 之前只退避重试，不再按尝试次数放弃；到 R 才放弃并记 TRANSIENT_DEADLINE
- backfill-max-attempts 降级为单行重试的告警阈值

D6（超期判据改用本地入队时间）：
- 新增 V6 迁移：PROC_STATE 加 ENQUEUED_AT（回填存量后置为非空 + 默认）
- findBackfillDue 的谓词与 overdue 标记改比较 enqueued_at，不再用库方时钟的 received_at
- BackfillDue 增加 overdue；收报与兼容入口显式写入本地入队时间

文档同步：
- 清理 4 处 message-lifecycle.md 章节号死链（Pump/InboxService/PipelineProps/application.yml）
- 关闭 G-HEAD-DEADLINE、G-BACKFILL-ABANDON-BYTIME、G-ENQUEUED-AT 三条缺口登记
- reference/user-stories/README 与实现对齐

验证：./gradlew test ⇒ 122 tests, 0 failures, 1 skipped

Refs: ACM2-45
 2026-09-11 20:44:30 +08:00
windyboy a84751bf03 fix(jobs): 留痕清理独立接通历史存储开关；精简死逻辑并对齐陈旧注释 2026-09-11 14:26:44 +08:00
windyboy d909a88167 fix(codec): 解码映射失败产出 CODEC_ERROR，落实退避重试与可重放白名单 2026-09-11 14:25:42 +08:00
windyboy 1e75a81107 fix(pipeline): 修复取报-处理-回填链路的超时、吞吐、回填与 FIFO 问题 
外部调用（ACM2-33）
- 共享 MySQL 与自有 PG 全部补有界超时：驱动 connect/socket 超时 + Hikari 池超时
  （注意 Micronaut 的 Hikari 项是毫秒数，不是 Duration 字面量）
- 删除主泵/毒丸路径的 inline 回填：跨库写不再占用 FIFO 关键路径，回填统一由扫描驱动
- 游标自愈：save() 改为「先 UPDATE、缺行 INSERT」，缺行只记一次 ERROR
- Pump/Dispatcher 外层 catch 补 error 日志与失败计数

投递吞吐（ACM2-34）
- Dispatcher 改批量领取；队头退避未到期或首条发送失败即停止本轮（保持目标内保序）
- 有活不再 sleep；删除不可达的 state==SENT 死条件；markSent 移入分支；
  superseded 清理加轮数上限与空 eventId 保护

回填闭环（ACM2-36，V4）
- MISSING（运行时确认行不存在）立即放弃自动重试并告警；暂时性故障达上限后停止自动重试
- 新增 reopen 人工恢复入口；放弃 ≠ 标记已确认（BACKFILL_AT 仍为空，清除前提不成立）
- 扫描改 (BACKFILL_ATTEMPTS, MSG_ID) 公平轮转并排除放弃行，消除全局回填饥饿
- V4 只加字段与必要索引，不按年龄做任何存量推断

切流播种（ACM2-35，V5）
- cutover-watermark 四模式（min/zero/max/显式 ID），默认不播种、代码不做默认选择
- 升级实例拒绝重新播种（SEEDED_AT 为 NULL ≠ 从未消费）；播种与水位同语句落库
- 非法取值由启动自检挡下

错误分类与入口契约（ACM2-37）
- 未知 SCHD 子类型改为 UNSUPPORTED，不再静默当全量日计划合并
- ADFT 运营日冲突改走 ProtocolViolation → DEAD(PROTOCOL)
- 兼容入口 receivedAt 缺失回退到注入 Clock；MessageLifecycleGate 强制注入 + 装配断言
- FIFO：主泵只领取 msgId ≤ W，兼容入口登记的行在水位追平前不被领取

时间源与可观测（ACM2-38 / ACM2-41 阶段 0）
- 仓储/处理器/作业全部经注入 Clock；移除 markTerminal/markBackfilled 的 Instant.now() 默认值
- 退避表档位与 max-attempts 对齐并加启动自检
- Micrometer 7 个 gauge（@Context 急切注册）+ /health 与 /metrics 共用积压快照缓存
- 只读迟到检测：监视被放行的空洞 ID 是否后来真的出现，只计数告警、不补入队

Plane: ACM2-33 ACM2-34 ACM2-35 ACM2-36 ACM2-37 ACM2-38 ACM2-41
Tests: 88 → 120（1 skipped 需真实 PG）
 2026-09-11 08:08:35 +08:00
windyboy eea11203a2 fix(processing): 收紧消息生命周期与投递约束 2026-09-10 20:39:22 +08:00
windyboy 1183c7522b docs(kdoc): 其余模块注释统一为直白说明 
把上一提交没覆盖到的模块也改完，至此仓库内不再有"只写编号、不写说明"的注释。

涉及 33 个文件（生产 24 + 测试 9），包括航班状态模型与合并引擎、事件与留痕模型、
运营日计算、投递器、历史归档作业、编解码与身份、重试与重放、健康指示器、
生命周期装配、以及各自的测试类。

改法与前面一致：先说这段代码做什么，再说为什么这么做，术语第一次出现就地解释
（FLID、OPERATION_DAY、航班版本号、删除通知、待发事件表等）。工单编号
（U07/N02/ACM2-10 之类）已全部移除；段落编号只剩 10 处，全部带文件名位于句尾，
用作延伸阅读，例如"见 docs/flight-state.md §5"。

保留了本来就自解释的行内注释、PgTestSupport 顶部的环境变量默认值表格，
以及 InboxController 里描述待补接口的 TODO。

校验：逐文件做"去注释后比对"（块注释 + 行注释清除、空白归一），33 个文件代码
零差异；另做逐行非注释代码比对，同样零差异。clean test 为 78 passed / 1 skipped。
 2026-09-10 11:14:11 +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
windyboy 99a0f5f738 refactor(flight-state): SCHD 日计划收敛为缺失保留合并语义并对齐现行设计文档 
按现行 docs/flight-state.md（111 行版，§1-§7）全面对齐 domain 包及其消费方，
删除整套指向已退役长版文档（§5.x-§10）的引用与死代码：

- 语义：FlightStateEngine.snapshotState 由"完整快照整体替换"改为 §3.1 合并语义
  ——出现 Set/Replace、缺失保留、标量空串显式清空；DELETED 不被日计划恢复（§3.3）。
- 校验：validateMessage 移除从未接线的报文覆盖范围（scope）参数，只保留 §4 步骤 2
  的声明数量/航班标识/运营日推导校验；ScheduleBody 删除 scopeStart/scopeEnd。
- 删除死代码：domain/Decision.kt、FlightModel 的 SnapshotPatch/UpsertOutcome、
  ProcState.isTerminal/archivable、SnapshotFlag.SEQN_REGRESSION、
  ScheduleRecord.seqn（及 wire FlightRecordXml.SEQN）；codec 移除未消费 FFID。
- 删除未接线且引用已退役列（fday/last_message_id）的 SqlDialect 方言脚手架，
  oracle11g README 改为按 V1 现列重建的口径。
- 注释/测试：domain、processing、infra 仓储与 jobs/delivery、配置类及对应测试的
  KDoc 章节引用全部对齐现行 flight-state.md/design.md；FlightStateEngineTest
  重写为合并语义（62/62 通过）。

V1__flight_state_baseline.sql 保留原样（内容注释仍带旧章节号，改动会破坏
已应用迁移的 Flyway checksum，待重建基线或 V2 净迁移时收敛）。
 2026-09-09 22:17:04 +08:00
windyboy 3ed54d306e refactor(codec): map SIS XML through annotated DTOs 2026-09-09 19:48:45 +08:00
windyboy 879d658159 refactor(flight-state): 按 flight-state.md 审计定稿全量重构脚手架与 SQL (ACM2-31) 
- SQL 基线 V1__flight_state_baseline.sql 整体取代 V1.0.0–V1.4.0：
  PIPELINE_LOCK/PROC_STATE/MSG_EVENT/REQ_TRACK/BACKFILL_TODO/FLIGHT_SCHD
  + 8 张资源明细表 + FLIGHT_ROUTE_POINT + SCHD_SNAP_LOG 留痕层
- 废除 FDAY 日代/SCHD_GEN/名单差删：OPERATION_DAY 不可变（应用层校验 +
  条件更新强化 §7.4），STATE 仅 ACTIVE/DELETED，物理清除只在历史归档后
- 处理器化：applyScheduleRecords（§5.1 七步同一事务，重放判定/整包
  DEAD(PROTOCOL)/归属冲突不落地）+ FLOP/FDEL/ADFT（tombstone 仅
  ACTIVE→DELETED，重复 FDEL 幂等不推进版本）
- 投递：KAFKA_SCHD 同 FLID 按最新 STATE_VERSION 合并，被压掉事件关闭，
  TOMBSTONE 发 null 值消息（键缺失=删除旧值 §7.3）
- 回填待办改为业务事务内预登记，消除提交后写待办的崩溃窗口（§7.2/§10）
- XML 解码改为 jackson-dataformat-xml 数据类直接映射（SIS 信封强类型，
  FLTR 开放标签泛型承载）
- 历史归档/物理清除顺序不可颠倒：归档确认成功集才物理删除，未接通删 0 条
- 移除 PUMP_JOB 队列/ReferenceService/FlightStoreDiffTool 等旧机制与测试，
  新增运营日/引擎/快照/FDEL/归档顺序不变性回归测试
 2026-09-09 17:53:08 +08:00
windyboy 2b112f527c docs: consolidate flight state design 2026-09-09 11:43:34 +08:00
windyboy 1fc2b2c895 fix(persistence): 差删先按 FDAY 圈定删除成员，修复保留航班明细误删 (ACM2-30) 2026-09-08 18:50:02 +08:00