🚀 DONGFENG Мини-тракторы - Next.js + Supabase

Современный e-commerce сайт для продажи DONGFENG мини-тракторов

Built with Next.js 16 + Supabase (PostgreSQL + REST API из коробки!)

---

✨ Особенности

🎯 Всё в одном проекте!

• ✅ Frontend - Next.js с TypeScript
• ✅ Backend API - Next.js API Routes
• ✅ База данных - Supabase (PostgreSQL в облаке)
• ✅ Аутентификация - Supabase Auth (готова к использованию)
• ✅ Storage - Supabase Storage для картинок

🚀 Преимущества Supabase:

• 🆓 Бесплатно до 500MB БД + 1GB файлов
• ⚡ Быстрый старт - 5 минут настройки
• 🔐 Безопасность - Row Level Security (RLS)
• 📊 Админка - GUI для управления данными
• 🔄 Realtime - WebSocket подписки
• 🌐 REST API - автоматически из таблиц

---

🚀 Быстрый старт (5 минут!)

Шаг 1: Клонировать репозиторий

git clone https://github.com/yourusername/dongfeng-minitraktor.git
cd dongfeng-minitraktor/frontend

Шаг 2: Создать проект на Supabase

1. Зайди на https://supabase.com
2. Создай новый проект (Project name: dongfeng)
3. Дождись создания БД (~2 минуты)

Шаг 3: Скопировать ключи

1. В Supabase: Settings → API
2. Скопируй Project URL и anon public key
3. Создай .env.local:

cp .env.example .env.local

Добавь свои ключи в .env.local:

NEXT_PUBLIC_SUPABASE_URL=https://ваш-проект.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=ваш-anon-key

Шаг 4: Запустить миграции

1. В Supabase Dashboard: SQL Editor
2. Открой файл supabase/migrations/001_init.sql
3. Скопируй весь SQL код
4. Вставь в SQL Editor и нажми RUN

Шаг 5: Запустить проект

npm install
npm run dev

Готово! 🎉 Открой http://localhost:3000

---

📁 Структура проекта

frontend/
├── app/
│   ├── page.tsx                 # Главная страница
│   ├── layout.tsx               # Корневой макет
│   │
│   ├── context/                 # 🔥 React Context для состояния!
│   │   ├── AuthContext.tsx      # Аутентификация пользователей
│   │   ├── CartContext.tsx      # Корзина покупок
│   │   ├── FavoritesContext.tsx # Избранные товары
│   │   └── CompareContext.tsx   # Сравнение товаров
│   │
│   ├── components/              # React компоненты
│   │   ├── Header.tsx           # Шапка сайта
│   │   ├── Footer.tsx           # Подвал
│   │   ├── ProductCard.tsx      # Карточка товара (полностью документирована)
│   │   └── Icons.tsx            # SVG иконки
│   │
│   ├── catalog/                 # Каталог и категории
│   │   ├── page.tsx             # Страница каталога
│   │   ├── minitractory/        # Категория: Минитракторы
│   │   ├── communal-equipment/  # Категория: Навесное оборудование
│   │   ├── parts/               # Категория: Запчасти
│   │   └── product/[slug]/      # Страница товара
│   │
│   ├── cart/                    # 🛒 Корзина покупок
│   │   ├── page.tsx             # Страница корзины (документирована)
│   │   └── cart.css
│   │
│   ├── favorites/               # ❤️ Избранное
│   │   ├── page.tsx             # Страница избранного (документирована)
│   │   └── favorites.css
│   │
│   ├── compare/                 # ⚖️ Сравнение товаров
│   │   ├── page.tsx             # Страница сравнения (документирована)
│   │   └── compare.css
│   │
│   ├── auth/                    # 🔐 Аутентификация
│   │   ├── page.tsx             # Форма входа/регистрации (документирована)
│   │   └── auth.css
│   │
│   └── api/                     # 🔥 Backend API в Next.js!
│       ├── products/
│       │   └── route.ts         # GET /api/products (с фильтрацией)
│       └── categories/
│           └── route.ts         # GET /api/categories
│
├── supabase/
│   └── migrations/
│       └── 001_init.sql         # SQL миграция (создание таблиц)
│
├── docs/                        # 📚 Документация
│   ├── claude.md                # Правила разработки (TDD, архитектура)
│   ├── claude2.md               # Дополнительные правила
│   └── agents.md                # Правила для AI агентов
│
├── package.json
├── next.config.js
├── tsconfig.json
└── .env.local                   # Supabase ключи (не в git!)

---

🗄️ База данных (Supabase)

7 таблиц создано:

• ✅ categories - Категории товаров
• ✅ products - Товары (мини-тракторы)
• ✅ customers - Покупатели
• ✅ orders - Заказы
• ✅ order_items - Товары в заказах
• ✅ contacts - Контакт-формы

