sfera-new/EXCHANGE_MODULE_IMPLEMENTATION_RULES.md

# ПРАВИЛА ВНЕДРЕНИЯ МОДУЛЯ "БИРЖА" В СИСТЕМУ SFERA

## 🎯 ОБЗОР ЗАДАЧИ

**Цель:** Создание нового раздела "Биржа" во всех кабинетах с переносом функционала из раздела "Маркет"

**Принцип:** Модульная архитектура с безопасным рефакторингом и сохранением совместимости

## 📋 ДЕТАЛЬНЫЕ ПРАВИЛА РЕАЛИЗАЦИИ

### 1. СТРУКТУРНАЯ АРХИТЕКТУРА

#### 1.1 Создание модульной структуры:

```
src/components/exchange/           # Новый модуль Биржи
├── exchange-dashboard.tsx         # Главная страница Биржи
├── tabs/
│   ├── investments-tab.tsx        # Перенос из market/investments
│   └── market-tab.tsx             # Перенос из market/market
├── hooks/
│   ├── useExchangeData.ts         # Хуки для данных биржи
│   └── useInvestmentOperations.ts # Логика инвестиций
├── components/
│   ├── ExchangeHeader.tsx         # Заголовок раздела
│   └── ExchangeStats.tsx          # Статистика биржи
└── types/
    └── exchange.types.ts          # TypeScript интерфейы
```

#### 1.2 Обновление навигации:

```typescript
// src/components/dashboard/sidebar.tsx
const navigationItems = [
  // ... существующие пункты
  {
    name: 'Биржа',
    href: '/exchange',
    icon: TrendingUp, // или Zap, или BarChart3
    position: 'before-settings', // Над разделом настройки
  },
  // ... остальные пункты
]
```

### 2. БЕЗОПАСНЫЙ ПЕРЕНОС КОМПОНЕНТОВ

#### 2.1 Сохранение оригиналов:

```bash
# Создаем backup перед переносом
cp -r src/components/market/investments-tab.tsx src/components/market/investments-tab.tsx.backup
cp -r src/components/market/market-tab.tsx src/components/market/market-tab.tsx.backup
```

#### 2.2 Поэтапный перенос:

```typescript
// Этап 1: Создание алиасов (временно)
export { InvestmentsTab as ExchangeInvestmentsTab } from '../market/investments-tab'
export { MarketTab as ExchangeMarketTab } from '../market/market-tab'

// Этап 2: Копирование с адаптацией
// Этап 3: Обновление импортов
// Этап 4: Удаление дубликатов
```

### 3. МАРШРУТИЗАЦИЯ И URL

#### 3.1 Новая структура маршрутов:

```
/exchange                  # Главная страница Биржи
├── /exchange/investments  # Инвестиции (было /market/investments)
└── /exchange/market       # Маркет (было /market/market)

/market                    # Остается, но без investments и market
├── /market/logistics      # Остается
├── /market/analytics      # Остается
└── /market/other-tabs     # Остальные вкладки остаются
```

#### 3.2 Редиректы для совместимости:

```typescript
// src/middleware.ts или pages/_app.tsx
const redirectRules = [
  {
    from: '/market/investments',
    to: '/exchange/investments',
    permanent: true,
  },
  {
    from: '/market/market',
    to: '/exchange/market',
    permanent: true,
  },
]
```

### 4. УНИВЕРСАЛЬНОСТЬ ДЛЯ ВСЕХ КАБИНЕТОВ

#### 4.1 Роль-агностический подход:

```typescript
// src/components/exchange/exchange-dashboard.tsx
interface ExchangeDashboardProps {
  userRole: 'SELLER' | 'WHOLESALE' | 'FULFILLMENT' | 'LOGIST'
  // Компонент адаптируется под роль, но функционал одинаковый
}

const ExchangeDashboard: FC<ExchangeDashboardProps> = ({ userRole }) => {
  // Одинаковая логика для всех ролей
  return (
    <div className="exchange-dashboard">
      <ExchangeHeader userRole={userRole} />
      <ExchangeTabs userRole={userRole} />
    </div>
  )
}
```

#### 4.2 Единая конфигурация:

```typescript
// src/config/exchange.config.ts
export const EXCHANGE_CONFIG = {
  tabs: [
    {
      id: 'investments',
      name: 'Инвестиции',
      path: '/exchange/investments',
      availableFor: ['SELLER', 'WHOLESALE', 'FULFILLMENT', 'LOGIST'], // Все роли
    },
    {
      id: 'market',
      name: 'Маркет',
      path: '/exchange/market',
      availableFor: ['SELLER', 'WHOLESALE', 'FULFILLMENT', 'LOGIST'], // Все роли
    },
  ],
}
```

### 5. ИКОНКА И UI ЭЛЕМЕНТЫ

#### 5.1 Выбор иконки:

```typescript
import { TrendingUp } from 'lucide-react' // Основной вариант - рост, тренды
// Альтернативы:
// import { Zap } from 'lucide-react'          // Энергия, быстрота
// import { BarChart3 } from 'lucide-react'    // Аналитика, графики
// import { Activity } from 'lucide-react'     // Активность, пульс
```

#### 5.2 Стилизация в соответствии с дизайн-системой:

```typescript
// Используем существующую Glass Morphism систему
<div className="glass-card">
  <div className="flex items-center gap-3">
    <TrendingUp className="h-5 w-5 text-primary" />
    <span className="font-semibold">Биржа</span>
  </div>
</div>
```

### 6. БЕЗОПАСНОСТЬ И СОВМЕСТИМОСТЬ

