# 📋 ПРАВИЛА URL И МАРШРУТИЗАЦИИ СИСТЕМЫ SFERA

> **Дата создания**: 28.08.2025  
> **Статус**: ✅ Активно  
> **Связанные документы**:
>
> - [COMPONENT_ARCHITECTURE.md](./COMPONENT_ARCHITECTURE.md)
> - [DOMAIN_MODEL.md](../core/DOMAIN_MODEL.md)
> - [SIDEBAR_ARCHITECTURE_RULES.md](./SIDEBAR_ARCHITECTURE_RULES.md)

## 🎯 ОСНОВНЫЕ ПРИНЦИПЫ

### ФОРМУЛА URL

```
/{role}/{domain}/{section}/{view}
```

### КЛЮЧЕВЫЕ ПРАВИЛА

1. **РОЛЕВОЕ РАЗДЕЛЕНИЕ**
   - Каждая роль имеет свой базовый путь
   - `/seller` - кабинет селлера
   - `/fulfillment` - кабинет фулфилмента
   - `/wholesale` - кабинет поставщика
   - `/logistics` - кабинет логистики

2. **ИЕРАРХИЧЕСКАЯ СТРУКТУРА**
   - От общего к частному
   - Максимум 4 уровня вложенности

3. **ИМЕНОВАНИЕ**
   - Английские термины
   - Множественное число для коллекций: `supplies/`, `orders/`
   - Единственное число для действий: `create/`
   - Дефисы для составных слов: `seller-consumables`

---

## 🏢 URL ПО РОЛЯМ

### 🛒 SELLER (Селлер)

```
/seller/
├── home                               # Главная селлера
├── supplies/                           # Поставки селлера
│   ├── goods/                         # Товары селлера → склад ФФ
│   │   ├── cards                     # Вид: карточки товаров
│   │   └── suppliers                 # Вид: по поставщикам
│   ├── consumables                   # Расходники селлера → склад ФФ
│   └── marketplace/                  # Поставки на маркетплейсы
│       ├── wildberries               # Поставки на WB
│       └── ozon                     # Поставки на Ozon
├── warehouse/                        # Складские операции селлера
│   ├── fulfillment                  # Склад фулфилмент (данные из ФФ)
│   ├── wildberries                  # Склад Wildberries
│   └── storage                      # Мой склад
├── create/                           # Создание поставок
│   ├── goods                        # Создать поставку товаров
│   └── consumables                  # Создать поставку расходников
├── statistics                       # Статистика селлера
├── messenger                        # Мессенджер
├── economics                        # Экономика
├── partners                         # Партнёры
├── market                          # Маркет
├── exchange                        # Биржа
└── settings                        # Настройки
```

**Примеры URL:**

- `/seller/home` - главная страница селлера
- `/seller/supplies/goods/cards` - товары-карточки
- `/seller/supplies/consumables` - расходники селлера
- `/seller/supplies/marketplace/wildberries` - поставки на WB
- `/seller/warehouse/fulfillment` - склад фулфилмент
- `/seller/warehouse/wildberries` - склад Wildberries
- `/seller/warehouse/storage` - мой склад
- `/seller/create/consumables` - создание расходников

### 🏭 FULFILLMENT (Фулфилмент)

```
/fulfillment/
├── home                              # Главная фулфилмента
├── supplies/                         # Входящие поставки на ФФ
│   ├── goods/                       # Товары от селлеров
│   │   ├── new                     # Новые поставки
│   │   ├── receiving               # Ожидают приемки
│   │   └── received                # Принятые на склад
│   ├── consumables                 # Расходники ФФ
│   └── seller-consumables          # Расходники селлеров (на хранении)
├── warehouse/                       # Главная складских операций
│   └── fulfillment-consumables/     # Подраздел: расходники фулфилмента
├── create/                         # Создание заказов ФФ
│   └── consumables                 # Заказ расходников ФФ
└── statistics                      # Статистика фулфилмента
```

**Примеры URL:**

- `/fulfillment/home` - главная страница фулфилмента
- `/fulfillment/supplies/goods/receiving` - товары на приемке
- `/fulfillment/supplies/consumables` - расходники ФФ
- `/fulfillment/supplies/seller-consumables` - расходники селлеров
- `/fulfillment/warehouse` - главная складских операций
- `/fulfillment/warehouse/fulfillment-consumables` - расходники фулфилмента

### 🏪 WHOLESALE (Поставщик)

```
/wholesale/
├── home                             # Главная поставщика
├── orders/                          # Входящие заказы (единый раздел)
│   └── (включает товары + расходники ФФ + расходники селлеров)
├── catalog/                        # Каталог товаров поставщика
│   ├── goods                      # Товары для продажи
│   └── consumables                # Расходники
└── statistics                     # Статистика поставщика
```

**Примеры URL:**

- `/wholesale/home` - главная страница поставщика
- `/wholesale/orders` - все входящие заказы
- `/wholesale/catalog/goods` - каталог товаров
- `/wholesale/catalog/consumables` - каталог расходников

### 🚛 LOGISTICS (Логистика)

