PRD: Danh mục

Module	Commerce (CORE-03)	PRD ID	PRD-CAT-001
Status	Shipped	Owner	Commerce squad
Date	2026-05-18	Version	v1.0
Packages	@nx/core · apps/client	URD	CAT · DEL

TL;DR

Trao cho mỗi danh mục sản phẩm một nhận diện trực quan - icon Lucide cùng một màu sắc - và một vị trí trong phân cấp danh mục, để danh mục hiển thị thành các ô được mã hóa màu, dễ nhận biết trên POS và back office thay vì chỉ là chữ trơn. Owner và nhân viên kho quản lý tất cả qua aggregate merchant hiện có, với một bộ chọn icon-màu có thể tái sử dụng cho các form khác.

1. Context & Problem

Danh mục nhóm các sản phẩm trong một merchant và được quản lý qua aggregate merchant (xem CAT). Form danh mục hiện chỉ là ô nhập tên/merchant mỏng, không có nhận diện trực quan, nên danh mục hiển thị dưới dạng chữ trơn trên lưới POS và trong back office. Trên màn hình cảm ứng POS bận rộn, danh mục chỉ-có-chữ chậm để quét mắt và dễ chạm nhầm, lại không có cách thể hiện cây danh mục ngoài một danh sách phẳng.

Phần này thiết kế lại form danh mục để mỗi danh mục có một icon (lấy từ toàn bộ thư viện Lucide) và một màu sắc, đồng thời thêm việc chọn danh mục cha để danh mục có thể tạo thành phân cấp - mà không phá vỡ quy tắc danh mục chỉ được tạo/sửa qua aggregate merchant.

2. Goals & Non-Goals

Goals

• Mỗi danh mục mang một nhận diện trực quan - một icon (toàn bộ thư viện Lucide) cùng một màu sắc - được hiển thị trên POS và back office (URD-CAT-001).
• Chọn danh mục cha để hình thành phân cấp danh mục.
• Một bộ chọn icon-màu có thể tái sử dụng (gắn RHF) dùng được ngoài danh mục.
• Lưu icon/màu trên model danh mục cùng với cờ add-on hiện có (URD-CAT-004), tất cả qua aggregate merchant.

Non-Goals

• CRUD danh mục độc lập ngoài aggregate merchant (URD Non-Goals) - danh mục vẫn được quản lý qua aggregate.
• Ngữ nghĩa đổi tên / soft-delete danh mục (URD-CAT-002, URD-CAT-003) - đã được aggregate merchant cung cấp; không đụng lại ở đây.
• Hành vi cascade của deletion-policy (→ DEL).

3. Success Metrics

Metric	Target / signal
Mức độ áp dụng trực quan	Tỷ lệ danh mục mang icon + màu khác mặc định tăng dần
Tốc độ quét	Chọn danh mục trên lưới POS nhanh hơn (ít chạm nhầm hơn)
Tái sử dụng bộ chọn	Bộ chọn icon-màu được tái sử dụng ở ít nhất một form ngoài danh mục
Toàn vẹn aggregate	100% thay đổi danh mục vẫn đi qua aggregate merchant (không phát sinh đường CRUD độc lập)

4. Personas & Use Cases

Persona	Mục tiêu trong tính năng này
Owner	Cho danh mục một diện mạo dễ nhận biết và tổ chức chúng thành cây
Nhân viên kho / catalog	Chọn icon + màu và một danh mục cha khi thiết lập danh mục
Thu ngân	Quét nhanh các ô danh mục được mã hóa màu trên POS

Core scenarios: mở aggregate merchant → thêm/sửa một danh mục → chọn một icon Lucide và một màu từ bộ chọn tái sử dụng → tùy chọn chọn một danh mục cha → lưu qua aggregate → danh mục hiển thị thành một ô có icon, được mã hóa màu trên POS và back office.

5. User Stories

• Là một owner, tôi muốn gán một icon và một màu cho danh mục, để nó nhận biết được ngay trên lưới POS.
• Là nhân viên catalog, tôi muốn chọn từ toàn bộ thư viện icon Lucide, để tìm được icon phù hợp mà không bị giới hạn trong một danh sách ngắn.
• Là nhân viên catalog, tôi muốn chọn bất kỳ màu nào (preset hoặc tùy chỉnh), để ô của một danh mục khớp với cách tôi hình dung về nó.
• Là một owner, tôi muốn đặt một danh mục cha, để danh mục hình thành phân cấp thay vì một danh sách phẳng.
• Là một developer, tôi muốn một bộ chọn icon-màu tái sử dụng, để cùng một control có thể thả vào các form khác.

6. Functional Requirements

