From e7668d6c53f8dfae7d5d1099083b054b1b0f5f92 Mon Sep 17 00:00:00 2001
From: Stream <stream@openclaw>
Date: Sun, 19 Apr 2026 00:20:01 +0300
Subject: [PATCH] auto-sync: 2026-04-19 00:20:01

---
 memory/ontology/graph.jsonl                   |   3 +
 tasks/flightradar24/PROJECT.md                | 149 +++++++++++----
 tasks/flightradar24/README.md                 |  25 ++-
 tasks/flightradar24/docs/ARCHITECTURE.md      | 178 ++++++++++++++++++
 tasks/flightradar24/docs/DEV_AGENT_HANDOFF.md | 129 +++++++++++++
 tasks/flightradar24/docs/INDEX.md             |  40 ++++
 tasks/flightradar24/docs/TEST_PLAN.md         | 112 +++++++++++
 tasks/flightradar24/docs/VM_SETUP.md          | 141 ++++++++++++++
 8 files changed, 740 insertions(+), 37 deletions(-)
 create mode 100644 tasks/flightradar24/docs/ARCHITECTURE.md
 create mode 100644 tasks/flightradar24/docs/DEV_AGENT_HANDOFF.md
 create mode 100644 tasks/flightradar24/docs/INDEX.md
 create mode 100644 tasks/flightradar24/docs/TEST_PLAN.md
 create mode 100644 tasks/flightradar24/docs/VM_SETUP.md

diff --git a/memory/ontology/graph.jsonl b/memory/ontology/graph.jsonl
index ad3242b..2adcbed 100644
--- a/memory/ontology/graph.jsonl
+++ b/memory/ontology/graph.jsonl
@@ -144,3 +144,6 @@
 {"op": "update", "id": "task_snowbike_kb_viewer", "properties": {"folder": "tasks/snowbike-rag/TASKS/active/kb-viewer/", "doc_path": "tasks/snowbike-rag/TASKS/active/kb-viewer/TASK.md"}, "timestamp": "2026-04-18T15:03:14.572807+00:00"}
 {"op": "create", "entity": {"id": "task_snowbike_rag_project_setup", "type": "Task", "properties": {"title": "Оформить Snowbike RAG как проект", "status": "active", "project": "proj_snowbike_rag", "folder": "tasks/snowbike-rag/TASKS/active/project-setup/", "doc_path": "tasks/snowbike-rag/TASKS/active/project-setup/TASK.md"}, "created": "2026-04-18T15:03:14.572807+00:00"}, "timestamp": "2026-04-18T15:03:14.572807+00:00"}
 {"op": "create", "entity": {"id": "task_fr24_rtl_sdr_iteration_2", "type": "Task", "properties": {"title": "FR24 RTL-SDR ТЗ: вторая итерация", "status": "open", "priority": "high", "project": "proj_noisemap", "description": "Дооформить вторую итерацию ТЗ для RTL-SDR контура: мониторинг, healthchecks, ротация логов, индексы/партиционирование, dedup для overlap, backup/restore, уведомления, контракт ingest↔UI."}, "created": "2026-04-18T21:03:00Z"}, "timestamp": "2026-04-18T21:03:00Z"}
