Alabuga Gamification Platform

Проект «Автостопом по Алабуге» — это геймифицированный гид по карьерной Галактике Алабуги. Как и в «Автостопом по Галактике», экипаж полагается на остроумные подсказки, лор и рейтинг пилотов, чтобы не потерять полотенце в бюрократических туманностях. Репозиторий содержит backend на FastAPI (Python 3.13) и фронтенд на Next.js (TypeScript).

Содержимое репозитория

• backend/ — FastAPI, SQLAlchemy, Alembic, бизнес-логика геймификации.
• frontend/ — Next.js с SSR, дизайн в космической стилистике.
• scripts/ — служебные скрипты (сидирование демо-данных).
• docs/ — документация, дополнительный лор.
• docker-compose.yaml — инфраструктура проекта.

Основные пользовательские сценарии

• Как кандидат: хочу проходить онбординг с лором и понимать своё место в программе.
• Как кандидат: хочу видеть прогресс-бар до следующего ранга и инструкции по ключевым веткам.
• Как кандидат: хочу получать награды (опыт, ману, артефакты) и видеть их в журнале.
• Как HR: хочу управлять миссиями, ветками, артефактами и требованиями рангов.
• Как HR: хочу видеть оперативную аналитику по активности и очереди модерации.

Быстрый старт в Docker

1. Установите Docker и Docker Compose.
2. Скопируйте пример конфигурации и при необходимости измените значения:

   cp backend/.env.example backend/.env
   cp frontend/.env.example frontend/.env
   

3. Запустите:

   make setup
   make start
   

4. После запуска будут доступны сервисы:
   • API: http://localhost:8000 (документация Swagger — /docs).
   • Фронтенд: http://localhost:3000.

Docker Compose автоматически переопределяет ALABUGA_SQLITE_PATH=/data/app.db, чтобы база сохранялась во внешнем volume. Для локального запуска вне Docker оставьте путь ./data/app.db из примера. Загружаемые кандидатами файлы помещаются в каталог, заданный переменной ALABUGA_UPLOADS_PATH (по умолчанию ./data/uploads).

Пользовательские учётные записи (сидированные)

Роль	Email	Пароль
Пилот	candidate@alabuga.space	orbita123
HR	hr@alabuga.space	orbita123

Проверка функционала

1. Регистрация: если хотите пройти сценарий «с нуля», откройте /register, заполните форму (имя, email, пароль, пожелания) и следуйте подсказкам. При отключённом подтверждении почты вы сразу попадёте на онбординг, при включённом — получите код на почту (в dev-режиме код отображается прямо в браузере).
2. Вход: откройте /login, авторизуйтесь как пилот (candidate@alabuga.space / orbita123) или HR (hr@alabuga.space / orbita123). После успешного входа пилот попадает на дашборд, HR — в админ-панель.
3. Онбординг и лор: под пилотом посетите /onboarding, прочитайте слайды и отметьте шаги выполненными. Прогресс сохраняется и открывает ветки миссий.
4. Кандидат: изучите дашборд (/), миссии (/missions) и журнал (/journal). Доступность миссий зависит от ранга и выполненных заданий.
5. Документы для миссии #1: на странице /missions/1 прикрепите паспорт (PDF/изображение), свежую фотографию и резюме (файл или ссылка). После отправки файлы можно скачать из блока «Загружено ранее».
6. Выполнение миссии: отправьте отчёт и документы, затем переключитесь на HR и одобрите выполнение — ранги, компетенции и мана обновятся автоматически.
7. HR панель: под HR-пользователем проверьте сводку, модерацию, редактирование веток/миссий/рангов, создание артефактов и аналитику (/admin). Для просмотра экрана кандидата используйте пункт «Просмотр от лица пилота» — он откроет / в режиме read-only и добавит кнопку «Вернуться к HR».
8. Магазин: вернитесь к пилоту, оформите заказ в /store — запись появится в журнале и очереди HR; при недостатке маны интерфейс подскажет, что делать.

Подтверждение электронной почты

По умолчанию вход не требует подтверждения почты (ALABUGA_REQUIRE_EMAIL_CONFIRMATION=false). Чтобы включить проверку:

1. Измените переменную ALABUGA_REQUIRE_EMAIL_CONFIRMATION в backend/.env и перезапустите API.
2. Пользователь должен запросить код через POST /auth/request-confirmation (в разработке код возвращается в ответе).
3. Затем подтвердите e-mail вызовом POST /auth/confirm с почтой и кодом. После этого вход станет доступен.

Демо-учётные записи в сид-данных имеют уже подтверждённый e-mail.

Тестирование

cd backend
pytest

Основные сценарии, реализованные в бэкенде

• Авторизация по email/паролю с JWT.
• Получение профиля пилота со списком компетенций и артефактов.
• Получение миссий, отправка отчётов, модерация HR.
• Начисление опыта, маны и повышение ранга по трём условиям из ТЗ.
• Журнал событий, экспортируемый через API.
• Магазин артефактов с оформлением заказа.
• Админ-панель для HR: модерация отчётов, управление ветками, миссиями и требованиями к рангам.
• Онбординг с сохранением прогресса и космическим лором.
• Таблица лидеров по опыту и мане за неделю/месяц/год.
• Аналитическая сводка для HR: активность пилотов, очередь модерации, завершённость веток.

Админ-инструменты доступны на странице /admin (используйте демо-пользователя HR). Здесь можно:

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

План развития

• Реализовать фронтенд-интерфейс всех экранов.
• Добавить экспорт CSV и агрегаты аналитики в API.
• Настроить CI/CD и автотесты во фреймворках фронтенда.
• Расширить документацию в docs/ (описание лора, сценарии e2e).