sfera-new/docs/business-processes/LOGISTICS_SYSTEM_DETAILED.md

ДЕТАЛЬНАЯ ДОКУМЕНТАЦИЯ ЛОГИСТИЧЕСКОЙ СИСТЕМЫ SFERA

🎯 ОБЗОР СИСТЕМЫ

Логистическая система SFERA обеспечивает полный цикл управления перевозками и логистическими заказами между организациями различных типов. Система включает планирование маршрутов, управление заказами поставок и отслеживание статусов доставки.

📊 АРХИТЕКТУРА ЛОГИСТИЧЕСКОЙ СИСТЕМЫ

Основные компоненты:

• LogisticsDashboard - управление перевозками и маршрутами
• LogisticsOrdersDashboard - обработка заказов поставок
• GraphQL мутации - LOGISTICS_CONFIRM_ORDER, LOGISTICS_REJECT_ORDER
• Интеграция с поставщиками - через систему партнерства

🚛 1. СИСТЕМА ПЕРЕВОЗОК (LogisticsDashboard)

1.1 Структура маршрута

Основано на коде: src/components/logistics/logistics-dashboard.tsx

interface LogisticsRoute {
  id: string
  routeNumber: string // Формат: "LOG-001"
  from: string // Точка отправления
  fromAddress: string // Полный адрес отправления
  to: string // Точка назначения
  toAddress: string // Полный адрес назначения
  status: RouteStatus // Статус маршрута
  distance: string // Расстояние "45 км"
  estimatedTime: string // Время "1 ч 30 мин"
  cargo: string // Описание груза
  price: number // Стоимость перевозки
  createdDate: string // Дата создания
}

1.2 Статусы маршрутов

Обнаружено в коде 4 статуса:

Статус	Описание	Цвет	CSS класс
planned	Запланировано	Синий	text-blue-300 border-blue-400/30
in_transit	В пути	Желтый	text-yellow-300 border-yellow-400/30
delivered	Доставлено	Зеленый	text-green-300 border-green-400/30
cancelled	Отменено	Красный	text-red-300 border-red-400/30

1.3 Ключевые точки доставки

Извлечено из mockLogistics данных:

1. Садовод

   • Адрес: Москва, 14-й км МКАД
   • Тип: Рынок поставщиков

2. SFERAV Logistics

   • Адрес: Москва, ул. Складская, 15
   • Тип: Логистический центр

3. Коледино WB

   • Адрес: МО, г. Подольск, Коледино
   • Тип: Склад Wildberries

4. Тверь Ozon

   • Адрес: г. Тверь, ул. Складская, 88
   • Тип: Склад Ozon

1.4 Статистика перевозок

Функции из кода:

// Общая выручка
const getTotalRevenue = () => {
  return mockLogistics.reduce((sum, route) => sum + route.price, 0)
}

// Количество в пути
const getInTransitCount = () => {
  return mockLogistics.filter((route) => route.status === 'in_transit').length
}

// Количество доставленных
const getDeliveredCount = () => {
  return mockLogistics.filter((route) => route.status === 'delivered').length
}

1.5 UI Компоненты перевозок

Структура дашборда:

1. Заголовок и действия

   • Кнопка "Создать маршрут" (bg-gradient-to-r from-blue-500 to-cyan-500)

2. Карточки статистики (4 шт.)

   • Всего маршрутов (иконка Truck, синий)
   • В пути (иконка Navigation, желтый)
   • Доставлено (иконка Package, зеленый)
   • Выручка (иконка TrendingUp, фиолетовый)

3. Список активных маршрутов

   • Карточка каждого маршрута с деталями
   • Информация о точках отправления/назначения
   • Детали груза и времени

📦 2. СИСТЕМА ЛОГИСТИЧЕСКИХ ЗАКАЗОВ (LogisticsOrdersDashboard)

2.1 Workflow заказов поставок

Основано на коде: src/components/logistics-orders/logistics-orders-dashboard.tsx

Поставщик создает заказ → PENDING
         ↓
Поставщик одобряет → SUPPLIER_APPROVED
         ↓
Логист подтверждает → LOGISTICS_CONFIRMED
         ↓
Начало отгрузки → SHIPPED
         ↓
Доставка → DELIVERED

2.2 Полный список статусов заказов

Извлечено из statusMap в коде:

Статус	Описание	Цвет	Иконка
PENDING	Ожидает поставщика	Серый	Clock
SUPPLIER_APPROVED	Требует подтверждения логиста	Желтый	AlertTriangle
CONFIRMED	Подтверждён (устаревший)	Синий	CheckCircle
LOGISTICS_CONFIRMED	Подтверждено логистом	Синий	CheckCircle
SHIPPED	В пути	Оранжевый	Truck
IN_TRANSIT	В пути (устаревший)	Оранжевый	Truck
DELIVERED	Доставлено	Зеленый	Package
CANCELLED	Отменено	Красный	XCircle

