# CLAUDE.md

Инструкции для Claude Code при работе с этим репозиторием.

## Цель проекта

Автоматизированная генерация промо-видео для товаров с маркетплейсов (Wildberries). Telegram-бот принимает ссылку на товар и создает 8-секундное видео с 2-актной структурой.

## Текущая фаза

**Production MVP** — рабочий бот с полным пайплайном генерации видео.

## Архитектура

```
Telegram Bot → Pipeline V2 → NanoBanana (изображения) → Veo3 (видео)
                  ↓
         Sellematics API (данные о товаре)
              или
         Playwright scraper (fallback)
```

### Пайплайн генерации (4 этапа)

1. **Stage 1: Data Extraction** — получение данных о товаре
   - Основной источник: Sellematics API (требует SSH туннель)
   - Fallback: Playwright scraper (`wb_fetcher_enhanced.py`)
   - Данные: название, описание, характеристики, изображения, рейтинг

2. **Stage 2: Story Vision** — Claude создает концепцию видео
   - Выбор архетипа (7 типов: problem_solution, before_after, epic_hero, gift, etc.)
   - Выбор стиля (20 visual_styles × 18 video_kinds = 360 комбинаций)
   - Создание 2-актной истории на основе фидбека

3. **Stage 3: Frame Design** — Claude создает промпты для NanoBanana
   - Анализ изображений товара через Vision API
   - Генерация детальных фото-промптов для Act 1 и Act 2

4. **Stage 4: Video Prompt** — сборка финального промпта для Veo3
   - Объединение сцен с переходами
   - Добавление негативных промптов

### Режимы генерации

Пайплайн поддерживает 3 режима (`generation_modes.py`):

| Режим | Формат | Описание | Применение |
|-------|--------|----------|------------|
| **wbcard** | 3:4 (720x960) | Для карточек Wildberries | **По умолчанию** |
| vertical | 9:16 (720x1280) | Вертикальное видео | Stories, Reels |
| cinematic | 16:9 (1280x720) | Горизонтальное видео | YouTube, сайты |

**Техника для 3:4 (wbcard)**:
- NanoBanana генерирует кадры 3:4
- Veo3 всегда выдает 9:16 (720x1280) — это ограничение модели
- Пайплайн обрезает видео **сверху** до 3:4 (720x960)
- Исходное видео 9:16 сохраняется как `video_generated.mp4`
- Финальное 3:4 видео сохраняется как `video.mp4`

## Структура проекта

```
/home/videobot/dev/
├── scripts/
│   ├── telegram_bot.py          # Telegram бот (+ платежи + /portfolio)
│   ├── full_pipeline_v2.py      # Основной пайплайн
│   ├── sellematics_fetcher.py   # Получение данных через Sellematics API
│   ├── wb_fetcher_enhanced.py   # Playwright scraper (fallback)
│   ├── laozhang_proxy.py        # Обертка для NanoBanana/Veo3 API
│   ├── creative_styles.py       # 20 visual styles + 18 video kinds
│   ├── generation_modes.py      # Режимы: cinematic (16:9), vertical (9:16), wbcard (3:4)
│   ├── feedback_parser.py       # Парсинг фидбека пользователей
│   ├── database.py              # SQLite база токенов + showcase
│   ├── token_manager.py         # Операции с токенами
│   ├── payment_handlers.py      # YooKassa платежи
│   ├── test_token_system.py     # Автотесты токенов
│   ├── test_showcase.py         # Автотесты портфолио
│   ├── import_showcase.py       # Импорт видео в портфолио
│   └── claude_laozhang.sh       # Claude Code через LaoZhang API
├── viewer/
│   ├── viewer_bot.py            # Просмотр видео + админ токенов
│   ├── data_reader.py           # Чтение данных
│   └── search.py                # Claude-поиск
├── prompts/
│   ├── stages/                  # Шаблоны для Claude
│   │   ├── stage2_story_vision.md
│   │   ├── stage2b_critic.md
│   │   ├── stage3_frame_design.md
│   │   └── stage4_video_prompt.md
│   ├── categories/              # Стили по категориям товаров (JSON)
│   └── negatives/               # Библиотека негативных промптов
├── docs/
│   ├── plans/
│   │   └── payment-integration.md   # План интеграции платежей
│   ├── showcase.md              # Документация портфолио
│   ├── prompt-archiving.md      # Архивация промптов и данных
│   └── claude-laozhang-api.md   # Claude Code через LaoZhang API
├── systemd/
│   ├── videobot-test.service    # Dev бот
│   ├── videobot-prod.service    # Prod бот
│   └── sellematics-tunnel.service # SSH туннель к Sellematics API
└── .env                         # Конфигурация (токены, пути, платежи)
```

