# Order Status Workflow

- **Complexity:** High
- **Stack:** Full-stack (Backend-heavy)

**As an** admin user, **I want to** update order statuses through a defined workflow **so that** customers can track their order progress.

## Description

The `Order` entity currently has no status field - orders are created via `OrderController` (`POST /api/orders`) and processed by `OrderService` using the strategy pattern for stock allocation, but there is no lifecycle tracking after creation. This story introduces a status field, a state machine that defines valid transitions, and provides an interface to manage order progression. Customers see their order's current status in the `orders-overview-page` and `order-detail-page`.

## Order Statuses

| Status     | Description                                                                            |
|------------|----------------------------------------------------------------------------------------|
| `NEW`      | Initial state - every order that is not saved yet                                      |
| `SAVED`    | Order is saved but still editable (add/remove products, change delivery address, etc.) |
| `PLACED`   | Order is placed and no longer editable (waiting for delivery)                          |
| `CANCELED` | Order is not valid anymore (will not be delivered)                                     |

## Order Status Flow

```mermaid
stateDiagram-v2
    classDef blueState fill:#82d1f5,stroke:#333,stroke-width:1px,color:#000

    [*] --> NEW: (Initial state)
    
    NEW --> SAVED: Save
    NEW --> PLACED: Place
    
    SAVED --> PLACED: Place
    SAVED --> CANCELED: Cancel
    
    PLACED --> CANCELED: Cancel
    PLACED --> [*]: Final state
    
    CANCELED --> [*]: Final state

    class SAVED, PLACED, CANCELED blueState
  ```

## Acceptance Criteria

- [ ] New orders are created with status `NEW` during the existing order creation flow in `OrderService`
- [ ] User can save an order: `NEW` -> `SAVED` (order becomes editable)
- [ ] User can place an order: `NEW` -> `PLACED` or `SAVED` -> `PLACED`
- [ ] Admin can cancel an order: `SAVED` -> `CANCELED` or `PLACED` -> `CANCELED`
- [ ] Placed and canceled orders cannot be modified further
- [ ] Attempting an invalid transition (e.g., `CANCELED` -> `NEW`) returns a clear error
- [ ] Admin order detail page shows the current status and only valid next-status actions
- [ ] Customers see the current status of their orders in `orders-overview-page` (via `order-card`) and `order-detail-page`
- [ ] Non-admin users cannot cancel orders
- [ ] Status changes persist after page reload

## Resources

- [Spring State Machine](https://docs.spring.io/spring-statemachine/docs/3.2.1/reference/#statemachine)
- [Spring State Machine Guide](https://www.baeldung.com/spring-state-machine)
- [Spring State Machine Example](https://stackoverflow.com/questions/35911877/how-to-use-spring-state-machine-for-an-order-object)