@educa-corp/sdd-framework 0.9.6 → 0.9.8

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

@@ -0,0 +1,128 @@
+---
+version: 1.0
+updated: 2026-09-17
+---
+
+# Test Case — Job chạy ngầm *(tự chạy theo lịch hoặc điều kiện)*
+
+Skill **tự chứa** để viết TC cho một việc **không ai gọi**: nó tự thức dậy theo lịch, theo ngưỡng,
+hoặc theo một cờ trong dữ liệu. Chỉ cần load file này.
+
+## Khi nào trigger
+- Nền `system`, và hình dạng đã chốt là **job** *(xem `/qc-design-test` §Nền `system`)*.
+- Ví dụ: dọn dữ liệu quá hạn lúc 2h sáng · tổng hợp báo cáo cuối ngày · gửi nhắc hạn ·
+  đồng bộ định kỳ với hệ ngoài · batch/ETL.
+
+## Khi KHÔNG trigger
+- Có endpoint, ai đó gọi vào → `functional/api.md`
+- Nằm chờ message rồi xử lý → `integration/queue.md`
+- Chỉ verify bản ghi DB sau **một thao tác của người** → `integration/db.md`
+
+---
+
+## 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), phân nhóm, Trace + `@trace.verifies`, `🚫 Block`.
+> **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` +
+> `shared/action-keywords-glossary.md`.
+
+**`Tags` của mọi TC ở đây mang lane `job`.** Trạm 5 và trạm 6 đọc nó để không phải hỏi lại.
+
+---
+
+## 1 · Ba thứ phải chốt TRƯỚC khi viết TC
+
+Job khác API ở chỗ **không có request để mô tả**. Thay vào đó phải chốt ba thứ, và **thiếu cái
+nào thì dừng hỏi, đừng đoán**:
+
+| | Chốt gì | Nếu thiếu |
+|---|---|---|
+| **Kích hoạt** | Trong môi trường test, job được làm cho chạy bằng cách nào? *(lịch bắn thật · gọi tay qua CLI/endpoint quản trị · cắm cờ trong DB · đẩy một message)* | Ghi `🚫 Block: [GAP-…]` — không có cách kích hoạt thì **không TC nào chạy được** |
+| **Cửa sổ dữ liệu** | Lượt chạy này **nhặt những bản ghi nào**? *(tạo trước mốc nào · trạng thái nào · giới hạn bao nhiêu bản ghi một lượt)* | Không biết cửa sổ thì không dựng được Test Data, và Expected Result thành *"xử lý đúng"* — một cụm bị cấm |
+| **Dấu vết quan sát được** | Sau khi chạy xong, **nhìn vào đâu** để biết nó đã làm? *(bản ghi đổi trạng thái · file sinh ra · message phát đi · thông báo gửi đi · số liệu/log)* | Không có dấu vết thì TC không có oracle — nó không đỗ/trượt được |
+
+> **Đây là chỗ job hay bị viết hụt nhất.** Người viết quen với API: có request, có response, oracle
+> hiển nhiên. Job **không trả gì cả** — oracle nằm ở **thay đổi trạng thái**, và nếu không chốt
+> trước thì Expected Result sẽ trôi về *"job chạy thành công"*, một câu không kiểm được.
+
+---
+
+## 2 · Chín nhóm TC bắt buộc soi
+
+Sáu nhóm từ **4** trở xuống là **rủi ro riêng của job** — không skill nào khác trong framework
+phủ chúng. Bỏ nhóm nào thì nêu rõ **vì sao bỏ**, đừng im lặng.
+
+### 1 · Đường thuận
+Có dữ liệu đúng trong cửa sổ → chạy → **từng dấu vết ở §1 đổi đúng như mong đợi**.
+Assert cả ba mặt nếu có: bản ghi · message phát ra · thông báo.
+
+### 2 · Không nhặt thứ ngoài cửa sổ
+Bản ghi **ngoài** điều kiện *(sai trạng thái, tạo sau mốc)* → chạy → **bản ghi đó KHÔNG đổi**.
+Đây là assert **phủ định**, và là nhóm hay bị đánh rơi nhất khi rút gọn TC.
+
+### 3 · Lượt chạy rỗng
+Không có bản ghi nào để làm → chạy → **không lỗi, không phát message, không gửi thông báo**.
+Job báo lỗi khi rỗng là bug; job gửi thông báo *"đã xử lý 0 bản ghi"* mỗi đêm cũng là bug.
+
+### 4 · Chạy lại lần hai cùng dữ liệu *(idempotency)*
+Chạy xong lần 1 → chạy lại ngay lần 2 trên cùng dữ liệu → **hiệu ứng chỉ xảy ra một lần**:
+không trừ tiền hai lần, không gửi mail hai lần, không tạo bản ghi trùng.
+
+> **Đây là bug kinh điển nhất của job chạy ngầm.** Nó xuất hiện thật khi lịch chạy chồng, khi
+> có người kích tay lúc job đang chạy, hoặc khi hệ thống khởi động lại giữa chừng.
+
+### 5 · Hỏng giữa chừng
+Cho lỗi ở bản ghi thứ **k** của **n** *(k nằm giữa)* → phải trả lời được **hai** câu, và TC phải
+ghi rõ thiết kế chọn đường nào:
+
+| Đường | Kỳ vọng |
+|---|---|
+| **Dừng cả lượt** | k−1 bản ghi đầu **đã xong** phải giữ nguyên, hay bị rollback hết? |
+| **Bỏ qua bản lỗi, chạy tiếp** | bản thứ k có được ghi lại ở đâu không? Lượt sau có nhặt lại nó không? |
+
+Chạy lại sau khi hỏng: **k−1 bản đầu KHÔNG được xử lý lần thứ hai** *(nối với nhóm 4)*.
+
+### 6 · Hai tiến trình cùng lúc
+Kích hai lượt chạy chồng nhau → **không bản ghi nào bị xử lý hai lần**. Hoặc job phải **từ chối**
+lượt thứ hai *(có khoá)*, hoặc hai lượt chia nhau bản ghi — **thiết kế chọn đường nào phải ghi
+trong TC**, vì hai đường có Expected Result khác hẳn.
+
+### 7 · Biên của cửa sổ
+Bản ghi tạo **đúng mốc** · **trước mốc một đơn vị** · **sau mốc một đơn vị** → nhặt đúng cái phải
+nhặt. Và ca khó hơn: bản ghi **được tạo trong lúc job đang chạy** — lượt này lấy hay để lượt sau?
+
+> Nêu **đơn vị** tường minh *(giây? ngày? theo múi giờ nào?)* — `precision-rules.md` cấm mốc mơ hồ.
+
+### 8 · Bản ghi độc
+Một bản ghi hỏng *(dữ liệu sai định dạng, tham chiếu chết)* → nó **không được làm chết cả lượt**,
+trừ khi thiết kế cố ý thế. Ghi rõ đường nào, và bản ghi độc đi đâu.
+
+### 9 · Thử lại và trần
+Job gọi ra ngoài mà bên kia lỗi → thử lại mấy lần, cách nhau bao lâu, **trần ở đâu**?
+Không có trần là job treo tới khi có người tắt.
+
+---
+
+## 3 · Phân nhóm trong file TC
+
+```
+1 Đường thuận            ← nhóm 1
+2 Cửa sổ & biên          ← nhóm 2, 7
+3 Chạy lặp & đồng thời   ← nhóm 4, 6
+4 Hỏng & phục hồi        ← nhóm 5, 8, 9
+5 Lượt rỗng              ← nhóm 3
+```
+
+---
+
+## 4 · Test Data — khác API ở chỗ nào
+
+Job **không nhận payload**; dữ liệu của nó là **trạng thái có sẵn trong hệ thống**. Nên Test Data
+của TC job là một **bảng bản ghi phải seed trước**, kèm ba cột tối thiểu: định danh · trạng thái ·
+mốc thời gian liên quan tới cửa sổ.
+
+Và phải nêu **dọn thế nào** — job đổi trạng thái thật, nên chạy hai lần liên tiếp mà không dọn
+thì lượt sau đã không còn ở điều kiện ban đầu *(và đó chính là nhóm 4 nếu cố ý, là nhiễu nếu vô ý)*.

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

@@ -15,7 +15,7 @@ verify luồng dữ liệu & contract giữa các thành phần. Chỉ cần loa
 
 ## Khi KHÔNG trigger
 - Chỉ verify request/response 1 endpoint → `functional/api`
-- Verify riêng trạng thái DB → `integration/db` · message/event → `integration/kafka`
+- Verify riêng trạng thái DB → `integration/db` · message/event → `integration/queue`
 
 ---
 
@@ -46,4 +46,4 @@ Nhóm TC: happy (dữ liệu đúng đầu→cuối) → contract negative (inpu
 
 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`.
