frontend/MVP-SPEC.md

YouTube Thumbnail A/B Preview Tool

MVP Specification

Название проекта: ThumbnailTest / ThumbPreview Цель: Помочь YouTube-креаторам увидеть, как их превью выглядит в поисковой выдаче рядом с конкурентами ДО публикации видео.

---

Проблема

YouTube-креаторы не могут визуализировать, как их превью будет выглядеть:

• В результатах поиска рядом с конкурентами
• На главной странице YouTube
• На мобильных устройствах
• В разных размерах (большой/маленький превью)

Они загружают видео, надеются на лучшее, и только потом видят результат.

---

Решение (MVP)

Веб-приложение где пользователь:

1. Загружает свой thumbnail (или несколько для сравнения)
2. Вводит поисковый запрос
3. Видит свой thumbnail рядом с реальными конкурентами из YouTube

---

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

1. Загрузка Thumbnail

• Drag & drop или выбор файла
• Поддержка форматов: JPG, PNG, WebP
• Рекомендуемый размер: 1280x720
• Превью загруженного изображения

2. Поиск конкурентов

• Поле ввода поискового запроса
• Получение топ-10 видео по запросу через YouTube Data API
• Отображение их thumbnails, заголовков, названий каналов

3. Превью в контексте

• Search Results View: Имитация страницы поиска YouTube
• Sidebar View: Имитация рекомендованных видео справа
• Mobile View: Мобильный вид результатов

4. A/B сравнение

• Загрузка 2-3 вариантов thumbnail
• Быстрое переключение между вариантами
• Сохранение сессии для возврата

---

Технический стек

Frontend

- React 18+ с TypeScript
- Tailwind CSS для стилей
- Vite как сборщик
- React Query для API запросов
- Zustand для state management (легковесный)

Backend

- NestJS с TypeScript
- PostgreSQL для хранения данных
- Redis для кеширования YouTube API ответов (опционально)
- Multer для загрузки файлов
- Sharp для обработки изображений

Внешние API

- YouTube Data API v3 (search.list, videos.list)

---

База данных (PostgreSQL)

Таблицы

-- Пользователи (для будущего)
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) UNIQUE,
  created_at TIMESTAMP DEFAULT NOW()
);

-- Проекты/Сессии превью
CREATE TABLE preview_sessions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id),
  search_query VARCHAR(255),
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- Загруженные thumbnails
CREATE TABLE thumbnails (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  session_id UUID REFERENCES preview_sessions(id) ON DELETE CASCADE,
  file_path VARCHAR(500) NOT NULL,
  original_name VARCHAR(255),
  title VARCHAR(255), -- Пользовательский заголовок для превью
  position INTEGER DEFAULT 0, -- Порядок в списке
  created_at TIMESTAMP DEFAULT NOW()
);

-- Кеш YouTube результатов
CREATE TABLE youtube_cache (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  search_query VARCHAR(255) NOT NULL,
  results JSONB NOT NULL,
  created_at TIMESTAMP DEFAULT NOW(),
  expires_at TIMESTAMP NOT NULL
);

CREATE INDEX idx_youtube_cache_query ON youtube_cache(search_query);
CREATE INDEX idx_youtube_cache_expires ON youtube_cache(expires_at);

---

API Endpoints

Backend API

POST   /api/thumbnails/upload     - Загрузка thumbnail
DELETE /api/thumbnails/:id        - Удаление thumbnail

GET    /api/youtube/search        - Поиск видео (с кешированием)
       ?q=query&maxResults=10

POST   /api/sessions              - Создание сессии
GET    /api/sessions/:id          - Получение сессии
PUT    /api/sessions/:id          - Обновление сессии

---

YouTube Data API

Настройка

1. Создать проект в Google Cloud Console
2. Включить YouTube Data API v3
3. Создать API ключ
4. Настроить ограничения (HTTP referrers)

Квоты

• Бесплатно: 10,000 units/день
• search.list = 100 units за запрос
• ~100 поисков в день бесплатно
• Кеширование обязательно!

Пример запроса

// GET https://www.googleapis.com/youtube/v3/search
{
  part: 'snippet',
  q: 'react tutorial',
  type: 'video',
  maxResults: 10,
  key: YOUTUBE_API_KEY
}

// Ответ содержит:
// - videoId
// - title
// - channelTitle
// - thumbnails.medium.url (320x180)
// - thumbnails.high.url (480x360)

---

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