## Сервисы

```bash
# Бот (dev) - USER service, без sudo
systemctl --user status videobot-dev
systemctl --user restart videobot-dev
journalctl --user -u videobot-dev -f

# Бот (prod) - system service
sudo systemctl status videobot-prod

# Туннель к Sellematics API (system service, нужен для обоих ботов)
sudo systemctl status sellematics-tunnel
```

## Данные о товаре

### Источники данных (в порядке приоритета)

1. **Sellematics API** (`sellematics_fetcher.py`)
   - Богатые данные: описание, характеристики, рейтинг, кол-во отзывов
   - Требует туннель: `ssh -L 127.0.0.1:43761:REMOTE_HOST:43761 user@SSH_HOST`
   - Сервис: `sellematics-tunnel.service`

2. **Playwright scraper** (`wb_fetcher_enhanced.py`)
   - Fallback если Sellematics недоступен
   - Может блокироваться CAPTCHA на WB

## Фидбек пользователей

- **activity.log** — лог всех действий пользователя с товаром
- **product_feedback.json** — агрегированный фидбек
- Пользователь оценивает: ✏️ Поправить (refine) | 🔄 Другой вариант (explore)
- Голосовые сообщения транскрибируются

## Debugging и архивация данных

Все промпты и данные каждой генерации сохраняются для debugging:

```
/mnt/video/wb_{product_id}/{task_id}/
├── prompts/                       # Промпты отправленные AI моделям
│   ├── stage2_story_vision.txt    # Claude: концепция видео
│   ├── stage3_frame_design.txt    # Claude: дизайн кадров
│   └── stage4_veo3_prompt.txt     # Veo3: финальный промпт
├── generation.log                 # Полный лог пайплайна (JSON)
├── pipeline.log                   # Real-time execution лог
└── metadata.json                  # Краткая метадата
```

**Подробнее**: [docs/prompt-archiving.md](docs/prompt-archiving.md)

**Примеры использования**:
```bash
# Посмотреть что было в промпте Stage 2
cat /mnt/video/wb_271933299/20260127_132905_wonv/prompts/stage2_story_vision.txt

# Проверить анализ фидбека
grep -A 10 "MOST RECENT" prompts/stage2_story_vision.txt

# Посмотреть все данные о товаре и отзывы
jq '.stages.stage1' generation.log

# Сравнить промпты разных генераций
for dir in /mnt/video/wb_271933299/2026*/; do
  echo "=== $dir ==="
  grep "MOST RECENT" "$dir/prompts/stage2_story_vision.txt"
done
```

## Ключевые команды

```bash
# Запустить пайплайн вручную
cd /home/videobot/dev/scripts
./venv/bin/python full_pipeline_v2.py "https://www.wildberries.ru/catalog/XXX/detail.aspx"

# Проверить Sellematics API
curl -X POST "http://127.0.0.1:43761/api/v1/products" -d 'mall=wb&id=14797921'

# Логи бота (dev)
journalctl --user -u videobot-dev -f
```

## Важные ограничения

- **Veo3**: Не умеет генерировать осмысленную речь (только восклицания: "Wow!", "Mmm!")
- **Veo3**: Сложные объекты (многосекционные сковородки, механизмы) рискованны
- **NanoBanana**: Scene consistency через reference image для Act 2
- **Дети**: ЗАПРЕЩЕНЫ в любых сценах (только 25-45 лет)

## Claude Code (LaoZhang API)

По умолчанию пайплайн использует Claude Code через LaoZhang API — более стабильный доступ к моделям Claude.

