jellybit/openspec/specs/web-ui/spec.md

# web-ui Specification

## Purpose

Презентационный слой веб-интерфейса: встроенная (`go:embed`) отдача статики и
self-hosted шрифтов, единая дизайн-система (`jellybit.css`, тёмная тема по
настройке ОС), рендеринг страниц (список загрузок, ревью, просмотр) с бейджами
состояний и клиентскими взаимодействиями без сборки (копирование идентификатора
загрузки, спойлер контекста). Превью раскладки берётся из единой логики `internal/layout`,
а не дублируется в шаблонах. Тонкий транспорт над ядром (приём — `ingest`,
команды — `worker`, чтение — `store`).
## Requirements
### Requirement: Встроенная отдача статики

Сервис SHALL отдавать статические ассеты (CSS, клиентский JS, вендорные
библиотеки, шрифты) из встроенной (`go:embed`) файловой системы под префиксом
`/static/`, без внешних зависимостей времени выполнения. Бинарь остаётся
единым и самодостаточным.

#### Scenario: Запрос встроенного ассета

- **WHEN** клиент запрашивает `GET /static/css/jellybit.css`
- **THEN** сервис отвечает `200` с телом из встроенной FS и корректным
  `Content-Type`

#### Scenario: Кэширование статики

- **WHEN** сервис отдаёт ответ на запрос под `/static/`
- **THEN** ответ содержит заголовок `Cache-Control`, разрешающий кэширование
  ассета браузером

#### Scenario: Несуществующий ассет

- **WHEN** клиент запрашивает несуществующий путь под `/static/`
- **THEN** сервис отвечает `404` и не раскрывает структуру файловой системы

### Requirement: Шрифты без внешних сетей

Веб-UI SHALL подключать шрифты (IBM Plex Sans, IBM Plex Mono) только из
локально встроенных файлов через `@font-face`. Страницы MUST NOT обращаться к
сторонним хостам (Google Fonts CDN и т. п.) для загрузки шрифтов или стилей.

#### Scenario: Нет внешних ссылок на шрифты

- **WHEN** браузер открывает любую страницу веб-UI
- **THEN** все используемые шрифты загружаются из-под `/static/` того же
  origin, без обращений к внешним доменам

### Requirement: Единая дизайн-система

Все страницы веб-UI SHALL использовать единственный CSS-файл `jellybit.css` с
дизайн-токенами; страницы MUST NOT содержать инлайн-`<style>` или хардкод
цветов вне токенов. Тема (светлая/тёмная) SHALL определяться настройкой ОС
(`color-scheme` + `prefers-color-scheme`), без отдельного переключателя.

#### Scenario: Тёмная тема по настройке ОС

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

#### Scenario: Нет инлайн-стилей

- **WHEN** рендерится любая страница веб-UI
- **THEN** оформление берётся из подключённого `jellybit.css`, в разметке нет
  блоков `<style>` с хардкодом цветов

### Requirement: Бейдж статуса загрузки

Веб-UI SHALL отображать состояние каждой загрузки бейджем
`<span class="badge st-{STATE}">` с человекочитаемой русской подписью; класс
определяет цвет группы. Маппинг SHALL покрывать все состояния домена
(`downloading`, `completed`, `recognizing`, `linking`, `review`, `deferred`,
`done`, `stuck`, `target_missing`, `failed`, `orphaned`, `cancelled`,
`reverted`, `deleted`).

#### Scenario: Состояние отрисовано бейджем

- **WHEN** загрузка находится в состоянии `review`
- **THEN** в списке у неё бейдж с классом `st-review` и подписью «на ревью»

#### Scenario: Полнота покрытия

- **WHEN** загрузка находится в любом из состояний домена
- **THEN** для него существует класс бейджа и русская подпись (неизвестных
  состояний без оформления нет)

### Requirement: Страницы веб-UI

