Readme

2026-02-13 23:00:34 +03:00
parent e9f0a6066e
commit 125bf410ed
1 changed files with 442 additions and 0 deletions
@@ -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 <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)