Система управления складом с использованием CQRS и Event Sourcing. Service Layer / Хабр

В данной статье будет рассмотрен Service Layer в Magento 2 и сервисы (API интерфейсы) для управления сущностями, которые были описаны в предыдущей статье, посвященной проектированию и выделению доменных сущностей для системы управления складом (Inventory).

Service Layer

Так как систему управления складом мы пишем на платформе Magento 2, соответсвенно и сервисы, которые мы вводим будут описаны с учетом особенностей этой платформы.
В Magento 2 для реализации принципа слабой связности на уровне модулей (в пределах Bounded Context-ов) был введен Service Layer, который определяет набор доступных операций для каждого модуля с точки зрения взаимодействия клиентов и других модулей системы.

Service Layer (или Service Contracts) в Magento это набор PHP интерфейсов, которые определены для модуля и находятся в папке Api этого модуля. Сервис контракты состоят из Data Interfaces — DTO интерфейсы, представляющие данные сущностей доменной области; и Service Interfaces — интерфейсы, которые предоставляют доступ к бизнес логике, которая может быть вызвана клиентом (контроллером, web сервисом REST/SOAP, PHP кодом других модулей).

Так как предполагается, что все внешние клиенты модуля будут работать с ним по контрактам, описанным Service Layer, то Service Layer фактически можно представить как Facade, который за собой скрывает детали реализации и сложность бизнес логики.
Для клиентов зависимость на четко определенные API позволяет легче проводить апгрейды на следующие версии системы, так как модули подчиняются семантическому версионированию (Semantic Versioning).

Для лучшей модулярности и отделения (decoupling) сервис контрактов от реализации иногда сервис контракты выделяют в отдельный модуль. Например, в случае Inventory мы имеем два модуля: один декларирует набор сервис интерфейсов InventoryAPI, второй — предоставляет реализацию для этих интерфейсов — Inventory. Таким образом, сторонний разработчик, который захочет подменить базовую реализацию, больше не привязан к этой реализации в коде. Все что ему нужно — интерфейсы, так как именно на интерфейсы зависят другие модули в системе.

Интерфейсы Репозиториев — Repository

Репозитории представляют собой интерфейсы предоставляющие набор CRUD операций для сущностей.
Типичный интерфейс репозитория состоит из набора следующих методов:

 public function save(\Magento\Module\Api\Data\DataInterface $entityData);
 public function get($entityId);
 public function delete(\Magento\Module\Api\Data\DataInterface $entityData);
 public function deleteById($entityId);
 public function getList(SearchCriteriaInterface $searchCriteria);

Набор методов может быть у́же (если для доменной сущности не характерны определенные операции. Например, удаление), но не шире, так как не рекомендовано добавлять методы с семантикой, отличающейся от предопределенного набора. Такие методы рекомендовано помещать в отдельные сервисы.

Репозитории можно воспринимать как Фасады (Facade), которые объединяют наборы методов по управлению сущностями.

В контексте модуля Inventory появляются репозитории для сущностей Source (сущность ответственная за представление любого физического склада где может находиться товар) и SourceItem ( сущность-связка, представляет собой количество определенного продукта (SKU) на конкретном физическом хранилище).


/**
 * This is Facade for basic operations with Source
 * There is no delete method, as Source can't be deleted from the system because we want to keep Order information for all orders placed. Sources can be disabled instead.
 *
 * Used fully qualified namespaces in annotations for proper work of WebApi request parser
 *
 * @api
 */
interface SourceRepositoryInterface
{
    /**
     * Save Source data
     *
     * @param \Magento\InventoryApi\Api\Data\SourceInterface $source
     * @return int
     * @throws \Magento\Framework\Exception\CouldNotSaveException
     */
    public function save(SourceInterface $source);

    /**
     * Get Source data by given sourceId. If you want to create plugin on get method, also you need to create separate
     * plugin on getList method, because entity loading way is different for these methods
     *
     * @param int $sourceId
     * @return \Magento\InventoryApi\Api\Data\SourceInterface
     * @throws \Magento\Framework\Exception\NoSuchEntityException
     */
    public function get($sourceId);

    /**
     * Load Source data collection by given search criteria
     *
     * @param \Magento\Framework\Api\SearchCriteriaInterface $searchCriteria
     * @return \Magento\InventoryApi\Api\Data\SourceSearchResultsInterface
     */
    public function getList(SearchCriteriaInterface $searchCriteria = null);
}

