auto-sync: 2026-04-19 00:20:01

2026-04-19 00:20:01 +03:00
parent cc3207e571
commit e7668d6c53
8 changed files with 740 additions and 37 deletions
--- a/tasks/flightradar24/docs/ARCHITECTURE.md
+++ b/tasks/flightradar24/docs/ARCHITECTURE.md
@@ -0,0 +1,178 @@
+# Архитектура RTL-SDR ingest-контура для FR24 / noisemap
+
+## 1. Назначение
+Этот документ описывает контейнерную архитектуру локального ADS-B контура на RTL-SDR внутри одной VM в PVE.
+
+Цель контура:
+- принимать ADS-B поток в real time
+- хранить сырьё с retention 3 дня
+- автоматически догонять пропуски после сбоя
+- хранить данные в PostgreSQL/PostGIS
+- отдавать данные в noisemap / карту
+
+## 2. Ограничения среды
+- 1 VM в PVE
+- USB RTL-SDR проброшен в VM
+- ресурсы VM ограничены:
+  - CPU: до 6 vCPU
+  - RAM: 10–12 GB
+  - SSD: 80–100 GB max
+- развёртывание через Docker Compose
+
+## 3. Логическая схема
+
+```text
+RTL-SDR USB
+   ↓
+capture
+   ↓
+raw_packets / captures (PostgreSQL)
+   ↓
+preprocess
+   ↓
+flights / tracks / track_points / processing_state
+   ↓
+noise_results
+   ↓
+noisemap / UI / API
+```
+
+## 4. Контейнеры
+
+### 4.1 `postgres`
+**Назначение:** хранение всех данных проекта.
+
+Содержит:
+- `captures`
+- `raw_packets`
+- `aircraft`
+- `flights`
+- `track_points`
+- `tracks`
+- `processing_state`
+- `noise_results`
+
+Требования:
+- PostgreSQL
+- PostGIS enabled
+- volume для данных
+- регулярные backup/restore процедуры
+
+### 4.2 `capture`
+**Назначение:** приём ADS-B потока с RTL-SDR.
+
+Функции:
+- чтение USB-устройства
+- получение live-потока
+- запись сырья в PostgreSQL
+- фиксация `captures`
+- маркировка границ сессий приёма
+
+Требования:
+- лёгкий CPU footprint
+- устойчивость к временной потере downstream
+- healthcheck
+- автоматический рестарт
+
+### 4.3 `preprocess`
+**Назначение:** нормализация и догоняющая обработка.
+
+Функции:
+- обработка live-потока
+- разбор `raw_packets`
+- построение `aircraft`
+- построение `flights`
+- построение `tracks` и `track_points`
+- обновление `processing_state`
+- recovery с overlap при сбоях
+
+Требования:
+- инкрементальная обработка
+- дедупликация на границах overlap
+- ограничение по памяти
+- возможность догонять пропуски автоматически
+
+### 4.4 `api` / `viewer`
+**Назначение:** отдача данных для noisemap.
+
+Функции:
+- чтение обработанных данных из PostgreSQL
+- отдача треков, точек и шумовых результатов
+- фильтрация по периоду и зоне
+- API для карты/визуализации
+
+Требования:
+- лёгкие запросы
+- минимальная логика в рантайме
+- кэширование только при реальной необходимости
+
+### 4.5 `monitoring` (optional)
+**Назначение:** наблюдение за здоровьем контура.
+
+Функции:
+- healthcheck контейнеров
+- мониторинг задержки обработки
+- мониторинг заполнения диска
+- мониторинг статуса RTL-SDR
+- алерты при деградации
+
+## 5. Docker Compose структура
+Минимальный compose должен поднимать:
+- `postgres`
+- `capture`
+- `preprocess`
+- `api`
+
+Опционально:
+- `monitoring`
+
+### Сетевое правило
+- контейнеры общаются внутри одной docker network
+- наружу публикуется только `api` и, если нужно, `monitoring`
+- `postgres` не публикуется наружу
+
+## 6. Данные и потоки
+
+### 6.1 Live flow
+1. RTL-SDR → `capture`
+2. `capture` пишет сырьё в `raw_packets`
+3. `preprocess` читает сырьё
+4. `preprocess` обновляет `flights`, `tracks`, `track_points`
+5. `api` отдаёт данные на карту
+
+### 6.2 Recovery flow
+1. `preprocess` обнаруживает отставание
+2. ищет недостающий диапазон в `raw_packets`
+3. добирает пропущенные записи
+4. обрабатывает с небольшим overlap
+5. обновляет `processing_state`
+
+## 7. Автозапуск и устойчивость
+- контейнеры стартуют после reboot VM
+- каждый контейнер имеет healthcheck
+- сбой одного контейнера не должен валить всю VM
+- `capture` должен уметь переживать временный разрыв downstream
+- `preprocess` должен уметь догонять запись после восстановления
+
+## 8. Производительность
+С учётом ограничений VM:
+- минимизировать число контейнеров и лишних сервисов
+- не тащить тяжёлые брокеры очередей без необходимости
+- не строить много промежуточных копий данных
+- хранить сырьё коротко и чистить автоматически
+- тяжёлые вычисления держать инкрементальными
+
+## 9. Что должно быть детализировано дальше
+Следующие документы/итерации должны закрыть:
+- схему БД и индексы
+- backup/restore
+- мониторинг и алерты
+- контракт между `preprocess` и `api`
+- точный формат `raw_packets`
+- стратегию партиционирования
+
+## 10. Связь с проектом
+Этот документ — техническая основа для:
+- `tasks/flightradar24/PROJECT.md`
+- `tasks/flightradar24/docs/RTL-SDR_TZ.md`
+
--- a/tasks/flightradar24/docs/DEV_AGENT_HANDOFF.md
+++ b/tasks/flightradar24/docs/DEV_AGENT_HANDOFF.md
@@ -0,0 +1,129 @@
+# Dev-agent handoff: FR24 / noisemap RTL-SDR ingest
+
+## 1. Контекст
+Проект переходит от FR24-only прототипа к локальному ADS-B ingest-контуру на RTL-SDR.
+
+Нужно построить внутри одной VM:
+- Docker Compose стек
+- PostgreSQL + PostGIS
+- capture
+- preprocess
+- API / viewer
+- мониторинг по необходимости
+
+## 2. Что должно быть сделано
+### Основной объём работ
+- описать и реализовать Docker Compose стек
+- подготовить контейнер PostgreSQL/PostGIS
+- реализовать capture-контур приёма ADS-B
+- реализовать preprocess-контур нормализации и recovery
+- реализовать API для карты / noisemap
+- подготовить healthchecks
+- подготовить backup/restore процедуру
+- зафиксировать схему БД и индексы
+
+### Что важно не забыть
+- raw retention = 3 дня
+- live + recovery + overlap
+- одна VM
+- один PostgreSQL
+- сырьё и core-данные разделены логически
+- код и схема БД должны быть компактными, без лишних слоёв
+
+## 3. Ограничения
+### Железо
+- CPU: до 6 vCPU
+- RAM: 10–12 GB
+- SSD: 80–100 GB
+
+### Архитектурные ограничения
+- без лишних VM
+- без брокера очередей, если он не нужен по факту
+- без тяжёлой нормализации
+- без хранения сырья дольше согласованного retention без причины
+
+### Что не трогать без отдельного решения
+- PVE-хост
+- текущий FR24/noisemap прототип как работающий артефакт
+- секреты и ключи
+
+## 4. Источники правды
+Dev-агент должен читать:
+- `tasks/flightradar24/PROJECT.md`
+- `tasks/flightradar24/docs/ARCHITECTURE.md`
+- `tasks/flightradar24/docs/RTL-SDR_TZ.md`
+- `tasks/flightradar24/docs/VM_SETUP.md`
+- `tasks/flightradar24/prototype/docs/ARCHITECTURE.md`
+- `tasks/flightradar24/prototype/docs/NOISE_MODEL.md`
+
+## 5. Нужный результат от Dev-агента
+### Deliverables
+- `docker-compose.yml`
+- Dockerfile / образа для сервисов
+- SQL schema / migrations
+- capture service
+- preprocess service
+- API service
+- healthcheck endpoints
+- backup/restore notes
+- runtime README
+- test report with commands and outputs
+
+### Acceptance criteria
+- VM + compose stack стартуют без ручной магии
+- RTL-SDR доступен контейнеру capture
+- raw-данные попадают в PostgreSQL
+- preprocess умеет добирать пропуски после сбоя
+- tracks / flights / points доступны для карты
+- PostGIS используется для геоданных
+- compose можно перезапустить без потери консистентности
+- smoke / integration / recovery tests documented and passed
+- all blockers for final hardware verification explicitly listed
+
+## 6. Предпочтительный порядок реализации
+1. Схема БД
+2. Compose scaffold
+3. PostgreSQL/PostGIS
+4. capture
+5. preprocess
+6. API
+7. recovery / overlap
+8. backup / monitoring
+9. документация
+
+## 7. Рекомендуемый формат задания Dev-агенту
+Использовать один запуск с явным scope.
+
+```text
+Прочитай:
+- tasks/flightradar24/PROJECT.md
+- tasks/flightradar24/docs/ARCHITECTURE.md
+- tasks/flightradar24/docs/RTL-SDR_TZ.md
+- tasks/flightradar24/docs/VM_SETUP.md
+
+Сделай:
+1) Docker Compose стек для RTL-SDR ingest-контура
+2) PostgreSQL + PostGIS
+3) capture/preprocess/API сервисы
+4) healthchecks
+5) backup/restore notes
+6) краткий отчёт по рискам и что ещё нужно от Славы
+
+Ограничения:
+- одна VM
+- raw retention 3 дня
+- live + recovery + overlap
+- компактная схема, без лишней сложности
+
+Верни:
+- список созданных файлов
+- список ключевых решений
+- список открытых вопросов
+```
+
+## 8. Что считать успехом
+Dev-агент успешно передал работу, если после его первого прохода:
+- понятно, какие сервисы и как поднимаются
+- понятно, где жить данным
+- понятно, как восстанавливать отставание
+- понятно, что осталось уточнить перед запуском в прод
--- a/tasks/flightradar24/docs/INDEX.md
+++ b/tasks/flightradar24/docs/INDEX.md
@@ -0,0 +1,40 @@
+# FR24 / noisemap docs index
+
+Набор документов для перехода проекта от FR24-only прототипа к локальному RTL-SDR ingest-контуру.
+
+## Основные документы
+- `tasks/flightradar24/PROJECT.md` — общий статус и границы проекта
+- `tasks/flightradar24/docs/ARCHITECTURE.md` — контейнерная архитектура ingest-контура
+- `tasks/flightradar24/docs/RTL-SDR_TZ.md` — ТЗ на приём, хранение и обработку ADS-B данных
+- `tasks/flightradar24/docs/VM_SETUP.md` — инструкция по созданию VM в PVE
+- `tasks/flightradar24/docs/TEST_PLAN.md` — тестовый контракт и acceptance checks
+- `tasks/flightradar24/docs/DEV_AGENT_HANDOFF.md` — пакет передачи Dev-агенту
+
+## Исторические и вспомогательные документы
+- `tasks/flightradar24/README.md` — обзор проекта и текущая справка
+- `tasks/flightradar24/prototype/docs/ARCHITECTURE.md` — архитектура текущего FR24-прототипа
+- `tasks/flightradar24/prototype/docs/NOISE_MODEL.md` — шумовая модель прототипа
+- `tasks/flightradar24/prototype/docs/DATA_LOADING.md` — загрузка исторических данных
+- `tasks/flightradar24/prototype/docs/UI.md` — UI прототипа
+- `tasks/flightradar24/prototype/docs/DEVLOG.md` — журнал разработки
+
+## Что читать в каком порядке
+
+### Для запуска нового контура
+1. `PROJECT.md`
+2. `ARCHITECTURE.md`
+3. `RTL-SDR_TZ.md`
+4. `VM_SETUP.md`
+5. `DEV_AGENT_HANDOFF.md`
+
+### Для понимания старого прототипа
+1. `tasks/flightradar24/README.md`
+2. `prototype/docs/ARCHITECTURE.md`
+3. `prototype/docs/NOISE_MODEL.md`
+
+## Принцип
+- `PROJECT.md` отвечает на вопрос "что это за проект"
+- `ARCHITECTURE.md` отвечает на вопрос "как это разложено по контейнерам"
+- `RTL-SDR_TZ.md` отвечает на вопрос "что именно строим"
+- `VM_SETUP.md` отвечает на вопрос "как поднять инфраструктуру"
+- `DEV_AGENT_HANDOFF.md` отвечает на вопрос "что отдать Dev-агенту и как"
--- a/tasks/flightradar24/docs/TEST_PLAN.md
+++ b/tasks/flightradar24/docs/TEST_PLAN.md
@@ -0,0 +1,112 @@
+# FR24 / RTL-SDR test plan
+
+## 1. Цель
+Проверить, что локальный RTL-SDR ingest-контур работает корректно, устойчиво восстанавливается после сбоев и отдаёт данные в noisemap / карту без потерь и без разъезда состояния.
+
+## 2. Уровни тестирования
+
+### 2.1 Smoke tests
+Быстрая проверка, что стек вообще поднялся:
+- Docker Compose стартует без ошибок
+- `postgres` доступен внутри сети compose
+- `capture` стартует и видит RTL-SDR
+- `preprocess` стартует и подключается к БД
+- `api` отвечает на health endpoint
+
+### 2.2 Integration tests
+Проверка связности компонентов:
+- `capture` пишет записи в `raw_packets`
+- `preprocess` читает `raw_packets` и обновляет `processing_state`
+- `preprocess` создаёт/обновляет `flights`, `tracks`, `track_points`
+- `api` читает данные из БД и отдаёт их в формате, нужном для карты
+- PostGIS-функции работают на геометриях
+
+### 2.3 Recovery tests
+Проверка восстановления после сбоя:
+- остановить `preprocess`
+- продолжить запись сырья
+- поднять `preprocess`
+- убедиться, что он автоматически догоняет пропущенный диапазон
+- проверить, что overlap не даёт дублей
+
+### 2.4 Retention tests
+Проверка хранения сырья:
+- raw-данные доступны не менее 3 дней
+- после истечения retention raw-слой чистится автоматически
+- обработанные данные не удаляются вместе с raw без причины
+
+### 2.5 Resource tests
+Проверка в рамках лимитов VM:
+- CPU не выходит за разумный потолок при live-режиме
+- RAM не утекает при длительном прогоне
+- диск не растёт неконтролируемо
+- логирование и БД не съедают всё место
+
+## 3. Минимальный smoke checklist
+- [ ] VM загружается
+- [ ] USB passthrough RTL-SDR работает
+- [ ] `docker compose up -d` успешен
+- [ ] `postgres` живой и PostGIS включён
+- [ ] `capture` видит устройство
+- [ ] `preprocess` пишет state
+- [ ] `api` отвечает `/health`
+- [ ] хотя бы одна тестовая запись проходит путь raw → core
+
+## 4. Минимальный integration checklist
+- [ ] raw packet попадает в `raw_packets`
+- [ ] создаётся/обновляется `captures`
+- [ ] создаётся/обновляется `aircraft`
+- [ ] создаётся/обновляется `flights`
+- [ ] создаются `track_points`
+- [ ] обновляется `tracks`
+- [ ] `processing_state` отражает последний checkpoint
+- [ ] `api` возвращает данные для визуализации
+
+## 5. Recovery сценарий
+### Сценарий A: preprocess down
+1. Остановить `preprocess`
+2. Записать часть сырья
+3. Запустить `preprocess`
+4. Проверить, что недостающий диапазон дочитан
+5. Проверить отсутствие дублей на overlap
+
+### Сценарий B: temporary DB restart
+1. Перезапустить `postgres`
+2. Проверить, что контейнеры восстанавливают соединение
+3. Проверить, что `capture` и `preprocess` не теряют состояние навсегда
+
+### Сценарий C: capture restart
+1. Перезапустить `capture`
+2. Проверить, что new live поток продолжает попадать в raw слой
+3. Проверить, что recovery не ломается после краткой паузы
+
+## 6. Data correctness checks
+- координаты в допустимых диапазонах
+- время монотонно внутри одного трека/сессии там, где это ожидается
+- `track_points` привязаны к правильному `flight`/`track`
+- `tracks` и `flights` не расходятся по времени и объёму
+- геометрии PostGIS валидны
+
+## 7. Performance checks
+- нет резкого роста latency на ingest
+- процесс recovery не блокирует live ingest
+- API отвечает в приемлемое время на типовые запросы карты
+- индексы реально используются, а не декоративны
+
+## 8. What must be proven before handoff to Слава
+Перед передачей Славе должны быть подтверждены:
+- compose stack поднимается и переживает restart
+- USB RTL-SDR стабильно доступен в VM
+- raw retention работает
+- recovery работает
+- карта может читать данные из API
+- БД и схема не вываливаются за лимиты VM
+- базовые smoke/integration tests пройдены
+
+## 9. Что должен вернуть Dev-агент
+В отчёте Dev-агента должны быть:
+- список тестов, которые он запускал
+- команды, которыми он тестировал
+- результаты smoke/integration/recovery tests
+- замечания по рискам
+- список того, что требует реального RTL-SDR железа для final verification
--- a/tasks/flightradar24/docs/VM_SETUP.md
+++ b/tasks/flightradar24/docs/VM_SETUP.md
@@ -0,0 +1,141 @@
+# Инструкция: создание VM для RTL-SDR ingest-контура
+
+## 1. Цель
+Поднять на PVE отдельную VM, в которую пробрасывается RTL-SDR по USB, после чего внутри VM разворачивается Docker Compose стек с PostgreSQL/PostGIS, capture, preprocess и API.
+
+## 2. Рекомендуемый профиль VM
+Ограничения проекта:
+- CPU: до 6 vCPU
+- RAM: 10–12 GB
+- SSD: 80–100 GB
+
+### Рекомендация по стартовому размеру
+Если нет явного дефицита ресурсов на хосте:
+- 4 vCPU
+- 10 GB RAM
+- 80 GB SSD
+
+Если хост позволяет и нужен запас:
+- 6 vCPU
+- 12 GB RAM
+- 100 GB SSD
+
+## 3. ОС
+Рекомендуемая ОС:
+- Debian 12 minimal
+
+Причина:
+- предсказуемая база для Docker/PostgreSQL
+- меньше лишнего, чем в desktop-образах
+- удобно держать long-running сервисы
+
+## 4. Настройки VM в PVE
+### 4.1 Общие параметры
+- Name: `fr24-adsb` или `fr24-ingest`
+- Machine: `q35`
+- BIOS: `SeaBIOS`
+- CPU type: `host`
+- Disk bus: `VirtIO SCSI`
+- Network model: `VirtIO`
+- QEMU guest agent: enabled
+- Ballooning: disabled или очень консервативно
+
+### 4.2 Диск
+- один системный диск на `80–100 GB`
+- включить `Discard` / `SSD emulation`, если storage позволяет
+- не дробить диск без необходимости
+
+### 4.3 Сеть
+- подключить к основному bridge PVE
+- лучше использовать DHCP reservation или статический IP
+- имя хоста зафиксировать заранее, чтобы не плодить путаницу в compose и мониторинге
+
+## 5. Установка ОС
+1. Создать VM в PVE
+2. Подключить ISO Debian 12
+3. Установить minimal system
+4. Включить SSH server
+5. Создать обычного пользователя для администрирования
+6. После первого boot обновить систему
+
+## 6. Базовые пакеты внутри VM
+После установки:
+- `qemu-guest-agent`
+- `docker.io` или Docker Engine
+- `docker compose plugin`
+- `git`
+- `curl`
+- `ca-certificates`
+- `gnupg`
+- `lsb-release`
+- `usbutils`
+- `jq`
+- `chrony` или аналогичный time sync
+
+## 7. Подготовка каталогов
+Рекомендуемая структура на VM:
+- `/srv/fr24/`
+- `/srv/fr24/postgres/`
+- `/srv/fr24/data/`
+- `/srv/fr24/logs/`
+- `/srv/fr24/config/`
+
+Смысл:
+- отдельно держать данные и логи
+- не сваливать всё в home пользователя
+- проще backup/restore
+
+## 8. USB passthrough для RTL-SDR
+### 8.1 Принцип
+RTL-SDR подключён к физической машине по USB, а в VM он должен быть проброшен как USB-устройство.
+
+### 8.2 Рекомендация
+- использовать постоянный способ привязки устройства: по USB port или by-id, а не по случайному bus number
+- после reboot хоста и VM устройство должно подниматься без ручной переконфигурации
+
+### 8.3 Проверка в VM
+Внутри VM проверить:
+- `lsusb`
+- `dmesg | tail`
+- `rtl_test` или аналогичный тест захвата
+
+Если устройство не видно:
+- проверить, не занял ли его хост
+- проверить настройки passthrough в PVE
+- переподключить устройство через интерфейс PVE
+
+## 9. Docker Compose подготовка
+Перед запуском стека внутри VM:
+1. Создать рабочую директорию проекта
+2. Подготовить `.env` отдельно от репозитория
+3. Создать volume для PostgreSQL
+4. Подготовить network для compose
+5. Проверить, что контейнеры смогут обращаться друг к другу по service name
+
+## 10. Проверка после создания VM
+Минимальный чек-лист:
+- [ ] VM загрузилась после установки ОС
+- [ ] SSH доступен
+- [ ] `qemu-guest-agent` работает
+- [ ] RTL-SDR виден внутри VM
+- [ ] Docker и Compose работают
+- [ ] диск и RAM соответствуют лимитам
+- [ ] каталог `/srv/fr24` создан
+- [ ] время синхронизировано
+
+## 11. Что делать дальше после создания VM
+После VM setup передать работу Dev-агенту на:
+- Docker Compose стек
+- PostgreSQL/PostGIS
+- capture/preprocess/API контейнеры
+- healthchecks
+- backup/restore
+- мониторинг
+
+## 12. Критерий готовности VM
+VM считается готовой, если:
+- RTL-SDR доступен внутри VM
+- Docker Compose запускается без ошибок
+- есть место под PostgreSQL volume
+- система переживает reboot и сохраняет USB passthrough
+- VM готова принимать конфигурацию от Dev-агента