Add statistics endpoints in MenuLayoutService for button clicks, including by type, hour, weekday, top users, period comparison, and user click sequences

docs/menu_stats_api_usage.md

@@ -118,6 +118,136 @@ POST /menu-layout/stats/log-click
 }
 ```
 
+### 4. Статистика по типам кнопок
+
+**GET** `/menu-layout/stats/by-type?days=30`
+
+**Возвращает:**
+- Статистику кликов по каждому типу кнопок (builtin, callback, url, mini_app)
+- Общее количество кликов по типам
+
+**Пример:**
+```python
+stats = await MenuLayoutService.get_stats_by_button_type(db, days=30)
+# Возвращает:
+# [
+#     {"button_type": "builtin", "clicks_total": 500, "unique_users": 100},
+#     {"button_type": "callback", "clicks_total": 200, "unique_users": 50},
+#     ...
+# ]
+```
+
+### 5. Статистика по часам дня
+
+**GET** `/menu-layout/stats/by-hour?button_id=menu_balance&days=30`
+
+**Параметры:**
+- `button_id` (optional) - ID кнопки для фильтрации
+- `days` (default: 30) - период в днях
+
+**Возвращает:**
+- Распределение кликов по часам дня (0-23)
+
+**Пример:**
+```python
+stats = await MenuLayoutService.get_clicks_by_hour(db, button_id="menu_balance", days=30)
+# Возвращает:
+# [
+#     {"hour": 9, "count": 50},
+#     {"hour": 10, "count": 75},
+#     ...
+# ]
+```
+
+### 6. Статистика по дням недели
+
+**GET** `/menu-layout/stats/by-weekday?button_id=menu_balance&days=30`
+
+**Возвращает:**
+- Распределение кликов по дням недели (0=понедельник, 6=воскресенье)
+
+**Пример:**
+```python
+stats = await MenuLayoutService.get_clicks_by_weekday(db, button_id="menu_balance", days=30)
+# Возвращает:
+# [
+#     {"weekday": 0, "weekday_name": "Понедельник", "count": 100},
+#     {"weekday": 1, "weekday_name": "Вторник", "count": 120},
+#     ...
+# ]
+```
+
+### 7. Топ пользователей по кликам
+
+**GET** `/menu-layout/stats/top-users?button_id=menu_balance&limit=10&days=30`
+
+**Параметры:**
+- `button_id` (optional) - ID кнопки для фильтрации
+- `limit` (default: 10) - количество пользователей
+- `days` (default: 30) - период в днях
+
+**Возвращает:**
+- Список пользователей с наибольшим количеством кликов
+
+**Пример:**
+```python
+top_users = await MenuLayoutService.get_top_users(db, button_id="menu_balance", limit=10, days=30)
+# Возвращает:
+# [
+#     {"user_id": 123456789, "clicks_count": 50, "last_click_at": datetime(...)},
+#     ...
+# ]
+```
+
+### 8. Сравнение периодов
+
+**GET** `/menu-layout/stats/compare?button_id=menu_balance&current_days=7&previous_days=7`
+
+**Параметры:**
+- `button_id` (optional) - ID кнопки для фильтрации
+- `current_days` (default: 7) - период текущего сравнения
+- `previous_days` (default: 7) - период предыдущего сравнения
+
+**Возвращает:**
+- Сравнение текущего и предыдущего периода
+- Изменение в абсолютных числах и процентах
+- Тренд (up/down/stable)
+
+**Пример:**
+```python
+comparison = await MenuLayoutService.get_period_comparison(
+    db, button_id="menu_balance", current_days=7, previous_days=7
+)
+# Возвращает:
+# {
+#     "current_period": {"clicks": 100, "days": 7, ...},
+#     "previous_period": {"clicks": 80, "days": 7, ...},
+#     "change": {"absolute": 20, "percent": 25.0, "trend": "up"}
+# }
+```
+
+### 9. Последовательности кликов пользователя
+
+**GET** `/menu-layout/stats/users/{user_id}/sequences?limit=50`
+
+**Параметры:**
+- `user_id` (path) - ID пользователя
+- `limit` (default: 50) - максимальное количество записей
+
+**Возвращает:**
+- Хронологическую последовательность кликов пользователя
+
+**Пример:**
+```python
+sequences = await MenuLayoutService.get_user_click_sequences(db, user_id=123456789, limit=50)
+# Возвращает:
+# [
+#     {"button_id": "menu_balance", "button_text": "💰 Баланс", "clicked_at": datetime(...)},
+#     {"button_id": "menu_subscription", "button_text": "📊 Подписка", "clicked_at": datetime(...)},
+#     ...
+# ]
+```
+
 ## Важные замечания
 
 1. **Автоматическое логирование**: Все клики по кнопкам логируются автоматически через `ButtonStatsMiddleware`
@@ -125,4 +255,5 @@ POST /menu-layout/stats/log-click
 3. **button_id**: Используется `callback_data` кнопки как идентификатор
 4. **Производительность**: Логирование выполняется асинхронно в фоне и не блокирует обработку запросов
 5. **Активация**: Middleware работает только если `MENU_LAYOUT_ENABLED=True` в настройках
+6. **Временные зоны**: Все временные метрики используют локальное время сервера