sys-analysis-design/ba-output/e-commerce/00-index/UICONV_e-commerce_v1.0.md

# 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 |