docs: перевод документации на канон av-dev

- Раскладка docs/ приведена к канону 2: заведены passport/architecture/
  database/security/review и research; docs/specs, drafts, backlog, review/
  и BRIEF.md разобраны и удалены, беклог переехал в docs/tasks (34 задачи,
  6 целей, слаги на английский).
- Нарративы specs удалены как дубли openspec-спек после поимённой сверки;
  остаток заведён задачами (редактор маппинга ревью, крайние случаи
  именования), отказ от сущности title промоутнут в ADR.
- Проектные копии агентов и скиллов ревью/пайплайна удалены в пользу
  плагинов av-dev-pm и av-dev-pipeline; в task gate добавлен шаг canon
  вместо er-schema.
This commit is contained in:
av
2026-08-04 09:27:26 +03:00
parent 08bef2cac0
commit 42d5b73a04
128 changed files with 1606 additions and 4889 deletions
@@ -0,0 +1,74 @@
# Согласование канона нумерации серий с провайдером тега
- **Секция:** ядро продукта
- **Зачем:** Косметика/редкость: порядок просмотра ок, но у тайтлов со спорным порядком (Бибоп) Jellyfin подтягивает не те подписи серий, если канон файлов ≠ дефолтный порядок провайдера тега
- **Теги:** goal:complex-releases
Косметика и редкий случай: порядок просмотра не страдает (файлы уже
пронумерованы канонически и лежат по порядку), разъезжаются только подписи серий
в Jellyfin — не то название/описание у части эпизодов. Задевает лишь тайтлы с
исторически спорным порядком, таких мало.
## Проблема
У некоторых сериалов есть несколько *легитимных* порядков серий, и разные
метабазы придерживаются разных. Каноничный пример — «Ковбой Бибоп»: в титрах и
на дисках/IMDb/TVDB порядок «сессий» (Session #1 «Asteroid Blues» … #26), а TMDB
по своей политике нумерует по **самой ранней дате эфира**. Часть серий вышла
раньше на TV Tokyo вразнобой (2, 3, 7–15, 18) — при сортировке по дате они
всплывают вперёд, и диапазон ~1–18 перемешивается. Это не баг одной базы: оба
порядка «правильные», просто разные каноны. У TMDB канон отдаётся отдельной
episode group (тип DVD/production), у TVDB — отдельными order-типами
(Aired/DVD/Absolute).
## Где это бьёт по jellybit (и где нет)
jellybit **не** матчит серии по `(season, episode)` между провайдерами —
описанного класса бага у нас нет. Номер эпизода рождается из имён файлов через
LLM (`recognize.PlanFile.Episode`), проходит без изменений в раскладку и
печатается в `SxxEyy`; метабаза даёт лишь `SeasonEpisodeCounts` для гейта
полноты пака. То есть мы **доверяем нумерации релиз-группы** и про порядок вообще
не знаем.
Настоящий риск — тихий и уже существует:
> jellybit пишет `SxxEyy` **и** тег папки `[tmdbid-…]`/`[tvdbid-…]`. Дальше
> Jellyfin по этому тегу заново скрейпит серии у *того же* провайдера. Номер в
> имени файла и порядок, который ждёт скрейпер, обязаны быть **из одного
> канона** — иначе метаданные разъедутся на именно тех сериях.
Для Бибопа: релиз почти всегда пронумерован канонически (session order). Если
матч ушёл на TVDB и написан `[tvdbid-…]` — Jellyfin скрейпит aired order TVDB,
для Бибопа = канон, всё сходится. Если матч ушёл на **TMDB** и написан
`[tmdbid-…]` — Jellyfin ждёт airing order TMDB (перемешанные 1–18), а файлы
канонические → метаданные поедут. Инвариант «канон нумерации файлов ↔ провайдер
тега» сейчас нигде не проверяется.
## Что можно сделать (варианты, не решение)
- **Минимум (дёшево, ценно):** осознать инвариант и эскалировать в review, когда
у распознанного тайтла провайдер матча — из тех, где порядок известно спорный
(episode groups у TMDB, absolute order у TVDB), а нумерация файлов может не
совпадать с дефолтным скрейп-порядком этого провайдера. Лучше явный вопрос
человеку, чем тихий разъезд.
- **Предпочтение провайдера тега:** для сериалов с известным расхождением тегать
папку провайдером, чей дефолтный порядок совпадает с каноном файлов (обычно
TVDB), даже если матч найден в TMDB.
- **Максимум:** знать про порядок явно — тянуть episode group (TMDB) / order-тип
(TVDB) и сверять нумерацию файлов с выбранным каноном. Требует, чтобы у нас
появилось понятие «канон эпизода», которого сейчас в модели нет (эпизодов как
сущностей в БД нет, план — JSON-блоб).
## Связи
- Тот же класс «у тайтла несколько легитимных порядков», что и
[Аниме с абсолютной нумерацией](anime-absolute-numbering.md) (absolute
order через TVDB) — стоит проработать совместно, возможно как одну тему.
- [Сложные сериальные раздачи](complex-series-releases.md) — соседний пласт
крайних случаев раскладки.
- Схема «локальная сущность каноническая, provider id — опциональный внешний
ключ» уже заложена (draft `logical-title-model.md`, сущность `title` осознанно
отвергнута) — эту же логику надо дотянуть до эпизодов/порядка, если пойдём в
«максимум».
- specs/recognition.md (гейт полноты пака, крайние случаи), specs/jellyfin-layout.md
(нумерация серий, тег провайдера), specs/review-ux.md (эскалация в review).