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




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

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

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

  • 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 работает по следующей бизнес-логике:
    .1Первичная проверка покупателя осуществляется по внешнему идентификатору (узел externalId). Если покупатель найден, никаких действий не выполняется.
    .2Если покупатель не найден по externalId , производится поиск по номеру телефона. Значение берется из поля Bitrix PHONE_NUMBER, а если оно пусто, то из поля PERSONAL_PHONE. Для ситуаций, когда на сайте номер телефона хранится не в стандартных полях сущности пользователя, надо создать обработчик на событие модуля onGetUserPhone.
    .3Если покупатель найден по телефону, выполняется обновление внешнего идентификатора (externalId) в MAXMA. В качестве значения узла externalId надо передается составное значение из префикса bx- и идентификатора пользователя в Bitrix (например, bx-337).
    .4Если покупатель не найден по externalId и phoneNumber, он создается в MAXMA.

Заказы

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

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

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


Расчет бонусов в каталоге

Данной функции у нас нет, но можно реализовать методом:  https://docs.maxma.com/api/#tag/Zakaz-internet-magazina/paths/~1calculate-products/post 

Компоненты

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

Компонент отображает количество бонусов, которое будет начислено при покупке товара.
Место интеграции — карточка товара.
Компонент получает данные о количестве бонусов из 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).
Параметры компонента:
Title
Title
Title
Название
Параметр
Описание
Страница авторизации
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 — класс-перечисление, хранящий символьные коды настроек модуля.



Доработка модуля (внедрение процессинга в каталог)

Для внедрения просчета скидок в каталоге товаров нужно реализовать данный функционал по этому ТЗ:  ссылка 

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

  •  https://github.com/cloudloyalty/client-php 
  •  https://github.com/php-fig/log 
  •  https://github.com/myclabs/php-enum