API Product Property Values - rubyhat/fastyshop-backend GitHub Wiki

🎯 Значения свойств товара (ProductPropertyValues API)

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

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

Значения свойств — это конкретные варианты характеристики товара, которые создаются вручную продавцом и затем прикрепляются к товарам.
Например:

  • Свойство: Цвет
    • Значения: Красный, Синий, Зелёный
  • Свойство: Объём
    • Значения: 250 мл, 500 мл, 1 л

Значения принадлежат ProductProperty и через них могут использоваться многократно разными товарами.

📄 Методы

🆕 POST /api/v1/product_property_values

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

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

Поле Тип Обязательный Пример
value string ✅ Красный
product_property_id UUID ✅ uuid-свойства

✅ Ответ (201 Created)

{
  "id": "1a2b...",
  "value": "Красный",
  "product_property_id": "property-uuid"
}

✅ Чек-лист

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

📋 Валидации

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

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

  • Значение создаётся только в контексте ProductProperty
  • Может быть прикреплено к множеству товаров
  • Используется в отображении характеристик товара

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

🎨 Кейс 1: Продавец добавляет "Красный" в список цветов

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

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

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

📂 GET /api/v1/product_property_values

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

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

Параметр Тип Обязательный Пример
product_property_id UUID ✅ uuid-свойства

✅ Ответ

[
  {
    "id": "val-1",
    "value": "Красный"
  },
  {
    "id": "val-2",
    "value": "Синий"
  }
]

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

🧾 Кейс 1: Отображение выпадающего списка в форме

Фронтенд показывает значения для выбора при добавлении товара.

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

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

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

  • value

✅ Ответ

{
  "id": "val-1",
  "value": "Бордовый"
}

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

🖊 Кейс 1: Исправление описки

Продавец случайно ввёл "Серыйй" вместо "Серый" и правит значение.

🗑 DELETE /api/v1/product_property_values/:id

Удаление значения (если не используется товарами)

✅ Ответ

{
  "message": "Значение удалено"
}

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

  • Удаление возможно только если значение не прикреплено к товарам
  • В будущем возможен soft-delete

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

🧹 Кейс 1: Удаление устаревшего значения

Продавец больше не использует "Фиолетовый" и удаляет его.

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

Если хотя бы один товар использует это значение — сервер вернёт ошибку 422.

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

Сущность Назначение
ProductPropertyValue Конкретное значение свойства
ProductProperty Родительское свойство
Product Использует значения через product_property_value_ids

📄 TODO / Идеи

  • Поддержка сортировки значений
  • Возможность указывать цвет/иконку (для визуализации)
  • Soft-delete и скрытие без удаления