sfera-new/docs/development/TECHNICAL_STACK.md

# ТЕХНОЛОГИЧЕСКИЙ СТЕК SFERA

## 🎯 ОБЗОР АРХИТЕКТУРЫ

SFERA - это современное B2B веб-приложение, построенное на основе full-stack TypeScript стека с акцентом на производительность, типобезопасность и масштабируемость. Система использует Next.js 15 для серверного рендеринга, GraphQL для API, PostgreSQL для данных и современные UI-библиотеки для интерфейса.

## 🏗️ ОСНОВНОЙ СТЕК

### Frontend

```json
{
  "framework": "Next.js 15.4.1",
  "runtime": "React 19.1.0",
  "language": "TypeScript 5",
  "styling": "Tailwind CSS 4",
  "ui_library": "Radix UI",
  "state_management": "Apollo Client + React Hooks",
  "bundler": "Next.js (Turbopack в dev)",
  "icons": "Lucide React"
}
```

### Backend

```json
{
  "framework": "Next.js API Routes",
  "api_layer": "GraphQL (Apollo Server 4.12.2)",
  "database_client": "Prisma ORM 6.12.0",
  "database": "PostgreSQL",
  "authentication": "JWT (jsonwebtoken)",
  "file_upload": "AWS S3 SDK",
  "sms_service": "SMS Aero API",
  "data_validation": "DaData API"
}
```

### DevOps & Deployment

```json
{
  "containerization": "Docker",
  "orchestration": "Docker Compose",
  "code_quality": "ESLint 9 + Prettier",
  "git_hooks": "Husky + lint-staged",
  "build_optimization": "Next.js Standalone Output"
}
```

## 📦 ДЕТАЛЬНЫЙ АНАЛИЗ ЗАВИСИМОСТЕЙ

### Core Framework (Next.js 15 + React 19)

```typescript
// next.config.ts - Production-ready конфигурация
const nextConfig: NextConfig = {
  output: 'standalone', // Оптимизированная сборка для Docker
  eslint: {
    ignoreDuringBuilds: false, // Строгая проверка в production
    dirs: ['src'],
  },
  typescript: {
    ignoreBuildErrors: false, // Полная проверка типов
  },
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 's3.twcstorage.ru', // S3-совместимое хранилище
        pathname: '/**',
      },
    ],
  },
  experimental: {
    optimizePackageImports: ['lucide-react'], // Tree-shaking оптимизация
  },
}
```

**Преимущества выбора:**

- **App Router**: Современная архитектура маршрутизации Next.js 15
- **Server Components**: Серверный рендеринг для улучшения производительности
- **Turbopack**: Ускоренная сборка в dev-режиме
- **React 19**: Новейшие возможности Concurrent Features

### GraphQL API Stack

```typescript
// Apollo Server конфигурация
const server = new ApolloServer<Context>({
  typeDefs, // GraphQL схемы
  resolvers, // Резолверы запросов
  plugins: [
    {
      requestDidStart() {
        return {
          didResolveOperation(requestContext) {
            // Логирование всех GraphQL запросов
            console.warn('🌐 GraphQL REQUEST:', {
              operationType: operation.operation,
              operationName: requestContext.request.operationName,
              timestamp: new Date().toISOString(),
            })
          },
        }
      },
    },
  ],
})

// Apollo Client конфигурация с кэшированием
export const apolloClient = new ApolloClient({
  link: from([authLink, httpLink]),
  cache: new InMemoryCache({
    typePolicies: {
      User: {
        fields: {
          organization: { merge: true }, // Умное слияние данных
        },
      },
      Organization: {
        fields: {
          apiKeys: { merge: false }, // Замена массива целиком
        },
      },
    },
  }),
  defaultOptions: {
    watchQuery: { errorPolicy: 'all' }, // Показ частичных данных при ошибках
    query: { errorPolicy: 'all' },
  },
})
```

**Архитектурные решения:**

