@educa-corp/sdd-framework 0.9.3 → 0.9.5

package/core/skills/qc/qa-designer/api/endpoint.md

@@ -0,0 +1,231 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/api-testcase-designer/api/templates/endpoint.md
+upstream_sha: 7b38edd94e5efd37ff561f53cff92adedabaff7f
+---
+
+> **VIẾT LẠI, không copy** *(B12)*. Bản upstream ra đời **trước** luật ATOMIC (đội QC chốt
+> 2026-07-09) nên mỗi mẫu của nó gộp nhiều kết cục vào một `**Expected:**` nối bằng `;`, và
+> dùng hệ mã `API-<FEATURE>-001` khác với `TC_<FEATURE>_NNN` mà phần còn lại dùng.
+>
+> Port nguyên là **dạy AI làm ngược luật vừa chốt** — mẫu cụ thể luôn thắng luật trừu tượng.
+> Nội dung phủ (5 nhóm ca) giữ nguyên; cấu trúc TC theo `shared/tc-metadata-format.md`.
+
+# Khuôn TC — một endpoint đơn
+
+Mẫu khi viết TC cho 1 endpoint (GET / POST / PUT / DELETE). Thay mọi `<placeholder>` bằng giá
+trị thật từ `TEST_PLAN.md` + hợp đồng API §4 của tech-doc gộp.
+
+Phủ **5 nhóm ca**: happy · validation · auth thiếu token · auth sai quyền · not found.
+Mã lỗi tra ở `http-status-codes.md`; header tra ở `common-headers.md`.
+
+---
+
+## Nhóm ca 1 — Happy case
+
+⚠️ **Một request thành công sinh RA NHIỀU kết cục → nhiều TC độc lập.** Upstream gộp
+`HTTP 201; body.id = x; bản ghi có trong DB` vào một dòng — đó là **ba** kết cục:
+
+### TC_<FEATURE>_001 — <METHOD> <path> trả về <success_code>
+
+- **Title:** <METHOD> <path> với request hợp lệ trả về <success_code>
+- **Feature:** <TICKET-ID> — <Tên feature>
+- **Priority:** P0
+- **Status:** Draft
+- **Author:** AI
+- **Tags:** api, happy-path, <feature-tag>
+- **Trace:** BR-xx
+- **@trace.verifies:** {UC-ID}-SC{N}
+
+#### Preconditions
+- Tài khoản role `<role>` đã có token hợp lệ.
+- <Dữ liệu nền cần có, vd "đã tồn tại course id = 123">
+
+#### Test Data
+- Method: <GET|POST|PUT|DELETE>
+- Path: `<path>`
+- Headers:
+  - Authorization: Bearer `<valid_token_<role>>`
+  - Content-Type: application/json
+- Body:
+  ```json
+  { "<field1>": "<valid_value>", "<field2>": "<valid_value>" }
+  ```
+
+#### Test Steps
+1. **[Action]** Gửi `<METHOD> <path>` với headers và body trên.
+2. **[Verify]** Đọc status code của response.
+
+#### Expected Result
+- HTTP `<success_code>`
+
+#### Teardown
+- `DELETE <base_path>/{body.id}` — xoá bản ghi vừa tạo *(chỉ khi TC này tạo bản ghi thật)*
+
+### TC_<FEATURE>_002 — body response chứa `<key_field>` đúng
+
+- **Title:** <METHOD> <path> — body response có `<key_field>` = `<expected_value>`
+- **Feature:** <TICKET-ID> — <Tên feature>
+- **Priority:** P0
+- **Status:** Draft
+- **Author:** AI
+- **Tags:** api, happy-path, <feature-tag>
+- **Trace:** BR-xx
+- **@trace.verifies:** {UC-ID}-SC{N}
+
+#### Preconditions
+- *(copy nguyên từ TC_001 — mỗi TC tách là testcase ĐỘC LẬP, giữ FULL steps)*
+
+#### Test Data
+- *(copy nguyên từ TC_001)*
+
+#### Test Steps
+1. **[Action]** Gửi `<METHOD> <path>` với headers và body trên.
+2. **[Verify]** Đọc trường `<key_field>` trong body response.
+
+#### Expected Result
+- `body.<key_field>` = `<expected_value>`
+
+#### Teardown
+- `DELETE <base_path>/{body.id}` *(chỉ khi TC này tạo bản ghi thật)*
+
+### TC_<FEATURE>_003 — side-effect được ghi
+
+*Chỉ viết khi có side-effect cần verify. Nếu side-effect nằm ở DB/Kafka, TC này thuộc
+**nhóm Integration API/DB/Kafka**, không thuộc nhóm Endpoint.*
+
+- **Title:** <METHOD> <path> — bản ghi xuất hiện trong `<bảng>` với id = body.id
+- **Priority:** P0
+- **Tags:** api, integration, <feature-tag>
+- **Trace:** BR-xx
+
+#### Expected Result
+- `<bảng>.id` = `body.id` AND `<bảng>.<cột>` = `<giá trị>`
+
+> ✅ Bullet compound `A AND B` ở đây **hợp lệ**: cả hai vế nói về **cùng một** kết cục
+> ("bản ghi đã được ghi đúng"). Còn `HTTP 201; body.id = x` là **hai** kết cục — phải tách.
+> Phép soi nhanh: bullet nối bằng `;`, hoặc nối một khẳng định với một phủ định, là 2 kết cục.
+
+---
+
+## Nhóm ca 2 — Validation: field bắt buộc để trống
+
+### TC_<FEATURE>_004 — thiếu `<required_field>` trả về 400
+
+- **Title:** POST <path> — thiếu `<required_field>` trả về 400
+- **Priority:** P1
+- **Status:** Draft
+- **Author:** AI
+- **Tags:** api, negative, validation, ep
+- **Trace:** BR-xx
+
+#### Test Data
+- Method: POST
+- Path: `<path>`
+- Headers:
+  - Authorization: Bearer `<valid_token_<role>>`
+  - Content-Type: application/json
+- Body: `{ }` — bỏ hẳn `<required_field>`
+
+#### Test Steps
+1. **[Action]** Gửi POST không có `<required_field>`.
+2. **[Verify]** Đọc status code.
+
+#### Expected Result
+- HTTP 400
+
+**Thông báo lỗi là một TC RIÊNG** — nội dung thông báo là oracle khác với mã trạng thái:
+
+### TC_<FEATURE>_005 — thông báo lỗi nêu đúng field thiếu
+
+#### Expected Result
+- `body.message` contains `"<chuỗi nguyên văn từ PRD/tech-doc>"`
+
+> ⚠️ Chuỗi này phải **có thật** trong PRD hoặc tech-doc của **chính feature này**. Chưa chốt →
+> để trống + gắn `🚫 Block: [GAP-UC{N}-{nnn}](../DOC_GAP.md)`, **đừng bịa oracle**.
+
+*Mỗi field bắt buộc là một cặp TC như trên. Field có ràng buộc độ dài/khoảng giá trị → thêm TC
+BVA riêng, số giá trị biên tra ở `../shared/precision-rules.md` §7.*
+
+---
+
+## Nhóm ca 3 — Auth: không có token
+
+### TC_<FEATURE>_006 — thiếu Authorization header trả về 401
+
+- **Priority:** P0
+- **Tags:** api, negative, auth, security
+- **Trace:** BR-xx
+
+#### Test Data
+- Method: <METHOD>
+- Path: `<path>`
+- Headers: Content-Type: application/json — **bỏ hẳn** `Authorization`
+
+#### Test Steps
+1. **[Action]** Gửi `<METHOD> <path>` không kèm header `Authorization`.
+2. **[Verify]** Đọc status code.
+
+#### Expected Result
+- HTTP 401
+
+*Biến thể theo `common-headers.md` §"TC Negative liên quan header": token sai định dạng → 401 ·
+`Content-Type` sai → 400 hoặc 415. Mỗi cái một TC.*
+
+---
+
+## Nhóm ca 4 — Auth: đúng token, sai quyền
+
+### TC_<FEATURE>_007 — token role `<wrong_role>` trả về 403
+
+- **Priority:** P0
+- **Tags:** api, negative, auth, security
+- **Trace:** BR-xx
+
+#### Test Data
+- Headers: Authorization: Bearer `<valid_token_<wrong_role>>`
+
+#### Test Steps
+1. **[Action]** Gửi `<METHOD> <path>` bằng token của role không được phép.
+2. **[Verify]** Đọc status code.
+
+#### Expected Result
+- HTTP 403
+
+> **401 vs 403 là hai chuyện khác nhau** — 401 = chưa xác thực được anh là ai; 403 = biết anh
+> là ai nhưng anh không được phép. Trộn hai cái là bỏ mất một lớp bảo mật khỏi phạm vi test.
+
+---
+
+## Nhóm ca 5 — Not found
+
+### TC_<FEATURE>_008 — ID không tồn tại trả về 404
+
+- **Priority:** P1
+- **Tags:** api, negative, not-found
+- **Trace:** BR-xx
+
+#### Test Data
+- Method: <GET|PUT|DELETE>
+- Path: `<base_path>/<nonexistent_id>` (vd `/api/v1/courses/999999`)
+- Headers: Authorization: Bearer `<valid_token_<role>>`
+
+#### Test Steps
+1. **[Action]** Gửi `<METHOD>` với ID chắc chắn không tồn tại trong hệ thống.
+2. **[Verify]** Đọc status code.
+
+#### Expected Result
+- HTTP 404
+
+---
+
+## Nhắc lại ba luật hay bị bỏ
+
+1. **Placeholder có tên rõ nghĩa** — `<valid_token_admin>`, `<expired_token>`,
+   `<token_wrong_role>`; **không** dùng `<token>` chung chung *(`common-headers.md` §Quy ước)*.
+2. **`#### Teardown` là section riêng, KHÔNG phải bullet của Expected Result.** TC tạo bản ghi
+   thật thì bắt buộc có; TC chỉ GET hoặc chỉ cấu hình mock thì **không cần**.
+3. **Mọi TC tách vẫn giữ FULL Test Steps** — lặp đủ bước để tới trạng thái assert. Không cắt
+   bước theo từng bullet, không đánh `(1/N)`, không hậu tố `001a`/`001b`.

