From 39a385bc722f29f8e63ece78ca87e34b740ab4bf Mon Sep 17 00:00:00 2001 From: Aleksandr Zavadkin Date: Mon, 8 Jun 2026 17:39:16 +0300 Subject: [PATCH 1/3] docs(documentation-unified): personal certificates Signed-off-by: Aleksandr Zavadkin --- docs/.vitepress/config.mts | 7 ++ .../certificates-by-phone-number.md | 88 +++++++++++++++++++ 2 files changed, 95 insertions(+) create mode 100644 docs/guides/loyalty/certificates/certificates-by-phone-number.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index a879a5c..63fa19a 100644 --- a/docs/.vitepress/config.mts +++ b/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' }, ] }, diff --git a/docs/guides/loyalty/certificates/certificates-by-phone-number.md b/docs/guides/loyalty/certificates/certificates-by-phone-number.md new file mode 100644 index 0000000..cb5c85d --- /dev/null +++ b/docs/guides/loyalty/certificates/certificates-by-phone-number.md @@ -0,0 +1,88 @@ +# Использование персональных сертификатов + +
+ + В двух словах о том, как это работает + +В настройках вы разрешаете использовать персональные сертификаты на этапе работы метода `checkout/estimate`. + +То есть, когда платформа будет считать все доступные к применению скидки, бонусы и сертификаты, персональные в этом подсчёте тоже будут учтены. + +При наличии других доступных сертификатов, алгоритм выберет наиболее приоритетный. Не обязательно будет использован именно персональный сертификат. + +Если других сертификатов нет, но использование персональных сертификатов не было разрешено - они не будут учитываться в подсчёте оплаты за товары в корзине. + +
+ +// TODO иллюстрация и описание по настройкам + +Выбор соответствующей настройки в меню активирует флаг `use_personal_certificates`. + +При активации флага, на этапе работы метода `checkout/estimate`, когда рассчитывается сумма к оплате для корзины, к учёту применимых акций, бонусов и сертификатов, добавляются персональные сертификаты, доступные пользователю. + +Доступные сертификаты определяются с помощью идентификатора. В рамках программы лояльности это номер телефона. + +Технически процесс выглядит так: + +1. Выполняется проверка активности флага `use_personal_certificates` и наличия идентификатора +2. После успешного прохождения, система находит все сертификаты доступные пользователю, включая персональные +3. Сертификаты применяются к корзине + +::: tip Для справки + +Акции обрабатываются отдельным процессором, поэтому сертификаты, и персональные сертификаты в частности, не влияют на выбор акций. И наоборот. + +::: + +## Типы сертификатов и ограничения + +Метод `checkout/estimate` работает со всеми сертификатами, доступными пользователю. + +Это подразумевает наличие алгоритмов выбора нужного и сопутствующие ограничения. Три типа сертификатов: + +1. Обычный +2. Промо +3. Персональный + +::: warning Ключевое ограничение + +К корзине может быть применён только один промо-сертификат + +::: + +Обычные сертификаты могут применяться сразу по несколько штук за раз. Но есть ограничения: + +1. Ни при каких условиях нельзя полностью оплатить товар сертификатом полностью. Даже если настройки на стороне магазина предусматривают максимальное долю оплаты сертификатом, покупателю в любом случае нужно будет заплатить хотя бы один рубль +2. Доли оплаты сертификатами устанавливаемые на стороне магазина. Какая часть стоимости товара может быть оплачена сертификатами зависит от заданных параметров в настройках программы лояльности + +// TODO Иллюстрация настроек в админке магазина плюс описание + +Промо сертификаты нельзя применить больше одного раза к конкретной корзине. + +Персональные сертификаты работают при успешной идентификации покупателя по номеру телефона. + +Номер телефона - главный идентификатор в системе программы лояльности. + +## Алгоритм выбора сертификата + +Как уже было сказано, метод `checkout/estimate` работает сразу со всеми доступными сертификатами. + +Решение какой именно должен быть применён принимается путём многоуровневой сортировки: + +1. Доля оплаты с помощью сертификата. Чем меньший процент стоимости товара можно оплатить с помощью сертификата, тем выше его приоритет на применение к корзине +2. Срок годности. Чем ближе сертификат к сроку истечения годности, тем выше его приоритет // TODO - подумать над формулировкой срока годности +3. Дата активации. Чем раньше активирован, тем желательнее его использовать +4. Остаток на балансе. Чем меньше оставшаяся сумма, тем вероятнее будет использован сертификат +5. ID (сортировка по возрастанию) + +Таким образом, логика алгоритма заключается в сведении к минимуму сгорания неиспользованных сертификатов и оставшихся на них средств. + +## Жизненный цикл сертификата + +| Этап | Метод | Действие | Статус сертификата | +|---------------|---------------------|---------------------------------------------------------------------------------------|--------------------------------------------------------------------| +| Расчет | `checkout/estimate` | Проверка, какие сертификаты можно применить | `active` (не меняется) | +| Применение | `checkout/apply` | Создание транзакций списания (`LoyaltyCertificateTransaction`) | `active` → `finished` (баланс меняется) | +| Подтверждение | `checkout/confirm` | Подтверждение (статус сертификата не меняется) | `finished` (не меняется) | +| Отмена | `checkout/cancel` | Возврат баланса, создание возвратных транзакций | `finished` → `active` (баланс восстанавливается) | +| Изменение | `checkout/change` | Изменение суммы списания ( в связи с изменением состава/количества товаров в корзине) | `finished` → `active` (частично, если баланс не обнулен полностью) | From 0c4537605d288b559a934e691fb0ceea08f18f19 Mon Sep 17 00:00:00 2001 From: Aleksandr Zavadkin Date: Mon, 8 Jun 2026 17:45:51 +0300 Subject: [PATCH 2/3] docs(certificates-by-phone-number): header note change, formatting Signed-off-by: Aleksandr Zavadkin --- .../loyalty/certificates/certificates-by-phone-number.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/guides/loyalty/certificates/certificates-by-phone-number.md b/docs/guides/loyalty/certificates/certificates-by-phone-number.md index cb5c85d..0ba6338 100644 --- a/docs/guides/loyalty/certificates/certificates-by-phone-number.md +++ b/docs/guides/loyalty/certificates/certificates-by-phone-number.md @@ -1,9 +1,8 @@ # Использование персональных сертификатов +::: tip Коротко о том, как это работает
- В двух словах о том, как это работает - В настройках вы разрешаете использовать персональные сертификаты на этапе работы метода `checkout/estimate`. То есть, когда платформа будет считать все доступные к применению скидки, бонусы и сертификаты, персональные в этом подсчёте тоже будут учтены. @@ -13,7 +12,7 @@ Если других сертификатов нет, но использование персональных сертификатов не было разрешено - они не будут учитываться в подсчёте оплаты за товары в корзине.
- +::: // TODO иллюстрация и описание по настройкам Выбор соответствующей настройки в меню активирует флаг `use_personal_certificates`. @@ -82,7 +81,7 @@ | Этап | Метод | Действие | Статус сертификата | |---------------|---------------------|---------------------------------------------------------------------------------------|--------------------------------------------------------------------| | Расчет | `checkout/estimate` | Проверка, какие сертификаты можно применить | `active` (не меняется) | -| Применение | `checkout/apply` | Создание транзакций списания (`LoyaltyCertificateTransaction`) | `active` → `finished` (баланс меняется) | +| Применение | `checkout/apply` | Создание транзакций списания | `active` → `finished` (баланс меняется) | | Подтверждение | `checkout/confirm` | Подтверждение (статус сертификата не меняется) | `finished` (не меняется) | | Отмена | `checkout/cancel` | Возврат баланса, создание возвратных транзакций | `finished` → `active` (баланс восстанавливается) | | Изменение | `checkout/change` | Изменение суммы списания ( в связи с изменением состава/количества товаров в корзине) | `finished` → `active` (частично, если баланс не обнулен полностью) | From 2ecb077c1550039fb06a3a11fa6f7a4454c6a59f Mon Sep 17 00:00:00 2001 From: Aleksandr Zavadkin Date: Wed, 10 Jun 2026 17:39:51 +0300 Subject: [PATCH 3/3] docs(certificates-by-phone-number): style improved, simplified Signed-off-by: Aleksandr Zavadkin --- .../certificates-by-phone-number.md | 34 ++++++++----------- 1 file changed, 14 insertions(+), 20 deletions(-) diff --git a/docs/guides/loyalty/certificates/certificates-by-phone-number.md b/docs/guides/loyalty/certificates/certificates-by-phone-number.md index 0ba6338..196773d 100644 --- a/docs/guides/loyalty/certificates/certificates-by-phone-number.md +++ b/docs/guides/loyalty/certificates/certificates-by-phone-number.md @@ -3,33 +3,29 @@ ::: tip Коротко о том, как это работает
-В настройках вы разрешаете использовать персональные сертификаты на этапе работы метода `checkout/estimate`. - -То есть, когда платформа будет считать все доступные к применению скидки, бонусы и сертификаты, персональные в этом подсчёте тоже будут учтены. +После включения настройки персональные сертификаты будут учитываться методом `checkout/estimate`. При наличии других доступных сертификатов, алгоритм выберет наиболее приоритетный. Не обязательно будет использован именно персональный сертификат. -Если других сертификатов нет, но использование персональных сертификатов не было разрешено - они не будут учитываться в подсчёте оплаты за товары в корзине. -
::: // TODO иллюстрация и описание по настройкам Выбор соответствующей настройки в меню активирует флаг `use_personal_certificates`. -При активации флага, на этапе работы метода `checkout/estimate`, когда рассчитывается сумма к оплате для корзины, к учёту применимых акций, бонусов и сертификатов, добавляются персональные сертификаты, доступные пользователю. +Если включён этот флаг, метод `checkout/estimate` учитывает персональные сертификаты при расчёте итоговой суммы заказа. Доступные сертификаты определяются с помощью идентификатора. В рамках программы лояльности это номер телефона. -Технически процесс выглядит так: +Процесс выглядит так: 1. Выполняется проверка активности флага `use_personal_certificates` и наличия идентификатора -2. После успешного прохождения, система находит все сертификаты доступные пользователю, включая персональные -3. Сертификаты применяются к корзине +2. Cистема находит все сертификаты, доступные пользователю, включая персональные +3. Система рассчитывает возможность применения найденных сертификатов к корзине. ::: tip Для справки -Акции обрабатываются отдельным процессором, поэтому сертификаты, и персональные сертификаты в частности, не влияют на выбор акций. И наоборот. +Акции обрабатываются отдельным процессором. Поэтому сертификаты, включая персональные, не влияют на выбор акций. И наоборот. ::: @@ -37,7 +33,7 @@ Метод `checkout/estimate` работает со всеми сертификатами, доступными пользователю. -Это подразумевает наличие алгоритмов выбора нужного и сопутствующие ограничения. Три типа сертификатов: +Из-за этого для сертификатов действуют правила выбора и ограничения применения. Три типа сертификатов: 1. Обычный 2. Промо @@ -51,30 +47,28 @@ Обычные сертификаты могут применяться сразу по несколько штук за раз. Но есть ограничения: -1. Ни при каких условиях нельзя полностью оплатить товар сертификатом полностью. Даже если настройки на стороне магазина предусматривают максимальное долю оплаты сертификатом, покупателю в любом случае нужно будет заплатить хотя бы один рубль -2. Доли оплаты сертификатами устанавливаемые на стороне магазина. Какая часть стоимости товара может быть оплачена сертификатами зависит от заданных параметров в настройках программы лояльности +1. Стоимость товара не может быть полностью оплачена сертификатом. Даже если настройки на стороне магазина предусматривают максимальную долю оплаты сертификатом, покупателю в любом случае нужно будет заплатить хотя бы один рубль // TODO проверить +2. Максимальная доля оплаты сертификатами настраивается на стороне магазина. Допустимая доля оплаты сертификатами определяется настройками // TODO Иллюстрация настроек в админке магазина плюс описание Промо сертификаты нельзя применить больше одного раза к конкретной корзине. -Персональные сертификаты работают при успешной идентификации покупателя по номеру телефона. - -Номер телефона - главный идентификатор в системе программы лояльности. +Персональные сертификаты учитываются только после идентификации покупателя по номеру телефона. ## Алгоритм выбора сертификата -Как уже было сказано, метод `checkout/estimate` работает сразу со всеми доступными сертификатами. +Метод `checkout/estimate` работает сразу со всеми доступными сертификатами. -Решение какой именно должен быть применён принимается путём многоуровневой сортировки: +Система выбирает сертификат с помощью многоуровневой сортировки: 1. Доля оплаты с помощью сертификата. Чем меньший процент стоимости товара можно оплатить с помощью сертификата, тем выше его приоритет на применение к корзине 2. Срок годности. Чем ближе сертификат к сроку истечения годности, тем выше его приоритет // TODO - подумать над формулировкой срока годности -3. Дата активации. Чем раньше активирован, тем желательнее его использовать +3. Дата активации. Приоритет получают сертификаты с более ранней датой активации. 4. Остаток на балансе. Чем меньше оставшаяся сумма, тем вероятнее будет использован сертификат 5. ID (сортировка по возрастанию) -Таким образом, логика алгоритма заключается в сведении к минимуму сгорания неиспользованных сертификатов и оставшихся на них средств. +Алгоритм направлен на то, чтобы минимизировать риск истечения сертификатов и потери оставшихся на них средств. ## Жизненный цикл сертификата