Inventory module (inventory)

The inventory module in src/cluster_erp/modules/inventory/ keeps the stock of the company. It holds warehouses and storage locations, one stock level row per product, model, version, place, batch, owning project, and custodian, and the goods movements that change those rows. It also manages stock reservations, usage decisions on received goods, project stock loans, batches, and serial numbers. Purchasing, production, nesting, and sales post their stock changes to this module through the EventBus.

At a glance¶

What the module does¶

• Keeps warehouses with a code that is unique among live rows, and their storage locations (src/cluster_erp/modules/inventory/warehouses/models.py:13-71).
• Keeps stock per product, model, and version. The quantity is split into six categories: unrestricted, reserved, quality, blocked, blocked at goods receipt, and returns (src/cluster_erp/modules/inventory/stock/models.py:25-123).
• Posts goods movements of 13 types and writes one movement row per change (src/cluster_erp/modules/inventory/stock/services.py:78-92).
• Reserves unrestricted stock for a reference and later consumes or cancels the reservation (src/cluster_erp/modules/inventory/stock/services.py:1901-2080).
• Records a usage decision on a received quantity and posts the follow-up movement (src/cluster_erp/modules/inventory/stock/services.py:1496-1666).
• Moves stock between a project stripe and common stock, and lends stock between stripes with a payback (src/cluster_erp/modules/inventory/stock/services.py:542-800).
• Tracks batches with origin, expiry, and status, and serial numbers with status (src/cluster_erp/modules/inventory/batches/models.py:14-125).
• Serves a warehouse dashboard read model (src/cluster_erp/modules/inventory/warehouses/services.py:145).

Sub-modules¶

All routers are mounted under the module prefix with the app entitlement dependency require_app("inventory") (src/cluster_erp/modules/inventory/module.py:52-62).

Data model¶

The stock key always carries the product breakdown. The partial unique index uq_stock_level_composite covers product, model, version, and warehouse, plus location, batch, owning project, and custodian with NULL coalesced, on live rows only (src/cluster_erp/modules/inventory/stock/models.py:27-47). Quantities are Numeric(14, 4) (src/cluster_erp/modules/inventory/stock/models.py:91-122). The module stores no money column; the analytics docstring states this (src/cluster_erp/modules/inventory/analytics_facts.py:17-18). The product breakdown is checked through the EventBus with ensure_product_breakdown, not by database foreign keys (src/cluster_erp/core/product_breakdown.py:86, src/cluster_erp/modules/inventory/stock/services.py:370-376).

Screens and metadata¶

get_metadata declares a sidebar group Inventory (Turkish Envanter) with eight sections: Warehouse Dashboard (custom widget warehouse_dashboard), Warehouses, Stock Levels, Goods Movements, Batches, Serial Numbers, Usage Decisions, and Stock Reservations (src/cluster_erp/modules/inventory/module.py:536-626). The 14 entity keys include drill-down views such as warehouse_stock_level, batch_movement, and product_stock_level (src/cluster_erp/modules/inventory/module.py:628-643). The web dashboard calls one read model, GET /inventory/warehouses/dashboard (gated_apps/inventory/app.js:7-11, src/cluster_erp/modules/inventory/warehouses/routes.py:99). The web app renders the rest generically; see generic list and gated app bundles. The desktop dashboard is described on desktop module screens.

Status and actions¶

Stock has no status field; movements change quantities. A reservation is active, consumed, or cancelled (src/cluster_erp/modules/inventory/stock/services.py:1950, src/cluster_erp/modules/inventory/stock/services.py:2015, src/cluster_erp/modules/inventory/stock/services.py:2068). A movement carries is_reversed (src/cluster_erp/modules/inventory/stock/models.py:253-257).

The ActionMeta class has no permission field; the permission comes from the route's require_permission (src/cluster_erp/core/metadata.py:418-434). The routes for ownership transfer and project loans have no ActionMeta (src/cluster_erp/modules/inventory/stock/routes.py:217-289).

Business rules¶