+**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-testcase`.

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

@@ -13,7 +13,7 @@ insert/update/soft-delete đúng giá trị, side-effect, toàn vẹn. Chỉ c
 - Kiểm tra bản ghi DB sau thao tác (tạo ticket → ghi đúng bảng/cột); soft-delete, default, audit log
 
 ## Khi KHÔNG trigger
-- Chỉ verify response API → `functional/api`/`integration/api` · message/event → `integration/kafka`
+- Chỉ verify response API → `functional/api`/`integration/api` · message/event → `integration/queue`
 
 ---
 
@@ -42,4 +42,4 @@ Nhóm TC: ghi đúng giá trị (happy) → default/null đúng → update khôn
 
 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`.
+**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-testcase`.

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

@@ -44,4 +44,4 @@ Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 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`.
+**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-testcase`.

package/core/skills/qc/qa-designer/integration/{kafka.md → queue.md}

@@ -4,16 +4,32 @@ updated: 2026-06-11
 ported_from: ui-automation-testing
 ---
 
-# Test Case — Integration Kafka (Message/Event)
+# Test Case — Integration hàng đợi (Message/Event)
 
-Skill **tự chứa** để viết TC tích hợp qua Kafka: producer phát event đúng, consumer xử lý
-đúng, đảm bảo ordering/idempotency/retry. Chỉ cần load file này.
+Skill **tự chứa** để viết TC tích hợp qua hàng đợi/message bus — Kafka, RabbitMQ, SQS, hay bất
+kỳ cơ chế nào có **người gửi** và **người nhận** tách rời: producer phát event đúng, consumer xử
+lý đúng, đảm bảo ordering/idempotency/retry. Chỉ cần load file này.
+
+> **Tên file đổi từ `kafka.md` (2026-09-17):** nội dung chưa bao giờ phụ thuộc Kafka — nó nói về
+> **hình dạng hàng đợi**. Giữ tên một công nghệ cụ thể làm người dùng RabbitMQ/SQS tưởng không
+> áp dụng được.
 
 ## Khi nào trigger
-- Action sinh event Kafka (vd tạo ticket → phát event sang service/CRM); verify topic/payload/thứ tự/khử trùng
+
+Hai phía, **cùng một file** — nêu rõ TC đang đứng ở phía nào:
+
+| Phía | Khi nào | Ví dụ |
+|---|---|---|
+| **Người gửi** *(producer)* | một action sinh ra event | tạo ticket → phát event sang CRM; verify topic · key · payload · điều kiện phát |
+| **Người nhận** *(consumer)* | service **nằm chờ**, có message tới thì xử lý — **không action nào của người đứng trước** | đơn hàng mới vào hàng đợi → service kho trừ tồn; verify xử lý đúng · khử trùng · lỗi thì đi đâu |
+
+> **Phía người nhận là chỗ hay bị bỏ sót.** Khung cũ chỉ viết *"Action sinh event"* — tức luôn
+> giả định có một thao tác đứng trước. Một consumer thuần thì **không có thao tác đó**, và TC
+> phải bắt đầu bằng *"có message X trên hàng đợi Y"*, không phải bằng một hành động của người.
 
 ## Khi KHÔNG trigger
 - Tích hợp đồng bộ qua API → `integration/api` · verify DB → `integration/db`
+- **Tự chạy theo lịch, không có message nào kích** → `functional/job.md`
 
 ---
 
@@ -44,4 +60,4 @@ Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 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`.
+**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-testcase`.

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

@@ -44,4 +44,4 @@ Trace BR; gap chặn → 🚫 Block.
 
 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`.
