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 мутация создания:

// 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

Исправленный код фильтрации:

// Для кабинета ПОСТАВЩИКА фильтруем по 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

Критическая проблема статусов:

// ❌ КОНФЛИКТ: Резолвер ожидает статус 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

Статусы, которые логистика может обработать:

// Логистика может подтвердить заказы со статусами:
order.status === 'SUPPLIER_APPROVED' || order.status === 'CONFIRMED'

✅ Что работает:

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

❌ Выявленные проблемы:

• Нет маршрутизации: отсутствует система планирования маршрутов
• Нет трекинга: отсутствует детальное отслеживание статуса доставки
• Нет интеграции: отсутствует интеграция с внешними логистическими системами

---

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

Текущие статусы системы:

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 Схемы (обновить):

# Обновить мутацию поставщика:
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 (добавить):

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-участнической цепочки поставок товаров.