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

# 🚚 WORKFLOW ЦЕПОЧКИ ПОСТАВОК SFERA v2.0

> **⚠️ ВАЖНО:** Этот документ описывает НОВУЮ архитектуру системы поставок с разделением на отдельные типы. Для старой системы см. SUPPLY_CHAIN_WORKFLOW.md

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

Система поставок SFERA v2.0 включает **5 типов поставок**, разделенных на две категории:

### 📦 **ПОСТАВКИ НА ФУЛФИЛМЕНТ**
- `GoodsSupplyOrder` - товары селлера → склад ФФ
- `FulfillmentConsumableSupplyOrder` - расходники ФФ → склад ФФ
- `SellerConsumableSupplyOrder` - расходники селлера → склад ФФ

### 🛒 **ПОСТАВКИ НА МАРКЕТПЛЕЙСЫ**
- `OzonSupplyOrder` - готовые продукты → Ozon
- `WildberriesSupplyOrder` - готовые продукты → Wildberries

---

## 🔄 WORKFLOW ПО ТИПАМ ПОСТАВОК

### 1️⃣ **WORKFLOW: Поставки расходников ФФ**

```mermaid
graph TD
    A[ФФ создает заказ расходников] --> B[PENDING]
    B --> C{Поставщик одобряет?}
    C -->|Да| D[SUPPLIER_APPROVED]
    C -->|Нет| X[CANCELLED]
    D --> E{Логистика назначена?}
    E -->|Да| F[LOGISTICS_CONFIRMED] 
    E -->|Нет| D
    F --> G[Поставщик отгружает]
    G --> H[SHIPPED]
    H --> I[IN_TRANSIT]
    I --> J[ФФ принимает на склад]
    J --> K[DELIVERED]
    
    style A fill:#e1f5fe
    style K fill:#c8e6c9
    style X fill:#ffcdd2
```

**Участники:**
- 🏭 **Фулфилмент** - создатель, получатель
- 🏪 **Поставщик (WHOLESALE)** - одобрение, отгрузка
- 🚛 **Логистика (LOGIST)** - доставка

**Особенности:**
- ✅ ФФ видит все детали + устанавливает цены продажи селлерам
- ✅ Поставщик видит товары/количества, НЕ видит цены продажи ФФ
- ✅ Показывается сразу после создания

### 2️⃣ **WORKFLOW: Поставки товаров селлера**

```mermaid
graph TD
    A[Селлер создает заказ товаров] --> B[PENDING]
    B --> C{Поставщик одобряет?}
    C -->|Да| D[SUPPLIER_APPROVED]
    C -->|Нет| X[CANCELLED]
    D --> E{Логистика назначена?}
    E -->|Да| F[LOGISTICS_CONFIRMED]
    E -->|Нет| D
    F --> G[Поставщик отгружает]
    G --> H[SHIPPED]
    H --> I[IN_TRANSIT]
    I --> J[ФФ принимает + обрабатывает]
    J --> K[DELIVERED]
    
    style A fill:#fff3e0
    style K fill:#c8e6c9
    style X fill:#ffcdd2
```

**Участники:**
- 🛒 **Селлер** - создатель, владелец товара
- 🏪 **Поставщик (WHOLESALE)** - поставка
- 🚛 **Логистика (LOGIST)** - доставка  
- 🏭 **Фулфилмент** - получатель, обработка

**Особенности:**
- ✅ Селлер видит свои товары + рецептуры + закупочные цены
- ✅ ФФ видит товары + рецептуры + услуги, НЕ видит закупочные цены селлера
- ✅ Поставщик видит товары + количества, НЕ видит рецептуры
- ✅ Расходники селлера идут **в состав продукта**, не отслеживаются отдельно

### 3️⃣ **WORKFLOW: Поставки расходников селлера**

```mermaid
graph TD
    A[Селлер заказывает свои расходники] --> B[PENDING]
    B --> C{Поставщик одобряет?}
    C -->|Да| D[SUPPLIER_APPROVED]
    C -->|Нет| X[CANCELLED]
    D --> E{Логистика назначена?}
    E -->|Да| F[LOGISTICS_CONFIRMED]
    E -->|Нет| D
    F --> G[Поставщик отгружает]
    G --> H[SHIPPED]
    H --> I[IN_TRANSIT]
    I --> J[ФФ принимает НА ХРАНЕНИЕ]
    J --> K[DELIVERED]
    
    style A fill:#f3e5f5
    style K fill:#c8e6c9
    style X fill:#ffcdd2
```

