Career Quest

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

Стек: Next.js + React → FastAPI → SQLite. Дата среза данных — 2026-10-01. Люди и компании в датасете вымышлены.

Стартовый экран — AI-чат: он автоматически открывается после входа и обновления страницы. В меню чат стоит первым, над маршрутом и картой навыков; активный раздел выделен. Сотрудник может сразу задать вопрос или выбрать готовую команду. Внешний AI необязателен для запуска демонстрации.

Проблема и практическая ценность

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

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

Быстрый запуск на Windows

Нужны Python 3.11+, Node.js 20.9+ и npm в PATH. При первой установке нужен доступ к pip/npm.

Получите исходники (нужен Git) и перейдите в корень проекта:

git clone https://github.com/BAITC-Hacks/hack-d7c925eb-assa.git
cd hack-d7c925eb-assa

Запустите приложение без API-ключа:

.\run.ps1

Если PowerShell блокирует скрипт:

powershell -ExecutionPolicy Bypass -File .\run.ps1

Откройте Career Quest. API: health, Swagger.

Скрипт создаёт .venv, устанавливает зависимости из lock-файлов, создаёт базу только при её отсутствии и запускает оба сервиса. Повторный запуск сохраняет прогресс. Уже работающая пара обнаруживается автоматически. Ctrl+C останавливает процессы этого запуска.

.\run.ps1 -PrepareOnly                    # подготовить зависимости и базу
.\run.ps1 -SmokeTest                      # запустить, проверить и остановить
.\run.ps1 -ApiPort 8100 -WebPort 3100      # альтернативные порты

Ограничение: если оба сервиса уже работают, -SmokeTest выходит после HTTP-проверок и не выполняет дополнительную проверку помощника.

Что работает

• Карта подтверждённых и ожидаемых навыков, требования выбранной цели, ручное сохранение цели.
• До трёх рекомендаций с факторами оценки: цель и критичность, сокращение дефицита, история участия, длительность и эффективность времени.
• Маршрут с ближайшим доступным шагом и оставшимися требованиями; это не обещание автоматического повышения.
• Подтверждение выполнения, пересчёт ожидаемых уровней и сохранение результата в SQLite. Обычное повторное нажатие не начисляет прирост заново.
• Для регулярного клуба EV_036 участие относится к конкретной дате сессии.
• Личный игровой прогресс: XP, уровни пути, 15 значков, 4 миссии, недельные серии, календарь активности и журнал наград.
• HR-срезы разрешённого отдела: частые дефициты, отсутствие следующего шага с причинами, участие по мероприятиям.
• Чат с интерактивными карточками, объяснениями и сравнением. Без внешнего AI действует ограниченный локальный обработчик команд, явно подписанный в интерфейсе.
• Адаптивное меню и интерфейс для узкого экрана. Голосовой ввод зависит от браузера; он заполняет текст, но не отправляет сообщение автоматически.

Сценарии для проверки

На новой базе без ранее сохранённого прогресса:

Шаг	Действие	Ожидаемый результат
1	Открыть главную страницу	Автоматический вход в demo как E0001, открытый чат и первый пункт меню «AI-чат»
2	«Покажи карту навыков»	Карточка с подтверждёнными и ожидаемыми уровнями, требованиями цели
3	«Что делать дальше?»	До трёх допустимых активностей, факторы оценки и причины выбора
4	«Сравни первые два варианта»	Сравнение двух вариантов, если найдено хотя бы два
5	«У меня 30 минут», затем «Только онлайн»	Условия применяются в диалоге; если подходящих активностей нет, показаны причины
6	«Построй маршрут без ограничений»	Ограничения снимаются, маршрут пересчитывается
7	В доступной карточке нажать «Отметить выполненным» и подтвердить	Участие сохраняется, ожидаемый прогресс обновляется; подтверждённые оценки и грейд прежние
8	Обновить страницу, запросить карту и историю	Чат снова открыт; прогресс сохранён, визуальная лента начинается заново

Шаг 7 изменяет локальную демонстрационную базу. Проверки backend ниже используют отдельные временные базы.

HR: выбрать HR в локальном demo либо войти с HR-кодом в private → «Пульс команды» → «Без следующего шага» → «Участие». Аналогичные вопросы можно задать в чате.

Полезные локальные команды: «Покажи карту навыков», «Построй маршрут», «У меня 30 минут», «Только онлайн», «Сними ограничение по времени», «Сравни первые два варианта», «Объясни System Design на примере», «Мои достижения», «Сколько у меня XP?», «Мои квесты».

Геймификация

Откройте «Мои достижения» в меню или карточку игрового прогресса в стартовом чате. Игровой профиль включает:

Механика	Как работает
XP за квесты	От 50 до 160 XP за уникальное завершение добровольной активности; награда заранее показана на карточке
Уровни и звания	Новый игровой уровень каждые 300 XP; звания от «Искателя» до «Легенды развития», индикатор до следующего уровня
Коллекция из 15 значков	За первые квесты, часы обучения, разнообразие навыков и форматов, наставничество, практикумы и регулярность; фильтры открытых и будущих наград
4 долгосрочные миссии	5 завершений, 12 часов обучения, активности для 8 навыков и серия из 6 недель; каждая даёт однократный бонус XP
Недельная серия	Последовательные календарные недели с завершённым обучением; текущая неделя может ещё идти, рекорд хранится в истории
Календарь и журнал	Активность за 84 дня с деталями выбранной даты; последние 12 начислений с источником и датой
Награда за выполнение	После подтверждения показываются фактический прирост XP, новый уровень и открытые значки; повторное подтверждение даёт 0 XP

Расчёт за квест: 40 + 10 × min(12, max(1, ceil(длительность_в_часах))). Бонусы значков и миссий добавляются автоматически при первом достижении условия. Отдельно забирать награду не нужно. XP учитывает всю сохранённую историю добровольного обучения, поэтому у демонстрационных сотрудников уже есть игровой прогресс.

Сохранение и честный расчёт: баланс, значки и миссии рассчитываются сервером из SQLite; обновление страницы, новая сессия и перезапуск backend не обнуляют прогресс. Обычное событие учитывается один раз, клуб EV_036 — один раз на дату сессии. Дубли импорта не дают повторные игровые награды. Обязательные события, незавершённые участия и будущая импортированная история XP не приносят. Новая таблица или миграция базы не требуется.

Игровой календарь привязан к синтетической дате 2026-10-01. Демо-завершение будущей сессии клуба сохраняет её уникальный ID, но игровая награда показывается на дату среза и помечается как демонстрационная. Это не подтверждение реального посещения. Недельные серии считаются по неделям с понедельника; перерыв не отнимает XP, значки и лучший результат. Число навыков в игровом профиле означает охват пройденных активностей, а не подтверждённое владение навыками.

Игровой уровень не равен карьерному грейду. XP не влияет на допуск, ранжирование рекомендаций и подтверждённые оценки. Личных рейтингов сотрудников и штрафов за паузу нет.

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

После обновления исходников перезапустите backend и frontend. Дополнительный импорт не принимает новые записи с assigned_by=career_quest: это источник, зарезервированный для завершений в приложении. Точный повтор существующей записи принимается без повторной награды.

Проверка этой версии: 37 backend-тестов и 2 теста анализа — OK, TypeScript и production-сборка успешны. Новые тесты проверяют дедупликацию XP, миссии, границы уровней и недель, сохранение наград, изоляцию профилей, команды чата и запрет подмены источника импортом.

Архитектура и роль AI

Браузер: Next.js / React / TypeScript
    ↓ HTTP API, токен сессии
FastAPI: доступ → диалог → проверенные инструменты → рекомендации
    ↓ SQL                         ↕ опциональный внешний AI
SQLite                       Responses API / function calling
    ↑
Импорт JSON / CSV из career_quest_dataset

Компонент	Ответственность
frontend/components/QuestApp.tsx	Сессия, стартовый чат, навигация, диалог, подтверждение выполнения
frontend/components/QuestViews.tsx	Карточки навыков, маршрута, рекомендаций и HR-срезов
frontend/components/Gamification.tsx, frontend/app/gamification.css	Игровой профиль, миссии, значки, календарь и уведомление о награде
backend/app/routes.py, auth.py	API, серверная идентичность, права сотрудника и HR
backend/app/recommendation.py	Допуск, дефициты, ранжирование, прогноз и HR-агрегаты
backend/app/gamification.py	Расчёт XP, уровней, достижений, миссий и недельных серий из истории
backend/app/assistant.py, agent_tools.py	Контекст диалога, локальные команды, цикл вызовов инструментов внешней моделью
backend/app/database.py, backend/scripts/import_dataset.py	Схема SQLite, загрузка и добавочный импорт данных

Внешний агент выбирает последовательность разрешённых инструментов: например, прочитать контекст → подобрать активности → смоделировать маршрут → показать карточку. Backend проверяет аргументы, доступ и допустимость событий, рассчитывает числовые результаты и формирует итоговый фактический ответ. Модель не меняет прогресс: выполнение подтверждает пользователь отдельным действием интерфейса.

Без включённого провайдера работает обработчик поддерживаемых русскоязычных команд. Он использует те же инструменты, но не обладает свободным пониманием речи LLM. Интерфейс различает ответы agent, local и fallback и показывает трассу выполненных инструментов.

Данные и расчёт

База: backend/data/career_quest.db. Исходные правила и схема файлов: README датасета.

Подтверждённые уровни взяты из последней оценки. Для завершённых событий строго после last_review_date ожидаемый уровень пересчитывается хронологически:

new = max(old, min(5, max_level, old + gain))

Грейд и подтверждённые оценки автоматически не повышаются. Допуск определяется текущими ролью, грейдом и подтверждёнными prerequisites. Цель влияет на полезность активности, но не открывает допуск. Обязательные события не рекомендуются. covered_skills.gain в карточке означает полезное сокращение дефицита относительно цели.

Перед ранжированием исключаются уже завершённые обычные события, события без доступной сессии, неподходящие по времени/формату или не сокращающие известный дефицит. Recommendation Score — сумма пяти эвристических компонентов: приоритет цели и критичность (до 30), сокращение дефицита (до 25), история участия (до 20), реалистичность длительности (до 15), эффективность времени (до 10). Это объяснимый рейтинг до 100, а не вероятность карьерного успеха. При равенстве баллов выше короткая активность, затем сортировка по ID.

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

Известное расхождение: стартовый кит считает отсутствующий навык равным 0; текущий код считает его неизвестным (null) и пропускает прирост по нему. Это влияет на рекомендации и HR-агрегаты. Не считать расчёт полностью соответствующим стартовому киту до исправления.

Дополнительные профили

Добавочный импорт папки с employees.json и/или activity_history.csv в формате датасета:

.\.venv\Scripts\python.exe backend/scripts/import_dataset.py --append C:\path\to\new-data

Импорт выполняется транзакционно. Проверяются основные поля, ссылки и диапазоны; повтор одинаковых ID не создаёт дубли. Существующие оценки и сохранённые цели не перезаписываются. Каталог новых событий/навыков этот режим не расширяет.

Проверки пока неполные: разные record_id повторного completed обычного события могут повторно начислять gain; перечисления формата/языка и будущая дата review валидируются недостаточно. Подробности — в аудите.

Перед переносом или сбросом остановите сервер и сохраните копию базы:

Copy-Item backend/data/career_quest.db backend/data/career_quest.backup.db

Только для намеренного удаления всего прогресса и возврата к исходным данным:

.\.venv\Scripts\python.exe backend/scripts/import_dataset.py --reset

Доступ и конфигурация AI

По умолчанию demo доступно только через loopback. Переключатель синтетических профилей и HR в demo не является авторизацией.

Для защищённого пилота скопируйте backend/.env.example в backend/.env, задайте параметры и перезапустите сервисы:

Переменная	Назначение
CQ_MODE	demo или private
CQ_EMPLOYEE_ACCESS_CODE	Код сотрудника длиной от 16 символов
CQ_HR_ACCESS_CODE	Другой код HR длиной от 16 символов
CQ_EMPLOYEE_ID	Серверная привязка сотрудника, например E0001
CQ_HR_DEPARTMENT	Точное название разрешённого отдела
CQ_CORS_ORIGINS	Разрешённые адреса frontend через запятую
CQ_ALLOW_EXTERNAL_AI	По умолчанию false; включать только при разрешённой передаче контекста провайдеру
OPENAI_API_KEY	Серверный ключ, не публиковать в Git или NEXT_PUBLIC_*
OPENAI_MODEL	Модель с Responses/function calling; шаблон использует gpt-4.1-mini

Процессные переменные имеют приоритет; затем читаются backend/.env, корневой .env и, для совместимости, frontend/.env. Новые секреты храните в backend/.env. Endpoint внешней модели фиксирован: https://api.openai.com/v1/responses.

Модель выбирает разрешённые серверные инструменты. Числовые факты и итоговое объяснение формирует backend; произвольные HTML, JS и SQL модели не исполняются. Без ключа/разрешения работает локальный помощник; при ошибке провайдера ответ помечается как резервный. Надпись о включённом AI сама по себе не подтверждает соединение с моделью.

Лимиты: сообщение до 2000 символов, 20 запросов/минуту на сессию, один запрос одновременно, до 3 раундов и 6 инструментов, 9 секунд на модельный цикл; клиент прекращает ожидание через 15 секунд. Реальный общий SLA внешнего AI не подтверждён.

В private проверяются API и инструменты: сотрудник не получает чужой профиль/историю или HR-сводку; HR ограничен отделом. Это пилот с заранее настроенными доступами, без регистрации и SSO. Для доступа по сети требуется отдельная настройка адресов, CORS и защищённого транспорта; стандартный запуск предназначен для локального компьютера.

Серверная сессия живёт в памяти до 8 часов и восстанавливается после reload через sessionStorage. После рестарта backend нужен новый вход. Прогресс и цель остаются в SQLite; диалог чата reload не переживает.

Проверки и известные ограничения

.\.venv\Scripts\python.exe -m unittest discover -s backend/tests -v
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
cd frontend
npx tsc --noEmit
npm run build

