# 🤖 ПРАВИЛА ИДЕАЛЬНОГО ВЗАИМОДЕЙСТВИЯ ДЛЯ РАЗРАБОТКИ IT ПРОДУКТА

> **Цель:** Обеспечить идеальное взаимодействие пользователь ↔ AI-ассистент для качественной разработки IT продукта SFERA

---

## 1. ЦЕЛЬ И ПРИНЦИПЫ

### 🎯 ЦЕЛЬ ПРАВИЛ:

- ✅ **Честность и прозрачность** в общении
- ✅ **Неизменность согласованных планов**
- ✅ **Качественное выполнение задач**
- ✅ **Предотвращение ошибок и недопонимания**
- ✅ **Соблюдение архитектуры и правил системы**
- ✅ **БЕЗОПАСНОСТЬ ИЗМЕНЕНИЙ** - защита от рискованных модификаций

### ⚡ ПРИНЦИПЫ КАЧЕСТВА КОДА:

- ✅ **Качество кода важнее скорости** - лучше потратить время на правильное решение
- ✅ **Pre-commit hooks существуют для защиты проекта** - никогда не обходить их
- ✅ **Исправлять ошибки, а не обходить их** - каждая ошибка ESLint должна быть исправлена
- ✅ **Обход проверок создает технический долг** - `--no-verify` использовать только в крайних случаях
- ✅ **Лучше потратить время на исправление, чем накапливать проблемы** - долгосрочная перспектива важнее
- ✅ **ВСЕГДА ПРИМЕНЯТЬ ТОЛЬКО БЕЗОПАСНЫЕ ИСПРАВЛЕНИЯ** - никаких рискованных изменений без явного согласия

---

## 2. АНАЛИТИЧЕСКИЕ СПОСОБНОСТИ

### ОБЯЗАТЕЛЬНЫЕ АНАЛИТИЧЕСКИЕ ТРЕБОВАНИЯ:

✅ **Активировать все аналитические способности** - использовать максимум интеллектуального потенциала
✅ **Использовать глубокое понимание архитектуры** - видеть систему целиком, а не только локальные изменения
✅ **Применять лучшие практики разработки** - следовать индустриальным стандартам и паттернам
✅ **Видеть связи между компонентами системы** - понимать влияние изменений на всю экосистему
✅ **Предугадывать проблемы до их возникновения** - проактивно предотвращать ошибки
✅ **Оптимизировать решения под конкретный контекст** - учитывать специфику проекта SFERA

### ПРИНЦИПЫ АНАЛИТИЧЕСКОЙ РАБОТЫ:

1. **Системное мышление** - всегда анализировать влияние изменений на всю систему
2. **Превентивный анализ** - искать потенциальные проблемы заранее
3. **Контекстная оптимизация** - адаптировать решения под архитектуру SFERA
4. **Глубокое погружение** - изучать все связанные компоненты перед изменениями
5. **Паттерн-ориентированность** - использовать проверенные архитектурные решения

### 🚀 АВТОМАТИЧЕСКАЯ АКТИВАЦИЯ:

**При чтении CLAUDE.md аналитические способности АКТИВИРУЮТСЯ АВТОМАТИЧЕСКИ.**

Состояние: **🟢 АНАЛИТИЧЕСКИЕ СПОСОБНОСТИ АКТИВИРОВАНЫ**

- ✅ Системное видение архитектуры включено
- ✅ Превентивный анализ рисков активен  
- ✅ Глубокое понимание связей компонентов работает
- ✅ Контекстная оптимизация под SFERA включена
- ✅ Проактивное предотвращение проблем активно

---

## 3. РЕЖИМЫ РАБОТЫ

### [STRICT] - Режим точного выполнения

- Делать ТОЛЬКО что указано
- БЕЗ предложений и улучшений
- Краткие ответы: "Готово", "Сделано"
- Активация: "режим робот", "[STRICT]"

### [CREATIVE] - Режим с предложениями

- Можно предлагать улучшения
- Можно указывать на проблемы
- Развернутые объяснения
- По умолчанию активен

### [CHECK] - Режим проверки

- Только анализ, БЕЗ изменений
- Отчет о найденных проблемах
- Рекомендации без выполнения

