## Управлениями пользователями.
- Пользователей может добавлять и удалять только супер админ. 
- Количество администраторов в системе не ограничено, однако супер админ может быть только один, это первый пользователь зарегистрированный в системе.

### USER_STRUCT
```json
	{
		"id": 12,
		"first_name": "John",
		"mid_name": "",
		"last_name": "Doe",
		"nickname": "john.doe",
		"userpic": "http://url-to-img",
		"contacts": {
			"email": "john.doe@gmail.com",
			"phone": "+38063xxxxxxx",
			"telegram": "@tgnickname",
			"viber": "+38063xxxxxxx",
		},
		"role": "user",
		"group": "GROUP_STRUCT", // | false
		"last_activity": "2025-07-28 18:35",
		"create_at": "2025-07-28 18:35"
	}
	```

---

### POST `/api/v1/users/new`
Добавить в систему нового пользователя. 
- Нового пользователя может добавить как админ так и суперадмин, но назначить группу прав ниже своей. 

#### Пример запроса
```json
	{
		"first_name": "John",
		"mid_name": "",
		"last_name": "Doe",
		"nickname": "john.doe",
		"email": "john.doe@gmail.com",
		"password": "strong_password",
		"role": "user" // "user" (default) | "admin" | "super" (Если это первая регистрация, иначе вернёт ошибку)
	}
	```

#### Пример ответа
```json
	{
		"status": "ok",
		"user": "USER_STRUCT"
	}
	```

#### Пример НЕ успешного ответа. Невалидные поля
```json
	{
		"status": "error",
		"field": "nickname", // password | email
		"message": "Alias already exists" // "Email|Password|Nickname can`t be empty" | "Password must be strongest"
	}
	```

#### Пример НЕ успешного ответа. Не хватает прав
```json
	{
		"status": "error",
		"message": "Permissions error" // "Permission error"
	}
	```

---

#### GET `/api/v1/users/list`
Получить список пользователей

### Пример ответа
```json
	{
		"status": "ok",
		"users": [
			"USER_STRUCT"
			// ...
		],
		"total": 15
	}
	```

#### Пример НЕ успешного ответа. Не хватает прав
```json
	{
		"status": "error",
		"message": "Permissions error" // "Permission error"
	}
	```

---

### GET `/api/v1/users/id/{{id}}`
Получить все доступные данные о пользователе.

#### Пример ответа
```json
	{
		"status": "ok",
		"user": "USER_STRUCT"
	}
	```

#### Пример НЕ успешного ответа
```json
	{
		"status": "error",
		"message": "User not found" // | "Permission error"
	}
	```

---

### GET `/api/v1/users/current/`
Получить все доступные данные о текущем авторизованом пользователе

#### Пример ответа
```json
	{
		"status": "ok",
		"user": "USER_STRUCT"
	}
	```

---

### POST `/api/v1/users/id/{{id}}/update`
Редактирование пользователя. Можно передать только необходимое поле для редактирования.
- **Внимание!** Поле `role` будет проигнорировано, используй для этого специальный эндпоинт

#### Пример запроса
```json
	{
		"last_name": "Smith",
		"phone": "3806372984234"
	}
	```

#### Пример ответа
```json
	{
		"status": "ok",
		"user": "USER_STRUCT"
	}
	```

---

### POST `/api/v1/users/id/{{id}}/update/userpic`
Установка новой аватарки пользователя.
- **Примечание:** через `/update` можно установить прямую ссылку на аватарку

#### Пример запроса
```json
	{
		"upload_userpic": "base64;...", // Обязательно в base64, разрешение 512*512 пикс.
	}
	```

#### Пример ответа
```json
	{
		"status": "ok",
		"user": "USER_STRUCT"
	}
	```

#### Пример НЕ успешного ответа
```json
	{
		"status": "error",
		"message": "Invalid image" // | "User not found"
	}
	```

---

### POST `/api/v1/users/id/{{id}}/update/role`
Смена роли пользователя.
- **ВНИМАНИЕ!** доступно лишь суперадмину

#### Пример запроса
```json
	{
		"role": "admin", // | "user"
	}
	```

#### Пример НЕ успешного ответа
```json
	{
		"status": "error",
		"message": "User not found" // | "Permission error"
	}
	```

---

### POST `/api/v1/users/id/{{id}}/update/password`
Изменить пароль, от 6 любых символов, больше критериев нет.

#### Пример запроса
```json
	{
		"password": "current_password",
		"new_password": "new_strong_password"
	}
	```

#### Пример НЕ успешного ответа
```json
	{
		"status": "error",
		"message": "Password must be strongest" // | "Wrong password"
	}
	```

---

### GET `/api/v1/users/id/{{id}}/reset_password`
- Доступно только администратору, сбрасывает пароль выбранному пользователю. 
- Новый временный пароль будет сгенерирован и вернётся в ответе.
#### Примечания
- Админ может сбросить пароль лишь простым пользователям.
- Админу сбросить пароль может лишь суперадминистратор

#### Пример ответа
```json
	{
		"status": "ok",
		"new_password": "generated_password"
	}
	```

#### Пример НЕ успешного ответа
```json
	{
		"status": "error",
		"message": "User not found" // | "Permission error"
	}
	```

---

### GET `/api/v1/users/id/{{id}}/permissions`
Вернуть таблицу прав пользователя. 
- Это доступно для администраторов, но только в отношении себя и прав обычных пользователей.
- Обычные пользователи не могут получить таблицу своих прав.
- Суперадмин может получить таблицу прав любого пользователя. Сам при этом обладает по умолчанию всеми доступными правами.
- **ВАЖНО!** Это права не отдельно взятого пользователя, а группы в которой состоит пользователь.

#### Пример ответа
```json
	{
		"status": "ok",
		"permissions": [ /* permissions */ ]
	}
	```

#### Пример НЕ успешного ответа
```json
	{
		"status": "error",
		"message": "User not found" // | "Permission error"
	}
	```

### GET `/api/v1/users/id/{{id}}/remove`
Удалить пользователя. **Может быть выполнено только администратором или выше**

#### Пример ответа
```json
	{
		"status": "ok",
		"user": "USER_STRUCT"
	}
	```

#### Пример НЕ успешного ответа
```json
	{
		"status": "error",
		"message": "User not found" // | "Permission error"
	}
	```
