PRD: Sale Categories

Module	Commerce	PRD ID	PRD-CAT-001
Status	Ready to dev	FEAT	CAT
Epic	—	Plane	BANA-1531
Date	2026-05-18	Version	v1.0
Packages	@nx/commerce	URD	CAT
Surface	Client · Owner/Mgr
Owner	Phát Nguyễn

What sale categories are

Categories are a merchant's product groups - a coffee merchant has "Coffee", "Milk tea", "Pastries". When creating a category in the Client app, the user picks an icon and a color for the group: about 40 industry suggestions are ready, or search the whole library for more. On the POS, the category shows up as a colored tile the cashier recognizes at a glance instead of reading text.

Tree arrangement and a shared picker

Categories nest as parent - child, up to 8 levels; tree arrangement is done on the Categories screen in the Client app. The icon-color picker is packaged as a shared control - other forms drop it in and use it right away, already adopted by the finance-category and helpdesk ticket-category forms.

This PRD covers sale categories only. Material categories for the warehouse are a different screen, to be designed in the Inventory module.

Why icon and color

The category form used to be just a name field: on a busy touch-screen POS every group looked like identical plain text, so cashiers had to read each label - slow scanning and easy mis-taps. There was also no way to express nested groups - everything was one flat list.

This increment gives every category an icon and a color, adds a parent-group selector to build a tree, and packages the icon-color picker as a control other forms can reuse.

One category, from creation to the POS

Open the Categories screen → create or edit a group → pick an icon and a color, the preview updates instantly → optionally pick a parent group to arrange the tree → save → the group shows up as an icon-carrying, color-coded tile on the POS and in the admin app.

The easiest thing to get wrong

The Edit-merchant screen has no parent selector

Categories are manageable through two paths: the dedicated Categories screen, or right inside the Edit-merchant screen. Creating a category on the Edit-merchant screen still saves normally, but that form has no parent-group selector - arranging the tree requires opening the dedicated Categories screen.

1. Goals & Non-Goals

Goals

• Every category has an icon + color, shown as a recognizable tile on the POS and in the owner's admin app.
• Parent-group selection arranging categories into a tree (up to 8 levels).
• An icon-color picker that is reusable beyond categories.
• Categories manageable through two paths: the dedicated Categories screen, or right inside the Edit-merchant screen - where the merchant, its categories and channels are saved in one submit.

Non-Goals

• Material categories for the warehouse - each screen has its category type fixed by design; the material-category screen is a separate piece, to be designed in the Inventory module.
• The Back Office copy of the categories screen - out of scope for this PRD.
• Rename / soft-delete semantics - unchanged (URD-CAT-002, URD-CAT-003); block/cascade behavior on deletion follows the merchant deletion policy.

2. Success Metrics

Metric	Target / signal
Adoption	Share of categories carrying a non-default icon + color trends up
Interaction speed	Faster category picking on the POS grid, fewer mis-taps
Picker reuse	The icon-color picker is used by at least one form beyond categories - achieved (finance category, helpdesk ticket category)

3. Personas & Scenarios

Persona	Goal in this feature
Owner	Give product groups a recognizable look and organize them into a tree
Catalog staff	Pick an icon + color and a parent group when setting up categories
Cashier	Spot the right color-coded tile on the POS instantly

Core scenario: open the Categories screen → create or edit a group → pick an icon and color (the preview updates instantly) → optionally pick a parent group → save → the group shows up as an icon-carrying, color-coded tile on the POS and in the admin list.

4. User Stories

#	As a	I want	So that
01	owner	to assign an icon and color to a group	it is instantly recognizable on the POS grid
02	catalog staff member	industry-fitting icon suggestions up front, and the ability to search the whole library for any other icon when needed	I can pick the right icon fast, without being limited to the suggested set
03	catalog staff member	to pick a quick preset color, or a free color of my own	the color is both fast to pick and able to match the brand when it needs to
04	owner	to place a group under a parent	categories have structure instead of one flat list
05	form builder	the icon-color picker to be a drop-in control for any form	other forms can reuse it right away, instead of building a new control

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	Sale categories are created/edited through two paths: the dedicated Categories screen (list / create / edit) and inside the Edit-merchant screen.	✅	URD-CAT-001
FR-002	Each category carries an icon and a color, stored on the category. A category without them shows a default look.	✅	URD-CAT-004
FR-003	The icon picker and color picker both ship with ready suggestions plus a way to go further. • Icon picker: ~40 industry suggestions (restaurant / retail) shown first, plus a search box over the system's full standard icon library, in a smoothly-scrolling virtualized grid. • Color picker: ~12 theme presets, plus one free color input.	✅	URD-CAT-004
FR-004	The icon-color picker is form-bound and reusable - already adopted by the finance-category and helpdesk ticket-category forms.	✅	URD-CAT-004
FR-005	A parent group can be selected to build a tree, up to 8 levels. • Self-parenting and cycles are blocked. • The parent selector exists only on the dedicated Categories screen; a group created on the Edit-merchant screen cannot be placed in the tree there (current design intent - open the Categories screen to arrange).	✅	URD-CAT-005
FR-006	The form shows a live preview: the POS tile and the list label update instantly with the chosen icon / color.	✅	URD-CAT-004
FR-007	On other forms (e.g. the product form), the category selector allows creating a new group in place, without leaving the screen.	✅	URD-CAT-001
FR-008	Shared system categories are visible to merchants but read-only - they cannot be edited or deleted.	✅	URD-CAT-006
FR-009	Renaming a category does not affect the products in the group. • Deletion is a soft-delete governed by the merchant's deletion policy. • Industry template groups are seeded at merchant sign-up.	✅	URD-CAT-002 · URD-CAT-003 · URD-CAT-007

