PRD: Units of Measure & Conversion

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

What units of measure and conversion are

A merchant counts goods in several ways at once: they buy Coke by the case and sell it by the can, buy sugar in 25 kg sacks and measure it into a recipe in grams. A unit of measure is the catalog of those ways of counting, and conversion is what brings every number onto one common scale.

The system ships a shared set of units out of the box (piece, box, case, kg, g, litre, ml and so on), usable from day one. A merchant adds their own units when the shared set falls short.

The base unit and the three roles

Every item declares three unit roles. This is the vocabulary every other Inventory PRD leans on whenever it talks about a quantity:

Role	Meaning	Required
Base unit	The smallest unit the item is counted in. All stock is always held in this unit, and its factor is always 1	Yes
Purchasing unit	The default unit when raising a purchase order and receiving goods	No
Selling unit	The default unit when selling	No

The number sitting in a stock item is always a number in the base unit. Paperwork written in cases or in sacks still raises stock in the base unit, after conversion.

Why the document author does not multiply the factor

Stock has to settle on one common unit, otherwise the arithmetic is meaningless: 2 cases plus 5 cans adds up to nothing usable.

Pushing the conversion work onto whoever writes the document - giving the line a factor field and letting the person multiply by hand - is how stock figures rot. One bad entry and the number is wrong forever, and nobody notices until the next stock count.

There is a second problem specific to the Vietnamese market: a "case" of Coke is 24 cans, a case of beer is 20 cans, a case of instant noodles is 30 packs. Force the factor to live in the shared unit catalog and the merchant has to spawn "case-24", "case-20", "case-30". The catalog bloats, people keep picking the wrong one, and reports can no longer group anything together.

Three items, one "case" unit

The catalog holds exactly one "case" unit. The packaging spec is declared on each item instead.

Item	Base unit	Purchasing unit	Declared on the item	Receive 2 purchasing units	Stock rises by
Coke	can	case	24	2 cases	48 cans
Beer	can	case	20	2 cases	40 cans
Sugar	g	kg	blank	5 kg	5000 g

• Coke and beer use the same "case" unit from the catalog and still produce two different numbers. The number declared on the item beats the catalog's shared factor.
• Sugar leaves the override blank, so the system walks the catalog's chain of factors: 1 kg = 1000 g. That is the right answer for standard measurement units, because 1 kg is 1000 g everywhere.
• The document author only picks a unit and types a quantity. The entry screen echoes back "2 cases = 48 cans" for a sanity check before approval.

The easiest thing to get wrong

The factor is locked the moment an item has any stock movement

Once an item has ever been received, sold, transferred or counted, the factor field is locked. Editing it at that point rewrites history: the old quantities stay put but their meaning changes, and past periods' cost drifts with them.

A vendor shipping a different pack size gets a new unit declared on the item (Case of 10 alongside Case of 12); the existing unit is left alone.

The consequence: a document freezes both the unit and the base-unit quantity the moment it is raised. Reopening an old purchase order always shows the figures of the day it was written.

1. Goals & Non-Goals

Goals

• A two-tier unit catalog: system units shipped to every merchant, plus custom units the merchant adds themselves.
• Stock is always held and displayed in the item's base unit, whatever unit the paperwork used.
• The system derives the conversion factor by walking the reference chain in the catalog and multiplying through, instead of asking the user to type a factor.
• Three unit roles on every item: base unit, purchasing unit, selling unit.
• Per-item packaging overrides for the purchasing role and the selling role, and the per-item number beats the catalog's shared factor.

Non-Goals

• Declaring packaging as a percentage - there is one mode only, an absolute value ("1 case = 24 cans"), never "1 case = 80% of...".
• Converting between two different unit groups (kg to litre, say) - factors can only be declared between units in the same group.
• Changing an item's base unit once that item already carries stock.
• Unit pricing (price per case vs price per can) - owned by Purchase orders and Pricing.

2. Success Metrics

