@educa-corp/sdd-framework 0.9.2 → 0.9.4

package/core/skills/qc/qa-designer/integration/db.md

@@ -17,10 +17,14 @@ insert/update/soft-delete đúng giá trị, side-effect, toàn vẹn. Chỉ c
 
 ---
 
-## Format file TC (bắt buộc)
-- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAP.md)`.
-- **Test Data** dạng list (giá trị input) · **Steps** `[Action]`/`[Verify]` · **Expected** 1 bullet nêu rõ **bảng.cột = giá trị**.
-- Cuối file: Trace matrix + bảng TC block · bỏ nội dung gạch ngang.
+## Format file TC
+
+> **Nạp `{paths.qc_skills_dir}/qa-designer/shared/tc-metadata-format.md`** — khuôn TC, luật
+> ATOMIC (1 kết cục = 1 TC), cách phân nhóm, hai file `.Test.md`, Trace + `@trace.verifies`,
+> `🚫 Block`, dòng `Test-ID attribute`. **Không lặp lại luật format ở đây.**
+>
+> Khi viết Expected Result / Test Data: nạp thêm `shared/precision-rules.md` (cấm từ mơ hồ,
+> đơn vị, toán tử) + `shared/action-keywords-glossary.md` (một hành động một từ).
 
 ## Kỹ thuật áp dụng
 - **State/DB verification:** verify bản ghi sau action (giá trị từng cột, flag, timestamp).
@@ -35,5 +39,7 @@ Nhóm TC: ghi đúng giá trị (happy) → default/null đúng → update khôn
 → audit log → ràng buộc/unique (negative). Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC trong `{paths.qc_dir}/{UC-ID}/test-cases/`. Ghi rõ query kiểm tra DB + yêu cầu cleanup;
-không hardcode ID, chuẩn bị/dọn data qua fixture. Bàn giao `qa-reviewer`.
+
+Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>_API.Test.md` — **Nhóm 2 Integration API/DB/Kafka**. Ghi rõ query kiểm tra DB + yêu cầu cleanup; không hardcode ID, chuẩn bị/dọn data qua fixture (3 mức teardown: `../shared/precision-rules.md` §8).
+
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.

package/core/skills/qc/qa-designer/integration/gui.md

@@ -18,10 +18,14 @@ lỗi từ server, đồng bộ trạng thái hai chiều. Chỉ cần load file
 
 ---
 
-## Format file TC (bắt buộc)
-- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAP.md)`.
-- **Test Data** dạng list · **Steps** `[Action]`/`[Verify]` · **Expected** 1 bullet (API liên quan + biểu hiện UI kỳ vọng).
-- Cuối file: Trace matrix + bảng TC block · bỏ nội dung gạch ngang.
+## Format file TC
+
+> **Nạp `{paths.qc_skills_dir}/qa-designer/shared/tc-metadata-format.md`** — khuôn TC, luật
+> ATOMIC (1 kết cục = 1 TC), cách phân nhóm, hai file `.Test.md`, Trace + `@trace.verifies`,
+> `🚫 Block`, dòng `Test-ID attribute`. **Không lặp lại luật format ở đây.**
+>
+> Khi viết Expected Result / Test Data: nạp thêm `shared/precision-rules.md` (cấm từ mơ hồ,
+> đơn vị, toán tử) + `shared/action-keywords-glossary.md` (một hành động một từ).
 
 ## Kỹ thuật áp dụng
 - **Data flow UI→API→UI:** verify request gửi đúng + render response đúng.
@@ -37,4 +41,7 @@ Nhóm TC: UI render đúng dữ liệu backend (happy) → empty state → lỗi
 Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC trong `{paths.qc_dir}/{UC-ID}/test-cases/`. Mỗi TC nêu API liên quan + biểu hiện UI. Bàn giao `qa-reviewer`.
+
+Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` — **Nhóm 4 Integration (qua UI)**. Đây là tầng verify dòng dữ liệu API → giao diện, nên **vẫn thuộc file giao diện**: bỏ UI đi thì TC mất nghĩa.
+
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.

package/core/skills/qc/qa-designer/integration/kafka.md

@@ -17,10 +17,14 @@ Skill **tự chứa** để viết TC tích hợp qua Kafka: producer phát even
 
 ---
 
