Career Quest

Публичное демо: Открыть Career Quest — опубликовано; вход и загрузка профиля через публичный адрес проверены.

Career Quest — демонстрационное веб-приложение для выбора добровольного шага профессионального развития. Сотрудник видит цель, навыки и участие, получает 1–3 объяснимые рекомендации и может выбрать, выполнить или пропустить шаг. HR видит профиль выбранного сотрудника, разрывы компетенций, доступность шагов и участие. Решение о развитии остаётся за человеком.

В публичном демо интерфейс размещается на Vercel, а запросы /api направляются к локальному FastAPI через временный Cloudflare Quick Tunnel. SQLite основного приложения хранится в постоянном Docker-томе career_quest_data. Для доступности демо должны оставаться включёнными компьютер, Docker-контейнер и туннель; при смене адреса временного туннеля маршрут API нужно обновить. Проект Supabase создан, но перенос профилей, истории и действий приложения в Supabase пока не реализован: рабочие данные остаются в SQLite.

Что запускать после объединения веток

В main сохранены приложение команды и разработка из ayko. Они имеют отдельные точки запуска, API и базы данных. Это позволяет сохранить оба варианта при пересечении файлов backend; автоматической синхронизации между ними пока нет.

	Основное приложение команды	Отдельный backend ayko
Интерфейс	React: кабинет сотрудника и HR	HTML HR-dashboard, профили через API
Точка запуска	backend.app.main:app	app.ayko_main:app --app-dir backend
Порт API	8000	8001
Страницы	/login, /employee, /hr/employees, /hr/competencies	/hr
Swagger	/api/docs	/docs
Вход	Email + DEMO_PASSWORD	Один HR-пароль HR_PASSWORD
SQLite локально	runtime/career_quest.sqlite (DB_PATH)	backend/data/career_quest.sqlite3 (DATABASE_PATH)
Зависимости	backend/requirements.txt, Python 3.12	backend/requirements-ayko.txt
Инструкция	Разделы ниже	Запуск и возможности ayko, контракт API

Для демонстрации полного сайта используйте основное приложение. React обращается к его API на порту 8000. Старые запросы /api/employees/{id}, /api/hr/summary и пароль HR_PASSWORD относятся к отдельному серверу ayko на порту 8001. Скрипт backend/start_hr.ps1 теперь запускает именно его; ранее сохранённые выполнения остаются в прежней базе.

Стек основного приложения: Python/FastAPI/Pydantic, SQLite, OpenAI SDK, React/TypeScript/Vite. SQLite отдельно устанавливать не нужно. Организационные ссылки хакатона: HACKATHON_GUIDE.md.

Источники и границы

• Требования: references/career_quest_requirements.pdf, страницы 2–4. Общие принципы содержательного AI: страница 4 references/voice_router_with_shared_requirements.pdf. Эти файлы находятся в выданном career_quest_codex_pack.zip.
• Данные: career_quest_dataset.zip с каталогом case_1/career_quest_dataset/: employees.json, skills.json, events.json, activity_history.csv и README на трёх языках.
• Wireframe в references/ — ориентиры композиции. Нарисованные курсы, оси и числа не входят в каталог.
• Skip, архив HR, выбор цели и показатель покрытия — решения MVP, описанные в docs/ASSUMPTIONS.md.

Исходный набор содержит 200 сотрудников, 40 мероприятий, 60 навыков, 32 профиля роли/грейда и 2 743 записи участия. Это контрольные числа первого импорта, а не пределы приложения. Синтетический датасет включён в репозиторий для запуска и тестирования.

Запуск одной командой

Нужны Docker и Docker Compose. Исходный career_quest_dataset.zip уже находится в корне репозитория рядом с compose.yaml и доступен после клонирования. Распакованные исходные JSON/CSV также включены в career_quest_dataset/.

Создайте приватный .env из шаблона (cp .env.example .env в Linux/macOS):

if (-not (Test-Path .env)) { Copy-Item .env.example .env }

Задайте в .env непустой DEMO_PASSWORD. Для реального AI-подбора добавьте OPENAI_API_KEY только в серверный .env самостоятельно. Пустой ключ включает явно помеченный резервный подбор. Ключ нельзя помещать в VITE_*, браузер или исходный код.

docker compose up --build

Откройте http://localhost:8000 или порт APP_PORT из .env. Первый запуск импортирует стартовый набор в SQLite. База находится в именованном томе career_quest_data; повторный запуск не должен сбрасывать действия или начислять навыки повторно. ZIP подключён к контейнеру только для чтения. Наличие Docker на конкретном компьютере проверяется отдельно.