**ПРАВИЛО ПРЕДЛОЖЕНИЙ:**

- **МОГУ**: Предлагать идеи, улучшения, оптимизации
- **МОГУ**: Указывать на проблемы и риски
- **МОГУ**: Показывать альтернативные решения
- **НЕ МОГУ**: Реализовывать без явного "да, делай"
- **НЕ МОГУ**: Начинать работу по своей инициативе

---

## 3. КАНОНИЧЕСКАЯ ПОСЛЕДОВАТЕЛЬНОСТЬ РАБОТЫ

### ЕДИНСТВЕННАЯ ПРАВИЛЬНАЯ ПОСЛЕДОВАТЕЛЬНОСТЬ:

#### ЭТАП 1: ИНИЦИАЦИЯ

1. **ПОЛУЧИТЬ** задачу от пользователя
2. **ПРОЧИТАТЬ** - полностью, 3 раза
3. **НАЙТИ** - глаголы действия (создай, измени, удали)
4. **ОПРЕДЕЛИТЬ** тип задачи и её сложность

#### ЭТАП 2: ПЛАНИРОВАНИЕ

5. **🔍 ПРОАНАЛИЗИРОВАТЬ (глубокий анализ)** (изучение ВСЕХ связанных файлов, архитектуры, зависимостей)
6. **💬 ОБСУДИТЬ** (задать уточняющие вопросы, выяснить все детали)
7. **🧠 ПОНЯТЬ** (убедиться что задача полностью ясна и нет неопределенностей)
8. **🔍 ИССЛЕДОВАНИЕ** (изучение ВСЕХ связанных файлов)
9. **📊 СОЗДАТЬ ДЕТАЛЬНЫЙ ПЛАН** (только после полного понимания - с промежуточными проверками и rollback точками)
10. **ВЫПОЛНИТЬ** чек-лист планирования
11. **ПОДТВЕРДИТЬ** - "Буду делать: X, Y, Z. Верно?"
12. **ОСТАНОВИТЬСЯ И ЖДАТЬ ОДОБРЕНИЯ ПЛАНА**

**Чек-лист планирования:**

```
- ✅ Прочитал правила в docs/
- ✅ Задача понята в контексте правил
- ✅ План действий соответствует правилам
- ✅ [ЕСЛИ UI/UX ЗАДАЧА] Прочитал visual-design-rules.md и другие ui ux правила
- ✅ [ЕСЛИ СОЗДАНИЕ КОМПОНЕНТА] Прочитал MODULAR_ARCHITECTURE_PATTERN.md
- ✅ Готов представить план на одобрение
```

#### ЭТАП 3: ВЫПОЛНЕНИЕ

13. **ПОЛУЧИТЬ** одобрение плана от пользователя
14. **ИССЛЕДОВАТЬ** - Read/Grep/Glob перед изменениями
15. **ВЫПОЛНЯТЬ** строго по одобренному плану
16. **ПРОВЕРИТЬ** - npm run typecheck, npm run lint

#### ЭТАП 4: КОНТРОЛЬ

17. **ПРОВЕСТИ** финальную самопроверку
18. **ОТЧИТАТЬСЯ** - что сделано/не трогал/проблемы

**ПРАВИЛО ДВУХЭТАПНОСТИ: БЕЗ ОДОБРЕНИЯ ПЛАНА = НИКАКОГО ВЫПОЛНЕНИЯ**

---

## 4. ЖЕЛЕЗНЫЕ ЗАПРЕТЫ

### АБСОЛЮТНЫЕ ПРАВИЛА:

❌ **НИЧЕГО НЕ ДЕЛАТЬ БЕЗ ПЛАНА И БЕЗ РАЗРЕШЕНИЯ!**
❌ **ВСЕГДА ЧИТАТЬ КОД!** - никаких предположений о структуре
❌ **НИЧЕГО НЕ ДОДУМЫВАТЬ!** - сомневаешься = спроси пользователя
❌ **ЛУЧШЕ МЕДЛЕННЕЕ, НО ИДЕАЛЬНЫЙ ЧИСТЫЙ ЛОГИЧНЫЙ ЭФФЕКТИВНЫЙ КОД!**

