# HƯỚNG DẪN VÀ TEMPLATE VIẾT DEV CHECKLIST (MD FORMAT)

Tài liệu này cung cấp **Template Dev Checklist** — danh sách tự kiểm tra dành cho Dev, sinh ở Gate 4 của workflow `create-testcase` ngay sau `[functionId]_TestCase.md`.

> ⚠️ **Bắt buộc đọc trước:** `../rules/qa-writing-standards.md` mục 6 và `custom/rules/document-wording.md`. Mọi chuẩn diễn đạt của Test Case đều áp dụng cho file này: mỗi ô tự chứa đủ nội dung, Expected Result đo được, không tham chiếu sang case khác hay tài liệu khác.
>
> ⚠️ **Thuật ngữ:** `custom/rules/domain-terminology.md` + `AK-Docs/00.Project-Overview/Glossary.md` — dùng đúng từ UC Spec / QnA-Log đã dùng, không tự dịch, không tự đặt tên phân hệ / menu / màn hình.
>
> ⚠️ **Động từ thao tác UI & thuật ngữ IT:** `custom/rules/ui-action-wording.md` — `Click button`, `Click menu item`, `Enter <value> into <field>`, `Select`, `Check`, trạng thái `Displayed` / `Enabled` / `Disabled`; thuật ngữ IT giữ tiếng Anh (field, toast, modal, server, cache, redirect…); không viết "bấm", "nhấn", "tích chọn", "chọn tay".

---

## 1. Mục đích

Checklist giúp Dev tự kiểm tra chức năng mình làm **trước khi bàn giao cho QA**, để QA không phải trả lại những bug cơ bản.

Checklist **không** thay thế bộ Test Case. Nó là tập con được bốc ra từ `[functionId]_TestCase.md`: mỗi dòng checklist map tới đúng **một** Test Case ID có thật trong bộ TC đã Approved.

---

## 2. Quy tắc sinh file

### 2.1. Vị trí và tên file

```
AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Dev_Checklist.md
```

Một file duy nhất cho mỗi `functionId`. **Không** đánh version vào tên file — Mode UPDATE ghi đè tại chỗ, giống `[functionId]_TestCase.md`. Lịch sử thay đổi tra bằng git.

### 2.2. Quy tắc đặt ID

```
<FE|BE>-<functionId>-<3 chữ số>
```

Ví dụ: `FE-AD06-001`, `BE-AD06-001`, `FE-WONDER-1035-012`.

Số thứ tự chạy độc lập cho FE và BE, bắt đầu từ `001`, liên tục trong từng section, không reset theo nhóm.

### 2.3. Nguồn nội dung — chỉ bốc từ Test Case

- Mỗi dòng checklist bốc từ **một** TC trong `[functionId]_TestCase.md`. Ghi TC ID đó vào cột `TC ID`.
- **Không gộp** nhiều TC thành một dòng checklist. Không viết "áp dụng tương tự".
- **Không tự sinh** dòng mới không có TC tương ứng. Thiếu vùng nào thì đó là lỗ hổng của bộ TC — ghi vào Findings của `[functionId]_Review Result.md`, không vá bằng cách bịa dòng checklist.
- Chọn TC **đại diện** cho mỗi nhóm ở mục 3 bên dưới. Nhiều TC cùng kiểm một điều (ví dụ 6 TC maxlength cho 6 field) → chọn TC của field rủi ro nhất, không bốc cả 6.

### 2.4. Phân loại FE / BE

| | Checklist FE | Checklist BE |
|:---|:---|:---|
| **Phạm vi** | Giao diện, thao tác người dùng, validate phía client, hiển thị dữ liệu và lỗi trả về từ API | API, validate phía server, logic nghiệp vụ, DB, phân quyền, tích hợp (email, hệ thống ngoài) |
| **Cách kiểm tra** | Thao tác trên trình duyệt, DevTools | Postman/Swagger, unit test, query DB, log |

**Nguyên tắc:** BE không được tin dữ liệu từ FE. Mọi validation đã có ở FE phải được kiểm tra lại ở checklist BE — nếu bộ TC có TC kiểm điều này.

**Khi một section không có TC nào thuộc phạm vi của nó** (ví dụ QA test hộp đen qua UI, không có TC gọi API trực tiếp) → giữ nguyên heading của section và ghi đúng một dòng:

```
N/A — bộ TestCase không có case kiểm qua API/DB.
```

Không xoá heading. Không bịa dòng để lấp chỗ trống.

**Khi task chỉ chạm một phía** (ví dụ task chỉ sửa FE) → section còn lại ghi:

```
N/A — task không thay đổi backend.
```

---

## 3. Năm nhóm nội dung bắt buộc