```bash
# Запуск Claude Code через LaoZhang (Opus Thinking по умолчанию)
./scripts/claude_laozhang.sh

# Выбор модели
./scripts/claude_laozhang.sh --haiku -p "Quick question"
./scripts/claude_laozhang.sh --sonnet -p "Code task"
./scripts/claude_laozhang.sh --opus -p "Complex task"

# Переключить пайплайн на прямой Claude (ваша подписка)
USE_CLAUDE_LAOZHANG=0 python full_pipeline_v2.py "https://..."
```

Подробнее: [docs/claude-laozhang-api.md](docs/claude-laozhang-api.md)

## Система токенов и платежей

### Архитектура

```
┌─────────────────────────────────────┐
│  Main Bot (telegram_bot.py)         │
│  - /buy - Покупка токенов           │
│  - /balance - Баланс и история      │
│  - Генерация = 1 токен              │
│  - Авто-рефанд при ошибке           │
└─────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────┐
│  SQLite Database                    │
│  /mnt/video/videobot_{dev|prod}.db  │
│  - users: балансы, блокировки       │
│  - transactions: аудит-лог          │
│  - promo_config: промо-слоты        │
│  - giveaway_config: раздача токенов │
└─────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────┐
│  Admin Bot (viewer/viewer_bot.py)   │
│  - /dev /prod - Переключение БД     │
│  - /users /user - Пользователи      │
│  - /grant /revoke - Управление      │
│  - /tokenstats - Статистика         │
└─────────────────────────────────────┘
```

### Ключевые файлы

```
scripts/
├── database.py           # SQLite CRUD, аудит-лог
├── token_manager.py      # Операции с балансом (+ раздача)
├── payment_handlers.py   # YooKassa через Telegram Payments
└── test_token_system.py  # Автотесты (47 тестов)

viewer/
└── viewer_bot.py         # Админ-команды для токенов + раздача
```

### Цены

| Пакет | Обычная цена | Промо-цена |
|-------|-------------|------------|
| 1 токен | 699₽ | 99₽ |
| 5 токенов | 2499₽ | 499₽ |
| 10 токенов | 3999₽ | 999₽ |

Промо-цена для первых N пользователей (настраивается в promo_config).

### Команды пользователя

- `/buy` — Выбор пакета и оплата через YooKassa
- `/balance` — Текущий баланс и история операций

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

```bash
/dev              # Переключить на DEV базу
/prod             # Переключить на PROD базу
/users [page]     # Список пользователей
/user <id>        # Детали пользователя
/grant <id> <n>   # Начислить токены
/revoke <id> <n>  # Списать токены
/block <id>       # Заблокировать
/unblock <id>     # Разблокировать
/txns [limit]     # Последние транзакции
/tokenstats       # Общая статистика
/promo [count]    # Промо-слоты (показать/установить)
/giveaway_start <users> [tokens]  # Запустить раздачу токенов
/giveaway_stop    # Остановить раздачу
/giftcamp list|new_user|deeplink|stop  # Управление кампаниями подарков
/giftpack <id> <tokens> [days]   # Подарок пользователю
/giftpacks [id]   # Статистика подарков / подарки пользователя
/giftbulk <tokens> <days>        # Массовая отправка неактивным
/usearch <query>  # Поиск пользователей
```

### Тестирование платежей

```bash
# Запуск тестов
cd /home/videobot/dev/scripts
source ../venv/bin/activate
python test_token_system.py

# Тестовая карта YooKassa
Номер: 4242 4242 4242 4242
Срок: любой будущий
CVV: любые 3 цифры
```

### Логика генерации с токенами

1. Пользователь отправляет URL товара
2. Проверка: в whitelist? → не заблокирован? → есть токены?
3. Списание 1 токена (transaction: generation)
4. Запуск пайплайна
5. При ошибке → автоматический рефанд токена

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

Система автоматической раздачи бесплатных токенов первым N новым пользователям.

**Особенности:**
- Работает параллельно с промо-ценами (это разные системы)
- Новые пользователи получают токены автоматически при первом взаимодействии
- Приветственное сообщение показывается только в `/start`
- Защита от двойной раздачи через флаг `giveaway_received`
- Race-condition safe (EXCLUSIVE транзакция)

