PRD: Materials

Module	Inventory	PRD ID	PRD-MAT-001
Status	Superseded	FEAT	MAT
Epic	—	Plane	—
Date	2026-07-13	Version	v1.0
Packages	@nx/inventory	URD	MAT
Surface	Client · Owner/Mgr
Owner	Phát Nguyễn

What a material is

A material (Material) is something used to make something else and never sold directly: milk, tea, pearls, plastic cups. The owner declares it on the Materials screen of the Client app and marks it as a raw material, a semi-finished item, or a consumable.

Materials are the second catalog of Inventory, a peer of the product variant. A material has stock at each inventory location (InventoryLocation) of a merchant (Merchant), is received through purchase orders, and is drawn down either by a bill of materials or by an inventory ticket.

The four stock numbers

Lifted from Stock Items & Levels so you do not have to open another PRD. Every item at every location carries four numbers:

Number	What the system calls it	Meaning
On hand	on-hand	Goods physically sitting at the location
Reserved	reserved	Already promised to another document, no longer sellable to anyone else
Available	available	The part still on offer
Incoming	incoming	Already left the source location, not yet arrived at the destination

The invariant, true at every moment:

Available = On hand - Reserved

Why materials need a catalog of their own

An F&B merchant does not sell milk, it sells milk tea. But what runs out in the back is the milk, the pearls, the plastic cups. A system that only knows about the products being sold cannot answer "how many glasses can we still make tonight", and does not know which carton of milk is about to expire.

What separates materials from products is that they are not managed uniformly. Milk needs stock tracking, lot splitting and expiry dates. Ice cubes can never be counted accurately. Plastic cups only need a heads-up before they run out. That is why the stock configuration flags hang off each material, rather than the whole location running one shared policy.

The second difference is vendors. A merchant buys milk from three places, each with its own price, minimum order quantity and lead time. So the vendor name does not live on the material. It lives on the vendor price list, where every vendor-material pair is its own row.

One material from start to finish

Fresh milk, base unit the litre, low-stock threshold 5 litres, shelf life 7 days. The milk tea recipe calls for 50ml of milk per glass.

What happens	On hand	Reserved	Available	Inventory valuation
Declare the material, opening stock 20 litres at the Kitchen	20	0	20	25,000 VND/litre, entered by hand
Receive 10 litres through a purchase order at 30,000 VND/litre	30	0	30	recomputed from the real receipt price
The cashier taps 1 glass of milk tea into the order	30	0.05	29.95	unchanged
The customer pays, the order completes	29.95	0	29.95	unchanged
The end-of-day stock count reads 29.5 litres	29.5	0	29.5	unchanged

• The hand-entered purchase price only lives until the first receipt. From then on the valuation follows the real receipt price.
• Tapping the item into the order reserves the milk, it does not deduct it. The milk leaves the location for real when the order completes.
• At 4 litres on hand the milk row is flagged low stock, because its threshold is 5 litres.

The easiest thing to get wrong

Stock quantities are never typed in on the material screen

The material edit screen lets you change the name, the category, the units, the stock configuration flags and the vendor list. It has no field for typing a stock quantity back in.

Quantities only change through four doors: a receipt, a sale, a stock transfer, a stock count. Every stock number therefore traces back to a document. The one allowed exception is the opening stock entered when the material is first created.

Consequence: when the book is wrong, raise a stock count and count it again. Do not overwrite the old number.

1. Goals & Non-goals

Goals

• Let a merchant declare and manage a material catalog in the Client app, split across three types: raw material, semi-finished item, consumable.
• Let each material carry its own stock configuration flags: stock tracking, lot tracking, expiry, shelf-life days, allow oversell, low-stock threshold.
• Let a material carry three unit roles (base, purchase, sales) and convert between them through the shared Inventory unit engine.
• Keep the vendor link on the vendor price list only, with no vendor field on the material itself.
• Fold material creation, opening stock across multiple locations, and vendor assignment into a single save.

Non-goals

• Bill of materials quantities (how many ml of milk go into one glass of milk tea) belong to Bill of Materials, not to this PRD.
• How stock is drawn down on a sale and when the ledger is posted belong to Bill of Materials and Stock Reservation.
• How a lot is created on receipt and the FEFO/FIFO picking strategy belong to Lots, Expiry & Picking Strategy. This PRD only declares the on/off flags on the material.
• Weighted moving average (AVCO) costing belongs to Inventory Valuation.
• The vendor price list (price, minimum order quantity, lead time) is fully defined in Vendors. This PRD only covers the material side of that link.
• Reorder points and safety stock belong to Replenishment. The low-stock threshold in this PRD is a simple alert, not a reorder point.