+{"op": "create", "entity": {"id": "doc_fr24_rtl_sdr_architecture", "type": "Document", "properties": {"title": "FR24 RTL-SDR architecture", "path": "tasks/flightradar24/docs/ARCHITECTURE.md", "summary": "Контейнерная архитектура ingest-контура RTL-SDR для FR24 / noisemap."}, "created": "2026-04-18T21:11:00Z"}, "timestamp": "2026-04-18T21:11:00Z"}
+{"op": "create", "entity": {"id": "doc_fr24_rtl_sdr_tz", "type": "Document", "properties": {"title": "FR24 RTL-SDR TZ", "path": "tasks/flightradar24/docs/RTL-SDR_TZ.md", "summary": "ТЗ на приём, хранение и обработку данных с RTL-SDR для FR24 / noisemap."}, "created": "2026-04-18T21:11:00Z"}, "timestamp": "2026-04-18T21:11:00Z"}
+{"op": "create", "entity": {"id": "doc_fr24_test_plan", "type": "Document", "properties": {"title": "FR24 RTL-SDR test plan", "path": "tasks/flightradar24/docs/TEST_PLAN.md", "summary": "Smoke, integration, recovery and retention checks for the RTL-SDR ingest stack."}, "created": "2026-04-18T21:18:00Z"}, "timestamp": "2026-04-18T21:18:00Z"}
diff --git a/tasks/flightradar24/PROJECT.md b/tasks/flightradar24/PROJECT.md
index e5aa968..74609e5 100644
--- a/tasks/flightradar24/PROJECT.md
+++ b/tasks/flightradar24/PROJECT.md
@@ -1,43 +1,122 @@
-# Проект: Карта шумового загрязнения FR24
+# Проект: FR24 / noisemap + RTL-SDR ingest
 
-## Общее
-- **Старт:** 22 марта 2026, **последнее обновление:** 27 марта 2026
-- **URL:** https://openclaw.mva154.duckdns.org/noisemap/
-- **Расположение:** `tasks/flightradar24/prototype/`
-- **Стек:** Flask + OpenLayers 10 + Turf.js (Canvas2D, без WebGL) + flask-compress (gzip)
+## 1. Назначение
+Проект строит карту шумового загрязнения авиации для Московской области и развивает её в сторону локального ADS-B контура на RTL-SDR.
 
-## Данные
-- 258 рейсов / 50 282 точки (4 аэропорта SVO/DME/VKO/ZIA, только 20–21.03.2026)
-- FR24 кредиты: ЗАКОНЧИЛИСЬ 27.03.2026 (402 при попытке загрузить 26 марта)
-- FR24 ключи: `FLIGHTRADAR24_API_KEY` в `~/.openclaw/.env` (перенесено из prototype/.env 01.04.2026)
-- Яндекс.Расписания: ключ `788c6840-...`, код SVO: `s9600213`
+Сейчас проект состоит из двух связанных частей:
+- **noisemap / FR24-прототип** — визуализация и расчёт шумовой плотности на базе исторических данных Flightradar24
+- **RTL-SDR ingest-контур** — приём ADS-B с локального приёмника, хранение в PostgreSQL/PostGIS и восстановление данных после сбоев
 
-## Важные особенности API
-- bounds FR24 API = `lat_max,lat_min,lon_min,lon_max`
-- `flight-tracks` не поддерживает фильтр по времени
+## 2. Статус
+- **Старт проекта:** 22 марта 2026
+- **Текущий статус:** активен
+- **Текущий фокус:** переход от FR24-only к локальному RTL-SDR контуру с PostgreSQL/PostGIS
+- **Последнее обновление:** 18 апреля 2026
 
-## Реализовано (статус 27.03.2026)
-- ✅ Слой "Плотность пролётов" — `density_model.py` + `/api/density` + Vector layer (Canvas2D)
-- ✅ Метрика рейсов/час (count / num_hours), макс. 1.46/ч над SVO
-- ✅ Радиусы влияния: H<1800м→2км, H<5000м→4км, H<7000м→7км, H≥7000м→не считать
-- ✅ Кэш плотности по ключу date_from_date_to (gzip ~220KB), пересчёт по ?refresh=1
-- ✅ Все рейсы загружаются в память при старте, фильтрация на клиенте (мгновенно)
-- ✅ Кастомный ползунок по дням: точки, drag, кнопка сброса ✕
-- ✅ Легенда плотности: градиент 0/ч → 2/ч → 4+/ч
-- ✅ Попап при клике: рейс./ч + всего пролётов + мин. высота
-- ✅ `/api/dates`, `/api/density?date_from&date_to`
-- ✅ `fetch_tablo.py` — загрузка табло через Яндекс.Расписания
+## 3. Текущая часть: noisemap / FR24-прототип
+### URL
+- https://openclaw.mva154.duckdns.org/noisemap/
 