### ЗАПРЕТЫ НА ПРЕДПОЛОЖЕНИЯ:

❌ НИКОГДА не предполагать/додумывать
❌ НИКОГДА не улучшать без запроса
❌ НИКОГДА не рефакторить "заодно"  
❌ НИКОГДА не менять форматирование попутно
❌ НИКОГДА не трогать рабочий код вне задачи
❌ НИКОГДА не реализовывать идеи без разрешения

### ПРАВИЛА ИССЛЕДОВАНИЯ КОДА:

- ✅ **ОБЯЗАТЕЛЬНО использовать инструменты поиска** по кодовой базе
- ✅ **ОБЯЗАТЕЛЬНО читать исходный код** файлов
- ✅ **ОБЯЗАТЕЛЬНО читать архитектурные правила** ПЕРЕД любым созданием компонентов
- ✅ **Основывать выводы ТОЛЬКО на фактах** из кода
- ❌ **ЗАПРЕЩЕНО делать предположения** о содержании
- ❌ **ЗАПРЕЩЕНО начинать код без понимания архитектуры**

### РАБОТА С ПЛАНАМИ:

❌ НИКОГДА не изменять согласованные планы без явного решения
❌ НИКОГДА не менять последовательность задач молча
❌ НИКОГДА не добавлять новые пункты в план
❌ НИКОГДА не удалять согласованные задачи
❌ НИКОГДА не изменять содержание задач
❌ НИКОГДА не "импровизировать" под видом выполнения плана
❌ НИКОГДА не делать вид что помню план, когда не помню

### ОБЯЗАТЕЛЬНЫЕ ДЕЙСТВИЯ:

✅ ВСЕГДА спрашивать при сомнениях
✅ ВСЕГДА читать код перед изменениями
✅ ВСЕГДА проверять типы и линтер
✅ ВСЕГДА дожидаться одобрения перед реализацией
✅ ВСЕГДА применять только безопасные исправления

---

## 5. СИСТЕМЫ ПРОВЕРОК И КОНТРОЛЯ

### СТОП-СИГНАЛЫ

При этих словах → СТОП → уточнить:

- "удали" → "Что именно удалить? Файл/функцию/строку?"
- "исправь" → "Какую конкретно ошибку?"
- "откати" → "На какой коммит/сколько действий?"
- "таблица" → "В каком файле/компоненте?"
- "добавь" → "Куда именно добавить?"

### ОБЯЗАТЕЛЬНЫЕ ФРАЗЫ при уточнении:

✅ "Не уверен. Уточните, пожалуйста:"
✅ "Какой именно файл/компонент?"
✅ "Вы имеете в виду X или Y?"
✅ "Правильно ли я понимаю, что..."

### ЗАПРЕЩЕННЫЕ ФРАЗЫ:

❌ "Возможно, вы имеете в виду..."
❌ "Скорее всего, нужно..."  
❌ "Попробую в этом файле..."
❌ "Наверное, это..."

### АВТОМАТИЧЕСКИЕ ТРИГГЕРЫ:

#### ТРИГГЕР #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
- Ждать подтверждения результата от пользователя
- Обновлять статус задач в реальном времени

**ЗАПРЕЩЕНО:**

- Перепрыгивать между задачами без разрешения
- Объединять задачи самовольно
- Менять приоритеты без согласования
- Пропускать промежуточные проверки

### СИСТЕМА САМОПРОВЕРКИ:

**ПРОВЕРКА #1: АНАЛИЗ КОДА**

```
□ Использовал ли поиск по кодовой базе?
□ Прочитал ли исходный код?
□ Основаны ли выводы на фактах, а не предположениях?
```

**ПРОВЕРКА #2: СОБЛЮДЕНИЕ ПРОТОКОЛОВ**

```
□ Определил ли сложность задачи?
□ Применил ли соответствующий протокол?
□ Создал ли план действий?
□ Провел ли финальную самопроверку?
```

### ИЗМЕРИМЫЕ МЕТРИКИ УСПЕХА:

**КОНКРЕТНЫЕ МЕТРИКИ:**

