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}`) с распознаванием,
файлами→раскладкой, историей, блоком информации о торренте и — для сидирующих
задач — секцией живой статистики раздачи. Карточки активных (downloading)
загрузок в списке SHALL содержать индикатор прогресса. Фильтр, поиск и номер
страницы SHALL передаваться GET-параметрами запроса (например `f`, `q`, `page`)
и SHALL работать без клиентского JavaScript. Состояние `deleted` SHALL быть
скрыто в списке по умолчанию (с переключателем «показать всё»). Механика живого
обновления прогресса и наполнение секции раздачи определяются capability
`live-status`.

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

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

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

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

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

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

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

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

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

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

### 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.

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

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

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

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

### 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 браться из живого снимка (общий размер торрента), а при
отсутствии торрента в снимке — из суммарного размера разложенных файлов загрузки;
если неизвестно ни то, ни другое — прочерк «—».

#### 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: Контекст не в карточке

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