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

# Order lifecycle

> Status flow, transitions, numbering, and production stages

## Status flow

```mermaid theme={null}
stateDiagram-v2
    [*] --> SUBMITTED : Submitted without approval
    [*] --> PENDING_APPROVAL : Rule set requires approval
    PENDING_APPROVAL --> APPROVED : HR / Admin approves
    PENDING_APPROVAL --> REJECTED : HR / Admin rejects
    SUBMITTED --> APPROVED : HR / Admin approves
    SUBMITTED --> REJECTED : HR / Admin rejects
    APPROVED --> PROCESSING : Admin
    PROCESSING --> MANUFACTURING : Admin
    MANUFACTURING --> EMBROIDERY : Admin
    MANUFACTURING --> QUALITY_CHECK : Admin (skips embroidery)
    MANUFACTURING --> PACKED : Admin (skips embroidery and QC)
    EMBROIDERY --> QUALITY_CHECK : Admin
    QUALITY_CHECK --> PACKED : Admin
    PACKED --> DISPATCHED : Admin
    DISPATCHED --> DELIVERED : Admin
```

Transitions are enforced server-side by the `STATUS_TRANSITIONS` map in `orders.service.ts`. Terminal states (`REJECTED`, `DELIVERED`, `CANCELLED`) never appear as a source.

## Status definitions

| Status             | Meaning                                                   | Who sets it                |
| ------------------ | --------------------------------------------------------- | -------------------------- |
| `PENDING_APPROVAL` | Awaiting approval (rule set has `approvalRequired: true`) | System, on submission      |
| `SUBMITTED`        | Submitted; no approval required by the rule set           | Store Manager / HR / Admin |
| `APPROVED`         | Approved and ready for production                         | HR / Muze Admin            |
| `PROCESSING`       | Being prepared for manufacturing                          | Muze Admin                 |
| `MANUFACTURING`    | Garments being manufactured                               | Muze Admin                 |
| `EMBROIDERY`       | Logos or branding being applied                           | Muze Admin                 |
| `QUALITY_CHECK`    | Inspection in progress                                    | Muze Admin                 |
| `PACKED`           | Packed and labelled for shipment                          | Muze Admin                 |
| `DISPATCHED`       | Shipment has left the facility                            | Muze Admin                 |
| `DELIVERED`        | Received at the store (terminal)                          | Muze Admin                 |
| `REJECTED`         | Rejected during approval (terminal)                       | HR / Muze Admin            |
| `CANCELLED`        | Cancelled before production (terminal)                    | Staff / Admin              |

## Allowed transitions

| From               | Allowed next statuses              |
| ------------------ | ---------------------------------- |
| `PENDING_APPROVAL` | APPROVED, REJECTED, CANCELLED      |
| `SUBMITTED`        | APPROVED, PROCESSING, CANCELLED    |
| `APPROVED`         | PROCESSING, CANCELLED              |
| `PROCESSING`       | MANUFACTURING                      |
| `MANUFACTURING`    | EMBROIDERY, QUALITY\_CHECK, PACKED |
| `EMBROIDERY`       | QUALITY\_CHECK                     |
| `QUALITY_CHECK`    | PACKED                             |
| `PACKED`           | DISPATCHED                         |
| `DISPATCHED`       | DELIVERED                          |

Notes on the flow:

* Status can only move forward. There is no transition back to an earlier stage.
* `MANUFACTURING` can skip `EMBROIDERY` (and quality check) for items that need no branding.
* Each transition writes an `OrderStatusHistory` record with timestamp, actor, and optional note.

## Order numbering

| Format              | Used for            | Sequence                          |
| ------------------- | ------------------- | --------------------------------- |
| `ORD-YYYYMMDD-NNNN` | Individual orders   | Resets daily, 4-digit zero-padded |
| `SO-XXXXX`          | Store order batches | Global sequential, 5-digit        |

Both prefixes are configurable via the `ORDER_NUMBER_PREFIX` and `STORE_ORDER_NUMBER_PREFIX` system settings. Numbers come from the persistent `NumberSequence` counter, which is concurrency-safe and never reuses a number after a row is deleted:

```
ORD-20260904-0001   first order of 4 Sept 2026
SO-00001            first store order batch
```

## Store order batches

Orders placed in the same submission are grouped under a `StoreOrder` batch, identified by its `SO-` number; every order in it links via `Order.storeOrderId`. Batch numbers are global and sequential.

A batch's displayed status uses a **worst-first** rule: the member order with the earliest lifecycle stage determines the batch status. If a batch holds one order at PACKED, one at MANUFACTURING, and one at APPROVED, the batch shows MANUFACTURING.

Admins can advance a single order or the whole batch; the batch advance applies to every eligible member order and derives each member's next stage individually.

## Production stages

After approval, orders move through `PROCESSING → MANUFACTURING → (EMBROIDERY) → QUALITY_CHECK → PACKED → DISPATCHED → DELIVERED`. Production status updates require the `orders.status-update` permission, held by Muze Admin and Super Admin only.

Every transition creates an `OrderStatusHistory` record:

```prisma theme={null}
model OrderStatusHistory {
  orderId     String
  fromStatus  OrderStatus?
  toStatus    OrderStatus
  note        String?
  changedById String?
  changedAt   DateTime     @default(now())
}
```

This gives a complete audit trail of who changed what, when, and why.

## Limitations

* No external production system integration; status updates are manual.
* No estimated delivery dates and no shipment tracking.
* No automated stage advancement.

The production pipeline feeds the Production Requirements report (see [Reporting](/notifications-reports/reporting)).