improve BA skill

.claude/skills/ba-3-specification/templates/ui-convention.md

@@ -0,0 +1,211 @@
+# 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`) | |