Как посмотреть данные:

1. Зайди в Supabase Dashboard
2. Table Editor (слева)
3. Выбери таблицу

Как добавить тестовые товары:

SQL уже содержит 2 тестовых товара! Они создались автоматически.

---

🔌 API Endpoints

Все API endpoints работают автоматически!

Products

# Все товары
GET /api/products

# С фильтрами
GET /api/products?search=DONGFENG&in_stock=true&page=1&limit=20

# Один товар
GET /api/products/df-244

# Создать товар (админ)
POST /api/products

Categories

# Все категории
GET /api/categories

Orders

# Создать заказ
POST /api/orders
Body: { items: [...], customer: {...}, shippingAddress: {...} }

Contact

# Отправить контакт-форму
POST /api/contact
Body: { name, email, phone, message }

---

🎓 Как это работает

Next.js + Supabase

Frontend (React)
    ↓
Next.js API Routes (src/app/api/)
    ↓
Supabase Client (@supabase/supabase-js)
    ↓
Supabase (PostgreSQL в облаке)

Преимущества:

• ✅ Всё в одном проекте
• ✅ TypeScript везде
• ✅ Один package.json
• ✅ Одна команда деплоя
• ✅ Нет CORS проблем

---

🧪 Тестирование API

С помощью curl:

# Health check
curl http://localhost:3000/api/products

# Получить товары
curl http://localhost:3000/api/products?limit=5

# Один товар
curl http://localhost:3000/api/products/df-244

# Категории
curl http://localhost:3000/api/categories

# Создать заказ
curl -X POST http://localhost:3000/api/orders \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{"productId": 1, "quantity": 1}],
    "customer": {
      "firstName": "Иван",
      "lastName": "Петров",
      "email": "[email protected]",
      "phone": "+79991234567"
    },
    "shippingAddress": {
      "street": "ул. Ленина 10",
      "city": "Москва",
      "region": "Московская",
      "postalCode": "101000",
      "country": "Россия"
    }
  }'

# Контакт-форма
curl -X POST http://localhost:3000/api/contact \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Иван",
    "email": "[email protected]",
    "phone": "+79991234567",
    "message": "Интересует модель DF-244"
  }'

---

🚀 Deployment

Deploy на Vercel (1 клик!)

1. Push на GitHub:

git add .
git commit -m "Ready to deploy"
git push origin main

2. Подключить к Vercel:

• Зайди на https://vercel.com
• Нажми "New Project"
• Импортируй репозиторий
• В настройках проекта установи:
  • Root Directory: frontend
• Добавь environment variables:

  NEXT_PUBLIC_SUPABASE_URL=...
  NEXT_PUBLIC_SUPABASE_ANON_KEY=...
  

• Deploy!

Готово! Сайт доступен на your-project.vercel.app

⚠️ Важно: Убедитесь, что вы установили правильный Root Directory в настройках Vercel проекта (frontend), иначе сборка не будет работать.

---

🔄 Context API и глобальное состояние

Проект использует React Context API для управления глобальным состоянием:

1. AuthContext (app/context/AuthContext.tsx)

Управление аутентификацией через Supabase Auth:

const { user, signIn, signUp, signOut, resetPassword } = useAuth();

• user - текущий авторизованный пользователь
• signIn(email, password) - вход в систему
• signUp(email, password, name) - регистрация
• signOut() - выход из системы
• resetPassword(email) - сброс пароля

2. CartContext (app/context/CartContext.tsx)

Управление корзиной покупок с localStorage:

const { items, addToCart, removeFromCart, updateQuantity, clearCart, total } = useCart();

• items - массив товаров в корзине
• addToCart(product) - добавить товар
• removeFromCart(id) - удалить товар
• updateQuantity(id, quantity) - изменить количество
• clearCart() - очистить корзину
• total - итоговая сумма

Особенности:

• Автосохранение в localStorage при каждом изменении
• SSR-безопасная работа с localStorage
• Расчет общей суммы в реальном времени

3. FavoritesContext (app/context/FavoritesContext.tsx)

Управление избранными товарами:

const { favorites, addFavorite, removeFavorite, toggleFavorite, isFavorite } = useFavorites();

• Хранит только ID товаров (оптимизация памяти)
• Toggle функция для удобного переключения
• Персистентность через localStorage

4. CompareContext (app/context/CompareContext.tsx)

Сравнение товаров (максимум 4):

const { compareItems, addToCompare, removeFromCompare, toggleCompare, clearCompare, isInCompare } = useCompare();

• FIFO очередь: при добавлении 5-го товара удаляется первый
• Хранит полные данные товаров для offline работы
• Персистентность через localStorage

📚 Документация

JSDoc документация:

Все компоненты и страницы полностью документированы с помощью JSDoc:

• app/components/ProductCard.tsx - Карточка товара

  • Интерфейсы: Product, ProductCardProps
  • Функции: handleAddToCart, handleToggleFavorite, handleToggleCompare
  • Логика предотвращения hydration mismatch

• app/favorites/page.tsx - Страница избранного

  • Загрузка данных из API
  • Empty state обработка

• app/cart/page.tsx - Страница корзины

  • Управление количеством товаров
  • Расчет итоговой суммы

• app/compare/page.tsx - Страница сравнения

  • Табличное представление характеристик
  • Максимум 4 товара

• app/auth/page.tsx - Страница аутентификации

  • 3 режима: login, signup, reset
  • Обработчики форм с валидацией

Файлы документации:

• docs/claude.md - Правила разработки (TDD, архитектура, антипаттерны)
• docs/claude2.md - Дополнительные правила
• docs/agents.md - Правила для AI агентов
• supabase/migrations/001_init.sql - SQL схема с комментариями
• README.md - Этот файл (общая документация)

Полезные ссылки:

• Next.js Docs
• Supabase Docs
• Supabase JavaScript Client
• React Context API

---

💡 Что дальше?

✅ Уже работает:

• Next.js 15 + TypeScript настроен
• Supabase подключен
• База данных создана
• API endpoints работают
• Главная страница готова
• Корзина (/cart) - добавление, удаление, изменение количества
• Избранное (/favorites) - добавление/удаление товаров
• Сравнение (/compare) - сравнение до 4-х товаров
• Аутентификация (/auth) - вход, регистрация, сброс пароля
• Каталог (/catalog) - 3 категории товаров
• Context API - глобальное состояние (Cart, Favorites, Compare, Auth)
• JSDoc документация - все компоненты и страницы документированы
• SSR совместимость - правильная работа с localStorage

🎨 Архитектурные решения:

• Context API вместо Redux - простота и минимум зависимостей
• localStorage - персистентность корзины/избранного без БД
• SSR safety - typeof window !== 'undefined' проверки
• Hydration mismatch prevention - isLoaded флаги в компонентах
• Constants extraction - никаких магических чисел
• Fail-fast approach - явная обработка ошибок (из claude.md)

⏳ Следующие шаги:

1. Тестирование (TDD подход):

   • Jest + React Testing Library настройка
   • Unit-тесты для Context провайдеров
   • Component тесты (ProductCard, Header)
   • Integration тесты для страниц

2. UX улучшения:

   • Toast уведомления (react-hot-toast)
   • Анимации переходов (framer-motion)
   • Skeleton loaders при загрузке
   • Оптимизация мобильной версии

3. Дополнительный функционал:

   • Оформление заказа (/checkout)
   • Страница профиля пользователя (/profile)
   • История заказов
   • Админ панель
   • Email уведомления
   • SEO оптимизация (metadata, sitemap)

---

🎓 Обучение

Этот проект отлично подходит для изучения:

Frontend:

• ✅ Next.js App Router
• ✅ React Server Components
• ✅ TypeScript
• ✅ CSS Modules

Backend:

• ✅ Next.js API Routes
• ✅ Supabase (PostgreSQL)
• ✅ REST API design
• ✅ Database design

Full-Stack:

• ✅ Authentication
• ✅ File uploads
• ✅ Realtime features
• ✅ Deployment

---

🤔 FAQ

Почему Supabase вместо обычной PostgreSQL?

Supabase дает:

• ✅ PostgreSQL БД в облаке (не нужен свой сервер)
• ✅ REST API автоматически
• ✅ Аутентификация из коробки
• ✅ Realtime подписки
• ✅ File storage
• ✅ Бесплатно для старта

Можно ли перенести на свой сервер потом?

Да! Supabase = обычная PostgreSQL + open-source инструменты. Можешь развернуть на своем сервере (Coolify, Railway, VPS).

Сколько стоит Supabase?

• Free tier: 500MB БД, 1GB файлов, 2GB трафика
• Pro: $25/мес - больше ресурсов
• Team/Enterprise: по запросу

Для начала Free tier более чем достаточно!

---

📞 Support

Если что-то не работает:

1. Проверь .env.local - правильные ли ключи
2. Проверь Supabase Dashboard - создались ли таблицы
3. Открой браузер DevTools (F12) - посмотри ошибки
4. Проверь терминал - логи сервера

---

📄 License

MIT License - свободно используй для учебы и коммерции

---

👏 Автор

Создано с ❤️ для обучения full-stack разработке

Stack: Next.js 16 + TypeScript + Supabase
Version: 2.0.0 (Supabase edition)
Status: ✅ Production Ready

---

🚀 Начни разрабатывать прямо сейчас!