**Участники:**
- 🛒 **Селлер** - создатель, владелец расходников
- 🏪 **Поставщик (WHOLESALE)** - поставка
- 🚛 **Логистика (LOGIST)** - доставка
- 🏭 **Фулфилмент** - хранитель (НЕ владелец)

**Особенности:**
- ✅ Селлер видит свои расходники + закупочные цены
- ✅ ФФ видит факт хранения + количества, НЕ видит закупочные цены селлера
- ✅ Срок хранения + права доступа настраиваются
- ✅ Используются селлером в рецептурах своих товаров

---

## 📊 СТАТУСЫ И ПЕРЕХОДЫ

### **SupplyOrderStatus (поставки НА фулфилмент)**

| Статус | Описание | Ответственный | Действия |
|--------|----------|---------------|----------|
| `PENDING` | Ожидает одобрения поставщика | Поставщик | Одобрить/Отклонить |
| `SUPPLIER_APPROVED` | Одобрено поставщиком | Логистика | Назначить маршрут |
| `LOGISTICS_CONFIRMED` | Логистика подтверждена | Поставщик | Отгрузить товар |
| `SHIPPED` | Отгружено | Система | Автоматический переход |
| `IN_TRANSIT` | В пути | Логистика | Отслеживание доставки |
| `DELIVERED` | Доставлено | ФФ | Принять на склад |
| `CANCELLED` | Отменено | Любой участник | Указать причину |

### **MarketplaceSupplyStatus (поставки НА маркетплейсы)**

| Статус | Описание | Ответственный | Действия |
|--------|----------|---------------|----------|
| `PLANNED` | Запланирована | ФФ | Подготовить товары |
| `PREPARED` | Подготовлена | ФФ | Отгрузить |
| `SHIPPED_TO_MARKETPLACE` | Отгружена | Маркетплейс | Принять товар |
| `ACCEPTED_BY_MARKETPLACE` | Принята | Система | Обновить остатки |
| `CANCELLED` | Отменена | ФФ/Маркетплейс | Указать причину |

---

## 🎭 РОЛИ И ПРАВА ДОСТУПА

### 🏭 **ФУЛФИЛМЕНТ**

**Может создавать:**
- ✅ Поставки расходников ФФ
- ✅ Поставки на маркетплейсы

**Может видеть:**
- ✅ Свои поставки расходников: все детали + цены продажи
- ✅ Товарные поставки селлеров: товары + рецептуры, НЕ закупочные цены
- ✅ Расходники селлеров на хранении: количества, НЕ закупочные цены

### 🛒 **СЕЛЛЕР** 

**Может создавать:**
- ✅ Товарные поставки
- ✅ Поставки расходников селлера

**Может видеть:**
- ✅ Свои товарные поставки: все детали + рецептуры + закупочные цены
- ✅ Свои расходники: все детали + закупочные цены
- ❌ Чужие поставки
- ❌ Поставки расходников ФФ

### 🏪 **ПОСТАВЩИК (WHOLESALE)**

**Может видеть:**
- ✅ Заказы к себе: товары + количества
- ❌ Рецептуры товаров
- ❌ Цены продажи ФФ селлерам
- ❌ Услуги ФФ

### 🚛 **ЛОГИСТИКА (LOGIST)**

**Может видеть:**
- ✅ Маршруты + объемы + вес
- ❌ Коммерческие данные (цены, услуги)
- ❌ Рецептуры товаров

---

## 🌐 ИНТЕРФЕЙСЫ СИСТЕМЫ

### 📦 **Кабинет фулфилмента**

**URL:** `/fulfillment-supplies/`

**Вкладки:**
- `ff-consumables` - поставки расходников ФФ (создание + просмотр)
- `seller-consumables` - расходники селлеров на хранении  
- `goods?status=new` - новые товарные поставки
- `goods?status=receiving` - товары в приемке
- `goods?status=accepted` - принятые товары