+**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-testcase`.

package/core/skills/qc/qa-designer/shared/skill-decision-tree.md

@@ -11,6 +11,21 @@ upstream_sha: 57125f0c21512f2abcc55d00420e92c84c95fc8f
 
 ---
 
+## Bước 0 — TC đã có lane chưa? *(hỏi TRƯỚC mọi câu khác)*
+
+Nếu `Tags` của TC đã mang một `<lane>` — `ui` · `api` · `job` · `queue` · `db` · `e2e` · `nfr` —
+thì **ĐỌC nó, dừng ở đây, không suy lại**. Bảng lane ↔ skill ở
+`shared/tc-metadata-format.md` §Tags.
+
+> **Vì sao dừng chứ không "kiểm tra lại cho chắc".** Với nền `system`, lane là **câu trả lời của
+> QC** ở trạm 3 cho một câu mà máy không suy được *(xem `/qc-design-test` §Nền `system`)*. Suy lại
+> là đặt phán đoán của máy lên trên câu trả lời của người — và khi hai bên lệch, TC và script sẽ
+> kiểm hai thứ khác nhau mà **cả hai đều chạy được**.
+>
+> Chưa có lane → đi tiếp Bước 1.
+
+---
+
 ## Bước 1 — Đối tượng test là gì?
 
 ```
@@ -18,6 +33,8 @@ upstream_sha: 57125f0c21512f2abcc55d00420e92c84c95fc8f
 ├── Hiển thị / validation / state của 1 screen       → [A] Xét tiếp Bước 2 (UI vs Integration GUI)
 ├── User thực hiện workflow có mục tiêu nghiệp vụ    → [B] Xét tiếp Bước 3 (E2E vs Integration)
 ├── 1 API endpoint (request/response/mã lỗi)         → api-testcase-designer