Проверено при обновлении 23.09.2026: 17 backend-тестов и 2 теста анализа — OK, TypeScript без ошибок, production-сборка создаёт страницы / и /hr. В браузере проверены стартовый чат на узком и широком экранах, первый пункт меню, переход к маршруту, повторное открытие чата после reload и старт чата в режиме HR. Внешняя модель в этих проверках не вызывалась; физическое мобильное устройство не использовалось.

Независимый аудит от 23.09.2026 содержит воспроизведение, ссылки на код, расчёты, ограничения и приоритеты. В нём прошли 17 backend-тестов; локальные API-запросы рекомендаций заняли до 51 мс. Это не доказательство скорости внешней LLM и не нагрузочное тестирование.

Открытые проблемы, которые изменение дизайна не исправляет:

1. Отсутствующие навыки обрабатываются не по правилу стартового кита.
2. После смены цели из чата может оставаться старая рекомендация; обновление страницы очищает её.
3. Ошибка завершения недоступной активности скрыта под окном подтверждения.
4. Фраза «Почему это, а не Public Speaking?» локально не вызывает сравнение; используйте явное сравнение вариантов.
5. Неполная семантическая валидация дополнительного импорта.

Исторический аудит выполнялся до предоставления рубрики ниже. Реальная внешняя модель, чистая установка на другом компьютере и физические мобильные устройства в нём не проверены. Предварительные 75/100 из отчёта — рабочая оценка аудитора, не официальный балл. Отчёты аудита относятся к состоянию кода на момент их подготовки.

Материалы по критериям оценки

Баллы в таблице — максимальный вес критерия из предоставленной рубрики, а не присвоенная проекту оценка.

Критерий	Что представлено и как проверить	Максимум
Соответствие задаче и работоспособность	Сценарий сотрудника от вопроса до сохранения прогресса и HR-срезы; пошаговая демонстрация выше, API и тесты	25
Техническая реализация	Разделение интерфейса, API, расчётов и хранения; agentic-цикл инструментов, проверка прав, локальный режим при недоступности AI; раздел архитектуры и исходники	25
README и воспроизводимость	Запуск из клона одной командой, lock-файлы зависимостей, исходный датасет, конфигурация, ожидаемые результаты и команды проверок	25
Ценность и применимость решения	Персональный следующий шаг, объяснение причин выбора, учёт времени и формата; HR видит дефициты и пробелы каталога	15
Потенциал развития и оригинальность подхода	Диалог управляет проверяемыми карточками и личным игровым прогрессом; XP, подтверждённые оценки и прогноз обучения разделены; ограничения и план развития явно описаны	10
Итого	Итоговую оценку выставляют проверяющие по результатам запуска	100

Дальнейшее развитие

1. Устранить перечисленные расхождения расчёта и импорта, синхронизировать карточки после смены цели и улучшить показ ошибок подтверждения.
2. Проверить качество свободного диалога на реальной модели: набор вопросов и перефразировок, корректность инструментов, задержки и стоимость; добавить потоковые ответы.
3. Для организационного пилота подключить SSO и индивидуальные учётные записи, перенести сессии из памяти в общее хранилище, настроить HTTPS и журналирование.
4. Интегрировать каталог обучения и подтверждённые оценки из LMS/HR-систем с версионированием требований; масштабировать хранение и проверить нагрузку.
5. Измерить на добровольном пилоте время выбора активности, долю принятых рекомендаций и завершений; отдельно проверить, насколько рекомендации полезны сотрудникам и HR.

Симптом	Действие
Порт занят	Используйте уже запущенную пару либо другие порты
Backend/frontend не запустился	Проверьте соответствующий server-error.log, зависимости и адрес API
Нет рекомендаций	Посмотрите причины фильтрации и выбранную цель
Сессия истекла	Войдите снова; прогресс в базе сохранён
Ошибка чата	Повторите запрос; при недоступной модели используется локальный режим
Редактор показывает тысячи файлов .next	Проверьте правила игнорирования и обновите панель Git; сборки не являются исходным кодом

Структура и порядок в репозитории

• frontend/app, frontend/components, frontend/lib — интерфейс, стили и API-клиент.
• backend/app — API, доступ, рекомендации и помощник; backend/scripts — импорт.
• career_quest_dataset — исходные синтетические данные и их правила.
• backend/tests, tests — проверки; scripts, analysis — аналитика датасета.
• audit/independent-20260923 — отчёт, fixtures и воспроизводимые доказательства; runtime и временные базы удалены.
• ARCHITECTURE.md, PRODUCT_PRINCIPLES.md — архитектурные и продуктовые материалы; Plan.md, FIX_PLAN.md — история планирования, а не подтверждение текущей приёмки.

node_modules, .next, временные runtime и базы аудита исключены из Git на любой глубине. Рабочую базу, секреты и сборочные артефакты коммитить не нужно. Автокоммиты — внешняя локальная задача Windows, не функция приложения.