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) СТАТУС: ОБЯЗАТЕЛЬНЫЙ К ВЫПОЛНЕНИЮ