jellybit/openspec/specs/review/spec.md

review Specification

Purpose

Ревью раскладки человеком после распознавания и матча: петля «догадка → подсказка → перераспознавание», команды (Применить/Уточнить/Распознать заново/ Игнор/Позже/Отклонить/Undo/Привязать заново; тип — read-only, корректируется через «Уточнить»), мягкие подсказки vs жёсткие override, единый список источников совпадения с ручным добавлением и предпросмотром (превью = применение), разделение труда транспортов (веб — точные правки, Telegram — быстрые действия и эскалация в веб).

Requirements

Requirement: Вход в review с явной причиной

Когда модель уверенности не разрешает авто-раскладку, система SHALL переводить загрузку в review и SHALL показывать конкретную причину (низкая самооценка LLM; нет матча в базе или несколько кандидатов; предупреждение структурной валидации; неразобранный ответ LLM), а не обобщённое «не уверен». Поверхность решения SHALL быть единой для всех транспортов и содержать источник (имя, контекст, дерево файлов), догадку системы (тип, название, год, матч) и превью целевой раскладки.

Scenario: Причина видна в интерфейсе

• GIVEN загрузка ушла в review из-за отсутствия матча в базе
• WHEN пользователь открывает ревью
• THEN показана конкретная причина (напр. «нет в TMDB · уверенность 0.46»)

Requirement: Команды ревью и их эффекты

Экран ревью SHALL предоставлять команды: Применить (создать хардлинки по эффективному плану), Уточнить (добавить подсказку → перераспознать), Распознать заново (повторный прогон без новой подсказки), Игнор файла, Позже (deferred), Отклонить (cancelled), Undo (снять созданные ссылки → reverted) и Привязать заново (из reverted/cancelled/target_missing → перераспознавание с ручным подтверждением). Никакая поверхность ревью — ни веб-UI, ни Telegram — MUST NOT содержать команду переключения типа movie↔series: тип показывается read-only, а его корректировка выполняется мягкой подсказкой через Уточнить (перераспознавание, где пользователь явно указывает тип). Команды из любого транспорта SHALL сериализоваться worker'ом под единой блокировкой; применяется последняя валидная команда.

Команда Позже (Defer) SHALL парковать задачу в deferred из любого не-терминального состояния, у которого уже есть раздача в qBittorrent, и SHALL отклонять её из пре-источникового состояния catched (торрент ещё НЕ добавлен в qBittorrent) — конфликтом (ErrConflict) с понятным пользователю сообщением, НЕ меняя состояние загрузки. Пре-источниковое catched — единственное состояние без раздачи среди не-терминальных: откладывать в нём нечего (задача ещё не дошла до ревью), а catched → deferred уводил бы задачу в лимбо — processCatched листает только catched и больше её не подхватит, а последующие команды через отсутствие источника выводят необратимый deleted. Терминальные состояния Defer SHALL отклонять как и прежде (ErrConflict).

Команды, которым нужен источник (Применить, Уточнить, Распознать заново, Привязать заново), SHALL синхронно (без дебаунса) проверять перед действием, что источник не только присутствует в qBittorrent, но и готов к раскладке — раздача в готовом классе состояния (uploading/stalledUP/pausedUP/… с учётом различий имён qBit v4/v5), т.е. файлы докачаны. Если источник ещё качается (любое downloading-подобное или переходное moving/checking состояние), команда SHALL отказывать с конфликтом и причиной «торрент ещё качается», НЕ создавая хардлинки и НЕ меняя состояние загрузки (её нахождение в review/deferred/… легитимно, приводить к реальности нечего). Отсутствие источника в qBittorrent SHALL по-прежнему приводить состояние к реальности (orphaned/deleted) и отказывать. Так недокачанная задача не может пройти через перераспознавание в авто-раскладку или ручное применение и захардлинкать неполные файлы, обойдя финальность состояния completed.

Scenario: Применение создаёт раскладку

• GIVEN загрузка в review с эффективным планом
• WHEN пользователь выбирает «Применить»
• THEN создаются хардлинки по плану, задача переходит к раскладке

Scenario: Отклонить и привязать заново

• GIVEN загрузка в review
• WHEN пользователь «Отклонить», затем «Привязать заново»
• THEN задача уходит в cancelled, а затем снова на распознавание с ручным подтверждением (авто-раскладка не делается)

Scenario: Тип не переключается командой ни в одном транспорте

• GIVEN загрузка в review с распознанным типом
• WHEN пользователь открывает ревью в вебе или в Telegram
• THEN отдельной команды/кнопки переключения movie↔series нет ни на одной поверхности
• AND тип показан read-only; для смены типа пользователь уточняет распознавание («Уточнить», явно указав тип)