package/core/skills/qc/qa-designer/api/http-status-codes.md

@@ -0,0 +1,102 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/api-testcase-designer/api/references/http-status-codes.md
+upstream_sha: a82baa99350f63955245764a6aa57c9dca6d055f
+---
+# Bảng tra cứu — HTTP Status Codes
+
+Dùng để điền chính xác mã lỗi vào cột Expected của TC API.
+Tra theo nhóm (2xx/4xx/5xx) hoặc theo tình huống.
+
+---
+
+## 2xx — Thành công
+
+| Mã | Tên | Dùng khi | Expected điển hình |
+|---|---|---|---|
+| 200 | OK | GET, PUT thành công; login | Body chứa data/resource |
+| 201 | Created | POST tạo bản ghi mới | Body chứa `id` + resource mới |
+| 204 | No Content | DELETE thành công; PUT không trả body | Body rỗng |
+
+---
+
+## 4xx — Lỗi phía client
+
+| Mã | Tên | Dùng khi | Expected điển hình |
+|---|---|---|---|
+| 400 | Bad Request | Body/params sai format, thiếu field bắt buộc, giá trị không hợp lệ | `body.message` hoặc `body.errors` mô tả field lỗi |
+| 401 | Unauthorized | Không có token, token hết hạn, token sai | `body.message` = "Unauthorized" hoặc "Token invalid/expired" |
+| 403 | Forbidden | Token hợp lệ nhưng không đủ quyền (sai role) | `body.message` = "Forbidden" hoặc "Access denied" |
+| 404 | Not Found | Resource ID không tồn tại | `body.message` = "Not found" |
+| 409 | Conflict | Tạo trùng bản ghi (unique constraint) | `body.message` mô tả field trùng |
+| 422 | Unprocessable Entity | Business rule validation (vd: ngày end < ngày start) | `body.errors` liệt kê vi phạm |
+| 429 | Too Many Requests | Vượt rate limit | `Retry-After` header; body thông báo limit |
+
+---
+
+## 5xx — Lỗi phía server (không test chủ động; ghi vào TC edge nếu plan đề cập)
+
+| Mã | Tên | Ghi chú |
+|---|---|---|
+| 500 | Internal Server Error | Không nên trigger trong test bình thường; ghi vào TC nếu plan có scenario |
+| 503 | Service Unavailable | Chỉ test trong integration/availability scope |
+
+---
+
+## Mapping tình huống → mã (LMS Edupia)
+
+| Tình huống | Mã kỳ vọng | Ghi chú |
+|---|---|---|
+| Login đúng | 200 | Body có `access_token` |
+| Login sai password | 401 hoặc 400 | Xác nhận lại với dev |
+| Tạo mới thành công | 201 | Body có `id` |
+| Lấy danh sách | 200 | Body có `data[]` + `pagination` |
+| Lấy 1 record hợp lệ | 200 | Body có đầy đủ fields |
+| Xóa thành công | 200 hoặc 204 | Xác nhận lại với dev |
+| Field bắt buộc để trống | 400 | `body.errors` có field name |
+| Vượt độ dài tối đa | 400 | `body.errors` có field name + giới hạn |
+| Format sai (email/phone) | 400 | `body.errors` mô tả format |
+| Token không có | 401 | — |
+| Token hết hạn | 401 | — |
+| Role không đủ quyền | 403 | — |
+| ID không tồn tại | 404 | — |
+| Tên/code trùng | 409 | Xác nhận field unique với dev |
+| Ngày end trước ngày start | 422 | Business rule validation |
+
+---
+
+## Cấu trúc body lỗi chuẩn (tham khảo)
+
+```json
+// 400 / 422 — validation error
+{
+  "statusCode": 400,
+  "message": "Validation failed",
+  "errors": [
+    { "field": "name", "message": "Trường này là bắt buộc" },
+    { "field": "startDate", "message": "Ngày bắt đầu không được để trống" }
+  ]
+}
+
+// 401 — unauthorized
+{
+  "statusCode": 401,
+  "message": "Unauthorized"
+}
+
+// 403 — forbidden
+{
+  "statusCode": 403,
+  "message": "Forbidden resource"
+}
+
+// 404 — not found
+{
+  "statusCode": 404,
+  "message": "Resource not found"
+}
+```
+
+> Cấu trúc thực tế có thể khác — xác nhận với dev/API spec trước khi điền vào TC.

