Sales orders module (sales_orders)

The sales_orders module in src/cluster_erp/modules/sales_orders/ turns a customer purchase order into a sales order and follows it to delivery. It checks the customer PO against the sent quote, freezes each PO revision, copies quote lines into order lines, tracks individual units (assets), ships them in shipments with packages and transport data, and generates the packing list and the delivery note. This page is the overview; the sub-topics have their own pages.

At a glance¶

What the module does¶

• Creates an order from a customer PO that references a sent or won quote, and copies the quote's open lines (src/cluster_erp/modules/sales_orders/orders/services.py:174-341).
• Compares the PO with the quote field by field and records each attempt (src/cluster_erp/modules/sales_orders/orders/services.py:342-463).
• Freezes each PO version as a snapshot revision (src/cluster_erp/modules/sales_orders/orders/services.py:871-939).
• Tracks individual units of an order line with customer asset numbers and serial numbers (src/cluster_erp/modules/sales_orders/units/models.py:14-40).
• Ships lines and units in shipments with packages, transport data, events, and proof of delivery, and rolls the order status up from shipped quantities (src/cluster_erp/modules/sales_orders/shipments/services.py:1253-1392).
• Generates the packing list and the delivery note as PDF from a frozen snapshot (src/cluster_erp/modules/sales_orders/trade_documents/services.py:169-278).

Sub-modules¶

All routers are mounted under the module prefix with require_app("sales_orders") (src/cluster_erp/modules/sales_orders/module.py:64-71).

Data model¶

Fields are listed on orders and lines, shipments, trade documents, and units and settings. Order lines carry part_id, part_model_id, and part_version_id; a catalogue line always carries its model and version (src/cluster_erp/modules/sales_orders/order_lines/models.py:22-62). Money is Numeric: order total Numeric(19, 4), line price and total Numeric(18, 4) (src/cluster_erp/modules/sales_orders/orders/models.py:81-84, src/cluster_erp/modules/sales_orders/order_lines/models.py:71-79).

Screens and metadata¶

get_metadata declares a sidebar group Order Management (Turkish Sipariş Yönetimi) with the sections Sales Orders, Shipments, Units (Assets), Export Documents, and Settings (src/cluster_erp/modules/sales_orders/module.py:321-368). See generic list and actions and action sheet.

Status and actions¶

Order statuses and actions are on orders and lines; shipment statuses on shipments. The diagram shows the path from a customer PO to the documents.

flowchart LR
 Q["Quote sent"] --> SO["SalesOrder po_received"]
 SO --> CHK["run_po_check: matched or mismatch"]
 CHK --> ACC["accept: opened"]
 ACC --> SH["SalesOrderShipment planned"]
 SH --> RDY["ready"]
 RDY --> SHIP["ship: shipped"]
 SHIP --> DEL["deliver with POD: delivered"]
 SH --> TD["generate-documents"]
 TD --> PL["TradeDocument packing_list"]
 TD --> DN["TradeDocument delivery_note"]
 SHIP --> ROLL["_advance_order_status on the order"]
 DEL --> ROLL

In prose: an order created from a PO starts as po_received (src/cluster_erp/modules/sales_orders/orders/models.py:72-77, src/cluster_erp/modules/sales_orders/orders/services.py:41-55). The PO check sets matched or mismatch, and accept opens a matched order (src/cluster_erp/modules/sales_orders/orders/services.py:342-463, src/cluster_erp/modules/sales_orders/orders/services.py:588-648). A shipment of the order is readied, dispatched, and delivered; each step rolls the order up from shipped quantities (src/cluster_erp/modules/sales_orders/shipments/services.py:1085-1191, src/cluster_erp/modules/sales_orders/shipments/services.py:1253-1392). Documents are generated per shipment (src/cluster_erp/modules/sales_orders/trade_documents/routes.py:102).

Business rules¶

Each sub-topic page lists its rules. Across the module, foreign data such as customers, parties, products, units of measure, and countries is read through EventBus queries, and the module imports no other module (src/cluster_erp/modules/sales_orders/trade_documents/builder.py:1-5).

Events and queries¶

The module consumes 7 contracts and produces 33, counted as on the parties module page. The full list is on the contracts reference.

Permissions¶

The module checks the families sales_order.*, po_revision.read, shipment.*, shipment_line.*, shipment_unit.*, shipment_package.*, shipment_event.*, trade_document.*, sales_order_unit.*, and sales_order_settings.*. The order line BOM route uses the permission named by the contract CreateBomForProduct.REQUIRED_PERMISSION (src/cluster_erp/modules/sales_orders/order_lines/routes.py:104-114). Each sub-topic page lists the keys per route.

Privacy, retention, and history¶

The module has no privacy_handlers.py. Records are soft-deleted; issued documents are superseded, not removed (src/cluster_erp/modules/sales_orders/trade_documents/services.py:262-263). Changes are captured by change history.

Analytics facts¶

analytics_facts.py contributes the fact set sales_order over so_sales_orders with the measures order_count, total_value, average_value, median_value, and total_quantity, read with sales_order.read (src/cluster_erp/modules/sales_orders/analytics_facts.py:22-126). See analytics facts.

Settings and reference data¶

One settings row per tenant controls the internal order number, document number templates, the proof-of-delivery rule, the dispatch check level, default units and package type, and the document language; see units and settings.

Tests¶

Found by a grep for modules.sales_orders in tests/ and for the path /sales_orders/ in web-client/_e2e_*.mjs.

Terms introduced¶

Related pages¶

• Modules index
• Orders and lines
• Shipments
• Trade documents
• Units and settings
• Quotations module
• API reference for this module

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