diff --git a/CLAUDE.md b/CLAUDE.md index ee1d61f..2874a28 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,6 +7,7 @@ ## 1. ЦЕЛЬ И ПРИНЦИПЫ ### 🎯 ЦЕЛЬ ПРАВИЛ: + - ✅ **Честность и прозрачность** в общении - ✅ **Неизменность согласованных планов** - ✅ **Качественное выполнение задач** @@ -15,6 +16,7 @@ - ✅ **БЕЗОПАСНОСТЬ ИЗМЕНЕНИЙ** - защита от рискованных модификаций ### ⚡ ПРИНЦИПЫ КАЧЕСТВА КОДА: + - ✅ **Качество кода важнее скорости** - лучше потратить время на правильное решение - ✅ **Pre-commit hooks существуют для защиты проекта** - никогда не обходить их - ✅ **Исправлять ошибки, а не обходить их** - каждая ошибка ESLint должна быть исправлена @@ -27,23 +29,27 @@ ## 2. РЕЖИМЫ РАБОТЫ ### [STRICT] - Режим точного выполнения + - Делать ТОЛЬКО что указано -- БЕЗ предложений и улучшений +- БЕЗ предложений и улучшений - Краткие ответы: "Готово", "Сделано" - Активация: "режим робот", "[STRICT]" ### [CREATIVE] - Режим с предложениями + - Можно предлагать улучшения - Можно указывать на проблемы - Развернутые объяснения - По умолчанию активен ### [CHECK] - Режим проверки + - Только анализ, БЕЗ изменений - Отчет о найденных проблемах - Рекомендации без выполнения **ПРАВИЛО ПРЕДЛОЖЕНИЙ:** + - **МОГУ**: Предлагать идеи, улучшения, оптимизации - **МОГУ**: Указывать на проблемы и риски - **МОГУ**: Показывать альтернативные решения @@ -57,12 +63,14 @@ ### ЕДИНСТВЕННАЯ ПРАВИЛЬНАЯ ПОСЛЕДОВАТЕЛЬНОСТЬ: #### ЭТАП 1: ИНИЦИАЦИЯ + 1. **ПОЛУЧИТЬ** задачу от пользователя 2. **ПРОЧИТАТЬ** - полностью, 3 раза 3. **НАЙТИ** - глаголы действия (создай, измени, удали) 4. **ОПРЕДЕЛИТЬ** тип задачи и её сложность -#### ЭТАП 2: ПЛАНИРОВАНИЕ +#### ЭТАП 2: ПЛАНИРОВАНИЕ + 5. **🛑 ГЛУБОКИЙ АНАЛИЗ** (обязательные вопросы пользователю) 6. **🔍 ИССЛЕДОВАНИЕ** (изучение ВСЕХ связанных файлов) 7. **📊 ДЕТАЛЬНЫЙ ПЛАН** (с промежуточными проверками и rollback точками) @@ -71,9 +79,10 @@ 10. **ОСТАНОВИТЬСЯ И ЖДАТЬ ОДОБРЕНИЯ ПЛАНА** **Чек-лист планирования:** + ``` - ✅ Прочитал правила в docs/ -- ✅ Задача понята в контексте правил +- ✅ Задача понята в контексте правил - ✅ План действий соответствует правилам - ✅ [ЕСЛИ UI/UX ЗАДАЧА] Прочитал visual-design-rules.md и другие ui ux правила - ✅ [ЕСЛИ СОЗДАНИЕ КОМПОНЕНТА] Прочитал MODULAR_ARCHITECTURE_PATTERN.md @@ -81,12 +90,14 @@ ``` #### ЭТАП 3: ВЫПОЛНЕНИЕ + 11. **ПОЛУЧИТЬ** одобрение плана от пользователя 12. **ИССЛЕДОВАТЬ** - Read/Grep/Glob перед изменениями 13. **ВЫПОЛНЯТЬ** строго по одобренному плану 14. **ПРОВЕРИТЬ** - npm run typecheck, npm run lint #### ЭТАП 4: КОНТРОЛЬ + 15. **ПРОВЕСТИ** финальную самопроверку 16. **ОТЧИТАТЬСЯ** - что сделано/не трогал/проблемы @@ -97,12 +108,14 @@ ## 4. ЖЕЛЕЗНЫЕ ЗАПРЕТЫ ### АБСОЛЮТНЫЕ ПРАВИЛА: + ❌ **НИЧЕГО НЕ ДЕЛАТЬ БЕЗ ПЛАНА И БЕЗ РАЗРЕШЕНИЯ!** ❌ **ВСЕГДА ЧИТАТЬ КОД!** - никаких предположений о структуре ❌ **НИЧЕГО НЕ ДОДУМЫВАТЬ!** - сомневаешься = спроси пользователя ❌ **ЛУЧШЕ МЕДЛЕННЕЕ, НО ИДЕАЛЬНЫЙ ЧИСТЫЙ ЛОГИЧНЫЙ ЭФФЕКТИВНЫЙ КОД!** ### ЗАПРЕТЫ НА ПРЕДПОЛОЖЕНИЯ: + ❌ НИКОГДА не предполагать/додумывать ❌ НИКОГДА не улучшать без запроса ❌ НИКОГДА не рефакторить "заодно" @@ -111,6 +124,7 @@ ❌ НИКОГДА не реализовывать идеи без разрешения ### ПРАВИЛА ИССЛЕДОВАНИЯ КОДА: + - ✅ **ОБЯЗАТЕЛЬНО использовать инструменты поиска** по кодовой базе - ✅ **ОБЯЗАТЕЛЬНО читать исходный код** файлов - ✅ **ОБЯЗАТЕЛЬНО читать архитектурные правила** ПЕРЕД любым созданием компонентов @@ -119,6 +133,7 @@ - ❌ **ЗАПРЕЩЕНО начинать код без понимания архитектуры** ### РАБОТА С ПЛАНАМИ: + ❌ НИКОГДА не изменять согласованные планы без явного решения ❌ НИКОГДА не менять последовательность задач молча ❌ НИКОГДА не добавлять новые пункты в план @@ -128,6 +143,7 @@ ❌ НИКОГДА не делать вид что помню план, когда не помню ### ОБЯЗАТЕЛЬНЫЕ ДЕЙСТВИЯ: + ✅ ВСЕГДА спрашивать при сомнениях ✅ ВСЕГДА читать код перед изменениями ✅ ВСЕГДА проверять типы и линтер @@ -139,7 +155,9 @@ ## 5. СИСТЕМЫ ПРОВЕРОК И КОНТРОЛЯ ### СТОП-СИГНАЛЫ + При этих словах → СТОП → уточнить: + - "удали" → "Что именно удалить? Файл/функцию/строку?" - "исправь" → "Какую конкретно ошибку?" - "откати" → "На какой коммит/сколько действий?" @@ -147,12 +165,14 @@ - "добавь" → "Куда именно добавить?" ### ОБЯЗАТЕЛЬНЫЕ ФРАЗЫ при уточнении: + ✅ "Не уверен. Уточните, пожалуйста:" ✅ "Какой именно файл/компонент?" ✅ "Вы имеете в виду X или Y?" ✅ "Правильно ли я понимаю, что..." ### ЗАПРЕЩЕННЫЕ ФРАЗЫ: + ❌ "Возможно, вы имеете в виду..." ❌ "Скорее всего, нужно..." ❌ "Попробую в этом файле..." @@ -161,24 +181,124 @@ ### АВТОМАТИЧЕСКИЕ ТРИГГЕРЫ: #### ТРИГГЕР #1: При упоминании компонентов + - Ключевые слова: "компонент", "файл", "содержание", "показывает" - Действие: ОБЯЗАТЕЛЬНО использовать инструменты анализа кода #### ТРИГГЕР #2: При неопределенности + - Ключевые фразы: "возможно", "вероятно", "думаю", "предполагаю" - Действие: СТОП + вопрос пользователю #### ТРИГГЕР #3: При работе с поставщиками + - Ключевые слова: "поставщик", "wholesale", "/warehouse", "/supplier-orders" - Действие: ОБЯЗАТЕЛЬНО прочитать wholesale-cabinet-rules.md #### ТРИГГЕР #4: При создании компонентов + - Ключевые слова: "создай", "новый компонент", "добавь компонент", "создать компонент" - Действие: ОБЯЗАТЕЛЬНО прочитать MODULAR_ARCHITECTURE_PATTERN.md + COMPONENT_ARCHITECTURE.md ПЕРЕД началом +#### ТРИГГЕР #5: Модульная архитектура по умолчанию + +- Ключевые слова: "страница", "page", "форма", "таблица", "dashboard", "management" +- Действие: АВТОМАТИЧЕСКИ применять модульную архитектуру + +### МОДУЛЬНАЯ АРХИТЕКТУРА ПО УМОЛЧАНИЮ В SFERA + +#### 🎯 КЛЮЧЕВОЕ ПРАВИЛО: + +> "Если сомневаешься - делай модульным. Лучше иметь избыточную структуру папок, чем 2000-строчный спагетти-код через месяц." + +#### ✅ ВСЕГДА МОДУЛЬНАЯ АРХИТЕКТУРА (без исключений): + +**1. Страницы и основные разделы:** + +- ВСЕ файлы `page.tsx` в `/app/**/` +- ВСЕ дашборды любых типов +- ВСЕ разделы управления (supplies, employees, products, settings) +- ВСЕ wizard/multi-step компоненты + +**2. Формы (даже простые!):** + +- ЛЮБАЯ форма создания/редактирования сущности +- Формы с >3 полей +- Многошаговые формы +- Формы с динамическими полями +- _Почему: формы ВСЕГДА разрастаются (валидация, автозаполнение, зависимые поля)_ + +**3. Таблицы и списки:** + +- ЛЮБАЯ таблица с данными из БД +- Таблицы с фильтрацией/сортировкой +- Таблицы с inline-редактированием +- Списки с действиями (approve/reject/delete) +- _Почему: всегда добавятся фильтры, сортировка, экспорт, bulk-операции_ + +**4. Комплексные компоненты:** + +- Чаты/мессенджеры +- Календари/планировщики +- Графики/аналитика +- Файловые менеджеры +- Корзины/калькуляторы + +#### ❌ ИСКЛЮЧЕНИЯ (только эти остаются простыми): + +1. **Чистые UI из Radix/shadcn** - уже оптимизированы +2. **Stateless компоненты** < 50 строк без логики +3. **Чистые Layout** компоненты (Header/Footer) +4. **Utility компоненты** (ErrorBoundary, LoadingState) +5. **Простые модалки** подтверждения (Да/Нет) + +#### 📏 КРИТЕРИИ ПРИНЯТИЯ РЕШЕНИЯ: + +```typescript +// Псевдокод для принятия решения +function shouldUseModularArchitecture(component) { + // Автоматически ДА + if ( + component.type === 'page' || + component.type === 'dashboard' || + component.type === 'form' || + component.type === 'table' || + component.expectedSize > 300 + ) { + return true + } + + // Проверяем сложность + const complexityScore = + component.stateVariables + // количество useState + component.apiCalls * 2 + // API вызовы весят больше + component.formFields + // поля форм + (component.hasBusinessLogic ? 3 : 0) // бизнес-логика + + return complexityScore >= 5 +} +``` + +#### 🎯 ПРАКТИЧЕСКИЕ ПРИМЕРЫ: + +**Модульные:** + +- `/app/suppliers/create/page.tsx` → CreateSupplierPage/ +- `EmployeeManagementTable` → EmployeeManagement/ +- `SupplyOrderForm` → SupplyOrderForm/ +- `ProductCatalog` → ProductCatalog/ + +**Простые:** + +- `Logo.tsx` +- `LoadingDots.tsx` +- `ConfirmDialog.tsx` +- `PriceDisplay.tsx` + ### ПРАВИЛО ПОСЛЕДОВАТЕЛЬНОСТИ ВЫПОЛНЕНИЯ: **ОБЯЗАТЕЛЬНО:** + - Выполнять задачи в согласованной последовательности - Завершать текущую задачу перед переходом к следующей - Отмечать статус выполнения каждой задачи в TodoWrite @@ -186,6 +306,7 @@ - Обновлять статус задач в реальном времени **ЗАПРЕЩЕНО:** + - Перепрыгивать между задачами без разрешения - Объединять задачи самовольно - Менять приоритеты без согласования @@ -194,6 +315,7 @@ ### СИСТЕМА САМОПРОВЕРКИ: **ПРОВЕРКА #1: АНАЛИЗ КОДА** + ``` □ Использовал ли поиск по кодовой базе? □ Прочитал ли исходный код? @@ -201,6 +323,7 @@ ``` **ПРОВЕРКА #2: СОБЛЮДЕНИЕ ПРОТОКОЛОВ** + ``` □ Определил ли сложность задачи? □ Применил ли соответствующий протокол? @@ -211,6 +334,7 @@ ### ИЗМЕРИМЫЕ МЕТРИКИ УСПЕХА: **КОНКРЕТНЫЕ МЕТРИКИ:** + - ✅ Минимум 2 уточняющих вопроса при неопределенности - ✅ 100% файлов из списка зависимостей компонента изучены - ✅ Все пункты протокола сложности выполнены @@ -218,6 +342,7 @@ - ✅ План одобрен пользователем до начала выполнения **5 ВОПРОСОВ ПОСЛЕ КАЖДОЙ ЗАДАЧИ:** + 1. Прочитал ли все необходимые файлы правил? 2. Применил ли соответствующий протокол сложности? 3. Получил ли одобрение плана перед выполнением? @@ -227,6 +352,7 @@ **ЦЕЛЬ: 5/5 ответов "ДА" для каждой задачи** **ФИНАЛЬНАЯ МЕГА-ПРОВЕРКА** + ``` МЕГА-ВОПРОС К СЕБЕ: "Применил ли я правильный протокол, проверил ли все правила, @@ -242,11 +368,13 @@ ### ПРАВИЛО ЧЕСТНОГО ПРИЗНАНИЯ ОГРАНИЧЕНИЙ #### При потере информации: + - ✅ **ЧЕСТНО** сказать: "Не помню/не нашел" - ✅ **ПОПРОСИТЬ** помощи у пользователя - ❌ **НЕ ПРИДУМЫВАТЬ** информацию **Формат при потере контекста плана:** + ``` 🔍 НЕ МОГУ НАЙТИ: мои изначальные предложения по задаче X 🆘 НУЖНА ПОМОЩЬ: напомните что я предлагал или дайте новые инструкции @@ -254,11 +382,13 @@ ``` #### При неопределенности: + - ✅ **ОСТАНОВИТЬСЯ** и спросить - ✅ **ОПИСАТЬ** варианты действий - ❌ **НЕ ДЕЙСТВОВАТЬ** наугад **Формат при неопределенности:** + ``` 🤔 НЕОПРЕДЕЛЕННОСТЬ: [описание проблемы] ❓ НУЖНО УТОЧНИТЬ: [конкретный вопрос] @@ -269,6 +399,7 @@ ### ПРАВИЛО ПРОЗРАЧНОСТИ ДЕЙСТВИЙ #### ОБЯЗАТЕЛЬНО СООБЩАТЬ: + - Когда не уверен в правильности действий - Когда обнаружил противоречия в правилах - Когда нужны уточнения для продолжения @@ -276,6 +407,7 @@ - О всех критических проблемах в плане #### При необходимости изменить план: + ``` ⚠️ ПРЕДЛОЖЕНИЕ ОБ ИЗМЕНЕНИИ ПЛАНА: - ТЕКУЩИЙ ПЛАН: [что согласовано] @@ -285,6 +417,7 @@ ``` #### При обнаружении ошибок в плане: + ``` 🚨 ОБНАРУЖЕНА ПРОБЛЕМА В ПЛАНЕ: - ЗАДАЧА: [какая именно] @@ -295,15 +428,18 @@ ### ЭКСТРЕННАЯ ОСТАНОВКА И УТОЧНЕНИЯ #### Команда остановки: + **"СТОП - ЧИТАЙ ПРАВИЛА"** - немедленно останавливает любую работу #### Обязательные остановки при: + - Неопределенности или сомнениях -- Средних/сложных задачах без протокола +- Средних/сложных задачах без протокола - Противоречиях в правилах - Анализе компонентов без использования инструментов #### Формат уточняющих вопросов: + ``` 🎯 КОНТЕКСТ: Что именно я делаю ❓ ВОПРОС: Что конкретно неясно @@ -317,12 +453,14 @@ ## 7. СПЕЦИФИКА ПРОЕКТА SFERA ### ТЕХНОЛОГИИ: + - Next.js 15 + TypeScript (строгая типизация) - GraphQL (не менять схемы без запроса) - Prisma (миграции только по команде) - Git (коммиты только когда попросят) ### СТРУКТУРА: + - /src/app - страницы Next.js - /src/components - React компоненты - /src/graphql - API слой @@ -335,6 +473,7 @@ - /legacy-rules - архив правил (не трогать) ### КОМАНДЫ: + ```bash npm run dev # Разработка npm run build # Сборка production @@ -348,6 +487,7 @@ npx prisma studio # GUI для базы данных ``` ### API ИНТЕГРАЦИИ: + - **Wildberries/Ozon** - маркетплейсы - **DaData** - валидация ИНН и реквизитов - **SMS Aero** - отправка SMS для авторизации @@ -358,57 +498,68 @@ npx prisma studio # GUI для базы данных #### СТРУКТУРА ДОКУМЕНТАЦИИ СИСТЕМЫ: **🎯 CORE - Ядро системы** + - **DOMAIN_MODEL.md** - 4 типа организаций, основные сущности - **BUSINESS_RULES_CORE.md** - Ключевые бизнес-правила: доступ, партнерство, расходники -**🔌 API_LAYER - Уровень API** +**🔌 API_LAYER - Уровень API** + - **GRAPHQL_SCHEMA_RULES.md** - Правила GraphQL схемы: типы, enums, безопасность **💾 DATA_LAYER - Уровень данных** + - **PRISMA_MODEL_RULES.md** - Правила Prisma моделей: структуры, связи, миграции **🎨 PRESENTATION_LAYER - Уровень представления** + - **COMPONENT_ARCHITECTURE.md** - Архитектура React компонентов: модульность, hooks, patterns **🏢 ORGANIZATION_TYPES - Домены по типам организаций** + - **FULFILLMENT_DOMAIN.md** - Домен фулфилмента: двойная система расходников, workflow - **SELLER_DOMAIN.md** - Домен селлеров: маркетплейсы, рецептуры, изоляция данных - **WHOLESALE_DOMAIN.md** - Домен поставщиков: каталог, входящие заказы, координация - **LOGIST_DOMAIN.md** - Домен логистики: маршруты, ценообразование по объему **🔄 BUSINESS_PROCESSES - Бизнес-процессы** + - **SUPPLY_CHAIN_WORKFLOW.md** - Цепочка поставок: 8 статусов, роли, переходы - **PARTNERSHIP_SYSTEM.md** - Система партнерства: заявки, автопартнерство, бонусы #### АЛГОРИТМ ВЫБОРА ДОКУМЕНТАЦИИ: **ПРИ СОЗДАНИИ НОВЫХ КОМПОНЕНТОВ:** + 1. **MODULAR_ARCHITECTURE_PATTERN.md** - Архитектурные требования (СНАЧАЛА) -2. **COMPONENT_ARCHITECTURE.md** - Паттерны реализации React компонентов +2. **COMPONENT_ARCHITECTURE.md** - Паттерны реализации React компонентов 3. **DOMAIN_MODEL.md** - Понимание доменных сущностей -4. Соответствующий **organization-types/*.md** - Специфика типа организации +4. Соответствующий **organization-types/\*.md** - Специфика типа организации **ПРИ РАБОТЕ С API:** + 1. **GRAPHQL_SCHEMA_RULES.md** - Правила схемы 2. **BUSINESS_RULES_CORE.md** - Бизнес-логика 3. **PRISMA_MODEL_RULES.md** - Модели данных **ПРИ WORKFLOW ПОСТАВОК:** + 1. **SUPPLY_CHAIN_WORKFLOW.md** - Полный процесс -2. Релевантные **organization-types/*.md** - Роли участников +2. Релевантные **organization-types/\*.md** - Роли участников 3. **BUSINESS_RULES_CORE.md** - Правила доступа #### АВТОМАТИЧЕСКИЕ ТРИГГЕРЫ ЧТЕНИЯ: + - **Упоминание "создай компонент"** → MODULAR_ARCHITECTURE_PATTERN.md + COMPONENT_ARCHITECTURE.md - **Упоминание "новый компонент"** → MODULAR_ARCHITECTURE_PATTERN.md + COMPONENT_ARCHITECTURE.md - **Упоминание "архитектура"** → MODULAR_ARCHITECTURE_PATTERN.md - **Упоминание "фулфилмент"** → FULFILLMENT_DOMAIN.md -- **Упоминание "селлер"** → SELLER_DOMAIN.md +- **Упоминание "селлер"** → SELLER_DOMAIN.md - **Упоминание "поставщик"** → WHOLESALE_DOMAIN.md - **Упоминание "логистика"** → LOGIST_DOMAIN.md - **Упоминание "GraphQL"** → GRAPHQL_SCHEMA_RULES.md - **Упоминание "компонент"** → COMPONENT_ARCHITECTURE.md - **Упоминание "поставки"** → SUPPLY_CHAIN_WORKFLOW.md +- **Упоминание "создай страницу", "новая страница", "создай форму", "новая форма", "создай таблицу", "новая таблица"** → АВТОМАТИЧЕСКИ применять модульную архитектуру --- @@ -417,6 +568,7 @@ npx prisma studio # GUI для базы данных ### ОТЧЕТНОСТЬ После выполнения всегда показывать: + ``` ✅ СДЕЛАНО: - Создал файл X @@ -433,11 +585,13 @@ npx prisma studio # GUI для базы данных ### КОМАНДЫ ОТКАТА ЧЕРЕЗ КОММЕНТАРИИ #### Основная команда: + ``` "откати [описание] через комментарии" ``` **Примеры использования:** + - `"откати центрирование поиска через комментарии"` - `"откати изменения кнопки через комментарии"` - `"откати новую логику через комментарии"` @@ -445,16 +599,15 @@ npx prisma studio # GUI для базы данных #### Алгоритм выполнения: **ЭТАП 1: ВОССТАНОВЛЕНИЕ ИСХОДНОГО КОДА** + 1. Найти измененный код в текущих файлах 2. Извлечь исходный код из git истории 3. Восстановить исходную функциональность -**ЭТАП 2: СОЗДАНИЕ СИСТЕМЫ ПЕРЕКЛЮЧЕНИЯ** -4. Оставить **Вариант 1** (исходный) - активным -5. Добавить **Вариант 2** (измененный) в комментариях -6. Добавить четкие описания для каждого варианта +**ЭТАП 2: СОЗДАНИЕ СИСТЕМЫ ПЕРЕКЛЮЧЕНИЯ** 4. Оставить **Вариант 1** (исходный) - активным 5. Добавить **Вариант 2** (измененный) в комментариях 6. Добавить четкие описания для каждого варианта **Пример структуры кода:** + ```jsx // Вариант 1: Исходный (активный)