wiki/tasks/flightradar24/docs/RTL-SDR_TZ.md

ТЗ: Приём, хранение и обработка данных с RTL-SDR для FR24 / noisemap

1. Цель

Построить локальный контур приёма ADS-B данных с RTL-SDR, их предобработки, хранения в PostgreSQL/PostGIS и дальнейшего использования для:

• восстановления данных после сбоев без потерь,
• формирования сущностей рейсов и треков,
• расчёта производных шумовых данных,
• визуализации на карте в рамках проекта FR24 / noisemap.

2. Целевой контур

Система разворачивается на одной VM в PVE.

Ограничения VM

• CPU: до 6 vCPU
• RAM: 10–12 GB
• SSD: 80–100 GB max

Аппаратный вход

• RTL-SDR подключён к физической машине по USB
• PVE-хост пробрасывает USB в VM

Развёртывание

• Docker Compose
• каждый компонент в отдельном контейнере

3. Архитектура

Компоненты внутри VM

• postgres + postgis
• capture
• preprocess
• api/viewer
• optional: monitoring

Принцип

• одна VM
• одна PostgreSQL база
• сырьё и обработанные данные живут в одной БД, но логически разделены
• сырьё хранится с небольшим retention и используется для догоняющей обработки

4. Режимы работы

4.1 Live mode

• система принимает поток в реальном времени
• записи сохраняются в сырьевой слой
• данные сразу уходят в предобработку

4.2 Recovery mode

• если обработка отстала или упала,
• но сырьё ещё доступно,
• система автоматически догоняет пропущенный диапазон

4.3 Overlap mode

• при догоняющей обработке допускается небольшой перекрывающийся участок
• это нужно, чтобы не терять данные на границах и компенсировать сбои

5. Хранение данных

5.1 Retention

• сырьё хранится 3 дня
• после этого raw-слой чистится автоматически
• 3 дня — минимальный гарантированный горизонт для восстановления

5.2 База

• PostgreSQL
• PostGIS обязателен

5.3 Принцип хранения

• raw-данные отделены от core-данных
• core-данные очищены и оптимизированы под запросы карты и расчётов
• схема должна быть компактной, без лишних таблиц и тяжёлой нормализации

6. Объекты хранения

Минимальный набор сущностей:

captures

Сессии приёма. Хранят:

• старт и конец сессии
• источник приёма
• статус
• покрытый диапазон времени
• признаки сбоя / восстановления

raw_packets

Сырой поток. Хранят:

• timestamp
• payload/packet data
• signal metadata при наличии
• привязку к capture/session

aircraft

Справочник бортов. Хранят:

• ICAO24
• callsign
• тип/категорию при наличии
• оператор/авиакомпанию при наличии

flights

Сущность рейса. Хранят:

• flight id / number
• aircraft
• время начала и конца
• маршрут / аэропорты при наличии
• состояние заполненности

track_points

Точки трека. Хранят:

• время
• координаты
• высоту
• скорость
• курс
• принадлежность к flight/track

tracks

Сводка трека. Хранят:

• bbox
• длительность
• min/max altitude
• количество точек
• краткое описание маршрута

processing_state

Состояние пайплайна. Хранят:

• последний успешный checkpoint
• обработанный диапазон
• отставание
• состояние recovery

noise_results

Производные данные для карты. Хранят:

• расчётные зоны/радиусы
• интенсивность/плотность
• геометрию для визуализации
• привязку к рейсу/треку/времени

7. Основные требования к обработке

7.1 Приём

• принимать ADS-B поток от RTL-SDR
• сохранять сырьё до обработки
• не терять данные при временном сбое downstream

7.2 Предобработка

• нормализовать записи
• выделять рейсы
• строить треки
• обновлять state обработки

7.3 Восстановление

• после сбоя искать недостающий диапазон
• добирать пропущенные записи из raw-слоя
• допускается overlap

7.4 Оптимизация

• обработка должна быть лёгкой по CPU и памяти
• БД и схема должны быть компактными
• лишних промежуточных слоёв не заводить

8. Карта и визуализация

Система должна поддерживать данные, нужные для:

• отображения треков рейсов
• отображения шумовых зон
• анализа плотности пролётов
• фильтрации по времени
• отрисовки результатов на карте

9. Требования к инфраструктуре

• запуск через Docker Compose
• отдельные контейнеры для ключевых частей
• автозапуск после ребута VM
• возможность мониторить состояние приёма и БД
• логирование по каждому компоненту отдельно

10. Критерии приёмки

Система считается готовой, если:

• RTL-SDR отдаёт поток в VM через USB passthrough
• raw-данные сохраняются в PostgreSQL
• raw retention работает на 3 дня
• при сбое система может догнать пропущенный диапазон
• в БД присутствуют рейсы, треки и точки треков
• PostGIS используется для геоданных
• данные доступны для визуализации на карте
• контейнеры поднимаются через Docker Compose

11. Открытые вопросы, которые ещё стоит уточнить позже

• точный формат сырьевых пакетов
• нужен ли отдельный UI мониторинга
• нужен ли архив beyond 3 days
• какие индексы и партиционирование делать на старте
• где именно будет жить API noisemap после переноса

12. Итерация 2 — обязательный список улучшений

Следующая итерация ТЗ должна включать:

• мониторинг отвалившегося RTL-SDR и автоперезапуск capture
• healthcheck контейнеров и БД
• политика ротации логов и объёма диска
• схема индексов и партиционирования raw/track tables
• unique key / dedup стратегия для overlapping recovery
• экспорт/импорт исторических данных при миграции
• резервное копирование PostgreSQL и восстановление
• уведомления о деградации приёма или заполнении диска
• контракт между ingest-слоем и noisemap UI, если они остаются раздельными

13. Анализ: ничего ли не упущено

Дополнительно стоит проверить перед реализацией:

• нужен ли отдельный UI мониторинга
• где живёт API после переноса
• как именно партиционируются raw_packets и track_points
• нужен ли отдельный архив после 3 дней
• какую политику дедупликации выбрать для overlap на границах
• как восстанавливать БД после полного падения VM

---

Подготовлено на основе текущей архитектуры FR24/noisemap и согласованных ограничений VM.