Mỗi section (FE và BE) chia theo đúng 5 nhóm dưới đây, dùng làm heading cấp 3. Nhóm nào không có TC tương ứng trong bộ TC → giữ heading, ghi `N/A — <lý do cụ thể>`.

### Nhóm 1 — Happy case (luồng chính thành công)

Thao tác đúng với dữ liệu hợp lệ và cho ra kết quả đúng như spec.

- FE: màn hình, thông báo, chuyển trang, dữ liệu hiển thị.
- BE: response, dữ liệu lưu trong DB, xử lý phía sau (email, trạng thái…).

### Nhóm 2 — Validation cơ bản (với từng trường nhập liệu)

- Bắt buộc: để trống, chỉ nhập khoảng trắng.
- Độ dài: max và max+1 (có min thì kiểm tra thêm min và min-1).
- Định dạng: email, số, ngày, URL, số điện thoại.
- Trùng dữ liệu, nếu trường có yêu cầu duy nhất.
- Quan hệ giữa các trường, ví dụ mật khẩu và xác nhận mật khẩu.

### Nhóm 3 — Yêu cầu riêng của task

- Mỗi yêu cầu hoặc acceptance criteria trong task có ít nhất 1 dòng checklist.
- Rule nghiệp vụ nào cũng cần cả dòng thoả điều kiện và dòng không thoả điều kiện.

### Nhóm 4 — Case liên quan đến API (bắt buộc với section BE)

- Request hợp lệ trả về đúng status code và đúng cấu trúc response.
- Request thiếu hoặc sai tham số, sai kiểu dữ liệu → 400/422 kèm message lỗi rõ ràng.
- Không có token → 401. Sai quyền hoặc truy cập dữ liệu của người khác → 403.
- ID không tồn tại → 404, không trả 500.
- Field không được phép sửa bị bỏ qua hoặc bị từ chối, ví dụ gửi kèm `status` khi tạo mới.
- Response và log không chứa dữ liệu nhạy cảm như mật khẩu hay token.

### Nhóm 5 — Case ngoại lệ

- Thao tác bất thường: click button nhiều lần, refresh hoặc back giữa chừng, hết session.
- Lỗi hệ thống: API lỗi, timeout, mất mạng. FE phải hiển thị thông báo phù hợp, không treo màn hình.
- Dữ liệu đặc biệt: ký tự đặc biệt, HTML/script, emoji, dữ liệu rất lớn.
- Xử lý đồng thời: 2 người thao tác cùng một dữ liệu.
- Ảnh hưởng chức năng cũ: các chức năng liên quan vẫn hoạt động như trước (regression).

---

## 4. Quy tắc viết từng cột

| Cột | Quy tắc |
|:---|:---|
| **ID** | `<FE\|BE>-<functionId>-<3 chữ số>` theo mục 2.2 |
| **Checklist Name** | Nội dung kiểm tra: **thao tác + dữ liệu hoặc điều kiện cụ thể**. Cấm viết chung chung kiểu "kiểm tra form hoạt động đúng" |
| **Expected Result** | Kết quả **đo được**: message nguyên văn gì, status code gì, dữ liệu DB ra sao, màn hình chuyển đi đâu. Cấm "hiển thị đúng", "xử lý đúng", "hoạt động bình thường" |
| **Result** | Dev điền khi chạy: `OK` / `NG` / `N/A`. Sinh ra để trống |
| **Note** | Bắt buộc điền khi `Result` là `N/A` (ghi lý do) hoặc `NG` (ghi known issue). Trống khi `OK` |
| **TC ID** | Test Case ID trong `[functionId]_TestCase.md` mà dòng này bốc ra. Bắt buộc, không để trống |

Mỗi dòng chỉ kiểm tra **một** nội dung. Hai nội dung → tách hai dòng.

---

## 5. Template

