121 lines
7.5 KiB
Markdown
121 lines
7.5 KiB
Markdown
# 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
|
||
|
||
# применяем миграции
|
||
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; при недостатке маны интерфейс подскажет, что делать.
|
||
|
||
## Тестирование
|
||
|
||
```bash
|
||
cd backend
|
||
pytest
|
||
```
|
||
|
||
## Основные сценарии, реализованные в бэкенде
|
||
|
||
- Авторизация по email/паролю с JWT.
|
||
- Получение профиля пилота со списком компетенций и артефактов.
|
||
- Получение миссий, отправка отчётов, модерация HR.
|
||
- Начисление опыта, маны и повышение ранга по трём условиям из ТЗ.
|
||
- Журнал событий, экспортируемый через API.
|
||
- Магазин артефактов с оформлением заказа.
|
||
- Админ-панель для HR: модерация отчётов, управление ветками, миссиями и требованиями к рангам.
|
||
- Онбординг с сохранением прогресса и космическим лором.
|
||
- Таблица лидеров по опыту и мане за неделю/месяц/год.
|
||
- Аналитическая сводка для HR: активность пилотов, очередь модерации, завершённость веток.
|
||
|
||
Админ-инструменты доступны на странице `/admin` (используйте демо-пользователя HR). Здесь можно:
|
||
|
||
- создавать и редактировать ветки миссий с категориями и порядком;
|
||
- подготавливать новые миссии с наградами, зависимостями, ветками и компетенциями;
|
||
- настраивать ранги: требуемый опыт, обязательные миссии и уровни компетенций.
|
||
- управлять каталогом артефактов и назначать их миссиям.
|
||
|
||
## План развития
|
||
|
||
- Реализовать фронтенд-интерфейс всех экранов.
|
||
- Добавить экспорт CSV и агрегаты аналитики в API.
|
||
- Настроить CI/CD и автотесты во фреймворках фронтенда.
|
||
- Расширить документацию в `docs/` (описание лора, сценарии e2e).
|