package/core/skills/qc/qa-designer/e2e/journey.md

@@ -17,11 +17,14 @@ Skill **tự chứa** để viết TC end-to-end: hành trình đầu→cuối x
 
 ---
 
-## 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 (tài khoản/role, dữ liệu lớp/buổi…) · **Steps** `[Action]`/`[Verify]` xuyên các màn ·
-  **Expected** 1 bullet = chuỗi verify point (tạo thành công, mã đúng, định tuyến đúng, đồng bộ đúng, hiển thị danh sách).
-- ID journey `E2E-<FEATURE>-NN` · 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
 - **Use Case/Scenario:** mỗi journey = main + alternate + exception flow.
@@ -34,8 +37,10 @@ Lấy danh sách journey + trục bao phủ + verify points từ TEST_PLAN · m
 
 ## Phase 2 — Write
 Mỗi journey → 1 TC bám Format; Expected = chuỗi verify point; chuẩn bị tiền điều kiện & cleanup, mỗi journey độc lập.
-**Journey phụ thuộc gap vẫn viết + 🚫 Block: GAP-xx**, định tuyến ghi "dự kiến theo BR". Trace BR.
+**Journey phụ thuộc gap vẫn viết + 🚫 Block: [GAP-UC{N}-{nnn}]**, định tuyến ghi "dự kiến theo BR". Trace BR.
 
 ## Output
