WFDASH-WEBAPP/docs/sops/order-operator.md

Order Operator — SOP

Owns: the order lifecycle, from quote → order → delivered → invoiced. Creates purchase orders, drives the order_items state machine, hands off to invoicing.

Tools: /orders, /orders/[id], /orders/new, /collection-pool, /collection-map, /stock, /stock-orders, dashboard widgets.

Handoffs:

• From Quote Operator → customer accepted a quote.
• To Collection Driver → PO sent, item moves to collection_pool.
• To Invoicing → item delivered, ready to invoice.
• To Approver → escalated pricing / margin / customer issues.

Note: the order lifecycle is item-level, not order-level. orders.status does not exist as a field. The "Complete" badge on the order header is derived from every item is delivered. This is in src/lib/server/order-completion.ts. Get familiar with it.

---

1. Daily / Weekly Checklist

Every working day (start of shift, 08:00 SAST)

• Open /orders — New tab. Every pending item should have a clear next action: either waiting for pricing review, waiting for a PO, or waiting for a supplier reply.
• Open /orders — Processing tab. Verify all processed items have a PO generated. Items stuck in processed for >1 working day = process bug. Fix or escalate.
• Open /orders — Collection Pool tab. If you see ready_for_collection: true items with no driver assigned, the collection driver hasn't picked them up — phone them.
• Open dashboard → "Follow-ups Due". Action anything from you (POs waiting on supplier reply, etc).
• Check /api/v1/purchase-orders/stale (or the dashboard widget). POs with no supplier reply for >3 working days must be phoned.

Every working day (mid-day, 13:00 SAST)

• Open /orders — Collected tab. Verify stock_verified and picking items are progressing. Anything stuck in stock_verified for >2 hours = stock discrepancy. Resolve or escalate to the Stock Controller.
• Check /stock?filter=low — if any of your orders used a stock item that's now critical, the customer needs a heads-up.

Every working day (end of shift, 17:00 SAST)

• Review every order that changed today. Make sure all status transitions are correct. A delivered item that shouldn't be delivered is a customer-facing disaster.
• Triage /orders — Delivered tab. Any delivered items older than 1 working day that aren't yet ready_invoice? Push them through.

Every Monday morning

• Review your KPIs (see §4). Pay attention to the items that drifted last week.
• Triage stuck orders — anything in pending or processed for >5 working days is a zombie. Either ship, cancel, or escalate.

Every Friday afternoon

• Close the week. Make sure no orders have items in limbo states over the weekend. assigned to a driver who doesn't work weekends = uncollected Monday morning.
• Invoicing handoff: confirm the invoice clerk has received everything they need for the week's ready_invoice items. They'll print Monday morning.

---

2. Step-by-Step Procedures

2.1 Create an order from a quote

When: a customer accepts a quote (you got the call, or the customer replied accepting).

1. Open the quote detail.
2. Click Create Order. The system creates:
   • One new orders record with number ORD-YYYY-MM-NNN.
   • One order_items row per quote_items row, linked back via order_items.quote_item.
3. The quote status does NOT change automatically. The quote stays in approved (or emailed + your acceptance note).
4. The order starts in New (pending) tab.

Don't:

• Don't try to create an order from the same quote twice. The system returns the existing order, not a duplicate.
• Don't edit the quote after creating the order — the items are now in order_items, edits to quote_items don't propagate.

2.2 Create a walk-in order (no quote)

When: a customer walks in / phones with an order that wasn't quoted.

1. Open /orders/new.
2. Pick or create the customer (and company).
3. Add items manually. Each item needs at minimum description
   • quantity + unit_price. Cost is optional at creation (defaults to 0 — fix later from the PO).
4. Save. Order lands in pending.
5. Pricing: see §2.3.

2.3 Price and process a pending item

When: an order item lands in pending and you have a quote to source from.

1. Open the order detail.
2. Click the line item. Set cost_price (from the quote or catalogue) and selling_price.
3. Click Mark Processed (status flips to processed).
4. Decide next path:
   • In stock? → click Book from Stock. The item flips to stock_verified and the stock qty decrements via the ledger. (See §2.7 for stock flow.)
   • Not in stock, need to buy? → generate a PO. See §2.4.

