Модуль 1С-Битрикс




Описание модуля

Программный модуль для упрощения интеграции сервиса программ лояльности  MAXMA.com  в веб-сайты брендов-партнеров, работающих на платформе 1С-Битрикс.
В модуле реализованы:
Обработчики событий стандартных модулей 1С-Битрикс
Правила работы с корзиной
Функции отключения обработки заказов для группы пользователей
Отложенная отправка ошибочных запросов к API
Компоненты публичной части
Логирование данных

Технические требования

1С-Битрикс ≥ 18.5
PHP ≥ 7.0

Установка и настройка

Установка

Модуль можно установить на проект с официального  маркетплейса 1С-Битрикс .

При установке модуль:
Регистрирует обработчики для событий  OnAfterUserAdd ,  OnAfterUserAuthorize  ,  OnBeforeSaleOrderFinalAction  ,  OnSaleOrderCanceled  ,  OnSaleStatusOrderChange ,  OnSaleOrderBeforeSaved  ,  OnSaleOrderSaved 
Создает таблицу  maxma_delayed_request  для хранения данных об отложенных запросах
Создает таблицу  maxma_product_discount  для хранения данных для расчета скидки позиции корзины заказа
Создает правило работы с корзиной  Скидка MAXMA 
Создает свойства заказа:
 MAXMA_BONUSES  для хранения бонусов, применённых к корзине заказа
 MAXMA_PROMOCODE  для хранения примененного промокода
Регистрирует агенты:
 \\Maxma\\Loyalty\\RequestQueue\\QueueCleaner::agentQueueCleaner();  для очистки обработанных записей в таблице  maxma_delayed_request 
 \\Maxma\\Loyalty\\RequestQueue\\QueueExecutor::agentQueueExecute();  - для обработки записей в таблице  maxma_delayed_request 

Настройка

Модуль содержит настройки в административной части сайта  Настройки продукта > Настройки модулей > MAXMA Loyalty 
Список настроек:
Секретный ключ — секретный API ключ для интеграции, можно получить у вашего менеджера.
Код точки продаж — идентификатор вашего магазина (цифры, символы).
Адрес сервера для отправки запросов
Боевой режим —  api.maxma.com 
Тестовый режим —  api-test.maxma.com 
Статус выкупа заказа — набор статусов, при которых заказ будет помечен выкупленным в MAXMA.
Включить логирование — логи хранятся в папке модуля в logs/, сгруппированные по дням.
Ограничения процессинга — используйте эту настройку, чтобы исключить служебных пользователей из процессинга заказов. Например, при синхронизации с 1С.

Логирование

Логирование реализовано в классе  Util/Logger . Логи записываются в директорию  /logs/  в корне проекта. Лог-файлы имеют расширение  .log 
Доступно 8 уровней логирования ( PSR-3 ).
Пример вызова логирования:
// данный вызов создаст файл client.log в директори /logs/{текущий день}/
// и запишет в файл лог уровня info
// @var string $message Сообщение лога
// @var array $context Дополнительные данные логирования

\Maxma\Bitrix\Util\Logger::channel('client')->info($message, $context);
Запись логов зависит от активной настройки модуля  logging .
В случае если нужно записать в логи, а настройка выключена, есть специальный метод  enableLogging()  . Предназначение данного метода — это отладка на клиентских проектах отдельных узлов модуля.

Отложенные запросы

Функционал отложенной отправки запросов нужен для безотказной передачи данных с сайта в API MAXMA. При отправке запросов через SDK MAXMA и получении исключения  TransportException  сохраняем данные и операцию в базу данных в таблицу  maxma_delayed_request . Класс описывающий таблицу — Maxma\Loyalty\RequestQueue\QueueTable
Методы API, для которых настроена отложенная отправка:
Создание нового клиента
Обновление externalId клиента
Создание и изменение заказа
Выкуп заказа
Отмена заказа

Бизнес-логика

Покупатели

Для создания новых покупателей в MAXMA используются обработчик двух событий:
 OnAfterUserAdd  (добавление пользователя на сайте)
 OnAfterUserAuthorize  (авторизация пользователя на сайте)
