Плагины процессинга лояльности

Руководство для разработчиков и интеграторов: возможности расширения расчёта кэшбэка, подключение плагинов через API и проверка результата.

Плагины расширяют расчёт кэшбэка модуля «Процессинг лояльности». В документации модуля описаны условия программы, категории, уровни клиентов и учёт бонусов.

Для чего нужны плагины

Плагины позволяют добавлять правила расчёта кэшбэка в accelera-loyalty-processing. Расширение подключается к определённому этапу обработки транзакции и получает данные этого этапа. Например, перед расчётом категорийного кэшбэка плагин может округлить расчётную базу или изменить ставку.

Механизм поддерживает изменение кода и конфигурации без перезапуска сервиса. Для каждого плагина задаются точка подключения, приоритет выполнения и состояние: включён или выключен. Управление выполняется через HTTP API процессинга.

Типовые задачи:

• изменить базу или ставку расчёта кэшбэка;
• задать исключения и дополнительные правила для отдельных уровней клиентов;
• изменить рассчитанный партнёрский или категорийный кэшбэк перед выбором итогового результата;
• изменить сумму и тип бонусов перед начислением;
• добавить логирование после завершения обработки.

Возможности конкретного расширения определяются доступной точкой подключения и её данными. Описание относится к процессингу карточного кэшбэка; оно не устанавливает такой же механизм расширения для loyalty-api, Flow или других модулей Accelera.

Как работает плагин

Плагин — Lua-функция с параметрами context и config:

function(context, config)
    -- Изменения данных выполняются в context.
    return context
end

context содержит данные текущего этапа обработки. config содержит настройки плагина и используется для чтения. Функция возвращает контекст, который продолжает участвовать в обработке транзакции. Набор полей зависит от точки подключения.

Согласно исходной документации, при возврате nil используется исходный контекст, а ошибка плагина записывается в лог и не прерывает транзакцию. Это означает, что само завершение транзакции ещё не подтверждает применение дополнительного правила. Гарантии отката частичных изменений контекста при ошибке в источнике не определены.

Плагины выполняются на Tarantool router в ходе process_cashback_transaction. Их данные хранятся в пространстве plugins на storage-узлах. Код компилируется и кешируется в памяти; изменения распространяются механизмом broadcast. Точная схема синхронизации нескольких router-узлов и время применения изменений требуют проверки для установленной версии.

Если к одной точке подключено несколько плагинов, раньше выполняется плагин с меньшим priority. Порядок при одинаковых значениях в источнике не задан.

Точки расширения

Обработка проходит через проверку исключений, расчёт партнёрского и категорийного кэшбэка, выбор максимального результата, начисление и обновление статистики. Плагины подключаются к следующим этапам.

Таблица описывает назначение точек. Полные схемы контекста, типы и обязательность полей в исходном документе отсутствуют; таблица не заменяет контракт для разработки произвольного плагина.

API управления

Адрес сервиса и параметры авторизации зависят от окружения. Обзор API процессинга указывает на необходимость токена в заголовке; точное имя заголовка и права для управления плагинами необходимо получить для своей установки. В примерах приведены HTTP-методы, относительные пути и JSON-тела без параметров доступа.

Зарегистрировать плагин

Для регистрации передайте идентификатор, Lua-код и точку подключения. Следующий пример создаёт расширение, которое возвращает контекст без изменения:

POST /plugins
Content-Type: application/json

{
  "plugin_id": "example_passthrough",
  "plugin_code": "function(context, config)\n  return context\nend",
  "hook_point": "before_calculate_category_cashback",
  "priority": 100,
  "description": "Пример подключения без изменения расчёта",
  "config": {}
}

По исходному контракту новый плагин получает enabled: false и version: 1. Регистрация сама по себе не меняет расчёт кэшбэка.

Включить и проверить подключение

Выполните PATCH /plugins/example_passthrough с телом:

{"enabled": true}

Затем проверьте:

1. GET /plugins/example_passthrough — поле enabled имеет значение true, точка подключения и настройки соответствуют ожидаемым.
2. GET /hooks — идентификатор присутствует в нужной точке подключения.
3. Контрольная транзакция — результат соответствует логике расширения. Для примера без изменений расчёт должен сохраниться.

Включение загружает и компилирует код, регистрирует его в точке подключения и запускает распространение изменений. Проверка результата транзакции нужна дополнительно к проверке состояния через API.

Изменить код, настройки или приоритет

