The Material Order Build Standard

1. What this standard covers

Any business that orders materials for jobs: plumbers with a wholesaler account, builders with three suppliers and a yard, electricians who keep stock on the van. If a job carries a material list and somebody has to turn it into orders, this applies.

It sits between two standards that exist. The Quote Out standard is where the material lines came from, priced only from the book. The Invoice Check standard is where the supplier’s invoice goes next, checked against the order this standard produced. The material ordering paper is the argument beside it.

What cannot meet it. A supplier with no catalogue the business can read, only a phone number, cannot be the source of a price. Orders to that supplier park on every line until a person prices them, and the standard says so rather than letting a remembered price through.

2. The objects, and what is in them

Seven objects. The stock read and the docket are the two most ordering tools leave out, because an order that arrived looks finished.

Job                               # theirs, from the job system
  - id, start, owner (a person)
  - material_lines[] { code, qty, description }

Stock
  - code, on_hand, reserved

Supplier
  - id, name, approved (a person set it), lead_days

SupplierCatalogue                 # theirs, read at order time
  - supplier_id, edition
  - items[] { code, price, lead_days }

Order
  - id, external_id (the ordering system's own id; null means the write failed)
  - job_id, supplier_id            # one order per pair
  - lines[] { code, qty, price }, catalogue_edition
  - status (draft | parked | released | sent | delivered)
  - park_reason (not_in_catalogue | write_failed)
  - released_by (person) | released_by_rule (rule name)

ReleaseRule                       # set by a person, once
  - name, threshold, owner

Delivery
  - order_id, at
  - lines[] { code, qty_received, reason (short | damaged | substituted) }
  - substitution_accepted_by (a person, or the line is a variance)

An Order with status sent and no release is the defect this standard exists to make unrepresentable. A second Order for one job and supplier is the other, and neither should be writable.

3. The checks, in order

The order is the claim. Stock is read before the catalogue, the catalogue before the write, and the existing order before a new one, because a build that orders first and checks afterwards has already spent the money.

1. Every ordered line traces to a material line on the job. An order line exists because the job carries a material line with that catalogue code and quantity. Nothing is ordered that the job does not list, and nothing on the job is dropped without a parked reason.
2. Stock on hand is read before the order, and a line stock covers is reserved rather than ordered. Before any order is written, stock on hand is read. A line the store or the van already covers is reserved against the job and does not appear on a purchase order. An order that ignores stock fails.
3. Every line carries the supplier's catalogue code and price, read at order time, and a line no catalogue holds parks the order. The price on a line is the supplier's catalogue price for that code, read when the order is drafted. No price is typed, remembered or averaged. A code no supplier's catalogue holds parks the order with reason not_in_catalogue and a person is told.
4. One order per job and supplier, written once, updated on a second run. The write is keyed to the job and the supplier. A second run for the same job updates the existing order or does nothing. Two orders for one job and supplier fails, and a null external id is a failed write, not a success.
5. An order over the threshold, or to a supplier not on the approved list, is released only by a named person. A release is one of two things: a named person, or a rule a named person set with a threshold. An order whose total is over the threshold, or whose supplier is not on the approved list, waits for a person. Under the threshold and to an approved supplier, the rule may release.
6. Each supplier carries a lead time, and an order that would miss the job's start tells the job owner. Lead time is a number on the supplier or the catalogue line, not a guess. When the order's arrival date lands after the job's start, the job owner is told in the same run, with the order and the supplier named.
7. A delivery is recorded against the order line by line, and a delivery with no order is refused. When goods arrive, the docket is matched to the order and each line is recorded with the quantity received and, where it differs, a reason: short or damaged. A docket that matches no order is not recorded as a delivery; it is raised to a person.
8. Short, over, wrong item and a changed price are escalated with the order id and an owner, never absorbed. Every difference between what was ordered and what arrived is a variance with a kind, the order id and an owner. It is never silently accepted into the job's cost, and it is never silently written off.
9. A supplier's substitution is accepted only by a named person. When the supplier delivers a different item in place of the one ordered, the line is received only when a named person has accepted the substitute. Without that acceptance the line is held as a variance and a person is told. A substitution accepted by a rule, or by nobody, fails.
10. Every order, release, delivery and variance is retrievable by job. When the supplier's invoice arrives, or the customer asks what a material cost, the record shows by job id: each order with its external id and the catalogue edition, who released it or which rule did, each delivery line by line, and every variance with its owner.
11. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
12. The pass test passes. On the real job system and a real supplier account: one job ordered twice, one line covered from stock, one line no catalogue holds, one order over the threshold waiting for a person, and one delivery short.

4. The six queues

Parking is a success. An order that waits a morning for a person to price one line beats one that went out at a remembered price, and beats by a long way one that went out twice.

5. Delivery, and what it feeds

A delivery is recorded against the order line by line: what was ordered, what arrived, and a reason for any gap. Short, damaged and substituted are the reasons. A delivery with no order to match is refused, because the supplier who delivers what nobody ordered will invoice for it. A substitution is accepted only by a named person, who is usually the one on site who can see whether it will do.

The matched delivery is the record the supplier’s invoice should be compared against. The Invoice Check standard covers that comparison against the order; it does not yet read the docket, so the received quantity recorded here is what a builder adds to it. Order, docket and invoice, three records that agree or a variance with an owner. That is the whole reason the docket is matched here rather than signed and filed.

6. What stays with a person

• ✓The release of any order over the threshold, or to a supplier not on the approved list.
• ✓Approving a supplier in the first place.
• ✓Accepting a substitution, on site, with their name on the line.
• ✓Every variance: short, over, wrong, damaged, or a price that moved between catalogue and invoice.

7. Provider: what to stub, and what not to hand-roll

One step not to hand-roll: the idempotent write of the order into the system the business buys from, with an id back. Everything else a coding agent builds against the stub in an afternoon.

provider:
  stub:       local.mock_supplier
  production: none                       # scoped build, not a product

stays local                          # yours, and the standard
  - the stock read and the reservation
  - the catalogue read and the priced lines
  - the threshold, the approved list, the docket match

the live step
  - one order per job and supplier, written into the supplier portal
    or the job system's purchasing with an id back. Quoted as a
    scoped build; there is no hosted product for it.

A vendor selling purchasing automation is usually selling the picking list, which is the easy half, and is silent about what happens when the job is ordered twice or the supplier sends a substitute. Ask them those two first.

8. Conformance checklist

Hold a DIY build or a vendor to this. If a box is empty, it is not in production.

• ✓1. Every ordered line traces to a material line on the job. An order line exists because the job carries a material line with that catalogue code and quantity. Nothing is ordered that the job does not list, and nothing on the job is dropped without a parked reason.
• ✓2. Stock on hand is read before the order, and a line stock covers is reserved rather than ordered. Before any order is written, stock on hand is read. A line the store or the van already covers is reserved against the job and does not appear on a purchase order. An order that ignores stock fails.
• ✓3. Every line carries the supplier's catalogue code and price, read at order time, and a line no catalogue holds parks the order. The price on a line is the supplier's catalogue price for that code, read when the order is drafted. No price is typed, remembered or averaged. A code no supplier's catalogue holds parks the order with reason not_in_catalogue and a person is told.
• ✓4. One order per job and supplier, written once, updated on a second run. The write is keyed to the job and the supplier. A second run for the same job updates the existing order or does nothing. Two orders for one job and supplier fails, and a null external id is a failed write, not a success.
• ✓5. An order over the threshold, or to a supplier not on the approved list, is released only by a named person. A release is one of two things: a named person, or a rule a named person set with a threshold. An order whose total is over the threshold, or whose supplier is not on the approved list, waits for a person. Under the threshold and to an approved supplier, the rule may release.
• ✓6. Each supplier carries a lead time, and an order that would miss the job's start tells the job owner. Lead time is a number on the supplier or the catalogue line, not a guess. When the order's arrival date lands after the job's start, the job owner is told in the same run, with the order and the supplier named.
• ✓7. A delivery is recorded against the order line by line, and a delivery with no order is refused. When goods arrive, the docket is matched to the order and each line is recorded with the quantity received and, where it differs, a reason: short or damaged. A docket that matches no order is not recorded as a delivery; it is raised to a person.
• ✓8. Short, over, wrong item and a changed price are escalated with the order id and an owner, never absorbed. Every difference between what was ordered and what arrived is a variance with a kind, the order id and an owner. It is never silently accepted into the job's cost, and it is never silently written off.
• ✓9. A supplier's substitution is accepted only by a named person. When the supplier delivers a different item in place of the one ordered, the line is received only when a named person has accepted the substitute. Without that acceptance the line is held as a variance and a person is told. A substitution accepted by a rule, or by nobody, fails.
• ✓10. Every order, release, delivery and variance is retrievable by job. When the supplier's invoice arrives, or the customer asks what a material cost, the record shows by job id: each order with its external id and the catalogue edition, who released it or which rule did, each delivery line by line, and every variance with its owner.
• ✓11. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
• ✓12. The pass test passes. On the real job system and a real supplier account: one job ordered twice, one line covered from stock, one line no catalogue holds, one order over the threshold waiting for a person, and one delivery short.