2.4 Generate a purchase order (PO)

When: an item needs to be ordered from a supplier.

1. On the order detail, click Generate PO. The system groups items by supplier and creates one PO per supplier.
2. Open the PO. Verify:
   • Items + quantities match the order.
   • Cost prices are correct (from the quote or a fresh supplier call).
   • Delivery date is realistic.
3. Click Send PO. The email modal opens. Same shape as sending a quote (§2.4 in the Quote Operator SOP).
4. n8n sends the email. The supplier reply monitor updates supplier_replied_at when the supplier replies.
5. The order item flips to po_generated.

Don't:

• Don't generate a PO without verifying the cost. Once sent, the PO is the contract — wrong cost = wrong margin.

2.5 Receive a supplier invoice and book the goods

When: a supplier invoice / delivery note arrives (PDF in email, or paper).

1. Identify the PO. Look for the "Your Ref" / "Order No" on the document. It'll be PO-YYYY-MM-NNN (customer PO) or PO{yy}{6d-seq}STK (stock PO).
2. Diff first — call the system to compare the invoice against the PO. Read the verdict:
   • ready_to_receive → continue to step 3.
   • Anything else (cost_mismatch, qty_mismatch, supplier_mismatch, wrong_status, po_not_found, unmatched_*) → stop and report to the supervisor. Don't force it through.
3. Commit the receive — for stock POs this books into stock_items.current_qty and writes a stock_ledger row. For customer POs, the order items flip to collected and the supplier invoice number is stamped.
4. The system attaches the invoice PDF to the PO.

Mode:

• mode: "invoice" — full invoice received (price + qty).
• mode: "grn" — only a delivery note (qty only, no price check). Use this when the supplier sends the packing slip before the invoice.

Surplus / Short:

• If the supplier delivered MORE than ordered (surplus), the PO diff flags it. Confirm with the Stock Controller; they may book the surplus to stock (§2.8).
• If LESS than ordered (short), the system records the received qty. Create a continuation order for the missing qty (§2.6).

2.6 Split an order into a continuation

When: some lines are stuck (waiting on a back-ordered part), the rest can ship. Or: a walk-in order has lines added later and the original is past pending.

1. Open the order detail.
2. Verify which lines are pending. Only pending lines can be moved (others refuse silently to avoid orphaning a PO or driver assignment).
3. Click Split Order. Pick the pending lines to move.
4. A new ORD-YYYY-MM-NNN order is created with the moved lines. The parent keeps its number; the moved lines get a breadcrumb in notes.
5. Process the new continuation order normally.

2.7 Book from stock

When: a processed line item has a stock_item_id set and qty available.

1. On the order detail, click Book from Stock.
2. The system calls /api/v1/stock/fulfill — decrements stock_items.current_qty and writes a stock_ledger row with reason: "customer_fulfillment".
3. The order item flips to stock_verified → picking (or directly to collected if the picking step is bypassed for direct-from-stock orders).

If the stock qty is short (someone else booked it first), the system refuses. Either:

• Cancel the line (status → cancelled).
• Wait for restock and re-try later.
• Source from the supplier instead (revert to processed → generate PO).

2.8 Book a surplus

When: the supplier delivered more than ordered (e.g. 12 instead of 10), and the customer only needs 10.

1. On the order item, click Book Surplus.
2. Enter the surplus qty (e.g. 2).
3. The system:
   • Splits the order line: customer qty (10) stays on the order, surplus qty (2) goes to stock.
   • Writes a stock_ledger row with reason: "purchase_surplus".
   • Sets order_items.surplus_qty and stock_booked_from on the line.
4. The stock item's current_qty increments.

2.9 Confirm collection (driver flow)

When: the driver has picked up the goods and the collection is being confirmed back at the office (or via the mobile app).

1. On the order detail, find the item. It should be in collection_pool or assigned.
2. Click Confirm Collected. Enter the qty received (the quantity_collected field is the amount to ADD, not the new total).
3. For partial deliveries: clamp to received_qty - qty_collected (≥0). Add a note explaining the partial.
4. The item flips to collected (full) or stays in collection_pool (partial) with the qty_collected updated.

