Unique Order Code Generation
Relevant source files
The following files were used as context for generating this wiki page:
The Unique Order Code Generation system is a core component responsible for creating a unique, human-readable identifier for every new order placed in the application. This system ensures that each order can be tracked and referenced consistently throughout its lifecycle. The generated code follows a specific format, combining a static prefix, the current date, and a sequential counter, making it both unique and sortable by date.
The generation logic is encapsulated within the static OrderCodeGenerator class, which is invoked during the order creation process handled by the OrderController. The generated code is then stored in the OrderCode property of the Order entity in the database.
Core Component: OrderCodeGenerator
The central piece of this feature is the OrderCodeGenerator, a static class designed to produce unique order codes in a thread-safe manner.
Sources: Service/OrderCodeGenerator.cs
Class Structure
The OrderCodeGenerator is a simple static class with no dependencies. It maintains a private static counter and a lock object to ensure thread safety when multiple orders are created concurrently.
This diagram shows the static structure of the OrderCodeGenerator class.
Sources: Service/OrderCodeGenerator.cs:9-12
Generation Logic
The GenerateOrderCode method is the sole public method. It constructs the order code using the following format: ORD<yyyyMMdd><####>.
- Prefix: A static string
ORD. - Date String: The current date formatted as
yyyyMMdd. - Counter: A 4-digit, zero-padded sequential number that increments with each call.
To prevent race conditions, the entire logic block is wrapped in a lock statement. The counter is reset to 0 if it exceeds 9999, allowing for up to 10,000 orders per day before a potential (though highly unlikely) reuse on the same day.
// Service/OrderCodeGenerator.cs:14-24
public static string GenerateOrderCode()
{
lock (lockObject)
{
// Reset counter nếu đạt tới 9999
if (counter > 9999) counter = 0;
string dateString = DateTime.Now.ToString("yyyyMMdd");
string counterString = (++counter).ToString("D4");
return $"ORD{dateString}{counterString}";
}
}
Sources: Service/OrderCodeGenerator.cs:14-24
The following flowchart illustrates the process within the GenerateOrderCode method.
This flowchart shows the step-by-step logic for generating a new order code.
Sources: Service/OrderCodeGenerator.cs:14-24
Integration in Order Creation Flow
The OrderCodeGenerator is utilized exclusively within the OrderController when a new order is created via the POST /api/v1/order endpoint.
Sources: Controllers/Order/OrderController.cs
API Endpoint and Data Flow
When a client sends a POST request to /api/v1/order with order details, the CreateOrder action in OrderController is triggered. Inside this action, a new Order object is instantiated. The OrderCode property of this new object is populated by calling OrderCodeGenerator.GenerateOrderCode(). The complete Order object is then passed to the OrderService to be persisted in the database.
The sequence diagram below illustrates this interaction.
This diagram shows the sequence of calls during the creation of a new order, highlighting when the order code is generated.
Sources: Controllers/Order/OrderController.cs:23-57, Service/OrderCodeGenerator.cs:14-24, Service/order/OrderService.cs:44-48, Dtos/CreateOrderRequest.cs
Data Model and Database Schema
The generated OrderCode is stored as a property on the Order model and persisted in the Orders table in the database.
Order Entity
The Order class defines the structure of an order, including the OrderCode property.
Sources: Models/Order.cs
// Models/Order.cs:7-9
public class Order
{
public int OrderID { get; set; } // Khóa chính
public string OrderCode { get; set; } //
// ... other properties
}
Database Configuration
The Entity Framework Core configuration for the Order entity specifies constraints for the OrderCode column in the database. It is defined as a string with a maximum length of 100 characters.
| Property | Type | Constraints | Description |
|---|---|---|---|
OrderID | int | Primary Key, Required | The unique identifier for the order. |
OrderCode | string | HasMaxLength(100) | The generated unique code for the order. |
CustomerID | int | Foreign Key, Required | ID of the customer who placed the order. |
TotalAmount | decimal(18,2) | Required | The total cost of the order. |
OrderDate | DateTime | Required, DefaultValueSql("GETDATE()") | The date and time the order was placed. |
Status | string | Required, HasMaxLength(50) | The current status of the order. |
Table data derived from Configuration/OrderConfiguration.cs:15-23 and Migrations/UserDBContextModelSnapshot.cs:92-126.
The relationship between the Order, OrderItem, and User (Customer) entities is shown below.
This ER diagram illustrates how the ORDER table, containing the OrderCode, relates to users and order items.
Sources: Models/Order.cs, Models/OrderItem.cs, Migrations/UserDBContextModelSnapshot.cs
Conclusion
The Unique Order Code Generation system is a simple yet critical feature that provides a reliable mechanism for identifying orders. By using a thread-safe, date-stamped, and sequential approach, the OrderCodeGenerator ensures that every order receives a unique and meaningful identifier upon creation. This code is integral to the system, used for tracking, customer communication, and administrative purposes, and is seamlessly integrated into the order creation API endpoint.