sfera-new/legacy-rules/правила создания поставки товаров.md

# ПРАВИЛА СОЗДАНИЯ ПОСТАВКИ ТОВАРОВ

**Полный анализ 4-участнической цепочки поставок**  
**Дата создания:** 2024-12-19  
**Версия:** 1.0  
**Основано на глубоком анализе кода системы**

---

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

### **4 УЧАСТНИКА ПРОЦЕССА:**
1. **СЕЛЛЕР** - создает поставку товаров в кабинете
2. **ПОСТАВЩИК (WHOLESALE)** - одобряет заказ и подготавливает товары  
3. **ФУЛФИЛМЕНТ** - принимает товары на склад и обрабатывает
4. **ЛОГИСТИКА** - организует доставку между участниками

### **ПОЛНЫЙ WORKFLOW ЦЕПОЧКИ:**
```
СЕЛЛЕР создает поставку → ПОСТАВЩИК одобряет → ФУЛФИЛМЕНТ принимает → ЛОГИСТИКА доставляет
```

---

## 📋 ЭТАП 1: АНАЛИЗ СОЗДАНИЯ ПОСТАВКИ СЕЛЛЕРОМ

### **Найденный код:**
- **Файл:** `/src/components/supplies/create-suppliers/index.tsx`
- **Компоненты:** `SupplyCreationProvider`, `CartBlock`, `ProductCardsBlock`, `SuppliersBlock`
- **Хуки:** `useSupplyCart`, `useProductCatalog`, `useRecipeBuilder`

### **Процесс создания:**
1. Селлер выбирает товары из каталога
2. Настраивает рецептуру и количества  
3. Выбирает поставщика из списка партнеров
4. Выбирает фулфилмент-центр для доставки
5. Создает заказ через мутацию `createSupplyOrder`

### **GraphQL мутация создания:**
```javascript
// src/graphql/mutations.ts
createSupplyOrder: {
  organizationId: string,    // Селлер (создатель)
  partnerId: string,         // Выбранный поставщик  
  items: SupplyOrderItem[],  // Товары и количества
  fulfillmentCenterId: string, // Куда доставить
  deliveryDate: DateTime     // Когда доставить
}
```

### ✅ **Что работает корректно:**
- Выбор товаров и настройка рецептуры
- Расчет общей стоимости заказа
- Интеграция с каталогом продуктов
- UI создания поставки

### ❌ **Выявленные проблемы:**
- Нет валидации минимальных количеств заказа
- Отсутствует проверка доступности товаров у поставщика
- Нет уведомления поставщика о новом заказе

---

## 📋 ЭТАП 2: АНАЛИЗ ОДОБРЕНИЯ ПОСТАВЩИКОМ

### **Найденный код:**
- **Файл:** `/src/components/supplier-orders/supplier-orders-tabs.tsx`
- **Резолвер:** `/src/graphql/resolvers.ts:2573-2588` (исправленный фильтр)
- **Мутация:** `supplierApproveOrder`

### **Процесс одобрения:**
1. Поставщик видит входящие заказы в разделе "Заявки/Новые"
2. Проверяет детали заказа (товары, количества, сроки) 
3. Видит только кнопки "Одобрить"/"Отклонить" (БЕЗ отображения статуса)
4. При одобрении статус меняется на `SUPPLIER_APPROVED`

### **Исправленный код фильтрации:**
```javascript
// Для кабинета ПОСТАВЩИКА фильтруем по partnerId
let whereClause
if (currentUser.organization.type === 'WHOLESALE') {
  // Поставщик видит заказы, где он является поставщиком
  whereClause = {
    partnerId: currentUser.organization.id,
  }
} else {
  // Остальные видят заказы, которые они создали  
  whereClause = {
    organizationId: currentUser.organization.id,
  }
}
```

### ✅ **Что работает корректно:**
- Корректная фильтрация заказов для поставщиков
- Отображение деталей заказа
- Мутации одобрения/отклонения

### ❌ **Выявленные критические проблемы:**
- **Отображается статус**: поставщик видит "ожидает подтверждения" вместо только кнопок действий
- **Отсутствуют поля ввода**: поставщик не может указать количество грузовых мест (packagesCount) и объем (volume)  
- **Нет даты готовности**: поставщик не может указать, когда товары будут готовы к отгрузке
- **Неполная мутация**: `supplierApproveOrder` не принимает дополнительные параметры

