Уточнение деталей архитектуры

docs/specs/review-ux.md

@@ -0,0 +1,123 @@
+# Ревью раскладки человеком
+
+Что происходит, когда система не уверена в распознавании и не
+раскладывает файлы автоматически. Когда именно наступает ревью — см.
+[recognition.md](recognition.md); конвенции целевых имён —
+[jellyfin-layout.md](jellyfin-layout.md).
+
+Главный принцип: ревью — это **петля «догадка → подсказка человека →
+перераспознавание»**, а не статичное «ок/нет». Человек остаётся
+супервизором, а не оператором ручного ввода.
+
+## Когда наступает
+
+Загрузка уходит в `review`, если сработал любой триггер модели
+уверенности: низкая самооценка LLM; нет матча в базе (или несколько
+кандидатов); структурная валидация ругается (у фильма >1 основного
+файла; число серий не бьётся с базой; дыры/дубли в нумерации S·E).
+В интерфейсе всегда видна **конкретная причина**, а не просто «не уверен».
+
+## Поверхность решения (едина для всех транспортов)
+
+1. **Источник:** имя торрента, переданный контекст, дерево файлов с
+   размерами, (если из бота) распарсенное сообщение.
+2. **Догадка системы:** тип, название, год, сезон, матч базы и
+   **превью целевой раскладки** — буквальные пути, которые создадутся.
+3. **Причина сомнения.**
+
+## Действия
+
+- **Применить** — сделать хардлинки по плану.
+- **Уточнить и перераспознать** — добавить подсказку текстом → LLM
+  перезапускается с исходными сигналами и накопленными подсказками →
+  новый план. Главный путь, когда «LLM не справился».
+- **Поправить вручную** — объём зависит от версии (см. ниже).
+- **Выбрать кандидата базы** / ввести id / «без базы».
+- **Отклонить** / **Позже**.
+
+**Подсказка vs override.** Подсказка мягкая — LLM её интерпретирует.
+Ручная правка поля — жёсткий **override**: система берёт значение как
+есть и «пиннит» его, перераспознавание не затирает уже поправленное.
+
+## Веб-UI — точные правки
+
+```
+Fargo.S02.2015.WEB-DL.1080p.rus.eng                 🟡 review
+Причины: нет в TMDB · уверенность 0.46
+
+Контекст: «второй сезон, рус+англ дорожки»  [+ добавить → 🔁 перераспознать]
+
+Тип: ( ) фильм  (•) сериал   Название: Фарго   Год: 2015   Сезон: 02
+База: [TMDB поиск…] [TVDB поиск…]   выбрано: — (без базы)   [ввести id]
+
+Файлы → серии:
+ # | файл                 | размер | роль   | S  | E
+ 1 | Fargo.S02E01.rus.mkv | 3.1 GB | эпизод | 02 | 01
+ …                                         [нумеровать подряд] [сброс]
+ 9 | sample.mkv           |  40 MB | игнор  |  – |  –
+
+Превью:
+ series/Фарго (2015)/Season 02/Фарго (2015) S02E01.mkv  ← #1
+[ Применить ]   [ Отклонить ]   [ Позже ]
+```
+
+Ядро экрана для сериала — таблица «файл → серия» с живой валидацией
+дыр/дублей и кнопкой «нумеровать подряд» (частый случай: файлы по
+порядку, но подписаны криво). Для фильма проще: выбрать основной файл,
+остальное — extra/sample/субтитры/игнор.
+
+## Telegram — быстро, где пользователь и так есть
+
+```
+🟡 Нужно подтверждение
+Источник: Fargo.S02.2015.WEB-DL.1080p
+Похоже на: 📺 сериал «Фарго», сезон 2 (2015)
+База: TMDB не найдено · уверенность низкая
+План: 10 видео → series/Фарго (2015)/Season 02/…E01–E10
+
+[✅ Применить]   [📺↔🎬 Тип]
+[🔢 Выбрать в базе]   [🔁 Уточнить]
+[🌐 Открыть в вебе]   [❌ Отклонить]
+```
+
+- **🔁 Уточнить** → бот просит подсказку ответом → перераспознаёт →
+  редактирует то же сообщение новым планом. Петля коррекции прямо в чате.
+- **🔢 Выбрать в базе** → кнопки по кандидатам (название · год · id).
+- Точечное переназначение файлов в чат не помещается → **🌐 Открыть в
+  вебе** (deep-link на ту же страницу).
+
+## Разделение труда
+
+Telegram = одобрить / подсказать / выбрать кандидата / эскалировать в
+веб. Веб = точные правки. Состояние ревью одно (в SQLite) — действовать
+можно из любого транспорта, последнее слово побеждает.
+
+## Крайние сценарии
+
+- **База неоднозначна** → выбор кандидата (часто чинит всё разом: пиннит
+  provider-id и каноническое имя).
+- **База пустая (рус/аниме)** → «без базы» или ручной id/url. Аниме с
+  абсолютной нумерацией → веб-хелпер «absolute → S·E» (см.
+  [drafts/ideas.md](../drafts/ideas.md)).
+- **Не тот тип (movie↔series)** → переключатель пересобирает форму плана.
+- **Мусор (sample/extra/дубли дорожек)** → роль «игнор».
+- **Полный провал** (LLM ничего не вытащил) → веб-«ручной режим»: выбрать
+  тип, ввести название/год, разложить файлы руками; в Telegram — сразу
+  эскалация в веб.
+
+## Вход в ревью и откат
+
+- Переход в `review` **пингует** (сообщение в Telegram / бейдж в вебе) —
+  пользователя зовут, а не он опрашивает. Таймера нет, источник
+  продолжает сидировать.
+- После «Применить» показываем, что создано. **Undo** — убрать созданные
+  хардлинки одной кнопкой (источник цел); страховка от ошибочного
+  подтверждения.
+
+## Объём по версиям
+
+- **Ф3 (первая версия):** подсказка + перераспознавание; из ручного —
+  переключатель типа, выбор кандидата базы, пометка файла «игнор». Undo —
+  есть.
+- **Ф5:** полный редактор маппинга «файл → серия», ручной режим,
+  подтверждение в Telegram с reply-подсказкой и эскалацией в веб.