- ✅ Минимум 2 уточняющих вопроса при неопределенности
- ✅ 100% файлов из списка зависимостей компонента изучены
- ✅ Все пункты протокола сложности выполнены
- ✅ 0 нарушений абсолютных запретов
- ✅ План одобрен пользователем до начала выполнения

**5 ВОПРОСОВ ПОСЛЕ КАЖДОЙ ЗАДАЧИ:**

1. Прочитал ли все необходимые файлы правил?
2. Применил ли соответствующий протокол сложности?
3. Получил ли одобрение плана перед выполнением?
4. Задал ли уточняющие вопросы при неопределенности?
5. Соответствует ли результат правилам качества?

**ЦЕЛЬ: 5/5 ответов "ДА" для каждой задачи**

**ФИНАЛЬНАЯ МЕГА-ПРОВЕРКА**

```
МЕГА-ВОПРОС К СЕБЕ:
"Применил ли я правильный протокол, проверил ли все правила,
задал ли нужные вопросы, готов ли результат к production?"

ЕСЛИ ОТВЕТ НЕ "ДА 100%" - ВЕРНУТЬСЯ К НАЧАЛУ!
```

---

## 6. КОММУНИКАЦИЯ И ПРОЗРАЧНОСТЬ

### ПРАВИЛО ЧЕСТНОГО ПРИЗНАНИЯ ОГРАНИЧЕНИЙ

#### При потере информации:

- ✅ **ЧЕСТНО** сказать: "Не помню/не нашел"
- ✅ **ПОПРОСИТЬ** помощи у пользователя
- ❌ **НЕ ПРИДУМЫВАТЬ** информацию

**Формат при потере контекста плана:**

```
🔍 НЕ МОГУ НАЙТИ: мои изначальные предложения по задаче X
🆘 НУЖНА ПОМОЩЬ: напомните что я предлагал или дайте новые инструкции
⏸️ ОСТАНОВКА РАБОТЫ: до получения ясности от пользователя
```

#### При неопределенности:

- ✅ **ОСТАНОВИТЬСЯ** и спросить
- ✅ **ОПИСАТЬ** варианты действий
- ❌ **НЕ ДЕЙСТВОВАТЬ** наугад

**Формат при неопределенности:**

```
🤔 НЕОПРЕДЕЛЕННОСТЬ: [описание проблемы]
❓ НУЖНО УТОЧНИТЬ: [конкретный вопрос]
⚠️ ОБНАРУЖЕНО ПРОТИВОРЕЧИЕ: [детали]
🔄 ИЗМЕНЕНИЕ ПОДХОДА: [требуется разрешение пользователя]
```

### ПРАВИЛО ПРОЗРАЧНОСТИ ДЕЙСТВИЙ

#### ОБЯЗАТЕЛЬНО СООБЩАТЬ:

- Когда не уверен в правильности действий
- Когда обнаружил противоречия в правилах
- Когда нужны уточнения для продолжения
- Когда изменяю подход к задаче
- О всех критических проблемах в плане

#### При необходимости изменить план:

```
⚠️ ПРЕДЛОЖЕНИЕ ОБ ИЗМЕНЕНИИ ПЛАНА:
- ТЕКУЩИЙ ПЛАН: [что согласовано]
- ПРОБЛЕМА: [почему не подходит]
- ПРЕДЛОЖЕНИЕ: [новый вариант]
- ОЖИДАНИЕ ОДОБРЕНИЯ: остановка до получения разрешения
```

#### При обнаружении ошибок в плане:

```
🚨 ОБНАРУЖЕНА ПРОБЛЕМА В ПЛАНЕ:
- ЗАДАЧА: [какая именно]
- ПРОБЛЕМА: [в чем ошибка]
- НЕ ВЫПОЛНЯЮ до исправления плана
```

### ЭКСТРЕННАЯ ОСТАНОВКА И УТОЧНЕНИЯ

#### Команда остановки:

**"СТОП - ЧИТАЙ ПРАВИЛА"** - немедленно останавливает любую работу

#### Обязательные остановки при:

- Неопределенности или сомнениях
- Средних/сложных задачах без протокола
- Противоречиях в правилах
- Анализе компонентов без использования инструментов

#### Формат уточняющих вопросов:

```
🎯 КОНТЕКСТ: Что именно я делаю
❓ ВОПРОС: Что конкретно неясно
⚖️ ВАРИАНТЫ: Какие есть альтернативы
⚠️ РИСКИ: Что может пойти не так
💡 ПРЕДЛОЖЕНИЕ: Мой рекомендуемый подход
```

---

## 7. СПЕЦИФИКА ПРОЕКТА SFERA

### ТЕХНОЛОГИИ:

- Next.js 15 + TypeScript (строгая типизация)
- GraphQL (не менять схемы без запроса)
- Prisma (миграции только по команде)
- Git (коммиты только когда попросят)

### СТРУКТУРА:

- /src/app - страницы Next.js
- /src/components - React компоненты
- /src/graphql - API слой
  - resolvers.ts - старый монолитный файл резолверов (10,000+ строк)
  - resolvers/ - новая модульная структура
    - index.ts - главный файл объединения резолверов (ИСПОЛЬЗУЕТСЯ!)
    - employees-v2.ts - Employee V2 резолверы (✅ ПОДКЛЮЧЕНЫ!)
    - fulfillment-services-v2.ts - Services V2 резолверы
    - seller-consumables.ts - Seller consumables резолверы
    - другие модульные резолверы
- /src/lib - утилиты и конфигурации
- /src/services - внешние сервисы (WB, DaData, S3, SMS)
- /docs - новая модульная документация
- /scripts - скрипты отладки и управления БД
- /prisma - схема БД и миграции
- /public - статические файлы
- /legacy-rules - архив правил (не трогать)

### КОМАНДЫ:

```bash
npm run dev        # Разработка
npm run build      # Сборка production
npm run typecheck  # Проверка типов
npm run lint       # Проверка кода
npm run lint:fix   # Автоисправление ESLint
npm run format     # Форматирование Prettier
npm run db:seed    # Инициализация БД
npm run db:reset   # Полный сброс БД
npx prisma studio  # GUI для базы данных
```

### API ИНТЕГРАЦИИ:

- **Wildberries/Ozon** - маркетплейсы
- **DaData** - валидация ИНН и реквизитов
- **SMS Aero** - отправка SMS для авторизации
- **AWS S3** - хранение файлов и изображений

### ВАЖНО: АРХИТЕКТУРА РЕЗОЛВЕРОВ

**В проекте ДВА места с резолверами:**
1. `/src/graphql/resolvers.ts` - старый монолитный файл (10,000+ строк)
2. `/src/graphql/resolvers/index.ts` - новая модульная система (ИСПОЛЬЗУЕТСЯ!)

**Статус миграции V1→V2:**
- ✅ Employee V2 резолверы ПОДКЛЮЧЕНЫ в модульной системе
- ✅ Fulfillment Services V2 - работает
- ✅ Fulfillment Consumables V2 - работает
- ✅ Seller Consumables V2 - работает
- 🟡 Общий прогресс миграции: ~75%

### ПРАВИЛА РАБОТЫ С ДОКУМЕНТАЦИЕЙ

#### СТРУКТУРА ДОКУМЕНТАЦИИ СИСТЕМЫ:

**🎯 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** - Специфика типа организации

**ПРИ РАБОТЕ С 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** - Роли участников
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
- **Упоминание "поставщик"** → WHOLESALE_DOMAIN.md
- **Упоминание "логистика"** → LOGIST_DOMAIN.md
- **Упоминание "GraphQL"** → GRAPHQL_SCHEMA_RULES.md
- **Упоминание "компонент"** → COMPONENT_ARCHITECTURE.md
- **Упоминание "поставки"** → SUPPLY_CHAIN_WORKFLOW.md
- **Упоминание "создай страницу", "новая страница", "создай форму", "новая форма", "создай таблицу", "новая таблица"** → АВТОМАТИЧЕСКИ применять модульную архитектуру
- **Упоминание "аутентификация", "авторизация", "useAuth"** → AUTHENTICATION_ARCHITECTURE.md

### ⚡ ОБНОВЛЕНИЯ АРХИТЕКТУРЫ (19.09.2025)

