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

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

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

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

Добавьте в ваш .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 методы

Сохранение пользователя

await db.save_user(user: User, interaction_source: str = "bot") -> bool

Обновление платежных данных

await db.update_user_payment(user_id: int, payment_amount: float) -> bool

Получение статистики пользователя

await db.get_user_stats(user_id: int) -> Optional[dict]

Общая статистика

await db.get_users_summary() -> dict

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

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

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

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

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

Мониторинг:

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

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

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

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;

Активные пользователи за месяц:

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;

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

Рекомендуется настроить мониторинг для:

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

📞 Поддержка

При возникновении проблем проверьте:

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

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