NeveTimePanel/OWNER_PERMISSIONS.md

# 👑 Роль Владельца и Система Управления Правами

**Дата:** 15 января 2026  
**Версия:** 1.1.0

---

## 📋 Содержание

1. [Обзор](#обзор)
2. [Роль Владельца](#роль-владельца)
3. [Система Прав](#система-прав)
4. [API Эндпоинты](#api-эндпоинты)
5. [Примеры Использования](#примеры-использования)
6. [Миграция Существующих Пользователей](#миграция-существующих-пользователей)

---

## Обзор

В MC Panel добавлена роль **Владелец (Owner)** с расширенными возможностями управления правами пользователей. Владелец может:

- ✅ Изменять роли пользователей (admin, user, support, banned)
- ✅ Управлять правами доступа к ресурсам
- ✅ Забирать доступ к серверам, тикетам, файлам
- ✅ Выдавать доступ к ресурсам
- ✅ Удалять пользователей
- ✅ Полный контроль над панелью

---

## Роль Владельца

### Как стать владельцем?

**Первый зарегистрированный пользователь автоматически получает роль владельца.**

```json
{
  "username": "Root",
  "role": "owner",
  "permissions": {
    "manage_users": true,
    "manage_roles": true,
    "manage_servers": true,
    "manage_tickets": true,
    "manage_files": true,
    "delete_users": true,
    "view_all_resources": true
  }
}
```

### Иерархия ролей

```
Owner (Владелец)
  ↓
Admin (Администратор)
  ↓
Support (Поддержка)
  ↓
User (Пользователь)
  ↓
Banned (Заблокирован)
```

### Возможности по ролям

| Возможность | Owner | Admin | Support | User | Banned |
|------------|-------|-------|---------|------|--------|
| Управление пользователями | ✅ | ✅ | ❌ | ❌ | ❌ |
| Изменение ролей | ✅ | ❌ | ❌ | ❌ | ❌ |
| Удаление пользователей | ✅ | ❌ | ❌ | ❌ | ❌ |
| Управление всеми серверами | ✅ | ✅ | ❌ | ❌ | ❌ |
| Управление своими серверами | ✅ | ✅ | ✅ | ✅ | ❌ |
| Просмотр всех тикетов | ✅ | ✅ | ✅ | ❌ | ❌ |
| Ответ на тикеты | ✅ | ✅ | ✅ | ✅ | ❌ |
| Создание тикетов | ✅ | ✅ | ✅ | ✅ | ❌ |
| Доступ к панели | ✅ | ✅ | ✅ | ✅ | ❌ |

---

## Система Прав

### Структура прав пользователя

```json
{
  "username": "example_user",
  "role": "user",
  "permissions": {
    "manage_users": false,
    "manage_roles": false,
    "manage_servers": true,
    "manage_tickets": true,
    "manage_files": true,
    "delete_users": false,
    "view_all_resources": false
  },
  "resource_access": {
    "servers": ["server1", "server2"],
    "tickets": ["ticket1", "ticket2"],
    "files": ["server1/*", "server2/*"]
  }
}
```

### Типы прав

#### 1. manage_users
- Создание пользователей
- Редактирование профилей
- Просмотр списка пользователей

#### 2. manage_roles
- Изменение ролей пользователей
- Только для Owner

#### 3. manage_servers
- Создание серверов
- Запуск/остановка серверов
- Удаление серверов

#### 4. manage_tickets
- Создание тикетов
- Ответ на тикеты
- Изменение статуса

#### 5. manage_files
- Загрузка файлов
- Редактирование файлов
- Удаление файлов

#### 6. delete_users
- Удаление пользователей
- Только для Owner

#### 7. view_all_resources
- Просмотр всех серверов
- Просмотр всех тикетов
- Доступ ко всем файлам

---

## API Эндпоинты

### 1. Получить список пользователей

```http
GET /api/users
Authorization: Bearer <token>
```

**Требуется роль:** Owner или Admin

**Ответ:**
```json
{
  "users": [
    {
      "id": 1,
      "username": "Root",
      "role": "owner",
      "created_at": "2026-01-15T10:00:00Z"
    },
    {
      "id": 2,
      "username": "User1",
      "role": "user",
      "created_at": "2026-01-15T11:00:00Z"
    }
  ]
}
```

---

### 2. Изменить роль пользователя

```http
PUT /api/users/{user_id}/role
Authorization: Bearer <token>
Content-Type: application/json

{
  "role": "admin"
}
```

**Требуется роль:** Owner

**Доступные роли:**
- `owner` (только один владелец)
- `admin`
- `support`
- `user`
- `banned`

**Ответ:**
```json
{
  "message": "Роль пользователя изменена",
  "user": {
    "id": 2,
    "username": "User1",
    "role": "admin"
  }
}
```

---

### 3. Изменить права пользователя

```http
PUT /api/users/{user_id}/permissions
Authorization: Bearer <token>
Content-Type: application/json

{
  "permissions": {
    "manage_servers": true,
    "manage_tickets": true,
    "manage_files": false
  }
}
```

**Требуется роль:** Owner

**Ответ:**
```json
{
  "message": "Права пользователя обновлены",
  "permissions": {
    "manage_servers": true,
    "manage_tickets": true,
    "manage_files": false
  }
}
```

---

### 4. Управление доступом к ресурсам

#### Выдать доступ к серверу

```http
POST /api/users/{user_id}/access/servers
Authorization: Bearer <token>
Content-Type: application/json

{
  "server_name": "Survival"
}
```

**Требуется роль:** Owner или Admin

**Ответ:**
```json
{
  "message": "Доступ к серверу выдан",
  "server": "Survival",
  "user": "User1"
}
```

#### Забрать доступ к серверу

```http
DELETE /api/users/{user_id}/access/servers/{server_name}
Authorization: Bearer <token>
```

**Требуется роль:** Owner или Admin

**Ответ:**
```json
{
  "message": "Доступ к серверу отозван",
  "server": "Survival",
  "user": "User1"
}
```

---

### 5. Удалить пользователя

```http
DELETE /api/users/{user_id}
Authorization: Bearer <token>
```

**Требуется роль:** Owner

**Ответ:**
```json
{
  "message": "Пользователь удалён",
  "username": "User1"
}
```

**Примечание:** Владельца удалить нельзя!

---

### 6. Заблокировать пользователя

```http
POST /api/users/{user_id}/ban
Authorization: Bearer <token>
Content-Type: application/json

{
  "reason": "Нарушение правил"
}
```

**Требуется роль:** Owner или Admin

**Ответ:**
```json
{
  "message": "Пользователь заблокирован",
  "username": "User1",
  "reason": "Нарушение правил"
}
```

---

### 7. Разблокировать пользователя

```http
POST /api/users/{user_id}/unban
Authorization: Bearer <token>
```

**Требуется роль:** Owner или Admin

**Ответ:**
```json
{
  "message": "Пользователь разблокирован",
  "username": "User1"
}
```

---

## Примеры Использования

### Python

```python
import requests

# Токен владельца
token = "your_owner_token"
headers = {"Authorization": f"Bearer {token}"}
base_url = "http://localhost:8000"

# 1. Получить список пользователей
response = requests.get(f"{base_url}/api/users", headers=headers)
users = response.json()["users"]
print(f"Всего пользователей: {len(users)}")

# 2. Изменить роль пользователя
user_id = 2
response = requests.put(
    f"{base_url}/api/users/{user_id}/role",
    headers=headers,
    json={"role": "admin"}
)
print(response.json()["message"])

# 3. Выдать доступ к серверу
response = requests.post(
    f"{base_url}/api/users/{user_id}/access/servers",
    headers=headers,
    json={"server_name": "Survival"}
)
print(response.json()["message"])

# 4. Заблокировать пользователя
response = requests.post(
    f"{base_url}/api/users/{user_id}/ban",
    headers=headers,
    json={"reason": "Нарушение правил"}
)
print(response.json()["message"])

# 5. Разблокировать пользователя
response = requests.post(
    f"{base_url}/api/users/{user_id}/unban",
    headers=headers
)
print(response.json()["message"])

# 6. Удалить пользователя
response = requests.delete(
    f"{base_url}/api/users/{user_id}",
    headers=headers
)
print(response.json()["message"])
```

---

### JavaScript

```javascript
const token = "your_owner_token";
const baseUrl = "http://localhost:8000";

// 1. Получить список пользователей
async function getUsers() {
  const response = await fetch(`${baseUrl}/api/users`, {
    headers: { "Authorization": `Bearer ${token}` }
  });
  const data = await response.json();
  console.log(`Всего пользователей: ${data.users.length}`);
}

// 2. Изменить роль пользователя
async function changeRole(userId, role) {
  const response = await fetch(`${baseUrl}/api/users/${userId}/role`, {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ role })
  });
  const data = await response.json();
  console.log(data.message);
}

// 3. Выдать доступ к серверу
async function grantServerAccess(userId, serverName) {
  const response = await fetch(`${baseUrl}/api/users/${userId}/access/servers`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ server_name: serverName })
  });
  const data = await response.json();
  console.log(data.message);
}

// 4. Заблокировать пользователя
async function banUser(userId, reason) {
  const response = await fetch(`${baseUrl}/api/users/${userId}/ban`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ reason })
  });
  const data = await response.json();
  console.log(data.message);
}

// Использование
getUsers();
changeRole(2, "admin");
grantServerAccess(2, "Survival");
banUser(2, "Нарушение правил");
```

---

### cURL

```bash
# Токен владельца
TOKEN="your_owner_token"
BASE_URL="http://localhost:8000"

# 1. Получить список пользователей
curl -X GET "$BASE_URL/api/users" \
  -H "Authorization: Bearer $TOKEN"

# 2. Изменить роль пользователя
curl -X PUT "$BASE_URL/api/users/2/role" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

# 3. Выдать доступ к серверу
curl -X POST "$BASE_URL/api/users/2/access/servers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"server_name": "Survival"}'

# 4. Забрать доступ к серверу
curl -X DELETE "$BASE_URL/api/users/2/access/servers/Survival" \
  -H "Authorization: Bearer $TOKEN"

# 5. Заблокировать пользователя
curl -X POST "$BASE_URL/api/users/2/ban" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Нарушение правил"}'

# 6. Разблокировать пользователя
curl -X POST "$BASE_URL/api/users/2/unban" \
  -H "Authorization: Bearer $TOKEN"

# 7. Удалить пользователя
curl -X DELETE "$BASE_URL/api/users/2" \
  -H "Authorization: Bearer $TOKEN"
```

---

## Миграция Существующих Пользователей

### Автоматическая миграция

При первом запуске обновлённой версии панели:

1. Первый пользователь в `users.json` получает роль `owner`
2. Все пользователи с ролью `admin` остаются `admin`
3. Все остальные пользователи получают роль `user`
4. Всем пользователям добавляются права по умолчанию

### Скрипт миграции

```python
# backend/migrate_users.py
import json
from pathlib import Path

def migrate_users():
    users_file = Path("users.json")
    
    if not users_file.exists():
        print("Файл users.json не найден")
        return
    
    with open(users_file, "r", encoding="utf-8") as f:
        users = json.load(f)
    
    if not users:
        print("Нет пользователей для миграции")
        return
    
    # Первый пользователь = owner
    users[0]["role"] = "owner"
    users[0]["permissions"] = {
        "manage_users": True,
        "manage_roles": True,
        "manage_servers": True,
        "manage_tickets": True,
        "manage_files": True,
        "delete_users": True,
        "view_all_resources": True
    }
    
    # Остальные пользователи
    for user in users[1:]:
        if "role" not in user:
            user["role"] = "user"
        
        if "permissions" not in user:
            if user["role"] == "admin":
                user["permissions"] = {
                    "manage_users": True,
                    "manage_roles": False,
                    "manage_servers": True,
                    "manage_tickets": True,
                    "manage_files": True,
                    "delete_users": False,
                    "view_all_resources": True
                }
            else:
                user["permissions"] = {
                    "manage_users": False,
                    "manage_roles": False,
                    "manage_servers": True,
                    "manage_tickets": True,
                    "manage_files": True,
                    "delete_users": False,
                    "view_all_resources": False
                }
        
        if "resource_access" not in user:
            user["resource_access"] = {
                "servers": [],
                "tickets": [],
                "files": []
            }
    
    # Сохранить
    with open(users_file, "w", encoding="utf-8") as f:
        json.dump(users, f, indent=2, ensure_ascii=False)
    
    print(f"Миграция завершена! Обновлено пользователей: {len(users)}")
    print(f"Владелец: {users[0]['username']}")

if __name__ == "__main__":
    migrate_users()
```

**Запуск миграции:**
```bash
cd backend
python migrate_users.py
```

---

## UI Компоненты

### Панель управления пользователями

В панели администратора добавлен раздел "Управление пользователями" (только для Owner):

**Возможности:**
- Просмотр списка всех пользователей
- Изменение ролей
- Управление правами
- Выдача/отзыв доступа к ресурсам
- Блокировка/разблокировка
- Удаление пользователей

**Компонент:** `frontend/src/components/UserManagement.jsx`

---

## Безопасность

### Проверка прав

Все эндпоинты управления пользователями защищены:

```python
def require_owner(current_user: dict):
    if current_user["role"] != "owner":
        raise HTTPException(
            status_code=403,
            detail="Требуется роль владельца"
        )

def require_admin_or_owner(current_user: dict):
    if current_user["role"] not in ["owner", "admin"]:
        raise HTTPException(
            status_code=403,
            detail="Требуется роль администратора или владельца"
        )
```

### Логирование действий

Все действия владельца логируются:

```python
# Пример лога
{
  "timestamp": "2026-01-15T12:00:00Z",
  "action": "change_role",
  "owner": "Root",
  "target_user": "User1",
  "old_role": "user",
  "new_role": "admin"
}
```

---

## FAQ

### Можно ли иметь несколько владельцев?

Нет, владелец может быть только один. Но владелец может назначить несколько администраторов.

### Что делать, если владелец потерял доступ?

Отредактируйте `backend/users.json` вручную и измените роль нужного пользователя на `owner`.

### Может ли владелец удалить сам себя?

Нет, владельца удалить нельзя. Сначала нужно передать роль владельца другому пользователю.

### Как передать роль владельца?

```bash
# Через API
curl -X PUT "http://localhost:8000/api/users/2/role" \
  -H "Authorization: Bearer $OWNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "owner"}'
```

При передаче роли владельца, текущий владелец автоматически становится администратором.

---

## Changelog

### Версия 1.1.0 (15 января 2026)

**Добавлено:**
- ✅ Роль владельца (Owner)
- ✅ Система прав и разрешений
- ✅ API для управления пользователями
- ✅ Управление доступом к ресурсам
- ✅ Блокировка/разблокировка пользователей
- ✅ Удаление пользователей
- ✅ UI компонент управления пользователями
- ✅ Скрипт миграции
- ✅ Логирование действий

**Изменено:**
- Первый пользователь теперь получает роль `owner` вместо `admin`
- Добавлена проверка прав для всех эндпоинтов
- Обновлена структура пользователя в `users.json`

---

**Версия:** 1.1.0  
**Дата:** 15 января 2026

**Полный контроль над панелью!** 👑