Career Quest

Career Quest — веб-приложение для развития сотрудников. Оно связывает навыки, требования следующего грейда и историю обучения, предлагает подходящие активности и сохраняет результат: навыки, XP, уровни, ранги и награды.

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

Это хакатон-демо с вымышленными профилями. Без API-ключа доступны локальные рекомендации и справка. Подключение OpenAI включает AI-подбор и свободный диалог с помощником.

Возможности

• Вход сотрудника и HR с серверной проверкой прав.
• Карта навыков, готовность к следующему грейду и до трёх рекомендованных шагов.
• Добровольный старт, завершение, отказ и пауза участия.
• XP, уровни, пять рангов, бейджи и однократные награды.
• AI-диалог по выбранному профилю; локальная справка без API.
• HR-аналитика, просрочки, импорт JSON и экспорт CSV.
• Переключатель Русский / English / Қазақша до входа и в кабинетах.

Используемые технологии

Технология	Версия / источник	Назначение
Python	3.11+	Серверная логика и запуск
Streamlit	1.64.0	Интерфейс, формы, кабинеты и диалоговое окно
pandas	3.0.6	Таблицы, аналитические сводки и CSV
SQLite	Стандартный модуль sqlite3	Пользователи, сессии, прогресс и награды
Pydantic	2.13.5	Валидация датасетов и JSON Schema
OpenAI Python SDK	2.54.0	Responses API для рекомендаций и диалога
python-dotenv	1.2.3	Чтение настроек из .env
JSON-каталоги	locales/	Английские и казахские переводы; русский — исходный язык
unittest + Streamlit AppTest	Python + Streamlit	Проверка сервисов и интерфейса

Версии закреплены в requirement.txt. Node.js, npm, MySQL и отдельный frontend-сервер для текущей версии не нужны.

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

Career Quest/
├── app.py                           # Вход, кабинеты, выбор языка, таблицы и AI-диалог
├── run.py                           # Создание venv, установка зависимостей, запуск
├── requirement.txt                  # Закреплённые версии Python-зависимостей
├── env.example                      # Шаблон настроек без секретов
├── .gitignore                       # Исключения для .env, venv и локальной БД
├── .streamlit/config.toml           # Тема, адрес сервера и лимит загрузки
├── services/
│   ├── dataset.py                   # Модели и проверка JSON-датасета
│   ├── store.py                     # SQLite, авторизация, прогресс и награды
│   ├── recommendations.py           # Подбор активностей и сводка HR
│   ├── progression.py               # Уровни, ранги, достижения и дедлайны
│   ├── assistant.py                 # AI-диалог и локальная справка
│   ├── ai_config.py                 # Настройки AI и сообщения об ошибках
│   └── i18n.py                      # Загрузка словарей и подстановка переводов
├── locales/
│   ├── en.json                      # Английские переводы
│   └── kk.json                      # Казахские переводы
├── data/
│   ├── demo.json                    # Начальные вымышленные профили и активности
│   ├── jury-example.json            # Пример для импорта из HR-кабинета
│   └── career_quest.sqlite3         # Создаётся при запуске, исключён из Git
├── docs/API_SETUP.md                # Подключение и диагностика OpenAI
├── tests/
│   ├── test_career_quest.py         # Авторизация, подбор, импорт и основные UI-сценарии
│   ├── test_progression_assistant.py # Ранги, награды, диалог и права доступа
│   └── test_i18n.py                 # Переводы, переключение языков и язык помощника
├── index.html                      # Отдельная статическая стартовая страница
└── Plan.md                         # Концепция, ограничения и этапы развития

Основная точка входа — app.py, запускаемый через Streamlit. Статический index.html не запускает серверную логику и не заменяет приложение. Каталог .venv-career создаётся локально и исключён из Git.

Поток данных: интерфейс → сервисы → SQLite. AI-сервис отправляет разрешённый контекст в OpenAI после настройки сервера и согласия пользователя. Локализация меняет отображение; ID, права, навыки и прогресс в БД остаются неизменными.