2.3 Структура заказа поставки

Интерфейс SupplyOrder из кода:

interface SupplyOrder {
  id: string
  organizationId: string // ID фулфилмент-центра
  partnerId: string // ID поставщика
  deliveryDate: string // Дата доставки
  status: SupplyOrderStatus // Статус заказа
  totalAmount: number // Общая сумма
  totalItems: number // Количество товаров
  fulfillmentCenterId: string // ID фулфилмент-центра (НОВОЕ ПОЛЕ)
  logisticsPartnerId?: string // ID логистического партнера (НОВОЕ ПОЛЕ)
  consumableType?: string // Тип расходников: FULFILLMENT_CONSUMABLES, SELLER_CONSUMABLES (НОВОЕ ПОЛЕ)

  // Новые поля для многоуровневой системы поставок (ОБНАРУЖЕНО В АУДИТЕ)
  packagesCount?: number // Количество грузовых мест (от поставщика)
  volume?: number // Объём товара в м³ (от поставщика)
  responsibleEmployee?: string // ID ответственного сотрудника ФФ
  notes?: string // Заметки и комментарии

  createdAt: string // Дата создания
  updatedAt: string // Дата обновления

  // Связи
  organization: Organization // Получатель (фулфилмент)
  partner: Organization // Поставщик
  fulfillmentCenter?: Organization // Фулфилмент-центр (НОВАЯ СВЯЗЬ)
  logisticsPartner?: Organization // Логистический партнер

  // Товары
  items: Array<{
    id: string
    quantity: number
    price: number
    totalPrice: number
    recipe?: {
      // Рецепт поставки (НОВАЯ СТРУКТУРА ИЗ АУДИТА)
      services: Array<{
        // Услуги
        id: string
        name: string
      }>
      fulfillmentConsumables: Array<{
        // Расходники фулфилмента
        id: string
        name: string
      }>
      sellerConsumables: Array<{
        // Расходники селлера
        id: string
        name: string
      }>
      marketplaceCardId?: string // ID карточки маркетплейса
    }
    product: {
      id: string
      name: string
      article: string
      description?: string
      category?: { id: string; name: string }
    }
  }>
}

2.4 Действия логиста

GraphQL мутации и их использование:

2.4.1 Подтверждение заказа

const [logisticsConfirmOrder] = useMutation(LOGISTICS_CONFIRM_ORDER, {
  refetchQueries: [{ query: GET_SUPPLY_ORDERS }],
  onCompleted: (data) => {
    if (data.logisticsConfirmOrder.success) {
      toast.success(data.logisticsConfirmOrder.message)
    }
  },
})

// Использование
const handleConfirmOrder = async (orderId: string) => {
  await logisticsConfirmOrder({ variables: { id: orderId } })
}

2.4.2 Отклонение заказа

const [logisticsRejectOrder] = useMutation(LOGISTICS_REJECT_ORDER, {
  refetchQueries: [{ query: GET_SUPPLY_ORDERS }],
  onCompleted: (data) => {
    setShowRejectModal(null)
    setRejectReason('')
  },
})

// Использование с причиной
const handleRejectOrder = async (orderId: string) => {
  await logisticsRejectOrder({
    variables: {
      id: orderId,
      reason: rejectReason || undefined,
    },
  })
}

2.5 Права доступа логиста

Фильтрация заказов из кода:

// Логист видит только заказы где он назначен логистическим партнером
const logisticsOrders: SupplyOrder[] = (data?.supplyOrders || []).filter((order: SupplyOrder) => {
  const isLogisticsPartner = order.logisticsPartner?.id === user?.organization?.id
  return isLogisticsPartner
})

Доступные действия:

• Просмотр заказов где организация является логистическим партнером
• Подтверждение заказов в статусе SUPPLIER_APPROVED или CONFIRMED
• Отклонение заказов с указанием причины
• Просмотр деталей маршрута и списка товаров

2.6 UI компоненты заказов

2.6.1 Статистика дашборда (4 карточки)

// Требуют подтверждения
const pendingCount = logisticsOrders.filter(
  (order) => order.status === 'SUPPLIER_APPROVED' || order.status === 'CONFIRMED',
).length

// Подтверждено
const confirmedCount = logisticsOrders.filter((order) => order.status === 'LOGISTICS_CONFIRMED').length

// В пути
const shippedCount = logisticsOrders.filter((order) => order.status === 'SHIPPED').length

// Доставлено
const deliveredCount = logisticsOrders.filter((order) => order.status === 'DELIVERED').length

2.6.2 Карточка заказа

Компоненты карточки:

1. Основная информация

   • Номер заказа (последние 8 символов ID)
   • Маршрут: Поставщик → Фулфилмент (с аватарами)
   • Дата доставки и количество товаров

2. Статус и действия

   • Бейдж статуса с иконкой
   • Кнопки "Подтвердить" и "Отклонить" (для статусов SUPPLIER_APPROVED, CONFIRMED)

3. Развернутые детали (при клике)

   • Общая сумма заказа
   • Информация о поставщике и получателе
   • Список товаров с артикулами, количеством и ценами
   • Категории товаров (бейджи)

2.6.3 Модальное окно отклонения

// Состояние модального окна
const [showRejectModal, setShowRejectModal] = useState<string | null>(null)
const [rejectReason, setRejectReason] = useState<string>('')

// Компонент модального окна с textarea для причины

🔗 3. ИНТЕГРАЦИЯ ЛОГИСТИКИ С ДРУГИМИ СИСТЕМАМИ

3.1 Связь с системой партнерства

Логистические партнеры определяются через:

• Organization.type должен включать логистические возможности
• Назначение в поле SupplyOrder.logisticsPartner
• Проверка прав доступа через user.organization.id

3.2 Связь с системой поставок

Workflow интеграции:

1. Поставщик создает заказ поставки
2. Система автоматически назначает логистического партнера
3. Логист получает уведомление и может подтвердить/отклонить
4. При подтверждении создается логистический маршрут
5. Обновляются статусы и отправляются уведомления

3.3 Связь со складской системой

Точки интеграции:

• Адреса складов в маршрутах
• Информация о товарах в заказах
• Статусы доставки влияют на складские остатки

🎨 4. ДИЗАЙН И UX ПАТТЕРНЫ

4.1 Цветовая схема

Glass Morphism стиль:

/* Основные карточки */
.glass-card {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(20px);
  border: 1px solid rgba(255, 255, 255, 0.2);
}

/* Вторичные элементы */
.glass-secondary {
  background: rgba(255, 255, 255, 0.05);
  border: 1px solid rgba(255, 255, 255, 0.1);
}

4.2 Иконки и визуальные элементы

Стандартные иконки Lucide React:

• Truck - перевозки и логистика
• MapPin - точки маршрута
• Package - товары и грузы
• Clock - время и ожидание
• CheckCircle - подтверждение
• XCircle - отклонение
• AlertTriangle - предупреждения

4.3 Адаптивность

Responsive дизайн:

• Мобильные устройства: вертикальный стек карточек
• Планшеты: 2-колоночная сетка
• Десктоп: 4-колоночная сетка статистики
• Боковая панель с useSidebar() хуком

📊 5. ТЕХНИЧЕСКАЯ РЕАЛИЗАЦИЯ

5.1 Зависимости и хуки

// Обязательные хуки
import { useSidebar } from '@/hooks/useSidebar'
import { useAuth } from '@/hooks/useAuth'

// GraphQL
import { useQuery, useMutation } from '@apollo/client'

// UI компоненты
import { Sidebar } from '@/components/dashboard/sidebar'
import { Card } from '@/components/ui/card'
import { Badge } from '@/components/ui/badge'
import { Button } from '@/components/ui/button'

5.2 Форматирование данных

// Валюта
const formatCurrency = (amount: number) => {
  return new Intl.NumberFormat('ru-RU', {
    style: 'currency',
    currency: 'RUB',
    minimumFractionDigits: 0,
  }).format(amount)
}

// Дата
const formatDate = (dateString: string) => {
  return new Date(dateString).toLocaleDateString('ru-RU', {
    day: '2-digit',
    month: '2-digit',
    year: 'numeric',
  })
}

// Инициалы для аватаров
const getInitials = (name: string): string => {
  return name
    .split(' ')
    .map((word) => word.charAt(0))
    .join('')
    .toUpperCase()
    .slice(0, 2)
}

5.3 Обработка состояний

// Управление развернутыми заказами
const [expandedOrders, setExpandedOrders] = useState<Set<string>>(new Set())

const toggleOrderExpansion = (orderId: string) => {
  const newExpanded = new Set(expandedOrders)
  if (newExpanded.has(orderId)) {
    newExpanded.delete(orderId)
  } else {
    newExpanded.add(orderId)
  }
  setExpandedOrders(newExpanded)
}

📈 6. МЕТРИКИ И АНАЛИТИКА

6.1 Ключевые показатели

Автоматически рассчитываемые метрики:

• Общее количество маршрутов
• Количество маршрутов в пути
• Количество доставленных маршрутов
• Общая выручка от перевозок
• Количество заказов по статусам

6.2 Отчетность

Потенциальные отчеты:

• Эффективность логистических партнеров
• Средние времена доставки по маршрутам
• Статистика отклонений заказов
• Загрузка логистических мощностей

