Costing module (costing)

The costing module in src/cluster_erp/modules/costing/ costs a BOM version. A costing analysis reads the BOM explosion, applies labour and overhead rates, adds an optional nesting cost, and stores a cost breakdown, a total, a suggested price for a target margin, and a low-margin flag. An analysis then goes through submission, approval, or rejection, and an approved analysis linked to a quotation reports its price back. Labour rates and overhead rates are the module's own reference records.

At a glance¶

What the module does¶

• Records a costing analysis for one BOM and BOM version, optionally linked to a quotation and a nesting job, with a target margin and a currency (src/cluster_erp/modules/costing/costing_analyses/models.py:23-189).
• Calculates the cost breakdown in tiers and stores one breakdown row per cost line (src/cluster_erp/modules/costing/costing_analyses/services.py:256-708).
• Stores a snapshot of every rate used, so a later rate change does not change the explanation of an old result (src/cluster_erp/modules/costing/costing_analyses/services.py:627-662).
• Lets a user set a final price, submit, approve, reject, return to draft, and supersede (src/cluster_erp/modules/costing/costing_analyses/services.py:710-896).
• Compares two to five analyses and clones an analysis as a what-if scenario with cost multipliers (src/cluster_erp/modules/costing/costing_analyses/services.py:957-1159).
• Keeps labour rates per work centre and operation type, and overhead rates with a basis and an apply order (src/cluster_erp/modules/costing/labor_rates/models.py:14-68, src/cluster_erp/modules/costing/overhead_rates/models.py:12-54).

Sub-modules¶

Data model¶

"Open" means valid_to is empty and the row is live; partial unique indexes enforce it (src/cluster_erp/modules/costing/labor_rates/models.py:16-24, src/cluster_erp/modules/costing/overhead_rates/models.py:14-21). Money is Numeric and Decimal; see money and Decimal.

Screens and metadata¶

get_metadata declares a sidebar group Costing Management (Turkish Maliyet Yönetimi) with three lists: Costing Analyses, Labor Rates, and Overhead Rates (src/cluster_erp/modules/costing/module.py:253-308). The analysis list shows number, status, total cost, final price, actual margin, currency, low-margin flag, and calculation time, with a status filter (src/cluster_erp/modules/costing/costing_analyses/metadata.py:125-200).

Status and actions¶

Statuses and allowed transitions are fixed in the service (src/cluster_erp/modules/costing/costing_analyses/services.py:71-80): draft to calculated; calculated to calculated again or to pending_approval; pending_approval to approved or rejected; approved to superseded; rejected back to draft. approved and superseded analyses cannot be changed.

Two lifecycle routes have no ActionMeta: POST /analyses/{id}/set-final-price and POST /analyses/{id}/supersede (src/cluster_erp/modules/costing/costing_analyses/routes.py:159-172, src/cluster_erp/modules/costing/costing_analyses/routes.py:237-250).

Business rules¶

The costing roll-up¶

The diagram shows the order of the tiers in calculate.

flowchart TD
 E["GetBomExplosion (bom)"] --> M["material tier: effective_qty x material_cost_per_unit, plus scrap"]
 E --> L["labour tier: minutes x hourly rate, or qty x unit rate, plus scrap"]
 N["GetNestingJobById (nesting)"] --> NT["nesting tier: net_material_cost"]
 M --> S["subtotal"]
 L --> S
 NT --> S
 S --> O["overhead tier, in apply_order"]
 O --> T["total_cost = material + labour + overhead + scrap + nesting"]
 T --> P["suggested_price = total / (1 - target margin)"]
 P --> F["low_margin_flag if margin below 15"]

In prose, step by step (src/cluster_erp/modules/costing/costing_analyses/services.py:256-708):

