🛍️ FastAPI Shop - Полнофункциональный интернет-магазин

Современный, масштабируемый интернет-магазин с REST API на FastAPI и SPA frontend на Vue.js 3

---

📋 Содержание

• О проекте
• Структура проекта
• Технологический стек
• Быстрый старт
• Развертывание
• API документация
• Архитектура

---

🎯 О проекте

FastAPI Shop - это современное веб-приложение для электронной коммерции. Проект демонстрирует best practices разработки full-stack приложений с разделением backend и frontend.

✨ Ключевые возможности

• 🛒 Управление корзиной - добавление, удаление, изменение количества товаров
• 📦 Каталог товаров - просмотр товаров с фильтрацией по категориям
• 🔍 Детальная информация - подробные страницы товаров
• 💾 Персистентность данных - сохранение корзины в localStorage
• 🎨 Современный UI - адаптивный дизайн на Tailwind CSS
• 🚀 Production-ready - автоматический деплой с SSL сертификатами

---

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

fastapi-shop/
│
├── backend/                      # Backend часть (FastAPI)
│   ├── app/
│   │   ├── models/              # SQLAlchemy модели БД
│   │   │   ├── category.py     # Модель категорий
│   │   │   └── product.py      # Модель товаров
│   │   │
│   │   ├── schemas/             # Pydantic схемы для валидации
│   │   │   ├── cart.py         # Схемы корзины
│   │   │   ├── category.py     # Схемы категорий
│   │   │   └── product.py      # Схемы товаров
│   │   │
│   │   ├── repositories/        # Слой работы с БД (Repository Pattern)
│   │   │   ├── category_repository.py
│   │   │   └── product_repository.py
│   │   │
│   │   ├── services/            # Бизнес-логика приложения
│   │   │   ├── cart_service.py
│   │   │   ├── category_service.py
│   │   │   └── product_service.py
│   │   │
│   │   ├── routes/              # API endpoints (Controllers)
│   │   │   ├── cart.py         # Эндпоинты корзины
│   │   │   ├── categories.py   # Эндпоинты категорий
│   │   │   └── products.py     # Эндпоинты товаров
│   │   │
│   │   ├── config.py            # Конфигурация приложения
│   │   ├── database.py          # Настройка SQLAlchemy
│   │   └── main.py              # Точка входа FastAPI
│   │
│   ├── static/images/           # Статические файлы (изображения)
│   ├── Dockerfile               # Docker образ backend
│   ├── requirements.txt         # Python зависимости
│   ├── run.py                   # Скрипт запуска сервера
│   └── seed_data.py            # Заполнение БД тестовыми данными
│
├── frontend/                     # Frontend часть (Vue.js 3)
│   ├── src/
│   │   ├── components/          # Vue компоненты
│   │   │   ├── CartItem.vue    # Элемент корзины
│   │   │   ├── CategoryFilter.vue  # Фильтр категорий
│   │   │   ├── Header.vue      # Шапка сайта
│   │   │   └── ProductCard.vue # Карточка товара
│   │   │
│   │   ├── views/               # Страницы приложения
│   │   │   ├── HomePage.vue    # Главная (каталог)
│   │   │   ├── ProductDetailPage.vue  # Детали товара
│   │   │   └── CartPage.vue    # Страница корзины
│   │   │
│   │   ├── stores/              # Pinia stores (State Management)
│   │   │   ├── cart.js         # Store корзины
│   │   │   └── products.js     # Store товаров
│   │   │
│   │   ├── services/            # API клиенты
│   │   │   └── api.js          # Axios конфигурация и методы
│   │   │
│   │   ├── router/              # Vue Router конфигурация
│   │   │   └── index.js        # Определение маршрутов
│   │   │
│   │   ├── assets/              # Статические ресурсы
│   │   ├── App.vue              # Корневой компонент
│   │   └── main.js              # Точка входа приложения
│   │
│   ├── Dockerfile               # Docker образ frontend
│   ├── nginx.conf               # Конфигурация Nginx для SPA
│   ├── package.json             # NPM зависимости
│   └── vite.config.js          # Конфигурация Vite
│
├── nginx/                        # Reverse proxy конфигурация
│   └── nginx.conf               # Главная конфигурация Nginx
│
├── docker-compose.yml            # Оркестрация Docker контейнеров
├── deploy.sh                     # Скрипт автоматического деплоя
└── README.md                     # Документация проекта

🔍 Назначение компонентов

Backend (FastAPI)

Компонент	Назначение
models/	SQLAlchemy модели для работы с БД (ORM)
schemas/	Pydantic схемы для валидации входящих/исходящих данных
repositories/	Инкапсуляция логики работы с БД (Repository Pattern)
services/	Бизнес-логика приложения (Service Layer)
routes/	HTTP endpoints и маршрутизация (Controllers)
config.py	Настройки приложения (CORS, DB, пути)
database.py	Конфигурация SQLAlchemy и управление сессиями
main.py	Инициализация FastAPI, подключение middleware и роутеров

