# KOT / Order Status Flow for Frontend

This file defines the frontend lifecycle without changing existing backend route paths.

## Frontend Status Flow

1. `CREATED`
2. `KOT_GENERATED`
3. `PENDING`
4. `PREPARING`
5. `READY`
6. `SERVED`
7. `PAID`

## Meaning

- `CREATED`
  - Order created by waiter or system
  - No kitchen action yet

- `KOT_GENERATED`
  - KOT created or printed
  - Sent to printer or kitchen display

- `PENDING`
  - Waiting in kitchen queue

- `PREPARING`
  - Chef started cooking
  - Main kitchen active state

- `READY`
  - Food prepared and ready for service

- `SERVED`
  - Delivered to customer
  - Only admin or waiter can move to this state

- `PAID`
  - Billing completed
  - Backend may internally close final records as `completed`

## Backend Compatibility Mapping

| Frontend Status | Backend/Internal Status |
| --- | --- |
| `CREATED` | `Running` |
| `KOT_GENERATED` | `Printed` or `RunningKOT` |
| `PENDING` | `Pending` |
| `PREPARING` | `Preparing` |
| `READY` | `Ready` |
| `SERVED` | `Served` |
| `PAID` | `Paid` or `completed` |
| `CANCELLED` | `cancelled` |

## Request Rule

Frontend may now send the improved status labels in these existing APIs:

- `PATCH /api/kitchen/kot/:id/status`
- `PATCH /api/admin/kitchen/kot/:id/status`
- `PATCH /api/orders/:orderId/status`

Example:

```json
{
  "status": "PREPARING"
}
```

## Response Rule

Frontend should prefer:

- `status_label`

Raw DB-compatible status remains available in:

- `legacy_status`

## Important Permission Rule

- Kitchen users must not set `SERVED`
- Only JWT users with role `admin` or `waiter` can set `SERVED`

## SQL Change Requirement

No SQL migration is required for this compatibility rollout.

The backend accepts the improved frontend statuses and safely maps them to current internal values.