NextNodeTemplate/docs/USAGE_GUIDE.md

# Руководство по использованию улучшений шаблона

## 📋 Содержание

1. [Переменные окружения](#переменные-окружения)
2. [Логирование](#логирование)
3. [Валидация запросов](#валидация-запросов)
4. [Rate Limiting](#rate-limiting)
5. [Docker](#docker)
6. [CI/CD](#cicd)

## 🔐 Переменные окружения

### Установка dotenv

```powershell
cd backend
npm install
```

### Использование

1. Скопируйте `.env.example` в `.env`:
```powershell
Copy-Item backend\.env.example backend\.env
```

2. Заполните значения в `backend/.env`

3. Переменные автоматически загружаются при старте сервера

### Доступные переменные

- `PORT` - порт сервера (по умолчанию 3001)
- `NODE_ENV` - окружение (development/production)
- `LOG_LEVEL` - уровень логирования (error/warn/info/debug)

## 📝 Логирование

### Winston

Winston настроен для логирования в файлы и консоль.

### Логи создаются в `backend/logs/`:
- `error.log` - только ошибки
- `combined.log` - все логи

### Использование в коде:

```javascript
const logger = require('./config/logger');

// Разные уровни логирования
logger.error('Error message');
logger.warn('Warning message');
logger.info('Info message');
logger.debug('Debug message');

// С контекстом
logger.info('User login', { userId: 123, ip: '192.168.1.1' });
```

### Настройка уровня логирования

В `.env` файле:
```
LOG_LEVEL=debug  # error, warn, info, debug
```

## ✅ Валидация запросов

### Express-Validator

Используется для валидации входящих данных.

### Пример использования:

```javascript
const { body } = require('express-validator');
const validate = require('../middleware/validate');

router.post(
  '/endpoint',
  [
    body('email')
      .isEmail()
      .withMessage('Invalid email'),
    body('password')
      .isLength({ min: 8 })
      .withMessage('Password must be at least 8 characters'),
  ],
  validate,
  (req, res) => {
    // Валидация прошла успешно
    // req.body содержит проверенные данные
  }
);
```

### Доступные валидаторы:

- `body()` - валидация тела запроса
- `param()` - валидация параметров URL
- `query()` - валидация query параметров

### Популярные методы:

```javascript
body('field')
  .notEmpty()           // Не пустое
  .isEmail()            // Email формат
  .isLength({ min: 5 }) // Минимальная длина
  .isInt()              // Целое число
  .isFloat()            // Число с плавающей точкой
  .trim()               // Убрать пробелы
  .custom((value) => {  // Кастомная валидация
    // Ваша логика
    return true;
  })
```

## 🛡️ Rate Limiting

### Защита от злоупотреблений

Два уровня защиты настроены:

1. **Общий limiter** (`generalLimiter`):
   - 100 запросов за 15 минут
   - Применяется ко всем маршрутам

2. **Строгий limiter** (`strictLimiter`):
   - 20 запросов за 15 минут
   - Для важных endpoints

### Использование:

```javascript
const { strictLimiter } = require('../middleware/rateLimiter');

router.post('/api/sensitive', strictLimiter, (req, res) => {
  // Защищенный endpoint
});
```

### Настройка:

В `.env` (опционально):
```
RATE_LIMIT_WINDOW_MS=900000      # 15 минут в миллисекундах
RATE_LIMIT_MAX_REQUESTS=100      # Максимум запросов
```

## 🐳 Docker

### Установка Docker

Убедитесь, что Docker установлен на вашей системе.

### Структура:

- `Dockerfile` - для backend
- `Dockerfile.frontend` - для frontend
- `docker-compose.yml` - для разработки

### Использование Docker Compose:

```powershell
# Запустить все сервисы
docker-compose up -d

# Просмотр логов
docker-compose logs -f

# Остановить
docker-compose down

# Пересобрать
docker-compose up -d --build
```

### Отдельная сборка:

```powershell
# Backend
docker build -t my-app-backend -f Dockerfile .
docker run -p 3001:3001 my-app-backend

# Frontend
docker build -t my-app-frontend -f Dockerfile.frontend .
docker run -p 3000:3000 my-app-frontend
```

### Переменные окружения в Docker:

Создайте `.env` файл или используйте `env_file` в `docker-compose.yml`.

## 🔄 CI/CD

### GitHub Actions

Автоматическая проверка кода при push в репозиторий.

### Что проверяется:

- ✅ Установка зависимостей
- ✅ ESLint проверка
- ✅ Prettier форматирование
- ✅ Сборка frontend
- ✅ Проверка синтаксиса backend

### Файл: `.github/workflows/ci.yml`

Workflow автоматически запускается при:
- Push в ветки `main` или `dev`
- Pull Request в `main`

### Просмотр результатов:

В GitHub репозитории: **Actions** → выберите workflow run

## 🔧 Интеграция всех улучшений

### Пример полного endpoint:

```javascript
const express = require('express');
const { body } = require('express-validator');
const validate = require('../middleware/validate');
const { strictLimiter } = require('../middleware/rateLimiter');
const logger = require('../config/logger');

router.post(
  '/api/users',
  strictLimiter,
  [
    body('name')
      .trim()
      .notEmpty()
      .withMessage('Name is required'),
    body('email')
      .isEmail()
      .withMessage('Invalid email'),
  ],
  validate,
  async (req, res) => {
    try {
      logger.info('Creating user', { email: req.body.email });
      
      // Ваша логика
      const user = { /* ... */ };
      
      logger.info('User created successfully', { userId: user.id });
      res.json({ success: true, data: user });
    } catch (err) {
      logger.error('Error creating user', { error: err.message });
      res.status(500).json({ success: false, error: err.message });
    }
  }
);
```

## 📚 Дополнительные ресурсы

- [Express Validator документация](https://express-validator.github.io/docs/)
- [Winston документация](https://github.com/winstonjs/winston)
- [Express Rate Limit](https://github.com/express-rate-limit/express-rate-limit)
- [Docker документация](https://docs.docker.com/)