wiki/tasks/flightradar24/docs/STEP2_DATA_MART.md

Шаг 2: Витрина данных — объединение FR24 API + табло + RTL-SDR

Статус

🔲 Не начат (зависит от Шага 1)

Цель

Спроектировать и реализовать витрину данных (data mart) которая объединяет три источника:

1. FR24 API — треки и рейсы из внешнего API (схема fr24_ext)
2. Онлайн табло — расписание и статусы рейсов (схема fr24_ext)
3. RTL-SDR dongle — локально принятые ADS-B треки (схема fr24)

Витрина — это набор материализованных представлений и таблиц в схеме fr24_mart, которые склеивают данные из всех источников в единую модель для визуализации и анализа.

---

Бизнес-требования

BR-1: Единая модель рейса

• Рейс идентифицируется по callsign + дата
• Один рейс может иметь данные из нескольких источников одновременно
• Приоритет данных: RTL-SDR (наиболее точный) > FR24 API > табло
• Витрина должна показывать из какого источника взяты данные

BR-2: Обогащение данных

• К треку из RTL-SDR добавлять данные из табло (авиакомпания, маршрут, тип ВС)
• К треку из FR24 API добавлять данные из табло (статус, фактическое время)
• Если рейс есть в табло но нет трека — показывать как "нет данных о треке"

BR-3: Покрытие источников

• Метрика: % рейсов из табло для которых есть трек (RTL-SDR или FR24)
• Метрика: % рейсов с треком из RTL-SDR vs только FR24
• Метрика: среднее качество трека (кол-во точек, покрытие маршрута)

BR-4: Шумовая модель

• Витрина должна содержать поле noise_score для каждой точки трека
• Расчёт: на основе высоты, скорости, типа ВС (упрощённая модель из прототипа)
• Агрегация: суммарный шум по сетке 0.01° × 0.01° за период

---

Технические требования

Схема fr24_mart

-- Единая таблица рейсов (объединение источников)
fr24_mart.flights_unified (
  unified_id, callsign, flight_date,
  origin_iata, destination_iata, airline_iata, aircraft_type,
  scheduled_dep, actual_dep, status,
  has_rtlsdr_track BOOL, has_fr24_track BOOL,
  rtlsdr_points INT, fr24_points INT,
  source_priority TEXT,  -- 'rtlsdr' | 'fr24' | 'schedule_only'
  updated_at
)

-- Единые точки трека (лучший доступный источник)
fr24_mart.track_points_unified (
  point_id, unified_id, observed_at,
  lat, lon, altitude_m, speed_kt, heading_deg,
  source TEXT,  -- 'rtlsdr' | 'fr24'
  noise_score FLOAT
)

-- Шумовая сетка (агрегат)
fr24_mart.noise_grid (
  grid_id, grid_lat FLOAT, grid_lon FLOAT,
  period_date DATE,
  flight_count INT, total_noise_score FLOAT,
  avg_altitude_m FLOAT,
  updated_at
)

-- Покрытие источников (метрики)
fr24_mart.source_coverage (
  coverage_date DATE,
  total_schedule INT,
  with_rtlsdr INT, with_fr24 INT, schedule_only INT,
  rtlsdr_pct FLOAT, fr24_pct FLOAT
)

Обновление витрины

• Отдельный контейнер fr24-mart или cron внутри существующего
• Обновление каждые 10 минут
• Инкрементальное (только новые данные)

---

ТЗ для Dev-агента

Файлы для создания

tasks/flightradar24/ingest/mart/
  Dockerfile
  main.py          # планировщик обновления витрины
  build_unified.py # логика объединения источников
  noise_model.py   # расчёт noise_score (перенос из прототипа)
  requirements.txt
tasks/flightradar24/db/init/004_schema_mart.sql  # DDL схемы fr24_mart

Обновить

• tasks/flightradar24/compose/docker-compose.yml — добавить сервис mart

---

Тест-кейсы

TC-1: Объединение источников

• Рейс с треком из RTL-SDR и записью в табло — объединяется корректно
• Рейс только в табло — создаётся запись с source_priority = 'schedule_only'
• Рейс только в RTL-SDR (нет в табло) — создаётся с source_priority = 'rtlsdr'

TC-2: Приоритет источников

• При наличии RTL-SDR трека — используется он, не FR24
• При отсутствии RTL-SDR — используется FR24

TC-3: Шумовая модель

• noise_score рассчитывается для каждой точки трека
• noise_grid обновляется после добавления новых точек
• Агрегация по сетке 0.01° корректна

TC-4: Метрики покрытия

• source_coverage обновляется ежедневно
• % покрытия считается корректно

TC-5: Производительность

• Обновление витрины за 10 минут занимает < 60 сек
• Запрос noise_grid за 1 день < 500 мс

---

Зависимости

• Шаг 1 (схема fr24_ext должна быть заполнена)
• Схема fr24 (RTL-SDR данные)
• Модель шума из прототипа (tasks/flightradar24/prototype/docs/NOISE_MODEL.md)