Purchase orders

This page describes the purchase_orders sub-module in src/cluster_erp/modules/procurement/purchase_orders/ and the shared helper src/cluster_erp/modules/procurement/delivery_address.py. A purchase order (PurchaseOrder) is an order placed with a vendor. Receiving an order line posts a goods receipt in the inventory module through the EventBus.

Scope and source¶

• Defined in: models.py (PurchaseOrder, PurchaseOrderItem), services.py (PurchaseOrderService), routes.py, metadata.py, and item_metadata.py of the sub-module.
• Count: 2 tables, 18 routes (@router. decorators in routes.py), 6 ActionMeta entries (5 on the order, 1 on the item).

Order fields¶

Item fields¶

Statuses and actions¶

The service allows these transitions (src/cluster_erp/modules/procurement/purchase_orders/services.py:67-75):

stateDiagram-v2
 [*] --> draft
 draft --> sent: send
 sent --> acknowledged: acknowledge
 acknowledged --> in_transit: in_transit
 acknowledged --> received: last line received
 in_transit --> received: last line received
 received --> in_transit: receipt reversed
 received --> closed: close
 draft --> cancelled: cancel
 sent --> cancelled: cancel
 acknowledged --> cancelled: cancel
 in_transit --> cancelled: cancel

In prose: an order starts as draft. send needs an order date and the flag has_technical_attachment (src/cluster_erp/modules/procurement/purchase_orders/services.py:620-641). Receiving is allowed in acknowledged and in_transit; when every live line is received, the order becomes received (src/cluster_erp/modules/procurement/purchase_orders/services.py:705-774). A receipt reversal can move a received order back to in_transit (src/cluster_erp/modules/procurement/purchase_orders/services.py:854-891). close follows received; cancel is open until receipt (src/cluster_erp/modules/procurement/purchase_orders/services.py:892-929).

Order routes¶

Goods receipt¶

The diagram shows a receipt of one line.

sequenceDiagram
 participant U as receive route
 participant S as PurchaseOrderService
 participant B as EventBus
 participant I as inventory
 U->>S: receive_item
 S->>S: check status, breakdown, quantity
 S->>B: emit PoReceivedFull or PoReceivedPartial
 S->>B: query PostGoodsReceipt
 B->>I: _handle_post_goods_receipt
 I-->>S: movement id

In prose: the service refuses a text item and an item without model and version, because stock is posted per breakdown (src/cluster_erp/modules/procurement/purchase_orders/services.py:718-731). The received quantity may not exceed the ordered quantity (src/cluster_erp/modules/procurement/purchase_orders/services.py:738-749). The service updates the line and order status, emits PoReceivedFull or PoReceivedPartial, and then queries PostGoodsReceipt with the order as reference, the line id, and the order's project as stock owner (src/cluster_erp/modules/procurement/purchase_orders/services.py:750-822). An error from inventory fails the receipt with PO_GOODS_RECEIPT_FAILED; a missing inventory handler is logged and the receipt stays a purchasing record only (src/cluster_erp/modules/procurement/purchase_orders/services.py:823-837). A reversed goods movement gives the open quantity back through the query ReconcilePoReceiptReversal (src/cluster_erp/modules/procurement/module.py:192-202, src/cluster_erp/modules/procurement/module.py:885-916).

Constraints and validation¶

• On create, the vendor is read with GetPartyById; a blacklisted vendor is refused (src/cluster_erp/modules/procurement/purchase_orders/services.py:215-243).
• Each catalogue item's breakdown is checked with ensure_product_breakdown (src/cluster_erp/modules/procurement/purchase_orders/services.py:279, src/cluster_erp/modules/procurement/purchase_orders/services.py:507).
• Unit price is rounded to four places and the line total to the column scale, both with ROUND_HALF_EVEN; the header total is the sum (src/cluster_erp/modules/procurement/purchase_orders/services.py:112-123, src/cluster_erp/modules/procurement/purchase_orders/services.py:307-312).
• The header and items change only in draft; only a draft can be deleted (src/cluster_erp/modules/procurement/purchase_orders/services.py:415-468).
• The delivery address must be a shipping address of the delivery party; its text is stored as a snapshot (src/cluster_erp/modules/procurement/delivery_address.py:24-28, src/cluster_erp/modules/procurement/delivery_address.py:78, src/cluster_erp/modules/procurement/purchase_orders/services.py:251).
• Events: PoCreated, PoSent, PoAcknowledged, PoReceivedFull, PoReceivedPartial, PoCancelled (src/cluster_erp/modules/procurement/purchase_orders/services.py:338, src/cluster_erp/modules/procurement/purchase_orders/services.py:648, src/cluster_erp/modules/procurement/purchase_orders/services.py:672, src/cluster_erp/modules/procurement/purchase_orders/services.py:779-797, src/cluster_erp/modules/procurement/purchase_orders/services.py:921).

Terms introduced¶

Related pages¶

• Procurement module
• Purchase requests
• Purchasing RFQs
• Inventory module

Verified against commit 92f8051 on 2026-11-13.