Career Quest — ИИ-навигатор развития сотрудника

Кейс 1 Halyk Bank, HackAlem AI · команда JassAI.

Локальное веб-приложение: HR загружает данные и создаёт доступ; сотрудник выбирает карьерную цель, получает рекомендации, проходит активности и видит прогресс. 3D-спутник — снежный барс — связывает навыки с личными квестами и заработанными предметами.

Устройство и технологии

Браузер: интерфейс + Three.js → FastAPI → правила развития → SQLite
                                      → AI-провайдер → проверка ответа
launcher.cmd → uv + Python → scripts/launcher.py → локальный сервер

Часть	Содержимое
app/	Python 3.12.14, FastAPI, Pydantic, Uvicorn; авторизация HR/employee, импорт, расчёты навыков и активности
app/ai/, app/companion_chat.py	OpenAI Responses API через httpx; рекомендации и потоковый чат. Чат также поддерживает NVIDIA при ручной настройке сервера
app/gamification.py, app/companion.py	XP, квесты, гардероб и древо навыков; состояние сохраняется в SQLite
frontend/	HTML/CSS, JavaScript ES modules, Three.js 0.170.0; без сборки Node.js и CDN
assets/snow_leopard/	GLB, Blender-исходник и две циклические анимации: дыхание 5 секунд и оглядывание 8 секунд
scripts/, tests/, uv.lock	Launcher, проверки, pytest и Node test runner, закреплённые Python-зависимости

Навыки рассчитывает сервер по оценке и завершённым активностям. AI выбирает 1–3 допустимых шага и минимум три разных фактора объяснения; обязательные и недоступные мероприятия исключены. Ответ проверяется сервером и не изменяет данные. Простые объяснения спутника формируются локально и не выдаются за LLM.

Запуск

Windows 10/11 x64, браузер и интернет для первой установки. Python, Git, Node.js, Blender и права администратора для обычного запуска не нужны. Для 3D требуется WebGL; при его отсутствии текстовые функции доступны.

1. На GitHub выбрать main → Code → Download ZIP и полностью распаковать архив. Перед запуском новой копии остановить старую через Ctrl+C в её launcher.
2. Дважды нажать launcher.cmd. Он загрузит закреплённые uv/Python, проверит SHA-256 uv, установит зависимости и откроет приложение на 127.0.0.1 со свободным портом.
3. Подключение OpenAI можно пропустить. Для облачных рекомендаций и свободного чата настройка выполняется в launcher; ключ хранится через Windows DPAPI. Без настройки работают каталог, прогнозы, локальные ответы и награды.
4. Создать первый аккаунт HR с собственным логином и паролем от 10 символов. Одноразовый токен launcher передаёт автоматически.
5. На пустой базе автоматически загрузится starter-data/: 200 сотрудников, 60 навыков, 32 профиля роли/грейда, 40 мероприятий и 2 743 записи истории. Все люди и компании вымышлены. Существующие данные не перезаписываются.
6. В «Сотрудники» → «Создать доступ» выбрать E0001, задать логин и пароль. Выйти из HR и войти этим логином; раздел «Спутник» доступен сотруднику. ID профиля не является логином.

Окно launcher оставить открытым; Ctrl+C останавливает сервер. Закрытие вкладки его не останавливает. При повторном запуске аккаунты, прогресс и экипировка сохраняются.

Данные и логи: %LOCALAPPDATA%\CareerQuest\instances\hack-9be09345-jassai\. SQLite находится в careerquest.sqlite3, диагностика — в logs/launcher.log и logs/server.stderr.log. При ошибке установки проверить доступ к GitHub/PyPI и повторить запуск.

Параметры: launcher.cmd /configure-ai — настройка OpenAI после остановки сервера; /disable-ai — удаление AI-настроек; /help — справка. Переменные ручного запуска описаны в .env.example; .env автоматически не читается. NVIDIA через launcher не подключается.

Основной сценарий

