PRD: Danh mục bán hàng

Module	Thương mại	PRD ID	PRD-CAT-001
Trạng thái	Sẵn sàng dev	FEAT	CAT
Epic	—	Plane	BANA-1531
Ngày	2026-05-18	Phiên bản	v1.0
Gói	@nx/commerce	URD	CAT
Surface	Client · Chủ/QL
Phụ trách	Phát Nguyễn

Danh mục bán hàng là gì

Danh mục là nhóm hàng của một merchant - ví dụ quán cà phê có nhóm "Cà phê", "Trà sữa", "Bánh ngọt". Khi tạo danh mục tại trang Client, người dùng chọn một icon và một màu riêng cho nhóm: có sẵn khoảng 40 icon gợi ý theo ngành, cần thêm thì tìm trong cả thư viện. Lên màn POS, danh mục hiện thành một ô có màu, thu ngân nhìn là nhận ra ngay chứ không phải đọc chữ.

Xếp cây và bộ chọn dùng chung

Danh mục xếp được thành cây cha - con, tối đa 8 tầng; việc xếp cây làm tại màn Danh mục ở trang Client. Bộ chọn icon-màu được đóng gói thành một control dùng chung - form khác lắp vào dùng được luôn, hiện đã dùng ở danh mục thu-chi và danh mục phiếu hỗ trợ.

PRD này chỉ nói danh mục bán hàng. Danh mục cho nguyên liệu trong kho là một màn hình khác, sẽ thiết kế ở phần Kho hàng (Inventory).

Vì sao cần icon và màu

Trước đây form danh mục chỉ có ô nhập tên: trên màn POS cảm ứng, mọi nhóm đều là chữ trơn giống nhau, thu ngân phải đọc từng chữ nên quét mắt chậm và dễ bấm nhầm. Cũng không có cách nào thể hiện nhóm lồng nhau - tất cả là một danh sách phẳng.

Phần này cho mỗi danh mục một icon và một màu, thêm ô chọn nhóm cha để xếp cây, và đóng gói bộ chọn icon-màu thành một control dùng lại được ở các form khác.

Một danh mục, từ lúc tạo tới lúc lên POS

Vào màn Danh mục → tạo hoặc sửa một nhóm → chọn icon và màu, ô xem trước đổi ngay theo lựa chọn → chọn nhóm cha nếu muốn xếp cây → lưu → nhóm hiện thành ô có icon, có màu trên POS và app quản trị.

Chỗ dễ sai nhất

Màn Sửa merchant không có ô chọn nhóm cha

Danh mục quản lý được qua hai đường: màn Danh mục riêng, hoặc ngay trong màn Sửa thông tin merchant. Tạo danh mục ở màn Sửa merchant vẫn lưu được bình thường, nhưng form ở đó không có ô chọn nhóm cha - muốn xếp cây phải mở màn Danh mục riêng.

1. Mục tiêu & Loại trừ

Mục tiêu

• Mỗi danh mục có icon + màu, hiển thị thành ô dễ nhận biết trên POS và app quản trị của Owner.
• Chọn nhóm cha để xếp danh mục thành cây (tối đa 8 tầng).
• Bộ chọn icon-màu tái sử dụng được ngoài danh mục.
• Danh mục quản lý được qua hai đường: màn Danh mục riêng, hoặc ngay trong màn Sửa thông tin merchant - nơi merchant, danh mục và kênh bán được lưu chung trong một lần bấm.

Loại trừ

• Danh mục cho nguyên liệu kho - mỗi màn hình đã cố định loại danh mục của nó (chủ đích thiết kế); màn danh mục nguyên liệu là phần riêng, sẽ thiết kế trong module Kho hàng.
• Màn danh mục phía Back Office - ngoài phạm vi bản này.
• Ngữ nghĩa đổi tên / xóa mềm - giữ nguyên như đã có (URD-CAT-002, URD-CAT-003); hành vi chặn/cascade khi xóa theo chính sách xóa của merchant.

2. Thước đo thành công

Thước đo	Mục tiêu / tín hiệu
Mức độ dùng	Tỷ lệ danh mục mang icon + màu khác mặc định tăng dần
Tốc độ thao tác	Chọn nhóm trên lưới POS nhanh hơn, ít bấm nhầm hơn
Tái sử dụng bộ chọn	Bộ chọn icon-màu được dùng ở ít nhất một form ngoài danh mục - đã đạt (danh mục thu-chi, danh mục phiếu hỗ trợ)

3. Persona & Tình huống

Persona	Mục tiêu trong tính năng này
Owner	Cho nhóm hàng 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 catalog	Chọn icon + màu và nhóm cha khi thiết lập danh mục
Thu ngân	Nhìn ô màu trên POS là bấm ngay đúng nhóm

Tình huống cốt lõi: vào màn Danh mục → tạo hoặc sửa một nhóm → chọn icon và màu (ô xem trước đổi ngay) → chọn nhóm cha nếu muốn xếp cây → lưu → nhóm hiện thành ô có icon, có màu trên POS và app quản trị.

4. User Stories

