# Chuẩn diễn đạt tài liệu (Document Wording) — dùng chung mọi tài liệu sinh ra

> File này là quy tắc dùng chung cho **tất cả** skill sinh tài liệu nghiệp vụ: UC Spec, System Requirement, Test Case / checklist, Test Report, Bug Report.
> Skill sinh hoặc sửa các tài liệu trên PHẢI đọc file này trước khi viết.
> Bổ sung cho `custom/rules/output-language.md` (chọn ngôn ngữ) — file này quy định **cách hành văn** trong ngôn ngữ đã chọn. Động từ thao tác UI và thuật ngữ IT: `custom/rules/ui-action-wording.md`.
> Nguồn: review comment của khách hàng/Reviewer (2026-09-21) về từ ngữ khó hiểu và nội dung phải tra chéo mới hiểu.

---

## 1. Hành văn tự nhiên — không để lại dấu vết dịch máy

Câu phải đọc như người bản ngữ viết trực tiếp, không phải dịch từng chữ từ một mẫu tiếng Anh.
Lỗi hay gặp nhất: dịch "Try to ..." thành "Cố ..." / "Cố gắng ...".

### 1.1. Từ cấm và cách viết đúng (output tiếng Việt)

| ❌ Sai (dịch máy / thừa từ) | ✅ Đúng |
| :--- | :--- |
| `Cố mở màn hình 「ダッシュボード」` | `Open screen 「ダッシュボード」` |
| `Thử mở màn hình chỉnh sửa` | `Open screen chỉnh sửa` |
| `Cố gắng nhập chữ cái vào ô Số lượng` | `Enter chữ cái into field Số lượng` |
| `Cố gắng submit form` | `Click button Lưu` |
| `Tiến hành thực hiện việc nhập dữ liệu` | `Enter dữ liệu into field <tên field>` |
| `Thực hiện click vào nút Xóa` | `Click button Xóa` |
| `Màn hình được hiển thị bởi hệ thống` | `Hệ thống hiển thị màn hình` |
| `Dữ liệu sẽ không được lưu lại bởi hệ thống` | `Hệ thống không lưu dữ liệu` |
| `Kiểm tra xem hệ thống có chặn hay không` | `Kiểm tra hệ thống chặn ...` |

### 1.2. Nguyên tắc

- **Steps là câu mệnh lệnh**, động từ hành động đứng đầu: `Open screen ...`, `Enter ... into ...`, `Click button ...`, `Select ...`, `Observe ...`. Bộ động từ và thuật ngữ IT chuẩn: `custom/rules/ui-action-wording.md`.
- **Không thêm động từ ý định** (`cố`, `cố gắng`, `thử`, `định`, `muốn`) trước động từ hành động. Việc hệ thống chặn hay không là **Expected Result**, không phải sắc thái của động từ trong Steps.
  - ❌ `1. Cố mở màn hình 「ダッシュボード」 khi chưa đăng nhập.` → `Hệ thống không cho vào.`
  - ✅ `1. Open screen 「ダッシュボード」 (Client TOP).` → Expected: `Hệ thống không cho vào 「ダッシュボード」 và chuyển về màn hình đăng nhập Client.`
- **Không dùng từ đệm thừa**: `tiến hành`, `thực hiện việc`, `việc ... được`, `một cách`, `có thể sẽ`.
- **Ưu tiên câu chủ động**, chủ ngữ rõ ràng (`Hệ thống ...`, `Người dùng ...`), bỏ cấu trúc bị động dịch từ tiếng Anh (`được ... bởi ...`).
- **Một câu một hành động**. Câu dài quá ~25 từ → tách thành 2 câu hoặc 2 bước.
- **Không dùng từ mơ hồ**: `hoạt động đúng`, `OK`, `bình thường`, `như mong đợi`, `hợp lý`. Phải nêu hiện tượng quan sát được.
- **Thống nhất 1 động từ cho 1 hành động** xuyên suốt cả tài liệu (chỉ dùng `Click button Lưu` theo `custom/rules/ui-action-wording.md`; không dùng `Bấm nút Lưu` / `Nhấn Lưu`).
- Output tiếng Anh: cùng nguyên tắc — bỏ `Try to ...`, `Attempt to ...`, `Proceed to ...`; viết thẳng `Open ...`, `Enter ...`, `Click ...`.

