jellybit/tasks/items/tvdb-search-response-live-check.md

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

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

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

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

Вопрос

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

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

• docs/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 у второй записи подтверждает форму; совпадение означает, что перевод не доехал.

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