Inventory module
Inventory tracks what the company holds, where it is and what it cost. Purchasing, sales, production, stores and the customer portal all move stock through it.
For the end-user view of these pages — what each screen does and how to use it — see the Warehouse Manager user guide.
Code lives in backend/src/main/java/com/motorph/payroll/inventory/ (plus production/ and sales/portal/). Pages are under frontend/src/pages/inventory/ and frontend/src/pages/production/, in the sidebar's Inventory group.
The one rule: everything goes through the stock ledger
StockLedger (inventory/costing/StockLedger.java) is the only code that changes stock. Each movement writes an immutable stock_transaction row (a database trigger refuses updates and deletes), updates the bin quantity in inventory_stock and recomputes the item's moving-average cost. Corrections are new rows, never edits. Movements must fall in an open inventory period.
Documents that move stock and the rows they post:
| Document | Ledger rows | Page |
|---|---|---|
| Goods receipt | RECEIVING at the receipt cost | /inventory/receiving |
| Delivery (posted) | OUT at average cost | /sales/deliveries |
| Transfer | A pair of TRANSFER rows (out and in), one step | /inventory/transfers |
| Count (posted) | COUNT for each variance | /inventory/counts |
| Opening stock import | OPENING | Stock page, Import |
| Production order (completed) | PRODUCTION_ISSUE per component, one PRODUCTION_RECEIPT at their total cost | /production/orders |
| Store quantity set | ADJUSTMENT to the target quantity, with a reason | /inventory/stores |
| Portal order shipped | Posts its sales order's delivery (OUT) | /inventory/portal-orders |
With perpetual accounting on, InventoryPostingBuilder turns posted rows into journal entries (see accounting.md). Production moves value between inventory accounts only, so it makes no entry.
Warehouses and bins
Any number of warehouses, each with bins (warehouse_location). A store is a warehouse of type STORE with a FLOOR bin (V164). The warehouses page shows per-warehouse totals and a ledger drawer with the running balance per item in that warehouse (V158).
Who sees which warehouse (V159)
user_warehouse_access grants a person view or entry on one warehouse, or on all of them (a row with no warehouse). Entry includes view.
inventory_settings.warehouse_access_mode:OPEN(someone with no grants sees everything, the default) orEXPLICIT(no grants, no warehouses).inventory.warehouses.allbypasses grants;inventory.access.manageedits them at/inventory/access.- Reads are filtered (a hidden record answers 404).
StockLedgerchecks entry on every movement; a transfer needs entry on the source and view on the destination.
Levels, availability and safety stock checks (V160)
item_warehouse_policy holds safety stock, reorder point and quantity, minimum and maximum, lead time and MOQ per item × warehouse. Empty fields fall back to the item's own levels.
vw_item_warehouse_position gives, per item × warehouse: on hand, committed (open approved sales orders), available (on hand − committed), on order, position and a status (OUT, BELOW_SAFETY, BELOW_REORDER, OVER_MAX, OK). The Stock Status tab on the stock page reads it.
Six settings decide what a screen does when it would leave an item below safety stock: OFF, WARN (409, the user confirms and the request is repeated with acknowledgeShortage=true) or BLOCK (422; inventory.safetystock.override may still confirm). The screens: sales order approval, delivery post, customer portal order, transfer out, manual stock-out and production issue. Counts and write-offs are never checked because they record what is already true. StockAvailabilityService.enforce locks the items in id order, like the ledger, so two requests cannot both take the last units.
Imports (V161)
/api/inventory/imports reads .xlsx or .csv (template downloads included). Opening stock and counted quantities are previewed first; every row is validated, and commit posts the whole file or nothing. Each import is an inventory_import_batch.
Live updates and alerts (V162)
- After each commit that moves stock,
InventoryLiveBroadcastersends the affected ids (never quantities) on/topic/inventory-stock.<tenant>. Pages refetch through their normal, access-filtered APIs./inventory/lookupis a phone-sized stock lookup. /inventory/alerts: rules that email people (with an XLSX or CSV attachment) and notify them in the app, on a schedule or when an item crosses a level. Each recipient only gets the warehouses they may see.
Production (V163)
Bills of materials (one active version per item) and production orders: draft → released (component quantities fixed) → completed or cancelled. Completing consumes the components and receives the made item at exactly their cost.
Customer portal orders (V165)
A portal order raises a sales order for the customer behind the portal account, at the portal price (PortalSalesBridge). The account is linked to a sales customer on its first order: an existing active customer with the same email, else a new one.
- Placing: the portal safety stock check runs first. Set to refuse, a short order is turned away naming the items but not quantities. Set to warn, it is accepted and flagged (
stock_short) for staff. - Approval:
portal_auto_approveapproves the sales order straight away unless the sales order check refuses it. Otherwise someone withsales.orders.approveapproves it, at the latest when it ships. - Shipping: marking the shipment
SHIPPED,IN_TRANSITorDELIVEREDraises and posts the delivery (needssales.deliveries.manage). Later updates do not ship it again. - Cancelling: the customer (while pending) or a
FAILEDshipment cancels the sales order. Once the delivery is posted the order can no longer be cancelled; returned goods need their own document. - Catalog: shows In stock, Low stock or Out of stock at the portal warehouse (
portal_warehouse_id, else the default warehouse), never quantities. Withportal_hide_safety_stockon, stock down to safety stock counts as out. - Orders placed before V165 have no sales order. Create sales order in the shipment drawer converts one that has not shipped.
Portal requests run in the portal account's company (TenantContextFilter.narrowToPrincipal), so catalog, stock and sales orders are that company's.
Tests
- ITs (
*IT, run withmvn -o test-compile failsafe:integration-test failsafe:verify -Dit.test=<Name>):WarehouseLedgerIT,WarehouseAccessIT,AvailabilityIT,OpeningStockImportIT,InventoryAlertIT,ProductionOrderIT,StoreStockMigrationIT,PortalOrderLedgerIT. - e2e:
e2e/Inventory/ande2e/Sales/. They share the live database: run them with--workers=1.