jellybit/openspec/changes/review-source-selection/design.md

## Context

Экран ревью уже умеет много: выбор кандидата (`ChooseCandidate`), ручной
ввод id (`SetProviderID`), «без базы» (`ClearProvider`), превью текущего
плана (`ReviewData.Preview` через `layout.BuildLinks`). Механика выбора
источника — это **overrides**: выбор кандидата пиннит `provider`,
`provider_id` и (если есть) `title`/`year`, после чего эффективный план
пересобирается `applyOverrides` и печатается превью путей.

Проблемы текущего экрана — не в отсутствии операций, а в подаче:

- нейронка и кандидаты баз показаны как разные сущности (план сверху,
  кандидаты снизу; «без базы» — особое состояние);
- **превью есть только для уже выбранного** источника: чтобы увидеть пути
  для другого кандидата, его надо сначала выбрать (запись пиннится), т.е.
  «примерить вслепую».

Ограничение capability `web-ui`: клиент не пересчитывает доменное
состояние — все доменные величины (пути, поля) приходят с сервера
(требование «Клиентские взаимодействия без сборки»).

## Goals / Non-Goals

**Goals:**

- Единый список источников: нейронка + кандидаты баз + добавленные вручную,
  один активный.
- Предпросмотр полей (тип/название/год) и целевых путей **для любого
  источника до его выбора**, посчитанный на сервере.
- Ручное добавление источника по id/URL как строки списка.
- Переиспользовать существующую логику (`applyOverrides` +
  `layout.BuildLinks`), не дублируя правила именования.

**Non-Goals:**

- Fetch деталей записи из метабазы (режиссёр и пр.) — только резервируем
  место в UI.
- **Сила совпадения кандидата** (per-candidate score) и сортировка/подсветка
  списка по ней — сегодня у кандидата такого поля нет; список берём в
  порядке сбора. Отдельная идея беклога (там же — пересмотр процесса
  распознавания/матчинга).
- Изменение решения «авто vs review» и модели уверенности — не трогаем: авто
  по-прежнему только при единственном сильном матче + валидации, иначе
  review; фича работает **внутри** уже наступившего review.
- Отдельный capability `review` и перекройка домена метабаз — отдельная
  задача беклога.
- Редактор маппинга «файл → серия» и правки в Telegram.

## Decisions

### 0. Двухуровневая модель ревью сохраняется, нового подтверждения нет

В ревью два независимых шага, оба остаются как есть:

1. **Выбор источника** — кнопки «выбрать» / «Задать id» / «Без базы» (POST →
   `ChooseCandidate`/`SetProviderID`/`ClearProvider`) **фиксируют** матч,
   записывая overrides. Файлы не раскладываются, лишь пересобирается план.
2. **«Применить»** (POST → `Apply`) — единственный шаг, создающий хардлинки.

Фича добавляет **только предпросмотр до шага 1**: увидеть поля и целевые
пути каждого источника, **не нажимая «выбрать»** (не трогая БД). Семантику
«выбрать» и «Применить» не меняем, новых кнопок-подтверждений не вводим.

### 1. Предпросмотр считается на сервере эфемерно, без записи overrides

Добавляем в `worker` чистый расчёт: по текущему плану и **гипотетическому**
источнику `(provider, provider_id, опц. title/year)` собрать эффективные
поля и `[]layout.Link`, **не записывая** overrides в БД. Технически — тот
же `applyOverrides` + `layouter.BuildLinks(toLayoutPlan(...))`, что и в
`ReviewData`, но поверх копии плана с временными пинами источника; в БД
ничего не пишем.

`ReviewData` расширяется срезом «источник → (поля, превью путей, активен
ли)» для нейронки и каждого кандидата. Транспорт рендерит их строками
списка.

- **Почему так, а не «выбрать → посмотреть → отменить»:** выбор сейчас
  пиннит запись (пишет overrides) и меняет сохранённый матч; «примерка»
  не должна трогать состояние (инвариант «предпросмотр ничего не
  раскладывает и не фиксирует»).
