# live-status Specification

## Purpose
Живая телеметрия раздач: единственный сэмплер — воркер, снимок держится в
памяти на тике поллинга и в БД не персистится. Состав телеметрии (прогресс,
скорость, ETA, размер; для сидирующих — рейтинг, сиды и пиры, отдано), узкий
контракт чтения транспортом и живое обновление интерфейса поллингом фрагментов.
Что именно рисуется на странице и в карточке — `web-ui`; откуда берутся сами
состояния загрузки — `download-tracking`.
## Requirements
### Requirement: Снимок живой телеметрии

Воркер — единственный сэмплер qBittorrent — SHALL на каждом тике поллинга
обновлять in-memory снимок телеметрии всех известных раздач. Снимок MUST NOT
персиститься в БД: он волатилен и переживает только до рестарта процесса.

#### Scenario: Обновление снимка на тике

- **WHEN** воркер завершает успешный тик поллинга qBittorrent
- **THEN** снимок телеметрии содержит актуальные данные по каждой раздаче,
  присутствующей в ответе qBittorrent

#### Scenario: Снимок волатилен

- **WHEN** процесс только что перезапущен и первый тик поллинга ещё не прошёл
- **THEN** снимок пуст, а UI отображает задачи без живых значений, не падая

### Requirement: Состав телеметрии

Телеметрия одной раздачи SHALL включать прогресс (доля 0..1), скорость загрузки,
ETA и общий размер раздачи (total size); а для сидирующих раздач дополнительно —
рейтинг, число сидов и пиров, объём отданного и скорость отдачи. Общий размер
SHALL быть доступен для любой раздачи, присутствующей в снимке (не только
сидирующей). Значения SHALL извлекаться из ответа qBittorrent `/torrents/info`
без дополнительного сетевого вызова.

#### Scenario: Телеметрия качающейся задачи

- **WHEN** торрент задачи находится в состоянии загрузки
- **THEN** в снимке для неё доступны прогресс, скорость загрузки и ETA

#### Scenario: Общий размер доступен для любой раздачи в снимке

- **WHEN** торрент задачи присутствует в снимке в любом состоянии
- **THEN** в телеметрии для неё доступен общий размер раздачи

#### Scenario: Телеметрия сидирующей задачи

- **WHEN** торрент задачи завершён и раздаётся
- **THEN** в снимке для неё доступны рейтинг, число сидов/пиров, объём
  отданного и скорость отдачи

### Requirement: Чтение телеметрии транспортом

Сервис SHALL предоставлять чтение снимка телеметрии по задаче через
изолированный контракт, не зависящий от способа доставки в браузер (поллинг
сейчас, SSE в будущем). Если для задачи нет записи в снимке (соответствующий
торрент отсутствовал в qBittorrent на последнем тике), чтение SHALL сообщать
об отсутствии данных, а UI MUST деградировать без живых значений, не падая.

#### Scenario: Данные есть

- **WHEN** транспорт читает телеметрию задачи, чей торрент был в последнем тике
- **THEN** он получает живые значения этой задачи

#### Scenario: Данных нет

- **WHEN** транспорт читает телеметрию задачи, торрента которой нет в qBittorrent
- **THEN** он получает признак отсутствия данных и рендерит страницу без живых
  значений

### Requirement: Свежесть не выше тика поллинга

Живые значения, видимые в браузере, SHALL быть не свежее последнего тика
поллинга воркера; браузер MUST NOT опрашивать qBittorrent напрямую. Любой
запрос UI за телеметрией SHALL обслуживаться из in-memory снимка, не порождая
обращения к qBittorrent — поэтому частота обновления UI может быть выбрана
свободно (в т.ч. чаще тика для плавности), не нагружая qBittorrent.

#### Scenario: Браузер не обгоняет воркер

- **WHEN** браузер запрашивает фрагмент телеметрии чаще, чем длится тик
  поллинга
- **THEN** он получает значения последнего тика, и обращения к qBittorrent при
  этом не происходит

### Requirement: Живой прогресс активных загрузок

Веб-UI SHALL показывать прогресс, скорость и ETA активных (`downloading`)
загрузок на главной без перезагрузки страницы, обновляя их тем же
самообновлением, которым обновляется сама карточка (см. `web-ui`,
«Самообновление живой задачи»). Обновление MUST NOT сбрасывать клиентские
фильтр, поиск и прокрутку.

Когда задача покидает состояние `downloading`, показ скорости и ETA SHALL
прекращаться: вне качания эти величины смысла не имеют. Снимок при этом
продолжает питать прочие живые значения карточки и страницы — размер и рейтинг
раздачи, — и прекращение показа цифр качания MUST NOT означать прекращения
обновления поверхности: она продолжает отражать смену состояния, пока задача
наблюдаема.

Живые цифры MUST браться из снимка воркера; при отсутствии данных по задаче
поверхность деградирует без них, не ломая остального отображения.

#### Scenario: Прогресс растёт без перезагрузки

- **WHEN** загрузка качается и пользователь смотрит на главную
- **THEN** её прогресс-бар, скорость и ETA обновляются на месте без
  перезагрузки страницы

#### Scenario: Клиентское состояние сохраняется

- **WHEN** применён фильтр или поиск и происходит фоновое обновление
- **THEN** выбранный фильтр, текст поиска и позиция прокрутки не сбрасываются

#### Scenario: Завершение убирает цифры качания, но не обновление

- **WHEN** загрузка переходит из `downloading` в другое наблюдаемое состояние
- **THEN** блок прогресса, скорости и ETA с карточки исчезает
- **AND** карточка продолжает обновляться и приносит новое состояние
- **AND** размер и рейтинг раздачи по-прежнему берутся из снимка

### Requirement: Секция раздачи на странице загрузки

Страница `/download/{id}` SHALL показывать секцию «Раздача» с живой статистикой
(рейтинг, число сидов и пиров, объём отданного, скорость отдачи) для задач,
чей торрент сидирует. Если живых данных по задаче нет, секция SHALL
отсутствовать либо явно показывать «нет данных», не ломая остальную страницу.

Секция MUST NOT опрашивать сервер самостоятельно: она лежит внутри области,
которую страница обновляет целиком, и собственный опрос секции подменял бы
разметку страницы. Её цифры SHALL приходить с тиком самообновления страницы
(см. `web-ui`, «Самообновление живой задачи»), а частота их обновления
SHALL совпадать с частотой обновления страницы.

#### Scenario: Сидирующая задача показывает раздачу

- **WHEN** открыта страница задачи, торрент которой раздаётся
- **THEN** в секции «Раздача» видны рейтинг, сиды/пиры, отдано и скорость отдачи

#### Scenario: Нет живых данных — секция деградирует

- **WHEN** открыта страница задачи, торрента которой нет в qBittorrent
- **THEN** секция «Раздача» отсутствует или показывает «нет данных», а
  распознавание, файлы и история отображаются нормально

#### Scenario: Секция обновляется тиком страницы

- **GIVEN** открыта страница наблюдаемой задачи, чья раздача сидирует
- **WHEN** страница отрисована
- **THEN** секция «Раздача» не несёт собственного опроса
- **AND** её цифры обновляются вместе с остальной страницей

