@educa-corp/sdd-framework 0.9.2 → 0.9.4

package/core/skills/qc/qa-analyst/DOC_GAP.template.md

@@ -13,13 +13,18 @@ upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
 > **Một chỗ CỐ Ý khác upstream:** mức nặng nhất dùng từ **`Blocker`**, không phải `Critical`.
 > Lý do: `/qc-run-test` đọc `🔴 Blocker` để đặt *"scenario đang chờ PO"* vào sổ kết quả trace.
 > Đổi từ là đứt liên kết đó. Ba mức còn lại giữ nguyên upstream.
+>
+> **Phạm vi: MỘT file cho cả (PRD × nền)** *(B11)*, không phải một file mỗi UC. Đây là quay về
+> đúng thiết kế upstream — chính ID `GAP-<UC>-…` của bản gốc chỉ có nghĩa khi một file chứa
+> nhiều UC, và file thật của đội QC (`DOC_GAP_FEAT-02-3.md`) cũng không có hậu tố UC. Đường
+> dẫn: `{paths.qc_dir}/{TICKET-ID}/{platform}/DOC_GAP.md`.
 
-# DOC GAP -- <UC>: <Tên UC>
+# DOC GAP -- <TICKET-ID> / <nền>: <Tên feature>
 
 | Trường | Giá trị |
 |---|---|
-| Feature | `<FEATURE>` |
-| UC | `<UC> — <Tên UC>` |
+| Feature | `<TICKET-ID>` — `<Tên feature>` |
+| Nền (platform) | `<web \| app \| system>` |
 | Tài liệu nguồn | `<đường dẫn PRD>` · `<đường dẫn BDD nếu có>` · `<các file inputs/ liên quan>` |
 | Ngày phân tích | `<YYYY-MM-DD>` |
 | Tổng số gap | `<N>` (Blocker: x · High: y · Medium: z · Low: w) |
@@ -27,6 +32,21 @@ upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
 
 ---
 
+## Phạm vi phân tích
+
+> **Một file gap phủ CẢ PRD** — mỗi UC là các hàng trong bảng gap, phân biệt bằng cột `UC`.
+> Bảng dưới là **căn cứ độ phủ**: nó phân biệt *"đã xét, không thấy gap"* với *"chưa xét"*.
+> UC nào có BDD chưa `approved` thì ghi `⏸ Chưa xét` — **KHÔNG bỏ khỏi bảng**.
+
+| UC | Tên UC | `@trace.status` | Đã phân tích? | Số gap |
+|---|---|---|---|---|
+| `<UC-ID>` | … | `approved` | ✅ | `<n>` |
+| `<UC-ID>` | … | `draft` | `⏸ Chưa xét` | — |
+
+**Trong phạm vi: `<n>`/`<N>` UC.** Chưa xét: `<danh sách UC-ID>` — chạy lại sau khi BDD được duyệt, hoặc `--include-draft` để xét luôn bản nháp.
+
+---
+
 ## Tài liệu đầu vào đã đọc để phân tích
 
 > Liệt kê **đầy đủ** mọi file đã đọc để dựng phân tích gap (spec chính + mọi ref-link + transitive 1-hop). Đây là căn cứ độ phủ — mọi file đã mở đều phải có mặt, KHÔNG bỏ sót. Đường dẫn tính từ `{paths.specs_dir}`.
@@ -41,9 +61,14 @@ upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
 
 ---
 
-| ID | Loại | Vấn đề cần confirm | Câu hỏi / Lý do cần confirm & Gợi ý | Trích đoạn tài liệu (Evidence) | Giao cho đội | Mức độ | Người trả lời | Trạng thái | Câu trả lời |
-|---|---|---|---|---|---|---|---|---|---|
-| GAP-<UC>-001 | MISSING / AMBIGUOUS / CONTRADICTORY / ASSUMPTION | Tiêu đề ngắn mô tả vấn đề | **Bối cảnh:** Ngữ cảnh dẫn đến gap này.<br/>**Vấn đề:** Điều gì chưa được spec hoặc mâu thuẫn.<br/>**Tại sao quan trọng:** Hậu quả nếu không làm rõ.<br/>**Gợi ý:** Ai cần làm gì để giải quyết. | `<đường dẫn file spec>` `<TÊN-BR hoặc AC gốc trong PRD, ví dụ FEAT-01-2-UC4-BR11>`: trích nguyên văn | Dev / PO / BA / Design | 🔴 Blocker | | Open | |
+> **ID gap mang UC** — `GAP-UC{N}-{nnn}` (vd `GAP-UC1-001`). Gap thuộc **cả PRD**, không riêng
+> UC nào → `GAP-GEN-{nnn}`. Đánh số **độc lập trong từng UC**: chạy lại phân tích cho UC1
+> KHÔNG được làm đổi số gap của UC2 — test case đã có đang trỏ `🚫 Block: [GAP-UC2-003]`, đổi
+> số là đứt liên kết đó trong im lặng.
+
+| ID | UC | Loại | Vấn đề cần confirm | Câu hỏi / Lý do cần confirm & Gợi ý | Trích đoạn tài liệu (Evidence) | Giao cho đội | Mức độ | Người trả lời | Trạng thái | Câu trả lời |
+|---|---|---|---|---|---|---|---|---|---|---|
+| GAP-UC1-001 | `<UC-ID>` | MISSING / AMBIGUOUS / CONTRADICTORY / ASSUMPTION | Tiêu đề ngắn mô tả vấn đề | **Bối cảnh:** Ngữ cảnh dẫn đến gap này.<br/>**Vấn đề:** Điều gì chưa được spec hoặc mâu thuẫn.<br/>**Tại sao quan trọng:** Hậu quả nếu không làm rõ.<br/>**Gợi ý:** Ai cần làm gì để giải quyết. | `<đường dẫn file spec>` `<TÊN-BR hoặc AC gốc trong PRD, ví dụ FEAT-01-2-UC4-BR11>`: trích nguyên văn | Dev / PO / BA / Design | 🔴 Blocker | | Open | |
 
 ---
 