Frontend (Vue.js 3)

Компонент	Назначение
components/	Переиспользуемые UI компоненты
views/	Страницы приложения (роутинг)
stores/	Глобальное состояние приложения (Pinia)
services/	HTTP клиент для взаимодействия с API
router/	Конфигурация маршрутизации (Vue Router)

---

🛠 Технологический стек

Backend

• FastAPI 0.119.0 - современный, быстрый web-framework
• SQLAlchemy 2.0.44 - ORM для работы с базой данных
• Pydantic 2.12.1 - валидация данных и настроек
• SQLite - легковесная реляционная СУБД
• Uvicorn - ASGI сервер для production

Frontend

• Vue.js 3.5.22 - прогрессивный JavaScript фреймворк
• Pinia 3.0.3 - официальный state management для Vue 3
• Vue Router 4.5.1 - роутинг для SPA
• Axios 1.12.2 - HTTP клиент
• Tailwind CSS - utility-first CSS фреймворк
• Vite 7.1.7 - быстрый build tool

DevOps

• Docker - контейнеризация приложений
• Docker Compose - оркестрация multi-container приложений
• Nginx - reverse proxy и веб-сервер
• Let's Encrypt - бесплатные SSL сертификаты
• Certbot - автоматическое обновление сертификатов

---

🚀 Быстрый старт

Предварительные требования

• Python 3.11+
• Node.js 20+
• npm/yarn
• Git

Локальная разработка

1️⃣ Клонирование репозитория

git clone https://github.com/yourusername/fastapi-shop.git
cd fastapi-shop

2️⃣ Запуск Backend

# Переход в директорию backend
cd backend

# Создание виртуального окружения
python -m venv venv
source venv/bin/activate  # Linux/Mac
# или
venv\Scripts\activate  # Windows

# Установка зависимостей
pip install -r requirements.txt

# Заполнение базы данных тестовыми данными
python seed_data.py

# Запуск сервера разработки
python run.py

Backend будет доступен по адресу: http://localhost:8000 API документация (Swagger UI): http://localhost:8000/api/docs

3️⃣ Запуск Frontend

# Переход в директорию frontend (новый терминал)
cd frontend

# Установка зависимостей
npm install

# Запуск dev сервера
npm run dev

Frontend будет доступен по адресу: http://localhost:5173

---

🌐 Развертывание

Проект включает полностью автоматизированный скрипт развертывания на production сервер с Ubuntu.

Что делает скрипт deploy.sh:

✅ Обновляет систему Ubuntu ✅ Устанавливает Docker и Docker Compose ✅ Устанавливает Certbot для SSL ✅ Получает SSL сертификаты от Let's Encrypt ✅ Настраивает Nginx как reverse proxy ✅ Собирает и запускает Docker контейнеры ✅ Заполняет базу данных тестовыми данными ✅ Настраивает автоматическое обновление SSL сертификатов

📦 Инструкция по развертыванию

Шаг 1: Подготовка сервера

# Подключение к VPS серверу
ssh root@your-server-ip

# Клонирование репозитория
git clone https://github.com/yourusername/fastapi-shop.git
cd fastapi-shop

Шаг 2: Настройка DNS

Перед запуском скрипта убедитесь, что DNS записи вашего домена указывают на IP адрес сервера:

A запись:     yourdomain.com    →  SERVER_IP
A запись:     www.yourdomain.com →  SERVER_IP

Проверить можно командой:

dig yourdomain.com +short
dig www.yourdomain.com +short

Шаг 3: Запуск скрипта деплоя

# Сделать скрипт исполняемым
chmod +x deploy.sh

# Запустить с правами root
sudo ./deploy.sh

Шаг 4: Интерактивная настройка

Скрипт запросит у вас:

1. Домен (например: myshop.com)
2. Email для SSL (например: admin@myshop.com)
3. Название магазина (например: My Awesome Shop)

После ввода данных скрипт:

• Создаст конфигурационные файлы
• Получит SSL сертификаты
• Соберет и запустит все сервисы

Шаг 5: Проверка работоспособности

После завершения скрипта ваш магазин будет доступен по адресам:

• 🌐 Магазин: https://yourdomain.com
• 🌐 API документация: https://yourdomain.com/api/docs
• ✅ Health check: https://yourdomain.com/health

🔧 Управление после деплоя

Просмотр логов

# Все сервисы
docker compose logs -f

# Только backend
docker compose logs -f backend

# Только frontend
docker compose logs -f frontend

# Nginx
docker compose logs -f nginx

Перезапуск сервисов

# Перезапуск всех контейнеров
docker compose restart

# Перезапуск конкретного сервиса
docker compose restart backend

Остановка приложения

# Остановить все контейнеры
docker compose down

