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

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 пользовательскими данными.