API Product Categories - rubyhat/fastyshop-backend GitHub Wiki

🧱 Категории товаров (ProductCategories API)

Контроллер: Api::V1::ProductCategoriesController
Версия: v1
Слой: Аутентифицированный API
Все действия доступны только авторизованным продавцам, работающим в рамках одного магазина.
Категории организованы в виде дерева (вложенность до 3 уровней, не более 20 подкатегорий на уровне).

📘 Общая логика

  • Категории используются для организации каталога товаров и услуг в рамках конкретного магазина
  • У каждой категории есть:
    • title — название
    • level — уровень вложенности (0, 1, 2)
    • parent_id — родительская категория
  • Максимальная глубина дерева — 3 уровня
  • Максимум подкатегорий у родителя — 20 штук
  • Категории нельзя переиспользовать между магазинами

📄 Методы

🆕 POST /api/v1/product_categories

Создание новой категории в магазине

🔹 Входные параметры

Поле Тип Обязательный Пример
title string ✅ Аксессуары
parent_id UUID ❌ (для вложенной)
shop_id UUID ✅ (ID магазина)

✅ Ответ (201 Created)

{
  "id": "b871...",
  "title": "Аксессуары",
  "level": 1,
  "parent_id": "8f7d..."
}

✅ Чек-лист

Пункт Значение
🔒 Требуется access token ✅ Да
🔐 Политики доступа Только продавец-владелец магазина и суперадмины
🔗 Зависимости Магазин, родительская категория (если есть)

📋 Валидации

  • Уникальность title внутри магазина
  • parent_id должен принадлежать тому же магазину
  • Глубина дерева ≤ 3
  • У родителя не более 20 дочерних категорий

📚 Кейсы использования

📦 Кейс 1: Продавец добавляет корневую категорию

Продавец указывает title и shop_id, не указывая parent_id. Категория создаётся на уровне 0.

🧲 Кейс 2: Добавление подкатегории

Продавец указывает parent_id на существующую категорию. Получается вложенная категория 1 уровня.

🚫 Кейс 3: Ошибка превышения уровня вложенности

При попытке создать подкатегорию 4 уровня сервер возвращает 422 с ошибкой: "Максимальный уровень вложенности — 3".

📂 GET /api/v1/product_categories

Получение дерева всех категорий для одного магазина

🔹 Параметры запроса

Параметр Тип Обязательный Пример
shop_id UUID ✅ shop-uuid-1

✅ Ответ

[
  {
    "id": "1",
    "title": "Мебель",
    "level": 0,
    "children": [
      {
        "id": "2",
        "title": "Диваны",
        "level": 1,
        "children": []
      }
    ]
  }
]

📚 Кейсы использования

🗺 Кейс 1: Отображение дерева категорий

Продавец открывает админ-панель и получает полное дерево категорий своего магазина для отображения в UI.

🔍 Кейс 2: Поиск категории при создании товара

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

✏️ PATCH /api/v1/product_categories/:id

Редактирование названия категории

✅ Ответ

{
  "id": "2",
  "title": "Новая подкатегория"
}

📚 Кейсы использования

🖊 Кейс 1: Продавец переименовывает подкатегорию

Название подкатегории изменилось на более понятное, сервер возвращает обновлённые данные.

🗑 DELETE /api/v1/product_categories/:id

Удаление категории (если в ней нет товаров и подкатегорий)

✅ Ответ

{
  "message": "Категория успешно удалена"
}

📚 Кейсы использования

🧹 Кейс 1: Удаление пустой категории

Продавец больше не использует категорию и удаляет её — в ней нет товаров или вложенных подкатегорий.

⚠️ Кейс 2: Ошибка при удалении

Сервер возвращает ошибку 422, если есть хотя бы один связанный товар или подкатегория.

🧩 Связанные сущности

Сущность Назначение
ProductCategory Дерево категорий товаров
Shop Владелец категорий
Product Связан через product_category_id

📄 TODO / Идеи

  • Drag & drop сортировка
  • Массовое удаление и перенос
  • Отображение количества товаров в категории