```markdown
# [functionId]_[Tên chức năng] - Dev Checklist

## 1. Thông tin chung

| Mục | Chi tiết |
|:---|:---|
| **Mã màn hình - Tên màn hình** | [Ví dụ: AD10_Create Product] |
| **Nguồn Test Case** | `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_TestCase.md` |
| **UC-Spec-Version** | [vd v3 — copy từ Mục 1 của file TestCase] |
| **System-Requirement-Version** | [vd v3, hoặc "—"] |
| **Người tạo (Author)** | [Ví dụ: AI QA (Gate 4)] |
| **Ngày tạo / cập nhật** | [Ví dụ: 2026-09-30] |

**Cách dùng:** Dev chạy toàn bộ checklist trước khi tạo Merge Request. Điền cột `Result` là `OK` / `NG` / `N/A`. Dòng `N/A` phải ghi lý do ở cột `Note`. Dòng `NG` chưa sửa kịp thì ghi là known issue ở cột `Note` và báo QA khi bàn giao.

## 2. Checklist FE

### 2.1. Happy case

| ID | Checklist Name | Expected Result | Result | Note | TC ID |
|---|---|---|---|---|---|
| FE-CRT-001 | Enter dữ liệu hợp lệ into toàn bộ field bắt buộc, click button [Lưu] | 1. Hiển thị thông báo nguyên văn "Tạo buyer thành công".<br>2. Hệ thống chuyển về màn hình danh sách Buyer.<br>3. Buyer vừa tạo hiển thị ở đầu danh sách với status `ACTIVATED`. |  |  | TC-CRT-001 |

### 2.2. Validation cơ bản

| ID | Checklist Name | Expected Result | Result | Note | TC ID |
|---|---|---|---|---|---|
| FE-CRT-002 | Leave toàn bộ field empty, click button [Lưu] | 1. Mọi trường bắt buộc hiển thị thông báo lỗi cùng lúc, nguyên văn "Hãy nhập [Tên Trường]".<br>2. Tab Network của DevTools không ghi nhận request nào tới `POST /buyers`. |  |  | TC-CRT-008 |

### 2.3. Yêu cầu riêng của task

| ID | Checklist Name | Expected Result | Result | Note | TC ID |
|---|---|---|---|---|---|
| FE-CRT-003 | [Điền theo acceptance criteria của task] | [Kết quả đo được] |  |  | [TC ID] |

### 2.4. Case liên quan đến API

N/A — nhóm này bắt buộc với section BE; các case gọi API trực tiếp nằm ở mục 3.4.

### 2.5. Case ngoại lệ

| ID | Checklist Name | Expected Result | Result | Note | TC ID |
|---|---|---|---|---|---|
| FE-CRT-004 | Click button [Lưu] 3 lần liên tiếp trong lúc request đang chạy | 1. Button [Lưu] chuyển sang Disabled ngay sau lần click đầu tiên.<br>2. Tab Network ghi nhận đúng 1 request `POST /buyers`. |  |  | TC-CRT-021 |
| FE-CRT-005 | Giả lập API `POST /buyers` trả về HTTP 500 rồi click button [Lưu] | 1. Hiển thị thông báo lỗi nguyên văn "Đã xảy ra lỗi. Vui lòng thử lại sau".<br>2. Toàn bộ dữ liệu đã nhập giữ nguyên trong form, không bị xoá. |  |  | TC-CRT-023 |

## 3. Checklist BE

### 3.1. Happy case

| ID | Checklist Name | Expected Result | Result | Note | TC ID |
|---|---|---|---|---|---|
| BE-CRT-001 | Gọi `POST /buyers` với body hợp lệ đủ trường bắt buộc | 1. Response trả về HTTP 201.<br>2. Bảng `buyers` có record mới với cột status là `ACTIVATED`.<br>3. Cột password lưu dạng hash, không lưu chuỗi gốc.<br>4. Hộp thư của email vừa đăng ký không nhận được email nào. |  |  | TC-CRT-002 |

### 3.2. Validation cơ bản

| ID | Checklist Name | Expected Result | Result | Note | TC ID |
|---|---|---|---|---|---|
| BE-CRT-002 | Gọi `POST /buyers` với email đã tồn tại, khác nhau ở chữ hoa chữ thường | 1. Response trả về HTTP 422 với message nguyên văn "Email đã tồn tại".<br>2. Bảng `buyers` không có thêm record mới. |  |  | TC-CRT-011 |

### 3.3. Yêu cầu riêng của task

| ID | Checklist Name | Expected Result | Result | Note | TC ID |
|---|---|---|---|---|---|
| BE-CRT-003 | [Điền theo business rule của task, kèm cả dòng thoả và dòng không thoả điều kiện] | [Kết quả đo được] |  |  | [TC ID] |

### 3.4. Case liên quan đến API

| ID | Checklist Name | Expected Result | Result | Note | TC ID |
|---|---|---|---|---|---|
| BE-CRT-004 | Gọi `POST /buyers` kèm trường `status` giá trị `INACTIVATED` trong body | 1. Response trả về HTTP 201.<br>2. Record trong bảng `buyers` có cột status là `ACTIVATED`; giá trị `INACTIVATED` gửi lên bị bỏ qua. |  |  | TC-CRT-014 |
| BE-CRT-005 | Gọi `POST /buyers` không kèm header Authorization | 1. Response trả về HTTP 401.<br>2. Bảng `buyers` không có thêm record mới. |  |  | TC-CRT-015 |
| BE-CRT-006 | Gọi `POST /buyers` bằng token của tài khoản Admin không có quyền tạo buyer | 1. Response trả về HTTP 403.<br>2. Bảng `buyers` không có thêm record mới. |  |  | TC-CRT-016 |
| BE-CRT-007 | Gọi `GET /buyers/999999` với ID không tồn tại trong bảng `buyers` | 1. Response trả về HTTP 404, không phải 500.<br>2. Body response có message nguyên văn "Không tìm thấy buyer". |  |  | TC-CRT-018 |
| BE-CRT-008 | Đọc body response và file log sau khi gọi `POST /buyers` thành công | 1. Body response không chứa cột password dưới bất kỳ dạng nào.<br>2. File log không ghi giá trị password và không ghi giá trị token. |  |  | TC-CRT-019 |

### 3.5. Case ngoại lệ

| ID | Checklist Name | Expected Result | Result | Note | TC ID |
|---|---|---|---|---|---|
| BE-CRT-009 | Hai tài khoản gửi đồng thời hai request `POST /buyers` cùng một email | 1. Đúng 1 request trả về HTTP 201, request còn lại trả về HTTP 422 với message "Email đã tồn tại".<br>2. Bảng `buyers` có đúng 1 record với email đó. |  |  | TC-CRT-025 |

## 4. Tiêu chí hoàn thành

- [ ] Section FE và section BE đều có đủ 5 nhóm ở mục 2/3, nhóm nào N/A thì đã ghi lý do cụ thể.
- [ ] Section BE có nhóm "Case liên quan đến API", trừ khi đã ghi N/A kèm lý do.
- [ ] Toàn bộ dòng có cột `Result` là `OK`.
- [ ] Dòng `N/A` đã ghi lý do ở cột `Note`.
- [ ] Dòng `NG` chưa sửa kịp đã ghi là known issue ở cột `Note` và đã báo QA khi bàn giao.
```