Веб-UI SHALL предоставлять страницы: список загрузок с единым окном
добавления, **серверными фильтром по группе состояний, поиском и постраничной
выдачей (пагинацией)** (`/`), экран ревью одной загрузки (`/review/{id}`),
страницу просмотра одной загрузки (`/download/{id}`) с распознаванием,
файлами→раскладкой, историей, блоком информации о торренте и — для сидирующих
задач — секцией живой статистики раздачи, а также **страницу группового
удаления загрузок** (`/delete`). Карточки активных (downloading)
загрузок в списке SHALL содержать индикатор прогресса. Карточка загрузки с
распознанным типом SHALL нести значок типа (фильм/сериал). Фильтр, поиск и номер
страницы SHALL передаваться GET-параметрами запроса (например `f`, `q`, `page`)
и SHALL работать без клиентского JavaScript. Терминальные состояния `deleted` и
`cancelled` SHALL быть скрыты в списке по умолчанию (переключатель «показать
всё» раскрывает оба). Шапка SHALL нести ссылки на список загрузок и на страницу
группового удаления. Механика живого
обновления прогресса и наполнение секции раздачи определяются capability
`live-status`.

#### Scenario: Просмотр одной загрузки

- **WHEN** клиент открывает `GET /download/{id}` существующей загрузки
- **THEN** отрисовывается страница с её распознаванием, файлами, раскладкой и
  историей

#### Scenario: Прогресс активной загрузки в списке

- **WHEN** в списке есть загрузка в состоянии `downloading`
- **THEN** её карточка содержит индикатор прогресса (прогресс-бар со скоростью
  и ETA)

#### Scenario: Отменённые и удалённые скрыты по умолчанию

- **WHEN** в списке есть загрузки в состоянии `deleted` или `cancelled` и фильтр
  «показать всё» не включён
- **THEN** они не отображаются, но доступны при включённом переключателе

#### Scenario: Значок типа в карточке списка

- **WHEN** загрузка в списке имеет распознанный тип (`movie` или `series`)
- **THEN** её карточка показывает значок типа (🎬 фильм / 📺 сериал); при
  отсутствии распознанного типа значок не показывается

#### Scenario: Пагинация списка

- **WHEN** загрузок под текущим фильтром больше, чем помещается на одну
  страницу, и клиент запрашивает `GET /?page=N`
- **THEN** возвращается N-я страница результатов и элементы навигации по
  страницам, сохраняющие текущие фильтр и поисковый запрос

#### Scenario: Серверный фильтр и поиск

- **WHEN** клиент запрашивает список с параметрами фильтра по состоянию и/или
  строкой поиска (`GET /?f=review&q=дюна`)
- **THEN** сервер возвращает только подходящие загрузки (по группе состояний и
  совпадению строки в названии, любом идентификаторе загрузки — `download.id`
  ИЛИ infohash — и контексте), отфильтрованные на стороне БД, а не на клиенте

#### Scenario: Ссылка на групповое удаление в шапке

- **WHEN** клиент открывает любую страницу веб-UI
- **THEN** в шапке есть ссылка на страницу группового удаления (`/delete`)

### Requirement: Порядок списка загрузок

Список загрузок SHALL сортироваться по времени добавления торрента в источник
(qBittorrent `added_on`), от новых к старым. Если время добавления в источник
неизвестно, для сортировки SHALL использоваться время создания загрузки в
jellybit (`created_at`). Порядок MUST быть согласован между страницами
пагинации.

#### Scenario: Сортировка по времени добавления в источник

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

#### Scenario: Фолбек порядка без времени источника

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

### Requirement: Заголовок загрузки из имени раздачи

Веб-UI SHALL показывать заголовком загрузки (в карточке списка и в шапке
страницы `/download/{id}`) сохранённое отображаемое имя раздачи (`display_name`,
переданное в qBittorrent при приёме). Если имя пусто, заголовок SHALL брать
распознанное название из плана; если и его нет — сырой источник (`source_ref`),
усечённый до одной строки как обычный заголовок. Заголовок MUST NOT занимать
несколько строк сырым magnet.

Имя раздачи — недоверенный вход, поэтому **на показе** заголовок SHALL терять
управляющие символы направления письма (с ними строка читается не в том
порядке, в каком хранится) и SHALL заменять прочие управляющие пробелом. Прочие
форматирующие символы юникода система снимать SHALL NOT: без соединителей
рассыпаются составные эмодзи и меняется написание имён на ряде письменностей.
Хранимое значение эта чистка менять SHALL NOT — поиск по списку идёт по
сохранённому имени.