-## Бэклог
-- [ ] Пополнить кредиты FR24 → загрузить 26 марта и другие дни
-- [ ] **RTL-SDR Blog V4** — отказ от FR24, приём ADS-B напрямую (1090 МГц): RTL-SDR → dump1090/readsb → JSON → сервер → noisemap
-- [ ] Модель шума v2: группы ВС (тяжёлый/средний/лёгкий), NPD-кривые OpenANP
-- [ ] Ночной штраф Lden в модели шума
-- [ ] Оптимизация расчёта плотности (~13сек → цель <5сек)
+### Расположение
+- `tasks/flightradar24/prototype/`
+
+### Стек
+- Flask
+- OpenLayers 10
+- Turf.js
+- Canvas2D
+- flask-compress
+
+### Что уже реализовано
+- слой "Плотность пролётов"
+- метрика рейсов/час
+- радиусы влияния по высоте
+- кэш плотности
+- слайдер по дням
+- легенда и попап по рейсам
+- `/api/dates` и `/api/density`
+- загрузка табло через Яндекс.Расписания
+
+### Ограничения текущей части
+- FR24 кредиты закончились
+- охват данных неполный
+- ночные рейсы и часть траекторий не покрываются
+
+## 4. Новая часть: RTL-SDR ingest-контур
+### Цель
+Построить локальный контур приёма ADS-B с RTL-SDR, который:
+- принимает поток в real time
+- сохраняет сырьё с retention 3 дня
+- догоняет пропуски после сбоя
+- хранит данные в PostgreSQL/PostGIS
+- отдаёт данные для визуализации на карте
+
+### Архитектурные рамки
+- 1 VM в PVE
+- USB RTL-SDR пробрасывается в VM
+- Docker Compose
+- отдельные контейнеры для компонентов
+- PostgreSQL + PostGIS
+- сырьё и core-данные в одной БД, но логически разделены
+
+### Согласованные ограничения VM
+- CPU: до 6 vCPU
+- RAM: 10–12 GB
+- SSD: 80–100 GB max
+
+### Режимы работы
+- live
+- recovery
+- overlap recovery
+
+### Базовые сущности хранения
+- `captures`
+- `raw_packets`
+- `aircraft`
+- `flights`
+- `track_points`
+- `tracks`
+- `processing_state`
+- `noise_results`
+
+## 5. Данные и источники
+### FR24
+- исторические данные использовались для прототипа noisemap
+- FR24 API ключ хранится в `~/.openclaw/.env`
+- ключи и секреты не хранятся в проектных файлах
+
+### ADS-B / RTL-SDR
+- локальный источник для ingest-контура
+- основной переходной источник после исчерпания FR24-only подхода
+
+## 6. Бэклог
+### Для FR24 / noisemap части
+- [ ] Пополнить кредиты FR24, если потребуется добор исторических дней
+- [ ] Улучшить модель шума v2
+- [ ] Ночной штраф Lden
+- [ ] Оптимизировать расчёт плотности
 - [ ] Экспорт зон в GeoJSON/KML
 
-## Ограничения текущего подхода
-- 32% охват рейсов, ночные рейсы без ADS-B не находятся
+### Для RTL-SDR ingest-контура
+- [ ] Описать схему БД и индексы
+- [ ] Описать контейнеры и compose-файл
+- [ ] Описать мониторинг и healthchecks
+- [ ] Описать backup/restore
+- [ ] Определить контракт между ingest и noisemap UI
 