@@ -51,13 +76,15 @@ upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
 
 | Mức độ | Gap ID |
 |---|---|
-| 🔴 Blocker | GAP-<UC>-00x · ... |
-| 🟠 High | GAP-<UC>-00x · ... |
-| 🟡 Medium | GAP-<UC>-00x · ... |
-| ⚪ Low | GAP-<UC>-00x · ... |
+| 🔴 Blocker | GAP-UC1-00x · GAP-UC3-00x · ... |
+| 🟠 High | GAP-UC2-00x · ... |
+| 🟡 Medium | GAP-UC1-00x · ... |
+| ⚪ Low | GAP-GEN-00x · ... |
+
+*Xếp theo mức độ trước, KHÔNG theo UC — người đọc cần biết "chặn gì" trước "chặn ở đâu".*
 
 **Cần chốt trước khi viết test case:**
-- GAP-<UC>-00x: <lý do block>
+- GAP-UC1-00x (`<UC-ID>`): <lý do block>
 
 ---
 
@@ -99,16 +126,19 @@ upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
 Trước khi lưu file gap, kiểm tra **từng hàng** trong bảng gap:
 
 - [ ] **Có section `Tài liệu đầu vào đã đọc để phân tích`** – bảng liệt kê **đầy đủ** mọi file đã đọc (spec chính + ref-link + transitive 1-hop), có đường dẫn `{paths.specs_dir}`, vai trò, phiên bản; ghi tổng số + trạng thái lane API. KHÔNG bỏ sót file nào đã mở.
-- [ ] **10 cột đủ** – đúng thứ tự: `ID | Loại | Vấn đề cần confirm | Câu hỏi / Lý do cần confirm & Gợi ý | Trích đoạn tài liệu (Evidence) | Giao cho đội | Mức độ | Người trả lời | Trạng thái | Câu trả lời`
-- [ ] **Cột 3 = `Vấn đề cần confirm`** – KHÔNG viết tắt thành `Vấn đề`
-- [ ] **Cột 4 = `Câu hỏi / Lý do cần confirm & Gợi ý`** – bắt buộc có đủ 4 phần, tách bằng `<br/>`:
+- [ ] **Có section `Phạm vi phân tích`** – bảng mỗi UC một hàng kèm `@trace.status` + Đã phân tích? + Số gap. UC chưa duyệt vẫn có hàng, ghi `⏸ Chưa xét`. Thiếu bảng này thì không ai phân biệt được *"đã xét, không thấy gap"* với *"chưa xét"*.
+- [ ] **11 cột đủ** – đúng thứ tự: `ID | UC | Loại | Vấn đề cần confirm | Câu hỏi / Lý do cần confirm & Gợi ý | Trích đoạn tài liệu (Evidence) | Giao cho đội | Mức độ | Người trả lời | Trạng thái | Câu trả lời`
+- [ ] **Cột 2 = `UC`** – mã UC đầy đủ (`<TICKET-ID>-UC{N}`), hoặc `— (toàn PRD)` cho gap `GAP-GEN-`. Mọi UC có gap phải khớp một hàng `✅` ở bảng *Phạm vi phân tích*.
+- [ ] **ID dạng `GAP-UC{N}-{nnn}`** (hoặc `GAP-GEN-{nnn}`) – KHÔNG dùng `GAP-01` phẳng: số phẳng sẽ bị đánh lại khi phân tích lại một UC, làm đứt `🚫 Block: [GAP-UC1-001]` trong test case đã có.
+- [ ] **Cột 4 = `Vấn đề cần confirm`** – KHÔNG viết tắt thành `Vấn đề`
+- [ ] **Cột 5 = `Câu hỏi / Lý do cần confirm & Gợi ý`** – bắt buộc có đủ 4 phần, tách bằng `<br/>`:
   ```
   **Bối cảnh:** ...<br/>**Vấn đề:** ...<br/>**Tại sao quan trọng:** ...<br/>**Gợi ý:** ...
   ```
   Không viết 4 mục liên tiếp trên cùng một dòng.
