114 lines
9.9 KiB
Markdown
114 lines
9.9 KiB
Markdown
# «Автостопом по Алабуге»
|
||
|
||
Проект «Автостопом по Алабуге» — это геймифицированный гид по карьерной Галактике Алабуги. Как и в «Автостопом по Галактике», экипаж полагается на остроумные подсказки, лор и рейтинг пилотов, чтобы не потерять полотенце в бюрократических туманностях. Репозиторий содержит 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
|
||
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; при недостатке маны интерфейс подскажет, что делать.
|
||
9. **Лидерборд**: откройте `/leaderboard` (доступно и пилотам, и 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
|
||
python -m scripts.reset_demo_data
|
||
```
|
||
|
||
Скрипт прогонит миграции, очистит таблицы `mission_submissions`, `orders`, `journal_entries`, сбросит опыт/ману пользователей и удалит весь каталог с загруженными документами (`ALABUGA_UPLOADS_PATH`).
|
||
|
||
## Тестирование
|
||
|
||
```bash
|
||
cd backend
|
||
pytest
|
||
```
|
||
|
||
## Основные сценарии, реализованные в бэкенде
|
||
|
||
- Авторизация по email/паролю с JWT.
|
||
- Получение профиля пилота со списком компетенций и артефактов.
|
||
- Получение миссий, отправка отчётов, модерация HR.
|
||
- Начисление опыта, маны и повышение ранга по трём условиям из ТЗ.
|
||
- Журнал событий, экспортируемый через API.
|
||
- Магазин артефактов с оформлением заказа.
|
||
- Админ-панель для HR: модерация отчётов, управление ветками, миссиями и требованиями к рангам.
|
||
- Онбординг с сохранением прогресса и космическим лором.
|
||
- Таблица лидеров по опыту и мане за неделю/месяц/год.
|
||
- Аналитическая сводка для HR: активность пилотов, очередь модерации, завершённость веток.
|
||
- Лидерборд пилотов по опыту с отображением ключевых компетенций.
|
||
|
||
Админ-инструменты доступны на странице `/admin` (используйте демо-пользователя HR). Здесь можно:
|
||
|
||
- создавать и редактировать ветки миссий с категориями и порядком;
|
||
- подготавливать новые миссии с наградами, зависимостями, ветками и компетенциями;
|
||
- настраивать ранги: требуемый опыт, обязательные миссии и уровни компетенций.
|
||
- управлять каталогом артефактов и назначать их миссиям.
|
||
|
||
## План развития
|
||
|
||
- Реализовать фронтенд-интерфейс всех экранов.
|
||
- Добавить экспорт CSV и агрегаты аналитики в API.
|
||
- Настроить CI/CD и автотесты во фреймворках фронтенда.
|
||
- Расширить документацию в `docs/` (описание лора, сценарии e2e).
|