remnawave-bedolaga-telegram-bot/docs/web-admin-integration.md

# Интеграция веб-админки

Этот документ описывает запуск встроенного административного веб-API бота и типовой сценарий интеграции c внешней веб-админкой.
API разворачивается вместе с ботом, использует FastAPI и защищено токенами доступа.

## 1. Обзор архитектуры

- Веб-API запускается в том же процессе, что и бот, через встроенный `uvicorn` сервер.
- Авторизация выполняется по токену: `X-API-Key` или `Authorization: Bearer <token>`.
- Все эндпоинты работают поверх HTTPS/HTTP и возвращают структуры в формате JSON.
- Встроенный механизм миграций создаёт таблицу `web_api_tokens` и бутстрап-токен, если указан в конфигурации.

## 2. Настройка окружения

Добавьте переменные в `.env` (или другую систему конфигурации):

| Переменная | Назначение | Значение по умолчанию / пример |
|------------|------------|---------------------------------|
| `WEB_API_ENABLED` | Включает веб-API. | `true`
| `WEB_API_HOST` | IP/hostname, на котором слушает API. | `0.0.0.0`
| `WEB_API_PORT` | Порт веб-API. | `8080`
| `WEB_API_ALLOWED_ORIGINS` | Список доменов для CORS, через запятую. `*` разрешит всё. | `https://admin.example.com`
| `WEB_API_DOCS_ENABLED` | Включить `/docs` и `/openapi.json`. В проде лучше `false`. | `false`
| `WEB_API_WORKERS` | Количество воркеров uvicorn. В embed-режиме всегда приводится к `1`. | `1`
| `WEB_API_REQUEST_LOGGING` | Логировать каждый запрос API. | `true`
| `WEB_API_DEFAULT_TOKEN` | Бутстрап-токен, который будет создан при миграции. | `super-secret-token`
| `WEB_API_DEFAULT_TOKEN_NAME` | Отображаемое имя созданного токена. | `Bootstrap Token`
| `WEB_API_TOKEN_HASH_ALGORITHM` | Алгоритм хеширования токенов (`sha256`, `sha512`, ...). | `sha256`

> ⚠️ Если вы храните конфигурацию в Kubernetes/Ansible/других системах — не забудьте обновить секреты, чтобы бот видел эти переменные.

### Включение Swagger (интерактивной документации)

Чтобы открыть интерфейс Swagger UI на `/docs`, убедитесь, что одновременно заданы две переменные окружения:

1. `WEB_API_ENABLED=true` — включает само веб-API.
2. `WEB_API_DOCS_ENABLED=true` — публикует `/docs`, `/redoc` и `/openapi.json`.

После изменения значений перезапустите бота. Интерфейс будет доступен по адресу `http://<WEB_API_HOST>:<WEB_API_PORT>/docs`.

## 3. Подготовка базы данных

1. Убедитесь, что настройки БД верны (`DATABASE_URL` или параметры PostgreSQL/SQLite).
2. При старте бота автоматически запускается универсальная миграция `run_universal_migration`, которая:
   - создаёт таблицу `web_api_tokens`, если её нет;
   - активирует токен из `WEB_API_DEFAULT_TOKEN`, если он задан.
3. Если нужно запустить миграцию вручную, выполните:

```bash
python -c "import asyncio; from app.database.universal_migration import run_universal_migration; asyncio.run(run_universal_migration())"
```

Или просто запустите `python main.py` — бот выполнит ту же процедуру автоматически.

## 4. Запуск веб-API

```bash
# Создаём .env и включаем веб-API
cp .env.example .env
nano .env  # проставьте WEB_API_* переменные и BOT_TOKEN

# Запускаем бота (локально)
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python main.py
```

В Docker достаточно пробросить порт `WEB_API_PORT` из контейнера бота. После запуска API будет доступно по адресу `http://<WEB_API_HOST>:<WEB_API_PORT>`.

## 5. Аутентификация и токены

- Первый токен удобно задать через `WEB_API_DEFAULT_TOKEN`. Он появится в таблице при запуске миграции и будет автоматически
  пересоздан/активирован после изменения значения через интерфейс настроек.
- Для управления токенами используйте эндпоинты `/tokens`:
  - `GET /tokens` — список токенов.
  - `POST /tokens` — создать новый токен. Возвращает открытое значение один раз.
  - `POST /tokens/{id}/revoke` и `/activate` — управление статусом.
  - `DELETE /tokens/{id}` — удаление.