---

## 📋 ЭТАП 3: АНАЛИЗ ПРИЕМКИ ФУЛФИЛМЕНТОМ

### **Найденный код:**
- **Файл:** `/src/components/fulfillment-supplies/fulfillment-supplies/fulfillment-detailed-supplies-tab.tsx`
- **Резолвер:** `fulfillmentReceiveOrder` в `/src/graphql/resolvers.ts`

### **Критическая проблема статусов:**
```javascript
// ❌ КОНФЛИКТ: Резолвер ожидает статус SHIPPED
if (supplyOrder.status !== 'SHIPPED') {
  return {
    success: false,
    message: 'Заказ должен быть в статусе SHIPPED для приемки'
  }
}

// ❌ Но UI пытается принять заказ со статусом SUPPLIER_APPROVED
// Это блокирует весь процесс приемки!
```

### **Процесс приемки (правильный workflow):**
1. После одобрения поставщиком товары должны отображаться в кабинете фулфилмента:
   - **Поставки товаров**: "Входящие поставки / Поставки на фулфилмент / Товар / Новые"
   - **Расходники селлера**: "Входящие поставки / Поставки на фулфилмент / Расходники селлера"
2. Фулфилмент выбирает ответственного сотрудника (из раздела "Сотрудники")
3. Фулфилмент выбирает логистического партнера (из раздела "Партнеры / Логистика")
4. Нажимает кнопку "Принять" (НЕ "Принять поставку")
5. Статус меняется на следующий этап

### ❌ **Критические проблемы:**
- **НЕПРАВИЛЬНАЯ ФИЛЬТРАЦИЯ**: поставки товаров отображаются в "Расходники селлера" вместо "Товар/Новые"
- **Нарушен workflow**: отсутствует промежуточный статус между SUPPLIER_APPROVED и LOGISTICS_CONFIRMED  
- **Нет UI выбора**: фулфилмент не может выбрать ответственного сотрудника
- **Нет UI выбора**: фулфилмент не может выбрать логистического партнера
- **Блокирующий баг**: невозможно принять товары из-за неправильной проверки статуса

---

## 📋 ЭТАП 4: АНАЛИЗ РОЛИ ЛОГИСТИКИ

### **Найденный код:**
- **Файл:** `/src/components/logistics-orders/logistics-orders-dashboard.tsx`
- **Фильтрация:** по `logisticsPartnerId`
- **Мутации:** `LOGISTICS_CONFIRM_ORDER`, `LOGISTICS_REJECT_ORDER`

### **Процесс работы логистики:**
1. Логистика видит заказы, где назначена как логистический партнер
2. Может подтвердить или отклонить логистическое сопровождение
3. При подтверждении статус меняется на `LOGISTICS_CONFIRMED`
4. После отгрузки статус меняется на `SHIPPED`

### **Статусы, которые логистика может обработать:**
```javascript
// Логистика может подтвердить заказы со статусами:
order.status === 'SUPPLIER_APPROVED' || order.status === 'CONFIRMED'
```

### ✅ **Что работает:**
- Корректная фильтрация заказов для логистических партнеров
- UI для подтверждения/отклонения заказов
- Статистика заказов по статусам

### ❌ **Выявленные проблемы:**
- **Нет маршрутизации**: отсутствует система планирования маршрутов
- **Нет трекинга**: отсутствует детальное отслеживание статуса доставки
- **Нет интеграции**: отсутствует интеграция с внешними логистическими системами

---

## 📋 ЭТАП 5: АНАЛИЗ СТАТУСОВ И ПЕРЕХОДОВ

### **Текущие статусы системы:**
```prisma
enum SupplyOrderStatus {
  PENDING              // Создан селлером, ждет поставщика
  SUPPLIER_APPROVED    // Одобрен поставщиком  
  CONFIRMED           // Устаревший статус
  LOGISTICS_CONFIRMED // Подтвержден логистикой
  SHIPPED             // Отправлен в доставку
  IN_TRANSIT          // Устаревший статус  
  DELIVERED           // Доставлен получателю
  CANCELLED           // Отменен
}
```

### **Проблемы в переходах статусов:**

#### ❌ **Критическая проблема workflow:**
```
Текущий поток: PENDING → SUPPLIER_APPROVED → ??? → LOGISTICS_CONFIRMED → SHIPPED → DELIVERED
                                            ↑
                                    ПРОПУЩЕН ЭТАП!
```

