```
- **Назначение**: Горизонтальная прокрутка карточек товаров
- **Раскладка**: Flex с промежутками gap-3 (12px) между карточками
- **Отступы**: padding p-4 (16px) со всех сторон
- **Скролл**: overflow-x-auto с тонкой полосой прокрутки
- **Поведение**: Автоматическое появление скролла при превышении ширины
**ПРАВИЛА КОНТЕЙНЕРОВ:**
- Внешний контейнер НЕ содержит заголовков, иконок, описаний
- Внутренний контейнер содержит ТОЛЬКО карточки товаров
- Высота адаптируется под размер карточек (80×112px + отступы)
- Визуальное единство со всеми блоками формы поставки
**ТЕХНИЧЕСКИЕ ПРАВИЛА:**
- **Условие отображения**: selectedSupplier && products.length > 0
- **Источник данных**: products массив из GraphQL запроса organizationProducts
- **Реактивность**: Автоматическое обновление при смене поставщика
- **Производительность**: React.memo для карточек при большом количестве товаров
- **Доступность**: Клавиатурная навигация (Tab, Enter для выбора)
**UX ПРАВИЛА ВЗАИМОДЕЙСТВИЯ:**
- **Скролл**: Автоматическое появление при превышении ширины контейнера
- **Индикация загрузки**: Скелетоны карточек во время загрузки товаров
- **Пустое состояние**: Скрытие блока при отсутствии поставщика или товаров
- **Фокус**: Первая карточка получает фокус при загрузке товаров
- **Навигация**: Стрелки ←→ для перемещения между карточками
**СОСТОЯНИЯ БЛОКА:**
- **Скрыт**: При отсутствии выбранного поставщика
- **Скрыт**: При отсутствии товаров у поставщика
- **Активен**: При наличии поставщика и товаров
- **Загрузка**: Показ скелетонов карточек во время запроса
**ПРАВИЛА ПРОИЗВОДИТЕЛЬНОСТИ:**
- **Виртуализация**: При количестве товаров > 100
- **Ленивая загрузка изображений**: loading="lazy" для всех изображений
- **Мемоизация**: React.memo для компонентов карточек
- **Дебаунс**: 300мс для поисковых запросов (если будет добавлен поиск)
**ПРАВИЛА АДАПТИВНОСТИ:**
- **Мобильные устройства**: Свайп для горизонтальной прокрутки
- **Планшеты**: Сохранение размеров карточек 80×112px
- **Десктоп**: Полная функциональность с клавиатурной навигацией
- **Высокие разрешения**: Сохранение пропорций и читаемости
**ПРАВИЛА БЕЗОПАСНОСТИ И ВАЛИДАЦИИ:**
- **Валидация данных**: Проверка существования product.id перед добавлением
- **Дубликаты**: Предотвращение добавления одного товара дважды в детальный каталог
- **Санитизация**: Безопасное отображение названий товаров (XSS защита)
- **Обработка ошибок**: Graceful degradation при ошибках загрузки изображений
- **Защита от спама**: Дебаунс кликов 200мс для предотвращения множественных добавлений
**ПРАВИЛА ИНТЕГРАЦИИ С ДРУГИМИ БЛОКАМИ:**
- **Блок 1 (Поставщики)**: Слушает изменения selectedSupplier для обновления товаров
- **Блок 3 (Детальный каталог)**: Передаёт выбранные товары через setAllSelectedProducts
- **Блок 4 (Корзина)**: Товары добавляются в корзину из Блока 3, не напрямую из Блока 2
- **Синхронизация состояний**: Реактивное обновление при изменении данных в любом блоке
**ПРАВИЛА АНАЛИТИКИ И МЕТРИК:**
- **Отслеживание кликов**: Логирование добавления товаров в детальный каталог
- **Метрики производительности**: Время загрузки товаров поставщика
- **Пользовательское поведение**: Количество просмотренных товаров на поставщика
- **A/B тестирование**: Готовность к тестированию различных размеров карточек
**ПРАВИЛА ЛОКАЛИЗАЦИИ:**
- **Alt-текст изображений**: На языке интерфейса пользователя
- **Направление скролла**: RTL поддержка для арабского/иврита
- **Размеры карточек**: Неизменны для всех локалей (80×112px)
- **Сообщения об ошибках**: Локализованные уведомления при проблемах загрузки
#### **9.2.1.1 Заголовок и поиск Блока 1**
**МИНИМАЛИСТИЧНЫЙ ДИЗАЙН:**
```jsx
```
**ПРАВИЛА ЗАГОЛОВКА:**
- **Иконка**: Building2 h-5 w-5 text-blue-400 (без фонового контейнера)
- **Текст**: "Поставщики" (убран избыточный "товаров")
- **Размер**: text-lg font-semibold (увеличен для лучшей читаемости)
- **БЕЗ бэджа**: Убран избыточный бэдж "Создание поставки"
- **Выравнивание**: flex items-center gap-2 (компактное)
**ПРАВИЛА ПОИСКА:**
- **Позиция**: Справа от заголовка (justify-between)
- **Ширина**: w-64 (256px) фиксированная ширина
- **Плейсхолдер**: "Поиск поставщиков..." (конкретное описание)
- **Иконка**: Search h-4 w-4 слева в поле
- **Стили**: Стандартные glass-эффекты, focus:border-white/20
**ПРАВИЛА КНОПКИ "НАЙТИ В МАРКЕТЕ":**
- **Условие**: Показывается только при allCounterparties.length === 0
- **Позиция**: Отдельный блок под заголовком (mt-4)
- **НЕ интегрирована**: В поле поиска (отдельно)
- **Стили**: glass-secondary outline button размера sm
#### **9.2.1.2 Структура карточки поставщика в Блоке 1**
**МИНИМАЛИСТИЧНАЯ КАРТОЧКА ПОСТАВЩИКА:**
**СТРУКТУРА ИНФОРМАЦИИ:**
```jsx
```
**ПРАВИЛА СОДЕРЖАНИЯ КАРТОЧКИ:**
**✅ ОСТАВИТЬ:**
- **Аватар организации**: OrganizationAvatar size="sm" слева
- **Название поставщика**: supplier.name || supplier.fullName (приоритет name)
- **ИНН**: font-mono, text-white/60, с префиксом "ИНН: "
**🔸 ДОБАВИТЬ:**
- **Принадлежность к рынку**: Badge с названием рынка из supplier.market
- **Рынки**: "Садовод", "ТЯК Москва" и другие из Organization.market поля
**❌ УБРАТЬ:**
- **Рейтинг**: Звездочка и цифра rating (избыточно)
- **Тип бэдж**: "Поставщик" badge (и так понятно из контекста)
- **Адрес**: supplier.address (занимает место, не критично)
**СТИЛИ РЫНОЧНЫХ БЭДЖЕЙ:**
- **Садовод**: bg-green-500/20 text-green-300 border-green-500/30
- **ТЯК Москва**: bg-blue-500/20 text-blue-300 border-blue-500/30
- **По умолчанию**: bg-gray-500/20 text-gray-300 border-gray-500/30
**ПРАВИЛА АДАПТИВНОСТИ:**
- **Мобильные**: Сохранение структуры, truncate для длинных названий
- **Планшеты/десктоп**: Полное отображение в сетке
- **Малые экраны**: line-clamp-1 для названия организации
**СОСТОЯНИЯ КАРТОЧКИ:**
- **Default**: bg-white/5 border-white/10
- **Hover**: hover:border-white/20 hover:bg-white/10
- **Selected**: bg-white/15 border-white/40 shadow-lg
- **Disabled**: opacity-50 cursor-not-allowed (при недоступности)
**ПРАВИЛА ИНТЕГРАЦИИ С РЫНКАМИ:**
**ИСТОЧНИК ДАННЫХ:**
- **Поле БД**: Organization.market (String?) - поле принадлежности к рынку
- **Настройка**: Указывается в настройках кабинета поставщика
- **Опциональность**: Поле может быть пустым (рынок не указан)
**ФУНКЦИЯ getMarketLabel():**
```jsx
const getMarketLabel = (market?: string) => {
const marketLabels = {
'sadovod': 'Садовод',
'tyak-moscow': 'ТЯК Москва',
'opt-market': 'ОПТ Маркет',
}
return marketLabels[market as keyof typeof marketLabels] || market
}
```
**СТИЛИ ДЛЯ РЫНКОВ:**
```jsx
const getMarketBadgeStyle = (market?: string) => {
const styles = {
'sadovod': 'bg-green-500/20 text-green-300 border-green-500/30',
'tyak-moscow': 'bg-blue-500/20 text-blue-300 border-blue-500/30',
'opt-market': 'bg-purple-500/20 text-purple-300 border-purple-500/30',
}
return styles[market as keyof typeof styles] || 'bg-gray-500/20 text-gray-300 border-gray-500/30'
}
```
**ПРАВИЛА ОТОБРАЖЕНИЯ:**
- **Условие**: Показывать badge только если supplier.market существует
- **Размер**: text-xs для соответствия ИНН
- **Позиция**: Справа от ИНН в той же строке
- **Приоритет**: Рынок важнее типа организации для селлера
### 9.2.2.2 ПРАВИЛО ПЕРСИСТЕНТНОСТИ ВЫБРАННЫХ ТОВАРОВ
**🎯 ОСНОВНОЙ ПРИНЦИП:**
Выбранные товары в детальном каталоге (блок 3) сохраняются при смене поставщика и могут быть удалены только явным действием пользователя.
**🔄 WORKFLOW СЦЕНАРИИ:**
**СЦЕНАРИЙ 1: Добавление товаров от разных поставщиков**
1. Пользователь выбирает Поставщика А
2. Добавляет Товар 1 и Товар 2 в детальный каталог
3. Переключается на Поставщика Б
4. Товар 1 и Товар 2 остаются в блоке 3
5. Добавляет Товар 3 от Поставщика Б
6. В блоке 3: Товар 1, Товар 2 (от А) + Товар 3 (от Б)
**СЦЕНАРИЙ 2: Визуальная индикация в блоке 2**
- При переключении на поставщика, товары которого уже есть в блоке 3, показываются как "выбранные"
- Товары от других поставщиков в блоке 2 не отображаются
**🛠️ ТЕХНИЧЕСКИЕ ПРАВИЛА:**
**Состояние selectedProductsForDetailView:**
- Глобальное состояние всех выбранных товаров
- НЕ зависит от текущего поставщика
- НЕ очищается при смене поставщика
- Очищается только явными действиями пользователя
**Единственные способы удаления:**
1. Кнопка "Удалить из каталога" в карточке товара (блок 3)
2. Кнопка "Очистить каталог" в заголовке блока 3
3. НЕ при смене поставщика
**🎨 UX ПРАВИЛА:**
- Счетчик товаров: "Детальный каталог (X товаров от Y поставщиков)"
- Визуальная индикация выбранных товаров в блоке 2
- Информация о поставщике для каждого товара в блоке 3
**СОСТОЯНИЯ БЛОКА:**
- **Не выбран поставщик**: Заглушка "Выберите поставщика для просмотра товаров"
- **Поставщик выбран, нет товаров**: "У поставщика нет товаров"
- **Поставщик выбран, есть товары**: Карточки товаров с горизонтальным скроллом
**ВЗАИМОДЕЙСТВИЕ:**
- **Навигация**: Горизонтальная прокрутка мышью, клавишами ←→
- **Выбор**: Клик → добавление в Блок 3 с анимацией
- **Состояния карточек**: Default, Selected, Active (при добавлении)
**ГРАНИЧНЫЕ СЛУЧАИ:**
- **1-5 карточек**: Скролл неактивен, выравнивание по левому краю
- **6+ карточек**: Полноценный горизонтальный скролл
- **Поиск**: Фильтрация карточек в реальном времени
- **Загрузка**: Скелетон-анимация при смене поставщика
**БЛОК 3: ТОВАРЫ ПОСТАВЩИКА** _(детальный каталог)_
- **Содержание**: Детальный каталог товаров для управления поставкой
- **Источник**: Товары, добавленные из Блока 2 "Карточки товаров"
- **Сортировка**: По цене, названию, категории
- **Фильтры**: По категории, ценовому диапазону
- **Карточка расходника**:
- Фото, название, цена, остаток, категория
- Количество в комплекте (если есть комплектность)
- Поле ввода количества (единицы или комплекты)
- Кнопки +/- для изменения количества
- **Действие**: Клик добавляет расходник в корзину
**БЛОК 3: КОРЗИНА** _(правая часть)_
- **Содержание корзины**:
- Количество видов расходников
- По каждому расходнику: название, количество, цена за единицу, сумма
- Общая сумма всех расходников
- **Управление**: Изменение количества, удаление позиций
- **Валидация**: Проверка остатков у поставщика
- **Настройки поставки**:
- Выбор фулфилмент-центра (dropdown из партнеров)
- Дата поставки (по умолчанию - дата создания, нельзя выбрать прошедшую)
- **Кнопка**: "Создать поставку"
### 9.3 Многоуровневые таблицы для отображения поставок
#### **📊 Структура многоуровневой таблицы:**
**ПЕРВЫЙ УРОВЕНЬ** _(основной список)_:
- Порядковый номер поставки (от большего к меньшему)
- Количество видов расходников селлера
- Стоимость всей поставки
- Количество категорий
- Статус поставки
- Кнопка раскрытия/сворачивания
**ВТОРОЙ УРОВЕНЬ** _(раскрывается по клику)_:
- Название расходника селлера
- Количество
- Цена за единицу
- Общая стоимость позиции
- Категория
- Поставщик
- **Режим**: Только просмотр (редактирование недоступно после создания)
**ПРАВИЛА ОТОБРАЖЕНИЯ**:
- По умолчанию таблица свернута, показан только первый уровень
- Клик по строке или кнопке раскрывает второй уровень
- Анимация раскрытия плавная (300ms)
- Визуальная индикация раскрытого состояния (поворот стрелки, изменение фона)
### 9.4 Правила кнопки "Создать поставку" в разделе "Мои поставки"
#### **9.4.1 Общие принципы**
- **КОНТЕКСТНОСТЬ**: Кнопка создания появляется только в активном табе
- **РАСПОЛОЖЕНИЕ**: Правая часть строки таба, на том же уровне что и название
- **СТИЛИСТИКА**: В том же стиле что и сами табы (соответствует уровню иерархии)
- **ФУНКЦИОНАЛЬНОСТЬ**: Кнопка ведет на страницу создания поставки соответствующего типа
#### **9.4.2 Размещение кнопок по табам**
**УРОВЕНЬ 2 (Подтабы фулфилмента):**
- **📦 Товар → Карточки**: Кнопка "Создать поставку" → `/supplies/create-cards`
- **📦 Товар → Поставщики**: Кнопка "Создать поставку" → `/supplies/create-suppliers`
- **🔧 Расходники селлера**: Кнопка "Создать поставку" → `/supplies/create-consumables`
**УРОВЕНЬ 2 (Подтабы маркетплейсов):**
- **🟣 Wildberries**: Кнопка "Создать поставку" → `/supplies/create-wildberries`
- **🔵 Ozon**: Кнопка "Создать поставку" → `/supplies/create-ozon`
#### **9.4.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.2.6 ПРАВИЛА КОРЗИНЫ - ЕДИНЫЙ СТАНДАРТ**
**КРИТИЧЕСКИ ВАЖНО**: Все корзины в системе должны следовать единому стандарту дизайна и функциональности.
##### **9.2.6.1 Размеры и позиционирование**
```tsx
```
**ОБЯЗАТЕЛЬНЫЕ ПАРАМЕТРЫ**:
- **Ширина**: `w-72` (288px) - фиксированная ширина для всех корзин
- **Флекс**: `flex-shrink-0` - корзина не сжимается
- **Позиция**: `sticky top-0` - прилипает к верху при прокрутке
- **Стиль**: Glass morphism эффект с `backdrop-blur` и `bg-white/10`
##### **9.2.6.2 Автодобавление товаров**
**ПРАВИЛО AUTO-ADD**: При вводе количества товар автоматически добавляется в корзину.
```tsx
// ОБЯЗАТЕЛЬНАЯ РЕАЛИЗАЦИЯ:
const handleQuantityChange = (e: React.ChangeEvent) => {
const inputValue = e.target.value
const newQuantity = inputValue === '' ? 0 : Math.max(0, parseInt(inputValue) || 0)
if (newQuantity > 0) {
// Автоматически добавляем товар в корзину
updateProductQuantity(product.id, newQuantity)
} else {
// Удаляем товар из корзины при количестве 0
removeFromCart(product.id)
}
}
```
**ДЕФОЛТНОЕ ЗНАЧЕНИЕ**: Пустой инпут (`value={''}`) вместо `value={0}`
##### **9.2.6.3 Структура корзины**
**ОБЯЗАТЕЛЬНЫЕ ЭЛЕМЕНТЫ**:
1. **Заголовок**: "Корзина (X шт)" с иконкой корзины
2. **Список товаров**:
- Название товара (БЕЗ суффикса "(с рецептурой)")
- Цена за единицу × количество
- Кнопка удаления (X справа)
3. **Мета-информация**: Дата поставки, фулфилмент-центр, логистика
4. **Итого**: Общая сумма с выделением зелёным цветом
5. **Кнопка действия**: "Создать поставку" с градиентом
**ЗАПРЕЩЕНО**: Отображать текст "(с рецептурой)" в названиях товаров в корзине
##### **9.2.6.4 Единая функция расчета стоимости**
**КРИТИЧЕСКИ ВАЖНО**: Использовать единую функцию расчета для избежания расхождений:
```tsx
const getProductTotalWithRecipe = (productId: string, quantity: number) => {
const product = products.find((p) => p.id === productId)
if (!product) return 0
// Базовая цена товара
let total = (product.pricePerUnit || 0) * quantity
// Добавляем услуги
if (product.services && product.services.length > 0) {
const servicesTotal = product.services.reduce((sum, service) => {
return sum + (service.pricePerUnit || 0) * quantity
}, 0)
total += servicesTotal
}
// Добавляем FF расходники (используем .price, НЕ .pricePerUnit!)
if (product.ffConsumables && product.ffConsumables.length > 0) {
const ffConsumablesTotal = product.ffConsumables.reduce((sum, consumable) => {
return sum + (consumable.price || 0) * quantity // ВАЖНО: .price!
}, 0)
total += ffConsumablesTotal
}
// Добавляем расходники продавца
if (product.sellerConsumables && product.sellerConsumables.length > 0) {
const sellerConsumablesTotal = product.sellerConsumables.reduce((sum, consumable) => {
return sum + (consumable.pricePerUnit || 0) * quantity
}, 0)
total += sellerConsumablesTotal
}
return total
}
```
##### **9.2.6.5 Синхронизация данных между блоками**
**ПРАВИЛО СИНХРОНИЗАЦИИ**: Данные в корзине должны отражать выборы из всех блоков формы:
1. **Дата поставки**: Из Блока 3 (дата пикер)
2. **Фулфилмент-центр**: Название выбранного FF (реальные данные!)
3. **Логистическая компания**: Только партнеры типа `'LOGIST'`
**ПОРЯДОК ОТОБРАЖЕНИЯ В КОРЗИНЕ**:
```
Дата поставки: 08.08.2025
Фулфилмент-центр: ФУЛФИЛМЕНТ РУ
Логистическая компания: [Выпадающий список]
```
##### **9.2.6.6 Критические требования**
🚨 **БЕЗОПАСНОСТЬ ТИПОВ**:
- Всегда проверять на `null/undefined`: `selectedSupplier?.id || ''`
- Использовать optional chaining для всех вложенных объектов
🚨 **ПРОИЗВОДИТЕЛЬНОСТЬ**:
- Мемоизация расчетов: `useMemo` для дорогих вычислений
- Debounce для инпутов количества
🚨 **UX КОНСИСТЕНТНОСТЬ**:
- Единые стили для всех корзин в системе
- Одинаковое поведение auto-add во всех формах
- Синхронная валидация данных
### 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: ПОСТАВЩИКИ** _(обязательный, 180px)_:
- **Навигация**: Плавающая кнопка "Назад" между сайдбаром и контентом (см. seller-ui-rules.md)
- **БЕЗ заголовка** - блок начинается сразу с поиска и карточек
- Карточки поставщиков из раздела "Партнеры"
- Горизонтальный скролл при превышении ширины
- Выбор только одного поставщика одновременно
**БЛОК 2: КАРТОЧКИ ТОВАРОВ** _(адаптивная высота - НОВЫЙ БЛОК)_:
- ТОЛЬКО минималистичные карточки товаров 80×112px
- ТОЛЬКО изображение товара, БЕЗ текста/названий/цен
- Горизонтальный скролл при множестве товаров
- Клик добавляет товар в блок 3
**БЛОК 3: ТОВАРЫ ПОСТАВЩИКА** _(flex-1, детальный каталог)_:
- Детальные карточки выбранных товаров
- Управление количеством и параметрами поставки
**БЛОК 4: КОРЗИНА И НАСТРОЙКИ** _(правая панель, 384px)_:
- Корзина поставки с выбранными товарами
- Настройки поставки (фулфилмент-центр, дата, логистика)
- Сортировка: цена, название, категория
- Фильтры: категория, ценовой диапазон
- Карточка с полем ввода количества и кнопками +/-
**БЛОК 3: КОРЗИНА** _(правая часть)_:
- **РАСПОЛОЖЕНИЕ**: Правая часть экрана
- **СОДЕРЖАНИЕ**:
- Счетчик видов расходников
- Детализация по каждому расходнику (название, количество, цена, сумма)
- Общая сумма всех расходников
- **УПРАВЛЕНИЕ**:
- Изменение количества (с валидацией остатков)
- Удаление позиций
- **ОБЯЗАТЕЛЬНЫЕ ПОЛЯ**:
- Выбор фулфилмент-центра (из партнеров)
- Дата поставки (не прошедшая, по умолчанию - текущая)
### 9.6 Многоуровневая таблица поставок
#### **ПЕРВЫЙ УРОВЕНЬ** _(основной список)_:
- **СОРТИРОВКА**: Номер поставки от большего к меньшему
- **ОБЯЗАТЕЛЬНЫЕ КОЛОНКИ**:
- Порядковый номер поставки
- Количество видов расходников
- Стоимость всей поставки
- Количество категорий
- Статус поставки
#### **ВТОРОЙ УРОВЕНЬ** _(детализация по клику)_:
- **АКТИВАЦИЯ**: По клику на строку первого уровня
- **СОДЕРЖАНИЕ**:
- Название расходника
- Количество
- Цена
- Категория
- Поставщик
- **ОГРАНИЧЕНИЯ**: Только просмотр, редактирование запрещено
---
## 10. 🏪 КАБИНЕТ ПОСТАВЩИКА
> 📖 **Технические детали кабинета**: См. [wholesale-cabinet-rules.md](./wholesale-cabinet-rules.md) для компонентов, GraphQL и UI/UX
### 10.1 Разделение понятий: РЫНОК vs МАРКЕТ
**🔍 КРИТИЧЕСКОЕ РАЗДЕЛЕНИЕ ПОНЯТИЙ:**
### **РЫНОК** 🏪 - физическое торговое место
- **Назначение**: Географическая принадлежность поставщиков
- **Примеры**: Садовод, ТЯК Москва
- **Структура**: Название + адрес
- **Связь**: Поставщик принадлежит рынку
### **МАРКЕТ** 🛒 - раздел системы для торговли
- **Назначение**: Глобальный каталог товаров в системе
- **Роут**: `/market` - просмотр и заказ товаров
- **Содержание**: Все доступные товары от всех поставщиков
- **Связь**: НЕ связан с физическими рынками
**🏢 АРХИТЕКТУРА ПРИНАДЛЕЖНОСТИ:**
```
РЫНОК (физическое место)
└── Поставщик (Organization.market)
└── Товары/Расходники (наследуют рынок от поставщика)
└── Отображаются в МАРКЕТЕ (/market)
```
**🎯 ПРИНЦИПЫ ИЕРАРХИИ:**
1. **РЫНОК → ПОСТАВЩИК**: Поставщик работает на конкретном рынке
2. **ПОСТАВЩИК → ТОВАРЫ**: Товары принадлежат поставщику с его рынка
3. **ТОВАРЫ → МАРКЕТ**: Все товары показываются в глобальном маркете (/market)
4. **НАСЛЕДОВАНИЕ**: Товары получают рынок от организации поставщика
**🏪 ФИЗИЧЕСКИЕ РЫНКИ В СИСТЕМЕ:**
- **"Садовод"** (`sadovod`) - Москва, 14-й км МКАД
- **Цветовая схема**: `bg-green-500/20 text-green-300 border-green-500/30`
- **"ТЯК Москва"** (`tyak-moscow`) - Москва, Алтуфьевское шоссе, 27
- **Цветовая схема**: `bg-blue-500/20 text-blue-300 border-blue-500/30`
**🛒 МАРКЕТ В СИСТЕМЕ:**
- **Роут**: `/market` - глобальный каталог товаров
- **Функции**: Просмотр, поиск, фильтрация, заказ товаров
- **Источник**: Товары от всех поставщиков всех рынков
- **Отображение рынка**: В карточках поставщиков и товаров
**🔧 ТЕХНИЧЕСКАЯ РЕАЛИЗАЦИЯ:**
- **Поле рынка**: `Organization.market` (String?) - принадлежность поставщика к рынку
- **Настройка рынка**: В настройках организации поставщика
- **Отображение в маркете**: Товары показывают рынок через `product.organization.market`
- **Фильтрация**: В маркете по рынку поставщика
### 10.2 Основные возможности
**СОЗДАНИЕ КАРТОЧЕК**:
- **ТОВАР** - базовые товары поставщика
- **РАСХОДНИКИ** - материалы и вспомогательные товары
### 10.3 Обязательные поля карточки
**Базовые параметры**:
- Фото (система загрузки и управления изображениями)
- Название
- Автоматическая генерация артикула СФ
- Описание
- Количество предметов в единицах
- Количество комплектов (если применимо)
- Категория (28 предустановленных + специализированные для расходников)
- Бренд, Цвет, Размер/объем, Вес, Габариты, Материал
- Цена за единицу и за комплект
- Заказано, В пути, Остаток, Продано
### 10.4 Отображение информации в карточках
**Каждая карточка содержит**:
- Основное изображение
- Название и артикул СФ
- Цена за единицу/комплект
- Категория и статус активности
- Данные о движении: остаток, заказано, в пути, продано
- Индикаторы низких остатков
### 10.5 Статистика поставщика
**Блок статистики включает**:
- **ТОВАРЫ**: Общая статистика товаров поставщика
- **РАСХОДНИКИ**: Материалы и вспомогательные товары
- Классифицируются при заказе в зависимости от заказчика
- Общая статистика по всем расходникам
---
## 11. 🏭 КАБИНЕТ ФУЛФИЛМЕНТА
> 📖 **Технические детали кабинета**: См. [fulfillment-cabinet-rules.md](./fulfillment-cabinet-rules.md) для компонентов, GraphQL, UI/UX и всех технических деталей реализации
### 11.1 Основные функции фулфилмента
**РОЛЬ В СИСТЕМЕ**: Обработка товаров и предоставление услуг
**ОСНОВНЫЕ ФУНКЦИИ**:
- **ПРИЕМКА ТОВАРОВ**: Получение и обработка поставок от поставщиков
- **СОЗДАНИЕ ПРОДУКТОВ**: Превращение товаров в готовые продукты по рецептурам
- **ПРЕДОСТАВЛЕНИЕ УСЛУГ**: Услуги обработки для селлеров
- **УПРАВЛЕНИЕ РАСХОДНИКАМИ**: Установка цен и контроль наличия
- **ЛОГИСТИЧЕСКИЕ УСЛУГИ**: Маршруты доставки и тарификация
### 11.2 Workflow фулфилмента
См. детальное описание в [workflow-catalog.md#4-workflow-фулфилмента](./workflow-catalog.md#4-workflow-фулфилмента)
### 11.3 Основные разделы кабинета
**СТРУКТУРА ДОСТУПА**:
- **Склад** - управление товарами по модулям
- **Поставки** - обработка входящих товаров
- **Услуги** - каталог услуг и расходники
- **Сотрудники** - управление персоналом
- **Статистика** - аналитика деятельности
### 11.4 Правила фулфилмента
**ОБЯЗАТЕЛЬНО**:
- Установка цен на расходники перед доступностью селлерам
- Контроль качества товаров при приемке
- Своевременная обработка возвратов
- Ведение учета движения товаров
- Управление персоналом и рабочим временем
**ЗАПРЕЩЕНО**:
- Отгружать товары без подтверждения наличия
- Создавать расходники минуя систему поставок
- Изменять цены закупки после поступления товара
- Показывать в рецептурах неактивные расходники
---
## 12. 🚚 КАБИНЕТ ЛОГИСТИКИ
### 12.1 Основные функции логистики
**РОЛЬ В СИСТЕМЕ**: Управление доставками и транспортировкой
**ОСНОВНЫЕ ФУНКЦИИ**:
- **ПОДТВЕРЖДЕНИЕ ДОСТАВКИ**: Подтверждение возможности доставки поставок
- **ТРАНСПОРТИРОВКА**: Организация и выполнение доставки товаров
- **КОНТРОЛЬ МАРШРУТОВ**: Управление логистическими маршрутами
- **ОТСЛЕЖИВАНИЕ**: Мониторинг грузов в пути
### 12.2 Workflow для логистики
См. детальное описание в [workflow-catalog.md#5-workflow-логистики](./workflow-catalog.md#5-workflow-логистики)
### 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'` для обхода кеша
### 13.6 Различие партнерских и реферальных ссылок
⚠️ **КРИТИЧЕСКИ ВАЖНО**: НЕ ПУТАТЬ два различных типа ссылок в системе!
#### **13.6.1 Партнерские ссылки**
**НАЗНАЧЕНИЕ**: Бизнес-партнерство с автоматическим добавлением в контрагенты
**ФОРМАТ URL**: `?partner=REFERRAL_CODE`
```
http://localhost:3000/register?partner=SF2X9K4M7P
```
**ЧТО ПРОИСХОДИТ**:
1. ✅ Начисляется 100 сфер (⚡) реферальная награда
2. ✅ **Автоматически создается партнерство**: взаимное добавление в контрагенты
3. ✅ Устанавливается реферальная связь (`referredById`)
4. ✅ Создаются записи в таблице `Counterparty` (двусторонние)
5. ✅ Организации видят друг друга в разделе "Партнеры"
**ИСПОЛЬЗОВАНИЕ**: Когда нужно сразу стать деловыми партнерами и начать работать
#### **13.6.2 Реферальные ссылки**
**НАЗНАЧЕНИЕ**: Маркетинговое привлечение с наградой, БЕЗ автоматического партнерства
**ФОРМАТ URL**: `?ref=REFERRAL_CODE`
```
http://localhost:3000/register?ref=SF2X9K4M7P
```
**ЧТО ПРОИСХОДИТ**:
1. ✅ Начисляется 100 сфер (⚡) реферальная награда
2. ✅ Устанавливается реферальная связь (`referredById`)
3. ❌ **НЕ создается партнерство**: организации НЕ добавляются в контрагенты
4. ❌ Организации НЕ видят друг друга в разделе "Партнеры"
**ИСПОЛЬЗОВАНИЕ**: Маркетинговые кампании, блогеры, инфлюенсеры
#### **13.6.3 Технические различия в коде**
**В резолверах регистрации**:
```typescript
// Обработка партнерского кода (создает партнерство)
if (partnerCode) {
// 1. Найти организацию-партнера
// 2. Создать реферальную транзакцию
// 3. Установить реферальную связь
// 4. СОЗДАТЬ ВЗАИМНОЕ ПАРТНЕРСТВО ← Ключевое отличие!
}
// Обработка реферального кода (только награда)
if (referralCode) {
// 1. Найти организацию-реферера
// 2. Создать реферальную транзакцию
// 3. Установить реферальную связь
// 4. БЕЗ создания партнерства ← Ключевое отличие!
}
```
#### **13.6.4 UI различия**
**В разделе "Партнеры"**:
**Вкладка "Мои партнеры"**:
- Партнерская ссылка: `?partner=CODE` (автоматическое партнерство)
- Заголовок: "Пригласить партнера"
- Описание: "Для прямого делового сотрудничества"
**Вкладка "Рефералы"**:
- Реферальная ссылка: `?ref=CODE` (только маркетинг)
- Заголовок: "Реферальная ссылка"
- Описание: "Для маркетинговых кампаний"
#### **13.6.5 Правила именования**
**В коде ВСЕГДА использовать**:
- `partnerCode` / `partner=` → бизнес-партнерство
- `referralCode` / `ref=` → маркетинговое привлечение
**В комментариях и документации**:
- "Партнерская ссылка" → автоматическое партнерство
- "Реферальная ссылка" → только маркетинг
**ЗАПРЕЩЕНО**:
- ❌ Называть партнерские ссылки "реферальными"
- ❌ Называть реферальные ссылки "партнерскими"
- ❌ Использовать термины взаимозаменяемо
- ❌ Путать логику обработки в резолверах
#### **13.6.6 Примеры использования**
**Сценарий 1 - Деловое партнерство**:
```
Фулфилмент-центр хочет пригласить логистическую компанию
→ Использует партнерскую ссылку ?partner=CODE
→ Логисты регистрируются и сразу становятся партнерами
→ Могут сразу работать друг с другом
```
**Сценарий 2 - Маркетинговая кампания**:
```
Организация запускает рекламу в соцсетях
→ Использует реферальную ссылку ?ref=CODE
→ Люди регистрируются, организация получает сферы
→ Партнерство НЕ создается (это маркетинг)
```
---
## 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 резолвере)
21. ❌ **ИСПОЛЬЗОВАТЬ МОКОВЫЕ ДАННЫЕ БЕЗ РАЗРЕШЕНИЯ** - все компоненты ОБЯЗАТЕЛЬНО должны использовать реальные GraphQL запросы. Моковые данные можно добавлять ТОЛЬКО с явного разрешения пользователя
22. ❌ **ДОБАВЛЯТЬ ПОЛЕ РЫНКА К ТОВАРАМ** - рынок принадлежит организации поставщика (`Organization.market`), товары наследуют рынок через связь с организацией
23. ❌ **ПУТАТЬ РЫНОК И МАРКЕТ** - РЫНОК = физическое место (Садовод, ТЯК), МАРКЕТ = раздел системы (/market)
24. ❌ **ИСПОЛЬЗОВАТЬ НАЗВАНИЯ ОРГАНИЗАЦИЙ В ЛОГИКЕ БЕЗОПАСНОСТИ** - проверки доступа только по `organization.type` и системным ID
25. ❌ **СОЗДАВАТЬ УСЛОВИЯ НА ОСНОВЕ ПОЛЬЗОВАТЕЛЬСКИХ СТРОК** - никаких `if (name.includes())` для определения функционала
26. ❌ **ПУТАТЬ ДАННЫЕ И ФУНКЦИОНАЛ** - "ОПТ Маркет" (название рынка) ≠ "Маркет" (раздел системы)
27. ❌ **ПРЕДСТАВЛЯТЬ ИНТЕРПРЕТАЦИИ КАК ФАКТЫ** - всегда четко разделять прямые цитаты из правил и логические выводы
28. ❌ **ОТВЕЧАТЬ БЕЗ ССЫЛОК НА ИСТОЧНИКИ** - при ссылке на правила всегда указывать номер строки или раздел
29. ❌ **ИСПОЛЬЗОВАТЬ КАТЕГОРИЧНЫЕ УТВЕРЖДЕНИЯ БЕЗ ДОКАЗАТЕЛЬСТВ** - избегать "ТОЧНО!", "ИМЕННО ТАК!" без прямых цитат
### 17.2 ОБЯЗАТЕЛЬНЫЕ ПРАВИЛА:
1. ✅ Проверка остатков перед добавлением в корзину
2. ✅ Валидация всех числовых значений (цена > 0, вес > 0)
3. ✅ Автоматическая генерация уникальных артикулов СФ
4. ✅ Логирование всех изменений статусов
5. ✅ Уведомления всех участников при изменении статусов
6. ✅ Обязательная типизация всех предметов
7. ✅ Связь производных типов с родительскими предметами
8. ✅ Проверка доступности товаров перед заказом
9. ✅ Соблюдение жизненного цикла статусов поставок
10. ✅ Фиксация план/факт в процессе создания продукта
11. ✅ **УКАЗЫВАТЬ ИСТОЧНИКИ ИНФОРМАЦИИ** - при ссылке на правила обязательно указывать строку/раздел
12. ✅ **РАЗДЕЛЯТЬ ФАКТЫ И ИНТЕРПРЕТАЦИИ** - четко маркировать что взято из правил, а что является выводом
13. ✅ **ИСПОЛЬЗОВАТЬ ОСТОРОЖНЫЕ ФОРМУЛИРОВКИ** - "согласно правилам", "возможно", "требует уточнения"
### 17.3 📝 ОБЯЗАТЕЛЬНЫЙ ФОРМАТ ОТВЕТОВ С ФАКТАМИ
**При ссылке на правила ОБЯЗАТЕЛЬНО использовать формат:**
✅ **ПРАВИЛЬНО:**
```
📖 ФАКТ из rules-complete.md (строка 2225): "установка цены за единицу"
🧠 МОЯ ИНТЕРПРЕТАЦИЯ: возможно, это происходит в разделе X
❓ ПРЕДПОЛОЖЕНИЕ: требует уточнения у пользователя
⚠️ НЕ НАЙДЕНО в правилах: информация о точном местоположении
```
❌ **НЕПРАВИЛЬНО:**
```
"Да! Точно понимаю! Фулфилмент устанавливает цены в разделе X!"
```
**ОБЯЗАТЕЛЬНАЯ МАРКИРОВКА:**
- 📖 **ФАКТ** - прямая цитата из правил с номером строки
- 🧠 **ИНТЕРПРЕТАЦИЯ** - мой логический вывод (четко обозначен)
- ❓ **ПРЕДПОЛОЖЕНИЕ** - гипотеза, требующая подтверждения
- ⚠️ **НЕ НАЙДЕНО** - информация отсутствует в правилах
**СТОП-СЛОВА (избегать без доказательств):**
❌ "ТОЧНО!", "ИМЕННО ТАК!", "ДА! ПОНИМАЮ!", "АБСОЛЮТНО ВЕРНО!"
✅ "Согласно правилам...", "Не указано, но возможно...", "Требует уточнения"
### 17.4 🔒 ПРАВИЛА БЕЗОПАСНОСТИ: Разделение данных и функционала
#### КРИТИЧЕСКОЕ ПРАВИЛО БЕЗОПАСНОСТИ
**ПРИНЦИП**: Названия организаций, рынков и любые пользовательские данные НИКОГДА не должны влиять на функционал и безопасность системы.
**ОБЯЗАТЕЛЬНЫЕ ПРАВИЛА:**
✅ **ПРАВИЛЬНЫЕ ПРОВЕРКИ:**
- Проверки доступа ТОЛЬКО по типу организации: `organization.type === 'WHOLESALE'`
- Роутинг ТОЛЬКО по предопределенным путям: `/market`, `/supplies` и т.д.
- Валидация ТОЛЬКО по ID и системным полям
- Фильтрация ТОЛЬКО по enum значениям из схемы
❌ **ЗАПРЕЩЕННЫЕ ПРОВЕРКИ (УЯЗВИМОСТИ):**
- Использование `organization.name` в условиях доступа
- Проверки по `organization.market` для определения функционала
- Любые проверки содержимого строк: `includes()`, `startsWith()`, `match()`
- Динамическое создание путей на основе пользовательских данных
**ПРИМЕРЫ:**
```typescript
// ❌ УЯЗВИМОСТЬ - название может быть любым
if (organization.name.includes('Маркет')) {
// предоставить специальный доступ
}
// ❌ УЯЗВИМОСТЬ - пользователь может подделать название
if (organization.market === 'special-market') {
// изменить цены
}
// ✅ БЕЗОПАСНО - проверка по системному типу
if (organization.type === 'WHOLESALE') {
// логика для поставщиков
}
// ✅ БЕЗОПАСНО - проверка по ID из whitelist
if (ALLOWED_FULFILLMENT_IDS.includes(organization.id)) {
// логика для проверенных фулфилментов
}
```
**РАЗДЕЛЕНИЕ КОНТЕКСТОВ:**
1. **ДАННЫЕ (могут быть любыми):**
- Названия организаций: "ОПТ Маркет", "Супер Склад", и т.д.
- Названия рынков: "Садовод", "ТЯК Москва", любые другие
- Любые пользовательские строки
2. **ФУНКЦИОНАЛ (строго определен):**
- Системные разделы: `/market`, `/supplies`, `/partners`
- Типы организаций: `WHOLESALE`, `SELLER`, `FULFILLMENT`, `LOGIST`
- Статусы и enum из Prisma схемы
**ПРАВИЛО**: Физический рынок "ОПТ Маркет" - это просто строка данных. Раздел "Маркет" (/market) - это системный функционал. Они никак не связаны и не должны влиять друг на друга.
### 17.5 📦 УПРАВЛЕНИЕ СВЯЗЯМИ ТОВАР-КАРТОЧКА В РЕЦЕПТУРЕ
#### 17.5.1 Общие принципы
**НАЗНАЧЕНИЕ**: Связь товара с карточкой маркетплейса - это метаданные для учета, НЕ влияющие на физический состав продукта.
**ФОРМУЛА ПРОДУКТА НЕИЗМЕННА**:
```
ПРОДУКТ = Товар + Услуга(и) + Расходники селлера + Расходники ФФ
```
**СВЯЗЬ С МП** = отдельные метаданные для логистики и учета
#### 17.5.2 UI компонент связи с карточками
**РАСПОЛОЖЕНИЕ**: В форме создания поставки, в секции каждого товара
**ТИП КОМПОНЕНТА**: Dropdown с поиском и фильтрацией
**ИСТОЧНИК ДАННЫХ**: База данных карточек маркетплейсов селлера (GraphQL запрос)
#### 17.5.3 Логика состояний карточек
**✅ СВЯЗАНО** - карточка уже привязана к этому товару:
- Показывать зеленую галочку
- Текст: "Название карточки - Связано"
- Можно отвязать (сброс в "Без привязки")
**⚠️ ДОСТУПНО** - карточка свободна для привязки:
- Показывать желтый значок предупреждения
- Текст: "Название карточки - Доступно"
- Можно привязать к текущему товару
**❌ ЗАНЯТО** - карточка привязана к другому товару:
- Показывать красный крестик
- Текст: "Название карточки - Занято (товар: 'Название')"
- Пункт заблокирован (disabled)
- Показывать для информации, но нельзя выбрать
**🔍 БЕЗ ПРИВЯЗКИ** - товар не связан с карточкой:
- Пункт по умолчанию
- Показывать серый значок
- Текст: "Без привязки к карточке"
#### 17.5.4 Техническая реализация
**GraphQL запрос**:
```graphql
query GetSellerCards {
myMarketplaceCards {
id
title
marketplace
article
linkedProductId # null если свободна
linkedProduct {
# для отображения занятости
id
name
}
}
}
```
**Логика фильтрации**:
- Все карточки селлера показываются в dropdown
- Статус определяется по полю `linkedProductId`
- Автосвязка: карточки с похожим названием показываются первыми
**Сохранение**:
- При создании поставки связь сохраняется в поле `marketplaceCardId` рецептуры
- При изменении связи обновляется поле `linkedProductId` в карточке
#### 17.5.5 UX поведение
**ПОИСК В DROPDOWN**:
- Фильтрация по названию карточки
- Фильтрация по артикулу маркетплейса
- Автофокус при открытии
**ГРУППИРОВКА**:
```
[Dropdown: Выберите карточку Wildberries ▼]
├─ 🔍 БЕЗ ПРИВЯЗКИ
├─ ────── ДОСТУПНЫЕ ──────
├─ ⚠️ "Кроссовки Nike Air" - Доступно
├─ ⚠️ "Футболка Adidas" - Доступно
├─ ────── СВЯЗАННЫЕ ──────
├─ ✅ "Джинсы Levi's" - Связано
├─ ────── ЗАНЯТЫЕ ──────
└─ ❌ "Куртка Puma" - Занято (товар "Верхняя одежда") [disabled]
```
**ВАЛИДАЦИЯ**:
- Связь опциональна - можно создать поставку без привязки
- При выборе занятой карточки показывать предупреждение
- При отвязке подтверждать действие
#### 17.5.6 Интеграция с существующими правилами
**СОВМЕСТИМОСТЬ**:
- Не нарушает существующую логику создания поставок
- Дополняет рецептуру метаданными
- Совместима с типами поставок (карточки/поставщики)
**ОБЯЗАТЕЛЬНОСТЬ**:
- Связь с карточкой - ОПЦИОНАЛЬНА
- Товар может существовать без привязки к МП
- Карточка может существовать без привязки к товару
**ПРИОРИТЕТ РАЗРАБОТКИ**: Средний (не блокирует основную функциональность)
---
## 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` для товаров конкретной организации
### 18.7 Правила РЫНКОВ и МАРКЕТА
**🔍 КРИТИЧЕСКОЕ РАЗДЕЛЕНИЕ:**
- **РЫНОК** 🏪 = физическое место (Садовод, ТЯК)
- **МАРКЕТ** 🛒 = раздел системы `/market`
**ПОЛЕ РЫНКА В SCHEMA:**
- **Organization.market** ✅ - поставщик принадлежит физическому рынку
- **Product.market** ❌ - ЗАПРЕЩЕНО, товары наследуют рынок от организации
- **Отображение рынка товаров**: через `product.organization.market`
- **Фильтрация по рынкам**: через `organization.market`, НЕ через `product.market`
**ЗАПРОСЫ С РЫНКАМИ:**
```graphql
# ✅ ПРАВИЛЬНО - рынок от организации поставщика
query GetProductsWithMarket {
myProducts {
id
name
organization {
market # Физический рынок поставщика
}
}
}
# ✅ ПРАВИЛЬНО - товары в маркете с информацией о рынке
query GetMarketProducts {
marketProducts {
id
name
organization {
market # Рынок поставщика
name # Название поставщика
}
}
}
```
**МАРКЕТ (/market) ПРАВИЛА:**
- **Назначение**: Глобальный каталог всех товаров
- **Фильтрация**: По рынкам поставщиков, типам товаров, категориям
- **Отображение**: Показать рынок поставщика в карточках товаров
- **НЕ путать**: МАРКЕТ ≠ конкретный физический рынок
- **Значения по умолчанию в резолверах** для критических параметров (`type: args.type || "PRODUCT"`)
- **Валидация обязательных параметров** на уровне схемы (`organizationId: ID!`)
- **Кеширование обходить при проблемах** через `fetchPolicy: 'network-only'`
### 18.8 GraphQL правила для поля organization в мутациях
#### 18.8.1 Обязательность поля organization
**ПРАВИЛО**: Все мутации, возвращающие объекты с типом, включающим `organization: Organization!`, ДОЛЖНЫ запрашивать это поле.
**ПРОБЛЕМА**: Apollo Client кэш ожидает поле `organization` в ответе, если оно определено в GraphQL типе как обязательное.
#### 18.8.2 Правильное написание мутаций
**❌ НЕПРАВИЛЬНО** (вызывает ошибку Apollo Client):
```graphql
mutation UpdateLogistics($id: ID!, $input: LogisticsInput!) {
updateLogistics(id: $id, input: $input) {
success
logistics {
id
fromLocation
# НЕТ поля organization - ОШИБКА кэша!
}
}
}
```
**✅ ПРАВИЛЬНО** (работает корректно):
```graphql
mutation UpdateLogistics($id: ID!, $input: LogisticsInput!) {
updateLogistics(id: $id, input: $input) {
success
logistics {
id
fromLocation
organization {
# ОБЯЗАТЕЛЬНО включить!
id
name
fullName
}
}
}
}
```
#### 18.8.3 Чек-лист для мутаций
**ОБЯЗАТЕЛЬНАЯ ПРОВЕРКА** перед созданием мутации:
1. ✅ Проверить GraphQL тип возвращаемого объекта
2. ✅ Если есть поле `organization: Organization!` - добавить в запрос
3. ✅ Включить минимальные поля: `id`, `name`, `fullName`
4. ✅ Проверить resolver включает `include: { organization: true }`
**ПРИМЕНЯЕТСЯ К**:
- `CREATE_LOGISTICS` ✅ Исправлено
- `UPDATE_LOGISTICS` ✅ Исправлено
- `CREATE_SERVICE` - проверить при разработке
- `UPDATE_SERVICE` - проверить при разработке
- Все другие мутации с организационными объектами
**ОШИБКА БЕЗ ПОЛЯ**: `Error converting field "organization" of expected non-nullable type`
---
## 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. 🟢 Расширенная кастомизация
---
## 🚨 КРИТИЧЕСКИЕ СИТУАЦИИ И EDGE CASES
### 🔴 Отмена заказов на разных этапах workflow
**PENDING → Отмена разрешена**
- Действие: Удаление заказа без последствий
- Уведомления: Поставщику о отмене
- Влияние на статистику: Нет
**SUPPLIER_APPROVED → Отмена с согласия поставщика**
- Действие: Требуется подтверждение поставщика
- Штрафы: Возможны согласно договору
- Восстановление: Товары возвращаются в доступные остатки
**CONFIRMED/LOGISTICS_CONFIRMED → Отмена критическая**
- Действие: Требуется согласие всех участников
- Штрафы: Логистические расходы
- Альтернатива: Изменение адреса доставки
**SHIPPED/IN_TRANSIT → Отмена невозможна**
- Действие: Только возврат после получения
- Процедура: Через модуль "Возвраты с ПВЗ"
### 🔄 Частичная доставка товаров
**Сценарий**: Поставщик доставил 80 из 100 заказанных единиц
**Алгоритм обработки**:
1. Фулфилмент фиксирует фактическое количество
2. Система создает два отдельных документа:
- DELIVERED (80 единиц) - обрабатывается обычным порядком
- PARTIAL_DELIVERED (20 единиц) - остается в статусе ожидания
3. Селлер получает уведомление о частичной поставке
4. Принятие решения: ждать остаток или отменить недопоставку
### 📊 Превышение лимитов остатков
**Проблема**: Попытка заказать больше чем есть у поставщика
**Техническая реализация**:
```typescript
if (requestedQuantity > availableStock) {
throw new GraphQLError(`Недостаточно товара. Доступно: ${availableStock}, запрошено: ${requestedQuantity}`)
}
```
**UX решение**: Real-time валидация в формах заказа
### 🔍 Дубликаты артикулов
**Сценарий**: Поставщик пытается создать товар с существующим артикулом
**Проверка на уровне БД**:
```sql
UNIQUE INDEX ON products(article, organization_id)
```
**Обработка**: Автоматическое добавление суффикса или предложение изменить артикул
---
## 24. 📎 ТЕХНИЧЕСКИЕ ПРИЛОЖЕНИЯ
### Приложение A: GraphQL запросы фулфилмента
```typescript
// Основные запросы
GET_MY_SERVICES // Услуги фулфилмента
GET_MY_LOGISTICS // Логистические маршруты
GET_MY_EMPLOYEES // Сотрудники организации
GET_FULFILLMENT_WAREHOUSE_STATS // Статистика склада
GET_WAREHOUSE_PRODUCTS // Товары на складе
GET_MY_FULFILLMENT_SUPPLIES // Расходники фулфилмента
GET_EMPLOYEE_SCHEDULE // Табель рабочего времени
// Мутации
;(CREATE_SERVICE, UPDATE_SERVICE, DELETE_SERVICE)
;(CREATE_LOGISTICS, UPDATE_LOGISTICS, DELETE_LOGISTICS)
;(CREATE_EMPLOYEE, UPDATE_EMPLOYEE, DELETE_EMPLOYEE)
UPDATE_EMPLOYEE_SCHEDULE // Обновление табеля
```
### Приложение B: Компоненты фулфилмента
```typescript
// Основные dashboard компоненты
FulfillmentWarehouseDashboard // Склад фулфилмента
FulfillmentStatisticsDashboard // Статистика
ServicesDashboard // Услуги (3 вкладки)
EmployeesDashboard // Сотрудники
SuppliesDashboard // Поставки фулфилмента
// Специализированные компоненты
;(ServicesTab, LogisticsTab, SuppliesTab) // Вкладки услуг
;(EmployeeInlineForm, EmployeeEditInlineForm) // Формы сотрудников
;(FulfillmentSuppliesTab, FulfillmentConsumablesOrdersTab) // Поставки
```
### Приложение C: Специальный роутинг для типов организаций
```typescript
const handleSuppliesClick = () => {
switch (user?.organization?.type) {
case 'FULFILLMENT':
router.push('/fulfillment-supplies') // Специальный роут
break
case 'SELLER':
router.push('/supplies')
break
case 'WHOLESALE':
router.push('/wholesale-supplies')
break
case 'LOGIST':
router.push('/logist-supplies')
break
}
}
```
---
_Эта база знаний создана путем объединения rules-unified.md (v3.0) и fulfillment-cabinet-rules.md (v1.0) с устранением всех несоответствий и добавлением критически важных улучшений: быстрый справочник, глоссарий терминов, детальные алгоритмы процессов, edge cases._
_Версия: 10.2_
_Дата создания: 2025_
_Статус: ЕДИНЫЙ ИСТОЧНИК ИСТИНЫ - ГОТОВ К РАЗРАБОТКЕ_
### 🚀 УЛУЧШЕНИЯ v6.0:
- ⚡ Быстрый справочник критических правил
- 🔤 Полный глоссарий терминов с определениями
- 🎯 Навигация по ролям (разработчики, аналитики, менеджеры)
- 🔄 Детальный алгоритм создания продукта с временными рамками
- 🚨 Раздел критических ситуаций и Edge Cases
- 📌 Связующие блоки между разделами
- 📊 Таблицы SLA и временных рамок
### 🔧 ИСПРАВЛЕНИЯ v6.1:
- ✅ Устранено противоречие в моменте создания БРАКА
- ✅ Исправлена логическая цепочка: рецептура задается селлером ДО процесса
- ✅ Реалистичные временные рамки SLA (рабочие дни вместо часов)
- ✅ Унифицирована классификация расходников (по назначению при использовании)
- ✅ Согласованы все алгоритмы и процессы между разделами
### 🔧 ОБНОВЛЕНИЯ v6.3:
- ✅ **ДОБАВЛЕН КРИТИЧЕСКИЙ ЗАПРЕТ**: Использование моковых данных в продакшене
- ✅ **ОБНОВЛЕН ЧЕКЛИСТ**: Добавлена проверка на отсутствие mock данных
- ✅ **РЕАЛИЗАЦИЯ**: Полная очистка моковых данных из раздела "Мои поставки" селлера
### 🎨 ИНТЕГРАЦИЯ v6.2:
- ✅ Синхронизация с visual-design-rules.md v1.1
- ✅ Добавлены визуальные правила для 8 статусов поставок
- ✅ Создана цветовая система для 6 модулей фулфилмента
- ✅ Визуальный workflow процесса создания продукта
- ✅ Перекрестные ссылки между техническими и визуальными правилами
- ✅ Покрытие визуальными решениями увеличено с 40% до 85%
### 🚀 КОНСОЛИДАЦИЯ v7.0:
- ✅ Интеграция development-checklist.md и CLAUDE.md
- ✅ Удаление дублирующих файлов
- ✅ Создание единого источника истины
### 🔧 ПОЛНАЯ ИНТЕГРАЦИЯ v8.0:
- ✅ Интеграция work-protocols.md (детальные протоколы по сложности)
- ✅ Интеграция violation-prevention-protocol.md (СТОП-сигналы и триггеры)
- ✅ Интеграция self-validation.md (расширенная система самопроверки)
- ✅ Удаление всех дублирующих файлов протоколов
### 🎯 ОПТИМИЗАЦИЯ UI/UX v8.1:
- ✅ Добавлен ТРИГГЕР #3 для автоматической активации visual-design-rules.md
- ✅ Интегрирован специальный UI/UX протокол в чеклист
- ✅ Создана система перекрестных ссылок с visual-design-rules.md
- ✅ visual-design-rules.md остается отдельным специализированным файлом
### 📊 ИНТЕГРАЦИЯ DESCRIPTION v9.0:
- ✅ Добавлена UI структура создания поставки расходников (3 блока)
- ✅ Интегрирована концепция многоуровневых таблиц
- ✅ Добавлен механизм учета ПЛАН/ФАКТ в процессе создания продукта
- ✅ Расширена детализация рецептуры продукта
- ✅ Добавлена опция места хранения готовых продуктов
### 🔧 УТОЧНЕНИЯ ЛОГИКИ v9.1:
- ✅ Уточнен статус брака: НЕ РЕАЛИЗОВАНО (еще не дошли до этого этапа)
- ✅ Добавлены четкие правила создания предметов по ролям
- ✅ Добавлен экономический учет расходников фулфилмента для селлера
- ✅ Обновлен механизм ПЛАН/ФАКТ: потери вместо брака при пересчете
- ✅ Добавлена заметка о будущей детализации статусов товаров
### 🎨 UI УЛУЧШЕНИЯ v9.2:
- ✅ Добавлены детальные правила горизонтального скролла для блока поставщиков
- ✅ Реализован горизонтальный скролл в create-suppliers-supply-page.tsx
- ✅ Добавлена адаптивность (десктоп 280px, планшет 260px, мобильный 240px)
- ✅ Интегрированы ARIA атрибуты для доступности
- ✅ Реализовано автоскрытие полосы прокрутки и навигация клавиатурой
### 🔒 БЕЗОПАСНОСТЬ И ТЕРМИНОЛОГИЯ v10.0:
- ✅ **ДОБАВЛЕН РАЗДЕЛ 17.3**: Правила безопасности - разделение данных и функционала
- ✅ **НОВЫЕ ЗАПРЕТЫ 24-26**: Запрет использования пользовательских данных в логике безопасности
- ✅ **РАСШИРЕН ГЛОССАРИЙ**: Контекстно-зависимые термины для SupplyOrder
- ✅ **УТОЧНЕНИЕ ТЕРМИНОВ**: Четкое разделение "Маркет" (раздел) vs "Маркетплейс" (внешние площадки)
- ✅ **ПРИМЕРЫ УЯЗВИМОСТЕЙ**: Конкретные примеры безопасного и небезопасного кода
### 📝 КАЧЕСТВО ОТВЕТОВ v10.1:
- ✅ **НОВЫЕ ЗАПРЕТЫ 27-29**: Запрет представления интерпретаций как фактов
- ✅ **ОБЯЗАТЕЛЬНЫЙ ФОРМАТ ОТВЕТОВ 17.3**: Четкое разделение фактов, интерпретаций и предположений
- ✅ **СИСТЕМА МАРКИРОВКИ**: 📖 ФАКТ, 🧠 ИНТЕРПРЕТАЦИЯ, ❓ ПРЕДПОЛОЖЕНИЕ, ⚠️ НЕ НАЙДЕНО
- ✅ **СТОП-СЛОВА**: Список категоричных утверждений для избегания без доказательств
- ✅ **ОБЯЗАТЕЛЬНЫЕ ПРАВИЛА 11-13**: Указание источников и осторожные формулировки
### 🔗 ПАРТНЕРСКАЯ И РЕФЕРАЛЬНАЯ СИСТЕМА v10.2:
- ✅ **ДОБАВЛЕН РАЗДЕЛ 13.6**: Критическое различие партнерских и реферальных ссылок
- ✅ **ЧЕТКИЕ ОПРЕДЕЛЕНИЯ**: Партнерские (?partner=) vs Реферальные (?ref=) ссылки
- ✅ **ТЕХНИЧЕСКИЕ ПРАВИЛА**: Различия в обработке кодов в резолверах
- ✅ **UI СПЕЦИФИКАЦИИ**: Разные интерфейсы для партнерства и маркетинга
- ✅ **ЗАПРЕТЫ ПУТАНИЦЫ**: Строгие правила именования и терминологии
- ✅ **ПРИМЕРЫ СЦЕНАРИЕВ**: Деловое партнерство vs маркетинговые кампании