octopus/FRONTEND_IMAGES_GUIDE.md

# Руководство по использованию изображений на фронтенде

## Обзор

Система автоматически служит изображения разных размеров в зависимости от контекста:

- **Списки товаров**: миниатюры (150×150) - быстрая загрузка
- **Карточки товаров**: средний размер (400×400) - хороший баланс
- **Галереи и модальные окна**: большой размер (800×800) - высокое качество
- **Полноэкранный просмотр**: оригинал - максимальное качество

## Использованные размеры в шаблонах

### 1. all_products_list.html (Объединённый список товаров и комплектов)

```django
<!-- Список с миниатюрами -->
<img src="{{ photo.get_thumbnail_url }}" alt="{{ item.name }}" class="img-thumbnail">
```

**Размер на диске**: 438B (93% экономия)
**Использование**: Таблица со списком товаров, быстрая загрузка

---

### 2. product_list.html (Список только товаров)

```django
<!-- В таблице - миниатюры -->
<img src="{{ photo.get_thumbnail_url }}" alt="{{ product.name }}" class="img-thumbnail">
```

**Размер на диске**: 438B (93% экономия)
**Использование**: Табличное отображение товаров

---

### 3. productkit_list.html (Список комплектов)

```django
<!-- В таблице - миниатюры -->
<img src="{{ photo.get_thumbnail_url }}" alt="{{ kit.name }}" class="img-thumbnail">
```

**Размер на диске**: 438B (93% экономия)
**Использование**: Табличное отображение комплектов

---

### 4. product_detail.html (Детали товара с галереей)

**Миниатюры в сетке:**
```django
<!-- Сетка с thumbnail размерами -->
<img src="{{ photo.get_thumbnail_url }}"
     alt="Фото товара"
     style="max-width: 100%; max-height: 100%; object-fit: contain;">
```

**Файл**: 438B
**Использование**: Маленькие превью для клика

---

**Модальное окно галереи (carousel):**
```django
<!-- В модальном окне - большие размеры 800x800 -->
<img src="{{ photo.get_large_url }}"
     class="d-block"
     alt="Фото товара"
     style="max-height: 70vh; max-width: 100%; object-fit: contain;">
```

**Файл**: 5.6K
**Использование**: Полноэкранный просмотр, хорошее качество

---

### 5. productkit_detail.html (Детали комплекта)

**Боковая панель с фото:**
```django
<!-- Средний размер для превью -->
<img src="{{ photo.get_medium_url }}"
     class="card-img-top"
     alt="{{ kit.name }}"
     style="height: 120px; object-fit: cover; cursor: pointer;">
```

**Файл**: 2.9K
**Использование**: Кликабельные превью в боку

---

**Модальное окно при клике:**
```django
<!-- Большой размер в модальном окне -->
<img src="{{ photo.get_large_url }}"
     class="img-fluid"
     style="max-height: 70vh;">
```

**Файл**: 5.6K
**Использование**: Полноэкранный просмотр одного фото

---

### 6. category_detail.html (Детали категории)

```django
<!-- Средний размер для отображения -->
<img src="{{ photo.get_medium_url }}"
     class="card-img-top"
     alt="Фото категории"
     style="height: 150px; object-fit: cover;">
```

**Файл**: 2.9K
**Использование**: Картинка категории в сетке

---

## Доступные методы

Каждая Photo-модель имеет методы для получения URL разных размеров:

```python
photo = ProductPhoto.objects.first()

# Получить URL миниатюры (150×150)
photo.get_thumbnail_url()
# → /media/products/thumbnails/image_12345.jpg (438B)

# Получить URL среднего размера (400×400)
photo.get_medium_url()
# → /media/products/medium/image_12345.jpg (2.9K)

# Получить URL большого размера (800×800)
photo.get_large_url()
# → /media/products/large/image_12345.jpg (5.6K)

# Получить URL оригинала (без изменений)
photo.get_original_url()
# → /media/products/originals/image_12345.jpg (6.1K)

# Получить все URL за раз
photo.get_all_urls()
# → {
#     'thumbnail': '/media/products/thumbnails/...',
#     'medium': '/media/products/medium/...',
#     'large': '/media/products/large/...',
#     'original': '/media/products/originals/...'
#   }
```

То же самое для ProductKitPhoto и ProductCategoryPhoto.

---

## Рекомендации по использованию

### Списки и таблицы
```django
<!-- Миниатюры для быстрой загрузки -->
{% if item.photos.all %}
  <img src="{{ item.photos.first.get_thumbnail_url }}"
       alt="{{ item.name }}"
       style="max-width: 50px; max-height: 50px;">
{% endif %}
```

**Почему**: Список может содержать 50+ товаров, миниатюры загружаются мгновенно

---

### Карточки товаров
```django
<!-- Средний размер для карточек -->
<div class="product-card">
  <img src="{{ product.photos.first.get_medium_url }}"
       alt="{{ product.name }}">
</div>
```

**Почему**: Карточка требует хорошего качества, но не нужна полная 800×800

---

### Модальные окна и галереи
```django
<!-- Большой размер для полного просмотра -->
<div class="modal-body">
  <img src="{{ photo.get_large_url }}"
       alt="{{ product.name }}"
       style="max-width: 100%; max-height: 70vh;">
</div>
```

