Поиск школ

📡 Поиск школ (fuzzy match)#

Ручка#

POST /search_by_school

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

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

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

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

Authorization: Basic base64(username:password)

Пример:

Authorization: Basic dXNlcm5hbWUxOnBhc3N3b3JkMQ==

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

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

Поле	Тип	Описание	Обязательное	По умолчанию	Пример
searchName	string	Строка для поиска (название)	✅	—	`школа предприним`
page	int	Страница	❌	`1`	`1`
limit	int	Кол-во результатов в ответе	❌	`20`	`20`

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

{
  "searchName": "школа предприним",
  "page": 1,
  "limit": 20
}

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

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

Элемент matches#

Поле	Тип	Описание	Обязательное	Пример
uuid	string	UUID школы	✅	`2222...`
name	string	Название школы	✅	`Школа предпринимательства`
score	float	Скор похожести (0..1)	✅	`0.9124`

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

{
  "page": 1,
  "limit": 20,
  "total": 12,
  "matches": [
    {
      "uuid": "22222222-2222-2222-2222-222222222222",
      "name": "Школа предпринимательства",
      "score": 0.9124
    },
    {
      "uuid": "33333333-3333-3333-3333-333333333333",
      "name": "Школа предпринимательства для детей",
      "score": 0.7843
    }
  ]
}

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

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

Нормализация (lowercase, очистка)
Предварительный отбор через wh.search_schools (pg_trgm similarity)
RapidFuzz + embedding reranking (семантическая близость)
Финальный скоринг и пагинация

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

Warning

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

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

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