# Документация REST API

## Базовая информация

- **Base URL**: `http://localhost/msg/backend/api`
- **Content-Type**: `application/json`
- **Аутентификация**: JWT Token в заголовке `Authorization: Bearer {token}`

## Коды ответов

- `200 OK` - Успешный запрос
- `201 Created` - Ресурс создан
- `400 Bad Request` - Ошибка валидации
- `401 Unauthorized` - Требуется аутентификация
- `403 Forbidden` - Доступ запрещен
- `404 Not Found` - Ресурс не найден
- `500 Internal Server Error` - Ошибка сервера

---

## Аутентификация

### Регистрация

```http
POST /auth/register
Content-Type: application/json

{
    "username": "user1",
    "password": "password123",
    "invite_code": "ABC123XY"
}
```

**Ответ (201)**:
```json
{
    "message": "Registration successful",
    "user_id": 2
}
```

**Ошибки**:
- `"Missing required fields"` - Недостают параметры
- `"Invalid or expired invite code"` - Неверный код приглашения
- `"Username already exists"` - Логин уже занят
- `"Registration failed"` - Ошибка при регистрации

---

### Вход

```http
POST /auth/login
Content-Type: application/json

{
    "username": "admin",
    "password": "admin123"
}
```

**Ответ (200)**:
```json
{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
        "id": 1,
        "username": "admin",
        "role": "admin"
    }
}
```

**Ошибки**:
- `"Missing username or password"` - Недостают учетные данные
- `"Invalid credentials"` - Неверные учетные данные

---

## Пользователь

### Получить профиль

```http
GET /user/profile
Authorization: Bearer {token}
```

**Ответ (200)**:
```json
{
    "id": 1,
    "username": "admin",
    "role": "admin",
    "invite_quota": 10,
    "created_at": "2024-01-01 10:00:00"
}
```

---

### Список онлайн пользователей

```http
GET /user/online-users
Authorization: Bearer {token}
```

**Ответ (200)**:
```json
{
    "message": "Online users list available via Socket.io"
}
```

---

## Приглашения

### Создать приглашение

```http
POST /invite/create
Authorization: Bearer {token}
```

**Ответ (200)**:
```json
{
    "code": "ABC123XY",
    "expires_at": "2024-02-09 10:00:00"
}
```

**Ошибки**:
- `"Daily invite limit reached"` - Достигнут лимит на день

---

### Мои приглашения

```http
GET /invite/my-invites
Authorization: Bearer {token}
```

**Ответ (200)**:
```json
[
    {
        "id": 1,
        "code": "ABC123XY",
        "creator_id": 1,
        "used_by": 2,
        "created_at": "2024-01-09 10:00:00",
        "expires_at": "2024-02-09 10:00:00",
        "used_at": "2024-01-09 11:00:00",
        "used_by_username": "user1"
    }
]
```

---

## Сообщения

### Отправить личное сообщение

```http
POST /message/send-private
Authorization: Bearer {token}
Content-Type: application/json

{
    "recipient_id": 2,
    "content": "Привет!"
}
```

**Ответ (200)**:
```json
{
    "message_id": 5
}
```

---

### Получить личные сообщения

```http
GET /message/get-private/{recipient_id}?limit=50&offset=0
Authorization: Bearer {token}
```

**Ответ (200)**:
```json
[
    {
        "id": 5,
        "sender_id": 1,
        "recipient_id": 2,
        "content": "Привет!",
        "is_group": 0,
        "is_deleted": 0,
        "created_at": "2024-01-09 10:00:00",
        "updated_at": null,
        "sender_username": "admin"
    }
]
```

---

### Отредактировать сообщение

```http
POST /message/update
Authorization: Bearer {token}
Content-Type: application/json

{
    "message_id": 5,
    "content": "Привет! (отредактировано)"
}
```

**Ответ (200)**:
```json
{
    "message": "Message updated"
}
```

---

### Удалить сообщение

```http
POST /message/delete
Authorization: Bearer {token}
Content-Type: application/json

{
    "message_id": 5
}
```

**Ответ (200)**:
```json
{
    "message": "Message deleted"
}
```

---

## Группы

### Создать группу

```http
POST /group/create
Authorization: Bearer {token}
Content-Type: application/json

{
    "name": "Разработчики",
    "description": "Группа для разработчиков"
}
```

**Ответ (200)**:
```json
{
    "group_id": 1
}
```

