🛍️ Online Store API

Полнофункциональный REST API интернет-магазина с JWT-аутентификацией, системой заказов, интеграцией платежей, фоновыми задачами и email-уведомлениями.

---

📋 Содержание

• О проекте
• Технологический стек
• Функциональность
• Быстрый старт с Docker
• Локальная установка
• API Endpoints
• Архитектура

---

🎯 О проекте

Современный асинхронный REST API для интернет-магазина с полным циклом обработки заказов: от регистрации пользователя до оплаты и отправки email-уведомлений.

Ключевые особенности:

• ✅ Асинхронная архитектура — высокая производительность с async/await
• ✅ JWT-аутентификация — access + refresh токены
• ✅ Ролевая модель — Admin, Seller, Buyer с разными правами
• ✅ Полнотекстовый поиск — PostgreSQL TSVECTOR с ранжированием
• ✅ Интеграция платежей — ЮKassa с webhook обработкой
• ✅ Фоновые задачи — Celery + Redis для email-уведомлений
• ✅ Email-сервис — асинхронная отправка писем через aiosmtplib
• ✅ Docker-ready — полная контейнеризация проекта
• ✅ Миграции БД — Alembic для версионирования схемы
• ✅ Логирование — Loguru с контекстом запросов

---

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

Backend Framework & Core

• Python 3.11+ — основной язык программирования
• FastAPI — современный асинхронный веб-фреймворк
• Uvicorn — ASGI-сервер для production
• Pydantic — валидация данных и settings management

База данных

• PostgreSQL 15 — реляционная СУБД
• SQLAlchemy 2.0 — асинхронный ORM
• asyncpg — асинхронный драйвер для PostgreSQL
• Alembic — миграции базы данных

Аутентификация и безопасность

• PyJWT — работа с JSON Web Tokens
• Passlib + Bcrypt — безопасное хеширование паролей
• OAuth2PasswordBearer — стандартная схема авторизации

Фоновые задачи и кэширование

• Celery — распределённая очередь задач
• Redis — брокер сообщений и кэш

Email-сервис

• aiosmtplib — асинхронная отправка email
• MailDev — тестирование email в разработке

Интеграция платежей

• YooKassa SDK — платёжная система
• Webhook processing — асинхронная обработка событий
• IP-валидация — защита webhook endpoints

DevOps & Tools

• Docker + Docker Compose — контейнеризация
• Loguru — продвинутое логирование
• python-multipart — обработка файлов

---

🚀 Функциональность

1. Управление пользователями

• Регистрация с ролями (buyer/seller/admin)
• JWT-аутентификация (access + refresh токены)
• Email-уведомления при регистрации
• Автоматическое создание первого администратора

2. Управление категориями

• Создание, обновление, удаление категорий
• Иерархическая структура (parent-child)
• Мягкое удаление (soft delete)
• Доступно только администраторам

3. Управление товарами

• CRUD операции для товаров
• Загрузка и обработка изображений (JPG, PNG, WebP)
• Полнотекстовый поиск по названию и описанию с ранжированием
• Фильтрация: категория, цена, наличие, продавец
• Пагинация результатов
• Автоматическое управление активностью при изменении остатков
• Продавцы управляют только своими товарами

4. Система отзывов

• Создание отзывов с оценками (1-5 звёзд)
• Ограничение: один отзыв на товар от покупателя
• Автоматический пересчёт рейтинга товара
• Модерация отзывов администратором

5. Корзина покупателя

• Добавление/обновление/удаление товаров
• Автоматический расчёт общей стоимости
• Проверка доступности товаров
• Уникальность товара в корзине пользователя

6. Система заказов

• Создание заказа из корзины (checkout)
• Автоматическое резервирование товаров
• Статусы: pending → paid/canceled
• История заказов с пагинацией
• Интеграция с платёжной системой

7. Интеграция платежей (ЮKassa)

