Orders: high-level design

[michaelbromley]

This issue is a discussion of the high-level implementation of Orders

Overview

Orders represent a collection of ProductVariants which a Customer is in the process of purchasing or has purchased.

Prior Art

• https://guides.spreecommerce.org/developer/orders.html
• https://guides.solidus.io/developers/orders/order-state-machine.html
• https://docs.sylius.com/en/1.2/components_and_bundles/components/Order/state_machine.html

Order States

An Order can be thought of as a finite state machine with the following states:

1. AddingItems: The first time a Customer adds a ProductVariant to an order, a new Order entity is created in the "AddingItems" state. A new OrderItem entity is created for each ProductVariant which represents the variant in the given quantity. This state continues until the checkout stage.
2. ArrangingShipping: Once all items are added, the shipping can be arranged. At this stage the shipping destination is set so that the shipping cost may be calculated.
3. ArrangingPayment: Once shipping has been calculated, we know the final cost of the Order and can arrange payment. At this point the order details can be sent to a payment provider. This state can be skipped if the order total is 0.
4. OrderComplete: Payment has been received and the order is completed.
5. Cancelled: A completed order may be cancelled after it is placed.

User-defined states

It would be useful to allow the developer to define additional states for the Order to match the particular business requirements of the shop. I'll look for existing FSM libs to see if this can be accommodated in a safe and intuitive manner.

Transition Hooks

When transitioning from one state into another, one or more functions can be called to execute some logic before the transition is made, and possibly also have the opportunity to stop the transition.

For example, when an Order transitions from "ArrangingPayment" to "Completed", a hook could generate and send a transactional email confirming the order.

Cost Calculation

The cost of an order must take into account the following factors:

1. The price of the ProductVariant * quantity for each OrderItem
2. Taxes applied to each OrderItem
3. Adjustments applied to each OrderItem (e.g. promotional discounts - buy 1 get one free)
4. Adjustments applied to the entire order (e.g. promotional discounts - £5 off order with voucher code)
5. Shipping costs (which is another type of Adjustment)

[michaelbromley]