# Наблюдения

`Observation` — центральная сущность портала. Одно наблюдение связывает станцию,
спутник, передатчик, набор TLE и автора, и покрывает временное окно одного пролёта.

## Жизненный цикл

1. **Планирование.** Наблюдение создаётся вручную или автоматически; рассчитывается окно
   `start`…`end` по актуальному TLE. См. [](scheduling.md).
2. **Выдача заданий.** Клиент станции запрашивает `/api/jobs/` при старте и получает свои
   будущие наблюдения с частотами и параметрами приёма; изменения расписания портал
   публикует ему по MQTT.
3. **Приём.** Клиент наводит антенну, запускает флоуграф, записывает аудио и водопад.
4. **Загрузка результатов.** Аудио (`payload`) и водопад (`waterfall`) уходят в
   `/api/observations/`, демодулированные кадры — в `/api/demoddata/`.
5. **Оценка.** Наблюдению проставляется статус — автоматически или человеком при
   вычитке. См. [](rating.md).
6. **Постобработка.** Декодирование данных, обновление статистики передатчиков,
   опционально — упаковка и архивация аудио.

## Статусы

Строковые статусы наблюдения:

| Статус | Значение |
|---|---|
| `unknown` | Не оценено |
| `good` | Приём успешен |
| `bad` | Приём неудачен |
| `failed` | Артефактов нет вовсе |

Внутренне статус хранится числом: `100` — good, `-1000` — failed, `0` — unknown.
Отдельно ведётся `waterfall_status` — результат ручной вычитки водопада; именно он
отличает оценку человека от автоматической.

## Артефакты

| Поле | Содержимое |
|---|---|
| `payload` | Аудиозапись пролёта |
| `waterfall` | Изображение-водопад (спектрограмма) |
| `demoddata` | Связанные записи `DemodData` — демодулированные кадры |

Каждый вид артефактов независимо кладётся локально или в S3 — флаги
`USE_S3_STORAGE_FOR_AUDIO`, `USE_S3_STORAGE_FOR_WATERFALL`, `USE_S3_STORAGE_FOR_DATA`.

Длительность аудио сверяется с длительностью окна с допуском
`OBS_AUDIO_DURATION_TOLERANCE`.

## Демодулированные данные

`DemodData` — кадры, полученные из наблюдения; связаны со спутником и станцией.
Обрабатываются задачами:

* `decode_current_frame` — декодирование конкретного кадра;
* `decode_recent_data` — ежедневное декодирование свежих данных;
* `decode_all_data`, `decode_all_nondecoded_data` — массовое и повторное декодирование.

Экспорт наборов кадров идёт через `export_frames` → `export_frames_batch` →
`export_frames_finalize`; результат хранится в `ExportedFramesetProxy`
(`ExportedFrameset`) и удаляется задачей `remove_old_exported_framesets` по истечении
`EXPORTED_FRAMESET_TIME_TO_LIVE`.

## Архивация аудио

Опциональный конвейер для экономии места:

1. `zip_audio_files` (каждые 15 минут) пакует аудио по `AUDIO_FILES_PER_ZIP` файлов в
   архив с префиксом `ZIP_FILE_PREFIX`.
2. `archive_audio_zip_files` (раз в час) выгружает архивы, по `ZIP_FILES_PER_ITEM` в
   элемент коллекции `ARCHIVE_COLLECTION`.
3. При включённых `REMOVE_ARCHIVED_AUDIO_FILES` / `REMOVE_ARCHIVED_ZIP_FILE` исходники
   удаляются.

Наблюдения моложе `ARCHIVE_SKIP_TIME` (48 ч) не архивируются. Обе задачи регистрируются
только при выключенном `USE_S3_STORAGE_FOR_AUDIO`.

## Просмотр

HTML-представления разложены по доменам в `network/base/views/`:
`observation.py` — списки и карточки наблюдений, `gallery.py` — галерея снимков,
`statistics.py` — сводная статистика.

Карточка наблюдения и её копия в проверке (`includes/observation_detail.html`) берут из
`observation_stages_context()` строку панели «Этапы приёма» — первый этап с ошибкой из
`client_metadata.stages`. Вкладка «Метаданные» над сырым деревом показывает таблицу
этапов с частями декодера; станция со старым клиентом этого блока не шлёт, и страница
выглядит как раньше.

Программный доступ — `/api/observations/`, `/api/demoddata/`, см. [](api/endpoints.md).