g2s-aggregator/spec/tasks/024_add_tomtom_address_suggestion_adapter.md

id, title, status, created

id	title	status	created
024	Add TomTom address suggestion adapter and Europe routing	DONE	2026-03-29

Context

Текущий flow подсказок адреса поддерживает dadata для RU, BY, KZ и yandex_geosuggest для части стран СНГ. Следующий этап требует добавить третий provider TomTom для европейских стран, сохранив текущий публичный API и routing через YAML-конфиг.

Goal

Добавить новый adapter tomtom для address suggestions на базе TomTom Search API Fuzzy Search, настроить routing европейских стран на provider id tomtom через конфиг и покрыть это config, adapter и service tests без изменения публичного API endpoint.

Constraints

• Scope задачи ограничен flow подсказок адреса: YAML-конфиг, wiring зависимостей, service routing, новый adapter и тесты.
• Controller path и публичный контракт POST /api/v1/delivery/suggest-address не изменять.
• Service остаётся orchestration layer: выбирает provider по injected config mapping и вызывает ровно один adapter без provider-specific HTTP-логики.
• Внешний IO должен оставаться только внутри нового adapter app/adapters/address_suggestions/tomtom/.
• Новый adapter должен следовать официальному HTTP-контракту TomTom Search API Fuzzy Search: GET https://api.tomtom.com/search/2/search/{query}.json.
• TomTom adapter должен формировать query из request.city и request.query, передавать countrySet=request.country_code, typeahead=true, а request.limit при наличии маппить в query-параметр limit.
• Для исключения POI из address suggestion flow adapter должен отправлять address-oriented idxSet=PAD,Addr,Str,EPP.
• Routing европейских стран должен определяться только YAML-маппингом country_code -> provider_id; запрещено добавлять в Service hardcoded классификацию Европы.
• Unified mapping наружу должен возвращать только AddressSuggestion без утечки provider-specific payload.
• Для TomTom Search поля должны маппиться детерминированно: address.freeformAddress -> address, address.streetName -> street, address.streetNumber -> house, address.postalCode -> postal_code, flat=None.
• Ошибки TomTom 400 должны маппиться в deterministic provider request error; 403, 429, transport errors и 5xx должны маппиться в adapter client error/unavailable path.
• Scope задачи не включает изменение order flow, price flow, новых endpoint'ов, расширение internal model AddressSuggestion и изменение контрактов существующих adapters dadata и yandex_geosuggest.
• Не изменять файлы в spec/.

Acceptance criteria

• В конфиге address suggestion providers добавлен provider id tomtom с параметрами, необходимыми для вызова TomTom Search API Fuzzy Search.
• Country mapping в конфиге маршрутизирует на tomtom европейские страны, явно перечисленные в YAML, при этом routing для RU, BY, KZ на dadata и для AM, AZ, KG, MD, TJ, TM, UZ на yandex_geosuggest сохраняется без изменений.
• Реализован adapter app/adapters/address_suggestions/tomtom/client.py, который отправляет запрос в TomTom Search API Fuzzy Search по официальному контракту и возвращает list[AddressSuggestion].
• Adapter объединяет request.city и request.query в search query, передаёт countrySet=request.country_code, typeahead=true, idxSet=PAD,Addr,Str,EPP и при наличии request.limit маппит его в limit.
• Поля address, street, house и postal_code детерминированно извлекаются из ответа TomTom (freeformAddress, streetName, streetNumber, postalCode), а flat возвращается как None.
• AggregatorService.suggest_addresses() по country_code выбирает tomtom для европейских стран, явно сопоставленных в YAML-конфиге, и сохраняет существующий routing на dadata и yandex_geosuggest для уже поддержанных стран.
• При ответе TomTom с 400 service flow возвращает deterministic bad-request path, а при 403, 429, 5xx и transport failure — deterministic unavailable path.

Definition of Done

• Добавлена конфигурация tomtom и обновлён country mapping для европейских стран.
• Реализован новый TomTom adapter без утечки HTTP-деталей в Service.
• Обновлён wiring address suggestion providers без изменения публичного endpoint контракта.
• Добавлены tests для config, adapter mapping/error handling и service routing на tomtom с сохранением существующего routing на dadata и yandex_geosuggest.
• Пройдены все команды из раздела Commands.

Tests

• Обновить tests/config/test_config_sections.py для проверки секции tomtom и country mapping, в котором европейские страны маршрутизируются на tomtom, а существующие маппинги RU, BY, KZ -> dadata и AM, AZ, KG, MD, TJ, TM, UZ -> yandex_geosuggest сохраняются.
• Добавить tests/adapters/address_suggestions/tomtom/test_client.py для success case, mapping limit, формирования search query из city и query, передачи typeahead=true и idxSet=PAD,Addr,Str,EPP, возврата flat=None, извлечения address/street/house/postal_code и error scenarios 400, 403, 429, 5xx.
• Обновить tests/services/test_address_suggestions.py для проверки routing на tomtom по европейским странам из YAML-конфига и сохранения routing на dadata и yandex_geosuggest для уже поддержанных стран.
• При необходимости обновить tests/controllers/v1/test_address_suggestions.py только для совместимости существующего endpoint с новым provider routing без изменения публичного API.

Commands

• poetry run pytest tests/config/test_config_sections.py -q
• poetry run pytest tests/adapters/address_suggestions/tomtom/test_client.py -q
• poetry run pytest tests/services/test_address_suggestions.py -q
• poetry run pytest tests/controllers/v1/test_address_suggestions.py -q
• python3 spec/gen_spec_index.py --check