Система полного учета пользователей 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. Создание таблицы

```sql
sqlplus username/password@database @create_users_table.sql
```

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

```env
# 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 методы

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

```python
# Сохранение пользователя
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 запросы

### Топ пользователей по платежам
```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;
```

### Активные за месяц
```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;
```

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

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

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

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

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

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