sfera-new/docs/infrastructure/DEPLOYMENT_GUIDE.md

# Руководство по развертыванию SFERA

## 🚀 Обзор

Это комплексное руководство по развертыванию платформы SFERA в различных окружениях - от локальной разработки до production развертывания с использованием Docker и оркестрации контейнеров.

## 📋 Требования к системе

### Минимальные требования

- **CPU**: 2 ядра (4 рекомендуется для production)
- **RAM**: 4GB (8GB рекомендуется для production)
- **Диск**: 20GB свободного места (SSD рекомендуется)
- **OS**: Linux Ubuntu 20.04+, CentOS 8+, или macOS 11+

### Программное обеспечение

- **Node.js**: 18.17.0+ (LTS рекомендуется)
- **npm**: 9.0.0+
- **Docker**: 24.0.0+
- **Docker Compose**: 2.20.0+
- **PostgreSQL**: 14+ (для прямого подключения)
- **Git**: 2.30.0+

## 🛠 Локальная разработка

### 1. Клонирование репозитория

```bash
git clone <repository-url>
cd sfera
```

### 2. Установка зависимостей

```bash
# Установка Node.js зависимостей
npm install

# Генерация Prisma клиента
npx prisma generate
```

### 3. Настройка окружения

Создайте файл `.env.local`:

```env
# База данных
DATABASE_URL="postgresql://user:password@localhost:5432/sfera_dev"

# SMS сервис (разработка)
SMS_AERO_EMAIL="test@example.com"
SMS_AERO_API_KEY="test-key"
SMS_AERO_API_URL="https://gate.smsaero.ru/v2"
SMS_DEV_MODE="true"

# DaData API
DADATA_API_KEY="your-dadata-key"
DADATA_API_URL="https://suggestions.dadata.ru/suggestions/api/4_1/rs"

# Marketplace APIs
WILDBERRIES_API_URL="https://common-api.wildberries.ru"
OZON_API_URL="https://api-seller.ozon.ru"

# JWT секрет
JWT_SECRET="your-super-secret-jwt-key-for-development"

# Next.js
NEXT_TELEMETRY_DISABLED=1
```

### 4. Настройка базы данных

```bash
# Применение миграций
npx prisma migrate dev

# Заполнение начальными данными (опционально)
npx prisma db seed
```

### 5. Запуск приложения

```bash
# Режим разработки
npm run dev

# Приложение будет доступно на http://localhost:3000
```

## 🐳 Docker развертывание

### Структура Docker файлов

```
sfera/
├── Dockerfile                 # Основной образ приложения
├── docker-compose.yml        # Локальная оркестрация
├── docker-compose.prod.yml   # Production конфигурация
├── .env                      # Переменные окружения
└── stack.env                # Production переменные
```

### Локальный Docker запуск

```bash
# Сборка и запуск всех сервисов
docker-compose up --build

# Запуск в фоновом режиме
docker-compose up -d

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

# Остановка сервисов
docker-compose down
```

### Production Docker развертывание

#### 1. Подготовка окружения

```bash
# Создание production переменных
cp .env stack.env

# Редактирование production конфигурации
nano stack.env
```

#### 2. Production переменные окружения

```env
# DATABASE
DATABASE_URL="postgresql://sfera_user:secure_password@db_host:5432/sfera_prod"

# Security
JWT_SECRET="super-secure-production-jwt-secret-256-bit"

# SMS сервис
SMS_AERO_EMAIL="production@company.com"
SMS_AERO_API_KEY="production-sms-key"
SMS_DEV_MODE="false"

# API ключи
DADATA_API_KEY="production-dadata-key"
WILDBERRIES_API_URL="https://common-api.wildberries.ru"
OZON_API_URL="https://api-seller.ozon.ru"

# System
NODE_ENV="production"
NEXT_TELEMETRY_DISABLED=1
```

#### 3. Production сборка

