Initial commit

2025-12-25 12:01:35 +03:00
commit c574533f63
85 changed files with 6027 additions and 0 deletions
@@ -0,0 +1,318 @@
+# Документация 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.