164 lines
5.1 KiB
Markdown
164 lines
5.1 KiB
Markdown
Система полного учета пользователей 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]] - разработка и отладка |