🌐 Sfera - B2B Marketplace Platform

Комплексная платформа для управления бизнес-процессами в сфере электронной коммерции

🏗️ Архитектура системы

Sfera - это многомодульная B2B платформа, объединяющая четыре типа участников:

• 👔 Seller - Продавцы на маркетплейсах
• 📦 Fulfillment - Фулфилмент-центры
• 🚛 Logist - Логистические компании
• 🏪 Wholesale - Поставщики товаров

🚀 Быстрый старт

Предварительные требования

• Node.js 20+
• PostgreSQL 14+
• npm или yarn

Установка

# Клонирование проекта
git clone <repository-url>
cd sfera

# Установка зависимостей
npm install

# Настройка базы данных
cp .env.example .env
# Отредактируйте DATABASE_URL в .env

# Инициализация БД
npx prisma db push
npm run db:seed

# Запуск в режиме разработки
npm run dev

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

👤 Администратор по умолчанию

При первом запуске автоматически создается администратор:

• Логин: admin
• Пароль: admin123
• Email: admin@sferav.com

⚠️ ОБЯЗАТЕЛЬНО смените пароль после первого входа для безопасности!

🔄 Автоматическая инициализация БД

Система умно инициализируется:

• ✅ Проверяет существующие данные
• ✅ Не создает дубликаты при повторном запуске
• ✅ Автоматическая инициализация при первом запуске приложения
• ✅ Создание 20 базовых категорий товаров
• ✅ Настройка администратора системы

🔧 Команды разработчика

🏃‍♂️ Основные команды

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

# Сборка для production  
npm run build

# Запуск production
npm start

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

# Инициализация БД (создание админа и категорий)
npm run db:seed

# Полный сброс БД и пересоздание данных
npm run db:reset

# Применение миграций и генерация клиента
npx prisma db push

# Prisma Studio
npx prisma studio

🧹 Качество кода

# Проверка ESLint
npm run lint

# Исправление ESLint ошибок
npm run lint:fix

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

# Проверка форматирования
npm run format:check

🏛️ Архитектура проекта

📁 Структура каталогов

src/
├── app/                    # Next.js App Router
│   ├── api/               # API endpoints
│   ├── dashboard/         # Дашборды по типам организаций
│   ├── supplies/          # Управление поставками
│   ├── wb-warehouse/      # Склад WB (только для SELLER)
│   ├── employees/         # Система управления персоналом
│   ├── market/           # B2B маркетплейс
│   └── ...
├── components/            # React компоненты
│   ├── dashboard/        # Компоненты дашбордов
│   ├── supplies/         # Компоненты поставок
│   ├── wb-warehouse/     # Компоненты интерфейса склада WB
│   ├── auth/             # Система авторизации
│   └── ui/               # UI Kit на Radix UI
├── graphql/              # GraphQL слой
│   ├── typedefs.ts       # GraphQL схема
│   ├── resolvers.ts      # Резолверы
│   ├── security/         # Система безопасности
│   └── ...
├── lib/                  # Утилиты и конфигурации
│   └── seed-init.ts      # Автоматическая инициализация
├── hooks/                # React хуки
├── services/             # Внешние сервисы
│   └── wildberries-service.ts  # Интеграция с API WB
└── types/                # TypeScript типы

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

Frontend

• Next.js 15.4.1 - React фреймворк с App Router
• React 19.1.0 - UI библиотека
• TypeScript 5 - Типизация
• Tailwind CSS 4 - Стилизация
• Radix UI - Компоненты интерфейса

Backend & API

• GraphQL - API слой с Apollo Server
• Prisma 6.12.0 - ORM для работы с БД
• PostgreSQL - Основная база данных
• JWT - Авторизация и безопасность

Интеграции

• Wildberries API - Интеграция с маркетплейсом
• Ozon API - Интеграция с маркетплейсом
• DaData API - Валидация ИНН организаций и работа с реквизитами
• SMS Aero - Отправка SMS-сообщений для авторизации
• AWS S3 - Хранение файлов

Инфраструктура

• Docker - Контейнеризация
• Husky - Git hooks
• ESLint + Prettier - Линтинг и форматирование

🏪 Новые возможности

🛒 Склад Wildberries для селлеров

Доступ: Только для пользователей с типом организации SELLER

Новый раздел позволяет:

• 📊 Просмотр остатков товаров на всех складах WB в реальном времени
• 📈 Статистика по складам - общее количество товаров, остатки, товары в пути
• 🔍 Фильтрация и поиск товаров по названию, артикулу, бренду
• 📋 Детальная информация по каждому складу отдельно
• 🎨 Красивые карточки товаров с изображениями и статусами остатков

Как использовать:

1. Настройте API ключ Wildberries в разделе "Настройки" → "API"
2. Перейдите в раздел "Склад ВБ" в боковом меню
3. Система автоматически загрузит актуальные остатки с вашего аккаунта WB

Технические особенности:

• ✅ Интеграция с официальным API Wildberries
• ✅ Поддержка всех типов складов WB
• ✅ Кэширование данных для быстрой работы
• ✅ Адаптивный дизайн в стиле платформы

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

Проект включает комплексную систему безопасности:

• 🛡️ Аудит действий - Логирование всех операций
• 🔍 Обнаружение угроз - Автоматическое выявление подозрительной активности
• 🚨 Мониторинг доступа - Контроль доступа к данным партнеров
• 📊 Security Dashboard - Панель управления безопасностью

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

🏪 Управление поставками

• Многоуровневая система заказов
• Интеграция поставщик → логистика → фулфилмент
• Отслеживание статусов поставок
• Управление рецептурами товаров

👥 Система партнерства

• Реферальная программа
• Автоматическое создание бизнес-партнерств
• Управление контрагентами
• B2B мессенджер

📈 Аналитика и статистика

• Статистика продаж Wildberries/Ozon
• Анализ рекламных кампаний
• Складская аналитика
• Отчеты по сотрудникам

🏭 Управление складом

• Система остатков и резервов
• Управление возвратами ПВЗ
• Складская логистика
• Инвентаризация

🔌 API и интеграции

GraphQL API

Основной API построен на GraphQL со следующими возможностями:

• Аутентификация через SMS-коды
• CRUD операции для всех сущностей
• Система прав доступа по типу организации
• Real-time подписки для чатов

Внешние API

• Wildberries API - статистика, товары, кампании, остатки склада
• Ozon API - интеграция с маркетплейсом
• DaData API - валидация ИНН организаций, получение реквизитов компаний
• SMS Aero - отправка SMS-кодов для авторизации пользователей

🧪 Тестирование и отладка

Скрипты отладки

# Анализ данных фулфилмента
node scripts/analyze-fulfillment-supplies.cjs

# Проверка типов поставок  
node scripts/check-supply-order-types.cjs

# Очистка тестовых данных
node scripts/clear-fulfillment-data.cjs

Health Check

# Проверка состояния API
curl http://localhost:3000/api/health

📚 Документация

Детальная документация проекта находится в:

• docs/ - Новая модульная архитектура документации
• legacy-rules/ - Бизнес-правила и процессы
• CLAUDE.md - Системные правила разработки
• prisma/seed.js - Скрипт инициализации БД

🐳 Docker

# Сборка образа
docker build -t sfera .

# Запуск с docker-compose
docker-compose up -d

🤝 Участие в разработке

Стиль кода

• ESLint - обязательное соблюдение правил
• Prettier - автоматическое форматирование
• TypeScript - строгая типизация
• Conventional Commits - стандарт коммитов

Git Flow

1. Создание feature-ветки
2. Разработка с соблюдением линтинга
3. Тестирование изменений
4. Pull Request с ревью

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

# База данных
DATABASE_URL="postgresql://user:pass@localhost:5432/sfera"

# JWT
JWT_SECRET="your-secret-key"

# API ключи маркетплейсов  
WB_API_TOKEN="wildberries-token"
OZON_CLIENT_ID="ozon-client-id"
OZON_API_KEY="ozon-api-key"

# DaData API
DADATA_API_KEY="dadata-api-key"
DADATA_SECRET="dadata-secret"

# SMS Aero
SMS_AERO_EMAIL="your-email"
SMS_AERO_API_KEY="sms-aero-api-key"

# S3 для файлов
AWS_ACCESS_KEY_ID="access-key"
AWS_SECRET_ACCESS_KEY="secret-key"

📞 Поддержка

При возникновении проблем:

1. Проверьте статус систем через /api/health
2. Просмотрите логи в dev.log
3. Обратитесь к документации в docs/

---

Лицензия: Частная разработка
Статус: Активная разработка
Версия: 0.2.0