sfera-new/logistics-statistics-warehouse-rules.md

# ПРАВИЛА ЛОГИСТИКИ, СТАТИСТИКИ И СКЛАДСКИХ СИСТЕМ

## 📊 АНАЛИТИЧЕСКИЕ ВЫВОДЫ ИЗ КОДА

### 🚛 1. ЛОГИСТИЧЕСКИЕ МОДУЛИ

#### 1.1 Логистическая Система Перевозок (LogisticsDashboard)
**Файл:** `src/components/logistics/logistics-dashboard.tsx`

**ОБНАРУЖЕННЫЕ ПРАВИЛА:**
- **Статусы маршрутов:** `planned`, `in_transit`, `delivered`, `cancelled`
- **Структура маршрута:** точка отправления → точка назначения
- **Обязательные поля:** номер маршрута, адреса, груз, цена, расстояние, время
- **Цветовая кодировка статусов:**
  - Запланировано: синий (`text-blue-300 border-blue-400/30`)
  - В пути: желтый (`text-yellow-300 border-yellow-400/30`)
  - Доставлено: зеленый (`text-green-300 border-green-400/30`)
  - Отменено: красный (`text-red-300 border-red-400/30`)

**КЛЮЧЕВЫЕ ТОЧКИ ДОСТАВКИ:**
- Садовод (14-й км МКАД)
- SFERAV Logistics (Складская, 15)
- Коледино WB (Подольск)
- Тверь Ozon (Складская, 88)

#### 1.2 Система Логистических Заказов (LogisticsOrdersDashboard)
**Файл:** `src/components/logistics-orders/logistics-orders-dashboard.tsx`

**WORKFLOW ЛОГИСТИКИ:**
```
SUPPLIER_APPROVED → LOGISTICS_CONFIRMED → SHIPPED → DELIVERED
       ↓                    ↓               ↓           ↓
   Требует          Подтверждено      В пути    Доставлено
 подтверждения         логистом
```

**ДЕЙСТВИЯ ЛОГИСТА:**
- Подтверждение заказа (`LOGISTICS_CONFIRM_ORDER`)
- Отклонение заказа с причиной (`LOGISTICS_REJECT_ORDER`)
- Статистика по статусам

**ПРАВА ЛОГИСТА:**
- Подтверждать заказы поставщиков
- Отклонять заказы с указанием причины
- Просматривать детали маршрута и товаров

### 📈 2. СИСТЕМА СТАТИСТИКИ И АНАЛИТИКИ

#### 2.1 Статистика Селлера (SellerStatisticsDashboard)
**Файл:** `src/components/seller-statistics/seller-statistics-dashboard.tsx`

**АРХИТЕКТУРА КЭШИРОВАНИЯ:**
- **Локальный кэш:** Map для salesCache и advertisingCache
- **Database кэш:** через GraphQL мутации `SAVE_SELLER_STATS_CACHE`
- **Время жизни кэша:** 24 часа
- **Ключи кэша:** период + даты для custom диапазонов

**ВКЛАДКИ СТАТИСТИКИ:**
1. **Продажи** (SalesTab) - данные о продажах товаров
2. **Реклама** (AdvertisingTab) - рекламная статистика
3. **Иное** - зарезервировано для будущих функций

**ПЕРИОДЫ АНАЛИЗА:**
- Неделя (`week`)
- Месяц
- Квартал  
- Пользовательский диапазон (`custom`)

#### 2.2 Статистика Фулфилмента (FulfillmentStatisticsDashboard)
**Файл:** `src/components/fulfillment-statistics/fulfillment-statistics-dashboard.tsx`

**БЛОКИ СТАТИСТИКИ:**
1. **Накопленная статистика:**
   - Обработано товаров
   - Выявлено брака
   - Поставок получено
   - Общий доход

2. **Отгрузка на площадки:**
   - Wildberries (фиолетовый)
   - Ozon (синий)
   - Другие маркетплейсы (зеленый)

3. **Аналитика производительности:**
   - Среднее время обработки
   - Уровень брака
   - Уровень возвратов
   - Рейтинг качества