Порядок запуска

1. Подготовьте окружение

Установите Python 3.11+ с venv и pip. Скачайте или клонируйте проект. Откройте терминал в корневой папке проекта, рядом с run.py и requirement.txt.

Для первой установки зависимостей нужен интернет. Для работы локальных рекомендаций подключение к OpenAI не требуется.

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

В Windows PowerShell используйте одну из команд:

python run.py
# Если используется Windows Python Launcher:
py -3 run.py

В macOS / Linux:

python3 run.py

Скрипт создаёт .venv-career, устанавливает зависимости из requirement.txt и запускает Streamlit. При изменении файла зависимостей установка повторяется. Активировать окружение вручную не требуется.

3. Откройте приложение и выберите язык

Перейдите на http://localhost:8501. SQLite, начальные профили и демо-аккаунты создаются автоматически. Повторный запуск сохраняет прогресс.

В боковой панели выберите «Язык / Language / Тіл». Если панель скрыта, раскройте её кнопкой со стрелками слева сверху.

4. Войдите под нужной ролью

Роль	Логин	Пароль
Сотрудник / Employee / Қызметкер	employee1, employee2 или employee3	Quest2026!
HR	hr	HrQuest2026!

Выбор роли не повышает права: сервер сверяет её с учётной записью. Пароли хранятся как PBKDF2-хеши с солью. Сессия действует 8 часов; выход отзывает токен. Пять неудачных попыток входа блокируют аккаунт на минуту. Логин и пароль для входа в демо-доступ: Демо-доступы: Роль Логин Пароль Сотрудник Логин employee1 Пароль :[скрыто]! HR Логин:hr Пароль HrQuest2026!

Ручная установка и повторный запуск

Windows:

py -3 -m venv .venv-career
.\.venv-career\Scripts\python.exe -m pip install -r requirement.txt
.\.venv-career\Scripts\python.exe -m streamlit run app.py

macOS / Linux:

python3 -m venv .venv-career
.venv-career/bin/python -m pip install -r requirement.txt
.venv-career/bin/python -m streamlit run app.py

Для остановки нажмите Ctrl+C в терминале сервера. Для повторного запуска используйте run.py или последнюю команду для своей ОС. В VS Code выберите интерпретатор из .venv-career, чтобы редактор видел зависимости.

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

1. Выберите язык и войдите как employee1 с ролью сотрудника.
2. Посмотрите профиль, цель Middle → Senior, навыки и готовность к грейду. XP и игровой ранг показаны отдельно от профессионального грейда.
3. Откройте «Мой маршрут». Первым предлагается «Спроектируй сервис вместе с наставником»: этот шаг закрывает критичный разрыв System Design. В карточке объясняются требования грейда, разрывы, история и предпочтения.
4. Нажмите «Начать». Активность перейдёт в «В работе», начнётся отсчёт дедлайна.
5. Нажмите «Отметить выполненной». На исходном датасете System Design вырастет с 50 до 65, а выполнение в срок даст 180 XP: 150 базовых и 30 бонусных. Повторное начисление запрещено.
6. Проверьте «Навыки и цель», «Ранги и награды», «История». Историю с начисленными XP можно скачать в CSV.
7. Нажмите «Открыть AI-помощника» и задайте вопрос о следующем шаге, навыках или ранге. Без API будет локальная справка, с настроенным API и согласием — ответ OpenAI на выбранном языке.
8. При необходимости приостановите участие или откажитесь от шага: полученные XP и навыки сохранятся. Выйдите и войдите снова, чтобы убедиться в сохранении прогресса.

Дополнительные примеры: employee2 получает базовый SQL-практикум; продвинутый SQL исключён до выполнения предпосылок. Для employee3 начальный каталог не содержит подходящего шага — приложение объясняет причину.

