PRD: Replenishment

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

What replenishment is

Replenishment is the order-suggestion screen on the Client app: the list of items that need reordering, with a suggested order quantity next to each one.

It runs on the stock of the inventory locations (InventoryLocation) of one merchant (Merchant), and answers two questions: what needs ordering today, and which class of goods the merchant's capital is sitting in. This is a suggestion tool. It does not raise purchase orders by itself, and it blocks nothing the owner wants to do.

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

The number this whole feature compares against is available.

Why a hand-typed threshold is not enough

A low-stock threshold typed in by hand on each stock item is the crudest tool for knowing when to buy more, because it is a static number. It has no idea whether the item is selling fast or slow, or whether the vendor delivers in two days or two weeks. A merchant selling 20 glasses a day and one selling 200 glasses a day both get the same alert at 10 cans of milk, even though one of them has half a day of cover left and the other has a full week.

Replenishment replaces that static number with a moving one: reorder when stock is only just enough to last until the next delivery arrives, plus a cushion for the days you sell more than usual or the vendor runs late. The inputs are already in the system. Sales velocity comes from sales history, lead time comes from the vendor-item record.

Alongside it comes the second question every merchant owner asks: out of hundreds of items, which ones are worth the attention. ABC classification answers that by consumption value, quantity sold times inventory valuation. The point here is controlling the capital tied up in stock, not spotting which item posts pretty revenue.

One item from start to finish

Canned milk. History window 30 days. The preferred vendor delivers in 3 days on average, 5 days at worst. Pack size 24 cans per case, minimum order quantity 2 cases.

Number	Where it comes from	Value
Average daily sales	30 days of sales history	20
Peak daily sales	the same window	35
Average lead time	real goods-receipt history	3 days
Longest lead time	real goods-receipt history	5 days
Safety stock	(35 x 5) - (20 x 3)	115
Reorder point	(20 x 3) + 115	175

• Available at 200: the item does not show up in the To-order list.
• Available drops to 170: the item does show up, because 170 is already below 175.
• The gap is 30 cans, but the suggested order quantity reads 2 cases (48 cans), because it always rounds up to the pack size and the minimum order quantity.
• The inventory manager types safety stock of 50 by hand: the reorder point is recomputed to 110. The hand-typed number always beats the formula result.

The easiest thing to get wrong

Missing data means an empty cell, never an invented number

An item with fewer than 14 days of actual sales, or with no vendor declaring a lead time, prints no number at all. It prints exactly what is missing instead: "Not enough sales history", "No lead time declared".

Treating an undeclared lead time as 0, or reading sales velocity out of three days of data, both produce a figure that looks scientific and that nobody can check. The merchant believes it and orders wrong.

Consequence: a row missing its lead time carries a shortcut straight into that item's vendor screen, so the merchant can declare it on the spot and come back.

1. Goals & Non-goals

Goals

• Compute a reorder point per item from real sales velocity and the vendor's lead time.
• Give safety stock a default that can be computed immediately from thin data, and let the owner override it with their own number.
• Be honest when the data is not sufficient, instead of printing a number nobody should trust.
• Show the list of items sitting below their reorder point, with a suggested order quantity already rounded to the vendor's pack size and minimum order quantity.
• Sort items into class A, B, C by consumption value, with adjustable class thresholds.
• Suggest a cycle-count cadence per ABC class.

Non-goals

• Raising purchase orders automatically from a replenishment suggestion. The owner clicks to create the order from the list; the system never sends anything to a vendor by itself.
• Demand forecasting for seasonality, promotions, or holidays.
• Order-quantity optimisation against ordering cost and holding cost.
• Rebalancing stock across inventory locations (automatic transfers).
• Blocking sales or any other operation when an item drops below its reorder point.

2. Success metrics

Metric	Target / signal
Stockout count	Trends down once the merchant works the To-order list into purchase orders
Suggestion trust	The merchant keeps the suggested order quantity most of the time, rather than typing over it
Data coverage	The share of items with enough data to compute a reorder point rises as the merchant fills in vendor lead times
Capital in stock	The merchant can see what percentage of consumption value class A holds, and tune stock levels for that class
Counting rhythm	Class A items get counted more often than class C once the cadence suggestion is on

3. Personas & scenarios