---

## 6. Ví dụ — chức năng Create buyer

Ba dòng dưới đây minh hoạ khác biệt giữa dòng đạt và dòng không đạt.

| Dòng | Checklist Name | Expected Result | Đánh giá |
|:---|:---|:---|:---|
| ❌ | Kiểm tra form Create buyer hoạt động đúng | Hiển thị đúng | Cả hai ô đều chung chung — không biết nhập gì, không biết lấy gì làm bằng chứng |
| ❌ | Enter dữ liệu rồi click button [Lưu] | Tạo thành công | Thiếu dữ liệu cụ thể; "tạo thành công" không nói được quan sát ở đâu |
| ✅ | Enter dữ liệu hợp lệ into toàn bộ field bắt buộc, click button [Lưu] | 1. Hiển thị thông báo nguyên văn "Tạo buyer thành công".<br>2. Hệ thống chuyển về màn hình danh sách Buyer.<br>3. Buyer vừa tạo hiển thị với status `ACTIVATED`. | Thao tác và dữ liệu rõ, kết quả quan sát được ở 3 điểm |

---

## 7. Mode UPDATE

Khi `create-testcase` chạy lại ở Mode UPDATE cho cùng `functionId`:

1. Đọc `[functionId]_Dev_Checklist.md` hiện có.
2. Đối chiếu cột `TC ID` với bộ TC mới:
   - TC ID không còn trong bộ TC mới (đã xoá hoặc gộp ở bản mới) → **xoá** dòng checklist tương ứng.
   - TC ID còn nhưng nội dung TC đã đổi → cập nhật `Checklist Name` và `Expected Result` theo TC mới, giữ nguyên `Result` và `Note` nếu Dev đã điền.
   - TC main mới xuất hiện trong bộ TC mới → thêm dòng mới, ID lấy số thứ tự kế tiếp trong section (không tái sử dụng ID đã xoá).
3. Cập nhật `UC-Spec-Version` / `System-Requirement-Version` ở Mục 1 theo file TestCase mới.
4. Ghi số dòng thêm/xoá/sửa vào `[functionId]_Review Result.md` mục 5.

---

## 8. Kiểm bằng máy

```bash
ak tc lint --checklist AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Dev_Checklist.md
```

Linter kiểm:

- Định dạng ID theo mục 2.2.
- Cột `TC ID` không rỗng, và trỏ tới TC **có thật** trong `[functionId]_TestCase.md` nằm cùng thư mục. TC đã bị xoá hoặc gộp ở bản mới → báo `checklist-dangling-tc`, xoá dòng checklist đó theo (mục 7). Không có file TestCase cạnh bên → bỏ qua riêng check này.
- `Expected Result` không dùng tính từ rỗng nghĩa, không tham chiếu ra ngoài ô.
- Cột `Result` chỉ nhận `OK` / `NG` / `N/A` hoặc để trống; `Note` đã điền khi `Result` là `NG` hoặc `N/A`.

Còn `error` → sửa rồi chạy lại. Không đóng Gate 4 khi linter còn `error`.
