API Carts - rubyhat/fastyshop-backend GitHub Wiki

🛒 Корзина пользователя (Carts API)

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

У каждого пользователя одна корзина на каждый магазин, автоматически создаваемая при первом использовании.

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

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

  • В корзине могут находиться товары из одного магазина
  • Если пользователь добавляет товар из другого магазина — старая корзина очищается
  • Каждый товар в корзине — это CartItem, с полем quantity и price_snapshot
  • Количество можно изменить, позицию — удалить
  • Цена на момент добавления фиксируется. (Нужно подумать, нужно ли это покупателю? Только если показывать. что цена изменилась с момента добавления в корзину.)
  • Пока товар(Product) не оформлен в заказ(Order) стоимость должна изменяться в корзине(Cart), если была изменена в карточке товара (Product)

📄 Методы

🆕 POST /api/v1/carts/add_item

Добавление товара в корзину

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

Поле Тип Обязательный Пример
product_id UUID ✅ prod-uuid
quantity number ✅ 2

✅ Ответ (200 OK)

{
  "message": "Товар добавлен в корзину",
  "cart": {
    "id": "cart-uuid",
    "items_count": 1,
    "total_quantity": 2
  }
}

✅ Чек-лист

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

📋 Валидации

  • quantity > 0
  • Нельзя добавить более, чем есть на складе
  • Все товары в корзине — из одного магазина

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

  • Если товар уже в корзине — увеличивается количество
  • Если товар из другого магазина — корзина очищается
  • Цена фиксируется при добавлении

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

➕ Кейс 1: Добавление нового товара

Пользователь выбирает товар и нажимает кнопку "Добавить в корзину".

🔁 Кейс 2: Повторное добавление того же товара

Количество увеличивается.

🧼 Кейс 3: Очистка при смене магазина

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

📂 GET /api/v1/carts

Получение текущей корзины пользователя

✅ Ответ

{
  "id": "cart-uuid",
  "items": [
    {
      "product": {
        "id": "prod-1",
        "title": "Кресло",
        "price": 14900
      },
      "quantity": 2,
      "price_snapshot": 14900
    }
  ],
  "total_quantity": 2,
  "items_count": 1
}

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

🛒 Кейс 1: Отображение корзины перед оформлением заказа

Пользователь открывает корзину и видит, что он выбрал.

✏️ PATCH /api/v1/carts/update_item

Изменение количества товара

🔹 Входные поля

Поле Тип Обязательный Пример
product_id UUID ✅ prod-1
quantity number ✅ 3

✅ Ответ

{
  "message": "Количество обновлено",
  "cart": {
    "total_quantity": 3
  }
}

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

🔢 Кейс 1: Изменение количества

Пользователь меняет 2 → 3 шт.

❌ Кейс 2: Установка quantity = 0

Товар удаляется из корзины.

🗑 DELETE /api/v1/carts/remove_item

Удаление товара из корзины

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

Поле Тип Обязательный Пример
product_id UUID ✅ prod-1

✅ Ответ

{
  "message": "Товар удалён из корзины"
}

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

🗑 Кейс 1: Удаление по кнопке "удалить"

Пользователь удаляет товар, который ему больше не нужен.

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

Сущность Назначение
Cart Корзина пользователя
CartItem Строка в корзине
Product Продукт, который добавляется
User Владелец корзины

📄 TODO / Идеи

  • Гостевая корзина (в cookies)
  • Сессия корзины через Redis
  • Купоны и промокоды
  • Мульти-магазинные корзины