- **Альтернатива — отдельный эндпоинт `GET /review/{id}/preview?source=…`,
  отдающий htmx-фрагмент:** отвергнута для известных источников — превью
  считается быстро и без сети (`BuildLinks` — чистая работа с путями), их
  дешевле посчитать сразу и вложить в страницу; лишний раундтрип на каждое
  наведение не нужен.

### 1a. Единая деривация «источник → набор overrides» (гарантия preview == apply)

**Проблема, найденная на ревью дизайна.** Пины `ovrTitle`/`ovrYear` пишутся
`SetOverride` и не удаляются (в store нет `DeleteOverride`). `ChooseCandidate`
пиннит title/year только при непустых полях кандидата (review.go:573-579), а
`ClearProvider` их вообще не трогает (review.go:624-640). Значит после выбора
кандидата «Fargo/2014» и последующего переключения на нейронку или на ручной
кандидат без title запиненный `ovrTitle=Fargo` **остаётся**. Тогда `applyOverrides`
(review.go:742) при `Apply` возьмёт `Fargo`, а эфемерное превью источника без
собственного title покажет title из плана → **пути превью ≠ пути применения**.
Это и латентный баг текущего кода (переключение кандидатов тянет чужой title).

**Решение.** Ввести одну чистую функцию «источник → полный самосогласованный
набор overrides» и использовать её **и в превью, и в коммите**:

- источник-кандидат с title/year → пиннит их; **без** title/year → пишет
  **пустую строку** в `ovrTitle`/`ovrYear` (в `applyOverrides` пустая строка
  трактуется как «нет override», review.go:742,745 — `DeleteOverride` не нужен,
  берётся значение плана);
- источник-нейронка (`ClearProvider`) → `provider=none` и пустые
  `ovrTitle`/`ovrYear` (поля из плана распознавания).

Так каждый источник даёт детерминированный эффективный план; превью считается
тем же набором overrides, что запишет выбор → **preview == apply по построению**.

- **Затрагивает поведение `worker`** (`ChooseCandidate`/`ClearProvider` теперь
  очищают title/year), а не только web-ui. Это осознанно: спека остаётся в
  `web-ui` (наблюдаемое — «превью == применение» и «переключение не тянет чужие
  поля»), а правка команд ревью — реализация. Заодно чиним латентный баг.
- **Альтернатива — превью «симулирует» унаследованные пины** (показывать чужой
  title у нейронки): отвергнута — противоречит принципу «нейронка = поля
  распознавания» и путает пользователя.

### 2. Клиент только показывает предпосчитанное, не считает пути

Превью всех источников предпосчитываем на сервере и вкладываем в страницу
(данных немного — кандидатов мало, порога/ленивой загрузки не вводим).
Клиент лишь раскрывает/скрывает предпосчитанный блок строки по клику
(нативный `<details>` или минимальный vanilla-JS) — никакого доменного
пересчёта на клиенте, соблюдаем требование `web-ui`.

UI-модель: секция **«Раскладка» остаётся отдельной** и показывает пути
**активного** источника (как сейчас); раскрываемое инлайн-превью в строке —
для сравнения **неактивных** источников до выбора. Фактическая смена
активного источника (пиннинг) — по явному действию формой (раундтрип), как
сейчас.

### 3. Нейронка — синтетическая строка, а не особый режим

Строку «распознано нейронкой» синтезируем из сырого плана распознавания
(`provider = none`): её поля — то, что дал LLM без базы, её превью —
раскладка без тега провайдера. Выбор этой строки = существующий
`ClearProvider`. Так «без базы» перестаёт быть отдельным состоянием UI и
становится обычной строкой списка.

### 4. Ручной источник — кандидат в том же списке

