Nesting module (nesting)

The nesting module in src/cluster_erp/modules/nesting/ plans how parts are cut from metal sheets. A nesting job describes the sheet and the parts; the job is exported to an external nesting tool, and the tool's layout is imported back, checked, and stored. The module then draws the layout as SVG or DXF, costs the material, reserves and consumes sheet stock through the inventory module, records reusable remnants, and reports utilisation KPIs. The layout itself is not computed inside the module; see nesting engine.

At a glance¶

What the module does¶

• Records a nesting job with sheet size, thickness, material grade, coating, kerf, part gap, edge margin, allowed rotations, mirroring, maximum sheets, and an optional sheet material breakdown and warehouse (src/cluster_erp/modules/nesting/nesting_jobs/models.py:22-291).
• Lists the parts to place, by hand or pulled from production and sales orders (src/cluster_erp/modules/nesting/nesting_jobs/services.py:676-802).
• Exports a job for an external tool and imports the tool's placements, remnants, and part outlines (src/cluster_erp/modules/nesting/integration/services.py:114-363).
• Draws the layout as SVG and writes it as DXF (src/cluster_erp/modules/nesting/nesting_jobs/routes.py:307-396).
• Costs the material, credits remnants, and allocates the net cost to parts (src/cluster_erp/modules/nesting/nesting_jobs/services.py:555-675).
• Approves a job, consumes reserved material, creates remnants, and posts them to stock (src/cluster_erp/modules/nesting/nesting_jobs/services.py:311-390).
• Reports utilisation and scrap KPIs over a period (src/cluster_erp/modules/nesting/kpi/services.py:36-238).

Sub-modules¶

Details are on jobs, parts, and remnants, integration and KPI, and nesting engine.

Data model¶

Screens and metadata¶

get_metadata declares a sidebar group Nesting & Optimization (Turkish Yerleşim & Optimizasyon) with three sections: the layout viewer (custom widget nesting_viewer), Nesting Jobs, and Remnants (src/cluster_erp/modules/nesting/module.py:162-217). The viewer shows the KPIs, the job list, a summary, the SVG drawing, and downloads; a client without the widget skips the section (src/cluster_erp/modules/nesting/module.py:178-187).

Status and actions¶

Job statuses are queued, running, completed, and failed (src/cluster_erp/modules/nesting/nesting_jobs/schemas.py:10). A job starts queued and becomes completed when a result is imported (src/cluster_erp/modules/nesting/nesting_jobs/models.py:31-36, src/cluster_erp/modules/nesting/integration/services.py:322). A grep for "running" and "failed" finds no code that sets either status at this commit. Remnant statuses include available, reserved, consumed, and scrapped (src/cluster_erp/modules/nesting/nesting_remnants/services.py:83, src/cluster_erp/modules/nesting/nesting_remnants/services.py:188-194, src/cluster_erp/modules/nesting/nesting_remnants/services.py:256-262).

The nesting pipeline¶

The diagram shows the path of a job from creation to approval.

flowchart TD
 A["create job (queued)"] --> B["add parts or pull parts from orders"]
 B --> C["reserve material (optional, ReserveStock)"]
 C --> D["export job"]
 D --> E["external nesting tool"]
 E --> F["import-result: check and store layout (completed)"]
 F --> G["svg and dxf drawings"]
 F --> H["calculate costs (NestingCostCalculated)"]
 H --> I["approve (NestingApproved)"]
 I --> J["consume material (ConsumeReservation, PostGoodsIssue)"]
 I --> K["create remnants and post to stock (PostGoodsReceipt)"]
 I --> L["NestingScrapRecorded"]

In prose: a job is created queued and filled with parts (src/cluster_erp/modules/nesting/nesting_jobs/services.py:111-160). Sheet stock can be reserved while the job is queued (src/cluster_erp/modules/nesting/nesting_jobs/services.py:394-468). The job is exported, nested by an external tool, and the result is imported, which checks the placements and marks the job completed (src/cluster_erp/modules/nesting/integration/services.py:114-363). A completed job can be drawn and costed (src/cluster_erp/modules/nesting/nesting_jobs/services.py:555-675). Approval checks utilisation, then consumes reserved material, creates remnants from the imported leftovers, posts them to stock, and records scrap (src/cluster_erp/modules/nesting/nesting_jobs/services.py:311-390).

Business rules¶

• A job's sheet material is optional; when given, its model and version are validated (src/cluster_erp/modules/nesting/nesting_jobs/services.py:116-122).
• A job can be edited and deleted only while queued or failed; a completed job accepts only low_utilization_acknowledged and notes (src/cluster_erp/modules/nesting/nesting_jobs/services.py:187-199, src/cluster_erp/modules/nesting/nesting_jobs/services.py:228-232).
• Approval of a job whose utilisation is below the threshold needs low_utilization_acknowledged; the threshold is the setting nesting_low_utilization_threshold, 60 by default (src/cluster_erp/modules/nesting/nesting_jobs/services.py:332-342, src/cluster_erp/modules/nesting/nesting_jobs/routes.py:221-222, src/cluster_erp/config/settings.py:418).
• Reserving material needs a sheet material breakdown and a warehouse (src/cluster_erp/modules/nesting/nesting_jobs/services.py:394-426).
• Money results are rounded to four places with ROUND_HALF_EVEN (src/cluster_erp/modules/nesting/nesting_jobs/services.py:594-628).
• code comes from the yearly sequences nesting_job and nesting_remnant (src/cluster_erp/modules/nesting/nesting_jobs/services.py:123, src/cluster_erp/modules/nesting/nesting_remnants/services.py:135).

Events and queries¶

The module consumes 2 contracts and produces 16, counted as on the parties module page.

GetNestingJobById returns money and area values as strings, including net_material_cost, which the costing module reads (src/cluster_erp/modules/nesting/module.py:82-108). The full list is on the contracts reference.

Permissions¶

Privacy, retention, and history¶

The module stores no personal data and has no privacy_handlers.py. Jobs are soft-deleted; deleting a job also soft-deletes its parts and remnants (src/cluster_erp/modules/nesting/nesting_jobs/services.py:219-249, src/cluster_erp/modules/nesting/nesting_jobs/services.py:289-309). Changes are captured by change history.

Analytics facts¶

This module has no analytics_facts.py. Its own KPI service is described on integration and KPI.

Settings and reference data¶

The module reads one setting, nesting_low_utilization_threshold (src/cluster_erp/config/settings.py:420). It has no settings section and seeds nothing (src/cluster_erp/modules/nesting/module.py:28-30). See settings reference.

Tests¶

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

Discrepancies¶

Terms introduced¶

Related pages¶

• Modules index
• Nesting engine
• Jobs, parts, and remnants
• Integration and KPI
• Costing module
• Inventory module
• API reference for this module

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