- **Type-First подход**: GraphQL схемы как источник истины
- **Context-based аутентификация**: JWT токены в заголовках
- **Intelligent Caching**: Настроенные политики кэширования
- **Error Handling**: Graceful degradation при частичных ошибках

### Database Layer (Prisma + PostgreSQL)

```typescript
// prisma/schema.prisma - Основные модели
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

// Пример сложной модели с индексами
model Organization {
  id                         String                @id @default(cuid())
  inn                        String                @unique
  type                       OrganizationType      // FULFILLMENT | SELLER | LOGIST | WHOLESALE

  // Связи с другими сущностями
  users                      User[]
  products                   Product[]
  messages                   Message[]             @relation("SentMessages")
  supplyOrders               SupplyOrder[]

  // Индексы для производительности
  @@index([referralCode])
  @@index([referredById])
}

// Prisma Client инициализация
export const prisma = globalThis.prisma || new PrismaClient()

if (process.env.NODE_ENV !== 'production') {
  globalThis.prisma = prisma  // Повторное использование в dev
}
```

**База данных и ORM:**

- **PostgreSQL**: Надежная реляционная СУБД
- **Prisma ORM**: Type-safe доступ к данным
- **CUID**: Collision-resistant уникальные идентификаторы
- **Составные индексы**: Оптимизация сложных запросов
- **Connection Pooling**: Эффективное управление соединениями

### UI/UX Stack

```typescript
// Radix UI + Tailwind CSS компоненты
export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, asChild = false, ...props }, ref) => {
    const Comp = asChild ? Slot : "button"
    return (
      <Comp
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        {...props}
      />
    )
  }
)

// Class Variance Authority для типизированных вариантов
const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input bg-background hover:bg-accent"
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
        lg: "h-11 rounded-md px-8",
        icon: "h-10 w-10"
      }
    },
    defaultVariants: {
      variant: "default",
      size: "default"
    }
  }
)
```

**UI Библиотеки:**

- **Radix UI**: Headless компоненты с accessibility
- **Tailwind CSS 4**: Utility-first стилизация
- **Class Variance Authority**: Типизированные варианты компонентов
- **Lucide React**: 1000+ SVG иконок с tree-shaking
- **React Resizable Panels**: Панели с изменяемыми размерами
- **Sonner**: Современные toast уведомления

### TypeScript Configuration

```json
// tsconfig.json - Строгая типизация
{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "strict": true, // Включаем все строгие проверки
    "noEmit": true, // Только проверка типов, сборка через Next.js
    "module": "esnext",
    "moduleResolution": "bundler", // Новая стратегия разрешения модулей
    "paths": {
      "@/*": ["./src/*"] // Absolute imports
    }
  }
}
```

**TypeScript Features:**

- **Strict Mode**: Максимальная типобезопасность
- **Path Mapping**: Absolute imports для чистоты кода
- **Bundler Resolution**: Совместимость с современными bundler'ами
- **GraphQL Codegen**: Автогенерация типов из схем (планируется)

## 🔧 ИНТЕГРАЦИИ И СЕРВИСЫ

### External APIs

```typescript
// SMS Service Integration
const SMS_CONFIG = {
  provider: 'SMS Aero',
  api_url: 'https://gate.smsaero.ru/v2',
  features: ['send', 'status', 'balance'],
  dev_mode: process.env.SMS_DEV_MODE === 'true', // Mock в разработке
}

// Data Validation Service
const DADATA_CONFIG = {
  provider: 'DaData',
  api_url: 'https://suggestions.dadata.ru/suggestions/api/4_1/rs',
  features: ['inn_validation', 'address_suggestions', 'company_info'],
}

// Marketplace APIs
const MARKETPLACE_APIS = {
  wildberries: {
    api_url: process.env.WILDBERRIES_API_URL,
    features: ['products', 'orders', 'analytics', 'returns'],
  },
  ozon: {
    api_url: process.env.OZON_API_URL,
    features: ['products', 'orders', 'analytics'],
  },
}
```

### File Storage (S3-Compatible)

