Career Quest

Карьерный навигатор в виде пиксельной RPG: мобильный кабинет сотрудника (режимы RPG и Classic), где выбирается цель, видны дефициты навыков и…

Рабочий MVP

HackAlem LLM Дашборды Менеджмент Оптимизация

GitHub

Команда «Amanzholov team» 5💬 0 комментариевс 23 сентября 2026 г.

О проекте

Команда: Amanzholov team
Кейс HackAlem.ai: Менеджмент — Halyk Bank · кейс 1
Стадия: Рабочий MVP

Задача кейса: «Career Quest»: AI-навигатор, связывающий навыки сотрудника с шагами развития

Суть

Карьерный навигатор в виде пиксельной RPG: мобильный кабинет сотрудника (режимы RPG и Classic), где выбирается цель, видны дефициты навыков и рекомендованные активности, плюс десктопный HR-кабинет с аналитикой команды.

Как устроено

Сотрудник выбирает целевую должность. Модуль careers/domain/matching сравнивает подтверждённые навыки с требованиями, recommendations подбирает активности по правилам. Если задан LLM_ENDPOINT (OpenAI-совместимый /v1), модель дополнительно ранжирует варианты с тайм-аутом 3 секунды, при недоступности остаётся rule-based подбор. Результат обучения проходит проверку оценщиком, повышение решает HR. Бэкенд модульный (DDD-подобные слои), FastAPI, PostgreSQL, миграции Alembic. Два фронтенда на React поднимаются через Docker Compose.

Ключевые решения

skill gap matching
rule-based рекомендации
опциональное LLM-ранжирование с fallback
верификация компетенций ревьюером
геймификация (RPG-карта уровней)
архитектурные тесты зависимостей

Особенности

Один и тот же набор данных и правила показаны в двух режимах: пиксельная RPG-карта карьеры и классический интерфейс. Бэкенд разбит на модули с тестами архитектурных зависимостей, ruff и mypy. Навык не повышается автоматически: нужна проверка оценщиком. Есть benchmark-results.md и отдельная валидация AI в Docker.

Стек

Python 3.13 · FastAPI · Pydantic · PostgreSQL · SQLAlchemy · asyncpg · Alembic · React · TypeScript · Vite · Tailwind CSS · Motion · Docker Compose · nginx · uv

Модели

OpenAI-совместимый LLM через LLM_ENDPOINT (опционально)

Проект создан за 5 часов на финале хакатона HackAlem.ai (23 сентября 2026, Астана). Код — BAITC-Hacks/hack-6413edd1-amanzholov-team.

README

README.md

Career Quest

Обучение и карьерный рост в стиле пиксельной RPG. Проект команды Amanzholov.

Мы выбрали направление Career Quest — платформа геймификации жизненного цикла сотрудника. Наша идея — сделать обучение похожим на приключение в пиксельной игре: сотрудник выбирает цель, проходит задания и развивает навыки. Мы хотим вернуть то чувство из детства, когда было весело исследовать мир и изучать новое.

В проекте два веб-приложения:

Для сотрудника — мобильный кабинет. Он помогает понять, какие навыки развивать, чему учиться и как двигаться к новой должности.
Для HR — кабинет для работы на компьютере. В нём можно смотреть прогресс сотрудников, их цели, навыки и участие в обучении.

Оба приложения открываются в браузере и работают с общей базой данных.

Как это работает

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

Например, сотрудник хочет перейти с Junior на Junior+. Он видит, какого уровня Python и SQL ему не хватает, и получает подходящее практическое задание.

Скриншоты

Кабинет сотрудника: два режима

В RPG-режиме карьерный путь выглядит как карта уровней. В классическом режиме сотрудник видит цель, прогресс и рекомендации в привычном рабочем интерфейсе. Переключение режима не меняет данные и правила оценки.

RPG — карьерная карта	Classic — цель и обучение

HR-кабинет: развитие команды

HR видит общую картину: сколько сотрудников выбрали цель, каких навыков не хватает и как команда участвует в обучении.

HR-кабинет: показатели развития команды, недостающие навыки и участие в активностях

На скриншотах показаны демонстрационные данные.

Что уже можно делать