### 1.3. Tự kiểm tra trước khi nộp tài liệu

```bash
grep -nE "Cố |Cố gắng|Thử (mở|nhập|bấm|click)|Tiến hành|thực hiện việc|được .* bởi|Try to |Attempt to " <file>.md
```
Có hit → sửa lại theo bảng ở mục 1.1 trước khi đóng gate.

---

## 2. Mỗi mục/ô phải tự chứa đủ nội dung — không tham chiếu ra ngoài

Người đọc chỉ đọc **1 mục** (1 FR/VR/AT của System Requirement, 1 dòng test case, thậm chí 1 ô của dòng đó) là phải hiểu trọn vẹn, **không phải mở tài liệu khác, case khác, hay mục khác** mới hiểu.

### 2.1. Ba loại tham chiếu bị cấm

1. **Tham chiếu sang tài liệu khác** — SRS, UC Spec, System Requirement, mail template, ticket, file thiết kế; bằng số mục hoặc bằng mã.
   - ❌ `Banner = copy KH mục 8`, `Mail body = câu team BR2.10`, `xem SRS §3.2`, `theo mẫu mail no-recommended-connet-fair`, `đúng như design`.
   - ✅ Chép **nguyên văn nội dung thật** (câu thông báo, subject, cấu trúc block cần đối chiếu) vào ngay ô/mục đang viết.
2. **Tham chiếu sang case/mục khác trong cùng tài liệu**.
   - ❌ `Mail đã gửi theo TC-WSA-030`, `như No.1`, `như trên`, `giống case trước`, `câu ①`, `xem mục 5`.
   - ✅ Viết lại đủ điều kiện/nội dung cần thiết ngay tại chỗ.
3. **Tham chiếu sang mục dữ liệu dùng chung / chú giải đầu tài liệu** (Test Data chung, PRE-COMMON, bảng mã ①②③, mã đối tượng tự đặt).
   - ❌ `Dùng cơ sở F-711-A`.
   - ✅ `Cơ sở dịch vụ 通所介護, mã cơ sở 1234567890, đã nộp file M`.

### 2.2. Mã trace được phép nằm ở đâu

- Mã trace (`BR-xx`, `FR-xx`, `VR-xx`, ticket ID, TC ID) chỉ đặt ở **cột/field trace riêng** (`Ticket ID`, `Comment`, `Requirement Coverage`, `Traceability Matrix`), hoặc trong ngoặc ở **cuối câu, sau khi nội dung đã đủ**.
- **Phép thử**: che hết mã trace đi — câu vẫn hiểu trọn vẹn → đạt. Che xong không hiểu nữa → đang cross-reference, phải viết lại.
- **Trong UC Spec / System Requirement**, mã nội bộ (`BR2.10`, `FR-01`, `VR-03`) là công cụ liên kết hợp lệ giữa các mục — được dùng, nhưng **luôn kèm 1 cụm mô tả nội dung ngay tại chỗ**, không để mã trần.
  - ❌ `Hệ thống gửi mail theo BR2.10.`
  - ✅ `Hệ thống gửi mail có nội dung thông báo chưa đăng ký 勤務・稼働予定 và không chứa URL (BR2.10).`
- **Trong Test Case**, mã của tài liệu khác không được thay cho nội dung: Tester không mở SRS/UC Spec khi chạy test → chép nguyên văn nội dung vào ô.
  - ❌ `Mail body = câu team BR2.10 (không URL).`
  - ✅ `Mail body hiển thị nguyên văn: "勤務・稼働予定が未登録の施設があります。..." và không chứa URL nào (BR2.10).`

### 2.3. Chấp nhận trùng lặp

Lặp nội dung giữa nhiều case/mục là **chấp nhận được và bắt buộc** khi cần — đổi lấy khả năng đọc độc lập từng dòng. Không được rút gọn bằng cách trỏ sang chỗ khác.

### 2.4. Ví dụ sửa (lấy từ review thật)

**Pre-condition**

- ❌ `Mail đã gửi theo TC-WSA-030`
- ✅ `1. Client bật thiết lập use_ppat_photo = はい.<br>2. Có dữ liệu 開催日 Plan tháng 3–6 thiếu shift.<br>3. Job gửi mail 勤務・稼働予定未登録 đã chạy và mail đã gửi tới hội trưởng của client này.`

