Order process documentation

.gitignore

@@ -29,3 +29,6 @@ hs_err_pid*
 .settings*
 .vscode
 *.iml
+out
+out/**
+*.bkp

docs/design/order-flows/README.md

@@ -0,0 +1,83 @@
+# Order Processing flow
+
+## Overview
+
+![Order Flow overview](./imgs/orders.drawio.png)
+
+*Checkout* will be created based on the product items on *Shopping Cart*.
+
+*Order* will be created based on the *Checkout*.
+
+**Design choice notes:** 
+- We decided to create an *Order* only after *Payment* for it has been confirmed. By doing this, the fulfilment cycle can be started immediately after an *Order* has been created, minimizing possible confusion later on.
+## Checkout Flow
+
+### Checkout Lifecycle
+![Checkout Lifecycle](./imgs/Checkout%20Lifecycle.png)
+
+When the user begins the checkout process, the `Checkout` object is created by copying all products the user wants to purchase with their desired quantities, allowing the user to focus on making the decision to place an order. The `Checkout` object will also contains information collected before the order is placed.
+ - It will be created with the `CHECKED_OUT` status when the user start the checkout process by clicking the *"Proceed to checkout"* button on the *Cart page*. At this stage, the `Checkout` object will only contains the products' types and quantities that the customer wants to order.
+ - The customer will then update the `Checkout` object with their desired shipping address, shipping provider, and payment method information. 
+ - After all the information required has been fulfilled and reflects the customer desired order, the payment amount with detailed breakdown can be calculated and review by the customer after which they can confirm, and start the payment process. This will change that state of the `Checkout` object to `PAYMENT_PROCESSING`.
+ - After the payment has been processed and confirmed by the `payment-confirmed` action, the `Checkout` object will be changed to the `PAYMENT_CONFIRMED` state. At this stage, the system can start the `create-order` process, which will place the necessary block on the inventory, and create a new order for the customer.
+ - In case some products in the `Checkout` object is out-of-stock or the `process-payment` action encounters an error, the `Checkout` object's status will be revert back to `CHECKED_OUT`. The last encountered error will also be attached to the `Checkout` object
+ - After an order has been placed, the `Checkout` has served its purpose, thus its state will be changed to `FULFILLED`. 
+
+### Checkout flow
+
+![Checkout Flow](./imgs/Checkout%20Flow.png)
+The Checkout flow happens between when the user begin the checkout process and the start of the payment process. This process includes:
+- User start this process by navigating to the *Cart page* and click on *"Proceed to check out"* after choosing all the desired items and their amount. The system will start the checkout process by creating a `Checkout` object by copying the user's current cart and then clear the cart. 
+- The system then prompt the user for additional information that is necessary for the order placing process. This includes showing the customer available shipping provider, payment provider, their address saved by the system, as well as a form for customer to input a new address should they need to.
+- The user will then input the requested information into the system and continually update their `Checkout` object. After all the necessary information for the object has been inputed, an event to calculate total order amount, delivery fee, and tax amount will be triggered and the result will be displayed to the customer.
+- The user can also input a promocode into the checkout, which will trigger a validation event to validate the code. If the promocode is valid, it will be added to the `Checkout` object and trigger a CDC Event to recalculate the payment amount and return the new total to `Storefront` to be displayed.
+- The user can iteratively change their order information at this step. After each change, the order amount, delivery fee, and tax amount will be recalculated and displayed to them.  
+- After the customer is satisfied with all their information, they will confirm by clicking *"Proceed to payment"* at which point the system will start the payment process for the order.
+
+### Payment flow
+
+![Payment Flow](./imgs/Payment%20Flow.png)
+
+The payment flow is the point at which the customer confirm their payment for the order so that the system can place their order and start the fulfilment cycle. This process can be divided into 3 phases including:
+
+![Payment Flow Sub 1](./imgs/Payment%20Flow%20Sub%201.png)
+
+- The first phase's goal is to create an internal `PaymentCheckout` object that will keep track of the payment status for the order. This phase includes the following steps:
+  - The Customer will start this phase by clicking *"Proceed to payment"* on the *Checkout page*. This will send a request to start the payment process to the `Order Service`. 
+  - The `Order Service` will then send a request to `Promotion Service` to create a usage of the promocode in the checkout (if exists). If this step fail then the payment flow will fail and the `Checkout` object will go back to the previous stage. The promocode will also be automatically removed from the `Checkout` object.
+  - The `Order Service` will then request the `Inventory service` to place a reservation on the products requested in the `Checkout` object.
+  - In case the reservation process fail due to some products being out of stock, the `Inventory Service` will return the error to the `Order Service` which will forward it to `Storefront`. The `Storefront` will then notified the Customer and stop the payment process. If the promocode was applied previously, it will also be rollbacked by an asynchronous event.
+  - If the reservation process succeed, the `Order Service` will trigger the creation of a `CheckoutPayment` object which will be managed by the `Payment Service`. Information about this object will be send back to the `Storefront` page which marks the end of phase 1. At the end of this phase, a `CheckoutPayment` object for the order must have been created.
+
+![Payment Flow Sub 2](./imgs/Payment%20Flow%20Sub%202.png)
+- The second phase of the payment process will concern the communication with the external payment provider and creating a `Checkout` object on their server to serve as a basis for the Payment process. This phase includes the following steps:
+    - The creation of an internal `CheckoutPayment` object will be captured with a CDC event which will trigger the start of this phase.
+    - If the created `CheckoutPayment`'s `payment_type` is not `COD` and its `status` is `NEW`, the `Payment Service` will then contact the external payment provider to create a Checkout object on their server with a reference id which will be sent back to the `Payment Service`.
+    - The `Payment Service` will then update this id into the `CheckoutPayment` object and change its status to `PROCESSING`.
+    - At the end of this stage, the `CheckoutPayment` object status need to be changed to `PROCESSING`, and in case `payment_type` is not `COD`, the `CheckoutPayment` object should contains the external payment provider's `Checkout`'s id.
+
+![Payment Flow 3](./imgs/Payment%20Flow%20Sub%203.png)
+- The final phase of the payment process will concern the payment completion and placing order into our system. This phase includes the steps below:
+  - After receiving the `CheckoutPayment` object id from phase 1, the `Storefront` page will periodically query the `Payment Service` for the status of the `CheckoutPayment` object. This will be repeated until the `CheckoutPayment`'s status changed to `PROCESSING`.
+  - The `Storefront` page will then navigate the user to the external payment provider payment page using the provided external payment provider's `Checkout` object's id. The customer can execute the payment on the external provider page.
+  - After the payment has been processed by the external provider, they will navigate the customer back to the *Payment confirmation page* of our `Storefront`. 
+  - At the same time, the external payment provider will also notify our `Backend` through a webhook registered to them. This webhook will then trigger the `Payment Completed` chain in our system, change the `CheckoutPayment` object status to `PAYMENT_COMPLETED`, notify the customer and create an `Order` object with the `PAYMENT_CONFIRMED` status in our system. After the `Order` is created, the items that has been placed in the order is then removed from the `Shopping Cart`.
+  - After this phase, an `Order` object must be created in our system. This object will be the starting point for the order fulfilment cycle.
+- After the `Order` object has been created, we will send a notification to the customer, then the `Storefront` can request and display the `Order` info to Customer.
+
+## Order Processing
+
+The Order will be created after the payment processed is finished and will be the entry point for the fulfilment cycle.
+
+### Order Lifecycle
+
+![Order Lifecycle](./imgs/Order%20Lifecycle.png)
+
+- After the payment has been confirmed for the order by the `Payment Service`, an `Order` with `PAYMENT_CONFIRMED` status will be created from the relevant `Checkout` object . 
+- At this point, the warehouse workers can trigger the action `prepare-parcel` after the have package the order items, which will change the order status to `READY_TO_SHIP`, at which point the desired delivery provider can be contacted to come and pick up the parcel
+- After the parcel has been picked up, the action `ship-parcel` will be triggered and the `Order`'s state will be changed to `SHIPPED`.
+- When the shipper reach the destination, they can trigger the action `deliver-parcel`, which will change the `Order`'s status to `RECEIVED`, at which point the customer can trigger the `confirm-receipt` action and change the `Order`'s status to `CONFIRMED`, which completes the order.
+- During the shipping process (when the order is at the `SHIPPED` state), the shipper can also trigger the `report-failure` action, which will change the order status to `SHIPMENT_FAILED` and start the refund process to refund the payment to the customer.
+- At any point before the `Order` reached the `RECEIVED` state, the customer can trigger the `cancel` action, which will notify the shop of their cancel request and change the `Order` state to `CANCEL_REQUESTED`.
+- At this point, the shop will start the `refund` action and start the refunding process as well as recollect the shipment as required.
+- After the `refund-confirm` action triggered to confirm that the refund process has finished, the order status will be changed to `CANCELLED`. 

docs/design/order-flows/diagrams/YAS.drawio

@@ -0,0 +1,61 @@
+<mxfile host="Electron" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/24.7.8 Chrome/128.0.6613.36 Electron/32.0.1 Safari/537.36" version="24.7.8">
+  <diagram id="q6kRX4-M01hZTGkx8Dg6" name="OrderFlow">
+    <mxGraphModel dx="1420" dy="822" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="0" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="0NfagcmIJmzYptjgjSYn-4" value="Check-out" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" parent="1" source="0NfagcmIJmzYptjgjSYn-2" target="rPNVTWdC8MnqqpMeGFjJ-1" edge="1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="0NfagcmIJmzYptjgjSYn-3" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=none;strokeColor=#d6b656;strokeWidth=2;" parent="1" vertex="1">
+          <mxGeometry x="250" y="100" width="350" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="0NfagcmIJmzYptjgjSYn-2" value="" style="verticalLabelPosition=bottom;shadow=0;dashed=0;align=center;html=1;verticalAlign=top;strokeWidth=1;shape=mxgraph.mockup.misc.shoppingCart;strokeColor=#d79b00;fillColor=#ffe6cc;" parent="1" vertex="1">
+          <mxGeometry x="110" y="115" width="50" height="50" as="geometry" />
+        </mxCell>
+        <mxCell id="0NfagcmIJmzYptjgjSYn-6" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;fillColor=#f5f5f5;strokeColor=#666666;endArrow=none;endFill=0;dashed=1;" parent="1" source="0NfagcmIJmzYptjgjSYn-5" edge="1">
+          <mxGeometry relative="1" as="geometry">
+            <mxPoint x="225" y="140" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="0NfagcmIJmzYptjgjSYn-5" value="&lt;h1 style=&quot;margin-top: 0px;&quot;&gt;&lt;font style=&quot;font-size: 16px;&quot;&gt;Check out&lt;/font&gt;&lt;/h1&gt;&lt;p&gt;&lt;span style=&quot;background-color: initial;&quot;&gt;- Create Checkout Object from Shopping Cart&lt;/span&gt;&lt;/p&gt;" style="text;html=1;whiteSpace=wrap;overflow=hidden;rounded=0;fillColor=#f5f5f5;fontColor=#333333;strokeColor=none;" parent="1" vertex="1">
+          <mxGeometry x="150" y="240" width="150" height="120" as="geometry" />
+        </mxCell>
+        <mxCell id="0NfagcmIJmzYptjgjSYn-7" value="Order" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontStyle=1" parent="1" vertex="1">
+          <mxGeometry x="680" y="120" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="rPNVTWdC8MnqqpMeGFjJ-6" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;dashed=1;strokeColor=#666666;align=center;verticalAlign=middle;fontFamily=Helvetica;fontSize=11;fontColor=default;labelBackgroundColor=default;endArrow=none;endFill=0;fillColor=#f5f5f5;" edge="1" parent="1" source="0NfagcmIJmzYptjgjSYn-9">
+          <mxGeometry relative="1" as="geometry">
+            <mxPoint x="635" y="140" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="0NfagcmIJmzYptjgjSYn-9" value="&lt;h1 style=&quot;margin-top: 0px;&quot;&gt;&lt;font style=&quot;font-size: 16px;&quot;&gt;Place Order&lt;/font&gt;&lt;/h1&gt;&lt;p&gt;- Create &lt;b&gt;Order &lt;/b&gt;with Payment Info and Delivery Info&lt;br&gt;- Update Shopping Cart&lt;/p&gt;" style="text;html=1;whiteSpace=wrap;overflow=hidden;rounded=0;fillColor=#f5f5f5;fontColor=#333333;strokeColor=none;" parent="1" vertex="1">
+          <mxGeometry x="560" y="240" width="150" height="120" as="geometry" />
+        </mxCell>
+        <mxCell id="rPNVTWdC8MnqqpMeGFjJ-3" value="Proceed&lt;br&gt;to Payment" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="rPNVTWdC8MnqqpMeGFjJ-1" target="rPNVTWdC8MnqqpMeGFjJ-2">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="rPNVTWdC8MnqqpMeGFjJ-1" value="CHECKED-OUT" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">
+          <mxGeometry x="270" y="120" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="rPNVTWdC8MnqqpMeGFjJ-4" value="Place Order" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="rPNVTWdC8MnqqpMeGFjJ-2" target="0NfagcmIJmzYptjgjSYn-7">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="rPNVTWdC8MnqqpMeGFjJ-2" value="PAYMENT-CONFIRMED" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;" vertex="1" parent="1">
+          <mxGeometry x="470" y="120" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="rPNVTWdC8MnqqpMeGFjJ-10" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;dashed=1;strokeColor=#666666;align=center;verticalAlign=middle;fontFamily=Helvetica;fontSize=11;fontColor=default;labelBackgroundColor=default;endArrow=none;endFill=0;fillColor=#f5f5f5;" edge="1" parent="1" source="rPNVTWdC8MnqqpMeGFjJ-7">
+          <mxGeometry relative="1" as="geometry">
+            <mxPoint x="435" y="140" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="rPNVTWdC8MnqqpMeGFjJ-7" value="&lt;h1 style=&quot;margin-top: 0px;&quot;&gt;&lt;font style=&quot;font-size: 16px;&quot;&gt;Payment&lt;/font&gt;&lt;/h1&gt;&lt;p&gt;- Lock Innventory&lt;br&gt;- Process Payment with Payment Provider&lt;/p&gt;" style="text;html=1;whiteSpace=wrap;overflow=hidden;rounded=0;fillColor=#f5f5f5;fontColor=#333333;strokeColor=none;" vertex="1" parent="1">
+          <mxGeometry x="360" y="240" width="150" height="120" as="geometry" />
+        </mxCell>
+        <mxCell id="rPNVTWdC8MnqqpMeGFjJ-8" value="&lt;b&gt;Checkout&lt;/b&gt;" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="360" y="98" width="110" height="24" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>