windy/msgexchange-v2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
86 Commits 1 Branch 0 Tags
592079055ffbb98f60fa341a735f2099e11c64c4
Commit Graph
86 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
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 3f2a1be75b chore(processing): remove stale backfill comment 
BackfillService.attempt 前仍声称「处理完立刻试一次、调用方是主泵」，与类注释及「回填一律扫描驱动」矛盾；删除过时 inline KDoc，保留 @param 说明，运行时代码不变。
 2026-09-12 20:32:52 +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 3085431bea docs: 落地上轮复审修正并修正参考表位置 
- G-IGNORE 缺口表述去掉错引 INV-19、补 US-04
- reference 登记 msgx.pipeline.backfill-scan-period
- user-stories 的 R_keep 下界/deadline 措辞对齐
- reference 归档参数行从空行后挪回参数表内（修正 acm2-52 提交中的表格位置）
 2026-09-12 11:36:52 +08:00
windyboy dcdc5117bf docs(acm2-51): 收口 D10/D14/D15 
- D10 投递保序：architecture 改为 FLID 级（与 design/CLM-7 对齐，实现收敛归 ACM2-34）
- D14 REQ_TRACK 状态名：user-stories US-08 对齐实现的 PENDING/SENT/DONE/EXPIRED
- D15 容量假设：invariants 新增 CLM-10（未实测，含解除条件），design §10 加指针
纯文档，不改代码/迁移/配置/legacy。
 2026-09-12 11:33:58 +08:00
windyboy 69c2cf219f docs(acm2-52): 修正跨文档事实冲突 F1–F9 与错引编号 
- F1/F6 HTTP 契约：C-28 目标 ResponseDto + 请求体上限暂定 10MB，Q3 指向 C-28
- F2 legacy 与 SIS 的优先级限定；F3 超期判据对齐 ENQUEUED_AT；F4 改引 D1
- F5 参数默认值改引 reference/PARAM；F7 补 4 条契约状态词；F8 定义 MAID/MAFL 并明确排除共享航班；F9 补 INV-20
- N1/N2 错配编号改引；N3 迁移链指针；N4/M5 白名单补 D-x/OPS-x；N6 补 INV-16/17 映射；N7 加粗规则
- M1 回填退避事实与论证；M2 Q6/Q7；M4 Q4 假定标注；M7 去复述
纯文档，不改代码/迁移/配置/legacy。
 2026-09-12 09:57:26 +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 6eade95a97 docs: 拆分契约/前提/参数文档，合并消息生命周期并收敛设计裁决 
- design.md 合并 message-lifecycle.md（后者保留跳转 stub），去重并改用稳定 ID 引用
- 新增 invariants.md（前提/不变量/声明边界/验证映射）、contracts.md（对外条款与 Q 台账）、
  reference.md（参数/指标/模块/错误分类）
- architecture/flight-state/user-stories/README 同步重划引用；README 废止「引用章节号」
- 裁决收敛：R 按超期而非次数放弃、清除前提含放弃清单、航班表写者互斥、head-deadline 仅告警、
  超期判据用本地入队时间、投递批次读取时刻冻结、schd 只进不退与条件标记、FLID 复用为前提
- 删除 runbooks 与 CI 防漂移校验：设计阶段不产出面向执行期的产物

Refs: ACM2-42..51
 2026-09-11 15:48:14 +08:00
windyboy 632a5fe422 docs: 精简重复论证与过时流程表述，口径与实现双向对齐 2026-09-11 14:26:44 +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 fed0b5df26 docs: 同步取报-处理-回填链路的修复结论 
- 事务边界表：区分业务型/非业务型终态；回填改为扫描驱动（主泵不再 inline 回填）
- 符号与配置：补 delivery-batch / backfill-max-attempts / cutover-watermark /
  late-detect-* / backlog-cache-ttl-ms / 邮箱超时与指标口径