- Заголовок авторизации можно передавать двумя способами:

```http
X-API-Key: <ваш_токен>
# или
Authorization: Bearer <ваш_токен>
```

Пример запроса на создание токена:

```bash
curl -X POST "http://127.0.0.1:8080/tokens" \
  -H "X-API-Key: super-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Web admin", "description": "UI token"}'
```

## 6. Основные эндпоинты

| Метод | Путь | Назначение |
|-------|------|------------|
| `GET` | `/health` | Статус API, версия бота, флаги включённых сервисов.
| `GET` | `/stats/overview` | Сводная статистика по пользователям, подпискам, платежам и тикетам.
| `GET` | `/settings/categories` | Категории системных настроек.
| `GET` | `/settings` | Полный список настроек (с текущими и дефолтными значениями).
| `GET` | `/settings/{key}` | Получить одну настройку.
| `PUT` | `/settings/{key}` | Обновить значение настройки.
| `DELETE` | `/settings/{key}` | Сбросить настройку к значению по умолчанию.
| `GET` | `/users` | Список пользователей с фильтрами и пагинацией.
| `GET` | `/users/{id}` | Детали пользователя.
| `POST` | `/users` | Создать пользователя (например, для ручной выдачи доступа).
| `PATCH` | `/users/{id}` | Обновить профиль пользователя или статус.
| `POST` | `/users/{id}/balance` | Корректировка баланса с созданием транзакции.
| `GET` | `/subscriptions` | Список подписок с фильтрами.
| `POST` | `/subscriptions` | Создать триальную или платную подписку.
| `POST` | `/subscriptions/{id}/extend` | Продлить подписку на N дней.
| `POST` | `/subscriptions/{id}/traffic` | Добавить трафик (ГБ).
| `POST` | `/subscriptions/{id}/devices` | Добавить устройства.
| `POST` | `/subscriptions/{id}/squads` | Привязать сквад.
| `DELETE` | `/subscriptions/{id}/squads/{uuid}` | Удалить сквад.
| `GET` | `/transactions` | История транзакций.
| `GET` | `/tickets` | Список тикетов поддержки.
| `GET` | `/tickets/{id}` | Тикет с перепиской.
| `POST` | `/tickets/{id}/status` | Изменить статус тикета.
| `POST` | `/tickets/{id}/priority` | Изменить приоритет.
| `POST` | `/tickets/{id}/reply-block` | Заблокировать ответы пользователя.
| `DELETE` | `/tickets/{id}/reply-block` | Снять блокировку.
| `GET` | `/promo-groups` | Список промо-групп с количеством участников.
| `POST` | `/promo-groups` | Создать промо-группу.
| `PATCH` | `/promo-groups/{id}` | Обновить промо-группу.
| `DELETE` | `/promo-groups/{id}` | Удалить промо-группу.
| `GET` | `/tokens` | Управление токенами доступа.

### RemnaWave интеграция

После включения веб-API в Swagger (`WEB_API_DOCS_ENABLED=true`) появится раздел **remnawave**. Он объединяет эндпоинты для управления панелью RemnaWave и синхронизации данных бота:

| Метод | Путь | Назначение |
|-------|------|------------|
| `GET` | `/remnawave/status` | Проверка конфигурации и доступности RemnaWave API. |
| `GET` | `/remnawave/system` | Агрегированная статистика по пользователям, нодам и трафику. |
| `GET` | `/remnawave/nodes` | Список нод и их текущее состояние. |
| `GET` | `/remnawave/nodes/realtime` | Текущая загрузка нод (realtime-метрики RemnaWave). |
| `GET` | `/remnawave/nodes/{uuid}` | Детальная информация по конкретной ноде. |
| `GET` | `/remnawave/nodes/{uuid}/statistics` | Агрегированная статистика и история нагрузок по ноде. |
| `GET` | `/remnawave/nodes/{uuid}/usage` | История использования ноды пользователями за выбранный период. |
| `POST` | `/remnawave/nodes/{uuid}/actions` | Включение, отключение или перезапуск ноды. |
| `POST` | `/remnawave/nodes/restart` | Массовый перезапуск всех нод в RemnaWave. |
| `GET` | `/remnawave/squads` | Список внутренних сквадов с составом и статистикой. |
| `GET` | `/remnawave/squads/{uuid}` | Детали выбранного сквада. |
| `POST` | `/remnawave/squads` | Создание нового сквада и привязка inbounds. |
| `PATCH` | `/remnawave/squads/{uuid}` | Обновление имени или состава inbounds сквада. |
| `POST` | `/remnawave/squads/{uuid}/actions` | Массовые операции: добавить/удалить всех, переименовать, обновить inbounds, удалить. |
| `GET` | `/remnawave/inbounds` | Список доступных inbounds в панели RemnaWave. |
| `GET` | `/remnawave/users/{telegram_id}/traffic` | Использование трафика конкретного пользователя RemnaWave. |
| `POST` | `/remnawave/sync/from-panel` | Синхронизация пользователей и подписок из панели в бота. |
| `POST` | `/remnawave/sync/to-panel` | Обратная синхронизация данных бота в панель. |
| `POST` | `/remnawave/sync/subscriptions/validate` | Проверка и восстановление подписок в RemnaWave. |
| `POST` | `/remnawave/sync/subscriptions/cleanup` | Очистка «осиротевших» подписок и пользователей в RemnaWave. |
| `POST` | `/remnawave/sync/subscriptions/statuses` | Приведение статусов подписок в боте и панели к единому виду. |
| `GET` | `/remnawave/sync/recommendations` | Рекомендации по синхронизации: что добавить, обновить или удалить. |


> Все списковые эндпоинты поддерживают пагинацию (`limit`, `offset`) и фильтры, описанные в OpenAPI спецификации. Если `WEB_API_DOCS_ENABLED=true`, документация доступна по `/docs`. В ответах `/settings` поле `choices` всегда массив: пустой список означает отсутствие предопределённых значений.

## 7. Сценарий интеграции веб-админки

1. **Health-check** — перед авторизацией UI вызывает `GET /health`, чтобы отобразить статус и версию бота.
2. **Настройки UI** — подгружает категории через `GET /settings/categories`, далее выводит форму со значениями из `GET /settings`.
3. **Статистика дашборда** — `GET /stats/overview` для карточек с показателями.
4. **Раздел пользователи** — `GET /users` с поиском (`search`), фильтрами по статусу или промо-группе. Для детальной карточки использовать `GET /users/{id}`.
5. **Операции с подпиской** — использовать `POST /subscriptions/{id}/...` эндпоинты для продления, выдачи трафика и устройств.
6. **Поддержка** — список тикетов (`GET /tickets`), изменение статуса (`POST /tickets/{id}/status`), блокировка ответов (`POST /tickets/{id}/reply-block`).
7. **История операций** — `GET /transactions` с фильтрами по пользователю, типу и периоду.

## 8. CORS, безопасность и логирование

- Разрешённые домены указываются в `WEB_API_ALLOWED_ORIGINS`. Для нескольких доменов перечислите их через запятую.
- Для продакшена рекомендуется отключить публичную документацию (`WEB_API_DOCS_ENABLED=false`).
- `WEB_API_REQUEST_LOGGING=true` добавляет middleware, которое логирует метод, путь и статус ответа. Используйте его для аудита или отключите в продакшене, если хватает reverse-proxy логов.
- Все токены хранятся в базе в хешированном виде. Не храните открытые значения в коде.

## 9. Диагностика проблем

| Симптом | Возможная причина | Что проверить |
|---------|------------------|---------------|
| 401 Unauthorized | Неверный или просроченный токен. | Пересоздайте токен через `/tokens` и обновите UI. |
| 403/404 при работе с настройками | Неверный ключ настройки. | Получите список доступных ключей через `GET /settings`. |
| 422 Unprocessable Entity | Неверный тип данных в теле запроса. | Проверьте типы (числа, булевы, строки) и формат JSON. |
| API не стартует | Порт занят или неверные переменные окружения. | Проверьте логи контейнера бота и значения `WEB_API_HOST/PORT`. |

## 10. Рекомендации по эксплуатации

- Регулярно ревизируйте список активных токенов и отключайте неиспользуемые.
- Для внешних админок размещайте API за reverse-proxy (nginx, Caddy, Traefik) с TLS.
- Включите мониторинг доступности (например, curl на `/health`) в систему наблюдения.
- Обновляйте бота и админку синхронно, чтобы использовать новые поля API.