-## Format file TC (bắt buộc)
-- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAP.md)`.
-- **Test Data** dạng list (payload) · **Steps** `[Action]`/`[Verify]` · **Expected** 1 bullet nêu **topic + field payload / hành vi consumer**.
-- Cuối file: Trace matrix + bảng TC block · bỏ nội dung gạch ngang.
+## Format file TC
+
+> **Nạp `{paths.qc_skills_dir}/qa-designer/shared/tc-metadata-format.md`** — khuôn TC, luật
+> ATOMIC (1 kết cục = 1 TC), cách phân nhóm, hai file `.Test.md`, Trace + `@trace.verifies`,
+> `🚫 Block`, dòng `Test-ID attribute`. **Không lặp lại luật format ở đây.**
+>
+> Khi viết Expected Result / Test Data: nạp thêm `shared/precision-rules.md` (cấm từ mơ hồ,
+> đơn vị, toán tử) + `shared/action-keywords-glossary.md` (một hành động một từ).
 
 ## Kỹ thuật áp dụng
 - **Message/event:** verify topic, key, payload schema, điều kiện phát.
@@ -37,4 +41,7 @@ Nhóm TC: phát đúng topic+payload (happy) → điều kiện không phát →
 Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC trong `{paths.qc_dir}/{UC-ID}/test-cases/`. Mỗi TC ghi topic, key, payload cần verify + hành vi consumer. Bàn giao `qa-reviewer`.
+
+Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>_API.Test.md` — **Nhóm 2 Integration API/DB/Kafka**. Mỗi TC ghi topic, key, payload cần verify + hành vi consumer.
+
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.

package/core/skills/qc/qa-designer/non-functional.md

@@ -17,10 +17,14 @@ Trọng tâm "hệ thống hoạt động TỐT thế nào". Chỉ cần load fi
 
 ---
 
