docs(orders_loyalty): order processing in loyalty system, first draft

docs/.vitepress/config.mts

@@ -95,6 +95,7 @@ export default defineConfig({
           collapsed: true,
           items: [
             { text: 'Введение', link: '/integration/loyalty/index.md' },
+            { text: 'Жизненный цикл заказа в программе лояльности', link: '/integration/loyalty/orders_loyalty.md' },
             {
               text: 'Wallet',
               collapsed: true,

docs/integration/loyalty/orders_loyalty.md

@@ -0,0 +1,191 @@
+# Обработка заказов в системе программы лояльности
+
+Жизненный цикл заказа в системе программы лояльности определяется четырьмя API-методами:
+
+- `Estimate`
+- `Apply`
+- `Confirm`
+- `Change`
+
+Безусловно, в рамках программы лояльности предусмотренны и другие методы. Но именно эти четыре управляют бизнес-логикой применения скидок, начисления и списания бонусов - иными словами, использованием бенефитов. 
+
+При инициализации процесса обработки заказа используются следующие данные:
+
+- Объект магазина из базы данных 
+- Корзина товаров
+- Предварительно отфильтрованный список акций
+- Идентификатор клиента. В программе лояльности - это номер телефона
+- Уникальный ID заказа, без которого невозможно применение методов `Confirm`, `Cancel` или `Change`
+
+Для начала процесса обработки заказа должны соблюдаться некоторые условия:
+
+- Корзина должна содержать валидные товары, для каждого из которых должны передаваться сведения о цене, количестве и уникальный идентификатор товара (`uniqid`)
+- Уникальный идентификатор не должен дублироваться
+- Если в заказе есть указание на использование бонусов, то клиент должен быть участником программы лояльности, а сама она должна быть предварительно настроена у магазина
+
+## Ключевые методы API
+
+### Метод Estimate - расчет оплаты и начисления вознаграждений
+
+Данный метод предназначен для расчёта всех скидок и бонусов, которые будут применены к заказу. В процессе используются те же данные, что и на этапе инициализации плюс результаты проверок применённых промокодов и сертификатов. 
+
+Применение скидок, предусмотренных разными инструментами программы лояльности, производится в строго установленном порядке:
+
+1. Акции. Процентные и фиксированные скидки
+2. Реферальная скидка. Применяется только акций и только если тип вознаграждения `discount`
+3. Скидки по программе лояльности
+4. Списание бонусов (с учётом акций с расширенным списанием бонусов)
+5. Оплата сертификатами
+
+Таков приоритет механик оплаты товара. Для начисления вознаграждений всех типов также установлена очерёдность:
+
+1. Начисление бонусов
+2. Начисление вознаграждения рефереру 
+3. Выдача стикеров и промокодов 
+
+Ограничения метода прописываются в настройках инструментов программы лояльности: акциях, настройках самой программы. Или же сразу в товарном фиде при импорте. 
+
+К ограничениям относятся: возможность списать или начислить бонусы за определённый товар, минимальная сумма заказа, максимальный размер скидки, применяемый к товару. 
+
+### Метод Apply - предварительное применение скидок к заказу
+
+На этом этапе применяются данные, полученные в Estimate. Происходит списание бонусов, стикеров, отметка промокодов как использованных, применение сертификатов с созданием транзакций. 
+
+Результаты списаний сохраняются в системе программы лояльности.
+
+### Метод Confirm - подтверждение заказа
+
+Метод проводит начисление бонусов, вознаграждений рефереру и выдача наград (стикеров и промокодов). Важно отметить, что именно на данном этапе создаются и логгируются транзакции. 
+
+### Метод Change - изменения в заказе
+
+Результат использования метода зависит от обрабатываемого сценария: увеличение или уменьшение количества товаров в корзине, удаление товара, добавление нового. 
+
+Если количество товара, уже имеющегося в корзине, увеличилось - происходит пересчёт сумм без дополнительных начислений. Уменьшилось - происходит частичный возврат бонусов и сертификатов. 
+
+Удаление определённого типа товара из корзины влечёт полный возврат скидок и бонусов. 
+
+Добавление нового товара, ранее отсутствовавшего в корзине, не приводит к начислению бонусов или применению к нему скидок. 
+
+## Инструменты программы лояльности
+
+### Стикеры 
+
+Виртуальные "наклейки" для участия в акциях. Наличие определённого количества стикеров может быть условием для участия в акции. Также их можно выдавать клиентам в качестве вознаграждения за участие в акциях, тем самым побуждая к дополнительной покупательской активности. 
+
+#### Что происходит во время применения методов программы лояльности
+
+1. На этапе Estimate происходит учёт имеющихся у участника программы лояльности стикеров
+2. Apply - списание использованных стикеров
+3. Confirm - начисление стикеров-наград
+
+При отмене заказа (метод Cancel) происходит восстановление потраченных стикеров. 
+
+### Акции
+
+Этот инструмент программы лояльности позволяет гибко управлять начислять вознаграждения в зависимости от поведения покупателя и предварительно настроенных условий. 
+
+Акция может требовать наличия определённого количества стикеров у покупателя или же промокода. Немалую роль имеют и ограничения: например, на количество товаров, участвующих в акции. 
+
+### **Реферальная программа**
+
+Механика, призванная мотивировать существующих клиентов привлекать новых покупателей через рекомендации. Она работает по принципу "пригласи друга - получи награду".
+
+В рамках этой программы существует две роли:
+
+- **Реферер (партнер)** - действующий клиент, который приглашает нового покупателя, используя свой уникальный промокод
+- **Реферал (приглашённый)** - новый покупатель, который совершает заказ с промокодом реферера
+
+Система предусматривает вознаграждения для обеих сторон, типы которых настраиваются индивидуально для каждой программы:
+
+#### **Для реферала (нового покупателя):**
+1. **Скидка** - процентная или фиксированная, применяется на этапе Estimate
+2. **Бонусы** - процентные или фиксированные, начисляются на этапе Confirm
+
+#### **Для реферера (пригласившего):**
+1. **Бонусы** - процентные от суммы заказа реферала или фиксированная сумма, начисляются на этапе Confirm
+
+#### **Ограничения программы:**
+- **Минимальная сумма заказа** - реферальная программа применяется только к заказам, превышающим установленный порог
+- **Тип использования** - программа может действовать только на первый заказ приглашённого (`first_order`) или на все заказы
+- **Запрет самоприглашения** - клиент не может использовать собственный реферальный промокод
+- **Активность программы** - реферальная программа должна быть активна на момент заказа
+
+#### **Взаимодействие с другими инструментами:**
+- **С промокодами** - реферальные промокоды являются кодами партнеров и проверяются на уникальность использования
+- **С программой лояльности** - вознаграждение рефералу начисляется только если он является участником программы лояльности
+- **С акциями** - реферальная программа имеет более низкий приоритет, чем акции со скидками
+
+### **Сертификаты**
+
+Цифровые подарочные карты с определённым номиналом, которые могут быть использованы для частичной или полной оплаты заказа. Сертификаты объединяются в пулы - группы с общими правилами использования.
+
+#### **Типы сертификатов:**
+
+1. **Подарочные (Gift certificates)** - предназначены для оплаты 100% стоимости товара (`payable_order_share = 100`)
+2. **Промо (Promo certificates)** - покрывают только часть стоимости, например 50% или 70% (`payable_order_share < 100`)
+
+#### **Ограничения применения:**
+
+- **Активность пула** - пул сертификатов должен быть активен
+- **Минимальная сумма заказа** - заказ должен превышать установленное значение
+- **Разрешенные каналы** - проверка стрима и локации, с которых пришёл заказ
+- **Лимит на промо-сертификаты** - в одном заказе можно использовать только один промо-сертификат (с долей оплаты менее 100%)
+- **Проверка владельца** - для персональных сертификатов осуществляется проверка соответствия владельца
+
+#### **Что происходит на разных этапах:**
+
+1. **Estimate** - проверяется валидность сертификатов и рассчитывается сумма, которую они могут оплатить
+2. **Apply** - сертификаты резервируются, создаются транзакции списания
+3. **Confirm** - списание подтверждается, обновляется баланс сертификатов
+4. **Cancel/Change** - сертификаты возвращаются, баланс восстанавливается
+
+#### **Сортировка при применении:**
+Система автоматически сортирует сертификаты в оптимальном порядке:
+1. Сначала **промо-сертификаты** (с частичной оплатой)
+2. Затем **подарочные сертификаты** (со 100% оплатой)
+3. Внутри каждой группы - по дате истечения (скоро истекающие первыми)
+
+#### **Взаимодействие с другими инструментами:**
+- **С бонусами** - сертификаты применяются ПОСЛЕ списания бонусов
+- **Со скидками** - сертификаты работают с остаточной стоимостью после применения всех скидок
+- **С программой лояльности** - промо-сертификаты не могут быть использованы одновременно с промокодами от реферальной программы
+
+### **Промокоды**
+
+Специальные коды, которые активируют дополнительные бенефиты при оформлении заказа. В системе существует несколько типов промокодов, каждый со своей логикой применения.
+
+#### **Типы промокодов:**
+
+1. **Реферальные** - уникальные коды партнеров, привязанные к конкретному клиенту-рефереру
+2. **Статические** - общие коды для акций, могут использоваться многократно (в рамках установленных лимитов)
+3. **Уникальные** - одноразовые коды, выдаваемые как награда за участие в акциях
+
+#### **Проверки при применении:**
+
+- **Уникальность использования** - для статических промокодов проверяется, использовал ли клиент данный код ранее
+- **Валидность реферального кода** - проверка, что промокод принадлежит действующему партнеру
+- **Запрет самоприглашения** - клиент не может использовать свой собственный реферальный код
+- **Соответствие условиям акции** - проверка минимальной суммы заказа и других ограничений
+
+#### **Что происходит на разных этапах:**
+
+1. **Estimate** - проверяется валидность промокодов, определяется их тип (реферальный или статический)
+2. **Apply** - промокоды отмечаются как использованные в данном заказе
+3. **Confirm** - для акций с выдачей промокодов формируются уникальные коды и связываются с клиентом
+
+#### **Взаимодействие с другими инструментами:**
+
+- **С акциями** - промокоды могут быть обязательным условием для активации акции
+- **С реферальной программой** - промокоды являются основным механизмом идентификации реферера
+- **С программой лояльности** - промокоды проверяются на конфликты с другими механиками программы лояльности
+
+#### **Особенности работы с реферальными промокодами:**
+Если в заказе используется реферальный промокод, система автоматически:
+1. Находит реферера по коду
+2. Проверяет активность реферальной программы
+3. Определяет тип вознаграждения (скидка или бонусы)
+4. Применяет соответствующее вознаграждение согласно приоритету применения механик
+
+
+