jellybit/openspec/changes/archive/2026-07-01-web-ui-list-detail/design.md

Context

Современный server-rendered веб-UI уже даёт список-карточки, страницу просмотра /download/{id}, ревью и живой прогресс (htmx-поллинг снимка воркера). Осталось закрыть хвосты беклога по UI/UX. Текущее состояние по пунктам:

• Список (handleIndex + index.html): грузит ListDownloads целиком, фильтр-чипы и поиск — клиентский JS по data-group/data-text уже отрендеренных карточек, deleted прячется чекбоксом showAll. Пагинации нет.
• Заголовок карточки и шапки страницы — d.SourceRef (для magnet это сырая ссылка). Красивое имя есть только в блоке «Распознано как» и только после распознавания (rd.Plan.Title). Имя rename, уходящее в qBittorrent при приёме (internal/ingest, Namer.DeriveName), нигде не сохраняется.
• Матч метабазы: на ревью кандидаты уже показываются со ссылкой (candidate_url, миграция 0004); но подтверждённый выбор («Выбрано: provider id») и блок «Распознано как» на /download/{id} ссылки не имеют.
• Полировка: в «Распознано как» список полей ограничен max-width:360px; в layout-виджете стрелка не приклеена к строке файла-источника.

Ограничения: один статический бинарь, без сборки фронта и реактивных фреймворков; чтение — через store, тонкий транспорт httpapi; SQLite (одиночное соединение, сериализация записи). Целевой масштаб — сотни–тысячи строк download.

Goals / Non-Goals

Goals:

• Список масштабируется на рост БД: серверные фильтр по состоянию, поиск и пагинация через GET-параметры, работающие без JS и шарящиеся ссылкой.
• Заголовок загрузки — человекочитаемое имя раздачи qBittorrent, доступное с первого кадра (до распознавания), с внятным фолбеком.
• Подтверждённый матч метабазы виден ссылкой на запись во всех веб-местах (карточка просмотра, «Источник совпадения» ревью).
• Сырой источник/magnet не мозолит глаза в заголовке — вынесен в отдельный блок.
• Мелкие дефекты вёрстки устранены.

Non-Goals:

• Полный лог переходов состояний (нужна таблица истории — отдельная задача).
• Собственный идентификатор загрузки, слияние по infohash.
• Полноценный «выбор источника матча с предпросмотром полей» (отдельная задача беклога); здесь — только ссылка на уже подтверждённый матч.
• Показ матча в Telegram, перевод живых обновлений на SSE.

Decisions

1. Список: серверные фильтр/поиск/пагинация через GET-параметры

Параметры: f (группа состояний: all|review|active|done|problem, по умолчанию all без deleted), q (строка поиска), page (1-based), плюс all=1 (показать в т.ч. deleted). Размер страницы — константа в httpapi (25).

Новый метод store возвращает страницу + общее число строк под фильтром для рендера пагинации: например ListDownloadsPage(ctx, ListFilter) ([]Download, int, error), где ListFilter{Group, Query, Deleted, Limit, Offset}. В SQL: WHERE по множеству состояний группы (маппинг из существующего stateGroup, вынести в общий источник истины состояние↔группа), deleted включается только при all; поиск — LIKE '%'||?||'%' по source_ref, display_name, context, infohash (регистронезависимо, COLLATE NOCASE); сортировка ORDER BY COALESCE(source_added_at, created_at) DESC, id DESC (см. решение 5); LIMIT/OFFSET. Итог count — отдельный COUNT(*) с тем же WHERE.

page клэмпится: < 1/нечисловой → 1; за последней страницей → пустая страница (не ошибка). Метасимволы %/_ в q не экранируем (параметризованный LIKE, не security-issue; при необходимости добавим ESCAPE позже). Пустое состояние (len(page)==0) рендерит сервер: «ничего не найдено», если активны фильтр/поиск, иначе «пока пусто» — клиентского JS для этого больше нет.

