This commit is contained in:
209
docs/ACTIVITY_TRACKING.md
Normal file
209
docs/ACTIVITY_TRACKING.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# Система отслеживания активности пользователей
|
||||
|
||||
## Описание
|
||||
|
||||
Система автоматически отслеживает активность пользователей и блокирует неактивных более 30 дней для исключения из рассылок.
|
||||
|
||||
## Компоненты
|
||||
|
||||
### 1. База данных
|
||||
|
||||
**Новое поле в таблице `users`:**
|
||||
- `last_activity` - дата и время последней активности пользователя
|
||||
- Автоматически обновляется при каждом взаимодействии с ботом
|
||||
|
||||
**Миграция:**
|
||||
- Файл: `migrations/versions/20260215_1201_08_1f1631301809_add_last_activity_to_users.py`
|
||||
- Добавляет поле `last_activity` и заполняет его значением `created_at` для существующих пользователей
|
||||
|
||||
### 2. ActivityService
|
||||
|
||||
**Файл:** `src/core/activity_service.py`
|
||||
|
||||
**Основные методы:**
|
||||
|
||||
- `update_user_activity(session, telegram_id)` - обновить последнюю активность пользователя
|
||||
- `get_inactive_users(session, days=30)` - получить список неактивных пользователей
|
||||
- `mark_inactive_users(session, days=30)` - пометить неактивных как заблокированных
|
||||
- `reactivate_user(session, telegram_id)` - реактивировать пользователя при новой активности
|
||||
- `check_and_mark_inactive_users()` - проверка для планировщика
|
||||
|
||||
**Параметры:**
|
||||
- `INACTIVITY_PERIOD_DAYS = 30` - период неактивности по умолчанию
|
||||
|
||||
### 3. ActivityMiddleware
|
||||
|
||||
**Файл:** `src/middlewares/activity.py`
|
||||
|
||||
Автоматически:
|
||||
- Обновляет `last_activity` при каждом сообщении или callback
|
||||
- Реактивирует пользователей, помеченных как неактивные
|
||||
|
||||
### 4. Планировщик задач
|
||||
|
||||
**Файл:** `src/core/scheduler.py`
|
||||
|
||||
**Расписание:**
|
||||
- Проверка неактивных пользователей: каждый день в 03:00
|
||||
|
||||
**Задачи:**
|
||||
- `check_inactive_users` - находит и блокирует неактивных пользователей
|
||||
|
||||
### 5. Интеграция с рассылками
|
||||
|
||||
**Модификации в `broadcast_services.py`:**
|
||||
```python
|
||||
# При получении списка пользователей для рассылки
|
||||
# автоматически исключаются все заблокированные,
|
||||
# включая заблокированных за неактивность (error_type='inactive')
|
||||
```
|
||||
|
||||
### 6. Админ-панель
|
||||
|
||||
**Новая секция "Неактивные пользователи":**
|
||||
|
||||
**Доступ:** Админ-панель → Массовая рассылка → ⏰ Неактивные пользователи
|
||||
|
||||
**Функции:**
|
||||
- Просмотр статистики неактивных пользователей
|
||||
- Количество заблокированных за неактивность
|
||||
- Список первых 10 неактивных с указанием дней неактивности
|
||||
- Кнопка "🔄 Проверить сейчас" - запуск проверки вручную
|
||||
|
||||
## Логика работы
|
||||
|
||||
### Отслеживание активности
|
||||
|
||||
1. Пользователь отправляет сообщение или нажимает callback
|
||||
2. `ActivityMiddleware` перехватывает событие
|
||||
3. Обновляется `last_activity` в базе данных
|
||||
4. Если пользователь был заблокирован за неактивность - реактивируется
|
||||
|
||||
### Автоматическая блокировка
|
||||
|
||||
1. Каждый день в 03:00 запускается задача `check_inactive_users`
|
||||
2. Система находит пользователей с `last_activity > 30 дней`
|
||||
3. Для каждого создается запись в `blocked_users`:
|
||||
- `error_type = 'inactive'`
|
||||
- `error_message = 'User inactive for 30 days'`
|
||||
- `is_active = True`
|
||||
4. Эти пользователи исключаются из будущих рассылок
|
||||
|
||||
### Реактивация
|
||||
|
||||
1. Неактивный пользователь снова взаимодействует с ботом
|
||||
2. `ActivityMiddleware` обновляет `last_activity`
|
||||
3. Запись в `blocked_users` деактивируется (`is_active = False`)
|
||||
4. Пользователь снова получит рассылки
|
||||
|
||||
## Настройка
|
||||
|
||||
### Изменение периода неактивности
|
||||
|
||||
В файле `src/core/activity_service.py`:
|
||||
|
||||
```python
|
||||
class ActivityService:
|
||||
# Изменить количество дней
|
||||
INACTIVITY_PERIOD_DAYS = 30 # Например, 60 дней
|
||||
```
|
||||
|
||||
### Изменение времени проверки
|
||||
|
||||
В файле `src/core/scheduler.py`:
|
||||
|
||||
```python
|
||||
self.scheduler.add_job(
|
||||
self._check_inactive_users,
|
||||
trigger=CronTrigger(hour=3, minute=0), # Изменить час и минуты
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
## Требования
|
||||
|
||||
**Добавлена зависимость:**
|
||||
- `apscheduler==3.10.4` в `requirements.txt`
|
||||
|
||||
## Логирование
|
||||
|
||||
Все действия системы логируются:
|
||||
- Обновление активности пользователей
|
||||
- Пометка неактивных пользователей
|
||||
- Реактивация пользователей
|
||||
- Запуск и остановка планировщика
|
||||
|
||||
**Примеры логов:**
|
||||
```
|
||||
INFO - Пользователь 123456789 помечен как неактивный (последняя активность: 2026-01-15)
|
||||
INFO - Пользователь 123456789 реактивирован
|
||||
INFO - Проверка неактивных пользователей завершена. Помечено: 5
|
||||
```
|
||||
|
||||
## База данных
|
||||
|
||||
### Структура BlockedUser для неактивных
|
||||
|
||||
```sql
|
||||
INSERT INTO blocked_users (
|
||||
telegram_id,
|
||||
error_type,
|
||||
error_message,
|
||||
is_active
|
||||
) VALUES (
|
||||
123456789,
|
||||
'inactive',
|
||||
'User inactive for 30 days',
|
||||
true
|
||||
);
|
||||
```
|
||||
|
||||
## Тестирование
|
||||
|
||||
### Ручной запуск проверки
|
||||
|
||||
1. Зайти в Админ-панель
|
||||
2. Массовая рассылка → Неактивные пользователи
|
||||
3. Нажать "🔄 Проверить сейчас"
|
||||
4. Система покажет количество помеченных пользователей
|
||||
|
||||
### Проверка middleware
|
||||
|
||||
Отправьте любое сообщение боту или нажмите callback - поле `last_activity` должно обновиться в БД.
|
||||
|
||||
### SQL запросы для проверки
|
||||
|
||||
```sql
|
||||
-- Неактивные более 30 дней
|
||||
SELECT * FROM users
|
||||
WHERE last_activity < NOW() - INTERVAL '30 days'
|
||||
AND is_registered = true;
|
||||
|
||||
-- Заблокированные за неактивность
|
||||
SELECT * FROM blocked_users
|
||||
WHERE error_type = 'inactive'
|
||||
AND is_active = true;
|
||||
|
||||
-- Проверка last_activity
|
||||
SELECT telegram_id, username, first_name, last_activity
|
||||
FROM users
|
||||
ORDER BY last_activity DESC
|
||||
LIMIT 10;
|
||||
```
|
||||
|
||||
## Преимущества
|
||||
|
||||
1. **Автоматизация** - не требует ручного вмешательства
|
||||
2. **Гибкость** - легко настроить период неактивности
|
||||
3. **Реактивация** - пользователи автоматически возвращаются в рассылки при активности
|
||||
4. **Контроль** - админ может видеть статистику и запускать проверку вручную
|
||||
5. **Оптимизация** - не отправляются сообщения неактивным пользователям
|
||||
6. **Логирование** - все действия фиксируются
|
||||
|
||||
## Возможные улучшения
|
||||
|
||||
1. Настраиваемый период через админ-панель
|
||||
2. Email уведомления администратору о заблокированных пользователях
|
||||
3. Отправка уведомления пользователю перед блокировкой
|
||||
4. Разные периоды для разных типов пользователей
|
||||
5. Статистика активности по дням/неделям/месяцам
|
||||
Reference in New Issue
Block a user