refactor aodb design docs around technical architecture

airport-wiki/concepts/aodb/开源机场运营数据库（AODB）高层设计文档.md

@@ -1,35 +1,35 @@
 # 开源机场运营数据库（AODB）高层设计文档
 
-## 1. 目标
+## 1. 文档目标
 
-本设计给出 AODB 的首期可开工高层方案，重点回答六件事：
+本文档定义 AODB MVP 的技术方案基线，重点回答以下问题：
 
-1. 首期上线到底做什么、不做什么。
-2. 系统由哪些核心聚合和服务组成。
-3. 关键业务数据如何在“观测、裁决、发布事实”之间流转。
-4. 资源分配、冲突、告警和人工复核如何闭环。
-5. 对外查询与事件订阅如何解耦。
-6. SLO 与部署、容灾和审计如何对齐。
+1. AODB 在 MVP 内承载哪些业务闭环，以及哪些能力明确不做。
+2. 系统如何划分聚合、服务、数据流和事件边界。
+3. 航班、里程碑、资源、告警等核心对象如何建模。
+4. 发布事实如何在观测、裁决、审计和订阅之间保持一致。
+5. 查询、订阅、部署、容灾和可观测性如何落到可实现架构。
 
-适用范围：年旅客吞吐量 500 万至 3000 万机场，单机场优先。
+适用范围：年旅客吞吐量 500 万至 3000 万机场，优先支持单机场部署。
 
 ## 2. 设计原则
 
-- 单一事实源：AODB 对外只发布单一当前权威事实，不暴露“谁最后写入”式伪一致。
+- 单一事实源：AODB 对外发布单一当前权威事实，不暴露“谁最后写入”式伪一致。
 - 事实分层：原始观测、裁决记录、发布事实必须分层建模。
-- 事件驱动：状态变化通过事件传播，系统间通过契约解耦。
-- 规则可解释：字段权威、冲突裁决、人工覆盖都必须能解释来源和原因。
-- 渐进建设：先做稳定闭环，再引入预测、CEP 和复杂编排能力。
+- 写主清晰：每个核心聚合只允许一个服务写入，避免跨服务共享可变状态。
+- 事件驱动：状态变化通过事件传播，系统通过契约解耦。
+- 规则可解释：字段权威、冲突裁决、人工覆盖必须可追溯、可回放、可解释。
+- 渐进复杂度：MVP 先建立稳定闭环，不引入复杂优化平台和长事务编排平台。
 
-## 3. 范围与阶段
+## 3. 范围定义
 
 ### 3.1 MVP 范围
 
-首期上线只覆盖以下闭环：
+首期只覆盖以下闭环：
 
 - 航班计划导入与实时状态更新
 - 航班配对与过站上下文最小建模
-- 基础资源分配（Stand、Gate、Belt、Counter）
+- 基础资源分配：Stand、Gate、Belt、Counter
 - 关键里程碑跟踪与发布事实治理
 - 延误、资源冲突和数据质量告警
 - 对外查询接口与事件订阅
@@ -37,33 +37,39 @@
 
 ### 3.2 非 MVP 范围
 
-不纳入首期：
+首期不纳入以下能力：
 
-- 复杂优化排班（全局优化模型）
-- 深度 AI 预测与自适应调度
-- Flink 驱动的复杂 CEP 和预测平台
+- 全局优化排班和复杂资源优化求解
+- 深度 AI 预测和自适应调度
+- Flink 驱动的复杂 CEP 平台
 - Temporal 驱动的复杂长事务工作流平台
 - 多机场统一调度中心能力
 
-### 3.3 分阶段演进
-
-- Phase 1：完成 MVP 闭环并上线单机场。
-- Phase 2：引入预测能力、复杂规则平台和补偿编排能力。
-- Phase 3：增强容量、容灾和多机场扩展。
-
 ## 4. 总体架构
 
 ### 4.1 架构分层
 
-| 层级 | 主要能力 | MVP 主路径组件 | 后续增强组件 |
+| 层级 | 主要能力 | MVP 主路径组件 | 说明 |
 | --- | --- | --- | --- |
-| 接入层 | 外部系统接入、协议解析、统一北向入口 | Kong Gateway、Apache Camel、SSIM 导入器 | 协议适配扩展插件 |
-| 业务层 | 航班当前态、观测治理、资源分配、告警处置、对外接口 | Flight Operation Service、Milestone Service、Resource Service、Alert Service、External API Service | 独立 Case / Workflow Service |
-| 事件层 | 事件骨干、重放、订阅分发 | Kafka、Outbox/CDC 发布器 | 订阅网关增强、Schema Registry |
-| 数据层 | 事务存储、时序存储、缓存 | PostgreSQL、TimescaleDB、Redis | OpenSearch、对象存储 |
-| 平台层 | 身份认证、部署、观测 | Keycloak、Kubernetes、Prometheus/Grafana/Loki | Linkerd、Jaeger |
+| 接入层 | 外部系统接入、协议解析、统一北向入口 | Kong Gateway、Apache Camel、SSIM 导入器 | 接收计划、动态、资源和人工操作输入 |
+| 业务层 | 航班当前态、观测治理、资源分配、告警处置、外部接口 | Flight Operation Service、Milestone Service、Resource Service、Alert Service、External API Service | 承担领域逻辑和对外契约 |
+| 事件层 | 事件骨干、重放、订阅分发 | Kafka、Outbox/CDC 发布器 | 负责异步传播和回放 |
+| 数据层 | 事务存储、时序存储、缓存 | PostgreSQL、TimescaleDB、Redis | 保存当前态、审计链路和热点读模型 |
+| 平台层 | 认证鉴权、部署、观测 | Keycloak、Kubernetes、Prometheus/Grafana/Loki | 提供运行时底座 |
 