-File TC e2e (hoặc nhóm E2E trong file feature) trong `{qc_artifact_dir}test-cases/`.
-In bảng `E2E-ID | Journey | Pri | Trace | Block` + bảng TC block. Bàn giao `qa-reviewer`.
+
+Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` — **Nhóm 6 E2E**. Mỗi journey một TC; tiền điều kiện · kết quả/định tuyến kỳ vọng · BR · phụ thuộc gap · priority ghi dạng trường danh sách.
+
+**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/exploratory/charter.md

@@ -66,3 +66,5 @@ Sinh 10-15 câu hỏi cho dev/BA (assumptions, edge case, error handling, securi
 Charter files: {paths.qc_dir}/exploratory/charters/<feature>_01.md, _02.md...
 Ideas file: {paths.qc_dir}/exploratory/ideas/<feature>.md
 Bảng tổng kết: STT | Charter | Tour | Risk | Time-box
+
+*(Charter KHÔNG phải file TC — luật "không bảng" chỉ áp cho `*.Test.md`. Charter chuyển thành TC ở `explore-to-functional.md`, lúc đó mới theo luật đó.)*

package/core/skills/qc/qa-designer/exploratory/explore-to-functional.md

@@ -32,12 +32,15 @@ So requirement vs draft: requirement chưa phủ → thêm TC · TC sai logic
 chỉnh Priority theo business. Không có requirement → giữ draft Phase 2.
 
 ## Phase 4 — Convert to Functional (format chuẩn)
-Chuyển draft → TC chính thức bám **format file `TC_<FEATURE>.md`**:
+Chuyển draft → TC chính thức bám **format file `TC_<FEATURE>.Test.md`**:
 - Metadata **list**: Title · Feature · Priority(P0/P1/P2) · Status(Draft) · Author(AI) · Tags ·
-  **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có BR → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx]` nếu chặn.
+  **Trace** `[BR-xx](../REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có BR → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-UC{N}-{nnn}]` nếu chặn.
 - **Test Data** dạng list · **Steps** `[Action]`/`[Verify]` · **Expected** 1 bullet cụ thể.
 - Phân nhóm GUI/Functional · cuối file: Trace matrix + bảng TC block · bỏ nội dung gạch ngang.