2. Success metrics

Metric	Target / signal
Material catalog coverage	An F&B merchant can declare every material it routinely uses without asking the operations team to enter it for them
Single save	The share of materials created together with their opening stock and vendors on the very first save trends up
Stock configuration quality	Materials with expiry always get a shelf-life day count filled in, rather than left blank and fixed up later
Low-stock alerts	The number of times an owner discovers a material has run out at the counter (instead of being warned ahead) trends down

3. Personas & scenarios

Persona	Goal in this feature
Owner	Declare the merchant's materials once, choose how each one is managed, know where to buy them
Manager	Browse the material catalog, edit stock configuration, watch materials hitting the low-stock threshold
Cashier / Kitchen	Never touch it directly, but live with the consequences: when a material runs out, the dish shows as sold out at the counter
Operations team	Help a merchant build the initial material catalog when it opens

Core scenario: the owner opens the Materials screen in the Client app → hits Create → enters the name "Fresh milk", picks the raw material type, picks a category, sets the base unit to litre → turns on stock tracking, turns on expiry with 7 days, sets a low-stock threshold of 5 litres → enters opening stock of 20 litres at the Kitchen and 10 litres at the Counter → picks two vendors → hits Save once → the material, both stock rows and both vendor links are written together.

4. User stories

#	As an	I want	So that
01	owner	to declare my merchant's materials and mark each one as a raw material, a semi-finished item, or a consumable	my catalog is organised the way I already think about it
02	owner	stock tracking on for milk but ice cubes left outside the warehouse	I never have to count things that cannot be counted accurately
03	owner	to set a 7-day shelf life on fresh milk	the system knows on its own when today's lot expires without me having to remember
04	owner	to allow oversell on ice and straws	the counter is never blocked from selling just because the system count drifted a little
05	owner	one material to link to several vendors, each with its own price	I know where to place the order
06	owner	to declare the material, its opening stock across locations, and its vendors in a single Save	I do not have to walk through three screens to get one material line set up
07	manager	to open the material list and immediately see which ones have hit the low-stock threshold	I can reorder before the merchant runs out

5. Functional requirements

