docs(acm2-63): 精简架构文档并闭合模块入口登记
architecture.md 138→116 行：删除 §9「当前实现与上线门槛」（进度内容，归 invariants 声明边界与 Plane，其中部署前提并入 §8）；§4 主流程压成链路摘要 + design 节名指针，去掉与 design 重复的机制细节；§8 可观测性收成一句并把指标口径指向 reference；D1–D4 第三列由「当前状态」改为「证据 / 缺口」稳定 ID 指针。 reference.md：模块入口补 infra/metrics/JobActivity.kt、infra/health/JobRunnerHealthIndicator.kt 与 config/OperationDayProps.kt；迁移清单补 V7–V9。
This commit is contained in:
windyboy
+10
-32
@@ -60,18 +60,9 @@ CIIMS / AODB 等上游
|
||||
|
||||
## 4. 主流程
|
||||
|
||||
### 收报与处理
|
||||
`InboxPoller` 发现 → 自有 PG 入队（`INV-2`）→ 主泵按最小未完成 `MSG_ID` 取队头、解码并按业务身份去重 → 处理器在持 `PIPELINE_LOCK` 的同一事务内写航班变更、待发事件、处理终态与回填意图（`INV-17`）→ 提交后回填共享信箱处理标记 → `Dispatcher` 投递 `KAFKA:msg` 与 `KAFKA:schd`（至少一次，`INV-10`）。
|
||||
|
||||
1. `InboxPoller` 按 `PARAM:msgx.pipeline.poll-interval` 周期按 ID 区间扫描水位 `W` 之后的信箱记录（`ID > W`，**不以处理标记为谓词**），在自有 PG 中建立 `PROC_STATE(PENDING)`；水位与入队在同一事务推进（`INV-2`）。重复扫描不能重复入队，中断后由重扫补建。扫描谓词与水位见 design.md「收报与水位」。
|
||||
2. 主泵只处理最小未完成 `MSG_ID`。解析报文、绑定业务身份并去重后，分派给 SCHD/FLOP/FDEL/ADFT 处理器。
|
||||
3. 在自有 PG 同一事务内（先取 `PIPELINE_LOCK`）保存航班状态变更（`FLIGHT_SCHD` 与明细表）、`MSG_EVENT` 待发事件、处理终态与回填意图。
|
||||
4. 事务提交后，补写共享信箱的处理标记（外部副作用，由回填退避重试与超期强制补写保障）。
|
||||
|
||||
### 投递
|
||||
|
||||
`Dispatcher` 从 `MSG_EVENT` 取出待发事件。普通事件按 `FLID` 与 `EVENT_ID` 保序（与分区键一致）：同一 `FLID` 内不跳队，不同 `FLID` 不互相阻塞（实现仍为目标级全序，收敛见 `CLM-7`）。
|
||||
|
||||
`schd` 是最新状态通知，不逐条发送中间变化：统一由 `flushSchd` 按 `FLID` 聚合，取批次内最新事件后发送。它不提供逐条变更历史，不能与普通事件的 FIFO 语义混为一谈。
|
||||
机制细节各有归属：扫描谓词与水位见 design.md「收报与水位」，分派与事务边界见「主泵调度与单条处理」，回填见「回填」，保序与 `schd` 聚合见「事件投递」。
|
||||
|
||||
## 5. 必须保持的约束
|
||||
|
||||
@@ -98,14 +89,14 @@ CIIMS / AODB 等上游
|
||||
|
||||
## 7. 关键决策
|
||||
|
||||
仅保留仍具约束价值、且无法从正文（§4–§6、design.md）直接推出的决策，按 D1–D4 连续编号供正文与 design.md 引用；其余曾编号条目（严格 FIFO、stub 门控、本地事务、UNSUPPORTED 处理等）已在正文以约束形式表达，不再重复列表。状态只反映是否已落地，不代表决策被撤销。
|
||||
仅保留仍具约束价值、且无法从正文（§4–§6、design.md）直接推出的决策，按 D1–D4 连续编号供正文与 design.md 引用；其余曾编号条目（严格 FIFO、stub 门控、本地事务、UNSUPPORTED 处理等）已在正文以约束形式表达，不再重复列表。第三列只给证据与缺口指针；交付状态与可声明性见 invariants.md 声明边界与 Plane，决策不因状态变化而撤销。
|
||||
|
||||
| 编号 | 决策及理由 | 当前状态 |
|
||||
| 编号 | 决策及理由 | 证据 / 缺口 |
|
||||
|---|---|---|
|
||||
| D1 | 航班清场只在历史写入成功后进行，未接通时删 0 条；未经 FDEL 的清场须先补发删除事件。ES 历史投影（阶段 B）暂缓。 | 红线已实现于 `HistorySweepJob`；恢复/去重方案未闭合 |
|
||||
| D2 | 动态状态单写者，生产只允许一个活动实例；多实例必须先具备可靠的排他保护。 | 事务行锁已实现；实例级排他未完成 |
|
||||
| D3 | Kafka 生产要求 `acks=all`、`enable.idempotence=true`、`max.in.flight=1`；不允许通过关闭幂等来满足生产接入。 | 约束未强制：默认值与 D3 不一致（见 reference 参数表），且可用环境变量覆盖 |
|
||||
| D4 | 自有库终态记录只归档到 `PROC_STATE_HST`，不侵入共享库的表结构或保留策略。 | 目标表未建，尚无归档作业 |
|
||||
| D1 | 航班清场只在历史写入成功后进行，未接通时删 0 条；未经 FDEL 的清场须先补发删除事件。ES 历史投影（阶段 B）暂缓。 | 红线见 flight-state.md「生命周期与开放项」；历史写入与删除事件之间仍无恢复方案（见 design.md「维护作业与归档」） |
|
||||
| D2 | 动态状态单写者，生产只允许一个活动实例；多实例必须先具备可靠的排他保护。 | 事务行锁见 design.md「事务边界」；实例级排他属部署前提 `PRE-5`，可声明性见 `CLM-6` |
|
||||
| D3 | Kafka 生产要求 `acks=all`、`enable.idempotence=true`、`max.in.flight=1`；不允许通过关闭幂等来满足生产接入。 | 参数默认值与 D3 不一致 `[G-KAFKA-D3]`（取值见 reference 参数表） |
|
||||
| D4 | 自有库终态记录只归档到 `PROC_STATE_HST`，不侵入共享库的表结构或保留策略。 | 目标表未建 `[G-PROC-HST]` |
|
||||
|
||||
## 8. 部署、切换与运维
|
||||
|
||||
@@ -114,6 +105,7 @@ CIIMS / AODB 等上游
|
||||
- 生产维持单活动实例，停机时停止接收新任务并等待工作线程退出。已有事务级行锁，但消息认领和整个实例的排他保护尚未完成，不能依靠行锁宣称支持双实例 FIFO。
|
||||
- 配置、口令和环境端点通过环境变量提供。兼容写接口沿用内网信任模式，缺少鉴权，必须限制网络访问；管理端点不得直接暴露到生产外网。
|
||||
- Eureka 用于服务发现，Logstash 接收结构化日志；日志出口故障不应阻塞业务处理。
|
||||
- 默认不自动启动管道：真实 PG、共享信箱与出站适配必须显式开启（键见 [reference.md](reference.md) 参数表）。
|
||||
|
||||
**替换旧系统**
|
||||
|
||||
@@ -121,18 +113,4 @@ CIIMS / AODB 等上游
|
||||
|
||||
**可观测性要求**
|
||||
|
||||
使用消息 ID、事件 ID 关联处理与投递日志；健康检查反映依赖实际可用性，而不只是进程存活。运行中重点关注队列积压、队头滞留时间、投递延迟、重试/DEAD 数量和回填补偿积压。死信和一致性异常需要可执行的告警与重放流程，不能只留一条错误日志。
|
||||
|
||||
## 9. 当前实现与上线门槛
|
||||
|
||||
当前已实现收报入队与判重、严格 FIFO 主泵、SCHD/FLOP/FDEL/ADFT 处理器与 PG 单事务写入、outbox 与 `schd` 聚合投递骨架、回填补偿与航班历史清理脚手架。**这些只证明机制可用，不证明生产链路已闭环**：默认配置不自动启动管道，真实数据库、信箱与出站适配必须显式开启（`msgx.pipeline.autostart`、`mailbox.shared-mysql.enabled`、真实 `DeliveryPort` 适配）。
|
||||
|
||||
上线前必须完成并验证：
|
||||
|
||||
- 真实 PG + 共享 MySQL 信箱的端到端处理、补偿与投递，以及出站信箱适配；未闭合的缺口与不可声明项见 [invariants.md](invariants.md) 的声明边界。
|
||||
- 航班状态不变量与恢复证据：`STATE_VERSION` 推进、`OPERATION_DAY` 不可变、故障中断回滚（`INV-12`–`INV-16`，语义见 flight-state.md）。
|
||||
- FIFO 越序、身份去重、FDEL/ADFT、清场顺序与投递故障的回归测试（见 [invariants.md](invariants.md) 验证映射）。
|
||||
- 单实例排他保护与启动校验、影子隔离、Kafka 生产配置约束——当前配置允许环境变量覆盖 `acks`/幂等/in-flight，且默认 in-flight 值与 D3 不同，切流前必须按 D3 收敛。
|
||||
- 死信与一致性异常的告警、可执行的人工重放流程、端到端追踪、积压指标与安全边界。
|
||||
|
||||
验收与进度由 Plane 跟踪，缺口逐项见 [invariants.md](invariants.md) 的声明边界与 [user-stories.md](user-stories.md)；航班状态规则统一以 flight-state.md 为准。
|
||||
用消息 ID、事件 ID 关联处理与投递日志；健康检查反映依赖实际可用性，而不只是进程存活；死信与一致性异常需要可执行的告警与重放流程，不能只留一条错误日志。指标名、取数规则与作业健康见 [reference.md](reference.md)「指标与健康」。
|
||||
|
||||
+3
-3
@@ -102,9 +102,9 @@
|
||||
| 日计划 | `processing/ScheduleProcessor.kt`；请求协调尚无实现（`REQ_TRACK` 仓储见 `infra/persistence/`） |
|
||||
| 回填与投递作业 | `processing/BackfillService.kt`、`jobs/JobRunner.kt`、`HistorySweepJob.kt`、`delivery/Dispatcher.kt` |
|
||||
| 持久化与恢复 | `infra/persistence/`、`infra/retry/`（`ProcFailure` / `ReplayService` / `FailureScheduler`） |
|
||||
| 启停与配置 | `PipelineLifecycle.kt`、`config/PipelineProps.kt`、`config/HistoryProps.kt` |
|
||||
| 指标与健康 | `infra/metrics/PipelineMetrics.kt`、`infra/health/BacklogSnapshotProvider.kt` |
|
||||
| 迁移 | `src/main/resources/db/migration/`（V1 基线、V2 生命周期、V3 稳定处理起点、V4 回填闭环、V5 切流播种、V6 本地入队时间；`oracle11g/` 为占位） |
|
||||
| 启停与配置 | `PipelineLifecycle.kt`、`config/PipelineProps.kt`、`config/HistoryProps.kt`、`config/OperationDayProps.kt`（含运营日时区启动自检） |
|
||||
| 指标与健康 | `infra/metrics/PipelineMetrics.kt`、`infra/metrics/JobActivity.kt`、`infra/health/BacklogSnapshotProvider.kt`、`infra/health/JobRunnerHealthIndicator.kt` |
|
||||
| 迁移 | `src/main/resources/db/migration/`（V1 基线、V2 生命周期、V3 稳定处理起点、V4 回填闭环、V5 切流播种、V6 本地入队时间、V7 删除处理起点、V8 `REQ_TRACK` 开放态唯一索引、V9 `schd` 单行化；`oracle11g/` 为占位） |
|
||||
|
||||
## 4. 错误分类与重放白名单
|
||||
|
||||
|
||||
Reference in New Issue
Block a user