diff --git a/README.md b/README.md new file mode 100644 index 0000000..760e1c5 --- /dev/null +++ b/README.md @@ -0,0 +1,442 @@ +# 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 +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 + login: (phone: string, password: string) => Promise + register: (data: any) => Promise + logout: () => void + getProfile: () => Promise + updateProfile: (data: any) => Promise + changePhone: (newPhone: string) => Promise + becomePerformer: () => Promise + updateCompetencies: (competencies: string[]) => Promise + uploadAvatar: (file: File) => Promise +} +``` + +## 🔧 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)