🛍️ FastAPI Web Shop Template

Шаблон современного интернет-магазина на FastAPI с админ-панелью, API и веб-интерфейсом.

✨ Возможности

🎯 Основной функционал

Каталог товаров с категориями, поиском и фильтрацией
Корзина покупок с сохранением в сессии
Система заказов с отслеживанием статуса
Отзывы и рейтинги товаров
Профиль пользователя с историей заказов
Аутентификация через JWT (RS256)

🛠️ Технический стек

FastAPI - современный, быстрый веб-фреймворк
SQLAlchemy 2.0 - асинхронная работа с БД
PostgreSQL - основная база данных
Alembic - миграции БД
SQLAdmin - готовая админ-панель
Jinja2 - шаблонизатор для веб-интерфейса
JWT (RS256) - безопасная аутентификация
Docker & Docker Compose - контейнеризация
Nginx - reverse proxy

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

app/
├── admin/          # Админ-панель (SQLAdmin)
├── api/            # REST API (v1)
│   └── v1/
│       └── endpoints/
├── core/           # Конфигурация, безопасность, зависимости
├── crud/           # CRUD операции
├── models/         # SQLAlchemy модели
├── schemas/        # Pydantic схемы
├── static/         # CSS, JS, изображения
├── templates/      # HTML шаблоны
├── utils/          # Утилиты (корзина и др.)
└── web/            # Веб-интерфейс (HTML страницы)

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

Требования

Python 3.14+
uv - быстрый менеджер пакетов Python
PostgreSQL 16+ (или Docker)
Docker с Docker Compose plugin v2+ (для Docker-режима)

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

# Клонировать репозиторий
git clone <repository-url>
cd web-shop-fastapi-template

# Установить зависимости
make install

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

# Скопировать пример конфигурации
cp .env.example .env

# Отредактировать .env файл
# Обязательно установите:
# - DB_NAME (имя базы данных)
# - ADMIN_SECRET_KEY (секретный ключ для сессий)

3. Генерация JWT ключей

# Создать директорию для сертификатов
mkdir -p app/core/certs

# Сгенерировать приватный ключ
openssl genrsa -out app/core/certs/jwt-private.pem 2048

# Сгенерировать публичный ключ
openssl rsa -in app/core/certs/jwt-private.pem -pubout -out app/core/certs/jwt-public.pem

4. Инициализация базы данных

# Применить миграции
make db-upgrade

5. Запуск приложения

# Запустить dev-сервер
make run

Приложение будет доступно по адресу: http://localhost:8000

📝 Основные команды

Разработка

make install        # Установить зависимости
make run           # Запустить dev-сервер
make dev           # Алиас для run

Качество кода

make fmt           # Форматировать код (ruff + black)
make lint          # Проверить код линтером
make type          # Проверить типы (mypy)
make check         # Запустить все проверки
make pre-commit    # Запустить pre-commit хуки

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

make test          # Запустить тесты
make test-v        # Тесты с подробным выводом
make test-cov      # Тесты с покрытием

База данных

make migrate           # Создать и применить миграцию
make migrate-create    # Создать миграцию без применения
make db-upgrade        # Применить все миграции
make db-downgrade      # Откатить последнюю миграцию

Docker

make docker-build      # Собрать образ
make docker-up         # Запустить контейнеры
make docker-down       # Остановить контейнеры
make docker-logs       # Просмотр логов
make docker-shell      # Открыть shell в контейнере

Очистка

make clean         # Удалить кэш и временные файлы
make clean-all     # Полная очистка (включая .venv)

🐳 Запуск с Docker

Быстрый запуск

# Запустить все сервисы
make docker-up

# Приложение доступно на http://localhost

Структура сервисов

services:
  postgres:  # PostgreSQL 16
  app:       # FastAPI приложение (порт 8000)
  nginx:     # Reverse proxy (порт 80)

Полезные команды

# Просмотр логов
make docker-logs

# Перезапуск сервисов
make docker-restart

# Остановка
make docker-down

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

Проект использует JWT токены с алгоритмом RS256 (асимметричное шифрование).

