# ПРАВИЛА СИСТЕМЫ УПРАВЛЕНИЯ СКЛАДАМИ И ПОСТАВКАМИ - ПОЛНАЯ БАЗА ЗНАНИЙ v3.0

> ⚠️ **ВАЖНОЕ ПРИМЕЧАНИЕ**: Данный файл является объединенной полной базой знаний системы, созданной на основе rules.md, rules1.md и rules2.md. Все изменения должны согласовываться.

## 🔤 ТЕРМИНЫ СИСТЕМЫ
> Для людей → `В коде`
- ТОВАР → `PRODUCT`
- РАСХОДНИКИ → `CONSUMABLE`
- БРАК → `DEFECT` *(планируется)*
- ПРОДУКТ → `FINISHED_PRODUCT` *(планируется)*
- ПОСТАВЩИК → `WHOLESALE`
- СЕЛЛЕР → `SELLER`
- ФУЛФИЛМЕНТ → `FULFILLMENT`
- ЛОГИСТИКА → `LOGIST`

---

## 📑 ОГЛАВЛЕНИЕ

### 🏗️ **АРХИТЕКТУРА И ОСНОВЫ**

1. [🎯 Основные принципы системы](#1--основные-принципы-системы)
2. [📦 Типизация предметов](#2--типизация-предметов)
3. [🏢 Структура кабинетов](#3--структура-кабинетов)
4. [🔐 Система ролей и доступов](#4--система-ролей-и-доступов)

### 🚚 **WORKFLOW И ПРОЦЕССЫ**

5. [🚚 Workflow поставок](#5--workflow-поставок)
6. [🔄 Процесс создания продукта](#6--процесс-создания-продукта)
7. [📊 Система учета движения товаров](#7--система-учета-движения-товаров)

### 🏢 **КАБИНЕТЫ СИСТЕМЫ**

8. [🏠 Общие правила кабинетов](#8--общие-правила-кабинетов)
9. [🏠 Кабинет селлера (детальные правила)](#9--кабинет-селлера-детальные-правила)
10. [🏪 Кабинет поставщика](#10--кабинет-поставщика)
11. [🏭 Кабинет фулфилмента](#11--кабинет-фулфилмента)
12. [🚚 Кабинет логистики](#12--кабинет-логистики)

### 🤝 **СИСТЕМА ПАРТНЕРСТВА**

13. [🤝 Система партнерства и контрагентов](#13--система-партнерства-и-контрагентов)

### 🌐 **ИНТЕГРАЦИИ И ФУНКЦИИ**

14. [🌐 Интеграции с системой](#14--интеграции-с-системой)
15. [📊 Статистика и аналитика](#15--статистика-и-аналитика)
16. [📱 Правила UI/UX и интерфейса](#16--правила-uiux-и-интерфейса)
17. [⚠️ Критические запреты](#17--критические-запреты)

### 🛠️ **ТЕХНИЧЕСКИЕ ПРАВИЛА**

18. [🛠️ GraphQL и TypeScript правила](#18--graphql-и-typescript-правила)
19. [🔧 Архитектурные принципы](#19--архитектурные-принципы)
20. [🎯 Правила качества кода](#20--правила-качества-кода)
21. [🔍 Диагностика и решение проблем](#21--диагностика-и-решение-проблем)

### 📋 **ПРИЛОЖЕНИЯ**

22. [📋 Категории товаров и расходников](#22--категории-товаров-и-расходников)
23. [🎖️ Приоритеты разработки](#23--приоритеты-разработки)

### 🌐 **ИНТЕГРАЦИИ И ФУНКЦИИ**

14. [🌐 Интеграции с системой](#14--интеграции-с-системой)
15. [📊 Статистика и аналитика](#15--статистика-и-аналитика)
16. [📱 Правила UI/UX и интерфейса](#16--правила-uiux-и-интерфейса)
17. [⚠️ Критические запреты](#17--критические-запреты)

### 🛠️ **ТЕХНИЧЕСКИЕ ПРАВИЛА**

18. [🛠️ GraphQL и TypeScript правила](#18--graphql-и-typescript-правила)
19. [🔧 Архитектурные принципы](#19--архитектурные-принципы)
20. [🎯 Правила качества кода](#20--правила-качества-кода)
21. [🔍 Диагностика и решение проблем](#21--диагностика-и-решение-проблем)

### 📋 **ПРИЛОЖЕНИЯ**

22. [📋 Категории товаров и расходников](#22--категории-товаров-и-расходников)
23. [🎖️ Приоритеты разработки](#23--приоритеты-разработки)

---

## 🏷️ РЕЕСТР СУЩНОСТЕЙ СИСТЕМЫ

### 📦 **ОСНОВНЫЕ ПРЕДМЕТЫ**

| Сущность   | Название в системе                 | Кабинет создания | Описание                                        | Статус          |
| ---------- | ---------------------------------- | ---------------- | ----------------------------------------------- | --------------- |
| Товар      | `Product` (type: `PRODUCT`)        | Поставщик        | Базовый тип товара от поставщика                | ✅ Реализовано  |
| Расходники | `Product` (type: `CONSUMABLE`)     | Поставщик        | Материалы и вспомогательные товары              | ✅ Реализовано  |
| Брак       | `Product` (type: `DEFECT`)*        | Фулфилмент       | Производная от товара с дефектами               | 📋 Планируется |
| Продукт    | `Product` (type: `FINISHED_PRODUCT`)* | Фулфилмент       | Готовый к продаже товар (производная от товара) | 📋 Планируется |

> **\* Планируется**: Типы `DEFECT` и `FINISHED_PRODUCT` еще не добавлены в Prisma схему

### 🏢 **ОРГАНИЗАЦИИ И РОЛИ**

| Сущность   | Название в системе                 | Основные функции                        | Статус         |
| ---------- | ---------------------------------- | --------------------------------------- | -------------- |
| Поставщик  | `Organization` (type: `WHOLESALE`) | Создание товаров, управление поставками | ✅ Реализовано |
| Селлер     | `Organization` (type: `SELLER`)    | Заказ товаров, управление поставками    | ✅ Реализовано |
| Фулфилмент | `Organization` (type: `FULFILLMENT`) | Обработка товаров, управление складом | ✅ Реализовано |
| Логистика  | `Organization` (type: `LOGIST`)    | Управление доставками                   | ✅ Реализовано |

### 🤝 **СИСТЕМА ПАРТНЕРСТВА**

| Сущность     | Название в системе | Описание                           | Статус         |
| ------------ | ------------------ | ---------------------------------- | -------------- |
| Контрагент   | `Counterparty`     | Связь между организациями          | ✅ Реализовано |
| Заявка       | `CounterpartyRequest` | Запрос на сотрудничество        | ✅ Реализовано |

---

## 1. 🎯 ОСНОВНЫЕ ПРИНЦИПЫ СИСТЕМЫ

### 1.1 Архитектура системы

**СТРУКТУРА СИСТЕМЫ ПО КАБИНЕТАМ:**

**🏢 КАБИНЕТ ПОСТАВЩИКА** - создает и управляет:
- **ТОВАР** (`PRODUCT`) - базовые товары от поставщика
- **РАСХОДНИКИ** (`CONSUMABLE`) - материалы и вспомогательные товары от поставщика

**🏭 КАБИНЕТ ФУЛФИЛМЕНТА** - принимает, обрабатывает и управляет всеми типами:
- **ТОВАР** (`PRODUCT`) - базовые товары от поставщиков (принятые на склад)
- **БРАК** (`DEFECT` - планируется) - производная от товара (товар с дефектами)
- **ПРОДУКТ** (`FINISHED_PRODUCT` - планируется) - готовый к продаже товар
- **РАСХОДНИКИ ФУЛФИЛМЕНТА** - операционные материалы фулфилмента
- **РАСХОДНИКИ СЕЛЛЕРОВ** - материалы для товаров селлеров

**🛍️ КАБИНЕТ СЕЛЛЕРА** - заказывает и управляет поставками:
- Создает заказы товаров и расходников
- Управляет поставками на фулфилмент и маркетплейсы
- Отслеживает статусы поставок

### 1.2 Основные принципы разработки

**КРИТИЧЕСКИ ВАЖНЫЕ ПРИНЦИПЫ:**

1. **Строгая типизация**: Каждый предмет имеет один из типов: ТОВАР (`PRODUCT`), РАСХОДНИКИ (`CONSUMABLE`), БРАК и ПРОДУКТ (планируется)
2. **Партнерская система**: Все связи между организациями через модель `Counterparty`
3. **Workflow статусов**: Строгая последовательность статусов поставок
4. **Безопасность доступа**: Контроль доступа на уровне GraphQL резолверов
5. **Единый источник истины**: Централизованное управление данными

---

## 2. 📦 ТИПИЗАЦИЯ ПРЕДМЕТОВ

### 2.1 Два реализованных и два планируемых типа предметов

#### **1. ТОВАР** (`PRODUCT` - базовый тип)

- **СОЗДАЕТСЯ**: Поставщиком
- **СТАТУС**: Может быть активным/неактивным
- **ЗАКАЗ**: Доступен для заказа всеми типами организаций
- **ТРАНСФОРМАЦИЯ**: Может стать ПРОДУКТОМ или БРАКОМ
- **ЦЕНА**: Обязательна, больше 0

#### **2. РАСХОДНИКИ** (`CONSUMABLE` - базовый тип)

- **СОЗДАЕТСЯ**: Поставщиком как универсальный тип
- **КЛАССИФИКАЦИЯ ПРИ ЗАКАЗЕ**:
  - Фулфилмент заказывает → "Расходники фулфилмента"
  - Селлер заказывает → "Расходники селлеров"
- **ДОСТУП**: Видны всем типам организаций в маркете

#### **3. БРАК** (`DEFECT` - планируется, производная от товара)

- **БУДЕТ СОЗДАВАТЬСЯ**: Фулфилментом на основе существующего ТОВАРА при обнаружении дефектов
- **МОМЕНТ СОЗДАНИЯ**: В процессе "Создание продукта" / "В работе" после подсчета факта
- **СВЯЗЬ**: Обязательная связь с родительским товаром (parentId)
- **ЗАКАЗ**: ЗАПРЕЩЕН заказ брака
- **СТАТУС**: Всегда неактивен для заказа
- **ЦЕНА**: Для селлера - себестоимость дефектного товара, для фулфилмента - 0
- **WORKFLOW**: Особый процесс списания и утилизации
- **УЧЕТ**: Отдельный учет в статистике потерь
- **ОТОБРАЖЕНИЕ**: Виден только для учета потерь
- **⚠️ СТАТУС РАЗРАБОТКИ**: Тип `DEFECT` еще не добавлен в схему БД

#### **4. ПРОДУКТ** (`FINISHED_PRODUCT` - планируется, производная от товара)

- **БУДЕТ СОЗДАВАТЬСЯ**: Фулфилментом на основе ТОВАРА по заказу селлера
- **ИНИЦИАТОР**: Селлер создает заказ с рецептурой, фулфилмент исполняет
- **СВЯЗЬ**: Обязательная связь с родительским товаром (parentId)
- **РЕЦЕПТУРА**: Задается селлером при создании заказа (Товар + Услуга + Расходники)
- **СТАТУСЫ**: "в работе" → "готов к отправке"
- **ЗАКАЗ**: Доступен только в статусе "готов к отправке"
- **⚠️ СТАТУС РАЗРАБОТКИ**: Тип `FINISHED_PRODUCT` еще не добавлен в схему БД

### 2.2 Обязательные поля карточки

**КРИТИЧЕСКИ ВАЖНО**: Название, артикул, цена > 0, тип предмета
**ИСКЛЮЧЕНИЕ ДЛЯ БРАКА**: Цена может быть 0 для фулфилмента (себестоимость для селлера)
**ОБЯЗАТЕЛЬНО**: Количество (может быть 0 для предзаказа)
**ДЛЯ ПРОИЗВОДНЫХ ТИПОВ**: Обязательная связь с родительским предметом

---

## 3. 🏢 СТРУКТУРА КАБИНЕТОВ

### 3.1 Общие принципы кабинетов

**КАЖДЫЙ КАБИНЕТ ИМЕЕТ:**

1. **Главная страница** (`/dashboard`) - общая информация и статистика
2. **Экономика** (`/economics`) - финансовая аналитика
3. **Универсальные разделы**:
   - Маркет (`/market`) - просмотр и заказ товаров
   - Партнеры (`/partners`) - управление контрагентами
   - Мессенджер (`/messenger`) - связь между организациями
   - Настройки (`/settings`) - профиль и API ключи

### 3.2 Специфические разделы по типам организаций

**🏪 ПОСТАВЩИК (`WHOLESALE`):**
- Склад (`/warehouse`) - управление товарами и расходниками
- Поставки (`/supplies`) - обработка заказов от селлеров

**🛍️ СЕЛЛЕР (`SELLER`):**
- Мои поставки (`/supplies`) - управление заказами товаров
- WB Интеграция (`/wb-integration`) - связь с Wildberries

**🏭 ФУЛФИЛМЕНТ (`FULFILLMENT`):**
- Склад фулфилмента (`/fulfillment-warehouse`) - управление всеми типами товаров
- Поставки фулфилмента (`/fulfillment-supplies`) - обработка поставок
- Услуги (`/services`) - управление услугами, логистикой, расходниками
- Сотрудники (`/employees`) - управление персоналом
- Статистика фулфилмента (`/fulfillment-statistics`) - детальная аналитика

**🚚 ЛОГИСТИКА (`LOGIST`):**
- Заявки (`/logistics-requests`) - управление заявками на доставку
- Маршруты (`/routes`) - планирование маршрутов

---

## 4. 🔐 СИСТЕМА РОЛЕЙ И ДОСТУПОВ

### 4.1 Контроль доступа к разделам

**ПРОВЕРКА НА УРОВНЕ КОМПОНЕНТОВ:**

```typescript
{user?.organization?.type === "FULFILLMENT" && (
  // Компоненты доступны только фулфилменту
)}
```

**СПЕЦИАЛЬНАЯ ЛОГИКА РОУТИНГА:**

```typescript
const handleSuppliesClick = () => {
  switch (user?.organization?.type) {
    case "FULFILLMENT":
      router.push("/fulfillment-supplies");
      break;
    case "SELLER":
      router.push("/supplies");
      break;
    // ... другие типы
  }
};
```

### 4.2 GraphQL проверки доступа

**В Apollo Client запросах:**

```typescript
const { data } = useQuery(GET_MY_SERVICES, {
  skip: user?.organization?.type !== "FULFILLMENT",
});
```

**В GraphQL резолверах:**

```typescript
if (currentUser.organization.type !== "FULFILLMENT") {
  throw new GraphQLError("Доступно только для фулфилмент центров");
}
```

### 4.3 Контроль доступа к заказам

- **Создатель заказа** - полный доступ к своим заказам
- **Поставщик** - доступ к заказам, где он является поставщиком
- **Фулфилмент-центр** - доступ к заказам, направленным в его центр
- **Логистическая компания** - доступ к заказам для доставки

---

## 5. 🚚 WORKFLOW ПОСТАВОК

### 5.1 Детализированная система статусов

**Статусы SupplyOrder (Заказ поставки):**

1. **PENDING** - Ожидает подтверждения поставщиком
2. **SUPPLIER_APPROVED** - Одобрено поставщиком
3. **CONFIRMED** - Подтвержден (готов к обработке)
4. **LOGISTICS_CONFIRMED** - Подтверждено логистикой
5. **SHIPPED** - Отгружено поставщиком
6. **IN_TRANSIT** - В пути (логистика доставляет)
7. **DELIVERED** - Доставлен на фулфилмент
8. **CANCELLED** - Отменен

### 5.2 Пошаговый процесс поставки

**ЭТАП 1: Создание заказа**
1. Селлер заказывает товар/расходники у поставщика
2. Система создает SupplyOrder со статусом `PENDING`
3. Автоматическое уведомление поставщику

**ЭТАП 2: Обработка поставщиком**
4. Поставщик получает оповещение
5. Поставщик нажимает "Одобрить"
6. Статус меняется на `SUPPLIER_APPROVED`

**ЭТАП 3: Передача в фулфилмент**
7. Поставка отображается в кабинете фулфилмента
8. Фулфилмент выбирает ответственного и логистику
9. Статус меняется на `CONFIRMED`

**ЭТАП 4: Логистическое подтверждение**
10. Логистика подтверждает доставку
11. Статус меняется на `LOGISTICS_CONFIRMED`

**ЭТАП 5: Отгрузка**
12. Поставщик отгружает товар
13. Статус меняется на `SHIPPED`, затем `IN_TRANSIT`

**ЭТАП 6: Доставка и приемка**
14. Логистика доставляет на фулфилмент
15. Фулфилмент принимает товар
16. Статус меняется на `DELIVERED`

### 5.3 Система уведомлений

**Обязательные уведомления:**
- Поставщику: о новом заказе
- Фулфилменту: о подтвержденной поставке
- Логистике: о назначении на заявку
- Селлеру: об изменении каждого статуса

---

## 6. 🔄 ПРОЦЕСС СОЗДАНИЯ ПРОДУКТА

### 6.1 Workflow создания продукта

**ЭТАПЫ ПРОЦЕССА:**

1. **ПОСТУПЛЕНИЕ**: Товар приходит на склад фулфилмента (статус "на складе")
2. **СОРТИРОВКА**: Перебор товара, отсеивание брака
3. **ПОДГОТОВКА К РАБОТЕ**: Менеджер задает параметры работы
4. **ОБРАБОТКА**: Превращение товара в продукт по "рецептуре" селлера
5. **ЗАВЕРШЕНИЕ**: Готовый продукт (статус "готов к отправке")

### 6.2 Управление процессом

**РАЗДЕЛ "СОЗДАНИЕ ПРОДУКТА":**

- **НОВЫЕ**: Поставки после нажатия "принято", ожидающие назначения
- **В РАБОТЕ**: Поставки в процессе обработки
- **ВЫПОЛНЕНО**: Завершенные поставки с готовыми продуктами

**ДЕЙСТВИЯ МЕНЕДЖЕРА В "НОВЫЕ":**

- **ДЕДЛАЙН**: Указание срока выполнения работы
- **ОТВЕТСТВЕННЫЙ**: Назначение исполнителя
- **МЕСТО ХРАНЕНИЯ**: Указание локации для готовых продуктов (опционально)
- **ЗАПУСК**: Нажатие кнопки "В работе"

### 6.3 Рецептура продукта

**СЕЛЛЕР УКАЗЫВАЕТ В ПОСТАВКЕ:**

- **БАЗОВЫЙ ТОВАР**: Исходный материал (например, футболка)
- **УСЛУГА ФУЛФИЛМЕНТА**: Из каталога услуг (например, "погладить")
- **РАСХОДНИК СЕЛЛЕРА**: Материалы селлера (например, фирменный пакет)
- **РАСХОДНИК ФУЛФИЛМЕНТА**: Материалы фулфилмента (например, короб + маркировка)

**РЕЗУЛЬТАТ**: ПРОДУКТ = Товар + Услуга + Расходники

### 6.4 Учет план/факт в процессе работы

**ПЛАН**: Количество товара из поставки селлера
**ФАКТ**: Реальное количество после сортировки

**ФИКСАЦИЯ БРАКА:**
- **КОГДА**: В процессе работы (вкладка "В работе")
- **КТО**: Ответственный исполнитель
- **ДЕТАЛИЗАЦИЯ**: По каждому предмету (размер/объем)
- **ОБНОВЛЕНИЕ**: Можно вносить изменения до нажатия "Выполнено"

**ВЛИЯНИЕ НА СТАТИСТИКУ:**
- При принятии поставки: +План в статистику
- При выявлении факта: корректировка на реальные данные
- **ФОРМУЛА**: Факт = Брак + Хороший товар
- **ЛОГИКА**: Фактическое количество = сумма всех пересчитанных предметов

---

## 7. 📊 СИСТЕМА УЧЕТА ДВИЖЕНИЯ ТОВАРОВ

### 7.1 Принципы учета в фулфилменте

**ОСНОВНЫЕ ПРИНЦИПЫ:**

- **ПРИХОД**: Товары поступают через принятые поставки (из состояния "в пути" → "на складе")
- **ОБРАБОТКА**: Товары переходят в статус "в работе" для создания продуктов
- **РАСХОД**: Товары убывают при отгрузке, списании, возврате, превращении в продукты
- **УЧЁТ**: Ведется учет прихода и расхода для каждого типа предметов
- **ВИЗУАЛИЗАЦИЯ**: Движение отображается в дополнительных значениях

### 7.2 Дополнительные и основные значения

**ДОПОЛНИТЕЛЬНЫЕ ЗНАЧЕНИЯ (показатели движения):**

- **ПРИБЫЛО**: Количество предметов, поступивших на склад
- **УБЫЛО**: Количество предметов, списанных со склада
- **ВЛИЯНИЕ**: От этих значений зависят основные значения (общее количество)

**ОСНОВНЫЕ ЗНАЧЕНИЯ (текущие остатки):**

- **ОПРЕДЕЛЕНИЕ**: Итоговое количество предметов на складе
- **РАСЧЁТ**: Основные значения = Предыдущие остатки + Прибыло - Убыло
- **ОТОБРАЖЕНИЕ**: Показываются в каждом модуле статистики
- **РАЗДЕЛЕНИЕ ТОВАРОВ**:
  - Товары "на складе" - готовы к обработке
  - Товары "в обработке" - находятся в процессе создания продукта

---

## 8. 🏠 ОБЩИЕ ПРАВИЛА КАБИНЕТОВ

### 8.1 Универсальная структура кабинетов

**ВСЕ ТИПЫ КАБИНЕТОВ** включают следующие обязательные разделы:

#### 8.1.1 Страница "Главная"

**СТАТУС**: Реализовано  
**ДОСТУП**: Через навигацию в sidebar для всех типов кабинетов  
**СОДЕРЖАНИЕ**: Универсальная страница с типо-зависимыми компонентами  

**ПРАВИЛА**:

- **ОБЯЗАТЕЛЬНО**: Каждый тип кабинета должен иметь страницу "Главная"
- **НАВИГАЦИЯ**: Доступ через кнопку в sidebar (первая в списке)
- **УНИВЕРСАЛЬНОСТЬ**: Одинаковая структура навигации для всех кабинетов
- **РОУТ**: `/home` с универсальным компонентом HomePageWrapper
- **КОМПОНЕНТЫ**: 4 типо-зависимых компонента: SellerHomePage, FulfillmentHomePage, WholesaleHomePage, LogistHomePage

#### 8.1.2 Раздел "Экономика"

**СТАТУС**: Реализовано в системе  
**РАСПОЛОЖЕНИЕ**: Перед настройками в каждом кабинете  
**СОДЕРЖАНИЕ**: Пустые разделы-заглушки с пометкой "будет добавлен позже"  

**ПРАВИЛА**:

- **ОБЯЗАТЕЛЬНО**: Каждый кабинет имеет раздел "Экономика"
- **РОУТ**: `/economics` с универсальным компонентом EconomicsPageWrapper
- **КОМПОНЕНТЫ**: 4 типо-зависимых компонента экономики: SellerEconomicsPage, FulfillmentEconomicsPage, WholesaleEconomicsPage, LogistEconomicsPage
- **КНОПКА**: "Экономика" в sidebar навигации перед настройками
- **БЕЗОПАСНОСТЬ**: Проверки доступа и безопасности в экономических компонентах

#### 8.1.3 Общие разделы для всех кабинетов

**УНИВЕРСАЛЬНЫЕ РАЗДЕЛЫ** (доступны всем типам):

- 🏠 **Главная** - основная страница кабинета (реализовано)
- 🛒 **Маркет** - просмотр и заказ товаров
- 🤝 **Партнеры** - управление контрагентами
- 💬 **Мессенджер** - внутренняя связь
- 💰 **Экономика** - финансовая аналитика (реализовано)
- ⚙️ **Настройки** - профиль и конфигурация

**СПЕЦИАЛИЗИРОВАННЫЕ РАЗДЕЛЫ** (зависят от типа кабинета):
- Определяются в соответствующих разделах каждого кабинета

### 8.2 Правила sidebar навигации

#### 8.2.1 Структура навигации

**ОБЩИЙ ПРИНЦИП**:

- Условное отображение: `{user?.organization?.type === "TYPE" && (...)}`
- Адаптивность: сворачиваемый sidebar с `getSidebarMargin()`
- Состояния активности: подсветка текущего раздела

**ПОРЯДОК РАЗДЕЛОВ В SIDEBAR**:

1. 🏠 **Главная** (реализовано для всех)
2. **Специализированные разделы** (зависят от типа кабинета)
3. 🛒 **Маркет** (универсальный)
4. 🤝 **Партнеры** (универсальный)
5. 💬 **Мессенджер** (универсальный)
6. 💰 **Экономика** (универсальный, реализовано)
7. ⚙️ **Настройки** (универсальный)
8. **Выход** (универсальный)

#### 8.2.2 Типо-зависимая логика

**АДАПТИВНЫЙ РОУТИНГ**:

```typescript
// Пример: кнопка "Поставки" ведет на разные страницы
const handleSuppliesClick = () => {
  switch (user?.organization?.type) {
    case "FULFILLMENT":
      router.push("/fulfillment-supplies");
      break;
    case "SELLER":
      router.push("/supplies");
      break;
    case "WHOLESALE":
      router.push("/supplies");
      break;
    case "LOGIST":
      router.push("/logistics-orders");
      break;
  }
};
```

---

## 9. 🏠 КАБИНЕТ СЕЛЛЕРА (ДЕТАЛЬНЫЕ ПРАВИЛА)

### 9.1 Структура раздела "Мои поставки"

#### **🏢 ПОСТАВКИ НА ФУЛФИЛМЕНТ**:

- **Товар** - поставка товаров для создания продуктов
  - **Карточки** - поставка через WB API с рецептурой (результат: WildberriesSupply)
  - **Поставщики** - заказ товаров у поставщиков с рецептурой (результат: SupplyOrder)
- **Расходники селлера** - поставка материалов для товаров селлера

#### **🛒 ПОСТАВКИ НА МАРКЕТПЛЕЙСЫ** _(планируется)_:

- **Wildberries** - прямые поставки на WB
- **Ozon** - прямые поставки на Ozon

### 9.2 Правила кнопки "Создать поставку" в разделе "Мои поставки"

#### **9.2.1 Общие принципы**

- **КОНТЕКСТНОСТЬ**: Кнопка создания появляется только в активном табе
- **РАСПОЛОЖЕНИЕ**: Правая часть строки таба, на том же уровне что и название
- **СТИЛИСТИКА**: В том же стиле что и сами табы (соответствует уровню иерархии)
- **ФУНКЦИОНАЛЬНОСТЬ**: Кнопка ведет на страницу создания поставки соответствующего типа

#### **9.2.2 Размещение кнопок по табам**

**УРОВЕНЬ 2 (Подтабы фулфилмента):**

- **📦 Товар → Карточки**: Кнопка "Создать поставку" → `/supplies/create-cards`
- **📦 Товар → Поставщики**: Кнопка "Создать поставку" → `/supplies/create-suppliers`
- **🔧 Расходники селлера**: Кнопка "Создать поставку" → `/supplies/create-consumables`

**УРОВЕНЬ 2 (Подтабы маркетплейсов):**

- **🟣 Wildberries**: Кнопка "Создать поставку" → `/supplies/create-wildberries`
- **🔵 Ozon**: Кнопка "Создать поставку" → `/supplies/create-ozon`

#### **9.2.3 Стили кнопок**

**ДЛЯ УРОВНЯ 2 (h-9):**

```css
/* Размер и отступы */
h-9 px-3 py-1 ml-auto

/* Фон и границы */
bg-white/8 border border-white/20 hover:bg-white/12

/* Текст и иконки */
text-xs font-medium text-white/80 hover:text-white

/* Скругления */
rounded-lg

/* Переходы */
transition-all duration-150
```

**ДЛЯ УРОВНЯ 3 (h-8):**

```css
/* Размер и отступы */
h-8 px-2 py-1 ml-auto

/* Фон и границы */
bg-white/5 border border-white/15 hover:bg-white/8

/* Текст и иконки */
text-xs font-normal text-white/60 hover:text-white/80

/* Скругления */
rounded-md

/* Переходы */
transition-all duration-150
```

#### **9.2.4 Поведение кнопок**

- **ВИДИМОСТЬ**: Кнопка показывается только в активном табе
- **ИКОНКА**: `Plus` размером `h-3 w-3` слева от текста
- **ТЕКСТ**: "Создать" на мобильных, "Создать поставку" на десктопах
- **АДАПТИВНОСТЬ**: Скрытие текста на маленьких экранах (`hidden sm:inline`)

#### **9.2.5 Удаление старой кнопки**

- **УБРАТЬ**: Текущий dropdown "Создать поставку" из верхней части
- **ПРИЧИНА**: Заменяется контекстными кнопками в табах
- **СОХРАНИТЬ**: Стили и логику навигации, но адаптировать под новые роуты

### 9.3 Структура страницы "Мои поставки" - Трёхблочная архитектура

#### **9.3.1 Обязательная структура страницы**

**ПРИНЦИП**: Страница состоит из трёх визуально разделённых блоков

```
┌─────────────────────────────────────────┐
│  1. БЛОК ТАБОВ (навигация)             │
│     - Фиксированная высота             │
│     - Glass-эффект                     │
│     - Иерархическая структура          │
├─────────────────────────────────────────┤
│  2. БЛОК СТАТИСТИКИ (метрики)          │
│     - Контекстные данные               │
│     - 4 карточки в ряд (desktop)       │
│     - Динамическое обновление          │
├─────────────────────────────────────────┤
│  3. ОСНОВНОЙ БЛОК (контент)            │
│     - Сохраняет весь функционал        │
│     - Таблицы, фильтры, действия       │
│     - Высота до низа sidebar           │
└─────────────────────────────────────────┘
```

#### **9.3.2 Блок статистики - контекстные метрики**

**ПРАВИЛО**: Статистика меняется в зависимости от выбранных табов

**Для путей "Фулфилмент → Товар → Карточки/Поставщики":**
- Всего поставок
- Активных поставок  
- Сумма активных поставок
- В пути

**Для пути "Фулфилмент → Расходники селлера":**
- Всего поставок
- Активных поставок
- Видов расходников
- Критические остатки

**Для путей "Маркетплейсы → Wildberries/Ozon":**
- Поставок на маркетплейс
- Товаров отправлено
- Возвраты за неделю
- Эффективность поставок

#### **9.3.3 Высота основного блока**

**ФОРМУЛА РАСЧЕТА**:
```css
height: calc(100vh - headerHeight - tabsHeight - statsHeight - margins)
```

**ПРАВИЛО ВЫРАВНИВАНИЯ**:
- Нижняя граница основного блока должна быть на одном уровне с нижней границей sidebar
- При изменении размера окна высота пересчитывается
- Внутренний скролл: `overflow-y-auto`

#### **9.3.4 Сохранение функционала**

**КРИТИЧЕСКИ ВАЖНО**: При добавлении блока статистики весь существующий функционал сохраняется:
- Таблицы с данными поставок
- Фильтры и сортировка
- Кнопки действий
- Детализация при клике
- Пагинация
- Поиск

**ЗАПРЕЩЕНО**:
- Удалять существующие компоненты
- Изменять логику работы таблиц
- Нарушать существующие API вызовы

### 9.4 Табы "Карточки" и "Поставщики" - объединённая логика

#### **9.4.1 Принцип единого типа предмета**

**КЛЮЧЕВОЕ ПРАВИЛО**: Табы "Карточки" и "Поставщики" - это два способа создания поставок одного типа предмета (ТОВАР)

**СПОСОБЫ СОЗДАНИЯ**:
- **Карточки** - импорт товаров через WB API с автоматическим созданием поставки
- **Поставщики** - прямой заказ товаров у поставщика с указанием рецептуры

**РЕЗУЛЬТАТ**: Оба способа создают `SupplyOrder` с товарами типа `PRODUCT`

#### **9.4.2 Общая статистика**

**ПРАВИЛО**: Блок статистики показывает ОДИНАКОВЫЕ данные для обоих табов

**МЕТРИКИ ДЛЯ ТАБОВ "КАРТОЧКИ" И "ПОСТАВЩИКИ"**:
- Всего поставок товаров (из всех источников)
- Активных поставок товаров (в работе) 
- Сумма активных поставок товаров
- Товаров в пути (все способы доставки)

**ЗАПРЕЩЕНО**: Разделять статистику по способу создания

#### **9.4.3 Общий основной блок**

**СОДЕРЖИМОЕ**: Единая таблица всех поставок товаров

**ИСТОЧНИКИ ДАННЫХ**:
- Поставки, созданные через импорт карточек WB
- Поставки, созданные через заказ у поставщиков
- Все промежуточные и завершённые поставки

**РАЗЛИЧИЯ ТАБОВ**:
- Только кнопки создания ведут на разные страницы
- Таб "Карточки": `/supplies/create-cards`
- Таб "Поставщики": `/supplies/create-suppliers`

### 9.5 Создание поставки расходников селлера

#### **Структура страницы**:

**БЛОК 1: ПОСТАВЩИКИ** _(обязательный, верхняя часть)_:

- Карточки поставщиков из раздела "Партнеры"
- Горизонтальный скролл при превышении ширины
- Выбор только одного поставщика одновременно

**БЛОК 2: РАСХОДНИКИ** _(зависимый, центральная часть)_:

- Активен только после выбора поставщика
- Сортировка: цена, название, категория
- Фильтры: категория, ценовой диапазон
- Карточка с полем ввода количества и кнопками +/-

**БЛОК 3: КОРЗИНА** _(правая часть)_:

- **РАСПОЛОЖЕНИЕ**: Правая часть экрана
- **СОДЕРЖАНИЕ**:
  - Счетчик видов расходников
  - Детализация по каждому расходнику (название, количество, цена, сумма)
  - Общая сумма всех расходников
- **УПРАВЛЕНИЕ**:
  - Изменение количества (с валидацией остатков)
  - Удаление позиций
- **ОБЯЗАТЕЛЬНЫЕ ПОЛЯ**:
  - Выбор фулфилмент-центра (из партнеров)
  - Дата поставки (не прошедшая, по умолчанию - текущая)

### 9.6 Многоуровневая таблица поставок

#### **ПЕРВЫЙ УРОВЕНЬ** _(основной список)_:

- **СОРТИРОВКА**: Номер поставки от большего к меньшему
- **ОБЯЗАТЕЛЬНЫЕ КОЛОНКИ**:
  - Порядковый номер поставки
  - Количество видов расходников
  - Стоимость всей поставки
  - Количество категорий
  - Статус поставки

#### **ВТОРОЙ УРОВЕНЬ** _(детализация по клику)_:

- **АКТИВАЦИЯ**: По клику на строку первого уровня
- **СОДЕРЖАНИЕ**:
  - Название расходника
  - Количество
  - Цена
  - Категория
  - Поставщик
- **ОГРАНИЧЕНИЯ**: Только просмотр, редактирование запрещено

---

## 10. 🏪 КАБИНЕТ ПОСТАВЩИКА

### 10.1 Основные возможности

**СОЗДАНИЕ КАРТОЧЕК**:

- **ТОВАР** - базовые товары поставщика
- **РАСХОДНИКИ** - материалы и вспомогательные товары

### 10.2 Обязательные поля карточки

**Базовые параметры**:

- Фото (система загрузки и управления изображениями)
- Название
- Автоматическая генерация артикула СФ
- Описание
- Количество предметов в единицах
- Количество комплектов (если применимо)
- Категория (28 предустановленных + специализированные для расходников)
- Бренд, Цвет, Размер/объем, Вес, Габариты, Материал
- Цена за единицу и за комплект
- Заказано, В пути, Остаток, Продано

### 10.3 Отображение информации в карточках

**Каждая карточка содержит**:

- Основное изображение
- Название и артикул СФ
- Цена за единицу/комплект
- Категория и статус активности
- Данные о движении: остаток, заказано, в пути, продано
- Индикаторы низких остатков

### 10.4 Статистика поставщика

**Блок статистики включает**:

- **ТОВАРЫ**: Общая статистика товаров поставщика
- **РАСХОДНИКИ**: Материалы и вспомогательные товары
  - Классифицируются при заказе в зависимости от заказчика
  - Общая статистика по всем расходникам

---

## 11. 🏭 КАБИНЕТ ФУЛФИЛМЕНТА

### 11.1 Структура раздела склад фулфилмента

#### **Модули в обязательной последовательности**:

1. **📦 ПРОДУКТ** - готовые к продаже товары
2. **🛒 ТОВАР** - базовые товары от поставщиков
   - Товары "на складе" - готовы к обработке
   - Товары "в обработке" - в процессе создания продукта
3. **❌ БРАК** - товары с дефектами
4. **↩️ ВОЗВРАТЫ С ПВЗ** - возвращенные товары
5. **🎯 РАСХОДНИКИ СЕЛЛЕРОВ** - материалы для селлеров
6. **⚙️ РАСХОДНИКИ ФУЛФИЛМЕНТ** - операционные материалы
   - **КЛИКАБЕЛЬНЫЙ МОДУЛЬ** - содержит полноценный раздел учёта

### 11.2 Движение товаров в фулфилменте

#### **Поступление товаров**:

- **ПОСТАВКИ**: От поставщиков через систему заказов
- **ВОЗВРАТЫ**: Товары, возвращенные с ПВЗ
- **ПЕРЕМЕЩЕНИЯ**: Между складами и магазинами

#### **Расход товаров**:

- **ОТГРУЗКА**: Товары отправлены селлерам
- **СПИСАНИЕ**: Брак, утрата, утилизация
- **ВОЗВРАТ**: Возврат поставщику
- **ИСПОЛЬЗОВАНИЕ**: Расходники для операций

### 11.3 Модуль "Расходники фулфилмента"

**ОСОБЕННОСТИ**:

- **ИНТЕРАКТИВНОСТЬ**: Кликабельный элемент в статистике
- **ФУНКЦИОНАЛЬНОСТЬ**: Полноценный раздел учёта
- **СОДЕРЖАНИЕ**: Управление расходниками фулфилмента

### 11.4 Блок детализации по магазинам

**НАЗНАЧЕНИЕ**: Распределение товаров по торговым точкам/магазинам

**ФУНКЦИИ**:

- **ОСТАТКИ ПО МАГАЗИНАМ**: Отображение количества товаров в каждом магазине
- **УПРАВЛЕНИЕ РАСПРЕДЕЛЕНИЕМ**: Перемещение товаров между точками
- **КОНТРОЛЬ ДВИЖЕНИЯ**: Отслеживание перемещений между складами и магазинами
- **АНАЛИТИКА**: Сравнение эффективности разных точек
- **ПЛАНИРОВАНИЕ**: Оптимизация распределения товаров

---

## 12. 🚚 КАБИНЕТ ЛОГИСТИКИ

### 12.1 Основные функции логистики

**РОЛЬ В СИСТЕМЕ**: Управление доставками и транспортировкой

**ОСНОВНЫЕ ФУНКЦИИ**:

- **ПОДТВЕРЖДЕНИЕ ДОСТАВКИ**: Подтверждение возможности доставки поставок
- **ТРАНСПОРТИРОВКА**: Организация и выполнение доставки товаров
- **КОНТРОЛЬ МАРШРУТОВ**: Управление логистическими маршрутами
- **ОТСЛЕЖИВАНИЕ**: Мониторинг грузов в пути

### 12.2 Workflow для логистики

#### **ЭТАП 1: Получение заявки**

1. Логистика получает уведомление о новой поставке
2. Заявка появляется в разделе "Заявки" кабинета логистики
3. Логист изучает детали поставки (объем, вес, маршрут)

#### **ЭТАП 2: Подтверждение доставки**

4. Логист нажимает кнопку "Одобрить"
5. Статус поставки меняется на `LOGISTICS_CONFIRMED`
6. Уведомления отправляются всем участникам

#### **ЭТАП 3: Забор товара**

7. Логист приезжает к поставщику за товаром
8. Поставщик отгружает товар логисту
9. Поставщик отмечает "Отправлено"
10. Статус меняется на `SHIPPED`, затем `IN_TRANSIT`

#### **ЭТАП 4: Доставка**

11. Логистика доставляет товар на фулфилмент-центр
12. В кабинете логистики нажимают "Доставлено"
13. Фулфилмент принимает товар и отмечает "Принято"

### 12.3 Система тарификации

**ПАРАМЕТРЫ ТАРИФИКАЦИИ**:

- **Тариф до 1м³** - базовая стоимость для малых грузов
- **Тариф свыше 1м³** - стоимость для крупных грузов
- **Маршруты доставки** - от точки отправления до точки назначения
- **Описание услуг** - дополнительные условия доставки

**РАСЧЕТ СТОИМОСТИ**:

- Автоматический расчет стоимости доставки по объему груза
- Отображение примерной стоимости при создании заказа
- Учет специфики маршрута и условий доставки

### 12.4 Управление заявками

**РАЗДЕЛЫ КАБИНЕТА ЛОГИСТИКИ**:

- **НОВЫЕ ЗАЯВКИ** - поступившие заявки на доставку
- **В РАБОТЕ** - принятые к исполнению заявки
- **ВЫПОЛНЕННЫЕ** - завершенные доставки
- **ОТКЛОНЕННЫЕ** - заявки, которые не могут быть выполнены

**ИНФОРМАЦИЯ О ЗАЯВКЕ**:

- Детали груза (объем, вес, габариты)
- Маршрут доставки (откуда - куда)
- Срочность доставки
- Особые требования к транспортировке
- Контактная информация участников

### 12.5 Правила логистики

**ОБЯЗАТЕЛЬНО**:

- Своевременное подтверждение заявок
- Соблюдение сроков доставки
- Бережная транспортировка товаров
- Уведомление о статусе доставки

**ЗАПРЕЩЕНО**:

- Принятие заявок без подтверждения возможности выполнения
- Нарушение сроков доставки без уведомления
- Повреждение товаров при транспортировке

---

## 13. 🤝 СИСТЕМА ПАРТНЕРСТВА И КОНТРАГЕНТОВ

### 13.1 Основы системы партнерства

**ПРИНЦИП РАБОТЫ**:
- Все типы кабинетов могут создавать партнерские отношения
- Партнерство реализовано через таблицы `Counterparty` и `CounterpartyRequest`
- Двустороннее партнерство: каждая организация видит другую в разделе "Партнеры"

**ТИПЫ ОРГАНИЗАЦИЙ-ПАРТНЕРОВ**:
- `WHOLESALE` - Поставщики товаров и расходников
- `FULFILLMENT` - Фулфилмент-центры
- `LOGIST` - Логистические компании
- `SELLER` - Селлеры (торговые организации)

### 13.2 Способы создания партнерства

#### **СПОСОБ 1: Через заказ в маркете (автоматическое партнерство)**

**WORKFLOW**:
1. Поставщик создает товар → товар попадает в глобальный маркет
2. Селлер/Фулфилмент находит товар в маркете
3. Создает заказ (`SupplyOrder`) → статус `PENDING`
4. Поставщик получает уведомление в разделе "Заявки"
5. Поставщик одобряет заявку → статус `SUPPLIER_APPROVED`
6. **Автоматически создается двустороннее партнерство**:
   - Запись в `Counterparty` для заказчика (`organizationId` → `counterpartyId`)
   - Обратная запись в `Counterparty` для поставщика
7. Обе организации видят друг друга в разделе "Партнеры"

#### **СПОСОБ 2: Через раздел "Партнеры" (заявочная система)**

**WORKFLOW**:
1. Любая организация идет в раздел "Партнеры"
2. Использует поиск для нахождения нужной организации
3. Отправляет заявку на партнерство → создается `CounterpartyRequest`:
   - `senderId` - отправитель заявки
   - `receiverId` - получатель заявки
   - `status: PENDING`
   - `message` - опциональное сообщение
4. Получатель видит заявку в разделе "Партнеры" → "Входящие заявки"
5. Получатель принимает заявку → статус меняется на `ACCEPTED`
6. **Автоматически создается двустороннее партнерство** (аналогично способу 1)

**СТАТУСЫ ЗАЯВОК**:
- `PENDING` - Ожидает рассмотрения
- `ACCEPTED` - Принята (партнерство создано)
- `REJECTED` - Отклонена
- `CANCELLED` - Отменена отправителем

### 13.3 Использование партнерства в системе

#### **В форме создания поставки товаров через поставщиков**

**ПРАВИЛО ОТОБРАЖЕНИЯ ПОСТАВЩИКОВ**:
- Показываются только партнеры с типом `WHOLESALE`
- Источник: таблица `Counterparty` where `counterparty.type === "WHOLESALE"`
- Фильтрация по `organizationId` текущего пользователя

**ЛОГИКА РАБОТЫ**:
1. Пользователь выбирает поставщика из dropdown партнеров-поставщиков
2. Загружается каталог товаров поставщика из `Product` таблицы
3. Товары фильтруются по `organizationId = поставщик.id`
4. Пользователь может добавлять товары в корзину и создавать заказ

#### **В других разделах системы**

**ВЫБОР ФУЛФИЛМЕНТ-ЦЕНТРА**:
- Партнеры с типом `FULFILLMENT`
- Используется при создании поставок расходников

**ВЫБОР ЛОГИСТИКИ**:
- Партнеры с типом `LOGIST`
- Используется при планировании доставок

**МЕССЕНДЖЕР**:
- Общение доступно только между партнерами
- Список чатов формируется из таблицы `Counterparty`

### 13.4 Технические правила

**СОЗДАНИЕ ЗАПИСЕЙ В COUNTERPARTY**:
```sql
-- При создании партнерства создаются ДВЕ записи
INSERT INTO counterparties (organizationId, counterpartyId) VALUES (org1_id, org2_id);
INSERT INTO counterparties (organizationId, counterpartyId) VALUES (org2_id, org1_id);
```

**ПРОВЕРКА ПАРТНЕРСТВА**:
```typescript
const isPartner = await prisma.counterparty.findFirst({
  where: {
    organizationId: currentOrgId,
    counterpartyId: targetOrgId
  }
});
```

**ПОЛУЧЕНИЕ ПАРТНЕРОВ ПО ТИПУ**:
```typescript
const wholesalePartners = await prisma.counterparty.findMany({
  where: {
    organizationId: currentOrgId,
    counterparty: {
      type: "WHOLESALE"
    }
  },
  include: {
    counterparty: true
  }
});
```

### 13.5 Решение распространенных проблем

#### **ПРОБЛЕМА: GraphQL запрос не возвращает данные партнеров**

**Симптомы**:
- В консоли браузера: `All counterparties: 0`, `All counterparties data: []`
- GraphQL запрос отправляется успешно, но возвращает пустой массив
- В базе данных партнеры существуют

**Возможные причины и решения**:

1. **НЕПРАВИЛЬНОЕ ИМЯ ПОЛЯ В КОДЕ** (наиболее частая ошибка):
   ```typescript
   // ❌ НЕПРАВИЛЬНО
   const allCounterparties = counterpartiesData?.getMyCounterparties || [];
   
   // ✅ ПРАВИЛЬНО
   const allCounterparties = counterpartiesData?.myCounterparties || [];
   ```
   **Объяснение**: В GraphQL схеме поле называется `myCounterparties`, а не `getMyCounterparties`

2. **НЕСООТВЕТСТВИЕ ID ПОЛЬЗОВАТЕЛЯ**:
   - Проверить что пользователь авторизован под правильным аккаунтом
   - Убедиться что `context.user.id` соответствует ожидаемому пользователю

3. **ПРОБЛЕМЫ С КЕШИРОВАНИЕМ APOLLO CLIENT**:
   ```typescript
   const { data, loading, error } = useQuery(GET_MY_COUNTERPARTIES, {
     fetchPolicy: 'network-only', // Обходим кеш
     errorPolicy: 'all'
   });
   ```

4. **ОТСУТСТВИЕ ЛОГИРОВАНИЯ В РЕЗОЛВЕРЕ**:
   - Добавить console.log в GraphQL резолвер для отладки
   - Проверить что резолвер вызывается

**Чек-лист для диагностики**:
- [ ] Проверить правильность имени поля в коде (`myCounterparties`)
- [ ] Убедиться что пользователь авторизован
- [ ] Проверить логи сервера на вызов резолвера
- [ ] Добавить отладочное логирование в браузере
- [ ] Проверить данные в базе через Prisma Studio
- [ ] Использовать `fetchPolicy: 'network-only'` для обхода кеша

---

## 14. 🌐 ИНТЕГРАЦИИ С СИСТЕМОЙ

### 14.1 Глобальная интеграция

- **МАРКЕТ**: Товары поставщиков отображаются в глобальном маркете
- **СИНХРОНИЗАЦИЯ**: Данные склада синхронизируются с модулем аналитики
- **УВЕДОМЛЕНИЯ**: Единая система через встроенный мессенджер

### 14.2 Интеграция с маркетплейсами

- **WILDBERRIES**: Обязательная проверка активности API ключа
- **СИНХРОНИЗАЦИЯ**: Регулярное обновление данных из внешних источников
- **ЛОКАЛЬНЫЕ КОПИИ**: Сохранение данных для офлайн работы

### 14.3 Интеграция с модулем "Услуги"

**РАСХОДНИКИ ФУЛФИЛМЕНТА В УСЛУГАХ**:

- Расходники фулфилмента - собственность фулфилмента (куплены у поставщиков)
- Фулфилмент создает заявки-поставки для покупки расходников у поставщиков
- Селлеры могут использовать расходники фулфилмента в разделе "Услуги / Расходники"
- Для создания продукта из товара
- Расходники списываются с остатков фулфилмента
- Стоимость включается в стоимость услуги

**WORKFLOW ИСПОЛЬЗОВАНИЯ**:

1. Селлер выбирает услугу "Создание продукта"
2. Указывает базовый товар
3. Выбирает необходимые расходники фулфилмента
4. Фулфилмент обрабатывает заказ и создает продукт
5. Расходники списываются, создается готовый продукт

---

## 15. 📊 СТАТИСТИКА И АНАЛИТИКА

### 15.1 Структура статистики по кабинетам

#### **В КАБИНЕТЕ ПОСТАВЩИКА**:

- **ТОВАРЫ**: Общая статистика товаров поставщика
- **РАСХОДНИКИ**: Материалы и вспомогательные товары (классифицируются при заказе)

#### **В КАБИНЕТЕ ФУЛФИЛМЕНТА**:

- **ТОВАРЫ**: Базовые товары от поставщиков (принятые на склад)
- **ПРОДУКТЫ**: Отдельный блок готовой продукции
- **БРАК**: Статистика потерь и списаний
- **РАСХОДНИКИ ФУЛФИЛМЕНТА**: Операционные материалы фулфилмента
- **РАСХОДНИКИ СЕЛЛЕРОВ**: Материалы для товаров селлеров

### 15.2 Ключевые метрики

**ОБЩИЕ ПОКАЗАТЕЛИ**:

- Общие остатки, заказано, в пути, остаток, продано
- Подсветка предметов с остатками ниже критического уровня

**АКТУАЛИЗАЦИЯ ДАННЫХ**:

- При изменении количества в карточке данные актуализируются во всей системе
- Статистика обновляется в реальном времени
- Отслеживание изменений для аналитики

---

## 16. 📱 ПРАВИЛА UI/UX И ИНТЕРФЕЙСА

### 16.1 Отзывчивость интерфейса

- **ОБЯЗАТЕЛЬНО**: Интерфейс должен работать на всех устройствах
- **ПРАВИЛО**: Адаптивная сетка для карточек товаров
- **ФУНКЦИЯ**: Оптимизация для мобильных устройств
- **ТРЕБОВАНИЕ**: Корректное отображение на экранах от 320px до 4K

### 16.2 Обратная связь пользователю

- **ОБЯЗАТЕЛЬНО**: Уведомления об успешных/неуспешных операциях
- **ПРАВИЛО**: Индикаторы загрузки для длительных операций
- **ФУНКЦИЯ**: Подтверждение критических действий (удаление, деактивация)
- **UX**: Понятные сообщения об ошибках с предложением решения

### 16.3 Правила обработки ошибок

- **ОБЯЗАТЕЛЬНО**: Логирование всех ошибок с детальной информацией
- **ПРАВИЛО**: Понятные сообщения об ошибках для пользователя
- **ФУНКЦИЯ**: Автоматическое восстановление после сбоев
- **МОНИТОРИНГ**: Отслеживание критических ошибок в реальном времени

### 16.4 Производительность

- **ПРАВИЛО**: Пагинация для больших списков товаров
- **ФУНКЦИЯ**: Ленивая загрузка изображений
- **ОПТИМИЗАЦИЯ**: Кэширование часто запрашиваемых данных
- **ПРОИЗВОДИТЕЛЬНОСТЬ**: Время загрузки страницы не более 3 секунд

---

## 17. ⚠️ КРИТИЧЕСКИЕ ЗАПРЕТЫ

### 17.1 НИКОГДА НЕ ДЕЛАТЬ:

1. ❌ Удалять предметы с существующими заказами
2. ❌ Изменять статусы заказов без уведомлений
3. ❌ Обходить проверки остатков предметов
4. ❌ Давать доступ к чужим данным
5. ❌ Игнорировать ошибки валидации
6. ❌ Сохранять пароли в открытом виде
7. ❌ Пропускать логирование критических операций
8. ❌ Блокировать интерфейс без индикации загрузки
9. ❌ Создавать брак или продукт без связи с родительским товаром
10. ❌ Создавать отдельные типы расходников (только общий тип "РАСХОДНИКИ")
11. ❌ Разрешать заказ брака
12. ❌ Нарушать иерархию типов предметов
13. ❌ Пропускать промежуточные статусы в workflow
14. ❌ Нарушать обязательную последовательность модулей в статистике фулфилмента
15. ❌ **Использовать неправильные имена полей GraphQL** (`getMyCounterparties` вместо `myCounterparties`)
16. ❌ **Использовать GET_SUPPLY_SUPPLIERS для отображения поставщиков в формах** (только партнеры WHOLESALE)
17. ❌ **Создавать интерфейсы TypeScript не соответствующие schema.prisma** (`sku`/`stock` вместо `article`/`quantity`)
18. ❌ **Использовать общие запросы вместо специализированных** (`GET_ALL_PRODUCTS` вместо `GET_ORGANIZATION_PRODUCTS` для конкретного поставщика)
19. ❌ **Показывать расходники в формах создания поставок товаров** (строгая типизация `PRODUCT`/`CONSUMABLE`)
20. ❌ **Фильтровать предметы по типу на фронтенде** (фильтрация должна быть в GraphQL резолвере)

### 17.2 ОБЯЗАТЕЛЬНЫЕ ПРАВИЛА:

1. ✅ Проверка остатков перед добавлением в корзину
2. ✅ Валидация всех числовых значений (цена > 0, вес > 0)
3. ✅ Автоматическая генерация уникальных артикулов СФ
4. ✅ Логирование всех изменений статусов
5. ✅ Уведомления всех участников при изменении статусов
6. ✅ Обязательная типизация всех предметов
7. ✅ Связь производных типов с родительскими предметами
8. ✅ Проверка доступности товаров перед заказом
9. ✅ Соблюдение жизненного цикла статусов поставок
10. ✅ Фиксация план/факт в процессе создания продукта

---

## 18. 🛠️ GRAPHQL И TYPESCRIPT ПРАВИЛА

### 18.1 Правила именования полей

**ВАЖНО**: Имена полей в GraphQL запросах должны точно соответствовать схеме!

```typescript
// ✅ ПРАВИЛЬНО - соответствует схеме
export const GET_MY_COUNTERPARTIES = gql`
  query GetMyCounterparties {
    myCounterparties {  // <- имя поля в схеме
      id
      name
      type
    }
  }
`;

// Использование в компоненте
const allCounterparties = counterpartiesData?.myCounterparties || [];
```

```typescript
// ❌ НЕПРАВИЛЬНО - не соответствует схеме
const allCounterparties = counterpartiesData?.getMyCounterparties || []; // Ошибка!
```

### 18.2 Правила отладки GraphQL

**При проблемах с GraphQL запросами следовать чек-листу**:

1. **Проверить соответствие имен полей схеме**
2. **Добавить fetchPolicy: 'network-only' для обхода кеша**
3. **Логировать данные в браузере и сервере**
4. **Проверить авторизацию пользователя** 
5. **Убедиться что резолвер вызывается**

### 18.3 Обязательные поля для отладки

```typescript
const { data, loading, error } = useQuery(QUERY_NAME, {
  fetchPolicy: 'network-only', // Обходим кеш при отладке
  errorPolicy: 'all'           // Показываем все ошибки
});

// Логирование для отладки
console.log("Data:", data);
console.log("Loading:", loading);
console.log("Error:", error);
```

### 18.4 TypeScript Rules

#### **Интерфейсы данных**

**Поля интерфейсов должны соответствовать GraphQL схеме**:

```typescript
// ✅ ПРАВИЛЬНО - соответствует schema.prisma
interface GoodsProduct {
  id: string;
  name: string;
  article: string;    // <- соответствует полю в schema
  quantity?: number;  // <- соответствует полю в schema
  organization: {
    id: string;
    name: string;
  };
}
```

```typescript
// ❌ НЕПРАВИЛЬНО - не соответствует schema
interface GoodsProduct {
  sku: string;        // <- в schema поле называется 'article'
  stock?: number;     // <- в schema поле называется 'quantity'
}
```

### 18.5 Система партнерства в GraphQL

**ПРАВИЛА ИСПОЛЬЗОВАНИЯ ПАРТНЕРСТВА**:

- Поставщики в формах берутся только из партнеров с типом `WHOLESALE`
- Используется запрос `GET_MY_COUNTERPARTIES` с фильтрацией по типу
- НЕ используется `GET_SUPPLY_SUPPLIERS` для отображения поставщиков в формах
- Партнерство создается двумя способами: через заказ в маркете или через раздел "Партнеры"
- Двусторонние записи в таблице `Counterparty` при создании партнерства

### 18.6 Архитектурные принципы GraphQL

- **Создавать специализированные резолверы** для каждого контекста использования
- **Использовать параметризованные запросы** (`organizationId`, `type`, `search`) вместо фильтрации на фронтенде
- **Добавлять подробное логирование** в резолверы для отладки (входные параметры, результаты фильтрации)
- **Типы запросов должны отражать бизнес-логику**: `organizationProducts` для товаров конкретной организации
- **Значения по умолчанию в резолверах** для критических параметров (`type: args.type || "PRODUCT"`)
- **Валидация обязательных параметров** на уровне схемы (`organizationId: ID!`)
- **Кеширование обходить при проблемах** через `fetchPolicy: 'network-only'`

---

## 19. 🔧 АРХИТЕКТУРНЫЕ ПРИНЦИПЫ

### 19.1 Стандарты разработки

- **ОБЯЗАТЕЛЬНО**: Покрытие тестами критической функциональности
- **ПРАВИЛО**: Следование принципам SOLID
- **ФУНКЦИЯ**: Автоматическое тестирование при развертывании
- **КАЧЕСТВО**: Минимальное покрытие тестами 80%

### 19.2 Документация

- **ОБЯЗАТЕЛЬНО**: Документирование всех API методов
- **ПРАВИЛО**: Комментарии к сложной бизнес-логике
- **ФУНКЦИЯ**: Автоматическая генерация документации
- **СТАНДАРТ**: Актуальная техническая документация

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

- **АРХИТЕКТУРА**: Модульная структура для легкого расширения
- **ПРАВИЛО**: Использование индексов для быстрого поиска
- **ФУНКЦИЯ**: Горизонтальное масштабирование при росте нагрузки
- **ПЛАНИРОВАНИЕ**: Готовность к увеличению нагрузки в 10 раз

### 19.4 Безопасность данных

- **ОБЯЗАТЕЛЬНО**: Шифрование чувствительных данных
- **ПРАВИЛО**: Аудит всех действий пользователей
- **ФУНКЦИЯ**: Контроль доступа на уровне API
- **БЕЗОПАСНОСТЬ**: Двухфакторная аутентификация для критических операций

---

## 20. 🎯 ПРАВИЛА КАЧЕСТВА КОДА

### 20.1 Проверки и валидация

**ОБЯЗАТЕЛЬНЫЕ ПРОВЕРКИ**:

- ✅ Типизация предметов: каждый предмет имеет один из типов: ТОВАР (`PRODUCT`), РАСХОДНИКИ (`CONSUMABLE`), БРАК и ПРОДУКТ (планируются)
- ✅ БРАК и ПРОДУКТ имеют обязательную связь с родительским товаром (parentId)
- ✅ Расходники создаются как универсальный тип, классифицируются при заказе
- ✅ **В формах создания поставок товаров показываются ТОЛЬКО предметы типа ТОВАР** (`PRODUCT`)
- ✅ **В формах создания поставок расходников показываются ТОЛЬКО предметы типа РАСХОДНИКИ** (`CONSUMABLE`)
- ✅ **Фильтрация по типу предмета происходит на уровне GraphQL резолвера**, не на фронтенде

### 20.2 Workflow статусов

- ✅ Соблюдена последовательность: PENDING → SUPPLIER_APPROVED → CONFIRMED → LOGISTICS_CONFIRMED → SHIPPED → IN_TRANSIT → DELIVERED
- ✅ Нет пропуска промежуточных статусов
- ✅ Каждое изменение статуса сопровождается уведомлением

### 20.3 Правила доступа

- ✅ Поставщик НЕ может добавлять собственные товары в корзину
- ✅ Заказ брака ЗАПРЕЩЕН
- ✅ Только активные предметы отображаются в маркете
- ✅ Проверка остатков перед добавлением в корзину

---

## 21. 🔍 ДИАГНОСТИКА И РЕШЕНИЕ ПРОБЛЕМ

### 21.1 Правило уточнений

**КРИТИЧЕСКИ ВАЖНО**: Если я не уверен в выполнении задачи или вижу противоречия в правилах - ОБЯЗАТЕЛЬНО уточнить у пользователя!

### 21.2 КОГДА УТОЧНЯТЬ:

- [ ] Недостаточно информации для правильного выполнения
- [ ] Вижу противоречия между правилами
- [ ] Задача может нарушить критические правила
- [ ] Неясно как применить правило в конкретной ситуации
- [ ] Есть сомнения в интерпретации требований

### 21.3 КАК УТОЧНЯТЬ:

1. Четко сформулировать что именно неясно
2. Указать какие правила/требования конфликтуют
3. Предложить варианты решения если возможно
4. Запросить конкретные уточнения

**❌ НИКОГДА не делать предположений если есть сомнения!**

---

## 22. 📋 КАТЕГОРИИ ТОВАРОВ И РАСХОДНИКОВ

### 22.1 Полный список 28 универсальных категорий товаров

1. Одежда и обувь
2. Косметика и парфюмерия
3. Дом и сад
4. Детские товары
5. Спорт и отдых
6. Электроника
7. Книги
8. Здоровье
9. Автотовары
10. Строительство и ремонт
11. Продукты питания
12. Зоотовары
13. Дача, сад и огород
14. Канцелярские товары
15. Хобби и творчество
16. Украшения и аксессуары
17. Сумки и чемоданы
18. Техника для дома
19. Музыкальные инструменты
20. Игры и игрушки
21. Мебель
22. Товары для красоты
23. Бытовая химия
24. Товары для путешествий
25. Медицинские товары
26. Религиозные товары
27. Антиквариат и коллекционирование
28. Прочие товары

### 22.2 12 специализированных категорий расходников

#### 🎁 **1. УПАКОВКА И ЗАЩИТА**
- Коробки (различных размеров)
- Пакеты (полиэтиленовые, бумажные, фирменные)
- Пузырчатая пленка, воздушные подушки
- Стрейч-пленка, гофрокартон
- Паллетная пленка, защитные уголки

#### 🏷️ **2. МАРКИРОВКА И ИДЕНТИФИКАЦИЯ**
- Этикетки (адресные, штрих-код, QR-код)
- Бирки (ценники, размерники)
- Стикеры и наклейки
- Маркеры и ручки
- Штампы и печати, термоэтикетки

#### 🔧 **3. КРЕПЕЖ И СОЕДИНЕНИЕ**
- Скотч (прозрачный, цветной, армированный)
- Клей и клеевые составы
- Стяжки пластиковые
- Степлер и скобы
- Веревки и шнуры, стрейч-лента

#### 📄 **4. ДОКУМЕНТООБОРОТ И ВКЛАДЫШИ**
- Накладные и сопроводительные документы
- Инструкции по эксплуатации
- Гарантийные талоны
- Рекламные буклеты, визитки и флаеры
- Благодарственные письма, купоны и промокоды

#### 🧼 **5. ГИГИЕНА И БЕЗОПАСНОСТЬ**
- Перчатки (латексные, нитриловые)
- Маски и респираторы
- Антисептики и дезинфекторы
- Салфетки и тряпки
- Фартуки и халаты, бахилы

#### 🛠️ **6. ИНСТРУМЕНТЫ И ПРИСПОСОБЛЕНИЯ**
- Ножи и резаки, ножницы
- Линейки и рулетки
- Упаковочные машины (ленточные)
- Дозаторы скотча
- Пистолеты для термоклея
- Весы и мерная тара

#### 🎨 **7. БРЕНДИНГ И ДИЗАЙН**
- Фирменные пакеты с логотипом
- Брендированные коробки
- Цветная упаковочная бумага
- Ленты и банты
- Наклейки с логотипом компании
- Подарочная упаковка

#### ⚡ **8. СПЕЦИАЛИЗИРОВАННЫЕ МАТЕРИАЛЫ**
- Антистатические пакеты
- Влагопоглотители
- Температурные индикаторы
- Хрупкие наклейки
- Пломбы и пломбировочные материалы
- Защита от краж (магнитные датчики)

#### 🏪 **9. ТОРГОВОЕ ОБОРУДОВАНИЕ**
- Манекены и вешалки
- Ценникодержатели
- Подставки и стойки
- Корзины и тележки
- Зеркала примерочные
- Освещение витрин

#### 🚚 **10. ЛОГИСТИКА И СКЛАДИРОВАНИЕ**
- Паллеты и поддоны
- Контейнеры и ящики
- Стеллажные системы
- Погрузочные ремни
- Защитные чехлы
- Адресные ярлыки для груза

#### 💻 **11. ТЕХНИЧЕСКИЕ РАСХОДНИКИ**
- Картриджи для принтеров
- Термоголовки, красящие ленты
- Батарейки для сканеров
- Чистящие средства для техники
- Запчасти для упаковочного оборудования

#### 🎪 **12. СЕЗОННЫЕ И ПРАЗДНИЧНЫЕ**
- Новогодняя упаковка
- Подарочные мешки
- Праздничные ленты
- Тематические наклейки
- Открытки и поздравления
- Сезонная упаковочная бумага

**ПРИМЕЧАНИЕ**: Данные категории являются рекомендательными и могут быть адаптированы под специфику конкретного поставщика расходников.

---

## 23. 🎖️ ПРИОРИТЕТЫ РАЗРАБОТКИ

### 23.1 ВЫСОКИЙ ПРИОРИТЕТ:

1. 🔴 Безопасность и контроль доступа
2. 🔴 Целостность данных и валидация
3. 🔴 Корректность статусов поставок
4. 🔴 Уведомления участников процесса
5. 🔴 Правильная типизация предметов
6. 🔴 Связи между товарами и производными типами

### 23.2 СРЕДНИЙ ПРИОРИТЕТ:

1. 🟡 Производительность и оптимизация
2. 🟡 Пользовательский опыт
3. 🟡 Аналитика и отчетность
4. 🟡 Интеграции с внешними системами
5. 🟡 Workflow для брака и продуктов
6. 🟡 Разделение расходников по типам

### 23.3 НИЗКИЙ ПРИОРИТЕТ:

1. 🟢 Дополнительные фильтры
2. 🟢 Косметические улучшения
3. 🟢 Экспериментальные функции
4. 🟢 Расширенная кастомизация

---

_Эта база знаний создана на основе анализа rules.md, rules1.md и rules2.md и является единым источником понимания структуры и логики проекта._

_Версия: 4.0_  
_Дата создания: 2024_  
_Статус: ПОЛНАЯ УНИФИЦИРОВАННАЯ БАЗА ЗНАНИЙ_