Используйте PATCH /plugins/:id и передайте нужные поля: plugin_code, config или priority. При изменении кода или конфигурации версия увеличивается. Для настройки отдельно предусмотрен PATCH /plugins/:id/config; JSON-тело также содержит поле config.

В исходной документации не определено, объединяется ли переданный config с прежним объектом или заменяет его целиком. До уточнения передавайте полный требуемый объект настроек, включая исключения, и проверяйте сохранённый результат через GET /plugins/:id.

После изменения проверьте версию, настройки, активный hook и контрольный расчёт. Гарантированный срок распространения изменений на весь кластер в этом руководстве не установлен.

Выключить или удалить

Для выключения выполните PATCH /plugins/:id с телом:

{"enabled": false}

Конфигурация остаётся зарегистрированной, но расширение не должно применяться к новым контрольным транзакциям. При этом продолжают действовать штатные правила процессинга и другие включённые плагины.

Для удаления используйте DELETE /plugins/:id. После этого проверьте отсутствие идентификатора в GET /plugins и GET /hooks. Поведение уже обрабатываемых транзакций при выключении, обновлении или удалении в исходном контракте не определено.

Пример: округление базы категорийного кэшбэка

Плагин cashback_rounding_category подключается к before_calculate_category_cashback и округляет базу расчёта вниз до значения, кратного заданному шагу. В примере шаг составляет 100 рублей. Уровни, перечисленные в исключениях, сохраняют полную базу.

Это округление базы перед умножением на ставку, а не округление уже рассчитанного кэшбэка:

База = floor(сумма / шаг) × шаг
Категорийный кэшбэк = база × ставка

Пример конфигурации из исходного документа:

{
  "default_rounding_step": 100,
  "level_overrides": {
    "max": null,
    "max_card_credit": null,
    "max_card_employee_credit": null,
    "premium": null,
    "premium_card_credit": null,
    "premium_card_employee_credit": null
  }
}

default_rounding_step задаёт шаг в рублях. В level_overrides значение null отключает округление для конкретного уровня, а число задаёт собственный шаг. В примере использованы условные идентификаторы уровней max и premium, а также их варианты для кредитных карт (card_credit) и кредитных карт сотрудников (card_employee_credit). При настройке укажите фактические идентификаторы уровней своей программы лояльности.

Для подключения готового расширения нужен регистрационный JSON с Lua-кодом. Объект выше содержит только настройки: его недостаточно для POST /plugins. В исходном репозитории регистрационный файл расположен по пути plugins/cashback-rounding-category/config.json.

Проверить расчёт

Для контрольных примеров подготовьте клиента с активной категорией, подходящим MCC и ставкой 3%. Исключите влияние лимитов, других плагинов и конкурирующего партнёрского кэшбэка на проверяемый результат. Используйте отдельные идентификаторы транзакций.

Для проверки обновления конфигурации используйте покупку на 175 ₽: при шаге 100 ₽ база равна 100 ₽ и кэшбэк — 3 ₽; при шаге 50 ₽ база равна 150 ₽ и кэшбэк — 4,50 ₽. Такой пример различает старую и новую настройку по результату расчёта.

Сопоставляйте начисление по конкретной операции и логи расчёта. Доступный баланс может отличаться от начисленной суммы из-за правил активации бонусов; изменение только доступного баланса не является достаточной проверкой.

Диагностика

Логи выполнения плагина ищите на Tarantool router, который обрабатывал транзакцию. Для плагина округления исходная документация приводит сообщения Amount rounded, Rounding skipped for excluded level и Amount already aligned с префиксом [cashback_rounding].

Для разбора сохраните идентификатор и время транзакции, версию процессинга, идентификатор и версию плагина, его настройки и логи соответствующего router. Отсутствие строки округления само по себе не определяет причину: обработка могла не дойти до этой точки или уровень мог подпадать под другую настройку.

Границы этого руководства

Документ описывает базовую модель и управление плагинами по исходному материалу. Он не задаёт полный контракт разработки: остаются неуточнёнными схемы контекста, права доступа, ограничения выполнения Lua, коды ошибок API и гарантии обновления кластера. Минимальная поддерживаемая версия процессинга также пока не установлена.

Для расширений, влияющих на другие этапы расчёта, возвраты или корректировки, требуется отдельная проверка контракта и результата. Пример округления не подтверждает работу произвольного плагина во всех способах приёма транзакций.