API Product Properties - rubyhat/fastyshop-backend GitHub Wiki

⚙️ Свойства товаров (ProductProperties API)

Контроллер: Api::V1::ProductPropertiesController
Версия: v1
Слой: Аутентифицированный API
Доступ только для авторизованных продавцов. Свойства создаются в рамках одного магазина и используются при создании/редактировании товаров и услуг.

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

Свойства описывают характеристики товара (например: цвет, размер, материал).
Каждое свойство принадлежит одному магазину и может быть использовано для одного или нескольких товаров.
Сами значения свойств (ProductPropertyValue) создаются отдельно и прикрепляются к свойствам.
Примеры свойств: "Цвет", "Материал", "Вес".

📄 Методы

🆕 POST /api/v1/product_properties

Создание свойства товара

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

Поле Тип Обязательный Пример
title string ✅ Цвет
shop_id UUID ✅ shop-uuid-123

✅ Ответ (201 Created)

{
  "id": "1a2b...",
  "title": "Цвет",
  "shop_id": "shop-uuid-123"
}

✅ Чек-лист

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

📋 Валидации

  • title: обязательный
  • title: уникален в рамках магазина
  • title: не длиннее 100 символов

💼 Бизнес-логика

  • Свойство создаётся только в рамках одного магазина
  • Может быть привязано к товарам через значения (ProductPropertyValue)
  • Используется в UI для отображения характеристик и фильтрации

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

🏷️ Кейс 1: Продавец создаёт новое свойство

Продавец создает свойство “Цвет” для группы товаров в магазине.

🧮 Кейс 2: Подготовка к массовой загрузке товаров

Свойства создаются заранее, чтобы позже можно было добавлять значения и связывать с товарами.

📂 GET /api/v1/product_properties

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

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

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

✅ Ответ

[
  {
    "id": "1a2b...",
    "title": "Цвет"
  },
  {
    "id": "2b3c...",
    "title": "Размер"
  }
]

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

📋 Кейс 1: Заполнение фильтров в админке

Продавец выбирает из списка доступных свойств для добавления к товару.

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

Редактирование свойства

🔹 Поддерживаемые поля

Поле Тип Обязательный Пример
title string ✅ Материал

✅ Ответ

{
  "id": "1a2b...",
  "title": "Материал"
}

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

🖊 Кейс 1: Переименование свойства

Продавец меняет название свойства “Материал изделия” на “Материал”.

🗑 DELETE /api/v1/product_properties/:id

Удаление свойства (если нет связанных значений)

✅ Ответ

{
  "message": "Свойство успешно удалено"
}

💼 Бизнес-логика

  • Проверка отсутствия связанных ProductPropertyValue
  • В будущем возможна реализация soft-delete

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

🧹 Кейс 1: Удаление неиспользуемого свойства

Продавец удаляет свойство, которое не содержит значений и больше не будет использоваться.

⚠️ Кейс 2: Ошибка при наличии связей

Если есть связанные значения, сервер возвращает ошибку 422 Unprocessable Entity.

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

Сущность Назначение
ProductProperty Свойство, создаваемое продавцом
ProductPropertyValue Значения свойства
Shop Контекст, в котором живёт свойство
Product Связывается через значения

📄 TODO / Идеи

  • Поддержка типизированных свойств (число, строка, список)
  • Свойства для фильтрации на клиенте
  • Множественные значения (например: Цвет — Красный и Синий)
  • Порядок отображения
  • При создании нового Product автоматически подгружать все свойства, которые создавались в этой категории товаров (?) Или дать возможность пользователю "Сохранить этой свойство для всех последующих создаваемых товаров" (?)