Числа относятся к исходному demo.json. Если активность уже выполнена, приложение показывает сохранённый результат, а не сбрасывает его для повторной демонстрации.

Основной сценарий: HR

1. Выйдите из кабинета сотрудника и войдите как hr, выбрав роль HR.
2. В «Обзор команды» посмотрите разрывы навыков, сотрудников без нового шага, участие и просрочки.
3. В «Профили и траектории» выберите сотрудника. Доступны навыки, рекомендации, история и награды. HR не выполняет активности за сотрудника.
4. Через «Обсудить профиль с AI» задайте вопрос по выбранному профилю. Переписки разных профилей разделены.
5. В «Ранги команды» проверьте распределение рангов, уровни, XP и Quest-баллы; при необходимости скачайте CSV.
6. В «Загрузка датасета» скачайте пример, выберите JSON, подтвердите синтетическое происхождение и нажмите «Проверить и загрузить».
7. Сохраните выданные логины и пароли новых сотрудников: они показываются только в текущей HR-сессии. После работы сотрудника нажмите «Обновить данные», чтобы увидеть результат.

Переключение языков

• ru — русский, en — английский, kk — казахский. Выбор доступен до входа и после него, сохраняется при выходе и в адресе ?lang=en / ?lang=kk.
• Обновление страницы с этим адресом сохраняет язык, но может потребовать нового входа.
• Переводятся кнопки, вкладки, ранги, бейджи, таблицы, CSV-заголовки, рекомендации, уведомления и встроенные названия демо-профилей и активностей.
• Произвольные тексты импортированного JSON остаются исходными. Системные элементы Streamlit, например меню таблицы и загрузчик файлов, используют язык компонента.
• Новые ответы помощника используют выбранный язык. Старые сообщения не переписываются. Локальная справка распознаёт вопросы на всех трёх языках.
• Русские сообщения находятся в коде, переводы — в locales/en.json и locales/kk.json. Для новой строки добавьте одинаковые ключи и параметры подстановки в оба словаря. Отсутствующий перевод возвращает исходный текст.

Настройка AI — необязательно

Для локального режима .env не требуется. Чтобы включить OpenAI, создайте .env из шаблона, если файла ещё нет:

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

Заполните настройки и перезапустите сервер:

ALLOW_EXTERNAL_AI=true
OPENAI_API_KEY=ваш_новый_ключ
OPENAI_MODEL=gpt-4o-mini

Переменная	По умолчанию	Назначение
ALLOW_EXTERNAL_AI	false	Разрешает внешние AI-запросы на сервере
OPENAI_API_KEY	Не задан	Секретный ключ OpenAI
OPENAI_MODEL	gpt-4o-mini	Модель Responses API; для подбора нужны Structured Outputs
CAREER_QUEST_DB	data/career_quest.sqlite3	Необязательный путь к SQLite-базе

В интерфейсе отдельно подтвердите передачу данных. «AI настроен» означает наличие конфигурации; успешный ответ помечен «AI-помощник · OpenAI» или «AI-подбор · OpenAI». Ключ хранится на сервере, .env исключён из Git. Переменные окружения имеют приоритет над .env.

Подробная инструкция и диагностика ошибок: docs/API_SETUP.md.

Прогресс и награды

Навык: min(100, текущий уровень + прирост активности).

Готовность к грейду: 100 × сумма(min(навык / цель, 1) × вес) / сумма весов, округление до одного знака. XP на готовность не влияет.

XP: базовые баллы + целочисленный бонус 20% до дедлайна включительно. Опоздание не отнимает базовые XP. За обязательные процессы баллы не начисляются. Уровень: 1 + XP // 300.

Ранг	Уровни	От XP	Однократная награда
Новичок	1–2	0	Бейдж «Начало пути»
Исследователь	3–4	600	100 Quest-баллов + бейдж
Практик	5–7	1200	250 Quest-баллов + бейдж
Эксперт	8–11	2100	500 Quest-баллов + бейдж
Лидер	12+	3300	1000 Quest-баллов + бейдж

