Career Quest

Понятный следующий шаг в карьере

Career Quest — веб-приложение для кейса Halyk Bank на HackAlem AI. Сотрудник видит, каких навыков ему не хватает до карьерной цели, какие активности помогут и почему они подходят именно ему. HR видит общие разрывы и может загрузить новые данные для проверки.

1. Что реализовано

• Профиль сотрудника: роль, грейд, стаж, навыки, история и карьерная цель.
• До трёх доступных шагов с четырьмя факторами: цель/грейд, разрывы навыков, история участия и формат.
• Прогноз изменения навыков и покрытия требований для каждого шага.
• Завершение активности с пересчётом прогресса, защитой от повторного начисления и сохранением в SQLite.
• HR-аналитика: разрывы, участие, сотрудники без доступного шага.
• Загрузка дополнительных профилей JSON и истории CSV прямо в HR-экране.
• Каталог активностей, русский, казахский и английский интерфейс.
• Разделение доступа: сотрудник видит свой профиль, HR — всю выборку.

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

2. Как работает решение

Профиль и история → карьерная цель → разрывы → допустимые активности → выбор 1–3 шагов → объяснение → выполнение → обновлённый прогресс.

Сервер отбирает только активности подходящего грейда с выполненными prerequisites и полезным приростом. Учитывается история похожих активностей, включая пропуски, отказы и незавершённые участия. Эти факты не трактуются как оценка личности или мотивации.

LLM выбирает из проверенных кандидатов по совокупности факторов. Все числа и объясняющие факты проверяемы: модель не может придумать событие, изменить уровень навыка или начислить прогресс. При недоступности модели отображается явный режим fallback с причиной; это резервная многофакторная формула, а не ответ LLM.

3. Технологии

Часть	Технологии
Интерфейс	Vue 3, Vite 7, JavaScript, vue-i18n
API и правила	Python 3.11+, FastAPI, Pydantic
Хранение	SQLite, исходные JSON/CSV только для чтения
AI	HTTPX, API chat completions; пример конфигурации OpenAI GPT-4.1 mini
Проверки	pytest, Node test runner, HTTP smoke с реальным сервером

Документация выбранной модели. Модель и провайдер заменяются переменными окружения. Ключ нужен только серверу.

4. Архитектура

