Sfera/sfera
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ee72a9488bcb419fb9f93971c5735bcca39e4cec
sfera/rules-unified.md

1627 lines
83 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# ПРАВИЛА СИСТЕМЫ УПРАВЛЕНИЯ СКЛАДАМИ И ПОСТАВКАМИ - ПОЛНАЯ БАЗА ЗНАНИЙ v3.0
> ⚠️ **ВАЖНОЕ ПРИМЕЧАНИЕ**: Данный файл является объединенной полной базой знаний системы, созданной на основе rules.md, rules1.md и rules2.md. Все изменения должны согласовываться.
## 🔤 ТЕРМИНЫ СИСТЕМЫ
> Для людей → `В коде`
- ТОВАР → `PRODUCT`
- РАСХОДНИКИ → `CONSUMABLE`
- БРАК → `DEFECT` *(планируется)*
- ПРОДУКТ → `FINISHED_PRODUCT` *(планируется)*
- ПОСТАВЩИК → `WHOLESALE`
- СЕЛЛЕР → `SELLER`
- ФУЛФИЛМЕНТ → `FULFILLMENT`
- ЛОГИСТИКА → `LOGIST`
---
## 📑 ОГЛАВЛЕНИЕ
### 🏗️ **АРХИТЕКТУРА И ОСНОВЫ**
1. [🎯 Основные принципы системы](#1--основные-принципы-системы)
2. [📦 Типизация предметов](#2--типизация-предметов)
3. [🏢 Структура кабинетов](#3--структура-кабинетов)
4. [🔐 Система ролей и доступов](#4--система-ролей-и-доступов)
### 🚚 **WORKFLOW И ПРОЦЕССЫ**
5. [🚚 Workflow поставок](#5--workflow-поставок)
6. [🔄 Процесс создания продукта](#6--процесс-создания-продукта)
7. [📊 Система учета движения товаров](#7--система-учета-движения-товаров)
### 🏢 **КАБИНЕТЫ СИСТЕМЫ**
8. [🏠 Общие правила кабинетов](#8--общие-правила-кабинетов)
9. [🏠 Кабинет селлера (детальные правила)](#9--кабинет-селлера-детальные-правила)
10. [🏪 Кабинет поставщика](#10--кабинет-поставщика)
11. [🏭 Кабинет фулфилмента](#11--кабинет-фулфилмента)
12. [🚚 Кабинет логистики](#12--кабинет-логистики)
### 🤝 **СИСТЕМА ПАРТНЕРСТВА**
13. [🤝 Система партнерства и контрагентов](#13--система-партнерства-и-контрагентов)
### 🌐 **ИНТЕГРАЦИИ И ФУНКЦИИ**
14. [🌐 Интеграции с системой](#14--интеграции-с-системой)
15. [📊 Статистика и аналитика](#15--статистика-и-аналитика)
16. [📱 Правила UI/UX и интерфейса](#16--правила-uiux-и-интерфейса)
17. [⚠️ Критические запреты](#17--критические-запреты)
### 🛠️ **ТЕХНИЧЕСКИЕ ПРАВИЛА**
18. [🛠️ GraphQL и TypeScript правила](#18--graphql-и-typescript-правила)
19. [🔧 Архитектурные принципы](#19--архитектурные-принципы)
20. [🎯 Правила качества кода](#20--правила-качества-кода)
21. [🔍 Диагностика и решение проблем](#21--диагностика-и-решение-проблем)
### 📋 **ПРИЛОЖЕНИЯ**
22. [📋 Категории товаров и расходников](#22--категории-товаров-и-расходников)
23. [🎖️ Приоритеты разработки](#23--приоритеты-разработки)
### 🌐 **ИНТЕГРАЦИИ И ФУНКЦИИ**
14. [🌐 Интеграции с системой](#14--интеграции-с-системой)
15. [📊 Статистика и аналитика](#15--статистика-и-аналитика)
16. [📱 Правила UI/UX и интерфейса](#16--правила-uiux-и-интерфейса)
17. [⚠️ Критические запреты](#17--критические-запреты)
### 🛠️ **ТЕХНИЧЕСКИЕ ПРАВИЛА**
18. [🛠️ GraphQL и TypeScript правила](#18--graphql-и-typescript-правила)
19. [🔧 Архитектурные принципы](#19--архитектурные-принципы)
20. [🎯 Правила качества кода](#20--правила-качества-кода)
21. [🔍 Диагностика и решение проблем](#21--диагностика-и-решение-проблем)
### 📋 **ПРИЛОЖЕНИЯ**
22. [📋 Категории товаров и расходников](#22--категории-товаров-и-расходников)
23. [🎖️ Приоритеты разработки](#23--приоритеты-разработки)
---
## 🏷️ РЕЕСТР СУЩНОСТЕЙ СИСТЕМЫ
### 📦 **ОСНОВНЫЕ ПРЕДМЕТЫ**
| Сущность | Название в системе | Кабинет создания | Описание | Статус |
| ---------- | ---------------------------------- | ---------------- | ----------------------------------------------- | --------------- |
| Товар | `Product` (type: `PRODUCT`) | Поставщик | Базовый тип товара от поставщика | ✅ Реализовано |
| Расходники | `Product` (type: `CONSUMABLE`) | Поставщик | Материалы и вспомогательные товары | ✅ Реализовано |
| Брак | `Product` (type: `DEFECT`)* | Фулфилмент | Производная от товара с дефектами | 📋 Планируется |
| Продукт | `Product` (type: `FINISHED_PRODUCT`)* | Фулфилмент | Готовый к продаже товар (производная от товара) | 📋 Планируется |
> **\* Планируется**: Типы `DEFECT` и `FINISHED_PRODUCT` еще не добавлены в Prisma схему
### 🏢 **ОРГАНИЗАЦИИ И РОЛИ**
| Сущность | Название в системе | Основные функции | Статус |
| ---------- | ---------------------------------- | --------------------------------------- | -------------- |
| Поставщик | `Organization` (type: `WHOLESALE`) | Создание товаров, управление поставками | ✅ Реализовано |
| Селлер | `Organization` (type: `SELLER`) | Заказ товаров, управление поставками | ✅ Реализовано |
| Фулфилмент | `Organization` (type: `FULFILLMENT`) | Обработка товаров, управление складом | ✅ Реализовано |
| Логистика | `Organization` (type: `LOGIST`) | Управление доставками | ✅ Реализовано |
### 🤝 **СИСТЕМА ПАРТНЕРСТВА**
| Сущность | Название в системе | Описание | Статус |
| ------------ | ------------------ | ---------------------------------- | -------------- |
| Контрагент | `Counterparty` | Связь между организациями | ✅ Реализовано |
| Заявка | `CounterpartyRequest` | Запрос на сотрудничество | ✅ Реализовано |
---
## 1. 🎯 ОСНОВНЫЕ ПРИНЦИПЫ СИСТЕМЫ
### 1.1 Архитектура системы
**СТРУКТУРА СИСТЕМЫ ПО КАБИНЕТАМ:**
**🏢 КАБИНЕТ ПОСТАВЩИКА** - создает и управляет:
- **ТОВАР** (`PRODUCT`) - базовые товары от поставщика
- **РАСХОДНИКИ** (`CONSUMABLE`) - материалы и вспомогательные товары от поставщика
**🏭 КАБИНЕТ ФУЛФИЛМЕНТА** - принимает, обрабатывает и управляет всеми типами:
- **ТОВАР** (`PRODUCT`) - базовые товары от поставщиков (принятые на склад)
- **БРАК** (`DEFECT` - планируется) - производная от товара (товар с дефектами)
- **ПРОДУКТ** (`FINISHED_PRODUCT` - планируется) - готовый к продаже товар
- **РАСХОДНИКИ ФУЛФИЛМЕНТА** - операционные материалы фулфилмента
- **РАСХОДНИКИ СЕЛЛЕРОВ** - материалы для товаров селлеров
**🛍️ КАБИНЕТ СЕЛЛЕРА** - заказывает и управляет поставками:
- Создает заказы товаров и расходников
- Управляет поставками на фулфилмент и маркетплейсы
- Отслеживает статусы поставок
### 1.2 Основные принципы разработки
**КРИТИЧЕСКИ ВАЖНЫЕ ПРИНЦИПЫ:**
1. **Строгая типизация**: Каждый предмет имеет один из типов: ТОВАР (`PRODUCT`), РАСХОДНИКИ (`CONSUMABLE`), БРАК и ПРОДУКТ (планируется)
2. **Партнерская система**: Все связи между организациями через модель `Counterparty`
3. **Workflow статусов**: Строгая последовательность статусов поставок
4. **Безопасность доступа**: Контроль доступа на уровне GraphQL резолверов
5. **Единый источник истины**: Централизованное управление данными
---
## 2. 📦 ТИПИЗАЦИЯ ПРЕДМЕТОВ
### 2.1 Два реализованных и два планируемых типа предметов
#### **1. ТОВАР** (`PRODUCT` - базовый тип)
- **СОЗДАЕТСЯ**: Поставщиком
- **СТАТУС**: Может быть активным/неактивным
- **ЗАКАЗ**: Доступен для заказа всеми типами организаций
- **ТРАНСФОРМАЦИЯ**: Может стать ПРОДУКТОМ или БРАКОМ
- **ЦЕНА**: Обязательна, больше 0
#### **2. РАСХОДНИКИ** (`CONSUMABLE` - базовый тип)
- **СОЗДАЕТСЯ**: Поставщиком как универсальный тип
- **КЛАССИФИКАЦИЯ ПРИ ЗАКАЗЕ**:
- Фулфилмент заказывает → "Расходники фулфилмента"
- Селлер заказывает → "Расходники селлеров"
- **ДОСТУП**: Видны всем типам организаций в маркете
#### **3. БРАК** (`DEFECT` - планируется, производная от товара)
- **БУДЕТ СОЗДАВАТЬСЯ**: Фулфилментом на основе существующего ТОВАРА при обнаружении дефектов
- **МОМЕНТ СОЗДАНИЯ**: В процессе "Создание продукта" / "В работе" после подсчета факта
- **СВЯЗЬ**: Обязательная связь с родительским товаром (parentId)
- **ЗАКАЗ**: ЗАПРЕЩЕН заказ брака
- **СТАТУС**: Всегда неактивен для заказа
- **ЦЕНА**: Для селлера - себестоимость дефектного товара, для фулфилмента - 0
- **WORKFLOW**: Особый процесс списания и утилизации
- **УЧЕТ**: Отдельный учет в статистике потерь
- **ОТОБРАЖЕНИЕ**: Виден только для учета потерь
- **⚠️ СТАТУС РАЗРАБОТКИ**: Тип `DEFECT` еще не добавлен в схему БД
#### **4. ПРОДУКТ** (`FINISHED_PRODUCT` - планируется, производная от товара)
- **БУДЕТ СОЗДАВАТЬСЯ**: Фулфилментом на основе ТОВАРА по заказу селлера
- **ИНИЦИАТОР**: Селлер создает заказ с рецептурой, фулфилмент исполняет
- **СВЯЗЬ**: Обязательная связь с родительским товаром (parentId)
- **РЕЦЕПТУРА**: Задается селлером при создании заказа (Товар + Услуга + Расходники)
- **СТАТУСЫ**: "в работе" → "готов к отправке"
- **ЗАКАЗ**: Доступен только в статусе "готов к отправке"
- **⚠️ СТАТУС РАЗРАБОТКИ**: Тип `FINISHED_PRODUCT` еще не добавлен в схему БД
### 2.2 Обязательные поля карточки
**КРИТИЧЕСКИ ВАЖНО**: Название, артикул, цена > 0, тип предмета
**ИСКЛЮЧЕНИЕ ДЛЯ БРАКА**: Цена может быть 0 для фулфилмента (себестоимость для селлера)
**ОБЯЗАТЕЛЬНО**: Количество (может быть 0 для предзаказа)
**ДЛЯ ПРОИЗВОДНЫХ ТИПОВ**: Обязательная связь с родительским предметом
---
## 3. 🏢 СТРУКТУРА КАБИНЕТОВ
### 3.1 Общие принципы кабинетов
**КАЖДЫЙ КАБИНЕТ ИМЕЕТ:**
1. **Главная страница** (`/dashboard`) - общая информация и статистика
2. **Экономика** (`/economics`) - финансовая аналитика
3. **Универсальные разделы**:
- Маркет (`/market`) - просмотр и заказ товаров
- Партнеры (`/partners`) - управление контрагентами
- Мессенджер (`/messenger`) - связь между организациями
- Настройки (`/settings`) - профиль и API ключи
### 3.2 Специфические разделы по типам организаций
**🏪 ПОСТАВЩИК (`WHOLESALE`):**
- Склад (`/warehouse`) - управление товарами и расходниками
- Поставки (`/supplies`) - обработка заказов от селлеров
**🛍️ СЕЛЛЕР (`SELLER`):**
- Мои поставки (`/supplies`) - управление заказами товаров
- WB Интеграция (`/wb-integration`) - связь с Wildberries
**🏭 ФУЛФИЛМЕНТ (`FULFILLMENT`):**
- Склад фулфилмента (`/fulfillment-warehouse`) - управление всеми типами товаров
- Поставки фулфилмента (`/fulfillment-supplies`) - обработка поставок
- Услуги (`/services`) - управление услугами, логистикой, расходниками
- Сотрудники (`/employees`) - управление персоналом
- Статистика фулфилмента (`/fulfillment-statistics`) - детальная аналитика
**🚚 ЛОГИСТИКА (`LOGIST`):**
- Заявки (`/logistics-requests`) - управление заявками на доставку
- Маршруты (`/routes`) - планирование маршрутов
---
## 4. 🔐 СИСТЕМА РОЛЕЙ И ДОСТУПОВ
### 4.1 Контроль доступа к разделам
**ПРОВЕРКА НА УРОВНЕ КОМПОНЕНТОВ:**
```typescript
{user?.organization?.type === "FULFILLMENT" && (
// Компоненты доступны только фулфилменту
)}
```
**СПЕЦИАЛЬНАЯ ЛОГИКА РОУТИНГА:**
```typescript
const handleSuppliesClick = () => {
switch (user?.organization?.type) {
case "FULFILLMENT":
router.push("/fulfillment-supplies");
break;
case "SELLER":
router.push("/supplies");
break;
// ... другие типы
}
};
```
### 4.2 GraphQL проверки доступа
**В Apollo Client запросах:**
```typescript
const { data } = useQuery(GET_MY_SERVICES, {
skip: user?.organization?.type !== "FULFILLMENT",
});
```
**В GraphQL резолверах:**
```typescript
if (currentUser.organization.type !== "FULFILLMENT") {
throw new GraphQLError("Доступно только для фулфилмент центров");
}
```
### 4.3 Контроль доступа к заказам
- **Создатель заказа** - полный доступ к своим заказам
- **Поставщик** - доступ к заказам, где он является поставщиком
- **Фулфилмент-центр** - доступ к заказам, направленным в его центр
- **Логистическая компания** - доступ к заказам для доставки
---
## 5. 🚚 WORKFLOW ПОСТАВОК
### 5.1 Детализированная система статусов
**Статусы SupplyOrder (Заказ поставки):**
1. **PENDING** - Ожидает подтверждения поставщиком
2. **SUPPLIER_APPROVED** - Одобрено поставщиком
3. **CONFIRMED** - Подтвержден (готов к обработке)
4. **LOGISTICS_CONFIRMED** - Подтверждено логистикой
5. **SHIPPED** - Отгружено поставщиком
6. **IN_TRANSIT** - В пути (логистика доставляет)
7. **DELIVERED** - Доставлен на фулфилмент
8. **CANCELLED** - Отменен
### 5.2 Пошаговый процесс поставки
**ЭТАП 1: Создание заказа**
1. Селлер заказывает товар/расходники у поставщика
2. Система создает SupplyOrder со статусом `PENDING`
3. Автоматическое уведомление поставщику
**ЭТАП 2: Обработка поставщиком**
4. Поставщик получает оповещение
5. Поставщик нажимает "Одобрить"
6. Статус меняется на `SUPPLIER_APPROVED`
**ЭТАП 3: Передача в фулфилмент**
7. Поставка отображается в кабинете фулфилмента
8. Фулфилмент выбирает ответственного и логистику
9. Статус меняется на `CONFIRMED`
**ЭТАП 4: Логистическое подтверждение**
10. Логистика подтверждает доставку
11. Статус меняется на `LOGISTICS_CONFIRMED`
**ЭТАП 5: Отгрузка**
12. Поставщик отгружает товар
13. Статус меняется на `SHIPPED`, затем `IN_TRANSIT`
**ЭТАП 6: Доставка и приемка**
14. Логистика доставляет на фулфилмент
15. Фулфилмент принимает товар
16. Статус меняется на `DELIVERED`
### 5.3 Система уведомлений
**Обязательные уведомления:**
- Поставщику: о новом заказе
- Фулфилменту: о подтвержденной поставке
- Логистике: о назначении на заявку
- Селлеру: об изменении каждого статуса
---
## 6. 🔄 ПРОЦЕСС СОЗДАНИЯ ПРОДУКТА
### 6.1 Workflow создания продукта
**ЭТАПЫ ПРОЦЕССА:**
1. **ПОСТУПЛЕНИЕ**: Товар приходит на склад фулфилмента (статус "на складе")
2. **СОРТИРОВКА**: Перебор товара, отсеивание брака
3. **ПОДГОТОВКА К РАБОТЕ**: Менеджер задает параметры работы
4. **ОБРАБОТКА**: Превращение товара в продукт по "рецептуре" селлера
5. **ЗАВЕРШЕНИЕ**: Готовый продукт (статус "готов к отправке")
### 6.2 Управление процессом
**РАЗДЕЛ "СОЗДАНИЕ ПРОДУКТА":**
- **НОВЫЕ**: Поставки после нажатия "принято", ожидающие назначения
- **В РАБОТЕ**: Поставки в процессе обработки
- **ВЫПОЛНЕНО**: Завершенные поставки с готовыми продуктами
**ДЕЙСТВИЯ МЕНЕДЖЕРА В "НОВЫЕ":**
- **ДЕДЛАЙН**: Указание срока выполнения работы
- **ОТВЕТСТВЕННЫЙ**: Назначение исполнителя
- **МЕСТО ХРАНЕНИЯ**: Указание локации для готовых продуктов (опционально)
- **ЗАПУСК**: Нажатие кнопки "В работе"
### 6.3 Рецептура продукта
**СЕЛЛЕР УКАЗЫВАЕТ В ПОСТАВКЕ:**
- **БАЗОВЫЙ ТОВАР**: Исходный материал (например, футболка)
- **УСЛУГА ФУЛФИЛМЕНТА**: Из каталога услуг (например, "погладить")
- **РАСХОДНИК СЕЛЛЕРА**: Материалы селлера (например, фирменный пакет)
- **РАСХОДНИК ФУЛФИЛМЕНТА**: Материалы фулфилмента (например, короб + маркировка)
**РЕЗУЛЬТАТ**: ПРОДУКТ = Товар + Услуга + Расходники
### 6.4 Учет план/факт в процессе работы
**ПЛАН**: Количество товара из поставки селлера
**ФАКТ**: Реальное количество после сортировки
**ФИКСАЦИЯ БРАКА:**
- **КОГДА**: В процессе работы (вкладка "В работе")
- **КТО**: Ответственный исполнитель
- **ДЕТАЛИЗАЦИЯ**: По каждому предмету (размер/объем)
- **ОБНОВЛЕНИЕ**: Можно вносить изменения до нажатия "Выполнено"
**ВЛИЯНИЕ НА СТАТИСТИКУ:**
- При принятии поставки: +План в статистику
- При выявлении факта: корректировка на реальные данные
- **ФОРМУЛА**: Факт = Брак + Хороший товар
- **ЛОГИКА**: Фактическое количество = сумма всех пересчитанных предметов
---
## 7. 📊 СИСТЕМА УЧЕТА ДВИЖЕНИЯ ТОВАРОВ
### 7.1 Принципы учета в фулфилменте
**ОСНОВНЫЕ ПРИНЦИПЫ:**
- **ПРИХОД**: Товары поступают через принятые поставки (из состояния "в пути" → "на складе")
- **ОБРАБОТКА**: Товары переходят в статус "в работе" для создания продуктов
- **РАСХОД**: Товары убывают при отгрузке, списании, возврате, превращении в продукты
- **УЧЁТ**: Ведется учет прихода и расхода для каждого типа предметов
- **ВИЗУАЛИЗАЦИЯ**: Движение отображается в дополнительных значениях
### 7.2 Дополнительные и основные значения
**ДОПОЛНИТЕЛЬНЫЕ ЗНАЧЕНИЯ (показатели движения):**
- **ПРИБЫЛО**: Количество предметов, поступивших на склад
- **УБЫЛО**: Количество предметов, списанных со склада
- **ВЛИЯНИЕ**: От этих значений зависят основные значения (общее количество)
**ОСНОВНЫЕ ЗНАЧЕНИЯ (текущие остатки):**
- **ОПРЕДЕЛЕНИЕ**: Итоговое количество предметов на складе
- **РАСЧЁТ**: Основные значения = Предыдущие остатки + Прибыло - Убыло
- **ОТОБРАЖЕНИЕ**: Показываются в каждом модуле статистики
- **РАЗДЕЛЕНИЕ ТОВАРОВ**:
- Товары "на складе" - готовы к обработке
- Товары "в обработке" - находятся в процессе создания продукта
---
## 8. 🏠 ОБЩИЕ ПРАВИЛА КАБИНЕТОВ
### 8.1 Универсальная структура кабинетов
**ВСЕ ТИПЫ КАБИНЕТОВ** включают следующие обязательные разделы:
#### 8.1.1 Страница "Главная"
**СТАТУС**: Реализовано
**ДОСТУП**: Через навигацию в sidebar для всех типов кабинетов
**СОДЕРЖАНИЕ**: Универсальная страница с типо-зависимыми компонентами
**ПРАВИЛА**:
- **ОБЯЗАТЕЛЬНО**: Каждый тип кабинета должен иметь страницу "Главная"
- **НАВИГАЦИЯ**: Доступ через кнопку в sidebar (первая в списке)
- **УНИВЕРСАЛЬНОСТЬ**: Одинаковая структура навигации для всех кабинетов
- **РОУТ**: `/home` с универсальным компонентом HomePageWrapper
- **КОМПОНЕНТЫ**: 4 типо-зависимых компонента: SellerHomePage, FulfillmentHomePage, WholesaleHomePage, LogistHomePage
#### 8.1.2 Раздел "Экономика"
**СТАТУС**: Реализовано в системе
**РАСПОЛОЖЕНИЕ**: Перед настройками в каждом кабинете
**СОДЕРЖАНИЕ**: Пустые разделы-заглушки с пометкой "будет добавлен позже"
**ПРАВИЛА**:
- **ОБЯЗАТЕЛЬНО**: Каждый кабинет имеет раздел "Экономика"
- **РОУТ**: `/economics` с универсальным компонентом EconomicsPageWrapper
- **КОМПОНЕНТЫ**: 4 типо-зависимых компонента экономики: SellerEconomicsPage, FulfillmentEconomicsPage, WholesaleEconomicsPage, LogistEconomicsPage
- **КНОПКА**: "Экономика" в sidebar навигации перед настройками
- **БЕЗОПАСНОСТЬ**: Проверки доступа и безопасности в экономических компонентах
#### 8.1.3 Общие разделы для всех кабинетов
**УНИВЕРСАЛЬНЫЕ РАЗДЕЛЫ** (доступны всем типам):
- 🏠 **Главная** - основная страница кабинета (реализовано)
- 🛒 **Маркет** - просмотр и заказ товаров
- 🤝 **Партнеры** - управление контрагентами
- 💬 **Мессенджер** - внутренняя связь
- 💰 **Экономика** - финансовая аналитика (реализовано)
- ⚙️ **Настройки** - профиль и конфигурация
**СПЕЦИАЛИЗИРОВАННЫЕ РАЗДЕЛЫ** (зависят от типа кабинета):
- Определяются в соответствующих разделах каждого кабинета
### 8.2 Правила sidebar навигации
#### 8.2.1 Структура навигации
**ОБЩИЙ ПРИНЦИП**:
- Условное отображение: `{user?.organization?.type === "TYPE" && (...)}`
- Адаптивность: сворачиваемый sidebar с `getSidebarMargin()`
- Состояния активности: подсветка текущего раздела
**ПОРЯДОК РАЗДЕЛОВ В SIDEBAR**:
1. 🏠 **Главная** (реализовано для всех)
2. **Специализированные разделы** (зависят от типа кабинета)
3. 🛒 **Маркет** (универсальный)
4. 🤝 **Партнеры** (универсальный)
5. 💬 **Мессенджер** (универсальный)
6. 💰 **Экономика** (универсальный, реализовано)
7. ⚙️ **Настройки** (универсальный)
8. **Выход** (универсальный)
#### 8.2.2 Типо-зависимая логика
**АДАПТИВНЫЙ РОУТИНГ**:
```typescript
// Пример: кнопка "Поставки" ведет на разные страницы
const handleSuppliesClick = () => {
switch (user?.organization?.type) {
case "FULFILLMENT":
router.push("/fulfillment-supplies");
break;
case "SELLER":
router.push("/supplies");
break;
case "WHOLESALE":
router.push("/supplies");
break;
case "LOGIST":
router.push("/logistics-orders");
break;
}
};
```
---
## 9. 🏠 КАБИНЕТ СЕЛЛЕРА (ДЕТАЛЬНЫЕ ПРАВИЛА)
### 9.1 Структура раздела "Мои поставки"
#### **🏢 ПОСТАВКИ НА ФУЛФИЛМЕНТ**:
- **Товар** - поставка товаров для создания продуктов
- **Карточки** - поставка через WB API с рецептурой (результат: WildberriesSupply)
- **Поставщики** - заказ товаров у поставщиков с рецептурой (результат: SupplyOrder)
- **Расходники селлера** - поставка материалов для товаров селлера
#### **🛒 ПОСТАВКИ НА МАРКЕТПЛЕЙСЫ** _(планируется)_:
- **Wildberries** - прямые поставки на WB
- **Ozon** - прямые поставки на Ozon
### 9.2 Правила кнопки "Создать поставку" в разделе "Мои поставки"
#### **9.2.1 Общие принципы**
- **КОНТЕКСТНОСТЬ**: Кнопка создания появляется только в активном табе
- **РАСПОЛОЖЕНИЕ**: Правая часть строки таба, на том же уровне что и название
- **СТИЛИСТИКА**: В том же стиле что и сами табы (соответствует уровню иерархии)
- **ФУНКЦИОНАЛЬНОСТЬ**: Кнопка ведет на страницу создания поставки соответствующего типа
#### **9.2.2 Размещение кнопок по табам**
**УРОВЕНЬ 2 (Подтабы фулфилмента):**
- **📦 Товар → Карточки**: Кнопка "Создать поставку" → `/supplies/create-cards`
- **📦 Товар → Поставщики**: Кнопка "Создать поставку" → `/supplies/create-suppliers`
- **🔧 Расходники селлера**: Кнопка "Создать поставку" → `/supplies/create-consumables`
**УРОВЕНЬ 2 (Подтабы маркетплейсов):**
- **🟣 Wildberries**: Кнопка "Создать поставку" → `/supplies/create-wildberries`
- **🔵 Ozon**: Кнопка "Создать поставку" → `/supplies/create-ozon`
#### **9.2.3 Стили кнопок**
**ДЛЯ УРОВНЯ 2 (h-9):**
```css
/* Размер и отступы */
h-9 px-3 py-1 ml-auto
/* Фон и границы */
bg-white/8 border border-white/20 hover:bg-white/12
/* Текст и иконки */
text-xs font-medium text-white/80 hover:text-white
/* Скругления */
rounded-lg
/* Переходы */
transition-all duration-150
```
**ДЛЯ УРОВНЯ 3 (h-8):**
```css
/* Размер и отступы */
h-8 px-2 py-1 ml-auto
/* Фон и границы */
bg-white/5 border border-white/15 hover:bg-white/8
/* Текст и иконки */
text-xs font-normal text-white/60 hover:text-white/80
/* Скругления */
rounded-md
/* Переходы */
transition-all duration-150
```
#### **9.2.4 Поведение кнопок**
- **ВИДИМОСТЬ**: Кнопка показывается только в активном табе
- **ИКОНКА**: `Plus` размером `h-3 w-3` слева от текста
- **ТЕКСТ**: "Создать" на мобильных, "Создать поставку" на десктопах
- **АДАПТИВНОСТЬ**: Скрытие текста на маленьких экранах (`hidden sm:inline`)
#### **9.2.5 Удаление старой кнопки**
- **УБРАТЬ**: Текущий dropdown "Создать поставку" из верхней части
- **ПРИЧИНА**: Заменяется контекстными кнопками в табах
- **СОХРАНИТЬ**: Стили и логику навигации, но адаптировать под новые роуты
### 9.3 Структура страницы "Мои поставки" - Трёхблочная архитектура
#### **9.3.1 Обязательная структура страницы**
**ПРИНЦИП**: Страница состоит из трёх визуально разделённых блоков
```
┌─────────────────────────────────────────┐
│ 1. БЛОК ТАБОВ (навигация) │
│ - Фиксированная высота │
│ - Glass-эффект │
│ - Иерархическая структура │
├─────────────────────────────────────────┤
│ 2. БЛОК СТАТИСТИКИ (метрики) │
│ - Контекстные данные │
│ - 4 карточки в ряд (desktop) │
│ - Динамическое обновление │
├─────────────────────────────────────────┤
│ 3. ОСНОВНОЙ БЛОК (контент) │
│ - Сохраняет весь функционал │
│ - Таблицы, фильтры, действия │
│ - Высота до низа sidebar │
└─────────────────────────────────────────┘
```
#### **9.3.2 Блок статистики - контекстные метрики**
**ПРАВИЛО**: Статистика меняется в зависимости от выбранных табов
**Для путей "Фулфилмент → Товар → Карточки/Поставщики":**
- Всего поставок
- Активных поставок
- Сумма активных поставок
- В пути
**Для пути "Фулфилмент → Расходники селлера":**
- Всего поставок
- Активных поставок
- Видов расходников
- Критические остатки
**Для путей "Маркетплейсы → Wildberries/Ozon":**
- Поставок на маркетплейс
- Товаров отправлено
- Возвраты за неделю
- Эффективность поставок
#### **9.3.3 Высота основного блока**
**ФОРМУЛА РАСЧЕТА**:
```css
height: calc(100vh - headerHeight - tabsHeight - statsHeight - margins)
```
**ПРАВИЛО ВЫРАВНИВАНИЯ**:
- Нижняя граница основного блока должна быть на одном уровне с нижней границей sidebar
- При изменении размера окна высота пересчитывается
- Внутренний скролл: `overflow-y-auto`
#### **9.3.4 Сохранение функционала**
**КРИТИЧЕСКИ ВАЖНО**: При добавлении блока статистики весь существующий функционал сохраняется:
- Таблицы с данными поставок
- Фильтры и сортировка
- Кнопки действий
- Детализация при клике
- Пагинация
- Поиск
**ЗАПРЕЩЕНО**:
- Удалять существующие компоненты
- Изменять логику работы таблиц
- Нарушать существующие API вызовы
### 9.4 Табы "Карточки" и "Поставщики" - объединённая логика
#### **9.4.1 Принцип единого типа предмета**
**КЛЮЧЕВОЕ ПРАВИЛО**: Табы "Карточки" и "Поставщики" - это два способа создания поставок одного типа предмета (ТОВАР)
**СПОСОБЫ СОЗДАНИЯ**:
- **Карточки** - импорт товаров через WB API с автоматическим созданием поставки
- **Поставщики** - прямой заказ товаров у поставщика с указанием рецептуры
**РЕЗУЛЬТАТ**: Оба способа создают `SupplyOrder` с товарами типа `PRODUCT`
#### **9.4.2 Общая статистика**
**ПРАВИЛО**: Блок статистики показывает ОДИНАКОВЫЕ данные для обоих табов
**МЕТРИКИ ДЛЯ ТАБОВ "КАРТОЧКИ" И "ПОСТАВЩИКИ"**:
- Всего поставок товаров (из всех источников)
- Активных поставок товаров (в работе)
- Сумма активных поставок товаров
- Товаров в пути (все способы доставки)
**ЗАПРЕЩЕНО**: Разделять статистику по способу создания
#### **9.4.3 Общий основной блок**
**СОДЕРЖИМОЕ**: Единая таблица всех поставок товаров
**ИСТОЧНИКИ ДАННЫХ**:
- Поставки, созданные через импорт карточек WB
- Поставки, созданные через заказ у поставщиков
- Все промежуточные и завершённые поставки
**РАЗЛИЧИЯ ТАБОВ**:
- Только кнопки создания ведут на разные страницы
- Таб "Карточки": `/supplies/create-cards`
- Таб "Поставщики": `/supplies/create-suppliers`
### 9.5 Создание поставки расходников селлера
#### **Структура страницы**:
**БЛОК 1: ПОСТАВЩИКИ** _(обязательный, верхняя часть)_:
- Карточки поставщиков из раздела "Партнеры"
- Горизонтальный скролл при превышении ширины
- Выбор только одного поставщика одновременно
**БЛОК 2: РАСХОДНИКИ** _(зависимый, центральная часть)_:
- Активен только после выбора поставщика
- Сортировка: цена, название, категория
- Фильтры: категория, ценовой диапазон
- Карточка с полем ввода количества и кнопками +/-
**БЛОК 3: КОРЗИНА** _(правая часть)_:
- **РАСПОЛОЖЕНИЕ**: Правая часть экрана
- **СОДЕРЖАНИЕ**:
- Счетчик видов расходников
- Детализация по каждому расходнику (название, количество, цена, сумма)
- Общая сумма всех расходников
- **УПРАВЛЕНИЕ**:
- Изменение количества (с валидацией остатков)
- Удаление позиций
- **ОБЯЗАТЕЛЬНЫЕ ПОЛЯ**:
- Выбор фулфилмент-центра (из партнеров)
- Дата поставки (не прошедшая, по умолчанию - текущая)
### 9.6 Многоуровневая таблица поставок
#### **ПЕРВЫЙ УРОВЕНЬ** _(основной список)_:
- **СОРТИРОВКА**: Номер поставки от большего к меньшему
- **ОБЯЗАТЕЛЬНЫЕ КОЛОНКИ**:
- Порядковый номер поставки
- Количество видов расходников
- Стоимость всей поставки
- Количество категорий
- Статус поставки
#### **ВТОРОЙ УРОВЕНЬ** _(детализация по клику)_:
- **АКТИВАЦИЯ**: По клику на строку первого уровня
- **СОДЕРЖАНИЕ**:
- Название расходника
- Количество
- Цена
- Категория
- Поставщик
- **ОГРАНИЧЕНИЯ**: Только просмотр, редактирование запрещено
---
## 10. 🏪 КАБИНЕТ ПОСТАВЩИКА
### 10.1 Основные возможности
**СОЗДАНИЕ КАРТОЧЕК**:
- **ТОВАР** - базовые товары поставщика
- **РАСХОДНИКИ** - материалы и вспомогательные товары
### 10.2 Обязательные поля карточки
**Базовые параметры**:
- Фото (система загрузки и управления изображениями)
- Название
- Автоматическая генерация артикула СФ
- Описание
- Количество предметов в единицах
- Количество комплектов (если применимо)
- Категория (28 предустановленных + специализированные для расходников)
- Бренд, Цвет, Размер/объем, Вес, Габариты, Материал
- Цена за единицу и за комплект
- Заказано, В пути, Остаток, Продано
### 10.3 Отображение информации в карточках
**Каждая карточка содержит**:
- Основное изображение
- Название и артикул СФ
- Цена за единицу/комплект
- Категория и статус активности
- Данные о движении: остаток, заказано, в пути, продано
- Индикаторы низких остатков
### 10.4 Статистика поставщика
**Блок статистики включает**:
- **ТОВАРЫ**: Общая статистика товаров поставщика
- **РАСХОДНИКИ**: Материалы и вспомогательные товары
- Классифицируются при заказе в зависимости от заказчика
- Общая статистика по всем расходникам
---
## 11. 🏭 КАБИНЕТ ФУЛФИЛМЕНТА
### 11.1 Структура раздела склад фулфилмента
#### **Модули в обязательной последовательности**:
1. **📦 ПРОДУКТ** - готовые к продаже товары
2. **🛒 ТОВАР** - базовые товары от поставщиков
- Товары "на складе" - готовы к обработке
- Товары "в обработке" - в процессе создания продукта
3. **❌ БРАК** - товары с дефектами
4. **↩️ ВОЗВРАТЫ С ПВЗ** - возвращенные товары
5. **🎯 РАСХОДНИКИ СЕЛЛЕРОВ** - материалы для селлеров
6. **⚙️ РАСХОДНИКИ ФУЛФИЛМЕНТ** - операционные материалы
- **КЛИКАБЕЛЬНЫЙ МОДУЛЬ** - содержит полноценный раздел учёта
### 11.2 Движение товаров в фулфилменте
#### **Поступление товаров**:
- **ПОСТАВКИ**: От поставщиков через систему заказов
- **ВОЗВРАТЫ**: Товары, возвращенные с ПВЗ
- **ПЕРЕМЕЩЕНИЯ**: Между складами и магазинами
#### **Расход товаров**:
- **ОТГРУЗКА**: Товары отправлены селлерам
- **СПИСАНИЕ**: Брак, утрата, утилизация
- **ВОЗВРАТ**: Возврат поставщику
- **ИСПОЛЬЗОВАНИЕ**: Расходники для операций
### 11.3 Модуль "Расходники фулфилмента"
**ОСОБЕННОСТИ**:
- **ИНТЕРАКТИВНОСТЬ**: Кликабельный элемент в статистике
- **ФУНКЦИОНАЛЬНОСТЬ**: Полноценный раздел учёта
- **СОДЕРЖАНИЕ**: Управление расходниками фулфилмента
### 11.4 Блок детализации по магазинам
**НАЗНАЧЕНИЕ**: Распределение товаров по торговым точкам/магазинам
**ФУНКЦИИ**:
- **ОСТАТКИ ПО МАГАЗИНАМ**: Отображение количества товаров в каждом магазине
- **УПРАВЛЕНИЕ РАСПРЕДЕЛЕНИЕМ**: Перемещение товаров между точками
- **КОНТРОЛЬ ДВИЖЕНИЯ**: Отслеживание перемещений между складами и магазинами
- **АНАЛИТИКА**: Сравнение эффективности разных точек
- **ПЛАНИРОВАНИЕ**: Оптимизация распределения товаров
---
## 12. 🚚 КАБИНЕТ ЛОГИСТИКИ
### 12.1 Основные функции логистики
**РОЛЬ В СИСТЕМЕ**: Управление доставками и транспортировкой
**ОСНОВНЫЕ ФУНКЦИИ**:
- **ПОДТВЕРЖДЕНИЕ ДОСТАВКИ**: Подтверждение возможности доставки поставок
- **ТРАНСПОРТИРОВКА**: Организация и выполнение доставки товаров
- **КОНТРОЛЬ МАРШРУТОВ**: Управление логистическими маршрутами
- **ОТСЛЕЖИВАНИЕ**: Мониторинг грузов в пути
### 12.2 Workflow для логистики
#### **ЭТАП 1: Получение заявки**
1. Логистика получает уведомление о новой поставке
2. Заявка появляется в разделе "Заявки" кабинета логистики
3. Логист изучает детали поставки (объем, вес, маршрут)
#### **ЭТАП 2: Подтверждение доставки**
4. Логист нажимает кнопку "Одобрить"
5. Статус поставки меняется на `LOGISTICS_CONFIRMED`
6. Уведомления отправляются всем участникам
#### **ЭТАП 3: Забор товара**
7. Логист приезжает к поставщику за товаром
8. Поставщик отгружает товар логисту
9. Поставщик отмечает "Отправлено"
10. Статус меняется на `SHIPPED`, затем `IN_TRANSIT`
#### **ЭТАП 4: Доставка**
11. Логистика доставляет товар на фулфилмент-центр
12. В кабинете логистики нажимают "Доставлено"
13. Фулфилмент принимает товар и отмечает "Принято"
### 12.3 Система тарификации
**ПАРАМЕТРЫ ТАРИФИКАЦИИ**:
- **Тариф до 1м³** - базовая стоимость для малых грузов
- **Тариф свыше 1м³** - стоимость для крупных грузов
- **Маршруты доставки** - от точки отправления до точки назначения
- **Описание услуг** - дополнительные условия доставки
**РАСЧЕТ СТОИМОСТИ**:
- Автоматический расчет стоимости доставки по объему груза
- Отображение примерной стоимости при создании заказа
- Учет специфики маршрута и условий доставки
### 12.4 Управление заявками
**РАЗДЕЛЫ КАБИНЕТА ЛОГИСТИКИ**:
- **НОВЫЕ ЗАЯВКИ** - поступившие заявки на доставку
- **В РАБОТЕ** - принятые к исполнению заявки
- **ВЫПОЛНЕННЫЕ** - завершенные доставки
- **ОТКЛОНЕННЫЕ** - заявки, которые не могут быть выполнены
**ИНФОРМАЦИЯ О ЗАЯВКЕ**:
- Детали груза (объем, вес, габариты)
- Маршрут доставки (откуда - куда)
- Срочность доставки
- Особые требования к транспортировке
- Контактная информация участников
### 12.5 Правила логистики
**ОБЯЗАТЕЛЬНО**:
- Своевременное подтверждение заявок
- Соблюдение сроков доставки
- Бережная транспортировка товаров
- Уведомление о статусе доставки
**ЗАПРЕЩЕНО**:
- Принятие заявок без подтверждения возможности выполнения
- Нарушение сроков доставки без уведомления
- Повреждение товаров при транспортировке
---
## 13. 🤝 СИСТЕМА ПАРТНЕРСТВА И КОНТРАГЕНТОВ
### 13.1 Основы системы партнерства
**ПРИНЦИП РАБОТЫ**:
- Все типы кабинетов могут создавать партнерские отношения
- Партнерство реализовано через таблицы `Counterparty` и `CounterpartyRequest`
- Двустороннее партнерство: каждая организация видит другую в разделе "Партнеры"
**ТИПЫ ОРГАНИЗАЦИЙ-ПАРТНЕРОВ**:
- `WHOLESALE` - Поставщики товаров и расходников
- `FULFILLMENT` - Фулфилмент-центры
- `LOGIST` - Логистические компании
- `SELLER` - Селлеры (торговые организации)
### 13.2 Способы создания партнерства
#### **СПОСОБ 1: Через заказ в маркете (автоматическое партнерство)**
**WORKFLOW**:
1. Поставщик создает товар → товар попадает в глобальный маркет
2. Селлер/Фулфилмент находит товар в маркете
3. Создает заказ (`SupplyOrder`) → статус `PENDING`
4. Поставщик получает уведомление в разделе "Заявки"
5. Поставщик одобряет заявку → статус `SUPPLIER_APPROVED`
6. **Автоматически создается двустороннее партнерство**:
- Запись в `Counterparty` для заказчика (`organizationId` → `counterpartyId`)
- Обратная запись в `Counterparty` для поставщика
7. Обе организации видят друг друга в разделе "Партнеры"
#### **СПОСОБ 2: Через раздел "Партнеры" (заявочная система)**
**WORKFLOW**:
1. Любая организация идет в раздел "Партнеры"
2. Использует поиск для нахождения нужной организации
3. Отправляет заявку на партнерство → создается `CounterpartyRequest`:
- `senderId` - отправитель заявки
- `receiverId` - получатель заявки
- `status: PENDING`
- `message` - опциональное сообщение
4. Получатель видит заявку в разделе "Партнеры" → "Входящие заявки"
5. Получатель принимает заявку → статус меняется на `ACCEPTED`
6. **Автоматически создается двустороннее партнерство** (аналогично способу 1)
**СТАТУСЫ ЗАЯВОК**:
- `PENDING` - Ожидает рассмотрения
- `ACCEPTED` - Принята (партнерство создано)
- `REJECTED` - Отклонена
- `CANCELLED` - Отменена отправителем
### 13.3 Использование партнерства в системе
#### **В форме создания поставки товаров через поставщиков**
**ПРАВИЛО ОТОБРАЖЕНИЯ ПОСТАВЩИКОВ**:
- Показываются только партнеры с типом `WHOLESALE`
- Источник: таблица `Counterparty` where `counterparty.type === "WHOLESALE"`
- Фильтрация по `organizationId` текущего пользователя
**ЛОГИКА РАБОТЫ**:
1. Пользователь выбирает поставщика из dropdown партнеров-поставщиков
2. Загружается каталог товаров поставщика из `Product` таблицы
3. Товары фильтруются по `organizationId = поставщик.id`
4. Пользователь может добавлять товары в корзину и создавать заказ
#### **В других разделах системы**
**ВЫБОР ФУЛФИЛМЕНТ-ЦЕНТРА**:
- Партнеры с типом `FULFILLMENT`
- Используется при создании поставок расходников
**ВЫБОР ЛОГИСТИКИ**:
- Партнеры с типом `LOGIST`
- Используется при планировании доставок
**МЕССЕНДЖЕР**:
- Общение доступно только между партнерами
- Список чатов формируется из таблицы `Counterparty`
### 13.4 Технические правила
**СОЗДАНИЕ ЗАПИСЕЙ В COUNTERPARTY**:
```sql
-- При создании партнерства создаются ДВЕ записи
INSERT INTO counterparties (organizationId, counterpartyId) VALUES (org1_id, org2_id);
INSERT INTO counterparties (organizationId, counterpartyId) VALUES (org2_id, org1_id);
```
**ПРОВЕРКА ПАРТНЕРСТВА**:
```typescript
const isPartner = await prisma.counterparty.findFirst({
where: {
organizationId: currentOrgId,
counterpartyId: targetOrgId
}
});
```
**ПОЛУЧЕНИЕ ПАРТНЕРОВ ПО ТИПУ**:
```typescript
const wholesalePartners = await prisma.counterparty.findMany({
where: {
organizationId: currentOrgId,
counterparty: {
type: "WHOLESALE"
}
},
include: {
counterparty: true
}
});
```
### 13.5 Решение распространенных проблем
#### **ПРОБЛЕМА: GraphQL запрос не возвращает данные партнеров**
**Симптомы**:
- В консоли браузера: `All counterparties: 0`, `All counterparties data: []`
- GraphQL запрос отправляется успешно, но возвращает пустой массив
- В базе данных партнеры существуют
**Возможные причины и решения**:
1. **НЕПРАВИЛЬНОЕ ИМЯ ПОЛЯ В КОДЕ** (наиболее частая ошибка):
```typescript
// ❌ НЕПРАВИЛЬНО
const allCounterparties = counterpartiesData?.getMyCounterparties || [];
// ✅ ПРАВИЛЬНО
const allCounterparties = counterpartiesData?.myCounterparties || [];
```
**Объяснение**: В GraphQL схеме поле называется `myCounterparties`, а не `getMyCounterparties`
2. **НЕСООТВЕТСТВИЕ ID ПОЛЬЗОВАТЕЛЯ**:
- Проверить что пользователь авторизован под правильным аккаунтом
- Убедиться что `context.user.id` соответствует ожидаемому пользователю
3. **ПРОБЛЕМЫ С КЕШИРОВАНИЕМ APOLLO CLIENT**:
```typescript
const { data, loading, error } = useQuery(GET_MY_COUNTERPARTIES, {
fetchPolicy: 'network-only', // Обходим кеш
errorPolicy: 'all'
});
```
4. **ОТСУТСТВИЕ ЛОГИРОВАНИЯ В РЕЗОЛВЕРЕ**:
- Добавить console.log в GraphQL резолвер для отладки
- Проверить что резолвер вызывается
**Чек-лист для диагностики**:
- [ ] Проверить правильность имени поля в коде (`myCounterparties`)
- [ ] Убедиться что пользователь авторизован
- [ ] Проверить логи сервера на вызов резолвера
- [ ] Добавить отладочное логирование в браузере
- [ ] Проверить данные в базе через Prisma Studio
- [ ] Использовать `fetchPolicy: 'network-only'` для обхода кеша
---
## 14. 🌐 ИНТЕГРАЦИИ С СИСТЕМОЙ
### 14.1 Глобальная интеграция
- **МАРКЕТ**: Товары поставщиков отображаются в глобальном маркете
- **СИНХРОНИЗАЦИЯ**: Данные склада синхронизируются с модулем аналитики
- **УВЕДОМЛЕНИЯ**: Единая система через встроенный мессенджер
### 14.2 Интеграция с маркетплейсами
- **WILDBERRIES**: Обязательная проверка активности API ключа
- **СИНХРОНИЗАЦИЯ**: Регулярное обновление данных из внешних источников
- **ЛОКАЛЬНЫЕ КОПИИ**: Сохранение данных для офлайн работы
### 14.3 Интеграция с модулем "Услуги"
**РАСХОДНИКИ ФУЛФИЛМЕНТА В УСЛУГАХ**:
- Расходники фулфилмента - собственность фулфилмента (куплены у поставщиков)
- Фулфилмент создает заявки-поставки для покупки расходников у поставщиков
- Селлеры могут использовать расходники фулфилмента в разделе "Услуги / Расходники"
- Для создания продукта из товара
- Расходники списываются с остатков фулфилмента
- Стоимость включается в стоимость услуги
**WORKFLOW ИСПОЛЬЗОВАНИЯ**:
1. Селлер выбирает услугу "Создание продукта"
2. Указывает базовый товар
3. Выбирает необходимые расходники фулфилмента
4. Фулфилмент обрабатывает заказ и создает продукт
5. Расходники списываются, создается готовый продукт
---
## 15. 📊 СТАТИСТИКА И АНАЛИТИКА
### 15.1 Структура статистики по кабинетам
#### **В КАБИНЕТЕ ПОСТАВЩИКА**:
- **ТОВАРЫ**: Общая статистика товаров поставщика
- **РАСХОДНИКИ**: Материалы и вспомогательные товары (классифицируются при заказе)
#### **В КАБИНЕТЕ ФУЛФИЛМЕНТА**:
- **ТОВАРЫ**: Базовые товары от поставщиков (принятые на склад)
- **ПРОДУКТЫ**: Отдельный блок готовой продукции
- **БРАК**: Статистика потерь и списаний
- **РАСХОДНИКИ ФУЛФИЛМЕНТА**: Операционные материалы фулфилмента
- **РАСХОДНИКИ СЕЛЛЕРОВ**: Материалы для товаров селлеров
### 15.2 Ключевые метрики
**ОБЩИЕ ПОКАЗАТЕЛИ**:
- Общие остатки, заказано, в пути, остаток, продано
- Подсветка предметов с остатками ниже критического уровня
**АКТУАЛИЗАЦИЯ ДАННЫХ**:
- При изменении количества в карточке данные актуализируются во всей системе
- Статистика обновляется в реальном времени
- Отслеживание изменений для аналитики
---
## 16. 📱 ПРАВИЛА UI/UX И ИНТЕРФЕЙСА
### 16.1 Отзывчивость интерфейса
- **ОБЯЗАТЕЛЬНО**: Интерфейс должен работать на всех устройствах
- **ПРАВИЛО**: Адаптивная сетка для карточек товаров
- **ФУНКЦИЯ**: Оптимизация для мобильных устройств
- **ТРЕБОВАНИЕ**: Корректное отображение на экранах от 320px до 4K
### 16.2 Обратная связь пользователю
- **ОБЯЗАТЕЛЬНО**: Уведомления об успешных/неуспешных операциях
- **ПРАВИЛО**: Индикаторы загрузки для длительных операций
- **ФУНКЦИЯ**: Подтверждение критических действий (удаление, деактивация)
- **UX**: Понятные сообщения об ошибках с предложением решения
### 16.3 Правила обработки ошибок
- **ОБЯЗАТЕЛЬНО**: Логирование всех ошибок с детальной информацией
- **ПРАВИЛО**: Понятные сообщения об ошибках для пользователя
- **ФУНКЦИЯ**: Автоматическое восстановление после сбоев
- **МОНИТОРИНГ**: Отслеживание критических ошибок в реальном времени
### 16.4 Производительность
- **ПРАВИЛО**: Пагинация для больших списков товаров
- **ФУНКЦИЯ**: Ленивая загрузка изображений
- **ОПТИМИЗАЦИЯ**: Кэширование часто запрашиваемых данных
- **ПРОИЗВОДИТЕЛЬНОСТЬ**: Время загрузки страницы не более 3 секунд
---
## 17. ⚠️ КРИТИЧЕСКИЕ ЗАПРЕТЫ
### 17.1 НИКОГДА НЕ ДЕЛАТЬ:
1. ❌ Удалять предметы с существующими заказами
2. ❌ Изменять статусы заказов без уведомлений
3. ❌ Обходить проверки остатков предметов
4. ❌ Давать доступ к чужим данным
5. ❌ Игнорировать ошибки валидации
6. ❌ Сохранять пароли в открытом виде
7. ❌ Пропускать логирование критических операций
8. ❌ Блокировать интерфейс без индикации загрузки
9. ❌ Создавать брак или продукт без связи с родительским товаром
10. ❌ Создавать отдельные типы расходников (только общий тип "РАСХОДНИКИ")
11. ❌ Разрешать заказ брака
12. ❌ Нарушать иерархию типов предметов
13. ❌ Пропускать промежуточные статусы в workflow
14. ❌ Нарушать обязательную последовательность модулей в статистике фулфилмента
15. ❌ **Использовать неправильные имена полей GraphQL** (`getMyCounterparties` вместо `myCounterparties`)
16. ❌ **Использовать GET_SUPPLY_SUPPLIERS для отображения поставщиков в формах** (только партнеры WHOLESALE)
17. ❌ **Создавать интерфейсы TypeScript не соответствующие schema.prisma** (`sku`/`stock` вместо `article`/`quantity`)
18. ❌ **Использовать общие запросы вместо специализированных** (`GET_ALL_PRODUCTS` вместо `GET_ORGANIZATION_PRODUCTS` для конкретного поставщика)
19. ❌ **Показывать расходники в формах создания поставок товаров** (строгая типизация `PRODUCT`/`CONSUMABLE`)
20. ❌ **Фильтровать предметы по типу на фронтенде** (фильтрация должна быть в GraphQL резолвере)
### 17.2 ОБЯЗАТЕЛЬНЫЕ ПРАВИЛА:
1. ✅ Проверка остатков перед добавлением в корзину
2. ✅ Валидация всех числовых значений (цена > 0, вес > 0)
3. ✅ Автоматическая генерация уникальных артикулов СФ
4. ✅ Логирование всех изменений статусов
5. ✅ Уведомления всех участников при изменении статусов
6. ✅ Обязательная типизация всех предметов
7. ✅ Связь производных типов с родительскими предметами
8. ✅ Проверка доступности товаров перед заказом
9. ✅ Соблюдение жизненного цикла статусов поставок
10. ✅ Фиксация план/факт в процессе создания продукта
---
## 18. 🛠️ GRAPHQL И TYPESCRIPT ПРАВИЛА
### 18.1 Правила именования полей
**ВАЖНО**: Имена полей в GraphQL запросах должны точно соответствовать схеме!
```typescript
// ✅ ПРАВИЛЬНО - соответствует схеме
export const GET_MY_COUNTERPARTIES = gql`
query GetMyCounterparties {
myCounterparties { // <- имя поля в схеме
id
name
type
}
}
`;
// Использование в компоненте
const allCounterparties = counterpartiesData?.myCounterparties || [];
```
```typescript
// ❌ НЕПРАВИЛЬНО - не соответствует схеме
const allCounterparties = counterpartiesData?.getMyCounterparties || []; // Ошибка!
```
### 18.2 Правила отладки GraphQL
**При проблемах с GraphQL запросами следовать чек-листу**:
1. **Проверить соответствие имен полей схеме**
2. **Добавить fetchPolicy: 'network-only' для обхода кеша**
3. **Логировать данные в браузере и сервере**
4. **Проверить авторизацию пользователя**
5. **Убедиться что резолвер вызывается**
### 18.3 Обязательные поля для отладки
```typescript
const { data, loading, error } = useQuery(QUERY_NAME, {
fetchPolicy: 'network-only', // Обходим кеш при отладке
errorPolicy: 'all' // Показываем все ошибки
});
// Логирование для отладки
console.log("Data:", data);
console.log("Loading:", loading);
console.log("Error:", error);
```
### 18.4 TypeScript Rules
#### **Интерфейсы данных**
**Поля интерфейсов должны соответствовать GraphQL схеме**:
```typescript
// ✅ ПРАВИЛЬНО - соответствует schema.prisma
interface GoodsProduct {
id: string;
name: string;
article: string; // <- соответствует полю в schema
quantity?: number; // <- соответствует полю в schema
organization: {
id: string;
name: string;
};
}
```
```typescript
// ❌ НЕПРАВИЛЬНО - не соответствует schema
interface GoodsProduct {
sku: string; // <- в schema поле называется 'article'
stock?: number; // <- в schema поле называется 'quantity'
}
```
### 18.5 Система партнерства в GraphQL
**ПРАВИЛА ИСПОЛЬЗОВАНИЯ ПАРТНЕРСТВА**:
- Поставщики в формах берутся только из партнеров с типом `WHOLESALE`
- Используется запрос `GET_MY_COUNTERPARTIES` с фильтрацией по типу
- НЕ используется `GET_SUPPLY_SUPPLIERS` для отображения поставщиков в формах
- Партнерство создается двумя способами: через заказ в маркете или через раздел "Партнеры"
- Двусторонние записи в таблице `Counterparty` при создании партнерства
### 18.6 Архитектурные принципы GraphQL
- **Создавать специализированные резолверы** для каждого контекста использования
- **Использовать параметризованные запросы** (`organizationId`, `type`, `search`) вместо фильтрации на фронтенде
- **Добавлять подробное логирование** в резолверы для отладки (входные параметры, результаты фильтрации)
- **Типы запросов должны отражать бизнес-логику**: `organizationProducts` для товаров конкретной организации
- **Значения по умолчанию в резолверах** для критических параметров (`type: args.type || "PRODUCT"`)
- **Валидация обязательных параметров** на уровне схемы (`organizationId: ID!`)
- **Кеширование обходить при проблемах** через `fetchPolicy: 'network-only'`
---
## 19. 🔧 АРХИТЕКТУРНЫЕ ПРИНЦИПЫ
### 19.1 Стандарты разработки
- **ОБЯЗАТЕЛЬНО**: Покрытие тестами критической функциональности
- **ПРАВИЛО**: Следование принципам SOLID
- **ФУНКЦИЯ**: Автоматическое тестирование при развертывании
- **КАЧЕСТВО**: Минимальное покрытие тестами 80%
### 19.2 Документация
- **ОБЯЗАТЕЛЬНО**: Документирование всех API методов
- **ПРАВИЛО**: Комментарии к сложной бизнес-логике
- **ФУНКЦИЯ**: Автоматическая генерация документации
- **СТАНДАРТ**: Актуальная техническая документация
### 19.3 Масштабируемость
- **АРХИТЕКТУРА**: Модульная структура для легкого расширения
- **ПРАВИЛО**: Использование индексов для быстрого поиска
- **ФУНКЦИЯ**: Горизонтальное масштабирование при росте нагрузки
- **ПЛАНИРОВАНИЕ**: Готовность к увеличению нагрузки в 10 раз
### 19.4 Безопасность данных
- **ОБЯЗАТЕЛЬНО**: Шифрование чувствительных данных
- **ПРАВИЛО**: Аудит всех действий пользователей
- **ФУНКЦИЯ**: Контроль доступа на уровне API
- **БЕЗОПАСНОСТЬ**: Двухфакторная аутентификация для критических операций
---
## 20. 🎯 ПРАВИЛА КАЧЕСТВА КОДА
### 20.1 Проверки и валидация
**ОБЯЗАТЕЛЬНЫЕ ПРОВЕРКИ**:
- ✅ Типизация предметов: каждый предмет имеет один из типов: ТОВАР (`PRODUCT`), РАСХОДНИКИ (`CONSUMABLE`), БРАК и ПРОДУКТ (планируются)
- ✅ БРАК и ПРОДУКТ имеют обязательную связь с родительским товаром (parentId)
- ✅ Расходники создаются как универсальный тип, классифицируются при заказе
- ✅ **В формах создания поставок товаров показываются ТОЛЬКО предметы типа ТОВАР** (`PRODUCT`)
- ✅ **В формах создания поставок расходников показываются ТОЛЬКО предметы типа РАСХОДНИКИ** (`CONSUMABLE`)
- ✅ **Фильтрация по типу предмета происходит на уровне GraphQL резолвера**, не на фронтенде
### 20.2 Workflow статусов
- ✅ Соблюдена последовательность: PENDING → SUPPLIER_APPROVED → CONFIRMED → LOGISTICS_CONFIRMED → SHIPPED → IN_TRANSIT → DELIVERED
- ✅ Нет пропуска промежуточных статусов
- ✅ Каждое изменение статуса сопровождается уведомлением
### 20.3 Правила доступа
- ✅ Поставщик НЕ может добавлять собственные товары в корзину
- ✅ Заказ брака ЗАПРЕЩЕН
- ✅ Только активные предметы отображаются в маркете
- ✅ Проверка остатков перед добавлением в корзину
---
## 21. 🔍 ДИАГНОСТИКА И РЕШЕНИЕ ПРОБЛЕМ
### 21.1 Правило уточнений
**КРИТИЧЕСКИ ВАЖНО**: Если я не уверен в выполнении задачи или вижу противоречия в правилах - ОБЯЗАТЕЛЬНО уточнить у пользователя!
### 21.2 КОГДА УТОЧНЯТЬ:
- [ ] Недостаточно информации для правильного выполнения
- [ ] Вижу противоречия между правилами
- [ ] Задача может нарушить критические правила
- [ ] Неясно как применить правило в конкретной ситуации
- [ ] Есть сомнения в интерпретации требований
### 21.3 КАК УТОЧНЯТЬ:
1. Четко сформулировать что именно неясно
2. Указать какие правила/требования конфликтуют
3. Предложить варианты решения если возможно
4. Запросить конкретные уточнения
**❌ НИКОГДА не делать предположений если есть сомнения!**
---
## 22. 📋 КАТЕГОРИИ ТОВАРОВ И РАСХОДНИКОВ
### 22.1 Полный список 28 универсальных категорий товаров
1. Одежда и обувь
2. Косметика и парфюмерия
3. Дом и сад
4. Детские товары
5. Спорт и отдых
6. Электроника
7. Книги
8. Здоровье
9. Автотовары
10. Строительство и ремонт
11. Продукты питания
12. Зоотовары
13. Дача, сад и огород
14. Канцелярские товары
15. Хобби и творчество
16. Украшения и аксессуары
17. Сумки и чемоданы
18. Техника для дома
19. Музыкальные инструменты
20. Игры и игрушки
21. Мебель
22. Товары для красоты
23. Бытовая химия
24. Товары для путешествий
25. Медицинские товары
26. Религиозные товары
27. Антиквариат и коллекционирование
28. Прочие товары
### 22.2 12 специализированных категорий расходников
#### 🎁 **1. УПАКОВКА И ЗАЩИТА**
- Коробки (различных размеров)
- Пакеты (полиэтиленовые, бумажные, фирменные)
- Пузырчатая пленка, воздушные подушки
- Стрейч-пленка, гофрокартон
- Паллетная пленка, защитные уголки
#### 🏷️ **2. МАРКИРОВКА И ИДЕНТИФИКАЦИЯ**
- Этикетки (адресные, штрих-код, QR-код)
- Бирки (ценники, размерники)
- Стикеры и наклейки
- Маркеры и ручки
- Штампы и печати, термоэтикетки
#### 🔧 **3. КРЕПЕЖ И СОЕДИНЕНИЕ**
- Скотч (прозрачный, цветной, армированный)
- Клей и клеевые составы
- Стяжки пластиковые
- Степлер и скобы
- Веревки и шнуры, стрейч-лента
#### 📄 **4. ДОКУМЕНТООБОРОТ И ВКЛАДЫШИ**
- Накладные и сопроводительные документы
- Инструкции по эксплуатации
- Гарантийные талоны
- Рекламные буклеты, визитки и флаеры
- Благодарственные письма, купоны и промокоды
#### 🧼 **5. ГИГИЕНА И БЕЗОПАСНОСТЬ**
- Перчатки (латексные, нитриловые)
- Маски и респираторы
- Антисептики и дезинфекторы
- Салфетки и тряпки
- Фартуки и халаты, бахилы
#### 🛠️ **6. ИНСТРУМЕНТЫ И ПРИСПОСОБЛЕНИЯ**
- Ножи и резаки, ножницы
- Линейки и рулетки
- Упаковочные машины (ленточные)
- Дозаторы скотча
- Пистолеты для термоклея
- Весы и мерная тара
#### 🎨 **7. БРЕНДИНГ И ДИЗАЙН**
- Фирменные пакеты с логотипом
- Брендированные коробки
- Цветная упаковочная бумага
- Ленты и банты
- Наклейки с логотипом компании
- Подарочная упаковка
#### ⚡ **8. СПЕЦИАЛИЗИРОВАННЫЕ МАТЕРИАЛЫ**
- Антистатические пакеты
- Влагопоглотители
- Температурные индикаторы
- Хрупкие наклейки
- Пломбы и пломбировочные материалы
- Защита от краж (магнитные датчики)
#### 🏪 **9. ТОРГОВОЕ ОБОРУДОВАНИЕ**
- Манекены и вешалки
- Ценникодержатели
- Подставки и стойки
- Корзины и тележки
- Зеркала примерочные
- Освещение витрин
#### 🚚 **10. ЛОГИСТИКА И СКЛАДИРОВАНИЕ**
- Паллеты и поддоны
- Контейнеры и ящики
- Стеллажные системы
- Погрузочные ремни
- Защитные чехлы
- Адресные ярлыки для груза
#### 💻 **11. ТЕХНИЧЕСКИЕ РАСХОДНИКИ**
- Картриджи для принтеров
- Термоголовки, красящие ленты
- Батарейки для сканеров
- Чистящие средства для техники
- Запчасти для упаковочного оборудования
#### 🎪 **12. СЕЗОННЫЕ И ПРАЗДНИЧНЫЕ**
- Новогодняя упаковка
- Подарочные мешки
- Праздничные ленты
- Тематические наклейки
- Открытки и поздравления
- Сезонная упаковочная бумага
**ПРИМЕЧАНИЕ**: Данные категории являются рекомендательными и могут быть адаптированы под специфику конкретного поставщика расходников.
---
## 23. 🎖️ ПРИОРИТЕТЫ РАЗРАБОТКИ
### 23.1 ВЫСОКИЙ ПРИОРИТЕТ:
1. 🔴 Безопасность и контроль доступа
2. 🔴 Целостность данных и валидация
3. 🔴 Корректность статусов поставок
4. 🔴 Уведомления участников процесса
5. 🔴 Правильная типизация предметов
6. 🔴 Связи между товарами и производными типами
### 23.2 СРЕДНИЙ ПРИОРИТЕТ:
1. 🟡 Производительность и оптимизация
2. 🟡 Пользовательский опыт
3. 🟡 Аналитика и отчетность
4. 🟡 Интеграции с внешними системами
5. 🟡 Workflow для брака и продуктов
6. 🟡 Разделение расходников по типам
### 23.3 НИЗКИЙ ПРИОРИТЕТ:
1. 🟢 Дополнительные фильтры
2. 🟢 Косметические улучшения
3. 🟢 Экспериментальные функции
4. 🟢 Расширенная кастомизация
---
_Эта база знаний создана на основе анализа rules.md, rules1.md и rules2.md и является единым источником понимания структуры и логики проекта._
_Версия: 4.0_
_Дата создания: 2024_
_Статус: ПОЛНАЯ УНИФИЦИРОВАННАЯ БАЗА ЗНАНИЙ_
Reference in New Issue View Git Blame Copy Permalink