sto-k-odnomu/README.md

# 100 к 1 - Multiplayer Game

Интерактивная веб-игра "100 к 1" с поддержкой мультиплеера и локальной игры.

## 🎮 Возможности

### 🌐 Мультиплеер (NEW!)
- **Игровые комнаты** с уникальными кодами
- **QR-коды** для быстрого присоединения
- **Real-time синхронизация** через WebSocket
- **Роли**: Ведущий, Игрок, Зритель
- **Статистика игр** с историей

### 🏠 Локальная игра
- Оригинальная версия для одного устройства
- Управление участниками
- Редактирование вопросов
- Автосохранение прогресса

## 🛠 Технологический стек

### Frontend
- **React 18.2** + **Vite 5.0**
- **React Router v6** - маршрутизация
- **Socket.IO Client** - WebSocket
- **Axios** - HTTP клиент
- **QRCode** - генерация QR-кодов

### Backend
- **NestJS** - TypeScript фреймворк
- **PostgreSQL** - база данных
- **Prisma ORM** - работа с БД
- **Socket.IO** - WebSocket сервер
- **JWT** - авторизация
- **Docker** - контейнеризация

## 📁 Структура проекта

```
sto_k_odnomu/
├── backend/               # NestJS Backend
│   ├── src/
│   │   ├── auth/          # Авторизация (JWT, анонимные)
│   │   ├── rooms/         # Модуль комнат
│   │   ├── questions/     # Паки вопросов
│   │   ├── game/          # WebSocket игра
│   │   ├── stats/         # Статистика
│   │   └── prisma/        # Prisma сервис
│   ├── prisma/
│   │   ├── schema.prisma  # Схема БД
│   │   └── seed.ts        # Seed данные
│   └── docker-compose.yml # Docker конфиг
│
├── src/                   # React Frontend
│   ├── pages/             # Страницы
│   │   ├── Home.jsx       # Главная
│   │   ├── CreateRoom.jsx # Создание комнаты
│   │   ├── JoinRoom.jsx   # Присоединение
│   │   ├── RoomPage.jsx   # Лобби комнаты
│   │   └── LocalGame.jsx  # Локальная игра
│   ├── services/          # API & WebSocket
│   ├── context/           # React Context
│   ├── hooks/             # Custom hooks
│   └── components/        # Компоненты игры
│
└── PLAN.md               # Детальный план разработки
```

## 🚀 Быстрый старт

### 1. Backend

```bash
cd backend

# Установить зависимости
npm install

# Настроить .env
cp .env.example .env

# Запустить PostgreSQL (Docker)
docker-compose up -d postgres

# Выполнить миграции
npx prisma migrate dev --name init

# Заполнить демо-данными
npm run prisma:seed

# Запустить backend
npm run start:dev
```

Backend: http://localhost:3000

### 2. Frontend

```bash
# В корне проекта
npm install
npm run dev
```

Frontend: http://localhost:5173

## 🎯 Как играть

### Мультиплеер

1. **Главная страница** → Выберите действие
2. **Создать комнату**:
   - Выберите пак вопросов
   - Настройте параметры
   - Поделитесь кодом/QR с игроками
3. **Присоединиться**:
   - Введите 6-значный код комнаты
   - Или отсканируйте QR-код
4. **Начать игру** (ведущий)
5. Игроки открывают ответы в реальном времени

### Локальная игра

1. Главная → **Локальная игра**
2. Добавьте участников (👥)
3. Играйте на одном устройстве

## 📊 API Endpoints

### REST API

- **Auth**: `/auth/anonymous`, `/auth/register`, `/auth/login`
- **Rooms**: `/rooms` (POST, GET), `/rooms/:code`, `/rooms/:id/join`
- **Questions**: `/questions/packs` (CRUD)
- **Stats**: `/stats/game-history/:userId`, `/stats/user/:userId`

### WebSocket Events

**Client → Server:**
- `joinRoom`, `startGame`, `revealAnswer`, `updateScore`, `nextQuestion`, `endGame`

**Server → Client:**
- `roomUpdate`, `gameStarted`, `answerRevealed`, `scoreUpdated`, `questionChanged`, `gameEnded`

## 🗄️ База данных

### Модели (Prisma)

- **User** - пользователи (анонимные/зарегистрированные)
- **Room** - игровые комнаты
- **Participant** - участники (HOST/PLAYER/SPECTATOR)
- **QuestionPack** - паки вопросов
- **GameHistory** - история игр

### Seed данные

- Демо пользователь
- 2 пака вопросов (общие, семейные)

## 🐳 Docker

```bash
# Backend + PostgreSQL
cd backend
docker-compose up -d

# Только PostgreSQL
docker-compose up -d postgres
```

## 📝 Разработка

### Backend

```bash
cd backend
npm run start:dev      # Dev режим
npm run build          # Сборка
npm run test           # Тесты
npx prisma studio      # DB GUI
```

### Frontend

```bash
npm run dev            # Dev сервер
npm run build          # Сборка
npm run preview        # Preview build
```

## 🔐 Безопасность

- JWT токены для авторизации
- CORS настройка
- Валидация данных (class-validator)
- PostgreSQL для надёжного хранения

## 📄 Документация

- [Backend README](backend/README.md) - детальная документация backend
- [PLAN.md](PLAN.md) - полный план разработки
- [API Documentation](backend/README.md#-api-endpoints) - REST и WebSocket API

## 🎨 Особенности

- ❄️ Новогодняя анимация снежинок
- 🎨 Адаптивный дизайн
- 💾 Автосохранение прогресса
- 🔄 Real-time синхронизация
- 📱 QR-коды для присоединения
- 📊 Статистика и история игр

## 🚧 Roadmap

- [x] Backend инфраструктура
- [x] Frontend интеграция
- [x] WebSocket real-time
- [x] Игровые комнаты
- [x] QR-коды
- [ ] Таймер ответов
- [ ] Экспорт статистики (PDF)
- [ ] Публичные комнаты
- [ ] Рейтинг игроков

## 📜 Лицензия

Private project

---

**Сделано с ❤️ для семейных праздников**