sfera-new/legacy-rules/новые-правила-фулфилмент.md

# 📦 НОВЫЕ ПРАВИЛА ФУЛФИЛМЕНТ - СКЛАД И РАСХОДНИКИ

> **Создано на основе глубокого анализа кода разделов склада и расходников кабинета фулфилмент**
> 
> **Дата анализа**: 19.08.2025  
> **Статус**: ✅ Актуально для текущей версии системы

---

## 📋 СОДЕРЖАНИЕ

1. [🏗️ Архитектурные основы](#1-🏗️-архитектурные-основы)
2. [📊 Раздел "Склад" - детальный план](#2-📊-раздел-склад---детальный-план)
3. [🔧 Подраздел "Расходники фулфилмента" - детальный план](#3-🔧-подраздел-расходники-фулфилмента---детальный-план)
4. [🔄 Интеграция между разделами](#4-🔄-интеграция-между-разделами)
5. [📈 GraphQL API структура](#5-📈-graphql-api-структура)
6. [⚡ Real-time обновления](#6-⚡-real-time-обновления)
7. [🎨 UI/UX компоненты](#7-🎨-uiux-компоненты)
8. [🚀 Оптимизация производительности](#8-🚀-оптимизация-производительности)

---

## 1. 🏗️ АРХИТЕКТУРНЫЕ ОСНОВЫ

### 1.1 Маршруты и страницы

```typescript
// Основные маршруты фулфилмент склада
/fulfillment-warehouse/          → Главный дашборд склада
/fulfillment-warehouse/supplies  → Расходники фулфилмента
```

### 1.2 Модульная архитектура dashboard склада

Компонент `FulfillmentWarehouseDashboard` реализован по **MODULAR_ARCHITECTURE_PATTERN**:

```
src/components/fulfillment-warehouse/fulfillment-warehouse-dashboard/
├── index.tsx                    # Главный оркестратор (1,322 строки)
├── types/index.ts               # TypeScript интерфейсы (223 строки)
├── hooks/                       # Бизнес-логика (4 хука)
│   ├── useWarehouseData.ts      # GraphQL запросы и real-time
│   ├── useStoreData.ts          # Критическая логика группировки данных
│   ├── useTableState.ts         # Управление состоянием таблиц
│   └── useWarehouseStats.ts     # Статистика и расчеты
├── blocks/                      # UI компоненты-блоки
│   ├── WarehouseStatsBlock.tsx  # Статистические карты
│   ├── StoreDataTableBlock.tsx  # Таблица данных магазинов
│   ├── SummaryRowBlock.tsx      # Строка итогов
│   └── TableHeadersBlock.tsx    # Заголовки с сортировкой
└── components/                  # Переиспользуемые компоненты
    └── StatCard.tsx            # Универсальная статистическая карта
```

### 1.3 Основные типы данных

#### 3-уровневая иерархия складских данных:

```typescript
// 🔵 УРОВЕНЬ 1: Магазины (StoreData)
interface StoreData {
  id: string
  name: string
  logo?: string
  avatar?: string
  products: number      // Готовые продукты
  goods: number         // Товары в обработке  
  defects: number       // Брак
  sellerSupplies: number    // Расходники селлеров
  pvzReturns: number    // Возвраты с ПВЗ
  items: ProductItem[]  // Детализация по товарам
}

// 🟢 УРОВЕНЬ 2: Товары (ProductItem)
interface ProductItem {
  id: string
  name: string
  article: string
  productQuantity: number
  productPlace?: string
  // ... места и количества для каждого типа
  variants?: ProductVariant[]  // Варианты товара
}

// 🟠 УРОВЕНЬ 3: Варианты товаров (ProductVariant)
interface ProductVariant {
  id: string
  name: string  // Размер, характеристика, вариант упаковки
  productQuantity: number
  productPlace?: string
  // ... аналогично ProductItem
}
```

---

## 2. 📊 РАЗДЕЛ "СКЛАД" - ДЕТАЛЬНЫЙ ПЛАН

### 2.1 Главный дашборд (`/fulfillment-warehouse`)

#### 2.1.1 📈 Статистические карты (WarehouseStatsBlock)

**6 основных метрик склада:**

1. **🔵 Продукты** (`products`)
   - Готовые к отправке товары
   - Иконка: `Box`
   - Показывает: текущий остаток + изменения за сутки + прибыло/убыло

2. **📦 Товары** (`goods`) 
   - На складе и в обработке
   - Иконка: `Package`
   - Группировка по магазинам селлеров

3. **⚠️ Брак** (`defects`)
   - Требует утилизации
   - Иконка: `AlertTriangle`
   - Цветовая индикация (красный)

4. **🔄 Возвраты с ПВЗ** (`pvzReturns`)
   - К обработке
   - Иконка: `RotateCcw`
   - Статус: требует сортировки

5. **👥 Расходники селлеров** (`sellerSupplies`)
   - Материалы клиентов
   - Иконка: `Users`
   - **КРИТИЧНО**: Группировка по ВЛАДЕЛЬЦУ, не по названию

6. **🔧 Расходники фулфилмента** (`fulfillmentSupplies`)
   - Операционные материалы
   - Иконка: `Wrench`
   - Кликабельно → переход на `/fulfillment-warehouse/supplies`

#### 2.1.2 🗂️ Детализация по магазинам (3-уровневая таблица)

**Ключевые особенности:**

1. **Поиск и фильтрация**
   - Поиск по названию магазина
   - Сортировка по всем столбцам
   - Показать/скрыть изменения за сутки

2. **Строка итогов**
   - Автоматический подсчет всех категорий
   - Движения товаров (прибыло/убыло)
   - Обновляется в real-time

3. **3-уровневая иерархия**
   ```
   🔵 Магазин
   ├─ 🟢 Товар 1
   │  ├─ 🟠 Размер S
   │  ├─ 🟠 Размер M  
   │  └─ 🟠 Размер L
   └─ 🟢 Товар 2
      └─ 🟠 Единственный размер
   ```

4. **Критическая группировка данных**
   ```typescript
   // ⚠️ ВАЖНО: Товары группируются по НАЗВАНИЮ с суммированием
   // ⚠️ ВАЖНО: Расходники группируются по СЕЛЛЕРУ-ВЛАДЕЛЬЦУ!
   
   // Группировка товаров по названию
   const productGroups = sellerProducts.reduce((acc, product) => {
     const key = product.name || 'Без названия'
     // Суммируем количества
     acc[key].productQuantity += product.productQuantity || 0
   }, {})
   
   // Группировка расходников по владельцу
   const sellerSuppliesForThisSeller = sellerSupplies.filter(supply => 
     supply.type === 'SELLER_CONSUMABLES' && 
     supply.sellerId === sellerId
   )
   ```

### 2.2 GraphQL интеграция

#### 2.2.1 Используемые запросы

1. `GET_MY_COUNTERPARTIES` - партнеры (селлеры)
2. `GET_SUPPLY_ORDERS` - заказы поставок  
3. `GET_WAREHOUSE_PRODUCTS` - товары на складе
4. `GET_SELLER_SUPPLIES_ON_WAREHOUSE` - расходники селлеров
5. `GET_MY_FULFILLMENT_SUPPLIES` - расходники фулфилмента
6. `GET_FULFILLMENT_WAREHOUSE_STATS` - статистика с изменениями
7. `GET_SUPPLY_MOVEMENTS` - движения товаров (прибыло/убыло)

#### 2.2.2 Стратегия кеширования

```typescript
// Разные стратегии для разных типов данных
fetchPolicy: 'cache-and-network'  // Контрагенты, товары, расходники
fetchPolicy: 'no-cache'          // Статистика (всегда актуальная)
pollInterval: 30000              // Обновление каждые 30 сек
pollInterval: 60000              // Данные партнеров реже
```

---

## 3. 🔧 ПОДРАЗДЕЛ "РАСХОДНИКИ ФУЛФИЛМЕНТА" - ДЕТАЛЬНЫЙ ПЛАН

### 3.1 Страница расходников (`/fulfillment-warehouse/supplies`)

#### 3.1.1 📊 Статистика расходников (SuppliesStats)

**6 основных показателей:**

1. **📦 Всего позиций** - общее количество видов расходников
2. **✅ Доступно** - расходники в наличии (currentStock > 0)
3. **⚠️ Мало на складе** - требует пополнения (currentStock ≤ minStock)
4. **❌ Нет в наличии** - необходим срочный заказ
5. **💰 Общая стоимость** - суммарная стоимость всех расходников
6. **🚚 В пути** - расходники в доставке + количество категорий

#### 3.1.2 🎛️ Система фильтрации и поиска

```typescript
interface FilterState {
  search: string      // Поиск по названию и описанию
  category: string    // Фильтр по категории
  status: string      // Статус: available/unavailable
  supplier: string    // Поставщик
  lowStock: boolean   // Показать только заканчивающиеся
}

interface SortState {
  field: 'name' | 'category' | 'status' | 'currentStock' | 'price' | 'supplier'
  direction: 'asc' | 'desc'
}
```

#### 3.1.3 📋 Режимы отображения

1. **Grid View** (сетка карточек)
   - Визуальные карточки с прогресс-барами
   - Индикаторы состояния остатков
   - Статусные бейджи

2. **List View** (табличный вид)
   - Компактное представление
   - Сортировка по столбцам
   - Массовые операции

3. **Analytics View** (аналитический режим)
   - **Статус**: Планируется к реализации
   - Графики потребления
   - Прогнозирование остатков

#### 3.1.4 📊 Группировка данных

```typescript
type GroupBy = 'none' | 'category' | 'status' | 'supplier'

// Группировка по категориям, статусу или поставщику
const groupedSupplies = useMemo(() => {
  if (groupBy === 'none') return { 'Все расходники': filteredSupplies }
  
  return filteredSupplies.reduce((acc, supply) => {
    let key: string
    if (groupBy === 'status') {
      key = supply.currentStock > 0 ? 'Доступен' : 'Недоступен'
    } else {
      key = supply[groupBy] || 'Без категории'  
    }
    if (!acc[key]) acc[key] = []
    acc[key].push(supply)
    return acc
  }, {})
}, [filteredSupplies, groupBy])
```

### 3.2 ⚡ Критическая логика консолидации

#### 3.2.1 Объединение одинаковых расходников

```typescript
// НОВОЕ: Группировка по артикулу СФ (более точно)
const consolidatedSupplies = useMemo(() => {
  const grouped = supplies.reduce((acc, supply) => {
    const key = supply.article // Группировка по артикулу
    
    if (!acc[key]) {
      acc[key] = {
        ...supply,
        currentStock: 0,
        quantity: 0,
        shippedQuantity: 0,
      }
    }

    // Учитываем принятые поставки (все варианты статусов)
    if (supply.status === 'доставлено' || 
        supply.status === 'На складе' || 
        supply.status === 'in-stock') {
      
      const actualQuantity = supply.actualQuantity ?? supply.quantity
      acc[key].quantity += actualQuantity
      acc[key].shippedQuantity += supply.shippedQuantity || 0
      acc[key].currentStock += actualQuantity - (supply.shippedQuantity || 0)
    }

    return acc
  }, {} as Record<string, Supply>)

  return Object.values(grouped)
}, [supplies])
```

#### 3.2.2 Статусы расходников

```typescript
const STATUS_CONFIG = {
  available: {
    label: 'Доступен',
    color: 'bg-green-500/20 text-green-300', 
    icon: CheckCircle,
  },
  unavailable: {
    label: 'Недоступен',
    color: 'bg-red-500/20 text-red-300',
    icon: AlertTriangle,
  },
} as const

const getStatusConfig = (supply: Supply): StatusConfig => {
  return supply.currentStock > 0 
    ? STATUS_CONFIG.available 
    : STATUS_CONFIG.unavailable
}
```

### 3.3 🎨 UI компоненты расходников

#### 3.3.1 SupplyCard - карточка расходника

**Основные элементы:**
- Заголовок с названием и статусным бейджем  
- Прогресс-бар остатков с цветовой индикацией
- Метрики: цена, общая стоимость
- Категория и количество поставок
- Информация о поставщике и дате создания

```typescript
// Цветовая индикация прогресс-бара остатков
const stockPercentage = supply.minStock > 0 
  ? (supply.currentStock / supply.minStock) * 100 
  : 100

// Цвета: зеленый (>50%), желтый (20-50%), красный (<20%)
const color = stockPercentage > 50 ? '#10b981' 
  : stockPercentage > 20 ? '#f59e0b' 
  : '#ef4444'
```

#### 3.3.2 SuppliesHeader - заголовок с управлением

**Функциональность:**
- Переключение режимов отображения (grid/list/analytics)
- Управление группировкой данных
- Панель фильтров (сворачиваемая)
- Экспорт данных в CSV
- Обновление данных

#### 3.3.3 SuppliesList - табличное представление

**Возможности:**
- Сортировка по всем столбцам
- Развертывание деталей поставок
- Информация о владельцах расходников
- Компактное отображение больших объемов данных

---

## 4. 🔄 ИНТЕГРАЦИЯ МЕЖДУ РАЗДЕЛАМИ

### 4.1 Связи данных

```mermaid
graph LR
    A[Главный склад] --> B[Статистика фулфилмента]
    B --> C[Страница расходников]
    C --> D[Детали поставок]
    A --> E[Расходники селлеров]
    E --> F[Группировка по владельцу]
```

### 4.2 Переходы между разделами

1. **Со склада на расходники**: Клик по карте "Расходники фулфилмента"
2. **Навигация через сайдбар**: Двухуровневое меню
3. **Real-time синхронизация**: Обновления отражаются во всех разделах

### 4.3 Общие компоненты

- `Sidebar` - единая боковая навигация
- `AuthGuard` - проверка доступа
- `StatCard` - унифицированные статистические карты
- Glass-morphism дизайн - единый стиль

---

## 5. 📈 GRAPHQL API СТРУКТУРА

### 5.1 Ключевые запросы

#### GET_MY_FULFILLMENT_SUPPLIES
```graphql
query GetMyFulfillmentSupplies {
  myFulfillmentSupplies {
    id
    name
    description
    article
    price
    quantity
    actualQuantity    # Фактически поставленное
    shippedQuantity   # Отправленное количество  
    currentStock      # = actualQuantity - shippedQuantity
    minStock
    unit
    category
    status            # доставлено/На складе/in-stock
    supplier
    createdAt
    updatedAt
  }
}
```

#### GET_FULFILLMENT_WAREHOUSE_STATS
```graphql
query GetFulfillmentWarehouseStats {
  fulfillmentWarehouseStats {
    products {
      current: Int
      change: Int       # Изменение за сутки
      percentChange: Float
    }
    goods { current change percentChange }
    defects { current change percentChange }
    pvzReturns { current change percentChange }
    fulfillmentSupplies { current change percentChange }
    sellerSupplies { current change percentChange }
  }
}
```

#### GET_SELLER_SUPPLIES_ON_WAREHOUSE
```graphql
query GetSellerSuppliesOnWarehouse {
  sellerSuppliesOnWarehouse {
    id
    name
    type              # MUST be 'SELLER_CONSUMABLES'
    currentStock
    sellerOwner {     # ⚠️ КРИТИЧНО для группировки
      id
      name
      fullName
    }
  }
}
```

### 5.2 Стратегии оптимизации

1. **Кеширование**: `cache-and-network` для стабильных данных
2. **Polling**: 30-60 секунд для разных типов данных
3. **No-cache**: Для критически важной статистики
4. **Batch запросы**: Группировка связанных запросов

---

## 6. ⚡ REAL-TIME ОБНОВЛЕНИЯ

### 6.1 WebSocket события

```typescript
useRealtime({
  onEvent: (evt) => {
    switch (evt.type) {
      case 'supply-order:new':
      case 'supply-order:updated':
        refetchOrders()
        refetchStats()
        refetchWarehouse()
        refetchSellerSupplies()
        refetchFulfillmentSupplies()
        break
        
      case 'warehouse:changed':
        refetchStats()
        refetchFulfillmentSupplies()
        break
    }
  }
})
```

### 6.2 Частота обновлений

- **Статистика**: Каждые 30 секунд + события
- **Товары на складе**: 30 секунд
- **Расходники**: 30 секунд + manual refresh
- **Контрагенты**: 60 секунд (стабильные данные)

---

## 7. 🎨 UI/UX КОМПОНЕНТЫ

### 7.1 Дизайн-система

**Glass-morphism стиль:**
- `glass-card` - основной класс для карточек
- Полупрозрачные фоны с размытием
- Градиенты blue-to-purple
- Белый текст с различной прозрачностью

### 7.2 Цветовая кодировка

```typescript
// Статусы остатков
const STOCK_COLORS = {
  high: '#10b981',     // Зеленый (>50%)
  medium: '#f59e0b',   // Желтый (20-50%)
  low: '#ef4444',      // Красный (<20%)
  empty: '#6b7280',    // Серый (0)
}

// Типы товаров
const TYPE_COLORS = {
  products: 'blue',     // Готовые продукты
  goods: 'green',       // Товары в обработке
  defects: 'red',       // Брак
  supplies: 'purple',   // Расходники
  returns: 'orange',    // Возвраты
}
```

### 7.3 Иконки и индикаторы

- `Box` - готовые продукты
- `Package` - товары в обработке  
- `AlertTriangle` - брак и предупреждения
- `RotateCcw` - возвраты
- `Users` - расходники селлеров
- `Wrench` - расходники фулфилмента
- `TrendingUp/Down` - изменения показателей

---

## 8. 🚀 ОПТИМИЗАЦИЯ ПРОИЗВОДИТЕЛЬНОСТИ

### 8.1 React оптимизации

```typescript
// Мемоизация блоков
export const WarehouseStatsBlock = React.memo<WarehouseStatsBlockProps>(...)

// Оптимизированные вычисления  
const storeData = useMemo(() => {
  // Сложная логика группировки выполняется только при изменении зависимостей
}, [sellerPartners, allProducts, sellerSupplies])

// Callback оптимизации
const handleSort = useCallback((field: StoreDataField) => {
  // Предотвращаем лишние рендеры
}, [])
```

### 8.2 Производительность запросов

1. **Селективное обновление**: Обновляем только измененные блоки
2. **Параллельные запросы**: Используем `Promise.all` для refetch
3. **Оптимистичные обновления**: UI реагирует до получения ответа
4. **Виртуализация**: Планируется для больших списков

### 8.3 Состояние загрузки

```typescript
// Умная индикация загрузки
const loading = counterpartiesLoading || ordersLoading || /* ... */

// Скелетоны для разных состояний
if (loading && storeData.length === 0) {
  return <LoadingSkeleton />
}

// Частичная загрузка данных
if (loading) {
  return <PartialDataView />
}
```

---

## 🎯 ЗАКЛЮЧЕНИЕ

Разделы склада и расходников фулфилмента представляют собой комплексную систему управления складскими операциями с:

### ✅ **Реализованные возможности:**
- 3-уровневая иерархия данных (магазины → товары → варианты)
- Real-time обновления через WebSocket
- Модульная архитектура с разделением ответственности
- Сложная система группировки и фильтрации данных
- Статистические dashboards с движениями товаров
- Экспорт данных и аналитика

### 🔧 **Критически важные особенности:**
- Расходники селлеров группируются по ВЛАДЕЛЬЦУ (не по названию)
- Товары группируются по названию с суммированием количества
- Консолидация расходников по артикулу СФ
- Строгая валидация типа `SELLER_CONSUMABLES`

### 🚀 **Технические преимущества:**
- GraphQL с оптимизированным кешированием
- React мемоизация и performance оптимизации
- Glass-morphism дизайн с единым стилем
- Responsive layout для разных устройств

**Архитектура готова к масштабированию и дальнейшему развитию функциональности.**