1. The analysis must be allowed to move to calculated (src/cluster_erp/modules/costing/costing_analyses/services.py:261-262).
2. The module asks the bom module for the explosion of the BOM version and fails if there is none or it has no items (src/cluster_erp/modules/costing/costing_analyses/services.py:264-290).
3. It loads the active labour and overhead rates and refuses any rate whose currency differs from the analysis currency, with COSTING_CURRENCY_MISMATCH (src/cluster_erp/modules/costing/costing_analyses/services.py:292-313).
4. It removes the previous breakdown rows and snapshots (src/cluster_erp/modules/costing/costing_analyses/services.py:315-329).
5. Material tier: for each item with a material cost, base cost is effective quantity times material cost per unit, and scrap cost is base cost times the scrap factor (src/cluster_erp/modules/costing/costing_analyses/services.py:346-404).
6. Labour tier: for each item with labour minutes, the rate is looked up by work centre and operation type, then work centre only, then operation type only, then the general operation type, then a rate with neither. A unit-price rate multiplies the quantity; an hourly rate multiplies the hours. Without a rate, the item's own labour cost per unit is used. Labour scrap is the labour cost times the scrap factor (src/cluster_erp/modules/costing/costing_analyses/services.py:406-504).
7. Nesting tier: when the analysis names a nesting job, its net_material_cost becomes one breakdown line (src/cluster_erp/modules/costing/costing_analyses/services.py:506-534).
8. Overhead tier: each active overhead rate, in apply_order, takes a percentage of labour, material, the total so far, or the running subtotal, or a fixed amount per unit of quantity; each result is added to the running subtotal (src/cluster_erp/modules/costing/costing_analyses/services.py:536-587).
9. The total is material plus labour plus overhead plus scrap plus nesting (src/cluster_erp/modules/costing/costing_analyses/services.py:589-600).
10. With a target margin, the suggested price is the total divided by one minus the margin, and the markup is derived from it (src/cluster_erp/modules/costing/costing_analyses/services.py:602-619).
11. The low-margin flag is set when the margin is below 15 percent (src/cluster_erp/modules/costing/costing_analyses/services.py:60, src/cluster_erp/modules/costing/costing_analyses/services.py:621-625).
12. Rate snapshots are stored, the status becomes calculated, calculation_version goes up by one, and CostingCalculated is emitted, plus LowMarginAlert when flagged (src/cluster_erp/modules/costing/costing_analyses/services.py:627-706).

Each money result is rounded with ROUND_HALF_EVEN to four places (src/cluster_erp/modules/costing/costing_analyses/services.py:359-372, src/cluster_erp/modules/costing/costing_analyses/services.py:606-609).

Other rules¶

• The final price can be set only on a calculated analysis; the actual margin becomes (price minus cost) divided by price, and the markup (price minus cost) divided by cost (src/cluster_erp/modules/costing/costing_analyses/services.py:710-739).
• Submission needs a final or a suggested price; without a final price, the suggested price is copied into it (src/cluster_erp/modules/costing/costing_analyses/services.py:742-759).
• Approval of an analysis with a quotation and a final price also emits QuoteCostingCompleted (src/cluster_erp/modules/costing/costing_analyses/services.py:768-808).
• Supersede needs a new analysis of the same BOM (src/cluster_erp/modules/costing/costing_analyses/services.py:857-880).
• Only a draft analysis can be deleted one by one (src/cluster_erp/modules/costing/costing_analyses/services.py:233-244).
• A scenario can be cloned from a calculated or approved analysis; material and labour lines are scaled by the given multipliers (src/cluster_erp/modules/costing/costing_analyses/services.py:1031-1104).
• A labour or overhead rate's valid_to may not be before its valid_from (src/cluster_erp/modules/costing/labor_rates/services.py:159-163, src/cluster_erp/modules/costing/overhead_rates/services.py:107-111). A labour rate type is hourly or unit_price (src/cluster_erp/modules/costing/labor_rates/schemas.py:9).
• analysis_no comes from the yearly sequence costing_analysis (src/cluster_erp/modules/costing/costing_analyses/services.py:183).

Events and queries¶

The module consumes 7 contracts and produces 10, counted as on the parties module page.

The two subscribed handlers have an empty body at this commit (src/cluster_erp/modules/costing/module.py:227-231). The full list is on the contracts reference.

Permissions¶

Privacy, retention, and history¶

The module stores user ids of submitters and approvers and no personal fields of its own; it has no privacy_handlers.py. Analyses and rates are soft-deleted. Changes are captured by change history.

Analytics facts¶

This module has no analytics_facts.py.

Settings and reference data¶

Labour and overhead rates are the module's reference data; there is no settings section and no seed (src/cluster_erp/modules/costing/module.py:28-30). The low-margin threshold is the module constant _LOW_MARGIN_THRESHOLD (src/cluster_erp/modules/costing/costing_analyses/services.py:60).

Tests¶

Found by a grep for modules.costing in tests/ and by file name in web-client/.

No pytest file imports the module.

Discrepancies¶

Terms introduced¶

Related pages¶

• Modules index
• BOM module
• Nesting module
• Quotations module
• Money and Decimal
• API reference for this module

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