#### Scenario: Заголовок из имени раздачи

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

#### Scenario: Фолбек до распознавания и без имени

- **WHEN** отображаемого имени нет, но есть распознанное название
- **THEN** заголовком служит распознанное название
- **AND** если нет ни того, ни другого — заголовком служит усечённый до одной
  строки сырой источник, а не многострочный magnet

#### Scenario: Переворачивающий символ до показа не доезжает

- **GIVEN** имя раздачи содержит символ переопределения направления письма
- **WHEN** заголовок показывается на любой странице веб-UI
- **THEN** этого символа в разметке нет
- **AND** составные эмодзи в том же имени остаются целыми

### Requirement: Действие «Обновить имя» на странице загрузки

Когда у загрузки есть распознавание, страница загрузки SHALL предлагать действие
«Обновить имя», запускающее обновление отображаемого имени по распознаванию (см.
capability `ingest`). Видимость действия SHALL определяться наличием распознавания
(а не состоянием ревью): в частности, действие SHALL быть доступно и на терминальных
состояниях с распознаванием (`done`/`orphaned`), где раздачу нужно переименовать
постфактум. Действие SHALL обновлять заголовок на месте по htmx-паттерну
(фрагмент заголовка перерисовывается ответом), без перезагрузки страницы, и SHALL
деградировать без JS (обычная форма-POST с переходом на страницу загрузки).

Действие SHALL быть идемпотентным по эффекту: повторный запуск на неизменном
распознавании даёт то же имя. Отсутствие распознавания (пустой источник имени)
SHALL приводить к отсутствию видимых изменений.

#### Scenario: Ручное обновление имени перерисовывает заголовок

- **GIVEN** страница загрузки с распознанным каноническим названием и заголовком
  «Unknown»
- **WHEN** пользователь запускает действие «Обновить имя»
- **THEN** заголовок на странице перерисовывается каноническим именем `Title (Year)`
  на месте (htmx), без полной перезагрузки

#### Scenario: Деградация без JS

- **GIVEN** клиент без htmx/JS
- **WHEN** пользователь отправляет действие «Обновить имя» обычной формой
- **THEN** сервер выполняет обновление и отвечает страницей загрузки с новым
  заголовком

### Requirement: Матч с записью метабазы ссылкой

Веб-UI SHALL показывать подтверждённый матч с записью метабазы (TMDB/TVDB/IMDb)
как ссылку на эту запись — на странице просмотра `/download/{id}` (блок
распознавания) и в едином списке источников совпадения экрана ревью (у
активного источника-кандидата). Ссылка SHALL открываться в новой вкладке с
`rel="noopener"`. Рядом со ссылкой SHALL быть видны провайдер, идентификатор
записи и (при наличии) год.

#### Scenario: Матч виден ссылкой на странице просмотра

- **WHEN** у загрузки подтверждён матч с записью метабазы и известен URL записи
- **THEN** в блоке распознавания на `/download/{id}` матч показан ссылкой на
  запись с провайдером и id

#### Scenario: URL записи неизвестен

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

### Requirement: Блок информации о торренте

Страница `/download/{id}` SHALL содержать блок «Информация о торренте» с полным
исходным источником (magnet/URL/`.torrent`-ссылка) и infohash с кнопкой
копирования. Сырой источник MUST выноситься в этот блок, а не в заголовок.

#### Scenario: Полный источник в отдельном блоке

- **WHEN** клиент открывает `GET /download/{id}`
- **THEN** полный источник (magnet) и infohash показаны в блоке «Информация о
  торренте», а заголовок страницы остаётся человекочитаемым именем

### Requirement: Действия соответствуют состоянию

Каждая страница SHALL показывать только действия, допустимые в текущем
состоянии загрузки, и каждое действие-кнопка SHALL отправлять форму с полями,
имена которых совпадают с ожидаемыми обработчиком (`internal/httpapi`).

#### Scenario: Набор действий по состоянию