Quest-баллы — коллекционные награды демо: они не добавляют XP и пока не обмениваются на товары или деньги. Завершение и награда сохраняются одной транзакцией; уникальная пара сотрудник/ранг предотвращает повторную выдачу. Импорт и обновление старой БД выдают уже заслуженные награды; дата выдачи — дата импорта или обновления. После высшего ранга уровни продолжают расти.

Бейджи отмечают первый шаг, три завершения, серию из трёх выполнений в срок и навык 100/100. Пропуск, опоздание или завершение без известного дедлайна прерывают серию; отказ и пауза её не уменьшают.

Данные и импорт

Пример: data/jury-example.json. Формат — UTF-8 JSON до 2 МБ; JSON Schema скачивается из HR-кабинета. Модели описаны в services/dataset.py.

• Верхний уровень: schema_version: 1, synthetic: true, employees, activities, history.
• Профиль: ID, вымышленное имя, должность, грейды, навыки, требования и предпочтения. Поле role в JSON — должность, а не право доступа.
• Активность: ID, название, формат, допустимые грейды, приросты, предпосылки, длительность, XP, срок и добровольность.
• История: employee_id, activity_id, status, date; необязательные due_date и xp. Статусы: started, completed, missed, declined.
• Навыки — снимок после истории: прирост не начисляется повторно. Без явного xp историческое завершение даёт 0 XP.
• Импорт добавляет новые профили. Конфликты ID, неверные типы, ссылки и диапазоны отклоняют весь импорт. Идентичную активность можно переиспользовать.
• Лимиты при импорте: 200 профилей, 200 активностей, 5000 событий. Данные и аккаунты добавляются атомарно. Создать HR-аккаунт через датасет нельзя.

SQLite хранит пользователей, сессии, JSON-снимок датасета и таблицу rank_rewards. Имя, логин, пароль и чужая история автоматически не передаются в AI-контекст. Введённый пользователем текст отправляется при согласии. Диалог хранится только в текущей сессии: видны последние 24 сообщения, в OpenAI передаются последние 12. Вопрос — до 2000 символов; выход очищает переписку.

Проверки

Windows:

.\.venv-career\Scripts\python.exe -m unittest discover -s tests -v

macOS / Linux:

.venv-career/bin/python -m unittest discover -s tests -v

Тесты используют временные БД и подменённый OpenAI-клиент. Проверяются права, подбор, импорт, прогресс, однократные награды, откат транзакций, диалог, словари и переключение языков. Реальная связь с OpenAI требует действующего ключа и отдельного запроса.

Частые проблемы

Проблема	Решение
python не найден	Попробуйте py -3 в Windows или python3 в macOS / Linux; при отсутствии Python установите его
ModuleNotFoundError	Используйте интерпретатор .venv-career и установите зависимости из requirement.txt
Порт 8501 занят	Остановите старый сервер или добавьте к команде Streamlit --server.port 8502
AI отвечает локально	Проверьте .env, перезапуск и согласие; подробности в docs/API_SETUP.md
Переключатель языка не виден	Раскройте боковую панель; доступны прямые ссылки ?lang=ru, ?lang=en, ?lang=kk
Конфликт ID при импорте	Используйте новые ID профилей: импорт не перезаписывает прогресс

Ограничения

Приложение использует вымышленные данные и слушает 127.0.0.1. Демо-пароли не подходят для корпоративных данных: для внедрения нужны SSO/OIDC, HTTPS и управление аккаунтами. Выполнение — самоотчёт; ранг не означает подтверждённую квалификацию или автоматическое повышение в должности.

OpenAI — внешний сервис. Используются store=false, таймаут 20 секунд и отсутствие автоматических повторов. store=false не гарантирует отсутствие всех служебных журналов провайдера. При ошибке показывается локальный режим. LMS/HRM, магазин наград, MySQL и анализ речи пока не реализованы.