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

Эта документация описывает все доступные эндпоинты API для приложения, включая методы, параметры, ответы и примеры использования. API разделено на три группы маршрутов: /api/auth, /api/settings и /api/dashboard. Большинство эндпоинтов, кроме /api/auth/login, требуют авторизации через Bearer-токен, который можно получить через эндпоинт логина.

## Общая информация

- **Базовый URL**: http://192.168.200.111:8000
- **Авторизация**: Большинство эндпоинтов требуют заголовок `Authorization: Bearer <token>` или query-параметр `token=<token>`. Токен получается через /api/auth/login.
- **Формат ответов**: JSON.
- **Коды ошибок**:
  - 401 Unauthorized: Требуется авторизация или токен недействителен.
  - 500 Internal Server Error: Ошибка на сервере.

## Получение токена авторизации

Для доступа к защищённым эндпоинтам необходимо получить Bearer-токен через эндпоинт /api/auth/login.

- **Эндпоинт**: POST /api/auth/login
- **Описание**: Аутентифицирует пользователя и возвращает сессионный токен.
- **Тело запроса (JSON)**:
  ```
  {
    "username": "string",
    "password": "string"
  }
  ```
- **Ответ**:

  - Успех (200):
    ```
    {
      "access_token": "string",
      "token_type": "bearer"
    }
    ```
  - Ошибка (401):
    ```
    {
      "detail": "Неверные учетные данные"
    }
    ```

- **Пример**:

  ```
  curl -X POST http://192.168.200.111:8000/api/auth/login \
   -H "Content-Type: application/json" \
   -d '{"username": "admin", "password": "admin"}'
  ```

  Результат (пример):

  ```
  {
    "access_token": "123e4567-e89b-12d3-a456-426614174000",
    "token_type": "bearer"
  }
  ```

Сохраните `access_token` для использования в других запросах.

## Эндпоинты /api/auth

1. **Получение информации о текущем пользователе**

   - **Эндпоинт**: GET /api/auth/me
   - **Описание**: Возвращает информацию о текущем пользователе на основе предоставленного токена. Если токен отсутствует или недействителен, возвращает неаутентифицированный статус.
   - **Параметры запроса**:
     - authorization (опционально, строка): Заголовок Authorization: Bearer <token>.
     - token_param (опционально, строка): Query-параметр token=<token>.
   - **Ответ**:

     - Успех (200):
       ```
       {
         "username": "string",
         "is_authenticated": true
       }
       ```
     - Неаутентифицирован (200):
       ```
       {
         "username": "",
         "is_authenticated": false
       }
       ```
     - Ошибка (500): {"detail": "Описание ошибки"}

   - **Пример**:
     ```
     curl -X GET http://192.168.200.111:8000/api/auth/me \
      -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
      -H "accept: application/json"
     ```

2. **Выход из системы**

   - **Эндпоинт**: POST /api/auth/logout
   - **Описание**: Завершает сессию пользователя, удаляя токен.
   - **Параметры запроса**:
     - authorization (опционально, строка): Заголовок Authorization: Bearer <token>.
     - token_param (опционально, строка): Query-параметр token=<token>.
   - **Ответ**:

     - Успех (200):
       ```
       {
         "status": "success",
         "message": "Выход выполнен успешно"
       }
       ```
     - Нет сессии (200):
       ```
       {
         "status": "success",
         "message": "Нет активной сессии"
       }
       ```
     - Ошибка (500): {"detail": "Описание ошибки"}

   - **Пример**:
     ```
     curl -X POST http://192.168.200.111:8000/api/auth/logout \
      -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
      -H "accept: application/json"
     ```

## Эндпоинты /api/settings

1. **Получение всех настроек**

   - **Эндпоинт**: GET /api/settings
   - **Описание**: Возвращает все настройки приложения (VAD, system, STT, commands, auth).
   - **Ответ**:

     - Успех (200): Объект с полями vad, system, stt, commands, auth (см. модели в коде).
     - Ошибка (401): {"detail": "Не авторизован"}
     - Ошибка (500): {"detail": "Описание ошибки"}

   - **Пример**:
     ```
     curl -X GET http://192.168.200.111:8000/api/settings \
      -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
      -H "accept: application/json"
     ```

2. **Обновление настроек VAD**

   - **Эндпоинт**: PUT /api/settings/vad
   - **Описание**: Обновляет настройки VAD.
   - **Тело запроса (JSON)**: Объект VADSettings (см. модель в коде).
   - **Ответ**:

     - Успех (200): Обновлённый объект VADSettings.
     - Ошибка (401): {"detail": "Не авторизован"}
     - Ошибка (500): {"detail": "Описание ошибки"}

   - **Пример**:
     ```
     curl -X PUT http://192.168.200.111:8000/api/settings/vad \
      -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
      -H "Content-Type: application/json" \
      -d '{"mode": 1, "sample_rate": 16000, ...}'
     ```

(Аналогично для /system, /stt, /commands, /auth — обновление соответствующих настроек.)

