msgexchange-v2/docs/spec-boundary-closure.md

精简实施方案

1. 本轮目标

关闭以下缺口：

1. [G-KAFKA-D3]：生产者配置满足 D3。
2. [G-IGNORE]：US-04 定义的忽略报文正常终结。
3. [G-EVENT-RETENTION]：已确认投递的事件不会无限增长。

依赖约束仅引用：D3、INV-7、INV-8、INV-9、INV-10、US-03、US-04。

2. 明确不做

本轮不实现：

• [G-BACKFILL-BACKOFF]：没有真实调参需求，保留现有退避算法。
• [G-PROC-HST]、[G-HST-RETENTION]：等待 Q6、Q7、Q9 定案后单独设计。
• [G-FLOP-IDEMPOTENT]：继续保持 INV-20、CLM-3 不可声明。
• [G-REQ-TRACK]、[G-MAFL]、[G-REPLAY-CHANNEL] 等其他缺口。

具体排期只记录在 Plane，不写入本 spec。

3. [G-KAFKA-D3]

实现：

• 将 Kafka producer 的有效 PARAM:kafka.producers.default.max-in-flight-requests-per-connection 固定为 D3 要求值。
• 启动时检查最终生效配置；不满足 D3 时拒绝启动。
• 不改变现有投递模型、批次、重试或 topic。

验收：

• 默认配置可以启动。
• 非法环境变量覆盖导致启动失败。
• acks、幂等和 max-in-flight 三项联合满足 D3。

4. [G-IGNORE]

实现：

• 继续使用现有 XML 解码结果和 MsgKind.Unsupported，不增加新的领域类型或规则引擎。

• 在 MessageProcessor 中按以下顺序处理：

  解码 META → 绑定 IDENTITY_KEY → 匹配 US-04 忽略清单 → 命中则写 SKIPPED + 回填意图 → 未命中则进入现有 MsgKind 分派

• 忽略终态不取得 PIPELINE_LOCK，不写航班表，不创建 MSG_EVENT。

• 使用 LAST_ERROR=ignored:<rule> 保存原因。

• 只增加 US-04 要求的忽略计数；指标名登记到 reference.md。

验收：

• US-04 中全部规则及大小写场景均命中。
• 忽略消息先完成身份绑定（US-03）。
• 重复身份继续走既有 duplicate-of 路径。
• SKIPPED 与回填意图同语句落库。
• 不产生航班或 outbox 副作用。
• 未命中的合法类型继续按 UNSUPPORTED 处理。

5. [G-EVENT-RETENTION]

实现：

• 下一条 PG Flyway 迁移仅给 MSG_EVENT 增加可空 SENT_AT。

• 所有投递确认操作在设置 STATE='SENT' 的同一条 UPDATE 中写入 SENT_AT。

• KAFKA:schd 新代次重置为 PENDING 时清空 SENT_AT。

• 迁移时将存量 SENT 行的 SENT_AT 设置为迁移时刻 CURRENT_TIMESTAMP，避免提前清理。

• 在现有 JobRunner 维护周期中增加一次有界清理，不新增线程或调度参数。

• 只删除同时满足以下条件的行：

  STATE = 'SENT'
  AND SENT_AT IS NOT NULL
  AND SENT_AT < 当前时间 - PARAM:msgx.pipeline.event-retention
  

• 删除仍携带 STATE='SENT' 条件，避免与 KAFKA:schd 新代次 upsert 竞态。

• PENDING、DEAD、SENT_AT IS NULL 一律保留。

验收：

• 投递确认与 SENT_AT 原子写入。
• 存量 SENT 行迁移后不会立即过期。
• 到期 SENT 行被分批清理，未到期及其他状态不受影响。
• KAFKA:schd 重置与清理两种并发顺序均不误删。
• 清理可重复执行，不影响投递顺序。

6. 测试约束

• 时间测试统一使用 TestClocks.kt。
• 仓储行为使用内存适配器；迁移结构使用既有 Flyway 测试设施。
• 禁止 Thread.sleep 和真实外部基础设施。
• 只补上述三个缺口对应的回归，不扩展其他功能矩阵。