4. **AI-аналитика и прогнозы:**
   - Прогноз роста (+23% в следующем квартале)
   - Оптимизация процессов (-18% времени при автоматизации)
   - Сезонные тренды (+45% в ноябре-декабре)

**УПРАВЛЕНИЕ БЛОКАМИ:**
- Все блоки сворачиваемые/разворачиваемые
- Состояние сохраняется в `expandedSections`

#### 2.3 Экономическая Система (Economics Modules)
**Файлы:** `src/components/economics/*.tsx`

**СПЕЦИАЛИЗАЦИЯ ПО ТИПАМ ОРГАНИЗАЦИЙ:**
- `fulfillment-economics-page.tsx` - экономика фулфилмента
- `logist-economics-page.tsx` - экономика логистики
- `seller-economics-page.tsx` - экономика селлера
- `wholesale-economics-page.tsx` - экономика оптовых поставщиков
- `economics-page-wrapper.tsx` - роутер по типу организации

### 🏬 3. СКЛАДСКИЕ СИСТЕМЫ

#### 3.1 Wildberries Warehouse (WBWarehouseDashboard)
**Файл:** `src/components/wb-warehouse/wb-warehouse-dashboard.tsx`

**ИНТЕГРАЦИЯ С WB API:**
- **Аутентификация:** через API ключи в `organization.apiKeys`
- **Валидация ключей:** проверка `marketplace === 'WILDBERRIES'` и `isActive`
- **Токен доступа:** из `validationData.token|apiKey|key`

**АЛГОРИТМ ЗАГРУЗКИ ДАННЫХ:**
1. Получение карточек товаров (`WildberriesService.getAllCards`)
2. Извлечение nmIds из карточек
3. Получение аналитики для каждого nmId (`getStocksReportByOffices`)
4. Комбинирование данных через `combineCardsWithIndividualAnalytics`
5. Кэширование результата через `SAVE_WB_WAREHOUSE_CACHE`

**СТРУКТУРА ДАННЫХ СКЛАДА:**
```typescript
interface WBStock {
  nmId: number
  vendorCode: string
  title: string
  brand: string
  price: number
  stocks: Array<{
    warehouseId: number
    warehouseName: string
    quantity: number
    quantityFull: number
    inWayToClient: number
    inWayFromClient: number
  }>
  totalQuantity: number
  totalReserved: number
  // ... media, characteristics, etc
}
```

**СТАТИСТИКА СКЛАДА:**
- Всего товаров
- Общий остаток
- Зарезервировано
- Возвраты от клиентов
- Активные склады

#### 3.2 Общий Склад (WarehouseDashboard)
**Файл:** `src/components/warehouse/warehouse-dashboard.tsx`

**ТОВАРНЫЕ ПОЗИЦИИ:**
- **Типы:** `PRODUCT` (товар) / `CONSUMABLE` (расходник)
- **Поля:** название, артикул, описание, цена, количество
- **Опциональные:** setQuantity, ordered, inTransit, stock, sold

**ИНТЕГРАЦИЯ С РЫНКАМИ:**
- **Поддерживаемые рынки:** `sadovod`, `tyak-moscow`
- **Цветовая кодировка:**
  - Садовод: зеленый (`bg-green-500/20 text-green-300`)
  - ТЯК Москва: синий (`bg-blue-500/20 text-blue-300`)

**РЕЖИМЫ ОТОБРАЖЕНИЯ:**
- **Карточки** (`cards`) - сетка карточек товаров
- **Таблица** (`table`) - табличное представление

**СТАТУСЫ ОСТАТКОВ:**
- 0 единиц: красный (`text-red-400`)
- < 10 единиц: желтый (`text-yellow-400`)
- ≥ 10 единиц: зеленый (`text-green-400`)

#### 3.3 Фулфилмент Склад (FulfillmentWarehouse)
**Файлы:** `src/components/fulfillment-warehouse/*.tsx`

**МОДУЛЬНАЯ АРХИТЕКТУРА:**
- **Основной:** `fulfillment-warehouse-dashboard.tsx`
- **Компоненты:** StatCard, TableHeader, блоки (17 файлов)
- **Специализированные:** поставки, статистика, претензии WB

