# UICONV — Quy ước giao diện — <PROJECT>

| | |
|---|---|
| **Version** | 1.0 |
| **Date** | YYYY-MM-DD |
| **Author** | <BA> (skill ba-3-specification, activity `uiconv`) |
| **Status** | 🟡 Draft |
| **Approved by** | Designer: — · PO: — |
| **Source** | <prototype / design system / SAD §7 / GLOBAL_UI_CONVENTION của dự án / DEC-nn> |
| **Scope** | Toàn project — mọi `SRS` và `WF` có `PRODUCT = screen` |
| **Profile** | `screen · … · …` |

## Change Log

| Version | Date | Người sửa | Thay đổi | CR |
|---|---|---|---|---|
| 1.0 | | | Bản đầu | — |

> **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** | *(tên + version + link, hoặc "Chưa có — dev chọn theo NFR, quy ước ở đây là ràng buộc tối thiểu")* |
| **Prototype tham chiếu** | *(đường dẫn / URL / mục SAD, phiên bản, ngày)* |
| **Guideline sẵn có của dự án** | *(vd: GLOBAL_UI_CONVENTION.md — nếu có thì file này chỉ bổ khuyết, không chép lại)* |
| **Ai sở hữu quy ước** | BA đề xuất · **Designer duyệt** · PO duyệt phần text/giọng văn |
| **Nền tảng** | Web desktop / web responsive / app di động — *(theo BRIEF)* |

## 1. Khung layout

| | |
|---|---|
| **Grid** | *(số cột · gutter px · max-width px)* |
| **Header cố định** | Có / Không — chứa: *(logo, tìm kiếm toàn cục, ngôn ngữ, tài khoản…)* |
| **Sidebar / menu** | Trái cố định / thu gọn được / không có |
| **Footer** | Có / Không — chứa: |

| Breakpoint | Khoảng (px) | Sidebar | Bảng dữ liệu | Form |
|---|---|---|---|---|
| Desktop | ≥ 1024 | Hiện | Bảng | 2 cột |
| Tablet | 768–1023 | Thu gọn icon | Bảng cuộn ngang | 1 cột |
| Mobile | < 768 | Ẩn sau nút menu | **Card** | 1 cột |

## 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 |
| Quay lại có giữ trạng thái danh sách (trang, bộ lọc, sắp xếp)? | ✅ Giữ, qua query string |
| 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 |
| 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 |
| 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." |
| Menu với chức năng không có quyền | ❌ Ẩn (W7) |
| Mở chi tiết | Cùng tab, đổi URL |

## 3. Danh sách

| | |
|---|---|
| **Kiểu phân trang** | Offset (`page`, `size`) / Cursor / Cuộn vô hạn |
| **Số dòng mỗi trang** | Mặc định … · tuỳ chọn … |
| **Sắp xếp mặc định** | *(vd: ngày tạo giảm dần)* |
| **Bấm vào dòng** | Mở chi tiết / Chỉ nút "Chi tiết" mới mở |
| **Cột hành động** | Cột cuối, icon + tooltip / Menu ⋯ |
| **Chọn nhiều dòng** | Checkbox cột đầu, thanh hành động hàng loạt xuất hiện phía trên |
| **Tìm kiếm** | Gõ rồi Enter / Gợi ý sau khi ngừng gõ … ms |
| **Bộ lọc** | Thanh ngang trên bảng (desktop) · nút "Lọc" mở bottom-sheet (mobile) |
| **Cột trên mobile** | Bảng → card; card hiện tối đa … trường: *(liệt kê thứ tự ưu tiên chung)* |

## 4. Form

| | |
|---|---|
| **Vị trí nút** | Lưu (nút chính) **bên phải**, Huỷ (nút phụ) bên trái nút Lưu |
| **Đánh dấu bắt buộc** | Dấu `*` màu cảnh báo sau nhãn |
| **Thời điểm validate** | Khi rời field (blur) **và** khi bấm Lưu |
| **Vị trí message lỗi** | Ngay dưới field, thay chỗ hint; field viền cảnh báo |
| **Lỗi nhiều field** | Focus vào field lỗi đầu tiên, cuộn tới nó |
| **Lỗi từ server không gắn field** | Banner đầu form |
| **Sau lỗi mạng/5xx** | 🔴 **Giữ nguyên dữ liệu đã nhập**, mở lại nút Lưu |
| **Đang gửi** | Khoá toàn form, spinner trong nút Lưu, nhãn đổi "Đang lưu…" |
| **Huỷ khi có thay đổi** | Modal xác nhận |
| **Nhãn field** | Trên field (không đặt cạnh trái) |
| **Nút Lưu khi form chưa hợp lệ** | Bấm được, hiện lỗi / 🔒 disable — *(chọn một)* |

