443 lines
14 KiB
Markdown
443 lines
14 KiB
Markdown
# Nashel Frontend
|
||
|
||
Фронтенд для маркетплейса услуг "Nashel" — современное веб-приложение на Next.js для поиска мастеров и исполнителей.
|
||
|
||
## 🏗️ Архитектура
|
||
|
||
Проект построен на **Feature-Sliced Design (FSD)** архитектуре:
|
||
|
||
```
|
||
nashel-frontend/
|
||
├── src/
|
||
│ ├── app/ # Next.js App Router (страницы и роутинг)
|
||
│ ├── entities/ # Бизнес-сущности (User, Session, Order)
|
||
│ ├── features/ # Бизнес-фичи (Auth, Orders, Map)
|
||
│ ├── widgets/ # Составные виджеты (Header, Footer)
|
||
│ ├── shared/ # Общий код (UI, lib, api)
|
||
│ ├── components/ # Переиспользуемые UI-компоненты
|
||
│ └── lib/ # Утилиты и хелперы
|
||
├── public/ # Статические файлы
|
||
└── tests/ # Тесты
|
||
```
|
||
|
||
### FSD Слои
|
||
|
||
- **app** — страницы и роутинг приложения
|
||
- **entities** — бизнес-сущности (User, Session)
|
||
- **features** — бизнес-фичи (Auth, Orders)
|
||
- **widgets** — составные виджеты (Header, Footer)
|
||
- **shared** — общий код (UI-компоненты, утилиты)
|
||
- **pages** — страницы (интеграция виджетов и фич)
|
||
- **processes** — бизнес-процессы (в планах)
|
||
|
||
## 🚀 Технологический стек
|
||
|
||
- **Next.js 15** — React фреймворк с App Router
|
||
- **TypeScript** — типизация
|
||
- **Tailwind CSS** — стилизация
|
||
- **shadcn/ui** — UI компоненты
|
||
- **Zustand** — state management
|
||
- **React Hook Form** — формы
|
||
- **Zod** — валидация
|
||
- **Axios** — HTTP клиент
|
||
- **React Easy Crop** — кроп изображений
|
||
- **Lucide React** — иконки
|
||
- **Sonner** — уведомления (toasts)
|
||
- **next-themes** — темная тема
|
||
|
||
## 📦 Установка и запуск
|
||
|
||
### Требования
|
||
|
||
- Node.js 18+ и npm/yarn/pnpm
|
||
|
||
### Установка
|
||
|
||
```bash
|
||
# Клонирование репозитория
|
||
git clone <repository-url>
|
||
cd nashel-frontend
|
||
|
||
# Установка зависимостей
|
||
npm install
|
||
|
||
# Копирование файла переменных окружения
|
||
cp .env.example .env.local
|
||
# Отредактируйте переменные в .env.local
|
||
```
|
||
|
||
### Переменные окружения
|
||
|
||
Создайте файл `.env.local` в корне проекта:
|
||
|
||
```env
|
||
# API
|
||
NEXT_PUBLIC_API_URL=http://localhost:5000
|
||
|
||
# Другие переменные (опционально)
|
||
NEXT_PUBLIC_APP_NAME=Nashel
|
||
NEXT_PUBLIC_APP_URL=http://localhost:3000
|
||
```
|
||
|
||
### Запуск
|
||
|
||
```bash
|
||
# Режим разработки
|
||
npm run dev
|
||
|
||
# Сборка для продакшена
|
||
npm run build
|
||
|
||
# Запуск продакшен-сборки
|
||
npm start
|
||
|
||
# Линтинг
|
||
npm run lint
|
||
```
|
||
|
||
Приложение будет доступно по адресу: `http://localhost:3000`
|
||
|
||
## 📚 Структура страниц
|
||
|
||
### Основные страницы
|
||
|
||
| Путь | Описание | Защищена |
|
||
|------|----------|----------|
|
||
| `/` | Главная страница | ❌ |
|
||
| `/map` | Поиск исполнителей на карте | ❌ |
|
||
| `/orders` | Мои заказы | ✅ |
|
||
| `/dashboard/profile` | Профиль пользователя | ✅ |
|
||
| `/auth/login` | Вход в систему | ❌ |
|
||
| `/auth/register` | Регистрация | ❌ |
|
||
|
||
## 🎯 Реализованный функционал
|
||
|
||
### Аутентификация
|
||
|
||
#### Вход в систему
|
||
- ✅ Форма входа с валидацией
|
||
- ✅ Отправка номера телефона и пароля
|
||
- ✅ Сохранение токенов в cookies
|
||
- ✅ Перенаправление после входа
|
||
|
||
#### Регистрация
|
||
- ✅ Регистрация частных лиц (ФИО)
|
||
- ✅ Регистрация компаний (название + ИНН)
|
||
- ✅ Валидация формы (zod)
|
||
- ✅ Переключатель "Я представляю компанию"
|
||
- ✅ Перенаправление после регистрации
|
||
|
||
#### Авторизация
|
||
- ✅ Проверка токена при загрузке приложения
|
||
- ✅ Автоматический вход при наличии токена
|
||
- ✅ Сохранение сессии между перезагрузками
|
||
- ✅ Выход из системы
|
||
|
||
### Профиль пользователя
|
||
|
||
#### Личные данные
|
||
- ✅ Отображение ФИО или названия компании
|
||
- ✅ Редактирование профиля
|
||
- ✅ Разные поля для частных лиц и компаний
|
||
- ✅ ИНН для компаний
|
||
|
||
#### Аватар
|
||
- ✅ Загрузка аватара
|
||
- ✅ Кроп изображения (круглый)
|
||
- ✅ Предпросмотр аватара
|
||
- ✅ Валидация размера (до 5 МБ) и формата (JPG, PNG)
|
||
- ✅ Отображение аватара в профиле и хедере
|
||
|
||
#### Компетенции
|
||
- ✅ Добавление компетенций
|
||
- ✅ Автодополнение при вводе (в стиле Яндекс)
|
||
- ✅ Теги в стиле hh.ru
|
||
- ✅ Нормализация в нижний регистр
|
||
- ✅ Общий пул компетенций для всех исполнителей
|
||
- ✅ Управление компетенциями (добавление/удаление)
|
||
|
||
#### Рейтинг (заглушка)
|
||
- ✅ Отображение рейтинга в профиле
|
||
- ✅ 5 звезд с прогресс-баром
|
||
- ✅ Цветовая схема как в Ozon:
|
||
- Зеленый (> 4.0)
|
||
- Синий (3.0 - 4.0)
|
||
- Красный (< 3.0)
|
||
- ✅ Числовое значение с точностью до сотых
|
||
- ✅ Случайный рейтинг (изменяется каждую секунду)
|
||
|
||
#### Связь
|
||
- ✅ Отображение номера телефона
|
||
- ✅ Изменение номера телефона
|
||
|
||
#### Безопасность
|
||
- ✅ Отображение ролей аккаунта
|
||
- ✅ Кнопка смены пароля (в планах)
|
||
- ✅ Выход из аккаунта
|
||
|
||
#### Стать исполнителем
|
||
- ✅ Блок "Зарабатывайте с нами" для клиентов
|
||
- ✅ Кнопка "Стать исполнителем"
|
||
- ✅ Смена роли на Master/Candidate
|
||
|
||
### Компании
|
||
|
||
#### Регистрация
|
||
- ✅ Отдельная форма регистрации
|
||
- ✅ Поля: название компании, ИНН
|
||
- ✅ Валидация ИНН (10 цифр)
|
||
|
||
#### Профиль
|
||
- ✅ Отображение названия компании вместо ФИО
|
||
- ✅ Отображение ИНН
|
||
- ✅ Редактирование данных компании
|
||
- ✅ Рейтинг компании
|
||
- ✅ Компетенции компании
|
||
|
||
### Исполнители
|
||
|
||
#### Статус исполнителя
|
||
- ✅ Роли: Master, Candidate
|
||
- ✅ Блок "Компетенции"
|
||
- ✅ Рейтинг исполнителя
|
||
|
||
#### Навигация
|
||
- ✅ Кнопка "Подобрать заказы" вместо "Стать исполнителем"
|
||
- ✅ Отображается в хедере и на главной странице
|
||
|
||
### UI/UX
|
||
|
||
#### Хедер
|
||
- ✅ Логотип и название
|
||
- ✅ Навигация (Поиск, Мои заказы)
|
||
- ✅ Информация о пользователе
|
||
- ✅ Кнопка входа/выхода
|
||
- ✅ Кнопка "Стать исполнителем" / "Подобрать заказы"
|
||
- ✅ Переключатель темы (светлая/темная)
|
||
|
||
#### Главная страница
|
||
- ✅ Hero секция с призывом к действию
|
||
- ✅ Кнопка "Найти исполнителя"
|
||
- ✅ Кнопка "Стать исполнителем" / "Подобрать заказы"
|
||
- ✅ Преимущества сервиса
|
||
- ✅ Адаптивный дизайн
|
||
|
||
#### Темы
|
||
- ✅ Светлая тема
|
||
- ✅ Темная тема
|
||
- ✅ Переключатель тем
|
||
- ✅ Сохранение выбора темы
|
||
|
||
#### Уведомления
|
||
- ✅ Toast уведомления (Sonner)
|
||
- ✅ Успешные операции
|
||
- ✅ Ошибки
|
||
- ✅ Информационные сообщения
|
||
|
||
## 🧩 Компоненты
|
||
|
||
### UI Компоненты (shadcn/ui)
|
||
|
||
- ✅ Button
|
||
- ✅ Input
|
||
- ✅ Card
|
||
- ✅ Badge
|
||
- ✅ Form
|
||
- ✅ Slider
|
||
- ✅ Avatar
|
||
- ✅ Dialog
|
||
- ✅ Dropdown Menu
|
||
- ✅ и др.
|
||
|
||
### Кастомные компоненты
|
||
|
||
#### AvatarUploader
|
||
- Загрузка аватара с кропом
|
||
- Предпросмотр
|
||
- Валидация
|
||
|
||
#### TagInput
|
||
- Ввод компетенций
|
||
- Автодополнение
|
||
- Теги в стиле hh.ru
|
||
|
||
#### Rating
|
||
- Отображение рейтинга
|
||
- 5 звезд с прогресс-баром
|
||
- Цветовая схема
|
||
|
||
## 📊 State Management
|
||
|
||
### Zustand Store
|
||
|
||
```typescript
|
||
// entities/session/store.ts
|
||
interface SessionState {
|
||
user: User | null
|
||
isAuth: boolean
|
||
isLoading: boolean
|
||
isInitialized: boolean
|
||
checkAuth: () => Promise<void>
|
||
login: (phone: string, password: string) => Promise<void>
|
||
register: (data: any) => Promise<void>
|
||
logout: () => void
|
||
getProfile: () => Promise<void>
|
||
updateProfile: (data: any) => Promise<void>
|
||
changePhone: (newPhone: string) => Promise<void>
|
||
becomePerformer: () => Promise<void>
|
||
updateCompetencies: (competencies: string[]) => Promise<void>
|
||
uploadAvatar: (file: File) => Promise<void>
|
||
}
|
||
```
|
||
|
||
## 🔧 API Клиент
|
||
|
||
### Axios Configuration
|
||
|
||
```typescript
|
||
// shared/api/axios.ts
|
||
- Базовый URL
|
||
- Интерцептор для токена
|
||
- Обработка ошибок
|
||
- Таймауты
|
||
```
|
||
|
||
### API Методы
|
||
|
||
```typescript
|
||
// lib/api.ts
|
||
- login
|
||
- register
|
||
- getProfile
|
||
- updateProfile
|
||
- changePhone
|
||
- becomePerformer
|
||
- uploadAvatar
|
||
- updateCompetencies
|
||
- searchCompetencies
|
||
```
|
||
|
||
## 📝 Конвенции кода
|
||
|
||
### TypeScript
|
||
|
||
- Строгая типизация
|
||
- Интерфейсы для всех DTO
|
||
- Generics где необходимо
|
||
- JSDoc для сложных функций
|
||
|
||
### React
|
||
|
||
- Функциональные компоненты
|
||
- Hooks (useState, useEffect, useCallback, useMemo)
|
||
- Компоненты высшего порядка (HOC) по необходимости
|
||
- Composition over inheritance
|
||
|
||
### Стилизация
|
||
|
||
- Tailwind CSS для стилей
|
||
- CSS Modules для сложных компонентов (при необходимости)
|
||
- Атомарные классы
|
||
- Responsive design (mobile-first)
|
||
|
||
## 🧪 Тестирование
|
||
|
||
```bash
|
||
# Запуск тестов
|
||
npm test
|
||
|
||
# Запуск с покрытием
|
||
npm test -- --coverage
|
||
|
||
# E2E тесты (Playwright)
|
||
npm run test:e2e
|
||
```
|
||
|
||
## 🚨 Обработка ошибок
|
||
|
||
- Глобальный обработчик ошибок
|
||
- Toast уведомления для пользователя
|
||
- Логирование в консоль (development)
|
||
- Отправка ошибок на сервер (production - в планах)
|
||
|
||
## 🎨 Дизайн
|
||
|
||
### Цветовая схема
|
||
|
||
- **Основной цвет:** синий (`blue-600`)
|
||
- **Успех:** зеленый (`green-600`)
|
||
- **Ошибка:** красный (`red-600`)
|
||
- **Предупреждение:** желтый (`yellow-600`)
|
||
- **Текст:** серый (`slate-900`)
|
||
|
||
### Шрифты
|
||
|
||
- **Основной:** Inter (Google Fonts)
|
||
- **Моноширинный:** для кода (при необходимости)
|
||
|
||
### Иконки
|
||
|
||
- **Библиотека:** Lucide React
|
||
- **Размеры:** sm (16px), md (20px), lg (24px)
|
||
|
||
## 📱 Адаптивность
|
||
|
||
- Mobile-first подход
|
||
- Breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px)
|
||
- Адаптивная навигация
|
||
- Адаптивные формы
|
||
|
||
## 🔐 Безопасность
|
||
|
||
- JWT токены в cookies (httpOnly)
|
||
- Валидация на клиенте и сервере
|
||
- XSS защита (React по умолчанию)
|
||
- CSRF защита (в планах)
|
||
|
||
## 🚀 Оптимизация
|
||
|
||
- Код-сплиттинг (Next.js по умолчанию)
|
||
- Ленивая загрузка компонентов
|
||
- Оптимизация изображений (Next.js Image)
|
||
- Кэширование (в планах)
|
||
|
||
## 📦 Сборка
|
||
|
||
```bash
|
||
# Production сборка
|
||
npm run build
|
||
|
||
# Анализ бандла
|
||
npm run analyze
|
||
```
|
||
|
||
## 🔄 CI/CD
|
||
|
||
- GitHub Actions для автоматического тестирования
|
||
- Vercel для деплоя (в планах)
|
||
- Автоматический деплой (в планах)
|
||
|
||
## 📞 Контакты
|
||
|
||
- **Проект:** Nashel
|
||
- **Версия:** 1.0.0
|
||
- **Лицензия:** MIT
|
||
|
||
## 🤝 Вклад в проект
|
||
|
||
1. Fork репозитория
|
||
2. Создайте ветку для фичи (`git checkout -b feature/AmazingFeature`)
|
||
3. Закоммитьте изменения (`git commit -m 'Add some AmazingFeature'`)
|
||
4. Запушьте в ветку (`git push origin feature/AmazingFeature`)
|
||
5. Откройте Pull Request
|
||
|
||
## 📚 Дополнительные ресурсы
|
||
|
||
- [Next.js Documentation](https://nextjs.org/docs)
|
||
- [React Documentation](https://react.dev)
|
||
- [TypeScript Documentation](https://www.typescriptlang.org/docs)
|
||
- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
|
||
- [shadcn/ui Documentation](https://ui.shadcn.com)
|
||
- [Zustand Documentation](https://zustand-demo.pmnd.rs)
|
||
- [Feature-Sliced Design](https://feature-sliced.design)
|