savagedb_bot/wiki/README_USER_TRACKING.md

# 📊 Система учета пользователей SalvageDB Bot

## 🎯 Обзор

Данная система реализует полный учет пользователей Telegram бота в соответствии с требованиями KYC (Know Your Customer) для сервисов, принимающих платежи.

## 📝 Что отслеживается

### Данные пользователя Telegram:
- **ID пользователя** (уникальный 64-bit идентификатор)
- **Имя и фамилия** пользователя
- **Username** (если есть)
- **Код языка** (IETF language tag)
- **Статус Premium** в Telegram
- **Флаг бота** (для различения ботов и пользователей)

### Данные взаимодействий:
- **Дата первого взаимодействия**
- **Дата последнего взаимодействия**
- **Количество взаимодействий**
- **Источник регистрации** (какая команда/кнопка)

### Финансовые данные:
- **Общая сумма платежей** в Telegram Stars
- **Количество успешных платежей**
- **История транзакций**

## 🗄️ Структура базы данных

### Таблица `bot_users`

```sql
CREATE TABLE bot_users (
    id NUMBER(19) PRIMARY KEY,                      -- Telegram user ID
    first_name VARCHAR2(256) NOT NULL,             -- Имя пользователя
    last_name VARCHAR2(256),                       -- Фамилия (опционально)
    username VARCHAR2(128),                        -- Username (опционально)
    language_code VARCHAR2(10),                    -- Код языка
    is_bot NUMBER(1) DEFAULT 0 NOT NULL,          -- Флаг бота
    is_premium NUMBER(1) DEFAULT 0,               -- Telegram Premium
    added_to_attachment_menu NUMBER(1) DEFAULT 0,  -- Добавлен в меню вложений
    first_interaction_date DATE DEFAULT SYSDATE,   -- Первое взаимодействие
    last_interaction_date DATE DEFAULT SYSDATE,    -- Последнее взаимодействие
    interaction_count NUMBER(10) DEFAULT 1,        -- Количество взаимодействий
    is_active NUMBER(1) DEFAULT 1,                -- Активен ли пользователь
    is_blocked NUMBER(1) DEFAULT 0,               -- Заблокирован ли
    registration_source VARCHAR2(50) DEFAULT 'bot', -- Источник регистрации
    total_payments NUMBER(10,2) DEFAULT 0,         -- Сумма платежей
    successful_payments_count NUMBER(8) DEFAULT 0, -- Количество платежей
    created_at DATE DEFAULT SYSDATE,              -- Дата создания записи
    updated_at DATE DEFAULT SYSDATE               -- Дата обновления
);
```

## 🚀 Развертывание

### 1. Создание таблицы в Oracle

```bash
# Выполните SQL скрипт для создания таблицы
sqlplus username/password@database @create_users_table.sql
```

### 2. Настройка переменных окружения

Добавьте в ваш `.env` файл:

```env
# Настройки базы данных (уже должны быть)
db_user=your_oracle_user
db_password=your_oracle_password
db_dsn=your_oracle_dsn

# ID администратора для команды /admin_stats
ADMIN_USER_ID=123456789
```

### 3. Обновление кода

Код уже интегрирован в основные файлы:
- `main.py` - обработчики с сохранением данных пользователей
- `db.py` - методы для работы с пользователями
- `create_users_table.sql` - SQL скрипт для создания таблицы

## 📈 Использование

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

Система автоматически сохраняет данные пользователя при:
- Использовании команды `/start`
- Нажатии любых кнопок
- Обработке VIN
- Совершении платежей

### Команды администратора

```
/admin_stats - Просмотр статистики пользователей
```

Пример вывода:
```
📊 Bot Users Statistics

👥 Users Overview:
• Total users: 1,234
• Premium users: 156

💰 Revenue:
• Total revenue: 567 ⭐️
• Total transactions: 445

📈 Activity:
• Active last 24h: 89
• Active last week: 234
```

## 🔧 API методы

### Сохранение пользователя
```python
await db.save_user(user: User, interaction_source: str = "bot") -> bool
```

### Обновление платежных данных
```python
await db.update_user_payment(user_id: int, payment_amount: float) -> bool
```

### Получение статистики пользователя
```python
await db.get_user_stats(user_id: int) -> Optional[dict]
```

### Общая статистика
```python
await db.get_users_summary() -> dict
```

## 🛡️ Безопасность и соответствие

### GDPR/Персональные данные:
- Сохраняются только данные, предоставляемые Telegram API
- Данные используются только для предоставления сервиса
- Пользователи могут быть помечены как неактивные

### Финансовая отчетность:
- Все платежи логируются с timestamp
- Связь платежей с пользователями для аудита
- Возможность генерации отчетов

### Мониторинг:
- Отслеживание активности пользователей
- Выявление подозрительной активности
- Статистика для бизнес-аналитики

## 📊 Полезные запросы

### Топ пользователей по платежам:
```sql
SELECT first_name, last_name, username, total_payments, successful_payments_count
FROM bot_users 
WHERE total_payments > 0 
ORDER BY total_payments DESC 
FETCH FIRST 10 ROWS ONLY;
```

### Активные пользователи за месяц:
```sql
SELECT COUNT(*) as active_users
FROM bot_users 
WHERE last_interaction_date >= SYSDATE - 30
AND is_active = 1;
```

### Конверсия в платящих пользователей:
```sql
SELECT 
    COUNT(*) as total_users,
    COUNT(CASE WHEN successful_payments_count > 0 THEN 1 END) as paying_users,
    ROUND(COUNT(CASE WHEN successful_payments_count > 0 THEN 1 END) * 100.0 / COUNT(*), 2) as conversion_rate
FROM bot_users 
WHERE is_active = 1;
```

## 🔍 Мониторинг и алерты

Рекомендуется настроить мониторинг для:
- Необычно высокой активности от одного пользователя
- Большого количества возвратов платежей
- Резкого роста/падения количества новых пользователей

## 📞 Поддержка

При возникновении проблем проверьте:
1. Права доступа к таблице `bot_users`
2. Корректность переменных окружения
3. Логи приложения для ошибок базы данных

Все операции с базой данных логируются для отладки.