Persona	Goal in this feature
Merchant owner	Know what to order today and how much; know which class their capital is sitting in
Inventory manager	Set safety stock for the items they know well; use ABC classes to schedule cycle counts
Purchasing staff	Open the To-order list, pick a vendor, and raise a purchase order from it

Core scenario: the owner opens the Replenishment screen first thing in the morning → sees 12 items that have dropped below their reorder point → reviews the suggested order quantity on each line, adjusts a few by feel → selects the lines that share a vendor → clicks to create the purchase order.

4. User stories

#	As a	I want	So that
01	merchant owner	the system to tell me which items need reordering today	I do not have to walk the shelves and guess
02	merchant owner	the reorder point computed from my merchant's real sales velocity and my vendor's real lead time	I do not have to live with a fixed threshold I typed in last year
03	inventory manager	to type safety stock in by hand for the items I know well	I always keep the two spare crates of milk I have always kept
04	merchant owner	the system to say plainly that the data is not sufficient	I am not handed a number I would not dare trust
05	purchasing staff member	the suggested order quantity already rounded to cases and to the vendor's minimum order quantity	I do not have to redo the arithmetic myself
06	merchant owner	to know which items eat the most capital	I can watch those closely and stop fussing over the small stuff
07	inventory manager	the system to suggest which items to count this week	I can cycle-count instead of shutting down to count everything at once

5. Functional requirements

#	Requirement	Status	URD ref
FR-001	The low-stock alert runs on three threshold tiers, uses the first tier that is declared, and is independent of the velocity-driven reorder point described below. • Per-stock-item threshold: the merchant types it directly on the Inventory screen. • Per-item threshold: the merchant declares it on the item form, and it applies across every location. • System default threshold: the merchant declares nothing and still gets an alert at this default number. • The system raises the alert when available stock falls to or below the threshold in force while still being above 0. Stock at 0 or negative is a different state - out of stock, or oversold - no longer low stock.	🔶	URD-STK-005
FR-002	The system computes an item's average daily demand from sales history. • The history window defaults to the last 30 days and the merchant can change it in the replenishment settings screen. • Quantity sold is measured in the item's base unit, and includes the volume exploded out of a prepared product's bill of materials. • From the same window, the system takes the peak sales day to feed the safety stock formula.	🚧	URD-RPL-001
FR-003	An item's reorder point equals average daily demand times lead time, plus safety stock. • Lead time comes from the vendor-item record of the vendor marked as preferred. • For an item with no preferred vendor, the system takes the longest lead time among the vendors currently offering that item. • The reorder point is computed per item, against available stock aggregated across every inventory location.	🚧	URD-RPL-001 · URD-VEN-003
FR-004	Default safety stock follows the max-min formula. • Formula: (peak daily sales x longest lead time) minus (average daily sales x average lead time). • Longest and average lead time come from the item's real goods-receipt history. With no receipt history yet, both fall back to the number of days declared on the vendor-item record. • If the formula goes negative, safety stock is 0.	🚧	URD-RPL-002
FR-005	The merchant types safety stock in by hand on the item's own row. The hand-typed number always beats the formula result until the merchant clears it.	🚧	URD-RPL-003
FR-006	The system prints no suggested number when the data is not sufficient, and says exactly what is missing. • An item with fewer than 14 days of actual sales inside the history window: the row reads "Not enough sales history". • An item with no vendor declaring a lead time: the row reads "No lead time declared", with a shortcut that opens the item's vendor screen directly. • Once the merchant has typed safety stock in by hand, the row still computes a reorder point even on thin sales history.	🚧	URD-RPL-001
FR-007	The statistical formula based on standard deviation and service level is an advanced option, not the formula that runs by default. • The merchant turns it on per item, never once for the whole merchant. • It is never the default. Any item left alone keeps using the max-min formula. • It only unlocks for items with 90 days of sales history or more.	🚧	URD-RPL-004
FR-008	The To-order screen lists the items whose available stock has fallen to or below their reorder point. • Columns: item, available stock, reorder point, safety stock, preferred vendor, lead time, suggested order quantity. • The suggested order quantity brings stock back up to one full delivery cycle of cover measured from the reorder point, then rounds up to the preferred vendor's pack size and minimum order quantity. • The merchant can edit the suggested order quantity inline on the row. • The merchant selects several rows sharing one vendor and clicks to create a purchase order. The selected rows carry straight into the new purchase order.	🚧	URD-RPL-008 · URD-RPL-009 · URD-VEN-003
FR-009	The system sorts items into class A, B or C by consumption value. • An item's consumption value is the quantity sold in the period times the item's current inventory valuation. • Items are ranked by consumption value descending, then the cumulative share cuts the classes. • The merchant can switch the classification basis to revenue, but inventory valuation is the default. • The classification period defaults to the last 90 days and is adjustable.	🚧	URD-RPL-005
FR-010	The A/B/C class thresholds default to 80/15/5 of cumulative consumption-value share, and the merchant can change them. • The merchant types their own three numbers in the replenishment settings screen. • The three numbers must add up to 100; anything short of 100 will not save. • Once the thresholds change, every item is reclassified against the new ones.	🚧	URD-RPL-006
FR-011	An item's ABC class drives its suggested cycle-count cadence. • Default cadence: class A weekly, class B monthly, class C quarterly. The merchant can change each class. • An item overdue against its class cadence is flagged "Due for count" and pre-selected when the merchant opens a new stock count. • This is a suggestion. It never stops the merchant counting whatever they like.	🚧	URD-RPL-007
FR-012	The replenishment settings screen holds the parameters shared across the whole merchant. • The history window for average daily demand, 30 days by default. • The ABC classification basis (inventory valuation or revenue) and the classification period, valuation and 90 days by default. • The three A/B/C class thresholds, 80/15/5 by default. • The suggested cycle-count cadence per class.	🚧	URD-RPL-006 · URD-RPL-007

