From 6211605cdba83dabaa44ea31bddb2359ea164f3f Mon Sep 17 00:00:00 2001 From: windyboy Date: Mon, 13 Apr 2026 15:27:20 +0800 Subject: [PATCH] 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. --- .../concepts/aodb/AODB 核心需求提炼.md | 103 +++++++++++++++ .../concepts/aodb/开源技术栈选型决策.md | 90 +++++++++++++ .../开源机场运营数据库（AODB）高层设计文档.md | 120 ++++++++++++++++++ 3 files changed, 313 insertions(+) create mode 100644 airport-wiki/concepts/aodb/AODB 核心需求提炼.md create mode 100644 airport-wiki/concepts/aodb/开源技术栈选型决策.md create mode 100644 airport-wiki/concepts/aodb/开源机场运营数据库（AODB）高层设计文档.md diff --git a/airport-wiki/concepts/aodb/AODB 核心需求提炼.md b/airport-wiki/concepts/aodb/AODB 核心需求提炼.md new file mode 100644 index 0000000..8369e80 --- /dev/null +++ b/airport-wiki/concepts/aodb/AODB 核心需求提炼.md @@ -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` diff --git a/airport-wiki/concepts/aodb/开源技术栈选型决策.md b/airport-wiki/concepts/aodb/开源技术栈选型决策.md new file mode 100644 index 0000000..948bc12 --- /dev/null +++ b/airport-wiki/concepts/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` 中定义。 diff --git a/airport-wiki/concepts/aodb/开源机场运营数据库（AODB）高层设计文档.md b/airport-wiki/concepts/aodb/开源机场运营数据库（AODB）高层设计文档.md new file mode 100644 index 0000000..c3de91a --- /dev/null +++ b/airport-wiki/concepts/aodb/开源机场运营数据库（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` 为准。