В случае SourceRepository у нас отсутствует метод delete, потому что такой бизнес операции над сущностями Source не существует, так как необходимо всегда сохранять всю информацию, связанную с размещенными заказами (включая откуда товар был доставлен). Соответсвенно нужно предотвратить возможную потерю таких данных в будущем (удаляя Source из которого выполнялась доставка). Вместо этого используется операция — пометить Source как неактивный (disabled).


/**
 * This is Facade for basic operations with SourceItem
 *
 * The method save is absent, due to different semantic (save multiple)
 * @see SourceItemSaveInterface
 *
 * There is no get method because SourceItem identifies by compound identifier (sku and source_id),
 * thus, it's needed to use getList() method
 *
 * Used fully qualified namespaces in annotations for proper work of WebApi request parser
 *
 * @api
 */
interface SourceItemRepositoryInterface
{
    /**
     * Load Source Item data collection by given search criteria
     *
     * We need to have this method for direct work with Source Items, as Source Item contains
     * additional data like  qty, status (can be searchable by additional field)
     *
     * @param \Magento\Framework\Api\SearchCriteriaInterface $searchCriteria
     * @return \Magento\InventoryApi\Api\Data\SourceItemSearchResultsInterface
     */
    public function getList(SearchCriteriaInterface $searchCriteria);

    /**
     * Delete Source Item data
     *
     * @param SourceItemInterface $sourceItem
     * @return void
     * @throws \Magento\Framework\Exception\NoSuchEntityException
     * @throws \Magento\Framework\Exception\CouldNotDeleteException
     */
    public function delete(SourceItemInterface $sourceItem);
}

Так как основные сценарии использования операции сохранения происходят с набором SourceItems, а не с одной сущностью, как это предполагает стандартный контракт save в репозитории.
Для множественного сохранения, которое может происходить во время операций импорта или синхронизации стоков с внешними ERP или PIM системами — вводится отдельный контракт SourceItemSaveInterface, который предоставляет возможность атомарного сохранения множества SourceItem-ов в рамках одного вызова сервиса. Такой контракт позволяет обработать операцию вставки используя один запрос в базу данных, что значительно ускорит обработку. Базовая операция сохранения, принимающая одиночную сущность, не добавлена в контракт репозитория для того, чтобы не добавлять несколько точек для расширения, так как по факту в этом случае стороннему разработчику прийдется плагинизировать обе save операции (единичную и множественную). Поэтому кастомизация одной точки расширения всегда выглядет предпочтительней.

Контракт команды множественного сохранения выглядит как Magento\InventoryApi\Api\SourceItemSaveInterface


/**
 * Service method for source items save multiple
 * Performance efficient API, used for stock synchronization
 *
 * Used fully qualified namespaces in annotations for proper work of WebApi request parser
 *
 * @api
 */
interface SourceItemSaveInterface
{
    /**
     * Save Multiple Source item data
     *
     * @param \Magento\InventoryApi\Api\Data\SourceItemInterface[] $sourceItems
     * @return void
     * @throws \Magento\Framework\Exception\InputException
     * @throws \Magento\Framework\Exception\CouldNotSaveException
     */
    public function execute(array $sourceItems);
}

А ее реализация SourceItemSave делегирует сохранение ресурс модели SaveMultiple.

Также в SourceItemRepository отсутствует метод get(), так как SourceItem — это сущность-связка и она определяется составным идентификатором (SKU и SourceId).

Репозиторий для Stock (виртуальных агрегаций Source сущностей) выглядит стандартно:


interface StockRepositoryInterface
{
    /**
     * Save Stock data
     *
     * @param \Magento\InventoryApi\Api\Data\StockInterface $stock
     * @return int
     * @throws \Magento\Framework\Exception\CouldNotSaveException
     */
    public function save(StockInterface $stock);
    /**
     * Get Stock data by given stockId. If you want to create plugin on get method, also you need to create separate
     * plugin on getList method, because entity loading way is different for these methods
     *
     * @param int $stockId
     * @return \Magento\InventoryApi\Api\Data\StockInterface
     * @throws \Magento\Framework\Exception\NoSuchEntityException
     */
    public function get($stockId);
    /**
     * Find Stocks by given SearchCriteria
     *
     * @param \Magento\Framework\Api\SearchCriteriaInterface|null $searchCriteria
     * @return \Magento\InventoryApi\Api\Data\StockSearchResultsInterface
     */
    public function getList(SearchCriteriaInterface $searchCriteria = null);
    /**
     * Delete the Stock data by stockId. If stock is not found do nothing
     *
     * @param int $stockId
     * @return void
     * @throws \Magento\Framework\Exception\CouldNotDeleteException
     */
    public function deleteById($stockId);
}