**Отсутствует статус `FULFILLMENT_ACCEPTED`** между одобрением поставщиком и подтверждением логистикой!

#### **Правильный workflow должен быть:**
```
PENDING → SUPPLIER_APPROVED → FULFILLMENT_ACCEPTED → LOGISTICS_CONFIRMED → SHIPPED → DELIVERED
```

### **Анализ переходов по участникам:**
1. **СЕЛЛЕР**: `null → PENDING` (создание)
2. **ПОСТАВЩИК**: `PENDING → SUPPLIER_APPROVED` (одобрение)
3. **ФУЛФИЛМЕНТ**: `SUPPLIER_APPROVED → FULFILLMENT_ACCEPTED` (❌ ОТСУТСТВУЕТ)
4. **ЛОГИСТИКА**: `FULFILLMENT_ACCEPTED → LOGISTICS_CONFIRMED` (подтверждение)
5. **ЛОГИСТИКА**: `LOGISTICS_CONFIRMED → SHIPPED` (отгрузка)
6. **СИСТЕМА**: `SHIPPED → DELIVERED` (финал)

---

## 📋 ЭТАП 6: АНАЛИЗ UI КОМПОНЕНТОВ ВСЕХ УЧАСТНИКОВ

### **6.1 СЕЛЛЕР** (`/src/components/supplies/supplies-dashboard.tsx`)
✅ **Работает корректно:**
- Многоуровневая навигация (фулфилмент/маркетплейсы → товар/расходники → карточки/поставщики)
- Интеграция с `AllSuppliesTab` для отображения поставок
- Статистика и уведомления
- Кнопки создания поставок

### **6.2 ПОСТАВЩИК** (`/src/components/supplier-orders/supplier-orders-dashboard.tsx`)
✅ **Работает:**
- Отображение входящих заявок
- Кнопки одобрения/отклонения

❌ **Критические недостатки:**
- Нет формы ввода дополнительных данных при одобрении
- Отсутствуют поля packagesCount, volume, readyDate

### **6.3 ФУЛФИЛМЕНТ** (`/src/components/fulfillment-supplies/fulfillment-supplies-dashboard.tsx`)
✅ **Работает:**
- Сложная многоуровневая навигация
- Статистика по типам поставок
- Уведомления о новых поставках

❌ **Критические недостатки:**
- Нет формы выбора ответственного сотрудника
- Нет формы выбора логистического партнера
- Компонент `FulfillmentDetailedSuppliesTab` не может принять товары из-за бага статусов

### **6.4 ЛОГИСТИКА** (`/src/components/logistics-orders/logistics-orders-dashboard.tsx`)
✅ **Работает:**
- Фильтрация заказов по логистическому партнеру
- Статистика заказов
- Подтверждение/отклонение заказов

❌ **Недостатки:**
- Отсутствует система маршрутизации
- Нет планировщика доставок
- Нет детального трекинга

---

## 📋 ЭТАП 7: ПОЛНЫЙ СПИСОК ПРОБЕЛОВ И НЕДОСТАЮЩЕЙ ФУНКЦИОНАЛЬНОСТИ

### **🔴 КРИТИЧЕСКИЕ ПРОБЛЕМЫ (11 шт.):**

#### **Backend/Workflow:**
1. **Отсутствует статус `FULFILLMENT_ACCEPTED`** в workflow между SUPPLIER_APPROVED и LOGISTICS_CONFIRMED
2. **Баг в `fulfillmentReceiveOrder`**: резолвер ожидает статус SHIPPED, но получает SUPPLIER_APPROVED
3. **Неполная мутация `supplierApproveOrder`**: не принимает поля packagesCount, volume, readyDate
4. **Отсутствует мутация для промежуточной приемки** фулфилментом с выбором сотрудника и логистики

#### **UI Формы:**
5. **Поставщик не может ввести packagesCount** (количество грузовых мест) при одобрении
6. **Поставщик не может ввести volume** (объем товара в м³) при одобрении  
7. **Поставщик не может указать дату готовности** товаров к отгрузке
8. **Фулфилмент не может выбрать ответственного сотрудника** для приемки товаров
9. **Фулфилмент не может выбрать логистического партнера** для дальнейшей доставки

