# Từ vựng thao tác UI & thuật ngữ IT — dùng chung mọi tài liệu

> File này là quy tắc dùng chung cho **mọi** tài liệu ai-flow-kit sinh ra hoặc sửa: Analysis, QnA-Log, UI Prototype (phần ghi chú), UC Spec, System Requirement, `requirement.md`, plan, test analysis, test scenario, test case, Dev Checklist, test report, bug report, tài liệu `gen-doc`.
> Kế thừa từ `custom/skills/test-skills/rules/qa-writing-standards.md` mục 6.11 (workflow `create-testcase`) — bảng từ vựng ở mục 2 bên dưới là bản gốc, mục 6.11 chỉ còn trỏ về đây.
> Đọc cùng `document-wording.md` (cách hành văn) và `domain-terminology.md` (thuật ngữ nghiệp vụ, tên tiếng Nhật).
> Nguồn: review của BA/PM trên UC Spec WONDER-1156 (2026-10-08) — "bấm nút → click button", "chọn tay → select manual": câu chữ phải chuẩn với môi trường IT mà Dev / Tester dùng hằng ngày.

## 1. Phạm vi áp dụng

| Loại câu | Áp dụng | Ví dụ |
| :--- | :--- | :--- |
| Câu mô tả **thao tác của người dùng trên UI** — bước của Main / Alternative / Exception Flow, Steps của test case, bước tái hiện bug, Acceptance Test, nhãn Mermaid | **Bắt buộc** dùng động từ chuẩn ở mục 2 | `admin click button 「登録」 (Đăng ký)` |
| Câu mô tả **trạng thái / kết quả hiển thị của UI** — System Response, Expected Result, hành động khi kiểm tra thất bại của Business Rule | **Bắt buộc** dùng tên trạng thái chuẩn ở mục 2 | `Button 「注文手続きへ」 chuyển sang Disabled` |
| Mọi câu có **thuật ngữ IT** (server, cache, toast, field…) | **Bắt buộc** giữ tiếng Anh theo mục 3 | `xóa cache`, không viết "xóa bộ nhớ đệm" |
| Câu mô tả **nghiệp vụ** — Description, điều kiện của Business Rule, bối cảnh câu hỏi Q&A | Viết tiếng Việt bình thường; riêng thuật ngữ IT vẫn theo mục 3 | `buyer chỉ thấy product thuộc group của mình` |
| **Chữ gốc trích nguyên văn** — nhãn màn hình, câu thông báo trong 「」, câu trả lời khách hàng | Không sửa | `「本当に削除しますか？」` |

## 2. Động từ thao tác và trạng thái chuẩn theo từng loại control

- Câu vẫn viết tiếng Việt, nhưng **cụm động từ thao tác và tên trạng thái của UI control** dùng đúng tiếng Anh chuẩn trong các bảng dưới — không tự dịch / sáng tác từ khác ("bấm", "nhấn", "tích chọn", "gạt nút", "mở khoá").
- Dùng thẳng tiếng Anh, **không chú thích tiếng Việt kèm theo** cho động từ / trạng thái. Quy tắc kèm tên gọi tiếng Việt chỉ áp dụng cho **nhãn tiếng Nhật** trên màn hình (`domain-terminology.md`).
- Một loại control chỉ dùng **một** cặp động từ / trạng thái xuyên suốt tài liệu và xuyên suốt các tài liệu của cùng functionId.
- Cột "Loại Component" của bảng UI Components (UC Spec) và loại control trong System Requirement dùng đúng tên Element trong các bảng dưới (`Text input`, `Button`, `Multi-select dropdown`, `Modal / Dialog`, `File upload`…).
- ✅ `1. Check checkbox "Ghi nhớ đăng nhập".` → Expected: `Checkbox chuyển sang trạng thái Checked.`
- ❌ `1. Tích chọn checkbox "Ghi nhớ đăng nhập".`

**A. Text/Number Input**

| Element | Hành động chuẩn (Steps) | Trạng thái/Kết quả chuẩn (Expected Result) |
|---|---|---|
| Text input / Textarea / Email / URL / Tel | `Enter <value> into <field>` ; `Clear <field>` | Field value = `<value>` ; Field is empty |
| Password input | `Enter <value> into password field` ; `Click Show/Hide password` | Password masked/unmasked |
| Number input | `Enter <value> into <field>` ; `Click stepper Up/Down` | Value increases/decreases by step |
| Search box | `Enter <keyword> into search box` ; `Clear search box` | — |

