Signed-off-by: Sujith mail.sujithvn@gmail.com

Resolves #6471
Impact: breaking
Type: feature

Issue

In the current system, the only way for order fulfillment is via shipping which is hardcoded into the system. We need to introduce the flexibility for users to add their own fulfillment types via plugins.

Solution

We are creating a base fulfillment plugin which would enable other fulfillment types (like shipping, pickup, digital) to be introduced via plugins. Each of the newly introduced fulfillment type plugin would need to have the specific fulfillment methods also to be added as separate plugins. Example, fulfillment type 'pickup' could have fulfillment methods like 'store pickup' and 'curb-side pickup'.

Breaking changes

Since this is the new way of handling fulfillment, the existing shipment plugins would not work along with this. User would need to migrate the data (migration script will be developed) and remove the shipment plugins (api-plugin-shipments and api-plugin-shipments-flat-rate).

Testing

To perform review and testing of the related code changes, we are adding details related to this feature implementation which spans across multiple plugins (each in its own folders in the packages folder in monorepo).

At a high level the impacted plugins are:

Existing plugin changes

api-plugin-products
api-plugin-catalogs
api-plugin-carts
api-plugin-orders

Plugins to be removed

api-plugin-shipments
api-plugin-shipments-flat-rate

New Plugins to be added

api-plugin-fulfillment
api-plugin-fulfillment-type-shipping
api-plugin-fulfillment-method-shipping-flat-rate
api-plugin-fulfillment-method-shipping-ups
api-plugin-fulfillment-type-pickup
api-plugin-fulfillment-method-pickup-store

Changes in detail:

CARTS

• New field - cartVersion in the cart to identify the new carts. Old carts will not have this field
• New field - selectedFulfillmentType: This field allows UI to send the fulfillment-type selected by user for the product while adding to the cart. This is optional and if not selected the item would default to undecided fulfillment group.
• New field - supportedFulfillmentTypes: This field was supposed to be existing but was missing. Added now (bug fix).
• New Mutation - setFulfillmentTypeForItems: Accepts an array of itemIds and a selected fulfillment type along with cart details. This mutation would move all the provided items to the requested fulfillment group depending on conditions like FFtype is supported by product, FFtype is active etc.
• Exported ShippingMethod & Shipment from SimpleSchema - these schemas will be extended in the api-plugin-fulfillment plugin to have the allowedValues changed from the hard coded "shipping" to dynamic array containing all the installed FFTypes
• New field - fulfillmentMethod - This is field will be non-editable and used for matching the fulfillment method from other functions/calls. Matching on existing fields like 'name' which are user-input in flat-rate method is not reliable.
• New field - displayMessageMethod - This new field will hold any string to be displayed along the FF Method in the UI, example store pickup requesting user to come in only after 24hrs of ordering.
• New field - methodAdditionalData: This could be fulfillment specific information used for processing in the system. Example Store may provide store details.
• updateCartFulfillmentGroups: logic updated - when new item is added to cart, if "selectedFulfillmentType" is provided, we add to that group, else the item goes to "Undecided" group.

CATALOGS

• supportedFulfillmentTypes - this field will be extended in the api-plugin-fulfillment plugin to have the allowedValues changed from the hard coded "shipping" to dynamic array containing all the installed FFTypes

PRODUCTS

• supportedFulfillmentTypes - this field will be extended in the api-plugin-fulfillment plugin to have the allowedValues changed from the hard coded "shipping" to dynamic array containing all the installed FFTypes

ORDERS

• Exported CommonOrder, orderFulfillmentGroupInputSchema, SelectedFulfillmentOption - these schemas will be extended in the api-plugin-fulfillment plugin to have the allowedValues changed from the hard coded "shipping" to dynamic array containing all the installed FFTypes
• New field - methodAdditionalData: This could be fulfillment specific information used for processing in the system. Example Store may provide store details.
  (above 2 changes are spread across multiple files)

ORDERS (specific to placeOrder refactor and introduction of validateOrder end-point)

• Moved out most of the functionalities from placeOrder to prepareOrder.
• Flattened out the hierarchical function calls by 1-2 levels and placed all the called functions in folder orderValidators inside util. Most of the functions are copied over from existing code base.
• prepareOrder builds up the order object and performs the validation steps in parallel. Validation results are accumulated in an array for most of the errors except the initial 2-3 errors where we return with the error.
• Both placeOrder and validateOrder calls prepareOrder with respective flags.
• Few steps specifically are related to payments auth and are skipped in case validateOrder is calling prepareOrder.
• In case of validateOrder call, most of the function calls are placed in a try-catch block to collect the errors. In case of placeOrder call, functions are directly executed.
• Final order object is validated against the schema (in case of prepare order, it is validated against a custom schema).
• prepareOrder returns Order & token to placeOrder, and returns success flag and validationResults to validateOrder.
• placeOrder will finally insert the order returned by prepareOrder into the DB and completes the placing of order.

API-PLUGIN-FULFILLMENT

This is the base plugin, basic features listed below.
Mutations

