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/ 保持原样。
This commit is contained in:
windyboy
+22
-30
@@ -29,7 +29,7 @@ CIIMS / AODB 等上游
|
||||
┌──────────────── msgexchange-v2（单实例）────────────────┐
|
||||
│ ingress：发现报文 → PostgreSQL 持久化入队 │
|
||||
│ │ │
|
||||
│ processing：取 FIFO 队头 → 解析 / 去重 → Handler 决策 │
|
||||
│ processing：取 FIFO 队头 → 解析 / 去重 → 处理器决策 │
|
||||
│ └─ PG 单事务：航班变更 + 终态 + 待发事件│
|
||||
│ │
|
||||
│ jobs：独立维护线程（回填补偿 / 历史归档 / 留痕清理） │
|
||||
@@ -52,9 +52,9 @@ CIIMS / AODB 等上游
|
||||
|---|---|
|
||||
| `ingress` | 轮询信箱、持久化入队、补偿重扫及兼容 HTTP 写入；不解析业务报文。 |
|
||||
| `codec` | XML 解码，区分非法报文与可修复的解码失败。 |
|
||||
| `processing` | FIFO 调度、业务身份绑定与去重、处理器决策（SCHD/FLOP/FDEL/ADFT）、事务提交。处理器只产出决策与落库计划，不直接触碰 Kafka。 |
|
||||
| `processing` | FIFO 调度、业务身份绑定与去重、处理器决策与落库（SCHD/FLOP/FDEL/ADFT）：处理器在锁事务内完成状态写入、事件与回填待办登记，不直接触碰 Kafka。 |
|
||||
| `delivery` | 消费待发事件，负责按目标保序、`schd` 聚合、投递和失败重试。 |
|
||||
| `jobs` | 回填补偿扫描、历史归档与物理清除（§8.2）、留痕保留期清理；独立线程执行，不参与 FIFO。 |
|
||||
| `jobs` | 回填补偿扫描、航班历史清理与留痕保留期清理；独立 job 线程执行（调度见 design.md §6.1，红线见 flight-state.md §6），不参与 FIFO。 |
|
||||
| `domain` / `config` | 领域状态、事件和决策模型，以及运行参数。 |
|
||||
| `infra` | 仓储（JDBC/stub）、外部适配器、重试、健康检查与日志；通过接口隔离基础设施。 |
|
||||
|
||||
@@ -78,8 +78,8 @@ CIIMS / AODB 等上游
|
||||
- **消息严格 FIFO**：队头失败并退避时，后续消息仍不能越过它。只有队头完成或按失败策略进入终态后，队列才继续推进。收报重扫和水位设计必须防止较小 ID 漏入队而被后续消息越过。
|
||||
- **动态状态单写者**：`FLIGHT_SCHD` 及明细表只由主泵单线程写入。事务内第一步对 `PIPELINE_LOCK` 单行 `SELECT ... FOR UPDATE` 互斥；该方案在 PG/Oracle 11g 均无需数据库扩展或额外 DBA 特权。不能通过增加实例或处理线程直接扩容。
|
||||
- **身份去重**：同一业务身份只能绑定一条有效处理记录，重复报文不应再次产生业务副作用。具体身份组成和重放规则见设计文档。
|
||||
- **快照可恢复**：快照以 `PROC_STATE` 成功终态判定重放（§5.1）；每次成功写入推进 `STATE_VERSION`；`OPERATION_DAY` 一经确定不可变（§5.3）。
|
||||
- **物理清除只发生在历史归档**：删除一律先标记（FDEL）或由生命周期清除；历史存储未接通时必须删 0 条（§8.2）。
|
||||
- **快照可恢复**：快照以 `PROC_STATE` 成功终态判定重放；每次成功写入推进 `STATE_VERSION`；`OPERATION_DAY` 一经确定不可变（见 flight-state.md §2.1）。
|
||||
- **物理清除只发生在历史归档**：删除一律先标记（FDEL）或由生命周期清除；历史存储未接通时必须删 0 条（见 flight-state.md §6）。
|
||||
|
||||
这些约束优先于吞吐量优化。单写者降低了并发复杂度，代价是队头阻塞和吞吐上限；如需并行化，必须先重新定义顺序与状态归属，不能只调整线程数。
|
||||
|
||||
@@ -89,7 +89,7 @@ CIIMS / AODB 等上游
|
||||
|---|---|---|
|
||||
| 自有 PostgreSQL | 单行锁 `PIPELINE_LOCK`、处理状态 `PROC_STATE`、待发事件 `MSG_EVENT`、请求跟踪 `REQ_TRACK`、回填待办 `BACKFILL_TODO`、航班当前态 `FLIGHT_SCHD` + 9 张明细表、留痕 `SCHD_SNAP_LOG` | 本系统唯一业务数据库。消息处理、状态推进与待发事件在单事务内原子提交；本地事务只在此库。 |
|
||||
| 共享 MySQL | `CMINMSGS` 入站信箱、`COUTMSGS` 出站信箱 | 外部系统所有。仅执行约定的信箱读写和处理标记回填，不建表、不迁移 schema、不写历史表。兼容 HTTP 入口可按既有契约写入入站信箱。 |
|
||||
**不使用跨库事务。** PG 事务只能保证“处理结果与待发事件一起提交”，不能覆盖 Redis 更新、MySQL 回填或 Kafka 发送。跨存储依靠幂等、重试和持久化补偿恢复：
|
||||
**不使用跨库事务。** PG 事务只能保证“处理结果与待发事件一起提交”，不能覆盖 MySQL 回填或 Kafka 发送等外部副作用。跨存储依靠幂等、重试和持久化补偿恢复：
|
||||
|
||||
| 中断位置 | 恢复要求 |
|
||||
|---|---|
|
||||
@@ -100,24 +100,16 @@ CIIMS / AODB 等上游
|
||||
|
||||
对外投递按**至少一次**设计，不承诺端到端恰好一次。Kafka 生产者幂等不能消除应用重启或 outbox 重发带来的所有重复。
|
||||
|
||||
## 7. 关键决策索引
|
||||
## 7. 关键决策
|
||||
|
||||
保留 D1–D12 编号，便于设计文档和工程历史引用；以下是决策摘要，而非完成清单。
|
||||
仅保留仍具约束价值、且无法从正文（§4–§6、design.md）直接推出的决策，按 D1–D4 连续编号供正文与 design.md 引用；其余曾编号条目（严格 FIFO、stub 门控、本地事务、UNSUPPORTED 处理等）已在正文以约束形式表达，不再重复列表。状态只反映是否已落地，不代表决策被撤销。
|
||||
|
||||
| 编号 | 决策及理由 |
|
||||
|---|---|
|
||||
| D1 | 业务报文严格 FIFO，优先保护航班状态的时序正确性；维护作业独立线程执行，不参与消息序。 |
|
||||
| D2 | 阶段 B 暂缓。历史写入成功后才可生成删除事件；顺序调用本身不保证原子性，恢复与去重方案需在启用前补齐。 |
|
||||
| D3 | `schd` 只从 `flushSchd` 聚合发送，减少已被覆盖的中间状态通知。 |
|
||||
| D4 | 未实现的报文类型按 `UNSUPPORTED` 可恢复失败处理，不当作非法报文直接丢弃；补齐能力后按重放规则恢复。 |
|
||||
| D5 | 在持有具体消息或批次上下文的位置记录失败和退避；不吞掉线程中断或 JVM 严重错误。 |
|
||||
| D6 | 基础设施通过接口注入，时间通过 `Clock` 注入，便于确定性测试顺序、重试与超时。 |
|
||||
| D7 | 内存 stub 仅显式开启时装配，生产禁止使用，避免把未持久化的数据误当作已落库。 |
|
||||
| D8 | 使用编译期依赖注入，并以启动冒烟测试验证关键 Bean 装配。 |
|
||||
| D9 | 自有 PG 内完成本地事务，共享 MySQL 仅作信箱；跨存储采用补偿，不使用 XA。 |
|
||||
| D10 | 动态状态单写者，生产只允许一个活动实例；多实例必须先具备可靠的排他保护。 |
|
||||
| D11 | Kafka 生产要求 `acks=all`、`enable.idempotence=true`、`max.in.flight=1`，切流前验证 Broker 兼容性；不允许通过关闭幂等来满足生产接入。 |
|
||||
| D12 | 仅将自有库终态记录归档到 `PROC_STATE_HST`，不侵入共享库的表结构或保留策略。 |
|
||||
| 编号 | 决策及理由 | 当前状态 |
|
||||
|---|---|---|
|
||||
| D1 | 航班清场只在历史写入成功后进行，未接通时删 0 条；未经 FDEL 的清场须先补发删除事件。ES 历史投影（阶段 B）暂缓。 | 红线已实现于 `HistorySweepJob`；恢复/去重方案未闭合 |
|
||||
| D2 | 动态状态单写者，生产只允许一个活动实例；多实例必须先具备可靠的排他保护。 | 事务行锁已实现；实例级排他未完成 |
|
||||
| D3 | Kafka 生产要求 `acks=all`、`enable.idempotence=true`、`max.in.flight=1`；不允许通过关闭幂等来满足生产接入。 | 约束未强制：默认 in-flight=5，且可用环境变量覆盖 |
|
||||
| D4 | 自有库终态记录只归档到 `PROC_STATE_HST`，不侵入共享库的表结构或保留策略。 | 目标表未建，尚无归档作业 |
|
||||
|
||||
## 8. 部署、切换与运维
|
||||
|
||||
@@ -137,14 +129,14 @@ CIIMS / AODB 等上游
|
||||
|
||||
## 9. 当前实现与上线门槛
|
||||
|
||||
当前已有管道骨架、重试机制、部分 JDBC 适配和开发环境 stub 冒烟能力，**不能据此认定生产链路已闭环**。默认配置关闭管道自动启动及真实数据库/信箱适配。
|
||||
当前已实现收报入队与判重、严格 FIFO 主泵、SCHD/FLOP/FDEL/ADFT 处理器与 PG 单事务写入、outbox 与 `schd` 聚合投递骨架、回填补偿与航班历史清理脚手架。**这些只证明机制可用，不证明生产链路已闭环**：默认配置不自动启动管道，真实数据库、信箱与出站适配必须显式开启（`msgx.pipeline.autostart`、`mailbox.shared-mysql.enabled`、真实 `DeliveryPort` 适配）。
|
||||
|
||||
上线前至少需要完成并验证：
|
||||
上线前必须完成并验证：
|
||||
|
||||
- 真实 PG 事务、信箱水位与补扫、回填补偿、出站信箱，以及所需业务 Handler。
|
||||
- `FLIGHT_SCHD` 事务原子性、`STATE_VERSION` 推进与 `OPERATION_DAY` 不可变校验、故障中断回滚恢复。
|
||||
- FIFO、身份去重、FDEL/ADFT 生命周期、历史归档顺序和投递故障下的回归测试。
|
||||
- 生产启动校验、单实例排他保护、影子隔离和 Kafka 配置约束；当前配置仍允许 Kafka 参数覆盖，且默认 in-flight 值与 D11 要求不同。
|
||||
- 死信告警、人工重放、端到端追踪、积压指标及安全边界。
|
||||
- 真实 PG + 共享 MySQL 信箱的端到端处理、补偿与投递，以及出站信箱适配；未闭合的缺口清单见 design.md §10。
|
||||
- 航班状态不变量与恢复证据：`STATE_VERSION` 推进、`OPERATION_DAY` 不可变、故障中断回滚（见 flight-state.md §7）。
|
||||
- FIFO 越序、身份去重、FDEL/ADFT、清场顺序与投递故障的回归测试（见 design.md §8）。
|
||||
- 单实例排他保护与启动校验、影子隔离、Kafka 生产配置约束——当前配置允许环境变量覆盖 `acks`/幂等/in-flight，且默认 in-flight 值与 D3 不同，切流前必须按 D3 收敛。
|
||||
- 死信与一致性异常的告警、可执行的人工重放流程、端到端追踪、积压指标与安全边界。
|
||||
|
||||
具体实现差异见 design.md §10 与 ACM2-29 核查报告，工作由 Plane 跟踪。航班状态的有效规则统一见 flight-state.md；历史阶段口径不覆盖当前规则。
|
||||
验收与进度由 Plane 跟踪，缺口逐项见 design.md §10 与 user-stories.md；航班状态规则统一以 flight-state.md 为准。
|
||||
|
||||
Reference in New Issue
Block a user