-## Девлог
-`tasks/flightradar24/prototype/docs/DEVLOG.md`
+## 7. Документация
+- `tasks/flightradar24/README.md` — обзор проекта
+- `tasks/flightradar24/docs/ARCHITECTURE.md` — контейнерная архитектура ingest-контура
+- `tasks/flightradar24/docs/RTL-SDR_TZ.md` — ТЗ на ingest-контур
+- `tasks/flightradar24/prototype/docs/ARCHITECTURE.md` — архитектура прототипа
+- `tasks/flightradar24/prototype/docs/NOISE_MODEL.md` — модель шума
+- `tasks/flightradar24/prototype/docs/DATA_LOADING.md` — загрузка данных
+- `tasks/flightradar24/prototype/docs/UI.md` — UI
+
+## 8. Критерий направления
+Проект считается развивающимся правильно, если:
+- noisemap остаётся рабочим и полезным
+- ingest-контур получает данные без дырок
+- recovery умеет догонять сырьё автоматически
+- БД не раздувается сверх лимитов VM
+- карта продолжает получать данные для визуализации
diff --git a/tasks/flightradar24/README.md b/tasks/flightradar24/README.md
index 020a4bd..264f315 100644
--- a/tasks/flightradar24/README.md
+++ b/tasks/flightradar24/README.md
@@ -1,6 +1,27 @@
-# Карта шумового загрязнения от самолётов (Московская область)
+# FR24 / noisemap
 
-Веб-приложение для визуализации шумового загрязнения от воздушных судов на основе исторических данных Flightradar24.
+Проект шумовой карты авиации для Московской области и локального ADS-B ingest-контура на RTL-SDR.
+
+## Что внутри
+- **noisemap / FR24-прототип** — визуализация и расчёт шумовой плотности на базе исторических данных Flightradar24
+- **RTL-SDR ingest-контур** — локальный приём ADS-B, хранение в PostgreSQL/PostGIS и recovery после сбоев
+
+## Куда смотреть
+- `tasks/flightradar24/PROJECT.md` — общий статус проекта
+- `tasks/flightradar24/docs/INDEX.md` — карта документации
+- `tasks/flightradar24/docs/ARCHITECTURE.md` — контейнерная архитектура ingest-контура
+- `tasks/flightradar24/docs/RTL-SDR_TZ.md` — ТЗ на RTL-SDR ingest
+- `tasks/flightradar24/docs/VM_SETUP.md` — инструкция по созданию VM в PVE
+- `tasks/flightradar24/docs/DEV_AGENT_HANDOFF.md` — пакет передачи Dev-агенту
+
+## Текущий статус
+- FR24-прототип жив и остаётся в проекте как историческая и визуальная база
+- новая линия проекта — переход к локальному RTL-SDR контуру
+- целевая БД: PostgreSQL + PostGIS
+- целевое развёртывание: одна VM + Docker Compose
+
+## Историческая часть
+Ниже сохранена справка по старому FR24/noisemap-прототипу.
 
 ## 📋 О проекте
 
diff --git a/tasks/flightradar24/docs/ARCHITECTURE.md b/tasks/flightradar24/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..7159b6b
--- /dev/null
+++ 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`
+
diff --git a/tasks/flightradar24/docs/DEV_AGENT_HANDOFF.md b/tasks/flightradar24/docs/DEV_AGENT_HANDOFF.md
new file mode 100644
index 0000000..a0c11d4
--- /dev/null
+++ 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-агент успешно передал работу, если после его первого прохода:
+- понятно, какие сервисы и как поднимаются
+- понятно, где жить данным
+- понятно, как восстанавливать отставание
+- понятно, что осталось уточнить перед запуском в прод
diff --git a/tasks/flightradar24/docs/INDEX.md b/tasks/flightradar24/docs/INDEX.md
new file mode 100644
index 0000000..8617945
--- /dev/null
+++ 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-агенту и как"
diff --git a/tasks/flightradar24/docs/TEST_PLAN.md b/tasks/flightradar24/docs/TEST_PLAN.md
new file mode 100644
index 0000000..d01eddf
--- /dev/null
+++ 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
diff --git a/tasks/flightradar24/docs/VM_SETUP.md b/tasks/flightradar24/docs/VM_SETUP.md
new file mode 100644
index 0000000..084ebb1
--- /dev/null
+++ 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-агента