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.