# Referral Source Tracking

Отслеживание источников привлечения пользователей через Telegram deep links.

## Как работает

1. Создаёте ссылку с меткой источника: `https://t.me/YourBotName?start=source_tag`
2. Пользователь переходит по ссылке → Telegram отправляет боту `/start source_tag`
3. Бот сохраняет `source_tag` как `ref_source` при первом создании пользователя
4. При повторном `/start` (с другой меткой или без) — оригинальный источник **не перезаписывается**

## Формат ссылок

```
https://t.me/YourBotName?start={source_tag}
```

`source_tag` — произвольная строка без пробелов (латиница, цифры, `_`, `-`).

### Примеры

| Канал | Ссылка |
|-------|--------|
| YouTube | `https://t.me/YourBotName?start=youtube` |
| YouTube (январь) | `https://t.me/YourBotName?start=youtube_jan` |
| VK группа | `https://t.me/YourBotName?start=vk_group` |
| Telegram Ads | `https://t.me/YourBotName?start=tgads_feb` |
| Блогер Иванов | `https://t.me/YourBotName?start=blogger_ivanov` |
| QR на выставке | `https://t.me/YourBotName?start=expo_2026` |

### Рекомендации по именованию

- Используйте формат `канал_кампания`: `youtube_jan`, `vk_launch`, `tgads_feb`
- Только латиница, цифры, `_` и `-`
- Без пробелов (Telegram их не поддерживает в deep links)

## Админ-команды (viewer bot)

### Посмотреть источник конкретного пользователя

```
/user <user_id>
```

В карточке пользователя отображается строка `Источник: youtube_jan` (или `—` если без метки).

### Агрегированная статистика по источникам

```
/refstats
```

Вывод:
```
📊 Источники пользователей

`youtube_jan`: 42
`vk_group`: 18
`tgads_feb`: 7
(без источника): 156
```

## Проверка в БД напрямую

```bash
# Все пользователи с источниками
sqlite3 /mnt/video/videobot_prod.db \
  "SELECT user_id, username, first_name, ref_source, created_at FROM users WHERE ref_source IS NOT NULL"

# Статистика по источникам
sqlite3 /mnt/video/videobot_prod.db \
  "SELECT ref_source, COUNT(*) as count FROM users GROUP BY ref_source ORDER BY count DESC"
```

## Ограничения

- Источник записывается **только при первом** `/start` (создание пользователя)
- Если пользователь уже существует — повторный `/start` с другой меткой не обновит источник
- Telegram передаёт аргументы `/start` только через deep link, не при обычном нажатии кнопки Start
