octopus/myproject/docs/product_variants_guide.md

Руководство по работе с вариантами товаров

Введение

Система вариантов товаров позволяет создавать букеты с гибкими заменами компонентов. Это полезно когда один товар может быть заменен на другой похожий товар (например, роза 50см на розу 70см), и приоритет замены индивидуален для каждого букета.

Основные концепции

1. Группа вариантов (ProductVariantGroup)

Группа вариантов - это набор взаимозаменяемых товаров.

Пример:

• Группа: "Роза красная Freedom"
  • Роза Freedom 50см
  • Роза Freedom 60см
  • Роза Freedom 70см

Один товар может входить в несколько групп вариантов.

2. Позиция в букете (KitItem)

Каждая позиция в букете может быть:

• Конкретным товаром - без возможности замены
• Группой вариантов - с приоритетами замен

3. Приоритеты (KitItemPriority)

Для каждой позиции с группой вариантов можно настроить индивидуальные приоритеты:

• Меньшее число = выше приоритет
• Приоритет 0 = наивысший приоритет
• Приоритет 1 = второй по важности
• И т.д.

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

Шаг 1: Создание группы вариантов

1. Откройте Django Admin
2. Перейдите в раздел "Группы вариантов"
3. Нажмите "Добавить группу вариантов"
4. Заполните:
   • Название: например, "Роза красная Freedom"
   • Описание: опционально
5. Сохраните

Шаг 2: Добавление товаров в группу

1. Откройте нужный товар в разделе "Товары"
2. В поле "Группы вариантов" выберите созданную группу
3. Сохраните товар
4. Повторите для всех товаров, которые должны быть в этой группе

Альтернативный способ:

• Выберите несколько товаров через filter_horizontal в админке товара

Шаг 3: Создание букета с вариантами

1. Создайте новый комплект (букет) или откройте существующий

2. При добавлении позиции в букете:

   • Вариант А: Укажите конкретный товар (если замены не нужны)
   • Вариант Б: Укажите группу вариантов (если нужны замены)

   ⚠️ Важно: Нельзя указывать одновременно и товар, и группу вариантов!

3. Укажите количество

4. При необходимости добавьте примечание

5. Сохраните позицию

Шаг 4: Настройка приоритетов

Если вы выбрали группу вариантов:

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

   Роза Freedom 70см - приоритет 0 (первый выбор)
   Роза Freedom 60см - приоритет 1 (второй выбор)
   Роза Freedom 50см - приоритет 2 (третий выбор)
   

4. Сохраните

Шаг 5: Проверка доступности

Система автоматически проверяет доступность букета:

# В коде или Django shell
kit = ProductKit.objects.get(name="Ранчо Виталия")

# Проверить доступность
if kit.check_availability():
    print("Букет можно собрать!")
else:
    print("Букет недоступен")

# Рассчитать цену с учетом замен
price = kit.calculate_price_with_substitutions()
print(f"Цена: {price} руб.")

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

Пример 1: Премиум букет с розами

Задача: Создать букет "Ранчо Виталия" где нужны длинные розы, но можно заменить на средние.

Решение:

1. Создать группу "Роза красная Freedom"
2. Добавить в неё розы 50см, 60см, 70см
3. В букете создать позицию с группой вариантов
4. Настроить приоритеты:
   • Роза 70см - приоритет 0
   • Роза 60см - приоритет 1
   • Роза 50см - приоритет 2

При проверке доступности система сначала проверит наличие 70см, потом 60см, и только потом 50см.

Пример 2: Эконом букет

Задача: Создать эконом-букет где приоритет у коротких роз.

Решение:

1. Использовать ту же группу "Роза красная Freedom"
2. Создать новый букет с другими приоритетами:
   • Роза 50см - приоритет 0 (первый выбор)
   • Роза 60см - приоритет 1
   • Роза 70см - приоритет 2

Та же группа товаров, но другой порядок приоритетов!

Пример 3: Букет без замен

Задача: Создать букет где конкретные товары без замен.

Решение:

1. При создании позиции в букете указать конкретный товар
2. Оставить поле "Группа вариантов" пустым
3. Приоритеты настраивать не нужно

Пример 4: Смешанный букет

Задача: В одном букете часть позиций с заменами, часть без.

Решение:

Позиция 1: Роза Freedom (группа вариантов) - 15 шт
Позиция 2: Упаковка крафт (конкретный товар) - 1 шт
Позиция 3: Лента атласная (конкретный товар) - 2 м
Позиция 4: Эустома белая (группа вариантов) - 5 шт

Как работает система

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

Когда вызывается kit_item.get_best_available_product():

1. Система получает список доступных товаров
2. Если настроены приоритеты - сортирует по ним
3. Проходит по списку от высшего приоритета к низшему
4. Для каждого товара проверяет наличие на складе
5. Возвращает первый доступный товар

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

Когда вызывается kit.check_availability():

1. Система проходит по всем позициям букета
2. Для каждой позиции ищет доступный товар
3. Если хотя бы одна позиция недоступна - весь букет недоступен
4. Если все позиции доступны - букет можно собрать

Расчет цены

Система рассчитывает цену на основе фактически доступных товаров:

# Пример
Позиция: Роза Freedom - 15 шт
Приоритеты:
  - Роза 70см (200 руб) - нет в наличии
  - Роза 60см (150 руб) - нет в наличии
  - Роза 50см (100 руб) - есть в наличии ✓

Цена позиции: 15 × 100 = 1500 руб

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

Текущая версия использует заглушку StockManager, которая всегда возвращает True.

В будущем StockManager будет интегрирован с реальной системой складского учета:

# Будущая реализация
class StockManager:
    def check_stock(self, product, quantity):
        # Запрос к складской системе
        available = get_stock_from_warehouse(product.sku)
        return available >= quantity

API моделей

ProductVariantGroup

Методы:

• get_products_count() - количество товаров в группе

Поля:

• name - название группы
• description - описание
• products - товары в группе (M2M)

KitItem

Методы:

• get_display_name() - название для отображения
• has_priorities_set() - настроены ли приоритеты
• get_available_products() - список доступных товаров
• get_best_available_product(stock_manager) - лучший доступный товар
• clean() - валидация

Поля:

• product - конкретный товар (nullable)
• variant_group - группа вариантов (nullable)
• quantity - количество
• notes - примечание

ProductKit

Методы:

• get_total_components_count() - количество позиций
• get_components_with_variants_count() - позиций с вариантами
• check_availability(stock_manager) - проверка доступности
• calculate_price_with_substitutions(stock_manager) - расчет цены

Product

Методы:

• get_variant_groups() - все группы вариантов
• get_similar_products() - похожие товары

Поля:

• variant_groups - группы вариантов (M2M)

Советы и лучшие практики

1. Именование групп: Используйте понятные названия, например "Роза красная Freedom" вместо "Группа 1"

2. Приоритеты: Начинайте с 0 и увеличивайте по 1 для простоты

3. Проверка: Всегда проверяйте доступность букета перед оформлением заказа

4. Цены: Учитывайте, что цена может меняться в зависимости от того, какой вариант доступен

5. Несколько групп: Один товар может быть в нескольких группах - это нормально

6. Валидация: Система не даст сохранить позицию, где указаны одновременно товар И группа

Часто задаваемые вопросы

Q: Можно ли товар добавить в несколько групп вариантов? A: Да, один товар может быть в любом количестве групп.

Q: Что если не настроить приоритеты? A: Система вернет все товары из группы в произвольном порядке.

Q: Можно ли изменить приоритеты после создания букета? A: Да, приоритеты можно менять в любое время.

Q: Как система выбирает товар, если несколько имеют одинаковый приоритет? A: По ID (первый созданный).

Q: Влияет ли порядок товаров в группе на выбор? A: Нет, только приоритеты имеют значение. Если приоритеты не настроены - порядок не определен.

Устранение неполадок

Ошибка: "Нельзя указывать одновременно товар и группу вариантов"

Причина: Заполнены оба поля - product и variant_group

Решение: Очистите одно из полей. Оставьте либо товар, либо группу.

Букет показывается как недоступный, хотя товары есть

Причина: Возможно, StockManager некорректно работает

Решение: Проверьте реализацию StockManager.check_stock()

Приоритеты не работают

Причина: Приоритеты не были сохранены для позиции

Решение:

1. Откройте позицию букета
2. Убедитесь, что в разделе "Приоритеты вариантов" есть записи
3. Проверьте значения приоритетов (меньше = выше)

Дополнительная информация

Для получения помощи обратитесь к разработчикам или создайте issue в репозитории проекта.

---

Дата создания: 2025-10-21 Версия: 1.0