Feat/dev 3958 certificate by phone number

docs/.vitepress/config.mts

@@ -45,6 +45,13 @@ export default defineConfig({
                                 { text:'Арбитраж',link: '/guides/loyalty/promotions/arbitr.md' }
                             ]
                         },
+                        {
+                            text: 'Сертификаты',
+                            collapsed: true,
+                            items: [
+                                { text:'Использование персональных сертификатов',link: '/guides/loyalty/certificates/certificates-by-phone-number.md' }
+                            ]
+                        },
                         { text: 'Как работает списание бонусов', link: '/guides/loyalty/bonuses-mechanics.md' },
                     ]
                 },

docs/guides/loyalty/certificates/certificates-by-phone-number.md

@@ -0,0 +1,81 @@
+# Использование персональных сертификатов
+
+::: tip Коротко о том, как это работает
+<details>
+
+После включения настройки персональные сертификаты будут учитываться методом `checkout/estimate`.
+
+При наличии других доступных сертификатов, алгоритм выберет наиболее приоритетный. Не обязательно будет использован именно персональный сертификат.
+
+</details>
+:::
+// TODO иллюстрация и описание по настройкам
+
+Выбор соответствующей настройки в меню активирует флаг `use_personal_certificates`. 
+
+Если включён этот флаг, метод `checkout/estimate` учитывает персональные сертификаты при расчёте итоговой суммы заказа.
+
+Доступные сертификаты определяются с помощью идентификатора. В рамках программы лояльности это номер телефона. 
+
+Процесс выглядит так:
+
+1. Выполняется проверка активности флага `use_personal_certificates` и наличия идентификатора
+2. Cистема находит все сертификаты, доступные пользователю, включая персональные
+3. Система рассчитывает возможность применения найденных сертификатов к корзине.
+
+::: tip Для справки
+
+Акции обрабатываются отдельным процессором. Поэтому сертификаты, включая персональные, не влияют на выбор акций. И наоборот.
+
+:::
+
+## Типы сертификатов и ограничения
+
+Метод  `checkout/estimate` работает со всеми сертификатами, доступными пользователю. 
+
+Из-за этого для сертификатов действуют правила выбора и ограничения применения. Три типа сертификатов:
+
+1. Обычный
+2. Промо
+3. Персональный
+
+::: warning Ключевое ограничение
+
+К корзине может быть применён только один промо-сертификат
+
+:::
+
+Обычные сертификаты могут применяться сразу по несколько штук за раз. Но есть ограничения:
+
+1. Стоимость товара не может быть полностью оплачена сертификатом. Даже если настройки на стороне магазина предусматривают максимальную долю оплаты сертификатом, покупателю в любом случае нужно будет заплатить хотя бы один рубль // TODO проверить
+2. Максимальная доля оплаты сертификатами настраивается на стороне магазина. Допустимая доля оплаты сертификатами определяется настройками
+
+// TODO Иллюстрация настроек в админке магазина плюс описание
+
+Промо сертификаты нельзя применить больше одного раза к конкретной корзине. 
+
+Персональные сертификаты учитываются только после идентификации покупателя по номеру телефона.
+
+## Алгоритм выбора сертификата
+
+Метод `checkout/estimate` работает сразу со всеми доступными сертификатами.
+
+Система выбирает сертификат с помощью многоуровневой сортировки:
+
+1. Доля оплаты с помощью сертификата. Чем меньший процент стоимости товара можно оплатить с помощью сертификата, тем выше его приоритет на применение к корзине
+2. Срок годности. Чем ближе сертификат к сроку истечения годности, тем выше его приоритет // TODO - подумать над формулировкой срока годности
+3. Дата активации. Приоритет получают сертификаты с более ранней датой активации.
+4. Остаток на балансе. Чем меньше оставшаяся сумма, тем вероятнее будет использован сертификат
+5. ID (сортировка по возрастанию)
+
+Алгоритм направлен на то, чтобы минимизировать риск истечения сертификатов и потери оставшихся на них средств.
+
+## Жизненный цикл сертификата
+
+| Этап          | Метод               | Действие                                                                              | Статус сертификата                                                 |
+|---------------|---------------------|---------------------------------------------------------------------------------------|--------------------------------------------------------------------|
+| Расчет        | `checkout/estimate` | Проверка, какие сертификаты можно применить                                           | `active` (не меняется)                                             |
+| Применение    | `checkout/apply`    | Создание транзакций списания                                                          | `active` → `finished` (баланс меняется)                            |
+| Подтверждение | `checkout/confirm`  | Подтверждение (статус сертификата не меняется)                                        | `finished` (не меняется)                                           |
+| Отмена        | `checkout/cancel`   | Возврат баланса, создание возвратных транзакций                                       | `finished` → `active` (баланс восстанавливается)                   |
+| Изменение     | `checkout/change`   | Изменение суммы списания ( в связи с изменением состава/количества товаров в корзине) | `finished` → `active` (частично, если баланс не обнулен полностью) |