add aodb detailed planning artifacts and adrs

2026-04-13 16:12:54 +08:00
parent 973c745762
commit 66d081faaf
15 changed files with 1069 additions and 0 deletions
@@ -0,0 +1,24 @@
+# ADR-001 MVP 不引入 Flink
+
+## 状态
+
+Accepted
+
+## 背景
+
+首期目标是完成单机场 AODB 核心闭环，规模为 500 万至 3000 万旅客机场，优先解决当前态统一、资源冲突和审计问题。
+
+## 决策
+
+MVP 不引入 Flink。首期只保留 Kafka 事件骨干和应用服务内流式处理逻辑。预测、CEP 和复杂有状态计算推迟到 P1。
+
+## 原因
+
+- 首期复杂度应优先让位于交付确定性。
+- 预测与复杂流处理不是首期闭环前提。
+- Flink 会显著提高部署、运维和故障恢复复杂度。
+
+## 后果
+
+- MVP 中实时计算能力受限。
+- 事件契约和聚合边界必须为未来引入 Flink 预留演进空间。
@@ -0,0 +1,24 @@
+# ADR-002 Kafka 作为唯一事件骨干
+
+## 状态
+
+Accepted
+
+## 背景
+
+AODB 需要支撑事件可回放、订阅分发、补偿和审计。
+
+## 决策
+
+Kafka 作为唯一事实事件骨干。所有对外事件订阅都以 Kafka 上的标准化事件为源头，禁止多路事件源头并存。
+
+## 原因
+
+- 统一重放和补偿语义。
+- 避免“写库成功但未发布”或“已发布但未落库”的治理空洞。
+- 降低外部消费者理解成本。
+
+## 后果
+
+- 事件可靠发布必须依赖 Outbox + CDC。
+- 查询 API 不能被下游误当作事件事实源。
@@ -0,0 +1,24 @@
+# ADR-003 事实分层模型
+
+## 状态
+
+Accepted
+
+## 背景
+
+AODB 需要同时处理多源观测、字段裁决和对外权威事实发布。
+
+## 决策
+
+采用 `Observation / Decision / Published Fact` 三层模型。
+
+## 原因
+
+- 让 SSOT 真正表示“经过治理后发布的事实”。
+- 保证原始观测、人工覆盖和当前值三者不互相污染。
+- 便于审计、回放和责任归因。
+
+## 后果
+
+- 数据模型和事件模型会更明确，但设计和实现复杂度略有上升。
+- Published Fact 的任何变更都必须可追溯到 Observation 和 Decision。
@@ -0,0 +1,24 @@
+# ADR-004 FlightOperation 写主归属
+
+## 状态
+
+Accepted
+
+## 背景
+
+原方案中 Flight、Milestone、Resource、Alert 边界存在写入重叠风险。
+
+## 决策
+
+Flight 当前权威态只能由 `Flight Operation Service` 写入，其他服务只能产生观测、候选事实、资源事实或告警事实。
+
+## 原因
+
+- 避免多个服务共同修改同一当前态。
+- 降低一致性和回放复杂度。
+- 方便将 Published Fact 聚合到单一领域对象。
+
+## 后果
+
+- Milestone 和 Resource 服务必须通过事件影响 Flight 当前态。
+- Flight Service 需要承担更明确的聚合协调责任。
@@ -0,0 +1,24 @@
+# ADR-005 Turnaround 独立建模
+
+## 状态
+
+Accepted
+
+## 背景
+
+仅以单航班建模无法充分表达到离港配对、机尾号上下文和资源联动。
+
+## 决策
+
+将 `Turnaround` 作为首期核心领域对象，引入最小独立建模。
+
+## 原因
+
+- 支撑航班配对（Linking）需求。
+- 提高资源分配和时序解释能力。
+- 为换机、延误联动和周转分析提供上下文。
+
+## 后果
+
+- 文档和模型复杂度上升。
+- 配对修正和不完整配对需要额外的事件和审计语义。
@@ -0,0 +1,24 @@
+# ADR-006 资源锁定模型
+
+## 状态
+
+Accepted
+
+## 背景
+
+单纯的资源时间窗分配无法表达建议分配、已确认分配和人工强制覆盖。
+
+## 决策
+
+ResourceAllocation 支持 `soft lock` 和 `hard lock` 两种锁定语义。
+
+## 原因
+
+- 表达自动建议和人工强制分配的区别。
+- 支持冲突检测、覆盖和回滚的可解释性。
+- 为未来优化排班预留空间。
+
+## 后果
+
+- 冲突检测和分配逻辑需要区分锁定强度。
+- 人工覆盖必须伴随审计和事件输出。
@@ -0,0 +1,24 @@
+# ADR-007 查询与订阅分离
+
+## 状态
+
+Accepted
+
+## 背景
+
+将 GraphQL Subscription 或查询层直接作为事实流会混淆读取和事件分发语义。
+
+## 决策
+
+对外查询接口和事件订阅接口分离设计。
+
+## 原因
+
+- 查询和事件分发的稳定性、回放、限流语义不同。
+- 便于明确外部消费者的消费契约。
+- 降低把查询接口误当权威事件骨干的风险。
+
+## 后果
+
+- 需要独立设计事件订阅网关或分发适配层。
+- API 文档要分别描述查询和订阅契约。
@@ -0,0 +1,24 @@
+# ADR-008 Outbox 与 CDC
+
+## 状态
+
+Accepted
+
+## 背景
+
+AODB 必须避免“写库成功但没发事件”或“发了事件但没落库”。
+
+## 决策
+
+采用 `Outbox Pattern + CDC` 作为写库与发事件一致性策略。
+
+## 原因
+
+- 能把数据库状态变化和事件发布绑定到同一事务边界。
+- 适合首期 Kafka 作为唯一事件骨干的架构。
+- 支持失败重试、断点恢复和事件回放。
+
+## 后果
+
+- 需要部署 CDC / 发布器组件。
+- 发布流程和 Outbox 堆积需要专门监控。
@@ -0,0 +1,24 @@
+# ADR-009 PostgreSQL HA
+
+## 状态
+
+Accepted
+
+## 背景
+
+Published Fact、审计和 Outbox 都依赖 PostgreSQL，数据库可用性直接决定系统可用性。
+
+## 决策
+
+MVP 必须采用 PostgreSQL 高可用部署，并具备备份恢复和 PITR 或等价能力。
+
+## 原因
+
+- 满足 RTO / RPO 目标。
+- 为审计、重放和一致性提供稳定基础。
+- 避免首期把可靠性寄托在应用层补偿上。
+
+## 后果
+
+- 部署和运维门槛上升，但这是首期必须承担的复杂度。
+- 需要单独演练主备切换和恢复流程。
@@ -0,0 +1,24 @@
+# ADR-010 人工裁决事件化
+
+## 状态
+
+Accepted
+
+## 背景
+
+AODB 中数据冲突、资源覆盖和解析失败都可能需要人工参与。
+
+## 决策
+
+所有人工裁决、人工覆盖和人工复核动作必须事件化和审计化，禁止仅通过数据库备注或日志留痕。
+
+## 原因
+
+- 人工动作是业务事实的一部分。
+- 需要对外解释当前值为何成立。
+- 便于回放、对账和合规审计。
+
+## 后果
+
+- Case 流程和审计模型需要更完整。
+- 首期必须实现最小人工复核状态机。