```bash
# Сборка production образа
docker build -t sfera:latest \
  --build-arg DATABASE_URL="${DATABASE_URL}" \
  --build-arg JWT_SECRET="${JWT_SECRET}" \
  --build-arg SMS_AERO_EMAIL="${SMS_AERO_EMAIL}" \
  --build-arg SMS_AERO_API_KEY="${SMS_AERO_API_KEY}" \
  --build-arg DADATA_API_KEY="${DADATA_API_KEY}" \
  .

# Запуск production контейнера
docker run -d \
  --name sfera-app \
  --env-file stack.env \
  -p 3017:3000 \
  --restart unless-stopped \
  sfera:latest
```

## 🏗 Multi-stage Docker архитектура

### Описание этапов сборки

#### 1. Base Stage

```dockerfile
FROM node:18-alpine AS base
```

- Базовый образ с Node.js 18 Alpine
- Минимальный размер для оптимизации

#### 2. Dependencies Stage

```dockerfile
FROM base AS deps
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm ci
```

- Установка только production зависимостей
- Кэширование слоя зависимостей

#### 3. Builder Stage

```dockerfile
FROM base AS builder
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npx prisma generate
RUN npm run build
```

- Генерация Prisma клиента
- Сборка Next.js приложения
- TypeScript компиляция

#### 4. Runner Stage

```dockerfile
FROM base AS runner
ENV NODE_ENV production
USER nextjs
COPY --from=builder /app/.next/standalone ./
```

- Минимальный runtime образ
- Непривилегированный пользователь
- Только необходимые файлы

## 🔧 Конфигурация Next.js для Production

### next.config.ts оптимизации

```typescript
const nextConfig: NextConfig = {
  // Standalone режим для Docker
  output: 'standalone',

  // Production проверки
  eslint: {
    ignoreDuringBuilds: false,
    dirs: ['src'],
  },
  typescript: {
    ignoreBuildErrors: false,
  },

  // Оптимизация изображений
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 's3.twcstorage.ru',
        port: '',
        pathname: '/**',
      },
    ],
  },

  // Экспериментальные оптимизации
  experimental: {
    optimizePackageImports: ['lucide-react'],
  },
}
```

## 🎯 Healthcheck и мониторинг

### Docker Healthcheck

```dockerfile
# В Dockerfile
RUN apk add --no-cache wget
```

```yaml
# В docker-compose.yml
healthcheck:
  test: ['CMD', 'wget', '--no-verbose', '--tries=1', '--spider', 'http://localhost:3000/api/health']
  timeout: 10s
  interval: 30s
  retries: 3
  start_period: 40s
```

### API Endpoint для проверки состояния

Создание `/app/api/health/route.ts`:

```typescript
import { NextResponse } from 'next/server'
import { PrismaClient } from '@prisma/client'

export async function GET() {
  try {
    const prisma = new PrismaClient()

    // Проверка подключения к базе данных
    await prisma.$queryRaw`SELECT 1`

    return NextResponse.json({
      status: 'healthy',
      timestamp: new Date().toISOString(),
      services: {
        database: 'connected',
        application: 'running',
      },
    })
  } catch (error) {
    return NextResponse.json(
      {
        status: 'unhealthy',
        timestamp: new Date().toISOString(),
        error: error.message,
      },
      { status: 500 },
    )
  }
}
```

## 📊 Производительность и оптимизация

### Сборка оптимизации

1. **Bundle Analysis**

```bash
# Анализ размера бандла
npm run analyze

# С помощью @next/bundle-analyzer
ANALYZE=true npm run build
```

2. **Image Optimization**

- Использование Next.js Image компонента
- Поддержка WebP/AVIF форматов
- Lazy loading по умолчанию

3. **Code Splitting**

- Автоматическое разделение по страницам
- Dynamic imports для больших компонентов
- Lazy loading библиотек

### Runtime оптимизации

```typescript
// Lazy loading компонентов
const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
  loading: () => <p>Загрузка...</p>,
})

// Мемоизация дорогих вычислений
const expensiveValue = useMemo(() => {
  return heavyCalculation(data)
}, [data])

// React.memo для предотвращения лишних рендеров
const OptimizedComponent = memo(({ data }) => {
  return <div>{data}</div>
})
```

## 🔐 Безопасность развертывания

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

```bash
# Генерация безопасного JWT секрета
openssl rand -hex 32

# Использование Docker secrets
echo "my-secret" | docker secret create jwt_secret -
```

