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` 和真实外部基础设施。
- 只补上述三个缺口对应的回归，不扩展其他功能矩阵。