- **WHEN** загрузка в состоянии `done`
- **THEN** доступно действие отката (undo), но недоступны «применить»/«позже»

#### Scenario: Имена полей формы

- **WHEN** пользователь отправляет форму действия (например, «уточнить»)
- **THEN** поля формы имеют `name`, которые обработчик читает без
  переименования, и действие исполняется

### Requirement: Превью раскладки через единую логику именования

Превью целевых путей раскладки в веб-UI SHALL вычисляться той же логикой
именования, что и реальная раскладка (`internal/naming`/`internal/layout`), а
не дублировать правила в шаблоне. На экране ревью превью SHALL строиться **для
выбранного (активного) источника** — эфемерно на сервере, без записи
сохранённого матча самим показом. При смене выбранного источника превью SHALL
пересчитываться под него и обновляться частичным свопом блока. Показанные для
источника пути MUST совпадать с теми, что создались бы при применении этого
источника.

#### Scenario: Превью совпадает с реальной раскладкой

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

#### Scenario: Смена источника пересчитывает превью

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

#### Scenario: Переключение источника не тянет чужие поля

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

### Requirement: Клиентские взаимодействия без сборки

Веб-UI SHALL реализовывать клиентскую логику без шага сборки и без реактивных
фреймворков: копирование идентификатора загрузки (vanilla JS). Основной
копируемый идентификатор в карточке списка и в шапке страницы просмотра SHALL
быть `download.id` (ULID) — тот же ключ, что пишется в логи (`download_id`). Все
действия над загрузкой SHALL выполняться через формы/htmx (раундтрип на сервер),
без клиентского пересчёта доменного состояния.

#### Scenario: Копирование идентификатора загрузки

- **WHEN** пользователь нажимает кнопку копирования рядом с идентификатором
  загрузки (`download.id`) в карточке списка или шапке страницы просмотра
- **THEN** значение `download.id` копируется в буфер обмена без перезагрузки
  страницы

#### Scenario: Действия только через раундтрип

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

### 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}`

### Requirement: Таймзона отображения времени

Веб-UI SHALL отображать все временные метки (абсолютные даты добавления и
создания, относительная давность) в **таймзоне отображения из конфигурации**
(`[general].timezone`, дефолт `UTC`). Зона MUST NOT быть зашита в код.
Метки в БД хранятся всегда в UTC (RFC 3339); конвертация в зону отображения
SHALL выполняться только на рендеринге, не затрагивая хранение и сортировку.

База зон (zoneinfo) SHALL встраиваться в бинарь (`time/tzdata`), поэтому зоны
доступны независимо от окружения контейнера. Некорректное (нераспознаваемое)
значение `timezone` в конфиге SHALL приводить к ошибке на старте приложения
(валидация конфигурации), а не к тихой подмене зоны на рендеринге.

#### Scenario: Дата в сконфигурированной зоне

- **WHEN** в конфиге `timezone = "Europe/Moscow"` и рендерится карточка загрузки
- **THEN** абсолютная дата добавления показана в зоне `Europe/Moscow`
- **AND** та же метка в БД хранится в UTC с суффиксом `Z`

#### Scenario: Зона по умолчанию — UTC

- **WHEN** `[general].timezone` в конфиге не задан
- **THEN** времена в веб-UI отображаются в UTC

#### Scenario: Невалидная зона в конфиге

- **WHEN** `[general].timezone` содержит нераспознаваемое значение
- **THEN** приложение завершается с ошибкой конфигурации на старте

### Requirement: Действия обновляют интерфейс на месте

Мутирующие действия над загрузкой в списке (`/`) и на странице `/download/{id}` SHALL выполняться htmx-запросом и обновлять затронутую область HTML на месте (partial swap), без навигации на другую страницу и без сброса контекста списка (фильтр, поиск, страница пагинации, позиция прокрутки).
Сервер SHALL отвечать на такой запрос HTML-фрагментом обновлённой области, а не
редиректом.

Область свопа SHALL соответствовать поверхности действия: в списке — карточка
загрузки (`<article class="card">`) целиком, отражающая новое состояние, бейдж
и допустимый набор действий; на странице `/download/{id}` — содержимое
страницы, отражающее новое состояние загрузки. После свопа набор показанных
действий MUST соответствовать новому состоянию (см. «Действия соответствуют
состоянию»).