```typescript
// AWS S3 SDK конфигурация
import { S3Client } from '@aws-sdk/client-s3'

const s3Client = new S3Client({
  region: 'ru-central1',
  endpoint: 'https://s3.twcstorage.ru',
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY,
    secretAccessKey: process.env.S3_SECRET_KEY,
  },
})

// Типизированная загрузка файлов
interface FileUploadOptions {
  bucket: string
  key: string
  file: File | Buffer
  contentType?: string
  metadata?: Record<string, string>
}
```

## 🐳 DEPLOYMENT & CONTAINERIZATION

### Docker Multi-Stage Build

```dockerfile
# Оптимизированный Dockerfile
FROM node:18-alpine AS base

# Зависимости
FROM base AS deps
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm ci

# Сборка
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Build-time переменные окружения
ARG DATABASE_URL
ARG JWT_SECRET
ENV DATABASE_URL=$DATABASE_URL
ENV JWT_SECRET=$JWT_SECRET
ENV NODE_ENV=production

# Генерация Prisma Client и сборка
RUN npx prisma generate
RUN npm run build
RUN npm prune --production

# Production образ
FROM base AS runner
WORKDIR /app
ENV NODE_ENV=production

# Standalone output для минимального размера
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/prisma ./prisma
COPY --from=builder /app/node_modules/.prisma ./node_modules/.prisma

EXPOSE 3000
CMD ["node", "server.js"]
```

**Containerization преимущества:**

- **Multi-stage build**: Минимальный размер production образа
- **Standalone output**: Next.js оптимизация для контейнеров
- **Alpine Linux**: Безопасный и легкий базовый образ
- **Non-root user**: Повышенная безопасность контейнера
- **Health checks**: Мониторинг состояния приложения

### Environment Management

```bash
# .env - Production переменные
DATABASE_URL="postgresql://user:pass@host:5432/db"

# SMS сервис
SMS_AERO_EMAIL="company@domain.ru"
SMS_AERO_API_KEY="secret_key"
SMS_DEV_MODE="false"

# Внешние API
DADATA_API_KEY="secret_key"
WILDBERRIES_API_KEY="secret_key"

# Security
JWT_SECRET="complex_jwt_secret_key"

# Storage
S3_ACCESS_KEY="access_key"
S3_SECRET_KEY="secret_key"
```

## ⚡ ПРОИЗВОДИТЕЛЬНОСТЬ И ОПТИМИЗАЦИИ

### Build Optimizations

```json
// package.json - Scripts для production
{
  "scripts": {
    "dev": "next dev --turbopack", // Turbopack в разработке
    "build": "next build", // Optimized production build
    "start": "next start", // Production server
    "lint": "next lint", // ESLint проверка
    "lint:fix": "next lint --fix", // Автоисправление
    "db:reset": "npx prisma db push --force-reset && npm run db:seed"
  }
}
```

### Code Quality Tools

```json
// ESLint + Prettier конфигурация
{
  "lint-staged": {
    "src/**/*.{js,jsx,ts,tsx,json,css,md}": ["prettier --write", "eslint --fix"]
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "pre-push": "npm run typecheck"
    }
  }
}
```

**Performance Features:**

- **Tree Shaking**: Исключение неиспользуемого кода
- **Code Splitting**: Автоматическое разделение бандлов
- **Image Optimization**: Next.js Image компонент
- **Bundle Analysis**: webpack-bundle-analyzer интеграция
- **Caching Strategy**: Многоуровневое кэширование (Browser, CDN, Database)

## 📊 МОНИТОРИНГ И АНАЛИТИКА

### Logging & Debugging

```typescript
// Структурированное логирование GraphQL
plugins: [
  {
    requestDidStart() {
      return {
        didResolveOperation(requestContext) {
          console.warn('🌐 GraphQL REQUEST:', {
            operationType: operation.operation,
            operationName: requestContext.request.operationName,
            timestamp: new Date().toISOString(),
            variables: requestContext.request.variables,
          })
        },
        didEncounterErrors(requestContext) {
          console.error('❌ GraphQL ERROR:', {
            errors: requestContext.errors?.map((e) => e.message),
            operationName: requestContext.request.operationName,
          })
        },
      }
    },
  },
]
```

