Feature: Order Management
Relevant source files
The following files were used as context for generating this wiki page:The Order Management feature is a cornerstone of the Becathlon e-commerce platform, responsible for the entire lifecycle of a customer's purchase. It encompasses the checkout process, creation of persistent order records, payment processing, post-purchase order tracking, and product rating capabilities. This system transforms a user's shopping cart into a concrete order, manages inventory adjustments, and provides customers with detailed history and status updates on their purchases.
This module is tightly integrated with the Cart Management and Catalog systems, acting as the final step in the customer's shopping journey.
Data Models
The Order Management system is built upon a set of interconnected Django models that store all information related to a purchase. The core models are Order, OrderItem, ShippingAddress, Payment, and ProductRating.
Sources: apps/order/models.py
Entity Relationship Diagram
The following diagram illustrates the relationships between the key data models in the order system.
Sources: apps/order/models.py:15-309
Order Model
The Order model is the central entity, representing a single customer order.
| Field | Type | Description |
|---|---|---|
user | ForeignKey to User | The customer who placed the order. |
shipping_address | ForeignKey to ShippingAddress | The address where the order will be delivered. |
total_price | DecimalField | The total cost of the order. Calculated by calculate_total(). |
status | CharField | The overall status of the order (e.g., PENDING, PAID, CANCELED). |
delivery_status | CharField | The status of the physical delivery (e.g., PROCESSING, EN_ROUTE, DELIVERED). |
delivery_started_at | DateTimeField | Timestamp for when the delivery process begins. |
created_at | DateTimeField | Timestamp for when the order was created. |
updated_at | DateTimeField | Timestamp for the last update. |
Sources: apps/order/models.py:80-111
OrderItem Model
This model represents a single line item within an order, linking a product to an order with a specific quantity and price.
| Field | Type | Description |
|---|---|---|
order | ForeignKey to Order | The parent order for this item. |
product | ForeignKey to Product | The product being ordered. |
quantity | PositiveIntegerField | The number of units of the product ordered. |
price | DecimalField | The price of a single unit at the time of purchase (price snapshot). |
subtotal | DecimalField | The calculated total for this line item (quantity * price). |
Sources: apps/order/models.py:189-207
ShippingAddress Model
Stores shipping information. It can be associated with a user for future use but is also used independently for guest checkouts.
| Field | Type | Description |
|---|---|---|
user | ForeignKey to User (nullable) | The user this address belongs to. |
full_name | CharField | Recipient's full name. |
phone_number | CharField | Recipient's phone number. |
address_line1 | CharField | Main street address. |
address_line2 | CharField (optional) | Apartment, suite, etc. |
city | CharField | City. |
state | CharField (optional) | State or province. |
postal_code | CharField | Postal or ZIP code. |
country | CharField | Country. |
Sources: apps/order/models.py:18-42
Payment Model
Records payment details associated with an order.
| Field | Type | Description |
|---|---|---|
order | OneToOneField to Order | The order this payment is for. |
method | CharField | The payment method used (e.g., CREDIT_CARD, BANK_TRANSFER). |
amount | DecimalField | The amount paid. |
status | CharField | The status of the payment (e.g., PENDING, SUCCESS, FAILED). |
transaction_id | CharField (optional) | An external transaction identifier. |
paid_at | DateTimeField (optional) | Timestamp for when the payment was successfully completed. |
Sources: apps/order/models.py:221-248
ProductRating Model
Allows users to rate a product they have purchased as part of an order.
| Field | Type | Description |
|---|---|---|
user | ForeignKey to User | The user providing the rating. |
product | ForeignKey to Product | The product being rated. |
order | ForeignKey to Order | The order through which the product was purchased. |
rating | IntegerField | The star rating, from 1 to 5. |
review | TextField (optional) | A textual review of the product. |
Sources: apps/order/models.py:263-282
Order Creation and Checkout
The checkout process is the primary mechanism for creating an order. It is initiated from the user's cart and requires the user to be authenticated.
Sources: apps/order/views.py:19-161, apps/order/templates/order/checkout.html
Checkout Flow
The following sequence diagram shows the high-level flow of a successful checkout.
This diagram illustrates the atomic transaction in checkout view that creates the order, its items, payment, and updates inventory.
Sources: apps/order/views.py:68-161, apps/order/models.py:143-186
Key Logic: Order.create_from_cart()
This class method is the core of converting a cart into an order. It performs several critical operations within a database transaction:
- Creates an
Orderinstance linked to the user and shipping address. - Iterates through items in the
Cart. - For each item, it checks if there is sufficient product stock. If not, it raises a
ValueError. - Creates an
OrderItem, snapshotting the product's current price. - Decrements the
Productstock using an atomicF()expression to prevent race conditions. - Calculates the final
total_pricefor the order. - Clears the user's cart.
Sources: apps/order/models.py:143-186, apps/order/tests.py:255-285
Order Viewing and History
Authenticated users can view a list of all their past orders and click through to see a detailed view of each one.
Order List
The order_list view retrieves all orders for the current user, ordered by creation date. The template displays a summary card for each order.
- URL:
/orders/ - View:
order_list - Template:
apps/order/templates/order/order_list.html
Each order card on the list page shows the order ID, date, total price, overall status, and delivery status.
Sources: apps/order/views.py:164-173, apps/order/templates/order/order_list.html
Order Detail
The order_detail view provides a comprehensive look at a single order. It displays:
-
Order header with ID, date, and status.
-
A real-time delivery tracking progress bar and status timeline.
-
Detailed order information, including total amount.
-
Shipping address and payment details.
-
A list of all items in the order with quantities and subtotals.
-
A modal for rating products if the order has been delivered.
-
URL:
/orders/<int:order_id>/ -
View:
order_detail -
Template:
apps/order/templates/order/order_detail.html
Sources: apps/order/views.py:176-220, apps/order/templates/order/order_detail.html
Delivery Tracking
The system includes a mock delivery tracking feature that simulates the journey of a package from processing to delivery.
Sources: apps/order/models.py:113-140, apps/order/views.py:223-255
Delivery Status State Machine
The delivery status transitions through a fixed set of states over a predefined duration.
This diagram shows the progression of an order's delivery status over time.
Sources: apps/order/models.py:93-100, 113-140
The Order model defines durations for each phase:
PROCESSING_DURATION: 60 secondsEN_ROUTE_DURATION: 60 seconds
The get_current_delivery_status() method calculates the current status based on the time elapsed since delivery_started_at. The front-end polls the check_delivery_status API endpoint to update the UI in real-time.
Sources: apps/order/models.py:102-103, 113-128, apps/order/templates/order/order_detail.html:33-100
Product Rating
After an order's delivery status is DELIVERED, the user can rate the products they purchased.
Sources: apps/order/views.py:258-348, apps/order/models.py:261-309
Rating Submission Flow
The rating submission is handled via an API endpoint and is restricted to delivered orders.
API Endpoints
The order module exposes several API endpoints to support dynamic front-end features.
| Method | URL | View Function | Description |
|---|---|---|---|
POST | /orders/checkout/ | checkout | Processes the checkout form, creating an order. |
GET | /orders/check-delivery-status/<int:order_id>/ | check_delivery_status | Returns the current delivery status and progress of an order. |
POST | /orders/<int:order_id>/rate/ | submit_rating | Submits a product rating for a delivered order. |
Sources: apps/order/views.py
Conclusion
The Order Management feature is a comprehensive system that handles the complete post-cart lifecycle of a customer's purchase. Through a well-structured data model and a series of views and APIs, it manages order creation, payment, inventory updates, real-time delivery tracking, and post-purchase feedback via product ratings. This module is essential for the core e-commerce functionality of the Becathlon application, providing a robust and user-friendly experience for customers to manage and track their purchases.