Поведение MUST деградировать без htmx: если запрос действия пришёл без признака
htmx (нет заголовка `HX-Request`), обработчик SHALL отвечать прежним
PRG-редиректом, и действие исполняется тем же доменным вызовом. Формы действий
остаются обычными POST-формами.

Ошибка действия (доменная или валидации) SHALL показываться на месте — в
подменённом фрагменте той же области, — а не только через параметр `?err=`
после редиректа; при ошибке активное состояние загрузки не меняется молча.
Ответ на htmx-запрос действия SHALL иметь статус `200` даже при ошибке действия
(иначе htmx не подменит фрагмент): сообщение об ошибке несёт сам фрагмент.

После свопа карточка SHALL оставаться на своём месте в списке, даже если её
новое состояние уже не подходит под активный фильтр; согласованность списка с
фильтром восстанавливается при следующей полной загрузке. Клиентского
переупорядочивания или пересчёта доменного состояния не выполняется.

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

- **GIVEN** в списке есть загрузка в состоянии `done` с действием отката
- **WHEN** пользователь нажимает «Откатить» (htmx активен)
- **THEN** карточка этой загрузки подменяется на месте на её новое состояние
  (`reverted`) с соответствующим бейджем и набором действий
- **AND** список не перезагружается: фильтр, поиск, страница и позиция прокрутки
  сохраняются

#### Scenario: Действие со страницы загрузки оставляет на странице

- **GIVEN** открыта страница `GET /download/{id}` загрузки в состоянии `done`
- **WHEN** пользователь нажимает «Откатить» или «Привязать заново» (htmx активен)
- **THEN** содержимое страницы обновляется на месте под новое состояние
  загрузки, без перехода на список и без прыжка прокрутки наверх

#### Scenario: Деградация без htmx — прежний редирект

- **WHEN** действие над загрузкой приходит POST-запросом без заголовка
  `HX-Request` (htmx недоступен)
- **THEN** обработчик исполняет то же доменное действие и отвечает
  PRG-редиректом, как раньше; поведение без JavaScript не ломается

#### Scenario: Ошибка действия показана на месте

- **GIVEN** пользователь запускает действие через htmx
- **WHEN** доменный вызов возвращает ошибку (например, состояние уже изменилось)
- **THEN** ответ имеет статус `200`, а сообщение об ошибке показывается в
  подменённом фрагменте той же области, а не только на отдельной странице после
  редиректа
- **AND** активное состояние загрузки не меняется

#### Scenario: Свопнутая карточка остаётся вне фильтра

- **GIVEN** список отфильтрован по группе состояний (например, `review`) и в нём
  есть карточка загрузки
- **WHEN** действие через htmx переводит загрузку в состояние вне этого фильтра
  (например, `cancelled`)
- **THEN** карточка подменяется на месте новым состоянием и остаётся видимой до
  следующей полной загрузки списка, без клиентского переупорядочивания

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

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

Требование распространяется на **карточку списка `/` и страницу
`/download/{id}`** и на страницу группового удаления (`/delete`)
распространяться SHALL NOT: там строки несут выбор человека, а своп корня унёс
бы отметки вместе с разметкой — и человек подтвердил бы необратимое удаление по
выбору, которого уже не видит. Наблюдаемость самих загрузок этого не отменяет:
строки `/delete` перечисляют в том числе `orphaned` и `target_missing`.

Самообновление 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** группа и фильтр пересчитываются при следующей навигации или
  перезагрузке — список целиком самообновлением не пересобирается

#### Scenario: Страница группового удаления не самообновляется

- **GIVEN** открыта страница `/delete`, и среди её строк есть загрузки в
  `orphaned` и `target_missing` (наблюдаемые состояния)
- **THEN** ни строки, ни страница целиком самообновления не несут, и фоновых
  запросов по ним не уходит

### 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: Загрузка .torrent-файла на форме добавления

