sfera/logist-cabinet-rules.md

# ПРАВИЛА КАБИНЕТА ЛОГИСТИКИ (LOGIST)

> ⚠️ **ВАЖНО**: Это файл с техническими деталями кабинета логистики.
> Общие бизнес-правила находятся в **[rules-complete.md](./rules-complete.md)**

## Когда использовать этот файл:

- Работа с компонентами `/logistics-requests`, `/routes`
- GraphQL запросы для логистики
- UI/UX специфика кабинета логистики
- Технические детали реализации доставок

## 1. 🚚 СТРУКТУРА КАБИНЕТА ЛОГИСТИКИ

### 1.1 Основные разделы

**ЛОГИСТИКА (`LOGIST`)** имеет доступ к следующим разделам:

- **Заявки** (`/logistics-requests`) - управление заявками на доставку
- **Маршруты** (`/routes`) - планирование маршрутов
- **В пути** (`/in-transit`) - отслеживание грузов
- **История** (`/delivery-history`) - архив доставок
- **Партнеры** (`/partners`) - управление контрагентами
- **Мессенджер** (`/messenger`) - связь с партнерами
- **Настройки** (`/settings`) - профиль и настройки
- **Экономика** (`/economics`) - финансовая аналитика

### 1.2 Навигация и роутинг

#### При входе в систему:

```typescript
switch (user?.organization?.type) {
  case 'LOGIST':
    router.push('/logistics-requests') // Направляем на страницу заявок
    break
}
```

#### Специальная логика роутинга:

> 📖 **Бизнес-логика роутинга**: См. [rules-complete.md#4-система-ролей-и-доступов](./rules-complete.md#4--система-ролей-и-доступов)

## 2. 🎨 UI/UX КОМПОНЕНТЫ

### 2.1 Dashboard компоненты

#### Основные компоненты кабинета:

- `LogisticsRequestsDashboard` - главный компонент заявок
- `RoutesManager` - управление маршрутами
- `DeliveryTracker` - отслеживание доставок
- `LogisticsEconomicsPage` - экономическая аналитика

#### Wrapper-компоненты:

- `HomePageWrapper` - маршрутизация по типам организаций
- `EconomicsPageWrapper` - адаптивная экономика по кабинетам

#### Специализированные компоненты:

- `LogisticsRequestCard` - карточка заявки на доставку
- `RouteCard` - карточка маршрута
- `DeliveryStatusTracker` - трекер статуса доставки
- `LogisticsStats` - статистика доставок

### 2.2 Карточка заявки на доставку

#### Структура карточки:

```jsx
<div className="logistics-request-card glass-card">
  <div className="flex items-start justify-between">
    {/* Основная информация */}
    <div className="flex-1">
      <h4 className="text-white font-medium">Заявка #{request.number}</h4>
      <p className="text-white/60 text-sm mt-1">
        {request.fromLocation} → {request.toLocation}
      </p>
    </div>

    {/* Статус */}
    <Badge className={getStatusColor(request.status)}>{getStatusLabel(request.status)}</Badge>
  </div>

  {/* Детали доставки */}
  <div className="mt-4 space-y-2">
    <div className="flex justify-between text-sm">
      <span className="text-white/60">Вес:</span>
      <span className="text-white">{request.weight} кг</span>
    </div>
    <div className="flex justify-between text-sm">
      <span className="text-white/60">Объем:</span>
      <span className="text-white">{request.volume} м³</span>
    </div>
  </div>
</div>
```

### 2.3 Интерфейс отслеживания

```jsx
<div className="delivery-tracker">
  <div className="flex items-center justify-between mb-4">
    <h3 className="text-white font-semibold">Статус доставки</h3>
    <Badge className="bg-yellow-500/20 text-yellow-300">В пути</Badge>
  </div>

  {/* Прогресс доставки */}
  <div className="relative">
    <div className="absolute left-4 top-0 bottom-0 w-0.5 bg-white/20"></div>
    {deliverySteps.map((step, index) => (
      <div key={step.id} className="flex items-center gap-4 mb-4">
        <div
          className={`
          w-8 h-8 rounded-full flex items-center justify-center
          ${step.completed ? 'bg-green-500' : 'bg-white/10'}
        `}
        >
          {step.completed ? '✓' : index + 1}
        </div>
        <div>
          <p className="text-white text-sm">{step.label}</p>
          <p className="text-white/60 text-xs">{step.time}</p>
        </div>
      </div>
    ))}
  </div>
</div>
```

## 3. 📊 ФУНКЦИОНАЛЬНЫЕ ВОЗМОЖНОСТИ

> 📖 **Бизнес-правила**: См. [rules-complete.md#12-кабинет-логистики](./rules-complete.md#12--кабинет-логистики) для правил workflow и процессов

### 3.1 Основные функции логистики

**РОЛЬ В СИСТЕМЕ**: Управление доставками и транспортировкой

**КЛЮЧЕВЫЕ ФУНКЦИИ**:

- **ПОДТВЕРЖДЕНИЕ**: Возможности доставки поставок
- **ПЛАНИРОВАНИЕ**: Оптимальных маршрутов
- **УПРАВЛЕНИЕ**: Транспортом и водителями
- **ОТСЛЕЖИВАНИЕ**: Мониторинг грузов в пути

### 3.2 Workflow для логистики

#### **ЭТАП 1: Получение заявки**

1. Логистика получает уведомление о новой поставке
2. Заявка появляется в разделе "Заявки" кабинета логистики
3. Логист изучает детали поставки (объем, вес, маршрут)

#### **ЭТАП 2: Подтверждение доставки**

4. Логист нажимает кнопку "Одобрить"
5. Статус поставки меняется на `LOGISTICS_CONFIRMED`
6. Уведомления отправляются всем участникам

#### **ЭТАП 3: Получение груза**

7. Логистика приезжает к поставщику
8. Поставщик передает товар и документы
9. В системе отмечается "Груз получен"
10. Статус меняется на `IN_TRANSIT`

#### **ЭТАП 4: Доставка**

11. Логистика доставляет товар на фулфилмент-центр
12. В кабинете логистики нажимают "Доставлено"
13. Фулфилмент принимает товар и отмечает "Принято"

### 3.3 Система тарификации

**ПАРАМЕТРЫ ТАРИФИКАЦИИ**:

- **Тариф до 1м³** - базовая стоимость для малых грузов
- **Тариф свыше 1м³** - стоимость для крупных грузов
- **Маршруты доставки** - от точки отправления до точки назначения
- **Описание услуг** - дополнительные условия доставки

**РАСЧЕТ СТОИМОСТИ**:

- Автоматический расчет стоимости доставки по объему груза
- Отображение примерной стоимости при создании заказа
- Учет специфики маршрута и условий доставки

#### Пример интерфейса тарификации:

```jsx
<div className="tariff-calculator glass-card p-4">
  <h3 className="text-white font-semibold mb-4">Расчет стоимости доставки</h3>

  <div className="space-y-3">
    <div className="flex justify-between">
      <span className="text-white/60">Объем груза:</span>
      <span className="text-white font-medium">{volume} м³</span>
    </div>

    <div className="flex justify-between">
      <span className="text-white/60">Базовый тариф:</span>
      <span className="text-white">{volume <= 1 ? tariffUnder1m3 : tariffOver1m3} ₽/м³</span>
    </div>

    <div className="border-t border-white/10 pt-3">
      <div className="flex justify-between text-lg">
        <span className="text-white font-semibold">Итого:</span>
        <span className="text-green-400 font-bold">{calculateTotal(volume, tariff)} ₽</span>
      </div>
    </div>
  </div>
</div>
```

### 3.4 Управление заявками

**РАЗДЕЛЫ КАБИНЕТА ЛОГИСТИКИ**:

- **НОВЫЕ ЗАЯВКИ** - поступившие заявки на доставку
- **В РАБОТЕ** - принятые к исполнению заявки
- **ВЫПОЛНЕННЫЕ** - завершенные доставки
- **ОТКЛОНЕННЫЕ** - заявки, которые не могут быть выполнены

**ИНФОРМАЦИЯ О ЗАЯВКЕ**:

- Детали груза (объем, вес, габариты)
- Маршрут доставки (откуда - куда)
- Срочность доставки
- Особые требования к транспортировке
- Контактная информация участников

#### Интерфейс управления заявками:

```jsx
<Tabs defaultValue="new" className="w-full">
  <TabsList className="grid w-full grid-cols-4 bg-white/5">
    <TabsTrigger value="new" className="data-[state=active]:bg-white/10">
      Новые
      <Badge className="ml-2 bg-blue-500/20">{newCount}</Badge>
    </TabsTrigger>
    <TabsTrigger value="in-progress" className="data-[state=active]:bg-white/10">
      В работе
      <Badge className="ml-2 bg-yellow-500/20">{inProgressCount}</Badge>
    </TabsTrigger>
    <TabsTrigger value="completed" className="data-[state=active]:bg-white/10">
      Выполненные
    </TabsTrigger>
    <TabsTrigger value="rejected" className="data-[state=active]:bg-white/10">
      Отклоненные
    </TabsTrigger>
  </TabsList>

  <TabsContent value="new" className="mt-4">
    <div className="grid gap-4">
      {newRequests.map((request) => (
        <LogisticsRequestCard key={request.id} request={request} />
      ))}
    </div>
  </TabsContent>
</Tabs>
```

## 4. 🛠️ GRAPHQL API

### 4.1 Основные запросы (Queries)

#### Получение заявок на доставку:

```graphql
query GetLogisticsRequests {
  logisticsRequests(where: { status: PENDING }) {
    id
    number
    fromLocation
    toLocation
    weight
    volume
    status
    supply {
      id
      totalAmount
      organization {
        name # Заказчик
      }
    }
  }
}
```

#### Получение активных маршрутов:

```graphql
query GetActiveRoutes {
  routes(where: { status: ACTIVE }) {
    id
    name
    driver {
      name
      phone
    }
    deliveries {
      id
      status
      estimatedTime
    }
  }
}
```

#### Получение статистики:

```graphql
query GetLogisticsStats {
  logisticsStats {
    totalDeliveries
    activeDeliveries
    completedToday
    averageDeliveryTime
    onTimeRate
  }
}
```

### 4.2 Мутации (Mutations)

#### Подтверждение доставки:

```graphql
mutation ConfirmLogistics($supplyId: ID!) {
  confirmLogistics(supplyId: $supplyId) {
    success
    supply {
      id
      status # Изменится на LOGISTICS_CONFIRMED
    }
  }
}
```

#### Обновление статуса доставки:

```graphql
mutation UpdateDeliveryStatus($deliveryId: ID!, $status: DeliveryStatus!) {
  updateDeliveryStatus(id: $deliveryId, status: $status) {
    success
    delivery {
      id
      status
      updatedAt
    }
  }
}
```

#### Создание маршрута:

```graphql
mutation CreateRoute($input: RouteInput!) {
  createRoute(input: $input) {
    success
    route {
      id
      name
      driver {
        id
        name
      }
      deliveries {
        id
        fromLocation
        toLocation
      }
    }
  }
}
```

### 4.3 Подписки (Subscriptions)

```graphql
subscription DeliveryTracking($deliveryId: ID!) {
  deliveryUpdates(deliveryId: $deliveryId) {
    id
    status
    currentLocation
    estimatedArrival
    events {
      type
      timestamp
      description
    }
  }
}
```

## 5. 📁 ТЕХНИЧЕСКИЕ КОМПОНЕНТЫ

### 5.1 Расположение компонентов

```
src/components/
├── logistics/              # Компоненты логистики
│   ├── logistics-requests-dashboard.tsx
│   ├── logistics-request-card.tsx
│   ├── route-manager.tsx
│   └── delivery-tracker.tsx
├── routes/                 # Компоненты маршрутов
│   ├── route-card.tsx
│   ├── route-planner.tsx
│   └── driver-assignment.tsx
└── economics/              # Экономика
    └── logistics-economics-page.tsx
```

### 5.2 Страницы (Pages)

```
src/app/
├── logistics-requests/
│   └── page.tsx           # Страница заявок
├── routes/
│   └── page.tsx           # Страница маршрутов
├── in-transit/
│   └── page.tsx           # Активные доставки
└── delivery-history/
    └── page.tsx           # История доставок
```

## 6. 🚨 ТЕХНИЧЕСКИЕ ПРАВИЛА И ОГРАНИЧЕНИЯ

> 📖 **Workflow поставок**: См. [rules-complete.md#5-workflow-поставок](./rules-complete.md#5--workflow-поставок) для бизнес-процессов

### 6.1 Обязательные проверки:

- Проверка типа организации: `organization.type === 'LOGIST'`
- Валидация прав доступа на уровне GraphQL резолверов
- Проверка возможности доставки (вес, объем, расстояние)
- Контроль статусов перед изменением

### 6.2 Правила безопасности доступа:

#### Контроль на уровне компонентов:

```typescript
{user?.organization?.type === "LOGIST" && (
  <LogisticsRequestsDashboard />
)}
```

#### Проверки в GraphQL резолверах:

```typescript
// Проверка что пользователь - логистика
if (context.user.organization.type !== 'LOGIST') {
  throw new Error('Access denied: Logistics access required')
}

// Проверка доступа к заявкам
const request = await prisma.logisticsRequest.findFirst({
  where: {
    id: requestId,
    organizationId: context.user.organizationId,
  },
})
```

### 6.3 Запрещено:

- Изменять статусы поставок минуя workflow
- Подтверждать доставки без физического получения груза
- Показывать данные других логистических компаний
- Изменять данные после завершения доставки

### 6.4 Правила статусов доставки:

- `LOGISTICS_CONFIRMED` → только после проверки возможности
- `IN_TRANSIT` → только после физического получения груза
- `DELIVERED` → требует подтверждения от фулфилмента

### 6.5 Правила логистики

**ОБЯЗАТЕЛЬНО**:

- Своевременное подтверждение заявок
- Соблюдение сроков доставки
- Бережная транспортировка товаров
- Уведомление о статусе доставки
- Документальное оформление приема/передачи груза

**ЗАПРЕЩЕНО**:

- Принятие заявок без подтверждения возможности выполнения
- Нарушение сроков доставки без уведомления
- Повреждение товаров при транспортировке
- Передача груза без документального оформления
- Изменение маршрута без согласования

**ИНТЕГРАЦИЯ С ПАРТНЕРАМИ**:

- Логистика видит только партнеров-поставщиков и фулфилмент-центры
- Выбор логистики осуществляется из списка партнеров типа `LOGIST`
- Все взаимодействия фиксируются в системе уведомлений

> 📖 **Критические запреты**: См. [rules-complete.md#17-критические-запреты](./rules-complete.md#17--критические-запреты)

---

**Последнее обновление**: Август 2025
**Связанные файлы**:

- [rules-complete.md](./rules-complete.md) - Общие бизнес-правила
- [visual-design-rules.md](./visual-design-rules.md) - Визуальные правила