sfera-new/docs/presentation-layer/URL_ROUTING_RULES.md

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

Дата создания: 28.08.2025
Статус: ✅ Активно
Связанные документы:

• COMPONENT_ARCHITECTURE.md
• DOMAIN_MODEL.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 автоматически перенаправляются на новые:

// Старый 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 роли происходит редирект:

/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:

// В 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 ЧЕРЕЗ КОММЕНТАРИИ

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

// Вариант 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