Сотрудник	HR
Смотреть профиль и навыки	Искать сотрудников и применять фильтры
Выбирать карьерную цель	Смотреть цели и навыки сотрудников
Получать рекомендации по обучению	Изучать историю обучения и аналитику
Записываться на активности	Следить за прогрессом доступных подразделений
Отправлять навыки и результаты на проверку	Смотреть предварительные рекомендации в профиле
Переключаться между Classic и RPG	Работать с командой в одном кабинете

Ограничение текущей версии: HR-кабинет предназначен для просмотра. Назначение оценщиков, подтверждение результатов и решения о повышении выполняются через API — серверный интерфейс, доступный в Swagger. Простая отправка результата не повышает уровень навыка автоматически.

На чём построен проект

Часть	Технологии	Для чего
Веб-интерфейсы	React, TypeScript, Vite	Экраны сотрудника и HR
Мобильный интерфейс	Tailwind CSS, Motion, Lucide React	Оформление, анимации и иконки
Сервер	Python 3.13, FastAPI, Pydantic	Обработка запросов и проверка данных
База данных	PostgreSQL, SQLAlchemy, asyncpg	Хранение профилей, навыков и истории
Миграции	Alembic	Обновление структуры базы
Запуск	Docker Compose, nginx	Запуск всех частей проекта вместе

Рекомендации работают без AI-ключей: сервер подбирает обучение по цели, навыкам и доступным активностям. При желании можно подключить языковую модель для ранжирования подходящих вариантов. Если она недоступна, подбор продолжает работать по правилам.

Быстрый запуск через Docker

Нужны Git и Docker с Docker Compose v2. На Windows запустите Docker Desktop с Linux-контейнерами. Для start.ps1 нужен PowerShell. Python и Node.js на компьютере для Docker-запуска не нужны. Первая сборка требует интернета для загрузки образов и зависимостей.

1. Скачайте проект

git clone https://github.com/BAITC-Hacks/hack-6413edd1-amanzholov-team.git
cd hack-6413edd1-amanzholov-team

2. Подготовьте настройки

При первом запуске в PowerShell:

if (-not (Test-Path backend/.env)) {
    Copy-Item examples/demo/.env backend/.env
}

Linux/macOS:

if [ ! -f backend/.env ]; then
    cp examples/demo/.env backend/.env
fi

Файл examples/demo/.env включён в репозиторий для локальной демонстрации. Перед запуском замените YOUR_URL_SAFE_PASSWORD в двух строках и YOUR_DEMO_PASSWORD своими паролями в локальном backend/.env. Для собственных настроек используйте backend/.env.example: заполните POSTGRES_PASSWORD, такой же пароль в DATABASE_URL и DEMO_PASSWORD длиной от 12 символов. Для демонстрации включите DEMO_AUTH=true и DEMO_SEED=true.

Если backend/.env уже существует, команды сохранят его. В этом случае пароль для входа берите из его DEMO_PASSWORD, а не из таблицы ниже. backend/.env исключён из Git; локальные пароли не публикуются.

3. Запустите приложение

Из корня репозитория:

docker compose -f backend/compose.yaml up --build -d --wait

В PowerShell также можно выполнить:

./start.ps1

Compose запускает PostgreSQL, применяет миграции, создаёт demo-аккаунты и импортирует frontend/public/data при включённом DEMO_SEED, затем поднимает API и оба интерфейса. Данные сохраняются в Docker volume между перезапусками.

4. Откройте приложение

Сервис	Адрес	Логин для примера	Пароль для примера
HR-кабинет	http://localhost:5173	`hr`	`YOUR_DEMO_PASSWORD`
Кабинет сотрудника	http://localhost:3000	`employee`	`YOUR_DEMO_PASSWORD`
Swagger / API	http://localhost:8000/docs	Авторизация через API	—

Эти логины предназначены для локальной демонстрации. Вместо YOUR_DEMO_PASSWORD используйте значение DEMO_PASSWORD из локального backend/.env для новой базы данных. Seed также создаёт аккаунты reviewer, reviewer2, admin и outsider с тем же паролем для проверки ролей через API. Повторный seed сохраняет существующие аккаунты: изменение DEMO_PASSWORD в файле не меняет пароль уже созданных пользователей.