Actor field is required. The system stamps the actor on every audit entry. If you don't pass it, the audit trail loses you.

2.10 Pick, pack, deliver

When: items are collected and ready to be packed for delivery.

1. collected → stock_verified (verify qty against the shelf count).
2. stock_verified → picking (operator starts pulling).
3. picking → ready_delivery (packed, on the truck).
4. ready_delivery → delivered (signed for at the customer).

Each step needs an operator action. Don't bulk-flip — the audit trail per step is the customer's dispute evidence.

2.11 Mark an order delivered (header-level)

When: every item on the order is delivered (or short-circuits via the eligible set — see tool doc).

1. Open the order detail.
2. Click Mark Delivered. The system flips every eligible item to delivered and stamps delivered_at + delivered_date.
3. Does NOT flip order.invoiced. The Invoicing Clerk does that.

If the tool reports data.itemsFailed (some items refused), inspect them. The most common reason is an item in pending/processed/cancelled that wasn't eligible.

2.12 Hand off to invoicing

When: items are delivered and the customer has been notified.

1. On the order detail, click Mark Ready to Invoice (the button shows when items are eligible). The items flip to ready_invoice.
2. Don't call mark_invoiced here — that's the Invoicing Clerk's job, after they generate the QB invoice or delivery note.

---

3. Decision Tree

3.1 The customer wants to cancel after the order is placed

Has the supplier been PO'd yet (item is in `processed` or later)?
├── No → cancel the line(s), no cost incurred. Easy.
└── Yes
    ├── Has the supplier confirmed the order (replied to PO)?
    │   ├── No → phone the supplier NOW. Most will cancel
    │   │         without charge if you catch it pre-confirm.
    │   └── Yes
    │       ├── Is the goods in transit / collected?
    │       │   ├── No → call the supplier, negotiate a cancel.
    │       │   │         Some will charge a handling fee.
    │       │   └── Yes → goods will arrive. Three options:
    │       │         a) Accept the goods, book to stock,
    │       │            re-sell later.
    │       │         b) Refuse delivery (record the refusal
    │       │            on the order notes, supervisor
    │       │            decides whether to charge the customer
    │       │            a restocking fee).
    │       │         c) Ask the supplier to return-to-vendor.
    │       │            Their policy, not yours.
    │       └── Surplus / different qty → see §3.3
    └── Customer wants to change items, not cancel → see §3.2

3.2 Customer wants to change items after the order is placed

Is the order still all-`pending`?
├── Yes → use the order editor to swap the items.
└── No (some lines already `processed` or later)
    ├── Only the `pending` lines need to change → split off the
    │   pending lines, edit on the parent, leave the rest.
    └── Some `processed` lines need to change
        ├── Has the supplier PO'd been sent?
        │   ├── No → revert the line to `pending`, edit.
        │   └── Yes → phone the supplier first, then decide:
        │             either cancel the PO + re-issue, or ship
        │             the original and create a separate order
        │             for the replacement.
        └── The change affects pricing → update the order's
            selling price, document the customer agreement in
            `order.notes`.

3.3 Supplier delivered wrong / damaged / short

What's the discrepancy?
├── Wrong qty (short)
│   ├── Receive what arrived (use the `quantity_collected`
│   │   to-add semantics).
│   ├── Mark the missing qty as back-ordered. Create a
│   │   continuation order for it (§2.6) when you can re-supply.
│   └── Phone the supplier, log the short in `order.notes`.
├── Wrong qty (over — surplus)
│   └── See §2.8. Book the surplus to stock, keep the order qty
│       at the customer's need.
├── Wrong item
│   ├── Refuse delivery. Phone the supplier for a return-to-
│   │   vendor or a credit note.
│   └── If customer will accept the wrong item at a discount →
│       call the supervisor, don't unilaterally discount.
├── Damaged
│   ├── Refuse delivery. Take photos, attach to the PO via the
│   │   supplier_invoice_ prefix on `order_item_attachements`.
│   └── If customer accepts damaged at a discount → supervisor
│       call, photos on file, credit note from supplier.
└── All correct
    └── Confirm the receive (§2.5).