Обработчик выполняет поиск покупателя в базе MAXMA и в соответствии с результатом регистрирует его, изменяет данные или не выполняет никаких действий.
Обработчик и поиск покупателя в MAXMA работает по следующей бизнес-логике:
Первичная проверка покупателя осуществляется по внешнему идентификатору (узел  externalId ). Если покупатель найден, никаких действий не выполняется.
Если покупатель не найден по  externalId  , производится поиск по номеру телефона. Значение берется из поля Bitrix  PHONE_NUMBER , а если оно пусто, то из поля  PERSONAL_PHONE . Для ситуаций, когда на сайте номер телефона хранится не в стандартных полях сущности пользователя, надо создать обработчик на событие модуля  onGetUserPhone .
Если покупатель найден по телефону, выполняется обновление внешнего идентификатора ( externalId ) в MAXMA. В качестве значения узла  externalId  надо передается составное значение из префикса bx- и идентификатора пользователя в Bitrix (например,  bx-337 ).
Если покупатель не найден по externalId и phoneNumber, он создается в MAXMA.

Заказы

Для создания и обновления заказов используется обработчик, который привязан к событию  OnSaleOrderSaved  (происходит в конце сохранения заказа).
При создании нового заказа переносятся значения списанных бонусов и промокода из сессии в свойство заказа  MAXMA_BONUSES  и  MAXMA_PROMOCODE .
Для фиксации выкупа заказа используется обработчик события  OnSaleStatusOrder  (происходит после изменения статуса заказа).
Для фиксации отмены заказа используется обработчик события  OnSaleOrderCanceled  (изменение флага отмены заказа).

Расчет скидок

Применение скидки MAXMA реализовано через пользовательское правило работы с корзиной.
Хранилище для правил работы с корзиной реализовано в виде таблицы в базе данных. Название таблицы —  maxma_product_discount . Взаимодействие с таблицей реализовано через ORM D7.
Для обработки данной операции реализована привязка к событию  OnBeforeSaleOrderFinalAction  (финальный расчет корзины).
Расчет скидки производится при следующих события:
Списание бонусов через компонент  maxma:basket.bonus 
Применение промокода через компонент  maxma:basket.promocode 
Пересчет заказа

Компоненты

Компонент баллов в карточке товара

Компонент отображает количество бонусов, которое будет начислено при покупке товара.
Место интеграции — карточка товара.
Компонент получает данные о количестве бонусов из API MAXMA.
Пример вызова:
<?php
$APPLICATION->IncludeComponent(
'maxma:catalog.element.bonus',
'',
[
'PRICE' => $item['BASE_PRICE'],
'PRODUCT_ID' => $item['ID']
],
$component,
['HIDE_ICONS' => 'Y']
);
?>

Компонент бонусов в корзине

Компонент отображает количество бонусов покупателя и содержит форму списания бонусов при оформлении заказа.
Место интеграции — корзина и страница оформления заказа.
Компонент доступен только для авторизованного пользователя.
При инициализации компонента на странице происходит получение информации о списанном текущем количестве бонусов из глобальной переменной сессии под ключом  MAXMA_BONUSES  и отображается в форме, если оно не пустое.
При отправке формы списания бонусов выполняется запрос в MAXMA с данными пользователя, количеством бонусов к списанию, корзиной заказа, данными промокода (ключ  MAXMA_PROMOCODE  переменной сессии).
Полученный расчет корзины с учетом списанных бонусов фиксируется в таблице  maxma_product_discount . Количество бонусов, которые были списаны пользователем, фиксируются в сессии под ключом  MAXMA_BONUSES .
При отмене списания бонусов значение в сессии под ключом  MAXMA_BONUSES  очищается.
Компонент содержит 2 шаблона: полный (default) и сокращенный (short).
Параметры компонента:
Название
Параметр
Описание
Страница авторизации
PATH_TO_AUTH
Путь до страницы авторизации
Подробная информация
DETAILED_LINK
Ссылка на страницу с подробной информацией
Ajax запрос
IS_AJAX
Работа в режиме Ajax (доступен только для стандартных компонентов Bitrix)
Пример вызова:
<?php
$APPLICATION->IncludeComponent(
'maxma:basket.bonus',
'short',
[
'PATH_TO_AUTH' => '/login/',
'DETAILED_LINK' => 'https://maxma.com/ru',
'IS_AJAX' => 'Y'
],
false
);
?>

Компонент промокода в корзине

