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

📦 V2 СИСТЕМА СЕЛЛЕРСКИХ РАСХОДНИКОВ

Статус: ✅ РЕАЛИЗОВАНО И АКТИВНО (август 2025)
Версия: 2.0
Заменяет: V1 Supply система для селлерских расходников

---

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

ПРИНЦИП РАБОТЫ V2:

• Специализированные модели вместо универсальной Supply таблицы
• Автоматическое управление инвентарем при смене статусов заказов
• Доменная изоляция между типами организаций
• Совместимость фронтенда через адаптированные резолверы

КЛЮЧЕВЫЕ КОМПОНЕНТЫ:

1. SellerConsumableInventory - основная модель V2
2. seller-inventory-v2.ts - GraphQL резолверы
3. inventory-management.ts - бизнес-логика управления
4. Автоматические триггеры в seller-consumables.ts

---

🗃️ МОДЕЛЬ ДАННЫХ

SellerConsumableInventory

model SellerConsumableInventory {
  id                  String   @id @default(cuid())
  sellerId            String   // Владелец расходников (селлер)
  fulfillmentCenterId String   // Фулфилмент-центр где хранятся
  productId           String   // Товар-расходник
  
  // === СКЛАДСКИЕ ДАННЫЕ ===
  currentStock        Int      @default(0)     // Текущий остаток
  minStock           Int      @default(0)     // Минимальный остаток
  maxStock           Int?                     // Максимальный остаток
  reservedStock      Int      @default(0)     // Зарезервировано
  totalReceived      Int      @default(0)     // Всего получено
  totalUsed          Int      @default(0)     // Всего использовано
  
  // === ФИНАНСОВЫЕ ДАННЫЕ ===
  averageCost        Decimal  @default(0)     // Средняя себестоимость
  usagePrice         Decimal?                 // Цена использования
  
  // === ВРЕМЕННЫЕ МЕТКИ ===
  lastSupplyDate     DateTime?                // Последняя поставка
  lastUsageDate      DateTime?                // Последнее использование
  
  // === МЕТАДАННЫЕ ===
  notes              String?                  // Заметки
  createdAt          DateTime @default(now())
  updatedAt          DateTime @updatedAt
  
  // === СВЯЗИ ===
  seller             Organization @relation("SellerInventory")
  fulfillmentCenter  Organization @relation("SellerInventoryWarehouse") 
  product            Product      @relation("SellerInventoryProducts")
  
  @@unique([sellerId, fulfillmentCenterId, productId])
}

КЛЮЧЕВЫЕ ИНДЕКСЫ:

• [sellerId, currentStock] - быстрый поиск по остаткам селлера
• [fulfillmentCenterId, sellerId] - поиск по фулфилменту
• [currentStock, minStock] - контроль минимальных остатков

---

🔄 БИЗНЕС-ПРОЦЕССЫ

1. СОЗДАНИЕ ЗАКАЗА СЕЛЛЕРОМ

graph TD
    A[Селлер создает заказ] --> B[createSellerConsumableSupplyOrder]
    B --> C[Статус: PENDING]
    C --> D[Уведомление поставщику]

Компоненты:

• CreateConsumablesSupplyPage - форма создания
• createSellerConsumableSupplyOrder - мутация

2. ОБРАБОТКА ПОСТАВЩИКОМ

graph TD
    A[PENDING] --> B[Поставщик одобряет]
    B --> C[SUPPLIER_APPROVED]
    C --> D[Автоматический переход в CONFIRMED]

3. ДОСТАВКА И ПОПОЛНЕНИЕ ИНВЕНТАРЯ

graph TD
    A[SHIPPED] --> B[Фулфилмент получает]
    B --> C[updateSellerSupplyStatus: DELIVERED]
    C --> D[🔄 АВТОМАТИЧЕСКИЙ ТРИГГЕР]
    D --> E[processSellerConsumableSupplyReceipt]
    E --> F[Обновление SellerConsumableInventory]
    F --> G[Пересчет averageCost]

Автоматический триггер (seller-consumables.ts:547-554):

if (status === 'DELIVERED') {
  const inventoryItems = updatedSupply.items.map(item => ({
    productId: item.productId,
    receivedQuantity: item.quantity,
    unitPrice: parseFloat(item.price.toString()),
  }))
  
  await processSellerConsumableSupplyReceipt(args.id, inventoryItems)
}

---

🛠️ ТЕХНИЧЕСКИЕ КОМПОНЕНТЫ

GraphQL Резолверы (seller-inventory-v2.ts):

mySellerConsumableInventory

• Доступ: Только селлеры
• Назначение: Получение собственного инвентаря
• Фильтрация: По sellerId из контекста

allSellerConsumableInventory

• Доступ: Только фулфилмент-центры
• Назначение: Управление всем инвентарем селлеров
• Фильтрация: По fulfillmentCenterId из контекста

Функции управления инвентарем (inventory-management.ts):

processSellerConsumableSupplyReceipt

async function processSellerConsumableSupplyReceipt(
  supplyOrderId: string,
  inventoryItems: Array<{
    productId: string
    receivedQuantity: number
    unitPrice: number
  }>
)

updateSellerInventory

• Автоматическое создание записей инвентаря
• Пересчет средней стоимости (FIFO принцип)
• Обновление статистики (totalReceived, currentStock)

---

🔄 МИГРАЦИЯ V1 → V2

ЧТО УДАЛЕНО ИЗ V1:

• ❌ Создание Supply записей в updateSupplyOrderStatus
• ❌ Создание Supply записей в fulfillmentReceiveOrder
• ❌ Создание Supply записей в createSupplyOrder
• ❌ Дублирование данных между системами

ЧТО СОХРАНЕНО:

• ✅ GraphQL совместимость через формат Supply
• ✅ Фронтенд работает без изменений
• ✅ Существующие V1 Supply записи (архивные)

АДАПТЕРЫ СОВМЕСТИМОСТИ:

sellerSuppliesOnWarehouse (V1→V2)

// Преобразование SellerConsumableInventory → Supply формат
const suppliesFormatted = sellerInventory.map((item) => ({
  // V2 данные адаптируются в V1 формат
  id: item.id,
  name: item.product.name,
  currentStock: item.currentStock,
  type: 'SELLER_CONSUMABLES',
  sellerOwner: {
    id: item.seller.id,
    name: item.seller.name || 'Неизвестно',
    inn: item.seller.inn || 'НЕ_УКАЗАН'
  }
}))

---

🎨 ФРОНТЕНД ИНТЕГРАЦИЯ

ФИЛЬТРАЦИЯ ПОСТАВОК:

/seller/supplies/goods/cards - ТОЛЬКО товары

goodsSupplies={(mySuppliesData?.mySupplyOrders || []).filter((supply: any) => 
  supply.consumableType !== 'SELLER_CONSUMABLES' // Исключаем расходники
)}

/seller/supplies/consumables - ТОЛЬКО расходники

const sellerOrders = (data?.supplyOrders || []).filter((order: SupplyOrder) => {
  return order.organization.id === user?.organization?.id && 
         order.consumableType === 'SELLER_CONSUMABLES' // Только расходники
})

КОМПОНЕНТЫ UI:

• SuppliesDashboard - главный дашборд с фильтрацией
• AllSuppliesTab - показывает товарные поставки
• SellerSupplyOrdersTab - показывает поставки расходников

---

📊 ПРЕИМУЩЕСТВА V2 СИСТЕМЫ

ПРОИЗВОДИТЕЛЬНОСТЬ:

• ✅ Специализированные запросы вместо JOIN по всей Supply таблице
• ✅ Индексированный поиск по sellerId и fulfillmentCenterId
• ✅ Кэширование на уровне GraphQL

ТОЧНОСТЬ ДАННЫХ:

• ✅ Автоматический расчет средней себестоимости (FIFO)
• ✅ Раздельная статистика поступлений и расходов
• ✅ Исключение дублирования данных

МАСШТАБИРУЕМОСТЬ:

• ✅ Доменная изоляция - каждый тип организации имеет свои модели
• ✅ Независимые обновления - изменения в одной системе не влияют на другие
• ✅ Простое добавление новых типов расходников

---

🛡️ БЕЗОПАСНОСТЬ И КОНТРОЛЬ

ДОСТУП К ДАННЫМ:

• Селлеры: Видят только свой инвентарь (mySellerConsumableInventory)
• Фулфилмент: Видит весь инвентарь селлеров на своем складе (allSellerConsumableInventory)
• Остальные: Доступ запрещен

АУДИТ ИЗМЕНЕНИЙ:

• Все изменения логируются через console.warn
• Временные метки lastSupplyDate/lastUsageDate
• Полная история в totalReceived/totalUsed

---

🔧 КОМАНДЫ И ТЕСТИРОВАНИЕ

ПОЛЕЗНЫЕ ЗАПРОСЫ:

-- Проверка инвентаря селлера
SELECT * FROM seller_consumable_inventory 
WHERE seller_id = 'SELLER_ID';

-- Статистика по фулфилменту
SELECT 
  seller_id,
  COUNT(*) as products_count,
  SUM(current_stock) as total_stock
FROM seller_consumable_inventory 
WHERE fulfillment_center_id = 'FULFILLMENT_ID'
GROUP BY seller_id;

ТЕСТИРОВАНИЕ:

# Проверка V2 системы
node -e "..." # См. примеры в коде

# Тестирование GraphQL
curl -X POST http://localhost:3001/api/graphql -d '{
  "query": "query { mySellerConsumableInventory { id currentStock } }"
}'

---

🚀 СТАТУС ВНЕДРЕНИЯ

✅ ЗАВЕРШЕНО (август 2025):

• SellerConsumableInventory модель создана
• GraphQL резолверы реализованы
• Автоматическое пополнение работает
• V1 код удален полностью
• UI фильтрация исправлена
• Система протестирована

📋 READY FOR PRODUCTION:

• Все тесты проходят
• Сборка успешна
• GraphQL эндпоинты работают
• Фронтенд совместим
• Нет breaking changes

---

📚 СВЯЗАННАЯ ДОКУМЕНТАЦИЯ

• SUPPLY_CHAIN_WORKFLOW_V2.md - общий workflow V2 систем
• SELLER_DOMAIN.md - домен селлеров
• FULFILLMENT_DOMAIN.md - домен фулфилмента
• PRISMA_MODEL_RULES.md - правила моделей данных
• COMPONENT_ARCHITECTURE.md - архитектура компонентов

---

🏆 РЕЗУЛЬТАТ: Полнофункциональная V2 система управления расходниками селлеров с автоматическим инвентарем, доменной изоляцией и совместимостью с существующим фронтендом.