+├── Việc TỰ CHẠY theo lịch/điều kiện, không ai gọi   → functional/job.md
+├── Nằm chờ message rồi xử lý                        → integration/queue.md
 ├── NFR (performance/security/a11y/i18n)              → nfr-testcase-designer
 └── Luồng đa màn nằm trong 1 feature, không xuyên hệ thống → ui-testcase-designer (gui-feature)
 ```

package/core/skills/qc/qa-designer/shared/tc-metadata-format.md

@@ -5,7 +5,12 @@ ported_from: ui-automation-testing
 upstream_path: skills/qa-tc-designer/shared/tc-metadata-format.md
 upstream_sha: a31d66a7a8dab19cf821c9102a88282b09e16cb9
 ---
-# TC Metadata Format (Chuẩn chung)
+# TC Metadata Format
+
+> **`Automatable` KHÔNG phải một field của `.Test.md`.** Quyết định *"TC này máy chạy được hay
+> phải chạy tay"* sống ở **đúng một chỗ**: `{qc_artifact_dir}AUTOMATION_ASSESSMENT.md`, do
+> `/qc-automation-assess` ghi. Đừng chép giá trị đó vào đây — hai nơi ghi cùng một quyết định
+> thì một nơi sẽ lệch, và lúc đó không ai biết nơi nào đúng. (Chuẩn chung)
 
 ## ⚠️ Nguyên tắc format file TC (BẮT BUỘC — QC yêu cầu)
 
@@ -56,6 +61,23 @@ Mỗi trường 1 dòng, không bảng, không emoji dư:
 - **Status:** Draft
 - **Author:** AI
 - **Tags:** <lane>, <loại: smoke|sanity|regression>, <feature-tag>
+
+  **`<lane>` — giá trị hợp lệ** *(khai 2026-09-17; trước đó để ngỏ nên mỗi file viết một kiểu)*:
+
+  | Lane | Khi nào | Skill thiết kế |
+  |---|---|---|
+  | `ui` | có màn hình | `functional/gui-screen` · `gui-feature` |
+  | `api` | có endpoint, ai đó gọi vào | `functional/api` · `integration/api` |
+  | `job` | **tự chạy** theo lịch/điều kiện, không ai gọi | `functional/job` |
+  | `queue` | nằm chờ message rồi xử lý | `integration/queue` |
+  | `db` | verify trạng thái dữ liệu sau thao tác | `integration/db` |
+  | `e2e` | hành trình xuyên nhiều màn/hệ | `e2e/journey` |
+  | `nfr` | hiệu năng · bảo mật · a11y · i18n | `non-functional` |
+
+  > **Lane là câu trả lời đã chốt, không phải nhãn trang trí.** Với nền `system`, nó do **QC trả
+  > lời** ở trạm 3 khi không suy được hình dạng *(xem `/qc-design-test` §Nền `system`)*. Trạm 5 và
+  > trạm 6 **ĐỌC** lane này, **không suy lại** — suy lại là mở đường cho hai trạm kết luận khác nhau
+  > về cùng một TC.
 - **Trace:** BR-xx (ID gốc trong PRD/BDD ở `{paths.specs_dir}`)
 - **@trace.verifies:** {UC-ID}-SC{N}
 - **🚫 Block:** [GAP-UC{N}-{nnn}](../DOC_GAP.md) — <lý do> *(chỉ khi có)*
@@ -205,7 +227,7 @@ Mọi thứ trên là chuẩn của đội QC. Bốn thứ dưới đây là **c
 **Câu hỏi phân file:** *"TC này verify được mà **không cần UI** không?"*
 → **có** = file API · **không** = file giao diện. *(Trùng Bước 2 của `skill-decision-tree.md`.)*
 
-⚠️ **Đuôi file là `.Test.md`, không phải `.md`.** `/qc-run-test` và `/qc-review` tìm `*.Test.md`;
+⚠️ **Đuôi file là `.Test.md`, không phải `.md`.** `/qc-design-script` và `/qc-review-testcase` tìm `*.Test.md`;
 ghi ra file thiếu phần `.Test` là ghi ra thứ **không trạm nào tìm thấy**, và không có gì báo lỗi.
 
 Đánh số `TC_<FEATURE>_NNN` **liên tục toàn file**, không đánh lại theo từng nhóm.
@@ -215,7 +237,7 @@ ghi ra file thiếu phần `.Test` là ghi ra thứ **không trạm nào tìm th
 | Trường | Dạng | Vì sao cần |
 |---|---|---|
 | `**Trace:**` | `[BR-xx](../REQUIREMENT_ANALYSIS.md#3-business-rules)` — không có BR → `⚠️ Chưa có Business Rule` | truy về luật nghiệp vụ |
-| `**@trace.verifies:**` | `{UC-ID}-SC{N}` (lấy từ `@trace.scenario` của file `.feature`) | **join key** để `/qc-run-test` ghi `qc_status` theo từng kịch bản vào sổ trace |
+| `**@trace.verifies:**` | `{UC-ID}-SC{N}` (lấy từ `@trace.scenario` của file `.feature`) | **join key** để `/qc-run-script` ghi `qc_status` theo từng kịch bản vào sổ trace |
 
 Một `SC` map được nhiều TC. **Thiếu `@trace.verifies` thì kết quả chạy không vào được sổ** — TC
 vẫn chạy, vẫn pass/fail, nhưng không ai biết nó phủ kịch bản nào.
@@ -241,7 +263,7 @@ Nguồn & phiên bản: BDD {UC-ID} `<vX.Y>` · tech-doc `<rev | —>`
 ```
 
 Lấy `<vX.Y>` từ `| **Version** |` ở header `.feature` của **chính UC này**, và `<rev>` từ header
-tech-doc gộp. `/qc-review` và `/qc-run-test` **so** khối này với version hiện tại để biết bộ TC còn
+tech-doc gộp. `/qc-review-testcase` và `/qc-design-script` **so** khối này với version hiện tại để biết bộ TC còn
 khớp spec không (`steps/qc-stamp.md` · `bin/trace-schema.json` → `qc_artifact_stamp`).
 
 **Vì sao cần, khi sổ trace đã có `qc_status`.** `/generate-bdd` hạ `qc_status → not_run` khi spec đổi
@@ -259,8 +281,8 @@ Test-ID attribute: {attr}
 ```
 
 Đọc `@trace.testid_attr` từ header tech-doc gộp (do `/map-testids` ghi). Bảng §4.5.6 chỉ cho
-**giá trị** test-id; đây là **tên thuộc tính** chứa chúng. `/qc-run-test` cần nó để cấu hình
-locator, `/qc-review` cần nó để biết selector trong script có đúng hợp đồng không.
+**giá trị** test-id; đây là **tên thuộc tính** chứa chúng. `/qc-design-script` cần nó để cấu hình
+locator, `/qc-review-script` cần nó để biết selector trong script có đúng hợp đồng không.
 
 Thiếu field trong tech-doc → ghi `Test-ID attribute: — (thiếu @trace.testid_attr, chạy /map-testids)`.
 **Đừng bỏ trống và đừng tự đoán** — đoán sai thì mọi locator trượt 100%, và trượt vì lý do

package/core/skills/qc/qa-reviewer/script/_shared/review-rules.md

@@ -0,0 +1,121 @@
+---
+version: 1.0
+updated: 2026-09-17
+source: upstream/qc-base-new/AGT-006-code_reviewer.md §3.1 §3.2 §3.3 §4 (Draft) · §5 Boundary
+---
+
+# Luật soát script — dùng chung cho mọi nền
+
+**Nạp file này TRƯỚC file lane.** Lane chỉ nói *"nền này soát thêm gì"*; mọi thứ ở đây đúng cho
+cả `web` · `mobile` · `api`. Viết một bản vì 11 file lane đều cần — 11 bản của một luật là nơi
+drift sống.
+
+---
+
+## 1 · Bảy luật của lượt soát *(R01–R07)*
+
+| Mã | Luật | Nghĩa khi soát |
+|---|---|---|
+| **R01** | **Review All Files** | Soát **mọi** file được đưa: spec · Page/Screen/API Object · data. Soát một phần rồi kết luận là kết luận về một thứ chưa đọc |
+| **R02** | **Evidence-Based Findings** | Mỗi lỗi phải có đủ **bốn**: tên file · số dòng (hoặc đoạn code) · mô tả vấn đề · cách sửa đề nghị. Thiếu một trong bốn thì đó là cảm tưởng, không phải finding |
+| **R03** | **No Silent Pass** | Không `APPROVED` một script chưa soát kỹ. Soát đủ mà không thấy lỗi → `APPROVED` là **đúng**, không phải lười |
+| **R04** | **No Rewriting** | Chỉ báo cáo, **không sửa code**. Đề xuất phải đủ rõ để người viết tự sửa được mà không hỏi lại |
+| **R05** | **Positive Observations Required** | Mỗi lượt soát ghi **ít nhất 2–3 điểm tốt**. Một biên bản chỉ có lỗi là biên bản mất cân bằng — người đọc không biết phần nào đang đúng để giữ |
+| **R06** | **Verdict Consistency** | Verdict suy ra từ **số đếm** finding theo §3, không tự nâng/hạ |
+| **R07** | **Traceability First** | Thiếu/sai header artifact ID *(TC-ID · `@trace.verifies`)* ⇒ **BLOCKER ngay, dừng soát**. Không soát tiếp một file không biết nó phục vụ scenario nào |
+
+> **R07 chặn cửa TRƯỚC, không phải sau.** Một lượt soát trên file không có trace tag vẫn chạy
+> trót lọt và vẫn in ra verdict — nhưng verdict đó nói về một thứ không neo vào scenario nào.
+> Đó là kiểu hỏng **Nói dối**: biên bản trông hợp lệ, nội dung vô nghĩa.
+
+---
+
+## 2 · Bốn mức nặng-nhẹ của một lỗi *(severity)*
+
+| Mức | Định nghĩa | Ví dụ |
+|---|---|---|
+| **BLOCKER** | Ngăn test chạy đúng, hoặc vi phạm chuẩn lõi | selector thô trong spec · thiếu `await` · lỗi cú pháp · **không có header block** |
+| **MAJOR** | Ảnh hưởng nặng tới khả năng bảo trì hoặc độ tin cậy | hard-code test data · `waitForTimeout` · locator bám class CSS tự sinh |
+| **MINOR** | Vấn đề chất lượng code, script **vẫn chạy được** | thiếu type annotation · đặt tên không nhất quán · logic lặp có thể tách |
+| **SUGGESTION** | Cơ hội cải thiện — **không bắt buộc** | tên biến rõ hơn · thông điệp assertion mô tả hơn |
+
+**Ranh giới BLOCKER ↔ MAJOR đo được, không cảm tính:** BLOCKER là *"chạy sẽ sai hoặc không chạy"*;
+MAJOR là *"chạy đúng hôm nay, hỏng khi có người sửa"*.
+
+---
+
+## 3 · Bốn verdict — suy ra từ số đếm, **không override**
+
+| Verdict | Điều kiện bắt buộc | Đi tiếp? |
+|---|---|:-:|
+| **APPROVED** | 0 BLOCKER, 0 MAJOR | ✅ |
+| **APPROVED_WITH_SUGGESTIONS** | 0 BLOCKER, 0 MAJOR, ≥1 MINOR hoặc SUGGESTION | ✅ |
+| **REVISION_REQUIRED** | 0 BLOCKER, ≥1 MAJOR | ❌ sửa rồi soát lại |
+| **REJECTED** | ≥1 BLOCKER | ❌ sửa rồi soát lại |
+
+**Ngưỡng qua cửa: `≥ APPROVED_WITH_SUGGESTIONS`** — khai ở `AGT-005:132` và `AGT-010:130`.
+Hai mức trên đi tiếp, hai mức dưới quay lại. Các trạm sau *(`/qc-run-script`)* đọc **hai luồng
+này**, không đọc bốn tên.
+
+> **Vì sao lane QC dùng 4 mức còn lane DEV *(`/review-code`)* giữ 2.** Lane QC có tài liệu chuẩn
+> định nghĩa severity thành bốn ô đếm được *(§2)*, nên bốn verdict chỉ là **tên của bốn ô đó** —
+> không thêm phán quyết nào. Lane DEV chưa có bảng severity tương ứng, nên 4 tên ở đó sẽ là bốn
+> nhãn phải tự đoán. Đây là **một bất đối xứng có lý do**, không phải chỗ quên đồng bộ.
+
+---
+
+## 4 · Ranh giới — soát cái gì, KHÔNG soát cái gì
+
+| | |
+|---|---|
+| ✅ **Soát** | code test đã sinh · Page/Screen/API Object · file data · khớp với `.Test.md` gốc |
+| ❌ **KHÔNG soát** | **cấu trúc file test case** — đó là việc của `/qc-review-testcase`. Áp checklist cấu trúc TC vào một Page Object là bảo người soát đi tìm `#### Expected Result` trong code |
+| ❌ **KHÔNG sửa** | *(R04)* — kể cả lỗi hiển nhiên một dòng |
+| ❌ **KHÔNG chạy** | chạy test là việc của `/qc-run-script`. Ở đây chỉ compile/list để biết script **dịch được** và **thấy đủ số test** |
+
+---
+
+## 5 · Phép kiểm cơ học bắt buộc — trước khi kết luận
+
+Chạy đủ hai lệnh, **dán output vào biên bản**:
+
+```
+npx tsc --noEmit                          ← dịch được? (BLOCKER nếu lỗi)
+npx playwright test <spec> --list         ← đếm số test collect được   (web · api)
+npx wdio <config> --dry-run               ← tương đương cho mobile
+```
+
+**Số test collect được phải bằng số TC `Automatable: Y`** của phạm vi này trong
+`AUTOMATION_ASSESSMENT.md`. Lệch là **BLOCKER** — không phải MINOR:
+
+- collect **ít hơn** ⇒ có TC không được sinh, và nó sẽ nằm `not_run` vĩnh viễn trong sổ trace
+- collect **nhiều hơn** ⇒ có test không neo vào TC nào, `qc_status` sẽ ghi cho một scenario không tồn tại
+
+> Đây là chỗ duy nhất trong lượt soát mà **máy trả lời thay vì người** — nên nó là chỗ đáng tin
+> nhất, và là lý do hai lệnh trên không được bỏ qua kể cả khi "nhìn code thấy ổn".
+
+---
+
+## 6 · Đường dẫn — lấy từ `§layout` của module, KHÔNG viết cứng
+
+Nền đang soát đã được `steps/qc-scope.md` §2b phân giải. Gốc thư mục lấy từ `§layout` của
+module tương ứng:
+
+```
+web      automation/tests/{TICKET-ID}/<feature>-<scenario>.spec.ts
+         automation/pages/<feature>.page.ts
+api      api-automation/tests/{TICKET-ID}/<feature>-<scenario>.spec.ts
+         api-automation/api/<resource>.api.ts
+mobile   mobile-automation/tests/{TICKET-ID}/<feature>-<scenario>.spec.ts
+         mobile-automation/screens/<feature>.screen.ts
+```
+
+> **`tests/` chia theo `{TICKET-ID}`, `pages/`·`api/`·`screens/` để phẳng — có chủ ý.** Một spec
+> **thuộc về** một PRD; một Page Object **được dùng bởi** nhiều PRD. Nhét Page Object vào thư mục
+> PRD là ép nhân bản nó cho mỗi PRD — đúng thứ Page Object Pattern sinh ra để tránh.
+>
+> Thiếu segment `{TICKET-ID}` ở `tests/` thì hai PRD cùng có feature `login` ghi vào **cùng một
+> đường dẫn** và đè nhau **im lặng**. Đó là lý do framework lệch khỏi bố cục phẳng của
+> `Automation-Standards §2.3`: chuẩn giả định `tests/` soi gương theo `test-suites/`, còn ở đây
+> test case sống ở `{qc_dir}/{TICKET-ID}/{platform}/test-cases/` — áp đúng **nguyên tắc** của
+> chuẩn vào layout này thì ra hình dạng trên.

package/core/skills/qc/qa-reviewer/script/api/auth.md

@@ -0,0 +1,49 @@
+---
+version: 1.0
+updated: 2026-09-17
+source: upstream/qc-base-new/API-Testing-Standards.md §5.5 §9.1 (Approved)
+---
+
+# Soát script — API xác thực & phân quyền
+
+**Nạp `../_shared/review-rules.md` rồi `endpoint.md` cùng lane.** Đây là phần thêm.
+
+## Khi nào trigger
+- Soát script kiểm đăng nhập, token, và **quyền truy cập** của từng vai lên từng endpoint.
+
+---
+
+## Thêm gì so với endpoint
+
+### A · Fixture token dùng chung *(§5.5)*
+
+- Mỗi test tự đăng nhập lại ⇒ **MINOR** — chậm và dễ chạm rate-limit; dùng `fixtures/api.fixture.ts`
+- Token hard-code / token thật commit vào repo ⇒ **BLOCKER**
+- Fixture không phân biệt **vai** ⇒ **MAJOR**: một token dùng cho mọi test thì không kiểm được phân quyền
+
+### B · Mọi endpoint được bảo vệ phải có đủ ba ca *(§9.1)*
+
+| Ca | Mong đợi |
+|---|---|
+| Không token | **401** |
+| Token sai / hết hạn | **401** |
+| Token đúng nhưng **sai vai** | **403** |
+
+- Thiếu bất kỳ ca nào cho một endpoint được bảo vệ ⇒ **MAJOR**
+- Gộp 401 và 403 thành một ca ⇒ **MAJOR** — hai lỗi khác nhau: *chưa biết anh là ai* vs *biết rồi
+  nhưng anh không được phép*
+
+### C · Assert phải là "bị chặn", không phải "không lỗi"
+
+- `expect(res.status()).not.toBe(200)` ⇒ **MAJOR** — 500 cũng qua được phép assert này
+- Assert đúng mã, và assert body **không rò dữ liệu** của tài nguyên bị cấm ⇒ thiếu ⇒ **MINOR**
+
+### D · Vòng đời token
+
+- Không kiểm token hết hạn / refresh khi hợp đồng có ⇒ **MINOR**
+
+---
+
+## Kiểm cơ học + Output
+
+Như `endpoint.md` Phase 3 và §Output.

package/core/skills/qc/qa-reviewer/script/api/endpoint.md

@@ -0,0 +1,89 @@
+---
+version: 1.0
+updated: 2026-09-17
+source: upstream/qc-base-new/API-Testing-Standards.md §4 §5 §6 §8 §10 §11 · AGT-010 §3 (Approved)
+---
+
+# Soát script — API endpoint *(Playwright API mode + TypeScript)*
+
+**Nạp `../_shared/review-rules.md` trước.** Lane này dùng khi `active_platform = system`.
+
+> ⚠️ **API Object ≠ Page Object.** Không có màn hình, không có locator, không có wait. Soát API
+> bằng checklist web là đi tìm những thứ không tồn tại rồi kết luận "không có lỗi".
+
+## Khi nào trigger
+- Soát script kiểm **endpoint** của một service: CRUD, mã trạng thái, cấu trúc response.
+
+## Khi KHÔNG trigger
+- Xác thực / phân quyền → `auth.md` · injection & input validation → `security.md`
+- API gọi phụ trợ **bên trong** một dự án web *(setup/teardown)* → `../web/functional.md`
+
+---
+
+## Phase 1 — Đọc đủ *(R01)*
+
+1. `api-automation/tests/{TICKET-ID}/<feature>-*.spec.ts`
+2. `api-automation/api/<resource>.api.ts` + `base.api.ts`
+3. `data/<resource>.data.ts` · `fixtures/api.fixture.ts` · `helpers/schema.helper.ts`
+4. `.Test.md` + `AUTOMATION_ASSESSMENT.md`
+
+**R07 chặn cửa** như mọi lane.
+
+---
+
+## Phase 2 — Năm nhóm soát
+
+### A · API Object *(§4 · AGT-010 R01)*
+
+- **Mọi HTTP request phải đi qua API Object.** `request.post(...)` thô trong spec ⇒ **BLOCKER**
+- `extends BaseAPI`; class `<Resource>API`; file `<resource>.api.ts`
+- **1 method = 1 endpoint action**; method gộp nhiều endpoint ⇒ **MAJOR**
+- Kiểu trả về `Promise<APIResponse>` — **không parse response trong API Object** ⇒ parse ⇒ **MAJOR**
+- **Không `expect()` trong API Object** ⇒ có ⇒ **MAJOR**
+- "God API Object" gom mọi resource ⇒ **MAJOR**
+
+### B · Cấu trúc spec *(§5 — AAA)*
+
+- Ba khối rõ: **Arrange** (data, token) → **Act** (gọi API Object) → **Assert**
+- Trộn assert vào giữa chuỗi gọi ⇒ **MINOR**
+- Header block có TC-ID + `@trace.verifies` ⇒ thiếu ⇒ **BLOCKER** *(R07)*
+- Data-driven dùng `for...of` hoặc `test.each`, không copy test 5 lần ⇒ copy ⇒ **MINOR**
+
+### C · Assertion *(§6)*
+
+- **Assert mã trạng thái là bắt buộc** — thiếu ⇒ **BLOCKER**
+- Assert **cả cấu trúc lẫn giá trị** của body, không chỉ `status === 200` ⇒ chỉ status ⇒ **MAJOR**
+- Kiểm schema cho response có cấu trúc ⇒ thiếu ⇒ **MINOR**
+- Assert header khi hợp đồng có nêu *(content-type, cache)* ⇒ thiếu ⇒ **MINOR**
+- `expect(res.ok()).toBeTruthy()` làm assertion duy nhất ⇒ **MAJOR** — nó đúng cho mọi 2xx/3xx
+
+### D · Dữ liệu *(AGT-010 R03)*
+
+- Credential, payload, giá trị mong đợi **hard-code trong spec** ⇒ **MAJOR** — để ở `data/`
+- Bản ghi tạo ra phải xoá trong `afterEach`/`afterAll`, kể cả khi fail ⇒ thiếu ⇒ **MAJOR**
+- Test phụ thuộc bản ghi có sẵn trên môi trường ⇒ **MAJOR**
+
+### E · Async *(AGT-010 R02)* và chất lượng *(§10 · §11)*
+
+- **`waitForTimeout` tuyệt đối không dùng** — API là đồng bộ về bản chất, `await` thẳng ⇒ có ⇒ **BLOCKER**
+- Thiếu `await` trước lời gọi API ⇒ **BLOCKER** *(test xanh giả, chạy xong trước khi có response)*
+- TypeScript strict, không `any` ⇒ **MINOR**
+- `test.only` sót lại ⇒ **BLOCKER**
+
+---
+
+## Phase 3 — Kiểm cơ học
+
+```
+npx tsc --noEmit
+npx playwright test --config=api-automation/playwright.config.ts <spec> --list
+```
+
+Số test collect được **phải bằng** số TC `Automatable: Y`. Lệch ⇒ **BLOCKER**.
+
+---
+
+## Output
+
+Theo `_shared/review-rules.md` §3, kèm ≥2–3 điểm tốt *(R05)*.
+Lưu ý dãy ID của lane này độc lập: `TC-API-*` ≠ `TC-*` *(§7.3)*.

package/core/skills/qc/qa-reviewer/script/api/security.md

@@ -0,0 +1,46 @@
+---
+version: 1.0
+updated: 2026-09-17
+source: upstream/qc-base-new/API-Testing-Standards.md §8 §9.2 (Approved)
+---
+
+# Soát script — API kiểm tra đầu vào & injection
+
+**Nạp `../_shared/review-rules.md` rồi `endpoint.md` cùng lane.** Đây là phần thêm.
+
+## Khi nào trigger
+- Soát script kiểm **biên của đầu vào** và các mẫu injection lên endpoint.
+
+---
+
+## Thêm gì so với endpoint
+
+### A · Kỹ thuật thiết kế phải thấy được trong code *(§8)*
+
+- **Phân lớp tương đương**: mỗi lớp có ít nhất một ca. Chỉ kiểm ca hợp lệ ⇒ **MAJOR**
+- **Giá trị biên**: với trường có giới hạn, phải có `min-1` · `min` · `max` · `max+1`.
+  Thiếu hẳn phân tích biên cho trường có ràng buộc ⇒ **MAJOR**
+- **Phủ HTTP method**: gọi method không được hỗ trợ phải trả **405**; thiếu ⇒ **MINOR**
+
+### B · Payload injection *(§9.2)*
+
+- Payload **hard-code rải trong spec** ⇒ **MAJOR** — gom vào `data/`, một bộ dùng cho nhiều endpoint
+- Bộ mẫu thiếu hẳn một họ *(SQL · NoSQL · command · path traversal · XSS lưu trữ)* ⇒ **MINOR**
+  kèm nêu rõ họ nào thiếu
+
+### C · Mong đợi phải cụ thể
+
+- Mong đợi đúng là **400/422 + thông điệp lỗi có cấu trúc**, hoặc dữ liệu được làm sạch
+- Assert kiểu "không sập" ⇒ **MAJOR** — một endpoint trả 200 kèm dữ liệu đã bị nhiễm vẫn "không sập"
+- Assert thông điệp lỗi **không rò** stack trace / tên bảng / phiên bản ⇒ thiếu ⇒ **MINOR**
+
+### D · Ranh giới của trạm này
+
+- Đây **không** phải kiểm thâm nhập. Soát script, không đánh giá mức độ an toàn của hệ thống.
+  Biên bản kết luận *"hệ thống an toàn"* ⇒ **MAJOR** — vượt thẩm quyền của lượt soát *(R04 tinh thần)*
+
+---
+
+## Kiểm cơ học + Output
+
+Như `endpoint.md` Phase 3 và §Output.