Source Selection Algorithm

When the system needs to determine from which Sources the delivery should be done - Source Selection Algorithm (SSA) has to be launched.

The main goal of SSA is to receive the total number of requested SKUs and their quantities, as well as the shipping address (the destination where the products should be shipped to), and based on particular business need which could be configured by merchant (organize delivery from Sources with Highest priority first or Minimal delivery cost etc.) algorithm should provide a list of Source Items with Quantities to deduct per each Source Item.

Based on results provided by SSA, Magento makes a deduction for each Source Item with specified quantity. A merchant can modify provided results adjusting quantities for deduction or even re-assigning sources from which delivery happen. That's why we never save results of Source Selection Algorithm as the results make sense just for given point of time, and can get invalid after some time (when stock data changed on source basis).

Minimal Viable Product (MVP) of MSI will implement Source Deduction at the time when Order has already been placed and Merchant creates Shipping for the given Order. That's why in current implementation is dealing with Order object from which all needed data is retrieved - ShippingAlgorithmInterface.

namespace Magento\InventoryShipping\Model;

/**
 * Returns shipping algorithm result for the order (extension point, SPI)
 *
 * @api
 */
interface ShippingAlgorithmInterface
{
    /**
     * @param OrderInterface $order
     * @return ShippingAlgorithmResultInterface
     */
    public function execute(OrderInterface $order): ShippingAlgorithmResultInterface;
}

But that's not flexible as potentially some could want to launch algorithm at the time when Order is being placed. For example, on fronted when customer proceeds to checkout. The goal of this move is to provide more accurate shipping cost to charge a customer. In this case Order object is not created yet, thus we can't use it as input data for SSA, the system should deal with Quote object instead.

Taking into account that there could be at least two valid business cases when SSA launched, and the source of data is different (Order and Quote) - it makes sense to introduce a new layer of Abstraction and make the algorithm use abstracted data container, but not particular Magento entity.

/**
 * Request products in a given Qty to be delivered to Shipping Address
 */
interface InventoryRequestInterface
{
    /**
     * @return \Magento\InventoryShipping\Api\Data\ShippingAddressInterface
     */
    public function getShippingAddress();

    /**
     * @return \Magento\InventoryShipping\Api\Data\ItemRequestInterface[]
     */
    public function getItems();
}

/**
 * Represents requested quantity for particular product
 */
interface ItemRequestInterface
{
    /**
     * Requested SKU
     *
     * @return string
     */
    public function getSku();

    /**
     * Requested Product Quantity
     *
     * @return float
     */
    public function getQty();
}

After these changes Source Selection Algorithm should be adjusted like this:

/**
 * Returns source selection algorithm result for given Inventory Request 
 *
 * @api
 */
interface SourceSelectionAlgorithmInterface
{
    /**
     * @param InventoryRequestInterface $inventoryRequest
     * @param string $algorithmType    DEFAULT | BY_PRIORITY | MINIMAL_COST | etc
     * @return SourceSelectionAlgorithmResultInterface
     */
    public function execute(
       InventoryRequestInterface $inventoryRequest,
       string $algorithmType
    ): SourceSelectionAlgorithmResultInterface;
}