🔄 7. WORKFLOW ПРОЦЕССЫ

7.1 Стандартный процесс доставки

1. Создание заказа поставки (Поставщик)
   ↓
2. Одобрение заказа (Поставщик) → SUPPLIER_APPROVED
   ↓
3. Назначение логистического партнера (Система)
   ↓
4. Подтверждение логистом → LOGISTICS_CONFIRMED
   ↓
5. Создание маршрута перевозки
   ↓
6. Начало отгрузки → SHIPPED
   ↓
7. Доставка на склад → DELIVERED

7.2 Исключительные случаи

Отклонение заказа:

• Логист может отклонить заказ с указанием причины
• Заказ переходит в статус CANCELLED
• Поставщик получает уведомление с причиной

Отмена маршрута:

• Маршрут может быть отменен до начала перевозки
• Статус меняется на cancelled
• Связанный заказ может потребовать нового логистического партнера

📱 8. ДОПОЛНИТЕЛЬНЫЕ ЛОГИСТИЧЕСКИЕ КОМПОНЕНТЫ

8.1 Маркетплейс логистики (MarketLogistics)

Основано на коде: src/components/market/market-logistics.tsx

Функциональность:

// Поиск логистических партнеров в маркетплейсе
const { data, loading, refetch } = useQuery(SEARCH_ORGANIZATIONS, {
  variables: { type: 'LOGIST', search: searchTerm || null },
})

// Отправка запроса на партнерство
const [sendRequest] = useMutation(SEND_COUNTERPARTY_REQUEST, {
  refetchQueries: [
    { query: SEARCH_ORGANIZATIONS, variables: { type: 'LOGIST' } },
    { query: GET_OUTGOING_REQUESTS },
    { query: GET_INCOMING_REQUESTS },
  ],
})

Возможности компонента:

• Поиск логистических организаций по типу 'LOGIST'
• Отправка запросов на партнерство
• Просмотр профилей логистических компаний
• Управление входящими и исходящими запросами

8.2 Вкладка логистических услуг (LogisticsTab)

Основано на коде: src/components/services/logistics-tab.tsx

Структура логистического маршрута:

interface LogisticsRoute {
  id: string
  fromLocation: string // Откуда
  toLocation: string // Куда
  priceUnder1m3: number // Цена за груз до 1м³
  priceOver1m3: number // Цена за груз свыше 1м³
  description?: string // Описание маршрута
  createdAt: string // Дата создания
  updatedAt: string // Дата обновления
}

CRUD операции:

// GraphQL операции для управления маршрутами
const [createLogistics] = useMutation(CREATE_LOGISTICS)
const [updateLogistics] = useMutation(UPDATE_LOGISTICS)
const [deleteLogistics] = useMutation(DELETE_LOGISTICS)

// Получение маршрутов организации
const { data, loading, error, refetch } = useQuery(GET_MY_LOGISTICS)

Редактируемый интерфейс:

interface EditableLogistics {
  id?: string
  fromLocation: string // Локация отправления
  toLocation: string // Локация назначения
  priceUnder1m3: string // Цена для малых грузов
  priceOver1m3: string // Цена для больших грузов
  description: string // Описание услуги
  isNew: boolean // Новый маршрут
  isEditing: boolean // Режим редактирования
  hasChanges: boolean // Есть несохраненные изменения
}

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

• Дифференцированная тарификация: разные цены для грузов до и свыше 1м³
• Inline редактирование: прямое редактирование в таблице
• Валидация данных: проверка корректности введенных данных
• Toast уведомления: информирование об успешных операциях и ошибках

8.3 Дополнительные GraphQL операции

Обнаруженные в аудите:

// Поиск организаций по типу
SEARCH_ORGANIZATIONS

// Управление логистическими маршрутами
CREATE_LOGISTICS // Создание нового маршрута
UPDATE_LOGISTICS // Обновление существующего маршрута
DELETE_LOGISTICS // Удаление маршрута
GET_MY_LOGISTICS // Получение маршрутов организации

// Управление партнерскими запросами
SEND_COUNTERPARTY_REQUEST // Отправка запроса на партнерство
GET_INCOMING_REQUESTS // Входящие запросы
GET_OUTGOING_REQUESTS // Исходящие запросы

🎯 ЗАКЛЮЧЕНИЕ

Логистическая система SFERA обеспечивает полный цикл управления перевозками от планирования маршрутов до доставки товаров. Система интегрирована с модулями партнерства, поставок и складского учета, обеспечивая единый workflow обработки заказов.

Ключевые преимущества:

• Прозрачный workflow с четкими статусами
• Ролевая модель доступа для логистов
• Интеграция с ключевыми точками доставки
• Современный UI с Glass Morphism дизайном
• Автоматический расчет метрик и статистики