tgex-frontend/IMPLEMENTATION_PLAN.md

План реализации фронтенда

Стек технологий

• Framework: Next.js 14 (App Router)
• UI: shadcn/ui + Tailwind CSS
• Icons: Lucide React
• Package Manager: pnpm
• State Management: React Context + Hooks
• Forms: React Hook Form + Zod
• API Client: Fetch API + SWR/React Query
• Charts: Recharts (для аналитики)

---

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

frontend/
├── app/
│   ├── (auth)/
│   │   ├── login/
│   │   │   └── page.tsx
│   │   └── auth-complete/
│   │       └── page.tsx
│   ├── (dashboard)/
│   │   ├── layout.tsx              # Layout с sidebar-07
│   │   ├── page.tsx                # Dashboard-01 (главная)
│   │   ├── channels/
│   │   │   ├── page.tsx            # Список целевых каналов
│   │   │   └── [id]/
│   │   │       └── page.tsx        # Детали канала
│   │   ├── external-channels/
│   │   │   ├── page.tsx            # Каталог внешних каналов
│   │   │   ├── [id]/
│   │   │   │   └── page.tsx        # Детали внешнего канала
│   │   │   └── import/
│   │   │       └── page.tsx        # Импорт из Excel
│   │   ├── creatives/
│   │   │   ├── page.tsx            # Список креативов
│   │   │   ├── new/
│   │   │   │   └── page.tsx        # Создание креатива
│   │   │   └── [id]/
│   │   │       ├── page.tsx        # Просмотр/редактирование
│   │   │       └── edit/
│   │   │           └── page.tsx
│   │   ├── purchases/
│   │   │   ├── page.tsx            # Список закупов
│   │   │   ├── new/
│   │   │   │   └── page.tsx        # Создание закупа
│   │   │   └── [id]/
│   │   │       ├── page.tsx        # Детали закупа
│   │   │       └── edit/
│   │   │           └── page.tsx
│   │   └── analytics/
│   │       ├── page.tsx            # Общая аналитика
│   │       ├── costs/
│   │       │   └── page.tsx        # График затрат
│   │       ├── channels/
│   │       │   └── page.tsx        # Аналитика по каналам
│   │       └── creatives/
│   │           └── page.tsx        # Аналитика по креативам
│   ├── globals.css
│   ├── layout.tsx
│   └── providers.tsx
├── components/
│   ├── ui/                         # shadcn компоненты
│   ├── auth/
│   │   ├── auth-provider.tsx
│   │   └── protected-route.tsx
│   ├── channels/
│   │   ├── channel-card.tsx
│   │   ├── channel-form.tsx
│   │   └── channel-stats.tsx
│   ├── external-channels/
│   │   ├── external-channel-card.tsx
│   │   ├── external-channel-form.tsx
│   │   ├── external-channel-import-dialog.tsx
│   │   └── channel-picker.tsx
│   ├── creatives/
│   │   ├── creative-card.tsx
│   │   ├── creative-form.tsx
│   │   └── creative-preview.tsx
│   ├── purchases/
│   │   ├── purchase-card.tsx
│   │   ├── purchase-form.tsx
│   │   ├── purchase-stats.tsx
│   │   └── invite-link-display.tsx
│   ├── analytics/
│   │   ├── overview-card.tsx
│   │   ├── cost-chart.tsx
│   │   ├── channel-comparison.tsx
│   │   └── metric-card.tsx
│   └── layout/
│       ├── app-sidebar.tsx         # sidebar-07
│       ├── header.tsx
│       └── breadcrumbs.tsx
├── lib/
│   ├── api/
│   │   ├── client.ts               # API client с перехватчиками
│   │   ├── auth.ts                 # Auth endpoints
│   │   ├── channels.ts             # Target channels endpoints
│   │   ├── external-channels.ts    # External channels endpoints
│   │   ├── creatives.ts            # Creatives endpoints
│   │   ├── purchases.ts            # Purchases endpoints
│   │   └── analytics.ts            # Analytics endpoints
│   ├── mocks/
│   │   ├── index.ts                # Мок-сервер (флаг USE_MOCKS)
│   │   ├── data/
│   │   │   ├── users.ts
│   │   │   ├── channels.ts
│   │   │   ├── external-channels.ts
│   │   │   ├── creatives.ts
│   │   │   ├── purchases.ts
│   │   │   └── analytics.ts
│   │   └── handlers.ts             # Request handlers для моков
│   ├── types/
│   │   ├── api.ts                  # API типы из документации
│   │   └── common.ts
│   ├── hooks/
│   │   ├── use-auth.ts
│   │   ├── use-channels.ts
│   │   ├── use-external-channels.ts
│   │   ├── use-creatives.ts
│   │   ├── use-purchases.ts
│   │   └── use-analytics.ts
│   ├── utils/
│   │   ├── format.ts               # Форматирование (даты, числа)
│   │   ├── validation.ts           # Zod схемы
│   │   └── constants.ts
│   └── store/
│       └── auth-store.ts           # Глобальный стейт авторизации
├── public/
├── .env.local.example
├── .env.local
├── next.config.js
├── tailwind.config.ts
├── components.json
├── tsconfig.json
├── package.json
└── API_DOCUMENTATION.md

---

Этапы реализации

