Обмен заказами в формате CommerceML

Важно

Статья актуальна для CS-Cart 4.12.2 и более новых версий.

Процесс обмена

1. Начало сеанса

Этап предназначен для авторизации системы учета на сайте. В ответе на запрос с базовой авторизацией сайт отправляет данные о запущенной сессии.

2. Запрос параметров

На этом этапе система учета запрашивает информацию о возможностях сайта:

  • Поддержка ZIP-файлов. Статус поддержки ZIP-файлов зависит от наличия расширения ZIP в PHP. Расширение является обязательным для работы CS-Cart, поэтому статус поддержки ZIP будет всегда положительным. Однако вы можете явно отключить поддержку ZIP-файлов для CommerceML через файл конфигурации, указав:

    $config['commerceml']['allow_zip'] = false;
    
  • Максимальный размер файла. Размер высчитывается на основе таких настроек PHP, как: upload_max_filesize и post_max_size. Однако вы можете явно указать меньший размер файла для CommerceML через файл конфигурации, указав:

    $config['commerceml']['file_limit'] = '12M';
    

Также на этом этапе проходит ротация файлов с предыдущих сеансов обмена данными и подготовка директории для текущего сеанса: var/files/<company_id>/exim/1C, где <company_id> — идентификатор витрины (в CS-Cart) или продавца (в Multi-Vendor).

3. Запрос файла обмена с сайта

Этап предназначен для выгрузки информации о заказах в систему учета.

Список выгружаемых заказов зависит от стратегии экспорта заказов. Для формирования XML-документа из данных о заказе используется \Tygh\Addons\CommerceML\Formators\OrderFormator.

4. Выгрузка файлов обмена на сайт

Этап разбит на несколько шагов:

  1. Распаковка ZIP-архива

  2. Парсинг XML и конвертация

    На этом этапе все необходимые для импорта сущности конвертируются в DTO и сохраняются в БД для дальнейшего использования. За процесс конвертации отвечают так называемые конверторы. Все конверторы модуля CommerceML расположены в пространстве имен Tygh\Addons\CommerceML\Convertors.

    В модуле CommerceML выделены следующие типы сущностей:

    • ProductDto — для данных о товаре;
    • CategoryDto — для данных о категории;
    • CurrencyDto — для данных о валюте;
    • PriceTypeDto — для данных о типе цен;
    • ProductFeatureDto — для данных о характеристики товара;
    • ProductFeatureVariantDto — для данных о варианте характеристики товара;
    • TaxDto — для данных о типе налог.

    Кроме этого, модуль реализует множество других DTO. Например PropertyDto, который может использоваться для сохранения значения пользовательского свойства товара. Полный список всех DTO вы можете посмотреть в пространстве имен Tygh\Addons\CommerceML\Dto.

  3. Импорт товаров

    Импорт выполняется итерационно с ограничением по времени на одну итерацию — 60 секунд. На этом шаге из БД выбираются товары и все необходимые для импорта товара DTO. За процесс импорта отвечают так называемые импортеры. Все импортеры модуля CommerceML расположены в пространстве имен Tygh\Addons\CommerceML\Importers.

    На процесс импорта влияет большое количество настроек синхронизации. В зависимости от настроек процесс импорта может значительно отличаться.

    Все импортеры стремятся использовать стандартные функции ядра. Так, например, для создания товара будет вызван fn_update_product, что значительно повышает согласованность данных и снимает нагрузку с разработчиков. Теперь не нужно дублировать логику с fn_update_product на CommerceML. Однако это влияет на скорость работы импорта в целом. По завершении всего импорта из БД удаляются все DTO.

    Важно

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

    • Типы цен;
    • Типы налогов;
    • Валюты.

5. Загрузка данных

Этап разбит на несколько шагов:

  1. Распаковка ZIP-архива

  2. Парсинг XML и конвертация

    На этом этапе все необходимые для импорта сущности конвертируются в DTO и сохраняются в БД для дальнейшего использования. За процесс конвертации заказа в DTO отвечает конвертор OrderConvertor.

  3. Импорт заказов

    Импорт выполняется итерационно с ограничением по времени на одну итерацию — 60 секунд. На этом шаге из БД выбираются заказы и все необходимые для импорта заказа DTO. За процесс импорта отвечает импортер OrderImporter, который использует функции ядра. Так, например, для обновления информации о заказе используется функция fn_update_order.

    Важно

    Импорт заказов не создает новые заказы — только обновляет существующие заказы на сайте.

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

Схемы

  • Cml/aliases

    Схема используется для замещения терминов формата CommerceML на термины английского языка в коде. Если схема не покрывает какие-либо термины, вы можете расширить эту схему. Схема используется классом \Tygh\Addons\CommerceML\Xml\SimpleXmlElement, в котором реализованы различные методы для работы с XML.

    Важно

    Не меняйте существующие термины, это может полностью сломать логику работы модуля.

  • Cml/callbacks_sales

    Схема описывает функции-обработчики для отдельных нод-элементов XML-документа.

    Структура схемы представляет из себя ассоциативный массив, ключами которого является пути к XML-элементу, а значениями — анонимные функции-обработчики, в аргументы которых приходят:

    • $xml — объект типа \Tygh\Addons\CommerceML\Xml\SimpleXmlElement;
    • $import_storage — объект типа Tygh\Addons\CommerceML\Storages\ImportStorage, который реализует методы для работы с хранилищем текущего импорта.

    Путь к XML-элементу — это некоторое подобие xpath, но сильно ограниченное в возможностях. Это связано с тем, что парсинг XML происходит построчно через XMLReader.

    Задача обработчиков — преобразовать/конвертировать $xml в полезные DTO и сохранить их в хранилище импорта.

  • Cml/commands

    Примечание

    Экспериментальная логика, со временем может измениться.

    Обработка запросов от системы учета реализована в виде Command Bus. Схема описывает связь команды с непосредственным обработчиком команды и дает возможность описать middleware, которые могут влиять на обработку команды.

    Потенциально через схему можно повлиять на выполнение таких команд, как:

    • AuthCommand — команда для выполнения авторизации системы учета;
    • UploadImportFileCommand — команда для загрузки файлов от системы учета;
    • CreateImportCommand — команда для создания импорта и выполнения конвертации;
    • UnzipImportFileCommand — команда для распаковки архивов;
    • ExecuteCatalogImportCommand — команда для выполнения импорта товаров;
    • RemoveImportCommand — команда для удаления импорта, например, если он был выполнен только в режиме анализа;
    • CleanUpFilesDirCommand — команда для ротации и очистки директории для файлов учетной системы.

Хуки

  • Commerceml_order_formator_form

    Выполняется после формирования данных для XML на основе данных о заказе, но до преобразования в XML. Таким образом вы можете расширить или изменить XML-документ заказа.

  • Commerceml_order_convertor_convert

    Выполняется после конвертации заказа в OrderDto. Позволяет расширить OrderDto пользовательскими данными.