-## Format file TC (bắt buộc)
-- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAP.md)`.
-- **Test Data** dạng list · **Steps** `[Action]`/`[Verify]` · **Expected** 1 bullet có **ngưỡng đo cụ thể** (không "nhanh/ổn định").
-- Cuối file: Trace matrix + bảng TC block · bỏ nội dung gạch ngang.
+## Format file TC
+
+> **Nạp `{paths.qc_skills_dir}/qa-designer/shared/tc-metadata-format.md`** — khuôn TC, luật
+> ATOMIC (1 kết cục = 1 TC), cách phân nhóm, hai file `.Test.md`, Trace + `@trace.verifies`,
+> `🚫 Block`, dòng `Test-ID attribute`. **Không lặp lại luật format ở đây.**
+>
+> Khi viết Expected Result / Test Data: nạp thêm `shared/precision-rules.md` (cấm từ mơ hồ,
+> đơn vị, toán tử) + `shared/action-keywords-glossary.md` (một hành động một từ).
 
 ## Kỹ thuật / loại
 - **Performance:** response time dưới tải mục tiêu; danh sách lớn (max data); pagination; concurrency.
@@ -37,4 +41,7 @@ Mỗi TC bám Format; **Expected có ngưỡng pass + công cụ đo**; đánh d
 Trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC non-functional trong `{paths.qc_dir}/{UC-ID}/test-cases/`. Mỗi TC ghi tiêu chí đo + ngưỡng + công cụ. Bàn giao `qa-reviewer`.
+
+Ghi vào file theo cùng câu hỏi phân file *"verify được mà không cần UI?"*: a11y · responsive · touch-target → `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` **Nhóm 5 NFR**; tải/hiệu năng/bảo mật ở tầng API → `{qc_artifact_dir}test-cases/TC_<FEATURE>_API.Test.md`. Mỗi TC ghi tiêu chí đo + ngưỡng + công cụ, đơn vị theo `../shared/precision-rules.md` §3.
+
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.

package/core/skills/qc/qa-designer/shared/action-keywords-glossary.md

@@ -0,0 +1,91 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/shared/action-keywords-glossary.md
+upstream_sha: df56df91eea42342537ccf67b5946df32d98dbf4
+---
+# Action Keywords Glossary — Từ Điển Chuẩn
+
+> **Quy tắc:** Mỗi hành động chỉ dùng **1 từ duy nhất** trong toàn bộ tài liệu TC. Không dùng Enter/Type/Input xen kẽ. Không dùng Verify/Assert/Check lẫn lộn.
+
+---
+
+## Nhóm 1 — UI Actions (Web & Mobile)
+
+| Từ chuẩn | Dùng khi nào | Không dùng thay thế |
+|---|---|---|
+| **Click** | Nhấn vào element trên Web (button, link, checkbox, radio) | Press, Hit, Select (cho button) |
+| **Tap** | Nhấn vào element trên Mobile | Click (cho mobile) |
+| **Enter** | Nhập văn bản vào input field / textarea | Type, Input, Fill, Write |
+| **Select** | Chọn option trong dropdown / listbox | Choose, Pick |
+| **Check** | Tick vào checkbox | Enable, Mark |
+| **Uncheck** | Bỏ tick checkbox | Disable, Unmark |
+| **Scroll** | Cuộn trang/container theo chiều dọc | Swipe (cho web) |
+| **Swipe** | Vuốt màn hình trên Mobile | Scroll (cho mobile) |
+| **Hover** | Di chuột vào element (hiện tooltip/dropdown) | Mouse over |
+| **Clear** | Xóa nội dung field | Delete, Empty |
+| **Upload** | Tải file lên qua input file | Attach, Import |
+| **Download** | Tải file về | Save, Export |
+| **Navigate to** | Mở URL / chuyển trang | Go to, Open URL |
+| **Refresh** | Tải lại trang | Reload |
+| **Wait for** | Chờ element/condition xuất hiện | Sleep, Pause |
+
+---
+
+## Nhóm 2 — Verification Actions
+
+| Từ chuẩn | Dùng khi nào | Không dùng thay thế |
+|---|---|---|
+| **Verify** | Kiểm tra trong test steps — kết quả trung gian | Assert, Check, Confirm |
+| **Assert** | Kết quả cuối (Expected Result) — điều kiện pass/fail | Verify (ở Expected), Check |
+| **Observe** | Ghi nhận trạng thái hiện tại (không pass/fail) | See, Notice |
+
+> **Phân biệt Verify vs Assert:**
+> - Trong **Test Steps**: dùng `[Verify]` → "Verify: Error message 'Email không hợp lệ' hiển thị dưới field"
+> - Trong **Expected Result**: dùng `Assert` → "Assert: HTTP 201, body.id tồn tại, body.email = email đã gửi"
+
+---
+
+## Nhóm 3 — API Actions
+
+| Từ chuẩn | Dùng khi nào | Không dùng thay thế |
+|---|---|---|
+| **Send** | Gửi HTTP request | Call, Hit, Invoke |
+| **GET** | HTTP GET request | Fetch, Read |
+| **POST** | HTTP POST request | Create, Submit |
+| **PUT** | HTTP PUT request | Update (toàn bộ) |
+| **PATCH** | HTTP PATCH request | Update (một phần) |
+| **DELETE** | HTTP DELETE request | Remove |
+| **Receive** | Nhận response từ server | Get response |
+| **Authenticate** | Thực hiện xác thực (login/token) | Login (trong API context) |
+
+---
+
+## Nhóm 4 — Test Setup / Teardown
+
+| Từ chuẩn | Dùng khi nào |
+|---|---|
+| **Setup** | Chuẩn bị dữ liệu / trạng thái trước test |
+| **Teardown** | Dọn dẹp sau test (xóa dữ liệu, reset state) |
+| **Login as** | Đăng nhập với role cụ thể: "Login as Teacher" |
+| **Logout** | Đăng xuất |
+| **Reset** | Đưa hệ thống về trạng thái ban đầu |
+| **Seed** | Tạo dữ liệu test (fixtures) trước khi chạy TC |
+
+---
+
+## Nhóm 5 — Trạng thái kỳ vọng (Expected keywords)
+
+| Từ chuẩn | Dùng khi nào | Không dùng |
+|---|---|---|
+| **displays** | UI hiển thị element/text | shows, appears, renders |
+| **is visible** | Element có thể nhìn thấy | is shown, is displayed |
+| **is enabled** | Element có thể tương tác | is active, is available |
+| **is disabled** | Element không thể tương tác | is inactive, is grayed out |
+| **is empty** | Field không có giá trị | is blank, is clear |
+| **contains** | Text/list chứa giá trị cụ thể | has, includes |
+| **equals** | Giá trị bằng chính xác | is, matches (cho exact match) |
+| **returns** | API trả về response | gives, sends back |
+| **persists** | Dữ liệu được lưu vào DB | saves, stores |
+| **navigates to** | Trình duyệt chuyển sang URL/màn mới | redirects to, goes to |

package/core/skills/qc/qa-designer/shared/duplicate-check-procedure.md

@@ -0,0 +1,105 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/shared/duplicate-check-procedure.md
+upstream_sha: c59357a56b289bb9fb7fae8490db37109209cb3a
+---
+# Duplicate Check Procedure
+
+> **Bắt buộc thực hiện** trước khi viết TC mới. TC trùng lặp làm tăng thời gian chạy, gây nhầm lẫn kết quả, và không tăng coverage.
+
+---
+
+## Định nghĩa TC trùng lặp
+
+Hai TC là **trùng** khi **cả 3** điều kiện sau đều giống nhau:
+1. **Điều kiện kiểm tra** (condition) — cùng scenario
+2. **Preconditions** — cùng trạng thái đầu vào
+3. **Test Data** — cùng partition/boundary value
+
+> Nếu chỉ khác tên/title nhưng nội dung giống → **trùng**.
+> Nếu cùng scenario nhưng khác role/data partition → **không trùng** (là 2 TC hợp lệ).
+
+---
+
+## Quy trình kiểm tra (3 bước)
+
+### Bước 1 — Grep title keywords trong file TC hiện tại
+
+Trước khi viết TC mới, tìm kiếm title keywords trong toàn bộ file:
+
+```bash
+# Tìm TC có chứa từ khóa scenario sắp viết
+grep -i "<từ_khóa_scenario>" {qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md
+```
+
+Ví dụ: Sắp viết TC "Nhập email không hợp lệ":
+```bash
+grep -i "email\|invalid\|không hợp lệ" {qc_artifact_dir}test-cases/TC_LOGIN.Test.md
+```
+
+### Bước 2 — So sánh preconditions + test data
+
+Nếu grep tìm thấy TC tương tự, so sánh:
+
+| Yếu tố | TC hiện có | TC sắp viết | Kết luận |
+|---|---|---|---|
+| Condition | Nhập email sai format | Nhập email sai format | Giống |
+| Precondition | Chưa login | Chưa login | Giống |
+| Test Data | `abc@` | `abc@` | Giống → **TRÙNG** |
+| Test Data | `abc@` | `abc` (không có @) | Khác partition → **KHÔNG TRÙNG** |
+
+### Bước 3 — Quyết định
+
+| Kết quả so sánh | Hành động |
+|---|---|
+| Trùng hoàn toàn (cả 3 yếu tố) | Không viết TC mới — sử dụng TC cũ |
+| Cùng condition, khác data/partition | Viết TC mới (hợp lệ) — thêm vào nhóm TC đó |
+| Cùng condition, khác platform (Web/App) | **KHÔNG trùng** — mỗi nền một thư mục (`{qc_dir}/{TICKET-ID}/web/` vs `/app/`) và mỗi nền phải tự đạt full coverage. Trùng logic giữa hai nền là **chủ đích** |
+| Không tìm thấy tương tự | Viết TC mới bình thường |
+
+---
+
+## Trường hợp đặc biệt
+
+### TC "uniqueness check" (kiểm tra trùng lặp dữ liệu)
+- **Chỉ viết** khi spec có ràng buộc uniqueness rõ ràng (vd: "email phải là duy nhất", "tên lớp không được trùng trong cùng giáo viên").
+- **Không viết** dựa trên suy đoán — cần có AC hoặc BR tường minh trong `{paths.specs_dir}`.
+
+### TC kế thừa logic từ UC khác
+- Nếu scenario giống UC khác đã có TC → **không viết lại**, ghi trace reference về UC nguồn.
+- Ví dụ: "Validation SĐT ở UC3 kế thừa logic UC2" → Trace: `BR-UC2-BR15`, ghi note "logic tương tự UC2".
+
+---
+
+## Áp dụng theo file — grep ở đâu
+
+Chỉ có **hai** file TC cho mỗi (tính năng × nền), chia theo *"verify được mà không cần UI?"*:
+
+| File | Chứa nhóm | Phạm vi grep khi kiểm trùng |
+|---|---|---|
+| `TC_<FEATURE>.Test.md` | GUI · Validation · Functional · Integration-qua-UI · NFR · E2E | **Toàn file** — trùng hay xảy ra giữa nhóm GUI và nhóm Functional |
+| `TC_<FEATURE>_API.Test.md` | Endpoint · Integration API/DB/Kafka | Toàn file — so cả **endpoint + method + phân vùng dữ liệu** |
+
+**Grep CẢ HAI file khi chưa chắc**, vì cùng một hành vi có thể đã được viết ở tầng khác: một
+TC "email đã tồn tại" có thể nằm ở nhóm Validation (qua UI) **hoặc** ở file API (409 Conflict).
+Hai cái đó **không trùng** — chúng test hai tầng khác nhau — nhưng phải biết cả hai tồn tại để
+không viết cái thứ ba.
+
+## Trùng chéo UC — chỗ mới xuất hiện
+
+Trước đây mỗi UC một thư mục riêng, nên TC của UC1 và UC2 không bao giờ gặp nhau. Giờ
+**mọi UC của một PRD nằm chung một thư mục `test-cases/`** — nên trùng chéo UC vừa **nhìn thấy
+được**, vừa **thực sự xảy ra**.
+
+Hai UC của cùng một PRD rất hay dùng lại một luật nghiệp vụ (validate số điện thoại, quyền
+truy cập, trạng thái hết hạn). Khi gặp:
+
+- **KHÔNG viết lại TC.** Ghi `Trace` trỏ về `BR-xx` của UC nguồn + một dòng ghi chú
+  *"logic tương tự {UC-ID}, đã phủ ở TC_<FEATURE>_NNN"*.
+- Chỉ viết TC mới khi **phân vùng dữ liệu hoặc tiền đề khác** — lúc đó không phải trùng.
+
+> **Vì sao gạch này quan trọng hơn sau khi bật chế độ tách tối đa.** Tách tối đa nhân số TC lên
+> (ví dụ thật: 82 → 130). Nhân một TC trùng lên 5 mảnh thì thành 5 TC trùng — và không ai đếm
+> được nữa. Kiểm trùng phải chạy **trước** khi tách, không phải sau.

package/core/skills/qc/qa-designer/shared/implicit-scenarios.md

@@ -0,0 +1,22 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/shared/implicit-scenarios.md
+upstream_sha: 6eb801a137ef4dfda97870c1eb36db62f3c782bc
+---
+# Implicit Scenarios (Bắt buộc nghĩ tới)
+
+**Với mọi TC ở mọi lane, luôn xét thêm các tình huống sau:**
+
+| Tình huống | Gợi ý kỹ thuật |
+|---|---|
+| Rate limiting / spam click | EP: vượt ngưỡng → block/error |
+| Concurrent / race condition | 2 request song song cùng resource |
+| Session / auth timeout | Hết hạn giữa chừng → redirect login |
+| Empty state | List rỗng, 0 kết quả, chưa có dữ liệu |
+| Max data | Trường đạt giới hạn ký tự/số lượng tối đa |
+| Ký tự đặc biệt | Emoji · Unicode · tiếng Việt có dấu · SQL injection attempt |
+| Audit / log | Hành động quan trọng có ghi log đúng không |
+
+> Không cần tạo TC riêng cho tất cả — đánh giá mức độ rủi ro: P0/P1 → viết TC, P2/P3 → ghi chú trong Test Data.

package/core/skills/qc/qa-designer/shared/precision-rules.md

@@ -0,0 +1,198 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/shared/precision-rules.md
+upstream_sha: 1c2005b55bd94c3e8fa25dfa12a29c8b23f7c01e
+---
+# Precision Rules — Quy Tắc Độ Chính Xác
+
+---
+
+## 1. Cấm từ mơ hồ — Bắt buộc lượng hóa
+
+| ❌ Mơ hồ — KHÔNG viết | ✅ Chuẩn — Thay bằng |
+|---|---|
+| "hiển thị nhanh" | "response time < 2 giây (đo P95)" |
+| "giao diện đẹp" | Không test (không đo được — bỏ qua) |
+| "phù hợp" | Chỉ rõ phù hợp với điều gì: "khớp với AC-03 của BR-12" |
+| "hiển thị đúng" | "displays text 'Tên lớp: Toán 6A'" |
+| "hoạt động bình thường" | Liệt kê hành vi cụ thể: "button enabled, click được, navigates to /dashboard" |
+| "không lỗi" | "HTTP 200, không có error message, field is empty" |
+| "dữ liệu chính xác" | "body.name = 'Toán 6A', body.teacher_id = 42" |
+| "validate thành công" | "Error message không hiển thị, form submits successfully" |
+| "load được" | "Page displays within 3 seconds, no console error" |
+
+---
+
+## 2. Assertion Granularity — Mỗi assertion 1 điều kiện
+
+**Nguyên tắc (ATOMIC — QC chốt 2026-07-09):** Mỗi TC có **đúng 1** `#### Expected Result` với **ĐÚNG 1 bullet** (1 outcome; bullet có thể compound `A AND B` trên cùng 1 outcome). **Nhiều bullet / điểm-kiểm → TÁCH thành nhiều TC ĐỘC LẬP, mỗi TC 1 bullet** (không còn gộp checkpoint). Test Steps chỉ `[Action]`/`[Verify]`, **không** gắn `→ [Expected]` ở bước (chi tiết tách + renumber đồng bộ: `tc-metadata-format.md §"1 bullet Expected = 1 TC ĐỘC LẬP"`).
+
+```
+✅ ĐÚNG — 1 outcome, nhiều assertion liên quan:
+Assert: HTTP 201 AND body.id exists AND body.name = "Toán 6A" AND body.teacher_id = 42
+
+✅ ĐÚNG — 1 assertion đơn lẻ:
+Assert: Error message "Email không hợp lệ" displays below email field
+
+❌ SAI — 2 outcome khác nhau gom chung:
+Assert: HTTP 201 AND trên UI hiển thị lớp mới trong danh sách
+→ Tách thành 2 TC riêng: TC API (HTTP 201) + TC UI (danh sách cập nhật)
+```
+
+### 2.1 Chế độ ATOMIC TỐI ĐA (QC chốt 2026-07-14 — khi user yêu cầu "tách tới mức nhỏ nhất")
+
+Mặc định trên vẫn cho compound `A AND B` **cùng 1 outcome**. Nhưng khi chủ dự án YÊU CẦU THẲNG tách nhỏ nhất, áp **atomic tối đa — mỗi assertion độc-lập-fail = 1 TC**, gồm **nổ completeness list theo từng thành phần**:
+- Thẻ/card "hiển thị **đủ** [A, B, C, D, E]" → **mỗi thành phần 1 TC** (vd thẻ khung giờ: ảnh GV / ngày·giờ / tên GV / tên bài / ô chọn = 5 TC; info card 4 mục = 4 TC; hero: tiêu đề / khẩu hiệu / linh vật = 3 TC).
+- Đa-outcome BẮT BUỘC tách kể cả khi liên quan: popup + data-state · silent-handoff (điều hướng + không-popup) · mỗi con (`profile_id` A / B) · mỗi element/breakpoint responsive · mỗi touch-target · include vs exclude của cùng 1 filter.
+
+**⛔ RANH GIỚI — GIỮ 1 TC (đừng over-split vô nghĩa) kể cả ở chế độ tối đa:**
+- *Predicate đa-điều-kiện định-nghĩa-1-khái-niệm*: "chưa bắt đầu **và** còn ≥10' = slot-hợp-lệ" → 1 TC.
+- *Ngưỡng*: "≥44pt/48dp", "WCAG AA ≥4.5:1" → 1 TC (không tách iOS/Android, không tách chữ-thường/chữ-lớn).
+- *Exclusivity* chọn-một; *qualifier* ("không chỉ bằng màu").
+- Bỏ vế TRÙNG nghĩa với TC khác (vd a11y "nút mở sau chọn" trùng TC chọn-1-khung → cắt, không nhân bản).
+
+**Thủ tục bắt buộc trước khi thực thi (chênh quy mô lớn — FEAT-01-4: 82→WEB 132/APP 130):**
+1. **HỎI 1 câu chốt ranh giới completeness** (giữ-1-completeness ~95 TC vs nổ-từng-thành-phần ~130 TC) — quy mô rất khác, phải để user quyết.
+2. Dựng **bản đồ tách** (số mảnh mỗi TC cha) trước, KHÔNG để agent con tự suy diễn → giảm sai + giảm cắt cụt.
+3. Ưu tiên (P0/P1) TC con **kế thừa** từ cha; renumber tuần tự + đồng bộ Mục lục/Tổng hợp(đếm lại P0/P1 từ tag)/Trace Matrix(expand cha→con).
+4. **Làm CẢ 2 nền WEB+APP** (nhóm NFR khác nền: web a11y/responsive vs app safe-area/touch/back-gesture → tổng có thể lệch, granularity atomic tương đương).
+5. **Verify bằng DIFF, không tin lời đếm của agent**: ID tuần tự · `###`=`#### Expected` · mỗi Expected 1 bullet · 0 bảng `|` · Trace Matrix không ID chết · P0/P1 khớp tag (bug renumber KHÔNG throw — xem `qa-agents-large-write-unreliable`).
+
+---
+
+## 3. Đơn vị chuẩn theo domain
+
+| Domain | Đơn vị bắt buộc | Ví dụ |
+|---|---|---|
+| Thời gian phản hồi | `ms` hoặc `giây` + percentile | "< 500ms (P95)" |
+| Throughput | `req/s` hoặc `req/phút` | "≥ 100 req/s" |
+| Tải concurrent | `users` | "50 concurrent users" |
+| Dung lượng file | `KB` hoặc `MB` | "< 5MB" |
+| Ký tự | `ký tự` | "≤ 100 ký tự" |
+| Accessibility | WCAG level + version | "WCAG 2.1 AA" |
+| HTTP status | Mã số đầy đủ | "HTTP 201", "HTTP 400" (không "success") |
+| DB record | Bảng + cột + giá trị | "users.email = 'test@gmail.com'" |
+| Error message | Chuỗi chính xác in nghiêng | `"Email không hợp lệ"` |
+
+---
+
+## 4. Toán tử so sánh — Dùng thống nhất
+
+| Ý nghĩa | Ký hiệu | Ví dụ |
+|---|---|---|
+| Bằng chính xác | `=` | `body.status = "active"` |
+| Nhỏ hơn | `<` | `response time < 2s` |
+| Nhỏ hơn hoặc bằng | `≤` | `file size ≤ 5MB` |
+| Lớn hơn | `>` | `list.count > 0` |
+| Lớn hơn hoặc bằng | `≥` | `throughput ≥ 100 req/s` |
+| Tồn tại | `exists` | `body.id exists` |
+| Không tồn tại | `not exists` | `error_message not exists` |
+| Chứa chuỗi | `contains` | `body.message contains "thành công"` |
+
+---
+
+## 5. Test Data sourcing — Dữ liệu test từ đâu
+
+**Quy tắc:**
+- **Không hardcode** giá trị nhạy cảm (password, token, production data) vào TC.
+- **Dùng placeholder** rõ nghĩa: `<valid_email>`, `<teacher_password>`, `<existing_class_id>`.
+- **Ghi nguồn dữ liệu** khi cần setup: "Seed: tạo 1 lớp học với teacher_id = fixture.teacher.id".
+- **Biên dữ liệu** (BVA) phải ghi rõ giá trị cụ thể: "10 ký tự (biên trên của maxlength=10)".
+
+**Baseline cho NFR:**
+- Lấy từ **SLA document** trong `{paths.specs_dir}` (nếu có).
+- Lấy từ **AC** trong PRD (vd "AC-05: response < 3s").
+- Nếu không có document → ghi rõ `[Cần xác nhận baseline với PO]` trong Test Data.
+
+---
+
+## 6. Format Expected Result chuẩn theo lane
+
+**UI:**
+```
+Assert: <element> <trạng thái> — ví dụ: "Error message 'Email không hợp lệ' is visible below field"
+```
+
+**API:**
+```
+Assert: HTTP <code> AND body.<field> <toán tử> <giá trị> — ví dụ: "HTTP 201 AND body.id exists AND body.name = 'Toán 6A'"
+```
+
+**E2E:**
+```
+Assert: <chuỗi verify point> — ví dụ: "Class 'Toán 6A' displays in list AND teacher dashboard shows 1 new class"
+```
+
+**NFR:**
+```
+Assert: <metric> <toán tử> <ngưỡng> (<đơn vị>) — ví dụ: "P95 response time < 500ms at 50 concurrent users"
+```
+
+**Integration:**
+```
+Assert: <Module A state> AND <Module B state> — ví dụ: "HTTP 201 AND DB: classes.id = new_id AND Kafka: event 'class.created' published"
+```
+
+---
+
+## 7. Decision Table — Quy tắc coverage
+
+**Standard coverage (ISTQB CTFL v4.0):** mỗi rule (cột) = 1 TC tối thiểu.
+
+| Điều kiện | Rule 1 | Rule 2 | Rule 3 | Rule 4 |
+|---|---|---|---|---|
+| user.role = admin | T | T | F | F |
+| resource.owner = self | T | F | T | F |
+| **Action** | 200 OK | 403 | 200 OK | 403 |
+
+→ 4 rules = 4 TC (1 happy + 3 negative/edge).
+
+**BVA — 3 giá trị hay 4 giá trị?**
+
+| Spec | Giá trị phải test |
+|---|---|
+| Range 2 biên (`min ≤ x ≤ max`) | **4 giá trị:** min−1, min, max, max+1 |
+| Biên trên chỉ (`x ≤ max`) | **3 giá trị:** max−1, max, max+1 |
+| Biên dưới chỉ (`x ≥ min`) | **3 giá trị:** min−1, min, min+1 |
+| Đúng 1 giá trị hợp lệ | **3 giá trị:** value−1, value, value+1 |
+
+**Don't-care conditions:** condition không ảnh hưởng action → gộp rule, ghi `DC` (don't care) trong bảng. Ví dụ: `resource.owner` không quan trọng khi `user.role = superadmin` → gộp 2 rules thành 1 TC.
+
+**Đếm TC từ Decision Table:** N unique rules sau gộp don't-care = N TC tối thiểu. Nếu spec không có Decision Table sẵn → tự xây bảng trong Phase Clarify trước khi viết TC.
+
+**Phủ ĐỦ mọi ô — kể cả ô "không hành động".** Mỗi tổ hợp điều kiện phải có TC, kể cả ô mà kết quả là "không làm gì / không hiển thị" (vd: cả 2 trục cùng đủ rõ → KHÔNG hỏi câu phụ; cả 2 cùng chưa rõ → KHÔNG hỏi). Không được bỏ ô vì "không có hành động".
+
+**Kết hợp Decision Table + BVA, không trộn lẫn:**
+- Giá trị trong TC Decision Table nên **cách biệt rõ** so với ngưỡng (vd chênh lệch 25 so với ngưỡng 20) để cô lập đúng rule.
+- Điểm **sát biên** (ngưỡng−1 / = ngưỡng / ngưỡng+1) tách thành TC **BVA riêng**, không nhét vào TC Decision Table.
+
+**Báo coverage bằng TC ID cụ thể.** Khi tổng kết độ phủ cho logic điều kiện/ngưỡng: lập bảng ánh xạ từng rule/điểm biên → TC ID, đánh dấu rõ ô nào đủ/thiếu. Không kết luận "phủ gián tiếp" chung chung.
+
+---
+
+## 8. Teardown Data Strategy
+
+### 3 mức cleanup:
+
+| Mức | Khi nào | Cách thực hiện |
+|---|---|---|
+| **Inline** | TC tạo 1 bản ghi độc lập | Bước cuối Steps: `[Teardown] DELETE /api/v1/resource/{created_id}` |
+| **Fixture** | Nhiều TC dùng chung 1 tập data | Preconditions: `Fixture: seed_class()` — teardown trong `conftest.py` scope=function |
+| **Reset env** | TC thay đổi trạng thái hệ thống (email sent, payment, notification) | Ghi vào TC: `⚠️ Manual teardown: [bước cụ thể]` |
+
+### Format Teardown trong TC:
+
+```markdown
+#### Teardown
+- DELETE /api/v1/classes/{created_id} — xóa lớp đã tạo trong Steps
+- Hoặc: [Reset: fixture scope=function tự cleanup sau mỗi test]
+```
+
+### Quy tắc:
+- TC tạo bản ghi DB hoặc state THẬT (ghi vào tài khoản test) → **bắt buộc** ghi Teardown (API DELETE hoặc fixture rollback / reset tài khoản).
+- TC chỉ đọc (GET) hoặc chỉ verify UI tĩnh → không cần Teardown.
+- **TC chỉ cấu hình mock / route intercept / network monitoring → KHÔNG cần Teardown.** Reset mock về default là trách nhiệm của fixture `conftest.py` (scope=function tự teardown). Ghi "Reset mock về default" trong từng TC là **thừa** — không thêm. (Lane test qua mock hoàn toàn, vd UI/E2E khi API SKIP, hầu hết TC KHÔNG có Teardown.)
+- TC mobile/E2E tạo account → ghi `[Teardown: deactivate user via admin API]`.
+- TC không cleanup được → đánh dấu `⚠️ Manual teardown required` + ghi hướng dẫn chi tiết.

