Career Quest

Краткое описание

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

Основной пользователь — сотрудник со стажем 1–5 лет. HR получает общую картину дефицитов навыков, участия в развитии и потребностей, которые каталог обучения не покрывает.

Основной сценарий: профиль → цель → рекомендация с объяснением → выполнение → сохранённый прогресс и следующий шаг. Ядро проекта — качество и объяснимость рекомендаций; баллы и награды не являются обязательной частью выбранного кейса.

Запуск · Сценарий для жюри · Проверка по ТЗ · Ограничения

Проверка запуска из чистого клона — 23 сентября 2026

Код d4b1670 заново клонирован с GitHub в пустой каталог. Запуск выполнен по инструкции ниже: .env.example → .env, четыре исходных файла организаторов в data/source/, затем docker compose up --build -d. Изменены только свободные порты: APP_PORT=3215, DB_PORT=54339. Созданы новые контейнеры и отдельный пустой volume PostgreSQL; старые node_modules, .next, .env и база не использовались. Команда актуальной редакции docker compose up --build -d --wait также выполнена: оба контейнера готовы, сохранённый volume повторно использован без сброса.

Результат: оба контейнера healthy, /api/health вернул status=ok, dataset_initialized=true, миграцию 003_learning_external_completion. В браузере проверены вход сотрудника, рекомендации, сохранение урока при закрытии/повторном открытии, неверный тест без начисления, успешный тест и сохранение прогресса 55% → 61% после обновления страницы. HR увидел 200 сотрудников и одно новое симулированное завершение. Ошибок консоли в этом проходе не обнаружено. Инструкция запуска воспроизвелась без правок кода.

Проверка выполнена без ключа AI (ai_configured=false, подбор по правилам). Для демонстрации обязательного AI-слоя жюри нужно настроить провайдера по шагу 2; эта проверка запуска не заменяет live AI-аудит и не подтверждает SLA под нагрузкой.

Замечания пяти судей и исправления обучения, изоляции БД и лишних чтений: аудит, техническая проверка.

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

Возможность	Что получает пользователь
Профиль и карьерный путь	Роль, грейд, стаж, навыки, история участия, выбранная или предложенная цель, её требования и критические разрывы
Персональные рекомендации	От одной до трёх допустимых и полезных активностей; при отсутствии шага — конкретная причина
Объяснение выбора	Проверенные факты минимум из трёх категорий: грейд, разрывы навыков, история, требования цели; ожидаемое изменение навыков и покрытия цели
Учёт истории	Завершения, начатые участия, отказы и пропуски, в том числе похожих активностей; нехватка наблюдений явно обозначается
Каталог по навыку	«Найти обучение» открывает подходящие программы с условиями допуска, предварительными требованиями и возможным приростом
Сохранение прогресса	Моделирование выполнения, пересчёт навыков и следующего шага; защита от повторного начисления
Учебная мастерская	Два авторских демомодуля, по три урока и три вопроса; сохранение уроков, серверная проверка теста, повторная попытка
HR-кабинет	Обзор команды, поиск и фильтры сотрудников, просмотр профилей, дефициты компетенций, участие и причины отсутствия рекомендации
Диагностика каталога	Потребности без подходящего обучения, несовпадение аудитории и предел развиваемого уровня
Импорт для жюри	JSON-профили и CSV-история, предварительная проверка по умолчанию, проверка связей и атомарное сохранение
Доступ и хранение	Роли сотрудника и HR, cookie-сессии, PostgreSQL; цели, импорт и учебный прогресс сохраняются между запусками

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

1. Входные данные. При первом запуске сервер проверяет четыре файла датасета, связи между записями и загружает их в PostgreSQL.
2. Профиль и цель. Рассчитываются текущие навыки и разрывы относительно выбранной цели. При отсутствии исходной цели может быть предложен следующий грейд текущей роли; для Lead без цели требуется выбрать направление.
3. Допустимые шаги. Доменная логика проверяет аудиторию, предварительные навыки, расписание, историю и пользу для цели. Обязательные назначения не выдаются как добровольные рекомендации. Подготовительная активность может открывать полезный следующий шаг.
4. AI-выбор и объяснение. Модель ранжирует готовых кандидатов и выбирает идентификаторы проверенных фактов. Сервер проверяет формат ответа, допустимость выбора, минимум три категории оснований и актуальность профиля. Дополнительно обязательны факты истории и трудозатрат, а для подготовительного шага — условия будущей пользы. Порядок не должен нарушать многофакторные приоритеты продукта; неполный или противоречащий им ответ отклоняется целиком. Модель не создаёт курсы и не изменяет навыки.
5. Действие и результат. Сотрудник проходит демомодуль или нажимает «Смоделировать выполнение». Сервер сохраняет результат, пересчитывает профиль и рекомендации. HR видит обновлённые данные.

Прирост задаётся gain активности и ограничен max_level и 5; уже более высокий уровень не снижается. История, уже учтённая в последней оценке навыков, повторно не начисляется.

Покрытие цели: Σ min(текущий уровень, требуемый уровень) / Σ требуемых уровней. Избыток одного навыка не компенсирует другой разрыв. 100% означает соответствие модели требований, а не автоматическое повышение. Рекомендации — альтернативы следующего действия; их эффекты не складываются заранее.

В интерфейсе различаются «AI-подборка» (ai), «Подборка по правилам» (rules_fallback) и отсутствие кандидатов (no_candidates). При сбое модели сохраняется работоспособность подбора по правилам. Для полной проверки обязательного AI-сценария нужен принятый ответ ai.

Технологии

Компонент	Используемые технологии
Язык и среда	TypeScript, Node.js 24, npm workspaces
Интерфейс	Next.js 16, React 19, CSS, Lucide
API	Next.js Route Handlers, Node.js runtime, серверный пакет backend/
База данных	PostgreSQL 18; Compose использует 18.6; схема Drizzle ORM, запросы и транзакции через pg
Валидация и импорт	Zod, csv-parse
AI	OpenAI-совместимый Chat Completions API через fetch, Structured Outputs / JSON Schema; в .env.example настроена gpt-6-luna, для неё адаптер задаёт reasoning_effort: low
Проверки	Vitest, Node.js test runner, React Test Renderer, интеграционные тесты PostgreSQL
Сборка и поставка	Docker, Docker Compose, GitHub Actions

Имя модели и полный URL API задаются в окружении. При замене провайдера необходимо проверить совместимость со строгой JSON Schema. Режим low выбран после сравнительных live-проверок; результаты, включая таймауты и отклонённые ответы, сохранены в аудите AI. Ключ хранится на сервере. Другие внешние сервисы для основного сценария не требуются.

Архитектура проекта

Модульный монолит: один процесс Next.js обслуживает UI и API, отдельный workspace содержит серверную логику, PostgreSQL хранит состояние.

flowchart LR
    User[Сотрудник или HR] --> UI[React / Next.js]
    UI --> API[Route Handlers: сессия и права]
    API --> Services[Сервисы: профиль, импорт, обучение]
    Services --> Domain[Домен: доступность, навыки, цель и факты]
    Services <--> DB[(PostgreSQL)]
    Services --> AI[AI-ранжирование рассчитанных кандидатов]
    AI <--> Provider[Совместимый LLM API]
    AI --> Validation[Проверка ответа или подбор по правилам]
    Validation --> UI

backend/src/
  domain/       расчёт навыков, кандидатов, оснований и HR-аналитики
  ai/           промпт, API-адаптер, проверка ответа и резервный подбор
  services/     цели, рекомендации, выполнение и импорт
  learning/     демоуроки, учебные попытки и проверка тестов
  auth/         сессии и права сотрудника / HR
  db/           схема, миграции, bootstrap и транзакции
  validation/   схемы исходных файлов и проверка связей
  http/         маршрутизация запросов
frontend/       страницы, компоненты и клиент API
contracts/      общие TypeScript-контракты
scripts/        запуск и команды проверки
data/source/    локальный датасет, исключённый из Git
docs/           описание правил и отчёты проверок

Изменение цели и начисление прогресса проверяют версию данных. Симуляция, сохранение импорта и отправка учебного теста дополнительно защищены ключами идемпотентности; повторное завершение урока не дублируется. Для рекомендаций выделен отдельный пул соединений; одновременно выполняются не более трёх подборов на процесс. Успешные AI-ответы кэшируются до 60 секунд с учётом профиля, фактов, версии и конфигурации. Бюджет провайдера ограничен восемью секундами, включая допустимый повтор временного сбоя; это не замер полного времени HTTP-запроса.

Подробнее: backend, доменные правила и API, AI, качество рекомендаций.

Установка и запуск

1. Подготовить проект и датасет

Нужны доступ к репозиторию, Git и работающий Docker с Compose v2+. Для первого запуска нужен интернет для образов и npm-пакетов. Node.js на хосте при Docker-запуске не требуется.

git clone https://github.com/BAITC-Hacks/hack-5abba766-orbit-jr.git
cd hack-5abba766-orbit-jr
cp .env.example .env
mkdir -p data/source

Скопируйте из архива организаторов четыре файла непосредственно в data/source/:

data/source/employees.json
data/source/skills.json
data/source/events.json
data/source/activity_history.csv

Для выданного career_quest_dataset.zip пример в Bash/zsh, если архив лежит в Downloads и установлен unzip:

unzip -j "$HOME/Downloads/career_quest_dataset.zip" \
  'case_1/career_quest_dataset/*.json' \
  'case_1/career_quest_dataset/activity_history.csv' -d data/source

В Windows архив можно распаковать через проводник и скопировать указанные файлы; вместо cp использовать Copy-Item .env.example .env. Исходный набор и .env не публикуются. Без четырёх файлов первый запуск основного приложения завершится ошибкой. Вариант репетиции без архива приведён ниже.

2. Настроить AI для проверки ТЗ

В корневом .env задайте действующий ключ и доступную ему модель:

LLM_API_KEY=ваш_ключ
LLM_MODEL=gpt-6-luna
LLM_API_URL=https://api.openai.com/v1/chat/completions
LLM_TIMEOUT_MS=8000

Не добавляйте ключ в Git. Без ключа можно проверить профиль, HR, обучение и резервный подбор, но это не подтверждает обязательную AI-рекомендацию. ai_configured=true в health означает наличие конфигурации, а успешное подключение подтверждается только ответом mode=ai.

3. Запустить одной командой

После подготовки файлов и .env:

Если порты 3000 или 54329 заняты, заранее измените их в .env, например APP_PORT=3215, DB_PORT=54339, оставив APP_ORIGIN пустым. Тогда приложение и health открываются на http://localhost:3215 и http://localhost:3215/api/health. Остальные команды не меняются.

docker compose up --build -d --wait

Откройте http://localhost:3000. Готовность: http://localhost:3000/api/health, ожидаются data.status="ok" и data.dataset_initialized=true.

docker compose ps
docker compose logs app

Флаг --wait ждёт готовности контейнеров; оба должны иметь статус healthy. Строка .env not found. Continuing without it. внутри контейнера штатная: Compose передаёт настройки через окружение, файл с ключами в образ не копируется.

Запуск применяет миграции и загружает набор один раз. БД сохраняется в именованном Docker volume. Порты по умолчанию: приложение 3000, PostgreSQL 54329; оба привязаны к 127.0.0.1.

Логин	Пароль по умолчанию	Доступ
employee	employee-demo-2026	Собственный профиль, цель и выполнение; привязан к первому по ID сотруднику исходного набора
hr	hr-demo-2026	Аналитика, просмотр профилей и рекомендаций, импорт; без выполнения активностей за сотрудника

Пароли можно задать через DEMO_EMPLOYEE_PASSWORD и DEMO_HR_PASSWORD до первой инициализации. Их последующее изменение в .env не меняет уже созданные аккаунты.

Основные настройки: APP_PORT и DB_PORT задают опубликованные порты Compose; пустой APP_ORIGIN автоматически соответствует http://localhost:${APP_PORT}. При явном origin или внешнем HTTPS укажите правильный адрес вручную. POSTGRES_PASSWORD задаёт пароль БД при её создании. После изменения AI-конфигурации пересоздайте приложение:

docker compose up -d --build --force-recreate --wait app

Обычная остановка docker compose down сохраняет БД. Добавление --volumes удаляет её вместе с прогрессом и импортами. Замена исходных файлов не перезаписывает уже инициализированную БД; новые профили и историю добавляют через HR-импорт.

Разработка без контейнера приложения

Нужны Node.js 24, npm и PostgreSQL. После подготовки .env и датасета:

npm ci
docker compose up -d --wait db
npm run dev

DATABASE_URL из .env должен соответствовать адресу, порту и паролю вашей БД. В локальном URL спецсимволы пароля нужно кодировать; Compose передаёт пароль отдельным полем. npm run dev и npm start выполняют bootstrap автоматически. Порт локального сервера задаётся PORT (по умолчанию 3000), а APP_PORT относится к Compose. При изменении PORT задайте соответствующий APP_ORIGIN, например http://localhost:3100 для порта 3100, иначе сервер отклонит изменяющие запросы.