frontend/                  Vue: сотрудник, каталог, HR, импорт
    │ /api/*
backend/main.py            FastAPI + права доступа
    ├── data_loader.py     Валидация JSON/CSV
    ├── domain.py          Навыки, цель, разрывы, допустимость
    ├── storage.py         SQLite, импорт, повторяемость запросов
    ├── reporting.py       HR-аналитика
    └── ai/engine.py       Рекомендации и объяснения
            └── provider.py   Проверяемый выбор LLM
shared/contracts.py        Общие формы запросов и ответов
start.py                   Подготовка и запуск одной командой

API описан в docs/API_CONTRACT.md; интерактивная документация после запуска — http://127.0.0.1:8000/docs.

5. Запуск одной командой

Нужны Python 3.11+, Node.js 22.12+ и официальный архив career_quest_dataset.zip. При первом запуске нужен интернет для установки зависимостей.

Из корня клонированного репозитория:

python start.py --dataset "/путь/к/career_quest_dataset.zip"

На Windows можно использовать py start.py; на Linux/macOS — python3 start.py. Если ZIP лежит в корне проекта или в папке Downloads, достаточно:

python start.py

Команда создаёт виртуальное окружение, устанавливает зависимости, готовит локальные данные и токены, проверяет датасет, собирает интерфейс и запускает сервер. Существующие .env, исходные данные и прогресс сохраняются. Частично распакованный набор не перезаписывается автоматически: используйте полный набор в отдельном DATA_DIR.

Откройте http://127.0.0.1:8000. В поле входа вставьте значение HR_TOKEN или EMPLOYEE_TOKEN из созданного локального файла .env — только значение после =. Это токены входа в приложение; API-ключ модели сюда вставлять не нужно. Сотрудник по умолчанию — E0001.

Повторный быстрый запуск после установки:

.\.venv\Scripts\python.exe run.py

Linux/macOS: ./.venv/bin/python run.py. Остановка — Ctrl+C. Режим разработки — run.py --dev.

Включить LLM

Заполните локальный .env и перезапустите приложение:

AI_ENABLED=true
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4.1-mini
LLM_API_KEY=<обычный проектный API-ключ>
LLM_JSON_MODE=true

Административные ключи sk-admin-... не используются. Жюри может использовать собственный проектный ключ: командный ключ публиковать не требуется. Для другого совместимого провайдера измените URL и модель; если он не поддерживает JSON mode, поставьте LLM_JSON_MODE=false.

Без ключа все экраны, импорт и прогресс работают в явно обозначенном резервном режиме. Внешний запрос ограничен общим таймаутом 8 секунд. При ошибке можно повторить запрос: временная ошибка провайдера не сохраняется в кэше навсегда.

Проверка живой модели: .\.venv\Scripts\python.exe scripts\check_ai.py. Успех — mode=llm; при fallback команда возвращает ненулевой код и причину, не печатая ключ.

6. Сценарий проверки для жюри

1. Запустите проект и войдите с HR_TOKEN. Откройте профиль сотрудника, цель, критические разрывы и объяснения карточек.
2. Перейдите в HR-аналитика. В блоке импорта выберите свои дополнительные employees.json и/или activity_history.csv в формате официального набора. Нажмите загрузку. Код и список ID менять не требуется.
3. Для воспроизводимой демонстрации можно взять наши три синтетических профиля из docs/jury_examples. После импорта новый ID доступен в выборе сотрудников сразу.
4. Выберите сотрудника с доступной активностью в самостоятельном формате. Подтвердите фактическое завершение. Навыки, рекомендации и HR-сводка обновятся; двойной клик не должен давать двойной прирост.
5. Проверьте профиль TEST_CQ_003: отсутствие подходящего шага объясняется, выдуманной рекомендации нет.
6. Попробуйте испорченный JSON или CSV с повторяющимся record_id: весь запрос отклоняется, ранее загруженные данные сохраняются.
7. Перезапустите приложение: импортированные профили и прогресс должны сохраниться.
8. Выйдите и войдите с EMPLOYEE_TOKEN: HR-экран и чужие профили недоступны.
9. Если ключ настроен, в карточках должен быть режим llm. При ошибке провайдера показываются fallback и причина. Переключите RU / KK / EN.

Каждый прогноз рассчитан независимо от текущего состояния; прогнозы карточек не складываются. Будущие сессии нельзя отметить завершёнными заранее.

7. Данные и интеграции

Официальный стартовый набор организаторов: 200 сотрудников, 40 активностей, 60 навыков, 32 матрицы требований, 2 743 записи истории. Дата среза — 2026-10-01, она берётся из данных.

Навыки профиля — срез последней оценки. Начисляются только завершения после last_review_date; более ранние достижения не учитываются повторно. Формула прироста: max(текущий, min(5, текущий + gain, max_level)).

Импорт поддерживает новые и существующие профили, историю отдельно или вместе с профилями. Все ссылки на навыки, активности и сотрудников проверяются. Лимит — 5 MiB на файл. Импорт атомарный: при ошибке ни одна его часть не сохраняется. Повторяющиеся ID записей внутри CSV запрещены.

Исходные данные не редактируются. Изменения хранятся в STATE_PATH, по умолчанию .local/career_quest.sqlite3. В LLM отправляются роль, цель, разрывы и сведения о кандидатах; ФИО, employee ID, manager ID и исходные файлы не отправляются.

Официальный ZIP и исходный датасет не включены в текущий main. Жюри использует архив организаторов. В репозитории есть только собственные проверочные примеры. .env, ключи, токены, база состояния и зависимости исключены из Git.

8. Проверки

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe scripts\check_dataset.py
.\.venv\Scripts\python.exe scripts\check_backend.py
npm --prefix frontend test
npm --prefix frontend run build

На Windows полный сценарий интерфейс → настоящий API → SQLite:

$env:DATA_DIR = (Resolve-Path docs).Path
$env:CQ_PYTHON = (Resolve-Path .venv\Scripts\python.exe).Path
npm --prefix frontend run test:live

Последняя проверка объединённой версии: 79 Python-тестов, 41 frontend-тест, production-сборка и сквозной сценарий успешно прошли на Python 3.13 / Node 24.15. Сквозная проверка использовала fallback; HTTP-контракт LLM проверен с тестовым провайдером. Подробнее — docs/VALIDATION.md.

9. Ценность и развитие

Сотрудник получает объяснимый следующий шаг и видит его ожидаемый результат. HR получает проверяемые причины разрывов и случаи, где каталога недостаточно. Следующие шаги развития: банковский SSO, подтверждение прохождения из LMS, интеграция HRIS, оценка качества рекомендаций на экспертной разметке и мониторинг использования.

10. Ограничения

• Настоящий LLM-вызов требует действующего проектного ключа и доступной квоты; на момент финальной проверки такой вызов не подтверждён.
• Demo-токены и один процесс SQLite предназначены для локального MVP, не для промышленной эксплуатации банка.
• Названия из датасета и серверные объяснения сохраняют язык исходных данных; переведена оболочка интерфейса.
• Исторический CSV не содержит точного времени завершения self-paced; используется доступная дата записи.
• Каталог ограничен: для некоторых сотрудников нет доступного полезного шага. Система сообщает об этом.
• Нет банковского SSO/HRIS/LMS, публичных рейтингов и автоматического решения о повышении.
• Полный аудит мобильной вёрстки и нагрузочные испытания не проводились.

11. Развёрнутая версия

Публичного развёртывания нет. Проверка — локально по команде выше. Репозиторий команды: BAITC-Hacks/hack-d92c0861-superai-team.