Orders Management System

This documentation provides a comprehensive overview of the Orders management system within the Nuxt 3 e-commerce B2B application. The system consists of two main composables: useLogisticOrder and useCommercialOrder that handle different aspects of order management throughout the complete order lifecycle.

System Architecture

The Orders system is built around two complementary composables that work together to provide complete order management functionality:

graph TB
    User[User Interface]

    subgraph "Composables Layer"
        ULO[useLogisticOrder]
        UCO[useCommercialOrder]
    end

    subgraph "useLogisticOrder Structure"
        ULOA[useLogisticOrderApi]
        ULOG[useLogisticOrderGetters]
        ULOH[useLogisticOrderHelpers]
    end

    subgraph "useCommercialOrder Structure"
        UCOA[useCommercialOrderApi]
        UCOG[useCommercialOrderGetters]
        UCOH[useCommercialOrderHelpers]
    end

    subgraph "Backend Integration"
        SDK[Djust SDK]
        API[API Routes]
    end

    subgraph "Store Management"
        OS[Order Store - Pinia]
    end

    User --> ULO
    User --> UCO

    ULO --> ULOA
    ULO --> ULOG
    ULO --> ULOH

    UCO --> UCOA
    UCO --> UCOG
    UCO --> UCOH

    ULOA --> SDK
    UCOA --> SDK
    SDK --> API

    ULO --> OS
    UCO --> OS

    style ULO fill:#e1f5fe
    style UCO fill:#f3e5f5
    style SDK fill:#e8f5e8
    style OS fill:#fff3e0

Data Structure Overview

The Orders system manages several key data types and their relationships:

Main Features

1. Commercial Order Management

Commercial orders represent the initial customer order before fulfillment processing:

• Order Creation: Initialize new orders from quotes or direct purchases
• Information Updates: Modify shipping address, billing information, and custom fields
• Status Management: Progress orders through validation stages (DRAFT → CREATED → PROCESSING)
• Payment Integration: Handle payment information and processing workflows

2. Logistic Order Management

Logistic orders handle the fulfillment and shipping aspects of commercial orders:

• Order Tracking: Monitor order progress through fulfillment stages
• Line Management: Handle individual product lines within orders
• Thread Communications: Manage communication threads for order issues and updates
• Status Progression: Track orders through logistic stages (WAITING_SUPPLIER_APPROVAL → WAITING_SHIPMENT → SHIPPED → COMPLETED)

3. Order State Management

stateDiagram-v2
    [*] --> DRAFT
    DRAFT --> CREATED : Validation
    CREATED --> WAITING_SUPPLIER_APPROVAL : Processing
    WAITING_SUPPLIER_APPROVAL --> WAITING_SHIPMENT : Approved
    WAITING_SUPPLIER_APPROVAL --> DECLINED_BY_SUPPLIER : Rejected
    WAITING_SHIPMENT --> SHIPPED : Dispatched
    SHIPPED --> COMPLETED : Delivered
    CREATED --> DECLINED_BY_CUSTOMER : Cancelled

    note right of DECLINED_BY_SUPPLIER : Order rejected by supplier
    note right of DECLINED_BY_CUSTOMER : Order cancelled by customer
    note right of COMPLETED : Order successfully delivered

4. Order Processing Flow

sequenceDiagram
    participant C as Customer
    participant CF as Component (Frontend)
    participant CO as useCommercialOrder
    participant LO as useLogisticOrder
    participant API as Order API
    participant Store as Order Store

    C->>CF: Place Order
    CF->>CO: createCommercialOrder(params)
    CO->>API: POST /api/commercial-orders
    API-->>CO: Commercial Order Created
    CO->>Store: Update Order State

    CO->>LO: Process for Fulfillment
    LO->>API: GET /api/logistic-orders
    API-->>LO: Logistic Orders
    LO->>Store: Store Orders by Status

    Store-->>CF: Reactive State Update
    CF-->>C: Order Confirmation

Key Points

Performance Considerations

• Intelligent Caching: Order requests are cached with unique keys to reduce redundant API calls
• Status-Based Grouping: Orders are organized by status in the store for efficient retrieval
• Lazy Loading: Order details and lines loaded on-demand to optimize initial load times
• Pagination Support: Large order lists support pagination for better performance

Authentication & Data Access

• Mandatory Authentication: All order operations require valid authentication and user session
• Account-Based Access: Orders are filtered by customer account ensuring data isolation
• Permission Validation: Backend validates user permissions for order access and modifications
• Secure State Management: Order data stored securely in Pinia store with proper access controls

Flexibility & Configuration

• Custom Fields Support: Orders support custom business fields for extended functionality
• Multi-Status Tracking: Flexible status system accommodates various business workflows
• Address Management: Separate shipping and billing address handling with snapshot preservation
• Communication Threads: Built-in messaging system for order-related communications

Integration Capabilities

• SDK Abstraction: Clean separation between frontend logic and backend communication
• Type Safety: Full TypeScript support with SDK-generated interfaces
• Composable Architecture: Modular structure allows selective feature usage
• Store Integration: Seamless integration with Pinia store for reactive state management

Best Practices

Order Lifecycle Management

1. Always validate authentication before performing order operations
2. Use appropriate composable - useCommercialOrder for order creation/modification, useLogisticOrder for fulfillment tracking
3. Handle state updates through the store to maintain UI consistency
4. Implement proper error handling for all order operations

Performance Optimization

1. Leverage caching by using the same parameters for repeated requests
2. Group orders by status when displaying large lists
3. Load order details on-demand rather than fetching all data upfront
4. Use pagination for large order collections

Error Handling

1. Implement comprehensive try-catch blocks for all async operations
2. Provide meaningful user feedback for different error scenarios
3. Handle authentication failures with appropriate redirections
4. Log errors appropriately for debugging and monitoring

Conclusion

The Orders management system provides a robust, scalable solution for handling complete order lifecycles in B2B e-commerce applications. The dual composable architecture separates commercial and logistic concerns while maintaining tight integration through shared state management.

For detailed implementation examples and API references, explore the specific documentation files:

• Order Functions - Detailed function documentation
• Types Reference - TypeScript interfaces and types
• Error Handling - Comprehensive error management guide
• Authentication - Authentication integration details