Форма добавления загрузки веб-UI SHALL позволять выбрать локальный
`.torrent`-файл рядом со строкой ввода источника (кнопка/поле выбора файла).
При отправке формы с выбранным файлом система SHALL принять его байты
(`multipart/form-data`) и провести приём по `.torrent` (см. `ingest` «Приём
источника из .torrent-файла»); при пустом файловом поле — приём по тексту
источника, как прежде.

Файловый ввод SHALL деградировать без JavaScript: обычная отправка
`multipart`-формы SHALL приводить к приёму файла и тем же результатом, что и
htmx-путь (список обновляется/происходит редирект — как у существующего
добавления). Размер принимаемого файла UI/обработчик SHALL ограничивать (см.
ограничение размера в `ingest`); превышение SHALL давать понятную ошибку без
создания загрузки.

#### Scenario: Добавление выбором .torrent-файла

- **GIVEN** пользователь открыл форму добавления и выбрал `.torrent`-файл
- **WHEN** форма отправлена
- **THEN** файл принимается байтами и заводится загрузка (`source_type =
  torrent`)
- **AND** список загрузок отражает новую задачу (как при добавлении по magnet)

#### Scenario: Файл не выбран — приём по тексту

- **GIVEN** пользователь оставил файловое поле пустым и ввёл magnet/текст
- **WHEN** форма отправлена
- **THEN** выполняется приём по тексту источника, как прежде

### Requirement: Режиссёр в блоке распознавания страницы загрузки

Страница просмотра `/download/{id}` в блоке «Распознано как» SHALL показывать
режиссёра эффективного источника, разрешённого теми же слоями, что и
отображаемое имя раздачи (`display_name`): первый непустой слой `override` →
`recognition`+матч → сохранённый при приёме контекст (`parsed_context`).
Разрешение режиссёра для поля блока и для отображаемого имени SHALL идти **единой
логикой** (общий источник разрешения), а не расходящимися путями — прежняя
захардкоженная в поле заглушка-прочерк при непустом режиссёре в заголовке
устраняется. Показанное значение SHALL проходить ту же очистку (санитайзинг
управляющих символов/пробелов), что и режиссёр внутри отображаемого имени, чтобы
присутствие/отсутствие режиссёра в поле и в заголовке определялось одинаково.
Когда режиссёр недоступен ни в одном слое, поле SHALL показывать прочерк, не
ломая вёрстку.

#### Scenario: Режиссёр из распознавания показан в блоке

- **GIVEN** загрузка, чей эффективный план несёт режиссёра (из матча метабазы или
  закреплённого источника)
- **WHEN** клиент открывает `GET /download/{id}`
- **THEN** в блоке «Распознано как» в поле «Режиссёр» показан этот режиссёр

#### Scenario: Режиссёр из контекста при распознавании без матча

- **GIVEN** загрузка без режиссёра в плане, но с режиссёром в сохранённом
  контексте (`parsed_context`)
- **WHEN** клиент открывает `GET /download/{id}`
- **THEN** в поле «Режиссёр» показан режиссёр из контекста
- **AND** он разрешён тем же нижним слоем контекста, что и режиссёр в
  отображаемом имени раздачи (единая логика, не расходящиеся пути)

#### Scenario: Режиссёр неизвестен — прочерк

- **GIVEN** загрузка, для которой режиссёр не разрешается ни одним слоем
- **WHEN** клиент открывает `GET /download/{id}`
- **THEN** поле «Режиссёр» показывает прочерк, а вёрстка блока не ломается

### Requirement: Страница группового удаления загрузок

Веб-UI SHALL предоставлять отдельную страницу (`GET /delete`), перечисляющую
**только** те загрузки, для которых полное удаление с файлами разрешено
поштучно (состояния `done`, `orphaned`, `target_missing` — см.
`state-reconciliation`, «Полное удаление загрузки пользователем»). Загрузки в
прочих состояниях страница показывать SHALL NOT. У каждой строки SHALL быть
чекбокс выбора, отображаемый заголовок загрузки и её состояние; страница SHALL
предлагать одно действие — «Удалить выбранные».

