sfera-new/docs/INDEX.md

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

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

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

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

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

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

1. COMPONENT_ARCHITECTURE.md - Архитектура React компонентов
2. GRAPHQL_SCHEMA_RULES.md - Правила GraphQL API
3. PRISMA_MODEL_RULES.md - Структура базы данных

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

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

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

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

🔌 API_LAYER - Уровень API

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

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

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

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

Файл	Описание	Статус
PRISMA_MODEL_RULES.md	Правила Prisma моделей: структуры, связи, миграции	✅
DATABASE_PATTERNS.md	Паттерны работы с БД и производительность	📋 Планируется
MIGRATIONS_GUIDE.md	Руководство по безопасным миграциям	📋 Планируется

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

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

Файл	Описание	Статус
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	Домен фулфилмента: двойная система расходников, workflow	✅
SELLER_DOMAIN.md	Домен селлеров: маркетплейсы, рецептуры, изоляция данных	✅
WHOLESALE_DOMAIN.md	Домен поставщиков: каталог, входящие заказы, координация	✅
LOGIST_DOMAIN.md	Домен логистики: маршруты, ценообразование по объему	✅
MARKET_INTEGRATION_RULES.md	Интеграция с маркетплейсами: WB/Ozon API, валидация ключей	✅

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

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

Файл	Описание	Статус
SUPPLY_CHAIN_WORKFLOW.md	Цепочка поставок: 8 статусов, роли, переходы, реальные мутации	✅
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 - Архитектурные паттерны
2. DOMAIN_MODEL.md - Понимание доменных сущностей
3. Соответствующий 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 - Правила доступа

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

• Фулфилмент: FULFILLMENT_DOMAIN.md
• Селлеры: SELLER_DOMAIN.md
• Поставщики: WHOLESALE_DOMAIN.md
• Логистика: LOGIST_DOMAIN.md

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

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

• 4 типа организаций → DOMAIN_MODEL.md
• 8-статусная система → SUPPLY_CHAIN_WORKFLOW.md
• Двойные расходники → BUSINESS_RULES_CORE.md + FULFILLMENT_DOMAIN.md
• Модульная архитектура → COMPONENT_ARCHITECTURE.md

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

• GraphQL → GRAPHQL_SCHEMA_RULES.md
• Prisma/БД → PRISMA_MODEL_RULES.md
• React/Hooks → COMPONENT_ARCHITECTURE.md
• TypeScript → Все файлы содержат примеры типизации
• Маркетплейсы → MARKET_INTEGRATION_RULES.md
• Партнерство → PARTNERSHIP_SYSTEM.md

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

• Права доступа → BUSINESS_RULES_CORE.md
• Изоляция данных → Все organization-types/*.md файлы
• API безопасность → GRAPHQL_SCHEMA_RULES.md

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

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

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

• 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 Статус: Базовая архитектура завершена + углублена реальными примерами ✅