Metric	Target / signal
Conversion mistakes on goods receipt	Trending to zero - no more stock discrepancies from someone multiplying the factor wrong
Unit catalog tidiness	A beverage merchant needs one "case" unit, with no "case-12" / "case-24" variants sprouting alongside it
Base unit coverage	100% of items carry a base unit from the moment they are created; no item is left without a way to be counted
Time to write a receipt line	Faster - pick a unit, type a quantity, no calculator and no factor field to fill in

3. Personas & Scenarios

Persona	Goal in this feature
Merchant owner / Manager	Declare units per item, declare the packaging of the goods they buy, and trust the stock figure
Warehouse staff	Write a receipt in the unit printed on the carton, without converting in their head
Cashier	Sell in the retail unit they know by heart, without caring which unit stock is held in
Operations team	Maintain the shared system unit set so a brand-new merchant is productive on day one

Core scenario: the owner picks "can" as the base unit for Coke, picks "case" as the purchasing unit and declares 24 cans per case → warehouse staff writes a receipt for 2 cases → the system records 48 cans into stock → the cashier sells 3 cans → 45 cans remain, all in the base unit.

4. User Stories

#	As a	I want	So that
01	merchant owner	to open the Units of Measure screen and find the common units already there	a new merchant is usable on day one, with nothing to declare from scratch
02	merchant owner	to add my own units (tray, blister pack, canister)	the catalog matches the way I actually count goods
03	merchant owner	to declare "one case of Coke is 24 cans" right on the product	I do not have to create a separate "case-24" unit just because every item packs differently
04	warehouse staff member	to enter "2 cases" and have the system produce 48 cans	I never multiply by hand and never fat-finger the number
05	cashier	stock to always show in the familiar retail unit	I know how many cans are left to sell
06	operations team member	system units to be immune to merchant edits and deletes	the standard conversion factors (kg/g, litre/ml) never get broken

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	The unit catalog has two tiers, and the merchant sees both in one list. • System units: pre-built, shared across every merchant, present from the merchant's first day. • Custom units: added by the merchant for their own use, visible only to that merchant. • Unit codes must be unique within a merchant. If a merchant reuses the code of a system unit, the merchant's own unit takes precedence.	🔶	URD-UOM-001
FR-002	System units are read-only to the merchant. • The merchant can pick and use a system unit anywhere a unit is chosen. • The merchant can only edit and delete units they added themselves. • On the list table, a system-unit row shows neither the Edit nor the Delete button.	🔶	URD-UOM-001
FR-003	Every unit carries a code, a bilingual name, a group and a status. • The group is one of seven values: count, weight, volume, length, time, area, other. • Status follows the lifecycle: active → inactive → archived. • An inactive unit no longer appears in the unit picker when writing a document, while older documents that used it keep it intact.	🔶	URD-UOM-001
FR-004	Every item has exactly one base unit, and stock is always held in it. • The stock screen, low-stock alerts and reports all read out in the base unit. • Whether the paperwork came in by the case or by the sack, stock rises in the base unit after conversion.	🔶	URD-UOM-002
FR-005	The merchant declares a conversion factor between a unit and a reference unit in the same group. • The unit form has two fields: reference unit and factor (e.g. "kg" references "g" with a factor of 1000). • The reference unit must sit in the same group as the unit being declared. • Several declarations chained together form a multi-level conversion chain (tonne → kg → g). • The chain must not form a cycle and must not exceed a depth limit; the actual limit is pending the PO's call.	🔶	URD-UOM-003
FR-006	The system derives the conversion factor when a document is written in a unit other than the base unit. • The system walks the reference chain from the chosen unit back to the base unit and multiplies the factors through. • Whoever writes the document only picks a unit and types a quantity; there is no factor field to fill in by hand. • The factor that was used is stamped onto the inventory ledger row, so reopening an old document still shows the exact number it was converted with at the time.	🚧	URD-UOM-004
FR-007	Every product variant and every material declares three unit roles. • Base unit: the unit stock is held in, mandatory. • Purchasing unit: the default unit when raising a purchase order and receiving goods. • Selling unit: the default unit when selling. • The three roles can point at three different units, or at the same one if the item only ever uses one unit. • Both the material form and the product form carry all three unit fields.	🔶	URD-UOM-005
FR-008	For the purchasing role and the selling role, the merchant declares a packaging spec on the item itself. • The override field sits right next to the unit picker and holds the number of base units in one packaging unit of this item (pick "case", enter 24, and 1 case of Coke = 24 cans). • The override is optional. Leave it blank and the item falls back to the catalog's shared factor.	🚧	URD-UOM-006
FR-009	The item's override beats the catalog's shared factor. • No override: the system uses the chain of factors declared in the unit catalog - the right answer for standard measurement units such as kg/g and litre/ml. • With an override: the system uses that item's number - the right answer for packaging units such as case, six-pack or crate, where the same word "case" means a different spec on every item.	🚧	URD-UOM-007
FR-010	The base unit has no override field. The base unit's factor is always 1 by definition.	🚧	URD-UOM-008
FR-011	A packaging spec is an absolute value only; there is no percentage mode. • The override is a count of base units, must be greater than 0, and accepts up to 4 decimal places (0.5 kg for a half-kilo pack, say). • There is no option to declare it as a percentage of some other factor.	🚧	URD-UOM-006
FR-012	The merchant needs one single "case" unit in the catalog, shared across many items even though each item packs to a different spec, instead of creating "case-12" and "case-24" as separate units.	🚧	URD-UOM-009
FR-013	Where units are declared differs by item type, but the three-role structure is one and the same. • Materials declare their units in the material form inside the Inventory module. • Product variants declare their units in the product form inside the Product Catalog module.	🔶	URD-UOM-010
FR-014	The entry screen always echoes the converted quantity back so the writer can double-check it. • The line shows the quantity typed in the chosen unit alongside the equivalent in the base unit ("2 cases = 48 cans"). • If the chosen unit has no conversion path back to the base unit, the line raises an error in place and cannot be saved.	🚧	URD-UOM-004
FR-015	A unit's conversion factor on an item cannot be edited once that item has any stock movement. • If the item has ever been received, sold, transferred or counted, the factor field is locked, and the form explains why right there. • Editing it at that point rewrites history: the old quantities stay put but their meaning changes, and past periods' cost drifts with them. • A vendor shipping a different pack size gets a new unit on the item; the existing unit is left alone.	🚧	URD-UOM-011
FR-016	A document freezes both the unit and the base-unit quantity the moment it is raised. • Purchase-order lines and stock-ticket lines store the unit the user picked and the quantity already converted to the base unit. • That number is never recomputed, so opening an old document always shows the figures it was written with.	🚧	URD-UOM-012

