UICONV — Quy ước giao diện — e-commerce
|
|
| Version |
1.1 |
| Date |
2026-09-08 |
| Author |
BA (qua skill ba-3-specification, activity uiconv) |
| Status |
🟡 Draft |
| Approved by |
Designer: — · PO: — (dự án chưa có Designer riêng — PO ký thay, xem DEC-01) |
| Source |
e-commerce/docs/sections/07-giao-dien.md (SAD §7 "Thiết kế giao diện", status: approved, version: 1 — coi là prototype tham chiếu dạng văn bản, xem DEC-01 đã sửa) · e-commerce/docs/sections/02-phan-tich-yeu-cau.md (NFR-01, NFR-06, NFR-07, FR-15, FR-16) · 02-analysis/BR_CartCheckout_v1.0.md §3 (vòng đời trạng thái CART/ORDER_SELLER/PAYMENT — nguồn cho Badge trạng thái §11) · 00-index/DECISION_e-commerce.md (DEC-01, DEC-05) · 00-index/PROFILE_e-commerce.md |
| Scope |
Toàn project — mọi SRS và WF có PRODUCT = screen. Lần chạy này ưu tiên điền quy ước phục vụ nhóm màn hình Guest/Customer (SCR-01…SCR-10, SAD §7.1.1); nhóm Seller/Admin/Ops/CSR (SCR-16…SCR-32) dùng chung khung §1–§10 nhưng phần điều hướng/menu riêng của họ chưa được đối chiếu chi tiết ở lần chạy này — xem ghi chú ở §1 và §12. |
| Profile |
screen · greenfield · standard (xem 00-index/PROFILE_e-commerce.md) |
Change Log
| Version |
Date |
Người sửa |
Thay đổi |
CR |
| 1.0 |
2026-09-08 |
BA (qua skill ba-3-specification, activity uiconv) |
Bản đầu — sinh từ SAD §7 (prototype dạng văn bản, SCR-01…SCR-32), NFR-01/06/07, BR_CartCheckout_v1.0.md §3. 10 open question mới (OQ-018…OQ-027) cho các ô "chọn một" mà SAD §7 không nói |
— |
| 1.1 |
2026-09-08 |
BA (qua skill ba-3-specification, activity srs/wf — bổ sung §10/§12 theo SRS_US002-003_v1.0.md/WF_US002-003_v1.0.md) |
§10: cập nhật số kế tiếp chưa dùng của dãy E-CART- từ 0002 lên 0007 (đã dùng 0002…0006 cho US-002/US-003). §12: thêm 2 dòng ngoại lệ đã duyệt — (1) SCR-04 dùng text riêng "Giỏ hàng trống"/"Tiếp tục mua sắm" thay mẫu chung §6 (đã ghi chú trước, nay chính thức hoá); (2) SCR-04 sửa số lượng theo mẫu inline auto-save (không có nút Lưu riêng), khác quy ước §4 mặc định |
— |
⚠️ Ngoại lệ gate G2 — tài liệu này được sinh trong khi Gate G2 (Solution sign-off) của
module Giỏ hàng & Checkout chưa được PO + Tech Lead ký chính thức (xem DEC-02, DEC-05
ở 00-index/DECISION_e-commerce.md). Ngoại lệ được người điều phối xác nhận rõ ràng. Nếu
BACKLOG_CartCheckout/BR_CartCheckout đổi khi G2 ký thật, phải rà lại §11 (từ vựng thành
phần liên quan Guest checkout) — xem OQ-027.
Vai trò của tài liệu này. Một project có nhiều SRS, mỗi lần chạy tối đa 3 US. Không có
tài liệu này thì mỗi SRS tự đặt một kiểu phân trang, một vị trí toast, một định dạng ngày.
SRS và WF tham chiếu mục ở đây thay vì định nghĩa lại; muốn lệch phải ghi vào §12.
Thứ tự ưu tiên khi lệch: Design system của dự án (nếu có) > Prototype đã duyệt > UICONV
SRS từng US. SRS chỉ được ghi khác UICONV khi có dòng ở §12.
0. Nguồn
|
|
| Design system |
Chưa có lựa chọn cụ thể. NFR-07 (SAD §2.2) ghi "sử dụng design system chuẩn (VD. Material Design hoặc Ant Design) làm nền tảng giao diện" — dev chọn, chưa chốt → OQ-022. Quy ước ở tài liệu này là ràng buộc tối thiểu (bố cục, trạng thái, text), không phụ thuộc design system cụ thể nào. |
| Prototype tham chiếu |
e-commerce/docs/sections/07-giao-dien.md — SAD §7 "Thiết kế giao diện" (status: approved, version: 1, ngày duyệt không ghi rõ trong front-matter). Mô tả bố cục dạng văn bản có cấu trúc (mục đích, persona, FR phục vụ, bố cục, 3 trạng thái, validation) cho SCR-01…SCR-32. Không phải Figma/ảnh — không có màu sắc/typography/khoảng cách chính xác (SAD §7.0 xác nhận rõ: "không có brand guideline cố định"). |
| Guideline sẵn có của dự án |
Không có GLOBAL_UI_CONVENTION.md trước đó — đây là bản đầu tiên. |
| Ai sở hữu quy ước |
BA đề xuất · Designer duyệt (dự án không có Designer ⇒ PO ký thay, DEC-01) · PO duyệt phần text/giọng văn |
| Nền tảng |
Web responsive (desktop, tablet, mobile-web) — theo SAD §7.0. Không có app di động native trong MVP (out-of-scope, xem SAD §1.1). |
1. Khung layout
|
|
| Grid |
🔴 Chưa chốt — SAD §7 không cho số cột/gutter/max-width cụ thể → OQ-018 |
| Header cố định |
Có — chứa: logo sàn, thanh tìm kiếm (autocomplete), LanguageSwitcher (FR-15), CurrencyToggle (FR-16, giá tham khảo), icon giỏ hàng (badge số lượng), icon tài khoản/đăng nhập. (Nguồn: SCR-01) |
| Sidebar / menu |
Nhóm Guest/Customer: Không có sidebar/menu cố định toàn cục — điều hướng chính qua header (tìm kiếm, tài khoản, giỏ hàng) + mega-menu ngành hàng (SCR-01 Section 2 "điều hướng ngành hàng"). Sidebar/bottom-sheet chỉ xuất hiện cục bộ ở màn hình có bộ lọc (SCR-02 — xem §3), không phải điều hướng toàn cục. (Nhóm Seller có header menu điều hướng riêng — SCR-17: "Sản phẩm, Đơn hàng, Báo cáo, Thông báo"; nhóm Admin tương tự SCR-22 — hai nhóm này ngoài phạm vi ưu tiên lần chạy này, chưa được điền chi tiết ở §1–§9, xem §12 khi có lần chạy uiconv bổ sung.) |
| Footer |
Có — chứa: thông tin sàn, chính sách đổi trả, liên kết ngôn ngữ, thông tin tuân thủ (thông báo Bộ Công Thương theo NĐ 52/2013, 85/2021 — NFR-05). (Nguồn: SCR-01) |
| Breakpoint |
Khoảng (px) |
Sidebar |
Bảng dữ liệu |
Form |
| Desktop |
🔴 OQ-018 |
Bộ lọc hiện cố định trái (SCR-02) |
N/A cho Guest/Customer — luôn dùng lưới ProductCard/CartItem, không phải bảng dữ liệu kiểu bảng-hành-chính (SCR-01, SCR-04) |
🔴 Số cột form — OQ-018 |
| Tablet |
🔴 OQ-018 |
🔴 Chưa chốt — SAD chỉ nói "desktop, tablet, mobile-web" không mô tả riêng hành vi tablet cho bộ lọc → OQ-018 |
Như trên |
🔴 OQ-018 |
| Mobile |
🔴 OQ-018 |
Bottom-sheet (SCR-02, nguyên văn: "Sidebar trái (desktop) / bottom-sheet (mobile)") |
Như trên |
🔴 OQ-018 |
Ghi chú: bảng Bảng → Card chuyển đổi theo breakpoint (mô tả ở template gốc) áp dụng cho các
màn hình quản trị (Seller/Admin, VD SCR-18, SCR-19, SCR-23) dùng bảng dữ liệu thật —
ngoài phạm vi ưu tiên Guest/Customer của lần chạy này.
2. Điều hướng
| Câu hỏi |
Quy ước |
| Quay lại từ màn hình chi tiết/form |
Nút Back và breadcrumb — cả hai. (Nguồn một phần: SCR-02 có breadcrumb "Trang chủ > Ngành hàng > Từ khoá"; nút Back không nói rõ trong SAD — BA đề xuất theo thực hành chung, PO/Dev FE xác nhận ở G3) |
| Quay lại có giữ trạng thái danh sách (trang, bộ lọc, sắp xếp)? |
✅ Giữ, qua query string — BA đề xuất (SAD không nói), không mâu thuẫn gì đã có |
| Vào bằng URL trực tiếp với id không tồn tại |
Trang trạng thái "Không tìm thấy" + nút về danh sách. (Nguồn: SCR-03 error = "Sản phẩm không tồn tại/đã bị gỡ" + link quay lại danh mục) |
| Vào bằng URL trực tiếp không có quyền |
Trang "Không có quyền" + nút về trang chủ; không lộ tên bản ghi — BA đề xuất theo W7, chưa có ví dụ cụ thể trong SAD §7.1.1–7.1.2 nhưng nhất quán với RBAC §4 (RBAC_CartCheckout_v1.0.md, che PII) |
| Rời màn hình khi form đang dở |
Modal xác nhận "Rời trang? Thay đổi chưa lưu sẽ mất." — BA đề xuất (SAD không nói) |
| Menu với chức năng không có quyền |
❌ Ẩn (W7) |
| Mở chi tiết |
Cùng tab, đổi URL. (Nguồn: luồng 7.2.1 "Tìm kiếm/duyệt danh mục (SCR-02, SCR-03)" mô tả điều hướng tuần tự trong cùng phiên, không có nhắc mở tab mới) |
3. Danh sách
|
|
| Kiểu phân trang |
🔴 Chưa chốt — SCR-02 nêu cả "phân trang hoặc infinite-scroll", chưa chọn 1 → OQ-019 |
| Số dòng mỗi trang |
🔴 Chưa chốt → OQ-019 |
| Sắp xếp mặc định |
🔴 Chưa chốt — SCR-02 liệt kê tuỳ chọn "giá tăng/giảm, mới nhất, bán chạy" nhưng không nói mặc định là gì → OQ-019 |
| Bấm vào dòng |
Bấm vào ProductCard → mở chi tiết sản phẩm (SCR-03). (Nguồn: luồng 7.2.1). Không áp dụng khái niệm "dòng bảng" cho Guest/Customer — xem §1 |
| Cột hành động |
N/A cho lưới ProductCard (Guest/Customer). Áp dụng cho bảng quản trị Seller/Admin (SCR-18, SCR-19, SCR-23…) — ngoài phạm vi ưu tiên lần này |
| Chọn nhiều dòng |
Riêng SCR-04 (Giỏ hàng): checkbox chọn/bỏ chọn từng CartItem hoặc cả nhóm seller để tính tạm tính — đây là chọn-để-tính-tổng, không phải thanh hành động hàng loạt kiểu xoá/duyệt. (Nguồn: SCR-04) |
| Tìm kiếm |
Autocomplete, tối thiểu 1 ký tự trước khi gợi ý; không cho submit tìm kiếm rỗng. (Nguồn: SCR-01 validation). Độ trễ debounce (ms) 🔴 chưa chốt → OQ-024 |
| Bộ lọc |
Thanh ngang trên bảng (desktop) · nút "Lọc" mở bottom-sheet (mobile) — tổng hợp từ SCR-02: "Sidebar trái (desktop) / bottom-sheet (mobile): bộ lọc — ngành hàng, khoảng giá, seller, rating, tình trạng còn hàng" (SAD gọi là sidebar chứ không phải "thanh ngang", đã điều chỉnh nhãn cho khớp — nội dung bộ lọc giữ nguyên theo SAD) |
| Cột trên mobile |
N/A — Guest/Customer dùng ProductCard/CartItem xuyên suốt mọi breakpoint, không có khái niệm "cột bảng → card" (đã là card từ đầu) |
4. Form
|
|
| Vị trí nút |
Lưu/CTA chính (nút chính) bên phải, Huỷ (nút phụ) bên trái nút chính — BA đề xuất, SAD không mô tả vị trí nút cụ thể, không mâu thuẫn với các CTA đã liệt kê (VD SCR-05 "Tiếp tục đến thanh toán", SCR-06 "Xác nhận thanh toán") |
| Đánh dấu bắt buộc |
Dấu * màu cảnh báo sau nhãn — BA đề xuất (SAD không mô tả) |
| Thời điểm validate |
Khi rời field (blur) và khi bấm nút chính — BA đề xuất, nhất quán với các validation liệt kê theo từng SCR (VD SCR-08 email đúng định dạng, SCR-09 SĐT đúng định dạng VN) |
| Vị trí message lỗi |
Ngay dưới field, thay chỗ hint; field viền cảnh báo — BA đề xuất, khớp với mô tả "thông báo inline" xuất hiện nhiều nơi (SCR-05 coupon không hợp lệ, SCR-18 xung đột SKU) |
| Lỗi nhiều field |
Focus vào field lỗi đầu tiên, cuộn tới nó — BA đề xuất (SAD không mô tả cơ chế UI chi tiết) |
| Lỗi từ server không gắn field |
Banner đầu form — BA đề xuất, khớp mẫu "banner lỗi" đã dùng ở SCR-01 |
| Sau lỗi mạng/5xx |
🔴 Giữ nguyên dữ liệu đã nhập, mở lại nút chính — quy tắc bắt buộc theo writing-rules.md, áp dụng toàn hệ thống trừ khi SRS ghi khác ở §12 |
| Đang gửi |
Khoá toàn form, spinner trong nút chính, nhãn đổi "Đang xử lý…". (Nguồn gần nhất: SCR-06 "Đang xử lý thanh toán..." — không cho thao tác khác, tránh double-submit; SCR-16 "spinner khi upload file (progress bar)") |
| Huỷ khi có thay đổi |
Modal xác nhận — BA đề xuất |
| Nhãn field |
Trên field (không đặt cạnh trái) — BA đề xuất |
| Nút CTA chính khi form chưa hợp lệ |
🔴 Chưa chốt — SAD chỉ nói rõ ở cấp wizard (SCR-16: "wizard chặn 'Next' nếu bước hiện tại chưa hợp lệ"), không nói cho form thường (VD SCR-08 đăng ký, SCR-09 hồ sơ) → OQ-021 |
5. Phản hồi hệ thống
| Loại |
Dùng khi |
Vị trí |
Thời lượng |
Có nút đóng |
| Toast thành công |
Lưu/xoá thành công |
🔴 Chưa chốt — SAD §7 không dùng khái niệm "toast" ở bất kỳ SCR nào → OQ-020 |
🔴 OQ-020 |
🔴 OQ-020 |
| Toast lỗi |
Lỗi không gắn field, có thể thử lại |
🔴 OQ-020 |
🔴 OQ-020 |
🔴 OQ-020 |
| Modal xác nhận |
Hành động không hoàn tác được (huỷ đơn, xoá) |
Giữa màn. (Nguồn: SCR-10 "xác nhận (dialog) trước khi huỷ đơn") |
— |
Nút chính bên phải; hành động nguy hiểm dùng nút nguy hiểm — BA đề xuất vị trí, hành vi "cần xác nhận" đã có nguồn |
| Inline dưới field |
Lỗi validation |
Dưới field |
Tới khi sửa |
— |
| Banner trong vùng |
Lỗi tải một vùng dữ liệu |
Trong vùng đó. (Nguồn: SCR-01 "banner lỗi 'Không tải được dữ liệu, thử lại' + nút retry"; SCR-02, SCR-03, SCR-09, SCR-10, SCR-14, SCR-15 dùng mẫu "lỗi tải + retry" tương tự) |
Tới khi thử lại |
Nút Thử lại |
| Trang trạng thái |
404 / 403 / lỗi toàn trang |
Toàn trang. (Nguồn: SCR-03 "Sản phẩm không tồn tại/đã bị gỡ" + link quay lại danh mục) |
— |
Nút về danh sách/trang chủ |
6. Trạng thái chuẩn
| Trạng thái |
Hiển thị |
Text mặc định (VI) |
Text (EN) |
Nút |
| Đang tải danh sách |
Skeleton lưới/bảng. (Nguồn: dùng ở hầu hết SCR-01…SCR-15, VD "loading = skeleton lưới sản phẩm/banner") |
— |
— |
— |
| Đang tải chi tiết/form |
Skeleton theo bố cục. (Nguồn: SCR-03 "loading = skeleton toàn trang") |
— |
— |
— |
| Đang tải cục bộ (tính lại phí ship/khuyến mãi) |
Spinner nhỏ tại chỗ. (Nguồn: SCR-05 "loading = tính lại phí vận chuyển/khuyến mãi khi thay đổi địa chỉ (spinner cục bộ)") |
— |
— |
— |
| Rỗng — chưa có dữ liệu nào |
Minh hoạ + câu dẫn + nút chính |
"Chưa có <đối tượng> nào." — mẫu quan sát được lặp lại nhiều nơi trong SAD (SCR-03 "Chưa có đánh giá nào", SCR-09 "Chưa có địa chỉ nào", SCR-14 "Chưa có giao dịch điểm thưởng nào", SCR-15 "Không có thông báo nào"). Hai ngoại lệ đã có text riêng trong SAD, không theo mẫu chung — giữ nguyên khi viết SRS cho đúng US: SCR-04 "Giỏ hàng trống", SCR-10 "Bạn chưa có đơn hàng nào" |
🔴 Chưa dịch chính thức — BA có thể đề xuất bản dịch EN khi viết SRS, ZH/KO/JA cần biên dịch chuyên nghiệp, không tự dịch → OQ-023 |
Tạo mới / CTA tương ứng (VD "Tiếp tục mua sắm" — SCR-04; "Tạo mới" — SCR-09) |
| Rỗng — bộ lọc không khớp |
Câu dẫn + nút phụ |
"Không tìm thấy <đối tượng> phù hợp với bộ lọc." — dựa trên SCR-02 "Không tìm thấy sản phẩm phù hợp" + gợi ý bỏ bớt bộ lọc |
🔴 OQ-023 |
Xoá lọc |
| Lỗi tải |
Banner trong vùng |
"Không tải được dữ liệu, thử lại." — nguyên văn SCR-01 |
🔴 OQ-023 |
Thử lại |
| Không có quyền |
Trang trạng thái |
"Bạn không có quyền truy cập nội dung này." — BA đề xuất (SAD không có ví dụ SCR cụ thể cho Guest/Customer, RBAC xử lý ở tầng khác) |
🔴 OQ-023 |
Về trang chủ |
| Không tìm thấy |
Trang trạng thái |
"Sản phẩm không tồn tại hoặc đã bị gỡ." (mẫu chung: "Không tìm thấy nội dung yêu cầu.") — nguồn SCR-03 |
🔴 OQ-023 |
Về danh sách |
SRS §2.3.6 chỉ ghi phần khác với bảng này (vd: câu dẫn riêng cho đối tượng), còn lại tham chiếu.
7. Ẩn · khoá · read-only (quy tắc W7)
| Trạng thái |
Trình bày |
Bắt buộc kèm |
❌ ẩn |
Không render |
— |
🔒 disable |
Mờ 45%, con trỏ mặc định |
Tooltip nêu lý do khi hover/focus. (Nguồn hành vi tương tự: SCR-03 "nút chuyển trạng thái 'Hết hàng', disabled" khi SKU hết hàng — SAD xác nhận có dùng disable, không cho chi tiết % mờ/tooltip, phần trình bày cụ thể là đề xuất BA) |
👁 read-only |
Giá trị dạng text, không viền ô nhập, nhãn giữ nguyên. (Nguồn: SCR-06 "tóm tắt đơn hàng (read-only, tham chiếu từ SCR-05)"; SCR-09 "email (read-only hoặc yêu cầu xác thực lại khi đổi)") |
— |
8. Định dạng hiển thị
SRS §4.3 tham chiếu bảng này; chỉ ghi khác khi có dòng ở §12.
| Loại |
Định dạng |
Ví dụ |
Ghi chú |
| Ngày |
dd/MM/yyyy |
30/08/2026 |
BA đề xuất theo chuẩn VN, SAD không cho ví dụ cụ thể |
| Ngày giờ |
dd/MM/yyyy HH:mm |
30/08/2026 14:05 |
Múi giờ hiển thị: đề xuất UTC+7 cố định (thị trường Việt Nam, giao dịch VND, tuân thủ NĐ 52/2013 — SAD §7.0) — 🔴 chưa được Tech Lead/PO xác nhận chính thức là không cần hiển thị theo múi giờ địa phương của người dùng nước ngoài dùng EN/ZH/KO/JA; coi là giả định của lần chạy này, cần xác nhận trước khi SRS dùng |
| Lưu trữ thời gian |
ISO-8601 UTC |
|
Khớp API §1 (khi viết) |
| Số |
#,##0 |
1.234.567 |
Dấu phân cách: theo chuẩn VN (dấu chấm phân nghìn) — BA đề xuất, SAD không cho ví dụ |
| Tiền (VND — giao dịch chính) |
#,##0 ₫ |
1.234.567 ₫ |
Làm tròn: không làm tròn thêm ở cấp hiển thị (VND không có phần thập phân) — theo BR-CART-09 (BR_CartCheckout_v1.0.md) |
| Giá quy đổi tham khảo (đa tiền tệ) |
🔴 Chưa chốt |
|
Nguồn tỷ giá, tần suất cập nhật, quy tắc làm tròn cho CurrencyToggle/PriceDisplay (FR-16/NFR-06) — SAD chỉ xác nhận đây là "giá quy đổi tham khảo", không phải giá giao dịch → OQ-025 |
| Phần trăm |
0,0 % |
12,5 % |
BA đề xuất — dùng cho % hoa hồng (SCR-25), ngoài phạm vi ưu tiên Guest/Customer nhưng dùng chung định dạng |
| Rỗng / null |
— |
|
Thống nhất toàn hệ thống — BA đề xuất |
| Số lớn (id, mã đơn) |
Hiển thị nguyên văn chuỗi |
order_number/sub_order_number — theo BR_CartCheckout_v1.0.md §4.1, đây là khoá nghiệp vụ dạng chuỗi, không phải số kỹ thuật để tính toán |
Không format |
9. Ngôn ngữ và giọng văn
|
|
| Ngôn ngữ hỗ trợ |
VI (mặc định) · EN · ZH · KO · JA — theo FR-15/NFR-06 (SAD §2.2, §7.0). Thiếu bản dịch ⇒ hiện khoá hay VI? 🔴 Chưa chốt → OQ-023 |
| Xưng hô |
🔴 Chưa chốt — SAD §7 không đề cập giọng văn → OQ-026 |
| Thông điệp lỗi |
Nói vì sao và làm gì tiếp; không mã kỹ thuật; kết thúc bằng dấu chấm. (Nguồn nhất quán với các ví dụ SAD: SCR-01 "Không tải được dữ liệu, thử lại", SCR-06 "thông báo lý do + nút 'Thử lại' hoặc 'Chọn phương thức khác'") |
| Nhãn nút |
Động từ, viết hoa chữ đầu — khớp các CTA đã liệt kê trong SAD: "Thêm vào giỏ", "Tiến hành Checkout", "Xác nhận thanh toán", "Tiếp tục mua sắm" |
| Tiêu đề màn hình |
Danh từ — khớp SCR-04 "Giỏ hàng của bạn" (có xưng "bạn" — mâu thuẫn tiềm ẩn với OQ-026 chưa chốt, cần thống nhất khi trả lời) |
| Độ dài nhãn tối đa |
🔴 Chưa chốt (ký tự) — SAD chỉ cảnh báo định tính "ZH/KO/JA cần rà soát độ dài chuỗi dịch có thể dài hơn, layout co giãn được" → OQ-023 |
| Khoá i18n |
<scr>.<thành phần>.<thuộc tính> — vd scr01.search.ph — quy ước kỹ thuật do BA đề xuất, Dev FE áp dụng, không cần PO duyệt |
10. Dãy mã lỗi
| Dãy |
Module / phạm vi |
Số kế tiếp chưa dùng |
Ai cấp |
E-CART- |
Giỏ hàng & Checkout (RQ-001…RQ-004) |
0007 — E-CART-0001 đã dùng cho BR-CART-02 (giữ tồn kho khi checkout, BR_CartCheckout_v1.0.md §2); E-CART-0002…0006 đã dùng cho US-002/US-003 (SRS_US002-003_v1.0.md §4.1) |
BA |
Các module khác (Catalog, Seller, Admin, Payout, Khuyến mãi/Loyalty…) chưa có SRS/BR viết
tới ở GĐ3 — sẽ đăng ký dãy mã khi module đó chạy ba-3-specification.
11. Từ vựng thành phần
WF §3.x.2 cột "Kiểu trình bày" chỉ dùng từ ở cột đầu. Cột thứ hai map sang design system khi có (🔴 OQ-022 — design system chưa chọn, để trống).
| Kiểu trình bày |
Component trong design system |
Dùng khi |
| Nút chính |
🔴 OQ-022 |
Một hành động chính mỗi màn hình (VD "Tiến hành Checkout" — SCR-04) |
| Nút phụ |
🔴 OQ-022 |
Huỷ, hành động thứ cấp |
| Nút nguy hiểm |
🔴 OQ-022 |
Xoá, huỷ đơn — luôn kèm modal xác nhận (SCR-10) |
| Liên kết |
🔴 OQ-022 |
Điều hướng trong text (VD "Theo dõi đơn hàng" — SCR-07) |
| Ô nhập |
🔴 OQ-022 |
|
| Ô nhập số |
🔴 OQ-022 |
Số lượng sản phẩm (SCR-03, SCR-04) |
| Chọn 1 |
🔴 OQ-022 |
Phương thức thanh toán (SCR-06: "radio group") — ≤ 7 lựa chọn |
| Chọn nhiều |
🔴 OQ-022 |
Checkbox chọn CartItem (SCR-04) |
| Chọn ngày / khoảng ngày |
🔴 OQ-022 |
|
| Công tắc |
🔴 OQ-022 |
|
| Bảng |
🔴 OQ-022 |
Desktop — chủ yếu dùng ở màn hình quản trị Seller/Admin, ngoài ưu tiên lần này |
| Card |
🔴 OQ-022 |
ProductCard (SCR-01, SCR-02, SCR-03, SCR-12), CartItem (SCR-04) — dùng xuyên suốt mọi breakpoint cho Guest/Customer, không chỉ trên mobile |
| Badge trạng thái |
🔴 OQ-022 |
Trạng thái vòng đời — xem bảng ánh xạ chi tiết bên dưới |
| Tab |
🔴 OQ-022 |
Đăng nhập/Đăng ký (SCR-08); Thông tin cá nhân/Sổ địa chỉ (SCR-09) |
| Modal |
🔴 OQ-022 |
Xác nhận huỷ đơn (SCR-10) |
| Drawer |
🔴 OQ-022 |
|
| Bottom-sheet |
🔴 OQ-022 |
Bộ lọc trên mobile (SCR-02) |
| Toast |
🔴 OQ-022 + OQ-020 (vị trí/thời lượng chưa chốt) |
§5 |
| Skeleton |
🔴 OQ-022 |
§6 |
LanguageSwitcher |
🔴 OQ-022 |
Component riêng của dự án (FR-15) — cố định ở header, mọi màn hình |
CurrencyToggle / PriceDisplay |
🔴 OQ-022 |
Component riêng của dự án (FR-16) — hiển thị giá VND + giá quy đổi tham khảo, mọi nơi có giá |
11.1 Badge trạng thái — ánh xạ theo vòng đời (nguồn: BR_CartCheckout_v1.0.md §3)
Chỉ mô tả nhãn hiển thị và nhóm ý nghĩa màu (không có hex cụ thể — SAD §7.0 xác nhận
dự án không có brand guideline; hex/màu chính xác thuộc OQ-022 khi chọn design system).
| Thực thể |
Trạng thái kỹ thuật |
Nhãn hiển thị (VI, đề xuất) |
Nhóm ý nghĩa màu |
Nguồn |
CART |
active |
"Đang hoạt động" |
Trung tính |
BR_CartCheckout_v1.0.md §3 |
CART |
converted |
"Đã chuyển thành đơn" |
Thành công |
nt |
CART |
abandoned |
"Bỏ quên" |
Trung tính/cảnh báo nhẹ |
nt |
ORDER_SELLER (đoạn khởi tạo) |
pending |
"Chờ thanh toán" |
Cảnh báo |
nt |
ORDER_SELLER (đoạn khởi tạo) |
confirmed |
"Đã xác nhận" |
Thành công |
nt |
ORDER_SELLER (đoạn khởi tạo) |
cancelled |
"Đã huỷ" |
Lỗi/trung tính |
nt |
PAYMENT |
pending |
"Chờ xử lý" |
Cảnh báo |
nt |
PAYMENT |
success |
"Thành công" |
Thành công |
nt |
PAYMENT |
failed |
"Thất bại" |
Lỗi |
nt |
🔴 Chưa đầy đủ để SRS dùng trực tiếp: vòng đời đầy đủ của ORDER_SELLER sau confirmed
(packed/shipped/delivered/returned…) thuộc module Quản lý đơn hàng (FR-08/FR-19), ngoài
phạm vi module Giỏ hàng & Checkout — SRS của module đó phải bổ sung nhãn cho các trạng thái
còn lại (khớp danh sách filter đã có ở SCR-10: "Chờ xác nhận, Đang xử lý, Đang giao, Đã giao,
Đã huỷ, Yêu cầu đổi trả" — các nhãn này chưa được đối chiếu 1-1 với state machine BR ở GĐ2,
cần rà khi viết SRS US-004 trở đi). Payment.status khi COD (ghi success ngay hay giữ
pending) chưa chốt — xem OQ-013 (đã mở từ GĐ2, chưa đóng).
12. Ngoại lệ đã duyệt
SRS/WF lệch quy ước ⇒ phải có dòng ở đây. Không có dòng ⇒ lệch là lỗi, không phải quyết định.
| # |
Tài liệu |
Mục lệch |
Quy ước |
Thực tế |
Vì sao |
Ai duyệt |
Ngày |
| 1 |
SRS_US002-003_v1.0.md §2.A.3.6, WF_US002-003_v1.0.md §3.1.3 |
§6 Trạng thái chuẩn — "Rỗng, chưa có dữ liệu nào" |
"Chưa có <đối tượng> nào." |
"Giỏ hàng trống" + nút "Tiếp tục mua sắm" |
Text nguyên văn đã có sẵn trong SAD §7.1.1 SCR-04 (nguồn duyệt sẵn), giữ nguyên để không tạo hai phiên bản câu chữ cho cùng một khái niệm |
PO (thay Designer, DEC-01) |
2026-09-08 |
| 2 |
SRS_US002-003_v1.0.md §2.A.3.1 (F01), UICONV §4 |
§4 Form — "Vị trí nút Lưu... Thời điểm validate: khi rời field và khi bấm Lưu" |
Không có nút "Lưu" riêng — mỗi lần đổi số lượng (F01) gửi PATCH ngay lập tức (auto-save) |
Số lượng trong giỏ hàng là thao tác tần suất cao, chỉ một field; mẫu "inline edit" tránh người dùng phải nhớ bấm Lưu cho từng dòng trong danh sách nhiều dòng |
PO (thay Designer, DEC-01) |
2026-09-08 |
|
13. Open Questions
| ID |
Câu hỏi |
Hỏi ai |
Từ ngày |
Chặn gì |
| OQ-018 |
Ngưỡng breakpoint theo px cho desktop/tablet/mobile-web, và grid layout (số cột, gutter px, max-width px) toàn site |
Dev FE / Tech Lead |
2026-09-08 |
§1 |
| OQ-019 |
Kiểu phân trang, số dòng/trang, tiêu chí sắp xếp mặc định cho danh sách sản phẩm (SCR-02) và lịch sử đơn hàng (SCR-10) |
PO, Dev FE |
2026-09-08 |
§3 |
| OQ-020 |
Vị trí và thời lượng hiển thị toast thông báo |
PO, Dev FE |
2026-09-08 |
§5, §11 |
| OQ-021 |
Nút CTA chính khi form chưa hợp lệ: bấm được rồi hiện lỗi, hay khoá (disable)? |
PO, Dev FE |
2026-09-08 |
§4 |
| OQ-022 |
Chọn design system cụ thể (Material Design hay Ant Design) |
Tech Lead |
2026-09-08 |
§0, §11 |
| OQ-023 |
Ngôn ngữ thiếu bản dịch: khoá hay fallback VI? Độ dài nhãn tối đa (ký tự)? Bản dịch EN/ZH/KO/JA cho các text mặc định ở §6 |
PO, Dev FE (và cần đơn vị biên dịch cho ZH/KO/JA) |
2026-09-08 |
§6, §9 |
| OQ-024 |
Độ trễ debounce (ms) cho gợi ý autocomplete tìm kiếm |
Dev FE |
2026-09-08 |
§3 |
| OQ-025 |
Quy tắc quy đổi tiền tệ tham khảo: nguồn tỷ giá, tần suất cập nhật, làm tròn |
PO, Tech Lead |
2026-09-08 |
§8 |
| OQ-026 |
Xưng hô trong toàn bộ text hệ thống ("bạn" hay không xưng hô) |
PO |
2026-09-08 |
§9 |
| OQ-027 |
🔴 Ngoại lệ gate G2 chưa ký — ảnh hưởng tới §11 (Guest checkout) nếu BACKLOG/BR đổi khi ký G2 thật |
PO, Tech Lead |
2026-09-08 |
Baseline UICONV |
Tự chấm
| # |
Tiêu chí |
☐/✅ |
| 1 |
Mọi ô "chọn một" đã chọn, không còn dấu / giữa các phương án |
☐ — 10 ô còn mở, mỗi ô có OQ tương ứng (§1, §3, §4, §5, §9), không tự chọn theo đúng chỉ đạo |
| 2 |
§6 có hai trạng thái rỗng trông khác nhau |
✅ — "Rỗng — chưa có dữ liệu nào" (minh hoạ + nút chính, VD "Tạo mới"/"Tiếp tục mua sắm") khác "Rỗng — bộ lọc không khớp" (không minh hoạ, nút phụ "Xoá lọc"), theo đúng mẫu SCR-02 |
| 3 |
§8 có múi giờ hiển thị và quy tắc làm tròn tiền |
🟡 — múi giờ đề xuất UTC+7 nhưng chưa xác nhận chính thức (đánh dấu 🔴 trong bảng); làm tròn VND đã có (không làm tròn thêm); làm tròn tiền quy đổi tham khảo chưa chốt (OQ-025) |
| 4 |
§11 mọi kiểu trình bày dùng trong WF hiện có đều có dòng |
✅ — WF_US002-003_v1.0.md (SCR-04) chỉ dùng: Nhãn, Nút chính, Nút phụ, Nút nguy hiểm, Ô nhập số, Card, Modal, Badge trạng thái — cả 8 kiểu đều đã có dòng ở §11 |
| 5 |
Có chữ ký Designer (hoặc ghi rõ dự án không có Designer ⇒ PO ký thay, DEC-nn) |
✅ — dự án không có Designer, PO ký thay theo DEC-01 (đã sửa nội dung ở v1.2, giữ nguyên phần này); chữ ký thật chưa có — Approved by vẫn để trống, chờ PO ký ở G3 |
