# Quy ước chung (SETTING) — Flow tạo testcase

> File này là "cấu hình" dùng chung cho **tất cả** các skill trong flow.
> Mọi skill PHẢI đọc file này trước khi chạy để giữ output nhất quán.
> Khi muốn đổi phong cách/quy tắc cho cả flow → chỉ sửa file này.

---

## 1. Ngôn ngữ & văn phong

- Ngôn ngữ nội dung mô tả/diễn giải **auto-detect theo ngôn ngữ của ticket/input** — xem `custom/rules/output-language.md`: input tiếng Việt → viết tiếng Việt (mặc định trước đây); input tiếng Anh → viết tiếng Anh.
- **Tiêu đề cột của bảng (checklist, testcase) luôn viết bằng tiếng Anh** theo quy ước team, bất kể ngôn ngữ nội dung ô; **nội dung trong ô theo ngôn ngữ đã xác định ở trên**.
- Thuật ngữ kỹ thuật/test có thể giữ tiếng Anh trong ngoặc khi cần (vd: kiểm thử biên (boundary)).
- Viết ngắn gọn, rõ ràng, không lan man. Ưu tiên gạch đầu dòng và bảng.
- Tên menu/tab/button/label tiếng Nhật trong thiết kế gốc → giữ nguyên tiếng Nhật, không dịch. Xem chi tiết + toàn bộ chuẩn diễn đạt Test Case Name/Steps/Expected Result ở **mục 6** bên dưới.

### Từ vựng trạng thái test (Status) — dùng thống nhất ở checklist & testcase

- `Untest` — chưa test (mặc định khi mới sinh).
- `Pass` — đạt.
- `Fail` — không đạt.
- `Blocked` — bị chặn, chưa test được.
- `N/A` — không áp dụng.

## 2. Mức độ ưu tiên

- **High** — luồng chính, ảnh hưởng nghiệp vụ/tiền/bảo mật, lỗi gây chặn người dùng.
- **Medium** — luồng phụ, validation quan trọng, ảnh hưởng trải nghiệm rõ rệt.
- **Low** — trường hợp hiếm, UI cosmetic, edge ít xảy ra.

## 3. Quy ước đặt ID

- Checklist mục: `CL-<FEATURE>-001`
- Testcase: `TC-<FEATURE>-001`
- `<FEATURE>` viết hoa, không dấu, gạch nối nếu dài. Vd: `TC-LOGIN-001`, `TC-DAT-HANG-005`.
- Đánh số liên tục, 3 chữ số.

## 4. Nguyên tắc viết testcase

1. **1 testcase = 1 mục tiêu kiểm thử** (đừng gộp nhiều mục đích).
2. **Bước (steps)** rõ ràng, đánh số, người khác đọc làm theo được mà không cần hỏi.
3. **Kết quả mong đợi** phải **đo được / quan sát được** (tránh "hoạt động đúng").
4. Luôn ghi **tiền điều kiện** (precondition) và **dữ liệu test** cụ thể.
5. Phủ đủ: happy path → edge/biên → negative. Không chỉ test trường hợp đúng.
6. Mỗi testcase truy vết được về 1 mục checklist và/hoặc 1 yêu cầu trong spec.

## 6. Chuẩn diễn đạt Test Case Name / Steps / Expected Result (Wording Standards)

> Nguồn: review comment thực tế từ Reviewer (Gate 2c/3). Áp dụng cho **mọi** skill sinh hoặc sửa testcase (`generate-testcase`, workflow `create-testcase`, `execute-flow`/`script-sync` khi đọc lại TC). Vi phạm phải được liệt kê là issue Priority High ở bước review (`00.04.testcase-review.md`).

### 6.1. Test Case Name luôn bắt đầu bằng động từ kiểm tra

- Tiếng Việt → bắt đầu bằng **"Kiểm tra"**. Tiếng Anh (theo `output-language.md`) → bắt đầu bằng **"Verify"** hoặc **"Check"**.
- Nêu đúng 1 hành vi/điều kiện cụ thể đang test, không viết như một bước thao tác.
- ✅ `Kiểm tra hệ thống chuyển hướng về màn hình đăng nhập khi mở trực tiếp URL màn hình chỉnh sửa lúc chưa đăng nhập`
- ❌ `Truy cập màn hình khi chưa đăng nhập` (thiếu "Kiểm tra", đọc như step chứ không phải tên case)

### 6.2. Điều hướng qua URL/path — luôn kèm tên menu + tên màn hình

- Steps không được viết trần 1 đường dẫn kỹ thuật rồi bắt Tester tự suy ra cách vào màn hình đó qua UI. Phải mô tả đúng thao tác click menu/tab thực tế, path kỹ thuật chỉ đi kèm trong ngoặc để đối chiếu.
- Format chuẩn: `<n>. Click menu "<Tên menu>" → click "<Tên màn hình/tab>" để mở màn hình <Tên màn hình> (<path>).`
- Ví dụ: mở `/supplier/orders` → `1. Click menu "注文管理".<br>2. Click "注文" để mở màn hình 注文管理 (/supplier/orders).`
- **Ngoại lệ:** case đang test chính hành vi "gõ thẳng URL vào address bar" (vd kiểm tra chặn truy cập trực tiếp khi chưa đăng nhập, kiểm tra deep-link) — khi đó path chính là dữ liệu test, được phép ghi thẳng: `1. Nhập trực tiếp URL <path> vào thanh địa chỉ trình duyệt rồi Enter.`