3. **Перезапуск VAD и STT**

   - **Эндпоинт**: POST /api/settings/restart
   - **Описание**: Перезапускает VAD и STT с новыми настройками.
   - **Ответ**:

     - Успех (200):
       ```
       {
         "status": "success",
         "message": "VAD и STT перезапущены"
       }
       ```
     - Ошибка (401): {"detail": "Не авторизован"}
     - Ошибка (500): {"detail": "Описание ошибки"}

   - **Пример**:
     ```
     curl -X POST http://192.168.200.111:8000/api/settings/restart \
      -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
      -H "accept: application/json"
     ```

## Эндпоинты /api/dashboard

1. **Получение данных о речи и энергии**

   - **Эндпоинт**: GET /api/dashboard/speech-data
   - **Описание**: Возвращает текущие данные о речи и энергии, включая расширенные метрики VAD и STT.
   - **Ответ**:

     - Успех (200):
       ```
       {
         "state": "string",
         "speech_prob": 0.0,
         "energy": 0.0,
         "energy_threshold": 0.0,
         "speech_detected": false,
         "continuous_frames": 0,
         "gain": 1.0,
         "noise_floor": 0.0,
         "stt_model_path": "string",
         "stt_commands_count": 0
       }
       ```
     - Ошибка (401): {"detail": "Не авторизован"}
     - Ошибка (500): {"detail": "Описание ошибки"}

   - **Пример**:
     ```
     curl -X GET http://192.168.200.111:8000/api/dashboard/speech-data \
      -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
      -H "accept: application/json"
     ```

2. **Получение последних распознанных фраз**

   - **Эндпоинт**: GET /api/dashboard/recent-phrases
   - **Описание**: Возвращает список последних распознанных фраз (до указанного лимита).
   - **Параметры запроса**:
     - limit (опционально, целое число, по умолчанию 10): Максимальное количество фраз.
   - **Ответ**:

     - Успех (200):
       ```
       [
         {
           "text": "Пример фразы",
           "timestamp": "2025-10-13T11:13:00",
           "is_command": true
         },
         ...
       ]
       ```
     - Ошибка (401): {"detail": "Не авторизован"}
     - Ошибка (500): {"detail": "Описание ошибки"}

   - **Пример**:
     ```
     curl -X GET http://192.168.200.111:8000/api/dashboard/recent-phrases?limit=5 \
      -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
      -H "accept: application/json"
     ```

3. **Получение статистики системы**

   - **Эндпоинт**: GET /api/dashboard/stats
   - **Описание**: Возвращает расширенную статистику работы системы (время работы, количество распознанных фраз, системная нагрузка и т.д.).
   - **Ответ**:

     - Успех (200):
       ```
       {
         "uptime": "0:00:00",
         "recognized_phrases_count": 0,
         "commands_executed_count": 0,
         "system_load": {
           "cpu_percent": 0.0,
           "memory_percent": 0.0,
           "temperature": 0.0
         },
         "total_speech_frames": 0,
         "avg_speech_prob": 0.0,
         "vad_initialized": true,
         "stt_initialized": true
       }
       ```
     - Ошибка (401): {"detail": "Не авторизован"}
     - Ошибка (500): {"detail": "Описание ошибки"}

   - **Пример**:
     ```
     curl -X GET http://192.168.200.111:8000/api/dashboard/stats \
      -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
      -H "accept: application/json"
     ```

4. **Получение данных о нагрузке системы**

   - **Эндпоинт**: GET /api/dashboard/sys-monitor
   - **Описание**: Возвращает данные о нагрузке системы (CPU, память, температура).
   - **Ответ**:

     - Успех (200):
       ```
       {
         "cpu_percent": 0.0,
         "memory_percent": 0.0,
         "temperature": 0.0
       }
       ```
     - Ошибка (401): {"detail": "Не авторизован"}
     - Ошибка (500): {"detail": "Описание ошибки"}

   - **Пример**:
     ```
     curl -X GET http://192.168.200.111:8000/api/dashboard/sys-monitor \
      -H "Authorization: Bearer 123e4567-e89b-12d3-a456-426614174000" \
      -H "accept: application/json"
     ```

## Замечания

- **Авторизация**: Все эндпоинты, кроме /api/auth/login, требуют токен, полученный через /api/auth/login. Токен можно передать:
  - В заголовке: `Authorization: Bearer <token>`
  - В query-параметре: `?token=<token>`
- **Безопасность**: Пароли в настройках хранятся в открытом виде. Рекомендуется использовать хэширование (например, bcrypt) для auth.password.
- **Хранение сессий**: Токены хранятся в памяти (ACTIVE_SESSIONS). Для продакшена используйте Redis или другую базу данных.
- **Ограничения**: Токены не имеют срока действия. Рекомендуется добавить expiration (например, хранить timestamp в ACTIVE_SESSIONS).
- **Обновления**: Документация актуализирована на 13 октября 2025 года. Добавлены новые поля в /speech-data, новый эндпоинт /sys-monitor и расширенная структура для /stats.