закрыта задача tvdb-title-locale

- вопрос о неподтверждённой форме ответа TVDB вынесен разведкой tvdb-search-response-live-check: закрытие задачи стёрло бы его вместе с файлом
2026-08-07 15:17:29 +03:00
parent fdbc781197
commit 1d375f55ba
4 changed files with 73 additions and 64 deletions
@@ -0,0 +1,72 @@
+# 🔬 Форма ответа поиска 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` у второй записи подтверждает форму;
+совпадение означает, что перевод не доехал.
+
+Автоматическим прогоном разведка не делается: лимиты ключа беречь, в гейт этот
+тест не заводить. Кода менять не требуется — исход разведки это запись; правка
+разбора, если форма окажется иной, заводится отдельной задачей.