# 📚 ИНДЕКС ДОКУМЕНТАЦИИ СИСТЕМЫ SFERA

> **Модульная архитектура правил, соответствующая структуре кода**

## 🚀 БЫСТРАЯ НАВИГАЦИЯ

### 🎯 НОВИЧКАМ В СИСТЕМЕ:

1. **[DOMAIN_MODEL.md](./core/DOMAIN_MODEL.md)** - Начните здесь: 4 типа организаций и основные сущности
2. **[BUSINESS_RULES_CORE.md](./core/BUSINESS_RULES_CORE.md)** - Ключевые бизнес-правила системы
3. **[SUPPLY_CHAIN_WORKFLOW.md](./business-processes/SUPPLY_CHAIN_WORKFLOW.md)** - 8-статусная система поставок

### 🛠️ РАЗРАБОТЧИКАМ:

1. **[COMPONENT_ARCHITECTURE.md](./presentation-layer/COMPONENT_ARCHITECTURE.md)** - Архитектура React компонентов
2. **[GRAPHQL_SCHEMA_RULES.md](./api-layer/GRAPHQL_SCHEMA_RULES.md)** - Правила GraphQL API
3. **[PRISMA_MODEL_RULES.md](./data-layer/PRISMA_MODEL_RULES.md)** - Структура базы данных

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

### 🎯 CORE - Ядро системы

Фундаментальные концепции и бизнес-правила.

| Файл                                                        | Описание                                               | Статус         |
| ----------------------------------------------------------- | ------------------------------------------------------ | -------------- |
| **[DOMAIN_MODEL.md](./core/DOMAIN_MODEL.md)**               | Доменная модель: 4 типа организаций, основные сущности | ✅             |
| **[BUSINESS_RULES_CORE.md](./core/BUSINESS_RULES_CORE.md)** | Ядро бизнес-правил: доступ, партнерство, расходники    | ✅             |
| `WORKFLOW_ENGINE_SPEC.md`                                   | Спецификация движка бизнес-процессов                   | 📋 Планируется |

### 🔌 API_LAYER - Уровень API

Правила и паттерны для GraphQL API.

| Файл                                                               | Описание                                         | Статус         |
| ------------------------------------------------------------------ | ------------------------------------------------ | -------------- |
| **[GRAPHQL_SCHEMA_RULES.md](./api-layer/GRAPHQL_SCHEMA_RULES.md)** | Правила GraphQL схемы: типы, enums, безопасность | ✅             |
| `RESOLVERS_PATTERNS.md`                                            | Паттерны резолверов и бизнес-логики              | 📋 Планируется |
| `API_CONTRACTS.md`                                                 | Контракты внешних API (WB, Ozon)                 | 📋 Планируется |

### 💾 DATA_LAYER - Уровень данных

Правила работы с базой данных и моделями.

| Файл                                                            | Описание                                           | Статус         |
| --------------------------------------------------------------- | -------------------------------------------------- | -------------- |
| **[PRISMA_MODEL_RULES.md](./data-layer/PRISMA_MODEL_RULES.md)** | Правила Prisma моделей: структуры, связи, миграции | ✅             |
| `DATABASE_PATTERNS.md`                                          | Паттерны работы с БД и производительность          | 📋 Планируется |
| `MIGRATIONS_GUIDE.md`                                           | Руководство по безопасным миграциям                | 📋 Планируется |

### 🎨 PRESENTATION_LAYER - Уровень представления

Архитектура фронтенда и UI компонентов.

| Файл                                                                            | Описание                                                    | Статус         |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------- | -------------- |
| **[COMPONENT_ARCHITECTURE.md](./presentation-layer/COMPONENT_ARCHITECTURE.md)** | Архитектура React компонентов: модульность, hooks, patterns | ✅             |
| `HOOKS_PATTERNS.md`                                                             | Паттерны custom hooks и управления состоянием               | 📋 Планируется |
| `UI_COMPONENT_RULES.md`                                                         | Правила UI компонентов на базе shadcn/ui                    | 📋 Планируется |
| `STATE_MANAGEMENT.md`                                                           | Управление состоянием приложения                            | 📋 Планируется |

### 🏢 ORGANIZATION_TYPES - Домены по типам организаций

Специфические правила для каждого типа участников.