5.1 Acceptance criteria

• Open the Units of Measure screen for a freshly created merchant → the system units are already listed (piece, box, case, kg, g, litre, ml and so on) with nothing to add.
• Click a system unit → no edit and no delete button; click a unit the merchant added → editing and deleting work as usual.
• Add a custom unit named "tray" in the "count" group → the unit shows up in the list and can be picked on the material form.
• Add a custom unit whose code collides with a system unit → when a unit is resolved by that code, the system uses the merchant's own unit.
• Add a custom unit whose code collides with another custom unit of the same merchant → the form raises a duplicate-code error and will not save.
• Flip a unit to inactive → it disappears from the unit picker when writing a document, but reopening an older document that used it still shows the right unit name.
• Declare "kg" referencing "g" with a factor of 1000, then "tonne" referencing "kg" with a factor of 1000 → pick "tonne" on a document for a material whose base unit is "g" → the system produces 1,000,000 g for 1 tonne.
• Pick a reference unit from a different group (declare "kg" referencing "litre") → the form raises an error and will not save.
• Write a receipt for 5 kg of sugar for a material whose base unit is "g" → the line shows "5 kg = 5000 g" → approve the ticket → stock rises by exactly 5000 g, with no factor field to fill in by hand.
• Open the Coke product with base unit "can", purchasing unit "case" and an override of 24 → raise a purchase order for 2 cases → stock records 48 cans.
• Open the Pepsi product, also with purchasing unit "case" but an override of 20 → raise a purchase order for 2 cases → stock records 40 cans; the same "case" unit in the catalog, two different results.
• Clear the override on a material whose purchasing unit is "kg" and base unit is "g" → write a receipt for 5 kg → the system still produces 5000 g, falling back to the catalog's shared factor.
• Open the product form on the base-unit role → there is no override field for this role.
• Enter 0 or a negative number in the override field → the form raises an error; enter 0.5 → it saves and converts to exactly half a base unit.
• Search the Units of Measure screen → there is exactly one unit named "case", even though the merchant sells Coke at 24 cans/case and beer at 20 cans/case.
• Open the material form in the Inventory module and the product variant form in the Product Catalog module → both carry all three unit fields: base, purchasing, selling.
• Pick, for a document line, a unit from a different group with no conversion path back to the item's base unit → the line raises an error in place and the document cannot be saved.
• Item "Milk" has no stock movement yet, change the Case factor from 12 to 10 → it saves normally.
• Same item, after one goods receipt → reopen the form → the factor field is locked, the form explains why and offers to declare a new unit instead.
• Vendor B ships 10-litre cases while the item's Case is 12 litres → declare a Case of 10 unit on the item, point Vendor B's row at it → order 5 of B's cases → stock goes up by 50 litres, not 60.
• Raise a purchase order for 5 Case of 10, then rename or add units in the catalog → reopen that purchase order → it still reads 5 Case of 10 and 50 litres, exactly as raised.

