238 lines
9.6 KiB
Markdown
238 lines
9.6 KiB
Markdown
# Backend - "100 к 1" Multiplayer Game
|
||
|
||
NestJS backend для мультиплеерной игры "100 к 1" с WebSocket поддержкой.
|
||
|
||
## 🚀 Быстрый старт
|
||
|
||
### Предварительные требования
|
||
|
||
- Node.js 18+
|
||
- PostgreSQL 15+ (должен быть запущен отдельно, например, в Coolify)
|
||
|
||
### Установка
|
||
|
||
**Важно:** PostgreSQL должен быть запущен отдельно как отдельное приложение. Все переменные окружения должны быть настроены в системе или через Coolify.
|
||
|
||
```bash
|
||
# 1. Установить зависимости
|
||
npm install
|
||
|
||
# 2. Настроить переменные окружения
|
||
# Переменные должны быть установлены в системе или через Coolify:
|
||
# - DATABASE_URL - строка подключения к PostgreSQL
|
||
# - JWT_SECRET - секретный ключ для JWT токенов
|
||
# - PORT - порт для backend (по умолчанию 3000)
|
||
# - HOST - хост для backend (по умолчанию 0.0.0.0)
|
||
# - CORS_ORIGIN - домен frontend приложения, с которого разрешены запросы (по умолчанию http://localhost:5173)
|
||
# ВАЖНО: CORS_ORIGIN - это домен frontend, а не backend!
|
||
|
||
# 3. Выполнить миграции
|
||
npx prisma migrate dev --name init
|
||
|
||
# 4. Заполнить демо-данными (опционально)
|
||
npm run prisma:seed
|
||
|
||
# 5. Сгенерировать Prisma Client
|
||
npx prisma generate
|
||
|
||
# 6. Запустить backend
|
||
npm run start:dev
|
||
```
|
||
|
||
Backend запустится на http://localhost:3000
|
||
|
||
## 📁 Структура проекта
|
||
|
||
```
|
||
backend/
|
||
├── src/
|
||
│ ├── auth/ # Модуль авторизации (JWT, анонимные пользователи)
|
||
│ ├── rooms/ # Модуль комнат (создание, присоединение)
|
||
│ ├── questions/ # Модуль паков вопросов (CRUD)
|
||
│ ├── game/ # WebSocket модуль (real-time игра)
|
||
│ ├── stats/ # Модуль статистики (история игр)
|
||
│ ├── prisma/ # Prisma сервис
|
||
│ ├── app.module.ts # Главный модуль
|
||
│ └── main.ts # Точка входа
|
||
├── prisma/
|
||
│ ├── schema.prisma # Схема базы данных
|
||
│ └── seed.ts # Seed скрипт с демо-данными
|
||
└── Dockerfile # Docker конфигурация
|
||
```
|
||
|
||
## 🗄️ База данных
|
||
|
||
### Модели
|
||
|
||
- **User** - пользователи (анонимные или зарегистрированные)
|
||
- **Room** - игровые комнаты
|
||
- **Participant** - участники комнат (игроки, ведущие, зрители)
|
||
- **QuestionPack** - паки вопросов
|
||
- **GameHistory** - история завершённых игр
|
||
|
||
### Миграции
|
||
|
||
```bash
|
||
# Создать новую миграцию
|
||
npx prisma migrate dev --name migration_name
|
||
|
||
# Применить миграции на production
|
||
npx prisma migrate deploy
|
||
|
||
# Сбросить базу данных (ВНИМАНИЕ: удалит все данные!)
|
||
npx prisma migrate reset
|
||
```
|
||
|
||
### Seed данные
|
||
|
||
Seed скрипт создаёт:
|
||
- Демо пользователя
|
||
- 2 пака вопросов (общие и семейные)
|
||
|
||
```bash
|
||
npm run prisma:seed
|
||
```
|
||
|
||
## 🔌 API Endpoints
|
||
|
||
### Auth
|
||
- POST /auth/anonymous - создать анонимного пользователя
|
||
- POST /auth/register - регистрация
|
||
- POST /auth/login - вход
|
||
|
||
### Rooms
|
||
- POST /rooms - создать комнату
|
||
- GET /rooms/:code - получить комнату по коду
|
||
- POST /rooms/:roomId/join - присоединиться к комнате
|
||
|
||
### Questions
|
||
- POST /questions/packs - создать пак вопросов
|
||
- GET /questions/packs - получить все паки
|
||
- GET /questions/packs/:id - получить пак по ID
|
||
- PUT /questions/packs/:id - обновить пак
|
||
- DELETE /questions/packs/:id - удалить пак
|
||
|
||
### Stats
|
||
- POST /stats/game-history - сохранить историю игры
|
||
- GET /stats/game-history/:userId - получить историю пользователя
|
||
- GET /stats/user/:userId - получить статистику пользователя
|
||
|
||
## 🌐 WebSocket Events
|
||
|
||
### Client → Server
|
||
- joinRoom - присоединиться к комнате
|
||
- startGame - начать игру
|
||
- revealAnswer - открыть ответ
|
||
- updateScore - обновить счёт
|
||
- nextQuestion - следующий вопрос
|
||
- endGame - завершить игру
|
||
|
||
### Server → Client
|
||
- roomUpdate - обновление комнаты
|
||
- gameStarted - игра началась
|
||
- answerRevealed - ответ открыт
|
||
- scoreUpdated - счёт обновлён
|
||
- questionChanged - вопрос изменён
|
||
- gameEnded - игра завершена
|
||
|
||
## 🔧 NPM Scripts
|
||
|
||
```bash
|
||
npm run start # Запуск в production режиме
|
||
npm run start:dev # Запуск в dev режиме с hot reload
|
||
npm run start:debug # Запуск в debug режиме
|
||
npm run build # Сборка для production
|
||
|
||
npm run lint # Проверка ESLint
|
||
npm run format # Форматирование кода (Prettier)
|
||
npm run test # Запуск тестов
|
||
npm run test:watch # Запуск тестов в watch режиме
|
||
npm run test:cov # Запуск тестов с coverage
|
||
|
||
npm run prisma:generate # Генерация Prisma Client
|
||
npm run prisma:migrate # Создание и применение миграции
|
||
npm run prisma:seed # Заполнение БД демо-данными
|
||
```
|
||
|
||
## 🔐 Переменные окружения
|
||
|
||
Приложение использует переменные окружения напрямую через `@nestjs/config`. Все переменные должны быть настроены в системе или через Coolify:
|
||
|
||
- `DATABASE_URL` - строка подключения к PostgreSQL (например: `postgresql://user:password@host:5432/dbname`)
|
||
- `JWT_SECRET` - секретный ключ для JWT токенов (см. ниже как сгенерировать)
|
||
- `PORT` - порт для backend (по умолчанию 3000)
|
||
- `HOST` - хост для backend (по умолчанию 0.0.0.0)
|
||
- `CORS_ORIGIN` - **домен frontend приложения**, с которого разрешены запросы к backend (по умолчанию http://localhost:5173)
|
||
|
||
### Что такое CORS_ORIGIN?
|
||
|
||
`CORS_ORIGIN` - это настройка безопасности CORS (Cross-Origin Resource Sharing). Она указывает backend, с каких доменов разрешено принимать HTTP и WebSocket запросы.
|
||
|
||
**Важно:** `CORS_ORIGIN` - это домен, где работает **frontend**, а не backend!
|
||
|
||
**Пример:**
|
||
- Frontend работает на: `https://example.com`
|
||
- Backend работает на: `https://api.example.com`
|
||
- `CORS_ORIGIN` должен быть: `https://example.com` (домен frontend)
|
||
|
||
Это защищает backend от запросов с неавторизованных доменов.
|
||
|
||
### 🔑 Как сгенерировать JWT_SECRET?
|
||
|
||
`JWT_SECRET` - это секретный ключ для подписи и проверки JWT токенов. Он используется для создания и проверки токенов авторизации.
|
||
|
||
**Требования к JWT_SECRET:**
|
||
- Должен быть случайным и криптографически стойким
|
||
- Минимум 32 символа, рекомендуется 64+ символа
|
||
- Уникальный для каждого приложения
|
||
- **Никогда не коммитьте в Git!**
|
||
|
||
**Способы генерации:**
|
||
|
||
1. **Node.js:**
|
||
```bash
|
||
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
|
||
```
|
||
|
||
2. **OpenSSL:**
|
||
```bash
|
||
openssl rand -hex 64
|
||
```
|
||
|
||
3. **Python:**
|
||
```bash
|
||
python3 -c "import secrets; print(secrets.token_hex(64))"
|
||
```
|
||
|
||
**Где использовать:**
|
||
- В Coolify: Добавьте переменную окружения `JWT_SECRET` в настройках приложения
|
||
- Локально: Можно использовать `.env` файл (но не коммитить его в Git!)
|
||
|
||
**⚠️ ВАЖНО:**
|
||
- Используйте **разные** `JWT_SECRET` для development и production
|
||
- Если измените `JWT_SECRET`, все существующие токены станут недействительными
|
||
- Храните секрет в безопасности - это критически важно для безопасности приложения
|
||
|
||
**Примечание:** PostgreSQL должен быть запущен отдельно как отдельное приложение в Coolify. Файлы `.env` не используются - все переменные берутся из переменных окружения системы.
|
||
|
||
## 📝 Prisma Studio
|
||
|
||
```bash
|
||
npx prisma studio
|
||
```
|
||
|
||
Откроется на http://localhost:5555
|
||
|
||
## 🚀 Production Deployment
|
||
|
||
```bash
|
||
# 1. Собрать проект
|
||
npm run build
|
||
|
||
# 2. Применить миграции
|
||
npx prisma migrate deploy
|
||
|
||
# 3. Запустить
|
||
npm run start:prod
|
||
```
|
||
|