## 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 | Góc trên phải (desktop) · trên cùng (mobile) | 3 s tự đóng | ✅ |
| **Toast lỗi** | Lỗi không gắn field, có thể thử lại | Như trên | Không tự đóng | ✅ |
| **Modal xác nhận** | Hành động không hoàn tác được (xoá, gửi duyệt) | Giữa màn | — | Nút chính bên **phải**; hành động nguy hiểm dùng nút nguy hiểm |
| **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 đó | 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 | — | 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 … dòng | — | — | — |
| Đang tải chi tiết/form | Skeleton theo bố cục | — | — | — |
| Đang tải cục bộ (dropdown, tính lại) | Spinner nhỏ tại chỗ | — | — | — |
| **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." | | Tạo mới |
| **Rỗng — bộ lọc không khớp** | Câu dẫn + nút phụ *(không minh hoạ, để khác loại trên)* | "Không tìm thấy kết quả phù hợp với bộ lọc." | | Xoá lọc |
| Lỗi tải | Banner trong vùng | "Không tải được dữ liệu." | | 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." | | Về trang chủ |
| Không tìm thấy | Trang trạng thái | "Không tìm thấy nội dung yêu cầu." | | 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 |
| `👁 read-only` | Giá trị dạng text, không viền ô nhập, nhãn giữ nguyên | — |

## 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 | |
| Ngày giờ | `dd/MM/yyyy HH:mm` | 30/08/2026 14:05 | **Múi giờ hiển thị:** … *(theo người dùng / cố định UTC+7)* |
| Lưu trữ thời gian | ISO-8601 UTC | | Khớp `API` §1 |
| Số | `#,##0` | 1.234.567 | Dấu phân cách: … |
| Tiền | `#,##0 ₫` | 1.234.567 ₫ | Làm tròn: … · đa tiền tệ: … |
| Phần trăm | `0,0 %` | 12,5 % | |
| Rỗng / null | `—` | | Thống nhất toàn hệ thống |
| Số lớn (id) | Hiển thị nguyên văn chuỗi | | Không format |

## 9. Ngôn ngữ và giọng văn

| | |
|---|---|
| **Ngôn ngữ hỗ trợ** | VI (mặc định) · EN · … — thiếu bản dịch ⇒ hiện **khoá** hay **VI**? *(chọn một)* |
| **Xưng hô** | "bạn" / không xưng hô |
| **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 |
| **Nhãn nút** | Động từ, viết hoa chữ đầu: "Tạo mới", "Lưu", "Huỷ" |
| **Tiêu đề màn hình** | Danh từ: "Danh sách cửa hàng" |
| **Độ dài nhãn tối đa** | … ký tự — để không vỡ ở ngôn ngữ dài (KO/DE) |
| **Khoá i18n** | `<scr>.<thành phần>.<thuộc tính>` — vd `scr01.search.ph` |

## 10. Dãy mã lỗi

| Dãy | Module / phạm vi | Số kế tiếp chưa dùng | Ai cấp |
|---|---|---|---|
| `E-<DOMAIN>-` | | 0001 | BA |

## 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ó.*

| Kiểu trình bày | Component trong design system | Dùng khi |
|---|---|---|
| Nút chính | | Một hành động chính mỗi màn hình |
| Nút phụ | | Huỷ, hành động thứ cấp |
| Nút nguy hiểm | | Xoá, huỷ đơn — luôn kèm modal xác nhận |
| Liên kết | | Điều hướng trong text |
| Ô nhập | | |
| Ô nhập số | | |
| Chọn 1 | | ≤ 7 lựa chọn: radio · > 7: dropdown có tìm |
| Chọn nhiều | | |
| Chọn ngày / khoảng ngày | | |
| Công tắc | | Bật/tắt có hiệu lực ngay |
| Bảng | | Desktop |
| Card | | Mobile, hoặc dữ liệu ít cột |
| Badge trạng thái | | Trạng thái vòng đời (BR §3) |
| Tab | | Nhóm nội dung cùng cấp trong một màn hình |
| Modal | | Form ngắn ≤ 6 field, xác nhận |
| Drawer | | Form dài, chi tiết nhanh |
| Bottom-sheet | | Bộ lọc trên mobile |
| Toast | | §5 |
| Skeleton | | §6 |

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

## 13. Open Questions

| ID | Câu hỏi | Hỏi ai | Từ ngày | Chặn gì |
|---|---|---|---|---|

---

## 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 | |
| 2 | §6 có hai trạng thái rỗng **trông khác nhau** | |
| 3 | §8 có múi giờ hiển thị và quy tắc làm tròn tiền | |
| 4 | §11 mọi kiểu trình bày dùng trong `WF` hiện có đều có dòng | |
| 5 | Có chữ ký Designer (hoặc ghi rõ dự án không có Designer ⇒ PO ký thay, `DEC-nn`) | |