**B. Selection Controls**

| Element | Hành động chuẩn (Steps) | Trạng thái/Kết quả chuẩn (Expected Result) |
|---|---|---|
| Checkbox | `Check` / `Uncheck` | `Checked` / `Unchecked` |
| Radio button | `Select` | `Selected` |
| Toggle / Switch | `Turn on` / `Turn off` | `On` / `Off` |
| Dropdown / Select (single) | `Select <option> from dropdown` | Selected value = `<option>` |
| Multi-select dropdown | `Select` / `Deselect <option(s)>` | Selected values = `[...]` |
| Combobox / Autocomplete | `Type <keyword>` then `select <option> from suggestion list` | Selected value = `<option>` |
| Slider / Range | `Drag slider to <value>` | Slider value = `<value>` |
| Rating (stars) | `Click <n>-star rating` | Rating = `<n> stars` |
| Color picker | `Select color <value>` | Selected color = `<value>` |

**C. Date & Time**

| Element | Hành động chuẩn (Steps) | Trạng thái/Kết quả chuẩn (Expected Result) |
|---|---|---|
| Date picker | `Select date <value> from calendar` ; `Enter date <value>` | Selected date = `<value>` |
| Time picker | `Select time <value>` | Selected time = `<value>` |

**D. Actionable Elements**

| Element | Hành động chuẩn (Steps) | Trạng thái/Kết quả chuẩn (Expected Result) |
|---|---|---|
| Button | `Click button <Label>` | Button `Enabled`/`Disabled` |
| Icon button | `Click icon <Label/aria-label>` | — |
| Link | `Click link <Label>` | `Navigate to <destination>` |

**E. Navigation & Disclosure**

| Element | Hành động chuẩn (Steps) | Trạng thái/Kết quả chuẩn (Expected Result) |
|---|---|---|
| Tab | `Click tab <Label>` | Tab `<Label>` is `Active` |
| Accordion / Collapsible section | `Expand` / `Collapse <section>` | Section `Expanded`/`Collapsed` |
| Menu (dropdown menu) | `Open menu <Label>` ; `Click menu item <Label>` | Menu `Opened`/`Closed` |
| Breadcrumb | `Click breadcrumb item <Label>` | — |
| Pagination | `Click page <n>` ; `Click Next`/`Previous` | Current page = `<n>` |
| Stepper (wizard) | `Click Next`/`Back` at step `<n>` | Current step = `<n>` |

**F. Overlay / Popup**

| Element | Hành động chuẩn (Steps) | Trạng thái/Kết quả chuẩn (Expected Result) |
|---|---|---|
| Modal / Dialog | `Open modal <Label>` ; `Close modal` (`Click "X"` / `Click outside modal` / `Press Esc`) | Modal `Displayed`/`Closed` |
| Tooltip | `Hover over <element>` | Tooltip `<content>` displayed |
| Popover / Context menu | `Right-click <element>` | Context menu displayed |

**G. Data Table**

| Element | Hành động chuẩn (Steps) | Trạng thái/Kết quả chuẩn (Expected Result) |
|---|---|---|
| Table row | `Select row <n>` (qua checkbox/click) | Row `Selected`/`Highlighted` |
| Column sort | `Click column header <Label>` | Sorted `Ascending`/`Descending` |
| Expandable row (tree table) | `Expand`/`Collapse row <n>` | Row `Expanded`/`Collapsed` |

**H. File & Drag-Drop**

| Element | Hành động chuẩn (Steps) | Trạng thái/Kết quả chuẩn (Expected Result) |
|---|---|---|
| File upload | `Select file <filename>` ; `Drag and drop file <filename> into upload area` | File `Uploaded`, filename displayed |
| Drag & Drop (general) | `Drag <item> and drop into <target>` | `<item>` moved to `<target>` |

**I. Feedback / Status**

| Element | Hành động chuẩn (Steps) | Trạng thái/Kết quả chuẩn (Expected Result) |
|---|---|---|
| Progress bar | `Observe progress bar` | Progress = `<n>%` |
| Tag / Chip | `Click "x" on tag <Label>` | Tag `Removed` |
| Toast / Snackbar / Notification | `Observe notification` | Notification `<content>` displayed then `Auto-dismissed` |

