sfera-new/README.md

# 🌐 Sfera - B2B Marketplace Platform

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

[![Next.js](https://img.shields.io/badge/Next.js-15.4.1-black?logo=next.js)](https://nextjs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/)
[![Prisma](https://img.shields.io/badge/Prisma-6.12.0-2D3748?logo=prisma)](https://www.prisma.io/)
[![GraphQL](https://img.shields.io/badge/GraphQL-16.11.0-E10098?logo=graphql)](https://graphql.org/)

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

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

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

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

### Предварительные требования
- Node.js 20+ 
- PostgreSQL 14+
- npm или yarn

### Установка

```bash
# Клонирование проекта
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 базовых категорий товаров
- ✅ Настройка администратора системы

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

### 🏃‍♂️ Основные команды
```bash
# Разработка с turbopack
npm run dev

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

# Запуск production
npm start
```

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

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

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

# Prisma Studio
npx prisma studio
```

### 🧹 Качество кода
```bash
# Проверка 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-кодов для авторизации пользователей

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

### Скрипты отладки
```bash
# Анализ данных фулфилмента
node scripts/analyze-fulfillment-supplies.cjs

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

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

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

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

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

## 🐳 Docker

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

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

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

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

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

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

```bash
# База данных
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