docs: Add comprehensive frontend images guide

- Complete guide for using responsive image sizes in templates
- Examples for all template types (lists, galleries, modals)
- Performance metrics and optimization tips
- Size recommendations for each context
- Troubleshooting and best practices

FRONTEND_IMAGES_GUIDE.md

@@ -0,0 +1,397 @@
+# Руководство по использованию изображений на фронтенде
+
+## Обзор
+
+Система автоматически служит изображения разных размеров в зависимости от контекста:
+
+- **Списки товаров**: миниатюры (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 метода в шаблонах
+✅ **Полная автоматизация** - создание размеров при загрузке
+
+Система готова к использованию! 🎉