# Остановить и удалить volumes (БД будет удалена!)
docker compose down -v

Обновление приложения

# Получить последние изменения
git pull

# Пересобрать и перезапустить контейнеры
docker compose up -d --build

Резервное копирование БД

# Создать backup базы данных
docker compose exec backend cp /app/shop.db /app/backup_shop.db

# Скопировать на хост машину
docker cp fashop_backend:/app/backup_shop.db ./backup_shop.db

🔐 SSL сертификаты

Сертификаты автоматически обновляются через контейнер certbot каждые 12 часов.

Ручное обновление:

docker compose restart certbot

Проверка срока действия:

sudo certbot certificates

---

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

Основные endpoints

Products (Товары)

Метод	Endpoint	Описание
GET	/api/products	Получить все товары
GET	/api/products/{id}	Получить товар по ID
GET	/api/products/category/{category_id}	Товары по категории

Categories (Категории)

Метод	Endpoint	Описание
GET	/api/categories	Получить все категории
GET	/api/categories/{id}	Получить категорию по ID

Cart (Корзина)

Метод	Endpoint	Описание
POST	/api/cart/add	Добавить товар в корзину
POST	/api/cart	Получить содержимое корзины
PUT	/api/cart/update	Обновить количество товара
DELETE	/api/cart/remove/{id}	Удалить товар из корзины

Примеры запросов

Получить все товары

curl -X GET "http://localhost:8000/api/products"

Ответ:

{
  "products": [
    {
      "id": 1,
      "name": "Wireless Headphones",
      "description": "High-quality wireless headphones...",
      "price": 299.99,
      "category_id": 1,
      "image_url": "https://...",
      "created_at": "2024-01-15T10:30:00",
      "category": {
        "id": 1,
        "name": "Electronics",
        "slug": "electronics"
      }
    }
  ],
  "total": 13
}

Добавить товар в корзину

curl -X POST "http://localhost:8000/api/cart/add" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 1,
    "quantity": 2,
    "cart": {}
  }'

Ответ:

{
  "cart": {
    "1": 2
  }
}

Полная документация API с интерактивными примерами доступна по адресу: http://localhost:8000/api/docs (Swagger UI)

---

🏗 Архитектура

Backend Architecture (Layered Architecture)

┌─────────────────────────────────────────┐
│           API Layer (Routes)            │  ← HTTP Endpoints
├─────────────────────────────────────────┤
│        Service Layer (Services)         │  ← Business Logic
├─────────────────────────────────────────┤
│    Repository Layer (Repositories)      │  ← Data Access
├─────────────────────────────────────────┤
│      Database Layer (SQLAlchemy)        │  ← ORM
└─────────────────────────────────────────┘

Преимущества подхода:

• ✅ Разделение ответственности (Separation of Concerns)
• ✅ Легкое тестирование каждого слоя
• ✅ Возможность замены компонентов без изменения других слоев
• ✅ Масштабируемость кода

Frontend Architecture (Component-Based)

┌─────────────────────────────────────────┐
│         Views (Pages)                   │  ← Route Components
├─────────────────────────────────────────┤
│         Components                       │  ← Reusable UI
├─────────────────────────────────────────┤
│         Stores (Pinia)                  │  ← State Management
├─────────────────────────────────────────┤
│         Services (API)                  │  ← HTTP Client
└─────────────────────────────────────────┘

Data Flow (Client-Server)

┌──────────┐         ┌─────────┐         ┌──────────┐         ┌──────────┐
│  Vue.js  │ ──────> │  Nginx  │ ──────> │  FastAPI │ ──────> │  SQLite  │
│ Frontend │ <────── │  Proxy  │ <────── │  Backend │ <────── │    DB    │
└──────────┘  HTTPS  └─────────┘   HTTP  └──────────┘   SQL   └──────────┘

Docker Architecture

┌─────────────────────────────────────────────────────────┐
│                    Docker Host                          │
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐ │
│  │   Nginx      │  │   Frontend   │  │   Backend   │ │
│  │ (Port 80/443)│  │  (Vue.js)    │  │  (FastAPI)  │ │
│  └──────┬───────┘  └──────┬───────┘  └──────┬──────┘ │
│         │                 │                  │         │
│         └─────────────────┴──────────────────┘         │
│                                                         │
│  ┌──────────────────────────────────────────────────┐ │
│  │           Docker Network (fashop_network)        │ │
│  └──────────────────────────────────────────────────┘ │
│                                                         │
│  ┌──────────────┐                                     │
│  │   Certbot    │  (SSL Certificate Renewal)          │
│  └──────────────┘                                     │
└─────────────────────────────────────────────────────────┘

---

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

Backend тесты (pytest)

cd backend
pytest

Frontend тесты (Vitest)

cd frontend
npm run test

API тестирование (Postman)

Импортируйте коллекцию из файла backend/test_commands.md

---