From d200885ff5cfc2d85ca8dc4a05dbd030fc45feff Mon Sep 17 00:00:00 2001 From: Veronika Smirnova Date: Mon, 25 Aug 2025 23:09:29 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=BE=D0=B1=D0=BD=D0=BE=D0=B2=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82?= =?UTF-8?q?=D0=B0=D1=86=D0=B8=D1=8E=20=D0=B4=D0=BB=D1=8F=20V2=20=D1=81?= =?UTF-8?q?=D0=B8=D1=81=D1=82=D0=B5=D0=BC=D1=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Обновления: - CLAUDE.md - обновлены правила взаимодействия с акцентом на модульную архитектуру - docs/development/MODULAR_ARCHITECTURE_PATTERN.md - обновлена документация паттерна модульной архитектуры 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 195 ++++++++++++++++-- .../MODULAR_ARCHITECTURE_PATTERN.md | 107 +++++++++- 2 files changed, 277 insertions(+), 25 deletions(-) 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: Исходный (активный)
@@ -470,11 +623,13 @@ npx prisma studio # GUI для базы данных ``` #### Дополнительные команды: + - `"очисти комментарии"` - удалить закомментированные варианты - `"переключи на вариант 2"` - активировать закомментированный код - `"покажи варианты"` - показать доступные варианты #### ПРАВИЛА ПРИМЕНЕНИЯ: + - ✅ **Использовать для UI экспериментов** и небольших логических изменений - ✅ **Всегда добавлять четкие комментарии** с описанием вариантов - ✅ **Очищать комментарии перед финальным коммитом** @@ -483,12 +638,14 @@ npx prisma studio # GUI для базы данных ### ДОКУМЕНТИРОВАНИЕ ИЗМЕНЕНИЙ #### При любых изменениях документировать: + - **ЧТО** изменено (конкретные файлы и функции) - **ПОЧЕМУ** изменено (обоснование решения) - **КТО** принял решение об изменении (пользователь/автоматически) - **КОГДА** изменено (временная метка) **Формат документирования:** + ``` 📝 ИЗМЕНЕНИЕ ЗАФИКСИРОВАНО: - ДАТА: [когда] @@ -500,11 +657,13 @@ npx prisma studio # GUI для базы данных ### АНАЛИЗ ПРИМЕРОВ КОДА #### Трехуровневый анализ примеров: + 1. **📋 СОДЕРЖАТЕЛЬНЫЙ** - что делает код (функциональность, логика, данные) 2. **🏗️ АРХИТЕКТУРНЫЙ** - как организован (структура, взаимосвязи, позиционирование) 3. **🎨 СТИЛЕВОЙ** - как выглядит (CSS классы, анимации, цвета) #### Алгоритм анализа примера: + 1. **Прочитать** весь код компонента-примера 2. **Понять архитектуру** - где элемент размещен относительно других 3. **Понять логику** - почему именно так структурировано @@ -512,6 +671,7 @@ npx prisma studio # GUI для базы данных 5. **Проверить** соответствие правилам проекта #### Стоп-вопросы перед реализацией: + - "Понимаю ли я **архитектуру** этого решения?" - "Где именно должен располагаться элемент в **общей структуре**?" - "Какова **семантическая роль** этого элемента?" @@ -524,12 +684,14 @@ npx prisma studio # GUI для базы данных **CASE STUDY: Ошибка с плавающей кнопкой из UI Kit** **❌ ОШИБКА**: При добавлении кнопки "🌟 Вариант 1: Плавающая кнопка слева": + 1. **Поверхностный анализ**: Скопировал только стили кнопки 2. **Игнорирование архитектуры**: Не заметил, что кнопка в **отдельном контейнере** 3. **Неправильное размещение**: Добавил как часть блока контента 4. **Непонимание термина**: "Плавающая" = независимая от контента, между элементами #### ОБЯЗАТЕЛЬНЫЙ ЧЕК-ЛИСТ ДЛЯ UI KIT КОМПОНЕНТОВ: + ``` 🔍 ПЕРЕД РЕАЛИЗАЦИЕЙ: □ Прочитал ВЕСЬ код компонента-примера @@ -541,12 +703,14 @@ npx prisma studio # GUI для базы данных ``` #### АНТИ-ПАТТЕРНЫ: + - **"Быстрое копирование"** - копировать стили без понимания архитектуры - **"Частичный анализ"** - читать только нужную часть кода - **"Буквальное применение"** - использовать без адаптации к контексту - **"Игнорирование контейнеров"** - не обращать внимание на DOM-структуру #### ПРАВИЛЬНЫЕ ПАТТЕРНЫ: + - **"Архитектурный анализ первым"** - понять структуру, потом стили - **"Контекстная адаптация"** - применять принципы, а не код буквально - **"Семантическое понимание"** - осознавать роль каждого элемента @@ -572,11 +736,13 @@ npx prisma studio # GUI для базы данных ### РАБОТА С КОНТЕКСТОМ #### Файлы контекста: + - **current-session.md** - текущие задачи и решения - **CLAUDE.md** - эти правила (загружаются автоматически) - **TodoWrite** - инструмент для отслеживания задач #### При потере контекста: + 1. Прочитать current-session.md 2. Проверить TodoWrite 3. Спросить у пользователя о текущей задаче @@ -584,7 +750,8 @@ npx prisma studio # GUI для базы данных --- # Важные напоминания для Claude Code + Делай только то, что просят; ни больше, ни меньше. НИКОГДА не создавай файлы, если они не абсолютно необходимы для достижения цели. ВСЕГДА отдавай предпочтение редактированию существующего файла, а не созданию нового. -НИКОГДА не создавай проактивно файлы документации (*.md) или README файлы. Создавай файлы документации только по явной просьбе пользователя. \ No newline at end of file +НИКОГДА не создавай проактивно файлы документации (\*.md) или README файлы. Создавай файлы документации только по явной просьбе пользователя. diff --git a/docs/development/MODULAR_ARCHITECTURE_PATTERN.md b/docs/development/MODULAR_ARCHITECTURE_PATTERN.md index 29dfbdf..cf970ce 100644 --- a/docs/development/MODULAR_ARCHITECTURE_PATTERN.md +++ b/docs/development/MODULAR_ARCHITECTURE_PATTERN.md @@ -1,7 +1,7 @@ # 🏗️ Паттерн модульной архитектуры для React компонентов > ⚠️ **ОФИЦИАЛЬНЫЙ СТАНДАРТ АРХИТЕКТУРЫ SFERA** -> Этот документ описывает **ОБЯЗАТЕЛЬНУЮ** архитектуру для всех новых компонентов >500 строк и рефакторинга существующих >800 строк. +> Этот документ описывает **ОБЯЗАТЕЛЬНУЮ** модульную архитектуру по умолчанию для большинства компонентов в системе SFERA. ## 🎯 СТАТУС АРХИТЕКТУРНОГО СТАНДАРТА @@ -12,13 +12,79 @@ ### 📋 ПРАВИЛА ПРИМЕНЕНИЯ: -1. **ВСЕ НОВЫЕ КОМПОНЕНТЫ >500 строк** → создавать по модульной архитектуре -2. **Существующие компоненты >800 строк** → рефакторить по возможности -3. **Обязательно использовать** этот паттерн для компонентов dashboard, creation, management +#### ✅ ВСЕГДА МОДУЛЬНАЯ АРХИТЕКТУРА (без исключений): -## 🎯 Применимость паттерна +**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. **Простые модалки** подтверждения (Да/Нет) + +## 🎯 КЛЮЧЕВОЕ ПРАВИЛО SFERA + +> **"Если сомневаешься - делай модульным. Лучше иметь избыточную структуру папок, чем 2000-строчный спагетти-код через месяц."** + +### 📏 Критерии принятия решения: + +```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 +} +``` + +### Кандидаты для рефакторинга (legacy компонентов): - **Размер**: >800 строк кода - **Сложность**: Множественные состояния и бизнес-логика @@ -287,10 +353,11 @@ function MainComponent() { ### Перед началом -- [ ] Компонент больше 800 строк -- [ ] Есть несколько логических секций UI -- [ ] Множественные useState и useEffect -- [ ] Активно развивающийся функционал +- [ ] Компонент относится к категории: page, form, table, dashboard +- [ ] ИЛИ ожидаемый размер >300 строк +- [ ] ИЛИ сложность по алгоритму ≥5 баллов +- [ ] ИЛИ есть несколько логических секций UI +- [ ] ИЛИ множественные useState и useEffect ### Планирование @@ -324,10 +391,28 @@ function MainComponent() { ## 🎯 Заключение -Модульная архитектура значительно улучшает качество кода, скорость разработки и поддержки. Применяйте этот паттерн к большим компонентам постепенно, следуя принципам безопасного рефакторинга. +Модульная архитектура по умолчанию значительно улучшает качество кода, скорость разработки и поддержки в долгосрочной перспективе. В SFERA мы применяем принцип "лучше переструктурировать сразу, чем рефакторить потом". + +### 🎯 Практические примеры применения: + +**Модульные (новые стандарты):** + +- `/app/suppliers/create/page.tsx` → CreateSupplierPage/ +- `EmployeeManagementTable` → EmployeeManagement/ +- `SupplyOrderForm` → SupplyOrderForm/ +- `ProductCatalog` → ProductCatalog/ +- `UserSettingsForm` → UserSettingsForm/ + +**Простые (исключения):** + +- `Logo.tsx` +- `LoadingDots.tsx` +- `ConfirmDialog.tsx` +- `PriceDisplay.tsx` --- **Основано на**: Успешном рефакторинге create-suppliers-supply-page.tsx (1,467→240 строк) +**Обновлено**: Синхронизировано с правилами CLAUDE.md **Автор паттерна**: Claude Code **Дата**: Август 2025