### Error Handling Strategy

```typescript
// Apollo Client error handling
defaultOptions: {
  watchQuery: {
    errorPolicy: 'all'  // Показ частичных данных при ошибках
  },
  query: {
    errorPolicy: 'all'  // Graceful degradation
  }
}

// Global error boundary в React
class ErrorBoundary extends React.Component {
  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
    // Логирование в внешний сервис (Sentry, LogRocket)
    console.error('React Error Boundary:', error, errorInfo)
  }
}
```

## 🔒 БЕЗОПАСНОСТЬ

### Authentication & Authorization

```typescript
// JWT-based authentication
const authLink = setContext((operation, { headers }) => {
  const adminToken = localStorage.getItem('adminAuthToken')
  const userToken = localStorage.getItem('authToken')
  const token = adminToken || userToken // Приоритет админскому токену

  return {
    headers: {
      ...headers,
      authorization: token ? `Bearer ${token}` : '',
    },
  }
})

// Context-based authorization в GraphQL
const resolvers = {
  Query: {
    protectedData: async (parent, args, context) => {
      if (!context.user) {
        throw new GraphQLError('Unauthorized')
      }
      // Логика авторизации...
    },
  },
}
```

**Security Measures:**

- **JWT Authentication**: Stateless токены с истечением
- **Role-based Access Control**: Разграничение прав доступа
- **Input Validation**: Валидация на уровне GraphQL и Prisma
- **HTTPS Only**: Принудительное использование зашифрованного соединения
- **CORS Configuration**: Настроенная политика cross-origin запросов

## 🚀 МАСШТАБИРУЕМОСТЬ

### Database Optimizations

```prisma
// Индексы для производительности
model Message {
  // Композитные индексы для сложных запросов
  @@index([senderOrganizationId, receiverOrganizationId, createdAt])
  @@index([receiverOrganizationId, isRead])
}

model Organization {
  // Индексы для реферальной системы
  @@index([referralCode])
  @@index([referredById])
}
```

### Caching Strategy

```typescript
// Apollo Client кэширование
cache: new InMemoryCache({
  typePolicies: {
    Organization: {
      fields: {
        apiKeys: { merge: false }, // Полная замена при обновлении
      },
    },
    User: {
      fields: {
        organization: { merge: true }, // Умное слияние объектов
      },
    },
  },
})
```

**Scalability Features:**

- **Connection Pooling**: Эффективное использование БД соединений
- **Query Optimization**: Составные индексы для частых запросов
- **Selective Data Fetching**: GraphQL field selection
- **Lazy Loading**: Загрузка компонентов по требованию
- **Horizontal Scaling**: Готовность к микросервисной архитектуре

## 📱 PROGRESSIVE WEB APP

### PWA Features (Planned)

```json
// Будущие возможности PWA
{
  "service_worker": "Кэширование ресурсов офлайн",
  "web_manifest": "Установка как native app",
  "push_notifications": "Уведомления о новых заказах",
  "background_sync": "Синхронизация при восстановлении связи"
}
```

## 🎯 MIGRATION STRATEGY

### Technology Evolution Path

```typescript
// Планируемые улучшения
const TECH_ROADMAP = {
  Q2_2024: [
    'GraphQL Codegen для автогенерации типов',
    'React Query для server state управления',
    'Storybook для документации компонентов',
  ],
  Q3_2024: ['Micro-frontends архитектура', 'Server-Sent Events для real-time', 'Advanced caching с Redis'],
  Q4_2024: ['Kubernetes deployment', 'Advanced monitoring с Prometheus', 'A/B testing framework'],
}
```

---

_Технологический стек обновлен на основе анализа package.json, конфигурационных файлов и архитектуры_  
_Версия документа: 2025-08-21_  
_Next.js 15.4.1 • React 19.1.0 • TypeScript 5 • Prisma 6.12.0 • Apollo Server 4.12.2_