# Система вариантов товаров - Краткое руководство

## Что реализовано

Система позволяет создавать букеты с гибкими заменами компонентов. Каждый букет может иметь свои индивидуальные приоритеты для одной и той же группы товаров.

## Новые модели

1. **ProductVariantGroup** - группа взаимозаменяемых товаров
2. **KitItemPriority** - приоритеты товаров для конкретной позиции букета

## Изменения в существующих моделях

1. **Product** - добавлено поле `variant_groups` (M2M)
2. **KitItem** - добавлены поля `variant_group`, `notes`
3. **ProductKit** - добавлены методы проверки доступности и расчета цен

## Быстрый старт

### 1. Запуск демо

```bash
python manage.py demo_variants
```

Это создаст демонстрационные данные и покажет работу системы.

### 2. Создание группы вариантов через админку

1. Откройте `/admin/`
2. Перейдите в "Группы вариантов"
3. Создайте новую группу (например, "Роза красная Freedom")
4. Откройте товары и добавьте их в группу через поле "Группы вариантов"

### 3. Создание букета с вариантами

1. Создайте новый комплект
2. Добавьте позицию:
   - Либо укажите конкретный товар (без замен)
   - Либо укажите группу вариантов (с заменами)
3. Откройте позицию и настройте приоритеты в разделе "Приоритеты вариантов"

## API для разработчиков

### Проверка доступности букета

```python
from products.models import ProductKit
from products.utils.stock_manager import StockManager

kit = ProductKit.objects.get(name="Мой букет")
stock_manager = StockManager()

if kit.check_availability(stock_manager):
    print("Букет доступен!")
    price = kit.calculate_price_with_substitutions(stock_manager)
    print(f"Цена: {price}")
```

### Получение лучшего товара для позиции

```python
from products.models import KitItem
from products.utils.stock_manager import StockManager

kit_item = KitItem.objects.get(id=1)
stock_manager = StockManager()

best_product = kit_item.get_best_available_product(stock_manager)
if best_product:
    print(f"Используем: {best_product.name}")
```

## Файлы документации

- [product_variants_guide.md](product_variants_guide.md) - подробное руководство
- [example_usage.py](example_usage.py) - примеры кода

## Интеграция со складом

Текущая версия использует заглушку `StockManager`. Для интеграции с реальной системой складского учета:

1. Откройте `products/utils/stock_manager.py`
2. Реализуйте методы:
   - `check_stock(product, quantity)` - проверка остатков
   - `get_available_quantity(product)` - получение доступного количества
   - `reserve_stock(product, quantity, order_id)` - резервирование
   - `release_stock(product, quantity, order_id)` - освобождение

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

- ✅ Создание групп взаимозаменяемых товаров
- ✅ Один товар может быть в нескольких группах
- ✅ Индивидуальные приоритеты для каждого букета
- ✅ Проверка доступности с учетом замен
- ✅ Расчет цены с учетом фактически доступных товаров
- ✅ Валидация данных
- ✅ Django Admin интерфейс
- ✅ Документация и примеры

## Примеры использования

### Премиум букет

```
Позиция: Роза Freedom (группа вариантов) - 15 шт
Приоритеты:
  0. Роза 70см (200 руб/шт) - первый выбор
  1. Роза 60см (150 руб/шт)
  2. Роза 50см (100 руб/шт)

Цена: 15 × 200 = 3000 руб
```

### Эконом букет

```
Позиция: Роза Freedom (группа вариантов) - 15 шт
Приоритеты:
  0. Роза 50см (100 руб/шт) - первый выбор
  1. Роза 60см (150 руб/шт)
  2. Роза 70см (200 руб/шт)

Цена: 15 × 100 = 1500 руб
```

Та же группа товаров, но разные приоритеты и разная цена!

## Структура файлов

```
products/
├── models.py                          # Модели (обновлено)
├── admin.py                           # Админка (обновлено)
├── utils/
│   └── stock_manager.py              # Менеджер остатков (новый)
├── management/
│   └── commands/
│       └── demo_variants.py          # Демонстрация (новая)
└── migrations/
    └── 0004_productvariantgroup_...  # Миграция (новая)

docs/
├── README_VARIANTS.md                # Это руководство
├── product_variants_guide.md         # Подробная документация
└── example_usage.py                  # Примеры кода
```

## Поддержка

Для получения помощи:
1. Прочитайте [product_variants_guide.md](product_variants_guide.md)
2. Изучите примеры в [example_usage.py](example_usage.py)
3. Запустите `python manage.py demo_variants`
4. Обратитесь к разработчикам

---

**Версия**: 1.0
**Дата**: 2025-10-21