**Expected Result**

- ❌ `Banner = copy KH mục 8 + có link workShift. Mail body = câu team BR2.10 (không URL) — hai kênh không lẫn.`
- ✅ `1. Banner hiển thị nguyên văn: "勤務・稼働予定が未登録です。..." kèm link mở màn hình 勤務・稼働予定管理.<br>2. Mail body hiển thị nguyên văn: "..." và không chứa URL/đường link nào.<br>3. Nội dung banner và nội dung mail không lẫn sang nhau.`

### 2.5. Tự kiểm tra trước khi nộp tài liệu

```bash
grep -nE "như trên|như No\.|giống case|theo TC[-_]|xem (mục|phần|SRS|UC|spec)|mục [0-9]+|câu [①②③]|BR ?[0-9]" <file>.md
```
Có hit → kiểm tra từng chỗ: nếu bỏ tham chiếu đi mà câu không còn đủ nghĩa → viết bổ sung nội dung đầy đủ vào tại chỗ.

---

## 3. Viết cho người đọc nghiệp vụ — chi tiết kỹ thuật đi kèm làm bằng chứng

> Nguồn: review artifact Gate 1 của `create-testcase` (U04 Transfer Token, 2026-09-30). Tester/BA/PM đọc bản phân tích yêu cầu thấy `TokenTransferService::assertNotSelfTransfer()`, `WalletTransferModal.vue:244 sendEmailCode: true`, `/^0x[a-fA-F0-9]{40}$/`, `wallet_asset_activities.activity_status`, `PENDING(0)` — không hiểu, không kiểm chứng được. Áp dụng cho **mọi** tài liệu sinh ra: UC Spec, System Requirement, Test Plan, QnA Log, Test Case, Review Result, Test Report.

### 3.1. Nguyên tắc 2 phần: câu nghiệp vụ trước, bằng chứng source sau

Không xoá chi tiết kỹ thuật — chi tiết đó là **bằng chứng** để tester nhờ Dev kiểm lại hoặc tự thao tác trên màn hình xác nhận đúng/sai. Nhưng nó không được thay chỗ cho câu nghiệp vụ.

- **Câu nghiệp vụ** đứng trước, tự đủ nghĩa: che hết phần kỹ thuật đi vẫn hiểu trọn vẹn và vẫn kiểm chứng được bằng thao tác trên màn hình.
- **Dòng bằng chứng** đứng ngay dưới, mở đầu bằng `Source code:` (hoặc `Bằng chứng:`). Chứa đúng vị trí trong source: file, dòng, tên class/method, tên bảng/cột, regex gốc, config key.
- Trong bảng: thêm **một cột riêng** tên `Source code` / `Bằng chứng`. Thân các cột khác giữ ngôn ngữ nghiệp vụ.

```markdown
Màn hình Transfer hiện tại mặc định **đã tích sẵn** ô "gửi mã xác thực qua email".
Source code: FE `itsol_resourcemng/src/js/modules/wallet/components/WalletTransferModal.vue:244` — `sendEmailCode: true`
```

- ❌ `code FE (WalletTransferModal.vue:244 sendEmailCode: true) mặc định Checked` — câu nghiệp vụ không tồn tại, người đọc phải tự dịch.
- ❌ Câu nghiệp vụ đúng nhưng **không có** dòng bằng chứng, trong khi kết luận lấy từ source → tester không có cách kiểm lại, phải tin AI.

### 3.2. Bảng quy đổi sang ngôn ngữ nghiệp vụ

