docs(aodb): add initial high-level design package

Capture a clear baseline across requirements, stack choices, and high-level architecture so review and implementation can align on scope and quality gates.
2026-04-13 15:27:20 +08:00
parent ab2182dee0
commit 6211605cdb
3 changed files with 313 additions and 0 deletions
@@ -0,0 +1,103 @@
+# AODB 核心需求提炼
+
+## 1. 文档定位
+
+本文档定义 AODB 的业务目标、范围边界、功能清单和验收指标，用于立项评审、架构设计和实施排期对齐。
+
+- 目标对象：年旅客吞吐量 500 万至 3000 万的中型机场
+- 目标系统：机场运营数据库（AODB）及其核心协同能力
+- 使用方式：作为 `开源机场运营数据库（AODB）高层设计文档.md` 和 `开源技术栈选型决策.md` 的上位需求输入
+
+## 2. 业务目标与范围
+
+### 2.1 业务目标
+
+1. 建立航班运营单一事实源（SSOT），消除多系统数据不一致。
+2. 支撑航班计划、动态运行、资源分配和里程碑协同的闭环运营。
+3. 通过事件驱动架构实现秒级数据传播，提升调度响应效率。
+4. 以开源技术栈实现可控成本、可持续演进和私有化可部署能力。
+
+### 2.2 范围边界
+
+MVP（首期必须）：
+
+- 航班计划导入（SSIM）与动态更新（AIDX/AFTN）
+- 机位/登机口/行李转盘/值机柜台基础资源分配
+- A-CDM 核心里程碑管理与变更发布
+- 运营告警（延误、资源冲突）
+- 外部数据共享接口（REST/GraphQL 订阅）
+
+非 MVP（后续迭代）：
+
+- 高级优化排班（全局优化/仿真）
+- 深度 AI 预测（跨季节模型、异常解释）
+- 多机场统一调度与集团化运营
+
+## 3. 功能需求清单
+
+| 功能域            | 核心能力                                              | 输入                       | 输出                     | MVP |
+| ----------------- | ----------------------------------------------------- | -------------------------- | ------------------------ | --- |
+| 航班数据管理      | 航班计划导入、动态更新、历史回放、航班配对（Linking） | SSIM、AIDX、AFTN           | 标准化航班主数据与状态流 | 是  |
+| 资源管理          | 机位/登机口/行李转盘/值机柜台分配与冲突检测           | 航班状态、资源可用性、规则 | 资源分配结果、冲突事件   | 是  |
+| A-CDM 里程碑      | 里程碑采集、校验、发布、追踪                          | ANSP/航司/地服事件         | 里程碑状态、时序记录     | 是  |
+| 实时计算引擎      | EIBT/EXIT/EXOT 预测、TSAT 计算                        | 运行态事件、历史统计       | 预测结果、排序建议       | 是  |
+| 告警与预警        | 延误告警、冲突告警、超阈值告警                        | 实时事件、规则配置         | 告警通知、处置状态       | 是  |
+| 信息共享（ACISP） | 面向航司/管制/地服的数据订阅                          | 业务实体与事件             | 外部查询/订阅接口        | 是  |
+| 起飞排序（PDS）   | TSAT/TTOT/EXOT 规则计算与可追溯                       | 里程碑、滑行预测、管制约束 | 排序建议与调整记录       | P1  |
+
+## 4. 标准与集成要求
+
+- AIDX（Aviation Information Data Exchange）：用于航班动态交换。
+- SSIM Chapter 7：用于季节性时刻表批量导入。
+- AFTN/SITA Type B：用于传统航电与运行消息接入。
+- ACARS（可选）：用于补充机载状态数据接入。
+
+集成约束：
+
+1. 所有外部输入必须经过标准化映射层，生成统一内部事件模型。
+2. 所有关键写入必须具备幂等键和可追溯来源字段。
+3. 解析失败消息必须进入死信队列并提供人工复核入口。
+
+## 5. 非功能需求（SLO）
+
+| 维度         | 目标值                        | 最低可接受值                  | 验收方式           |
+| ------------ | ----------------------------- | ----------------------------- | ------------------ |
+| 可用性       | 月度 99.95%                   | 月度 99.9%                    | 监控报表与故障统计 |
+| 事件处理延迟 | P95 <= 2 秒                   | P95 <= 5 秒                   | 压测与生产观测     |
+| 数据一致性   | 关键实体强一致                | 最终一致 <= 30 秒             | 对账任务与抽检     |
+| 恢复能力     | RTO <= 30 分钟，RPO <= 5 分钟 | RTO <= 2 小时，RPO <= 15 分钟 | 容灾演练记录       |
+| 审计追踪     | 100% 关键变更可追溯           | 99.9% 可追溯                  | 审计抽样与链路回放 |
+| 安全         | OIDC/OAuth2 + RBAC + 传输加密 | RBAC + 传输加密               | 安全测试与配置核查 |
+
+## 6. 上线假设与约束
+
+- 单机场优先，跨机场能力不作为首期交付前提。
+- 首期仅覆盖核心运行场景，不包含深度历史迁移改造。
+- 2 至 4 周快速上线仅适用于 MVP 范围和数据源受控场景。
+- 若外部系统接口稳定性不足，需预留灰度和人工兜底流程。
+
+## 7. 术语与缩写（权威定义）
+
+| 缩写  | 定义                                                |
+| ----- | --------------------------------------------------- |
+| AODB  | Airport Operational Database，机场运营数据库        |
+| SSOT  | Single Source of Truth，单一事实源                  |
+| A-CDM | Airport Collaborative Decision Making，机场协同决策 |
+| TSAT  | Target Start-up Approval Time，目标放行时间         |
+| TTOT  | Target Take-off Time，目标起飞时间                  |
+| EXOT  | Estimated Exit/Taxi-Out Time，预计滑出时间          |
+| EXIT  | Estimated Taxi-In Time，预计滑入时间                |
+| EIBT  | Estimated In-Block Time，预计靠桥时间               |
+
+## 8. 验收清单（DoD）
+
+1. MVP 功能域全部具备可演示业务闭环。
+2. 关键非功能指标达到最低可接受值。
+3. 核心实体和关键事件具备统一主键与幂等规则。
+4. 对外接口具备鉴权、限流、审计能力。
+5. 文档与实现一致，可用于排期拆解与测试用例编制。
+
+## 9. 关联文档
+
+- `airport-wiki/concepts/aodb/开源技术栈选型决策.md`
+- `airport-wiki/concepts/aodb/开源机场运营数据库（AODB）高层设计文档.md`
@@ -0,0 +1,90 @@
+# 开源技术栈选型决策
+
+## 1. 决策目标与原则
+
+本文档用于对 AODB 技术栈做唯一主选决策，避免多方案并列导致实施阶段反复。
+
+决策原则：
+
+1. 满足中型机场场景下的稳定性与可维护性。
+2. 优先选择成熟开源生态和团队可落地能力。
+3. 对核心路径采用单一主选，备选仅定义触发条件。
+4. 支持私有化部署和后续多机场扩展。
+
+## 2. 技术栈总览（主选）
+
+| 分层         | 主选方案                             | 说明                         |
+| ------------ | ------------------------------------ | ---------------------------- |
+| 主数据存储   | PostgreSQL 16                        | 关键业务数据强一致事务       |
+| 时序存储     | TimescaleDB                          | 里程碑与遥测时序数据         |
+| 缓存与实时态 | Redis 7 (Valkey)                     | 高频状态读取与短期流式缓存   |
+| 搜索分析     | OpenSearch 2.x                       | 全文检索、日志分析、开源友好 |
+| 事件总线     | Apache Kafka 3.x                     | 高吞吐与持久化事件骨干       |
+| 流处理       | Apache Flink 1.19                    | 低延迟有状态流计算与 CEP     |
+| 协议集成     | Apache Camel                         | AIDX/AFTN/SITA 协议适配      |
+| API 网关     | Kong Gateway OSS                     | 鉴权、限流、路由治理         |
+| GraphQL 层   | Hasura                               | 实时订阅与快速 API 暴露      |
+| 规则引擎     | Drools                               | 复杂规则可配置与可追溯       |
+| 工作流编排   | Temporal                             | 长事务与补偿流程编排         |
+| 认证授权     | Keycloak 24                          | OIDC/OAuth2 与 RBAC          |
+| 可观测性     | Prometheus + Grafana + Jaeger + Loki | 指标、追踪、日志统一观测     |
+| 容器平台     | Kubernetes + Helm                    | 标准化部署与扩缩容           |
+| 服务网格     | Linkerd                              | 轻量 mTLS 与服务治理         |
+| 对象存储     | MinIO                                | S3 兼容对象存储              |
+| 前端与终端   | React + TypeScript + PWA             | 看板与移动访问统一前端栈     |
+
+## 3. 关键决策与备选触发条件
+
+| 决策项       | 主选       | 备选          | 触发备选条件                                         | 说明                              |
+| ------------ | ---------- | ------------- | ---------------------------------------------------- | --------------------------------- |
+| 搜索引擎     | OpenSearch | Elasticsearch | 必须依赖特定商业插件时                               | 优先开源许可证与成本可控          |
+| GraphQL 引擎 | Hasura     | PostGraphile  | 已有团队深度 PostgreSQL 函数驱动实践且无需订阅增强时 | Hasura 对实时订阅和权限模型更直接 |
+| 工作流引擎   | Temporal   | Airflow       | 主要需求转为离线批任务编排时                         | AODB 更偏在线长事务与补偿         |
+| 服务网格     | Linkerd    | Istio         | 多集群高级流量治理和复杂策略显著增加时               | 中型机场先以轻量可运维为优先      |
+| 移动端策略   | PWA        | React Native  | 必须深度离线和原生硬件能力时                         | PWA 可降低交付复杂度和维护成本    |
+
+## 4. 分层选型理由（精要）
+
+### 4.1 数据层
+
+- PostgreSQL + TimescaleDB 统一 SQL 体验，降低多数据库运维复杂度。
+- Redis 负责热点读和实时态缓存，减轻主库读取压力。
+- OpenSearch 负责检索和日志分析，不承载强一致事务。
+
+### 4.2 消息与计算层
+
+- Kafka 作为唯一事件骨干，保障事件可回放与可追溯。
+- Flink 承担里程碑计算、异常检测和实时指标聚合。
+- Temporal 承担长流程编排（例如异常补偿和人工复核闭环）。
+
+### 4.3 集成与接口层
+
+- Camel 统一协议适配，减少自研连接器维护成本。
+- Kong 提供统一北向入口及治理能力。
+- Hasura 提供面向运营终端的订阅能力，降低 API 开发负担。
+
+### 4.4 安全与基础设施层
+
+- Keycloak 提供统一身份与授权管理。
+- Linkerd 提供轻量服务间 mTLS 与可观测能力。
+- Kubernetes + Helm 提供标准化部署与环境一致性。
+
+## 5. 风险与缓解
+
+| 风险                     | 影响               | 缓解措施                                     |
+| ------------------------ | ------------------ | -------------------------------------------- |
+| Kafka/Flink 运维门槛高   | 实施初期效率下降   | 提供标准化模板、最小可运行拓扑和 SRE Runbook |
+| 多协议接入数据质量不稳定 | 里程碑计算误差     | 建立标准化校验、死信队列和人工复核流程       |
+| 规则引擎规则膨胀         | 告警误报或漏报     | 规则分层管理、灰度发布和回放测试             |
+| 文档与实现偏离           | 评审通过后落地失真 | 将关键决策同步为 ADR 并纳入变更流程          |
+
+## 6. 版本与升级策略
+
+- 技术栈版本采用“年度主版本评审 + 季度补丁更新”策略。
+- 升级优先级：安全补丁 > 稳定性修复 > 新功能。
+- 升级前必须完成回归测试、性能基线对比和回滚演练。
+
+## 7. 与架构文档的边界
+
+- 本文档回答“选什么、为什么选、何时切备选”。
+- 具体数据模型、事件契约、流程编排细节在 `开源机场运营数据库（AODB）高层设计文档.md` 中定义。
@@ -0,0 +1,120 @@
+# 开源机场运营数据库（AODB）初步高层设计
+
+## 1. 目标
+
+本设计给出 AODB 的初步高层方案，重点回答三件事：
+
+1. 系统由哪些核心模块组成。
+2. 关键业务数据如何流转。
+3. 首期上线应覆盖哪些能力。
+
+适用范围：年旅客吞吐量 500 万至 3000 万机场。
+
+## 2. 设计原则
+
+- 单一事实源（SSOT）：航班与资源状态统一归口到 AODB。
+- 事件驱动：状态变化通过事件广播，减少系统耦合。
+- 标准优先：优先兼容 AIDX、SSIM、AFTN/SITA。
+- 渐进建设：先实现核心闭环，再扩展高级能力。
+
+## 3. 总体架构
+
+### 3.1 架构分层
+
+| 层级         | 主要能力                                 | 代表组件                                                           |
+| ------------ | ---------------------------------------- | ------------------------------------------------------------------ |
+| 接入层       | 外部系统接入、协议解析、统一 API         | API Gateway、协议适配器、SSIM 导入器                               |
+| 业务层       | 航班管理、资源分配、里程碑管理、告警处理 | Flight Service、Resource Service、Milestone Service、Alert Service |
+| 事件与计算层 | 事件总线、规则计算、基础预测             | Kafka、规则引擎、轻量预测服务                                      |
+| 数据层       | 事务存储、时序存储、缓存、检索           | PostgreSQL、TimescaleDB、Redis、OpenSearch                         |
+| 平台层       | 身份认证、部署运行、监控告警             | Keycloak、Kubernetes、Prometheus/Grafana                           |
+
+### 3.2 核心模块职责
+
+- Flight Service：维护航班计划、动态状态和历史记录。
+- Resource Service：进行机位/登机口等资源分配与冲突检查。
+- Milestone Service：维护 A-CDM 关键里程碑时间点。
+- Alert Service：统一处理延误、冲突等运营告警。
+- ACISP 接口层：向航司、地服、AOC 提供查询与订阅能力。
+
+### 3.3 核心实体标识约定（最小集）
+
+- Flight：`carrier + flight_number + op_date + leg_no` 作为业务唯一标识。
+- Milestone：`flight_id + milestone_type + source + event_time` 作为幂等写入键。
+- ResourceAssignment：`resource_type + resource_id + time_window + flight_id` 作为分配唯一键。
+
+## 4. 关键数据流（初版）
+
+### 4.1 航班计划导入流
+
+1. 外部系统提交 SSIM/AIDX 数据。
+2. 接入层完成解析与标准化。
+3. Flight Service 写入 AODB 主库。
+4. 业务层发布航班状态事件给订阅方。
+
+### 4.2 运行态更新流
+
+1. 空管/航司发送运行动态（如 ALDT、TOBT）。
+2. Milestone Service 更新关键节点。
+3. Resource Service 根据最新状态重算资源占用。
+4. Alert Service 在冲突或延误时触发通知。
+
+### 4.3 事件一致性与异常处理约束
+
+1. 所有写入事件必须携带 `idempotency_key`，重复事件只更新一次。
+2. 同一 `flight_id` 的事件按 `event_time + version` 排序处理，过旧版本进入旁路审计。
+3. 解析失败或校验失败消息进入 DLQ，并生成人工复核任务。
+4. 外部源异常抖动时启用降级策略：保留最近可信状态并标记数据可信度。
+
+## 5. 首期上线范围（MVP）
+
+首期建议只覆盖以下最小闭环：
+
+- 航班计划导入与实时状态更新。
+- 基础资源分配（机位、登机口）。
+- 关键里程碑跟踪（EOBT/TOBT/TSAT/ALDT/EIBT）。
+- 延误与资源冲突告警。
+- 对外查询接口与基础订阅推送。
+
+不纳入首期：
+
+- 复杂优化排班（全局优化模型）。
+- 深度 AI 预测与自适应调度。
+- 多机场统一调度中心能力。
+
+### 5.1 上线门禁（Go/No-Go）
+
+- 功能门禁：航班导入、里程碑更新、资源分配、冲突告警链路可端到端演示。
+- 性能门禁：关键状态事件处理延迟达到最低可接受值。
+- 数据门禁：核心实体对账通过率 >= 99.9%，无高危不一致项。
+- 安全门禁：统一认证鉴权生效，关键接口通过授权与审计检查。
+
+## 6. 非功能目标（初步）
+
+- 可用性：支持 7x24 运行。
+- 实时性：核心状态更新达到秒级可见。
+- 可追溯：关键状态变化具备审计记录。
+- 安全性：统一认证鉴权与最小权限控制。
+
+### 6.1 最小 SLO（评审口径）
+
+| 指标         | 目标值                        | 最低可接受值                  |
+| ------------ | ----------------------------- | ----------------------------- |
+| 可用性       | 月度 99.95%                   | 月度 99.9%                    |
+| 事件处理延迟 | P95 <= 2 秒                   | P95 <= 5 秒                   |
+| 容灾恢复     | RTO <= 30 分钟，RPO <= 5 分钟 | RTO <= 2 小时，RPO <= 15 分钟 |
+| 审计覆盖率   | 100% 关键变更可追溯           | 99.9% 可追溯                  |
+
+## 7. 迭代方向
+
+Phase 1：完成 MVP 闭环并上线单机场。
+
+Phase 2：补充预测能力和规则优化，提高运行效率。
+
+Phase 3：增强容量与容灾，支持多机场扩展。
+
+## 8. 文档边界与引用
+
+- 本文档仅定义初步高层设计，不展开详细数据字典、接口字段级协议和部署参数。
+- 技术栈主选、备选触发条件以 `airport-wiki/concepts/aodb/开源技术栈选型决策.md` 为准。
+- 需求边界、验收基线以 `airport-wiki/concepts/aodb/AODB 核心需求提炼.md` 为准。