[OrderRefactor][Order][Checkout] Fulfill Checkout information

[nashtech-vietvuhoang1]

After creating the Checkout object (ticket #1105),
The Storefront will:

• Get all payment methods from Payment Service
  • Service: Payment Service
  • API GET /methods
• Get all shipment methods from Delivery Service
  • Service: Delivery Service
  • API GET /providers
• Get Customer Addresses from Customer Service
  • Service: Customer Service
  • API GET /profile/addresses

The Storefront will display on UI and The Customer will use Storefront to enter following information:

• Payment methods to Checkout Object PUT /order/checkouts/{checkout_id}/payment { payment_method }
• Promotion Code to apply to the Checkout PUT /order/checkouts/{checkout_id}/promocode { promocode }
• When receiving the Promotion Code, Order Service will call to Promotion Service to verify the Promotion Code
• Delivery method to Checkout Object PUT /order/checkouts/{checkout_id}/shipment { shipment_provider }
• Shipping Address to Checkout Object PUT /order/checkouts/{checkout_id}/address { shipment_address }
  • When Delivery method and Shipping Address are fulfilled, Order Service will call to Delivery Service to update Shipping Cost to update to Checkout Items
• Storefront will call API GET /order/checkouts/{checkout_id} to get Checkout Information, if Product Price, Tax, Shipment fee, discount are fulfilled, Storefront will display "Proceed to Payment" button

Checkout Flow

[duylv27]

API Design

View

openapi: 3.0.0
info:
  title: Orders API
  description: API for managing Checkout adn Orders
  version: 1.0.0
servers:
  - url: http://localhost:8080
    description: Local server
paths:
  /checkouts:
    post: 
      summary: Create a new checkout
      operationId: createCheckout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Checkout'
      responses:
        '201':
          description: Checkout created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout'

  /checkouts/{id}:
    get: 
      summary: get Checkout By Id
      operationId: getCheckoutById
      parameters:
        - name: id
          in: path
          description: The checkout id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Checkout'
      responses:
        '200':
          description: Checkout Information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout'
  /checkouts/{id}/payment:
    put:
      summary: Update Payment Method
      operationId: updatePaymentMethod
      parameters:
        - name: id
          in: path
          description: The checkout id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paymentMethodId:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Checkout Information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout'
  /checkouts/{id}/promocode:
    put:
      summary: Update Promotion Code
      operationId: updatePromotionCode
      parameters:
        - name: id
          in: path
          description: The checkout id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                promocode:
                  type: string
      responses:
        '200':
          description: Checkout Information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout'
  /checkouts/{id}/shipment:
    put:
      summary: Update Shipment Provider
      operationId: updateShipmentProvider
      parameters:
        - name: id
          in: path
          description: The checkout id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                providerId:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Checkout Information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout'
  /checkouts/{id}/address:
    put:
      summary: Update Shipment Address
      operationId: updateShipmentAddress
      parameters:
        - name: id
          in: path
          description: The checkout id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                addressId:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Checkout Information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout'

components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: SESSION
  schemas:
    Checkout:
      type: object
      properties:
        id:
          type: string
          format: uuid
        customerId:
          type: string
          format: uuid
        promotionCode: 
          type: string
        shipmentMethodId:
          type: string
          format: uuid
        paymentMethodId:
          type: string
          format: uuid
        shipmentAddressId:
          type: string
          format: uuid
        last_error: 
          type: object
        status:
          type: string
          enum: [CHECKED_OUT, PAYMENT_PROCESSING, PAYMENT_CONFIRMED, FULFILLED]
        totalAmount:
          type: number
          format: numeric(12, 4)
        totalTax:
          type: number
          format: numeric(12, 4)
        totalShipmentFee:
          type: number
          format: numeric(12, 4)
        totalShipmentTax:
          type: number
          format: numeric(12, 4)
        totalDiscountAmount:
          type: number
          format: numeric(12, 4)
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        createAt: 
          type: string
          format: date-time
        createBy:
          type: string
          format: uuid
        lastUpdateAt:
          type: string
          format: date-time
        lastUpdateBy:
          type: string
          format: uuid  
    Item:
      type: object
      required:
        - checkoutId
        - productId
        - quantity
      properties:
        checkoutId:
          type: string
          format: uuid
        productId:
          type: string
          format: uuid
        name: 
          type: string
        description:
          type: string
        shortDescription:
          type: string
        quantity:
          type: integer
          format: int64
        price:
          type: number
          format: float
        tax:
          type: number
          format: float
        shipment_fee:
          type: number
          format: numeric(12, 4)
        shipment_tax:
          type: number
          format: numeric(12, 4)
        discount_amount:
          type: number
          format: numeric(12, 4)
        status:
          type: string
        createAt: 
          type: string
          format: date-time
        createBy:
          type: string
          format: uuid
        lastUpdateAt:
          type: string
          format: date-time
        lastUpdateBy:
          type: string
          format: uuid 
security:
  - cookieAuth: []

[mochacr0]

Task Breakdown

• Address:
  • [OrderRefactor][Checkout] Fulfill Checkout Information - Address Selection #1176
• Payment:
  • [Order Refactor][Step 1] Get all payment methods from Payment Service #1171
• Delivery:
• Promotion:
• Checkout:

---

View

API

1. Address Selection API:

Implement an API to allow buyers to select their billing and shipping address IDs. The selected addresses should be validated before being saved to the checkout object.

2. Payment Method Selection API:

Update the existing payment method selection API to include validation of the chosen payment method before saving it. The API should verify the payment method’s validity.

3. Promotion Code Selection API:

Implement an API for buyers to select a promotion code to their checkout. Utilize the existing promotion code verification API to check if the code is valid, has not expired, and is applicable to the current order.

UI

1. Pre-create Addresses for Selection:

Modify the checkout flow so that users are required to create and save their shipping and billing addresses before selecting them during checkout. Currently, these addresses are only created after the "Proceed to Payment" button is clicked. This change should allow users to create and select their addresses in during the checkout process before moving forward.

2. Get Shipping Providers, Select Service ID & Validate:

Since delivery services are not yet implemented, mock the shipping provider options on the UI. Once selected, validate the chosen shipping service to ensure compatibility with the order (e.g., availability for the delivery address).

3. UI Adjustments for Address, Payment Method & Promocode Selection:

Review the UI components for address, payment method and promocode selection and update the UI to ensure alignment with the new APIs (if needed).

4. Fee Calculation UI:

After the user has provided all required checkout information (address, payment method, shipping provider, etc.), the UI should call the "calculate fee" API from the delivery module to estimate shipping costs and delivery times. Similar to other delivery APIs, this will initially be mocked.

[khanhduzz]

[Updated 15/11] General updated diagram for fulfill checkout with API

(Scroll down to see the latest update)
Green: Existed API - Consider rename it if need

[ General workflow ]

• User in the Cart page -> click the Process to checkout -> redirect to Checkout page with all the information is loaded
• User is able to select information about: Payment method, Shipment provider, Address (Shipping address, Billing address), Coupon code.
• Each time a attribute selected -> trigger API to call Order Service to update the Checkout information
• When have enough information -> user is able to Payment

[ Order Service ]:

• Each time get call from Storefront -> Validate the data, then update the Checkout -> return Checkout to Storefront
• When have the Address -> trigger extra call to Tax Service to take the Tax rate -> update Checkout
• When have Address and Shipping provider -> trigger extra call to Delivery Service -> get fees for delivery -> update Checkout

[Updated 19/11] More specific diagram

[ Update: ]

• Added the delivery flow in previous design to this new
• The coupon code now needs to be verified with the delivery method/provider. Currently, the flow only checks the coupon code against the total price, but it should be enhanced later
• Use delivery instead of shipment