-- [ ] **Cột 5 = `Trích đoạn tài liệu (Evidence)`** – KHÔNG viết tắt thành `Evidence`; dẫn nguyên văn + đường dẫn file `{paths.specs_dir}`; **dùng PRD source ID** (ví dụ `FEAT-01-2-UC4-BR11`), KHÔNG dùng internal analysis ID (ví dụ `BR-UC4-12`)
-- [ ] **Cột Mức độ** (cột 7) – bắt buộc dùng emoji: `🔴 Blocker` / `🟠 High` / `🟡 Medium` / `⚪ Low`. Không được ghi text thuần.
-- [ ] **Cột Giao cho đội** (cột 6) – dùng: `Dev` / `PO` / `BA` / `Design` / `Architect` / `Analytics` hoặc kết hợp. Nếu thấy "Open" ở đây → đang bị lệch cột.
+- [ ] **Cột 6 = `Trích đoạn tài liệu (Evidence)`** – KHÔNG viết tắt thành `Evidence`; dẫn nguyên văn + đường dẫn file `{paths.specs_dir}`; **dùng PRD source ID** (ví dụ `FEAT-01-2-UC4-BR11`), KHÔNG dùng internal analysis ID (ví dụ `BR-UC4-12`)
+- [ ] **Cột Mức độ** (cột 8) – bắt buộc dùng emoji: `🔴 Blocker` / `🟠 High` / `🟡 Medium` / `⚪ Low`. Không được ghi text thuần.
+- [ ] **Cột Giao cho đội** (cột 7) – dùng: `Dev` / `PO` / `BA` / `Design` / `Architect` / `Analytics` hoặc kết hợp. Nếu thấy "Open" ở đây → đang bị lệch cột.
 - [ ] **Cột Người trả lời = vai trò** (PO / BA / Dev / Design / ...). Nếu thấy "Open" ở đây → đang bị lệch cột.
 - [ ] **Cột Trạng thái** = `Open` / `Resolved` / `Out of Scope` / `Re-scoped → Covered`
 - [ ] **Trạng thái chung** trong metadata có emoji: `🔴 Blocked` / `🟠 Cần làm rõ` / `🟢 Đủ rõ để thiết kế TC`

package/core/skills/qc/qa-analyst/acceptance-criteria.md

@@ -53,7 +53,7 @@ Mỗi AC gắn mã trace: chức năng + BR-xx để TC sau này map 1-1.
 
 ## Output
 
-Ghi vào **mục Acceptance Criteria** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`
+Ghi vào **mục Acceptance Criteria** của `{qc_artifact_dir}REQUIREMENT_ANALYSIS.md`
 (KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`):
 
 - Danh sách AC dạng Given/When/Then, có mã trace về chức năng, business rule (BR-xx)

package/core/skills/qc/qa-analyst/business-rules.md

@@ -83,11 +83,11 @@ Với rule có nhiều điều kiện kết hợp → gợi ý dựng **Decision
 
 ## Output
 
-Ghi vào **mục Business Rules** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`
+Ghi vào **mục Business Rules** của `{qc_artifact_dir}REQUIREMENT_ANALYSIS.md`
 (KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`):
 
 - Bảng business rule có ID (BR-xx) để TC trace ngược về.
 - Gợi ý các rule cần Decision Table / BVA khi sang qa-designer.
 
-Rule MÂU THUẪN / KHÔNG RÕ → ghi vào `{paths.qc_dir}/{UC-ID}/DOC_GAP.md`
+Rule MÂU THUẪN / KHÔNG RÕ → ghi vào `{qc_artifact_dir}DOC_GAP.md`
 (loại CONTRADICTORY / AMBIGUOUS, cột "Ảnh hưởng" trỏ BR-xx).

package/core/skills/qc/qa-analyst/data-flow.md

@@ -54,7 +54,7 @@ Thể hiện luồng dạng bước tuần tự hoặc sơ đồ text:
 
 ## Output
 
-Ghi vào **mục Data Flow** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`
+Ghi vào **mục Data Flow** của `{qc_artifact_dir}REQUIREMENT_ANALYSIS.md`
 (KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`):
 
 - Sơ đồ/list luồng dữ liệu cho mỗi kịch bản chính.
@@ -63,4 +63,4 @@ Ghi vào **mục Data Flow** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.
 - Dữ liệu/trạng thái cần chuẩn bị & cleanup → đầu vào fixture cho qa-runner.
 
 Chặng nào luồng/hành vi chưa rõ (vd lỗi xử lý ra sao, retry, partial commit) →
-ghi vào `{paths.qc_dir}/{UC-ID}/DOC_GAP.md` (loại MISSING / OPEN QUESTION).
+ghi vào `{qc_artifact_dir}DOC_GAP.md` (loại MISSING / OPEN QUESTION).

