212 lines
11 KiB
Markdown
212 lines
11 KiB
Markdown
# 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`) | |
|