Переменная	Значение	Назначение
DEMO_MODE	true	Синтетические аккаунты и явно помеченное моделирование будущих сессий.
DEMO_PASSWORD	задаётся в .env	Общий пароль демо-аккаунтов; сервер хранит хеш.
OPENAI_API_KEY	пусто в шаблоне	Секрет серверного вызова OpenAI; без него показывается fallback.
OPENAI_MODEL	gpt-4.1-mini	Модель Responses API.
COOKIE_SECURE	false для локального HTTP	Принудительно включает Secure-cookie при HTTPS за proxy.
APP_PORT	8000	Порт хоста в Docker Compose.
DB_PATH	/data/career_quest.sqlite в Compose	Постоянная база SQLite.
DATASET_ZIP	/app/career_quest_dataset.zip в Compose	Исходный архив внутри контейнера.

.env, .env.txt и локальная база исключены из Git и Docker build context. Исходный синтетический датасет хранится в Git; Compose подключает архив к контейнеру только для чтения.

При размещении за HTTPS reverse proxy выставьте COOKIE_SECURE=true и настройте список доверенных IP для forwarded headers в инфраструктуре. Настройки по умолчанию рассчитаны на локальный HTTP-демо.

Локальная разработка

Нужны Python 3.12 и Node.js 22. Из корня проекта установите зависимости и запустите API:

if (-not (Test-Path .env)) { Copy-Item .env.example .env }
py -3.12 -m venv .venv-main
.\.venv-main\Scripts\python.exe -m pip install -r backend/requirements.txt
# Перед запуском откройте .env и задайте непустой DEMO_PASSWORD.
.\.venv-main\Scripts\python.exe -m uvicorn backend.app.main:app --reload --port 8000

В другом терминале:

cd frontend
npm ci
npm run dev

Откройте http://localhost:5173. Vite передаёт /api на http://127.0.0.1:8000; Swagger находится на http://127.0.0.1:8000/api/docs. Активация окружения и запуск .ps1 не нужны: команды работают при запрете PowerShell-скриптов. Если команды py нет, используйте путь к установленному Python 3.12. Окружение .venv-main отделено от существующего .venv для backend ayko.

Backend читает .env из корня проекта. Локальные значения по умолчанию: runtime/career_quest.sqlite и career_quest_dataset.zip в корне репозитория. При необходимости задайте другие абсолютные пути через DB_PATH и DATASET_ZIP. В Compose пути выставлены автоматически. APP_PORT меняет порт Docker, а при локальном запуске порт задаёт аргумент --port.

Чтобы сайт отдавался целиком с порта 8000 без Vite dev-сервера, выполните npm run build в frontend/, затем откройте http://localhost:8000 при работающем backend.

Вход и экраны

В DEMO_MODE=true используются синтетические учётные записи приложения, которых нет в исходном датасете: [email protected] и [email protected]. У каждого исходного и нового импортированного профиля автоматически появляется демо-логин вида [email protected]. Пароль — значение DEMO_PASSWORD; его изменение при перезапуске обновляет хеши демо-аккаунтов и аннулирует их действующие сессии. При DEMO_MODE=false вход в демо-аккаунты закрыт. Должностная role в JSON не выдаёт права HR; сервер хранит роль доступа отдельно, проверяет владельца данных и использует HttpOnly-cookie для сессии.

Маршрут	Содержимое
/login	Вход без регистрации и восстановления пароля.
/employee	Профиль, цель и её происхождение, текущие и требуемые навыки, расчётная динамика, история и рекомендации.
/hr/employees	Поиск и фильтры сотрудников, профиль выбранного человека, архивирование и восстановление предложения с причиной.
/hr/competencies	Разрывы по индивидуальным целям, причины отсутствия шага и участие.
/hr/import	Загрузка дополнительных профилей JSON и истории CSV, предварительная проверка и подтверждение импорта.

Основная навигация находится в закрываемой левой панели. В HR доступны «HR view», «HR компетенции» и «Импорт профилей»; кнопка выхода расположена внизу. Кнопка меню в верхней строке открывает панель снова, а её состояние сохраняется между обновлениями страницы. На узком экране панель открывается поверх содержимого.

Пропуск рекомендации доброволен: он не уменьшает навык и не создаёт no_show/declined. Сотрудник может вернуть мероприятие в рассмотрение. Архив HR действует на пару сотрудник/мероприятие, сохраняет историю и причину, виден сотруднику и обратим; восстановление архива не отменяет Skip. HR не отмечает обучение выполненным от имени человека.

