# Order Lifecycle & State Machine ## Order State Transition Rules Managed via `OrderRouter.py`. ```mermaid stateDiagram-v2 [*] --> ORDER_CREATED ORDER_CREATED --> PAYMENT_PENDING PAYMENT_PENDING --> PAYMENT_AUTHORIZED PAYMENT_AUTHORIZED --> PAYMENT_CAPTURED PAYMENT_CAPTURED --> ORDER_CONFIRMED ORDER_CONFIRMED --> PROCESSING PROCESSING --> PACKED PACKED --> SHIPPED SHIPPED --> DELIVERED PAYMENT_PENDING --> PAYMENT_FAILED PAYMENT_PENDING --> PAYMENT_EXPIRED ORDER_CONFIRMED --> CANCELLED DELIVERED --> RETURNED ``` --- ## Order Status Audit Trail Every state change creates an append-only audit entry in `order_status_history`: ```sql INSERT INTO order_status_history (id, order_id, previous_status, new_status, changed_by, reason, created_at) VALUES ('his_01J8X9', 'ord_01J8X9', 'PAYMENT_PENDING', 'ORDER_CONFIRMED', 'SYSTEM', 'Razorpay Webhook ACK', NOW()); ```