Документация "Кадровый резерв"
2026-08-12 19:48

Инструкция по эксплуатации программного обеспечения «Кадровый резерв»

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. Типовой сценарий эксплуатации

  1. Проверить доступность сервиса.
  2. Получить актуальные справочники.
  3. Передать или обновить профили кандидатов.
  4. При необходимости прикрепить исходные данные резюме.
  5. Передать текст поискового запроса.
  6. Добавить необходимые структурированные фильтры.
  7. Получить ранжированный список кандидатов.
  8. По идентификатору запросить полную карточку выбранного кандидата.

14. Завершение работы

Программное обеспечение является серверным сервисом и работает непрерывно.
При необходимости штатной остановки используются средства управления контейнерами, описанные в инструкции по установке.

15. Диагностика

Если API недоступен, рекомендуется:
  1. проверить состояние контейнеров;
  2. проверить доступность PostgreSQL;
  3. проверить служебный метод состояния;
  4. просмотреть журналы API-сервиса;
  5. при необходимости перезапустить сервисы.
Пример просмотра журналов:
docker compose logs