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

# ПРАВИЛА ПАРАМЕТРОВ ПОСТАВКИ

## 📋 **ОПРЕДЕЛЕНИЕ ПАРАМЕТРОВ ПОСТАВКИ**

**Параметры поставки** - это все характеристики и данные, которые описывают конкретную поставку товаров в системе SFERA.

## 🎯 **КЛАССИФИКАЦИЯ ПАРАМЕТРОВ ПОСТАВКИ**

### **1. ОБЯЗАТЕЛЬНЫЕ ПАРАМЕТРЫ:**
- **`id`** - Уникальный идентификатор поставки
- **`deliveryDate`** - Дата поставки (когда товары должны быть доставлены)
- **`totalAmount`** - Общая стоимость поставки
- **`totalItems`** - Количество товаров в поставке
- **`organizationId`** - Идентификатор заказчика
- **`partnerId`** - Идентификатор поставщика
- **`status`** - Статус поставки (PENDING, APPROVED, SHIPPED и т.д.)

### **2. ЦЕНОВЫЕ ПАРАМЕТРЫ:**
- **`totalAmount`** - Общая сумма поставки
- **`goodsPrice`** - Стоимость товаров (расчетное поле)
- **`servicesPrice`** - Стоимость услуг фулфилмента (расчетное поле)
- **`logisticsPrice`** - Стоимость логистических услуг (расчетное поле)
- **`sellerConsumablesPrice`** - Стоимость расходников селлера (расчетное поле)
- **`ffConsumablesPrice`** - Стоимость расходников фулфилмента (расчетное поле)

### **3. ТОВАРНЫЕ ПАРАМЕТРЫ:**
- **`items[]`** - Массив товаров с количествами и ценами
- **`productId`** - ID товара в позиции
- **`quantity`** - Количество каждого товара
- **`price`** - Цена за единицу товара
- **`totalPrice`** - Общая стоимость позиции
- **`services[]`** - Массив услуг для товара
- **`fulfillmentConsumables[]`** - Расходники фулфилмента для товара
- **`sellerConsumables[]`** - Расходники селлера для товара
- **`marketplaceCardId`** - ID карточки маркетплейса

### **4. ЛОГИСТИЧЕСКИЕ ПАРАМЕТРЫ:**
- **`packagesCount`** - Количество грузовых мест
- **`volume`** - Объём груза в м³
- **`routes[]`** - Маршруты доставки
- **`fromLocation`** - Точка забора груза
- **`toLocation`** - Точка доставки
- **`fromAddress`** - Полный адрес забора
- **`toAddress`** - Полный адрес доставки
- **`distance`** - Расстояние маршрута в км
- **`estimatedTime`** - Время доставки в часах
- **`logisticsPartnerId`** - ID логистического партнера

### **5. УПРАВЛЕНЧЕСКИЕ ПАРАМЕТРЫ:**
- **`responsibleEmployee`** - Ответственный сотрудник
- **`notes`** - Комментарии и дополнительная информация
- **`createdAt`** - Дата создания поставки
- **`updatedAt`** - Дата последнего обновления
- **`fulfillmentCenterId`** - ID фулфилмент центра
- **`consumableType`** - Тип расходников

<!-- ОТКАТ: Расширенная классификация параметров поставки

### **6. ВРЕМЕННЫЕ ПАРАМЕТРЫ:**
- **`deliveryDate`** - Плановая дата доставки
- **`readyDate`** - Дата готовности к отгрузке
- **`actualDeliveryDate`** - Фактическая дата доставки
- **`createdAt`** - Время создания заявки
- **`approvedAt`** - Время одобрения поставщиком
- **`shippedAt`** - Время отгрузки

### **7. КОНТАКТНЫЕ ПАРАМЕТРЫ:**
- **`supplierContact`** - Контактное лицо поставщика
- **`buyerContact`** - Контактное лицо покупателя
- **`logisticsContact`** - Контактное лицо логистики
- **`fulfillmentContact`** - Контактное лицо фулфилмента

### **8. АДРЕСНЫЕ ПАРАМЕТРЫ:**
- **`pickupAddress`** - Адрес забора груза
- **`deliveryAddress`** - Адрес доставки
- **`warehouseLocation`** - Местоположение склада
- **`marketLocation`** - Адрес торговой точки

### **9. КАЧЕСТВЕННЫЕ ПАРАМЕТРЫ:**
- **`qualityRequirements`** - Требования к качеству товаров
- **`temperatureConditions`** - Температурные условия хранения/транспортировки
- **`handlingInstructions`** - Инструкции по обращению с грузом
- **`packagingType`** - Тип упаковки товаров
- **`fragileGoods`** - Отметка о хрупких товарах

### **10. ФИНАНСОВЫЕ ПАРАМЕТРЫ:**
- **`paymentTerms`** - Условия оплаты
- **`paymentMethod`** - Способ оплаты
- **`currency`** - Валюта расчетов
- **`taxRate`** - Налоговая ставка
- **`invoiceNumber`** - Номер счета
- **`paymentStatus`** - Статус оплаты

### **11. ТЕХНИЧЕСКИЕ ПАРАМЕТРЫ:**
- **`supplyOrderId`** - Уникальный идентификатор поставки
- **`supplierOrderNumber`** - Внутренний номер заказа поставщика
- **`trackingNumber`** - Трек-номер для отслеживания
- **`barcodes`** - Штрих-коды товаров
- **`rfidTags`** - RFID метки для автоматизации

### **12. АНАЛИТИЧЕСКИЕ ПАРАМЕТРЫ:**
- **`profitMargin`** - Маржинальность поставки
- **`supplierRating`** - Рейтинг поставщика
- **`deliveryReliability`** - Надежность доставки
- **`orderPriority`** - Приоритет заказа
- **`seasonalFactor`** - Сезонный коэффициент

-->

## 🔄 **ЖИЗНЕННЫЙ ЦИКЛ ПАРАМЕТРОВ ПОСТАВКИ**

### **Этап 1: Создание поставки (SELLER)**
```typescript
// Селлер указывает базовые параметры поставки
{
  deliveryDate: "2025-08-25",
  totalItems: 100,
  items: [...products],
  partnerId: "supplier-123",
  organizationId: "seller-456"
}
```

### **Этап 2: Одобрение поставщиком (WHOLESALE)**
```typescript
// Поставщик может дополнить параметры поставки
{
  status: "SUPPLIER_APPROVED",
  packagesCount: 3,        // Новый параметр
  volume: 1.2,            // Новый параметр
  readyDate: "2025-08-24", // Новый параметр
  notes: "Хрупкий груз"    // Новый параметр
}
```

### **Этап 3: Логистическое планирование (LOGIST)**
```typescript
// Логистика использует параметры для расчетов
{
  logisticsPrice: calculateByVolume(volume, distance),
  routes: [
    {
      from: "Садовод",
      to: "ФФ Центр",
      packagesCount: 3,
      volume: 1.2
    }
  ]
}
```

## 🛡️ **ПРАВИЛА БЕЗОПАСНОСТИ ПАРАМЕТРОВ**

### **Видимость по ролям:**

| Параметр поставки | SELLER | WHOLESALE | FULFILLMENT | LOGIST |
|------------------|--------|-----------|-------------|---------|
| deliveryDate     | ✅     | ✅        | ✅          | ✅     |
| totalAmount      | ✅     | ❌        | ❌          | ❌     |
| productPrice     | ✅     | ✅        | ❌          | ❌     |
| packagesCount    | ✅     | ✅        | ✅          | ✅     |
| volume           | ✅     | ✅        | ✅          | ✅     |
| recipe           | ✅     | ❌        | ✅          | ❌     |
| logisticsPrice   | ✅     | ❌        | ✅          | ✅     |

### **Права на изменение:**

- **SELLER**: Может изменять до одобрения поставщиком
- **WHOLESALE**: Может добавлять логистические параметры при одобрении
- **FULFILLMENT**: Не может изменять, только просматривать
- **LOGIST**: Может добавлять маршруты и логистические расчеты

## 🎛️ **UI КОМПОНЕНТЫ ДЛЯ ПАРАМЕТРОВ ПОСТАВКИ**

### **Форма ввода параметров поставщиком:**

```jsx
<div className="supply-parameters-form">
  <h3>Параметры поставки</h3>
  
  {/* Основные параметры */}
  <Input name="deliveryDate" label="Дата поставки" type="date" required />
  <Input name="totalAmount" label="Общая стоимость" type="number" readOnly />
  
  {/* Логистические параметры (опционально) */}
  <Input name="packagesCount" label="Количество грузовых мест" type="number" />
  <Input name="volume" label="Объём груза (м³)" type="number" step="0.01" />
  
  {/* Дополнительные параметры */}
  <Input name="readyDate" label="Дата готовности" type="date" />
  <Textarea name="notes" label="Комментарии к поставке" />
</div>
```

### **Отображение в таблице заявок:**

```jsx
<Table>
  <TableHeader>
    <TableRow>
      <TableHead>Дата поставки</TableHead>
      <TableHead>Количество товаров</TableHead>
      <TableHead>Стоимость товаров</TableHead>
      {userRole !== 'WHOLESALE' && <TableHead>Общая стоимость</TableHead>}
      <TableHead>Параметры логистики</TableHead>
      <TableHead>Статус</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    {supplies.map(supply => (
      <TableRow key={supply.id}>
        <TableCell>{supply.deliveryDate}</TableCell>
        <TableCell>{supply.totalItems}</TableCell>
        <TableCell>{formatCurrency(supply.productPrice)}</TableCell>
        {userRole !== 'WHOLESALE' && (
          <TableCell>{formatCurrency(supply.totalAmount)}</TableCell>
        )}
        <TableCell>
          {supply.packagesCount && `${supply.packagesCount} мест`}
          {supply.volume && ` • ${supply.volume} м³`}
        </TableCell>
        <TableCell><StatusBadge status={supply.status} /></TableCell>
      </TableRow>
    ))}
  </TableBody>
</Table>
```

## 📊 **ВАЛИДАЦИЯ ПАРАМЕТРОВ ПОСТАВКИ**

### **Серверная валидация:**

```typescript
function validateSupplyParameters(params: SupplyParameters) {
  // Обязательные параметры
  if (!params.deliveryDate) throw new Error('Дата поставки обязательна')
  if (!params.totalItems || params.totalItems <= 0) {
    throw new Error('Количество товаров должно быть больше 0')
  }
  
  // Логистические параметры
  if (params.packagesCount && params.packagesCount <= 0) {
    throw new Error('Количество грузовых мест должно быть положительным')
  }
  
  if (params.volume && params.volume <= 0) {
    throw new Error('Объём груза должен быть положительным')
  }
  
  // Даты
  if (params.readyDate && params.deliveryDate) {
    if (new Date(params.readyDate) > new Date(params.deliveryDate)) {
      throw new Error('Дата готовности не может быть позже даты поставки')
    }
  }
}
```

## 🔍 **ПОИСК И ФИЛЬТРАЦИЯ ПО ПАРАМЕТРАМ**

### **GraphQL запрос с фильтрами:**

```graphql
query GetSuppliesByParameters(
  $deliveryDateFrom: DateTime
  $deliveryDateTo: DateTime
  $minAmount: Float
  $maxAmount: Float
  $status: SupplyStatus
  $hasLogisticsParams: Boolean
) {
  mySupplyOrders(
    filters: {
      deliveryDate: { gte: $deliveryDateFrom, lte: $deliveryDateTo }
      totalAmount: { gte: $minAmount, lte: $maxAmount }
      status: $status
      packagesCount: { isNull: $hasLogisticsParams }
    }
  ) {
    id
    deliveryDate
    totalAmount
    totalItems
    packagesCount
    volume
    status
  }
}
```

## 📈 **АНАЛИТИКА ПО ПАРАМЕТРАМ ПОСТАВКИ**

### **Ключевые метрики:**
- Средний объём поставки (в м³)
- Среднее количество грузовых мест
- Распределение по стоимости поставок
- Время цикла от создания до доставки
- Процент поставок с дополнительными параметрами

---

*Все параметры поставки служат для оптимизации логистических процессов и обеспечения прозрачности цепочки поставок в экосистеме SFERA.*