Sfera/sfera
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Объединены файлы правил системы в единую базу знаний v3.0 с устранением противоречий и дублирования. Создан rules-unified.md на основе rules.md, rules1.md и rules2.md с добавлением всех уникальных разделов. Обновлена терминология системы с соответствием реальной схеме БД (ТОВАР→PRODUCT, РАСХОДНИКИ→CONSUMABLE). Архивированы старые файлы правил в папку archive. Обновлены ссылки в CLAUDE.md и development-checklist.md на новый единый источник истины.

Browse Source 
🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Veronika Smirnova
2025-08-05 00:19:17 +03:00
parent 17ffd6c9ed
commit ee72a9488b
21 changed files with 9147 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1819
archive/rules-v2.0.md Normal file
View File

@ -0,0 +1,1819 @@
# ПРАВИЛА СИСТЕМЫ УПРАВЛЕНИЯ СКЛАДАМИ И ПОСТАВКАМИ - БАЗА ЗНАНИЙ v2.0
> ⚠️ **ВАЖНОЕ ПРИМЕЧАНИЕ**: Данный файл является объединенной базой знаний системы на основе анализа rules.md, rules1.md и description.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. [⚠️ Критические запреты](#16--критические-запреты)
### 💻 **ТЕХНИЧЕСКИЕ ПРАВИЛА**
17. [📱 Правила пользовательского интерфейса](#17--правила-пользовательского-интерфейса)
18. [🚨 Правила обработки ошибок](#18--правила-обработки-ошибок)
19. [📈 Правила производительности](#19--правила-производительности)
20. [🔐 Правила безопасности данных](#20--правила-безопасности-данных)
21. [🎯 Правила качества кода](#21--правила-качества-кода)
### 📋 **ДОПОЛНИТЕЛЬНО**
22. [📋 Приложение: Дополнительные возможности и планы](#22-приложение-дополнительные-возможности-и-планы)
---
## 🏷️ РЕЕСТР СУЩНОСТЕЙ СИСТЕМЫ
### 📦 **ОСНОВНЫЕ ПРЕДМЕТЫ**
| Сущность | Название в системе | Кабинет создания | Описание | Статус |
| ---------- | ---------------------------------- | ---------------- | ----------------------------------------------- | --------------- |
| Товар | `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) | Управляет доставками | ✅ Реализовано |
---
## 1. 🎯 ОСНОВНЫЕ ПРИНЦИПЫ СИСТЕМЫ
### 1.1 Главная логика системы
**КЛЮЧЕВОЕ ПРАВИЛО**: Товар ≠ Продукт (это разные сущности в системе)
- **ТОВАР** - сырье, базовый материал от поставщика
- **ПРОДУКТ** - готовая к продаже единица после обработки
### 1.2 Потоки в системе
**ПОТОК ТОВАРОВ**: Поставщик → Фулфилмент → Селлер/Маркетплейс
**ПОТОК РАСХОДНИКОВ**: Поставщик → Фулфилмент/Селлер (в зависимости от заказчика)
### 1.3 Уникальность артикулов
- **ФОРМАТ**: `СФ-{ТИП}-{КОД_КАТЕГОРИИ}-{КОД_ОРГАНИЗАЦИИ}-{TIMESTAMP}-{RANDOM}`
- **ТИПЫ В АРТИКУЛЕ**:
- `TOV` - Товар
- `BRK` - Брак
- `R` - Расходники
- `PRD` - Продукт
---
## 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 Кабинет поставщика
**СОЗДАЕТ И УПРАВЛЯЕТ**:
- **ТОВАР** - базовые товары поставщика
- **РАСХОДНИКИ** - материалы и вспомогательные товары
### 3.2 Кабинет фулфилмента
**ПРИНИМАЕТ, ОБРАБАТЫВАЕТ И УПРАВЛЯЕТ**:
- **ТОВАР** - базовые товары от поставщиков (принятые на склад)
- **БРАК** - производная от товара (товары с дефектами)
- **ПРОДУКТ** - производная от товара (готовые к продаже товары)
- **РАСХОДНИКИ ФУЛФИЛМЕНТА** - операционные материалы фулфилмента
- **РАСХОДНИКИ СЕЛЛЕРОВ** - материалы для товаров селлеров
### 3.3 Кабинет селлера
**ЗАКАЗЫВАЕТ И УПРАВЛЯЕТ ПОСТАВКАМИ**:
- Создает заказы товаров и расходников
- Управляет поставками на фулфилмент и маркетплейсы
- Отслеживает статусы поставок
---
## 4. 🔐 СИСТЕМА РОЛЕЙ И ДОСТУПОВ
### 4.1 Роли в системе
| Роль | Функции |
| ---------- | ------------------------------------------------------------------------ |
| Поставщик | Создание товаров, одобрение заказов, отгрузка |
| Селлер | Создание заказов, отслеживание поставок |
| Фулфилмент | Приемка товаров, выбор логистики, управление складом, создание продуктов |
| Логистика | Подтверждение доставки, транспортировка |
### 4.2 Контроль доступа
- **ЗАПРЕЩЕНО**: Поставщик не может добавлять собственные предметы в корзину
- **ПРАВИЛО**: Только активные предметы (`isActive: true`) отображаются в маркете
- **ОГРАНИЧЕНИЕ**: Доступ к заказам только для участников процесса
- **БРАК**: Доступен только для просмотра, заказ запрещен
### 4.3 Проверка остатков
- **ОБЯЗАТЕЛЬНО**: Проверять наличие предмета перед добавлением в корзину
- **ПРАВИЛО**: Количество в заказе не может превышать остаток на складе
- **ИСКЛЮЧЕНИЕ**: Предзаказы (если реализована функция)
- **ОСОБЕННОСТИ ПО ТИПАМ**:
- **ТОВАР/ПРОДУКТ**: Стандартная проверка остатков
- **БРАК**: Остатки учитываются, но заказ запрещен
- **РАСХОДНИКИ**: Проверка с учетом резервирования под активные заказы
---
## 5. 🚚 WORKFLOW ПОСТАВОК
### 5.1 Жизненный цикл статусов
```
PENDING → SUPPLIER_APPROVED → CONFIRMED → LOGISTICS_CONFIRMED → SHIPPED → IN_TRANSIT → DELIVERED
```
### 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: ПОСТУПЛЕНИЕ И ПОДСЧЕТ**
1. Товар приходит на склад фулфилмента (статус "на складе")
2. Подсчет фактического количества товара (может отличаться от плана)
3. Проверка товара на дефекты и выявление брака
#### **ЭТАП 2: ПОДГОТОВКА К РАБОТЕ**
4. Поставка попадает в раздел "Создание продукта" / "Новые"
5. Менеджер задает:
- Дедлайн выполнения
- Ответственного исполнителя
- Место хранения готовых продуктов
6. Нажимает "В работе"
#### **ЭТАП 3: ОБРАБОТКА**
7. Товары получают статус "в работе"
8. Исполнитель работает по "рецептуре" селлера:
- Применяет услуги фулфилмента
- Использует расходники селлера
- Использует расходники фулфилмента
#### **ЭТАП 4: УЧЕТ ПЛАН/ФАКТ**
9. Фиксируется в разделе "В работе":
- **ПЛАН**: Количество из поставки селлера
- **ФАКТ**: Реальное количество после подсчета = Брак + Хороший товар
- **СОЗДАНИЕ БРАКА**: Данные о браке вносятся в кабинете фулфилмента
- **ДЕТАЛИЗАЦИЯ**: По каждому размеру/объему
#### **ЭТАП 5: ЗАВЕРШЕНИЕ**
10. Исполнитель нажимает "Выполнено"
11. Товары становятся продуктами со статусом "готов к отправке"
12. Поставка переходит в "Выполнено"
### 6.2 Рецептура продукта (задается селлером)
**РЕЗУЛЬТАТ**: ПРОДУКТ = Товар + Услуга + Расходники
**КОМПОНЕНТЫ**:
- **БАЗОВЫЙ ТОВАР**: Исходный материал (например, футболка)
- **УСЛУГА ФУЛФИЛМЕНТА**: Из каталога услуг (например, "погладить")
- **РАСХОДНИК СЕЛЛЕРА**: Материалы селлера (например, фирменный пакет)
- **РАСХОДНИК ФУЛФИЛМЕНТА**: Материалы фулфилмента (например, короб + маркировка)
- **СВЯЗЬ С MP**: Опциональная связь с карточкой маркетплейса
---
## 7. 📊 СИСТЕМА УЧЕТА ДВИЖЕНИЯ ТОВАРОВ
### 7.1 Основные принципы учета
- **ПРИХОД**: Товары поступают через принятые поставки (из "в пути" → "на складе")
- **ОБРАБОТКА**: Товары переходят в статус "в работе" для создания продуктов
- **РАСХОД**: Товары убывают при отгрузке, списании, возврате, превращении в продукты
### 7.2 Двойной учет
**ДОПОЛНИТЕЛЬНЫЕ ЗНАЧЕНИЯ (показатели движения)**:
- **ПРИБЫЛО**: Количество предметов, поступивших на склад
- **УБЫЛО**: Количество предметов, списанных со склада
**ОСНОВНЫЕ ЗНАЧЕНИЯ (текущие остатки)**:
- **ФОРМУЛА**: Основные значения = Предыдущие остатки + Прибыло - Убыло
- **ОТОБРАЖЕНИЕ**: Показываются в каждом модуле статистики
### 7.3 Состояния процессов в фулфилменте
- **"На складе"** - состояние завершения процесса поставки (товар принят)
- **"В работе"** - состояние процесса "Создание продукта" (товар обрабатывается)
- **ВАЖНО**: Это состояния процессов, а не взаимоисключающие характеристики товара
---
## 8. 🏠 ОБЩИЕ ПРАВИЛА КАБИНЕТОВ
### 8.1 Универсальная структура кабинетов
**ВСЕ ТИПЫ КАБИНЕТОВ** включают следующие обязательные разделы:
#### 8.1.1 Страница "Главная"
**СТАТУС**: Планируется к реализации
**ДОСТУП**: Через навигацию в sidebar для всех типов кабинетов
**СОДЕРЖАНИЕ**: Пока пустые страницы, будут наполнены позже
**ПРАВИЛА**:
- **ОБЯЗАТЕЛЬНО**: Каждый тип кабинета должен иметь страницу "Главная"
- **НАВИГАЦИЯ**: Доступ через кнопку в sidebar (первая в списке)
- **УНИВЕРСАЛЬНОСТЬ**: Одинаковая структура навигации для всех кабинетов
- **ПЛАНЫ**: Содержание страниц будет определено на следующих этапах
#### 8.1.2 Общие разделы для всех кабинетов
**УНИВЕРСАЛЬНЫЕ РАЗДЕЛЫ** (доступны всем типам):
- 🏠 **Главная** - основная страница кабинета (планируется)
- 🛒 **Маркет** - просмотр и заказ товаров
- 🤝 **Партнеры** - управление контрагентами
- 💬 **Мессенджер** - внутренняя связь
- ⚙️ **Настройки** - профиль и конфигурация
**СПЕЦИАЛИЗИРОВАННЫЕ РАЗДЕЛЫ** (зависят от типа кабинета):
- Определяются в соответствующих разделах каждого кабинета
### 8.2 Правила sidebar навигации
#### 8.2.1 Структура навигации
**ОБЩИЙ ПРИНЦИП**:
- Условное отображение: `{user?.organization?.type === "TYPE" && (...)}`
- Адаптивность: сворачиваемый sidebar с `getSidebarMargin()`
- Состояния активности: подсветка текущего раздела
**ПОРЯДОК РАЗДЕЛОВ В SIDEBAR**:
1. 🏠 **Главная** (планируется для всех)
2. **Специализированные разделы** (зависят от типа кабинета)
3. 🛒 **Маркет** (универсальный)
4. 🤝 **Партнеры** (универсальный)
5. 💬 **Мессенджер** (универсальный)
6. ⚙️ **Настройки** (универсальный)
7. **Выход** (универсальный)
#### 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 Создание поставки расходников селлера
#### **Структура страницы**:
**БЛОК 1: ПОСТАВЩИКИ** _(обязательный, верхняя часть)_:
- Карточки поставщиков из раздела "Партнеры"
- Горизонтальный скролл при превышении ширины
- Выбор только одного поставщика одновременно
**БЛОК 2: РАСХОДНИКИ** _(зависимый, центральная часть)_:
- Активен только после выбора поставщика
- Сортировка: цена, название, категория
- Фильтры: категория, ценовой диапазон
- Карточка с полем ввода количества и кнопками +/-
**БЛОК 3: КОРЗИНА** _(правая часть)_:
- **РАСПОЛОЖЕНИЕ**: Правая часть экрана
- **СОДЕРЖАНИЕ**:
- Счетчик видов расходников
- Детализация по каждому расходнику (название, количество, цена, сумма)
- Общая сумма всех расходников
- **УПРАВЛЕНИЕ**:
- Изменение количества (с валидацией остатков)
- Удаление позиций
- **ОБЯЗАТЕЛЬНЫЕ ПОЛЯ**:
- Выбор фулфилмент-центра (из партнеров)
- Дата поставки (не прошедшая, по умолчанию - текущая)
#### **Валидация и ограничения**:
**КОЛИЧЕСТВО ТОВАРОВ**:
- **МИНИМУМ**: 1 единица/комплект
- **МАКСИМУМ**: Остаток у поставщика
- **ПРОВЕРКА**: В реальном времени при изменении
**ДАТА ПОСТАВКИ**:
- **ЗАПРЕТ**: Выбор прошедших дат
- **ПО УМОЛЧАНИЮ**: Дата создания поставки
**ОБЯЗАТЕЛЬНЫЕ ПОЛЯ**:
- Выбор поставщика
- Минимум один расходник в корзине
- Выбор фулфилмент-центра
- Дата поставки
### 8.3 Отображение созданных поставок
#### **Многоуровневая таблица**:
**ПЕРВЫЙ УРОВЕНЬ** _(основной список)_:
- **СОРТИРОВКА**: Номер поставки от большего к меньшему
- **ОБЯЗАТЕЛЬНЫЕ КОЛОНКИ**:
- Порядковый номер поставки
- Количество видов расходников
- Стоимость всей поставки
- Количество категорий
- Статус поставки
**ВТОРОЙ УРОВЕНЬ** _(детализация по клику)_:
- **АКТИВАЦИЯ**: По клику на строку первого уровня
- **СОДЕРЖАНИЕ**:
- Название расходника
- Количество
- Цена
- Категория
- Поставщик
- **ОГРАНИЧЕНИЯ**: Только просмотр, редактирование запрещено
### 8.4 Статусы поставок селлера
1. **В работе** - создана селлером
2. **Одобрена** - подтверждена поставщиком
3. **Ожидает отгрузки** - логистика назначена
4. **В пути** - товар отгружен
5. **Доставлена/Принято** - получена фулфилментом
### 9.3 Правила кнопки "Создать поставку" в разделе "Мои поставки"
#### **9.3.1 Общие принципы**
- **КОНТЕКСТНОСТЬ**: Кнопка создания появляется только в активном табе
- **РАСПОЛОЖЕНИЕ**: Правая часть строки таба, на том же уровне что и название
- **СТИЛИСТИКА**: В том же стиле что и сами табы (соответствует уровню иерархии)
- **ФУНКЦИОНАЛЬНОСТЬ**: Кнопка ведет на страницу создания поставки соответствующего типа
#### **9.3.2 Размещение кнопок по табам**
**УРОВЕНЬ 2 (Подтабы фулфилмента):**
- **📦 Товар → Карточки**: Кнопка "Создать поставку" → `/supplies/create-cards`
- **📦 Товар → Поставщики**: Кнопка "Создать поставку" → `/supplies/create-suppliers`
- **🔧 Расходники селлера**: Кнопка "Создать поставку" → `/supplies/create-consumables`
**УРОВЕНЬ 2 (Подтабы маркетплейсов):**
- **🟣 Wildberries**: Кнопка "Создать поставку" → `/supplies/create-wildberries`
- **🔵 Ozon**: Кнопка "Создать поставку" → `/supplies/create-ozon`
#### **9.3.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.3.4 Поведение кнопок**
- **ВИДИМОСТЬ**: Кнопка показывается только в активном табе
- **ИКОНКА**: `Plus` размером `h-3 w-3` слева от текста
- **ТЕКСТ**: "Создать" на мобильных, "Создать поставку" на десктопах
- **АДАПТИВНОСТЬ**: Скрытие текста на маленьких экранах (`hidden sm:inline`)
#### **9.3.5 Удаление старой кнопки**
- **УБРАТЬ**: Текущий dropdown "Создать поставку" из верхней части
- **ПРИЧИНА**: Заменяется контекстными кнопками в табах
- **СОХРАНИТЬ**: Стили и логику навигации, но адаптировать под новые роуты
### 9.4 Структура страницы "Мои поставки" - Трёхблочная архитектура
#### **9.4.1 Обязательная структура страницы**
**ПРИНЦИП**: Страница состоит из трёх визуально разделённых блоков
```
┌─────────────────────────────────────────┐
│ 1. БЛОК ТАБОВ (навигация) │
│ - Фиксированная высота │
│ - Glass-эффект │
│ - Иерархическая структура │
├─────────────────────────────────────────┤
│ 2. БЛОК СТАТИСТИКИ (метрики) │
│ - Контекстные данные │
│ - 4 карточки в ряд (desktop) │
│ - Динамическое обновление │
├─────────────────────────────────────────┤
│ 3. ОСНОВНОЙ БЛОК (контент) │
│ - Сохраняет весь функционал │
│ - Таблицы, фильтры, действия │
│ - Высота до низа sidebar │
└─────────────────────────────────────────┘
```
#### **9.4.2 Блок статистики - контекстные метрики**
**ПРАВИЛО**: Статистика меняется в зависимости от выбранных табов
**Для путей "Фулфилмент → Товар → Карточки/Поставщики":**
- Всего поставок
- Активных поставок
- Сумма активных поставок
- В пути
**Для пути "Фулфилмент → Расходники селлера":**
- Всего поставок
- Активных поставок
- Видов расходников
- Критические остатки
**Для путей "Маркетплейсы → Wildberries/Ozon":**
- Поставок на маркетплейс
- Товаров отправлено
- Возвраты за неделю
- Эффективность поставок
#### **9.4.3 Высота основного блока**
**ФОРМУЛА РАСЧЕТА**:
```css
height: calc(100vh - headerHeight - tabsHeight - statsHeight - margins)
```
**ПРАВИЛО ВЫРАВНИВАНИЯ**:
- Нижняя граница основного блока должна быть на одном уровне с нижней границей sidebar
- При изменении размера окна высота пересчитывается
- Внутренний скролл: `overflow-y-auto`
#### **9.4.4 Сохранение функционала**
**КРИТИЧЕСКИ ВАЖНО**: При добавлении блока статистики весь существующий функционал сохраняется:
- Таблицы с данными поставок
- Фильтры и сортировка
- Кнопки действий
- Детализация при клике
- Пагинация
- Поиск
**ЗАПРЕЩЕНО**:
- Удалять существующие компоненты
- Изменять логику работы таблиц
- Нарушать существующие API вызовы
#### **9.4.5 Проверка остатков при создании поставки**
**ОБЯЗАТЕЛЬНАЯ ВАЛИДАЦИЯ**:
1. **Проверка на клиенте**:
```typescript
// При изменении количества
if (quantity > product.stock) {
toast.error(`Недостаточно товара. Доступно: ${product.stock}`);
return;
}
```
2. **Проверка на сервере**:
```typescript
// Перед созданием заказа
const stockAvailable = await checkStockAvailability(productId, quantity);
if (!stockAvailable) {
throw new Error("Insufficient stock");
}
```
3. **Логирование проверок**:
- Все попытки добавления в корзину
- Результаты проверки остатков
- ID пользователя и timestamp
#### **9.4.6 Адаптивность блоков**
**Desktop (>1024px)**:
- Все три блока вертикально
- Статистика: 4 карточки в ряд
**Tablet (768-1024px)**:
- Все три блока вертикально
- Статистика: 2 карточки в ряд
**Mobile (<768px)**:
- Блоки в колонку
- Статистика: 1 карточка в ряд
- Сворачиваемая статистика
### 9.5 Табы "Карточки" и "Поставщики" - объединённая логика
#### **9.5.1 Принцип единого типа предмета**
**КЛЮЧЕВОЕ ПРАВИЛО**: Табы "Карточки" и "Поставщики" - это два способа создания поставок одного типа предмета (ТОВАР)
**СПОСОБЫ СОЗДАНИЯ**:
- **Карточки** - импорт товаров через WB API с автоматическим созданием поставки
- **Поставщики** - прямой заказ товаров у поставщика с указанием рецептуры
**РЕЗУЛЬТАТ**: Оба способа создают `SupplyOrder` с товарами типа `PRODUCT`
#### **9.5.2 Общая статистика**
**ПРАВИЛО**: Блок статистики показывает ОДИНАКОВЫЕ данные для обоих табов
**МЕТРИКИ ДЛЯ ТАБОВ "КАРТОЧКИ" И "ПОСТАВЩИКИ"**:
- Всего поставок товаров (из всех источников)
- Активных поставок товаров (в работе)
- Сумма активных поставок товаров
- Товаров в пути (все способы доставки)
**ЗАПРЕЩЕНО**: Разделять статистику по способу создания
#### **9.5.3 Общий основной блок**
**СОДЕРЖИМОЕ**: Единая таблица всех поставок товаров
**ИСТОЧНИКИ ДАННЫХ**:
- Поставки, созданные через импорт карточек WB
- Поставки, созданные через заказ у поставщиков
- Все промежуточные и завершённые поставки
**РАЗЛИЧИЯ ТАБОВ**:
- Только кнопки создания ведут на разные страницы
- Таб "Карточки": `/supplies/create-cards`
- Таб "Поставщики": `/supplies/create-suppliers`
#### **9.5.4 Структура таблицы поставок товаров**
**ОБЯЗАТЕЛЬНЫЕ КОЛОНКИ**:
- Номер поставки
- Способ создания (иконка: 📱 карточки / 🏢 поставщик)
- Количество товаров
- Общая стоимость
- Поставщик/Источник
- Дата поставки (планируемая дата доставки)
- Статус
- Дата создания
- Действия
**ФИЛЬТРЫ**:
- По статусу workflow
- По способу создания
- По поставщику
- По периоду
- По дате поставки
- По сумме заказа
#### **9.5.5 Детализация поставки**
**ПРИ КЛИКЕ НА ПОСТАВКУ**:
- Раскрывается детализация товаров в поставке
- Информация о рецептуре (если применимо)
- История изменения статусов
- Логистическая информация
- Связанные документы
**ДЕЙСТВИЯ В ДЕТАЛИЗАЦИИ**:
- Отслеживание статуса
- Связь с поставщиком/логистикой
- Отмена (если статус позволяет)
- Экспорт данных
#### **9.5.6 Принципы реализации**
**ОБЯЗАТЕЛЬНО**:
- Использовать единый компонент для отображения таблицы
- Агрегировать данные из всех источников в статистике
- Сохранять фильтрацию при переключении между табами
**ЗАПРЕЩЕНО**:
- Создавать отдельные таблицы для разных способов создания
- Разделять статистику по источникам
- Дублировать логику отображения поставок
### 9.7 Форма создания поставки товаров через поставщиков
#### **9.7.1 Маршрут и навигация**
**URL**: `/supplies/create-suppliers`
**Доступ**: Только для селлеров и администраторов
**Возврат**: Кнопка "Назад" ведет к табу "Поставщики" в разделе товаров
#### **9.7.2 Структура страницы - 3 блока (аналогично create-consumables)**
**БЛОК 1: ЗАГОЛОВОК И НАВИГАЦИЯ**
- Заголовок: "Создание поставки товаров через поставщиков"
- Подзаголовок: "Прямой заказ товаров у поставщика с указанием рецептуры"
- Кнопка "Назад" (возврат к табу "Поставщики")
- Индикатор прогресса: "Шаг 1 из 3" (Товары → Логистика → Подтверждение)
**БЛОК 2: ФОРМА ТОВАРОВ**
- **Выбор поставщика**: Работает как на create-consumables (выбор из существующих)
- **Каталог товаров поставщика**: Отображение доступных товаров выбранного поставщика
- **Корзина товаров**: Система добавления товаров в корзину как на create-consumables
- **Поля товара при добавлении в корзину**:
- Название товара (из каталога поставщика)
- Артикул поставщика (из каталога)
- Категория (из каталога)
- Количество (вводит пользователь, > 0)
- Цена за единицу (из каталога или договорная)
- Комплектность (если есть) - описание состава комплекта
- Рецептура/состав (текстовое поле для дополнений)
- Параметры товара (цвет, размер, материал - если применимо)
**БЛОК 3: КОРЗИНА И ИТОГИ**
- Таблица товаров в корзине
- **Желаемая дата поставки** (обязательное поле с календарем)
- **Выбор логистики**:
- Dropdown "Логистическая компания" (опционально)
- Если не выбрано: "Логистику выберет фulfilment"
- Ориентировочная стоимость логистики (расчетная)
- Общее количество товаров в корзине
- Общая стоимость товаров
- Ориентировочная стоимость фулфилмента (расчетная)
- **Итого к оплате** (сумма всех составляющих)
- Кнопка "Продолжить" (переход к подтверждению заказа)
#### **9.7.3 Принцип работы с поставщиками-партнерами**
**ИСТОЧНИК ПОСТАВЩИКОВ**:
- Показываются только поставщики-партнеры из таблицы `Counterparty`
- Фильтрация: `counterparty.type === "WHOLESALE"`
- Партнерство может быть создано двумя способами:
1. Через заказ в маркете → автоматическое партнерство после одобрения
2. Через раздел "Партнеры" → отправка и принятие заявки `CounterpartyRequest`
**ВЫБОР ПОСТАВЩИКА**:
- Dropdown с поиском партнеров-поставщиков
- Отображение: Название поставщика, ИНН, статус партнерства
- Только активные партнеры с типом WHOLESALE
- При выборе загружается каталог товаров поставщика из `Product` таблицы
**КАТАЛОГ ТОВАРОВ ПАРТНЕРА**:
- Товары из `Product` where `organizationId = поставщик.id`
- Отображение в виде карточек с полями:
- Картинка товара
- Название, артикул
- Цена за единицу
- Доступное количество
- Поле ввода количества (минимум 5 цифр) с кнопками +/-
- Фильтрация по категориям
- Поиск по названию/артикулу
#### **9.7.4 Принцип работы с товарами и корзиной (как на create-consumables)**
**ДОБАВЛЕНИЕ В КОРЗИНУ**:
- Клик по товару → модальное окно с деталями
- Указание количества, комплектности, дополнительных параметров
- Кнопка "Добавить в корзину"
**КОРЗИНА**:
- Отображение добавленных товаров в таблице
- Колонки: Товар, Артикул, Количество, Цена, Комплектность, Сумма
- Возможность изменения количества
- Кнопка удаления товара из корзины
- Автоматический пересчет итогов
#### **9.7.5 Поля формы товара**
**ОСНОВНЫЕ ПОЛЯ** (из каталога поставщика):
- Название товара
- Артикул поставщика
- Категория
- Базовая цена
**ПОЛЯ ДЛЯ ЗАПОЛНЕНИЯ**:
- Количество (целое число > 0)
- Комплектность (если есть) - текстовое описание состава
- Цена за единицу (может отличаться от базовой по договоренности)
- Описание/рецептура (дополнительные требования)
- Особые требования к товару
**ПАРАМЕТРЫ ТОВАРА** (если применимо):
- Цвет, Размер, Материал, Бренд
- Динамические параметры для конкретной категории
#### **9.7.6 Валидация и проверки**
**ОБЯЗАТЕЛЬНАЯ ВАЛИДАЦИЯ**:
- Выбран поставщик
- В корзине минимум 1 товар
- Указана желаемая дата поставки
- У всех товаров указано количество > 0
- Все товары проверены на наличие у поставщика
- Количество каждого товара ≤ доступному остатку
**ПРЕДУПРЕЖДЕНИЯ**:
- "Товар заканчивается на складе поставщика (осталось X шт)"
- "Товар недоступен, выберите другое количество"
- "Выбранная дата может не соответствовать возможностям логистики"
- "Габариты не указаны - стоимость логистики ориентировочная"
- Превышение лимитов заказа
- Значительное отклонение цены от каталожной
**АВТОМАТИЧЕСКИЕ РАСЧЕТЫ**:
- Стоимость по каждому товару = количество × цена
- Общая стоимость товаров в корзине
- Комиссии фулфилмента (% от стоимости)
- Логистика (по весу/габаритам или фиксированная ставка)
#### **9.7.7 Выбор логистики**
**ОПЦИИ ЛОГИСТИКИ**:
- "Автоматический выбор" (фулфилмент выберет оптимальную)
- Список доступных логистических компаний
- Отображение ориентировочной стоимости по каждой опции
- Сроки доставки по каждой опции
**ЛОГИКА ВЫБОРА**:
- Если селлер не выбрал → фулфилмент выбирает оптимальную
- Если селлер выбрал → используется выбранная компания
- Финальная стоимость может отличаться от ориентировочной
#### **9.7.8 Желаемая дата поставки**
**РАСПОЛОЖЕНИЕ**: В блоке корзины и итогов
**ПОЛЕ "ЖЕЛАЕМАЯ ДАТА ПОСТАВКИ"**:
- **Обязательное поле** для планирования
- **Календарь** с ограничениями:
- Минимум: завтра (нельзя выбрать прошедшие даты)
- Максимум: +90 дней от текущей даты
- **Проверка на рабочие дни** (опционально)
- **Подсказки** по срокам доставки от выбранной логистической компании
**ЛОГИКА РАБОТЫ С ДАТОЙ**:
- При выборе логистики → автоматическое обновление возможных дат
- При изменении даты → пересчет стоимости логистики (если зависит от срочности)
- Отображение: "Ориентировочная дата доставки: 15-17 января 2024"
#### **9.7.9 Ограничения и проверки товаров**
**КОЛИЧЕСТВЕННЫЕ ОГРАНИЧЕНИЯ**:
- **НЕТ ограничений** на максимальное количество товаров в поставке
- **ОБЯЗАТЕЛЬНАЯ проверка** доступности на складах поставщиков
- **В реальном времени** проверка остатков при добавлении в корзину
- **Предупреждения** если запрашиваемое количество превышает доступное
- **Блокировка** добавления товара если его нет в наличии у поставщика
**ЛОГИКА ПРОВЕРКИ ОСТАТКОВ**:
- При добавлении товара в корзину → запрос к API поставщика
- При изменении количества → повторная проверка
- Отображение доступного количества рядом с полем ввода
- Сообщение: "Доступно: 150 шт" или "Нет в наличии"
#### **9.7.10 Габариты и логистические данные**
**НА ЭТАПЕ СОЗДАНИЯ ПОСТАВКИ**:
- **НЕТ обязательных** полей для габаритов/веса
- **Ориентировочный расчет** логистики по средним показателям категории
- **Предупреждение** что финальная стоимость может отличаться
**В КАБИНЕТЕ ПОСТАВЩИКА** (при одобрении поставки):
- **Возможность ввести** точные логистические данные:
- Габариты каждого товара (Д×Ш×В в см)
- Объем упаковки (в куб.м)
- Количество мест/коробок
- Общий вес поставки
- **НЕ обязательные** для заполнения (можно оставить пустыми)
- **Уточнение стоимости** логистики после заполнения данных
#### **9.7.11 Навигация и сохранение**
**УПРАВЛЕНИЕ СЕССИЕЙ**:
- Автосохранение корзины каждые 30 секунд
- Сохранение состояния при смене поставщика
- Предупреждение при попытке покинуть страницу
**ПЕРЕХОДЫ**:
- "Назад" → возврат к табу "Поставщики" (с предупреждением о потере данных)
- "Очистить корзину" → очистка всех товаров с подтверждением
- "Продолжить" → переход к подтверждению и оформлению заказа
#### **9.7.12 Интеграция с системой**
**СВЯЗЬ С ДАННЫМИ**:
- Работа с каталогом товаров поставщиков
- Проверка остатков в реальном времени
- Создание черновика `SupplyOrder` типа `ТОВАР` способом `suppliers`
**ОСОБЕННОСТИ**:
- Отличие от "Карточки": здесь товары выбираются из каталога поставщика
- Отличие от "Расходники": здесь товары предназначены для перепродажи
- Возможность указания комплектности для наборов товаров
### 9.8 Экономика
_Раздел находится в разработке. Будет добавлен позже._
---
## 10. 🏪 КАБИНЕТ ПОСТАВЩИКА
### 10.1 Основные возможности
**СОЗДАНИЕ КАРТОЧЕК**:
- **ТОВАР** - базовые товары поставщика
- **РАСХОДНИКИ** - материалы и вспомогательные товары
### 10.2 Обязательные поля карточки
**Базовые параметры**:
- Фото (система загрузки и управления изображениями)
- Название
- Автоматическая генерация артикула СФ
- Описание
- Количество предметов в единицах
- Количество комплектов (если применимо)
- Категория (28 предустановленных + специализированные для расходников)
- Бренд, Цвет, Размер/объем, Вес, Габариты, Материал
- Цена за единицу и за комплект
- Заказано, В пути, Остаток, Продано
### 10.3 Отображение информации в карточках
**Каждая карточка содержит**:
- Основное изображение
- Название и артикул СФ
- Цена за единицу/комплект
- Категория и статус активности
- Данные о движении: остаток, заказано, в пути, продано
- Индикаторы низких остатков
### 10.4 Статистика поставщика
**Блок статистики включает**:
- **ТОВАРЫ**: Общая статистика товаров поставщика
- **РАСХОДНИКИ**: Материалы и вспомогательные товары
- Классифицируются при заказе в зависимости от заказчика
- Общая статистика по всем расходникам
### 10.5 Экономика
_Раздел находится в разработке. Будет добавлен позже._
---
## 11. 🏭 КАБИНЕТ ФУЛФИЛМЕНТА
### 11.1 Структура раздела склад фулфилмента
#### **Модули в обязательной последовательности**:
1. **📦 ПРОДУКТ** - готовые к продаже товары
2. **🛒 ТОВАР** - базовые товары от поставщиков
- Товары "на складе" - готовы к обработке
- Товары "в обработке" - в процессе создания продукта
3. **❌ БРАК** - товары с дефектами
4. **↩️ ВОЗВРАТЫ С ПВЗ** - возвращенные товары
5. **🎯 РАСХОДНИКИ СЕЛЛЕРОВ** - материалы для селлеров
6. **⚙️ РАСХОДНИКИ ФУЛФИЛМЕНТ** - операционные материалы
- **КЛИКАБЕЛЬНЫЙ МОДУЛЬ** - содержит полноценный раздел учёта
### 11.2 Движение товаров в фулфилменте
#### **Поступление товаров**:
- **ПОСТАВКИ**: От поставщиков через систему заказов
- **ВОЗВРАТЫ**: Товары, возвращенные с ПВЗ
- **ПЕРЕМЕЩЕНИЯ**: Между складами и магазинами
#### **Расход товаров**:
- **ОТГРУЗКА**: Товары отправлены селлерам
- **СПИСАНИЕ**: Брак, утрата, утилизация
- **ВОЗВРАТ**: Возврат поставщику
- **ИСПОЛЬЗОВАНИЕ**: Расходники для операций
### 11.3 Модуль "Расходники фулфилмента"
**ОСОБЕННОСТИ**:
- **ИНТЕРАКТИВНОСТЬ**: Кликабельный элемент в статистике
- **ФУНКЦИОНАЛЬНОСТЬ**: Полноценный раздел учёта
- **СОДЕРЖАНИЕ**: Управление расходниками фулфилмента
### 11.4 Блок детализации по магазинам
**НАЗНАЧЕНИЕ**: Распределение товаров по торговым точкам/магазинам
**ФУНКЦИИ**:
- **ОСТАТКИ ПО МАГАЗИНАМ**: Отображение количества товаров в каждом магазине
- **УПРАВЛЕНИЕ РАСПРЕДЕЛЕНИЕМ**: Перемещение товаров между точками
- **КОНТРОЛЬ ДВИЖЕНИЯ**: Отслеживание перемещений между складами и магазинами
- **АНАЛИТИКА**: Сравнение эффективности разных точек
- **ПЛАНИРОВАНИЕ**: Оптимизация распределения товаров
### 11.5 Экономика
_Раздел находится в разработке. Будет добавлен позже._
---
## 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 Правила логистики
**ОБЯЗАТЕЛЬНО**:
- Своевременное подтверждение заявок
- Соблюдение сроков доставки
- Бережная транспортировка товаров
- Уведомление о статусе доставки
**ЗАПРЕЩЕНО**:
- Принятие заявок без подтверждения возможности выполнения
- Нарушение сроков доставки без уведомления
- Повреждение товаров при транспортировке
### 12.6 Экономика
_Раздел находится в разработке. Будет добавлен позже._
---
## 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 Глобальная интеграция
- **МАРКЕТ**: Товары поставщиков отображаются в глобальном маркете
- **СИНХРОНИЗАЦИЯ**: Данные склада синхронизируются с модулем аналитики
- **УВЕДОМЛЕНИЯ**: Единая система через встроенный мессенджер
### 13.2 Интеграция с маркетплейсами
- **WILDBERRIES**: Обязательная проверка активности API ключа
- **СИНХРОНИЗАЦИЯ**: Регулярное обновление данных из внешних источников
- **ЛОКАЛЬНЫЕ КОПИИ**: Сохранение данных для офлайн работы
### 13.3 Интеграция с модулем "Услуги"
**РАСХОДНИКИ ФУЛФИЛМЕНТА В УСЛУГАХ**:
- Расходники фулфилмента - собственность фулфилмента (куплены у поставщиков)
- Фулфилмент создает заявки-поставки для покупки расходников у поставщиков
- Селлеры могут использовать расходники фулфилмента в разделе "Услуги / Расходники"
- Для создания продукта из товара
- Расходники списываются с остатков фулфилмента
- Стоимость включается в стоимость услуги
**WORKFLOW ИСПОЛЬЗОВАНИЯ**:
1. Селлер выбирает услугу "Создание продукта"
2. Указывает базовый товар
3. Выбирает необходимые расходники фулфилмента
4. Фулфилмент обрабатывает заказ и создает продукт
5. Расходники списываются, создается готовый продукт
### 12.4 Система тарификации логистики
**ПАРАМЕТРЫ**:
- **Тариф до 1м³** - базовая стоимость для малых грузов
- **Тариф свыше 1м³** - стоимость для крупных грузов
- **Маршруты доставки** - от точки отправления до точки назначения
- **Описание услуг** - дополнительные условия доставки
---
## 14. 📊 СТАТИСТИКА И АНАЛИТИКА
### 14.1 Структура статистики по кабинетам
#### **В КАБИНЕТЕ ПОСТАВЩИКА**:
- **ТОВАРЫ**: Общая статистика товаров поставщика
- **РАСХОДНИКИ**: Материалы и вспомогательные товары (классифицируются при заказе)
#### **В КАБИНЕТЕ ФУЛФИЛМЕНТА**:
- **ТОВАРЫ**: Базовые товары от поставщиков (принятые на склад)
- **ПРОДУКТЫ**: Отдельный блок готовой продукции
- **БРАК**: Статистика потерь и списаний
- **РАСХОДНИКИ ФУЛФИЛМЕНТА**: Операционные материалы фулфилмента
- **РАСХОДНИКИ СЕЛЛЕРОВ**: Материалы для товаров селлеров
### 14.2 Ключевые метрики
**ОБЩИЕ ПОКАЗАТЕЛИ**:
- Общие остатки, заказано, в пути, остаток, продано
- Подсветка предметов с остатками ниже критического уровня
**АКТУАЛИЗАЦИЯ ДАННЫХ**:
- При изменении количества в карточке данные актуализируются во всей системе
- Статистика обновляется в реальном времени
- Отслеживание изменений для аналитики
---
## 15. ⚠️ КРИТИЧЕСКИЕ ЗАПРЕТЫ
### 15.1 НИКОГДА НЕ ДЕЛАТЬ:
1. ❌ Удалять предметы с существующими заказами
2. ❌ Изменять статусы заказов без уведомлений
3. ❌ Обходить проверки остатков предметов
4. ❌ Давать доступ к чужим данным
5. ❌ Игнорировать ошибки валидации
6. ❌ Сохранять пароли в открытом виде
7. ❌ Пропускать логирование критических операций
8. ❌ Блокировать интерфейс без индикации загрузки
9. ❌ Создавать брак или продукт без связи с родительским товаром
10. ❌ Создавать отдельные типы расходников (только общий тип "РАСХОДНИКИ")
11. ❌ Разрешать заказ брака
12. ❌ Нарушать иерархию типов предметов
13. ❌ Пропускать промежуточные статусы в workflow
14. ❌ Нарушать обязательную последовательность модулей в статистике фулфилмента
### 13.2 ОБЯЗАТЕЛЬНЫЕ ПРАВИЛА:
1. ✅ Проверка остатков перед добавлением в корзину
2. ✅ Валидация всех числовых значений (цена > 0, вес > 0)
3. ✅ Автоматическая генерация уникальных артикулов СФ
4. ✅ Логирование всех изменений статусов
5. ✅ Уведомления всех участников при изменении статусов
6. ✅ Обязательная типизация всех предметов
7. ✅ Связь производных типов с родительскими предметами
8. ✅ Проверка доступности товаров перед заказом
9. ✅ Соблюдение жизненного цикла статусов поставок
10. ✅ Фиксация план/факт в процессе создания продукта
---
## 🎖️ ПРИОРИТЕТЫ РАЗРАБОТКИ
### ВЫСОКИЙ ПРИОРИТЕТ:
1. 🔴 Безопасность и контроль доступа
2. 🔴 Целостность данных и валидация
3. 🔴 Корректность статусов поставок
4. 🔴 Уведомления участников процесса
5. 🔴 Правильная типизация предметов
6. 🔴 Связи между товарами и производными типами
### СРЕДНИЙ ПРИОРИТЕТ:
1. 🟡 Производительность и оптимизация
2. 🟡 Пользовательский опыт
3. 🟡 Аналитика и отчетность
4. 🟡 Интеграции с внешними системами
5. 🟡 Workflow для брака и продуктов
6. 🟡 Разделение расходников по типам
### НИЗКИЙ ПРИОРИТЕТ:
1. 🟢 Дополнительные фильтры
2. 🟢 Косметические улучшения
3. 🟢 Экспериментальные функции
4. 🟢 Расширенная кастомизация
---
## 📦 ПРИЛОЖЕНИЕ: КАТЕГОРИИ РАСХОДНИКОВ
### Специализированные категории для расходников:
#### 🎁 **УПАКОВКА И ЗАЩИТА**
- Коробки, пакеты, пузырчатая пленка, стрейч-пленка, защитные уголки
#### 🏷️ **МАРКИРОВКА И ИДЕНТИФИКАЦИЯ**
- Этикетки, бирки, стикеры, маркеры, штампы, термоэтикетки
#### 🔧 **КРЕПЕЖ И СОЕДИНЕНИЕ**
- Скотч, клей, стяжки, степлер, веревки, стрейч-лента
#### 📄 **ДОКУМЕНТООБОРОТ И ВКЛАДЫШИ**
- Накладные, инструкции, буклеты, визитки, промокоды
#### 🧼 **ГИГИЕНА И БЕЗОПАСНОСТЬ**
- Перчатки, маски, антисептики, салфетки, бахилы
#### 🛠️ **ИНСТРУМЕНТЫ И ПРИСПОСОБЛЕНИЯ**
- Ножи, линейки, упаковочные машины, весы
#### 🎨 **БРЕНДИНГ И ДИЗАЙН**
- Фирменные пакеты, брендированные коробки, подарочная упаковка
#### ⚡ **СПЕЦИАЛИЗИРОВАННЫЕ МАТЕРИАЛЫ**
- Антистатические пакеты, влагопоглотители, защита от краж
---
## 16. 📱 ПРАВИЛА ПОЛЬЗОВАТЕЛЬСКОГО ИНТЕРФЕЙСА
### 16.1 Отзывчивость интерфейса
- **ОБЯЗАТЕЛЬНО**: Интерфейс должен работать на всех устройствах
- **ПРАВИЛО**: Адаптивная сетка для карточек товаров
- **ФУНКЦИЯ**: Оптимизация для мобильных устройств
- **ТРЕБОВАНИЕ**: Корректное отображение на экранах от 320px до 4K
### 15.2 Обратная связь пользователю
- **ОБЯЗАТЕЛЬНО**: Уведомления об успешных/неуспешных операциях
- **ПРАВИЛО**: Индикаторы загрузки для длительных операций
- **ФУНКЦИЯ**: Подтверждение критических действий (удаление, деактивация)
- **UX**: Понятные сообщения об ошибках с предложением решения
---
## 17. 🚨 ПРАВИЛА ОБРАБОТКИ ОШИБОК
### 17.1 Обработка ошибок
- **ОБЯЗАТЕЛЬНО**: Логирование всех ошибок с детальной информацией
- **ПРАВИЛО**: Понятные сообщения об ошибках для пользователя
- **ФУНКЦИЯ**: Автоматическое восстановление после сбоев
- **МОНИТОРИНГ**: Отслеживание критических ошибок в реальном времени
### 16.2 Резервное копирование
- **КРИТИЧЕСКИ ВАЖНО**: Регулярное резервное копирование данных товаров
- **ПРАВИЛО**: Версионность изменений для возможности отката
- **ФУНКЦИЯ**: Автоматическое восстановление связей при сбоях
- **ПЕРИОДИЧНОСТЬ**: Ежедневные и еженедельные бэкапы
---
## 18. 📈 ПРАВИЛА ПРОИЗВОДИТЕЛЬНОСТИ
### 18.1 Оптимизация загрузки
- **ПРАВИЛО**: Пагинация для больших списков товаров
- **ФУНКЦИЯ**: Ленивая загрузка изображений
- **ОПТИМИЗАЦИЯ**: Кэширование часто запрашиваемых данных
- **ПРОИЗВОДИТЕЛЬНОСТЬ**: Время загрузки страницы не более 3 секунд
### 17.2 Масштабируемость
- **АРХИТЕКТУРА**: Модульная структура для легкого расширения
- **ПРАВИЛО**: Использование индексов для быстрого поиска
- **ФУНКЦИЯ**: Горизонтальное масштабирование при росте нагрузки
- **ПЛАНИРОВАНИЕ**: Готовность к увеличению нагрузки в 10 раз
---
## 19. 🔐 ПРАВИЛА БЕЗОПАСНОСТИ ДАННЫХ
### 19.1 Защита данных
- **ОБЯЗАТЕЛЬНО**: Шифрование чувствительных данных
- **ПРАВИЛО**: Аудит всех действий пользователей
- **ФУНКЦИЯ**: Контроль доступа на уровне API
- **БЕЗОПАСНОСТЬ**: Двухфакторная аутентификация для критических операций
### 18.2 Соответствие требованиям
- **GDPR**: Право на удаление и экспорт данных
- **ПРАВИЛО**: Прозрачность обработки персональных данных
- **ФУНКЦИЯ**: Логирование согласий пользователей
- **СООТВЕТСТВИЕ**: Регулярный аудит безопасности
---
## 20. 🎯 ПРАВИЛА КАЧЕСТВА КОДА
### 20.1 Стандарты разработки
- **ОБЯЗАТЕЛЬНО**: Покрытие тестами критической функциональности
- **ПРАВИЛО**: Следование принципам SOLID
- **ФУНКЦИЯ**: Автоматическое тестирование при развертывании
- **КАЧЕСТВО**: Минимальное покрытие тестами 80%
### 19.2 Документация
- **ОБЯЗАТЕЛЬНО**: Документирование всех API методов
- **ПРАВИЛО**: Комментарии к сложной бизнес-логике
- **ФУНКЦИЯ**: Автоматическая генерация документации
- **СТАНДАРТ**: Актуальная техническая документация
---
## 21. 📋 ПРИЛОЖЕНИЕ: ДОПОЛНИТЕЛЬНЫЕ ВОЗМОЖНОСТИ И ПЛАНЫ
### 🔄 Сложные сценарии (требуют дальнейшей проработки)
**ЗАМЕТКА**: Данные сценарии выявлены, но пока не учитываются в текущей системе. Требуют отдельного обсуждения:
#### **Сценарий 1: Из разных товаров → один продукт**
- **ПРИМЕР**: Товар "Футболка" + Товар "Джинсы" = Продукт "Комплект одежды"
- **ТРЕБУЕТ**: Разработки системы "составных продуктов"
- **СЛОЖНОСТЬ**: Управление несколькими parentId, распределение себестоимости
- **СТАТУС**: Требует технического решения
#### **Сценарий 2: Из одного товара → несколько продуктов**
- **ПРИМЕР**: Товар "Ткань 10 метров" → Продукт "Платье" (3м) + Продукт "Юбка" (2м) + остаток 5м
- **ТРЕБУЕТ**: Системы "деления товаров" и учета остатков
- **СЛОЖНОСТЬ**: Контроль использования материала, учет отходов
- **СТАТУС**: Требует проработки алгоритмов
### 🚀 Предложения по улучшению
#### **В разработке**:
- ✅ **Workflow для создания брака и продуктов** - детально описан
- ✅ **Разделение расходников на подтипы** - реализовано
- ✅ **Связи между товарами и производными типами** - реализовано
#### **Требует реализации**:
- **Автогенерация артикулов СФ с префиксами типов** - автоматическое создание уникальных номеров
- **Система комплектов товаров** - управление наборами товаров
- **Умные уведомления о низких остатках** - персонализированные алерты
- **Расширенные фильтры по типам предметов** - улучшенная навигация
- **Система прогнозирования спроса** - аналитика и планирование
### 📊 Полный список 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. Прочие товары
---
## 21. 🎯 ПРАВИЛА КАЧЕСТВА КОДА
### 21.1 GraphQL Rules
#### **Правила именования полей**
**ВАЖНО**: Имена полей в GraphQL запросах должны точно соответствовать схеме!
```typescript
// ✅ ПРАВИЛЬНО - соответствует схеме
export const GET_MY_COUNTERPARTIES = gql`
query GetMyCounterparties {
myCounterparties { // <- имя поля в схеме
id
name
type
}
}
`;
// Использование в компоненте
const allCounterparties = counterpartiesData?.myCounterparties || [];
```
```typescript
// ❌ НЕПРАВИЛЬНО - не соответствует схеме
const allCounterparties = counterpartiesData?.getMyCounterparties || []; // Ошибка!
```
#### **Правила отладки GraphQL**
**При проблемах с GraphQL запросами следовать чек-листу**:
1. **Проверить соответствие имен полей схеме**
2. **Добавить fetchPolicy: 'network-only' для обхода кеша**
3. **Логировать данные в браузере и сервере**
4. **Проверить авторизацию пользователя**
5. **Убедиться что резолвер вызывается**
#### **Обязательные поля для отладки**
```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);
```
### 21.2 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'
}
```
---
_Эта база знаний создана на основе анализа rules.md, rules1.md и description.md и является единым источником понимания структуры и логики проекта._
_Версия: 2.0_
_Дата создания: 2024_
_Статус: АКТИВНАЯ БАЗА ЗНАНИЙ_
1