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>
This commit is contained in:
Veronika Smirnova
181
CLAUDE.md
181
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: ПЛАНИРОВАНИЕ
|
||||
|
||||
5. **🛑 ГЛУБОКИЙ АНАЛИЗ** (обязательные вопросы пользователю)
|
||||
6. **🔍 ИССЛЕДОВАНИЕ** (изучение ВСЕХ связанных файлов)
|
||||
7. **📊 ДЕТАЛЬНЫЙ ПЛАН** (с промежуточными проверками и rollback точками)
|
||||
@ -71,6 +79,7 @@
|
||||
10. **ОСТАНОВИТЬСЯ И ЖДАТЬ ОДОБРЕНИЯ ПЛАНА**
|
||||
|
||||
**Чек-лист планирования:**
|
||||
|
||||
```
|
||||
- ✅ Прочитал правила в docs/
|
||||
- ✅ Задача понята в контексте правил
|
||||
@ -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,47 +498,57 @@ npx prisma studio # GUI для базы данных
|
||||
#### СТРУКТУРА ДОКУМЕНТАЦИИ СИСТЕМЫ:
|
||||
|
||||
**🎯 CORE - Ядро системы**
|
||||
|
||||
- **DOMAIN_MODEL.md** - 4 типа организаций, основные сущности
|
||||
- **BUSINESS_RULES_CORE.md** - Ключевые бизнес-правила: доступ, партнерство, расходники
|
||||
|
||||
**🔌 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 компонентов
|
||||
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
|
||||
@ -409,6 +559,7 @@ npx prisma studio # GUI для базы данных
|
||||
- **Упоминание "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 файлы. Создавай файлы документации только по явной просьбе пользователя.
|
||||
|
||||
@ -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
|
||||
|
||||
Reference in New Issue
Block a user