585 lines
20 KiB
Markdown
585 lines
20 KiB
Markdown
# Система оценки качества фотографий товаров - Полное описание
|
||
|
||
## Обзор
|
||
|
||
Реализована полнофункциональная система для оценки, отслеживания и визуализации качества фотографий товаров. Система полностью гибкая - все пороги и настройки читаются из `settings.py`, не требует редактирования кода при изменении параметров.
|
||
|
||
---
|
||
|
||
## Фаза 1: Оценка качества и хранение данных
|
||
|
||
### Концепция
|
||
|
||
Система определяет качество фото на основе **процентного соотношения минимального размера фото к максимально возможному размеру** (устанавливается в settings).
|
||
|
||
**Формула расчета:**
|
||
```
|
||
quality_percent = min(width, height) / max_dimension (из settings)
|
||
|
||
Excellent: >= 95% (>= 2052px при max 2160px)
|
||
Good: >= 70% (>= 1512px)
|
||
Acceptable: >= 40% (>= 864px)
|
||
Poor: >= 20% (>= 432px)
|
||
Very Poor: < 20% (< 432px)
|
||
```
|
||
|
||
### Конфигурация (settings.py)
|
||
|
||
```python
|
||
IMAGE_PROCESSING_CONFIG = {
|
||
'max_width': 2160,
|
||
'max_height': 2160,
|
||
'quality_threshold': 0.95, # Для excellent
|
||
# ... другие параметры
|
||
}
|
||
|
||
# Пороги качества (в процентах от max_dimension)
|
||
IMAGE_QUALITY_LEVELS = {
|
||
'excellent': 0.95, # >= 95%
|
||
'good': 0.70, # >= 70%
|
||
'acceptable': 0.40, # >= 40%
|
||
'poor': 0.20, # >= 20%
|
||
}
|
||
|
||
# Описания и визуальное оформление
|
||
IMAGE_QUALITY_LABELS = {
|
||
'excellent': {
|
||
'label': 'Отлично',
|
||
'color': 'success',
|
||
'icon': '✓',
|
||
'recommendation': 'Отличное качество, готово к выгрузке',
|
||
},
|
||
'good': {
|
||
'label': 'Хорошо',
|
||
'color': 'info',
|
||
'icon': '✓',
|
||
'recommendation': 'Хорошее качество, готово к выгрузке',
|
||
},
|
||
'acceptable': {
|
||
'label': 'Приемлемо',
|
||
'color': 'warning',
|
||
'icon': '⚠',
|
||
'recommendation': 'Приемлемое качество, рекомендуется обновить',
|
||
},
|
||
'poor': {
|
||
'label': 'Плохо',
|
||
'color': 'danger',
|
||
'icon': '✗',
|
||
'recommendation': 'Плохое качество, требует обновления',
|
||
},
|
||
'very_poor': {
|
||
'label': 'Очень плохо',
|
||
'color': 'danger',
|
||
'icon': '✗✗',
|
||
'recommendation': 'Очень плохое качество, обязательно обновить',
|
||
},
|
||
}
|
||
```
|
||
|
||
**Ключевое свойство:** Если вы измените `max_width` с 2160 на 2000, система **автоматически пересчитает** все пороги без изменения кода.
|
||
|
||
### Модели БД
|
||
|
||
#### ProductPhoto, ProductKitPhoto, ProductCategoryPhoto
|
||
|
||
Добавлены два поля:
|
||
|
||
```python
|
||
# Уровень качества (excellent/good/acceptable/poor/very_poor)
|
||
quality_level = models.CharField(
|
||
max_length=20,
|
||
choices=QUALITY_LEVEL_CHOICES,
|
||
default='acceptable',
|
||
db_index=True, # Для быстрой фильтрации
|
||
)
|
||
|
||
# Флаг требует ли обновления (poor или very_poor)
|
||
quality_warning = models.BooleanField(
|
||
default=False,
|
||
db_index=True, # Для быстрого поиска проблемных фото
|
||
)
|
||
```
|
||
|
||
### ImageProcessor
|
||
|
||
Обновлена функция `process_image()`:
|
||
|
||
```python
|
||
def process_image(self, image_file, max_size=None, quality_level=75):
|
||
"""
|
||
Возвращает теперь:
|
||
{
|
||
'path': 'products/2024/photo.jpg',
|
||
'width': 2150,
|
||
'height': 2150,
|
||
'quality_level': 'excellent',
|
||
'quality_warning': False,
|
||
}
|
||
"""
|
||
```
|
||
|
||
Автоматически вычисляет качество при обработке фото.
|
||
|
||
### Валидаторы (products/validators/image_validators.py)
|
||
|
||
```python
|
||
def get_max_dimension_from_config():
|
||
"""Читает max_width из settings динамически"""
|
||
max_width = getattr(settings, 'IMAGE_PROCESSING_CONFIG', {}).get('max_width', 2160)
|
||
return max_width
|
||
|
||
def get_image_quality_level(width, height):
|
||
"""Определяет уровень качества фото"""
|
||
min_dimension = min(width, height)
|
||
max_dimension = get_max_dimension_from_config()
|
||
quality_percent = min_dimension / max_dimension
|
||
|
||
quality_levels = getattr(settings, 'IMAGE_QUALITY_LEVELS', {...})
|
||
|
||
if quality_percent >= quality_levels.get('excellent', 0.95):
|
||
return 'excellent', False
|
||
# ... и т.д.
|
||
|
||
return 'very_poor', True # True означает quality_warning
|
||
|
||
def get_quality_info(quality_level):
|
||
"""Возвращает информацию о качестве из settings"""
|
||
return getattr(settings, 'IMAGE_QUALITY_LABELS', {}).get(quality_level, {})
|
||
```
|
||
|
||
### Migration для БД
|
||
|
||
```
|
||
myproject/products/migrations/0003_productcategoryphoto_quality_level_and_more.py
|
||
```
|
||
|
||
Добавляет поля `quality_level` и `quality_warning` ко всем трём моделям фото.
|
||
|
||
---
|
||
|
||
## Фаза 2: Интерфейс админа
|
||
|
||
### QualityLevelFilter
|
||
|
||
Кастомный фильтр Django для отображения товаров по качеству фото:
|
||
|
||
```python
|
||
class QualityLevelFilter(admin.SimpleListFilter):
|
||
title = 'Качество фото'
|
||
parameter_name = 'photo_quality'
|
||
|
||
lookups = (
|
||
('excellent', '🟢 Отлично'),
|
||
('good', '🟡 Хорошо'),
|
||
('acceptable', '🟠 Приемлемо'),
|
||
('poor', '🔴 Плохо'),
|
||
('very_poor', '🔴🔴 Очень плохо'),
|
||
('warning', '⚠️ Требует обновления'), # poor + very_poor
|
||
('no_warning', '✓ Готово к выгрузке'), # excellent + good
|
||
)
|
||
```
|
||
|
||
**Использование в админе:**
|
||
```
|
||
list_filter = (DeletedFilter, 'is_active', QualityLevelFilter, 'categories')
|
||
```
|
||
|
||
### Display Functions (admin_displays.py)
|
||
|
||
```python
|
||
def format_quality_badge(quality_level, show_icon=True):
|
||
"""HTML бейдж: <span class="badge bg-success">✓ Отлично</span>"""
|
||
|
||
def format_quality_display(quality_level, width, height, warning):
|
||
"""Полный индикатор: 🟢 Отлично (2150×2150px) или ⚠️ Требует обновления"""
|
||
|
||
def format_photo_quality_column(obj):
|
||
"""Для list_display в админе"""
|
||
first_photo = obj.photos.first()
|
||
return format_quality_display(...)
|
||
|
||
def format_photo_preview_with_quality(photo_obj):
|
||
"""Превью фото с индикатором качества"""
|
||
```
|
||
|
||
### Photo Inlines
|
||
|
||
Обновлены `ProductPhotoInline`, `ProductKitPhotoInline`, `ProductCategoryPhotoInline`:
|
||
|
||
```python
|
||
readonly_fields = (..., 'quality_display')
|
||
|
||
def quality_display(self, obj):
|
||
"""Показывает качество в inline таблице"""
|
||
if not obj.pk:
|
||
return format_html('<span style="color: #999;">Сохраните фото</span>')
|
||
|
||
return format_quality_display(
|
||
obj.quality_level,
|
||
obj.width,
|
||
obj.height,
|
||
obj.quality_warning
|
||
)
|
||
```
|
||
|
||
### Product Admin Classes
|
||
|
||
Обновлены `ProductAdmin`, `ProductCategoryAdmin`, `ProductKitAdmin`:
|
||
|
||
```python
|
||
list_display = (..., 'photo_with_quality', ...)
|
||
list_filter = (..., QualityLevelFilter, ...)
|
||
|
||
def photo_with_quality(self, obj):
|
||
"""Превью + цветной бейдж качества в списке"""
|
||
first_photo = obj.photos.first()
|
||
if not first_photo or not first_photo.image:
|
||
return format_html('<span style="color: #999;">Нет фото</span>')
|
||
|
||
# Flexbox контейнер с иконкой и фото
|
||
quality_indicator = format_quality_badge(first_photo.quality_level)
|
||
return format_html(
|
||
'<div style="display: flex; align-items: center; gap: 8px;">'
|
||
'<img src="{}" style="width: 50px; height: 50px; object-fit: cover;" />'
|
||
'{}'
|
||
'</div>',
|
||
first_photo.image.url,
|
||
quality_indicator
|
||
)
|
||
```
|
||
|
||
### Admin Actions (новые)
|
||
|
||
```python
|
||
def show_poor_quality_photos(modeladmin, request, queryset):
|
||
"""Перенаправляет на список товаров с quality_warning=True"""
|
||
return redirect(f'...?photo_quality=warning')
|
||
|
||
def show_excellent_quality_photos(modeladmin, request, queryset):
|
||
"""Перенаправляет на список с excellent/good качеством"""
|
||
return redirect(f'...?photo_quality=no_warning')
|
||
|
||
def show_all_quality_levels(modeladmin, request, queryset):
|
||
"""Показывает статистику распределения качества"""
|
||
quality_stats = queryset.filter(photos__isnull=False).values(
|
||
'photos__quality_level'
|
||
).annotate(count=Count('id', distinct=True))
|
||
```
|
||
|
||
---
|
||
|
||
## Фаза 3: Фронтенд UI
|
||
|
||
### Template Tags (products/templatetags/quality_tags.py)
|
||
|
||
```python
|
||
@register.filter
|
||
def quality_badge_mini(photo):
|
||
"""Маленький кружочек-значок в углу фото (🟢/🟡/🟠/🔴/⚠️)"""
|
||
|
||
@register.filter
|
||
def quality_badge_full(photo):
|
||
"""Полный бейдж: 🟢 Отлично (2150×2150px)"""
|
||
|
||
@register.filter
|
||
def quality_icon_only(photo):
|
||
"""Только символ для списков"""
|
||
|
||
@register.inclusion_tag('products/includes/quality_badge.html')
|
||
def quality_indicator(photo, show_size=False):
|
||
"""Включаемый тег для вывода индикатора в углу"""
|
||
# Возвращает контекст с всей информацией о качестве
|
||
```
|
||
|
||
### CSS Стили (static/css/quality_indicator.css)
|
||
|
||
```css
|
||
/* Ненавязчивое отображение */
|
||
.quality-badge-mini {
|
||
opacity: 0.8; /* Не отвлекает */
|
||
cursor: help;
|
||
}
|
||
|
||
.quality-badge-mini:hover {
|
||
opacity: 1; /* Более видимо при наведении */
|
||
}
|
||
|
||
/* Компактные размеры для списков */
|
||
.photo-list-item .quality-icon {
|
||
position: absolute;
|
||
top: -4px;
|
||
right: -4px;
|
||
width: 20px;
|
||
height: 20px;
|
||
}
|
||
|
||
/* Отзывчивость */
|
||
@media (max-width: 576px) {
|
||
.quality-indicator {
|
||
font-size: 0.8rem;
|
||
}
|
||
}
|
||
```
|
||
|
||
### Интеграция в шаблоны
|
||
|
||
#### product_detail.html
|
||
|
||
```django
|
||
{% load quality_tags %}
|
||
|
||
<!-- В сетке миниатюр: индикатор + полный бейдж -->
|
||
<div class="card photo-card-with-quality">
|
||
<div class="photo-container">
|
||
<img src="...">
|
||
{% quality_indicator photo %} <!-- В углу -->
|
||
</div>
|
||
<div class="card-body">
|
||
...
|
||
{{ photo|quality_badge_full }} <!-- Под фото -->
|
||
</div>
|
||
</div>
|
||
|
||
<!-- В модальной галерее: качество в footer -->
|
||
<div class="modal-footer">
|
||
<div id="galleryQualityStatus">
|
||
<!-- Динамически обновляется JS -->
|
||
</div>
|
||
</div>
|
||
```
|
||
|
||
**JavaScript для галереи:**
|
||
```javascript
|
||
photoCarousel.addEventListener('slid.bs.carousel', function(event) {
|
||
const photoInfo = photos[event.to];
|
||
|
||
// Обновляем статус качества при смене слайда
|
||
qualityStatusEl.innerHTML =
|
||
`<span class="badge bg-${info.color}">
|
||
${info.symbol} ${info.label} (${width}×${height}px)
|
||
</span>`;
|
||
});
|
||
```
|
||
|
||
#### product_list.html
|
||
|
||
```django
|
||
{% load quality_tags %}
|
||
|
||
<div class="photo-list-item">
|
||
<img src="...">
|
||
<span class="quality-icon">{{ photo|quality_icon_only }}</span>
|
||
</div>
|
||
```
|
||
|
||
Показывает маленький значок (🟢/🟡/🟠/🔴/⚠️) в углу миниатюры.
|
||
|
||
#### productkit_detail.html
|
||
|
||
```django
|
||
{% load quality_tags %}
|
||
|
||
<div class="photo-card-with-quality">
|
||
<div class="photo-container">
|
||
<img src="...">
|
||
{% quality_indicator photo %}
|
||
</div>
|
||
<div class="card-footer">
|
||
{{ photo|quality_badge_full }}
|
||
</div>
|
||
</div>
|
||
```
|
||
|
||
---
|
||
|
||
## Файлы проекта
|
||
|
||
### Новые файлы
|
||
|
||
| Файл | Описание |
|
||
|------|---------|
|
||
| `myproject/products/templatetags/quality_tags.py` | Template tags для отображения качества |
|
||
| `myproject/products/templates/products/includes/quality_badge.html` | Шаблон включаемого тега |
|
||
| `myproject/static/css/quality_indicator.css` | CSS стили для индикаторов |
|
||
| `myproject/products/admin_displays.py` | Вспомогательные функции для админа |
|
||
| `myproject/products/validators/image_validators.py` | Валидаторы и расчёт качества |
|
||
|
||
### Модифицированные файлы
|
||
|
||
| Файл | Изменения |
|
||
|------|-----------|
|
||
| `myproject/products/admin.py` | QualityLevelFilter, actions, photo_with_quality методы |
|
||
| `myproject/products/models/photos.py` | quality_level и quality_warning поля |
|
||
| `myproject/products/utils/image_processor.py` | Возврат quality_level и quality_warning |
|
||
| `myproject/templates/base.html` | Подключение CSS для качества |
|
||
| `myproject/products/templates/products/product_detail.html` | Индикаторы в сетке и галерее |
|
||
| `myproject/products/templates/products/product_list.html` | Иконка качества в таблице |
|
||
| `myproject/products/templates/products/productkit_detail.html` | Индикаторы для комплектов |
|
||
|
||
### Migrations
|
||
|
||
| Файл | Описание |
|
||
|------|---------|
|
||
| `myproject/products/migrations/0003_productcategoryphoto_quality_level_and_more.py` | Добавляет поля в БД |
|
||
|
||
---
|
||
|
||
## Использование
|
||
|
||
### Для администратора
|
||
|
||
1. **Фильтрация товаров в админе:**
|
||
- Перейти в Products → Products
|
||
- Открыть фильтр "Качество фото"
|
||
- Выбрать нужный уровень (Отлично, Хорошо, Требует обновления и т.д.)
|
||
|
||
2. **Использование Actions:**
|
||
- Выбрать товары → Action → "Показать товары с фото требующими обновления"
|
||
- Система автоматически применит фильтр
|
||
|
||
3. **Просмотр статистики:**
|
||
- Action → "Показать статистику качества фото"
|
||
- Увидите распределение товаров по уровням качества
|
||
|
||
### Для пользователя (фронтенд)
|
||
|
||
1. **На странице товара:**
|
||
- Миниатюры фотографий показывают маленький значок качества в углу
|
||
- Под каждой миниатюрой видно "🟢 Отлично (2150×2150px)"
|
||
- При клике на фото открывается галерея с информацией о качестве текущего фото в footer
|
||
|
||
2. **В списке товаров:**
|
||
- Рядом с иконкой фото видна маленькая цветная точка (🟢/🟡/🟠/🔴)
|
||
- При наведении показывается полное название качества
|
||
|
||
---
|
||
|
||
## Гибкость системы
|
||
|
||
### Изменение порогов качества
|
||
|
||
**В settings.py:**
|
||
```python
|
||
IMAGE_QUALITY_LEVELS = {
|
||
'excellent': 0.90, # Вместо 0.95 - чуть менее строгий
|
||
'good': 0.65, # Вместо 0.70
|
||
'acceptable': 0.40,
|
||
'poor': 0.20,
|
||
}
|
||
```
|
||
|
||
✅ **Никакого кода не нужно менять** - система автоматически пересчитает все пороги.
|
||
|
||
### Изменение максимального размера фото
|
||
|
||
**В settings.py:**
|
||
```python
|
||
IMAGE_PROCESSING_CONFIG = {
|
||
'max_width': 2000, # Вместо 2160
|
||
'max_height': 2000,
|
||
...
|
||
}
|
||
```
|
||
|
||
✅ **Все пороги автоматически пересчитаются:**
|
||
- Excellent: >= 1900px (вместо 2052px)
|
||
- Good: >= 1400px (вместо 1512px)
|
||
- И т.д.
|
||
|
||
### Добавление новых уровней качества
|
||
|
||
```python
|
||
IMAGE_QUALITY_LEVELS = {
|
||
...
|
||
'premium': 0.99, # Новый уровень!
|
||
}
|
||
|
||
IMAGE_QUALITY_LABELS = {
|
||
...
|
||
'premium': {
|
||
'label': 'Премиум',
|
||
'color': 'primary',
|
||
'icon': '⭐',
|
||
'recommendation': 'Премиум качество',
|
||
},
|
||
}
|
||
```
|
||
|
||
Система найдёт и использует новый уровень без изменений в коде.
|
||
|
||
---
|
||
|
||
## Коммиты
|
||
|
||
### Commit 1: Phase 1
|
||
```
|
||
d15e7d9 fix: Исправить подмену фотографий при загрузке
|
||
```
|
||
- Удаление старых файлов перед сохранением
|
||
- Cleanup скрипт для удаления старых файлов из media/
|
||
|
||
### Commit 2: Phase 1
|
||
```
|
||
622e17a feat: Реализовать систему оценки качества фотографий товаров
|
||
```
|
||
- Валидаторы и расчёт качества
|
||
- Поля в БД (quality_level, quality_warning)
|
||
- Integration с ImageProcessor
|
||
|
||
### Commit 3: Phase 2
|
||
```
|
||
[уже в истории]
|
||
```
|
||
- Admin interface с фильтрами
|
||
- Visual indicators в админе
|
||
- Actions для поиска товаров
|
||
|
||
### Commit 4: Phase 3
|
||
```
|
||
2d344ef feat: Фаза 3 - Добавить индикаторы качества фото на фронтенд
|
||
```
|
||
- Template tags для качества
|
||
- CSS стили для индикаторов
|
||
- Integration в product_detail, product_list, productkit_detail
|
||
|
||
---
|
||
|
||
## Тестирование
|
||
|
||
### Phase 1
|
||
|
||
1. Загрузить фото 2160×2160px → quality_level должна быть "excellent", warning=False
|
||
2. Загрузить фото 1500×1500px → "good"
|
||
3. Загрузить фото 400×400px → "poor", warning=True
|
||
4. Изменить max_width в settings на 2000
|
||
5. Перезагрузить БД → все фото пересчитаны с новыми порогами
|
||
|
||
### Phase 2
|
||
|
||
1. Перейти в Products → Products в админе
|
||
2. Применить фильтр "Требует обновления" → видны только товары с warning=True
|
||
3. Выбрать товар, кликнуть Action → "Показать статистику"
|
||
4. Убедиться что видна статистика по разным уровням качества
|
||
|
||
### Phase 3
|
||
|
||
1. Открыть страницу товара → видны индикаторы в углу миниатюр
|
||
2. Кликнуть на фото → открыть галерею → в footer видно качество текущего фото
|
||
3. Переключить слайд → качество обновляется в footer
|
||
4. Открыть список товаров → видны маленькие иконки качества рядом с фото
|
||
5. Проверить мобильный → индикаторы должны быть компактными
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
Создана **полностью гибкая и модульная система** для оценки качества фотографий:
|
||
|
||
- ✅ **100% читает из settings** - изменения без редактирования кода
|
||
- ✅ **Three-tier implementation** - Backend logic, Admin UI, Frontend display
|
||
- ✅ **Ненавязчивый дизайн** - не отвлекает от основного контента
|
||
- ✅ **Полная интеграция** - работает со всеми моделями фото
|
||
- ✅ **Производительность** - использует индексы БД для быстрой фильтрации
|
||
|
||
System is **production-ready** и готова к использованию.
|