5.1 Acceptance criteria

• Create a group on the Categories screen with an icon + color + parent → it appears as a tile with the right icon and color on the POS and in the admin list.
• Change the color in the form → the preview updates immediately, before saving.
• Pick a parent that forms a cycle (A parents B, then B is picked as A's parent) or exceeds 8 levels → blocked with a clear message.
• On the Edit-merchant screen, add a new category in the categories section and save → it is created successfully; confirm that form has no parent selector (open the Categories screen to arrange the tree).
• Try to edit or delete a system category → rejected.
• An old category without icon/color/parent → still works, shown with the default look.
• On the product form, create a new group in place from the category selector → usable immediately without leaving the screen.

6. Non-Functional Requirements

Area	Requirement
Data integrity	Icon + color live on the category; the parent only changes when the user changes it on the Categories screen - the Edit-merchant screen does not touch the tree
Tenancy & authz	Categories are scoped to the user's own merchant; changes go through each path's permission
Performance	The icon grid is virtualized - only visible icons render, smooth with thousands of icons
Backward compatibility	Icon, color, and parent are all optional; existing categories without them keep working
i18n	Form labels and category names are bilingual (EN / VI)

7. UX & Flows

Key screens (owner's admin app): the Categories screen (list / create / edit) with a form carrying the bilingual name, the icon-color picker, the parent selector and a live preview; plus the category section inside the Edit-merchant screen (no parent selector).

8. Data & Domain

Entity	Role
Category	A merchant's product group - name + description (bilingual), parent reference, icon + color
System category	A shared group provided by the platform - read-only to merchants
Two management paths	The dedicated Categories screen (full, with tree arrangement) and the Edit-merchant screen (quick, no tree)

Conceptual only - the full schema lives in the developer domain model.

9. Dependencies & Assumptions

Depends on

#	Feature	What is depended on
01	The Edit-merchant screen (URD-MER-004)	one of the two category create/update paths.
02	The system's standard icon set	the icon source for the picker.

Assumptions

#	Assumption	What breaks if it is wrong
01	A merchant already exists; a category always belongs to one specific merchant.	A category that cannot be tied to the right merchant breaks the per-merchant scoping in §6, and one merchant's categories leak into another's.
02	Icon, color, and parent are all optional - unset means the default look.	If these three fields became required, existing categories that lack icon/color/parent would stop working, and a migration would be needed before they work again.
03	The category type is fixed per screen (this screen = sale groups) - users do not choose a type.	If users could choose the category type themselves, the boundary with material categories for the warehouse (owned by the Inventory module) blurs, and one screen ends up mixing both category types into a single list.

10. Release Plan & Launch Criteria

Aspect	Plan
Phase	P2 - see the URD feature catalog
Rollout	All merchants; no feature flag
Migration	None - icon/color/parent are optional, existing data untouched
Launch criteria	All acceptance criteria in §5.1 pass on a real merchant
Monitoring	Share of categories with a custom icon/color; category save errors

References

• URD: Commerce - CAT Categories · MER deletion policy
• Related: MER Merchant aggregate · Inventory (material categories)
• Module: Commerce - URD
• Developer: @nx/commerce · domain model

Risks & Open Questions

#	Risk / question	Mitigation / status
01	Rendering the whole icon library could be slow	Virtualized grid - only icons in view are rendered
02	A parent pick could create a cycle	Blocked: self-parenting, cycles, and more than 8 levels are all rejected
03	A user creates a group on the Edit-merchant screen and finds no tree placement	Documented guidance: tree arrangement is done on the Categories screen (current design intent)

Frequently asked questions

#	Question	Answer
01	Where do I create categories?	Two places: the dedicated Categories screen (the full one - with tree arrangement), or right inside the Edit-merchant screen (quick, but no parent selector). Either way the group belongs to that merchant.
02	Why can't I arrange the tree from the Edit-merchant screen?	Current design intent, to keep the Edit-merchant screen lean. To arrange the tree, open the Categories screen.
03	Which icons can I pick?	About 40 industry-fitting suggestions come first; search the system's full standard library for anything else.
04	Do colors have to come from the presets?	No - there are ~12 presets for speed, plus a free color input.
05	Do old categories without an icon or parent break?	No - all three are optional; old groups keep the default look.
06	What about material groups for the warehouse?	That is a different screen with its category type fixed by design. Its design belongs to the Inventory module, not this PRD.