1. Назначение
«Кадровый резерв» является серверным программным сервисом для поиска, фильтрации и ранжирования кандидатов.
Собственный пользовательский интерфейс не требуется. Управление функциями осуществляется внешними системами через HTTP API с передачей данных в формате JSON.
2. Общие правила работы с API
Базовый адрес API определяется при развертывании в инфраструктуре заказчика.
Все тела запросов и ответов передаются в формате JSON в кодировке UTF-8.
Для запросов с телом необходимо указывать заголовок:
Content-Type: application/json
Типовые коды ответов:
- 200 — запрос выполнен успешно;
- 400 — переданы некорректные входные данные;
- 404 — запрашиваемый объект не найден;
- 500 — внутренняя ошибка приложения.
3. Проверка готовности
Перед началом работы необходимо убедиться, что сервис доступен.
Пример:
curl -s http://localhost:8080/healthz
Ожидаемый ответ:
ok
4. Получение справочников
Допустимые значения структурированных фильтров предоставляются API системы.
Пример получения всех справочников:
curl -s http://localhost:8080/dictionaries
Справочники могут включать:
- уровни образования;
- уровни опыта;
- языки;
- уровни владения языками;
- категории тегов.
При формировании фильтров рекомендуется использовать только значения, полученные из справочников системы.
5. Загрузка кандидата
Для добавления или полного замещения профиля используется API создания кандидата.
Пример:
curl -s -X POST http://localhost:8080/candidates \
-H 'Content-Type: application/json' \
-d '{
"external_id": "demo-candidate-1",
"position_title": "Системный администратор",
"key_skills": "Linux, Windows Server, Active Directory, TCP/IP",
"age_years": 34,
"education_level": "higher",
"experience_months": 120
}'
Поле external_id используется как внешний уникальный идентификатор кандидата.
При повторной передаче профиля с тем же идентификатором данные кандидата замещаются актуальными значениями.
6. Прикрепление исходного резюме
К существующему кандидату может быть прикреплен произвольный JSON-объект исходного резюме.
Пример:
curl -s -X PUT http://localhost:8080/candidates/demo-candidate-1/resume \
-H 'Content-Type: application/json' \
-d '{
"resume_object": {
"source": "external_system",
"raw": {}
}
}'
7. Получение карточки кандидата
Для получения сохраненного профиля используется внешний идентификатор кандидата.
Пример:
curl -s http://localhost:8080/candidates/demo-candidate-1
Ответ содержит структурированный профиль и, при наличии, сохраненный JSON исходного резюме.
8. Поиск и ранжирование
Основной поисковый запрос передается в свободной текстовой форме.
Пример:
curl -s -X POST http://localhost:8080/search \
-H 'Content-Type: application/json' \
-d '{
"query_text": "системный администратор Linux Windows сети инфраструктура",
"limit": 5
}'
Система выполняет полнотекстовый поиск, рассчитывает релевантность и возвращает ранжированный список кандидатов.
9. Ограничение области поиска
Поиск может быть ограничен группой кандидатов, связанной с конкретной вакансией, работодателем или другим тегом.
Пример:
curl -s -X POST http://localhost:8080/search \
-H 'Content-Type: application/json' \
-d '{
"query_text": "руководитель отдела продаж B2B управление командой",
"tag_category_id": 2,
"tag_value": "example-vacancy-id",
"limit": 10
}'
10. Использование структурированных фильтров
К текстовому запросу могут добавляться фильтры.
Пример:
curl -s -X POST http://localhost:8080/search \
-H 'Content-Type: application/json' \
-d '{
"query_text": "руководитель отдела продаж B2B",
"age_years_from": 30,
"age_years_to": 50,
"experience_level": "moreThan6",
"education_level": "higher",
"language": {
"name": "eng",
"level": "b2"
},
"limit": 10
}'
Правила обработки отсутствующих у кандидата значений определяются конфигурацией программного обеспечения.
11. Результат поиска
Ответ содержит массив результатов.
Пример структуры:
{
"results": [
{
"external_id": "demo-candidate-1",
"position_title": "Системный администратор",
"score": 35.0,
"normalized_score": 1.0,
"best_rang": 3,
"filter_score": 0.75
}
]
}
Основные показатели:
- score — внутренняя оценка текстовой релевантности;
- normalized_score — нормализованная оценка релевантности;
- best_rang — количество текстовых представлений кандидата, соответствующих запросу;
- filter_score — доля пройденных заданных структурированных критериев.
Дополнительно в ответе могут присутствовать признаки прохождения каждого заданного фильтра.
12. Нормализация оценки
В зависимости от конфигурации система может использовать дополнительную нормализацию поисковой оценки относительно подготовленных эталонных результатов.
Эта функция позволяет приводить внутренние поисковые оценки к единой шкале для последующего использования внешними информационными системами.
13. Типовой сценарий эксплуатации
- Проверить доступность сервиса.
- Получить актуальные справочники.
- Передать или обновить профили кандидатов.
- При необходимости прикрепить исходные данные резюме.
- Передать текст поискового запроса.
- Добавить необходимые структурированные фильтры.
- Получить ранжированный список кандидатов.
- По идентификатору запросить полную карточку выбранного кандидата.
14. Завершение работы
Программное обеспечение является серверным сервисом и работает непрерывно.
При необходимости штатной остановки используются средства управления контейнерами, описанные в инструкции по установке.
15. Диагностика
Если API недоступен, рекомендуется:
- проверить состояние контейнеров;
- проверить доступность PostgreSQL;
- проверить служебный метод состояния;
- просмотреть журналы API-сервиса;
- при необходимости перезапустить сервисы.
Пример просмотра журналов:
docker compose logs