Products and services module (products_and_services)

The products_and_services module in src/cluster_erp/modules/products_and_services/ is the material master. It holds products and services with their planning, stock-size, and costing fields, the mandatory product, model, and version breakdown, a category tree, vendor sources per breakdown, and the units of measure. Every other module that names a product asks this module over the EventBus. The shared breakdown rule is explained on product breakdown and stock conversion.

At a glance¶

What the module does¶

• Keeps products and services with a material type, four capability flags, a status, units, physical data, stock-size and make-or-buy data, planning parameters, costing fields, and trade data (src/cluster_erp/modules/products_and_services/products/models.py:20-351).
• Gives every product at least one model and every model at least one version, so that stock and documents can always post against a full breakdown (src/cluster_erp/modules/products_and_services/product_versions/models.py:16-19).
• Links a product to several categories of a category tree (src/cluster_erp/modules/products_and_services/products/models.py:395-417, src/cluster_erp/modules/products_and_services/categories/models.py:11-30).
• Records vendor sources per product, model, version, and vendor party (src/cluster_erp/modules/products_and_services/vendors/models.py:14-63).
• Holds unit categories and units with conversion factors and seeds a default set at start-up (src/cluster_erp/modules/products_and_services/module.py:31-50).

Sub-modules¶

Router paths are relative to the module prefix; all six routers sit under one module router that depends on the app entitlement (src/cluster_erp/modules/products_and_services/module.py:75-83).

Data model¶

The product, model, and version breakdown¶

The diagram shows the breakdown tables and the rows that point at them.