-- Đặt file `{qc_artifact_dir}test-cases/TC_<FEATURE>.md`.
+- Đặt file `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` (nhóm 3 Functional).
 
 ## Output
-File TC functional + bảng `TC_ID | Title | Priority | Technique | Trace`. Bàn giao `qa-reviewer`.
+
+Ghi TC đã chuyển thành functional vào `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` — **Nhóm 3 Functional**.
+
+**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/functional/api.md

@@ -1,13 +1,15 @@
 ---
 version: 1.0
-updated: 2026-06-11
+updated: 2026-09-04
 ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/api-testcase-designer.md
+upstream_sha: 211c18728baf029a7572f0ffb161e92a933fa8fb
 ---
 
 # Test Case — Functional API (không qua UI)
 
-Skill **tự chứa** để viết TC kiểm thử một API endpoint ở mức chức năng (request → response).
-Chỉ cần load file này.
+Viết TC kiểm thử một API endpoint ở mức chức năng (request → response).
+Nạp cùng `shared/` (khuôn + độ chính xác + từ điển hành động) và `../api/` (mẫu + bảng tra).
 
 ## Khi nào trigger
 - "viết test case cho API [method] [path]" — verify contract, validation, mã lỗi của endpoint
@@ -18,28 +20,95 @@ Chỉ cần load file này.
 
 ---
 