Для production-версии остановите dev-сервер, затем выполните npm run build и npm start. Не используйте один порт для Docker app и локального сервера и не запускайте сборку одновременно с dev в том же каталоге.

Как проверить решение

Основной сценарий сотрудника

1. На свежем официальном наборе войдите как employee: откроется E0001. Посмотрите роль, грейд, цель, навыки, историю и карьерный путь.
2. В карточке рекомендации раскройте «Что даст обучение». Сопоставьте объяснение с текущими навыками, историей и требованиями цели; проверьте ожидаемый эффект. Для AI-проверки должна отображаться «AI-подборка».
3. Выберите активность с действием «Смоделировать выполнение» — например, Public Speaking Club (EV_036) на свежем наборе. После подтверждения сравните «было → стало», покрытие цели и следующий шаг. Обновите страницу: результат должен сохраниться.
4. Дополнительно откройте учебный модуль через «Открыть уроки». Для свежего E0001 доступен System Design Fundamentals (EV_005), демомодуль «Демо-модуль: запрос, данные и надёжный повтор». Завершите урок, закройте и откройте плеер — прогресс сохраняется. Пройдите три урока, отправьте тест с ошибкой, затем исправьте ответы по материалу. При успешном тесте сохраняется выполнение без повторного начисления.

Для шагов 3 и 4 выбирайте разные ещё не выполненные активности либо показывайте только один способ выполнения. Если БД уже использовалась, набор доступных шагов может отличаться. HR может просмотреть другой профиль, но не пройти активность за него.

Два учебных модуля — Python (EV_012) и System Design (EV_005) — демонстрационные. Уроки и проверка ответов работают, но успешный короткий тест моделирует полный эффект активности из каталога, а не подтверждает освоение всего 24- или 16-часового курса.

HR и проверочные профили жюри

1. Войдите как hr. В «Обзоре команды» проверьте дефициты навыков, участие, сотрудников без следующего шага и ограничения каталога.
2. Откройте «Сотрудники», используйте поиск или фильтры и просмотрите произвольный профиль. Фильтры меняют список сотрудников; общая сводка остаётся по всей компании.
3. В «Импорте данных» выберите JSON-профили и/или CSV-историю в формате датасета. Оставьте включённым установленный по умолчанию флажок «Только проверить файлы, без сохранения», нажмите «Проверить файлы».
4. После успешной проверки снимите флажок, нажмите «Импортировать», найдите новый профиль и проверьте его рекомендации. Изменения кода не нужны.
5. Повторите идентичный импорт: записи пропускаются без дублирования. Изменённая запись с уже занятым ID отклоняет пакет целиком.
6. Перезапустите приложение командой docker compose restart app и убедитесь, что импорт и ранее сохранённый прогресс доступны.

Импорт не создаёт учётные записи. Жюри может проверить подбор нового профиля через HR; самостоятельный вход и выполнение от имени нового сотрудника требуют отдельного создания аккаунта, интерфейс которого пока не реализован.

Репетиция без архива организаторов

После clone и подготовки .env, с Node.js 24 и PostgreSQL:

npm ci
docker compose up -d --wait db
npm run build
npm run demo:prepare
npm run demo:start

Откройте http://localhost:3210. Это отдельная схема БД с авторским профилем и двумя шагами: SQL 1 → 2 → 3, покрытие цели 33% → 67% → 100%. Пароли — из таблицы выше. Повторный demo:start сохраняет результат; новый demo:prepare создаёт новую схему, сохраняя предыдущую. Репетиция намеренно отключает внешний AI и не заменяет AI-проверку ТЗ. Подробный сценарий. Страница /demo — отдельная визуальная витрина на фикстурах, без настоящего цикла с БД.

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

Из корня проекта после npm ci, на Node.js 24:

npm test
npm run typecheck
npm run eval:ai -- --suite=all
npm run build

Для интеграций нужен PostgreSQL. Пример Bash/zsh для стандартного локального подключения:

export TEST_DATABASE_URL=postgresql://career_quest:[email protected]:54329/career_quest
npm run test:integration
npm run verify:ai-flow

В PowerShell используйте $env:TEST_DATABASE_URL="postgresql://career_quest:[email protected]:54329/career_quest". Тесты создают временные схемы и не сбрасывают таблицы основного приложения.

С настроенным провайдером, с расходованием его API:

npm run smoke:ai
npm run eval:ai -- --live --suite=all
npm run verify:ai-flow -- --live