#	Là một	Tôi muốn	Để
01	Owner	gán icon và màu cho nhóm hàng	nó nhận ra được ngay trên lưới POS
02	nhân viên catalog	có sẵn bộ icon gợi ý đúng ngành của mình, và vẫn tìm được icon khác trong thư viện khi cần	chọn đúng icon nhanh mà không bị bó buộc trong danh sách gợi ý
03	nhân viên catalog	chọn màu preset cho nhanh, hoặc tự chọn màu bất kỳ	vừa nhanh vừa khớp được nhận diện thương hiệu khi cần
04	Owner	xếp nhóm con vào nhóm cha	danh mục có cấu trúc thay vì một danh sách phẳng
05	người dựng form	bộ chọn icon-màu là một control thả vào form nào cũng chạy	form khác dùng lại được ngay, không phải dựng control mới

5. Yêu cầu chức năng

#	Yêu cầu	Trạng thái	URD ref
FR-001	Danh mục hàng bán được tạo/sửa qua hai đường: màn Danh mục riêng (danh sách / tạo / sửa) và trong màn Sửa merchant.	✅	URD-CAT-001
FR-002	Mỗi danh mục mang một icon và một màu, lưu ngay trên danh mục. Danh mục không đặt icon/màu hiển thị với diện mạo mặc định.	✅	URD-CAT-004
FR-003	Bộ chọn icon và bộ chọn màu đều có sẵn gợi ý, kèm tùy chọn mở rộng. • Bộ chọn icon: khoảng 40 icon gợi ý theo ngành (quán ăn / bán lẻ) hiện trước, kèm ô tìm kiếm trên toàn bộ thư viện icon chuẩn của hệ thống, lưới cuộn mượt cả nghìn icon. • Bộ chọn màu: khoảng 12 màu preset theo giao diện, cộng một ô tự chọn màu bất kỳ.	✅	URD-CAT-004
FR-004	Bộ chọn icon-màu gắn với form và tái sử dụng được - đã dùng lại ở form danh mục thu-chi và danh mục phiếu hỗ trợ.	✅	URD-CAT-004
FR-005	Chọn nhóm cha để xếp danh mục thành cây, tối đa 8 tầng. • Tự làm cha chính mình và xếp thành vòng đều bị chặn. • Ô chọn cha chỉ có ở màn Danh mục riêng; tạo nhóm ở màn Sửa merchant thì chưa xếp cây được (chủ đích hiện tại, muốn xếp thì mở màn Danh mục).	✅	URD-CAT-005
FR-006	Form có ô xem trước trực tiếp: ô nhóm trên POS và nhãn trong danh sách đổi ngay theo icon / màu vừa chọn.	✅	URD-CAT-004
FR-007	Ở form khác (ví dụ form sản phẩm), ô chọn danh mục cho phép tạo nhanh một nhóm mới tại chỗ, không phải rời màn.	✅	URD-CAT-001
FR-008	Danh mục hệ thống dùng chung hiển thị cho merchant nhưng chỉ-đọc - không sửa, không xóa được.	✅	URD-CAT-006
FR-009	Đổi tên danh mục không ảnh hưởng sản phẩm trong nhóm. • Xóa là xóa mềm và theo chính sách xóa của merchant. • Bộ nhóm mẫu theo ngành được tạo sẵn khi đăng ký merchant.	✅	URD-CAT-002 · URD-CAT-003 · URD-CAT-007

5.1 Tiêu chí nghiệm thu

• Tạo một nhóm ở màn Danh mục với icon + màu + nhóm cha → nhóm hiện thành ô đúng icon, đúng màu trên POS và trong danh sách quản trị.
• Đổi màu trong form → ô xem trước đổi ngay, chưa cần lưu.
• Chọn cha tạo thành vòng (A là cha B, rồi chọn B làm cha A) hoặc vượt 8 tầng → bị chặn với thông báo rõ.
• Vào màn Sửa merchant, thêm một danh mục mới ở mục Danh mục rồi bấm lưu → danh mục được tạo thành công; xác nhận form ở màn này không có ô chọn nhóm cha (muốn xếp cây thì mở màn Danh mục).
• Thử sửa hoặc xóa một danh mục hệ thống → bị từ chối.
• Danh mục cũ chưa có icon/màu/cha → vẫn hoạt động, hiện diện mạo mặc định.
• Ở form sản phẩm, tạo nhanh một nhóm mới từ ô chọn danh mục → nhóm dùng được ngay không rời màn.

6. Yêu cầu phi chức năng

Khía cạnh	Yêu cầu
Toàn vẹn dữ liệu	Icon + màu nằm trên danh mục; nhóm cha chỉ đổi khi người dùng chủ động đổi ở màn Danh mục - lưu ở màn Sửa merchant không đụng tới cây
Tenancy & phân quyền	Danh mục giới hạn trong merchant của chính người dùng; thay đổi đi qua quyền của từng đường (màn Danh mục hoặc màn Sửa merchant)
Hiệu năng	Lưới icon được ảo hóa - chỉ vẽ phần đang nhìn thấy, cuộn mượt với cả nghìn icon
Tương thích ngược	Icon, màu và cha đều tùy chọn; danh mục cũ không có chúng vẫn chạy bình thường
i18n	Nhãn form và tên danh mục song ngữ (Anh / Việt)