#	Requirement	Status	URD ref
FR-001	A material is declared with the following fields on the Materials screen. • Bilingual display name, required. • Material code, required and unique within the merchant. The owner picks it, the system does not generate one. • Material category, optional. • Description, optional. • Base unit, required: the smallest unit this material is counted in. • Dimensions, required: length, width, height plus a unit of measure. • Weight, optional: a number plus a unit of measure.	🔶	URD-MAT-001 · URD-MAT-003
FR-002	Every material carries one type, chosen from three values. • Raw material: bought and used as is (milk, tea, flour). This is the default. • Semi-finished item: made by the merchant itself and then used as an ingredient in something else, such as cooked tapioca pearls. • Consumable: handed out with the order but not part of it (cups, straws, paper bags). • A semi-finished item with stock tracking on is where BOM explosion stops (see Bill of Materials). Selling an item draws down the semi-finished item's own stock, and the system does not go on to the materials that were used to make it. A pot of broth and house-made tapioca pearls are two examples. • A semi-finished item only gets stock when a production order declares it (see Production Orders).	🔶	URD-MAT-001
FR-003	Every material carries its own set of stock configuration flags. • Stock-tracked or not. Turn it off and this material never touches inventory. • Lot-tracked or not. • Serial-tracked or not, off by default. How serials are generated and scanned belongs to Lots, Expiry & Picking Strategy; here we only keep the on/off flag. • Has expiry or not, plus the shelf-life day count from receipt. • Allow oversell or not, off by default. Turn it on and this material keeps selling even at zero stock. • A low-stock threshold specific to this material.	🔶	URD-MAT-002
FR-004	A material carries three unit roles at once, with its own conversion factor. • Base unit: stock is always stored in this unit. • Purchase unit: the unit prefilled when raising a purchase order for this material. • Sales unit: the unit used when writing bill of materials quantities. • The conversion factor is declared per material and overrides the shared factor from the unit catalog. The owner types "a carton of my milk is 24 cans" and that number applies to that material only. The three roles convert through the shared Inventory unit engine, so beyond that override the owner never multiplies or divides factors by hand.	🔶	URD-MAT-003
FR-005	A material has no vendor field on itself. • Who sells this material is looked up through the vendor price list. • One material can link to several vendors, each with its own price, minimum order quantity and lead time. • Removing a vendor from the price list never strips the material of any of its own information.	🔶	URD-MAT-004
FR-006	Creating a new material finishes in a single Save, stock and vendors included. • Enter the material details and the stock configuration flags. • Enter opening stock at several locations at once, one quantity row per location. • Pick one or more vendors for this material. • If any part of the save fails, nothing is written at all and the form keeps everything already typed in.	🔶	URD-MAT-005
FR-007	Editing a material is also a single save, but stock quantities cannot be edited here. • Editable: name, description, category, units, stock configuration flags, vendor list. • Stock quantities only change through receipts, sales, stock transfers or stock counts. • Turning off stock tracking on a material that still holds stock prompts for confirmation before its inventory is dropped.	🔶	URD-MAT-006
FR-008	An initial purchase price is entered alongside the opening stock. • This number is the material's starting inventory valuation at the moment the catalog entry is created. • From the first receipt onwards, Inventory recomputes the valuation from real receipt prices and the hand-entered number is no longer used.	🔶	URD-MAT-005
FR-009	The low-stock threshold resolves from the most specific to the most general. • If the material's stock row at a location declares its own threshold, that one wins. The Kitchen needs 10 litres of milk, the Counter only needs 2. • If the location has none, fall back to the threshold declared on the material itself. • If neither is set, use the system-wide default of 5 base units.	🔶	URD-MAT-007
FR-010	The Materials screen lists every material of the merchant. • Columns shown: code, name, category, base unit, inventory valuation, current stock, status. • Search by name or code. Filter by category, by material type and by status. • Materials that hit the low-stock threshold are flagged right on their row. • Four stat cards sit at the top of the screen: total materials, materials with stock tracking on, low-stock materials, out-of-stock materials.	🔶	URD-MAT-001 · URD-MAT-007
FR-011	A stock-tracked material becomes a stock item, a peer of the product variant. • It carries all four stock numbers at every location: on hand, reserved, available, incoming. • It is received through purchase orders, reserved and drawn down by a bill of materials, and recounted by a stock count, exactly like any regular item.	🔶	URD-MAT-002
FR-012	A material moves through three statuses: active, discontinued, archived. • Discontinued: no longer offered in the pickers when writing a bill of materials or raising a purchase order. Its stock and history stay intact. • Archived: fully locked, neither details nor stock configuration can be edited. To change anything the material must be reactivated first.	🚧	URD-MAT-008
FR-013	A material is synced to other merchants in the same organizer, right from the material form. • The owner picks one or more of the organizer's other merchants and the system clones the material into each of them. • Removing a merchant from the sync list asks for confirmation, because the copy on that merchant will no longer be kept in sync. • The material at each merchant stays an independent row: the copy's stock, vendor price list and stock configuration are not tied to the original.	🔶	URD-MAT-001 · URD-MAT-005

5.1 Acceptance criteria

