API Users

👤 Пользователи (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": "user@test.com",
  "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	❌	user@test.com
password	string	✅	Test1234!
password_confirmation	string	✅	Test1234!
country_code	string	✅	KZ

Например:

{
    "user": {
        "country_code": "KZ",
        "phone": "+77010000020",
        "email": "test@test.com",
        "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": "new@mail.com"
}

---

✅ Чек-лист

Пункт	Значение
🔒 Требуется 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 аккаунта