Последняя команда требует TEST_DATABASE_URL и проверяет настоящую цепочку с PostgreSQL и AI на авторских данных. HTTP handlers входят в проверку, браузер и TCP-сервер Next — нет.

Повторная проверка 23 сентября 2026: код d4b1670, включая последние изменения frontend, AI и обработки ожидания БД. 488 backend-тестов, 98 клиентских, 66 PostgreSQL integration прошли; один opt-in live-тест пропущен в обычном наборе и затем проверен отдельным live-запуском 3/3. Docker-сборка и чистый запуск прошли. Новый live-набор: 23/23 принятых AI-ответа, без fallback; это авторская регрессия, не гарантия будущих запросов. Offline evaluation: 23 случая ранжирования и 2 проверки пустого результата. Детали, границы измерений и матрица ТЗ — в отчёте проверки. Исторические live-наборы сохранены в отчёте AI; они не являются результатами на скрытых профилях жюри. CI-конфигурация включена, локальный результат не означает успешный запуск GitHub Actions.

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

Источник	Содержимое официального набора
employees.json	200 профилей, роли, грейды, навыки и карьерные цели
skills.json	60 навыков и 32 профиля требований: 8 ролей × 4 грейда
events.json	40 активностей, аудитория, предварительные требования, gain и max_level
activity_history.csv	2 743 записи участия за 24 месяца, включая пропуски и отказы

Все люди и компании в наборе вымышлены. Дата среза — 2026-10-01; домен использует meta.as_of_date, а не дату компьютера. Фактическое время пользовательских действий хранится отдельно. По условиям ТЗ исходные данные нельзя выносить за пределы хакатона; в Git они не включены.

HR-импорт принимает JSON-объект {meta, employees} и CSV в UTF-8: до 20 МиБ на пакет, 1 000 профилей и 50 000 строк истории. Новые ID поддерживаются; роли, навыки, события и другие ссылки должны соответствовать объединённому набору. Каталог навыков и активностей через этот экран не заменяется. Схемы и проверки.

При включённом AI внешнему провайдеру передаются роль, грейд, цель, навыки, допустимые кандидаты и рассчитанные факты одного профиля. ФИО, пароли, руководитель и полная история компании в запрос не включаются. Использование провайдера для данных организаторов должно соответствовать условиям хакатона; опубликованные live-проверки используют авторские синтетические данные.

Интеграций с HRIS, LMS, почтой, календарями и мессенджерами пока нет.

Ограничения

• Одна компания и два демонстрационных аккаунта. Нет регистрации, SSO и интерфейса создания аккаунтов; импортированные профили проверяются через HR.
• Выполнение и прирост навыков моделируются. Короткие учебные модули не заменяют обучение и аттестацию; 100% покрытия цели не гарантирует повышение.
• Подбор ограничен загруженным каталогом. Подготовительный шаг рассматривает одну следующую активность; полный многошаговый маршрут до цели не гарантируется.
• Скрытые профили жюри и реальный бизнес-эффект заранее не проверены. Принятый AI-порядок обязан соблюдать общую с baseline политику приоритетов, поэтому их совпадение не является независимым доказательством пользы LLM. В live-регрессиях встречались таймауты и переходы в резервный режим. История участия не устанавливает причины пропусков или мотивацию человека.
• Требования UI ≤2 с и AI ≤10 с на всём пути под нагрузкой не подтверждены. В предыдущей браузерной проверке зафиксирован запрос профиля 2,811 с; восьмисекундный бюджет провайдера не включает всю обработку запроса. Подробности — в матрице ТЗ.
• Интерфейс русскоязычный; полная локализация на казахский и английский не реализована. Мобильные состояния проверены выборочно. HR-сводка участия не является подробной аналитикой просмотра уроков.
• Известна ошибка клавиатурной навигации: «Перейти к содержимому» и переходы только по hash могут сбрасывать фокус и локальный раздел. Она зафиксирована в аудите интерфейса; соответствующий обработчик пока сохранён.
• Не реализованы внутренняя валюта, магазин наград, признание коллег, конструктор событий и прогноз оттока. Это опциональные пункты кейса. Публичных рейтингов результативности и вознаграждений за обязательные процессы нет.

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

Публичная deployed-версия не указана в репозитории. Основной проверяемый способ запуска — Docker Compose на http://localhost:3000.

Compose публикует порты только локально. Для внешнего стенда требуются отдельная настройка адреса, APP_ORIGIN, HTTPS и доступа; готовой облачной конфигурации нет.