• Open the Materials screen from the Inventory menu in the Client app → the merchant's material list shows up with four stat cards at the top: total materials, stock-tracked, low-stock, out-of-stock.
• Hit Create, enter the name "Fresh milk", leave the code blank, set the base unit to litre, hit Save → the save is rejected with a required-field error on the code; fill in the code "SUA-TUOI" and save again → the material is created.
• Create a second material with the same code "SUA-TUOI" in the same merchant → the save is rejected because the code already exists.
• Create a material and pick the "consumable" type for "500ml plastic cup" → after saving, reopen it and the type is still consumable, and filtering the list by that type brings up "500ml plastic cup".
• Turn on expiry for "Fresh milk" with 7 days → receive a lot of milk today → that lot carries an expiry date 7 days after the receipt date.
• Turn on allow oversell for "Ice cubes" and leave it off for "Fresh milk" → sell an item that consumes both at zero stock → the ice cubes go through and post a negative stock figure, the fresh milk is blocked and reported right at the counter.
• Turn off stock tracking for "Straws" while it still holds 200 units → the system prompts before dropping its inventory → confirm → "Straws" no longer appears on the stock screen.
• Declare "Fresh milk" with litre as the base unit, carton as the purchase unit and ml as the sales unit → raise a purchase order for milk → the unit field is prefilled with carton; write a milk tea bill of materials → the unit field is prefilled with ml.
• Declare a material-specific conversion factor for "Canned milk", one carton is 24 cans → receive 2 cartons through a purchase order → stock goes up by 48 cans; another material using the same carton-can pair without its own factor still converts through the shared factor from the unit catalog.
• Receive 10 litres of "Fresh milk" through a purchase order → on hand goes up 10, available goes up 10, reserved is unchanged, incoming drops back to 0; add an item whose bill of materials calls for milk to an order → reserved goes up, available goes down, on hand does not move until the ledger is posted; run a stock count that recounts 8 litres → on hand lands exactly on 8.
• Create "Fresh milk" with opening stock of 20 litres at the Kitchen and 10 litres at the Counter, pick 2 vendors, hit Save once → the material, both location stock rows and both vendor links are all written, with no other screen to visit.
• On the same form, deliberately pick a location that has been deactivated and hit Save → the save is rejected, no material is created, and the form keeps everything already typed in.
• Create "Fresh milk" with an initial purchase price of 25,000 VND per litre → the inventory valuation screen shows 25,000 VND per litre; receive 10 litres at 30,000 VND per litre → the valuation is recomputed from the real receipt price with the hand-entered number gone.
• Remove vendor A from the price list of "Tea" → "Tea" keeps every bit of its own information, losing only vendor A's price list row.
• Open the edit screen for "Fresh milk" → there is no field for typing a stock quantity; change the name, change the category, add a vendor and hit Save → all three changes land in one go.
• Set a low-stock threshold of 5 litres on "Fresh milk" and none on "Tea" → milk drops to 4 litres and tea drops to 4 units → both are flagged as low stock on the list, milk against its own threshold of 5 and tea against the default of 5.
• Set a location-specific threshold of 10 litres on the "Fresh milk" stock row at the Kitchen while the material's own threshold is 5 → the Kitchen holds 8 litres and the Counter holds 8 litres → the Kitchen is flagged low stock against the location threshold of 10, and the Counter is not, since it is still above the material's threshold of 5.
• Open the Materials screen, pick a second merchant of the organizer in the sync section of "Fresh milk" and Save → that merchant now has a "Fresh milk" material of its own; remove that merchant from the sync list → the system asks for confirmation first, and once confirmed the original keeps its stock and vendor price list untouched.
• Move "Glutinous rice flour" to discontinued → open the bill of materials screen and search for it → it is gone from the picker; open the stock screen → its stock is still fully there.
• Move "Glutinous rice flour" to archived and try to edit its low-stock threshold → the system refuses and asks for the material to be reactivated first.

6. Non-functional requirements

Aspect	Requirement
Merchant scoping	Materials, their vendor price lists and their stock all live inside the user's merchant scope; nobody from another merchant can read or edit them
Data integrity	A save covering the material, multi-location stock and vendors is all-or-nothing: if any part fails, nothing is written
Soft delete	Deleting a material is a soft delete and can be restored; its inventory ledger history stays intact
Data constraints	The material code is unique within the merchant; quantities and prices use 4-decimal precision
i18n	Material names and descriptions are bilingual, Vietnamese and English
Scale	An F&B merchant typically declares 50 to 300 materials; list pagination and search must hold up at that scale

7. UX & flows

Creating a material, from opening the screen to the save landing:

How a material enters the rest of Inventory once it has been declared:

8. Data & domain

Concept	Role
Material	Something used to make something else, never sold directly; carries a name, code, category, type, and a set of stock configuration flags
Material type	Raw material, semi-finished item, or consumable; used to group the catalog
Stock configuration flags	Stock-tracked, lot-tracked, serial-tracked, has expiry, shelf-life days, allow oversell, low-stock threshold - declared per material
Three unit roles	Base unit (stock storage), purchase unit (ordering), sales unit (bill of materials quantities), plus an override conversion factor declared per material
Stock item	The bridge that brings a material into the inventory world, the same way a product variant does
Vendor price list	The only home for the link between a material and the vendors that sell it, along with price, minimum order quantity and lead time
Material category	A merchant-defined group used to organise the material list

Conceptual level only - the full schema and invariants live in the inventory domain model.

9. Dependencies & assumptions

Depends on

#	Feature	What it depends on
01	LOC Stock Locations	a material's opening stock must land on a real, active location.
02	UOM Units of Measure & Conversion	a material's three unit roles come from the unit catalog, and the conversion engine handles the factor arithmetic.
03	VEN Vendors	the vendor price list is the only home for the link between a material and whoever sells it.
04	STK Stock Items & Levels	a stock-tracked material shares the same four stock numbers as a product variant.
05	BOM Bill of Materials	a material is only ever really drawn down when a bill of materials calls for it.

