Add web admin API schemas and docs

docs/web-admin-integration.md

@@ -0,0 +1,155 @@
+# Интеграция веб-админки
+
+Этот документ описывает запуск встроенного административного веб-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/других системах — не забудьте обновить секреты, чтобы бот видел эти переменные.
+
+## 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` | Управление токенами доступа.
+
+> Все списковые эндпоинты поддерживают пагинацию (`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.