sto-k-odnomu/backend/README.md

# 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
```