erDiagram
 Product ||--|{ ProductModel : "product_id"
 ProductModel ||--|{ ProductVersion : "product_model_id"
 Product ||--o{ ProductCategoryLink : "product_id"
 ProductCategory ||--o{ ProductCategoryLink : "category_id"
 Product ||--o| ProductServiceAttributes : "product_id"
 ProductVersion ||--o{ ProductVendor : "product_version_id"
 UnitCategory ||--|{ UnitOfMeasure : "category_id"
 UnitOfMeasure ||--o{ Product : "base_unit_id"

In prose: a product has one or more models and a model has one or more versions. Exactly one live model per product and exactly one live version per model carry is_default, enforced by partial unique indexes (src/cluster_erp/modules/products_and_services/product_models/models.py:32-38, src/cluster_erp/modules/products_and_services/product_versions/models.py:35-41). A version name is unique within its model (src/cluster_erp/modules/products_and_services/product_versions/models.py:42-49). A product has category links and, when it is a service, one service facet row. A vendor source names a product, a model, a version, and a vendor party (src/cluster_erp/modules/products_and_services/vendors/models.py:16-49). Units belong to a unit category, and a product points at its base, purchase, sales, weight, volume, and dimension units (src/cluster_erp/modules/products_and_services/products/models.py:103-138).

Entities¶

Money and quantity columns are Numeric; costs and vendor prices use Numeric(18, 4) (src/cluster_erp/modules/products_and_services/products/models.py:313-314, src/cluster_erp/modules/products_and_services/vendors/models.py:56). Decimal values are serialised as strings (src/cluster_erp/modules/products_and_services/products/schemas.py:149-151, src/cluster_erp/modules/products_and_services/products/schemas.py:478-481). See money and Decimal.

Screens and metadata¶

get_metadata declares a sidebar group Products & Services (Turkish Ürünler ve Hizmetler) with three sections: Products (a list), Categories (a tree), and Settings with the tabs unit_category and unit (src/cluster_erp/modules/products_and_services/module.py:954-997). The product detail has the tabs General, Service, Physical Properties, Inventory & Planning, Production & Costing, Vendors, Models, Bill of Materials, and Stock (src/cluster_erp/modules/products_and_services/products/metadata.py:222-295). The Service tab shows only for the material type service, and the physical, inventory, production, and stock tabs hide for it. The Bill of Materials tab shows only for manufacturable products and reads the bom module's list, and Stock reads the inventory module's list (src/cluster_erp/modules/products_and_services/products/metadata.py:230-294). The create form collects the first model's name, SKU, and barcode and the first version's name (src/cluster_erp/modules/products_and_services/products/metadata.py:381-424). Products and models have photos (src/cluster_erp/modules/products_and_services/products/metadata.py:118, src/cluster_erp/modules/products_and_services/products/metadata.py:1328). The category tree uses GET /categories/tree (src/cluster_erp/modules/products_and_services/categories/metadata.py:26-32).

Status and actions¶

Product statuses are draft, active, blocked, and obsolete (src/cluster_erp/modules/products_and_services/products/schemas.py:24-28). The status is a form field, and a change emits ProductStatusChanged (src/cluster_erp/modules/products_and_services/products/services.py:590-598). The module declares one ActionMeta.

Business rules¶

• Each material type has default capability flags, used when the payload leaves a flag out (src/cluster_erp/modules/products_and_services/products/schemas.py:34-89, src/cluster_erp/modules/products_and_services/products/services.py:296-312).
• Hard constraints: a service is neither stockable nor manufacturable, a consumable is not stockable, and a raw material is not manufacturable; a violation answers PRODUCT_CAPABILITY_VIOLATION (src/cluster_erp/modules/products_and_services/products/schemas.py:91-95, src/cluster_erp/modules/products_and_services/products/services.py:671-683).
• A product that is not stockable has its batch, serial, shelf-life, safety-stock, and reorder-point fields cleared (src/cluster_erp/modules/products_and_services/products/services.py:48-55, src/cluster_erp/modules/products_and_services/products/services.py:316-318).
• SKU and barcode must be free among live products (src/cluster_erp/modules/products_and_services/products/services.py:272-292).
• Creating a product creates its default model, named after the product when no name is given, and the model creates its default version, named 1 by default (src/cluster_erp/modules/products_and_services/products/services.py:376-395, src/cluster_erp/modules/products_and_services/product_models/services.py:103-112, src/cluster_erp/modules/products_and_services/product_models/schemas.py:22).
• The first model of a product and the first version of a model become the default; a new default takes the flag from the old one (src/cluster_erp/modules/products_and_services/product_models/services.py:78-99, src/cluster_erp/modules/products_and_services/product_versions/services.py:72-90).
• The default model or version cannot be demoted, deactivated, or deleted; the answer is PRODUCT_MODEL_DEFAULT_PROTECTED or PRODUCT_VERSION_DEFAULT_PROTECTED with HTTP 409 (src/cluster_erp/modules/products_and_services/product_models/services.py:115-160, src/cluster_erp/modules/products_and_services/product_versions/services.py:92-140).
• A product that is a live component of an active BOM version cannot be deleted; the module asks the bom module with GetPartUsageCounts and answers PRODUCT_IN_ACTIVE_BOM (src/cluster_erp/modules/products_and_services/products/services.py:604-626).
• Deleting a product also soft-deletes its category links and service facet with the same timestamp; reactivating it restores them (src/cluster_erp/modules/products_and_services/products/services.py:628-660, src/cluster_erp/modules/products_and_services/module.py:165-236).
• Every category named on a product must be live; the first one becomes the denormalised category_id (src/cluster_erp/modules/products_and_services/products/services.py:151-206).
• A vendor source checks that the product and the party exist, validates the breakdown, and refuses a second live source for the same breakdown and party with HTTP 409 (src/cluster_erp/modules/products_and_services/vendors/services.py:94-143).
• Unit conversion works only within one unit category: value times the source factor, divided by the target factor (src/cluster_erp/modules/products_and_services/settings/services.py:237-247). The seed has 13 unit categories (src/cluster_erp/modules/products_and_services/settings/seed_data.py, entries with a code key).
• Codes come from the yearly sequences product, product_model, product_version, product_category, and unit_of_measure (src/cluster_erp/modules/products_and_services/products/services.py:325, src/cluster_erp/modules/products_and_services/product_models/services.py:79, src/cluster_erp/modules/products_and_services/product_versions/services.py:73).

Events and queries¶

The module consumes 19 contracts and produces 8, counted as on the parties module page. The full list of producers and consumers is on the contracts reference.

CreateScaffoldIntermediate creates, or reuses by SKU, a stockable semi-finished product that is not manufacturable, for the output of a routing operation (src/cluster_erp/modules/products_and_services/module.py:806-875). It is used by the routing scaffold described on the BOM module page.

Permissions¶

Privacy, retention, and history¶

The module stores no personal data of its own and has no privacy_handlers.py. A vendor source keeps the vendor party's display name in vendor_name_cache (src/cluster_erp/modules/products_and_services/vendors/models.py:51, src/cluster_erp/modules/products_and_services/vendors/services.py:145-148). Changes are captured by change history.

Analytics facts¶

analytics_facts.py declares one fact set, product, over products_products, with the dimensions material type, status, stock form, sourcing preference, ABC indicator, active, and created date, and the measures product_count and average_lead_time_days (src/cluster_erp/modules/products_and_services/analytics_facts.py:21-87).

Settings and reference data¶

Unit categories and units are reference data in the database. At every start the module seeds the default set from UNIT_SEED_DATA (src/cluster_erp/modules/products_and_services/module.py:37-50, src/cluster_erp/modules/products_and_services/settings/services.py:86-150). The Seed Defaults action runs the same seeding on demand.

Tests¶

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

Discrepancies¶

Terms introduced¶

Related pages¶

• Modules index
• Product breakdown and stock conversion
• Decision record on the product, model, and version breakdown
• BOM module
• Inventory module
• API reference for this module
• Related material, historical, not verified: the in-tree note src/cluster_erp/modules/products_and_services/docs/how-to.md. It does not mention product versions and uses a field default_unit_id, which the product model does not have (src/cluster_erp/modules/products_and_services/products/models.py:103-116).

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