1. HR видит частые дефициты навыков, сотрудников без следующего шага и участие в активностях; создаёт доступ сотруднику. Дополнительные данные загружаются через «Импорт данных» → «Проверить файлы» → «Применить изменения»; проверка сама по себе ничего не записывает.
2. Сотрудник открывает «Мой путь», выбирает цель, изучает дефициты навыков и прогноз активности. При настроенном OpenAI запрашивает объяснимую рекомендацию.
3. В «Спутник» смотрит древо навыков, задаёт вопрос и по желанию нажимает «Включить награды», затем выбирает личный квест.
4. В «Активности» начинает доступное мероприятие; в «История» нажимает «Отметить выполнение». Навыки, покрытие цели и награды пересчитываются.
5. В «Гардероб» примеряет и явно надевает открытый предмет. Обновление страницы и перезапуск сохраняют результат. Кнопки «Оглянуться» и «Пауза» управляют анимацией барса.

Награды выключены по умолчанию и видны только сотруднику. Импорт, обязательные активности и повторное завершение XP не дают. Закрытую вещь можно примерить, но нельзя надеть. Покрытие требований не означает повышение грейда; завершение в прототипе подтверждает сотрудник, внешняя LMS не подключена.

Воспроизведение результата

Для точного сценария на малом наборе остановить приложение и выполнить в PowerShell из корня проекта:

$env:CAREERQUEST_DATA_DIR = Join-Path $env:LOCALAPPDATA ('CareerQuest\demo-check-' + [guid]::NewGuid().ToString('N'))
$env:CAREERQUEST_SEED_DATA_DIR = 'off'
.\launcher.cmd

Это отдельная пустая база. Создать HR, импортировать из demo/ employees.json, events.json, skills.json, activity_history.csv и создать доступ для DEMO_E001. Войти его логином. Дата расчётов — 2026-10-01 из данных, независимо от часов компьютера.

1. Проверить цель Инженер → Senior: «Проектирование сервисов» — уровень 2, покрытие 55,6%.
2. В «Спутник» → «Включить награды» выбрать личный квест «Практика проектирования сервисов (демо)», DEMO_EV_DESIGN, и нажать «Выбрать».
3. Начать эту активность и отметить выполнение. Результат: навык 2 → 4, покрытие 55,6% → 77,8% (API: 55,56% → 77,78%), +40 XP, завершённый квест.
4. Проверить три новых предмета: кепка первого шага, блокнот открытий, шапка личного квеста. Надеть предмет, обновить страницу и проверить сохранение.

Для проверки перезапуска повторить только .\launcher.cmd в том же окне: повтор всего блока создаст ещё одну пустую базу. После завершения закрыть это окно PowerShell; обычный запуск продолжит использовать основной каталог данных.

Автоматические проверки

.\launcher.cmd /check

/check проверяет установку, готовность сервера, выдачу HTML/JavaScript и ресурса GLB, затем останавливает созданный проверочный сервер. Это не проверка всего пользовательского интерфейса; браузер и AI-запросы не запускаются.

Для полного набора нужны uv в PATH и Node.js. Из корня проекта:

uv sync --locked
uv run pytest -q
node --test tests/*.test.mjs
uv run python scripts/check_dataset.py starter-data
uv run python scripts/check_dataset.py demo

Результат: 225 Python-тестов и 93 теста JavaScript прошли. Проверяются импорт и сохранение данных, роли/CSRF, расчёты, повторные завершения, приватность наград, экипировка и контракты AI. AI-транспорт в автоматических тестах заменён синтетическими ответами; платные API не вызываются. check_dataset.py использует временную БД и проверяет импорт, дополнительный профиль, завершение, права и перезапуск.

На Windows проверены запуск из ZIP, стартовый набор, повторный /check с UV_OFFLINE=1; в браузере — сценарий +40 XP, сохранение одежды, обе анимации и экран 390 px. Это проверка на рабочем ПК, не отдельной чистой виртуальной машине. Автоматические тесты не оценивают качество и задержку живых моделей; без облачного подключения свободный AI-диалог недоступен, локальные объяснения остаются.