• createFulfillmentType - this is for internal call only from ff-type plugins (NEW)
• createFulfillmentMethod - this is for internal call only from ff-method plugins (NEW)
• updateFulfillmentType - public mutation which allows to update certain specific fields of the ff-type (NEW)
• updateFulfillmentMethod - public mutation which allows to update certain specific fields of the ff-type (NEW)
• updateFulfillmentOptionsForGroup - Existing code/functionality from the old shipment plugin. This updates the cart with quote details from all available ff-methods for the provided ff-type
• selectFulfillmentOptionForGroup - Existing code/functionality from the old shipment plugin. This updates the cart with one of the selected ff-method from the available quote presented by above mutation.

Queries

• getFulfillmentMethodsWithQuotes - Existing code/functionality from the old shipment plugin. Calls the quote providing functions by collecting them via functionByType. Calls are made only for the specific methods of the provided ff-type.
• getFulfillmentType - returns the ff-type matching the provided ID (NEW)
• getFulfillmentTypes - returns all the ff-types (NEW)
• getFulfillmentMethods - returns all the ff-methods for the specified ff-type (NEW)

Others

• preStartup - extends all impacted schemas mostly with dynamic values for 'allowedValues' (NEW)
• startup - inserts the default 'undecided' entry to the new Fulfillment collection (NEW)
• registration - collects all the "registeredFulfillmentType" from ff-type plugins and adds allRegisteredFulfillmentTypes to context (contextAddition) (NEW)
• util folder - copied over from shipment plugin (Existing code)

API-PLUGIN-FULFILLMENT-TYPE-SHIPPING

• Registers the 'shipping' as a ff-type via registeredFulfillmentTypes: ["shipping"]
• Inserts the default entry for shipping ff-type in Fulfillment collection

API-PLUGIN-FULFILLMENT-TYPE-PICKUP

• Registers the 'pickup' as a ff-type via registeredFulfillmentTypes: ["pickup"]
• Inserts the default entry for pickup ff-type in Fulfillment collection

API-PLUGIN-FULFILLMENT-METHOD-SHIPPING-FLAT-RATE

• Mostly copied over from api-plugin-shipment-flat-rate by making certain fixes to adhere to new structure and new DB collections. Fixes are similar to the details provided for the other 2 ff-method plugins below.
• The mutations & queries present were left as it is and it works slightly differently compared to the new mutations/queries that were introduced in api-plugin-fulfillment (which is used by remaining ff-methods)
• Shipping restrictions feature is copied over from existing code. This feature is not added to other ff-methods.

API-PLUGIN-FULFILLMENT-METHOD-SHIPPING-UPS

• getFulfillmentMethodsWithQuotesShippingUPS - returns the quote or equivalent details for the method when called from base ff plugin
• preStartup - extends the union of "methodAdditionalData" with data structure specific to UPS
• startup - Inserts the required ff-method entry into Fulfillment collection
• util/calculateUPSRate - dummy function to simulate api providing UPS specific info while returning quotes.
• util/ validateOrderMethodsups - dummy function to simulate UPS specific validations done. Called by prepareOrder.js

API-PLUGIN-FULFILLMENT-METHOD-PICKUP-STORE

• getFulfillmentMethodsWithQuotesPickupStore - returns the quote or equivalent details for the method when called from base ff plugin
• preStartup - extends the union of "methodAdditionalData" with data structure specific to Store
• startup - Inserts the required ff-method entry into Fulfillment collection
• util/collectStoreDetails - dummy function to simulate api providing Store specific info while returning quotes.
• util/ validateOrderMethodsstore - dummy function to simulate Store specific validations done. Called by prepareOrder.js

Test cases

With the above changes, we should be able to test the following cases:

1. The current code base has 2 ff-types and 3 ff-methods implemented. We could add more by following the same template (pref type-pickup, method-store). New ff-type should register itself similar to registration.js and insert the base entry in Fulfillment collection. New ff-method should have the functionalities that provide quotes/equivalent with additional data if any, validation results (refer method-store-ups).
2. Use "createCart" endpoint to create a new cart and add an item. If the "selectedFulfillmentType" is provided in the input, a fulfillment group of that ff-type will be created. Else the item will be placed in "undecided" group.
3. More items could be added to the cart using the "addCartItems" endpoint. Here also we could optionally include the "selectedFulfillmentType". All items belonging to one ff-type will be grouped together.
4. We can use endpoint "setFulfillmentTypeForItems" to re-assign the items in "undecided" group to any of the selected ff-group.
5. Use "updateFulfillmentOptionsForGroup" to update the cart with quote details from all available ff-methods for the provided ff-type and then subsequently use "selectFulfillmentOptionForGroup" to select one of them as the selected ff-method for the ff-group.
6. Place the order as usual by providing the "selectedFulfillmentMethodId" for each of the ff-group created. Order should be placed successfully
7. validateOrder endpoint could be used to verify the correctness & completeness of the input to placeOrder prior to actually placing the order.

Pending items

The below pending items will be introduced via separate PR/tickets

• Documentation providing details of the Fulfillment features for a UI team
• i18n feature
• Data migration
• Feature to split order resulting in multiple groups for same ff-type
• Enable default ff-type for products