# 🤖 Алгоритмы рекомендаций

Алгоритмы формируют основу рекомендательных стратегий в Gravity Field. Каждый алгоритм отвечает за логику формирования товарной выдачи на основе поведения пользователя, контекста страницы и продуктового фида.

---

## Персональные алгоритмы

Эти алгоритмы строят рекомендации на основе индивидуального поведения пользователя.

### User Affinity

Рекомендует товары на основе **профиля интересов (аффинити)** пользователя, который строится в реальном времени. Алгоритм анализирует атрибуты товаров (категория, бренд, цвет и т.д.), с которыми взаимодействовал пользователь.

**Подходит для:** Всех страниц, особенно для главной и страниц категорий.  
**Обновление:** В реальном времени.  
**Fallback-цепочка:** `Viewed with Recently Viewed` → `Popularity`.

[Подробнее об аффинити-профиле →](./affinity_profile.md)

### Recently Viewed

Показывает **последние просмотренные** пользователем товары в порядке от новых к старым.

- **Ограничение:** Хранит до 100 последних товаров.
- **Особенность:** Не проверяет наличие товара (`in_stock`), поэтому рекомендуется использовать с правилом "в наличии".

**Подходит для:** Всех страниц, особенно для блоков "Вы недавно смотрели".  
**Обновление:** В реальном времени.  
**Fallback:** Не применяется.

### Recently Purchased

Показывает **последние купленные** пользователем товары.

- **Ограничение:** Хранит до 500 последних товаров.
- **Особенность:** Не зависит от фида и не проверяет наличие товара.

**Подходит для:** Страниц благодарности за заказ, личного кабинета.  
**Обновление:** В реальном времени.  
**Fallback:** Не применяется.

### Last Purchase

Показывает товары **из последней покупки** пользователя в том порядке, в котором они были в заказе.

- **Особенность:** Учитывает только один, самый последний заказ.

**Подходит для:** Сценариев "Спасибо за заказ", повторных продаж.  
**Обновление:** В реальном времени.  
**Fallback:** Не применяется.

---

## Контекстные алгоритмы (Item-to-Item)

Эти алгоритмы строят рекомендации на основе связей между товарами.

### Similarity

Рекомендует товары, **похожие** на текущий просматриваемый товар.

- **Логика:** Анализирует атрибуты товаров из фида: `categories`, `keywords`, `price`, `name`. Чем реже совпавший атрибут, тем выше его вес.
- **Как формируется выдача:** Сначала алгоритм ранжирует группы товаров (`group_id`) по похожести, а затем runtime разворачивает каждую группу в конкретные SKU для показа.
- **Варианты того же товара:** Для текущей группы товара (`group_id` просматриваемого товара) система может показать несколько sibling SKU, если для секции разрешена внутренняя настройка `max_same_group_items`. Для остальных групп обычно показывается не более одного SKU.
- **Пример:** Если кандидаты содержат группы `G0`, `G1`, `G2`, `G3`, `G4`, где `G0` — группа текущего товара, и `max_same_group_items = 3`, итоговая выдача может содержать до 3 SKU из `G0` и по 1 SKU из остальных групп.
- **Важно:** Порядок групп в выдаче определяется их релевантностью, но порядок SKU внутри одной и той же группы не является жёстко детерминированным.
- **Изменение настройки:** `max_same_group_items` — внутренняя конфигурация Gravity Field. Изменить её может только аккаунт-менеджер.
- **Требование:** Качественный и подробно заполненный продуктовый фид.

**Подходит для:** Страниц товаров, корзины.  
**Обновление:** Ежедневно.  
**Fallback-цепочка:** `Viewed Together` → `Popularity`.

### Viewed Together

Рекомендует товары, которые **другие пользователи часто просматривали** вместе с текущим товаром в рамках одной сессии.

- **Логика:** Анализирует совместные просмотры. Популярные товары, которые смотрят со всем подряд, получают меньший вес.

**Подходит для:** Страниц товаров, корзины.  
**Обновление:** Ежедневно.  
**Fallback-цепочка:** `Similarity` → `Popularity`.

### Purchased Together

Рекомендует товары, которые **другие пользователи часто покупали вместе** с текущим товаром в рамках одной транзакции.

- **Логика:** Учитывает силу связи между товарами в заказах. Недавние покупки имеют больший вес.

**Подходит для:** Страниц товаров, корзины, страниц благодарности за заказ.  
**Обновление:** Ежедневно.  
**Fallback-цепочка:** `Viewed Together` → `Similarity` → `Popularity`.

---

## Гибридные алгоритмы

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

### Viewed with Recently Viewed

Показывает товары, которые **другие пользователи просматривали** вместе с товарами, которые **текущий пользователь недавно смотрел**.

- **Логика:** Берет до 50 последних просмотренных товаров пользователя и находит для них популярные сопутствующие товары.

**Подходит для:** Главной страницы, страниц категорий.  
**Обновление:** Ежедневно.  
**Fallback-цепочка:** `Viewed Together` → `Popularity`.

### Purchased with Recently Purchased

Аналогично предыдущему, но на основе **покупок**. Показывает, что обычно покупают вместе с тем, что текущий пользователь купил ранее.

- **Логика:** Берет до 50 последних купленных товаров и находит для них сопутствующие товары из покупок других пользователей.

**Подходит для:** Главной страницы, личного кабинета.  
**Обновление:** Ежедневно.  
**Fallback-цепочка:** `Purchased Together` → `Similarity` → `Popularity`.

---

## Алгоритмы на основе популярности

### Popularity

Ранжирует товары по **взвешенной популярности**, учитывая просмотры, добавления в корзину и покупки за последние 180 дней.

- **Формула весов:** Покупка > Добавление в корзину > Просмотр.
- **Коэффициент давности:** Недавние события (до 2 дней) имеют больший вес.

**Подходит для:** Всех страниц, особенно для новых пользователей.  
**Обновление:** Ежедневно.  
**Fallback:** Не применяется.

---

## 🔁 Fallback логика

Если основной алгоритм не дал нужного количества товаров — включается fallback по заранее заданной логике:

| Основной | Fallback-цепочка |
|----------|------------------|
| Affinity | → Viewed with Recently Viewed → Popularity |
| Similarity | → Viewed Together → Popularity |
| Purchased Together | → Viewed Together → Similarity → Popularity |
| Viewed Together | → Similarity → Popularity |
| Viewed with Recently Viewed | → Viewed Together → Popularity |
| Purchased with Recently Purchased | → Purchased Together → Similarity → Popularity |
| Last Purchase | ❌ fallback не применяется |

> ❗ Фильтры и ослабления, заданные в стратегии, **переносятся** на fallback-алгоритмы.

---

## 📌 Особенности

- Для стратегий, где передаётся контекст корзины (`CART`), товары из корзины исключаются.
- Для Recently purchased и Recently viewed выдаются товары **вне зависимости от наличия**. Остальные алгоритмы используют `in_stock = true`.
- Алгоритмы работают по `group_id`, чтобы исключить дубли (одинаковые товары с разными SKU).
- При использовании нескольких виджетов на одной странице — выдача **дедуплируется**.
- Для запуска некоторых алгоритмов (Affinity, Purchased Together) требуется накопление данных (от 30 дней).