```
/logistics/
├── home                             # 🏠 Главная логистики
├── orders/                          # 🚛 Перевозки (логистические заказы)
│   ├── pending                      # Ожидают подтверждения
│   ├── confirmed                    # Подтвержденные
│   ├── in-transit                   # В пути
│   └── delivered                    # Доставленные
├── messenger                        # 💬 Мессенджер
├── economics                        # 💰 Экономика
├── partners                         # 🤝 Партнёры
├── market                           # 🏪 Маркет
├── exchange                         # 📈 Биржа
├── routes                           # 🗺️ Управление маршрутами
└── settings                         # ⚙️ Настройки
```

**Примеры URL (в порядке сайдбара):**

- `/logistics/home` - 🏠 главная страница логистики
- `/logistics/orders/pending` - 🚛 ожидающие заказы (перевозки)
- `/logistics/messenger` - 💬 мессенджер логиста
- `/logistics/economics` - 💰 экономика логистической компании
- `/logistics/partners` - 🤝 партнёры логистики
- `/logistics/market` - 🏪 маркет логистических услуг
- `/logistics/exchange` - 📈 биржа логистических услуг
- `/logistics/settings` - ⚙️ настройки профиля

---

## 🔄 РЕДИРЕКТЫ ДЛЯ СОВМЕСТИМОСТИ

Старые URL автоматически перенаправляются на новые:

```typescript
// Старый URL → Новый URL
/supplies → /seller/supplies/goods/cards
/fulfillment-supplies → /fulfillment/supplies/goods/receiving
/supplier-orders → /wholesale/orders
/logistics-orders → /logistics/orders/pending
/home → ролевой редирект на /[role]/home
```

---

## 📏 ТЕХНИЧЕСКИЕ ДЕТАЛИ РЕАЛИЗАЦИИ

### ДЕФОЛТНЫЕ СТРАНИЦЫ

При переходе на корневой URL роли происходит редирект:

```typescript
/seller → /seller/home
/fulfillment → /fulfillment/home
/wholesale → /wholesale/home
/logistics → /logistics/home
```

### СТРУКТУРА ФАЙЛОВ

```
src/app/
├── seller/
│   ├── page.tsx                    # Редирект на дефолтную страницу
│   ├── supplies/
│   │   ├── page.tsx                # Редирект на goods/cards
│   │   ├── goods/
│   │   │   ├── page.tsx           # Редирект на cards
│   │   │   ├── cards/page.tsx     # Основная страница
│   │   │   └── suppliers/page.tsx
│   │   └── consumables/page.tsx
│   └── create/...
├── fulfillment/...
├── wholesale/...
└── logistics/...
```

### ОБРАБОТКА НАВИГАЦИИ В КОМПОНЕНТАХ

Компоненты определяют активные табы на основе текущего URL:

```typescript
// В supplies-dashboard.tsx
useEffect(() => {
  const currentPath = window.location.pathname

  if (currentPath.includes('/seller/supplies/goods/cards')) {
    setActiveTab('fulfillment')
    setActiveSubTab('goods')
    setActiveThirdTab('cards')
  }
  // ... другие проверки
}, [])
```

---

## 🚀 ПРЕИМУЩЕСТВА СИСТЕМЫ

1. **SEO-оптимизация** - понятные и описательные URL
2. **Масштабируемость** - легко добавлять новые разделы
3. **Навигация** - интуитивная структура для пользователей
4. **Аналитика** - точное отслеживание путей пользователей
5. **Поддержка** - четкое соответствие бизнес-логике

---

## ⚠️ ВАЖНЫЕ ЗАМЕЧАНИЯ

1. **V1/V2 автоопределение** - система поставок автоматически определяет версию данных, но URL остается единым
2. **Права доступа** - URL проверяются на уровне middleware для соответствия роли пользователя
3. **Локализация** - URL остаются на английском, перевод только в UI
4. **Sidebar изоляция** - каждая роль имеет отдельный sidebar компонент (см. SIDEBAR_ARCHITECTURE_RULES.md)

---

## 🔄 МИГРАЦИЯ V1 → V2 С ROLLBACK

### СИСТЕМА ROLLBACK ЧЕРЕЗ КОММЕНТАРИИ

Все критические компоненты содержат закомментированные старые версии для быстрого отката:

```typescript
// Вариант 1: Новый URL (активный)
router.push('/fulfillment/supplies/detailed-supplies')

// Вариант 2: Старый URL (для отката)
// router.push('/fulfillment-supplies/detailed-supplies')
```

### КОМПОНЕНТЫ С ROLLBACK:

- `create-fulfillment-consumables-supply-v2.tsx`
- `modular-version.tsx`
- `monolithic-version.tsx`
- `seller-modular-version.tsx`
- `multilevel-supplies-table/index.tsx`

### КОМАНДЫ ROLLBACK:

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

---

## 📝 ИСТОРИЯ ИЗМЕНЕНИЙ

| Дата       | Версия | Описание                                 | Автор |
| ---------- | ------ | ---------------------------------------- | ----- |
| 28.08.2025 | 1.0    | Первая версия правил URL                 | AI    |
| 28.08.2025 | 1.1    | Миграция /supplies → /seller             | AI    |
| 28.08.2025 | 1.2    | Связь с SIDEBAR_ARCHITECTURE_RULES.md    | AI    |
| 30.08.2025 | 2.0    | Полная миграция V1→V2 + rollback система | AI    |