Условие «в этом состоянии удаление разрешено» SHALL вычисляться единой точкой
домена, общей со страницей одной загрузки и с проверкой допуска в ядре;
собственного перечня состояний страница держать SHALL NOT.

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

Страница SHALL NOT самообновляться опросом сервера — своп разметки стёр бы
выбор человека.

Страница и все её действия SHALL работать без клиентского JavaScript.

#### Scenario: Показаны только разрешённые к удалению

- **WHEN** клиент открывает `GET /delete`, а в хранилище есть загрузки во всех
  состояниях
- **THEN** страница содержит строки загрузок в `done`, `orphaned` и
  `target_missing`
- **AND** не содержит строк загрузок в прочих состояниях

#### Scenario: Ни одной разрешённой загрузки

- **WHEN** клиент открывает `GET /delete`, а разрешённых к удалению загрузок
  нет
- **THEN** страница показывает пустое состояние и не предлагает удаление

#### Scenario: Предел пачки назван до отправки

- **WHEN** клиент открывает `GET /delete` и на странице есть хотя бы одна
  строка
- **THEN** страница называет верхний предел числа загрузок в одной пачке

#### Scenario: Страница не опрашивает сервер

- **WHEN** клиент открывает `GET /delete`
- **THEN** разметка страницы не содержит самообновления (`hx-trigger="every …"`)

### Requirement: Групповое удаление требует поимённого подтверждения

Групповое удаление SHALL идти двумя шагами: выбор и **подтверждение**. Шаг
подтверждения SHALL называть каждую выбранную загрузку поимённо — отображаемым
заголовком, идентификатором и **состоянием**, — и SHALL нести признак
подтверждения в форме исполняющего запроса. Для загрузки в состоянии
`orphaned` подтверждение SHALL нести явную отметку, что источник уже пропал и
библиотечная ссылка осталась последней копией данных: гард последней копии в
удалении выключен сознательно, и осведомлённость человека — единственный
оставшийся предохранитель.

**Граница этой отметки названа прямо: она выводится из состояния, а не из
файловой системы.** Случай, когда байты источника исчезли с диска, но раздача
осталась в списке qBittorrent, сверка `done` не переоценивает (присутствие
источника она берёт из списка раздач, а не с диска) — такая загрузка остаётся
`done`, и отметки не получает, хотя библиотечная ссылка уже последняя копия.
Требовать обхода файловой системы на экране подтверждения система SHALL NOT;
непокрытый случай назван здесь, чтобы отметка не читалась как гарантия.
Поштучный путь удаления такой отметки не несёт вовсе.

Запрос группового удаления без признака подтверждения система SHALL отклонять и
SHALL NOT выполнять ни одного удаления. Одно подтверждение SHALL покрывать
ровно ту пачку, которая на нём перечислена.

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

На каждой из этих границ система SHALL:

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

Отказ по превышению предела SHALL возвращать страницу выбора с **сохранёнными**
отметками и объяснением, а не пустой экран отказа: иначе проверка отнимает всю
проделанную человеком работу.

Идентификатор, который разобрался, но записи в хранилище не имеет, система
SHALL называть отдельной строкой — на подтверждении и в отчёте — и молча
выбрасывать его SHALL NOT.

Отказ чтения хранилища система SHALL отличать от отсутствия записи и SHALL NOT
выдавать одно за другое: строка, о которой сказано «удалять нечего», а на деле
снесённая с файлами, разводит подтверждённое с исполненным, а для `orphaned`
уносит с экрана отметку о последней копии — единственный оставшийся
предохранитель. Такой идентификатор SHALL получать собственную строку,
называющую, что состояние прочитать не удалось, а сам отказ SHALL уходить в
журнал.

#### Scenario: Подтверждение называет выбранные поимённо

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

#### Scenario: Подтверждение предупреждает о последней копии

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

#### Scenario: Без подтверждения не удаляется ничего

- **GIVEN** выбраны разрешённые к удалению загрузки
- **WHEN** приходит запрос группового удаления без признака подтверждения
- **THEN** запрос отклоняется с объяснением
- **AND** команда удаления не вызывается ни по одной загрузке

#### Scenario: Неразобранный идентификатор отклоняет запрос

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