Scenario: Позже паркует задачу из ревью

• GIVEN загрузка в review (раздача в qBittorrent уже есть)
• WHEN пользователь выбирает «Позже»
• THEN задача переходит в deferred и возвращается на поверхность ревью по любому последующему действию

Scenario: Позже отклоняется для пре-источникового catched

• GIVEN загрузка в catched (торрент ещё не добавлен в qBittorrent)
• WHEN приходит команда «Позже» (Defer, напр. прямым POST на /ui/downloads/{id}/defer)
• THEN команда отклоняется конфликтом с понятным сообщением, что отложить можно только после добавления торрента
• AND загрузка остаётся в catched и штатно доходит до downloading через processCatched

Scenario: Недокачанный источник отклоняет перераспознавание

• GIVEN загрузка припаркована в deferred, а её раздача в qBittorrent ещё качается (downloading, файлы не докачаны)
• WHEN пользователь выбирает «Распознать заново» (или «Уточнить»/«Привязать заново»)
• THEN команда отклоняется с конфликтом и причиной «торрент ещё качается»
• AND загрузка остаётся в deferred, хардлинки не создаются, авто-раскладка не запускается

Scenario: Недокачанный источник отклоняет ручное применение

• GIVEN загрузка в review, чья раздача в qBittorrent ещё качается
• WHEN пользователь выбирает «Применить»
• THEN команда отклоняется с конфликтом «торрент ещё качается», хардлинки на неполные файлы не создаются, состояние загрузки не меняется

Requirement: Подсказка мягкая, override жёсткий

Подсказка (hint) SHALL быть мягким сигналом — её интерпретирует LLM при перераспознавании. Ручная правка поля SHALL быть жёстким override: система берёт значение как есть и «пиннит» его; перераспознавание НЕ SHALL затирать уже поправленное поле. Накопленные подсказки и правки SHALL переживать перераспознавание и накладываться на новый план.

Scenario: Override переживает перераспознавание

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

Requirement: Единый список источников совпадения на ревью

Экран ревью (/review/{id}) SHALL показывать совпавшие источники единым списком, в котором распознавание нейронкой (без базы) — такая же строка, как кандидаты метабаз (TMDB/TVDB/TVMaze), а не отдельный режим сверху. Ровно один источник в списке SHALL быть отмечен активным (эффективный матч). Активный источник SHALL выбираться одним кликом/тапом по строке варианта (радиокнопка), без отдельной кнопки подтверждения выбора. Выбор источника SHALL сохранять его как эффективный матч (persist) и SHALL выполняться через раундтрип на сервер (форма/htmx), без клиентского пересчёта доменного состояния; при этом инфо-часть и предпросмотр раскладки SHALL немедленно обновляться под выбранный источник (частичный своп блока, без полной перезагрузки страницы). Тем же ответом свопа SHALL синхронно обновляться панель действий — в частности доступность команды Применить, зависящая от наличия предпросмотра раскладки, — через out-of-band-фрагмент, чтобы кнопка не рассинхронизировалась с блоком источника (например при пустом предпросмотре из-за коллизии путей). Экран SHALL позволять операции над этим списком: выбрать кандидата базы, переключиться на другого кандидата и снять матч с базы обратно на нейронку («без базы»). Список источников SHALL показываться только при наличии плана распознавания.

Scenario: Нейронка — строка в общем списке

• GIVEN загрузка в review с распознаванием нейронкой и одним или несколькими кандидатами метабаз
• WHEN пользователь открывает GET /review/{id}
• THEN источники показаны единым списком, где строка «распознано нейронкой» стоит наравне с кандидатами баз
• AND активным отмечен ровно один источник (текущий эффективный матч)

Scenario: Выбор кандидата одним кликом

• GIVEN на экране ревью выбран один кандидат метабазы
• WHEN пользователь кликает/тапает строку другого кандидата
• THEN выбранный кандидат сохраняется активным, прочие — неактивны, без отдельного нажатия кнопки «выбрать»
• AND инфо-часть и предпросмотр раскладки сразу обновляются под выбранного кандидата без полной перезагрузки страницы
• AND панель действий обновляется тем же ответом (out-of-band): доступность «Применить» синхронна наличию предпросмотра раскладки

Scenario: Снятие матча в пользу нейронки

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

Requirement: Ручное добавление источника по id или URL

Когда автопоиск по базам промахнулся, экран ревью SHALL позволять добавить источник вручную — по идентификатору записи метабазы или, где применимо, по её URL. Ввод SHALL разбираться и валидироваться в пару (provider, provider_id) на входной границе (internal/httpapi); допустимые провайдеры — tmdb, tvdb, imdb. Добавленный источник SHALL появляться в списке как выбираемая строка; при совпадении provider:id с уже присутствующим источником новая строка NOT создаётся, а выбирается существующая. Некорректный ввод SHALL отклоняться с сообщением, не меняя текущий активный источник.

