> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laportenard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Order state machine

> Order lifecycle states, kitchen status transitions, and configurable kitchen notifications.

Source: `nu_pos_react/src/state/machines/orderMachine.ts`

## Order states

```
  ┌──────┐    ┌─────────┐    ┌──────────┐    ┌──────┐    ┌───────────┐
  │ idle │───►│ editing │───►│ checkout │───►│ paid │───►│ finalized │
  └──────┘    └─────────┘    └──────────┘    └──────┘    └───────────┘
```

| State       | Description                          |
| ----------- | ------------------------------------ |
| `idle`      | No draft loaded                      |
| `editing`   | Building or modifying the draft      |
| `checkout`  | Ticket prepared / sent to kitchen    |
| `paid`      | Payment collected — no edits allowed |
| `finalized` | Terminal archival                    |

## Kitchen status mapping

| State                   | Status    | Notes                                            |
| ----------------------- | --------- | ------------------------------------------------ |
| `editing` (before send) | `open`    |                                                  |
| `checkout` entry        | `sent`    |                                                  |
| Edits after send        | `changed` | Any line change post-checkout flips to `changed` |
| `paid` entry            | `paid`    | Edits blocked                                    |
| `finalized`             | `paid`    | Unchanged                                        |

## Order metadata

Guest count and staff assignment are set when an order is created via the `StartOrderModal`. The guest count can also be edited after creation by tapping the guest count indicator in the order panel header. This reopens the same modal in edit mode, pre-filled with the current count.

The `SET_TABLE_META` action updates `guestCount` and `staffName` on the active order.

## Core events

| Event                                       | Guard / Notes                      |
| ------------------------------------------- | ---------------------------------- |
| `ORDER_NEW`, `ORDER_LOAD`, `ORDER_CLEAR`    | Order lifecycle                    |
| `LINE_ADD`, `LINE_SET_QTY`, `LINE_REMOVE`   | Line editing                       |
| `ORDER_SET_CUSTOMER`, `PRICING_CONTEXT_SET` | Customer / metadata                |
| `GO_CHECKOUT`                               | Guard: must have at least one item |
| `GO_EDITING`                                | Return to editing from checkout    |
| `MARK_PAID`, `FINALIZE`                     | Payment flow                       |
| `DRAFT_SAVE`, `DRAFT_SAVED`                 | Autosave                           |

## Business rules

* Entering `paid` forces `status = "paid"` — no further edits are allowed.
* Draft loads normalize missing `status` to `"open"`.
* **Split behavior**: Source check becomes `"changed"`, destination checks inherit `"sent"` (not treated as new tickets).
* After payment is complete and the user taps Done, the app submits the order to Odoo. On success it navigates back to the floor plan, preserving area context (`/?area=...`) when available.

## Configurable kitchen notifications

The `send_changes_to_kitchen` setting on the shared POS config (`nu.pos.config`) controls whether non-quantity operations notify the kitchen:

| Setting          | Behavior                                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------------------- |
| `true` (default) | Splitting, removing, or transferring items marks orders as `"changed"` — kitchen is notified            |
| `false`          | These operations preserve the original status (e.g., `"sent"`) without triggering kitchen notifications |

**Configure in Odoo**: Point of Sale > Configuration > select config > "Send non-quantity changes to kitchen" checkbox.

This setting applies to:

* Splitting a sent order (source order status)
* Removing items from a sent order
* Adding items to a sent order
* Transferring items between orders

## Kitchen provenance

Order items carry optional `kitchenTicketId` and `kitchenSentAt` fields to remember the ticket and time they were originally sent. This is used when splitting a sent check — the new checks know which kitchen ticket their items came from.