# План реализации фронтенда ## Стек технологий - **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: Базовая инфраструктура ✅ - [x] Создать API документацию - [x] Создать план реализации - [ ] Настроить переменные окружения - [ ] Создать типы 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 (если поддерживается) - [ ] Подготовка презентации для команды --- ## Работа с моками ### Переменная окружения ```env NEXT_PUBLIC_USE_MOCKS=true NEXT_PUBLIC_API_URL=https://api.tgex.app/v1 ``` ### Логика переключения ```typescript // 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 Необходимо установить: ```bash 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