diff --git a/tasks/flightradar24/docs/RTL-SDR_TZ.md b/tasks/flightradar24/docs/RTL-SDR_TZ.md new file mode 100644 index 0000000..bd16694 --- /dev/null +++ b/tasks/flightradar24/docs/RTL-SDR_TZ.md @@ -0,0 +1,210 @@ +# ТЗ: Приём, хранение и обработка данных с 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. Анализ: ничего ли не упущено +Что ещё важно добавить в следующую итерацию ТЗ: +- мониторинг отвалившегося RTL-SDR и автоперезапуск capture +- healthcheck контейнеров и БД +- политика ротации логов и объёма диска +- схема индексов и партиционирования raw/track tables +- unique key / dedup стратегия для overlapping recovery +- экспорт/импорт исторических данных при миграции +- резервное копирование PostgreSQL и восстановление +- уведомления о деградации приёма или заполнении диска +- если FR24 проект остаётся отдельным приложением, определить контракт между ingest-слоем и noisemap UI + +--- +Подготовлено на основе текущей архитектуры FR24/noisemap и согласованных ограничений VM.