QALDY AI — Career Quest

Что решает

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

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

Технологии

• Web: Next.js, React, TypeScript; Node.js 22.x.
• API и расчёт рекомендаций: Python 3.12+, FastAPI; SQLite для импортов и завершений.
• AI: OpenAI-compatible Responses API, структурированный ответ и проверка допустимых кандидатов; детерминированный fallback.
• Проверки: pytest, Vitest/Testing Library, Playwright, ESLint, TypeScript; Docker Compose для совместного запуска.

JTBD

Сотрудник

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

HR и команда развития

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

Как запустить

Требуются Docker Desktop (или Docker Engine) и Docker Compose v2.

Из корня чистого checkout:

git clone https://github.com/BAITC-Hacks/hack-efa741b1-qaldy-ai.git
cd hack-efa741b1-qaldy-ai
docker compose up --build

На Windows без Docker установите Python 3.12+ и Node.js 22.x. Из корня checkout подготовьте зависимости и запустите приложение:

Push-Location .\apps\api
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
Pop-Location
Push-Location .\apps\web
npm ci
Pop-Location
powershell -ExecutionPolicy Bypass -File .\start-local.ps1

Скрипт запускает оба сервиса в фоне и открывает http://localhost:3000. Он требует уже подготовленных зависимостей и Node.js по стандартному пути C:\Program Files\nodejs\node.exe. При первом запуске создаётся demo HR-токен; для входа сотрудника настройте DEMO_EMPLOYEE_TOKENS по инструкции. Логи находятся в %TEMP%\qaldy-career-quest-local. Если порт 8000 занят несовместимым API, скрипт сообщает об этом и не останавливает чужой процесс.

Для чистого checkout Compose использует только локальные demo-токены: local-demo-employee-token-2026 для сотрудника E0001 и local-demo-hr-token-2026 для HR. Их можно заменить секретными значениями в .env через .\scripts\setup-demo-auth.ps1. Откройте главную страницу, введите нужный токен через меню профиля, затем используйте траекторию, HR-обзор, импорт или схему API. Без настройки LLM рекомендации рассчитываются детерминированно.

Для этого чистого Compose-демо не требуется копировать .env.example: его DEMO_EMPLOYEE_TOKENS={} переопределит встроенный employee-доступ. Если используете собственный .env, настройте HR-токен через setup-demo-auth.ps1 и отдельно задайте соответствие ID → токен в DEMO_EMPLOYEE_TOKENS по SETUP.

Последовательность показа обязательного сценария и импорта профиля жюри приведена в JURY_DEMO.md.

Короткий показ: войдите employee-токеном → откройте /journey → покажите роль, грейд, навыки, историю и причины рекомендации → завершите доступную добровольную активность → проверьте изменение навыков и траектории → смените токен на HR → откройте /hr. HR может просматривать и импортировать данные, но не завершать активность от имени сотрудника.

Стартовый набор содержит 200 синтетических профилей, 40 активностей, 60 навыков и 2 743 записи истории. Схемы описаны в README датасета.

Чтобы остановить сервисы, выполните docker compose down. Именованный Docker volume career_quest_runtime хранит runtime-БД с завершениями активностей и импортированными профилями/историей.

Шаги проверки

1. Проверьте доступность API и вход по токену: /health, затем /api/v1/auth/me.
2. Пройдите ручной сценарий выше: профиль → объяснение → завершение → обновлённый прогресс → HR.
3. При включённой модели проверьте recommendation_mode=ai способом из следующего раздела.
4. Выполните автоматизированные команды ниже; сравнивайте результат с текущим commit.

Финальная локальная проверка 23 сентября 2026: web 78/78 PASS, ESLint и TypeScript PASS; backend smoke 11/11 PASS (health, профиль, рекомендации, четыре HR-маршрута и запреты доступа). Это конкретные запуски, а не заявление о прохождении всей матрицы из 100 пользовательских сценариев.

GitHub Actions запускает проверки при каждом push и pull_request:

• API: установка Python-зависимостей разработки и pytest.
• Web: npm ci, ESLint, проверка TypeScript, unit-тесты Vitest и Playwright E2E на production-сборке Next.js.

Для запуска проверок локально используйте Python 3.12+ и Node.js 22.x.

Backend (из корня репозитория):

cd apps/api
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m pytest