package/core/skills/qc/qa-designer/shared/read-doc-gap-inputs.md

@@ -0,0 +1,25 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/shared/read-doc-gap-inputs.md
+upstream_sha: a7e113b19f35aa47acf91e55cdfb3f630539806c
+---
+# Thủ tục: Nạp TOÀN BỘ tài liệu input từ DOC_GAP (BẮT BUỘC trước khi thiết kế/review TC)
+
+> Mục tiêu: designer/reviewer phải đọc **đúng bộ tài liệu nguồn mà qa-tc-analyst đã dùng** để dựng TEST_PLAN + DOC_GAP — không chỉ file domain. Tránh thiết kế/review TC trên ngữ cảnh thiếu, dẫn tới bỏ sót nghiệp vụ hoặc hiểu sai contract.
+
+## Các bước
+
+1. **Tìm file DOC_GAP** tại `{qc_artifact_dir}DOC_GAP.md` — **một file cho cả PRD**, các UC là các hàng phân biệt bằng cột `UC` (xem `/qc-analyze`). Không có → chạy `/qc-analyze {TICKET-ID} {platform}` trước; **đừng thiết kế TC trên ngữ cảnh thiếu**.
+2. **`Read` toàn bộ DOC_GAP.** Định vị mục **`## Tài liệu đầu vào đã đọc để phân tích`** — bảng liệt kê **đầy đủ** file nguồn (cột "Đường dẫn", tính từ `{paths.specs_dir}/`), kèm vai trò & phiên bản.
+3. **`Read` TỪNG file trong bảng đó** — ghép prefix `{paths.specs_dir}/` vào đường dẫn ở cột. Đọc HẾT, không bỏ sót dòng nào (spec chính + ref bắt buộc + transitive 1-hop). Nếu bảng liệt kê phiên bản, kiểm tra file hiện tại khớp; lệch phiên bản → ghi chú, không tự bịa.
+4. **Đối chiếu chéo:** nếu ngoài bảng DOC_GAP còn `## Coverage Attestation` / dòng "Tài liệu nguồn (spec chính)" ở header → xác nhận đã phủ hết; file nào có mặt ở header mà thiếu trong bảng → vẫn đọc.
+5. Chỉ sau khi đã nạp xong toàn bộ input + file domain (`business-dictionary.md`, `product-definition/`) mới bắt đầu viết/soát TC.
+
+## Nguyên tắc
+
+- **Không tự suy diễn ngoài tài liệu.** Chỉ dùng nội dung thực có trong các file đã đọc.
+- **Không đọc thiếu:** nếu DOC_GAP nói "Tổng: N tài liệu" thì phải mở đủ N (trừ file domain đã nạp riêng — vẫn nằm trong N).
+- **Bỏ qua** phần Change log / Appendix / "Giả định AI" khi trích evidence (giống ràng buộc nguồn của analyst), nhưng vẫn được đọc để hiểu ngữ cảnh.
+- Lane API: nếu DOC_GAP ghi SKIP (không có `openapi.yaml`/`.dbml`/`tdd/`) → không bịa endpoint.