#### **Валидация:**
10. **Нет валидации обязательных полей** при одобрении поставщиком
11. **Нет проверки доступности логистических партнеров** при выборе фулфилментом

### **🟡 ВЫСОКИЙ ПРИОРИТЕТ (6 шт.):**

#### **Бизнес-логика:**
12. **Нет проверки минимальных количеств заказа** при создании поставки селлером
13. **Отсутствует валидация доступности товаров** у поставщика в момент заказа
14. **Нет связи между сотрудниками и фулфилмент-центрами** для корректного выбора

#### **Интеграция и уведомления:**
15. **Отсутствуют автоматические уведомления** поставщику о новых заказах  
16. **Нет real-time обновлений статусов** между всеми участниками процесса
17. **Отсутствует система уведомлений** о смене статуса для всех участников

### **🟠 СРЕДНИЙ ПРИОРИТЕТ (3 шт.):**

#### **Логистика и маршрутизация:**
18. **Отсутствует система маршрутизации** для планирования оптимальных доставок
19. **Нет детального трекинга статуса доставки** с промежуточными точками
20. **Отсутствует интеграция с внешними логистическими API** для расчета расстояний и времени

---

## 🎯 СТРУКТУРИРОВАННЫЙ ПЛАН ДОРАБОТКИ

### **ЭТАП 1: КРИТИЧЕСКИЕ ИСПРАВЛЕНИЯ WORKFLOW** 
**🔴 Приоритет: КРИТИЧЕСКИЙ** | **Время: 2-3 дня**

#### 1.1 Исправление фильтрации в кабинете фулфилмента
- [ ] **КРИТИЧНО**: Исправить неправильную фильтрацию - поставки товаров должны отображаться в "Товар/Новые", а НЕ в "Расходники селлера"
- [ ] **Логика разделения**: 
  - Если селлер создал поставку товаров → отображать в "Поставки на фулфилмент/Товар/Новые"
  - Если селлер создал поставку расходников → отображать в "Поставки на фулфилмент/Расходники селлера"

#### 1.2 Убрать отображение статуса у поставщика
- [ ] **UI поставщика**: Убрать текст "ожидает подтверждения" - оставить только кнопки "Одобрить"/"Отклонить"
- [ ] **Файл**: `/src/components/supplier-orders/supplier-orders-tabs.tsx`

#### 1.3 Создать форму выбора для фулфилмента  
- [ ] **Компонент**: Форма с выбором:
  - Ответственный сотрудник (из раздела "Сотрудники")
  - Логистический партнер (из раздела "Партнеры/Логистика")
- [ ] **Кнопка**: "Принять" (НЕ "Принять поставку")
- [ ] **Интеграция**: Обновить таблицу товаров по образцу "Партнеры/Контрагенты"

### **ЭТАП 2: СТАТУСЫ И BACKEND**
**🔴 Приоритет: КРИТИЧЕСКИЙ** | **Время: 1-2 дня**

#### 2.1 Исправление workflow статусов
- [ ] **Prisma**: Добавить статус `FULFILLMENT_ACCEPTED` в enum SupplyOrderStatus  
- [ ] **GraphQL**: Обновить резолверы для поддержки нового workflow
- [ ] **Backend**: Исправить мутацию `fulfillmentReceiveOrder` для корректной работы с SUPPLIER_APPROVED → FULFILLMENT_ACCEPTED
- [ ] **Мутация**: Создать `fulfillmentAcceptOrder` для промежуточной приемки с выбором сотрудника и логистики

### **ЭТАП 3: СИСТЕМА УВЕДОМЛЕНИЙ**  
**🟡 Приоритет: ВЫСОКИЙ** | **Время: 1 день**

#### 3.1 Real-time уведомления между участниками
- [ ] **WebSocket**: Настроить уведомления о смене статусов
- [ ] **Email**: Уведомления поставщику о новых заказах
- [ ] **Dashboard**: Обновить бейджи уведомлений для всех участников

### **ЭТАП 4: ИНТЕГРАЦИЯ С ЛОГИСТИКОЙ**
**🟠 Приоритет: СРЕДНИЙ** | **Время: 2-3 дня**

#### 4.1 Система маршрутизации и планирования
- [ ] **Компонент**: Система планирования маршрутов для логистики
- [ ] **API**: Интеграция с внешними сервисами для расчета расстояний  
- [ ] **Планировщик**: Календарь доставок и оптимизация маршрутов