- 闭环状态：G2/G3/G9 标记已修；G1 标注「阶段 0 只读迟到检测已交付」
- 修正 R/R_keep 论证：R 不保护重放窗口；原文保留归 R_keep 与 Q7/Q9，
  并删除「由 SIS Expiry 推导提交时延」的无效推论
- 回填语义补全：四种结果、放弃 ≠ 标记已确认、公平轮转与饥饿说明
- 兼容入口与水位：登记行超出水位、水位追平前不被领取，并写明运维含义

Plane: ACM2-35 ACM2-37 ACM2-38 ACM2-39 ACM2-41
 2026-09-11 08:08:39 +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 b65728f312 refactor(ingress): 信箱连续上界遍历改用解构 
contiguousUpTo 由 row.msgId 改为 for ((msgId, _) in rows)；MailboxRow 是 data class，
取值结果相同，行为不变，无配置与迁移影响。

验证：./gradlew test 通过。
 2026-09-10 21:03:04 +08:00
windyboy 50e0e7f389 docs: 修复跨文档冲突与外部规范口径 
不动代码、配置与迁移，只收敛文档口径。

- 登记两项外部冲突：Q13 日计划缺失可选字段（SIS §3.16 注释 4 要求删除本地值，
  与现行"未携带字段保留"相反）、Q14 主/共享删除顺序与 EROR 回报义务
  （SIS §1.6.1-1.d / §4.8）；航班级"缺席不删"补 SIS §3.16 注释 1 依据。
- flight-state §3.3 补主/共享关联按 FLID 值比较的规则。
- message-lifecycle：§11 水位不变量与 §5.1 空洞老化自洽；删除过期的 updatedAt
  判据，统一为 PROCESSING_STARTED_AT + 可注入 Clock；§5.1/§6 补 SIS 480 分钟
  Expiry 与 legacy 1 天保留窗，作为 Q2/Q6/Q7 的取值参照。
- architecture/design：明细表口径统一为 8 张资源明细表 + FLIGHT_ROUTE_POINT；
  Oracle 11g 断言收敛为待适配验证；配置键按 application.yml 实际名称加 msgx. 前缀。
- user-stories：Q2/Q6/Q11 补外部锚点并收窄 Q11 到重置周期 + SNDR 值域；
  新增 Q13/Q14 并挂入 US-05/06/08 前置；五个独立事实改为引用 message-lifecycle §1。
- README/legacy：文档基线改为代码基线 eea1120 + git log 指引；补"外部协议冲突以
  SIS 为准"的维护规则；修正 /all/flights 过滤措辞；术语统一为「回填意图」。

验证：文档间章节引用 0 缺失、markdown 0 断链、SIS 引用小节全部存在、
Q1–Q14 正文与 Q 表双向可解析、代码块配对正常。
 2026-09-10 20:54:01 +08:00
windyboy eea11203a2 fix(processing): 收紧消息生命周期与投递约束 2026-09-10 20:39:22 +08:00
windyboy dd839e6abb docs: 统一生命周期与处理职责口径 2026-09-10 19:48:49 +08:00
windyboy 9fdb5ba6a5 chore: 纳入 agent 工具配置与忽略规则 
.gitignore：忽略 agents.state.json、.openagentpack/versions/ 与 .env——
后两者分别是工具运行状态和本地环境变量文件，都不应进版本库。

agents.yaml：agent 工具（bailian provider，qwen3.8-max）的配置。
密钥走 ${DASHSCOPE_API_KEY} / ${BAILIAN_BASE_URL} 环境变量占位，文件内不含明文凭据。

与本次信箱生命周期重构无关，单独提交以便回退。
 2026-09-10 11:15:49 +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 8c6bb83b62 docs: 同步信箱生命周期实现口径——§4 缺口收敛、水位空洞老化、回填事实并入 PROC_STATE 