3.4 Stock item is short when I try to book

Is the short a rounding / measurement error?
├── Yes → recheck the stock count. The Stock Controller may
│         have missed an entry.
└── No
    ├── Is the item critical (low stock) → flagged in
    │   `/stock?filter=critical`?
    │   ├── Yes → the order is more important than the stock
    │   │         refill. Book it. File a stock-order for
    │   │         restock.
    │   └── No → cancel the stock booking, source from the
    │             supplier via PO.
    └── Has the stock item been double-booked? → check
        `stock_ledger` for recent bookings. The Stock
        Controller can release the duplicate.

3.5 Supplier hasn't replied to a PO in 3+ days

Did the PO send successfully (check `email_message_id`)?
├── No (mail_failed) → retry the send, verify recipient address
└── Yes
    ├── Phone the supplier. Most POs are lost in spam.
    ├── If no answer, email the sales rep directly (check
    │   `/suppliers` for the contact).
    └── After 7 working days with no reply → escalate to
        supervisor. We may need to find a backup supplier.

3.6 Customer wants a delivery date that's not realistic

Can the supplier meet it (have they confirmed)?
├── Yes → set the order's `delivery_date` accordingly.
└── No
    ├── Is the customer willing to wait?
    │   ├── Yes → set a realistic date, log the agreement in
    │   │         `order.notes`. Don't over-promise.
    │   └── No → escalate to supervisor. We may need to split
    │             sources, expedite (at a cost), or partial-
    │             ship.
    └── Is there stock for at least part of the order? → split
        the order (§2.6). Ship what's in stock, back-order
        the rest.

3.7 An order has items in mixed states (some delivered, some pending)

Is the customer OK with partial delivery?
├── Yes → ship what's ready. The delivered items go to
│         invoicing. The pending items stay on the order
│         until they're ready.
└── No (customer needs everything together) → leave the order
    open. Don't flip anything to delivered until everything
    is on the truck. The customer is OK with the wait.

---

4. KPIs

All KPIs measured in working days.

KPI	Target	How it's measured
Order creation turnaround (quote accepted → order exists)	< 30 min median	orders.created - quotes.approved_at
pending → processed turnaround	< 4 working hours	median processed_at - created on order_items
PO send turnaround (processed → po_generated)	< 1 working day	median po_generated_at - processed_at
Supplier reply time	< 2 working days median	supplier_replied_at - email_message_id_sent
PO stale rate	< 5% of open POs	POs without reply > 3 working days / open POs
Collection turnaround (po_generated → collected)	< 3 working days	median collected_at - po_generated_at
collected → delivered turnaround	< 1 working day	median delivered_at - collected_at
Order completion rate (delivered within 5 working days of pending)	> 80%	orders with all items delivered within 5 wd / orders created
PO cost-mismatch rate	< 3% of receives	count of cost_mismatch verdicts on diff / total receives
Surplus booking rate	100% of surpluses booked same day	stock_ledger entries with reason="purchase_surplus" per day vs supplier delivery notes
Split order rate	< 10% of orders	orders with notes containing a split breadcrumb / total orders
Cancellation rate	< 5% of pending lines	order_items.item_status="cancelled" / total order_items created

How KPIs feed into your review

• Weekly (Monday standup): one-pager with the operator's KPIs. Stale POs, cost mismatches, and stuck pending items are the supervisor's first questions.
• Monthly (1st of month): 1-page review with the operator. Surplus booking rate and PO cost-mismatch rate are weighted double — getting them wrong is a money leak.
• Quarterly: top performers on completion rate + on-time delivery are eligible for the "trusted buyer" tier — they can raise POs up to a higher value without supervisor sign-off.

What the system does NOT measure (yet)

• Customer satisfaction post-delivery (no feedback loop yet)
• Damage rate per supplier (only the PO-level diff verdict is captured, not the cause)
• Driver utilisation (that's the collection driver's KPI)

If a KPI is unfair, raise it. The supervisor can adjust targets, but the metric stays.