7. UX & Luồng

Màn hình chính (app quản trị của Owner): màn Danh mục (danh sách / tạo / sửa) với form gồm tên song ngữ, bộ chọn icon-màu, ô chọn nhóm cha và ô xem trước; cùng mục danh mục bên trong màn Sửa merchant (không có ô chọn cha).

8. Dữ liệu & Miền nghiệp vụ

Thực thể	Vai trò
Danh mục	Nhóm hàng theo merchant - tên + mô tả (song ngữ), tham chiếu nhóm cha, icon + màu
Danh mục hệ thống	Bộ nhóm dùng chung do hệ thống cấp - chỉ-đọc với merchant
Hai đường quản lý	Màn Danh mục riêng (đầy đủ, có xếp cây) và màn Sửa merchant (nhanh, không xếp cây)

Chỉ ở mức khái niệm - schema đầy đủ nằm trong developer domain model.

9. Phụ thuộc & Giả định

Phụ thuộc vào

#	Feature	Phụ thuộc điều gì
01	Màn Sửa merchant (URD-MER-004)	một trong hai đường tạo/sửa danh mục.
02	Bộ icon chuẩn của hệ thống	nguồn icon cho bộ chọn.

Giả định

#	Giả định	Sai thì sao
01	Merchant đã tồn tại; danh mục luôn thuộc một merchant cụ thể.	Danh mục không gắn được vào đúng merchant thì phân quyền theo merchant (NFR §6) vỡ, danh mục của merchant này lẫn sang merchant khác.
02	Icon, màu và nhóm cha đều tùy chọn - không đặt thì dùng diện mạo mặc định.	Nếu ba trường này bắt buộc, danh mục cũ chưa có icon/màu/cha ngừng hoạt động được, và cần chạy migration mới dùng lại bình thường.
03	Loại danh mục được cố định theo từng màn hình (màn này = nhóm hàng bán) - người dùng không chọn loại.	Nếu người dùng tự chọn được loại danh mục, ranh giới với danh mục nguyên liệu kho (thuộc module Kho hàng) bị xóa nhòa, và một màn hình lẫn cả hai loại danh mục vào chung một danh sách.

10. Kế hoạch phát hành & Tiêu chí

Khía cạnh	Kế hoạch
Phase	P2 - xem danh mục feature URD
Rollout	Mọi merchant; không feature flag
Migration	Không - icon/màu/cha đều tùy chọn, dữ liệu cũ giữ nguyên
Tiêu chí ra mắt	Toàn bộ Tiêu chí nghiệm thu §5.1 pass trên merchant thật
Giám sát	Tỷ lệ danh mục có icon/màu tùy chỉnh; lỗi khi lưu danh mục

Tham chiếu

• URD: Commerce - CAT Danh mục · MER chính sách xóa
• Liên quan: MER Aggregate merchant · Kho hàng (danh mục nguyên liệu)
• Module: Commerce - URD
• Developer: @nx/commerce · domain model

Rủi ro & Câu hỏi mở

#	Rủi ro / câu hỏi	Giảm thiểu / trạng thái
01	Vẽ cả thư viện icon có thể chậm	Lưới ảo hóa - chỉ vẽ icon trong tầm nhìn
02	Chọn cha tạo vòng lặp	Đã chặn: tự làm cha, vòng lặp, và quá 8 tầng đều bị từ chối
03	Người dùng tạo nhóm ở màn Sửa merchant rồi không thấy chỗ xếp cây	Ghi rõ trong tài liệu hướng dẫn: xếp cây làm ở màn Danh mục (chủ đích hiện tại)

Câu hỏi thường gặp

#	Câu hỏi	Trả lời
01	Tạo danh mục ở đâu?	Hai chỗ: màn Danh mục riêng (đầy đủ nhất - có xếp cây), hoặc ngay trong màn Sửa merchant (nhanh, nhưng không có ô chọn cha). Dù tạo ở đâu, nhóm vẫn thuộc về đúng merchant đó.
02	Vì sao tạo nhóm ở màn Sửa merchant không xếp cây được?	Đây là chủ đích hiện tại để giữ màn đó gọn nhẹ. Muốn xếp cây, mở màn Danh mục.
03	Tôi chọn được icon nào?	Khoảng 40 icon gợi ý đúng ngành hiện trước; cần icon khác thì gõ tìm trong cả thư viện chuẩn của hệ thống.
04	Màu có bắt buộc chọn từ preset không?	Không - có khoảng 12 màu preset cho nhanh, và một ô tự chọn màu bất kỳ.
05	Danh mục cũ không có icon hay cha có hỏng không?	Không - cả ba đều tùy chọn; nhóm cũ giữ diện mạo mặc định.
06	Nhóm cho nguyên liệu kho thì sao?	Là màn hình khác, loại danh mục đã cố định theo màn. Thiết kế của nó thuộc module Kho hàng, không nằm trong PRD này.