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