diff --git a/docs/web-api-analysis-and-suggestions.md b/docs/web-api-analysis-and-suggestions.md deleted file mode 100644 index 79aca506..00000000 --- a/docs/web-api-analysis-and-suggestions.md +++ /dev/null @@ -1,360 +0,0 @@ -# Анализ существующих API и предложения по расширению - -## Обзор существующих API эндпоинтов - -### 1. Health & Monitoring (health.py) -- ✅ `GET /health` - статус API и версия бота -- ✅ `GET /health/database` - состояние БД -- ✅ `GET /metrics/pool` - метрики пула подключений - -### 2. Statistics (stats.py) -- ✅ `GET /stats/overview` - общая статистика -- ✅ `GET /stats/full` - полная статистика с детализацией - -### 3. Settings (config.py) -- ✅ `GET /settings/categories` - категории настроек -- ✅ `GET /settings` - список всех настроек -- ✅ `GET /settings/{key}` - получить настройку -- ✅ `PUT /settings/{key}` - обновить настройку -- ✅ `DELETE /settings/{key}` - сбросить настройку - -### 4. Users (users.py) -- ✅ `GET /users` - список пользователей (с фильтрами) -- ✅ `GET /users/{id}` - детали пользователя (поддерживает telegram_id) -- ✅ `GET /users/by-telegram-id/{telegram_id}` - получить по Telegram ID -- ✅ `POST /users` - создать пользователя -- ✅ `PATCH /users/{id}` - обновить пользователя -- ✅ `POST /users/{id}/balance` - корректировка баланса - -### 5. Subscriptions (subscriptions.py) -- ✅ `GET /subscriptions` - список подписок -- ✅ `GET /subscriptions/{id}` - детали подпискит -- ✅ `POST /subscriptions` - создать подписку -- ✅ `POST /subscriptions/{id}/extend` - продлить подписку -- ✅ `POST /subscriptions/{id}/traffic` - добавить трафик -- ✅ `POST /subscriptions/{id}/devices` - добавить устройства -- ✅ `POST /subscriptions/{id}/squads` - привязать сквад -- ✅ `DELETE /subscriptions/{id}/squads/{uuid}` - удалить сквад - -### 6. Support/Tickets (tickets.py) -- ✅ `GET /tickets` - список тикетов -- ✅ `GET /tickets/{id}` - детали тикета с сообщениями -- ✅ `POST /tickets/{id}/status` - изменить статус -- ✅ `POST /tickets/{id}/priority` - изменить приоритет -- ✅ `POST /tickets/{id}/reply-block` - заблокировать ответы -- ✅ `DELETE /tickets/{id}/reply-block` - снять блокировку -- ✅ `POST /tickets/{id}/reply` - ответить на тикет -- ✅ `GET /tickets/{id}/messages/{message_id}/media` - получить медиа - -### 7. Transactions (transactions.py) -- ✅ `GET /transactions` - история транзакций - -### 8. Promo Groups (promo_groups.py) -- ✅ Полный CRUD для промо-групп - -### 9. Promo Offers (promo_offers.py) -- ✅ Управление промо-предложениями, шаблонами и логами - -### 10. Promocodes (promocodes.py) -- ✅ Полный CRUD для промокодов - -### 11. Servers (servers.py) -- ✅ Управление серверами RemnaWave - -### 12. RemnaWave Integration (remnawave.py) -- ✅ Статус, ноды, сквады, синхронизация - -### 13. Contests (contests.py) -- ✅ Управление конкурсами (реферальные, ежедневные) - -### 14. Campaigns (campaigns.py) -- ✅ Управление кампаниями - -### 15. Broadcasts (broadcasts.py) -- ✅ `POST /broadcasts` - создать рассылку -- ✅ `GET /broadcasts` - список рассылок -- ✅ `POST /broadcasts/{id}/stop` - остановить рассылку - -### 16. Menu Layout (menu_layout.py) -- ✅ Полное управление меню, статистика кликов, история - -### 17. Main Menu (main_menu_buttons.py, user_messages.py) -- ✅ Управление кнопками и сообщениями главного меню - -### 18. Welcome Texts (welcome_texts.py) -- ✅ CRUD для приветственных текстов - -### 19. Pages (pages.py) -- ✅ Управление публичными страницами - -### 20. Partners (partners.py) -- ✅ Статистика реферальной программы - -### 21. Polls (polls.py) -- ✅ Управление опросами - -### 22. Logs (logs.py) -- ✅ Логи мониторинга, поддержки и системные - -### 23. Tokens (tokens.py) -- ✅ Управление токенами доступа - -### 24. Media (media.py) -- ✅ Загрузка медиа - -### 25. Miniapp (miniapp.py) -- ✅ Информация о подписке для Mini App - -### 26. Subscription Events (subscription_events.py) -- ✅ Уведомления о событиях подписок - -### 27. Support Settings (support_settings.py) -- ✅ Настройки поддержки - -### 28. Backups (backups.py) -- ✅ Управление бэкапами - ---- - -## Предложения по расширению API - -### 🔴 Высокий приоритет - -#### 1. Расширенная аналитика и отчеты -**Эндпоинты:** -- `GET /analytics/revenue` - доходы по периодам (день/неделя/месяц/год) -- `GET /analytics/users/growth` - динамика роста пользователей -- `GET /analytics/subscriptions/conversion` - конверсия триалов в платные -- `GET /analytics/churn` - анализ оттока пользователей -- `GET /analytics/retention` - анализ удержания пользователей -- `GET /analytics/export` - экспорт данных в CSV/Excel - -**Польза:** Глубокая аналитика для принятия бизнес-решений - -#### 2. Массовые операции с пользователями -**Эндпоинты:** -- `POST /users/batch/update` - массовое обновление пользователей -- `POST /users/batch/balance` - массовая корректировка балансов -- `POST /users/batch/status` - массовое изменение статусов -- `POST /users/batch/promo-group` - массовое назначение промо-групп -- `POST /users/export` - экспорт списка пользователей - -**Польза:** Эффективное управление большими группами пользователей - -#### 3. Расширенное управление подписками -**Эндпоинты:** -- `POST /subscriptions/{id}/pause` - приостановить подписку -- `POST /subscriptions/{id}/resume` - возобновить подписку -- `POST /subscriptions/{id}/cancel` - отменить подписку -- `POST /subscriptions/{id}/transfer` - перенести подписку другому пользователю -- `GET /subscriptions/{id}/history` - история изменений подписки -- `POST /subscriptions/batch/extend` - массовое продление подписок -- `GET /subscriptions/expiring` - подписки, истекающие в ближайшее время - -**Польза:** Гибкое управление жизненным циклом подписок - -#### 4. Улучшенная работа с тикетами -**Эндпоинты:** -- `GET /tickets/stats` - статистика по тикетам (среднее время ответа, распределение по приоритетам) -- `POST /tickets/{id}/assign` - назначить тикет модератору -- `GET /tickets/assigned/{admin_id}` - тикеты, назначенные модератору -- `POST /tickets/{id}/notes` - добавить внутреннюю заметку (не видна пользователю) -- `GET /tickets/{id}/notes` - получить заметки -- `POST /tickets/batch/close` - массовое закрытие тикетов -- `GET /tickets/search` - расширенный поиск по тикетам - -**Польза:** Улучшенная организация работы поддержки - -#### 5. Управление уведомлениями -**Эндпоинты:** -- `GET /notifications` - список всех уведомлений (расширенный) -- `GET /notifications/types` - типы уведомлений -- `POST /notifications/mark-read` - отметить как прочитанное -- `GET /notifications/unread-count` - количество непрочитанных -- `POST /notifications/settings` - настройки уведомлений для админа - -**Польза:** Централизованное управление уведомлениями в админке - -### 🟡 Средний приоритет - -#### 6. Управление платежными системами -**Эндпоинты:** -- `GET /payments/methods` - список доступных методов оплаты -- `GET /payments/methods/{id}/stats` - статистика по методу оплаты -- `POST /payments/methods/{id}/toggle` - включить/выключить метод -- `GET /payments/failed` - список неудачных платежей -- `POST /payments/{id}/retry` - повторить платеж -- `GET /payments/refunds` - список возвратов - -**Польза:** Мониторинг и управление платежами - -#### 7. Автоматизация и задачи -**Эндпоинты:** -- `GET /automation/tasks` - список автоматических задач -- `POST /automation/tasks` - создать задачу -- `PATCH /automation/tasks/{id}` - обновить задачу -- `DELETE /automation/tasks/{id}` - удалить задачу -- `POST /automation/tasks/{id}/run` - запустить задачу вручную -- `GET /automation/tasks/{id}/history` - история выполнения - -**Польза:** Автоматизация рутинных операций - -#### 8. Управление контентом -**Эндпоинты:** -- `GET /content/templates` - список шаблонов сообщений -- `POST /content/templates` - создать шаблон -- `PATCH /content/templates/{id}` - обновить шаблон -- `DELETE /content/templates/{id}` - удалить шаблон -- `POST /content/templates/{id}/preview` - предпросмотр шаблона -- `GET /content/media-library` - библиотека медиа-файлов -- `POST /content/media-library` - загрузить в библиотеку - -**Польза:** Централизованное управление контентом - -#### 9. Аудит и безопасность -**Эндпоинты:** -- `GET /audit/logs` - журнал действий администраторов -- `GET /audit/logs/{admin_id}` - действия конкретного админа -- `GET /audit/sessions` - активные сессии API -- `POST /audit/sessions/{id}/revoke` - отозвать сессию -- `GET /security/events` - события безопасности -- `POST /security/block-ip` - заблокировать IP -- `GET /security/blocked-ips` - список заблокированных IP - -**Польза:** Безопасность и отслеживание действий - -#### 10. Интеграции и вебхуки -**Эндпоинты:** -- `GET /integrations` - список интеграций -- `POST /integrations` - создать интеграцию -- `PATCH /integrations/{id}` - обновить интеграцию -- `DELETE /integrations/{id}` - удалить интеграцию -- `GET /integrations/{id}/webhooks` - вебхуки интеграции -- `POST /integrations/{id}/webhooks` - создать вебхук -- `GET /integrations/{id}/logs` - логи интеграции -- `POST /integrations/{id}/test` - протестировать интеграцию - -**Польза:** Расширение функциональности через интеграции - -### 🟢 Низкий приоритет - -#### 11. Экспорт и импорт данных -**Эндпоинты:** -- `POST /export/users` - экспорт пользователей -- `POST /export/subscriptions` - экспорт подписок -- `POST /export/transactions` - экспорт транзакций -- `POST /import/users` - импорт пользователей -- `GET /import/templates` - шаблоны для импорта -- `GET /import/{id}/status` - статус импорта - -**Польза:** Работа с большими объемами данных - -#### 12. Тестирование и разработка -**Эндпоинты:** -- `POST /dev/test-notification` - отправить тестовое уведомление -- `POST /dev/simulate-payment` - симулировать платеж -- `POST /dev/create-test-user` - создать тестового пользователя -- `GET /dev/test-endpoints` - список тестовых эндпоинтов - -**Польза:** Упрощение разработки и тестирования - -#### 13. Расширенная статистика по меню -**Эндпоинты:** -- `GET /menu-layout/stats/funnels` - воронки использования меню -- `GET /menu-layout/stats/heatmap` - тепловая карта кликов -- `GET /menu-layout/stats/ab-test` - A/B тестирование кнопок - -**Польза:** Оптимизация UX меню - -#### 14. Управление версиями и обновлениями -**Эндпоинты:** -- `GET /system/version` - версия системы -- `GET /system/updates` - доступные обновления -- `POST /system/updates/check` - проверить обновления -- `GET /system/changelog` - история изменений - -**Польза:** Управление версиями бота - -#### 15. Расширенная работа с промокодами -**Эндпоинты:** -- `GET /promo-codes/stats/usage` - статистика использования -- `POST /promo-codes/batch/create` - массовое создание -- `GET /promo-codes/{id}/users` - пользователи, использовавшие промокод -- `POST /promo-codes/{id}/deactivate` - деактивировать промокод - -**Польза:** Более гибкое управление промокодами - ---- - -## Рекомендации по приоритизации - -### Фаза 1 (Следующие 2-4 недели) -1. Расширенная аналитика и отчеты (п.1) -2. Массовые операции с пользователями (п.2) -3. Расширенное управление подписками (п.3) - -### Фаза 2 (Следующие 1-2 месяца) -4. Улучшенная работа с тикетами (п.4) -5. Управление уведомлениями (п.5) -6. Управление платежными системами (п.6) - -### Фаза 3 (Долгосрочная перспектива) -7. Автоматизация и задачи (п.7) -8. Управление контентом (п.8) -9. Аудит и безопасность (п.9) -10. Интеграции и вебхуки (п.10) - ---- - -## Технические улучшения - -### 1. WebSocket поддержка -- Real-time обновления для дашборда -- Уведомления о новых тикетах -- Мониторинг рассылок в реальном времени - -### 2. GraphQL endpoint -- Альтернатива REST для сложных запросов -- Более гибкая выборка данных - -### 3. Rate limiting по токенам -- Разные лимиты для разных токенов -- Защита от злоупотреблений - -### 4. Версионирование API -- `/v1/`, `/v2/` для обратной совместимости -- Плавная миграция на новые версии - -### 5. Webhooks для событий -- Подписка на события (новый пользователь, платеж, тикет) -- Автоматические уведомления внешних систем - -### 6. Расширенная документация -- Примеры использования для каждого эндпоинта -- Postman коллекция -- SDK для популярных языков (Python, JavaScript) - ---- - -## Метрики для отслеживания использования API - -### Предлагаемые эндпоинты для мониторинга: -- `GET /api/metrics/usage` - статистика использования API -- `GET /api/metrics/endpoints` - популярность эндпоинтов -- `GET /api/metrics/errors` - статистика ошибок -- `GET /api/metrics/performance` - производительность API - ---- - -## Заключение - -Текущий API уже достаточно функционален и покрывает основные потребности веб-админки. Предложенные расширения помогут: - -1. **Улучшить аналитику** - для принятия обоснованных бизнес-решений -2. **Повысить эффективность** - массовые операции и автоматизация -3. **Улучшить UX** - более гибкое управление подписками и тикетами -4. **Повысить безопасность** - аудит и мониторинг -5. **Расширить возможности** - интеграции и вебхуки - -Рекомендуется начать с Фазы 1, так как эти функции наиболее востребованы для ежедневной работы администраторов. -