message-lifecycle.md：§4 两个崩溃窗口随"终态与回填意图同体同行"消除（不再是缺口，改为
说明剩余未闭环项是回填跨库单写期间的持续失败）；§5.1 补空洞老化规则（自增回滚空位会使
水位永久停摆，超出最大提交时延即判永久并放行，只跳过空洞不越过已存在的行）；§5.2 补判据
机制（不依赖独立待办表，R 覆盖退避）；§3 表格改回填意图与"到期或已达 NOW − R"。
design.md：§2.1 表以 INBOX_CURSOR 取代 BACKFILL_TODO、PROC_STATE 责任补回填事实；
§3.1 收报改为按 ID 区间扫描且不以标记为谓词；§3.3 终态由处理器事务内落库、死信同样可
补写；§6.1 维护作业改为 BackfillService.sweep；§7 补 max-commit-delay/overdue-backfill/
backfill-batch 与 mailbox.processed-value；§8 验证表补"终态未回填不得阻断发现"与"意图随
事务回滚"；§9 入口表更新；§10 缺口两则改写为现状与待确认项。
architecture.md：§4 主流程第 1/3/4 步与 §3 存储表同步（水位、回填意图、单事务范围）。
flight-state.md：§2 对象表同步。user-stories.md：US-01/US-09 当前基础与落点改为实现现状、
Q2 口径改为"老化阈值待库方书面承诺"。
 2026-09-10 11:00:02 +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 ffd3abd655 docs: message-lifecycle 审查修正——消解跨文档冲突、口径归口并登记 Q12 
message-lifecycle.md：
- §5.3 日计划改为现行合并语义（缺席不删、缺失保留，引 flight-state §3.1），类型粒度统一 TYPE-STYP
- §5.1 明确两条扫描路径按 ID 区间取行、不以处理标记为谓词；水位定义与 Q2 绑定
- §4 两个缺口改与 design §10 同措辞；§5.2 的 R 构成挂 Q6/Q9，新增 Q12 积压跳过授权
- §6 方案 B 对账补“只补缺失行、标记单调不回退”；删除能力声明标注待 Q9 确认
- §7 改为“尚未实现”、统一 COUTMSGS_* 列名；§11 ID 不断链改为条件式不变量

user-stories.md：US-11 第 4 条限定为“本系统不写共享历史表/不清除外部信箱”；US-01 扫描谓词指向 lifecycle §5.1；US-01/09/11 前置补口径指针；新增 Q12；OPS-2 补积压与最老未处理信龄；Q10 列名统一。

architecture.md：共享 MySQL 红线限定主体；§6 中断恢复表改为指向 message-lifecycle §4；收报步骤补扫描谓词指针。

design.md：水位定义、回填死信处理、维护作业、归档、缺口恢复统一指向 message-lifecycle。

README.md：核对日期更新至 2026-09-10（代码基线 99a0f5f，文档基线 328bbf8）；维护规则补规范类文档一档。
 2026-09-10 09:00:53 +08:00
windyboy 328bbf88d2 docs: 新增 message-lifecycle.md——上游消息生命周期唯一规范（五事实/崩溃恢复/水位/超期补写/历史积压/信箱清除 A/B/出站契约），登记 Q9/Q10/Q11，README 索引与 architecture/design 指针补齐 2026-09-10 08:55:43 +08:00
windyboy 8068ed975b docs: 文档整理——统一 KAFKA 事件名与运营日术语，链接文字对齐标题，修复两处空行格式，README 补旧行为基线索引；主/共享级联语义上移至 flight-state §3.3 并增补 STATE_VERSION 不变量（architecture §9 引用同步改为 §3.1/§4/§7） 2026-09-10 08:16:31 +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 b75f566276 docs: 按代码现状收敛 architecture/design/user-stories 口径并对齐 flight-state 口吻 
- design.md：删除已退场 PUMP_JOB/Handler/Decision 等引用，改按 ScheduleProcessor 与
  DynamicProcessors 实际分派描述；补 PROTOCOL 错误类与 RESP 守卫缺口；实现入口与 §10
  差异清单按 HEAD 代码重写
