# Thuật ngữ nghiệp vụ — Dùng đúng từ hệ thống đang dùng

> File này là quy tắc dùng chung cho **tất cả** skill sinh nội dung người khác đọc: câu hỏi Q&A, tài liệu phân tích, UC Spec, test case, report, bug report. Đọc file này cùng với `output-language.md` — file kia chọn **ngôn ngữ**, file này chọn **từ vựng**.

## Vấn đề file này giải quyết

Quy tắc "viết cho người không chuyên kỹ thuật" bị áp quá tay: AI dịch luôn cả thuật ngữ nghiệp vụ mà hệ thống và cả đội đang dùng hằng ngày (`group` → "nhóm", `buyer` → "cửa hàng", `import` → "nhập", `server` → "máy chủ"). Người đọc là PM, khách hàng, tester — họ dùng `group`, `buyer`, `import` mỗi ngày trong ticket, trong màn hình, trong hội thoại. Bản dịch tiếng Việt làm họ phải dịch ngược lại trong đầu, và tệ hơn là làm tài liệu không khớp với màn hình thật.

Quy tắc đúng không phải "dịch hết" hay "giữ hết", mà là **phân biệt hai loại từ**.

## Quy tắc

| Loại từ | Xử lý | Ví dụ |
| :--- | :--- | :--- |
| **Thuật ngữ nghiệp vụ hệ thống đang dùng** — xuất hiện trên màn hình, trong ticket, trong hội thoại của đội | **Giữ nguyên, bắt buộc.** Cấm dịch | `group`, `buyer`, `shop`, `product`, `import`, `export`, `admin`, `order`, `cart` |
| **Thuật ngữ viết bằng chữ người đọc không đọc được** — nhãn tiếng Nhật (kana/kanji) khi output là tiếng Việt/tiếng Anh | Dùng **tên gọi trong Glossary**, kèm chữ gốc trong ngoặc ở lần đầu — xem mục [Thuật ngữ tiếng Nhật](#thuật-ngữ-tiếng-nhật--và-chữ-người-đọc-không-đọc-được) | `サプライヤー` → nhà cung cấp (サプライヤー); `得意先一覧` → danh sách `buyer` (得意先一覧) |
| **Tên kỹ thuật nội bộ** — chỉ có trong mã nguồn | **Vẫn cấm** xuất hiện trong phần Bối cảnh / Câu hỏi / Options | tên bảng, tên cột, tên hàm, tên biến, đường dẫn API, tên file |
| **Từ viết tắt / thuật ngữ nội bộ** | Giữ nguyên + giải nghĩa ngắn **ngay lần đầu xuất hiện** | `BR (Business Rule — quy tắc nghiệp vụ)`, `UC (Use Case)` |
| **Từ phổ thông** — liên từ, câu dẫn | Dịch sang ngôn ngữ output bình thường. Động từ thao tác UI và thuật ngữ IT thì **không** dịch — theo `custom/rules/ui-action-wording.md` | "nếu để trống thì", "sau khi lưu xong" |

Cần nêu một tên kỹ thuật để Dev khỏi hiểu nhầm → đặt trong ngoặc ở **cuối** câu, sau phần diễn đạt nghiệp vụ, không đặt trong câu hỏi.

## Thuật ngữ tiếng Nhật — và chữ người đọc không đọc được

Áp dụng cho **mọi output** (câu hỏi Q&A, Analysis, UC Spec, System Requirement, test case, Dev Checklist, report, bug report, tài liệu Dev). Người đọc gồm Dev/tester không biết tiếng Nhật. Giữ nguyên `サプライヤー`, `得意先一覧`, `グループ管理`, `公開` trong câu tiếng Việt buộc họ phải đi dịch. Ví dụ thật: *"mỗi サプライヤー chỉ thấy và quản lý product của mình trên Cổng nhà cung cấp"* — cùng một khái niệm, chỗ dịch, chỗ giữ chữ Nhật.

Quy tắc "giữ nguyên, cấm dịch" ở bảng trên vẫn đúng cho từ dự án viết bằng chữ Latin (`group`, `buyer`, `product`) — cả đội đọc được. Với chữ người đọc không đọc được, xử lý theo thứ tự:

1. **Glossary đã có từ dự án dạng Latin cho khái niệm đó → dùng từ đó.** `得意先` đã có `buyer` → viết "danh sách `buyer` (得意先一覧)", không viết "danh sách khách hàng".
2. **Không có từ Latin → dùng cột `Viết trong tài liệu` của Glossary**, kèm chữ gốc trong ngoặc ở **lần đầu xuất hiện trong mỗi đơn vị đọc độc lập**: một khối câu hỏi, một test case, một bug report, một mục cấp 2 của tài liệu. Từ lần thứ hai trong cùng đơn vị → chỉ viết tên gọi. Ví dụ: "nhà cung cấp (サプライヤー)", sau đó "nhà cung cấp".
3. **Glossary chưa có → hỏi user** theo Bước 4 bên dưới. AI được **đề xuất** một tên gọi để user xác nhận, rồi ghi ngược vào Glossary. Cấm tự dịch rồi dùng luôn — mỗi câu dịch một kiểu chính là lỗi mà quy tắc "cấm dịch" chặn.

**Thứ tự trong ngoặc theo mục đích của câu:**

| Mục đích | Cách viết | Ví dụ |
| :--- | :--- | :--- |
| Mô tả khái niệm, vai trò, màn hình | **Tên gọi (chữ gốc)** | "màn hình Quản lý `group` (グループ管理)", "nhà cung cấp (サプライヤー)" |
| Người đọc phải **khớp đúng chữ trên màn hình** — bước test click button / click menu item, nội dung thông báo mong đợi, nhãn cần kiểm tra | **Chữ gốc (tên gọi)** | "Click button 保存 (Lưu)", "Hiển thị thông báo 「登録しました」 (Đã đăng ký)" |

Nội dung chữ gốc phải **chép nguyên văn** từ màn hình/mã nguồn — không sửa, không rút gọn — để tester tìm đúng trên màn hình.

Không áp dụng khi ngôn ngữ output chính là tiếng Nhật (xem `custom/rules/output-language.md`) — khi đó viết chữ Nhật bình thường.

## Glossary dự án — một file duy nhất trong AK-Docs

Glossary là **một file dùng chung cho toàn dự án**, không phải bảng riêng của từng functionId:

```
AK-Docs/00.Project-Overview/Glossary.md
```

### Bước 1 — Đọc Glossary trước khi viết câu đầu tiên

Chạy **một lần** ở đầu Gate 1, **trước khi** soạn câu hỏi hoặc tài liệu đầu tiên.

- **File đã tồn tại** → đọc hết, dùng làm từ điển bắt buộc cho cả phiên. Mọi thuật ngữ nghiệp vụ trong output lấy từ file này, không tự dịch, không tự đặt từ mới.
- **File chưa tồn tại** → **hỏi user xác nhận trước khi tạo**, không tự tạo im lặng:

```
Dự án chưa có AK-Docs/00.Project-Overview/Glossary.md.
Tôi tạo file này và điền các thuật ngữ quét được từ ticket / màn hình / mã nguồn — đồng ý không? (Có / Không)
```

  User đồng ý → tạo file theo mẫu bảng ở Bước 3. User từ chối → đặt bảng Glossary trong tài liệu phân tích của functionId này, và không hỏi lại trong cùng phiên.

### Bước 2 — Quét nguồn để điền

Thứ tự ưu tiên:

1. Tiêu đề và mô tả ticket (cả bản gốc tiếng Nhật/tiếng Anh nếu có — từ gốc thường nằm ở đó).
2. Tài liệu trong `AK-Docs/` của dự án — UC Spec, biên bản, QnA-Log các version trước.
3. Nhãn hiển thị trên màn hình trong mã nguồn frontend (file i18n, text trên nút và tiêu đề).
4. Tên khái niệm trong mã nguồn backend (entity, service, enum) — chỉ dùng khi ba nguồn trên không có.

### Bước 3 — Mẫu bảng

**Cột Nguồn viết bằng ngôn ngữ nghiệp vụ** — tên màn hình, nhãn nút, tên tài liệu, số hiệu ticket. `file:line` không đưa vào bảng này: Glossary là thứ người đọc tra khi không hiểu một từ, mở ra gặp đường dẫn mã nguồn thì phản tác dụng. Cần dẫn mã nguồn thì ghi ở phần hồ sơ truy vết.

Cột **`Viết trong tài liệu`** là tên gọi dùng trong output. Với từ Latin cả đội đang dùng thì trùng với cột Thuật ngữ. Với từ tiếng Nhật thì là từ dự án dạng Latin (nếu có) hoặc tên gọi tiếng Việt/tiếng Anh đã được user xác nhận — xem mục [Thuật ngữ tiếng Nhật](#thuật-ngữ-tiếng-nhật--và-chữ-người-đọc-không-đọc-được).

| Thuật ngữ | Viết trong tài liệu | Nghĩa | Nguồn |
| :--- | :--- | :--- | :--- |
| `group` | `group` | Nhóm khách hàng, quyết định khách nào thấy hàng nào | Ticket PROJ-123; màn hình `グループ管理` |
| `buyer` | `buyer` | Khách hàng đã đăng nhập | Màn hình quản trị `得意先`. Hệ thống tham chiếu gọi là `shop` — cùng một đối tượng |
| `得意先一覧` | danh sách `buyer` | Màn hình liệt kê mọi `buyer` | Menu quản trị |
| `サプライヤー` | nhà cung cấp | Doanh nghiệp đăng `product` lên Cổng nhà cung cấp | Màn hình Cổng nhà cung cấp |

Glossary cũ chưa có cột `Viết trong tài liệu` → thêm cột khi gặp từ đầu tiên cần dùng nó. Dòng Latin điền trùng cột Thuật ngữ; dòng tiếng Nhật thì hỏi user xác nhận tên gọi trước khi điền.

Một khái niệm có **hai tên** ở hai hệ thống → ghi cả hai vào bảng, rồi chọn **một** tên dùng xuyên suốt tài liệu, không xoay vòng.

### Bước 4 — Gặp từ chưa có trong Glossary khi đang làm → hỏi, rồi ghi ngược vào file

Đang viết câu hỏi / tài liệu mà gặp một khái niệm nghiệp vụ **không có** trong Glossary và **không tìm được** từ tương ứng ở cả 4 nguồn Bước 2 → **hỏi user ngay, không tự đặt từ và không tự dịch**:

```
Tôi chưa tìm được thuật ngữ dự án đang dùng cho "<mô tả khái niệm bằng một cụm ngắn>"
(thấy ở: <màn hình / ticket / mã nguồn>). Dự án gọi nó là gì?
```

User trả lời → làm **cả hai** việc, trong cùng lượt:

1. Dùng đúng từ đó trong tài liệu đang viết.
2. **Thêm ngay một dòng vào `AK-Docs/00.Project-Overview/Glossary.md`** (Thuật ngữ | Viết trong tài liệu | Nghĩa | Nguồn = "User xác nhận <dd/mm/yyyy>; <màn hình/ticket>"). Không để dồn tới cuối gate.

Glossary là tài liệu sống: mỗi lần user đính chính một từ cũng cập nhật lại dòng tương ứng, không tạo dòng thứ hai cho cùng khái niệm.

## Quy tắc một từ một nghĩa

Chọn xong thì giữ nguyên trong toàn bộ tài liệu và các version sau. Cấm dùng từ đồng nghĩa cho cùng một khái niệm ("group" ở mục này, "nhóm" ở mục kia) — người đọc sẽ tưởng là hai thứ khác nhau.

## Dùng lại đúng từ của tài liệu trước trong cùng functionId

Các tài liệu của một functionId nối tiếp nhau: Analysis → QnA-Log → UI Prototype → UC Spec → System Requirement → test case. Người đọc tài liệu sau đã đọc tài liệu trước. Đổi từ giữa hai tài liệu (QnA-Log viết `buyer`, UC Spec viết "khách hàng") làm họ tưởng là hai khái niệm khác nhau.

- **Trước khi viết** tài liệu sau: lập danh sách danh từ nghiệp vụ trong QnA-Log và Analysis đã chốt — actor, phân hệ, menu, màn hình, trạng thái, nút. Đối chiếu từng từ với Glossary. Tài liệu mới dùng đúng danh sách đó.
- **Từ mới** chưa có ở tài liệu trước và chưa có trong Glossary → xử lý theo Bước 4 (hỏi user), không tự đặt.
- **Sau khi viết**: grep tài liệu mới tìm các từ phổ thông hay bị tự đặt thay cho từ dự án — `cửa hàng`, `khách hàng`, `người mua`, `nhà cung cấp`, `trang quản trị`, `cổng`, `nhóm`, `sản phẩm`, `giỏ hàng`, `nhập`, `xuất`. Mỗi hit phải là từ có trong cột `Viết trong tài liệu` của Glossary; không có → thay bằng từ trong Glossary hoặc hỏi user.

## Tên phân hệ, menu, khu vực màn hình cũng là thuật ngữ

Tên các phần của hệ thống — trang quản trị, trang mua hàng, tên menu, tên khu vực trên màn hình — là thuật ngữ giống `group`, `buyer`. Lấy từ Glossary (hoặc từ tài liệu tổng quan dự án như Function List), không tự đặt một cụm tiếng Việt chung chung.

Ví dụ lỗi thật (UC Spec WONDER-1156, 2026-10-08):

| ❌ Tự đặt | Vì sao sai |
| :--- | :--- |
| "cửa hàng" để chỉ trang mua hàng | Không có trong Glossary, và trùng bản dịch cấm của `buyer` / `shop` — người đọc không biết là trang mua hàng hay là `buyer` |
| "3.1. Menu Cổng nhà cung cấp" | Người đọc không biết đó là menu nào, ở màn hình nào; "Cổng nhà cung cấp" không phải tên đội dùng hằng ngày |

Cách viết đúng: dùng tên phân hệ đội đang dùng (theo Glossary / Function List), và chỉ rõ vị trí trên màn hình — ví dụ "menu bên trái của <tên phân hệ trong Glossary>". Glossary chưa có tên phân hệ → hỏi user theo Bước 4 trước khi viết.

## Cấm dịch tên kỹ thuật thành thuật ngữ

Một tên trong mã nguồn mà dự án **không** dùng khi nói chuyện thì không phải thuật ngữ nghiệp vụ — và cũng không được dịch ra để dùng như thuật ngữ. Dịch `sceneCarts` thành "giỏ theo không gian" tạo ra một từ không ai hiểu, không tra được ở đâu, và không có trong màn hình.

Xử lý đúng: tìm **nhãn thật trên màn hình** của chức năng đó và dùng nhãn ấy; không tìm được thì mô tả bằng một cụm nghiệp vụ ngắn kèm chú thích tên kỹ thuật ở phần truy vết, và đưa vào Glossary trước khi dùng.

**Mọi danh từ chức năng xuất hiện trong phần người ngoài đọc đều phải có trong Glossary** hoặc được giải nghĩa ngay tại chỗ.

## Self-check trước khi gửi

- [ ] Đã đọc `AK-Docs/00.Project-Overview/Glossary.md` trước khi viết câu đầu tiên? (chưa có file → đã hỏi user xác nhận tạo mới, không tự tạo)
- [ ] Mọi thuật ngữ nghiệp vụ trong tài liệu đều lấy từ Glossary, không có từ nào tự dịch?
- [ ] Mọi từ user vừa cung cấp trong phiên này đã được ghi ngược vào `Glossary.md` ngay, không để dồn?
- [ ] Không có tên bảng / cột / hàm / API nào lọt vào phần Bối cảnh, Câu hỏi hay Options?
- [ ] Mỗi khái niệm chỉ dùng đúng một từ xuyên suốt?
- [ ] Cột Nguồn của Glossary viết bằng ngôn ngữ nghiệp vụ, không có `file:line`?
- [ ] Không có tên kỹ thuật nào bị dịch ra tiếng Việt rồi dùng như thuật ngữ?
- [ ] Không còn chữ tiếng Nhật đứng một mình trong câu tiếng Việt/tiếng Anh? Mỗi thuật ngữ tiếng Nhật đã viết bằng tên gọi trong Glossary, kèm chữ gốc trong ngoặc ở lần đầu của mỗi đơn vị đọc?
- [ ] Chỗ người đọc phải khớp chữ trên màn hình (bước test, thông báo mong đợi) đã viết chữ gốc trước, tên gọi trong ngoặc, chữ gốc chép nguyên văn?
- [ ] Cùng một từ tiếng Nhật chỉ có một tên gọi trong toàn tài liệu, đúng như cột `Viết trong tài liệu`?
- [ ] Tài liệu sau (UC Spec, System Requirement, test case) dùng đúng từ QnA-Log / Analysis của cùng functionId đã dùng — không đổi sang từ đồng nghĩa?
- [ ] Tên phân hệ, menu, khu vực màn hình lấy từ Glossary, không tự đặt ("cửa hàng", "cổng", "trang quản trị")? Đã grep các từ phổ thông hay bị tự đặt và mỗi hit đều có trong cột `Viết trong tài liệu`?