package/core/skills/qc/qa-analyst/spec-breakdown.md

@@ -29,7 +29,7 @@ Bóc tách spec/PRD/user story thô thành mô tả yêu cầu có cấu trúc c
    vào phân tích/BR/AC. Với file Confluence/HTML/MHTML: phát hiện qua thẻ `<s>`,
    `<strike>`, `<del>` hoặc style `text-decoration: line-through`.
 3. Xác định: feature name, actor/role, mục tiêu nghiệp vụ, phạm vi (in/out scope).
-4. Đánh dấu phần MƠ HỒ / THIẾU → ghi vào `DOC_GAP.md` (gap GAP-xx).
+4. Đánh dấu phần MƠ HỒ / THIẾU → ghi vào `DOC_GAP.md` (gap `GAP-UC{N}-{nnn}`; gap thuộc cả PRD → `GAP-GEN-{nnn}`).
 
 ---
 
@@ -49,7 +49,7 @@ F. GIẢ ĐỊNH & CÂU HỎI MỞ: điều suy ra được vs điều cần dev
 ## Output
 
 ⚠️ `/qc-analyze` chỉ ghi **ĐÚNG 2 FILE** cho mỗi UC, đặt trong thư mục QC **lộ ra ngoài**
-`{paths.qc_dir}/{UC-ID}/` (mặc định `docs/{UC-ID}/` — KHÔNG để trong `.agent/` ẩn):
+`{qc_artifact_dir}` (mặc định `docs/{TICKET-ID}/{platform}/` — gom theo **PRD**, KHÔNG để trong `.agent/` ẩn):
 `REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`. KHÔNG tách mỗi bước phân tích thành file riêng.
 
 Phần spec-breakdown là **mục đầu tiên** của `REQUIREMENT_ANALYSIS.md`:
@@ -57,7 +57,7 @@ Phần spec-breakdown là **mục đầu tiên** của `REQUIREMENT_ANALYSIS.md`
 - Sơ đồ/list luồng chính & phụ
 - Danh sách giả định và câu hỏi mở (đánh dấu rõ điều CHƯA chắc)
 
-Đồng thời ghi mọi khoảng trống phát hiện vào `{paths.qc_dir}/{UC-ID}/DOC_GAP.md`
-(theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md`), mỗi gap có ID `GAP-xx`.
+Đồng thời ghi mọi khoảng trống phát hiện vào `{qc_artifact_dir}DOC_GAP.md`
+(theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md`), mỗi gap có ID `GAP-UC{N}-{nnn}` — mã mang UC để phân tích lại một UC không đánh số lại UC khác.
 
 Kết thúc bằng gợi ý: feature đã đủ rõ để chuyển sang `qa-planner` (phân tích rủi ro) chưa.

package/core/skills/qc/qa-analyst/spec-issue-reporter.md

@@ -14,6 +14,9 @@ có cấu trúc, đủ thông tin để người nhận trả lời được nga
 > **`/qc-analyze` nạp file này** *(B9 — hợp nhất 2026-08-25)*. Nó là luật viết cho
 > `DOC_GAP.template.md` — template **duy nhất** của file gap. Bản 9 cột cũ đã bỏ.
 >
+> **Một file gap phủ CẢ PRD** *(B11)* — `{paths.qc_dir}/{TICKET-ID}/{platform}/DOC_GAP.md`,
+> mỗi UC là các hàng phân biệt bằng cột `UC`. Không còn một-file-mỗi-UC.
+>
 > **Một chỗ cố ý khác upstream:** mức nặng nhất dùng `🔴 Blocker`, không phải `Critical` —
 > `/qc-run-test` đọc đúng từ đó để đặt *"scenario đang chờ PO"* vào sổ trace.
 
@@ -38,8 +41,11 @@ Một file gap gồm:
    transitive 1-hop): `# | Đường dẫn | Vai trò | Phiên bản`, kèm tổng số.
    KHÔNG bỏ sót file nào đã mở — đây là **căn cứ độ phủ**: không có nó thì không ai phân biệt
    được *"đã đọc và không thấy"* với *"chưa đọc"*.
-2. **Bảng gap 10 cột**, đúng thứ tự:
-   `ID | Loại | Vấn đề cần confirm | Câu hỏi / Lý do cần confirm & Gợi ý | Trích đoạn tài liệu (Evidence) | Giao cho đội | Mức độ | Người trả lời | Trạng thái | Câu trả lời`
+2. **Bảng gap 11 cột**, đúng thứ tự:
+   `ID | UC | Loại | Vấn đề cần confirm | Câu hỏi / Lý do cần confirm & Gợi ý | Trích đoạn tài liệu (Evidence) | Giao cho đội | Mức độ | Người trả lời | Trạng thái | Câu trả lời`
+3. **Section `Phạm vi phân tích`** — BẮT BUỘC, giữa metadata và section trên. Mỗi UC của
+   (PRD × nền) một hàng, kèm `@trace.status` + đã phân tích chưa + số gap. UC có BDD chưa
+   `approved` **vẫn có hàng**, ghi `⏸ Chưa xét`.
 
 ## Quy tắc
 