### 6.3. Diễn đạt non-tech nhưng giữ đúng thuật ngữ nghiệp vụ chuẩn

- Không đưa thuật ngữ code/dev thuần (tên biến, tên cột DB, tên middleware, HTTP method, class CSS nội bộ...) vào Steps/Expected Result — Tester đọc phải hiểu được mà không cần biết code.
- Vẫn phải giữ đúng thuật ngữ nghiệp vụ/UI chính thức của hệ thống (tên trường, tên nút, tên business rule) — không diễn giải sai lệch nghĩa gốc.
- ✅ `Nhập giá trị bắt đầu bằng "javascript:" vào ô URL của nút, sau đó bấm Lưu`
- ❌ `Set fair_list_btn_url = 'javascript:alert(1)' rồi submit form` (lộ tên field DB/biến code)
- Field/DB key kỹ thuật chỉ nên xuất hiện ở cột **Comment** (để dev đối chiếu), không đưa vào Steps/Expected Result chính.

### 6.4. Chi tiết, rõ ràng, súc tích, thống nhất câu chữ

- Steps đánh số, mỗi step 1 hành động, đủ để người khác làm theo ngay không cần hỏi lại (đã có ở mục 4.2).
- Expected Result đo lường/quan sát được, không dùng "hoạt động đúng"/"OK" chung chung (đã có ở mục 4.3).
- Dùng thống nhất 1 bộ động từ và cấu trúc câu xuyên suốt cả bộ testcase — không đổi qua lại giữa "Bấm nút Lưu" / "Click Save" / "Nhấn nút Lưu" cho cùng 1 hành động.

### 6.5. Không cross-reference sang bất kỳ đâu ngoài chính ô đang viết — mỗi ô của mỗi case tự chứa đầy đủ nội dung

> Phạm vi: áp dụng cho **TẤT CẢ** các cột của bảng testcase — Pre-condition, Steps, Conditions for Expected Result, Expected Result, Data Test, và **cả cột Comment** (không còn ngoại lệ nào). Người đọc 1 dòng/1 ô bất kỳ không được bắt buộc phải mở dòng khác, case khác, hay mục khác trong tài liệu (Test Data dùng chung, PRE-COMMON, chú giải ①②③...) mới hiểu được nội dung.

