Measurement Units
- Code: INV-MSU
- Module: Inventory
- Type: Master Data
1. Overview
Measurement Units are the list of units used to express product packages — pcs, carton, box, kilogram, and the like. Every product package selects exactly one measurement unit, so this unit is what appears on purchase orders, goods receipts, bills, and stock lists. Each unit has a short symbol for table display and a full name for selection.
Expected outcome: the units used by all stores are uniform, so quantities on transaction documents always read the same to anyone.
2. Problem
Without a centrally managed list of units, units are written freely when filling in product packages. As a result:
- The same unit is written in different ways, so transaction documents read inconsistently.
- Quantity columns in tables become long and hard to read because there is no agreed short symbol.
- Unit mistakes are only discovered when goods arrive, when the quantity delivered does not match expectations.
3. Goals & Non-goals
3.1 Goals
- The units used across all product packages come from the same single list.
- Every unit has a consistent short symbol for table display and printed documents.
- Units that are no longer used can be deactivated without changing the packages already using them.
3.2 Non-goals
- General conversion between measurement units, for example kilograms to grams; conversion is only recorded per product package through the conversion quantity.
- Classifying units by dimension such as weight, length, or volume.
- Rounding and number of decimal places per unit.
4. Business Rules
Business rules are the set of provisions and constraints that apply to Measurement Units throughout the application, on every screen and action that involves it, whoever performs it. These rules are the single source of truth: if another part of this PRD appears to differ, the rules here prevail.
- BR-01 The unit symbol is required, maximum 5 characters.
- BR-02 The measurement unit name is required, maximum 20 characters.
- BR-03 Every product package selects exactly one measurement unit.
- BR-04 Inactive units are not used for new packages. Needs confirmation: currently the unit options on the product package form do not yet filter by active status.
- BR-05 Every change to measurement unit data is recorded along with its actor and time.
5. Flow
5.1 Main Flowchart
- Fill In Unit Data — Staff set the unit’s status, symbol, and name through the add dialog.
- Validation — Inputs are checked before the unit is saved. A unit that violates the rules cannot be saved, and the errors are shown on the relevant fields.
- Unit Saved — The unit is immediately available as an option when a product package is created or edited.
- 3a. Edit Unit Data — The unit’s status, symbol, and name can be updated at any time through the edit dialog.
- Used on Product Packages — A product package selects one measurement unit, which then appears on all transaction documents. The details are explained in the Products PRD.
5.2 Status Lifecycle
| Status | Description | Next |
|---|---|---|
Activeis_active: true | The unit is used for product packages | Inactive, or deleted |
Inactiveis_active: false | The unit is no longer used for new packages | Active, or deleted |
6. Document Structure
This section defines the content of the Measurement Unit data itself: which fields it has, their type, which are required, their initial values, and their value rules. The provisions here apply wherever the unit is created or changed and are enforced on save, regardless of how the field is displayed.
6.1 General
| Field | Type | Required | Default | Rules |
|---|---|---|---|---|
| Status | Enum | Yes | Not selected | Active or Inactive |
| Symbol | Text | Yes | — | Maximum 5 characters (BR-01) |
| Measurement Unit Name | Text | Yes | — | Maximum 20 characters (BR-02) |
7. UI Structure
This section defines how Measurement Units are displayed and operated: the list columns and form controls along with their behavior. Activity Logs are available as a drawer from the list page (all units) and from the detail dialog (per unit). This section only governs display and interaction; content and value rules still follow Document Structure.
7.1 Datatable
| Column | Sortable | Sample Value | Component |
|---|---|---|---|
| Select | — | — | Checkbox |
| No | — | 1 | Number |
| Symbol | Yes | CTN | Text |
| Measurement Unit Name | Yes | Carton | Text |
| Status | — | Active | Badge |
| Actions | — | View · Edit · Delete | Action Menu |
7.2 Form & Details
Create — A dialog containing status, symbol, and measurement unit name. Action: Save, which is only enabled after an input changes.
Edit — The same dialog with its inputs filled with the selected unit’s data. Action: Update.
Detail — A read-only dialog containing status, symbol, and measurement unit name, with an action menu containing Activity Logs and Edit.
Measurement Unit Data
| Field | Control | Options Source | Behavior |
|---|---|---|---|
| Status | Single Select | Active or Inactive | The currently selected option can be deselected, leaving the status empty |
| Symbol | Text Input | — | Maximum 5 characters |
| Measurement Unit Name | Text Input | — | Maximum 20 characters |
8. User Stories
US-01 - Add a measurement unit
As inventory staff, I want to add a measurement unit, so that product packages use uniform units.
| ID | Acceptance criteria |
|---|---|
| AC-01.1 | The Add New button only appears for users with the create permission, and opens a dialog with empty inputs. |
| AC-01.2 | Status, symbol, and unit name are required; the symbol is at most 5 characters and the name at most 20 characters (BR-01, BR-02). |
| AC-01.3 | The save button is disabled until an input has changed. |
| AC-01.4 | On success, a success toast appears, the dialog closes, and the list is refreshed. |
| AC-01.5 | Duplicate symbol — Needs confirmation: whether the symbol must be unique and rejected on save. |
US-02 - Edit a measurement unit
As inventory staff, I want to edit a measurement unit, so that its symbol and name stay appropriate.
| ID | Acceptance criteria |
|---|---|
| AC-02.1 | The Edit action is available from the list and from the detail dialog, only for users with the update permission. |
| AC-02.2 | Validation is the same as when adding (AC-01.2). |
| AC-02.3 | Changing a unit’s symbol also changes how the unit is displayed on the product packages using it (BR-03). |
US-03 - Measurement unit list
As an owner, I want to see all measurement units, so that I can make sure there are no duplicate units.
| ID | Acceptance criteria |
|---|---|
| AC-03.1 | Columns: symbol, measurement unit name, and status; default sort by name A–Z with pagination. |
| AC-03.2 | Sortable columns: symbol and measurement unit name. Search uses keywords. |
| AC-03.3 | Row actions: View, Edit, Delete according to permissions. |
US-04 - Delete a measurement unit
As inventory staff, I want to delete a unit created by mistake, so that the list stays clean.
| ID | Acceptance criteria |
|---|---|
| AC-04.1 | Single and bulk delete require confirmation and the delete permission. |
| AC-04.2 | If the deletion is rejected, the error message appears as a toast. |
| AC-04.3 | Deleting a unit still used by product packages — Needs confirmation: whether it is rejected, since every package must have a unit (BR-03). |
US-05 - Activity history
As an owner, I want to see the measurement unit activity log, so that changes can be traced.
| ID | Acceptance criteria |
|---|---|
| AC-05.1 | The activity log is available for all units (in the list) and per unit (from the detail dialog) (BR-05). |
9. User Scenarios
| Role | Scenario |
|---|---|
| Inventory Staff | Prepares the tenant’s basic units — pcs, carton, box — before the first product package is created |
| Inventory Staff | Adds a new unit when a supplier starts delivering goods in a package type never used before |
| Owner | Deactivates a unit that is no longer used so it is not selected for new packages |
10. Permissions & Actions
10.1 Permission by Action
| Action | Permission | Condition |
|---|---|---|
| View Measurement Unit List | inventory:measurement-unit:list:any | — |
| View Activity Logs | inventory:measurement-unit:list:any | — |
| View Measurement Unit Detail | inventory:measurement-unit:view:any | — |
| Create Measurement Unit | inventory:measurement-unit:create:any | — |
| Edit Measurement Unit | inventory:measurement-unit:update:any | — |
| Delete Measurement Unit | inventory:measurement-unit:delete:any | — |
10.2 Action by Status
| Action | Active | Inactive |
|---|---|---|
| View Measurement Unit Detail | ✓ | ✓ |
| Edit Measurement Unit | ✓ | ✓ |
| Delete Measurement Unit | ✓ | ✓ |
| Selected on New Packages | ✓ | — |
11. Notifications
This feature does not trigger any notifications.
12. Dependencies
Related PRDs
- Products — each product package selects one measurement unit (BR-03).
Effects on other modules
- The measurement unit appears in the unit column of Product Inventory, Purchase Order, Purchase Order Line, Goods Receipt, and Bill, including on their PDF documents.
- Every change is recorded in the activity log (BR-05).