@@ -56,6 +62,12 @@ Một file gap gồm:
   do bước phân tích tự đánh số lại (vd `BR-UC4-12`). Hai hệ ID khác nhau; trộn vào là người
   đọc không tra ngược được về PRD.
 - **Mức độ bắt buộc có emoji**: `🔴 Blocker` · `🟠 High` · `🟡 Medium` · `⚪ Low`.
+- **ID gap mang UC**: `GAP-UC{N}-{nnn}` (vd `GAP-UC1-001`); gap thuộc cả PRD → `GAP-GEN-{nnn}`.
+  Đánh số **độc lập trong từng UC** — phân tích lại UC1 KHÔNG được làm đổi số gap của UC2,
+  vì test case đã có đang trỏ `🚫 Block: [GAP-UC2-003]` và đổi số là đứt liên kết trong im lặng.
+  **Không dùng `GAP-01` phẳng.**
+- **Cột `UC`** ghi mã UC đầy đủ (`{TICKET-ID}-UC{N}`), hoặc `— (toàn PRD)` cho `GAP-GEN-`.
+  Mọi UC xuất hiện ở đây phải khớp một hàng `✅` trong bảng *Phạm vi phân tích*.
 - **Pipe trong cell**: escape thành `\|` (vd `{a\|b\|c}`), nếu không sẽ vỡ bảng.
 - **Thêm hàng vào bảng đã có**: nối **ngay liền sau hàng cuối**, TUYỆT ĐỐI không chèn dòng
   trắng giữa các hàng — dòng trắng làm Markdown tách thành hai bảng riêng và các gap mới

package/core/skills/qc/qa-designer/api/auth-chain.md

