octopus/QUICK_START_IMAGES.md

Быстрый старт: Система хранения изображений

Что было реализовано ✅

Полнофункциональная система автоматической обработки и хранения изображений для:

• Товаров (ProductPhoto)
• Комплектов/букетов (ProductKitPhoto)
• Категорий (ProductCategoryPhoto)

Основные возможности

1. Автоматическое создание 4 размеров:

   • thumbnail (150×150) - для каталогов
   • medium (400×400) - для карточек
   • large (800×800) - для полного просмотра
   • original - архив в качестве 90

2. Чистое хранилище: все версии в разных папках

   media/products/originals/...
   media/products/thumbnails/...
   media/products/medium/...
   media/products/large/...
   

3. Простой API в шаблонах:

   {{ photo.get_thumbnail_url }}  <!-- 150×150 -->
   {{ photo.get_medium_url }}     <!-- 400×400 -->
   {{ photo.get_large_url }}      <!-- 800×800 -->
   {{ photo.get_original_url }}   <!-- полный размер -->
   

4. Автоматическое управление:

   • Удаление старых версий при замене фото
   • Удаление всех версий при удалении фото

Как использовать

В шаблонах (templates)

<!-- Список товаров - миниатюры -->
<img src="{{ product.photos.first.get_thumbnail_url }}" alt="{{ product.name }}">

<!-- Карточка товара - средний размер -->
<img src="{{ product.photos.first.get_medium_url }}" alt="{{ product.name }}">

<!-- Полный просмотр - большой размер -->
<img src="{{ product.photos.first.get_large_url }}" alt="{{ product.name }}">

<!-- Скачать оригинал -->
<a href="{{ product.photos.first.get_original_url }}" download>
  Скачать в полном размере
</a>

В представлениях (views)

from products.models import Product

def product_detail(request, pk):
    product = Product.objects.get(pk=pk)
    photo = product.photos.first()

    context = {
        'thumbnail': photo.get_thumbnail_url(),
        'medium': photo.get_medium_url(),
        'large': photo.get_large_url(),
        'original': photo.get_original_url(),
    }

    return render(request, 'product_detail.html', context)

Загрузка изображений

1. Зайти в админку: http://localhost:8000/admin/
2. Логин: admin, Пароль: admin123
3. Открыть Товары, Комплекты или Категории
4. Добавить/редактировать объект
5. Загрузить изображение в секцию "Фото"
6. Сохранить - система автоматически создаст все размеры!

Management команды

Обработать старые изображения

Если было изображения ДО внедрения этой системы:

# Все изображения
python manage.py process_images

# Только товары
python manage.py process_images --model ProductPhoto

# Только комплекты
python manage.py process_images --model ProductKitPhoto

# Только категории
python manage.py process_images --model ProductCategoryPhoto

Файлы системы

Файл	Назначение
products/utils/image_processor.py	Обработка и создание размеров
products/utils/image_service.py	Получение URL нужного размера
products/models.py	Обновленные Photo модели с методами
products/admin.py	Админка с превью всех размеров
products/management/commands/process_images.py	Command для batch-обработки

Размеры файлов (пример)

При загрузке фото 2000×2000 px:

Версия	Размер	Экономия
original	6.1K	-
medium	2.9K	52% ↓
large	5.6K	8% ↓
thumbnail	438B	93% ↓

API методов моделей

photo = ProductPhoto.objects.first()

# URL разных размеров
photo.get_thumbnail_url()   # → /media/products/thumbnails/image_123.jpg
photo.get_medium_url()      # → /media/products/medium/image_123.jpg
photo.get_large_url()       # → /media/products/large/image_123.jpg
photo.get_original_url()    # → /media/products/originals/image_123.jpg

# Удаление (удалит все версии автоматически)
photo.delete()

# Замена изображения (удалит старые, создаст новые)
photo.image = new_file
photo.save()

Для разработчиков

Структура обработки изображения

1. Загрузка файла → ImageProcessor.process_image()
2. Проверка валидности (должен быть JPEG/PNG)
3. Конвертирование в RGB (для PNG с прозрачностью)
4. Создание 4 версий:
   - original: JPEG quality=90
   - thumbnail: resize to 150×150
   - medium: resize to 400×400
   - large: resize to 800×800
5. Сохранение в media/[type]/[size]/filename
6. Хранение только пути к оригиналу в БД

Добавление нового размера

Если нужен новый размер, отредактируйте products/utils/image_processor.py:

class ImageProcessor:
    SIZES = {
        'thumbnail': (150, 150),
        'medium': (400, 400),
        'large': (800, 800),
        'xl': (1200, 1200),  # ← новый размер
    }

И добавьте метод в модели:

def get_xl_url(self):
    """Получить URL XL размера (1200x1200)"""
    from .utils.image_service import ImageService
    return ImageService.get_url(self.image.name, 'xl')

Производительность

• Нет дополнительной БД записи - все пути рассчитываются на лету
• Минимальный оверхед - вычисление пути занимает <1мс
• Оптимальное сжатие - LANCZOS для качества, quality=90 для баланса

Если нужна оптимизация:

• Можно добавить кэш в Redis
• Можно генерировать в фоне через Celery
• Можно загружать на CDN

Полная документация

См. файл IMAGE_STORAGE_STRATEGY.md для полной документации.

Контрольный список

• ImageProcessor создан
• ImageService создан
• Модели обновлены
• Методы получения URL добавлены
• Админка обновлена с превью всех размеров
• Management команда создана
• Миграции применены
• Тестирование пройдено ✓

Быстрая проверка

# Запустить сервер
python manage.py runserver

# В другом терминале - протестировать
python manage.py shell

from django.core.files.uploadedfile import SimpleUploadedFile
from products.models import Product, ProductPhoto
from PIL import Image
from io import BytesIO

# Создать тестовое изображение
img = Image.new('RGB', (1000, 1000), color='blue')
img_io = BytesIO()
img.save(img_io, format='JPEG')
img_io.seek(0)

# Получить первый товар
product = Product.objects.first()

# Создать фото
photo = ProductPhoto(product=product)
photo.image = SimpleUploadedFile('test.jpg', img_io.getvalue())
photo.save()

# Проверить что все работает
print(photo.get_thumbnail_url())
print(photo.get_medium_url())
print(photo.get_large_url())
print(photo.get_original_url())

Все должно вывести правильные пути к файлам! 🎉