sfera/docs/ARCHITECTURE.md

Архитектура системы управления складами и поставками

📋 Обзор проекта

Система управления складами и поставками - это комплексное решение для управления логистикой, включающее 4 типа кабинетов для разных ролей.

🏗️ Технологический стек

Frontend

• Framework: Next.js 15.4.1 (с Turbopack)
• UI Library: React 19.1.0
• Language: TypeScript 5
• Styling: TailwindCSS 4
• State Management: Apollo Client 3.13.8
• UI Components: Radix UI

Backend

• API: GraphQL (Apollo Server 4.12.2)
• Database: PostgreSQL с Prisma ORM 6.12.0
• Authentication: JWT
• File Storage: AWS S3

DevOps & Tools

• Package Manager: npm
• Linting: ESLint 9 + Prettier
• Build: Next.js build system

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

sfera/
├── src/
│   ├── app/                    # Next.js 15 App Router
│   │   ├── api/               # API endpoints
│   │   ├── dashboard/         # Главная страница
│   │   ├── supplies/          # Управление поставками
│   │   ├── warehouse/         # Склад
│   │   └── ...               # Другие страницы
│   ├── components/            # React компоненты
│   │   ├── ui/               # Базовые UI компоненты
│   │   ├── supplies/         # Компоненты поставок
│   │   ├── warehouse/        # Компоненты склада
│   │   └── ...              # Компоненты по доменам
│   ├── graphql/              # GraphQL схема и резолверы
│   │   ├── queries.ts       # GraphQL запросы
│   │   ├── mutations.ts     # GraphQL мутации
│   │   ├── resolvers/       # Модульные резолверы
│   │   └── typedefs.ts      # Type definitions
│   ├── hooks/                # Custom React hooks
│   ├── lib/                  # Утилиты и конфигурации
│   ├── services/             # Бизнес-логика и интеграции
│   └── types/                # TypeScript типы
├── prisma/
│   └── schema.prisma         # Схема базы данных
├── public/                   # Статические файлы
└── docs/                     # Документация

🏢 Типы кабинетов

1. Кабинет Селлера (SELLER)

• Управление поставками
• Интеграция с маркетплейсами
• Заказ товаров у поставщиков

2. Кабинет Поставщика (WHOLESALE)

• Управление складом товаров
• Обработка заказов от селлеров
• Создание товаров и расходников

3. Кабинет Фулфилмента (FULFILLMENT)

• Полный доступ к системе
• Управление складом фулфилмента
• Услуги и сотрудники
• Обработка поставок

4. Кабинет Логистики (LOGIST)

• Управление доставками
• Маршруты и тарифы
• Отслеживание грузов

🔄 Основные бизнес-процессы

Workflow поставки

1. PENDING - Ожидает подтверждения
2. SUPPLIER_APPROVED - Одобрено поставщиком
3. CONFIRMED - Подтверждено
4. LOGISTICS_CONFIRMED - Подтверждено логистикой
5. SHIPPED - Отгружено
6. IN_TRANSIT - В пути
7. DELIVERED - Доставлено
8. CANCELLED - Отменено

🗄️ Схема базы данных

Основные модели

• User - Пользователи системы
• Organization - Организации (4 типа)
• Product - Товары и расходники
• SupplyOrder - Заказы поставок
• Counterparty - Партнерские связи
• Service - Услуги фулфилмента
• Employee - Сотрудники

🔐 Система безопасности

• JWT авторизация
• Ролевой доступ (RBAC)
• Проверки на уровне GraphQL резолверов
• Шифрование чувствительных данных

📡 API Endpoints

GraphQL

• /api/graphql - Основной GraphQL endpoint

REST

• /api/upload-file - Загрузка файлов
• /api/health - Health check
• /api/track-click - Трекинг кликов

🚀 Команды для разработки

# Разработка
npm run dev

# Сборка
npm run build

# Линтинг
npm run lint
npm run lint:fix

# Форматирование
npm run format
npm run format:check

# База данных
npm run db:seed
npm run db:reset

📊 Метрики и мониторинг

• Логирование ошибок в консоль
• Отслеживание производительности через Next.js
• Метрики использования API

🔄 Планы развития

1. Внедрение микросервисной архитектуры
2. Улучшение типизации (GraphQL Codegen)
3. Добавление E2E тестирования
4. Поддержка офлайн-режима
5. Оптимизация производительности

---

Последнее обновление: ${new Date().toISOString().split('T')[0]}