Компонент представляет собой форму ввода и применения промокода.
Место интеграции — корзина, страница оформления заказа.
Компонент доступен для авторизованного и неавторизованного пользователя.
При инициализации компонента на странице происходит получение информации о примененном промокоде из глобальной переменной сессии под ключом  MAXMA_PROMOCODE  и отображается в форме, если оно не пустое.
При отправке формы промокода выполняется запрос в MAXMA с данными пользователя, промокодом, корзиной заказа, количеством списанных бонусов (ключ  MAXMA_BONUSES  переменной сессии).
При успешном применении промокода его значение записывается в переменной сессии под ключом  MAXMA_PROMOCODE  и полученный расчет фиксируется в таблице  maxma_product_discount .
При отмене применения промокода значение в сессии под ключом  MAXMA_PROMOCODE  очищается.
Компонент содержит 2 шаблона: полный (default) и сокращенный (short).
Параметры компонента:
Пример вызова:
<?$APPLICATION->IncludeComponent(
'maxma:basket.promocode',
'short',
[
'IS_AJAX' => 'Y'
],
false
);?>

Кастомизация компонентов

Для подготовки дизайна интерфейса компонентов рекомендуется использовать макеты в  Figma :
Для кастомизации цветов компонента необходимо в глобальном файле стилей сайта добавить правило с объявлением CSS переменных:
:root .maxma {
--maxma-accent-color: #1CA1BD; /* базовый цвет */
--maxma-success-color: #87C73D; /* цвет успешной операции */
--maxma-error-color: #C71E1E; /* цвет ошибки */
--maxma-main-hover-color: #5B9F0B; /* цвет при наведении */
}
Если нужны более сложные изменения в визуальной части компонента, необходимо скопировать дефолтный шаблон компонента в соответствующую директорию шаблона сайта и внести изменения.

Порядок поддержки модуля

Поддержка (вопросы, ошибки, идеи) осуществляется по электронной почте  support@maxma.com .
Режим работы: 09:00-18:00 по московскому времени. Выходные дни: суббота и воскресенье.
Время реакции на обращение – 24 часа.

Структура модуля

Файловая структура

lang/ru/ — каталог с языковыми файлами скриптов модуля;
lib/ — каталог с классами, реализующие основную бизнес-логику;
logs/ — каталог с логами;
install/ — каталог с файлами используемыми для инсталляции и деинсталляции модуля;
components/maxma/basket.bonus/ — каталог компонента списания бонусов;
components/maxma/basket.promo/ — каталог компонента промокода;
components/maxma/catalog.element.bonus/ — каталог компонента отображения бонусов в карточке товара;
index.php — файл с описанием модуля;
version.php — файл с номером версии модуля.
vendor/ — каталог с зависимостями модуля;
composer.json — конфиг для composer;
include.php — файл для подключения автолоадера composer;
default_option.php — содержит массив с именем $ID модуля_default_option, в котором заданы значения по умолчанию для параметров модуля;
options.php — страница настроек модуля;
 README.md  — описание модуля

Структура классов

Maxma — класс ответственен за получение и настройку экземпляра SDK MAXMA. В классе описаны основные необходимые операция для взаимодействия с API.
Settings — класс реализует шаблон Singleton и нужен доступа к настройкам модуля. Хранит код модуля и реализовано получение настроек модуля через COption.
Exceptions/ — неймспейс для хранения исключений модуля.
Entity/Order — класс, содержащий основную бизнес-логику сущности заказа.
Entity/User — класс, содержащий основную бизнес-логику сущности пользователя.
Entity/Product— класс, содержащий основную бизнес-логику сущности товар.
Event/UserEvent — события для работы с пользователем.
Event/OrderEvent — события для работы с заказом.
Util/Logger — класс для логирования в проекте.
Util/Helper — класс со статическими методами для типовых действий.
RequestQueue/QueueExecutor — класс реализует функционал добавления запроса в очередь (записать в хранилище), исполнение запроса.
RequestQueue/QueueCleaner — класс реализует функционал очищения отработанных очередей. Функционал запускается агентом.
RequestQueue/QueueTable — класс описывает таблицу при помощи ORM Bitrix.
Install/Discount— класс реализует установку пользовательское правила работы с корзиной.
Install/OrderProperty — класс реализует установку свойств заказа Bitrix.
Discount/CartRuleAction — класс, описывающий кастомное правило работы с корзиной.
Discount/DiscountStorageTable — orm аннотация таблицы maxma_product_discount.
Discount/DiscountManager — реализация расчета скидки.
Enum/EntityNameEnum — класс-перечисление, хранящий названия дополнительных сущностей модуля.
Enum/SettingsEnum — класс-перечисление, хранящий символьные коды настроек модуля.

Зависимости проекта