### 2. Пользователи и права

```dockerfile
# Создание непривилегированного пользователя
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
USER nextjs
```

### 3. Network security

```yaml
# docker-compose.yml
networks:
  app-network:
    driver: bridge
    internal: true
```

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

### Производственная настройка PostgreSQL

```bash
# Создание пользователя и базы данных
sudo -u postgres psql
CREATE USER sfera_user WITH PASSWORD 'secure_password';
CREATE DATABASE sfera_prod OWNER sfera_user;
GRANT ALL PRIVILEGES ON DATABASE sfera_prod TO sfera_user;
```

### Миграции в Production

```bash
# Проверка статуса миграций
npx prisma migrate status

# Применение миграций
npx prisma migrate deploy

# Создание администратора (если нужно)
node scripts/create-admin.mjs
```

### Backup стратегия

```bash
# Ежедневный backup
pg_dump -h localhost -U sfera_user -d sfera_prod > backup_$(date +%Y%m%d).sql

# Автоматический backup через cron
0 2 * * * pg_dump -h localhost -U sfera_user -d sfera_prod > /backups/sfera_$(date +\%Y\%m\%d).sql
```

## 🔄 CI/CD Pipeline

### GitHub Actions пример

```yaml
name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Type check
        run: npm run typecheck

      - name: Lint
        run: npm run lint

      - name: Build Docker image
        run: |
          docker build -t sfera:${{ github.sha }} .
          docker tag sfera:${{ github.sha }} sfera:latest

      - name: Deploy to production
        run: |
          docker-compose -f docker-compose.prod.yml down
          docker-compose -f docker-compose.prod.yml up -d
```

## 🚨 Troubleshooting

### Частые проблемы

#### 1. Database connection errors

```bash
# Проверка подключения к БД
npx prisma db execute --preview-feature --stdin <<< "SELECT 1;"

# Перегенерация Prisma клиента
npx prisma generate
```

#### 2. Permission denied

```bash
# Проверка прав на файлы
ls -la .next/standalone/server.js

# Исправление прав
chmod +x .next/standalone/server.js
```

#### 3. Memory issues

```bash
# Увеличение Node.js heap size
NODE_OPTIONS="--max-old-space-size=4096" npm run build

# В Docker
ENV NODE_OPTIONS="--max-old-space-size=2048"
```

#### 4. Build failures

```bash
# Очистка кэша
rm -rf .next node_modules
npm install
npm run build

# Проверка TypeScript ошибок
npm run typecheck
```

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

```typescript
// Структурированное логирование
const logger = {
  info: (message: string, meta?: object) => {
    console.log(
      JSON.stringify({
        level: 'info',
        message,
        timestamp: new Date().toISOString(),
        ...meta,
      }),
    )
  },
  error: (message: string, error?: Error, meta?: object) => {
    console.error(
      JSON.stringify({
        level: 'error',
        message,
        error: error?.stack,
        timestamp: new Date().toISOString(),
        ...meta,
      }),
    )
  },
}
```

## 📈 Масштабирование

### Горизонтальное масштабирование

```yaml
# docker-compose.prod.yml
version: '3.8'
services:
  app:
    image: sfera:latest
    deploy:
      replicas: 3
      restart_policy:
        condition: on-failure
    ports:
      - '3017-3019:3000'
```

### Load Balancer конфигурация (Nginx)

```nginx
upstream sfera_backend {
    server localhost:3017;
    server localhost:3018;
    server localhost:3019;
}

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://sfera_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

## 🎯 Заключение

Это руководство покрывает полный цикл развертывания SFERA от локальной разработки до production окружения. Ключевые принципы:

1. **Безопасность**: Использование секретов, непривилегированных пользователей
2. **Производительность**: Multi-stage сборка, оптимизация образов
3. **Надежность**: Healthchecks, автоматический restart, backup
4. **Масштабируемость**: Готовность к горизонтальному масштабированию
5. **Мониторинг**: Структурированные логи, метрики производительности

Следуйте этому руководству для надежного и безопасного развертывания платформы SFERA в любом окружении.