Endpoints

POST /api/v1/auth/register - регистрация
POST /api/v1/auth/login - вход
POST /api/v1/auth/refresh - обновление токена
POST /api/v1/auth/logout - выход

Типы токенов

Access Token - короткий срок жизни (15 минут по умолчанию)
Refresh Token - длительный срок жизни (7 дней по умолчанию)

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

После запуска приложения доступны:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

Основные endpoints

Товары

GET /api/v1/products - список товаров
GET /api/v1/products/{id} - детали товара
POST /api/v1/products - создать товар (admin)

Категории

GET /api/v1/categories - список категорий
POST /api/v1/categories - создать категорию (admin)

Заказы

GET /api/v1/orders - мои заказы
POST /api/v1/orders - создать заказ
GET /api/v1/orders/{id} - детали заказа

Корзина

GET /api/v1/cart - содержимое корзины
POST /api/v1/cart/add - добавить товар
DELETE /api/v1/cart/remove/{product_id} - удалить товар

Отзывы

GET /api/v1/reviews - список отзывов
POST /api/v1/reviews - оставить отзыв

🎨 Веб-интерфейс

Доступные страницы:

/ - главная страница
/catalog - каталог товаров
/product/{slug} - страница товара
/cart - корзина
/checkout - оформление заказа
/account - личный кабинет
/login - вход
/register - регистрация

🔧 Админ-панель

Админ-панель доступна по адресу: http://localhost:8000/admin

Возможности

Управление товарами
Управление категориями
Управление пользователями
Просмотр заказов
Управление отзывами

Настройка прав

Права администратора настраиваются в .env:

ADMIN_CAN_CREATE=True
ADMIN_CAN_EDIT=True
ADMIN_CAN_DELETE=True
ADMIN_CAN_VIEW_DETAILS=True

🗄️ Модели данных

Product (Товар)

name - название
slug - URL-идентификатор
description - описание
price - цена
category_id - категория
image - изображение
stock - остаток на складе
is_active - активность

Category (Категория)

name - название
slug - URL-идентификатор
description - описание

Order (Заказ)

user_id - пользователь
total_price - общая стоимость
status - статус заказа
created_at - дата создания

User (Пользователь)

email - email (уникальный)
username - имя пользователя
hashed_password - хеш пароля
is_active - активность
is_superuser - администратор

Review (Отзыв)

product_id - товар
user_id - пользователь
rating - оценка (1-5)
comment - комментарий

⚙️ Конфигурация

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

База данных

DB_USER=postgres
DB_PASSWORD=postgres
DB_HOST=localhost
DB_PORT=5432
DB_NAME=web_shop

DB_ECHO=False              # SQL логирование
DB_POOL_SIZE=5             # Размер пула соединений
DB_MAX_OVERFLOW=10         # Дополнительные соединения
DB_POOL_PRE_PING=True      # Проверка соединений
DB_POOL_RECYCLE=3600       # Переиспользование соединений (сек)
DB_AUTOFLUSH=False
DB_EXPIRE_ON_COMMIT=False

Админ-панель

ADMIN_SECRET_KEY=your-secret-key-here
ADMIN_CAN_CREATE=True
ADMIN_CAN_EDIT=True
ADMIN_CAN_DELETE=True
ADMIN_CAN_VIEW_DETAILS=True

JWT

AUTHJWT_ACCESS_TOKEN_EXPIRE_MINUTES=15
AUTHJWT_REFRESH_TOKEN_EXPIRE_DAYS=7

📦 Зависимости

Основные:

fastapi - веб-фреймворк
uvicorn - ASGI сервер
sqlalchemy - ORM
asyncpg - PostgreSQL драйвер
alembic - миграции
sqladmin - админ-панель
pydantic - валидация данных
pyjwt - JWT токены
passlib - хеширование паролей
jinja2 - шаблоны

Инструменты разработки:

ruff - линтер и форматтер
black - форматтер кода
mypy - проверка типов
pytest - тестирование
pre-commit - Git хуки

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

# Запустить все тесты
make test

# С покрытием кода
make test-cov

