feat(docs): Add docs on orders workflow

docs/content/docs/developer-guide/order-workflow/_index.md

@@ -0,0 +1,38 @@
+---
+title: "Order Workflow"
+showtoc: true
+---
+
+# Order Workflow
+
+An Order is a collection of one or more ProductVariants which can be purchased by a Customer. Orders are represented internally by the [Order entity]({{< relref "order" >}}) and in the GraphQL API by the [Order type]({{< relref "/docs/graphql-api/shop/object-types#order" >}}).
+
+## Order State
+
+Every Order has a `state` property of type [`OrderState`]({{< relref "order-state" >}}). The following diagram shows the default states and how an Order transitions from one to the next.
+
+{{< figure src="./order_state_diagram.png" >}}
+
+## Structure of an Order
+
+In Vendure an [Order]({{< relref "order" >}}) consists of one or more [OrderLines]({{< relref "order-line" >}}) (representing a given quantity of a particular SKU), which in turn contain one or more [OrderItems]({{< relref "order-item" >}}) (which represent the individual physical units). 
+
+Here is a simplified diagram illustrating this relationship:
+
+{{< figure src="./order_class_diagram.png" >}}
+
+So if the customer adds 2 *Widgets* to the Order, there will be **one OrderLine** containing **two OrderItems**, one for each of the added *Widgets*.
+
+## Shop client order workflow
+
+The following is a description of the flow and related GraphQL operations which are used when dealing with Orders in a customer-facing client application (i.e. a storefront).
+
+1. [`activeOrder` query]({{< relref "/docs/graphql-api/shop/queries#activeorder" >}}) returns the currently-active Order for the session.
+* [`addItemToOrder` mutation]({{< relref "/docs/graphql-api/shop/mutations#additemtoorder" >}}) adds an item to the order. The first time it is called will also create a new Order for the session.
+* [`adjustOrderLine` mutation]({{< relref "/docs/graphql-api/shop/mutations#adjustorderline" >}}) is used to adjust the quantity of an OrderLine.
+* [`removeOrderLine` mutation]({{< relref "/docs/graphql-api/shop/mutations#removeorderline" >}}) removes an OrderLine from the Order.
+* [`setCustomerForOrder` mutation]({{< relref "/docs/graphql-api/shop/mutations#setcustomerfororder" >}}) specifies the Customer details (required if the customer is not logged in as an authenticated user).
+* [`setOrderShippingAddress` mutation]({{< relref "/docs/graphql-api/shop/mutations#setordershippingaddress" >}}) sets the shipping address for the Order.
+* [`eligibleShippingMethods` query]({{< relref "/docs/graphql-api/shop/queries#eligibleshippingmethods" >}}) returns all available shipping methods based on the customer's shipping address and the contents of the Order.
+* [`setOrderShippingMethod` mutation]({{< relref "/docs/graphql-api/shop/mutations#setordershippingmethod" >}}) sets the shipping method to use.
+* [`addPaymentToOrder` mutation]({{< relref "/docs/graphql-api/shop/mutations#addpaymenttoorder" >}}) adds a payment to the Order. If the payment amount equals the order total, then the Order will be transitioned to either the `PaymentAuthorized` or `PaymentSettled` state (depending on how the payment provider is configured) and the order process is complete from the customer's side.

docs/diagrams/order-class-diagram.puml

@@ -0,0 +1,38 @@
+@startuml
+!include theme.puml
+title Vendure Order Class Diagram
+
+enum OrderState {
+    AddingItems
+    ArrangingPayment
+    PaymentAuthorized
+    ...
+}
+
+class Order {
+    state: OrderState
+    lines: OrderLine[]
+    subTotal: number
+    shipping: number
+    total: number
+}
+
+class OrderLine {
+    quantity: number
+    unitPrice: number
+    quantity: number
+    totalPrice: number
+    productVariant: ProductVariant
+    items: OrderItem[]
+}
+
+class OrderItem {
+    unitPrice: number
+    taxRate: number
+}
+
+Order -- OrderState
+Order *-- "0..*" OrderLine
+OrderLine *-- "0..*" OrderItem
+
+@enduml

docs/diagrams/order-state-diagram.puml

@@ -2,27 +2,64 @@
 !include theme.puml
 title Order State Diagram
 
-[*] --> AddingItems: AddProductVariantToOrder
-AddingItems: Customer is adding items to order
-AddingItems: All non-shipping Adjustments get applied here
+state ShopAPI {
+    [*] --> AddingItems: addItemToOrder
+    state AddingItems {
+        AddingItems: Customer adds items to the order
+        AddingItems: Customer details are set
+        AddingItems: Shipping destination is set
+        AddingItems: Shipping method is selected
+    }
 
-AddingItems --> ArrangingShipping:Next
-ArrangingShipping: Shipping destination is set
-ArrangingShipping: Shipping Adjustment added to Order
+    state ArrangingPayment {
+        ArrangingPayment: Payment provider is used to take payment
+    }
+}
 
-ArrangingShipping --> AddingItems:Previous
-ArrangingShipping --> ArrangingPayment:Next
-ArrangingPayment: Payment provider is used to take payment
+state AdminAPI {
+    state PaymentAuthorized {
+        PaymentAuthorized: The payment has been authorized by the
+        PaymentAuthorized: payment provider.
+    }
 
-ArrangingPayment --> ArrangingShipping:Previous
-ArrangingPayment --> OrderComplete:Next
-OrderComplete: Order is complete and ready to be processed
+    state PaymentSettled {
+        PaymentSettled: The payment has been settled with the payment
+        PaymentSettled: provider, i.e. the transaction is complete.
+    }
 
-OrderComplete --> Cancelled:Cancel
-Cancelled: Customer or Admin cancelled the order
+    state PartiallyFulfilled {
+        PartiallyFulfilled: One or more OrderItems have been dispatched to the Customer
+    }
+
+    state Fulfilled #9d9 {
+        Fulfilled: All OrderItems have been dispatched to the Customer
+    }
+
+
+    state Cancelled #d99 {
+        Cancelled: All OrderItems in the Order have been cancelled
+    }
+    Cancelled --> [*]
+
+    Fulfilled --> [*]
+}
+
+
+AddingItems --> ArrangingPayment: transitionOrderToState
+ArrangingPayment --> AddingItems: transitionOrderToState
+ArrangingPayment --> PaymentAuthorized: addPaymentToOrder
+ArrangingPayment -----> PaymentSettled: addPaymentToOrder
+PaymentAuthorized --> PaymentSettled: settlePayment
+PaymentSettled --> Fulfilled: fulfillOrder
+PaymentSettled --> PartiallyFulfilled: fulfillOrder
+PartiallyFulfilled --> PartiallyFulfilled: fulfillOrder
+PartiallyFulfilled --> Fulfilled: fulfillOrder
+
+PaymentAuthorized --> Cancelled: cancelOrder
+PaymentSettled --> Cancelled: cancelOrder
+PartiallyFulfilled --> Cancelled: cancelOrder
+Fulfilled --> Cancelled: cancelOrder
 
-Cancelled --> [*]
 
-OrderComplete --> [*]
 
 @enduml