API Users - rubyhat/fastyshop-backend GitHub Wiki

👤 Пользователи (Users API)

Контроллер: Api::V1::UsersController
Версия: v1
Слой: Публичный API и Аутентифицированный API
Некоторые методы доступны без токена, остальные требуют access-токен

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

Контроллер предоставляет CRUD-операции над пользователями, а также специальный endpoint /me для получения текущего авторизованного пользователя.

Все действия защищены политиками доступа (UserPolicy), логика работы с деактивацией (is_active) встроена в сериалайзер и ApiErrorHandling.

📄 Методы

👤 GET /api/v1/me

Получить данные текущего пользователя.

✅ Ответ (200 OK)

{
  "id": "1e2c...",
  "phone": "+77001234567",
  "email": "[email protected]",
  "role": "user",
  "is_active": true
}

✅ Чек-лист

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

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

  • Текущий пользователь извлекается из JWT access-токена
  • Если пользователь is_active: false, возвращается ошибка 410

📚 Кейсы

  • Покупатель заходит в профиль
  • Продавец смотрит, кто он
  • Неавторизованный пользователь — 401 Unauthorized

👤 GET /api/v1/users/:id

Публичный просмотр профиля пользователя

✅ Ответ

{
  "id": "1e2c...",
  "phone": "+77001234567",
  "role": "user",
  "email": null
}

❌ Удалённый пользователь — 410 Gone

{
  "error": {
    "key": "user.deleted",
    "message": "Пользователь удалил свой аккаунт",
    "code": 410,
    "status": "gone"
  }
}

✅ Чек-лист

Пункт Значение
🔒 Требуется access token ❌ Нет
🔐 Политики доступа UserPolicy#show? → true
🔗 Зависимости user.is_active == true

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

  • Доступен всем
  • Если пользователь удалён — 410 Gone
  • Email скрывается

📚 Кейсы

  • Покупатель смотрит профиль продавца
  • Продавец открывает другого пользователя
  • Удалённый пользователь — заглушка

🆕 POST /api/v1/users

Регистрация нового пользователя

✅ Входные параметры обернутные в объект user

Поле Тип Обязательный Пример
phone string ✅ +77005554433
email string ❌ [email protected]
password string ✅ Test1234!
password_confirmation string ✅ Test1234!
country_code string ✅ KZ

Например:

{
    "user": {
        "country_code": "KZ",
        "phone": "+77010000020",
        "email": "[email protected]",
        "password": "UserPassword1@",
        "password_confirmation": "UserPassword1@"
    }
}

✅ Ответ (201 Created)

{
  "id": "b45c...",
  "phone": "+77005554433",
  "role": "user"
}

✅ Чек-лист

Пункт Значение
🔒 Требуется access token ❌ Нет
🔐 Политики доступа UserPolicy#create? → true
🔗 Зависимости Нет

📚 Кейсы

  • Регистрация нового пользователя
  • Только номер и пароль
  • Попытка указать superadmin — игнорируется

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

Редактирование пользователя

✅ Ответ

{
  "id": "1e2c...",
  "phone": "+77005553322",
  "email": "[email protected]"
}

✅ Чек-лист

Пункт Значение
🔒 Требуется access token ✅ Да
🔐 Политики доступа Только сам пользователь или superadmin/supermanager
🔗 Зависимости Пользователь активен (is_active: true)

📚 Кейсы

  • Обновление номера
  • Админ меняет email
  • Продавец меняет пароль

❌ DELETE /api/v1/users/:id

Мягкое удаление пользователя

✅ Ответ

{
  "message": "Аккаунт деактивирован"
}

✅ Чек-лист

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

📚 Кейсы

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

👥 GET /api/v1/users

Просмотр всех пользователей (админ)

✅ Ответ

[
  {
    "id": "1e2c...",
    "phone": "+7700...",
    "role": "user"
  }
]

✅ Чек-лист

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

📚 Кейсы

  • Админ смотрит всех
  • Просмотр неактивных
  • Проверка связей

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

Сущность Назначение
User Основная модель
UserPolicy Контроль доступа
UserSerializer Скрытие email, статус активен
ApiErrorHandling Стандартизация ошибок

📄 TODO / Идеи

  • Фильтрация по ролям
  • Поддержка аватаров
  • Soft-restore аккаунта