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

СТРУКТУРА ДАННЫХ СКЛАДА:

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

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

Цветовая Система Статусов

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

Система Кэширования

// Паттерн многоуровневого кэша:
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 эндпоинты
• Описать административную систему
• Создать руководства по интеграции