# 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. Скопируйте пример конфигурации и при необходимости измените значения:
   ```bash
   cp backend/.env.example backend/.env
   cp frontend/.env.example frontend/.env
   ```
3. Запустите окружение:
   ```bash
   docker compose up --build
   ```
4. После запуска будут доступны сервисы:
   - API: http://localhost:8000 (документация Swagger — `/docs`).
   - Фронтенд: http://localhost:3000.

Docker Compose автоматически переопределяет `ALABUGA_SQLITE_PATH=/data/app.db`, чтобы база сохранялась во внешнем volume. Для локального запуска вне Docker оставьте путь `./data/app.db` из примера.

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

```bash
cd backend
python -m venv .venv
source .venv/bin/activate
export PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1
pip install -r requirements-dev.txt

# подготовьте переменные окружения (однократно)
cp .env.example .env

# при необходимости включите в .env подтверждение почты
# ALABUGA_REQUIRE_EMAIL_CONFIRMATION=true

# применяем миграции
alembic upgrade head

# создаём демо-данные (команда выполняется из корня репозитория)
cd ..
python -m scripts.seed_data
cd backend

# Запуск API
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

## Локальная разработка фронтенда

```bash
cd frontend
npm install
cp .env.example .env
npm run dev
```

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

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

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

1. **Вход**: откройте `/login`, авторизуйтесь как пилот (`candidate@alabuga.space / orbita123`) или HR (`hr@alabuga.space / orbita123`). После успешного входа пилот попадает на дашборд, HR — в админ-панель.
2. **Онбординг и лор**: под пилотом посетите `/onboarding`, прочитайте слайды и отметьте шаги выполненными. Прогресс сохраняется и открывает ветки миссий.
3. **Кандидат**: изучите дашборд (`/`), миссии (`/missions`) и журнал (`/journal`). Доступность миссий зависит от ранга и выполненных заданий.
4. **Выполнение миссии**: откройте карточку миссии, отправьте доказательство. Переключитесь на HR и одобрите выполнение — ранги, компетенции и мана обновятся автоматически.
5. **HR панель**: под HR-пользователем проверьте сводку, модерацию, редактирование веток/миссий/рангов, создание артефактов и аналитику (`/admin`).
6. **Магазин**: вернитесь к пилоту, оформите заказ в `/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.

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

```bash
cd backend
pytest
```

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

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

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

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

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

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