# Доменная модель

Все модели предметной области — в `network/base/models.py`, метрики аналитики —
в `network/analytics/models.py`, пользователь — в `network/users/models.py`.

## Связи

```
User ──┬── Station ──┬── Antenna ── FrequencyRange
       │             ├── StationStat
       │             ├── StationStatusLog
       │             ├── StationSchedule
       │             └── StationScheduleSec
       │
       └── Observation ── DemodData
              │
              ├── Station
              ├── Satellite ──┬── Transmitter ── Mode
              │               │        └── TransmitterStats
              │               ├── SatelliteStatusLog
              │               ├── SatelliteSubscription ── User
              │               ├── Telemetry
              │               ├── Tle ── LatestTleSet
              │               ├── Operator
              │               └── Network
              └── Tle

Launch ── SatelliteLaunch ── Satellite
NetworkSchedule (одиночная запись)
ExportedFrameset
```

## Основные сущности

`Station`
: Наземная станция. Владелец, координаты (`lat`, `lng`, `alt`), `horizon`, флаги
  `is_available` и `testing`, `violator_scheduling`, `target_utilization`.
  Конфигурация с портала — `desired_config` (плоский JSON, поля из
  `network/base/station_config.py`), `config_generation` и разовые команды станции
  `commands`; что станция сообщила о себе — `reported_status` (слияние по ключам:
  `modes`, `config`, `sdr`, `calibration`, `connection`, `agent`). Состояние (online / testing /
  unavailable / offline / never) не хранится — оно выводится из `last_seen` и
  двух флагов. Подробно — [](../stations.md).

`ReleaseChannel`
: Две строки, `canary` и `stable`, с digest образа клиента (только `имя@sha256:…`,
  тег валидатор не пропустит). Станция следует каналу `release_channel`; применяет
  образ агент станции, не портал, и отчитывается ключом `agent` в `reported_status`.

`Antenna`, `AntennaType`, `FrequencyRange`
: Антенное хозяйство станции. Диапазоны сопоставляются с частотами передатчиков при
  планировании.

`StationStat`, `StationStatusLog`
: Агрегаты по станции и история смены состояний. Строка журнала — три булевых
  (`is_connected`, `is_available`, `testing`), то есть снимок того же, из чего
  состояние выводится.

`StationSchedule`, `StationScheduleSec`, `NetworkSchedule`
: Параметры автопланирования: флаг `active`, список спутников и JSON с ограничениями.
  Первые две — one-to-one со станцией, третья одна на всю сеть.

`Satellite`
: Аппарат: `sat_id`, `norad_cat_id`, `source` (`Admin`/`CelesTrak`), связи с
  `Operator` и `Network`. Хранимый `status` — словарь satnogs-db
  (`in orbit`/`future`/`re-entered`/`launch failed`), потому что оттуда его приносит
  `fetch_data`; наружу в v1 идёт довоенный `alive`/`dead` через `status_badge`.
  `associated_satellite` — самоссылка на аппарат, в который этот слит: выборки по
  спутнику ходят по всей группе (`Satellite.associated_satellite_ids()`).
  `reception_status` и `reception_evidence` — подтверждён ли приём аппарата и чем;
  заполняются импортом, наружу пока не отдаются.

`SatelliteStatusLog`
: История **автоматических** смен статуса спутника: старый и новый статус,
  сработавшее правило (`spacetrack decay` / `tle silence`), время. Ручные правки
  сюда не пишутся — они есть в истории объекта в админке. Наличие строки заодно
  запрещает автоматике повторно переводить аппарат, которого человек вернул
  в орбиту — см. [](../satellites.md).

`SatelliteSubscription`
: Подписка пользователя на кадры спутника: пара `user` + `satellite`, уникальная.
  По ней ACL брокера пускает `subscriber-<id>` читать `satellites/<sat_id>/frames`, и
  только пока у пользователя есть станция в сети. Пароль подписчика —
  `User.subscription_key`, отдельный от API-токена. См. [](../satellites.md), раздел
  «Подписка на данные».

`Transmitter`, `Mode`, `TransmitterStats`
: Передатчик с частотами вверх/вниз, режимом, типом (`Transmitter`/`Transceiver`/
  `Transponder`), статусом (`active`/`inactive`/`invalid`) и статусом координации IARU.
  `params` — JSON с параметрами режима в том виде, в каком их отдаёт источник; портал
  их не разбирает, а переносит в снимок наблюдения и дальше в `/api/jobs/`. Исключение —
  режим `LoRa`: схему проверяет `Transmitter.clean()`, а форма админки рисует поля TinyGS
  (SF, полоса, CR, sync word…) и собирает из них `params` поверх прежних ключей.
  Пустой `params` у LoRa — «не настроен»: запись сохраняется (иначе у неё нельзя
  сменить даже статус), но ни один путь планирования её не берёт.

`Telemetry`
: Декодеры телеметрии спутника.

`Tle`, `LatestTleSet`
: Наборы орбитальных элементов. `Tle` — по записи на источник и загрузку,
  `LatestTleSet` — указатель на выбранный набор. См. [](../tle.md).

`Observation`
: Наблюдение. Ссылается на станцию, спутник, передатчик, `Tle` и автора; хранит окно
  `start`…`end`, `status`, `waterfall_status`, файлы `payload` и `waterfall`.
  Плюс снимок передатчика и станции на момент планирования — `transmitter_mode`,
  `transmitter_baud`, `transmitter_frequency_low`/`_high`/`_drift`,
  `transmitter_status`, `transmitter_parameters`, `station_lat`/`_lng`/`_alt` и
  остальные поля с теми же префиксами. Снимок снимается в `Observation.save()` при создании; читать данные
  о наблюдении нужно из него, а не по FK, иначе правка справочника задним числом
  перепишет историю. У наблюдений, которые ещё не начались,
  `refresh_future_observation_snapshots()` обновляет снимок по `post_save`
  передатчика — но только для станции, чьи антенны держат новую частоту.
  См. [](../observations.md).

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

`ExportedFrameset`
: Выгрузка набора кадров, живёт `EXPORTED_FRAMESET_TIME_TO_LIVE`.

`Launch`, `SatelliteLaunch`
: Запуск — носитель, площадка, оператор, орбита, статус и снимок Launch Library 2
  в `ll2`; `is_tracked` отделяет запуски сети от мирового календаря — и аппарат в
  его составе (тип миссии, статус). См. [](../launches.md).

`Operator`, `Network`
: Оператор аппарата и сеть, к которой он отнесён.

## Аналитика

`NetworkDailyMetric` — один срез по сети на дату; `StationDailyMetric` — срез на пару
«станция × дата». Состав полей — в [](../analytics.md).

## Соглашения

* Существующие миграции в `network/*/migrations/` не редактируются — только новые через
  `makemigrations`.
* Пользовательские строки в моделях оборачиваются в `gettext_lazy` (`_("...")`).
* Числовые справочники статусов вынесены в константы модуля: `OBSERVATION_STATUSES`,
  `STATION_STATUSES`, `SATELLITE_STATUS`, `TRANSMITTER_STATUS`, `TRANSMITTER_TYPE`,
  `SATELLITE_SOURCE`, `IARU_COORDINATION_STATUS`,
  `STATION_VIOLATOR_SCHEDULING_CHOICES`.
* Частоты валидируются в границах `MIN_FREQ` (0 Гц) … `MAX_FREQ` (40 ГГц).
* `ModifiedArrayField` — `ArrayField` с формой в виде набора чекбоксов; используется
  там, где нужно множественное значение из фиксированного списка.