353 lines
14 KiB
Markdown
353 lines
14 KiB
Markdown
# План реализации фронтенда
|
||
|
||
## Стек технологий
|
||
|
||
- **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
|