Почему GET, а не htmx/JSON: закладки/шаринг, работа без JS, минимум кода; согласуется с «клиентская логика без сборки». Пагинация и чипы — обычные ссылки, сохраняющие текущие f/q. Клиентская JS-фильтрация удаляется (заменена серверной), копирование infohash и <details> остаются.

Живой прогресс: карточки текущей страницы по-прежнему сами поллят свой фрагмент прогресса — механика live-status не затрагивается. Форма поиска — обычный GET-submit; фильтр-чипы — ссылки.

Альтернатива (клиентская пагинация или «Только пагинация» с клиентским фильтром) отвергнута: фильтрует лишь текущую страницу и вводит в заблуждение.

2. Персистентность отображаемого имени (display_name)

Миграция 0005: ALTER TABLE download ADD COLUMN display_name TEXT NOT NULL DEFAULT ''. При приёме (internal/ingest) выведенное имя rename пишется и в download.display_name (та же строка, что уходит в qBittorrent). Инвариант ingest-спеки сохраняется: имя не влияет на пути/распознавание/раскладку.

Для усыновлённых торрентов (discover.adopt()) приёма через ingest нет и rename не выводится; там SourceRef — искусственный magnet:?xt=urn:btih:…. Чтобы заголовок таких задач не был голым btih, при усыновлении пишем display_name = t.Name (имя торрента из qBittorrent).

Заголовок в веб-UI (карточка списка и шапка /download/{id}) — фолбек-цепочка:

1. display_name (если непустой);
2. распознанное rd.Plan.Title (если есть план);
3. сырой источник (source_ref), усечённый в одну строку как обычный заголовок.

Старые строки БД получат display_name='' → отработает п.2/п.3, регресса нет.

Почему колонка, а не вывод на лету: rename выводится единожды при приёме (в т.ч. через LLM) и в БД сейчас не сохраняется; пересчитывать на каждый рендер дорого и недетерминированно. Хранение — дёшево и даёт стабильный заголовок с первого кадра.

3. Ссылка на запись метабазы

Приоритет — URL уже сохранённого выбранного кандидата (candidate_url, миграция 0004): в ReviewData есть Candidates с флагом Chosen и URL (детальная страница их грузит — handleDownload → ReviewData, проверено).

Важно: URL выбранного кандидата берём только если его provider+id совпадают с эффективными rd.Provider/rd.ProviderID (пользователь мог выбрать кандидата, а затем вручную переопределить provider_id — тогда Chosen-кандидат указывает на другую запись). Если не совпадают или URL у кандидата нет — строим канонический URL функцией providerURL(provider, id, mediaType).

providerURL учитывает тип медиа: для tmdb — /movie/{id} vs /tv/{id} (см. internal/metadata/tmdb.go), для tvdb — медиазависимый путь (см. internal/metadata/tvdb.go), для imdb — /title/{id}. Тип на детальной странице известен (view.IsSeries/rd.Plan.Type). Если для провайдера/типа надёжный URL не построить — показываем матч текстом (провайдер, id) без ссылки (предусмотрено сценарием «URL записи неизвестен»).

Ссылка показывается в «Распознано как» на /download/{id} и в строке «Выбрано» блока «Источник совпадения» ревью. Ссылки — target=_blank rel=noopener (как у кандидатов).

4. Блок «Информация о торренте» на /download/{id}

Отдельная секция: тип источника, полный source_ref/magnet и infohash с кнопкой копирования. Разгружает заголовок (см. решение 2) и собирает «сырьё» в одном месте.

5. Сортировка списка по времени добавления в источник

Список сортируется по времени добавления торрента в qBittorrent (added_on), с фолбеком на время создания загрузки в jellybit (created_at). Причина: jellybit может захватывать уже добавленные (усыновлённые) торренты, поэтому created_at не отражает реальный порядок появления раздачи; added_on — более верный базис (тем же соображением воркер уже считает возраст задачи от added_on, см. worker.torrentAge).

