Перейти к содержанию

Модуль dadata

Статус

Реализованы подсказки имени покупателя (NameSuggestions) через DaData suggest/fio. Это перенос legacy POST /names (MainController::names, PHP SDK hflabs/dadata). Остальные сервисы DaData (подсказки адресов, стандартизация, геокодирование) не подключены.

Назначение и границы

Модуль dadata — инфраструктурный клиент сервиса подсказок DaData, по аналогии с notifications для провайдеров доставки. Он не знает, кто и зачем запрашивает подсказку.

Модуль владеет:

  • HTTP-взаимодействием с suggestions.dadata.ru;
  • API-ключом DaData.

Модуль не отвечает за:

  • HTTP-интерфейс для покупателя — им владеет storefront (GET /api/v1/users/me/name-suggestions, см. модуль storefront);
  • сохранение имени в профиле — им владеет customer (CustomerProfiles.update, см. модуль customer). Подсказка ничего не проверяет и не нормализует: покупатель может ввести имя, которого нет среди подсказок.

Корневой пакет объявлен модулем Spring Modulith, allowedDependencies = {}: модуль ни от кого не зависит. Пакет dadata.api объявлен named interface api. Собственной схемы БД нет.

Структура

ru.panampizza.monolith.dadata
├── api
│   └── NameSuggestions      публичный контракт подсказок имени
├── DadataProperties         настройки panam.dadata.*
└── DadataClient             реализация на RestClient

Публичный контракт

interface NameSuggestions {
    fun suggest(query: String): List<String>
}

query обрезается по пробелам. На пустой запрос сразу возвращается пустой список без обращения к DaData.

Иначе выполняется POST {baseUrl}suggest/fio с заголовком Authorization: Token <ключ> и телом {"query": ..., "count": 5, "parts": ["NAME"]}, как в legacy: только имя, без фамилии и отчества, 5 подсказок (значение по умолчанию PHP SDK). Из ответа берутся только suggestions[].value; пол и прочие поля data не используются.

Подсказка не критична для сценария: покупатель может просто ввести имя целиком. Поэтому сбой провайдера (сетевая ошибка, таймаут, HTTP-ошибка, неразбираемый ответ — любой RestClientException) не пробрасывается, а даёт пустой список и warn в лог. Это осознанное отличие от legacy, где ошибка DaData превращалась в 500.

Настройки

Префикс panam.dadata:

PANAM_DADATA_API_KEY_SECRET        ключ инлайном (локальная разработка)
PANAM_DADATA_API_KEY_SECRET_FILE   ключ файлом (общие среды и production)
panam.dadata.base-url              по умолчанию https://suggestions.dadata.ru/suggestions/api/4_1/rs/
panam.dadata.timeout               по умолчанию 2s

В отличие от секретов notifications, ключ необязателен. Если не задан ни один источник или файл пустой, подсказки отключены: suggest всегда возвращает пустой список, при старте пишется warn, приложение стартует. Указать оба источника сразу нельзя — это ошибка старта.

Таймаут подключения и чтения задаётся отдельно от общего spring.http.client.read-timeout (60s): подсказка запрашивается при вводе каждого символа, и медленный провайдер не должен надолго держать поток запроса.

Проверка модульности

Модуль входит в ModularityTests и WebModularityTests. DadataClientTests проверяет тело и заголовки запроса через MockRestServiceServer, пустой запрос, отключённый ключ, ошибку провайдера и разрешение ключа из значения или файла.