**Админ-команды:**
```bash
/giveaway_start 100      # Первые 100 пользователей получат 3 токена
/giveaway_start 50 5     # Первые 50 пользователей получат 5 токенов
/giveaway_stop           # Остановить + показать статистику
```

**Пример использования:**
```
Admin: /giveaway_start 100 5

User1: /start
→ "🎁 Добро пожаловать! Вы получили 5 бесплатных генераций!"

User2: [отправляет URL товара]
→ Токены начислены тихо (без сообщения)

User101: /start
→ Обычное приветствие (слоты закончились)
```

**Документация:** [docs/giveaway-system.md](docs/giveaway-system.md)

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

Система подарочных пакетов с ограниченным сроком действия. Токены НЕ зачисляются на баланс сразу — подарок автоматически активируется при первом использовании (отправка URL товара).

**Ключевые особенности:**
- Один подарок на пользователя (флаг `gift_pack_received`)
- Автоматическая выдача через кампании (new_user / deeplink)
- Срок действия (по умолчанию 7 дней)
- Уведомление за 24 часа до истечения
- Автоматическая активация при отправке URL товара
- Админ может отправить подарок вручную (обходит одноразовое ограничение)

**Админ-команды (viewer bot):**
```bash
# Управление кампаниями
/giftcamp list                              # Показать все кампании
/giftcamp new_user <tokens> <days> [slots]  # Новые пользователи получают подарки
/giftcamp deeplink <source> <tokens> <days> [slots]  # По deeplink
/giftcamp stop <id>                         # Остановить кампанию

# Ручная отправка
/giftpack <user_id> <tokens> [days]         # Подарок конкретному пользователю

# Просмотр
/giftpacks                                  # Общая статистика подарков
/giftpacks <user_id>                        # Подарки конкретного пользователя

# Массовая отправка
/giftbulk <tokens> <days>                   # Отправить неактивным пользователям
```

**Пример использования:**
```
Admin: /giftcamp new_user 3 7 100
→ Первые 100 новых пользователей получат подарок (3 генерации на 7 дней)

User: /start
→ "🎁 Вам подарок! 3 бесплатных генераций на 7 дней."

User: [отправляет URL товара]
→ "🎁 Подарок активирован! +3 генераций на балансе"
→ Генерация запускается
```

### Отслеживание источников (Referral Tracking)

Отслеживание откуда пришёл пользователь через Telegram deep links.

**Ссылка:** `https://t.me/YourBotName?start=source_tag`

**Админ-команды:**
```bash
/user <id>          # Показывает источник пользователя
/refstats           # Агрегированная статистика по источникам
```

**Документация:** [docs/referral-tracking.md](docs/referral-tracking.md)

## Портфолио видео (Showcase)

Система для демонстрации лучших примеров пользователям.

### База данных

- Файл: `/mnt/video/showcase.db` (общий для dev и prod)
- Таблица: `showcase_videos` (video_path, task_id, product_id, rating, has_artifacts)

### Команды пользователя

- `/portfolio` — показать 5 случайных примеров видео

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

```bash
/showcase           # Список видео в портфолио
/showcase_add <task_id> [rating]  # Добавить видео
/showcase_rm <id>   # Удалить видео
```

Также доступны кнопки под каждым видео:
- ➕ В портфолио / ➖ Из портфолио
- ☆☆☆☆☆ — рейтинг 1-5

### Импорт данных

```bash
python import_showcase.py          # Импорт из good-generations.md
python import_showcase.py --dry-run  # Только показать что будет импортировано
```

Подробнее: [docs/showcase.md](docs/showcase.md)

## Связанные проекты

- **microdrama/** — Автоматизация коротких видео (45-60 сек) для YouTube Shorts/TikTok. См. [microdrama/README.md](microdrama/README.md)
  - **Story Adaptation Pipeline** — мульти-эпизодная адаптация рассказов. Пайплайн story_pipeline.py → orchestrator_v5.py. См. [microdrama-v2/docs/story-pipeline.md](microdrama-v2/docs/story-pipeline.md)
- **../yandex-xml-server/** — Yandex Search API клиент для поиска референсов
- **sellematics/** — API для аналитики маркетплейсов
- **everything-as-a-code** — планирование проекта

## Контакты

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