- architecture.md：修正悬空章节引用；关键决策删减为仍具约束价值的 4 条并连续编号 D1–D4，
  补当前状态列
- user-stories.md：逐条更新 US 当前基础与落点，清理已不存在的文件与旧叙事，Handler 术语统一
- README.md：实现核对日期更新至 2026-09-09（基线 d53a0a1）

flight-state.md 与 docs/legacy/ 保持原样。
 2026-09-09 21:50:05 +08:00
windyboy d53a0a1c2f docs: remove retired schedule generation design 2026-09-09 20:22:10 +08:00
windyboy f6f9d6c6cb fix(codec): make XML annotation targets explicit 2026-09-09 19:53:37 +08:00
windyboy c688f08337 build(kotlin): stabilize annotation targets 2026-09-09 19:50:33 +08:00
windyboy 3ed54d306e refactor(codec): map SIS XML through annotated DTOs 2026-09-09 19:48:45 +08:00
windyboy c2d4a76e3e docs: flight-state 定稿唯一设计规范，移除 §10–§12 并落地评审修正 A–M (ACM2-31) 2026-09-09 19:28:14 +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 6af292d103 docs(flight-state): 移除对账账本并按三轮评审收敛删除与时序语义 (ACM2-31) 2026-09-09 15:40:54 +08:00
windyboy 9e434d6486 docs(flight-state): 重写当前态设计为简洁版并落定航班身份模型 (ACM2-32) 
按评审意见重写 docs/flight-state.md（603 → 332 行），去掉堆叠的补充说明，每条规则只保留一处：

身份模型：
- FLID 由 AODB 分配、与运营日绑定；同一 FLNO 不同运营日 = 不同 FLID
- OPERATION_DAY 一经确定不可变，跨日归属不符属协议异常（整包拒绝）
- 延误跨日不是迁移：同一 FLID、运营日不变，由 FLOP 继续更新
- 补齐 FDEL 删除入口（§2、§6.2）：按 FLID 删除并移出名单，不换代
- 代码共享与过站关联分离；物理列名 FDAY 统一改称 OPERATION_DAY

快照与差删：
- 11 步事务固定顺序；差删集合即 O − N，OPERATION_DAY = D 为删除前断言
- 覆盖范围按“是否单个完整运营日”判定：48 小时窗口只覆盖状态、不差删
- 完整快照字段缺失即清除（SIS §3.16 注释 2/4），只对本模块映射字段生效
- SEQN 仅用于同会话顺序观测，不启用陈旧拦截

其余：留痕 RESULT/FLAGS 分列、身份不变量六条、保留期默认 7/90/7 天、
未定事项与 SIS 规范依据各收进一张表（§10）。
 2026-09-09 14:54:54 +08:00
windyboy 2b112f527c docs: consolidate flight state design 2026-09-09 11:43:34 +08:00
windyboy 4449ee5dcc docs(flight-state): 按 2026-09-09 二轮评审修正设计文档，开放项锚定 ACM2-31 (ACM2-31) 
依据 ACM2-31 二轮外部评审逐条修正，待协议确认项已对照 SIS_AODB_RMS V0.1 佐证：