-### 4.2 领域划分与聚合边界
+### 4.2 核心技术链路
+
+MVP 主链路采用“接入标准化 -> 观测入库 -> 裁决生成 -> 发布事实更新 -> 事件发布 -> 查询/订阅消费”的结构：
+
+1. 外部计划或运行动态通过接入层进入系统。
+2. Milestone Service 将输入标准化为 Observation，并按幂等键写入。
+3. 规则引擎根据字段权威矩阵和当前上下文生成 Decision。
+4. Flight Operation Service 更新 Published Fact 和当前状态摘要。
+5. 同一事务内写入 Outbox，由 CDC 发布到 Kafka。
+6. External API Service 对外提供查询接口和事件订阅接口。
+7. 告警、人工裁决和重放都沿同一事实链路工作，不直接绕过 Published Fact。
+
+### 4.3 领域划分与聚合边界
 
 为避免多服务共同修改同一业务对象，MVP 采用以下聚合边界：
 
@@ -82,7 +88,7 @@
 - Resource Service 只拥有资源占用与冲突事实，不直接修改 Flight 当前态中的非资源字段。
 - Alert Service 不产生业务事实，只管理处置状态和告警生命周期。
 
-### 4.3 核心服务职责
+### 4.4 核心服务职责
 
 - `Flight Operation Service`
   - 管理 FlightOperation 当前态。
@@ -106,19 +112,19 @@
 
 ### 5.1 核心标识约定
 
-- Flight：
+- Flight
   - `flight_key`：`carrier + flight_number + op_date + leg_no`
   - `flight_id`：内部不可变主键
-- Turnaround：
+- Turnaround
   - `turnaround_id`
   - 可关联一个到达航班和一个离港航班
-- MilestoneObservation：
+- MilestoneObservation
   - `observation_id`
   - 幂等键优先使用上游报文 ID、序列号或批次 + 行号
-- Resource：
+- Resource
   - `resource_id`
   - `resource_type + resource_code` 唯一
-- ResourceAllocation：
+- ResourceAllocation
   - `allocation_id`
   - 幂等键由 `resource_id + validity_window + assignment_source + correlation_id` 组合约束
 
@@ -414,7 +420,7 @@ MVP 采用 `Outbox Pattern + CDC`：
 - 顺序仅保证到 `flight_id`
 - 消费者必须按 `event_id` 去重
 - 消费者必须处理数据质量标记和裁决摘要
-- 回放窗口和游标语义必须文档化并纳入验收
+- 回放窗口和游标语义必须文档化
 
 ## 12. 规则体系与人工复核
 
@@ -486,30 +492,19 @@ MVP 采用 `Outbox Pattern + CDC`：
 - Outbox / CDC 必须具备断点恢复和重复投递幂等能力。
 - 容灾演练必须覆盖数据库切换、事件堆积、订阅重连和回放。
 
-### 13.4 SLO 映射表
+### 13.4 可观测性要求
 
-| SLO | 设计支撑 | 验收方式 |
-| --- | --- | --- |
-| 可用性 | 多副本 API、DB HA、Kafka 副本 | 演练和月度故障统计 |
-| 延迟 | 单聚合写主、Kafka 事件骨干、缓存热点读 | 压测和生产观测 |
-| RTO / RPO | DB 备份恢复、Kafka 重放、CDC 恢复 | 容灾演练 |
-| 审计覆盖 | Observation / Decision / AuditTrail | 抽样链路回放 |
+- 所有写路径必须具备请求追踪、事件追踪和审计追踪三类关联 ID。
+- 关键链路必须暴露延迟、失败率、积压量和重试次数指标。
+- 人工裁决、资源覆盖和更正事件必须进入统一审计检索视图。
+- 订阅接口必须暴露连接数、滞后量、推送速率和补偿次数指标。
 
-## 14. 上线门禁（Go / No-Go）
+## 14. 文档边界与引用
 
-- 功能门禁：计划导入、动态接入、里程碑发布事实、资源分配、冲突告警、人工裁决链路可端到端演示。
-- 数据门禁：核心实体对账通过率 >= 99.9%，无高危不一致项。
-- 一致性门禁：Outbox / CDC、重放、幂等和断线补偿完成验证。
-- 安全门禁：统一认证鉴权生效，关键接口通过授权与审计检查。
-- 演练门禁：完成数据库恢复、事件重放和订阅补偿演练。
-
-## 15. 文档边界与引用
-
-- 本文档定义首期可开工的高层设计，不展开字段级数据字典和实现细节。
-- 技术栈主选、后续启用条件以 `airport-wiki/concepts/aodb/开源技术栈选型决策.md` 为准。
-- 需求边界、验收基线以 `airport-wiki/concepts/aodb/AODB 核心需求提炼.md` 为准。
+- 本文档定义首期可开工的技术方案，不展开字段级数据字典和实现细节。
+- 技术栈主选和启用条件以 `airport-wiki/concepts/aodb/开源技术栈选型决策.md` 为准。
+- 需求边界以 `airport-wiki/concepts/aodb/AODB 核心需求提炼.md` 为准。
 - 字段级权威矩阵以 `airport-wiki/concepts/aodb/AODB 字段级权威矩阵.md` 为准。
 - 事件 envelope 和 payload 草案以 `airport-wiki/concepts/aodb/AODB 事件 Schema 草案.md` 为准。
 - 最小部署拓扑和恢复策略草案以 `airport-wiki/concepts/aodb/AODB 最小部署拓扑草案.md` 为准。
-- 实施拆解以 `airport-wiki/concepts/aodb/AODB 实施 Backlog.md` 为准。
 - 关键设计取舍以 `airport-wiki/concepts/aodb/adr/` 下 ADR 为准。