Frontend (из корня репозитория):

cd apps/web
npm ci
npm run lint
npm run typecheck
npm test
npm run build
npx playwright install chromium
npm run test:e2e

Playwright E2E запускает production-сервер Next.js и использует web fixtures; это проверка интерфейса, не сквозная проверка с запущенным FastAPI. В CI Chromium устанавливается автоматически.

AI и проверка его режима

Детерминированное ядро проверяет аудиторию, prerequisites, историю, реальные gain/max_level и разрывы до целевого грейда. Необязательный AI меняет порядок допустимых кандидатов в ограниченном диапазоне; фактические объяснения строит проверяемый движок.

Для AI-reranking задайте LLM_ENABLED=true, LLM_API_KEY, LLM_MODEL, LLM_BASE_URL и при необходимости LLM_TIMEOUT_SECONDS в локальном окружении API; перезапустите API с этой конфигурацией. Без ключа или при ошибке модели доступен явно обозначенный детерминированный режим. Секреты не добавляйте в Git.

23 сентября 2026 отдельно подтверждён реальный запрос на изолированных синтетических данных: HTTP 200, завершённый ответ, recommendation_mode=ai, модель gpt-4o-mini-2024-07-18, около 7,02 с, 677 токенов. Это один успешный замер, а не гарантия задержки для всех профилей. Браузерный стенд аудита на порту 3002 работал с отключённой LLM; его демонстрация не доказывает использование модели.

Для проверки своего API в PowerShell задайте EMPLOYEE_TOKEN в окружении текущей сессии, затем выполните:

$apiBase = 'http://localhost:8000'
$authHeaders = @{ Authorization = "Bearer $env:EMPLOYEE_TOKEN" }
$result = Invoke-RestMethod -Method Post -Uri "$apiBase/api/v1/employees/E0001/recommendations" -Headers $authHeaders
$result | Select-Object recommendation_mode, recommendation_notice, recommendations

Токен должен принадлежать E0001 или разрешённому HR; используйте ID из действующего набора данных. Проверяйте recommendation_mode и сообщение API, не называйте fallback ответом модели. Перед внешним вызовом соблюдайте правила хакатона по передаче синтетических данных.

Структура

apps/api/       FastAPI API, доменная логика и тесты
apps/web/       Next.js интерфейс сотрудника и HR
data/seed/      начальный набор JSON/CSV
docs/           настройка, архитектура, API и формат данных

Документация

• Настройка и запуск
• Архитектура
• Контракт API и demo-доступ
• Формат seed-датасета
• Движок рекомендаций
• План разработки и известные пробелы
• Backend API
• Web-приложение
• Передача проекта и сценарий сдачи

Статус и ограничения

• Основной путь сотрудника и HR-аналитика реализован на seed-данных.
• Employee- и HR-доступ определяются серверными demo Bearer-токенами. Это не production identity provider; публичное окружение по умолчанию закрывает demo-auth.
• HR может загрузить employees.json и необязательный activity_history.csv, проверить их через dry-run и применить. Импортированные записи доступны в профилях, рекомендациях и HR-агрегатах; они сохраняются в SQLite.
• Завершения активности и результаты импорта хранятся в SQLite по DATABASE_URL и переживают перезапуск API.
• Веб-страницы дополнительных разделов продукта могут использовать локальные демонстрационные данные; наличие страницы не означает наличие live API.
• Проведён аудит с ручным путём сотрудника, API-проверками и регрессионными тестами. Сводка: 55 PASS / 3 FAIL / 42 BLOCKED — 55% пунктов подтверждено, 45% остаются незакрытыми. Три FAIL относятся к историческим воспроизведениям, не все повторены после изменений; это не перечень трёх доказанных текущих дефектов и не утверждение о готовности на 100%.
• Чистый запуск Docker имеет статус BLOCKED: Docker недоступен в среде аудита. Полный импорт неизвестного профиля через браузер, повторная полная репетиция и все измерения задержки интерфейса остаются неподтверждёнными. Один успешный AI-вызов не закрывает эти проверки. Актуальные границы и порядок сдачи перечислены в HANDOFF.md.

Перед использованием для реальных сотрудников замените demo-авторизацию, перенесите SQLite на production-grade хранилище с резервным копированием и согласуйте обработку персональных данных.