-## Format file `TC_<FEATURE>.md` (bắt buộc)
-- 1 file/feature · mỗi TC **1 concept** · metadata **list** (không bảng/emoji): Title · Feature ·
-  Priority(P0/P1/P2) · Status(Draft) · Author(AI) · Tags · Trace · 🚫 Block(nếu có).
-- **Trace:** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)`; không có BR → `⚠️ Chưa có Business Rule`.
-- **🚫 Block:** TC phụ thuộc gap vẫn viết đủ + `[GAP-xx](DOC_GAP.md) — lý do`.
-- **Test Data:** dạng **list** (request cụ thể: method/path/headers/body). **Steps:** `[Action]`/`[Verify]`.
-  **Expected:** 1 bullet nêu rõ **status code + field response cần chốt** (không ✅/❌).
-- Cuối file: **Trace matrix** (BR↔TC, ⚠️ TC thiếu BR) + **bảng TC bị block** · bỏ nội dung gạch ngang.
+## Format file TC
 
-## Kỹ thuật áp dụng
-- Mỗi field request → **EP** (phân vùng valid/invalid) + **BVA** (biên độ dài/giá trị).
-- Tổ hợp điều kiện (auth × param × state) → **Decision Table**.
+> **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ừ).
+
+## Đầu vào — sáu trường bắt buộc cho mỗi endpoint
+
+Trước khi viết TC, mỗi endpoint phải biết đủ **sáu** thứ. Thiếu bất kỳ trường nào → **hỏi, đừng đoán**:
+
+| # | Trường | Lấy ở đâu |
+|---|---|---|
+| 1 | Endpoint (method + path) | tech-doc gộp §4 Hợp đồng API |
+| 2 | Auth / role được phép | §4 + PRD phần phân quyền |
+| 3 | Schema request (field · kiểu · bắt buộc · ràng buộc) | §4 |
+| 4 | Response thành công (mã + schema) | §4 |
+| 5 | **Các mã lỗi** và body lỗi | §4 + §8 Xử lý lỗi & biên |
+| 6 | Side-effect (ghi DB, phát event) | §6 Điểm tích hợp |
+
+Trường 5 và 6 là hai chỗ hay thiếu nhất. Thiếu 5 → không viết được nhóm negative. Thiếu 6 →
+side-effect không ai verify, và lỗi mất dữ liệu lọt qua toàn bộ dây chuyền.
+
+## Kỹ thuật ISTQB cho tầng API *(CTFL v4.0)*
+
+| Tình huống | Kỹ thuật |
+|---|---|
+| Tham số có kiểu / phạm vi / định dạng | **EP + BVA** |
+| Tổ hợp điều kiện (quyền × trạng thái × input) | **Decision Table** |
+| Spec mỏng, nghi có lỗi tiềm ẩn | **Error Guessing** |
+
+- **EP/BVA từng tham số**: valid + invalid (thiếu · sai kiểu · vượt biên · rỗng · quá dài).
+  Mỗi phân vùng một TC. Số giá trị biên (3 hay 4) tra `../shared/precision-rules.md` §7.
+- **Decision Table cho phân quyền**: điều kiện = (role, sở hữu resource, trạng thái resource)
+  → hành động = mã trạng thái. **Mỗi rule một TC**, kể cả rule mà kết quả là "không làm gì".
+- **Error Guessing theo mã trạng thái** — phủ đủ mã **áp dụng được** cho endpoint đó:
+
+| Mã | Khi nào |
+|---|---|
+| 400 | thiếu / sai tham số |
+| 401 | thiếu hoặc sai token |
+| 403 | đúng token, sai quyền |
+| 404 | resource không tồn tại |
+| 409 | trùng giá trị unique |
+| 422 | validate nghiệp vụ (đúng định dạng, sai luật) |
+| 5xx | lỗi hệ thống / dịch vụ phụ thuộc |
+
+Bảng đầy đủ + nghĩa trong ngữ cảnh: `../api/http-status-codes.md`. **401 ≠ 403** — trộn hai cái
+là bỏ mất một lớp bảo mật khỏi phạm vi test.
+
+## Thứ tự viết
+
+**1. Positive → 2. Negative → 3. Edge → 4. Implicit.**
+
+Bước 4 nạp `../shared/implicit-scenarios.md` — 7 tình huống bắt buộc nghĩ tới (rate limit ·
+đồng thời · hết hạn phiên · trạng thái rỗng · dữ liệu tối đa · ký tự đặc biệt · ghi log).
+Áp cho **mọi** nhóm TC, không riêng nhóm edge.
+
+**Trước khi viết TC mới**: nạp `../shared/duplicate-check-procedure.md` — grep từ khoá trong file
+TC hiện có. Một TC "email đã tồn tại" có thể đã nằm ở nhóm Validation của file giao diện.
+
+## Năm luật chất lượng *(để reviewer không phải trả lại)*
+
+1. **Title ≤ 60 ký tự**, nêu được cả tình huống lẫn kết quả.
+2. **Test Steps ≥ 2 bước.** Chỉ một hành động → thêm bước `[Verify]` quan sát kết quả.
+3. **Expected Result đo được** — cấm cụm mơ hồ. Phép thử: *hai QC đọc có ra cùng một kết luận
+   pass/fail không?* Danh sách 9 cụm bị cấm: `../shared/precision-rules.md` §1.
+4. **Test Data ghi note kỹ thuật**: `EP: valid`, `BVA: biên trên`, `DT: rule 3`.
+5. **Priority có nghĩa cố định**: P0 = chặn phát hành · P1 = smoke · P2 = regression.
 
 ## Phase 1 — Clarify
 Endpoint (method/path/auth/role/content-type) · request (path/query/body schema: field, kiểu, bắt buộc, ràng buộc) ·
 response (schema thành công + các mã lỗi 4xx/5xx + body lỗi) · side-effect (nếu cần verify → cân nhắc `integration/api`).
 
+*Có `TEST_PLAN.md` đủ sáu trường trên → bỏ qua Phase 1, sang thẳng Phase 2.*
+
 ## Phase 2 — Write
-- Nhóm TC: happy (200 + schema đúng) → validation (400 từng field, dùng EP/BVA) → auth (401/403)
+- Nhóm TC: happy (mã thành công + schema) → validation (400 từng field, EP/BVA) → auth (401/403)
   → not found (404) → edge (payload lớn, ký tự đặc biệt, rate limit).
-- Mỗi TC bám khối Format; Expected ghi status code + phần body verify; trace BR; gap chặn → 🚫 Block.
+- Mỗi TC bám mẫu `../api/endpoint.md`; chuỗi nhiều bước bám `../api/auth-chain.md`.
+- **Không hardcode URL / thông tin đăng nhập.** Placeholder có tên rõ nghĩa
+  (`<valid_token_admin>`, không phải `<token>`).
 
 ## Output
-File TC (`TC_<FEATURE>_API.md` hoặc gộp trong file feature) trong `{qc_artifact_dir}test-cases/`.
-In bảng TC + Trace matrix. Bàn giao `qa-reviewer`.
+
+Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>_API.Test.md` — **Nhóm 1 Endpoint**.
+
+File này chỉ sinh khi có cờ `--api` hoặc `--all`. Mẫu TC: `../api/endpoint.md` · chuỗi auth: `../api/auth-chain.md` · tra mã: `../api/http-status-codes.md` · header: `../api/common-headers.md`.
+
+**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/functional/gui-feature.md

