# Админ-бот: руководство пользователя

Админ-бот (viewer bot) — это отдельный Telegram-бот для управления основным ботом. Через него можно просматривать видео, управлять пользователями, токенами, подарками и портфолио.

---

## Оглавление

- [Начало работы](#начало-работы)
- [Просмотр видео](#просмотр-видео)
- [Переключение базы данных](#переключение-базы-данных)
- [Управление пользователями](#управление-пользователями)
- [Токены: начисление и списание](#токены-начисление-и-списание)
- [Статистика](#статистика)
- [Промо-цены](#промо-цены)
- [Раздача токенов (Giveaway)](#раздача-токенов-giveaway)
- [Подарки (Gift Packs)](#подарки-gift-packs)
- [Портфолио (Showcase)](#портфолио-showcase)
- [Отправка видео в подарок](#отправка-видео-в-подарок)
- [Источники трафика](#источники-трафика)

---

## Начало работы

`/start` или `/help` — показывает меню бота.

Бот работает с двумя базами данных: **DEV** (тестовая) и **PROD** (боевая). По умолчанию используется DEV. Переключение — см. ниже.

---

## Просмотр видео

### Список товаров

```
/products
/products 2        — вторая страница
```

Показывает все товары, для которых генерировались видео. Кнопками можно листать страницы.

### Карточка товара

```
/product 271933299
/p_271933299        — короткая запись
```

Показывает товар и список всех генераций. Под каждой генерацией — кнопка для просмотра видео.

### Просмотр видео

```
/video 20260205_142848_w5ij
/v_20260205_142848_w5ij    — короткая запись
```

Показывает метаданные видео (промпты, стиль, режим) и отправляет сам файл. Под видео — кнопки оценки и добавления в портфолио.

### Поиск

```
/search кастрюля красная
```

Поиск по описаниям товаров. Можно писать на естественном языке. Также можно просто написать текст без команды — бот поймёт.

### Оценка видео

```
/rate good
/rate bad
```

Оценивает последнее просмотренное видео. Также доступно кнопками под видео.

### Комментарий

```
/comment Хорошее видео, но слишком тёмное
```

Добавляет комментарий к последнему просмотренному видео.

---

## Переключение базы данных

```
/dev     — работать с тестовой базой
/prod    — работать с боевой базой
```

После переключения все команды (пользователи, токены, статистика) работают с выбранной базой. В ответе каждой команды показывается текущая база: `[DEV]` или `[PROD]`.

**Важно:** перед любыми действиями с реальными пользователями убедитесь, что вы в `/prod`.

---

## Управление пользователями

### Список пользователей

```
/users         — первая страница
/users 3       — третья страница
```

Показывает всех пользователей: ID, имя, баланс. Листается кнопками.

### Карточка пользователя

```
/user 123456789
```

Подробная информация:
- Имя и username
- Баланс токенов
- Сколько купил и использовал
- Промо-статус
- Заблокирован или нет
- Откуда пришёл (источник)
- Подарки (если есть)
- Последние транзакции

Под карточкой — кнопки быстрого начисления (+10, +100), списания (-10) и блокировки.

### Поиск пользователя

```
/usearch Иван
/usearch testuser
/usearch 123456789
```

Ищет по имени, username или ID.

### Блокировка

```
/block 123456789 причина
/unblock 123456789
```

Заблокированный пользователь не может пользоваться основным ботом.

---

## Токены: начисление и списание

### Начислить токены

```
/grant 123456789 10
/grant 123456789 5 Бонус за отзыв
```

Первый аргумент — ID пользователя, второй — количество токенов, третий (необязательный) — причина.

### Списать токены

```
/revoke 123456789 5
/revoke 123456789 3 Ошибочное начисление
```

Списание не может привести к отрицательному балансу.

### Последние транзакции

```
/txns          — последние 20 транзакций
/txns 50       — последние 50
```

Показывает все операции по всем пользователям: покупки, генерации, возвраты, начисления.

Значки операций:
- 💳 — покупка
- 🎬 — генерация (списание)
- ↩️ — возврат
- 🎁 — начисление / активация подарка
- ⛔ — списание администратором
- 📦 — миграция
- 🎉 — раздача (giveaway)

---

## Статистика

### Общая статистика по видео

```
/stats
```

Количество товаров, генераций, оценок.

### Статистика по токенам

```
/tokenstats
```

Сводка по всей системе:
- Всего пользователей
- С балансом / заблокированных
- Общий баланс токенов
- Выручка
- Промо-слоты
- Разбивка транзакций по типам

---

## Промо-цены

```
/promo          — показать сколько промо-слотов осталось
/promo 200      — установить 200 промо-слотов
```

Промо-слоты определяют, сколько ещё пользователей могут купить токены по сниженной цене. Когда слоты заканчиваются — все покупают по обычной цене.

---

## Раздача токенов (Giveaway)

Автоматическая раздача токенов новым пользователям. Токены зачисляются **сразу на баланс**.

### Запустить

```
/giveaway_start 100        — первые 100 новых пользователей получат 3 токена
/giveaway_start 50 5       — первые 50 получат по 5 токенов
```

После запуска: каждый новый пользователь автоматически получает токены при первом взаимодействии с ботом. Когда слоты заканчиваются — раздача прекращается.

### Остановить

```
/giveaway_stop
```

Показывает статистику: сколько пользователей получили, сколько токенов роздано, сколько слотов осталось.

---

## Подарки (Gift Packs)

Подарки — это токены **с ограниченным сроком действия**. В отличие от раздачи (giveaway), токены НЕ зачисляются на баланс сразу. Подарок автоматически активируется, когда пользователь отправляет ссылку на товар.

Каждый пользователь может получить подарок **только один раз** (администратор может обойти это ограничение).

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

1. Администратор создаёт **кампанию** (правило автоматической раздачи)
2. Новый пользователь приходит в бот → получает подарок (видит сообщение)
3. Пользователь отправляет ссылку на товар → подарок активируется, токены на балансе
4. Если не использовал до истечения срока → подарок сгорает
5. За 24 часа до истечения — напоминание

### Кампании

Кампания — это правило, по которому подарки раздаются автоматически.

**Показать все кампании:**

```
/giftcamp list
```

**Создать кампанию для новых пользователей:**

```
/giftcamp new_user 3 7
/giftcamp new_user 3 7 100
```

- `3` — количество токенов в подарке
- `7` — срок действия в днях
- `100` — количество слотов (необязательно; если не указать — безлимит)

Пример: `/giftcamp new_user 3 7 100` — первые 100 новых пользователей получат по 3 генерации на 7 дней.

**Создать кампанию по deeplink (рекламная ссылка):**

```
/giftcamp deeplink campaign_tag 5 3 50
```

- `campaign_tag` — метка источника (та же, что в ссылке `t.me/YourBotName?start=campaign_tag`)
- `5` — токенов
- `3` — дней
- `50` — слотов

Пользователи, пришедшие по этой ссылке, получат подарок. Deeplink-кампания имеет приоритет над кампанией для новых пользователей.

**Остановить кампанию:**

```
/giftcamp stop 1
```

Где `1` — ID кампании (виден в `/giftcamp list`).

### Ручная отправка подарка

```
/giftpack 123456789 3
/giftpack 123456789 5 14
```

- `123456789` — ID пользователя
- `3` — токенов
- `14` — дней (необязательно, по умолчанию 7)

Отправляет подарок конкретному пользователю. Обходит ограничение «один подарок на пользователя» — можно отправить даже тому, кто уже получал.

### Просмотр подарков

```
/giftpacks              — общая статистика по всем подаркам
/giftpacks 123456789    — подарки конкретного пользователя
```

Статусы подарков:
- ✅ active — активный, ожидает использования
- 💰 redeemed — использован (токены на балансе)
- ⏰ expired — истёк, не был использован

### Массовая отправка

```
/giftbulk 3 7
```

- `3` — токенов
- `7` — дней

Находит всех **неактивных** пользователей (ни разу не покупали, не использовали токены, не получали подарков) и предлагает отправить им подарки. Перед отправкой показывает количество и просит подтверждение.

---

## Портфолио (Showcase)

Портфолио — коллекция лучших видео, которые показываются пользователям по команде `/portfolio` в основном боте.

### Просмотр портфолио

```
/showcase          — первая страница
/showcase 2        — вторая страница
```

Показывает все видео в портфолио с рейтингами.

### Добавить видео

```
/showcase_add 20260205_142848_w5ij
/showcase_add 20260205_142848_w5ij 5
```

- Первый аргумент — task_id видео
- Второй (необязательный) — рейтинг от 1 до 5

Также можно добавить кнопкой ➕ при просмотре видео через `/video`.

### Удалить видео

```
/showcase_rm 15
```

Где `15` — ID записи в портфолио (виден в `/showcase`).

### Рейтинг и кнопки

При просмотре видео через `/video` доступны кнопки:
- ➕ / ➖ — добавить/убрать из портфолио
- ⭐ 1-5 — установить рейтинг

Видео с более высоким рейтингом показываются пользователям чаще.

---

## Отправка видео в подарок

```
/gift 123456789 20260205_142848_w5ij
/gift 123456789 20260205_142848_w5ij Вот пример видео для вашего товара!
```

Отправляет готовое видео пользователю в основной бот. Пользователь увидит видео с кнопками оценки. Полезно для демонстрации возможностей конкретному пользователю.

---

## Источники трафика

```
/refstats
```

Показывает откуда приходят пользователи — статистику по меткам из deeplink-ссылок (`t.me/YourBotName?start=метка`).

Источник каждого конкретного пользователя также виден в `/user <id>`.