Ручной ввод (id или URL) на входной границе `httpapi` парсим в
`(provider, provider_id)`. Допустимые провайдеры — `tmdb`, `tvdb`, `imdb`
(набор согласован с `providerTag`/`providerURL`; `tvmaze` — только источник
автопоиска, вручную не вводится). Добавляем как **строку списка**: сохраняем
`metadata_candidate` с этим `provider`/`provider_id` и (если дан) `url`;
`title`/`year` — пустые (деталей не тянем). Дедуп по `provider:id`: если такой
источник уже в списке — не плодим строку, а выбираем существующую. Такой
кандидат участвует в выборе и предпросмотре наравне с автонайденными; выбор —
тот же `ChooseCandidate` (с очисткой title/year по решению 1a).

**Парсинг URL реалистичен не для всех баз.** `providerURL` строит TVDB как
`thetvdb.com/dereferrer/series/{numeric_id}`, но с сайта пользователь копирует
`thetvdb.com/series/{slug}` — без числового id. Поэтому обещаем: **URL — для
TMDB/IMDb**, для **TVDB — ручной ввод числового id** (slug из URL не
распознаём). Список принимаемых паттернов фиксируем в реализации как обратный
к `providerURL`.

- Превью ручного источника корректно и без title/year из базы: имя папки
  берётся из title **плана**, а от источника меняется лишь тег провайдера
  в пути. Значит «предпросмотр путей» для ручного кандидата полноценен.
- **Альтернатива — просто пиннить `SetProviderID` без строки в списке:**
  отвергнута — тогда ручной источник не «переключаемый» наравне с
  остальными, что противоречит принципу единого списка.

### 5. Режиссёр — зарезервированное место, источник позже

В предпросмотре полей выводим строку «Режиссёр» пустой (прочерк). Fetch
деталей из метабазы — отдельная задача; при появлении источника (детали по
id или парсинг из контекста загрузки) заполняем это же место.

## Risks / Trade-offs

- **[Рассинхрон превью и применения]** Превью и реальная раскладка должны
  идти одной логикой. → Оба используют `layout.BuildLinks`/`naming` и **одну
  деривацию «источник → overrides»** (решение 1a); в тестах проверяем равенство
  путей превью и применения (требование `web-ui` «Превью совпадает с реальной
  раскладкой», сценарий «Переключение источника не тянет чужие поля»).
- **[Залипший override title/year]** Пины title/year не удаляются и могут
  утечь между источниками (латентный баг). → Решение 1a: выбор источника пишет
  полный самосогласованный набор (пустая строка = сброс к плану).
- **[Раздувание страницы]** Предпосчёт превью для всех кандидатов кладёт N
  наборов путей в HTML. → Кандидатов немного (потолок сбора уже есть в
  `recognition`); `BuildLinks` без сети. Приемлемо; если станет тяжело —
  ленивый htmx-фрагмент (решение 1, альтернатива) как эволюция.
- **[Ручной кандидат с пустыми title/year]** Строки списка и матч-ссылка
  должны переживать пустые поля. → `matchURL` уже строит URL из
  provider/id; заголовок берём из плана. Проверить рендер строки без
  title/year.
- **[Дубль ручного и автокандидата]** Пользователь может ввести id, уже
  присутствующий в списке. → Дедуп по `provider:id` при добавлении (как в
  сборе кандидатов): не плодим строку, просто выбираем существующую.

## Migration Plan

- Данные: миграций схемы не требуется — ручной кандидат ложится в
  существующую `metadata_candidate` (title/year nullable уже так). Новый
  источник строки — пользовательское действие, обратная совместимость
  полная.
- Откат: изменения ограничены страницей ревью и добавочным методом
  предпросмотра в `worker`; откат — возврат прежнего шаблона/обработчика,
  данные не затрагиваются.

## Open Questions

Блокирующих открытых вопросов нет. Оставшийся детерминированный на
реализацию пункт — точный список принимаемых URL-паттернов ручного ввода
(обратный к `providerURL`: `themoviedb.org/{movie,tv}/{id}`,
`imdb.com/title/{id}`; TVDB — числовой id, не slug), см. решение 4.