Для презентации войдите как employee, выберите Classic или RPG, посмотрите навыки и карьерную карту, выберите цель и подходящую активность. Затем откройте HR-кабинет под hr, найдите сотрудника и посмотрите его профиль и прогресс.

Для разработчиков

Структура проекта, настройки, разработка и проверки

Структура проекта

frontend/src/ — HR-кабинет.
frontend/mobile/ — мобильный кабинет сотрудника.
frontend/public/data/ — данные для демонстрации и импорта.
backend/src/career_quest/ — API и бизнес-логика.
backend/migrations/ — миграции базы данных.
backend/tests/ и backend/scripts/ — тесты и скрипты.
backend/docs/ — техническая документация и скриншоты.
examples/demo/.env — пример настроек для запуска.

Настройки окружения

Переменная	Назначение
`POSTGRES_PASSWORD`	Пароль PostgreSQL; для строки подключения используйте буквы, цифры, `_`, `-`
`DATABASE_URL`	Подключение локального Python к БД; Compose подставляет адрес сервиса `db`
`ENVIRONMENT`	`development`, `test` или `production`
`DEMO_AUTH` / `DEMO_SEED`	Демонстрационный вход / создание демонстрационных данных
`DEMO_PASSWORD`	Пароль создаваемых demo-аккаунтов, от 12 символов
`BUSINESS_DATE`	Дата чистого demo: `2026-10-01`; при импорте используется дата набора данных
`LLM_ENDPOINT`	Необязательный адрес AI-сервиса с `/v1`; без него работают рекомендации по правилам
`LLM_TIMEOUT_SECONDS`	Тайм-аут AI, по умолчанию 3 секунды

Для обычного запуска достаточно backend/.env: корневой .env и .env мобильного интерфейса не требуются. Для подключения AI задайте LLM_ENDPOINT с окончанием /v1, LLM_MODEL и при необходимости LLM_API_KEY. Для сервиса на хосте из Docker используйте адрес host.docker.internal. Внешний AI требует HTTPS и ALLOW_EXTERNAL_AI=true.

Разработка и проверки

Для разработки интерфейсов нужен Node.js 24. Сначала запустите приложение через Docker, затем откройте отдельный терминал для нужного интерфейса. Дополнительные порты позволяют работать одновременно с Docker-версией.

HR-кабинет:

cd frontend
npm ci
npm run dev -- --port 5174

Мобильный кабинет, из корня репозитория в другом терминале:

cd frontend/mobile
npm ci
npm run dev -- --host 127.0.0.1 --port 3001

Адреса разработки: http://localhost:5174 и http://localhost:3001. Vite перенаправляет /api на backend по адресу 127.0.0.1:8000.

В каждой из папок интерфейсов доступны:

npm test
npm run lint
npm run build

Для разработки backend нужны Python 3.13 и uv. Из папки backend:

uv sync --locked
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src
uv run pytest

Без TEST_DATABASE_URL PostgreSQL-тесты пропускаются. Полный прогон через scripts/Check.ps1 требует отдельной тестовой PostgreSQL с именем базы, заканчивающимся на _test. Из папки backend в PowerShell:

docker compose --profile test up -d --wait db-test
# Замените YOUR_URL_SAFE_PASSWORD значением POSTGRES_PASSWORD из backend/.env.
$env:TEST_DATABASE_URL = 'postgresql+asyncpg://career_quest:YOUR_URL_SAFE_PASSWORD@localhost:55433/career_quest_test'
./scripts/Check.ps1

Остановка и диагностика

Команды из корня репозитория:

docker compose -f backend/compose.yaml ps
docker compose -f backend/compose.yaml logs --tail=100 api bootstrap
docker compose -f backend/compose.yaml down

down останавливает сервисы и сохраняет данные. Проверка готовности API: http://localhost:8000/health/ready.

Если Docker недоступен, запустите Docker Desktop и дождитесь готовности Engine.
Если занят порт, проверьте 3000, 5173, 8000, 5432 и остановите конфликтующий локальный сервис либо измените проброс порта в Compose.
Если вход не работает, проверьте DEMO_AUTH, DEMO_SEED и пароль, с которым впервые создавались аккаунты.
Существующий volume сохраняет прежний пароль PostgreSQL; изменение .env не меняет пароль в базе автоматически.