#### Scenario: Гарды исполняющего запроса не слабее гардов подтверждения

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

#### Scenario: Пачка сверх предела отклоняется и не стирает выбор

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

#### Scenario: Пустой выбор

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

#### Scenario: Отказ чтения не выдаётся за отсутствие записи

- **GIVEN** в пачке есть идентификатор, чтение которого отказало (не «записи
  нет», а отказ хранилища)
- **WHEN** открывается страница подтверждения
- **THEN** его строка говорит, что состояние прочитать не удалось, и не
  утверждает, что удалять нечего
- **AND** отказ записан в журнал

#### Scenario: Идентификатор без записи назван строкой

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

### Requirement: Исход группового удаления назван поимённо

Групповое удаление SHALL выполнять команду удаления по каждой подтверждённой
загрузке **последовательно и независимо**: отказ на одной загрузке остальных
отменять SHALL NOT. По завершении система SHALL показать страницу результата,
называющую поимённо удалённые загрузки и отказавшие — каждую с причиной отказа.

Отчёт SHALL отдаваться **ответом на исполняющий запрос**, а не перенаправлением:
поимённый исход нечем передать через параметры адреса, а сессий у сервиса нет.
Повторная отправка той же формы удалённые загрузки повторно сносить SHALL NOT —
они находятся в терминальном `deleted`, удаление им недоступно, и повторный
запрос даёт по ним отказ по конфликту. Остаток, не выполненный из-за остановки
прохода, повторная отправка **доисполняет**, и это ожидаемо: эти загрузки
человек подтвердил тем же подтверждением, а браузер о повторной отправке
переспрашивает сам. Утверждать, что повтор ничего не делает, система SHALL NOT.

Исполнение пачки система SHALL доводить до конца независимо от того, дождался
ли клиент ответа: отмена HTTP-запроса (закрытая вкладка, обрыв связи)
прекращать необратимую операцию на середине SHALL NOT. Исход каждой единицы
SHALL попадать в журнал, чтобы факт «что именно снесено» пережил потерю ответа.

**Проход ограничен сверху временем.** Удаление удерживает общий замок ядра на
всё время обращения к qBittorrent, поэтому медленно, но **успешно** отвечающий
внешний сервис останавливает фоновую работу сервиса целиком, а порог отказов
такого не ловит — он считает только ошибки. Система SHALL держать потолок
времени на один проход и по его исчерпании SHALL прекращать проход, называя
остаток в отчёте невыполненным. Потолок SHALL проверяться **между** единицами:
начатое удаление обрывать SHALL NOT — оборванное, оно встанет между снятием
библиотечных ссылок и сносом раздачи.

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

Причина отказа SHALL передаваться публичным каналом (нейтральное сообщение),
сырой текст ошибки наружу уходить SHALL NOT.

Групповой путь прав поштучного расширять SHALL NOT: допуск по состоянию
проверяет ядро в момент операции, и загрузка в недопустимом состоянии SHALL
отклоняться тем же конфликтом, что и при поштучном удалении.

#### Scenario: Отказ одной не отменяет остальных

- **GIVEN** подтверждены три загрузки, и удаление второй из них отказывает
- **WHEN** выполняется групповое удаление
- **THEN** первая и третья удалены
- **AND** страница результата называет вторую и причину её отказа

#### Scenario: Недопустимое состояние отклоняется тем же конфликтом

- **GIVEN** в подтверждённой пачке есть загрузка в состоянии, из которого
  удаление недоступно
- **WHEN** выполняется групповое удаление
- **THEN** по этой загрузке приходит отказ по конфликту состояния, и она
  попадает в отчёт строкой отказа
- **AND** остальные подтверждённые загрузки удалены

#### Scenario: Все удалены успешно

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

#### Scenario: Обрыв связи не останавливает пачку

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

#### Scenario: Потолок времени останавливает проход

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

#### Scenario: Повтор доисполняет невыполненный остаток

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

#### Scenario: Недоступный внешний сервис останавливает пачку

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

#### Scenario: Одиночный отказ пачку не прерывает

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

#### Scenario: Сырая ошибка наружу не уходит

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