@@ -0,0 +1,155 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/api-testcase-designer/api/templates/auth-chain.md
+upstream_sha: ef8f9761f1b53d0ccd752f8fe0c13a427fa15f45
+---
+
+> **VIẾT LẠI, không copy** *(B12)* — cùng lý do với `endpoint.md`: bản upstream có trước luật
+> ATOMIC (2026-07-09), gộp nhiều kết cục vào một `**Expected:**` và dùng hệ mã
+> `API-<FEATURE>-AUTH-001`. Ba nhóm ca giữ nguyên; cấu trúc theo `shared/tc-metadata-format.md`.
+
+# Khuôn TC — chuỗi xác thực (login → token → gọi endpoint được bảo vệ)
+
+Dùng khi TC phải đăng nhập lấy token trước khi gọi endpoint chính. Thứ tự gọi và điểm verify
+của từng chuỗi: xem `auth-sequence.md`.
+
+Phủ **3 nhóm ca**: chuỗi thành công · token hết hạn · login sai mật khẩu.
+
+> **Một chuỗi auth KHÔNG phải một TC.** Chuỗi có nhiều bước, mỗi bước có kết cục riêng —
+> nên nó là **nhiều TC độc lập**, mỗi TC giữ FULL steps để tự tới được trạng thái cần assert.
+> Đây đúng là chỗ luật ATOMIC dễ bị bỏ nhất, vì cảm giác "một chuỗi = một ca".
+
+---
+
+## Nhóm ca 1 — Chuỗi thành công
+
+### TC_<FEATURE>_101 — login trả về access_token
+
+- **Title:** Login role `<role>` với thông tin đúng trả về access_token
+- **Feature:** <TICKET-ID> — <Tên feature>
+- **Priority:** P0
+- **Status:** Draft
+- **Author:** AI
+- **Tags:** api, happy-path, auth, <feature-tag>
+- **Trace:** BR-xx
+- **@trace.verifies:** {UC-ID}-SC{N}
+
+#### Preconditions
+- Tài khoản role `<role>` đã tồn tại (username `<username>`, password `<password>`).
+
+#### Test Data
+- Method: POST
+- Path: `/auth/login`
+- Headers: Content-Type: application/json
+- Body:
+  ```json
+  { "username": "<username>", "password": "<password>" }
+  ```
+
+#### Test Steps
+1. **[Action]** Gửi `POST /auth/login` với body trên.
+2. **[Verify]** Đọc `body.access_token`.
+
+#### Expected Result
+- HTTP 200 AND `body.access_token` exists
+
+> ✅ Compound hợp lệ — cả hai vế nói về **cùng một** kết cục: "login thành công và có token".
+
+### TC_<FEATURE>_102 — token lấy được gọi được endpoint bảo vệ
+
+- **Title:** Token của role `<role>` gọi <METHOD> <protected_path> trả về <success_code>
+- **Priority:** P0
+- **Tags:** api, happy-path, auth, <feature-tag>
+- **Trace:** BR-xx
+
+#### Preconditions
+- Tài khoản role `<role>` đã tồn tại.
+
+#### Test Steps
+1. **[Action]** Gửi `POST /auth/login` lấy `access_token`.
+2. **[Action]** Gửi `<METHOD> <protected_path>` với `Authorization: Bearer {access_token}`.
+3. **[Verify]** Đọc status code của request thứ hai.
+
+#### Expected Result
+- HTTP `<success_code>`
+
+> ⚠️ Bước 1 **lặp lại đủ**, không viết "dùng token từ TC_101". Mỗi TC tách phải tự chạy độc
+> lập — nếu nó phụ thuộc TC khác đã chạy thì thứ tự chạy trở thành điều kiện ẩn, và chạy riêng
+> một TC sẽ fail vì lý do không liên quan tới thứ nó kiểm.
+
+---
+
+## Nhóm ca 2 — Token hết hạn
+
+### TC_<FEATURE>_103 — token hết hạn trả về 401
+
+- **Priority:** P0
+- **Tags:** api, negative, auth, security
+- **Trace:** BR-xx
+
+#### Preconditions
+- Có sẵn một token đã quá thời hạn (`<expired_token>` — seed hoặc lấy từ fixture).
+
+#### Test Data
+- Headers: Authorization: Bearer `<expired_token>`
+
+#### Test Steps
+1. **[Action]** Gửi `<METHOD> <protected_path>` với token đã hết hạn.
+2. **[Verify]** Đọc status code.
+
+#### Expected Result
+- HTTP 401
+
+*Chuỗi refresh token (nếu API có) là nhóm ca riêng — xem `auth-sequence.md` §Chuỗi 2. Mỗi bước
+của chuỗi refresh cũng là một TC.*
+
+---
+
+## Nhóm ca 3 — Login sai mật khẩu
+
+### TC_<FEATURE>_104 — sai password trả về 401
+
+- **Priority:** P0
+- **Tags:** api, negative, auth, security
+- **Trace:** BR-xx
+
+#### Test Data
+- Body: `{ "username": "<username>", "password": "<wrong_password>" }`
+
+#### Test Steps
+1. **[Action]** Gửi `POST /auth/login` với password sai.
+2. **[Verify]** Đọc status code.
+
+#### Expected Result
+- HTTP 401
+
+### TC_<FEATURE>_105 — sai password KHÔNG trả về token
+
+- **Priority:** P0
+- **Tags:** api, negative, auth, security
+- **Trace:** BR-xx
+
+#### Test Steps
+1. **[Action]** Gửi `POST /auth/login` với password sai.
+2. **[Verify]** Kiểm trường `access_token` trong body.
+
+#### Expected Result
+- `body.access_token` not exists
+
+> **Vì sao tách khỏi TC_104 dù cùng một request.** *"Trả 401"* và *"không phát token"* là hai
+> kết cục **fail độc lập được**: một API hỏng có thể trả 401 mà vẫn kèm token trong body. Gộp
+> lại thì TC pass khi chỉ một nửa đúng — và nửa còn lại là lỗ bảo mật.
+>
+> Đây chính là luật *"assertion loại-trừ (KHÔNG có / KHÔNG xảy ra) là oracle THẬT"* ở
+> `shared/tc-metadata-format.md`. Khi tách bằng script, kiểm lại không đánh rơi các bullet
+> phủ định — chúng dễ bị bỏ nhất.
+
+---
+
+## Không cần Teardown
+
+Cả 5 TC trên **không tạo bản ghi thật** — chúng chỉ login và đọc. Không thêm dòng
+`#### Teardown` cho có. Thêm khi và chỉ khi TC tạo tài khoản mới hoặc đổi trạng thái thật; lúc
+đó ghi `[Teardown: deactivate user via admin API]` *(`shared/precision-rules.md` §8)*.

package/core/skills/qc/qa-designer/api/auth-sequence.md