Статус и документация

Проект — хакатонный прототип с демонстрационной авторизацией. Production-конфигурация запрещает demo-auth и demo-seed; корпоративный SSO пока не реализован. Для рабочего развёртывания потребуется полноценная авторизация и собственные секреты.

GitHub

BAITC-Hacks/hack-6413edd1-amanzholov-team

Звёзды

⭐ 0

Форки

Язык

Python

Последний push

в прошлом месяце

Коммиты

Авторы

Файлы

200

Ветки

Авторы коммитов

nurasyl301098-alt 11Daurosh 8bgulim 2

История коммитов

2026-09-23 18:00docs: use environment placeholders and keep local credentials privatenurasyl301098-alt
2026-09-23 17:56Improve HR dashboard design and readable team insightsDaurosh
2026-09-23 17:56Remove obsolete project documents and update ignore rulesnurasyl301098-alt
2026-09-23 17:55docs: simplify project overview and show interface screenshotsnurasyl301098-alt
2026-09-23 17:53docs: keep a single root READMEnurasyl301098-alt
2026-09-23 17:51docs: describe Career Quest and add public demo environmentnurasyl301098-alt
2026-09-23 17:44Merge origin/main and preserve employee workspace with HR reportsnurasyl301098-alt
2026-09-23 17:42Integrate web and mobile clients with backend and HR workflowsnurasyl301098-alt

Все коммиты (21)

2026-09-23 17:19Merge remote-tracking branch 'origin/main'Daurosh
2026-09-23 17:17Build HR-only API dashboardDaurosh
2026-09-23 16:55Improve backend API contracts and local AI integrationnurasyl301098-alt
2026-09-23 15:40Add employee, HR and mobile website screenshotsbgulim
2026-09-23 15:39Add Career Quest website design and working employee and HR flowsbgulim
2026-09-23 16:38Merge branch 'main' of https://github.com/BAITC-Hacks/hack-6413edd1-amanzholov-teamDaurosh
2026-09-23 16:32Build local employee navigation shellDaurosh
2026-09-23 16:31Merge remote-tracking branch 'origin/main'nurasyl301098-alt
2026-09-23 16:30Add Career Quest backend with migrations, API and testsnurasyl301098-alt
2026-09-23 15:36Polish local MVP validation and demo flowDaurosh
2026-09-23 15:10Merge remote-tracking branch 'origin/main'Daurosh
2026-09-23 15:05Build local Career Quest frontend MVPDaurosh
2026-09-23 12:14Update READMEnurasyl301098-alt

Структура репозитория (200 файлов)

