API Seller Profiles - rubyhat/fastyshop-backend GitHub Wiki

🛍️ Профиль продавца (SellerProfiles API)

Контроллер: Api::V1::SellerProfilesController
Версия: v1
Слой: Аутентифицированный API
Большинство методов требует авторизации, часть доступна публично (GET /users/:user_id/seller_profile)

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

Каждый пользователь может создать один SellerProfile, если он хочет продавать товары и услуги.
После создания продавец получает доступ к созданию юридических профилей (LegalProfile) и магазинов (Shop).
Публичный просмотр профиля доступен по user_id. Доступ к редактированию — только владельцу и администраторам.

📄 Методы

🆕 POST /api/v1/seller_profiles

Создание нового профиля продавца

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

Поле Тип Обязательный Пример
display_name string ✅ My Awesome Brand
description string ❌ Платформа уникальных товаров
logo_url string ❌ https://cdn/logo.png

✅ Ответ (201 Created)

{
  "id": "sp-uuid",
  "display_name": "My Awesome Brand",
  "slug": "my-awesome-brand",
  "description": "Платформа уникальных товаров",
  "user_id": "user-uuid"
}

✅ Чек-лист

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

📋 Валидации

  • display_name — обязательное, уникальное в системе
  • slug генерируется автоматически
  • Один профиль на одного пользователя

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

  • Проверка, что у пользователя нет уже SellerProfile
  • Присвоение user_id автоматически
  • Генерация slug на основе display_name
  • Продавец с SellerProfile может создавать юридические профили и магазины

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

🆕 Кейс 1: Продавец создаёт первый профиль

После регистрации пользователь решает стать продавцом и заполняет форму.

🚫 Кейс 2: Повторное создание

Сервер вернёт ошибку 422 — у пользователя уже есть профиль.

📂 GET /api/v1/seller_profiles

Получить список всех профилей продавцов (только для админов)

✅ Ответ

[
  {
    "id": "sp-uuid",
    "display_name": "Магазин А",
    "slug": "magazin-a"
  }
]

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

  • Отображение списка всех зарегистрированных продавцов в админке
  • Поиск и фильтрация по названию магазина

👤 GET /api/v1/seller_profiles/:id

Получить один профиль по ID (для владельца или админа)

✅ Ответ

{
  "id": "sp-uuid",
  "display_name": "Магазин А",
  "description": "Производим мебель",
  "logo_url": "https://...",
  "slug": "magazin-a"
}

🌍 GET /api/v1/users/:user_id/seller_profile

Публичный просмотр профиля продавца

✅ Ответ

{
  "id": "sp-uuid",
  "display_name": "Магазин А",
  "slug": "magazin-a"
}

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

  • Публичная страница магазина
  • Получение seller-профиля через user_id

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

Обновление профиля продавца

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

  • description
  • logo_url

✅ Ответ

{
  "id": "sp-uuid",
  "description": "Обновлённое описание"
}

✅ Чек-лист

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

📋 Валидации

  • display_name нельзя редактировать
  • Только поля description и logo_url разрешены к изменению

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

  • Продавец загружает логотип
  • Обновляет описание магазина

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

Сущность Назначение
SellerProfile Основной профиль продавца
User Владелец профиля
UserPolicy Политика доступа
Shop, LegalProfile Привязаны к SellerProfile

📄 TODO / Идеи

  • Добавить дату создания
  • Статус подтверждения профиля
  • Публичные метрики продавца
  • Отображение рейтинга и отзывов