# 🔬 Форма ответа поиска TheTVDB и семантика параметра language

- **Тип:** research
- **Категория:** Ядро продукта
- **Зачем:** форма ответа поиска TheTVDB принята по swagger 4.7.10 и живым прогоном не подтверждена — при иной форме разбор молча уходит в фолбэк, гейт зелёный, локализованное название не работает
- **Теги:** goal:recognition-accuracy, sprint:2026-08-06

Задача `tvdb-title-locale` научила клиент TVDB брать локализованное название из
блока переводов ответа `/search` и заполнять `OriginalTitle` primary name'ом. Но
живым прогоном форма ответа не сверялась: `CLAUDE.md` → «Запреты» запрещает
ходить в боевые метабазы из отладочных прогонов и расходовать лимиты ключа.
Форма взята из публичной документации (swagger TheTVDB v4, версия `4.7.10`) и
записана в [docs/research/tvdb-search-translations.md](../../research/tvdb-search-translations.md)
как **условие, а не замер**.

Разведка нужна потому, что ошибка предположения **не наблюдаема**: разбор уйдёт в
тотальный фолбэк, `Title` станет равен primary name, то есть исход побайтно
совпадёт с поведением до задачи. Гейт зелёный, карточка ревью прежняя, фича не
работает. Единственный след — DEBUG-строка «в выдаче не разобрался ни один блок
переводов».

## Вопрос

Какова реальная форма блока переводов в ответе `/search` TheTVDB v4 — карта
«трёхбуквенный код языка → название» или иная, — и правда ли параметр `language`
этого эндпоинта сужает выдачу по основному языку записи, а не выбирает перевод?

## Куда ляжет ответ

- [docs/research/tvdb-search-translations.md](../../research/tvdb-search-translations.md):
  предположения заменяются наблюдениями с датой прогона, а строка «живым
  прогоном не подтверждено» — результатом. Условие пересмотра там уже записано.
- Решение по трём развилкам, оставшимся от `tvdb-title-locale`:
  1. **Критерий приёмки про параметр языка в запросе.** Задача требовала, чтобы
     запрос поиска содержал параметр языка из `[general].language`. При
     реализации критерий отменён: по документации параметр — фильтр («Restrict
     results to a specific primary language»), и его передача отсекла бы ровно
     иноязычные записи, ради которых задача заводилась. Тест сейчас проверяет
     обратное — что параметра нет. Критерий менял исполнитель, а не приёмщик;
     нужно решение человека: переписать критерий под факт, отвергнуть решение
     или подтвердить семантику прогоном и решить по факту. Рекомендация —
     подтвердить прогоном, затем переписать критерий.
  2. **Форма блока `translations`.** Подтвердить карту и трёхбуквенность ключей
     либо починить разбор под реальную форму.
  3. **Граница авто-раскладки сдвинулась в обе стороны.** Заполнение
     `OriginalTitle` даёт кандидату TVDB два названия вместо одного. Логика
     гейта не менялась, вход изменился: запись, которую отсекал иероглифический
     primary name, теперь может пройти по переводу (review → авто), а две разные
     записи могут совпасть с планом разными названиями (авто → review —
     франшиза с одним русским названием и годами в пределах ±1). Рекомендация —
     принять как есть: движение вниз ведёт к человеку, движение вверх и есть
     польза задачи, и это ровно то, как уже работает TMDB. Альтернатива —
     сравнивать у TVDB только по `OriginalTitle`, но тогда пропадает польза от
     совпадения по переводу.

## Рамки

Оракул уже написан и лежит в репозитории — прогоняется вручную, человеком, под
своим ключом:

```
TVDB_API_KEY=… go test ./internal/metadata/ -run Integration -v
```

Он печатает `Title` и `OriginalTitle` для `Fargo` и для иноязычной записи
`Ne Zha` (movie 131155, primary name `哪吒之魔童降世`, русский перевод «Нэчжа»).
Расхождение `Title` и `OriginalTitle` у второй записи подтверждает форму;
совпадение означает, что перевод не доехал.

Автоматическим прогоном разведка не делается: лимиты ключа беречь, в гейт этот
тест не заводить. Кода менять не требуется — исход разведки это запись; правка
разбора, если форма окажется иной, заводится отдельной задачей.