WFDASH-WEBAPP/docs/order-workflow-rules.md

Order Workflow Rules

Quote to Order

• A quote remains in quotes.
• Quote items remain in quote_items.
• Creating an order from a quote creates one new orders record.
• The new order links back to the quote through orders.quote.
• Each quote item is copied into order_items.
• Each copied order item links back to its source quote item through order_items.quote_item.
• Creating an order from the same quote twice returns the existing order instead of duplicating it.
• Quote status is not changed by order creation.

Order Items as Source of Truth

order_items is the operational source of truth after an order is created. No order-level status field exists. Items are the only authoritative lifecycle record; the order-level "Complete" badge in the UI is derived client-side from the items (see "Order Completion" below).

Order items move through:

• supplier ordering / purchase order
• driver list / collection pool
• collected (back at office)
• picking
• ready for delivery
• delivered

Driver/collection fields use drv_* naming where possible, for example drv_status and drv_id.

Item Status Lifecycle

order_items.item_status takes one of:

Status	Meaning
pending	Item created, not yet sent to a supplier.
processed	Operator has reviewed/edited the line.
po_generated	PO created; in_stock flag determines next step.
driver_pool	Queued for collection (in_stock=false path).
assigned	A driver has picked it up.
collected	Back at the office (in_stock=true jumps straight here from PO).
stock_verified	Verified against stock count.
picking	Being pulled for delivery.
ready_delivery	Packed, on the delivery vehicle.
delivered	Signed for at the customer (terminal for the item).
cancelled	Cancelled (terminal for the item).

Orders List — Item-Status Tabs

The /orders page tabs are filtered by item status, not order status. There are six tab groups; each one is the set of item statuses that "live" on that tab. An order appears on tab X iff it has at least one item whose item_status is in X (so an order with items in both pending and delivered shows on both tabs).

Tab	Item statuses in this tab
New	pending
Processing	processed, po_generated
Collection Pool	driver_pool, assigned
Collected	collected, stock_verified, picking, ready_delivery
Delivered	delivered
Cancelled	cancelled

The mapping lives in src/lib/item-status-ui.ts (TAB_GROUP_ITEM_STATUSES) and is the single source of truth for both the tab labels and the underlying PB filter strings.

By default each row shows only items in the active tab. A "Show all items" toggle per row expands to the full item list.

Order Completion (derived, not stored)

A small helper isOrderComplete(items) in src/lib/server/order-completion.ts answers the only order-level question the UI still asks: "is this order done?". It returns true iff items.length > 0 && every item is delivered. The green "Complete" badge on /orders/[id] and the order row header is driven entirely by this helper — there is no orders.status field to keep in sync, and therefore no flip-flop bug on refresh.

Invoiced is a separate boolean (orders.invoiced, set by the invoicing action), intentionally independent from item lifecycle — an order can be marked invoiced before, during, or after the items are all delivered.

In-Stock Items

Each order_items row carries an in_stock: bool flag. When true, the line bypasses the driver collection pool entirely after PO generation:

• in_stock = false → on PO send, item transitions to driver_pool and a collection_pool row is created.
• in_stock = true → on PO send, item transitions to collected (skipping the pool).

Invoices and delivery notes ignore the flag — the item is still part of the order and counted in totals.

Driver List and Collection Pool

The old Django driver_list workflow is represented by the new collection_pool concept.

collection_pool tracks assignment and collection work, while order_items keeps the item lifecycle state.

Future Stock Collection

Later we will add a dedicated stock collection.

Stock is used when:

• more items are collected than the order requires
• stock is ordered and arrives at the office
• collected items should be booked into stock instead of moving to invoicing

Until that collection exists, stock-related operational movement stays on order_items.

Delivery Notes

Delivery notes should be generated from order items that are ready, loaded, or delivered.

Repairs

Repairs will be rebuilt only where they connect to the practical order/quote/repair flow.