thumbnail-preview-tool/
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── ThumbnailUploader.tsx
│   │   │   ├── SearchInput.tsx
│   │   │   ├── PreviewGrid.tsx
│   │   │   ├── YouTubeSearchResult.tsx
│   │   │   ├── UserThumbnail.tsx
│   │   │   ├── ViewSwitcher.tsx
│   │   │   └── MobilePreview.tsx
│   │   ├── hooks/
│   │   │   ├── useYouTubeSearch.ts
│   │   │   └── useThumbnails.ts
│   │   ├── store/
│   │   │   └── previewStore.ts
│   │   ├── api/
│   │   │   └── client.ts
│   │   ├── types/
│   │   │   └── index.ts
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── package.json
│   └── vite.config.ts
│
├── backend/
│   ├── src/
│   │   ├── modules/
│   │   │   ├── thumbnails/
│   │   │   │   ├── thumbnails.controller.ts
│   │   │   │   ├── thumbnails.service.ts
│   │   │   │   └── thumbnails.module.ts
│   │   │   ├── youtube/
│   │   │   │   ├── youtube.controller.ts
│   │   │   │   ├── youtube.service.ts
│   │   │   │   └── youtube.module.ts
│   │   │   └── sessions/
│   │   │       ├── sessions.controller.ts
│   │   │       ├── sessions.service.ts
│   │   │       └── sessions.module.ts
│   │   ├── entities/
│   │   │   ├── thumbnail.entity.ts
│   │   │   ├── session.entity.ts
│   │   │   └── youtube-cache.entity.ts
│   │   ├── app.module.ts
│   │   └── main.ts
│   ├── uploads/           # Загруженные файлы
│   ├── package.json
│   └── .env
│
├── docker-compose.yml     # PostgreSQL для разработки
├── MVP-SPEC.md
└── README.md

---

UI/UX Дизайн (MVP)

Главная страница

┌─────────────────────────────────────────────────────────┐
│  [Logo] ThumbnailTest          [Login] [Try Free]       │
├─────────────────────────────────────────────────────────┤
│                                                         │
│     See how your thumbnail looks before publishing      │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │                                                   │   │
│  │     [Drag & drop your thumbnail here]            │   │
│  │              or click to upload                  │   │
│  │                                                   │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  Search query: [_________________________] [Search]     │
│                                                         │
└─────────────────────────────────────────────────────────┘

Страница превью

┌─────────────────────────────────────────────────────────┐
│  [← Back]   Query: "react hooks tutorial"    [Desktop ▼]│
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Your thumbnails:  [A] [B] [+Add]                       │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  YouTube Search Results Simulation              │   │
│  │                                                   │   │
│  │  ┌──────┐  React Hooks Tutorial for Beginners   │   │
│  │  │ YOUR │  Your Channel Name                     │   │
│  │  │THUMB │  125K views • 2 days ago              │   │
│  │  └──────┘  ← YOUR THUMBNAIL (highlighted)       │   │
│  │                                                   │   │
│  │  ┌──────┐  Learn React Hooks in 30 Minutes      │   │
│  │  │ img  │  Fireship                             │   │
│  │  └──────┘  1.2M views • 1 year ago              │   │
│  │                                                   │   │
│  │  ┌──────┐  React Hooks Crash Course             │   │
│  │  │ img  │  Traversy Media                       │   │
│  │  └──────┘  890K views • 2 years ago             │   │
│  │                                                   │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘

---

План разработки MVP (5-7 дней)

День 1: Настройка проекта

• Инициализация frontend (Vite + React + TypeScript + Tailwind)
• Инициализация backend (NestJS)
• Docker compose для PostgreSQL
• Настройка YouTube Data API ключа

День 2: Backend - загрузка файлов

• Модуль thumbnails с upload endpoint
• Обработка изображений (Sharp)
• Хранение в файловой системе
• Базовые entities и миграции

День 3: Backend - YouTube интеграция

• Модуль youtube с поиском
• Кеширование результатов в БД
• Rate limiting

День 4: Frontend - загрузка и поиск

• Компонент ThumbnailUploader
• Компонент SearchInput
• API клиент
• Базовый state management

День 5: Frontend - превью

• Компонент PreviewGrid (имитация YouTube)
• Стили максимально похожие на YouTube
• Переключение между вариантами thumbnail
• ViewSwitcher (Desktop/Mobile)

День 6: Полировка

• Мобильная адаптивность
• Обработка ошибок
• Loading states
• Базовая аналитика

День 7: Деплой

• Деплой backend (Railway/Render)
• Деплой frontend (Vercel)
• Тестирование production
• Лендинг с ценами

---

Монетизация

Free Tier

• 3 превью сессии в месяц
• Водяной знак "Made with ThumbnailTest"
• Только desktop view

Pro - $9/месяц

• Безлимитные сессии
• Без водяного знака
• Desktop + Mobile + Sidebar views
• Сохранение истории сессий
• A/B сравнение до 5 вариантов

Будущие фичи (после MVP)

• AI оценка кликабельности
• Тепловая карта внимания
• Интеграция с Canva
• Chrome расширение
• Командный доступ

---

Конкуренты

Инструмент	Цена	Особенности	Наше преимущество
Clickpilot	$9/mo	Похожий функционал	Проще UX, быстрее
TubeBuddy	$9-49/mo	Много фич, сложно	Фокус на одной задаче
VidIQ	$7.50-49/mo	Аналитика, сложно	Простота

---

Метрики успеха MVP

• 100 уникальных пользователей за первую неделю
• 10 регистраций email для Pro
• 2 платных подписки
• NPS > 7 от первых пользователей

---

Риски и решения

Риск	Решение
YouTube API квоты	Агрессивное кеширование (24 часа)
Низкий трафик	Постинг на r/NewTubers, Product Hunt
Сложность YouTube стилей	Использовать скриншоты как референс
Юридические вопросы	Только публичные данные, no scraping

---

Следующие шаги

1. Сейчас: Создать YouTube API ключ
2. Сегодня: Инициализировать проекты frontend/backend
3. Завтра: Первый рабочий прототип загрузки + поиска