Assumptions

#	Assumption	What breaks if it is wrong
01	An F&B merchant will accept the one-time effort of declaring the material catalog when it opens, in exchange for knowing how many glasses can still be made.	A half-declared catalog leaves the recipes with no components to call, and the whole material-based drawdown stops meaning anything.
02	Not every material needs stock tracking, and the owner is the one who decides which ones do.	Forcing stock tracking on every material makes the merchant count ice cubes and straws, and the stock figures fill up with rows nobody believes.
03	Buying one material from several vendors is the normal case, not the exception.	If in reality a material only ever has one vendor, a separate price list is overhead, and a plain vendor field on the material would be simpler.

10. Release plan & criteria

Aspect	Plan
Phase	P2 (Inventory) - see the feature URD catalog
Rollout	F&B merchants first, then open to every merchant; no feature flag
Migration	No material needs a data migration; the material catalog is declared from scratch by the merchant
Release criteria	A merchant opens the Materials screen from the Inventory menu, creates a material together with multi-location stock and vendors in a single save, and that material is drawn down correctly when a dish whose bill of materials calls for it is sold
Monitoring	Materials declared per merchant, share of materials with stock tracking on, number of low-stock alerts fired

References

• URD: Inventory - Materials
• Related: Stock Items & Levels · Units of Measure & Conversion · Vendors · Bill of Materials · Lots, Expiry & Picking Strategy
• Module: Inventory - URD
• Developer: @nx/inventory · domain model

Risks & open questions

#	Risk / question	Mitigation / status
01	Declaring the material catalog is a chore and the owner gives up halfway	Fold the material, multi-location stock and vendors into a single save (FR-006); the operations team helps build the initial catalog when the merchant opens
02	The owner turns on allow oversell for every material just to keep things easy, and the stock numbers stop meaning anything	The flag is off by default and is set per material, never for the whole location (FR-003)
03	Turning on lot tracking for materials that do not need lots makes receiving heavier than it should be	The lot flag is off by default and is only turned on for materials that genuinely need traceability (FR-003)
04	Turning off stock tracking on a material that still holds stock wipes out the stock on hand	The system prompts for confirmation before the inventory is dropped from the material (FR-007)
05	Editing the stock configuration of an archived material distorts historical numbers	Archived materials are locked from editing and must be reactivated first (FR-012)
06	A default low-stock threshold of 5 base units does not suit every material (5 litres of milk is not 5 grams of tea)	Open: let a merchant set their own default threshold instead of a hard-coded system number
07	A hand-entered initial purchase price can be far off the real receipt price	The number is only the starting inventory valuation and is replaced by the real receipt price from the very first receipt (FR-008)

Frequently asked questions

#	Question	Answer
01	How is a material different from a product?	A product is what you sell to a customer. A material is what you use to make the product, and it is never sold directly. From Inventory's point of view the two are the same thing: both are stock items, both carry the four stock numbers, both are received through purchase orders.
02	Does every material have to be stock-tracked?	No. Each material carries its own stock tracking flag. Turn it off and the material still sits in the catalog and still works in a bill of materials, it just does not draw down stock when the dish is sold.
03	Why is there no "vendor" field on a material?	Because a material is usually bought from several places, each with its own price and minimum order quantity. A single field on the material cannot hold that. The link lives on the vendor price list, one row per vendor-material pair.
04	What are "shelf-life days" for?	So the system can compute the expiry date for a lot when it is received. Set 7 days on fresh milk, and a lot received today automatically carries an expiry 7 days out, with no owner typing dates lot by lot.
05	If I allow oversell, is negative stock a problem?	Not for selling, the counter keeps working. But negative stock means the system numbers have drifted from reality, and the next stock count is what pulls them back into line.
06	When does each of the three unit roles get used?	The base unit stores stock, always. The purchase unit is prefilled when raising a purchase order. The sales unit is prefilled when writing bill of materials quantities. You buy a carton of 24 cans of milk, stock is still stored in cans, and the recipe still works in ml.
07	Can I edit stock quantities on the material screen?	No. Quantities only change through receipts, sales, stock transfers or stock counts, so that every stock number traces back to a document. The one allowed exception is the opening stock entered when the material is created.