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`

```typescript
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 Статистика перевозок

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

```typescript
// Общая выручка
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 из кода:**

```typescript
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 Подтверждение заказа

```typescript
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 Отклонение заказа

```typescript
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 Права доступа логиста

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

```typescript
// Логист видит только заказы где он назначен логистическим партнером
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 карточки)

```typescript
// Требуют подтверждения
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 Модальное окно отклонения

```typescript
// Состояние модального окна
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 стиль:**

```css
/* Основные карточки */
.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 Зависимости и хуки

```typescript
// Обязательные хуки
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 Форматирование данных

```typescript
// Валюта
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 Обработка состояний

```typescript
// Управление развернутыми заказами
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`

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

```typescript
// Поиск логистических партнеров в маркетплейсе
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`

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

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

**CRUD операции:**

```typescript
// 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)
```

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

```typescript
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 операции

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

```typescript
// Поиск организаций по типу
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 дизайном
- Автоматический расчет метрик и статистики