@@ -0,0 +1,75 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/api-testcase-designer/api/flows/auth-sequence.md
+upstream_sha: 69d60c12fe6d641638132581cce1dc6c955354a6
+---
+# Flow — Auth Sequence (login → token → authenticated calls)
+
+Mô tả chuỗi gọi API liên tiếp liên quan đến xác thực.
+Load file này khi thiết kế TC cần thực hiện đăng nhập trước khi gọi endpoint chính.
+
+---
+
+## Chuỗi 1 — Login lấy token + gọi 1 endpoint
+
+```
+POST /auth/login  →  nhận access_token  →  <METHOD> <protected_endpoint>
+```
+
+**Khi dùng:** TC cần tài khoản đăng nhập trước khi thao tác (tạo/sửa/xóa resource).
+
+**Điểm verify:**
+1. Sau login: HTTP 200, `body.access_token` không rỗng.
+2. Sau gọi endpoint: status code kỳ vọng, body đúng schema.
+
+**TC pattern:** xem `templates/auth-chain.md` (TC AUTH-001).
+
+---
+
+## Chuỗi 2 — Token refresh
+
+```
+POST /auth/login  →  nhận access_token + refresh_token
+→  (sau khi access_token hết hạn)
+→  POST /auth/refresh  →  nhận access_token mới
+→  <METHOD> <protected_endpoint>  →  thành công
+```
+
+**Khi dùng:** API có cơ chế refresh token (nếu plan đề cập).
+
+**Điểm verify:**
+1. Login: nhận cả `access_token` và `refresh_token`.
+2. Gọi refresh: HTTP 200, `body.access_token` khác token cũ.
+3. Gọi endpoint bằng token mới: thành công.
+
+**TC negative liên quan:**
+- Dùng refresh_token hết hạn → 401.
+- Dùng refresh_token đã dùng lần trước (replay) → 401.
+
+---
+
+## Chuỗi 3 — Multi-role: cùng endpoint, khác role, khác kết quả
+
+```
+POST /auth/login (admin)   →  token_admin   →  <METHOD> <endpoint>  →  200/201
+POST /auth/login (teacher) →  token_teacher →  <METHOD> <endpoint>  →  200 hoặc 403
+POST /auth/login (student) →  token_student →  <METHOD> <endpoint>  →  403
+```
+
+**Khi dùng:** TC RBAC — verify phân quyền theo role.
+
+**Điểm verify:** mỗi role cần TC riêng; Expected ghi rõ mã cho từng role.
+
+**TC pattern:** Decision Table (role × endpoint → expected code).
+
+---
+
+## Ghi chú thiết kế TC
+
+- **Test isolation:** mỗi TC tự gọi login để lấy token riêng. Không dùng token từ TC khác.
+- **Token fixture (Python):** nếu nhiều TC cùng role, dùng `conftest.py` fixture
+  `logged_in_token_<role>` (session scope) để tránh login lặp lại khi chạy test.
+- **Expired token test:** tạo token expired sẵn trong `test_data/tokens.json` thay vì
+  đợi token tự hết hạn trong test.

package/core/skills/qc/qa-designer/api/common-headers.md

@@ -0,0 +1,61 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/api-testcase-designer/api/references/common-headers.md
+upstream_sha: 74f10a36bec7b40f4d9de2d0928798cb6fad0c2c
+---
+# Bảng tra cứu — Headers chuẩn
+
+Dùng khi điền mục **Test Data > Headers** trong TC API.
+Chỉ ghi header thực sự cần thiết cho TC đó; không copy toàn bộ bảng.
+
+---
+
+## Request headers thường dùng
+
+| Header | Giá trị điển hình | Khi nào cần |
+|---|---|---|
+| `Authorization` | `Bearer <access_token>` | Mọi endpoint yêu cầu auth |
+| `Content-Type` | `application/json` | POST / PUT có body JSON |
+| `Content-Type` | `multipart/form-data` | Upload file |
+| `Accept` | `application/json` | Luôn ghi khi API có thể trả nhiều format |
+| `Accept-Language` | `vi` hoặc `en` | Khi test response message theo ngôn ngữ |
+| `X-Request-ID` | `<uuid>` | Nếu API yêu cầu idempotency key |
+| `X-Tenant-ID` | `<tenant_id>` | Nếu LMS hỗ trợ multi-tenant |
+
+---
+
+## Response headers cần verify (ghi vào `[Verify]` step nếu TC liên quan)
+
+| Header | Verify khi |
+|---|---|
+| `Content-Type: application/json` | Mọi response trả JSON |
+| `Location: <url>` | POST 201 Created — verify URL tạo mới |
+| `Retry-After: <seconds>` | TC rate limit (429) |
+| `X-RateLimit-Remaining` | TC rate limit — verify còn bao nhiêu request |
+
+---
+
+## TC Negative liên quan header
+
+| Kịch bản | Header điều chỉnh | Expected |
+|---|---|---|
+| Không có Authorization | Bỏ header `Authorization` | 401 |
+| Token sai format | `Authorization: InvalidToken abc` | 401 |
+| Content-Type sai | `Content-Type: text/plain` (khi API cần JSON) | 400 hoặc 415 |
+| Token đúng nhưng sai role | Token của role không được phép | 403 |
+
+---
+
+## Quy ước ghi trong Test Data
+
+```
+Headers:
+  - Authorization: Bearer <valid_token_admin>
+  - Content-Type: application/json
+```
+
+- Dùng placeholder có tên rõ ràng: `<valid_token_admin>`, `<valid_token_teacher>`,
+  `<expired_token>`, `<token_wrong_role>` — không dùng `<token>` chung chung.
+- Không ghi header không liên quan đến TC (vd `User-Agent`, `Host`).

package/core/skills/qc/qa-designer/api/crud-sequence.md