Сервисы для маппинга Source и Stock

Руководствуясь правилом "don't make your client do anything you can do for them" чтобы уменьшить количество boilerplate кода в клиенте API (в коде бизнес логики) мы не вводим Data interface SourceStockLinkInterface. Вместо этого мы вводим набор доменных сервисов-команд для связывания (assignment) Source на Stock.

В итоге получаем три команды:


interface AssignSourcesToStockInterface
{
    /**
     * Assign list of source ids to stock
     *
     * @param int $stockId
     * @param int[] $sourceIds
     * @return void
     * @throws \Magento\Framework\Exception\InputException
     * @throws \Magento\Framework\Exception\CouldNotSaveException
     */
    public function execute(array $sourceIds, $stockId);
}

interface GetAssignedSourcesForStockInterface
{
    /**
     * Get Sources assigned to Stock
     *
     * @param int $stockId
     * @return \Magento\InventoryApi\Api\Data\SourceInterface[]
     * @throws \Magento\Framework\Exception\InputException
     * @throws \Magento\Framework\Exception\LocalizedException
     */
    public function execute($stockId);
}

interface UnassignSourceFromStockInterface
{
    /**
     * Unassign source from stock
     *
     * @param int $sourceId
     * @param int $stockId
     * @return void
     * @throws \Magento\Framework\Exception\InputException
     * @throws \Magento\Framework\Exception\CouldNotDeleteException
     */
    public function execute($sourceId, $stockId);
}

API vs SPI

В рамках данного проекта было решено явно разделять API (Application Programming Interface) от SPI (Service Provider Interfaces) для того, чтобы улучшить возможности расширения и уменьшить связность компонентов.

Репозитории могут быть расценены как API, соответственно предполагается, что методы интерфейса репозитория вызываются в PHP коде бизнес логики.
Отдельные классы-команды на которые класс-реализация репозитория проксирует методы (такие как: Get, Save, GetList, Delete) могут быть расценены как SPI — интерфейсы, для которых может быть предложена своя реализация сторонним разработчиком, чтобы расширить или заменить текущее поведение системы.

Таким образом, например, реализация репозитория Magento\Inventory\Model\StockRepository выглядит следующим образом:


/**
 * @inheritdoc
 */
class StockRepository implements StockRepositoryInterface
{
    /**
     * @var SaveInterface
     */
    private $commandSave;

    /**
     * @var GetInterface
     */
    private $commandGet;

    /**
     * @var DeleteByIdInterface
     */
    private $commandDeleteById;

    /**
     * @var GetListInterface
     */
    private $commandGetList;

    /**
     * @param SaveInterface $commandSave
     * @param GetInterface $commandGet
     * @param DeleteByIdInterface $commandDeleteById
     * @param GetListInterface $commandGetList
     */
    public function __construct(
        SaveInterface $commandSave,
        GetInterface $commandGet,
        DeleteByIdInterface $commandDeleteById,
        GetListInterface $commandGetList
    ) {
        $this->commandSave = $commandSave;
        $this->commandGet = $commandGet;
        $this->commandDeleteById = $commandDeleteById;
        $this->commandGetList = $commandGetList;
    }

    /**
     * @inheritdoc
     */
    public function save(StockInterface $stock)
    {
        $this->commandSave->execute($stock);
    }

    /**
     * @inheritdoc
     */
    public function get($stockId)
    {
        return $this->commandGet->execute($stockId);
    }

    /**
     * @inheritdoc
     */
    public function deleteById($stockId)
    {
        $this->commandDeleteById->execute($stockId);
    }

    /**
     * @inheritdoc
     */
    public function getList(SearchCriteriaInterface $searchCriteria = null)
    {
        return $this->commandGetList->execute($searchCriteria);
    }
}

Конструктор принимает набор интерфейсов команд для каждой из предоставляемых операций. И во время вызова публичного метода из репозитория — вызов проксируется в соответствующую команду.

Интерфейсы SPI команд выглядят следующим образом:


/**
 * Save Stock data command (Service Provider Interface - SPI)
 *
 * Separate command interface to which Repository proxies initial Save call, could be considered as SPI - Interfaces
 * so that you should extend and implement to customize current behaviour, but NOT expected to be used (called) in the code
 * of business logic directly
 *
 * @see \Magento\InventoryApi\Api\StockRepositoryInterface
 * @api
 */
interface SaveInterface
{
    /**
     * Save Stock data
     *
     * @param StockInterface $stock
     * @return int
     * @throws CouldNotSaveException
     */
    public function execute(StockInterface $stock);
}

/**
 * Get Stock by stockId command (Service Provider Interface - SPI)
 *
 * Separate command interface to which Repository proxies initial Get call, could be considered as SPI - Interfaces
 * that you should extend and implement to customize current behavior, but NOT expected to be used (called) in the code
 * of business logic directly
 *
 * @see \Magento\InventoryApi\Api\StockRepositoryInterface
 * @api
 */
interface GetInterface
{
    /**
     * Get Stock data by given stockId
     *
     * @param int $stockId
     * @return StockInterface
     * @throws NoSuchEntityException
     */
    public function execute($stockId);
}

/**
 * Delete Stock by stockId command (Service Provider Interface - SPI)
 *
 * Separate command interface to which Repository proxies initial Delete call, could be considered as SPI - Interfaces
 * that you should extend and implement to customize current behaviour, but NOT expected to be used (called) in the code
 * of business logic directly
 *
 * @see \Magento\InventoryApi\Api\StockRepositoryInterface
 * @api
 */
interface DeleteByIdInterface
{
    /**
     * Delete the Stock data by stockId. If stock is not found do nothing
     *
     * @param int $stockId
     * @return void
     * @throws CouldNotDeleteException
     */
    public function execute($stockId);
}

/**
 * Find Stocks by SearchCriteria command (Service Provider Interface - SPI)
 *
 * Separate command interface to which Repository proxies initial GetList call, could be considered as SPI - Interfaces
 * that you should extend and implement to customize current behaviour, but NOT expected to be used (called) in the code
 * of business logic directly
 *
 * @see \Magento\InventoryApi\Api\StockRepositoryInterface
 * @api
 */
interface GetListInterface
{
    /**
     * Find Stocks by given SearchCriteria
     *
     * @param SearchCriteriaInterface|null $searchCriteria
     * @return StockSearchResultsInterface
     */
    public function execute(SearchCriteriaInterface $searchCriteria = null);
}

Эти команды представляют SPI интерфейсы модуля и находятся под неймспейсом

Magento\Inventory\Model\Stock\Command\*

Реализации команд выглядят следующим образом (Magento\Inventory\Model\Stock\Command\*). Например, команда сохранения Stock:


/**
 * @inheritdoc
 */
class Save implements SaveInterface
{
    /**
     * @var StockResourceModel
     */
    private $stockResource;

    /**
     * @var LoggerInterface
     */
    private $logger;

    /**
     * @param StockResourceModel $stockResource
     * @param LoggerInterface $logger
     */
    public function __construct(
        StockResourceModel $stockResource,
        LoggerInterface $logger
    ) {
        $this->stockResource = $stockResource;
        $this->logger = $logger;
    }

    /**
     * @inheritdoc
     */
    public function execute(StockInterface $stock)
    {
        try {
            $this->stockResource->save($stock);
            return $stock->getStockId();
        } catch (\Exception $e) {
            $this->logger->error($e->getMessage());
            throw new CouldNotSaveException(__('Could not save Stock'), $e);
        }
    }
}

Механизм Резервирования продуктов

Объект резервирования создается для того, чтобы иметь актуальный уровень товаров, которыми мы располагаем для продажи, между событиями создания заказа и уменьшением количества товаров на конкретных физических складах.
Реализуя бизнес сценарий размещения заказа, подробно описанный в предыдущей части.

Мы вводим Data Interface для резервирования


/**
 * The entity responsible for reservations, created to keep inventory amount (product quantity) up-to-date.
 * It is created to have a state between order creation and inventory deduction (deduction of specific SourceItems)
 *
 * @api
 */
interface ReservationInterface extends ExtensibleDataInterface
{
    /**
     * Constants for keys of data array. Identical to the name of the getter in snake case
     */
    const RESERVATION_ID = 'reservation_id';
    const STOCK_ID = 'stock_id';
    const SKU = 'sku';
    const QUANTITY = 'quantity';
    const STATUS = 'status';

