av
66d39297c5
- каталог задач: PLAN.md → ROADMAP.md с каноническими секциями, все 44 записи получили тип, заголовки приведены к форме своего типа - расхождения, найденные судьями канона: исключения инварианта «источник неприкосновенен», инвариант про один активный infohash, UTC в logging.md, поведение из architecture.md заменено ссылками на спеки - триггеры профиля ревью переписаны под умолчание standard
128 lines
8.7 KiB
Markdown
128 lines
8.7 KiB
Markdown
# 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 обновлять прогресс активных (downloading) загрузок на главной без
|
|
перезагрузки страницы — поллингом фрагмента через htmx. Обновление MUST NOT
|
|
сбрасывать клиентские фильтр, поиск и прокрутку. Когда задача покидает
|
|
состояние downloading, поллинг её прогресса SHALL прекращаться.
|
|
|
|
#### Scenario: Прогресс растёт без перезагрузки
|
|
|
|
- **WHEN** загрузка качается и пользователь смотрит на главную
|
|
- **THEN** её прогресс-бар, скорость и ETA обновляются на месте без
|
|
перезагрузки страницы
|
|
|
|
#### Scenario: Клиентское состояние сохраняется
|
|
|
|
- **WHEN** применён фильтр или поиск и происходит фоновое обновление прогресса
|
|
- **THEN** выбранный фильтр, текст поиска и позиция прокрутки не сбрасываются
|
|
|
|
#### Scenario: Завершение останавливает поллинг
|
|
|
|
- **WHEN** загрузка переходит из downloading в другое состояние
|
|
- **THEN** фоновый поллинг прогресса для этой карточки прекращается
|
|
|
|
### Requirement: Секция раздачи на странице загрузки
|
|
|
|
Страница `/download/{id}` SHALL показывать секцию «Раздача» с живой статистикой
|
|
(рейтинг, число сидов и пиров, объём отданного, скорость отдачи) для задач,
|
|
чей торрент сидирует. Если живых данных по задаче нет, секция SHALL
|
|
отсутствовать либо явно показывать «нет данных», не ломая остальную страницу.
|
|
|
|
#### Scenario: Сидирующая задача показывает раздачу
|
|
|
|
- **WHEN** открыта страница задачи, торрент которой раздаётся
|
|
- **THEN** в секции «Раздача» видны рейтинг, сиды/пиры, отдано и скорость отдачи
|
|
|
|
#### Scenario: Нет живых данных — секция деградирует
|
|
|
|
- **WHEN** открыта страница задачи, торрента которой нет в qBittorrent
|
|
- **THEN** секция «Раздача» отсутствует или показывает «нет данных», а
|
|
распознавание, файлы и история отображаются нормально
|
|
|