- 标注约定：区分规范要求与现状/未决披露，杜绝混作依据
- 航班身份：FLID≠航班号，FDEL+ADFT 换名时 FLID 可能不同（规范 §3.18），代码共享独立事件经 MAID/TAID 关联
- FDAY 三日期概念区分（业务日期/快照覆盖日期/名单归属日期）；跨日归属回迁列为未决（§3.3 约束 4）
- 规则 M 补成立条件标注（快照生成时点 + 投递顺序前提未逐条核实）
- 差删完整性前提引协议口径：单包不分段、RECS 记录数、完整快照注释（§3.16.1）
- 动态线集合全量/增量语义待逐类确认（CHOT CSNO 实为机位序号 §3.22.2），Replace 全集仅对快照线定案
- tombstone 澄清为自定义删除事件（非 Kafka 原生墓碑），删除版本/世代缺口开放
- 行锁表述纠正（跨实例同样生效，但不实现认领/选主/切换/FIFO）；Oracle 空串=NULL 为既定行为，验证目标改为字段语义保真
- ACTT 实际时间口径（进港 ATA/出港 ATD §3.20），修正示例字段名；FLOP 29 类改为规范 §3.19–3.43 实数；99 上限标注协议出处
- 语言修订：主泵/数据一致性比对/JSON 数组/整态替换措辞等；错误矩阵每类错误单一默认路径
- 开放项（回迁防护/动态集合语义/删除世代/幂等键/FIFO 参数/一致性读/TAOP 语义核对等）归集 ACM2-31
 2026-09-09 10:47:03 +08:00
windyboy bb81deae0a docs: 航班状态设计重写为当前基线，按请求/下载与动态两条线讲清状态变更 (ACM2-30) 2026-09-08 18:50:34 +08:00
windyboy 1fc2b2c895 fix(persistence): 差删先按 FDAY 圈定删除成员，修复保留航班明细误删 (ACM2-30) 2026-09-08 18:50:02 +08:00
windyboy 7c2d22e8f1 feat(persistence)!: V1.4.0 退场 legacy 槽位存储，persistNextStates 成为唯一写路径 (ACM2-29 P4) 
- V1.4.0 迁移：DROP FLIGHT_SCHD 全部 77 个槽位/里程碑/紧凑航路列（V1.3.0 起
  零写入、P2-2 起零读取）+ 三个与 PK 前缀冗余的 (flid) 单列索引；回退窗口关闭
  （对拍留档：P2-1 FS7 v2 双读差异记录）
- 接口收敛：FlightSchdRepository 删除 upsertSnapshotBatch/upsertIncremental，
  删除废弃 FlightStateRepository 及 Jdbc/Stub 适配器；仓储与装配器删除全部
  legacy flatten/slot/milestone/route 视图代码，ALL_COLUMNS 收敛为无损承载列
- FS7 对拍工具移除 diffDualRead（legacy 槽位基准退场）；diff() 对 legacy
  FLTR JSON 比对保留；FlightStoreDualReadTest 随工具移除
- 测试种子统一走 v2 写路径（support/SeedHelpers），GuardedFlightSchd 简化
- docs/decision-flight-state.md：头部复核入口更新 + 新增 §10 v2 落地终态索引，
  §1–§9 保留为历史记录

验证：MSGX_PG_PORT=5433 真实 PG 全量 100 用例 0 失败 0 跳过；无环境变量
Testcontainers 全新容器 V1.0.0→V1.4.0 迁移链 18/18 全绿
 2026-09-08 17:44:20 +08:00
windyboy 107be5d74a feat(infra): 数据库方言接缝 SqlDialect（PG 实装 + 11g MERGE 编译级交付）(ACM2-29 P3-B) 
- SqlDialect 接口：快照 upsert / 主行存在性保障两类方言敏感 SQL；
  PostgreSqlDialect 承接现有 ON CONFLICT 路径，JdbcFlightSchdRepository 已接入
- Oracle11gDialect：MERGE INTO 模板（编译级交付，未经目标库验证）——激活门控
  写入 KDoc：11.2 补丁 × JDK25 × ojdbc × Flyway(oracle11g location) × 连接池
  组合现场实测通过才允许切换，MERGE 绑定顺序适配随激活完成
- db/migration/oracle11g/README.md：11g 迁移位置占位与前置条件清单（CLOB 映射、
  空串=NULL 语义回归、display 视图 11g 版）

