# Аналитика

Приложение `network.analytics` считает суточные метрики по сети и по каждой станции и
отдаёт их через API и отдельную страницу-дашборд.

Смысл отдельного приложения — не гонять тяжёлые агрегаты по таблице наблюдений на каждый
запрос: метрики считаются раз в сутки и складываются в свои таблицы.

## Модели

### NetworkDailyMetric

Одна запись на дату (`date` уникальна) — срез по всей сети:

| Группа | Поля |
|---|---|
| Станции | `total_stations`, `active_stations`, `inactive_stations`, `testing_stations` |
| Объёмы | `total_observations`, `total_demod_data`, `total_images` |
| Качество | `good_observations`, `bad_observations`, `failed_observations`, `unknown_observations` |
| Покрытие | `distinct_satellites_observed` |

### StationDailyMetric

Запись на пару «станция × дата»:

`observations_count`, `demod_data_count`, `images_count`, `status_snapshot`
(статус станции на момент среза), `good_observations`, `bad_observations`,
`failed_observations`, `unknown_observations`, `distinct_satellites_observed`.

## Расчёт

Задача `generate_daily_metrics(days_ago=1, refresh_days=REFRESH_WINDOW_DAYS)` запускается
ежедневно в 00:30 UTC и пересобирает метрики **за последние 30 дней**, а не только за
вчера.

```{note}
Окно в 30 дней не избыточно: оценка качества приёма проставляется позже самого
наблюдения (вручную при вычитке или отложенными задачами), поэтому пересчёт одного
прошедшего дня оставил бы метрики качества устаревшими. См. [](rating.md).
```

Историческое наполнение — задача `backfill_historical_metrics(force=False, since=None)`
и одноимённая management-команда:

```bash
docker compose run --rm web django-admin backfill_analytics
```

Команда считает метрики за все прошедшие дни начиная с даты создания первой станции.
Аргументы позволяют задать начальную дату и принудительно перезаписать уже посчитанное —
см. `--help`.

## Доступ к данным

### REST API

| Эндпоинт | Что отдаёт |
|---|---|
| `GET /api/analytics/network/` | Суточные метрики по сети (только чтение) |
| `GET /api/analytics/station/` | Суточные метрики по станциям (только чтение) |
| `GET /api/analytics/dynamic-demod/` | Динамика поступления демодулированных данных |
| `GET /api/analytics/needs-attention/` | Станции, требующие внимания |

Лимиты запросов: `ANALYTICS_THROTTLE_RATE` (120/мин) для обычных эндпоинтов и
`ANALYTICS_HEAVY_THROTTLE_RATE` (30/мин) для тяжёлых.

### Станции, требующие внимания

`get_stations_needing_attention(lookback_days=7)` в `network/analytics/queries.py`
отбирает станции, чьё поведение за последнюю неделю выглядит проблемным — например,
наблюдения идут, а результатов нет. Это тот же класс проблем, который отслеживает задача
`notify_for_stations_without_results` (см. [](stations.md)), но в виде выборки для
дашборда, а не уведомления.

### Дашборд

HTML-страница доступна по `/analytics/` (`analytics_dashboard`).

## Смежная статистика

Не всё, что выглядит статистикой, живёт в `network.analytics`:

* `StationStat` и задачи `calculate_all_station_stat` / `calculate_station_stat` —
  агрегаты по станции в приложении `base` (ежедневно в 03:00 UTC).
* `TransmitterStats` и задача `update_transmitters_stats` — статистика передатчиков
  (каждые 15 минут).
* `network/base/stats.py` — кэшируемые расчёты по спутникам и передатчикам.
* `network/base/views/statistics.py` — сводные страницы портала.
* InfluxDB (`USE_INFLUX`) — необязательная выгрузка телеметрии, `network/base/influx.py`.