    /**#@+
     * Reservation possible statuses.
     */
    const STATUS_OPEN = 1;    
    const STATUS_CLOSED = 2;   
    /**#@-*/

    /**
     * Get Reservation id
     *
     * @return int|null
     */
    public function getReservationId();

    /**
     * Get stock id
     *
     * @return int
     */
    public function getStockId();

    /**
     * Get Product SKU
     *
     * @return string
     */
    public function getSku();

    /**
     * Get Product Qty
     *
     * @return float
     */
    public function getQuantity();

    /**
     * Get Reservation Status
     *
     * @return int
     */
    public function getStatus();
}

Так как мы воспринимаем резервирование как Append-Only неизменяемую сущность, то нам не нужны модификаторы (setter методы) в ReservationInterface. Соответсвенно нам нужен ReservationBuilderInterface для того, чтобы создавать объекты-резервирование.


$reservationBuilder->setStockId(1);
$reservationBuilder->setSku('sku');
$reservationBuilder->setQty(10);
$newReservation = $reservationBuilder->build();
//now we could save Reservation entity 
$reservationAppend->execute([$newReservation]);

Сервисы Резервирования объектов

Сервис добавления резервирований (бронирований) используется во время размещения заказа, обработки заказа или отмены заказа. А также создания и обработки операции возврата товара. В это время создается пачка резервирований, по одному резервированию на каждый SKU, и добавляются с помощью данного сервиса для обработки.


/**
 * Command which appends reservations when order placed or canceled
 *
 * @api
 */
interface ReservationAppend
{
    /**
     * Append reservations when Order Placed (or Cancelled)
     *
     * @param Reservation[] $reservations
     * @return void
     * @throws \Magento\Framework\Exception\InputException
     * @throws \Magento\Framework\Exception\CouldNotSaveException
     */
    public function execute(array $reservations);
}

Следующий сервис используется для того, чтобы подсчитать точное число (Quantity) товара доступное для продажи, так как Quantity StockItem-a обновляется с задержкой (latency) вызванной природой Event Sourcing, так как во время размещения заказа система работает со StockItem сущностью (виртуальной агригацией) и не знает из каких физических складов (Source) произойдет списание. Таким образом между операцией размещения заказа и обработки — может пройти опредленное время.


/**
 * Command which returns Reservation Quantity by Product SKU and Stock
 *
 * @api
 */
interface GetReservationQuantityForProduct
{
    /**
     * Get Reservation Quantity for given SKU in a given Stock
     *
     * @param string $sku
     * @param int $stockId
     * @return float
     */
    public function execute($sku, $stockId);
}

Каждое резервирование может иметь открытое или закрытое состояние.
Так как резервирование — immutable объект, который не может изменяться. Вместо того, чтобы изменить состояние резервирования — мы просто создаем второй резерв, который «гасит» списание первого.
Например,
размещая заказ на 30 единиц товара создаем резервирование:
ReservationID — 1, StockId — 1, SKU — SKU-1, Qty — (-30), Status — OPEN
Обработав этот заказ — создаем другое резервирование
ReservationID — 2, StockId — 1, SKU — SKU-1, Qty — (+30), Status — CLOSED

Суммарно эти два резерва (-30) + (+30) = 0 не повлияют на Quantity, которое хранится в StockItem.
Здесь важно заметить две вещи: мы не вводим связь (binding) между объектом резервирования и заказом (Order), так как резерв может быть привязан и к другим бизнес операциям. И с точки зрения склада (Inventory) нам не важен номер заказа, в рамках которого нужно отгрузить товар и уменьшить сток.
Использование отрицательных и положительных значений для резервирований поможет нам упростить подсчет общего числа, которое мы должны отнять от Quantity сохраненным в StockItem.

Например, с помощью такого запроса:

select 
   SUM(r.qty) as total_reservation_qty
from 
   Reservations as r
where 
  stockId = {%id%} and sku  = {%sku%}

Magento MSI (Multi Source Inventory)

Данная статья является третьей статьей в цикле «Система управления складом с использованием CQRS и Event Sourcing» в рамках которого будет рассмотрен сбор требований, проектирование и разработка системы управления складом на примере Magento 2.

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

Более подробная документация по

MSI Service Contracts (Англ.)
Reservations (Англ.)