• Создание платежей с фискализацией
• Webhook для обработки платёжных событий
• Проверка IP-адресов YooKassa для безопасности
• Автоматическое обновление статуса заказа

8. Email-уведомления

• Приветственные письма при регистрации
• Асинхронная отправка через Celery

---

⚡ Быстрый старт с Docker

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

• Docker Desktop или Docker Engine + Docker Compose
• Git

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

git clone https://github.com/9meows/online-store-api.git
cd online-store-api

2. Настройка переменных окружения

cp .env.example .env
# Отредактируйте .env файл (SECRET_KEY, YooKassa credentials)

3. Запуск всего стека

# Сборка образов
docker-compose build

# Запуск всех сервисов
docker-compose up -d

# Проверка статуса
docker-compose ps

4. Применение миграций и создание админа

# Миграции БД
docker-compose exec api alembic upgrade head

# Создание первого администратора
docker-compose exec api python -m app.scripts.create_first_admin

5. Готово! 🎉

• API: http://localhost:8000
• Swagger Docs: http://localhost:8000/docs
• MailDev (Email): http://localhost:8080

---

💻 Локальная установка

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

• Python 3.11+
• PostgreSQL 15+
• Redis 7+

1. Клонирование и окружение

git clone https://github.com/9meows/online-store-api.git
cd online-store-api

python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

pip install -r requirements.txt

2. Настройка БД и Redis

# PostgreSQL
createdb online_store

# Redis (должен быть запущен)
redis-cli ping  # Проверка

3. Переменные окружения

cp .env.example .env
# Отредактируйте .env:
# - DB_HOST=localhost
# - CELERY_BROKER_URL=redis://localhost:6379/0
# - SMTP_HOST=localhost (или ваш SMTP)

4. Миграции и админ

alembic upgrade head
python -m app.scripts.create_first_admin

5. Запуск сервисов

# Терминал 1: FastAPI
uvicorn app.main:app --reload --port 8000

# Терминал 2: Celery Worker
celery -A app.celery_app worker --loglevel=info

---

📡 API Endpoints

Аутентификация

POST   /users/                # Регистрация (→ email-уведомление)
POST   /users/token           # Логин (получение токенов)
POST   /users/refresh-token   # Обновление access токена

Категории (Admin only)

GET    /categories/           # Список категорий
POST   /categories/           # Создание
PUT    /categories/{id}       # Обновление
DELETE /categories/{id}       # Удаление (soft delete)

Товары

GET    /products/             # Список (фильтры + полнотекстовый поиск)
POST   /products/             # Создание (seller)
GET    /products/{id}         # Детали товара
PUT    /products/{id}         # Обновление (seller, свои товары)
DELETE /products/{id}         # Удаление (seller, свои товары)
GET    /products/category/{id} # Товары по категории

Примеры фильтров:

GET /products/?search=iphone&min_price=500&max_price=2000&category_id=1&in_stock=true

Отзывы

GET    /reviews/              # Все отзывы
GET    /products/{id}/reviews/ # Отзывы товара
POST   /reviews/              # Создание (buyer, 1 на товар)
DELETE /reviews/{id}          # Удаление (admin)

Корзина (Buyer only)

GET    /cart/                 # Просмотр корзины
POST   /cart/items            # Добавление товара
POST   /cart/items/{id}       # Обновление количества
DELETE /cart/items/{id}       # Удаление товара
DELETE /cart/                 # Очистка корзины

Заказы (Buyer only)

POST   /orders/checkout       # Оформление заказа → YooKassa
GET    /orders/               # История заказов (пагинация)
GET    /orders/{id}           # Детали заказа
GET    /orders/{id}/status    # Статус заказа

Платежи

POST   /payments/yookassa/webhook  # Webhook от YooKassa

Health Check

GET    /                     # Приветственное сообщение

---

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

Структура базы данных

users (пользователи)
├── cart_items (корзина)
├── orders (заказы)
│   └── order_items (позиции заказов)
└── products (товары)
    ├── reviews (отзывы)
    └── categories (категории)

