remnawave-bedolaga-telegram-bot/docs/menu_stats_api_usage.md

# Использование API статистики кнопок меню

## Обзор

Система статистики кликов по кнопкам меню позволяет отслеживать, какие кнопки чаще всего нажимают пользователи.

## API Эндпоинты

### 1. Логирование клика по кнопке

**POST** `/menu-layout/stats/log-click`

**Параметры:**
- `button_id` (str) - ID кнопки
- `user_id` (int, optional) - ID пользователя (telegram_id)
- `callback_data` (str, optional) - callback_data кнопки
- `button_type` (str, optional) - тип кнопки: `builtin`, `callback`, `url`, `mini_app`
- `button_text` (str, optional) - текст кнопки на момент клика

**Пример:**
```python
await MenuLayoutService.log_button_click(
    db,
    button_id="menu_balance",
    user_id=123456789,
    callback_data="menu_balance",
    button_type="builtin",
    button_text="💰 Баланс"
)
```

### 2. Получение статистики по конкретной кнопке

**GET** `/menu-layout/stats/buttons/{button_id}?days=30`

**Возвращает:**
- `clicks_total` - общее количество кликов
- `clicks_today` - клики сегодня
- `clicks_week` - клики за неделю
- `clicks_month` - клики за месяц
- `unique_users` - уникальные пользователи
- `last_click_at` - последний клик
- `clicks_by_day` - клики по дням

**Пример:**
```python
stats = await MenuLayoutService.get_button_stats(db, "menu_balance", days=30)
# Возвращает:
# {
#     "button_id": "menu_balance",
#     "clicks_total": 150,
#     "clicks_today": 5,
#     "clicks_week": 25,
#     "clicks_month": 150,
#     "unique_users": 45,
#     "last_click_at": datetime(...)
# }
```

### 3. Получение общей статистики по всем кнопкам

**GET** `/menu-layout/stats?days=30`

**Возвращает:**
- `items` - список статистики по каждой кнопке
- `total_clicks` - общее количество кликов
- `period_start` - начало периода
- `period_end` - конец периода

**Пример:**
```python
all_stats = await MenuLayoutService.get_all_buttons_stats(db, days=30)
total = await MenuLayoutService.get_total_clicks(db, days=30)
```

## Автоматическое логирование

✅ **Логирование кликов происходит автоматически!**

Все клики по кнопкам автоматически логируются через `ButtonStatsMiddleware`. Middleware перехватывает все `CallbackQuery` события и логирует их в базу данных.

### Как это работает

1. При каждом клике по кнопке middleware автоматически:
   - Извлекает `callback_data` (используется как `button_id`)
   - Получает `user_id` из события
   - Определяет тип кнопки (`builtin`, `callback`, `url`)
   - Извлекает текст кнопки из клавиатуры (если доступен)
   - Логирует в базу данных асинхронно (не блокирует обработку)

2. Middleware активируется автоматически, если `MENU_LAYOUT_ENABLED=True`

3. Логирование происходит в фоновом режиме и не влияет на производительность

### Ручное логирование (опционально)

Если нужно логировать клики вручную (например, для внешних интеграций), можно использовать API:

```python
# Через сервис
await MenuLayoutService.log_button_click(
    db,
    button_id="custom_button",
    user_id=user_id,
    callback_data="custom_callback",
    button_type="callback",
    button_text="Кастомная кнопка"
)

# Или через API эндпоинт
POST /menu-layout/stats/log-click
{
    "button_id": "custom_button",
    "user_id": 123456789,
    "callback_data": "custom_callback",
    "button_type": "callback",
    "button_text": "Кастомная кнопка"
}
```

## Важные замечания

1. **Автоматическое логирование**: Все клики по кнопкам логируются автоматически через `ButtonStatsMiddleware`
2. **Требуется авторизация**: API эндпоинты для получения статистики требуют токен авторизации (`require_api_token`)
3. **button_id**: Используется `callback_data` кнопки как идентификатор
4. **Производительность**: Логирование выполняется асинхронно в фоне и не блокирует обработку запросов
5. **Активация**: Middleware работает только если `MENU_LAYOUT_ENABLED=True` в настройках