added_on не хранится в БД — воркер берёт его из живого qbt.Torrent. Добавляем колонку download.source_added_at (nullable) и один раз персистим её из воркера. Значение неизменно (время добавления не меняется), пишем только при первом наблюдении.

Формат (критично для сортировки): source_added_at хранится байт-в-байт в том же формате, что created_at — YYYY-MM-DD HH:MM:SS в UTC (store.sqliteTimeLayout). Воркер форматирует time.Unix(t.AddedOn,0).UTC().Format(...) через хелпер store (не RFC3339 и не число), иначе лексикографическое сравнение TEXT в COALESCE(...) даст неверный порядок при смешивании заполненных и фолбек-строк.

Точка записи: в цикле Poll сразу после успешного сопоставления активной задачи с торрентом по byHash (до reconcile), для любого класса состояния торрента — иначе задача, увиденная тиком уже готовой (classReady → сразу transition), запись пропустит. Для усыновлённых торрентов added_on доступен уже в adopt() (discover.go) — пишем и там. Всё под w.mu. Идемпотентность: проверка d.SourceAddedAt в Go + SQL-гард WHERE source_added_at IS NULL в методе стора (не писать на каждом тике).

Сортировка в запросе списка — ORDER BY COALESCE(source_added_at, created_at) DESC, id DESC. Вторичный ключ id DESC обязателен: без него при равных метках времени (пакетное добавление в одну секунду) SQLite даёт неустойчивый порядок, и при LIMIT/OFFSET строки задваиваются/пропадают между страницами — это нарушило бы требование «порядок согласован между страницами».

Альтернатива (сортировка по id DESC или только created_at) отвергнута: порядок разъедется для усыновлённых торрентов.

6. Полировка вёрстки (CSS/шаблоны)

• «Распознано как»: снять max-width:360px у dl.kv — блок на всю ширину.
• Layout-виджет: приклеить стрелку к строке файла-источника (источник и цель строго друг под другом) — правка layout_widget.html/CSS.

Инвариант дизайн-системы соблюдаем: без инлайн-<style> с хардкодом цветов, правки уходят в jellybit.css.

Risks / Trade-offs

• UX: перезагрузка страницы вместо мгновенной клиентской фильтрации → GET-параметры быстры на server-rendered UI; форма/ссылки дёшевы; выигрыш — масштаб и шаринг ссылок.
• Производительность LIKE '%q%' (не использует индекс) → на целевом масштабе (сотни–тысячи строк) приемлемо; при нужде позже — FTS/индекс, вне объёма.
• Взаимодействие пагинации с живым прогрессом → карточки поллят индивидуальные фрагменты по id; пагинация не меняет live-status.
• Пустой display_name у старых строк → фолбек-цепочка покрывает; бэкофилл не требуется.
• Ручной provider_id без кандидата → providerURL строит ссылку по провайдеру; для неизвестного провайдера ссылку не показываем (только текст).

Migration Plan

1. Добавить goose-миграцию 0005 — колонки download.display_name и download.source_added_at (up: ADD COLUMN; down: снятие колонок по возможностям SQLite/goose).
2. Обновить ER-схему docs/specs/database.md (обе новые колонки).
3. Писать display_name в ingest при CreateDownload.
4. В worker персистить source_added_at при поллинге (однократно, при первом наблюдении added_on).
5. Добавить запрос списка с фильтром/поиском/сортировкой/пагинацией и count в store.
6. Перевести handleIndex на параметры + новый запрос, обновить шаблоны и CSS, убрать клиентскую фильтрацию.

Откат: обратная миграция (down) снимает колонку; UI-код фолбечит на source_ref. Изменения аддитивны, REST-контракт /api/downloads не меняется.

Open Questions

• Размер страницы (25) — уточним по ощущению на реальных данных; вынести в конфиг при необходимости (сейчас константа).