5.1 Acceptance criteria

• Type a low-stock threshold of 10 on a stock item, sell down until available stock is exactly 10 → the stock item shows the low-stock alert (at the threshold already counts as an alert); keep selling until available stock hits 0 → the stock item flips to out of stock and is no longer low stock.
• A stock item with no threshold of its own, whose item declares no shared threshold either → the stock item still gets a low-stock alert at the system default threshold.
• An item with no preferred vendor assigned but two vendors declaring lead times of 3 days and 6 days → that item's reorder point is computed on 6 days, the longest lead time.
• A material only consumed through a prepared product's bill of materials, never sold directly → sell 100 glasses of a product using 30ml of the material each → the material's demand records 3,000ml, not 0.
• An item selling 20 units/day on average with a peak of 35 units/day; the vendor delivers in 3 days on average, 5 days at worst → open the To-order screen → safety stock reads 115 and the reorder point reads 175.
• Same item, sell down until available stock is 170 → the item appears in the To-order list; leave stock at 200 → it does not.
• Peak daily sales equal to average daily sales, and the longest lead time equal to the average lead time → safety stock reads 0, never a negative number.
• Type safety stock of 50 by hand on an item the formula puts at 115 → the reorder point is recomputed on 50; clear the hand-typed number → the reorder point goes back to 115.
• Open the To-order screen with an item that has only 5 days of sales → that row reads "Not enough sales history" and prints no reorder point.
• An item with no vendor declaring a lead time → the row reads "No lead time declared" with a shortcut to the item's vendor screen; declare a 4-day lead time and come back → the row now shows a full reorder point.
• An item with only 5 days of sales but a hand-typed safety stock → the row still computes a reorder point and raises no missing-history message.
• Open the advanced option on an item with 30 days of sales history → the standard-deviation formula cannot be turned on; open it on an item with 120 days → it can.
• An item with a pack size of 24 units per case and a minimum order quantity of 2 cases, needing 30 units of replenishment → the suggested order quantity reads 2 cases (48 units), not a loose 30 units.
• Select 3 rows sharing one vendor in the To-order list and click to create a purchase order → a new purchase order opens with exactly those 3 lines, the suggested order quantities, and the chosen vendor.
• Item X sells 100 units at a valuation of 50,000; item Y sells 500 units at a valuation of 2,000 → run ABC classification → X ranks above Y on consumption value (5,000,000 against 1,000,000), even though Y moved more units.
• Change the class thresholds from 80/15/5 to 70/20/10 and save → the ABC table is reclassified on 70/20/10; type 70/20/5 → it will not save, and reports that the three thresholds must add up to 100.
• Switch the classification basis to revenue → the ABC table is reclassified on revenue, and a fast-moving cheap item climbs to a higher class than it held on valuation.
• A class A item last counted 10 days ago (class A cadence is weekly) → the item is flagged "Due for count" and pre-selected when a new stock count is opened.
• In the settings screen, change the class B cadence from monthly to fortnightly and save → a class B item last counted 20 days ago flips to "Due for count", where it was not yet due before.
• Open the replenishment settings screen and change the history window from 30 days to 60 days → average daily demand and the reorder point are recomputed for every item on the 60-day window.