6. Non-Functional Requirements

Aspect	Requirement
Data integrity	The factor used for a conversion is stamped onto the inventory ledger row and never changes afterwards, even if the merchant later edits the factor in the catalog
Cycle prevention	The reference chain must not form a cycle (A references B, B references A back); the chain also needs a depth limit, and exceeding it raises a form error; the actual limit is pending the PO's call
Per-merchant isolation	Custom units are visible only to the merchant who created them; system units are readable by every merchant but writable by nobody inside a merchant
Precision	Conversion factors and quantities use 4-decimal precision end to end
Performance / scale	A merchant's unit list returns every system unit plus every custom unit in one load, with no truncation
i18n	Unit names and descriptions are bilingual Vietnamese - English

7. UX & Flows

The merchant reaches the Units of Measure screen from the Inventory menu on Client. The screen carries one table listing both system units and custom units, filterable by group and by status. "Add unit" opens a form with fields for code, name, group, reference unit and factor.

Declaring the three unit roles and the packaging override does not happen on this screen. It happens in the material form (Inventory module) and the product form (Product Catalog module), inside the "Units of Measure" block.

8. Data & Domain

Concept	Role
Unit of measure	A way of counting goods: can, case, kg, g. Belongs to a group, carries a code and a bilingual name
System unit	A unit shared by every merchant, maintained by the operations team, read-only to merchants
Custom unit	A unit a merchant adds themselves, visible and editable only by that merchant
Unit group	Seven groups: count, weight, volume, length, time, area, other. Factors can only be declared within one group
Reference unit	The unit another unit converts back to, together with a factor (kg references g, factor 1000)
Conversion chain	Several reference pairs strung together (tonne → kg → g); the factor to the base unit is the product of the factors along the chain
Base unit	The smallest unit an item is counted in. Stock is always held in it, and its factor is always 1
Unit role	The three roles on every item: base, purchasing, selling
Packaging override	The number of base units in one packaging unit of that specific item ("one of my cases = 24 cans"). Exists only on the purchasing and selling roles
Factor used	The conversion number stamped onto the inventory ledger row when the document was written; it never changes afterwards

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

9. Dependencies & Assumptions

Depends on

#	Feature	What is depended on
01	MAT Materials	where the three unit roles are declared for a material.
02	Product catalog	where the three unit roles are declared for a product variant; that boundary stays as it is, Inventory does not take over unit declaration for products.
03	LDG Inventory ledger	where the factor used is stamped and preserved.
04	TKT Inventory tickets · PO Purchase orders	where users pick a unit other than the base unit and need the system to convert.

Assumptions

