sfera-new/docs/development/TECHNICAL_STACK.md

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

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

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

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

Frontend

{
  "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

{
  "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

{
  "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)

// 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

// 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)

// 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

// 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

// 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

// 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)

// 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
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

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

// 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

// 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

// Структурированное логирование 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

// 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

// 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

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

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

Caching Strategy

// 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)

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

🎯 MIGRATION STRATEGY

Technology Evolution Path

// Планируемые улучшения
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