docs: обновить документацию для V2 системы

Обновления: - CLAUDE.md - обновлены правила взаимодействия с акцентом на модульную архитектуру - docs/development/MODULAR_ARCHITECTURE_PATTERN.md - обновлена документация паттерна модульной архитектуры 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-25 23:09:29 +03:00
parent 6e3cedec67
commit d200885ff5
2 changed files with 277 additions and 25 deletions
--- 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: Исходный (активный)
 <div className="flex items-center justify-between">
@ -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 файлы. Создавай файлы документации только по явной просьбе пользователя.
+НИКОГДА не создавай проактивно файлы документации (\*.md) или README файлы. Создавай файлы документации только по явной просьбе пользователя.
--- 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