#### 4.2 Детальный трекинг доставки
- [ ] **Статусы**: Промежуточные статусы доставки (в пути, на складе, доставлено)
- [ ] **UI**: Компонент отслеживания доставки для всех участников

---

## 📁 ФАЙЛОВАЯ СТРУКТУРА ДЛЯ РЕАЛИЗАЦИИ

### **Backend изменения:**
```
prisma/schema.prisma                 - добавить FULFILLMENT_ACCEPTED статус
src/graphql/resolvers.ts            - исправить переходы статусов
src/graphql/mutations.ts            - обновить мутации с доп. полями  
src/graphql/typedefs.ts             - типы для новых полей
```

### **Frontend компоненты:**
```
src/components/supplier-orders/
  ├── supplier-approval-form.tsx     - новый компонент
  └── supplier-orders-tabs.tsx       - обновить

src/components/fulfillment-supplies/
  ├── fulfillment-acceptance-form.tsx - новый компонент
  └── fulfillment-detailed-supplies-tab.tsx - обновить

src/components/logistics-orders/
  ├── route-planner.tsx             - новый компонент  
  └── logistics-orders-dashboard.tsx - обновить
```

---

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

### **GraphQL Схемы (обновить):**
```graphql
# Обновить мутацию поставщика:
supplierApproveOrder(
  id: String!
  packagesCount: Int!      # Обязательное
  volume: Float!           # Обязательное  
  readyDate: DateTime      # Опциональное
  notes: String           # Опциональное
): SupplyOrderResponse!

# Новая мутация фулфилмента:
fulfillmentAcceptOrder(
  id: String!
  responsibleEmployee: String!    # ID сотрудника
  logisticsPartnerId: String!     # ID логистики
  notes: String                   # Примечания
): SupplyOrderResponse!
```

### **Prisma Schema (добавить):**
```prisma
enum SupplyOrderStatus {
  PENDING
  SUPPLIER_APPROVED  
  FULFILLMENT_ACCEPTED    # ← НОВЫЙ СТАТУС
  LOGISTICS_CONFIRMED
  SHIPPED
  DELIVERED
  CANCELLED
}

model SupplyOrder {
  // ... существующие поля
  packagesCount       Int?        # Активное использование
  volume              Float?      # Активное использование
  readyDate           DateTime?   # Дата готовности от поставщика
  responsibleEmployee String?     # ID ответственного сотрудника ФФ
  acceptanceNotes     String?     # Примечания при приемке
}
```

---

## ⚠️ КРИТИЧЕСКИЕ ЗАМЕЧАНИЯ ДЛЯ РАЗРАБОТКИ

### **1. Обратная совместимость:**
- НЕ НАРУШАТЬ существующие поставки при добавлении нового статуса
- Добавить миграцию для корректного обновления существующих записей
- Протестировать на существующих данных

### **2. Права доступа:**
- ВАЛИДИРОВАТЬ права каждого участника на каждом этапе
- Поставщик может работать только с заказами где он partnerId
- Фулфилмент может работать только с заказами своего центра
- Логистика может работать только с назначенными ей заказами

### **3. Тестирование:**
- ОБЯЗАТЕЛЬНО протестировать все переходы статусов
- Проверить корректность фильтрации для каждого типа организации
- Тестировать валидацию полей на frontend и backend

### **4. Производительность:**
- Учесть индексы в БД для новых полей
- Оптимизировать запросы при добавлении новых фильтров
- Проверить нагрузку при увеличении количества статусов

---

## 📊 МЕТРИКИ УСПЕХА РЕАЛИЗАЦИИ

### **Функциональные метрики:**
- [ ] Поставщик может успешно одобрить заказ с указанием packagesCount и volume
- [ ] Фулфилмент может выбрать сотрудника и логистику при приемке
- [ ] Все статусы корректно переходят от PENDING до DELIVERED
- [ ] Каждый участник видит только свои заказы в правильных статусах

### **Технические метрики:**
- [ ] Нет ошибок в консоли при переходах статусов
- [ ] Все GraphQL мутации возвращают корректные результаты
- [ ] UI формы корректно валидируют обязательные поля
- [ ] Real-time обновления работают для всех участников

---

**Документ содержит полный анализ существующей системы и детальный план реализации недостающего функционала для создания полноценной 4-участнической цепочки поставок товаров.**