jellybit/openspec/changes/archive/2026-08-10-card-live-refresh/specs/web-ui/spec.md

ADDED Requirements

Requirement: Самообновление живой задачи

Карточка списка и страница /download/{id} SHALL самообновляться, пока задача наблюдаема, и SHALL прекращать самообновление, как только она наблюдаемой быть перестала. Наблюдаемы все нетерминальные задачи, а из терминальных — те, которые фоновая сверка возвращает в поток сама: failed, target_missing, orphaned. Задача, которую с места двигает только человек (done, cancelled, reverted, deleted), наблюдаемой не является. Признак SHALL жить в домене рядом с признаком терминальности; второго перечня состояний веб-UI MUST NOT заводить.

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

У одной поверхности SHALL быть ровно один источник самообновления. Вложенные живые регионы (прогресс качания в карточке, секция раздачи на странице) MUST NOT опрашивать сервер самостоятельно: своп корня уносит вложенный узел вместе с его поллером, поэтому два опроса на одну поверхность подменяют разметку друг друга и опрашивают одно и то же дважды.

Интервал самообновления SHALL зависеть от того, несёт ли поверхность блок живых цифр качания: у поверхности с таким блоком интервал SHALL быть строго меньше, чем у поверхности без него. Числовые значения интервалов живут в документации проекта, не в спеке.

Тик самообновления, не сумевший прочитать задачу (записи нет, хранилище отказало), SHALL отвечать успехом и фрагментом, который объясняет положение дел и не несёт самообновления: неуспешный ответ не заменяет разметку, поэтому поверхность осталась бы прежней, а опрос продолжался бы бесконечно.

Scenario: Завершение качания видно без перезагрузки

• GIVEN открыт список загрузок и в нём есть задача в downloading
• WHEN qBittorrent довёл раздачу до конца и воркер увёл задачу в recognizing и дальше в review
• THEN карточка без перезагрузки страницы показывает бейдж ревью и кнопку «Ревью →»
• AND блок живого прогресса с неё исчезает

Scenario: Переход, сделанный не из этого браузера

• GIVEN открыт список загрузок и в нём есть задача в review
• WHEN человек подтвердил план из Telegram и задача прошла linking в done
• THEN карточка без перезагрузки страницы показывает бейдж done и действия терминальной задачи

Scenario: Ненаблюдаемая задача не опрашивается

• WHEN задача находится в done, cancelled, reverted или deleted
• THEN её карточка и страница /download/{id} не несут самообновления, и фоновых запросов по ним не уходит

Scenario: Задача, оживлённая сверкой, видна без перезагрузки

• GIVEN открыт список, и в нём есть задача в failed (магнет не добрал метаданные за отведённое время)
• WHEN источник ожил и фоновая сверка вернула задачу в downloading
• THEN карточка без перезагрузки страницы показывает состояние качания

Scenario: Один источник обновления на поверхность

• WHEN отрисована карточка задачи в downloading или страница задачи, чья раздача сидирует
• THEN самообновление объявлено ровно в одном месте поверхности, а вложенные живые регионы своего опроса не ведут

Scenario: Быстрее обновляется то, где есть живые цифры

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

Scenario: Тик, который не смог прочитать задачу

• GIVEN открыта карточка наблюдаемой задачи
• WHEN очередной тик самообновления не нашёл записи или получил отказ хранилища
• THEN ответ успешен и несёт фрагмент с объяснением
• AND фрагмент не несёт самообновления, поэтому опрос прекращается

Scenario: Группа и фильтр списка пересчитываются навигацией

• GIVEN открыт список и в нём есть задача в downloading
• WHEN задача дошла до терминального состояния на глазах у смотрящего
• THEN карточка показывает новое состояние и остаётся на своём месте в прежней группе списка
• AND группа и фильтр пересчитываются при следующей навигации или перезагрузке — список целиком самообновлением не пересобирается

MODIFIED Requirements

Requirement: Отображение промежуточного состояния catched

Веб-UI SHALL отображать состояние catched как штатную промежуточную фазу («поймано, добавляется в qBittorrent»): бейдж статуса загрузки SHALL иметь понятную человекочитаемую подпись для catched (а не сырое catched), а загрузка в catched SHALL относиться к активной группе списка.