Этап 1: Базовая инфраструктура ✅

• Создать API документацию
• Создать план реализации
• Настроить переменные окружения
• Создать типы TypeScript из API документации
• Настроить API клиент с поддержкой моков
• Создать мок-данные и handlers

Этап 2: Авторизация

• Создать AuthProvider с Context
• Реализовать страницу входа
• Реализовать страницу завершения авторизации
• Добавить Protected Route HOC
• Реализовать мок-авторизацию (кнопка "Войти как тестовый пользователь")
• Настроить хранение токенов (localStorage)

Этап 3: Layout и навигация

• Установить shadcn sidebar-07
• Установить shadcn dashboard-01
• Настроить app-sidebar с навигацией
• Создать header с профилем пользователя
• Добавить breadcrumbs навигацию
• Настроить responsive layout

Этап 4: Целевые каналы

• Страница списка целевых каналов
• Карточки каналов с основной статистикой
• Страница детальной информации о канале
• Функция отключения канала
• Инструкция по подключению бота

Этап 5: Внешние каналы

• Страница каталога внешних каналов
• Форма создания внешнего канала
• Форма редактирования внешнего канала
• Привязка к целевым каналам (multi-select)
• Страница импорта из Excel
• Drag & drop для Excel файлов
• Валидация и preview импорта
• Обработка ошибок импорта

Этап 6: Креативы

• Страница списка креативов
• Форма создания креатива
• Редактор текста с placeholder {link}
• Превью креатива с подстановкой ссылки
• Форма редактирования креатива
• Функция архивирования
• Статистика по креативу

Этап 7: Закупы

• Страница списка закупов (таблица)
• Фильтры и сортировка
• Форма создания закупа (multi-step)
• Генерация invite-ссылки
• Отображение форматированного сообщения
• Копирование в буфер обмена
• Страница детальной информации о закупе
• График подписок по времени
• История просмотров
• Обновление просмотров вручную
• Редактирование закупа
• Архивирование/удаление

Этап 8: Аналитика

• Dashboard с общей статистикой (dashboard-01)
• Карточки метрик (CPF, CPM, конверсия)
• Страница графика затрат
• Выбор периода группировки (день/неделя/месяц)
• Фильтр по целевым каналам
• Столбчатая диаграмма (recharts)
• Страница аналитики по каналам
• Таблица сравнения каналов
• Страница аналитики по креативам
• Рейтинг креативов по эффективности

Этап 9: Доработки и полировка

• Адаптивность для мобильных устройств
• Обработка состояний загрузки
• Обработка ошибок с user-friendly сообщениями
• Добавить Toast уведомления
• Анимации и переходы
• Оптимизация производительности
• Accessibility (a11y)
• SEO метатеги

Этап 10: Тестирование

• Проверка всех флоу с моками
• Проверка валидации форм
• Проверка авторизации
• Проверка responsive дизайна
• Проверка dark mode (если поддерживается)
• Подготовка презентации для команды

---

Работа с моками

Переменная окружения

NEXT_PUBLIC_USE_MOCKS=true
NEXT_PUBLIC_API_URL=https://api.tgex.app/v1

Логика переключения

// lib/api/client.ts
const USE_MOCKS = process.env.NEXT_PUBLIC_USE_MOCKS === "true";

if (USE_MOCKS) {
  // Используем локальные моки
  return mockHandler(endpoint, options);
} else {
  // Реальный API запрос
  return fetch(`${API_URL}${endpoint}`, options);
}

Мок-авторизация

При включенных моках на странице логина будет кнопка:

• "Войти как Иван Иванов" - мгновенный вход без Telegram

Преимущества подхода

1. Полная независимость от бекенда
2. Быстрая разработка - нет задержек сети
3. Предсказуемые данные - всегда одинаковые моки
4. Простое тестирование - можно тестировать edge cases
5. Демонстрация - презентация работает без сервера

---

Ключевые компоненты shadcn/ui

Необходимо установить:

npx shadcn@latest add sidebar-07
npx shadcn@latest add dashboard-01
npx shadcn@latest add button
npx shadcn@latest add input
npx shadcn@latest add textarea
npx shadcn@latest add select
npx shadcn@latest add dialog
npx shadcn@latest add table
npx shadcn@latest add card
npx shadcn@latest add badge
npx shadcn@latest add dropdown-menu
npx shadcn@latest add toast
npx shadcn@latest add form
npx shadcn@latest add tabs
npx shadcn@latest add separator
npx shadcn@latest add avatar
npx shadcn@latest add calendar
npx shadcn@latest add popover

---

Приоритеты разработки

1. Высокий:

   • Авторизация
   • Layout с sidebar
   • Целевые каналы (просмотр)
   • Закупы (создание и просмотр)
   • Базовая аналитика

2. Средний:

   • Креативы
   • Внешние каналы (CRUD)
   • Детальная аналитика
   • Импорт Excel

3. Низкий:

   • Продвинутая фильтрация
   • Экспорт данных
   • Дополнительные виджеты

---

Метрики успеха презентации

• ✅ Полный флоу от входа до создания закупа
• ✅ Работающая аналитика с графиками
• ✅ Адаптивный дизайн
• ✅ Плавные анимации
• ✅ Быстрая загрузка (моки)
• ✅ Понятный UX