sfera/development-checklist.md

# ЧЕКЛИСТ РАЗРАБОТКИ - ОБЯЗАТЕЛЬНЫЕ ПРОВЕРКИ

> ⚠️ **КРИТИЧЕСКИ ВАЖНО**: Этот чеклист ОБЯЗАТЕЛЕН к проверке перед любым изменением кода!

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

## 🔴 КРИТИЧЕСКИЕ ПРОВЕРКИ (НЕЛЬЗЯ НАРУШАТЬ)

### ✅ Типизация предметов

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

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

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

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

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

### ✅ Система фулфилмента

- [ ] Товары разделены на "на складе" и "в обработке"
- [ ] Модули статистики в правильной последовательности: ПРОДУКТ → ТОВАР → БРАК → ВОЗВРАТЫ → РАСХОДНИКИ СЕЛЛЕРОВ → РАСХОДНИКИ ФУЛФИЛМЕНТА
- [ ] Процесс создания продукта включает учет план/факт

### ✅ Система логистики

- [ ] Своевременное подтверждение заявок на доставку
- [ ] Соблюдение workflow логистики: получение заявки → подтверждение → забор → доставка
- [ ] Корректная работа системы тарификации (до 1м³ и свыше 1м³)
- [ ] Обязательные уведомления о статусе доставки

### ✅ Структура кабинетов

- [ ] Каждый тип кабинета имеет страницу "Главная" (РЕАЛИЗОВАНО)
- [ ] Страница "Главная" первая в sidebar навигации (РЕАЛИЗОВАНО)
- [ ] Условное отображение разделов по типу организации: `{user?.organization?.type === "TYPE" && (...)}`
- [ ] Адаптивный роутинг для кнопок с разной логикой по типам кабинетов
- [ ] Роут `/home` с универсальным компонентом HomePageWrapper
- [ ] 4 типо-зависимых компонента: SellerHomePage, FulfillmentHomePage, WholesaleHomePage, LogistHomePage
- [ ] Проверки доступа и безопасности в каждом компоненте
- [ ] Каждый кабинет имеет раздел "Экономика" (РЕАЛИЗОВАНО В СИСТЕМЕ)
- [ ] Разделы "Экономика" размещены перед настройками в каждом кабинете (РЕАЛИЗОВАНО)
- [ ] Пустые разделы-заглушки с пометкой "будет добавлен позже" (РЕАЛИЗОВАНО)
- [ ] Роут `/economics` с универсальным компонентом EconomicsPageWrapper (РЕАЛИЗОВАНО)
- [ ] 4 типо-зависимых компонента экономики: SellerEconomicsPage, FulfillmentEconomicsPage, WholesaleEconomicsPage, LogistEconomicsPage (РЕАЛИЗОВАНО)
- [ ] Кнопка "Экономика" в sidebar навигации перед настройками (РЕАЛИЗОВАНО)
- [ ] Проверки доступа и безопасности в экономических компонентах (РЕАЛИЗОВАНО)

### ✅ Обязательные поля

- [ ] Название, артикул, цена > 0, тип предмета
- [ ] ИСКЛЮЧЕНИЕ: Цена брака может быть 0 для фулфилмента (себестоимость для селлера)
- [ ] Уникальность артикула в рамках организации
- [ ] Формат артикула: СФ-{ТИП}-{КОД*КАТЕГОРИИ}-{КОД*ОРГАНИЗАЦИИ}-{TIMESTAMP}-{RANDOM}
- [ ] Товар имеет минимум одно изображение (ПРИМЕР АВТОСИНХРОНИЗАЦИИ)

## 🟡 ВАЖНЫЕ ПРОВЕРКИ

### ✅ Валидация данных

- [ ] Все числовые значения корректны (цена > 0, вес > 0)
- [ ] Количество в заказе не превышает остаток
- [ ] Проверка корректности дат (не прошедшие для поставок)
- [ ] Валидация количества: минимум 1 единица/комплект, максимум = остаток у поставщика
- [ ] Проверка в реальном времени при изменении количества

### ✅ Уведомления

- [ ] Автоматические уведомления при создании заказов
- [ ] Уведомления при изменении статусов всем участникам
- [ ] Логирование всех изменений

### ✅ Интеграции

- [ ] Синхронизация данных между модулями
- [ ] Корректная работа с API маркетплейсов
- [ ] Связь с модулем "Услуги" для расходников фулфилмента

## 💻 ТЕХНИЧЕСКИЕ ПРОВЕРКИ

### ✅ Пользовательский интерфейс

- [ ] Адаптивность интерфейса для всех устройств
- [ ] Индикаторы загрузки для длительных операций
- [ ] Подтверждение критических действий
- [ ] Время загрузки страницы не более 3 секунд

### ✅ Обработка ошибок

- [ ] Логирование всех ошибок с детальной информацией
- [ ] Понятные сообщения об ошибках для пользователя
- [ ] Автоматическое восстановление после сбоев
- [ ] Регулярное резервное копирование данных

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

- [ ] Пагинация для больших списков товаров
- [ ] Ленивая загрузка изображений
- [ ] Кэширование часто запрашиваемых данных
- [ ] Готовность к масштабированию

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

- [ ] Шифрование чувствительных данных
- [ ] Аудит всех действий пользователей
- [ ] Контроль доступа на уровне API
- [ ] Соответствие требованиям GDPR

### ✅ Качество кода

- [ ] Покрытие тестами критической функциональности (минимум 80%)
- [ ] Следование принципам SOLID
- [ ] Документирование всех API методов
- [ ] Автоматическое тестирование при развертывании

### ✅ GraphQL и TypeScript

- [ ] Имена полей в коде соответствуют GraphQL схеме (`myCounterparties`, не `getMyCounterparties`)
- [ ] Интерфейсы TypeScript соответствуют schema.prisma (`article`, не `sku`; `quantity`, не `stock`)
- [ ] При проблемах с GraphQL использовать `fetchPolicy: 'network-only'` для обхода кеша
- [ ] Добавлять логирование при отладке GraphQL запросов
- [ ] Проверка что резолверы вызываются (логи сервера)
- [ ] **Использовать специализированные запросы вместо общих** (`GET_ORGANIZATION_PRODUCTS` вместо `GET_ALL_PRODUCTS` для конкретного поставщика)
- [ ] **Обязательная фильтрация по типу предмета** в резолверах (`PRODUCT`/`CONSUMABLE`)
- [ ] **Параметр `organizationId` обязателен** для запросов товаров конкретной организации

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

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

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

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

## 🟢 РЕКОМЕНДУЕМЫЕ ПРОВЕРКИ

### ✅ Пользовательский опыт

- [ ] Адаптивность интерфейса
- [ ] Индикаторы загрузки
- [ ] Понятные сообщения об ошибках

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

- [ ] Пагинация для больших списков
- [ ] Ленивая загрузка изображений
- [ ] Кэширование данных

## ❌ АБСОЛЮТНО ЗАПРЕЩЕНО

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

---

## 🤔 ПРАВИЛО УТОЧНЕНИЙ

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

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

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

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

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

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

---

**ПРАВИЛО**: Перед каждым изменением кода проверить этот чеклист!
**ИСТОЧНИК ИСТИНЫ**: rules-unified.md (v4.0)
**СТАТУС**: ОБЯЗАТЕЛЬНЫЙ К ВЫПОЛНЕНИЮ