API User Addresses - rubyhat/fastyshop-backend GitHub Wiki

🏠 Адреса доставки пользователя (UserAddresses API)

Контроллер: Api::V1::UserAddressesController
Версия: v1
Слой: Аутентифицированный API
Все методы требуют access-токен

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

  • Каждый пользователь может создать до 10 адресов доставки
  • Один из адресов может быть установлен как адрес по умолчанию (is_default: true)
  • Адрес используется при оформлении заказа
  • Адрес принадлежит пользователю, CRUD только для владельца

📄 Методы

🆕 POST /api/v1/user_addresses

Создание нового адреса

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

Поле Тип Обязательный Пример
label string ✅ Дом
country_code string ✅ KZ
city string ✅ Алматы
street string ✅ Абая
house string ✅ 10
apartment string ❌ 15
postal_code string ❌ 050000
contact_name string ✅ Алексей
contact_phone string ✅ 77001112233
description string ❌ Вход со двора
is_default boolean ❌ true

✅ Ответ

{
  "id": "addr-uuid",
  "label": "Дом",
  "city": "Алматы",
  "street": "Абая",
  "is_default": true
}

✅ Чек-лист

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

📋 Валидации

  • Поля: label, city, street, contact_phone, contact_name, house
  • Проверка, что адресов не более 10
  • is_default: true может быть только у одного экземпляра

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

  • Добавление первого адреса (он станет is_default)
  • Добавление адреса офиса
  • Добавление больше 10 адресов — ошибка

📂 GET /api/v1/user_addresses

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

✅ Ответ

[
  {
    "id": "addr-1",
    "label": "Дом",
    "city": "Алматы",
    "is_default": true
  },
  {
    "id": "addr-2",
    "label": "Офис",
    "city": "Алматы",
    "is_default": false
  }
]

✅ Чек-лист

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

🔍 GET /api/v1/user_addresses/:id

Получить один адрес по ID

✅ Ответ

{
  "id": "addr-1",
  "label": "Дом",
  "city": "Алматы",
  "contact_name": "Алексей",
  "contact_phone": "77001112233"
}

✅ Чек-лист

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

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

  • Отображение адреса для редактирования
  • Ошибка 404, если адрес чужой или не существует

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

Обновление адреса

✅ Ответ

{
  "id": "addr-1",
  "label": "Дом",
  "city": "Астана",
  "is_default": true
}

✅ Чек-лист

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

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

  • Пользователь меняет адрес или номер телефона
  • Установка адреса как is_default заменяет предыдущий основной

🗑 DELETE /api/v1/user_addresses/:id

Удаление адреса

✅ Ответ

{
  "message": "Адрес успешно удален"
}

✅ Чек-лист

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

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

  • Удаление старого или неверного адреса
  • Удаление единственного адреса — без ошибок

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

Сущность Назначение
UserAddress Адрес доставки
UserAddressPolicy Контроль доступа
User Владелец адреса
Order Использует UserAddress при оформлении

📄 TODO / Идеи

  • Геолокация по адресу
  • Выбор адреса на карте
  • Ограничение по стране
  • Массовое удаление или экспорт