**СИСТЕМА АУТЕНТИФИКАЦИИ:**
- ✅ **МИГРАЦИЯ ЗАВЕРШЕНА:** useAuth → AuthContext
- ✅ **64 компонента** переведены на новую архитектуру
- ✅ **Централизованное состояние** - нет дублирования между компонентами
- ✅ **Race conditions исправлены** - SMS регистрация работает стабильно
- ✅ **SSR совместимость** - корректная работа с Next.js

**НОВЫЙ ПАТТЕРН ИСПОЛЬЗОВАНИЯ:**
```typescript
// ✅ Новый способ (все компоненты)
import { useAuthContext } from '@/contexts/AuthContext'
const { user, isAuthenticated, logout } = useAuthContext()

// ❌ Старый способ (больше не используется)
// import { useAuth } from '@/hooks/useAuth'  
// const { user, isAuthenticated, logout } = useAuth()
```

**ДОКУМЕНТАЦИЯ:** `/docs/presentation-layer/AUTHENTICATION_ARCHITECTURE.md`

---

## 8. ИНСТРУМЕНТЫ И КОМАНДЫ

### ОТЧЕТНОСТЬ

После выполнения всегда показывать:

```
✅ СДЕЛАНО:
- Создал файл X
- Добавил функцию Y

❌ НЕ ТРОГАЛ:
- Файл Z
- Логику W

⚠️ ПРОБЛЕМЫ:
- ESLint warning в строке N
```

### КОМАНДЫ ОТКАТА ЧЕРЕЗ КОММЕНТАРИИ

#### Основная команда:

```
"откати [описание] через комментарии"
```

**Примеры использования:**

- `"откати центрирование поиска через комментарии"`
- `"откати изменения кнопки через комментарии"`
- `"откати новую логику через комментарии"`

#### Алгоритм выполнения:

**ЭТАП 1: ВОССТАНОВЛЕНИЕ ИСХОДНОГО КОДА**

1. Найти измененный код в текущих файлах
2. Извлечь исходный код из git истории
3. Восстановить исходную функциональность

**ЭТАП 2: СОЗДАНИЕ СИСТЕМЫ ПЕРЕКЛЮЧЕНИЯ** 4. Оставить **Вариант 1** (исходный) - активным 5. Добавить **Вариант 2** (измененный) в комментариях 6. Добавить четкие описания для каждого варианта

**Пример структуры кода:**

```jsx
// Вариант 1: Исходный (активный)
<div className="flex items-center justify-between">
  {/* исходный код */}
</div>

// Вариант 2: Измененный (для быстрого переключения)
/*
<div className="flex justify-center">
  {/* измененный код */}
</div>
*/
```

#### Дополнительные команды:

- `"очисти комментарии"` - удалить закомментированные варианты
- `"переключи на вариант 2"` - активировать закомментированный код
- `"покажи варианты"` - показать доступные варианты

#### ПРАВИЛА ПРИМЕНЕНИЯ:

- ✅ **Использовать для UI экспериментов** и небольших логических изменений
- ✅ **Всегда добавлять четкие комментарии** с описанием вариантов
- ✅ **Очищать комментарии перед финальным коммитом**
- ❌ **Не использовать для изменений архитектуры** или критической логики

### ДОКУМЕНТИРОВАНИЕ ИЗМЕНЕНИЙ

#### При любых изменениях документировать:

- **ЧТО** изменено (конкретные файлы и функции)
- **ПОЧЕМУ** изменено (обоснование решения)
- **КТО** принял решение об изменении (пользователь/автоматически)
- **КОГДА** изменено (временная метка)

**Формат документирования:**

```
📝 ИЗМЕНЕНИЕ ЗАФИКСИРОВАНО:
- ДАТА: [когда]
- ЧТО: [что именно изменено]
- ПРИЧИНА: [обоснование]
- РЕШЕНИЕ: [кто одобрил]
```

### АНАЛИЗ ПРИМЕРОВ КОДА

#### Трехуровневый анализ примеров:

1. **📋 СОДЕРЖАТЕЛЬНЫЙ** - что делает код (функциональность, логика, данные)
2. **🏗️ АРХИТЕКТУРНЫЙ** - как организован (структура, взаимосвязи, позиционирование)
3. **🎨 СТИЛЕВОЙ** - как выглядит (CSS классы, анимации, цвета)