---

### Мои группы

```http
GET /group/my-groups
Authorization: Bearer {token}
```

**Ответ (200)**:
```json
[
    {
        "id": 1,
        "creator_id": 1,
        "name": "Разработчики",
        "description": "Группа для разработчиков",
        "created_at": "2024-01-09 10:00:00",
        "member_count": 3
    }
]
```

---

### Получить участников группы

```http
GET /group/members/{group_id}
Authorization: Bearer {token}
```

**Ответ (200)**:
```json
[
    {
        "id": 1,
        "username": "admin"
    },
    {
        "id": 2,
        "username": "user1"
    }
]
```

---

### Добавить участника в группу

```http
POST /group/members
Authorization: Bearer {token}
Content-Type: application/json

{
    "group_id": 1,
    "user_id": 3
}
```

**Ответ (200)**:
```json
{
    "message": "Member added"
}
```

---

## Админ endpoints

### Все пользователи

```http
GET /admin/users
Authorization: Bearer {token}
```

**Требует**: роль `admin`

**Ответ (200)**:
```json
[
    {
        "id": 1,
        "username": "admin",
        "role": "admin",
        "invite_quota": 10,
        "created_at": "2024-01-01 10:00:00"
    },
    {
        "id": 2,
        "username": "user1",
        "role": "user",
        "invite_quota": 3,
        "created_at": "2024-01-09 11:00:00"
    }
]
```

---

### Обновить квоту инвайтов

```http
POST /admin/update-quota
Authorization: Bearer {token}
Content-Type: application/json

{
    "user_id": 2,
    "quota": 5
}
```

**Требует**: роль `admin`

**Ответ (200)**:
```json
{
    "message": "Quota updated"
}
```

---

### Обновить роль пользователя

```http
POST /admin/update-role
Authorization: Bearer {token}
Content-Type: application/json

{
    "user_id": 2,
    "role": "admin"
}
```

**Требует**: роль `admin`

**Параметры**:
- `role`: `"user"` или `"admin"`

**Ответ (200)**:
```json
{
    "message": "Role updated"
}
```

---

### Все приглашения

```http
GET /admin/all-invites
Authorization: Bearer {token}
```

**Требует**: роль `admin`

**Ответ (200)**:
```json
[
    {
        "id": 1,
        "code": "ABC123XY",
        "creator_id": 1,
        "used_by": 2,
        "created_at": "2024-01-09 10:00:00",
        "expires_at": "2024-02-09 10:00:00",
        "used_at": "2024-01-09 11:00:00",
        "creator_username": "admin",
        "used_by_username": "user1"
    }
]
```

---

### Дерево приглашений

```http
GET /admin/invite-tree
Authorization: Bearer {token}
```

**Требует**: роль `admin`

**Ответ (200)**:
```json
{
    "id": 1,
    "username": "admin",
    "created_at": "2024-01-01 10:00:00",
    "invited_count": 2,
    "children": [
        {
            "id": 2,
            "username": "user1",
            "created_at": "2024-01-09 11:00:00",
            "invited_count": 1,
            "children": [
                {
                    "id": 3,
                    "username": "user2",
                    "created_at": "2024-01-09 12:00:00",
                    "invited_count": 0,
                    "children": []
                }
            ]
        }
    ]
}
```

---

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

### JavaScript (Fetch API)

```javascript
// Вход
const loginResponse = await fetch('http://localhost/msg/backend/api/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        username: 'admin',
        password: 'admin123'
    })
});

const { token, user } = await loginResponse.json();

// Создать приглашение
const inviteResponse = await fetch('http://localhost/msg/backend/api/invite/create', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
    }
});

const invite = await inviteResponse.json();
console.log('Код приглашения:', invite.code);
```

### cURL

```bash
# Вход
curl -X POST http://localhost/msg/backend/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# Создать приглашение
curl -X POST http://localhost/msg/backend/api/invite/create \
  -H "Authorization: Bearer {token}"
```

---

## Ошибки аутентификации

### 401 Unauthorized

```json
{
    "error": "No token provided"
}
```

или

```json
{
    "error": "Invalid token"
}
```

### 403 Forbidden

```json
{
    "error": "Admin access required"
}
```

---

## Rate Limiting

В текущей версии отсутствует. Рекомендуется добавить в production!

---

## CORS

API поддерживает CORS со всех источников. В production рекомендуется ограничить.