Order Management API

Relevant source files

The following files were used as context for generating this wiki page:

• Controllers/Order/OrderController.cs
• Service/order/IOrderService.cs
• Service/order/OrderService.cs
• Dtos/CreateOrderRequest.cs
• Dtos/UpdateOrderRequest.cs
• Models/Order.cs
• Models/OrderItem.cs
• Configuration/OrderConfiguration.cs
• Configuration/OrderItemConfiguration.cs
• Program.cs
• Migrations/UserDBContextModelSnapshot.cs

The Order Management API provides a set of RESTful endpoints for creating, retrieving, updating, and deleting orders within the application. It follows a standard layered architecture, separating concerns between the controller, service, and data access layers. This system is responsible for handling all order-related operations, including managing order details, associated items, and status updates.

The core components include the OrderController which exposes the API endpoints, the IOrderService and its implementation OrderService which contain the business logic, and the data models (Order, OrderItem) which represent the database entities. The API interacts with the database through Entity Framework Core, using a UserDBContext.

Architecture

The Order Management feature is built on a dependency injection pattern. The IOrderService is registered as a scoped service and injected into the OrderController. This decouples the web layer from the business logic, allowing for easier maintenance and testing.

Sources: Program.cs:33, Controllers/Order/OrderController.cs:15-19

The following diagram illustrates the high-level component architecture.

API Endpoints

The API endpoints for order management are defined in OrderController under the base route api/v1/order.

Sources: Controllers/Order/OrderController.cs:13

Method	Route	Description	Request Body
POST	/	Creates a new order. A unique OrderCode is generated automatically.	CreateOrderRequest
GET	/	Retrieves a list of all orders, including their items, products, and customer details.	N/A
GET	/{id}	Retrieves a single order by its OrderID.	N/A
GET	/user/{CustomerID}	Retrieves all orders for a specific customer.	N/A
PUT	/{id}	Fully updates an existing order by its OrderID.	UpdateOrderRequest
PATCH	/{id}	Partially updates an order's status, address, and delivery method.	UpdateOrderStatusRequest
DELETE	/{id}	Deletes an order by its OrderID.	N/A

Sources: Controllers/Order/OrderController.cs:21-131

Data Models and Schema

The order system relies on two primary data models: Order and OrderItem. These are configured using Entity Framework Core's Fluent API.

Entity Relationship Diagram

This diagram shows the relationships between the User, Order, OrderItem, and Product entities.

Order Model

The Order model represents a single customer order.

Sources: Models/Order.cs

Property	Type	Constraints	Description
OrderID	int	Primary Key	Unique identifier for the order.
OrderCode	string	MaxLength(100)	A unique, generated code for the order.
CustomerID	int	Required, Foreign Key to User	The ID of the customer who placed the order.
TotalAmount	decimal	Required, decimal(18,2)	The total cost of the order.
OrderDate	DateTime	Required, Default GETDATE()	The date and time the order was placed.
DeliveryMethod	string?	MaxLength(50)	The chosen method for delivery.
PaymentMethod	string?	MaxLength(50)	The chosen method for payment.
Address	string	Required, MaxLength(200)	The delivery address.
Status	string	Required, MaxLength(50)	The current status of the order (e.g., "Pending").
Customer	User	Navigation Property	The associated customer object.
OrderItems	List<OrderItem>	Navigation Property	A list of items included in the order.

Sources: Models/Order.cs:7-24, Configuration/OrderConfiguration.cs:11-29

OrderItem Model

The OrderItem model represents a single line item within an Order.

Sources: Models/OrderItem.cs

Property	Type	Constraints	Description
Id	int	Primary Key	Unique identifier for the order item.
OrderID	int	Required, Foreign Key to Order	The ID of the parent order.
ProductID	int	Required, Foreign Key to Product	The ID of the product.
Quantity	int	Required	The quantity of the product ordered.
UnitPrice	decimal	Required, decimal(18,2)	The price of a single unit of the product at the time of order.
Order	Order	Navigation Property	The parent order object.
Product	Product	Navigation Property	The associated product object.

Sources: Models/OrderItem.cs:11-21, Configuration/OrderItemConfiguration.cs:11-25

Data Transfer Objects (DTOs)

DTOs are used to shape the data sent to and from the API endpoints, separating the API contract from the internal data models.

CreateOrderRequest

Used for the POST /api/v1/order endpoint.

Property	Type	Description
CustomerID	int	The ID of the customer.
TotalAmount	decimal	The total amount for the order.
DeliveryMethod	string?	Method of delivery.
PaymentMethod	string?	Method of payment.
Address	string	Delivery address.
Status	string	Initial status of the order.
OrderItems	List<OrderItemRequest>	A list of items to be included in the order.

Sources: Dtos/CreateOrderRequest.cs:9-18

UpdateOrderRequest

Used for the PUT /api/v1/order/{id} endpoint.

Property	Type	Description
OrderCode	string	The unique code of the order.
OrderDate	DateTime	The date the order was placed.
CustomerID	int	The ID of the customer.
TotalAmount	decimal	The total amount for the order.
DeliveryMethod	string?	Method of delivery.
PaymentMethod	string?	Method of payment.
Address	string	Delivery address.
Status	string	The updated status of the order.
OrderItems	List<OrderItemRequest>	The complete, updated list of items for the order.

Sources: Dtos/UpdateOrderRequest.cs:9-19

UpdateOrderStatusRequest

Used for the PATCH /api/v1/order/{id} endpoint for partial updates.

Property	Type	Description
Status	string	The new status of the order.
Address	string	The new delivery address.
DeliveryMethod	string	The new delivery method.

Sources: Dtos/UpdateOrderRequest.cs:23-28

Service Layer Logic

The OrderService class contains the core business logic for managing orders. It interacts directly with the UserDBContext to perform database operations.

Sources: Service/order/OrderService.cs

Key Methods

• AddOrderAsync(Order newOrder): Adds a new order to the database. It takes a complete Order object and saves it.
• GetOrdersAsync(): Retrieves all orders and eagerly loads related OrderItems, Product, and Customer data.
• UpdateOrderAsync(int id, Order updatedOrder): Finds an existing order by ID, clears its existing OrderItems, and replaces all its properties with the values from updatedOrder.
• UpdateOrderPartialAsync(int id, string status, string address, string deliveryMethod): Performs a partial update on an order, modifying only the Status, Address, and DeliveryMethod fields.
• DeleteOrderAsync(int id): Finds an order by ID and removes it from the database.
• GetOrdersByCustomerIdAsync(int customerId): Fetches all orders belonging to a specific customer, including related data.

Sources: Service/order/IOrderService.cs, Service/order/OrderService.cs

Create Order Flow

The following sequence diagram shows the process of creating a new order.