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

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

Создано на основе глубокого анализа кода разделов склада и расходников кабинета фулфилмент

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

---

📋 СОДЕРЖАНИЕ

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

---

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

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

// Основные маршруты фулфилмент склада
/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-уровневая иерархия складских данных:

// 🔵 УРОВЕНЬ 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. Критическая группировка данных

   // ⚠️ ВАЖНО: Товары группируются по НАЗВАНИЮ с суммированием
   // ⚠️ ВАЖНО: Расходники группируются по СЕЛЛЕРУ-ВЛАДЕЛЬЦУ!
   
   // Группировка товаров по названию
   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 Стратегия кеширования

// Разные стратегии для разных типов данных
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 🎛️ Система фильтрации и поиска

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 📊 Группировка данных

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 Объединение одинаковых расходников

// НОВОЕ: Группировка по артикулу СФ (более точно)
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 Статусы расходников

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 - карточка расходника

Основные элементы:

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

// Цветовая индикация прогресс-бара остатков
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 Связи данных

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

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

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

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 события

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 Цветовая кодировка

// Статусы остатков
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 оптимизации

// Мемоизация блоков
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 Состояние загрузки

// Умная индикация загрузки
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 для разных устройств

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