Поиск пользователей по ФИО

📡 Поиск пользователей по ФИО (fuzzy match)#

Ручка#

POST /search_by_fio

Полный адрес в сети#

Среда	URL
🧪 Dev	`https://terra-searcher-service.club.terra/search_by_fio`
🚀 Prod	`http://terra-searcher-service.prodterra.ru/srv/terra-searcher/search_by_fio`

🔐 Авторизация#

Ручка защищена BasicAuth

Authorization: Basic base64(username:password)

Пример:

Authorization: Basic dXNlcm5hbWUxOnBhc3N3b3JkMQ==

📥 Входные данные#

Основной запрос#

Поле	Тип	Описание	Обязательное	По умолчанию	Пример
searchName	string	Строка для поиска (ФИО / транслит / шум)	✅	—	`ivan ivanov`
userUuids	array[string]	UUID пользователей для ограничения поиска	❌	`null`	см. ниже
page	int	Страница	❌	`1`	`1`
limit	int	Кол-во результатов в ответе	❌	`20`	`20`

Фильтр userUuids

Если передан непустой массив userUuids, поиск выполняется только среди указанных пользователей. Если поле не передано, null или пустой массив — поиск выполняется по всем пользователям.

📤 Пример JSON запроса#

{
  "searchName": "ivan ivanov",
  "userUuids": [
    "22222222-2222-2222-2222-222222222222",
    "33333333-3333-3333-3333-333333333333"
  ],
  "page": 1,
  "limit": 20
}

📤 Выходные данные#

Поле	Тип	Описание	Обязательное	Пример
page	int	Страница из запроса	✅	`1`
limit	int	Лимит из запроса	✅	`20`
total	int	Общее число найденных кандидатов	✅	`134`
matches	array	Список найденных совпадений (страница)	✅	см. ниже

Элемент matches#

Поле	Тип	Описание	Обязательное	Пример
uuid	string	UUID пользователя	✅	`2222...`
fullName	string	Полное имя кандидата	✅	`Ivan Ivanov`
score	float	Скор похожести (0..1)	✅	`0.9821`

📤 Пример ответа#

{
  "page": 1,
  "limit": 20,
  "total": 134,
  "matches": [
    {
      "uuid": "22222222-2222-2222-2222-222222222222",
      "fullName": "Ivan Ivanov",
      "score": 0.9821
    },
    {
      "uuid": "33333333-3333-3333-3333-333333333333",
      "fullName": "Иван Иваненко",
      "score": 0.8114
    }
  ]
}

📌 Особенности работы алгоритма#

Алгоритм поиска

Нормализация (lowercase, очистка)
Замена никнеймов (Саша → Александр)
RapidFuzz предварительный отбор
Embedding reranking (семантическая близость)
Финальный скоринг

🚀 Производственные ограничения#

Warning

candidateLimit ограничивает нагрузку CPU
embeddings считаются только на top-K
сервис stateless (не хранит данные пользователей)

📈 Рекомендации по использованию#

candidateLimit = 50–200 для production
limit = 5–20 для UI
использовать кэш на уровне клиента при повторных запросах