Scenario: Добавление кандидата по URL TMDB

• GIVEN загрузка в review, где нужной записи нет среди автокандидатов
• WHEN пользователь вводит URL записи TMDB и подтверждает добавление
• THEN из URL извлекаются провайдер и id, источник добавляется в список выбираемой строкой

Scenario: Дубль id выбирает существующую строку

• GIVEN в списке уже есть кандидат с данным provider:id
• WHEN пользователь добавляет вручную тот же provider:id
• THEN новая строка не создаётся, активным становится существующий кандидат

Scenario: Некорректный ввод отклонён

• WHEN пользователь вводит нераспознаваемый id/URL
• THEN экран показывает сообщение об ошибке и не меняет текущий активный источник

Requirement: Подтверждение матча обновляет отображаемое имя

Система SHALL при подтверждении матча в ревью запускать обновление отображаемого имени загрузки по подтверждённому распознаванию (см. capability ingest): переливать полный ярлык имени — «Название (режиссёр, год)», для сериала со сводкой сезонов — в download.display_name и в имя раздачи qBittorrent, без нового вызова LLM. Имя строится из эффективных полей (override → распознавание с вложенным матчем → сохранённый контекст). Подтверждением матча SHALL считаться как выбор кандидата из списка совпадений, так и ручное добавление источника по id/URL (оба закрепляют провайдера и каноническое название).

При закреплении выбранного/добавленного источника система SHALL best-effort получить режиссёра этого источника из метабазы (credits по provider:id, см. metadata-match) и закрепить его как override, чтобы он попал в эффективные поля и в ярлык. Недоступность credits или отсутствие режиссёра SHALL NOT проваливать выбор источника: режиссёр остаётся из более низкого слоя (сохранённый контекст) или пустым. Так режиссёр из метабазы появляется и на основном пути подтверждения — ручном выборе кандидата, а не только при авто-матче.

Обновление SHALL выполняться после успешного закрепления выбора кандидата и SHALL быть best-effort по отношению к qBittorrent: недоступность клиента SHALL NOT проваливать команду ревью. Это согласуется с инвариантом «авто-действие только при подтверждённом матче».

Scenario: Выбор кандидата обновляет имя

• GIVEN загрузка в ревью с пустым или неинформативным display_name (например, «Unknown») и списком кандидатов
• WHEN пользователь выбирает кандидата, подтверждая матч
• THEN выбор кандидата закрепляется как и прежде
• AND download.display_name обновляется полным ярлыком «Название (режиссёр, год)» (для сериала — со сводкой сезонов)
• AND раздача в qBittorrent переименовывается в то же имя

Scenario: Ручное добавление источника обновляет имя

• GIVEN загрузка в ревью без совпадений в списке
• WHEN пользователь вручную добавляет источник по id/URL, подтверждая матч
• THEN источник закрепляется как и прежде
• AND download.display_name и имя раздачи в qBittorrent обновляются полным ярлыком подтверждённого источника

Scenario: Выбор кандидата подтягивает режиссёра в ярлык

• GIVEN загрузка в ревью, у выбранного кандидата в credits метабазы указан режиссёр
• WHEN пользователь выбирает кандидата, подтверждая матч
• THEN режиссёр best-effort извлекается из метабазы и закрепляется override
• AND download.display_name получает полный ярлык с этим режиссёром

Scenario: Режиссёр кандидата недоступен — выбор не ломается

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

Scenario: Недоступность qBittorrent не ломает выбор кандидата

• GIVEN выбор кандидата в ревью
• WHEN переименование раздачи в qBittorrent завершается ошибкой
• THEN выбор кандидата и обновление download.display_name выполнены
• AND команда ревью не возвращает ошибку

Requirement: Инфо и предпросмотр выбранного источника

В едином блоке выбора источника экран ревью SHALL показывать для выбранного (активного) источника две части: инфо — тип (read-only, movie/series), название, оригинальное название, год, режиссёра эффективного источника, разрешённого слоями (override/подтверждённый матч+кандидат → сохранённый при приёме контекст раздачи, parsed_context; когда режиссёр недоступен ни в одном слое — пусто/прочерк, не ломая вёрстку), для сериала — сводку сезонов (один сезон, диапазон/список для многосезонного пака или «Спецвыпуски»); и предпросмотр раскладки — целевые пути хардлинков этого источника. Обе части SHALL относиться именно к активному источнику и SHALL обновляться при смене выбора. Отрисовка блока (показ инфо и предпросмотра) MUST NOT создавать хардлинки: раскладка создаётся только явным действием «Применить». Совпадение целевых путей предпросмотра с результатом применения регулируется требованием «Превью раскладки через единую логику именования» (web-ui).