**ФУНКЦИОНАЛЬНОСТЬ:**
- Управление поставками
- Статистика склада
- Обработка возвратов WB
- Детали доставки

## 🎯 ВЫЯВЛЕННЫЕ СТАНДАРТЫ И ПАТТЕРНЫ

### 1. АРХИТЕКТУРНЫЕ ПАТТЕРНЫ

#### Glass Morphism Design
```css
glass-card: "bg-white/10 backdrop-blur border-white/20"
glass-secondary: "bg-white/5 backdrop-blur border-white/10"
glass-input: прозрачные инпуты с размытием
```

#### Цветовая Система Статусов
- **Синий:** планирование, информация, подтверждение
- **Желтый:** ожидание, предупреждения, в процессе
- **Зеленый:** успех, доставлено, высокие показатели
- **Красный:** ошибки, отмены, критические состояния
- **Фиолетовый:** премиум функции, аналитика, WB

#### Система Кэширования
```javascript
// Паттерн многоуровневого кэша:
1. Local State (Map/useState)
2. GraphQL Cache (Apollo)
3. Database Cache (через мутации)
4. External API (последний ресурс)
```

### 2. БИЗНЕС-ПРАВИЛА

#### Workflow Логистики
```
Поставщик → Логист → Фулфилмент → Маркетплейс → Клиент
    ↓         ↓          ↓            ↓          ↓
 Заказ  → Подтверждение → Отгрузка → Доставка → Возврат
```

#### Роли в Логистике
- **Поставщик:** создает заказ поставки
- **Логист:** подтверждает/отклоняет, организует доставку
- **Фулфилмент:** принимает груз, обрабатывает товары
- **Система:** автоматически отслеживает статусы

#### Экономические Правила
- Каждый тип организации имеет свой экономический модуль
- Данные кэшируются на 24 часа
- Поддерживаются пользовательские временные диапазоны
- AI-аналитика предоставляет прогнозы и рекомендации

### 3. ИНТЕГРАЦИОННЫЕ ПРАВИЛА

#### Маркетплейсы
- **Wildberries:** полная интеграция через API, поддержка складов, аналитика
- **Ozon:** поддержка в workflow, данные статистики
- **Другие:** Яндекс.Маркет, Авито (ограниченная поддержка)

#### Склады и Рынки
- **Садовод:** зеленая палитра, первичные поставщики
- **ТЯК Москва:** синяя палитра, альтернативные поставщики
- **WB Склады:** автоматическое определение из API данных

## 🚀 ТЕХНИЧЕСКИЕ ТРЕБОВАНИЯ

### Обязательные Хуки
- `useSidebar()` - управление боковой панелью
- `useAuth()` - аутентификация и права доступа
- Для WB: проверка `hasWBApiKey` перед загрузкой

### GraphQL Операции
**Логистика:**
- `GET_SUPPLY_ORDERS` - получение заказов
- `LOGISTICS_CONFIRM_ORDER` - подтверждение логистом
- `LOGISTICS_REJECT_ORDER` - отклонение с причиной

**Статистика:**
- `GET_SELLER_STATS_CACHE` - кэш статистики селлера
- `SAVE_SELLER_STATS_CACHE` - сохранение кэша
- `GET_WB_WAREHOUSE_DATA` - данные склада WB

**Склады:**
- `GET_MY_PRODUCTS` - товары пользователя
- `SAVE_WB_WAREHOUSE_CACHE` - кэш WB склада

### Внешние Сервисы
- **WildberriesService:** интеграция с API WB
- **Токены:** хранение в `organization.apiKeys`
- **Rate Limiting:** 1 секунда между запросами для WB API

## 📋 ВЫВОДЫ И РЕКОМЕНДАЦИИ

1. **Логистическая система** полноценно реализована с workflow и статусами
2. **Статистические модули** используют сложное многоуровневое кэширование
3. **Складские системы** имеют разную степень интеграции (WB - полная, остальные - базовая)
4. **Экономические модули** специализированы по типам организаций
5. **Дизайн-система** консистентна во всех модулях

**СЛЕДУЮЩИЕ ШАГИ:**
- Документировать API эндпоинты
- Описать административную систему
- Создать руководства по интеграции