new_lottery_bot/docs/ACTIVITY_TRACKING.md

Система отслеживания активности пользователей

Описание

Система автоматически отслеживает активность пользователей и блокирует неактивных более 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:

# При получении списка пользователей для рассылки
# автоматически исключаются все заблокированные,
# включая заблокированных за неактивность (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:

class ActivityService:
    # Изменить количество дней
    INACTIVITY_PERIOD_DAYS = 30  # Например, 60 дней

Изменение времени проверки

В файле src/core/scheduler.py:

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 для неактивных

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 запросы для проверки

-- Неактивные более 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. Статистика активности по дням/неделям/месяцам