Scenario: Инфо и предпросмотр относятся к активному источнику

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

Scenario: Просмотр блока не создаёт раскладку

• GIVEN экран ревью с показанным блоком выбора источника
• WHEN пользователь только просматривает инфо и предпросмотр, не нажимая «Применить»
• THEN хардлинки не создаются, файлы под paths.movies/series не меняются

Scenario: Режиссёр показан, когда доступен

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

Scenario: Режиссёр берётся из контекста, когда матч его не даёт

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

Requirement: Разделение труда транспортов в ревью

Состояние ревью SHALL быть единым (в SQLite) для всех транспортов. Веб-UI SHALL быть поверхностью точных правок (маппинг файлов, ручной ввод/выбор источника по id или URL, «без базы», предпросмотр). Telegram SHALL давать быстрые действия (одобрить, подсказать, быстрый выбор источника из готового списка кандидатов метабазы, «Позже»/«Отклонить») и эскалацию в веб deep-link'ом на ту же страницу; точечные правки, не помещающиеся в чат (ручной ввод id/URL, маппинг файлов), SHALL делаться в вебе.

Scenario: Эскалация из Telegram в веб

• GIVEN загрузка в review, требующая точечного маппинга файлов
• WHEN пользователь в Telegram выбирает «В вебе»
• THEN бот даёт deep-link на страницу ревью той же загрузки

Scenario: Быстрый выбор кандидата в Telegram, точный ввод — в вебе

• GIVEN загрузка в review с сохранёнными кандидатами метабазы
• WHEN пользователь выбирает кандидата inline-кнопкой в Telegram
• THEN кандидат закрепляется как источник (тот же единый выбор источника, что и в вебе), а ручной ввод id/URL и «без базы» остаются точными правками веба

Requirement: Петлевые действия ревью обновляют экран на месте

Петлевые действия распознавания на экране ревью — Распознать заново (rerecognize) и Уточнить (refine) — SHALL выполняться htmx-запросом и обновлять тело экрана ревью на месте (partial swap), без полной перезагрузки страницы и без сброса позиции прокрутки. Поскольку эти действия асинхронны (переводят загрузку в recognizing, распознавание доделывает воркер), своп SHALL отражать актуальное состояние — состояние recognizing с индикацией «идёт распознавание», а не мгновенно готовый план. Накопленные подсказки и ручные override MUST переживать перераспознавание. Это согласуется с уже действующим частичным свопом при смене выбранного источника (см. «Единый список источников совпадения на ревью»).

Пока загрузка в recognizing, экран ревью SHALL сам обновляться поллингом htmx-фрагмента (GET /fragments/downloads/{id}/review) и по завершении распознавания SHALL автоматически смениться на готовый план (список источников, инфо и предпросмотр активного источника), без ручного обновления страницы. Как только состояние вышло из recognizing, фрагмент SHALL возвращаться без поллера, и опрос прекращается. Без htmx экран SHALL деградировать до ручной ссылки «Обновить».

Выходы из ревью, после которых загрузка покидает review — Применить (apply → раскладка/done), Позже (defer → deferred) и Отклонить (cancel → cancelled), — НЕ обязаны свопить экран на месте и MAY уводить с экрана ревью навигацией (редирект/HX-Redirect), поскольку загрузка перестаёт быть предметом этого экрана.

Поведение петлевых действий MUST деградировать без htmx: без заголовка HX-Request обработчик SHALL исполнять то же доменное действие и отвечать редиректом на /review/{id}, как раньше.

Scenario: Перераспознавание свопит экран в состояние recognizing

• GIVEN загрузка в review, экран ревью открыт
• WHEN пользователь нажимает «Распознать заново» или «Уточнить» с подсказкой (htmx активен)
• THEN тело экрана ревью обновляется на месте в состояние recognizing с индикацией «идёт распознавание», без полной перезагрузки и без прыжка прокрутки наверх
• AND накопленные подсказки и ручные override сохраняются

Scenario: Экран сам обновляется до готового плана

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

Scenario: Выход из ревью уводит с экрана

• GIVEN загрузка в review с готовым превью
• WHEN пользователь нажимает «Применить», «Позже» или «Отклонить»
• THEN загрузка покидает review (соответственно done/deferred/ cancelled), а интерфейс уводит пользователя с экрана ревью навигацией

Scenario: Деградация петлевого действия без htmx

• WHEN «Распознать заново» или «Уточнить» приходит POST-запросом без заголовка HX-Request
• THEN обработчик исполняет то же доменное действие и отвечает редиректом на /review/{id}, поведение без JavaScript не ломается