6. Non-functional requirements

Aspect	Requirement
Performance	The To-order screen opens within 3 seconds for a merchant with 5,000 items; sales velocity figures are precomputed on a background schedule, never recomputed from scratch on each page open
Data freshness	Average daily demand and the ABC classification are recomputed at least once a day; the screen states when the last computation ran
Numeric accuracy	Quantities carry 4 decimal places; the suggested order quantity always rounds UP, never down into a shortage
Never blocking	Every number here is a suggestion; none of them blocks a sale, a purchase order, or a stock count
Per-merchant isolation	Replenishment settings, hand-typed safety stock, and ABC classification results are all isolated per merchant
Data honesty	An item missing an input shows the reason it is missing, never a guessed number

7. UX & flows

The Replenishment screen sits in the Inventory group on the Client app and carries two tabs: To-order (the items below their reorder point) and ABC classification (the ranking by consumption value). The shared settings live behind a Settings button in the top right of the screen.

8. Data & domain

Concept	Role
Average daily demand	The average number of units an item sells per day, measured over a configurable history window
Peak daily sales	The single biggest sales day inside that same window, an input to the safety stock formula
Lead time	The number of days between placing an order and receiving the goods, declared on the vendor-item record and reconciled against real goods-receipt history
Safety stock	The cushion held back to absorb a spike in sales or a late delivery; either computed by the max-min formula or typed in by the merchant
Reorder point	The level of available stock at which it is time to order: average daily demand x lead time + safety stock
Suggested order quantity	The quantity to buy to bring stock back to one full delivery cycle of cover, rounded up to pack size and minimum order quantity
Consumption value	Quantity sold in the period times current inventory valuation; the default basis for ABC classification
ABC class	Three item classes cut from the cumulative consumption-value share, 80/15/5 by default
Cycle-count cadence	The suggested interval between two counts of an item, derived from its ABC class

Conceptual level only - the full schema lives in the inventory domain model.

9. Dependencies & assumptions

Depends on

#	Feature	What it depends on
01	Sales history	the only source of average daily demand and the peak sales day; a prepared product must explode down to its materials before those materials show any sales at all.
02	VEN Vendor-item	the source of lead time, pack size and minimum order quantity; without it there is no reorder point to compute.
03	VAL Inventory Valuation	the source of consumption value when ABC classifies on valuation.
04	STK Stock Items & Levels	the source of available stock, the number compared against the reorder point.
05	PO Purchase Orders	where the rows selected in the To-order list are carried across.
06	CNT Stock Count	where the ABC-driven cycle-count cadence is put to use.

Assumptions

#	Assumption	What breaks if it is wrong
01	The merchant declares lead times at least for the items that matter to them; items left blank simply get no suggestion.	If nobody declares a lead time, the To-order screen is empty and the whole feature has nothing to show.
02	Demand over the history window forecasts the next delivery cycle well enough; no seasonal spike or promotion distorts that window.	A peak landing right after the history window drags the reorder point below real demand, and the merchant runs out exactly when sales are strongest.
03	The merchant understands these are suggestions and remains the one deciding how much to order.	A merchant ordering mechanically off the number turns one batch of dirty data into one wrong purchase order, and takes the trust in the whole screen down with it.
04	An item's inventory valuation is trustworthy enough to serve as the ABC classification basis.	Wrong valuations rank the ABC table wrong, and the merchant pours attention into exactly the class that does not eat capital.

10. Release plan & criteria

Aspect	Plan
Phase	P2 (Inventory) - see the URD feature catalogue; sequenced after the foundational Inventory features
Rollout	Every merchant; the Replenishment screen only suggests, it automates nothing. It does write data (hand-typed safety stock, the shared settings, and purchase orders the merchant chooses to create), but it changes no running sales, receiving or counting flow
Migration	No stock data changes; the replenishment settings take their defaults (30 days, 80/15/5, inventory valuation, 90 days) for every merchant
Release criteria	Reorder point and safety stock match a hand calculation over a sample set; items missing data show the correct reason; creating a purchase order from the list carries the right lines at the right quantities
Monitoring	The share of items with enough data to compute, the share of merchants typing over the suggested order quantity, the number of purchase orders raised from the To-order screen