#	Assumption	What breaks if it is wrong
01	An item's base unit is chosen once at creation and does not change after the item carries stock.	Changing the base unit once stock exists changes the meaning of every historical number: old stock, old cost and old ledger entries all turn into nonsense with no way to rebuild them.
02	The system unit set covers the everyday needs of Vietnamese retail and F&B; custom units are for the edge cases only.	If the shared set lacks what a merchant needs, every merchant invents their own variant, the catalog bloats, and reports grouped by unit stop being comparable across merchants.
03	An item only needs one packaging spec per role; goods that ship in several case sizes at once are split into two items.	An item that genuinely ships in two case sizes at once can only hold one override, and every receipt in the other size converts wrong right from the document line.

10. Release Plan & Criteria

Aspect	Plan
Phase	P2 (Inventory v2) - see the URD feature catalog
Rollout	Every merchant; no feature flag. The system unit set is there for a new merchant the moment the merchant opens
Migration	Items that already carry stock keep their current base unit; the packaging override defaults to blank, so every existing item keeps falling back to the catalog's shared factor and no stock figure moves
Release criteria	The merchant can reach the Units of Measure screen from the Inventory menu; a receipt written in cases produces the right number of cans; two products sharing the "case" unit but with different overrides produce two different numbers
Monitoring	Number of items carrying a packaging override, number of document lines blocked for having no conversion path, stock-count discrepancies on items received in packaging units

References

• URD: Inventory - Units of measure & conversion
• Related: Materials · Stock items & levels · Inventory ledger · Purchase orders
• Module: Inventory - URD
• Developer: @nx/inventory

Risks & Open Questions

#	Risk / question	Mitigation / status
01	A merchant edits a catalog factor after goods were received, and older quantities get reinterpreted wrongly	The factor used is stamped onto the inventory ledger row when the document is written and is never re-read from the catalog (FR-006)
02	A merchant enters the wrong override (240 instead of 24) and stock is off by a factor of ten	The entry screen always echoes the converted quantity back on the line so the writer can check it before approving (FR-014)
03	The reference chain gets declared into a cycle	The form blocks cycles and caps chain depth (§6); the actual limit is pending the PO's call
04	The unit list gets truncated for a merchant with many custom units, and the user cannot see the unit they just created	The list returns every system unit plus every custom unit in one load, with no truncation (§6)
05	Changing the base unit of an item that already carries stock would make every historical number meaningless	Open: we need a rule for handling existing stock before allowing a base-unit change, or block the change outright
06	A material is bought by the kilo but the recipe measures in grams, and rounding error accumulates across many explosions	Every factor and quantity uses 4-decimal precision end to end (§6)

Frequently asked questions

#	Question	Answer
01	Which unit is stock held in?	Always the item's base unit. You buy in cases and sell in cans, but the number sitting in the warehouse is a number of cans. That is what keeps the arithmetic usable.
02	Do I have to multiply the factor myself when writing a document?	No. Pick a unit and type a quantity; the system walks the declared conversion chain, multiplies through to the base unit, and echoes the result back for you to check ("2 cases = 48 cans").
03	A case of Coke is 24 cans and a case of beer is 20 - how do I declare that?	Keep exactly one "case" unit in the catalog, then go into each product and declare the override: Coke 24, beer 20. The per-product override always beats the catalog's shared factor.
04	When should I use an override and when the shared factor?	Standard measurement units (kg/g, litre/ml) use the shared factor, because 1 kg is 1000 g everywhere. Packaging units (case, six-pack, crate, tray) use an override, because every item packs to its own spec.
05	Can I declare a packaging spec as a percentage?	No. There is one mode only, an absolute value - the count of base units in one packaging unit. Percentages produce meaningless fractions and hide a dependency on some shared factor, which is very hard to sanity-check on the receiving dock.
06	Can I edit the system's "kg" unit?	No. System units are read-only to merchants: you can use them anywhere, but you cannot edit or delete them. If you need your own way of counting, add a unit for your merchant.
07	Does the base unit have an override field?	No. The base unit's factor is 1 by definition, so there is nothing to declare.
08	Materials and products declare units in two different places?	Correct. Materials in the material form of the Inventory module, product variants in the product form of the Product Catalog module. The three-role structure is identical; only the place you work in differs.