- **Không cross-reference case khác:** không viết kiểu "như No.1", "như trên", "giống case trước", "câu ①", "→ xem TC_021" ở bất kỳ cột nào kể cả Comment. Copy đủ nội dung cần thiết (điều kiện, bước, dữ liệu, kỳ vọng) vào đúng ô đang viết, kể cả khi bị lặp lại giữa nhiều case — chấp nhận trùng lặp để đổi lấy khả năng đọc độc lập từng dòng.
- **Không cross-reference sang mục dữ liệu test dùng chung:** khi case cần dùng lại 1 đối tượng đã được đặt mã ngắn gọn ở mục dữ liệu test dùng chung (Test Data / mã cơ sở / mã sản phẩm / tên actor...) → mỗi lần mã đó xuất hiện ở **bất kỳ cột nào**, phải viết kèm ngay tại chỗ mô tả nghiệp vụ đầy đủ của mã đó (loại đối tượng, thuộc tính liên quan đang test, quan hệ với đối tượng khác nếu cần để hiểu case) — không chỉ nêu mã trần rồi để người đọc tự tra mục dữ liệu ở đầu tài liệu.
  - ❌ `F-711-A và F-821-A trùng mã 1234567890` (bắt người đọc nhớ/tra F-711-A, F-821-A là gì)
  - ✅ ``F-711-A` (cơ sở dịch vụ 通所介護, mã cơ sở `1234567890`, nộp file M) và `F-821-A` (cơ sở phúc lợi 居宅支援, cùng mã cơ sở `1234567890` — trùng mã với F-711-A, nộp file K)``
- **Không cross-reference sang chú giải/nhãn tắt của mục khác:** cùng nguyên tắc cho các nhãn tắt kiểu "câu ①/②/③", "điều kiện ①②③" được định nghĩa 1 lần ở đầu section rồi dùng lại xuyên suốt các case bên dưới — vẫn giữ nhãn để ngắn gọn, nhưng phải kèm mô tả ngay tại chỗ dùng (vd: `câu ① (thông báo liệt kê tên các cơ sở cùng nhóm)`), không được để trần ký hiệu.
- Cột **Comment** không còn là ngoại lệ: nếu cần ghi mã case/nguồn liên quan để truy vết, phải viết kèm đủ ngữ cảnh ngay trong ô đó, không được ghi trần mã case rồi bắt tra ngược.

### 6.6. Không gộp case — 1 case chỉ xác nhận đúng 1 kịch bản cụ thể

- Mở rộng nguyên tắc "1 testcase = 1 mục tiêu" ở mục 4.1: không dùng "hoặc" để nhét nhiều giá trị input/nhiều luồng khác nhau vào chung 1 case rồi kỳ vọng verify hết trong 1 lượt chạy.
- Mỗi biến thể input tách thành 1 test case riêng, ID riêng.
- ❌ `Nhập URL trống hoặc chỉ khoảng trắng` (2 giá trị input khác nhau gộp 1 case) → tách thành 2 case: "để trống" và "chỉ nhập khoảng trắng".

### 6.7. Giữ nguyên keyword của dự án

- Giữ nguyên các từ khóa/tên riêng đã xuất hiện trong ticket/SRS/UC Spec: tên tính năng, tên module, mã business rule (BR-001...), mã ticket, tên field nghiệp vụ. Không tự ý dịch hoặc đổi tên.

### 6.8. Tên tiếng Nhật của menu/item/màn hình — giữ nguyên, không dịch

- Nếu UC Spec/thiết kế ghi tên menu, tab, button, label bằng tiếng Nhật → giữ nguyên tiếng Nhật trong testcase.
- Có thể chú thích nghĩa tiếng Việt trong ngoặc ở lần xuất hiện đầu tiên nếu cần, nhưng từ gốc tiếng Nhật là bắt buộc, không được thay thế hoàn toàn bằng bản dịch.
- ✅ `Click menu "注文管理" (Quản lý đơn hàng)`
- ❌ `Click menu "Quản lý đơn hàng"` (mất tên gốc hệ thống đang hiển thị, Tester không tra được trên UI thật)

### 6.9. Không dùng element id/selector trần — mô tả theo label hiển thị trên UI

- Không viết thẳng `#btn-search`, `.recommend_btn a`, `input[name=...]` trong Steps/Expected Result — Tester không đọc DOM/code nên không hiểu.
- Luôn mô tả theo đúng label/text hiển thị trên UI trước: `button <Label hiển thị>`.
- Nếu case sẽ được dùng để sinh script automation (`execute-flow`/`script-sync` — bản thân skill này vẫn tự dò lại selector thật qua Playwright MCP snapshot theo label mô tả, không bắt buộc phải có sẵn id) → được phép thêm selector trong ngoặc ngay sau label như một gợi ý để phân biệt khi có nhiều phần tử cùng label, **không thay thế label**:
  - ✅ `Bấm nút 検索 (#btn-search)`
  - ✅ `Bấm nút Lưu (button[type=submit])`
  - ❌ `Click #btn-search`

### 6.10. Không tự đặt mã ngắn gọn kiểu "F-711-A" để định danh đối tượng test — mô tả bằng ngôn ngữ tự nhiên; nhiều điều kiện thì đánh số rõ ràng

- Không tự đặt ký hiệu/mã tắt (dạng `F-711-A`, `ACC-01`, `USER_X`...) để đại diện cho 1 đối tượng test (cơ sở, tài khoản, sản phẩm...) trong bất kỳ cột nào — Tester đọc phải tự nhớ hoặc tra lại mã đó nghĩa là gì, vi phạm nguyên tắc tự chứa đầy đủ nội dung ở mục 6.5.
- Mô tả trực tiếp bằng đặc điểm nghiệp vụ giúp nhận diện đối tượng ngay khi đọc (loại đối tượng, vai trò, thuộc tính đang test...). Vẫn giữ nguyên các giá trị dữ liệu nghiệp vụ thật (mã cơ sở, số hợp đồng, số tiền...) vì đó là dữ liệu cần thiết để tái hiện case, không phải ký hiệu tự đặt.
  - ❌ `F-711-A upload file M, F-821-A chưa upload`
  - ✅ `Cơ sở dịch vụ 通所介護 upload file M; cơ sở phúc lợi 居宅支援 (trùng mã cơ sở với cơ sở dịch vụ này) chưa upload`
- Khi 2+ đối tượng cùng loại xuất hiện trong 1 case mà không còn đặc điểm nghiệp vụ nào phân biệt được (vd 3 cơ sở hoàn toàn giống nhau, cố ý dùng để test case trùng lặp) → dùng số thứ tự bằng lời ("cơ sở thứ nhất/thứ hai/thứ ba"), không dùng ký hiệu viết tắt.
- Khi 1 ô (Pre-condition/Steps/Expected Result/Conditions for Expected Result) chứa **từ 2 điều kiện/dữ kiện độc lập trở lên**, trình bày dưới dạng danh sách đánh số `1. ...<br>2. ...<br>3. ...` thay vì nối liền bằng dấu chấm phẩy — giúp đọc tách bạch từng điều kiện. Chỉ giữ văn xuôi liền mạch khi cả ô chỉ diễn đạt đúng 1 ý.

## 7. Khi gặp điểm mơ hồ

- KHÔNG tự bịa nghiệp vụ. Ghi rõ là **giả định (assumption)** và đánh dấu cần xác nhận.
- Dồn các điểm chưa rõ vào bước QA (`/tc-qa`) để hỏi, đừng đoán bừa rồi viết testcase sai.