#### 6.1 Проверка существующих зависимостей:

```bash
# Поиск всех ссылок на старые компоненты
grep -r "market/investments" src/
grep -r "market/market" src/
grep -r "/market/investments" src/
grep -r "/market/market" src/
```

#### 6.2 Градуальная миграция:

```typescript
// Временный мост-компонент
const MarketInvestmentsBridge: FC = () => {
  // Редирект на новый URL
  useEffect(() => {
    router.replace('/exchange/investments')
  }, [])

  return <div>Перенаправление на новую страницу...</div>
}
```

### 7. ТЕСТИРОВАНИЕ И ПРОВЕРКА

#### 7.1 Чек-лист проверки:

- [ ] Все ссылки работают корректно
- [ ] Редиректы функционируют
- [ ] Навигация обновлена во всех кабинетах
- [ ] Компоненты отображаются идентично
- [ ] Данные загружаются без ошибок
- [ ] TypeScript типы корректны

#### 7.2 Тестирование по ролям:

```typescript
const testScenarios = [
  { role: 'SELLER', path: '/exchange' },
  { role: 'WHOLESALE', path: '/exchange' },
  { role: 'FULFILLMENT', path: '/exchange' },
  { role: 'LOGIST', path: '/exchange' },
]
```

### 8. ГРАФQL И ДАННЫЕ

#### 8.1 Анализ существующих компонентов:

```typescript
// ✅ ОБНАРУЖЕНО: Компоненты НЕ ИСПОЛЬЗУЮТ GraphQL
// market-investments.tsx - статичные UI карточки
// market-business.tsx - статичные UI карточки
// Никаких useQuery/useMutation не найдено
```

#### 8.2 Стратегия переноса данных:

```typescript
// Компоненты используют только UI элементы:
// - Статичный контент
// - Иконки Lucide React
// - Glass Morphism карточки
// - Никаких внешних API вызовов
```

#### 8.3 Заключение по GraphQL:

- ❌ **GraphQL запросы НЕ НУЖНЫ** - компоненты статичные
- ✅ **Простой перенос** - только UI компоненты
- ✅ **Без изменений в resolvers** - данные не загружаются

### 9. ПЛАН ПОЭТАПНОЙ РЕАЛИЗАЦИИ

#### Фаза 1: Подготовка

1. Создание структуры папок
2. Анализ зависимостей
3. Создание TypeScript интерфейсов

#### Фаза 2: Создание компонентов

1. Копирование и адаптация существующих компонентов
2. Создание exchange-dashboard.tsx
3. Настройка навигации

#### Фаза 3: Интеграция

1. Обновление маршрутов
2. Настройка редиректов
3. Обновление импортов

#### Фаза 4: Тестирование и очистка

1. Тестирование всех сценариев
2. Удаление дубликатов
3. Финальная проверка

---

## ✅ ПОДТВЕРЖДЁННЫЕ РЕШЕНИЯ:

1. **Иконка:** ✅ `TrendingUp` подходит для раздела "Биржа"
2. **Позиционирование:** ✅ Размещать прямо перед Settings в сайдбаре
3. **GraphQL:** ✅ Изменения НЕ НУЖНЫ - компоненты статичные
4. **Уведомления:** ✅ НЕ показывать уведомления о переносе

## 🎯 ФИНАЛЬНАЯ АРХИТЕКТУРА:

### Структура переноса:

```
ИЗ: /market (4 вкладки)
├── investments ➜ /exchange/investments
├── business    ➜ /exchange/market
├── products    ➜ остается в /market
└── requests    ➜ остается в /market

В: /exchange (2 вкладки)
├── /exchange/investments (было: market-investments.tsx)
└── /exchange/market      (было: market-business.tsx)
```

### Обновление nav структуры:

```typescript
// sidebar.tsx порядок пунктов:
[Home, Supplies, Services, Exchange, Settings, ...]
//                          ↑ новый пункт
```

## 📊 СТАТУС РЕАЛИЗАЦИИ

**Текущий статус**: ✅ **ПОЛНОСТЬЮ РЕАЛИЗОВАНО**

**Дата завершения**: 22 августа 2025

### Выполненные фазы:

✅ **Фаза 1**: Создана структура папок `src/components/exchange/`
✅ **Фаза 2**: Скопированы и адаптированы компоненты из market  
✅ **Фаза 3**: Обновлена навигация и созданы маршруты
✅ **Фаза 4**: Протестировано и очищено

### Результат реализации:

- ✅ Раздел "Биржа" доступен во всех кабинетах с иконкой TrendingUp
- ✅ Перенесены вкладки "Инвестиции" и "Бизнес" из Маркета в Биржу
- ✅ Маркет теперь содержит только "Товары" и "Заявки"
- ✅ Сохранена полная функциональность без потери данных
- ✅ Безопасная реализация с резервными копиями
- ✅ Протестировано - dev сервер запускается корректно
- ✅ Типы TypeScript корректны

### Финальная структура:

```
src/components/exchange/
├── exchange-dashboard.tsx       ✅ Главная страница Биржи
├── tabs/
│   ├── investments-tab.tsx      ✅ Перенос из market-investments
│   └── business-tab.tsx         ✅ Перенос из market-business
├── types/
│   └── exchange.types.ts        ✅ TypeScript интерфейсы
└── index.ts                     ✅ Экспорты модуля

src/app/exchange/page.tsx        ✅ Next.js маршрут
```

**ЗАДАЧА ВЫПОЛНЕНА УСПЕШНО!** 🎉