savagedb_bot/wiki/User-Tracking.md

Система полного учета пользователей Telegram бота в соответствии с требованиями KYC.

Обзор системы

Отслеживает взаимодействия пользователей, финансовые операции и предоставляет аналитику для администратора.

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

👤 Данные пользователя

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

💬 Взаимодействия

• Первое взаимодействие (дата)
• Последнее взаимодействие (дата)
• Количество взаимодействий
• Источник регистрации (команда/кнопка)

💰 Финансы

• Общая сумма платежей (Telegram Stars)
• Количество успешных платежей
• История транзакций

Структура БД

Таблица bot_users с основными полями:

Поле	Тип	Описание
id	NUMBER(19)	Telegram user ID
first_name	VARCHAR2(256)	Имя пользователя
username	VARCHAR2(128)	Username
total_payments	NUMBER(10,2)	Сумма платежей
interaction_count	NUMBER(10)	Число взаимодействий
last_interaction_date	DATE	Последняя активность

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

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

sqlplus username/password@database @create_users_table.sql

2. Настройка переменных

# Oracle Database
db_user=your_oracle_user
db_password=your_oracle_password  
db_dsn=your_oracle_dsn

# Админ для статистики
ADMIN_USER_ID=123456789

3. Интеграция

Код уже интегрирован:

• main.py - обработчики событий
• db.py - методы работы с БД
• Автоматическое сохранение при взаимодействиях

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

/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 методы

Основные функции

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

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

# Статистика пользователя
await db.get_user_stats(user_id: int)

# Общая статистика
await db.get_users_summary()

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

Система сохраняет данные при:

• ✅ Команде /start
• ✅ Нажатии кнопок меню
• ✅ Обработке VIN номеров
• ✅ Совершении платежей
• ✅ Любых взаимодействиях с ботом

Полезные SQL запросы

Топ пользователей по платежам

SELECT first_name, username, total_payments, successful_payments_count
FROM bot_users 
WHERE total_payments > 0 
ORDER BY total_payments DESC 
FETCH FIRST 10 ROWS ONLY;

Активные за месяц

SELECT COUNT(*) as active_users
FROM bot_users 
WHERE last_interaction_date >= SYSDATE - 30
AND is_active = 1;

Конверсия в платежи

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;

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

GDPR/Персональные данные

• 🔒 Только данные из Telegram API
• 🔒 Использование только для сервиса
• 🔒 Возможность деактивации пользователей

Финансовая отчетность

• 📊 Логирование всех платежей
• 📊 Связь платежей с пользователями
• 📊 Генерация отчетов

Мониторинг

• 👁️ Отслеживание активности
• 👁️ Выявление подозрительной активности
• 👁️ Бизнес-аналитика

Связанные страницы

• Home - общая информация о боте
• Development - разработка и отладка