Основные API основного приложения

Метод	Путь	Назначение
POST	/api/login, /api/logout	Вход и выход
GET	/api/me	Сессия, роль доступа, CSRF-токен
GET	/api/employee/profile	Профиль текущего сотрудника, навыки, история
POST	/api/employee/goal	Подтвердить карьерную цель
GET / POST	/api/employee/recommendations / /api/employee/recommendations/generate	Получить сохранённый результат / запросить новый подбор
POST / DELETE	/api/employee/recommendations/{event_id}/skip	Пропустить или вернуть шаг
POST	/api/employee/participations	Выбрать активность
POST	/api/employee/participations/{participation_id}/complete	Завершить выбранную активность и пересчитать прогресс
GET	/api/hr/employees, /api/hr/employees/{employee_id}	Список и профиль для HR
GET	/api/hr/competencies	Разрывы, отсутствие следующего шага, участие
POST	/api/hr/import/preview, /api/hr/import/commit	Проверить и сохранить импорт

Точные поля всех запросов — в /api/docs. Изменяющие запросы после входа требуют cookie сессии и заголовок X-CSRF-Token из /api/me; frontend передаёт их автоматически.

От данных к рекомендации

JSON/CSV → валидация и SQLite → replay завершений → цель и разрывы
         → допустимые мероприятия → OpenAI выбирает 1–3 шага
         → серверная проверка ответа → UI и сохранённые действия

employees.skills — неизменённая база последней оценки. Сервер применяет только completed после last_review_date до даты среза 2026-10-01, затем новые завершения приложения ровно один раз. Исходная история до оценки остаётся видимой. Для каждого навыка события:

new_level = max(current_level, min(5, current_level + gain, max_level))
actual_gain = new_level - current_level

Частичное прохождение не даёт частичный уровень. Отсутствующий навык равен 0. Выполнение обязательного мероприятия может повысить навык, хотя оно исключено из добровольных рекомендаций. Для self-paced исходный date — дата зачисления, а точного времени завершения CSV не содержит; для импортированного completed она используется как приближение.

Цель берётся из career_goal или отдельно подтверждённого выбора. При отсутствии цели до Lead показывается предложение следующего грейда текущей профессии; для Lead — развитие в текущем профиле без обещания пятого грейда. Для выбранного профиля:

gap(skill) = max(0, required_level - current_level)
coverage_pct = 100 × Σ min(current_level, required_level) / Σ required_level

В знаменатель входят только положительные требования цели. При нулевом знаменателе процент не вычисляется. «Покрытие требований цели» не является вероятностью повышения; грейд автоматически не меняется.

Backend до вызова модели отсекает обязательные, недоступные по текущей роли/грейду, prerequisites и датам, уже завершённые неповторяемые, пропущенные сотрудником, архивированные HR и шаги без полезного прироста. self_paced доступен без сессии. Исключение на повтор — клуб EV_036 при новой допустимой сессии и реальном приросте. Исторические no_show/declined не становятся пожизненным запретом.

OpenAI получает минимум контекста выбранного человека без имени, email и пароля, все допустимые альтернативы и пул проверяемых фактов. Модель ранжирует 1–3 шага и возвращает event_id, действие и evidence_ids; она не вычисляет уровни и не меняет SQLite. Backend проверяет IDs, факты и актуальность версии, затем формирует отображаемые числа. Источник AI или fallback и время расчёта должны быть видны. При отсутствии ключа, ошибке или таймауте показывается обозначенный резервный подбор по правилам. Автоматические тесты с mock не проверяют реальный доступ к API.

Текущий выбор и результаты ограниченных live-проверок моделей записаны в docs/MODEL_SELECTION.md. Развёртывание в Compose использует один процесс Uvicorn. Блокировка одновременных AI-запросов для одного сотрудника хранится в памяти процесса; для запуска с несколькими workers нужна общая координация через БД или очередь.

Импорт дополнительных профилей

HR открывает «Импорт профилей» в левой панели или кнопку «Загрузить профили и историю» на странице сотрудников. Загрузите дополнительный employees.json в исходном формате {meta, employees} и/или activity_history.csv с исходными заголовками. Каталоги навыков/мероприятий повторно загружать не нужно. Сначала просмотрите preview с количеством новых записей, дублями и ошибками, затем подтвердите импорт. При обновлении базовой оценки тем же днём, когда человек завершил активность в приложении, preview предлагает явное подтверждение, что новая оценка уже включает эти завершения; без отметки они остаются в replay. Ссылки проверяются по объединению имеющейся и загружаемой базы; конфликт ID с другим содержимым должен быть явным. После успешной транзакции новые профили доступны в поиске HR, сводки пересчитаны. Файлы импорта не отправляются во внешние API для разбора.