#	Requirement	URD ref
FR-1	Danh mục chỉ được tạo/sửa qua thao tác aggregate merchant	URD-CAT-001
FR-2	Một danh mục mang một icon (tên Lucide) và một màu, lưu trên metadata của model danh mục	URD-CAT-001
FR-3	Bộ chọn icon phủ toàn bộ thư viện Lucide qua lưới ảo hóa; bộ chọn màu cung cấp preset cùng một màu tùy chỉnh native	URD-CAT-001
FR-4	Bộ chọn icon-màu gắn RHF và tái sử dụng được ngoài form danh mục	URD-CAT-001
FR-5	Một danh mục có thể chọn một danh mục cha, hình thành phân cấp danh mục	URD-CAT-001
FR-6	Một danh mục có thể được đánh dấu / bỏ đánh dấu là nhóm add-on, giữ cùng icon/màu	URD-CAT-004
FR-7	Đổi tên và soft-delete vẫn khả dụng qua aggregate và không thay đổi	URD-CAT-002 · URD-CAT-003

Toàn văn requirement và tiêu chí nghiệm thu nằm trong Commerce URD. PRD này tham chiếu chúng thay vì lặp lại.

7. Non-Functional Requirements

Area	Requirement
Data integrity	Icon/màu nằm trong metadata của model danh mục; cờ add-on và tham chiếu cha được giữ qua các lần cập nhật aggregate
Tenancy & authz	Danh mục được scope theo merchant; thay đổi đi qua aggregate merchant và permission của nó
Performance / scale	Lưới icon toàn-Lucide được ảo hóa để render hàng nghìn icon vẫn mượt
Tương thích ngược	Icon/màu và cha đều tùy chọn; danh mục hiện có không có chúng vẫn hoạt động
i18n	Nhãn form và tên danh mục song ngữ ({ en, vi })

8. UX & Flows

Màn hình chính (trong apps/client): form danh mục với các phần chi tiết, add-on và xem trước trực tiếp; bộ chọn icon-màu tái sử dụng (lưới icon, ô màu + bộ chọn native); và ô nhập danh mục cha.

9. Data & Domain

Entity	Vai trò
Category	Nhóm sản phẩm theo merchant - tên (i18n), discrimination add-on, parentId, và metadata.icon (tên + màu)
Metadata danh mục	Mang nhận diện trực quan (icon.name, icon.color) trên model danh mục
Aggregate merchant	Đường tạo/cập nhật duy nhất cho danh mục

Chỉ ở mức khái niệm - schema đầy đủ và bất biến nằm trong developer domain model.

10. Dependencies & Assumptions

Depends on

• Aggregate merchant (URD-MER-004) - đường tạo/cập nhật duy nhất cho danh mục.
• Model danh mục (@nx/core) - mở rộng với metadata.icon và parentId.
• Thư viện icon Lucide - nguồn icon được render trong bộ chọn.

Assumptions

• Một merchant đã tồn tại; danh mục luôn được quản lý trong ngữ cảnh aggregate merchant của nó.
• Tên icon và màu là tùy chọn - danh mục không có chúng hiển thị với diện mạo mặc định.

11. Risks & Open Questions

Risk / question	Mitigation / status
Render toàn bộ thư viện Lucide có thể chậm	Lưới icon được ảo hóa; chỉ render icon trong tầm nhìn
Màu tùy chỉnh có thể xung đột với theme / dark mode	Bộ chọn màu cung cấp preset theo theme; bộ chọn native là tùy chọn cho giá trị tùy chỉnh
Chọn cha có thể tạo vòng lặp	Các guard vòng lặp / merchant / discrimination nằm trong CategoryService
Nhu cầu CRUD danh mục độc lập	Ngoài phạm vi; danh mục vẫn được quản lý qua aggregate (xem Commerce URD Non-Goals)

12. Release Plan & Launch Criteria

Aspect	Plan
Phase	P2 - xem Commerce feature catalog
Rollout	Mọi merchant; không feature flag
Migration	Không - icon/màu là metadata tùy chọn; parentId mặc định null
Launch criteria	Form danh mục lưu icon/màu/cha qua aggregate; bộ chọn toàn-Lucide render mượt; danh mục hiện có không bị ảnh hưởng
Monitoring	Tỷ lệ danh mục có icon/màu tùy chỉnh, tỷ lệ lỗi bộ chọn, tỷ lệ lưu aggregate thành công

13. FAQ

Tôi có thể tạo một danh mục mà không qua merchant không? Không - danh mục chỉ được tạo và sửa qua aggregate merchant; không có CRUD danh mục độc lập.

Tôi chọn được icon nào? Toàn bộ thư viện icon Lucide, trình bày trong lưới ảo hóa để giữ tốc độ.

Tôi dùng được màu tùy chỉnh chứ không chỉ preset không? Có - bộ chọn màu cung cấp preset theo theme cùng một bộ chọn màu tùy chỉnh native.

Danh mục hiện có không có icon hay cha có hỏng không? Không - icon, màu và cha đều tùy chọn; danh mục không có chúng giữ diện mạo mặc định.

Bộ chọn icon-màu chỉ dùng cho danh mục thôi à? Không - nó gắn RHF và tái sử dụng được, nên các form khác có thể dùng cùng control.

References

• URD: Commerce - CAT Danh mục · DEL Deletion Policy
• Liên quan: MER Aggregate merchant
• Module: Commerce - tổng quan + traceability
• Developer: @nx/commerce · domain model