.env.example
.gitignore
README.md
backend/.dockerignore
backend/.env.example
backend/.gitignore
backend/Dockerfile
backend/alembic.ini
backend/compose.ai.yaml
backend/compose.yaml
backend/docs/architecture.md
backend/docs/assumptions.md
backend/docs/benchmark-results.md
backend/docs/demo.md
backend/docs/docker-ai-validation.md
backend/docs/screenshots/hr-dashboard.png
backend/docs/screenshots/mobile-classic.png
backend/docs/screenshots/mobile-rpg.png
backend/docs/validation.md
backend/migrations/env.py
backend/migrations/script.py.mako
backend/migrations/versions/0001_initial_relational_schema.py
backend/pyproject.toml
backend/scripts/Check.ps1
backend/scripts/Demo.ps1
backend/scripts/benchmark.py
backend/scripts/smoke_ai.py
backend/src/career_quest/__init__.py
backend/src/career_quest/bootstrap.py
backend/src/career_quest/cli.py
backend/src/career_quest/demo.py
backend/src/career_quest/hr_demo.py
backend/src/career_quest/infrastructure/authentication/passwords.py
backend/src/career_quest/infrastructure/database/models.py
backend/src/career_quest/infrastructure/database/uow.py
backend/src/career_quest/infrastructure/observability/rate_limit.py
backend/src/career_quest/infrastructure/settings.py
backend/src/career_quest/main.py
backend/src/career_quest/modules/careers/application/career.py
backend/src/career_quest/modules/careers/application/vacancies.py
backend/src/career_quest/modules/careers/domain/matching.py
backend/src/career_quest/modules/careers/domain/models.py
backend/src/career_quest/modules/careers/presentation/routes.py
backend/src/career_quest/modules/competencies/application/verification.py
backend/src/career_quest/modules/competencies/domain/experience.py
backend/src/career_quest/modules/competencies/domain/models.py
backend/src/career_quest/modules/competencies/presentation/routes.py
backend/src/career_quest/modules/data_import/application/importer.py
backend/src/career_quest/modules/data_import/domain/models.py
backend/src/career_quest/modules/data_import/domain/package.py
backend/src/career_quest/modules/data_import/infrastructure/parser.py
backend/src/career_quest/modules/data_import/presentation/routes.py
backend/src/career_quest/modules/hr/application/analytics.py
backend/src/career_quest/modules/hr/application/dataset.py
backend/src/career_quest/modules/hr/presentation/routes.py
backend/src/career_quest/modules/identity/application/auth.py
backend/src/career_quest/modules/identity/domain/models.py
backend/src/career_quest/modules/identity/presentation/routes.py
backend/src/career_quest/modules/learning/application/activities.py
backend/src/career_quest/modules/learning/domain/models.py
backend/src/career_quest/modules/learning/domain/progression.py
backend/src/career_quest/modules/learning/presentation/routes.py
backend/src/career_quest/modules/people/domain/models.py
backend/src/career_quest/modules/recommendations/application/recommend.py
backend/src/career_quest/modules/recommendations/domain/models.py
backend/src/career_quest/modules/recommendations/infrastructure/llm.py
backend/src/career_quest/modules/recommendations/presentation/routes.py
backend/src/career_quest/shared/application/commands.py
backend/src/career_quest/shared/application/ports.py
backend/src/career_quest/shared/application/security.py
backend/src/career_quest/shared/domain/audit.py
backend/src/career_quest/shared/domain/core.py
backend/src/career_quest/shared/presentation/dependencies.py
backend/src/career_quest/shared/presentation/localization.py
backend/src/career_quest/shared/presentation/schemas.py
backend/src/career_quest/startup.py
backend/tests/api/test_completion_requests.py
backend/tests/api/test_decisions.py
backend/tests/api/test_hr_workspace.py
backend/tests/api/test_journey.py
backend/tests/architecture/test_dependencies.py
backend/tests/conftest.py
backend/tests/integration/test_import.py
backend/tests/integration/test_learning.py
backend/tests/integration/test_repeatability.py
backend/tests/unit/test_domain.py
backend/tests/unit/test_llm.py
backend/tests/unit/test_zip.py
backend/uv.lock
examples/demo/.env
frontend/.dockerignore
frontend/.gitignore
frontend/.oxlintrc.json
frontend/Dockerfile
frontend/index.html
frontend/mobile/.dockerignore
frontend/mobile/.env.example
frontend/mobile/.gitignore
frontend/mobile/Dockerfile
frontend/mobile/index.html
frontend/mobile/metadata.json
frontend/mobile/nginx.conf
frontend/mobile/package-lock.json
frontend/mobile/package.json
frontend/mobile/src/App.tsx
frontend/mobile/src/assets/images/aruzhan_cozy_pixel_avatar_1790163005446.jpg
frontend/mobile/src/assets/images/aruzhan_pixel_avatar_1790162672385.jpg
frontend/mobile/src/assets/images/career_adventurer_portal_1790162657969.jpg
frontend/mobile/src/assets/images/career_quest_guild_crest_1790162684031.jpg
frontend/mobile/src/assets/images/cozy_guild_crest_1790163020661.jpg
frontend/mobile/src/assets/images/stardew_adventurer_portal_1790162988782.jpg
frontend/mobile/src/components/classic/ClassicBottomNav.tsx
frontend/mobile/src/components/classic/ClassicCanvas.tsx
frontend/mobile/src/components/classic/ClassicCareerExplorerScreen.tsx
frontend/mobile/src/components/classic/ClassicCareerPathScreen.tsx
frontend/mobile/src/components/classic/ClassicDevPlanScreen.tsx
frontend/mobile/src/components/classic/ClassicHomeScreen.tsx
frontend/mobile/src/components/classic/ClassicModeSelectScreen.tsx
frontend/mobile/src/components/classic/ClassicRoleDetailsScreen.tsx
frontend/mobile/src/components/classic/ClassicSkillsScreen.tsx
frontend/mobile/src/components/classic/ClassicTopBar.tsx
frontend/mobile/src/components/common/BottomNav.tsx
frontend/mobile/src/components/common/CozyAmbientParticles.tsx
frontend/mobile/src/components/common/ErrorBoundary.tsx
frontend/mobile/src/components/common/MobileTopBar.tsx
frontend/mobile/src/components/common/ModeSelectionScreen.tsx
frontend/mobile/src/components/common/MuteIndicatorOverlay.tsx
frontend/mobile/src/components/common/PixelBadge.tsx
frontend/mobile/src/components/common/PixelButton.tsx
frontend/mobile/src/components/common/PixelCard.tsx
frontend/mobile/src/components/common/ProgressBar.tsx
frontend/mobile/src/components/common/RankNode.tsx
frontend/mobile/src/components/figma/ComponentSpecsDrawer.tsx
frontend/mobile/src/components/figma/FigmaCanvas.tsx
frontend/mobile/src/components/modals/AddSkillModal.tsx
frontend/mobile/src/components/modals/LevelUpModal.tsx
frontend/mobile/src/components/screens/CareerMapScreen.tsx
frontend/mobile/src/components/screens/HomeScreen.tsx
frontend/mobile/src/components/screens/OpenRolesScreen.tsx
frontend/mobile/src/components/screens/RecommendedQuestsScreen.tsx
frontend/mobile/src/components/screens/SkillsLedgerScreen.tsx
frontend/mobile/src/components/screens/SplashScreen.tsx
frontend/mobile/src/data/mockData.ts
frontend/mobile/src/index.css
frontend/mobile/src/main.tsx
frontend/mobile/src/services/api.ts
frontend/mobile/src/services/workspace.ts
frontend/mobile/src/types/career.ts
frontend/mobile/src/utils/audio.ts
frontend/mobile/tests/workspace.test.mjs
frontend/mobile/tsconfig.json
frontend/mobile/vite.config.ts
frontend/nginx.conf
frontend/package-lock.json
frontend/package.json
frontend/public/data/activity_history.csv
frontend/public/data/employees.json
frontend/public/data/events.json
frontend/public/data/skills.json
frontend/public/favicon.svg
frontend/public/icons.svg
frontend/src/App.css
frontend/src/App.tsx
frontend/src/assets/hero.png
frontend/src/assets/react.svg
frontend/src/assets/vite.svg
frontend/src/components/AppLayout.tsx
frontend/src/components/PageHeading.tsx
frontend/src/components/WorkspaceIcon.tsx
frontend/src/context/ApiSessionContext.tsx
frontend/src/context/CareerDataContext.tsx
frontend/src/context/apiSession.ts
frontend/src/context/careerDataStore.ts
frontend/src/context/useApiSession.ts
frontend/src/index.css
frontend/src/main.tsx
frontend/src/pages/ApiPages.tsx
frontend/src/pages/EmployeeOverviewPage.tsx
frontend/src/pages/EmployeeProfilePage.tsx
frontend/src/pages/EmployeeSearchPage.css
frontend/src/pages/EmployeeSearchPage.tsx
frontend/src/pages/HrDashboardPage.tsx
frontend/src/pages/LoginPage.tsx
frontend/src/services/api.ts
frontend/src/services/careerData.ts
frontend/src/services/employeeDirectory.ts
frontend/src/types/career.ts
frontend/tests/careerData.test.mjs
frontend/tests/employeeDirectory.test.mjs
frontend/tsconfig.app.json
frontend/tsconfig.json
frontend/tsconfig.node.json
frontend/vite.config.ts
public/app.js
public/index.html
public/styles.css
server.py
start.ps1
test_server.py
test_ui.py

Ветки (2)

codex/hr-dashboard-visuals main

Обсуждение 0 комментариев

Войдите, чтобы комментировать

Пока нет комментариев — будьте первым.