@@ -0,0 +1,122 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/api-testcase-designer/api/flows/crud-sequence.md
+upstream_sha: 65bf214d9f9beabe3c40b8697ba7c058adfd8bb5
+---
+# Flow — CRUD Sequence (create → read → update → delete)
+
+Mô tả các chuỗi gọi API CRUD phụ thuộc nhau.
+Load file này khi TC cần tạo resource trước khi thao tác sửa/xóa/đọc chi tiết.
+
+---
+
+## Chuỗi 1 — Create → Read
+
+```
+POST <resource>       →  HTTP 201, nhận body.id
+→  GET <resource>/{id}  →  HTTP 200, body đúng data đã tạo
+```
+
+**Khi dùng:** Verify GET trả đúng data sau khi tạo; kiểm tra data persistence.
+
+**Điểm verify:**
+1. POST: HTTP 201, `body.id` tồn tại và không rỗng.
+2. GET bằng `id` từ bước 1: HTTP 200; các field chính (name, status…) = giá trị đã gửi lúc POST.
+
+**TC pattern:**
+- 1 TC happy cho chuỗi (P0).
+- Tách TC riêng nếu cần test GET với ID không tồn tại (P1).
+
+---
+
+## Chuỗi 2 — Create → Update → Read
+
+```
+POST <resource>         →  HTTP 201, nhận id
+→  PUT <resource>/{id}   →  HTTP 200/204
+→  GET <resource>/{id}   →  HTTP 200, body = data đã update
+```
+
+**Khi dùng:** Verify update áp dụng đúng, không mất dữ liệu không liên quan.
+
+**Điểm verify:**
+1. POST: `body.id` tồn tại.
+2. PUT: HTTP 200 hoặc 204 (theo contract).
+3. GET sau PUT: field đã update = giá trị mới; field không update = giá trị cũ (unchanged).
+
+**TC negative liên quan:**
+- PUT với ID không tồn tại → 404.
+- PUT với body vi phạm validation → 400.
+- PUT sau khi resource đã ở trạng thái không cho sửa (vd đã publish) → 409/422.
+
+---
+
+## Chuỗi 3 — Create → Delete → Read
+
+```
+POST <resource>         →  HTTP 201, nhận id
+→  DELETE <resource>/{id} →  HTTP 200/204
+→  GET <resource>/{id}    →  HTTP 404
+```
+
+**Khi dùng:** Verify xóa thực sự xóa resource (không còn truy cập được).
+
+**Điểm verify:**
+1. POST: HTTP 201, `body.id` tồn tại.
+2. DELETE: HTTP 200 hoặc 204.
+3. GET sau DELETE: HTTP 404.
+
+**TC negative liên quan:**
+- DELETE với ID không tồn tại → 404.
+- DELETE resource đang được tham chiếu (foreign key) → 409/422 (nếu API có bảo vệ).
+
+---
+
+## Chuỗi 4 — List + Pagination
+
+```
+POST <resource> x N lần   →  tạo N bản ghi
+→  GET <resource>?page=1&limit=<L>  →  trả đúng L bản ghi + pagination
+→  GET <resource>?page=2&limit=<L>  →  trang tiếp theo đúng
+```
+
+**Khi dùng:** TC pagination — verify tổng bản ghi, số trang, dữ liệu mỗi trang.
+
+**Điểm verify:**
+1. `body.total` = N (tổng bản ghi đã tạo).
+2. `body.data.length` = L (số bản ghi trên trang).
+3. Trang 2: `body.data` không trùng trang 1.
+
+---
+
+## Chuỗi 5 — Dependent resource (parent → child)
+
+```
+POST <parent>            →  HTTP 201, nhận parent_id
+→  POST <child>?parentId=<parent_id>  →  HTTP 201, nhận child_id
+→  GET <parent>/{parent_id}           →  body.children chứa child_id
+```
+
+**Khi dùng:** Resource con phụ thuộc resource cha (vd: buổi học phụ thuộc lớp học).
+
+**Điểm verify:**
+1. POST parent: `body.id` tồn tại.
+2. POST child với `parentId`: HTTP 201.
+3. GET parent: `body.children` (hoặc trường tương đương) chứa child đã tạo.
+
+**TC negative liên quan:**
+- POST child với `parentId` không tồn tại → 404.
+- POST child với parent đã bị xóa/đóng → 422/409.
+
+---
+
+## Ghi chú thiết kế TC
+
+- **Cleanup:** Mỗi TC trong chuỗi CRUD cần xóa data đã tạo ở cuối (teardown).
+  Ghi rõ bước cleanup trong Test Steps: `**[Action]** Xóa resource id=<id> (cleanup)`.
+- **ID dependency:** Khi TC sau cần ID từ TC trước, ghi rõ trong Preconditions:
+  `Đã có <resource> với id=<test_id> trong DB`.
+- **Không nối TC thành chuỗi:** Mỗi TC vẫn độc lập; nếu cần data sẵn → tạo trong
+  Preconditions/fixture, không phụ thuộc TC khác đã chạy trước.