### 🛒 **Кабинет селлера**

**URL:** `/seller-supplies/`

**Вкладки:**
- `my-goods` - мои товарные поставки
- `my-consumables` - мои расходники
- `create-goods` - создать поставку товаров  
- `create-consumables` - заказать расходники

### 🛍️ **Кабинет маркетплейсов**

**URL:** `/marketplace-supplies/`

**Вкладки:**
- `ozon` - поставки на Ozon
- `wildberries` - поставки на Wildberries
- `create-ozon` - создать поставку на Ozon
- `create-wildberries` - создать поставку на WB

---

## ⚡ ОСОБЕННОСТИ РЕАЛИЗАЦИИ

### 🔄 **Дополнение данных по этапам**

Каждая поставка - это **одна запись**, которая дополняется участниками:

```typescript
// Создание (селлер/ФФ)
supply = {
  id: "...",
  status: "PENDING",
  sellerId: "...",        // кто создал
  requestedDate: "...",   // когда нужно
  items: [...]           // что заказано
}

// Одобрение (поставщик)
supply = {
  ...supply,
  status: "SUPPLIER_APPROVED",
  supplierId: "...",      // кто одобрил
  approvedAt: "...",      // когда одобрил
  packagesCount: 5,       // уточненные параметры
  estimatedVolume: 2.5
}

// Назначение логистики (ФФ)
supply = {
  ...supply, 
  status: "LOGISTICS_CONFIRMED",
  logisticsPartnerId: "...",  // кто повезет
  routeId: "...",             // маршрут
  logisticsCost: 1500         // стоимость
}
```

### 🔐 **Фильтрация по безопасности**

Каждый resolver применяет фильтрацию по роли:

```typescript
// Пример: поставки расходников ФФ
const supplies = await prisma.fulfillmentConsumableSupplyOrder.findMany({
  where: {
    // Только свои поставки для ФФ
    fulfillmentCenterId: user.organizationId  
  }
})

// Фильтрация полей по роли
return supplies.map(supply => 
  SupplyDataFilter.filterByRole(supply, user.organizationType)
)
```

### 📈 **Масштабируемость**

Новые типы поставок добавляются независимо:

```typescript
// Будущее: Поставки на Яндекс.Маркет
interface YandexMarketSupplyOrder {
  // специфичные поля для Яндекс.Маркета
}

// Отдельные операции
createYandexMarketSupply()
myYandexMarketSupplies()
```

---

## ✅ ПРЕИМУЩЕСТВА НОВОЙ АРХИТЕКТУРЫ

### 🎯 **Четкое разделение ответственности**
- Каждый тип поставки имеет свою логику
- Независимая разработка и тестирование
- Простота добавления новых типов

### 🔒 **Надежная безопасность**  
- Раздельные правила доступа для каждого типа
- Невозможно случайно показать чужие данные
- Гранулярные права по ролям

### 📈 **Масштабируемость**
- Легко добавлять новые маркетплейсы
- Независимые схемы для разных процессов  
- Оптимизация каждого типа отдельно

### 🛡️ **Безопасная миграция**
- Поэтапное внедрение без остановки системы
- Система откатов на каждом этапе
- Сохранение работоспособности старой системы

---

## 🚀 ПЛАН ВНЕДРЕНИЯ

### **Phase 1:** FulfillmentConsumableSupplyOrder ⏳
- Новая модель данных
- GraphQL операции  
- Интерфейс создания и просмотра
- Тестирование

### **Phase 2:** SellerConsumableSupplyOrder 
- Аналогично Phase 1
- Интеграция с системой хранения

### **Phase 3:** GoodsSupplyOrder
- Самый сложный тип с рецептурами
- Миграция существующих товарных поставок

### **Phase 4:** Поставки на маркетплейсы
- Отдельная система для Ozon/WB
- API интеграции с маркетплейсами

### **Phase 5:** Очистка и оптимизация
- Миграция старых данных
- Удаление устаревшего кода (с одобрения)
- Финальная оптимизация

**Следующий шаг:** Начало реализации Phase 1 - FulfillmentConsumableSupplyOrder