| Файл                                                                                | Описание                                                   | Статус |
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------ |
| **[FULFILLMENT_DOMAIN.md](./organization-types/FULFILLMENT_DOMAIN.md)**             | Домен фулфилмента: двойная система расходников, workflow   | ✅     |
| **[SELLER_DOMAIN.md](./organization-types/SELLER_DOMAIN.md)**                       | Домен селлеров: маркетплейсы, рецептуры, изоляция данных   | ✅     |
| **[WHOLESALE_DOMAIN.md](./organization-types/WHOLESALE_DOMAIN.md)**                 | Домен поставщиков: каталог, входящие заказы, координация   | ✅     |
| **[LOGIST_DOMAIN.md](./organization-types/LOGIST_DOMAIN.md)**                       | Домен логистики: маршруты, ценообразование по объему       | ✅     |
| **[MARKET_INTEGRATION_RULES.md](./organization-types/MARKET_INTEGRATION_RULES.md)** | Интеграция с маркетплейсами: WB/Ozon API, валидация ключей | ✅     |

### 🔄 BUSINESS_PROCESSES - Бизнес-процессы

Детальное описание ключевых бизнес-процессов системы.

| Файл                                                                                    | Описание                                                         | Статус         |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------- |
| **[SUPPLY_CHAIN_WORKFLOW.md](./business-processes/SUPPLY_CHAIN_WORKFLOW.md)**           | Цепочка поставок: 8 статусов, роли, переходы, реальные мутации   | ✅             |
| **[SUPPLY_DATA_SECURITY_RULES.md](./business-processes/SUPPLY_DATA_SECURITY_RULES.md)** | 🔐 Безопасность данных в поставках: изоляция, фильтрация, аудит  | ✅ NEW         |
| **[PARTNERSHIP_SYSTEM.md](./business-processes/PARTNERSHIP_SYSTEM.md)**                 | Система партнерства: заявки, автопартнерство, реферальные бонусы | ✅             |
| `REFERRAL_MECHANICS.md`                                                                 | Механика реферальной системы                                     | 📋 Планируется |

### 🛠️ DEVELOPMENT - Разработка

Правила разработки, тестирования и развертывания.

| Файл                            | Описание                                       | Статус         |
| ------------------------------- | ---------------------------------------------- | -------------- |
| `MODULAR_ARCHITECTURE_GUIDE.md` | Детальное руководство по модульной архитектуре | 📋 Планируется |
| `CODING_STANDARDS.md`           | Стандарты кодирования TypeScript/React         | 📋 Планируется |
| `TESTING_PATTERNS.md`           | Паттерны тестирования компонентов и API        | 📋 Планируется |
| `DEPLOYMENT_RULES.md`           | Правила развертывания и CI/CD                  | 📋 Планируется |

### 🔧 INFRASTRUCTURE - Инфраструктура

Системная архитектура и инфраструктурные решения.

| Файл                       | Описание                                         | Статус         |
| -------------------------- | ------------------------------------------------ | -------------- |
| `SERVICES_ARCHITECTURE.md` | Архитектура сервисов: SMS, marketplace APIs      | 📋 Планируется |
| `REALTIME_SYSTEM.md`       | Real-time система: GraphQL subscriptions         | 📋 Планируется |
| `SECURITY_RULES.md`        | Правила безопасности: JWT, шифрование API ключей | 📋 Планируется |

## 🎯 ИСПОЛЬЗОВАНИЕ ПО ЗАДАЧАМ

### 📝 СОЗДАНИЕ НОВЫХ КОМПОНЕНТОВ:

1. **[COMPONENT_ARCHITECTURE.md](./presentation-layer/COMPONENT_ARCHITECTURE.md)** - Архитектурные паттерны
2. **[DOMAIN_MODEL.md](./core/DOMAIN_MODEL.md)** - Понимание доменных сущностей
3. Соответствующий **organization-types/\*.md** - Специфика типа организации

### 🔧 РАБОТА С API:

1. **[GRAPHQL_SCHEMA_RULES.md](./api-layer/GRAPHQL_SCHEMA_RULES.md)** - Правила схемы
2. **[BUSINESS_RULES_CORE.md](./core/BUSINESS_RULES_CORE.md)** - Бизнес-логика
3. **[PRISMA_MODEL_RULES.md](./data-layer/PRISMA_MODEL_RULES.md)** - Модели данных

### 🚚 WORKFLOW ПОСТАВОК:

1. **[SUPPLY_CHAIN_WORKFLOW.md](./business-processes/SUPPLY_CHAIN_WORKFLOW.md)** - Полный процесс
2. Релевантные **organization-types/\*.md** - Роли участников
3. **[BUSINESS_RULES_CORE.md](./core/BUSINESS_RULES_CORE.md)** - Правила доступа

### 🏢 СПЕЦИФИКА ОРГАНИЗАЦИЙ:

- **Фулфилмент**: [FULFILLMENT_DOMAIN.md](./organization-types/FULFILLMENT_DOMAIN.md)
- **Селлеры**: [SELLER_DOMAIN.md](./organization-types/SELLER_DOMAIN.md)
- **Поставщики**: [WHOLESALE_DOMAIN.md](./organization-types/WHOLESALE_DOMAIN.md)
- **Логистика**: [LOGIST_DOMAIN.md](./organization-types/LOGIST_DOMAIN.md)

## 🔍 ПОИСК ПО ТЕМАМ

### 🔑 КЛЮЧЕВЫЕ КОНЦЕПЦИИ:

- **4 типа организаций** → [DOMAIN_MODEL.md](./core/DOMAIN_MODEL.md)
- **8-статусная система** → [SUPPLY_CHAIN_WORKFLOW.md](./business-processes/SUPPLY_CHAIN_WORKFLOW.md)
- **Двойные расходники** → [BUSINESS_RULES_CORE.md](./core/BUSINESS_RULES_CORE.md) + [FULFILLMENT_DOMAIN.md](./organization-types/FULFILLMENT_DOMAIN.md)
- **Модульная архитектура** → [COMPONENT_ARCHITECTURE.md](./presentation-layer/COMPONENT_ARCHITECTURE.md)

### 💻 ТЕХНИЧЕСКИЕ ТЕМЫ:

- **GraphQL** → [GRAPHQL_SCHEMA_RULES.md](./api-layer/GRAPHQL_SCHEMA_RULES.md)
- **Prisma/БД** → [PRISMA_MODEL_RULES.md](./data-layer/PRISMA_MODEL_RULES.md)
- **React/Hooks** → [COMPONENT_ARCHITECTURE.md](./presentation-layer/COMPONENT_ARCHITECTURE.md)
- **TypeScript** → Все файлы содержат примеры типизации
- **Маркетплейсы** → [MARKET_INTEGRATION_RULES.md](./organization-types/MARKET_INTEGRATION_RULES.md)
- **Партнерство** → [PARTNERSHIP_SYSTEM.md](./business-processes/PARTNERSHIP_SYSTEM.md)

### 🔒 БЕЗОПАСНОСТЬ И ДОСТУП:

- **Права доступа** → [BUSINESS_RULES_CORE.md](./core/BUSINESS_RULES_CORE.md)
- **Изоляция данных** → Все **organization-types/\*.md** файлы
- **Безопасность коммерческих данных** → [SUPPLY_DATA_SECURITY_RULES.md](./business-processes/SUPPLY_DATA_SECURITY_RULES.md) 🔐
- **API безопасность** → [GRAPHQL_SCHEMA_RULES.md](./api-layer/GRAPHQL_SCHEMA_RULES.md)

## 📈 СТАТУС И ПРОГРЕСС

### ✅ ЗАВЕРШЕННЫЕ РАЗДЕЛЫ (12 файлов):

Базовая архитектура документации полностью готова + углубленная функциональность:

- **Core**: Доменная модель + углубленные бизнес-правила с реальным кодом
- **API Layer**: GraphQL правила с примерами resolver'ов
- **Data Layer**: Prisma модели
- **Presentation Layer**: Архитектура компонентов с модульными паттернами
- **Organization Types**: Все 4 типа + интеграция с маркетплейсами
- **Business Processes**: Workflow поставок + система партнерства + безопасность данных

### 📋 ПЛАНИРУЕМЫЕ РАЗДЕЛЫ:

- Детализация разработки и инфраструктуры
- Практические руководства и примеры
- Детальная механика реферальной системы
- Паттерны тестирования и развертывания

## 🎯 ПРИНЦИПЫ ДОКУМЕНТАЦИИ

### 1. **СООТВЕТСТВИЕ КОДУ**

Каждое правило основано на анализе реального кода системы.

### 2. **МОДУЛЬНОСТЬ**

Документация структурирована по архитектурным слоям.

### 3. **ТРАССИРУЕМОСТЬ**

Явная связь между правилами и кодом (ссылки на файлы и функции).

### 4. **ПРАКТИЧНОСТЬ**

Конкретные примеры и паттерны для повседневной работы.

### 5. **РАЗВИВАЕМОСТЬ**

Легко добавлять новые правила и расширения.

---

## 🔗 СВЯЗАННЫЕ РЕСУРСЫ

- **Legacy правила**: `/legacy-rules/` (архивные файлы)
- **Архитектурный стандарт**: `/MODULAR_ARCHITECTURE_PATTERN.md`
- **Документы проекта**: `/docs-and-reports/`

---

_Создано: 2025-08-21_  
_На основе анализа реального кода системы SFERA_  
_Обновлено: 2025-08-21_
_Статус: Базовая архитектура завершена + углублена реальными примерами ✅_