验证：MSGX_PG_PORT=5433 真实 PG 全量 108 用例 0 失败 0 跳过
 2026-09-08 17:10:40 +08:00
windyboy 35c91c67b9 test(integration): JDBC 集成测试 Testcontainers 兜底 + 全结构回环矩阵 (ACM2-29 P3-A) 
- PgTestSupport 三级解析：MSGX_PG_* 显式环境变量 → Testcontainers 自动起
  postgres:17-alpine 隔离容器（JVM 单例复用，docker 不可用才跳过）→ assumeTrue
  绝不误报通过；解决了「本机端口被占/无库则集成测试静默跳过」的验收假绿问题
- loadCollections 只输出非空属性（缺失键语义），write→read 线格式一致
- 新增 readAfterWrite 矩阵用例：16 类结构（多行/重复资源号/非连续源序号/异常
  前缀列/文本旁列）persist → findNextStateByFlid 深度等值 + wire(nextState) ==
  wire(readAfterWrite) 双断言（评审 F5 持久化侧+线格式侧闭环）

验证：MSGX_PG_PORT=5433 外接库 108 用例全绿；无环境变量 Testcontainers
自动容器路径 18/18 全绿
 2026-09-08 16:00:26 +08:00
windyboy 06a1081bdd test(migration): 带数据 V1.1→最新升级链验证 + DELY Apply 拒绝 (ACM2-29 P2-4) 
- FlywayMigrationTest 新增升级链用例：隔离 schema 迁至 V1.1.0、写入含
  *_TXT 的存量行、一路升级到最新——断言标量数据存活、v2 追踪列默认就位、
  display 视图/backfill_todo/明细表可用、*_TXT 列按已知损失边界消失（评审 F6：
  升级前必须导出或重放，测试固化该边界）
- L2 收尾：DELY 无协议序号属性（DLNO 非法）——SEQ_ATTR 移除 DELY，Apply 对
  DELY fail fast 拒绝（语义矩阵 §2 同步口径）
- 级联回归已在 P2-2 落地（deleteByFlids/deleteDiffByDay 明细级联断言）

验证：MSGX_PG_PORT=5433 真实 PG 全量 107 用例 0 失败 0 跳过
 2026-09-08 15:54:50 +08:00
windyboy 20aafb9ab0 feat(processing): 快照流程锁内复核收敛 + 异常显式清除语义 + 语义矩阵定稿 (ACM2-29 P2-5/M3) 
- SnapshotFlow 收敛到 v2 §5 事务顺序：锁外仅解析校验；取得 PIPELINE_LOCK 后
  锁内复核快照身份（last_message_id 重放短路）→ 锁内读代与当前航班态 →
  计算 nextState → 写入 → CAS → 事件 → SUCCEEDED。锁内 CAS 失败属数据异常，
  一律回滚 FAILED(INFRA)，删除「版本号相同即视为重放」的推断路径（评审 F7/F8 收口）
- M3/F4：异常对象（FDIV/FRET/FLAB）显式清除语义——null 字面量/空对象/空串
  翻译为 Clear 命令；FlightNextState.clearedKeys 携带本次清除键；增量路径按
  映射把前缀标量列置 NULL；库内清除后读视图无该键（线格式保持键缺失，显式
  清除表达留待阶段 2 按下游契约定）
- StubFlightSchd 增量分支改为 nextState 权威整体替换（引擎已合并当前态），
  天然承载 Clear；flattenScalarsOnly 去除冗余循环（L2）
- docs/flight-state-semantics.md：16 类结构语义矩阵定稿（P0-A 交付物落库）
- 新测试：引擎 0 标记/异常清除/混排 fail-fast 单测；JDBC 异常清除回环用例

验证：MSGX_PG_PORT=5433 真实 PG ./gradlew test --rerun-tasks
105 用例 0 失败 0 跳过
 2026-09-08 15:44:48 +08:00