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 Обновление навигации:

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

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

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

# Создаем 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 Поэтапный перенос:

// Этап 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 Редиректы для совместимости:

// 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 Роль-агностический подход:

// 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 Единая конфигурация:

// 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 Выбор иконки:

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

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

// Используем существующую 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 Проверка существующих зависимостей:

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

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

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

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

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

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

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

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

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

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

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

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

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

// Компоненты используют только 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 структуры:

// 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 маршрут

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