Ролевая модель

Роль	Права
Admin	Управление категориями, модерация отзывов
Seller	CRUD своих товаров, загрузка изображений
Buyer	Корзина, заказы, отзывы, просмотр товаров

Полнотекстовый поиск

-- PostgreSQL TSVECTOR с GIN индексом
CREATE INDEX ix_products_tsv_gin ON products USING gin(tsv);

-- Веса: название (A) > описание (B)
tsv = setweight(to_tsvector('english', name), 'A') 
   || setweight(to_tsvector('english', description), 'B')

Celery задачи

# Текущие задачи:
- send_email_task: Отправка email-уведомлений

# Идеи для расширения:
- generate_report_task: Генерация отчётов
- optimize_images_task: Оптимизация изображений
- cleanup_old_orders_task: Очистка старых заказов (через Celery Beat)

---

📊 Мониторинг и отладка

MailDev (Email Testing)

# URL: http://localhost:8080
# Все отправленные email отображаются здесь

Логи

# Docker
docker-compose logs -f api
docker-compose logs -f celery_worker

# Локально
tail -f info.log

---

🐛 Troubleshooting

Проблема: Email не отправляются

# 1. Проверьте Celery worker
docker-compose logs celery_worker

# 2. Проверьте MailDev
open http://localhost:8080

# 3. Проверьте настройки SMTP в .env
SMTP_HOST=maildev
SMTP_PORT=1025

Проблема: Ошибки миграций

# Сбросить БД и пересоздать
docker-compose down -v
docker-compose up -d
docker-compose exec api alembic upgrade head

Проблема: Celery не подключается к Redis

# Проверьте Redis
docker-compose exec redis redis-cli ping

# Проверьте переменные окружения
docker-compose exec celery_worker env | grep CELERY

---

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

└── online-store-api/
    ├── Dockerfile
    ├── README.md
    ├── alembic.ini
    ├── app
    │   ├── __init__.py
    │   ├── auth.py
    │   ├── celery_app.py
    │   ├── config.py
    │   ├── database.py
    │   ├── db_depends.py
    │   ├── email_service
    │   │   ├── __init__.py
    │   │   └── send_email.py
    │   ├── log.py
    │   ├── main.py
    │   ├── migrations
    │   │   ├── README
    │   │   ├── env.py
    │   │   ├── script.py.mako
    │   │   └── versions
    │   ├── models
    │   │   ├── __init__.py
    │   │   ├── cart_items.py
    │   │   ├── categories.py
    │   │   ├── orders.py
    │   │   ├── products.py
    │   │   ├── reviews.py
    │   │   └── users.py
    │   ├── payments.py
    │   ├── routers
    │   │   ├── cart.py
    │   │   ├── categories.py
    │   │   ├── orders.py
    │   │   ├── payments.py
    │   │   ├── products.py
    │   │   ├── reviews.py
    │   │   └── users.py
    │   ├── schemas.py
    │   ├── scripts
    │   │   └── create_first_admin.py
    │   └── tasks
    │       ├── __init__.py
    │       └── email_tasks.py
    ├── docker-compose.yml
    │── requirements.txt
    ├── .env.example           
    └── .dockerignore

---

🎓 Что демонстрирует проект

Архитектурные паттерны

• ✅ Dependency Injection
• ✅ Repository Pattern (через SQLAlchemy)
• ✅ Soft Delete Pattern
• ✅ Middleware Pattern
• ✅ Task Queue Pattern (Celery)

Best Practices

• ✅ Асинхронное программирование (async/await)
• ✅ Полная типизация (Python type hints)
• ✅ Валидация данных (Pydantic)
• ✅ Миграции БД (Alembic)
• ✅ Безопасность (JWT, bcrypt, IP validation)
• ✅ Логирование с контекстом
• ✅ Контейнеризация (Docker)
• ✅ Фоновые задачи (Celery)

Database Features

• ✅ Сложные связи (One-to-Many, Many-t