References

• URD: Replenishment
• Related: Vendors · Purchase orders · Inventory valuation · Stock items & levels · Stock count
• Module: Inventory - URD
• Developer: @nx/inventory · domain model

Risks & open questions

#	Risk / question	Mitigation / status
01	A newly opened merchant has thin, dirty sales data, and the formula produces a meaningless number that still looks scientific	The statistical formula is never the default; the simple max-min formula runs instead, and the number is hidden outright below 14 days of sales history (FR-006)
02	A merchant who never declares lead times gets nothing out of the feature	The row missing that data carries a shortcut straight into the item's vendor screen so it can be declared on the spot (FR-006)
03	Seasonality and promotions pull average daily demand far away from reality	The history window is adjustable, and the merchant can type over safety stock when they see a peak coming (FR-005)
04	The 80/15/5 ABC thresholds do not fit a long-tail industry like multi-SKU retail	The thresholds are adjustable per merchant (FR-010)
05	If a prepared product sells but its materials never explode into sales figures, those materials always look short on history	Settled: the material volume exploded out of the bill of materials is added to that material's own average daily demand (FR-002); materials of a product with no bill of materials declared land in the missing-history state with the reason spelled out (FR-006)
06	Rounding the suggested order quantity up to a full case can far overshoot real demand on a slow-moving item	The merchant edits the quantity inline before creating the purchase order (FR-008)
07	Picking a 90-day ABC classification period for a merchant open only 2 months	Open: decide how the ABC classes are presented when the available history is shorter than the configured classification period
08	The default numbers in this PRD are not yet ratified by the PO as business rules: the 14-day minimum history before a number is printed (FR-006), the 30-day demand window (FR-002), the 90-day ABC classification period (FR-009) and the 90-day minimum to unlock the statistical formula (FR-007), the weekly/monthly/quarterly count cadence (FR-011), reading longest and average lead time from real goods-receipt history (FR-004), and taking the longest lead time when an item has no preferred vendor (FR-003)	Open: the PO ratifies the whole cluster in one pass. All of it is written down in URD-RPL-001/002/004/006/007 so the FRs have a source; if the PO agrees they stand as they are, and any number the PO changes is edited in the URD first, with the PRD following

Frequently asked questions

#	Question	Answer
01	How is the reorder point different from the low-stock threshold I type in today?	The low-stock threshold is a static number you type; it has no idea whether you are selling fast or slow. The reorder point is computed from real sales velocity and your vendor's lead time, so it rises when you sell more and falls when you sell less. The two run side by side and you can use both.
02	Why not use a statistical formula for safety stock, so it is more accurate?	A statistical formula only earns its accuracy on long, clean sales history. For a merchant open a few months it produces junk that looks very scientific, which makes it easy to believe. The max-min formula needs only four numbers you can actually see, and you can check it by hand. If you do have the history, turn the advanced option on.
03	What if I already know my own safety stock level?	Type it straight into that item's row. Your number always beats what the formula computes, until you clear it.
04	Why does ABC use inventory valuation rather than revenue?	Because ABC here exists to control the capital tied up in stock, not to show which item posts pretty revenue. An item that sells rarely but costs a lot still eats more of your capital than a cheap fast mover. If you would rather look at revenue, switch the classification basis in the settings screen.
05	Where does 80/15/5 come from and do I have to follow it?	It is the common split, used as a default so you get an ABC table without having to think about it. Multi-SKU retail and a small-menu F&B merchant have very different distributions, so you can retune it for your own merchant, as long as the three numbers add up to 100.
06	Will the system order for me?	No. The system only produces the list and the suggested quantities. You review them, adjust anything that looks off, and create the purchase order yourself.
07	How do ABC classes affect stock counts?	Class A eats the most capital, so it is suggested for more frequent counting (weekly by default), and class C for less (quarterly by default). It is a suggestion so you can cycle-count instead of shutting down to count everything, and you are still free to count whatever you like.