API Orders - rubyhat/fastyshop-backend GitHub Wiki

📦 Заказы (Orders API)

Контроллер: Api::V1::OrdersController
Версия: v1
Слой: Аутентифицированный API
Доступ для покупателей (создание, просмотр), продавцов (просмотр заказов своего магазина) и администраторов.

Заказ создаётся на основе корзины пользователя. Покупатели и продавцы могут просматривать свои заказы.

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

  • Заказ создаётся на основе текущей корзины пользователя
  • Копируются товары (price_snapshot), адрес (UserAddress)
  • Один заказ — один магазин
  • После создания корзина очищается, а остатки на складе уменьшаются
  • Статус заказа изменяется по строгой последовательности
  • Пользователь может отменить заказ, если он еще не был отправлен на доставку, обязательно указать комментарий причины отмены
  • Продавец может отменить заказ, если он еще не был отправлен на доставку
  • Если товар был оплачен онлайн, но еще не доставлен - кто, когда и как может отменить заказ?

📄 Методы

🆕 POST /api/v1/orders/create_from_cart

Создание нового заказа из корзины

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

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

✅ Ответ

{
  "id": "order-uuid",
  "shop_id": "shop-uuid",
  "status": "new",
  "total_price": 19800,
  "products": [
    {
      "id": "prod-uuid",
      "title": "Кресло",
      "quantity": 1,
      "price_snapshot": 19800
    }
  ]
}

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

  • Покупатель оформляет заказ на текущую корзину
  • Сервер копирует все данные и очищает корзину
  • При ошибке (нет корзины или адреса) — 422

📂 GET /api/v1/orders

Получение всех заказов текущего пользователя (или продавца)

🔹 Параметры

Параметр Тип Описание
role string buyer / seller (опц.)

✅ Ответ

[
  {
    "id": "order-uuid",
    "status": "new",
    "total_price": 25000,
    "shop": {
      "title": "Магазин"
    }
  }
]

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

  • Покупатель видит историю своих заказов
  • Продавец просматривает заказы на свои товары

🔍 GET /api/v1/orders/:id

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

✅ Ответ

{
  "id": "order-uuid",
  "status": "new",
  "user": {
    "id": "user-uuid",
    "phone": "+77001234567"
  },
  "products": [
    {
      "title": "Кресло",
      "quantity": 1,
      "price_snapshot": 19800
    }
  ]
}

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

  • Покупатель проверяет состав и статус своего заказа
  • Продавец видит данные покупателя и список позиций

✏️ PATCH /api/v1/orders/:id/update_status

Обновление статуса заказа

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

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

✅ Ответ

{
  "id": "order-uuid",
  "status": "accepted"
}

🧩 Бизнес-логика статусов

valid_transitions = {
  created: %i[accepted canceled_by_user canceled_by_seller],
  accepted: %i[delivery_in_progress ready_for_pickup canceled_by_user canceled_by_seller],
  delivery_in_progress: %i[completed canceled_by_seller],
  ready_for_pickup: %i[completed canceled_by_seller],
  completed: [],
  canceled_by_user: [],
  canceled_by_seller: []
}

В массиве i%[...] указаны статусы, которые доступны для смены для статуса, указанного в ключе объекта.

Например из created можно сменить на один из accepted canceled_by_user canceled_by_seller

  • Продавец может:
    • принять,
    • отправить на доставку,
    • отметить, что заказ готов к выдаче,
    • отметить, что заказ завершен
  • Покупатель может создать заказ и отменить

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

  • Продавец обрабатывает заказ и обновляет статус
  • Покупатель отменяет заказ до отправки на доставку

✅ Чек-лист

Пункт Значение
🔒 Требуется access token ✅ Да
🔐 Политики доступа По роли: покупатель / продавец
🔗 Зависимости Корзина, адрес, статус, роли

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

Сущность Назначение
Order Модель заказа
OrderItem Позиции в заказе
User Покупатель
Shop Продавец
Product Привязка через OrderItem
UserAddress Адрес, копируется в заказ

📄 TODO / Идеи

  • История изменения статусов
  • Интеграция с оплатой
  • Email / Telegram уведомления
  • Отзывы на заказы
  • Если товар был оплачен онлайн, но еще не доставлен - кто, когда и как может отменить заказ?