• Every posting first asks GetProductById and refuses a product that is not stockable (src/cluster_erp/modules/inventory/stock/services.py:2119-2134).
• A batch-managed product needs a batch, and a serial-tracked product needs a serial number. A blocked or expired batch is refused (src/cluster_erp/modules/inventory/stock/services.py:2136-2193).
• A goods receipt adds to the unrestricted quantity of the matching stock row and creates the row when it is missing. The row is read with a row lock (src/cluster_erp/modules/inventory/stock/services.py:2195-2286).
• A goods receipt that names a purchase order as reference is refused; purchase order receipts go through the procurement receive flow (src/cluster_erp/modules/inventory/stock/routes.py:166-178).
• A decrease takes the requested quantity from the given project stripe. A goods issue may take the rest from common stock and then writes one movement per stripe; the other decreases refuse a shortfall (src/cluster_erp/modules/inventory/stock/services.py:2288-2363, src/cluster_erp/modules/inventory/stock/services.py:473-490).
• A transfer between two project stripes is refused unless the setting allow_project_to_project_stock_transfer is on (src/cluster_erp/modules/inventory/stock/services.py:552-566).
• A project loan needs two different sides, at least one of them a project (src/cluster_erp/modules/inventory/stock/services.py:615-640).
• An adjustment sets the unrestricted quantity to the new value and records the difference as the movement quantity (src/cluster_erp/modules/inventory/stock/services.py:1051-1100).
• Stock categories move only along nine allowed pairs, for example gr_blocked to unrestricted or quality to blocked (src/cluster_erp/modules/inventory/stock/services.py:112-122).
• A usage decision applies only to a goods receipt or a blocked goods receipt, and not beyond the undecided quantity. accept and conditional_accept move to unrestricted, reject returns to the vendor, rework moves to blocked, and scrap posts a scrap movement (src/cluster_erp/modules/inventory/stock/services.py:124-135, src/cluster_erp/modules/inventory/stock/services.py:1496-1625).
• A reservation moves quantity from unrestricted to reserved. Consuming removes it from reserved; cancelling returns it to unrestricted (src/cluster_erp/modules/inventory/stock/services.py:1901-2080).
• A movement can be reversed once, and a reversal movement cannot be reversed (src/cluster_erp/modules/inventory/stock/services.py:1730-1760).
• Batch origin is customer, supplier, or internal (src/cluster_erp/modules/inventory/batches/services.py:35).
• Movement numbers come from the yearly sequence goods_movement, decisions from usage_decision, and loans from stock_loan (src/cluster_erp/modules/inventory/stock/services.py:383).

Events and queries¶

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

The query handlers for reservations and postings commit their own session (src/cluster_erp/modules/inventory/module.py:410, src/cluster_erp/modules/inventory/module.py:465, src/cluster_erp/modules/inventory/module.py:494). The field-consumer answer marks the product flag is_stockable as a hard dependency and batch_managed and serial_tracked as soft ones (src/cluster_erp/modules/inventory/module.py:646-696); see tenant fields.

Permissions¶

Privacy, retention, and history¶

The module has no privacy_handlers.py. Warehouse, location, batch, and serial deletes set deleted_at (src/cluster_erp/modules/inventory/warehouses/services.py:137-143, src/cluster_erp/modules/inventory/batches/services.py:178-184). Movements have no delete route; a wrong movement is reversed by a counter movement (src/cluster_erp/modules/inventory/stock/routes.py:376-450, src/cluster_erp/modules/inventory/stock/services.py:1730). Changes are captured by change history.

Analytics facts¶

analytics_facts.py contributes one fact set, goods_movement, over inventory_goods_movements. Its dimensions are movement type, product, warehouse, party, reference type, reversal flag, and posting date. Its measures are movement_count and total_qty, read with goods_movement.read (src/cluster_erp/modules/inventory/analytics_facts.py:29-104). Stock levels are not contributed; the docstring gives the reason (src/cluster_erp/modules/inventory/analytics_facts.py:1-8). See analytics facts.

Settings and reference data¶

The module has no settings section. The project-to-project transfer switch is the server setting allow_project_to_project_stock_transfer, default False, read through Settings (src/cluster_erp/config/settings.py:184, src/cluster_erp/modules/inventory/stock/services.py:561); see settings reference.

Tests¶

Found by a grep for modules.inventory in tests/ (no hit) and for the path /inventory/ in web-client/_e2e_*.mjs.

Discrepancies¶

Terms introduced¶

Related pages¶

• Modules index
• Procurement module
• Production module
• Product breakdown and stock conversion
• Soft delete and deactivation
• API reference for this module

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