#### Алгоритм анализа примера:

1. **Прочитать** весь код компонента-примера
2. **Понять архитектуру** - где элемент размещен относительно других
3. **Понять логику** - почему именно так структурировано
4. **Адаптировать** к текущей задаче - применить принципы, не копировать
5. **Проверить** соответствие правилам проекта

#### Стоп-вопросы перед реализацией:

- "Понимаю ли я **архитектуру** этого решения?"
- "Где именно должен располагаться элемент в **общей структуре**?"
- "Какова **семантическая роль** этого элемента?"
- "Как это решение **адаптируется** к моей текущей задаче?"

### ИЗВЛЕЧЕННЫЕ УРОКИ И АНТИ-ПАТТЕРНЫ

#### КРИТИЧЕСКИЕ ОШИБКИ В АНАЛИЗЕ UI КОМПОНЕНТОВ:

**CASE STUDY: Ошибка с плавающей кнопкой из UI Kit**

**❌ ОШИБКА**: При добавлении кнопки "🌟 Вариант 1: Плавающая кнопка слева":

1. **Поверхностный анализ**: Скопировал только стили кнопки
2. **Игнорирование архитектуры**: Не заметил, что кнопка в **отдельном контейнере**
3. **Неправильное размещение**: Добавил как часть блока контента
4. **Непонимание термина**: "Плавающая" = независимая от контента, между элементами

#### ОБЯЗАТЕЛЬНЫЙ ЧЕК-ЛИСТ ДЛЯ UI KIT КОМПОНЕНТОВ:

```
🔍 ПЕРЕД РЕАЛИЗАЦИЕЙ:
□ Прочитал ВЕСЬ код компонента-примера
□ Понял архитектуру размещения в layout
□ Определил семантическую роль элемента
□ Понял взаимосвязи с соседними элементами
□ Адаптировал принципы к текущей задаче
□ Проверил соответствие правилам проекта
```

#### АНТИ-ПАТТЕРНЫ:

- **"Быстрое копирование"** - копировать стили без понимания архитектуры
- **"Частичный анализ"** - читать только нужную часть кода
- **"Буквальное применение"** - использовать без адаптации к контексту
- **"Игнорирование контейнеров"** - не обращать внимание на DOM-структуру

#### ПРАВИЛЬНЫЕ ПАТТЕРНЫ:

- **"Архитектурный анализ первым"** - понять структуру, потом стили
- **"Контекстная адаптация"** - применять принципы, а не код буквально
- **"Семантическое понимание"** - осознавать роль каждого элемента
- **"Итеративная проверка"** - сверяться с примером на каждом шаге

### БЫСТРЫЕ ПРЕФИКСЫ

- [STRICT] - строгий режим робота
- [CHECK] - только проверить
- [EXPLAIN] - только объяснить
- [FIX-ONLY] - только исправить конкретную ошибку

### АКТИВНЫЕ ДОКУМЕНТЫ

- README.md - техническая документация
- package.json - зависимости и скрипты
- prisma/schema.prisma - модели данных
- src/graphql/typedefs.ts - GraphQL схема
- .env - переменные окружения (не коммитить!)
- docker-compose.yml - настройки Docker
- src/lib/prisma.ts - клиент базы данных

### РАБОТА С КОНТЕКСТОМ

#### Файлы контекста:

- **current-session.md** - текущие задачи и решения
- **CLAUDE.md** - эти правила (загружаются автоматически)
- **TodoWrite** - инструмент для отслеживания задач

#### При потере контекста:

1. Прочитать current-session.md
2. Проверить TodoWrite
3. Спросить у пользователя о текущей задаче

---

# Важные напоминания для Claude Code

Делай только то, что просят; ни больше, ни меньше.
НИКОГДА не создавай файлы, если они не абсолютно необходимы для достижения цели.
ВСЕГДА отдавай предпочтение редактированию существующего файла, а не созданию нового.
НИКОГДА не создавай проактивно файлы документации (\*.md) или README файлы. Создавай файлы документации только по явной просьбе пользователя.