Проверки и пятиминутная демонстрация

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

.\.venv-main\Scripts\python.exe -m pytest tests -q
$env:PYTHONPATH = "backend"
.\.venv\Scripts\python.exe -m unittest discover -s backend/tests -v
cd frontend
npm run typecheck
npm run build

Статус фактически выполненных проверок указан в docs/ACCEPTANCE.md. Live-вызов OpenAI требует собственного ключа и проводится отдельно.

Отдельная явная платная проверка реального AI без изменения состояния рекомендаций:

.venv-main\Scripts\python.exe scripts/live_openai_check.py --employee E0005

Скрипт читает ключ только из серверного окружения/.env и выводит безопасный итог: модель, результат валидации, время и ID мероприятий. Команда не входит в pytest и делает оплачиваемый запрос к OpenAI.

1. Войти как [email protected]; показать цель Senior, разрыв System Design и историю. У E0005 исходная история содержит три завершения Public Speaking Club, а не три пропуска.
2. Запросить AI-подбор, раскрыть три фактора и подтверждённый эффект. EV_007 — допустимый пример, но не жёстко заданный ответ.
3. Пропустить добровольный шаг, получить альтернативу и при необходимости вернуть пропущенное.
4. Выбрать и завершить доступный шаг; для будущей сессии в демо-режиме использовать явную кнопку «Смоделировать выполнение». Показать изменение навыка и покрытия.
5. Войти как HR, найти E0005, увидеть обновление, архивировать предложение с причиной и восстановить его. Открыть сводку компетенций и preview дополнительного профиля/истории.

Приложение не проводит обучение внутри себя, не интегрировано с LMS/SSO и не служит системой оценки персонала. Ограничения исходных дат и расчётов указаны в docs/ASSUMPTIONS.md.

Обновление интерфейса и HR-аналитики

• Сотрудник начинает с личного плана и кнопки «Подобрать с AI». Навыки и журнал с Attended/Skipped находятся в отдельных вкладках; добровольный Skip не смешивается с no_show.
• HR начинает со списка команды, поиска и рабочих фильтров. Выбранный сотрудник открывается в отдельном HR-экране анализа; изменение цели, выбор и выполнение активности доступны только сотруднику.
• Импорт JSON и CSV вынесен в /hr/import; сворачиваемая боковая панель содержит разделы HR и выход.
• Из дизайна ayko адаптированы полосы разрывов, матрица «отдел × навык» и диаграмма статусов участия. Они используют основную API и SQLite. API /api/hr/competencies дополнен department_skills и overview; знаменатель каждого навыка учитывает индивидуальные цели.
• Проверено: 25 тестов основного backend и 9 тестов отдельного backend ayko, TypeScript и Docker-сборка. В браузере на отдельной тестовой базе выполнены импорт одного профиля и двух историй до commit, поиск, вход нового сотрудника, desktop/mobile-панель и ограничения HR-маршрутов.

Если что-то не запускается

Ситуация	Что сделать
running scripts is disabled	Используйте прямой вызов .venv-main\Scripts\python.exe, без Activate.ps1. Для ayko есть такие же команды в его инструкции.
DEMO_PASSWORD must be set или вход не работает	В корневом .env задайте DEMO_MODE=true и свой DEMO_PASSWORD, перезапустите основной backend.
Frontend build is not available на 8000	Откройте Vite на 5173 или выполните npm run build в frontend/.
404 для /api/hr/summary или старых employee endpoints	Это API ayko: запустите app.ayko_main:app на 8001 и используйте /docs на этом порту.
503 HR-вход не настроен на ayko	Задайте HR_PASSWORD в терминале до запуска; это другой вход, чем DEMO_PASSWORD основного приложения.
401 после reload/смены пароля	Войдите заново; сессии двух приложений независимы.
Порт занят	Остановите старый сервер через Ctrl+C; при изменении порта основного API измените и proxy в frontend/vite.config.ts.

Правило обновления main и README

Рабочая ветка для изменений пользователя mynameisayko — ayko. Перед каждым push в main:

1. Получить актуальную origin/main и объединить изменения команды с ayko.
2. Актуализировать этот README: возможности, запуск, API, настройки и ограничения, которых касается изменение. Добавить запись в журнал ниже с реально выполненными проверками.
3. Зафиксировать изменения, отправить ayko, затем перенести результат в main без force-push. Вернуться в ayko для следующей разработки.

Правило закреплено в AGENTS.md. Hook .githooks/pre-push блокирует обновление main, если корневой README не изменился относительно удалённой версии. Он проверяет наличие изменения; содержательность проверяет автор.

В этом клоне hook включён. Для нового клона:

git config --local core.hooksPath .githooks

Настройка локальная: другим участникам нужно включить её в своих клонах. Она не блокирует изменения через интерфейс GitHub. При наличии собственных hooks сначала сохраните их поведение. Автор коммита и аккаунт push проверяются отдельно; один git config user.name не меняет GitHub-авторизацию.

Журнал обновлений main

2026-09-23 — проверена публикация на Vercel

• Публичный адрес отдаёт актуальный Career Quest и собранный JavaScript. Проверены HTTP 200 для страницы и ресурса, HTTP 401 для /api/me без авторизации, вход сотрудника через публичный адрес с Origin и cookie, получение его профиля с 19 записями истории.
• Реальный вызов OpenAI на работающем backend вернул три рекомендации с source=ai за 3,2 секунды. Объяснение связывает курс с целью Senior, критическим навыком System Design, ожидаемым ростом и предыдущим участием; внутренних кодов и сырых статусов в тексте нет.
• Интерфейс опубликован из Rufus602/hellohack, ветка codex/test-vercel-supabase. Компьютер, Docker и временный туннель по-прежнему нужны для работы API; облачная миграция базы не выполнена.

2026-09-23 — читаемые объяснения и подготовка публичного демо

• В интерфейсе сотрудника и HR скрыты внутренние коды навыков и мероприятий, пути к служебным источникам факторов и техническая колонка происхождения записи. При этом идентификаторы сохранены в API, связях данных и действиях. Журнал оставляет понятные Attended/Skipped, дату и статус; самостоятельные курсы помечают приблизительную дату исходной записи.
• Объяснения рекомендаций и карточки истории стали короче и понятнее. Публичная ссылка Vercel указана как развёртываемая: frontend использует временный туннель к локальному FastAPI, данные остаются в постоянном Docker-томе SQLite. Созданный проект Supabase пока не хранит бизнес-данные.
• Фактически пройдены 25 тестов основного backend, 9 тестов backend ayko, проверка типов TypeScript и Docker-сборка. Сквозная проверка публичной ссылки ещё не подтверждена.

2026-09-23 — раздельные роли, импорт и статистика ayko в React

• Добавлены отдельный HR-профиль и обзор команды; сотрудник видит личный план, AI-подбор с объяснениями, навыки и историю в разных вкладках.
• Добавлены закрываемая левая панель, отдельный импорт JSON/CSV и явные Attended/Skipped. Импорт через браузер проверен до commit на изолированной SQLite: 1 новый профиль, 2 записи истории, последующий вход нового сотрудника.
• В основной React UI перенесены визуальные подходы ayko: полосы разрывов, карта отделов и диаграмма участия. Расчёты выполняются по основной базе; API дополнена department_skills и overview. Отдельный backend ayko сохранён без изменения его контрактов.
• Фактически проверены 24 теста основного backend, TypeScript, Vite и Docker-сборка; закрытие/открытие панели, мобильная навигация и ограничение HR-маршрутов в браузере. Основное приложение запущено локально на порту APP_PORT=8013.

2026-09-23 — объединение ayko и приложения команды

• Сохранены все коммиты ayko и новые изменения команды: React, основной backend, Docker и синтетический ZIP-датасет.
• Backend ayko сохранён в backend/app/ayko_main.py; его HR-dashboard, профиль, история, OpenAI-рекомендации и SQLite completion доступны отдельным запуском на 8001.
• Разделены команды запуска, входы и зависимости, обновлены документация API и скрипт HR. Автоматической синхронизации двух баз пока нет.
• Добавлены правило обязательного обновления README и локальный pre-push hook.
• Проверки объединённой версии: 23 теста основного backend проходят на Python 3.12 с закреплёнными зависимостями; 9 тестов backend ayko проходят на существующем Python 3.14; TypeScript typecheck и production-сборка frontend успешны. Проверены 4 сценария pre-push hook. Docker и реальный вызов OpenAI в этой проверке не запускались. Сборка Vite предупреждает о JS-файле больше 500 кБ; это не блокирует сборку.