windy/msgexchange-v2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: 统一生命周期与处理职责口径

Browse Source
This commit is contained in:
windyboy
2026-09-10 19:48:49 +08:00
parent 9fdb5ba6a5
commit dd839e6abb
5 changed files with 20 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/message-lifecycle.md
+9 -9
View File
@@ -25,9 +25,9 @@
| 入队：本系统开始处理 | 自有 PG 建立 `PROC_STATE` 记录 | `InboxPoller` |
| 处理完成：业务处理完成 | `PROC_STATE` 到达终态（SUCCEEDED / SKIPPED / DEAD） | 主泵 |
| 已回填：信箱写入处理标记 | 信箱行持有处理标记 | 回填与补偿通道 |
| 下游确认：下游已接收 | `MSG_EVENT` 置 `SENT` | `delivery`（Dispatcher / flushSchd） |
| 投递确认：投递目标已接受 | 目标端返回成功且 `MSG_EVENT` 置 `SENT` | `delivery`（Dispatcher / flushSchd） |
分环节的原因是存储边界：信箱与自有 PG 之间的写入不共享事务。前三个环节以自有 PG 为准；"已回填""下游确认"两个环节各自独立重试，都可能单独失败。
分环节的原因是存储边界：信箱与自有 PG 之间的写入不共享事务。“落信”以共享 MySQL 为准，“入队”和“处理完成”以自有 PG 为准；“已回填”与“投递确认”各以外部操作成功和本地确认事实共同判定。后两个环节各自独立重试，都可能单独失败。“投递确认”只表示 Kafka Broker 或其他投递目标已接受，不表示业务消费者已消费。
## 2. 状态总纲
@@ -54,10 +54,10 @@ MSG_EVENT PENDING ──→ SENT
| 解码与身份 | 信箱原文 | `DecodedMessage`、`IDENTITY_KEY` | 身份唯一约束 | 报文非法→`DEAD`；处理能力不足→`FAILED` 退避 |
| 事务处理 | 当前完整状态 + 报文载荷 | 航班变更、终态、事件、回填待办 | 消息 ID + 业务身份 | 事务整体回滚重试 |
| 提交后回填 | 终态消息 | 信箱处理标记 | 标记单调（§11） | 终态事务内登记回填意图；失败退避重试，超期强制补写 |
| 投递 | `MSG_EVENT` | 下游确认 | `EVENT_ID` | 退避至 `DEAD`；至少一次 |
| 投递 | `MSG_EVENT` | 投递目标接受确认 | `EVENT_ID` | 退避至 `DEAD`；至少一次 |
| 补偿作业 | 到期或已达 `NOW − R` 的终态记录 | 追平标记 | 消息 ID（仅空标生效） | 指数退避，独立线程执行；`R` 覆盖退避 |
处理器只在持有 `PIPELINE_LOCK` 的事务内写入自有 PG 状态，不操作信箱与 Kafka；全部外部副作用发生在事务提交之后。
领域决策逻辑不执行 I/O；Processor 作为事务协调器，只在持有 `PIPELINE_LOCK` 的事务内写入自有 PG 状态，不操作信箱与 Kafka。全部外部副作用发生在事务提交之后。
## 4. 故障恢复
@@ -65,12 +65,12 @@ MSG_EVENT PENDING ──→ SENT
| 中断位置 | 重启后的判定 | 恢复动作 |
|---|---|---|
| 已落信、未入队 | 信箱无标记且 PG 无记录 | 重扫补建入队记录 |
| 已落信、未入队 | 信箱行位于应扫描的 ID 范围且 PG 无记录（不以处理标记为判据） | 重扫补建入队记录 |
| 事务执行中 | PG 无该消息终态 | 事务整体回滚，按 `PENDING` 重新处理 |
| 事务已提交、标记未写 | 终态行仍持有回填意图（`BACKFILL_NEXT_AT` 非空） | 仅补写标记；业务处理结果保持不变 |
| 回填待办登记失败（与业务同事务） | 事务未提交 | 同"事务执行中"，不构成独立窗口 |
| 标记写入中途 | 标记仍为空 | 重新写入；重复写入同一值无副作用 |
| 下游已接收、`SENT` 未置 | 事件仍 `PENDING` | 允许重发，下游按事件身份去重 |
| 投递目标已接受、`SENT` 未置 | 事件仍 `PENDING` | 允许重发，消费方按事件身份去重 |
两个窗口已随"终态与回填意图同体同行"消除（口径与 design.md §10「事务与外部副作用」一致），不再是缺口：
@@ -98,11 +98,11 @@ MSG_EVENT PENDING ──→ SENT
### 5.2 超期标记补写
两类信箱行无法通过正常回填获得处理标记：报文残缺且缺少元数据的死信，以及回填通道长期失败的行。处理规则为：
所有处理终态都只依赖消息 ID 执行回填；报文残缺或缺少 META 不妨碍正常回填。本节规定回填通道长期失败时的超期兜底，避免终态信箱行无限期保持空标记。处理规则为：
**已达 `PROC_STATE` 终态、且接收时间超期（`DATE_RECEIVED < NOW − R`）仍无标记的信箱行，由回填通道补写一个库方认可的"已处理"类标记。**
- 期限 `R` 必须不小于（人工重放期限 + 人工处置期限）之和；两项期限的取值口径分别见 Q6 与 Q9，确认前不得下调 `R`。提前补写会使仍可重放的消息先被库方清除、失去原件资格。
- 期限 `R` 必须不小于（人工重放期限 + 人工处置期限）之和；两项期限的取值口径统一见 Q6，确认前不得下调 `R`。提前补写会使仍可重放的消息先被库方清除、失去原件资格。
- 中间态（`PENDING` / `FAILED`）不适用本规则：处理未完成时不打标，也不允许被清除。
- 补写值仅限于库方认可的 legacy 值集（Q7）；死信、业务重复等内部原因记录在 `PROC_STATE` 与审计日志，不在信箱新增枚举。
- 补写只针对空标记；已有值不回撤、不覆盖，重复执行无副作用。
@@ -190,7 +190,7 @@ MSG_EVENT PENDING ──→ SENT
- 可重放的错误类别为 `CODEC_ERROR / UNSUPPORTED / INFRA / EXHAUSTED` 四类（以 design.md §6.1 为准）；重放处理当前状态，不恢复历史顺序。
- 重放的前提是信箱原文仍可读取：`R_keep` 必须覆盖重放期限（§6），属于硬约束。
- 处理时无法读取原文，一律按 `MALFORMED → DEAD` 处理。若原文缺失源于库方违反保留契约提前清除，按契约违例走运维追责通道（契约条款见 Q7/Q9）；该消息的死信处置本身不变。
- 确认信箱行或原文已缺失时，按 `MALFORMED → DEAD` 处理；共享库超时、连接失败等暂时性读取异常按 `INFRA` 退避重试，不得伪装成原文缺失。若原文缺失源于库方违反保留契约提前清除，按契约违例走运维追责通道（契约条款见 Q7/Q9）；该消息的死信处置本身不变。
## 10. 开放问题索引