Пока отображаемое имя ещё не выведено (в catched download.display_name пуст), заголовок загрузки SHALL деградировать по существующему фолбеку (распознанное название или усечённый источник) — см. «Заголовок загрузки из имени раздачи». Секция раздачи/живого прогресса для catched SHALL корректно отсутствовать (раздачи в qBittorrent ещё нет), не создавая ошибок отображения.

Самообновление карточки и страницы в catched — частный случай требования «Самообновление живой задачи»: catched нетерминален, поэтому интерфейс подхватывает переход в downloading (бейдж, выведенное имя, появившийся живой прогресс) без перезагрузки страницы. Отдельного правила самообновления для этой фазы веб-UI MUST NOT иметь: фаза перестала быть единственной, где интерфейс обновляется сам.

Scenario: Бейдж и группа для catched

• WHEN загрузка находится в состоянии catched
• THEN её бейдж статуса имеет человекочитаемую подпись для catched
• AND загрузка попадает в активную группу списка

Scenario: Заголовок catched без имени

• GIVEN загрузка в catched с пустым download.display_name
• WHEN рендерится карточка/страница загрузки
• THEN заголовок берётся из фолбека (распознанное название или усечённый источник), без ошибок отображения
• AND секция раздачи/живого прогресса не показывается (раздачи ещё нет)

Scenario: Самообновление при переходе в downloading

• GIVEN открытая карточка загрузки в catched
• WHEN worker перевёл загрузку в downloading
• THEN интерфейс без перезагрузки показывает состояние downloading (бейдж, имя, живой прогресс)
• AND самообновление продолжается, потому что задача осталась наблюдаемой

Requirement: Обзор жизненного цикла в карточке списка

Карточка загрузки в списке SHALL показывать обзорную мета-строку для решения о судьбе раздачи: метку ID: перед копируемым идентификатором загрузки, дату добавления раздачи (всегда), размер раздачи и рейтинг отдачи. Контекст загрузки MUST NOT показываться в карточке списка — он доступен на странице /download/{id}.

Дата добавления SHALL показываться всегда как абсолютная дата и относительная давность (например «2026-06-30 · 5 дней назад»); источником SHALL быть время добавления раздачи в источник (source_added_at, qBittorrent added_on) с фолбэком на время создания загрузки (created_at), согласованным с порядком списка.

Рейтинг отдачи SHALL браться из живого снимка телеметрии; если торрента нет в снимке (источник ушёл из qBittorrent), рейтинг SHALL отображаться прочерком «—».

Размер раздачи SHALL браться из живого снимка (общий размер торрента), а при отсутствии торрента в снимке — из суммарного размера разложенных файлов загрузки; если неизвестно ни то, ни другое — прочерк «—».

Карточка, пришедшая самообновлением, SHALL показывать те же значения, что и карточка в полном рендере списка: фоновое обновление MUST NOT подменять известное значение прочерком.

Scenario: Метка идентификатора

• WHEN рендерится карточка загрузки в списке
• THEN перед значением download.id показана метка «ID:», а кнопка копирования копирует именно download.id

Scenario: Дата добавления показана всегда

• WHEN рендерится любая карточка списка
• THEN в ней показана дата добавления раздачи абсолютной датой и относительной давностью
• AND если source_added_at неизвестно, используется created_at

Scenario: Рейтинг из живого снимка

• WHEN торрент загрузки присутствует в живом снимке
• THEN в карточке показан его рейтинг отдачи
• AND если торрента в снимке нет, рейтинг показан прочерком «—»

Scenario: Размер с фолбэком на разложенные файлы

• WHEN торрент загрузки присутствует в живом снимке
• THEN размер раздачи в карточке берётся из общего размера торрента
• AND если торрента в снимке нет, но у загрузки есть разложенные файлы — размер берётся из суммарного размера этих файлов

Scenario: Самообновление не теряет размер

• GIVEN торрента нет в живом снимке, а файлы задачи разложены
• WHEN карточка пришла самообновлением, а не полным рендером списка
• THEN размер показан по тому же фолбэку, а не прочерком «—»

Scenario: Контекст не в карточке

• WHEN у загрузки есть переданный контекст
• THEN он не показывается в карточке списка, но доступен на странице /download/{id}