**J. Thao tác chuột/bàn phím chung (áp dụng cho mọi element ở trên khi cần)**

| Thao tác | Hành động chuẩn (Steps) |
|---|---|
| Di chuột vào | `Hover over <element>` |
| Cuộn trang | `Scroll to <element/section>` |
| Nhấp đúp | `Double-click <element>` |
| Nhấp chuột phải | `Right-click <element>` |
| Focus vào field | `Focus into <field>` |
| Rời khỏi field (blur) | `Click outside <field>` (blur) |
| Nhấn phím | `Press <key>` (vd `Press Enter`, `Press Esc`) |
| Để trống field | `Leave <field> empty` |
| Mở một màn hình | `Open screen <Tên màn hình>` (qua menu: `Click menu item <Label>`; qua URL: `Enter URL <path> into address bar`) |
| Quan sát kết quả | `Observe <element/section>` |

## 3. Thuật ngữ IT — giữ tiếng Anh, cấm dịch

Đội Dev / Tester dùng các từ dưới đây bằng tiếng Anh hằng ngày. Dịch sang tiếng Việt làm câu khó đối chiếu với code, màn hình và ticket.

| ❌ Không viết | ✅ Viết |
| :--- | :--- |
| bấm / nhấn / ấn (nút) | click (button) |
| nhập / gõ / điền (vào ô) | enter … into (field) |
| ô nhập, ô, trường nhập liệu | field (text input) |
| nút | button |
| tích chọn / bỏ tích | check / uncheck |
| chọn tay | select manual |
| ô chọn nhiều | multi-select dropdown |
| hộp xác nhận | confirm dialog |
| hộp, cửa sổ bật lên | modal / popup |
| thông báo góc màn hình | toast |
| khung lỗi đầu màn hình | error alert |
| câu lỗi dưới ô | inline error message |
| rời ô | blur (`Click outside <field>`) |
| kéo thả | drag and drop |
| di chuột vào | hover over |
| chuyển sang trang / chuyển hướng | redirect to |
| máy chủ | server |
| bộ nhớ đệm | cache |
| phân trang | pagination |
| sắp xếp | sort |
| lọc | filter |
| kiểm tra dữ liệu đầu vào | validate |
| bắt buộc nhập | required |
| độ dài tối đa | max length |
| tải lên / tải về | upload / download |
| đăng nhập / đăng xuất (thao tác) | login / logout |
| phiên đăng nhập | session |
| menu bên trái | sidebar |
| bật / tắt (hiển thị) | Displayed / Hidden |
| khóa / mở (nút) | Disabled / Enabled |

Từ trong bảng là từ IT chung. Thuật ngữ nghiệp vụ của dự án (`buyer`, `group`, `product`, tên phân hệ, tên menu) vẫn theo `domain-terminology.md` và `AK-Docs/00.Project-Overview/Glossary.md`. Dự án muốn dùng từ khác cho một dòng → ghi vào Glossary; Glossary thắng bảng này.

## 4. Ghép với nhãn tiếng Nhật

Mẫu câu: `<Actor> <động từ chuẩn> <loại control> <nhãn gốc> (<tên gọi>)`. Nhãn gốc chép nguyên văn từ màn hình; tên gọi lấy từ Glossary và chỉ kèm ở lần đầu của mỗi đơn vị đọc (`domain-terminology.md`).

- ✅ `admin click menu item 「グループ管理」 (Quản lý group) ở sidebar của Supplier site`
- ✅ `admin enter "ABC" into field 「グループコード」 (mã group)`
- ✅ `Hệ thống hiển thị toast 「登録完了しました。」 (Đã đăng ký xong.) và redirect to danh sách group`
- ❌ `admin bấm nút 「登録」` · ❌ `admin nhấn Đăng ký` · ❌ `hệ thống chuyển sang trang danh sách`

## 5. Tự kiểm tra trước khi đóng gate

```bash
grep -niE "bấm|nhấn nút|ấn nút|tích chọn|bỏ tích|chọn tay|gõ vào|điền vào|ô nhập|hộp xác nhận|thông báo góc|khung lỗi|rời ô|kéo thả|di chuột|máy chủ|bộ nhớ đệm|chuyển hướng" <file>.md
```

Mỗi hit nằm ngoài chữ gốc trích nguyên văn → viết lại theo mục 2 và mục 3.