@@ -18,13 +18,14 @@ Skill **tự chứa** để viết TC functional cho feature có luồng span
 
 ---
 
-## Format file `TC_<FEATURE>.md` (bắt buộc)
-- 1 file/feature · mỗi TC **1 concept** · metadata **list** (không bảng/emoji): Title · Feature ·
-  Priority(P0/P1/P2) · Status(Draft) · Author(AI) · Tags · Trace · 🚫 Block(nếu có).
-- **Trace:** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)`; không có BR → `⚠️ Chưa có Business Rule`.
-- **🚫 Block:** TC phụ thuộc gap vẫn viết đủ + `[GAP-xx](DOC_GAP.md) — lý do`.
-- **Test Data:** dạng **list** (không bảng). **Steps:** `[Action]`/`[Verify]`, không `*Expected:*`/bước. **Expected:** 1 bullet cụ thể.
-- Cuối file: **Trace matrix** (BR↔TC, ⚠️ TC thiếu BR) + **bảng TC bị block** · không `#### Python Test Mapping` · 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
 - **Use Case** cho flow tổng: main (P0) → alternate (P1) → exception (negative).
@@ -42,5 +43,7 @@ Liệt kê các màn/route + thứ tự điều hướng · state/dữ liệu tr
 - Mỗi TC bám khối Format; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File `TC_<FEATURE>.md` trong `{qc_artifact_dir}test-cases/`. In bảng TC + Trace matrix + bảng TC block.