| Loại | ❌ Chỉ ghi kỹ thuật | ✅ Câu nghiệp vụ + bằng chứng |
| :--- | :--- | :--- |
| Class / method | `TokenTransferService::assertNotSelfTransfer() luôn từ chối` | `Hệ thống luôn từ chối khi địa chỉ nhận trùng ví của chính người gửi.`<br>`Source code: BE TokenTransferService::assertNotSelfTransfer()` |
| Hàm test tự động | `có testStoreRejectsSendingToOwnWalletThroughRealValidation` | `Đội Dev đã có kiểm thử tự động cho hành vi này — đây là hành vi cố ý, không phải lỗi.`<br>`Source code: testStoreRejectsSendingToOwnWalletThroughRealValidation` |
| Bảng / cột DB | `tạo transfer_requests (PENDING) + wallet_asset_activities (PENDING)` | `Hệ thống ghi nhận 1 yêu cầu chuyển tiền và 1 dòng lịch sử ví, cả hai ở trạng thái "Đang xử lý".`<br>`Source code: bảng transfer_requests.status, wallet_asset_activities.activity_status` |
| Regex | `khớp /^0x[a-fA-F0-9]{40}$/` | `Bắt đầu bằng "0x", theo sau đúng 40 ký tự trong khoảng 0-9 và a-f, chấp nhận cả chữ hoa.`<br>`Source code: /^0x[a-fA-F0-9]{40}$/` |
| Config key | `TTL 5 phút (aube_stake.wallet_transfer_verify_ttl_minutes)` | `Mã xác thực hết hạn sau 5 phút; giá trị này đổi được theo môi trường.`<br>`Source code: config aube_stake.wallet_transfer_verify_ttl_minutes` |
| Enum kèm số | `PENDING(0) → SENDING(1) → COMPLETED(2)` | `Đang xử lý → Đang gửi lên blockchain → Hoàn tất.`<br>`Source code: status 0 / 1 / 2` |
| Hàng đợi nền | `enqueue blockchain_service_jobs (outbox)` | `Yêu cầu được xếp vào hàng đợi gửi lên blockchain, hệ thống xử lý nền.`<br>`Source code: bảng blockchain_service_jobs, ProcessBlockchainServiceJobsOutboxCommand` |
| Khoá dữ liệu | `có lockForUpdate theo thứ tự wallet → transfer_requests` | `Hệ thống khoá số dư trong lúc xử lý để 2 giao dịch gửi cùng lúc không cùng tiêu một khoản tiền.`<br>`Source code: lockForUpdate (wallet → transfer_requests)` |
| Chữ ký webhook | `xác thực keccak256 hash + secret, trả {"result":1} để ack` | `Thông báo từ blockchain phải có chữ ký hợp lệ; hệ thống phải phản hồi xác nhận, nếu không bên gửi sẽ gửi lại.`<br>`Source code: PublicChainWebhookController, keccak256 + secret, response {"result":1}` |
| Endpoint | `POST /token-transfers-v2` | `Click button "Gửi" ở bước xác nhận khi đang bật xác thực email.`<br>`Source code: POST /api/app/user-wallet/token-transfers-v2` |

Giữ nguyên trong câu nghiệp vụ (là dữ liệu tester đối chiếu trực tiếp trên màn hình hoặc trong phản hồi API): mã lỗi hiển thị (`SELF_TRANSFER_NOT_ALLOWED`, `INSUFFICIENT_ETH_FOR_GAS`), tên token/tiền tệ, địa chỉ ví `0x...`, `tx_hash`, tên nút/nhãn/màn hình thật, giá trị giới hạn (5 phút, 8 chữ số thập phân).

### 3.3. Mọi kết luận lấy từ source phải có bằng chứng

Mục nào đánh dấu `[từ code]` — hoặc nói "code thực tế", "theo code hiện tại" — bắt buộc có dòng/cột bằng chứng đi kèm. Không có bằng chứng thì tester không kiểm lại được và kết luận đó không dùng được để viết Expected Result.

### 3.4. Tự kiểm tra trước khi nộp tài liệu

```bash
ak tc lint --doc <file>.md
```
Linter báo lỗi khi tên class/method, `file.ext:dòng`, tên hàm test, regex hoặc enum kèm số nội bộ nằm trong câu nghiệp vụ mà không phải dòng/cột bằng chứng; báo cảnh báo khi một kết luận `[từ code]` không có bằng chứng nào đi kèm.

---

## 4. Cách trích dẫn quy tắc này trong một SKILL.md

Thêm 1 dòng ngay gần bước sinh nội dung tài liệu:

```
Chuẩn diễn đạt: xem `custom/rules/document-wording.md` — hành văn tự nhiên (không "cố/thử/tiến hành"),
mỗi mục tự chứa đủ nội dung, không tham chiếu sang tài liệu/case/mục khác.
```