**Почему**: Пользователь просматривает один товар, качество важнее

---

### Ссылка на оригинал
```django
<!-- Для скачивания оригинала -->
<a href="{{ photo.get_original_url }}"
   download>
  Скачать оригинал
</a>
```

**Почему**: Для печати или отправки по почте нужно максимальное качество

---

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

### Пример загрузки страницы:

**Список товаров (20 товаров)**:
- 20 × 438B = 8.76 КБ
- Время загрузки: ~100мс на медленном 3G

**VS** если бы были оригиналы:
- 20 × 6.1K = 122 КБ
- Время загрузки: ~1.2сек на медленном 3G

**Экономия: 93% трафика, 12× быстрее** ⚡

---

## Адаптивный дизайн

Система изображений работает на всех устройствах:

```django
<!-- Адаптивное отображение -->
<img src="{{ photo.get_thumbnail_url }}"
     alt="{{ product.name }}"
     class="img-fluid"
     style="max-width: 100%;">
```

- На мобильных: 50px → выглядит хорошо
- На планшетах: 50px → увеличение не требуется
- На десктопе: 50px → оптимально

Для больших экранов используются большие размеры (800×800) в модальном окне.

---

## Примеры в JavaScript

Если нужно работать с изображениями через JavaScript:

```javascript
// Получить URL через атрибут data
const largeImageUrl = document.querySelector('[data-large-url]').dataset.largeUrl;

// Или из HTML через обычный селектор
const img = document.querySelector('.product-image');
const src = img.src; // /media/products/medium/image_12345.jpg
```

---

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

### Через админку:
1. Откройте товар/комплект/категорию в админке
2. В секции "Фото товара" загрузите изображение
3. **Система автоматически создаст все 4 размера!**
4. Фото появится во всех шаблонах с правильным размером

### Через API (если нужно):
```python
from products.models import ProductPhoto
from products.utils.image_processor import ImageProcessor

photo = ProductPhoto(product=product)
photo.image = request.FILES['image']
photo.save()  # Все размеры создадутся автоматически
```

---

## Кэширование и оптимизация

### Текущая реализация:
- Каждый размер сохраняется на диск (быстро)
- URL вычисляется динамически (не нужна дополнительная БД)

### Будущие оптимизации (опционально):
- Redis кэширование URL
- WebP формат для современных браузеров
- Ленивая загрузка изображений (lazy loading)
- CDN интеграция

---

## Поиск и устранение проблем

### Изображение не загружается
1. Проверьте консоль браузера (F12 → Network)
2. Правильный ли URL? (должен быть `/media/products/...`)
3. Загруженное ли изображение в админке?

### Размер слишком мал/велик
1. Используйте правильный метод:
   - `get_thumbnail_url()` → для списков
   - `get_medium_url()` → для карточек
   - `get_large_url()` → для галерей
   - `get_original_url()` → для оригинала

### Качество плохое
- Используйте `get_large_url()` или `get_original_url()` вместо `get_thumbnail_url()`

---

## Примеры полных шаблонов

### Пример 1: Сетка товаров (Bootstrap)

```django
<div class="row row-cols-1 row-cols-md-3 g-4">
  {% for product in products %}
  <div class="col">
    <div class="card h-100">
      <!-- Миниатюра - быстро загружается -->
      {% if product.photos.first %}
        <img src="{{ product.photos.first.get_thumbnail_url }}"
             class="card-img-top"
             alt="{{ product.name }}"
             loading="lazy">
      {% endif %}

      <div class="card-body">
        <h5 class="card-title">{{ product.name }}</h5>
        <p class="card-text">{{ product.description|truncatewords:20 }}</p>
        <a href="{% url 'products:product-detail' product.pk %}"
           class="btn btn-primary">
          Открыть →
        </a>
      </div>
    </div>
  </div>
  {% endfor %}
</div>
```

### Пример 2: Галерея с модальным окном

```django
<div class="row g-2">
  {% for photo in product.photos.all %}
  <div class="col-md-3">
    <!-- Кликабельная миниатюра -->
    <div class="card"
         role="button"
         data-bs-toggle="modal"
         data-bs-target="#photoModal{{ photo.pk }}"
         style="cursor: pointer;">
      <img src="{{ photo.get_thumbnail_url }}"
           class="card-img-top"
           alt="{{ product.name }}"
           style="height: 150px; object-fit: cover;">
    </div>
  </div>

  <!-- Модальное окно с большим размером -->
  <div class="modal fade" id="photoModal{{ photo.pk }}">
    <div class="modal-dialog modal-lg modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-body">
          <img src="{{ photo.get_large_url }}"
               class="img-fluid"
               alt="{{ product.name }}">
        </div>
      </div>
    </div>
  </div>
  {% endfor %}
</div>
```

---

## Итоги

✅ **Автоматическое масштабирование** - правильный размер в правильном месте
✅ **Экономия трафика** - 90% для миниатюр
✅ **Быстрая загрузка** - миниатюры 438B
✅ **Высокое качество** - большие размеры 800×800 для просмотра
✅ **Простой API** - всего 4 метода в шаблонах
✅ **Полная автоматизация** - создание размеров при загрузке

Система готова к использованию! 🎉