Реализованное поведение перенесено в openspec/specs: - web-ui: cancelled скрыт по умолчанию наравне с deleted; значок типа в карточке; - review: панель действий обновляется oob-фрагментом при свопе источника. Пять закрытых задач удалены из docs/backlog + индекса. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
544 lines
40 KiB
Markdown
544 lines
40 KiB
Markdown
# 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 нести значок типа (фильм/сериал). Фильтр, поиск и номер
|
||
страницы SHALL передаваться GET-параметрами запроса (например `f`, `q`, `page`)
|
||
и SHALL работать без клиентского JavaScript. Терминальные состояния `deleted` и
|
||
`cancelled` 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 — и контексте), отфильтрованные на стороне БД, а не на клиенте
|
||
|
||
### 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: Действие «Обновить имя» на странице загрузки
|
||
|
||
Когда у загрузки есть распознавание, страница загрузки 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 браться из живого снимка (общий размер торрента), а при
|
||
отсутствии торрента в снимке — из суммарного размера разложенных файлов загрузки;
|
||
если неизвестно ни то, ни другое — прочерк «—».
|
||
|
||
#### 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}`
|
||
|
||
### 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: Отображение промежуточного состояния catched
|
||
|
||
Веб-UI SHALL отображать состояние `catched` как штатную промежуточную фазу
|
||
(«поймано, добавляется в qBittorrent»): бейдж статуса загрузки SHALL иметь
|
||
понятную человекочитаемую подпись для `catched` (а не сырое `catched`), а
|
||
загрузка в `catched` SHALL относиться к **активной** группе списка.
|
||
|
||
Пока отображаемое имя ещё не выведено (в `catched` `download.display_name`
|
||
пуст), заголовок загрузки SHALL деградировать по существующему фолбеку
|
||
(распознанное название или усечённый источник) — см. «Заголовок загрузки из
|
||
имени раздачи». Секция раздачи/живого прогресса для `catched` SHALL корректно
|
||
отсутствовать (раздачи в qBittorrent ещё нет), не создавая ошибок отображения.
|
||
|
||
Карточка/страница загрузки в `catched` SHALL самообновляться самозавершающимся
|
||
htmx-поллингом (см. конвенцию веб-UI): по переходе загрузки в `downloading`
|
||
интерфейс SHALL отражать это без перезагрузки страницы (подхватить бейдж,
|
||
выведенное имя и появившийся живой прогресс), а поллинг фазы `catched` SHALL
|
||
завершаться, как только загрузка её покинула.
|
||
|
||
#### 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** поллинг фазы `catched` завершается
|
||
|
||
|
||
### 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** выполняется приём по тексту источника, как прежде
|