Career Quest

AI-система персонализированного карьерного развития и HR-аналитики для АО «Народный Банк Казахстана» на официальном синтетическом датасете (200 сотрудников, 40 событий, 60 навыков, 24 мес. истории).

Сервис строит траекторию грейдов, рассчитывает дефицит компетенций (skill gaps), подбирает 1–3 релевантных шага с прозрачным обоснованием на 3+ факторах, мгновенно сдвигает прогресс при завершении активностей и формирует срез для HR.

---

Быстрый запуск (Docker — рекомендуется)

Запуск всего контура (Go Backend + React Frontend) одной командой:

docker compose up --build

• Веб-интерфейс: http://localhost:3000 (или http://localhost:8080)
• REST API: http://localhost:8080/api
• Проверка здоровья (Healthcheck): http://localhost:8080/health

---

Локальный запуск (без Docker)

Требования: Go 1.27+, Node.js 22+, pnpm.

# 1. Сборка фронтенда
cd web
pnpm install --frozen-lockfile
pnpm build
cd ..

# 2. Запуск сервера (раздает API и скомпилированный UI)
go run ./cmd/career-quest

Открыть в браузере: http://localhost:8080.

Переменные окружения перечислены в .env.example. По умолчанию зафиксирована дата среза SNAPSHOT_DATE=2026-10-01 (системное время не используется). Максимум навыка — 5.

---

Сценарий проверки MVP (Для жюри)

1. Профиль сотрудника и траектория:
   • Открыть http://localhost:3000 (по умолчанию загружен E0001, Middle).
   • Отображаются текущие уровни навыков (0–5), требования для перехода на грейд Senior и 1–3 персональные рекомендации.
2. Прозрачное объяснение (Explainable AI):
   • Каждая рекомендация содержит структурированное обоснование: дефицит навыка, критичность для грейда, статус пререквизитов и учет истории посещений.
3. Выполнение активности и мгновенный сдвиг прогресса:
   • Нажать кнопку «Завершить активность» (Complete).
   • Сервер пересчитывает профиль по формуле gain + max_level, навык мгновенно сдвигается, траектория обновляется без перезагрузки.
4. HR-дашборд:
   • Переключить роль на HR (тумблер в интерфейсе или заголовок X-Demo-Role: hr).
   • Отображается срез по 200 сотрудникам: топ дефицитных компетенций, сотрудники без траектории и статистика явки по активностям.

---

Загрузка проверочных данных жюри

Сервис поддерживает динамический импорт новых датасетов без перезапуска:

curl -X POST http://localhost:8080/api/import \
  -F "employees=@data/employees.json" \
  -F "events=@data/events.json" \
  -F "skills=@data/skills.json" \
  -F "history=@data/activity_history.csv"

---

Логика скоринга и решение ловушки жюри

В проверочном профиле жюри сотрудник имеет минимальный балл по Public Speaking (уровень 1 при норме 2), но трижды пропускал тренинги в истории, тогда как для целевого грейда критичен System Design (уровень 2 при норме 4).

Примитивное правило («бери минимальный навык») проваливается. Наш алгоритм:

1. Исключает обязательные (mandatory) мероприятия и проверяет prerequisites.
2. Применяет мультифакторный скоринг: Score = (Gap × Critical_Multiplier) + History_Penalties + Feasibility.
3. Штрафует за пропуски (no_show, dropped) и повышает приоритет критического навыка (вес x2.5), безошибочно рекомендуя System Design.

---

Архитектура

data/*.json + activity_history.csv
  → internal/importer (валидация схемы и связей)
  → internal/store (in-memory потокобезопасное хранилище)
  → internal/progress (расчет уровней с учетом gain и max_level)
  → internal/recommendation (мультифакторный скоринг и фильтрация)
  → internal/explanation (шаблоны RU/KK + Explainable DTO)
  → internal/transport/httpapi (REST API, отклик < 30 мс)
  → web/ (React 19 + TypeScript + Vite + Tailwind CSS)

backend/ сохранен как автономная Python-реализация для проверки данных и алгоритма. Go не вызывает Python и не требует сторонних сервисов.

---

REST API

Метод и путь	Доступ / Роль	Назначение
GET /health	Без ограничений	Проверка здоровья сервиса и размеры датасета
GET /api/v1/employees/{id}/profile	employee	Профиль, уровни, gaps, evidence и рекомендации
POST /api/v1/employees/{id}/complete	employee	Отметка о прохождении активности и пересчет навыка
GET /api/events	employee / hr	Каталог обучающих мероприятий
GET /api/skills	employee / hr	Справочник навыков с названиями
GET /api/v1/hr/analytics	hr	HR-агрегаты: дефициты, явка, вовлеченность
POST /api/import	admin / жюри	Динамическая загрузка файлов датасета (multipart / ZIP)

• Демо-доступ: заголовки X-Demo-Role: employee и X-Employee-ID: E0001, либо X-Demo-Role: hr.
• Язык интерфейса и обоснований: параметр ?locale=ru или ?locale=kk.

---

Тестирование и верификация

Все тесты проходят со 100% успехом:

go test ./...              # Unit-тесты бэкенда (PASS)
go vet ./...               # Статический анализ Go
go build ./...             # Компиляция бинарника
cd web && pnpm test        # Тесты фронтенда

---

Дополнительные материалы

• Интерактивная презентация проекта для защиты: docs/presentation.html
• Руководство по интеграции: docs/integration.md
• Описание исходных данных: data/README.ru.md