-Bàn giao `qa-reviewer` (test-case).
+
+Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` — **Nhóm 3 Functional** (luồng đa màn trong cùng một feature).
+
+**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/functional/gui-screen.md

@@ -18,14 +18,14 @@ Skill **tự chứa** để viết TC functional cho 1 màn hình đơn lẻ (we
 
 ---
 
-## Format file `TC_<FEATURE>.md` (bắt buộc)
-- 1 file/feature · mỗi TC **1 concept** · metadata **list** (mỗi trường 1 dòng, không bảng/emoji):
-  Title · Feature · Priority(P0/P1/P2) · Status(Draft) · Author(AI) · Tags · Trace · 🚫 Block(nếu có).
-- **Trace:** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)`; TC không có BR → `⚠️ Chưa có Business Rule`.
-- **🚫 Block:** TC phụ thuộc gap **vẫn viết đủ** + `[GAP-xx](DOC_GAP.md) — lý do`; chưa chạy tới khi gap Answered.
-- **Test Data:** dạng **list** (`- **Trường:** giá trị`), không bảng.
-- **Test Steps:** `**[Action]**` / `**[Verify]**`, KHÔNG `- *Expected:*` sau bước. **Expected:** 1 bullet cụ thể (không ✅/❌).
-- Phân nhóm GUI/Functional · cuối file: **Trace matrix** (BR↔TC, ⚠️ TC thiếu BR) + **bảng TC bị block** · KHÔNG `#### Python Test Mapping` · 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
 - Field có ràng buộc (độ dài/số/ngày) → **EP** (mỗi phân vùng 1 TC, tag `ep`) + **BVA** (4 TC min−1/min/max/max+1, tag `bva`).
@@ -48,5 +48,7 @@ chức năng (input/action/display/nav) · constraint (required/min-max/format/e
 - Mỗi TC bám khối Format trên; trace BR; TC chặn bởi gap → 🚫 Block.
 
 ## Output
-File `TC_<FEATURE>.md` trong `{qc_artifact_dir}test-cases/`. In bảng `TC_ID | Title | Priority | Tags | Trace`
-+ Trace matrix + bảng TC block. Bàn giao `qa-reviewer` (test-case).
+
+Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` — **Nhóm 1 GUI** · **Nhóm 2 Validation** · **Nhóm 3 Functional**.
+
+**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/api.md

@@ -19,10 +19,14 @@ verify luồng dữ liệu & contract giữa các thành phần. Chỉ cần loa
 
 ---
 
-## 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)` (TC chặn vẫn viết đủ).
-- **Test Data** dạng list · **Steps** `[Action]`/`[Verify]` · **Expected** 1 bullet nêu rõ chặng verify (response/bản ghi/event).
-- 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
 - **Interface/Contract:** verify schema request/response giữa caller↔callee.
@@ -39,4 +43,7 @@ Nhóm TC: happy (dữ liệu đúng đầu→cuối) → contract negative (inpu
 → concurrency → điều kiện đồng bộ (đổ/không đổ). Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC integration trong `{qc_artifact_dir}test-cases/`. Ưu tiên P0 cho định tuyến & tiền-dữ liệu. 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**. Ưu tiên P0 cho định tuyến & tiền-dữ liệu. Chuỗi gọi phụ thuộc nhau: `../api/crud-sequence.md`.
+
+**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`.