# Просмотр HTML отчета покрытия
open htmlcov/index.html

🔍 Линтинг и форматирование

Проект использует:

Ruff - быстрый линтер и форматтер
Black - форматтер кода
MyPy - проверка типов

# Автоматическое форматирование
make fmt

# Проверка линтером
make lint

# Проверка типов
make type

# Все проверки сразу
make check

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

web-shop-fastapi-template/
├── alembic/                 # Миграции БД
│   └── versions/
├── app/
│   ├── admin/              # Админ-панель
│   │   ├── auth.py
│   │   ├── setup.py
│   │   └── views.py
│   ├── api/                # REST API
│   │   └── v1/
│   │       ├── endpoints/
│   │       └── api.py
│   ├── core/               # Ядро приложения
│   │   ├── auth.py
│   │   ├── config.py
│   │   ├── database.py
│   │   ├── deps.py
│   │   ├── handlers.py
│   │   ├── security.py
│   │   └── templates.py
│   ├── crud/               # CRUD операции
│   ├── models/             # SQLAlchemy модели
│   ├── schemas/            # Pydantic схемы
│   ├── static/             # Статические файлы
│   │   ├── css/
│   │   ├── img/
│   │   └── js/
│   ├── templates/          # HTML шаблоны
│   ├── utils/              # Утилиты
│   └── web/                # Веб-интерфейс
├── tests/                  # Тесты
├── .env.example            # Пример конфигурации
├── docker-compose.yml      # Docker Compose
├── Dockerfile              # Docker образ
├── main.py                 # Точка входа
├── Makefile                # Make команды
└── pyproject.toml          # Конфигурация проекта

🚢 Production

🤝 Разработка

Рабочий процесс

Создайте ветку для фичи
```
git checkout -b feature/amazing-feature
```
Внесите изменения и проверьте код
```
make check
```
Запустите тесты
```
make test
```
Создайте коммит
```
git commit -m "Add amazing feature"
```

Pre-commit хуки

Проект использует pre-commit для автоматических проверок:

# Установить хуки
uv run pre-commit install

# Запустить вручную
make pre-commit

📄 Лицензия

Этот проект является шаблоном для создания собственных веб-магазинов. Используйте его свободно для своих проектов.

🙏 Благодарности

Создано с использованием:

📞 Поддержка

Если у вас возникли вопросы или проблемы:

Проверьте существующие issues
Создайте новый issue с подробным описанием
Укажите версию Python и ОС

Создано с ❤️ для быстрого старта веб-магазинов на FastAPI

Name		Name	Last commit message	Last commit date
Latest commit History 97 Commits
alembic		alembic
app		app
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
alembic.ini		alembic.ini
docker-compose.yml		docker-compose.yml
main.py		main.py
nginx.conf		nginx.conf
pyproject.toml		pyproject.toml
uv.lock		uv.lock

softlyfear/web-shop-fastapi-template

Folders and files

Latest commit

History

Repository files navigation

🛍️ FastAPI Web Shop Template

✨ Возможности

🎯 Основной функционал

🛠️ Технический стек

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

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

Требования

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

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

3. Генерация JWT ключей

4. Инициализация базы данных

5. Запуск приложения

📝 Основные команды

Разработка

Качество кода

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

База данных

Docker

Очистка

🐳 Запуск с Docker

Быстрый запуск

Структура сервисов

Полезные команды

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

Endpoints

Типы токенов

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

Основные endpoints

Товары

Категории

Заказы

Корзина

Отзывы

🎨 Веб-интерфейс

🔧 Админ-панель

Возможности

Настройка прав

🗄️ Модели данных

Product (Товар)

Category (Категория)

Order (Заказ)

User (Пользователь)

Review (Отзыв)

⚙️ Конфигурация

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

База данных

Админ-панель

JWT

📦 Зависимости

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

🔍 Линтинг и форматирование

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

🚢 Production

Рекомендации для продакшена

🤝 Разработка

Рабочий процесс

Pre-commit хуки

📄 Лицензия

🙏 Благодарности

📞 Поддержка

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages