@educa-corp/sdd-framework 0.9.7 → 0.9.8

package/core/commands/qc-review-testcase.md

@@ -6,8 +6,9 @@ ported_from: ai-automation-qc-base
 
 # /qc-review-testcase — QC Review Gate: test case
 
-> Stage 4 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test →
-> **qc-review-testcase** → qc-design-script → qc-run-script → qc-report). Soát `.Test.md` do
+> Trạm 4/9 của dây chuyền QC automation (qc-analyze → qc-plan → qc-design-test → **qc-review-testcase** →
+> qc-automation-assess → qc-design-script → qc-review-script → qc-run-script ∥ qc-run-manualtest
+> → qc-report). Soát `.Test.md` do
 > `/qc-design-test` sinh: coverage · độ rõ · trace. Cặp với `/qc-review-script` — hai lệnh, hai vai.
 
 ## Gate
@@ -339,10 +340,10 @@ File **phải** chứa đúng một dòng theo khuôn này, ở §Tổng quan:
 ```
 hoặc
 ```
-**Verdict:** NEEDS_FIX
+**Verdict:** REVISION_REQUIRED   ← hoặc REJECTED khi có BLOCKER
 ```
 
-`APPROVED` khi **điểm `≥80` VÀ không còn `FAIL` chặn**; ngược lại `NEEDS_FIX`.
+Verdict suy từ **số đếm lỗi**, không từ điểm — `≥1 BLOCKER` → `REJECTED` · `≥1 MAJOR` → `REVISION_REQUIRED` · chỉ MINOR/SUGGESTION → `APPROVED_WITH_SUGGESTIONS` · sạch → `APPROVED`. Xem `qa-reviewer/shared/review-file-template.md` §Verdict.
 
 > **Đây là contract, không phải định dạng cho đẹp.** `/qc-automation-assess` (Đợt 2 · b3) **loại**
 > khỏi lượt mọi TC chưa `APPROVED`. Đổi chuỗi này là làm trạm đó mù — nên nếu phải đổi, đổi ở cả
@@ -401,9 +402,9 @@ Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
 ```
 /qc-review-testcase Hoàn tất — {UC-ID} vòng #{N}
 Điểm  : {XX}/100  ({fail} FAIL × −5đ · {warn} WARN × −2đ){nếu có vòng trước: "   ← vòng #{N-1}: {YY}/100"}
-Verdict: {APPROVED | NEEDS_FIX} — {n} findings ({crit} chặn)
+Verdict: {APPROVED | APPROVED_WITH_SUGGESTIONS | REVISION_REQUIRED | REJECTED} — {n} findings ({blk} BLOCKER · {maj} MAJOR · {min} MINOR · {sug} SUGGESTION)
 File  : {qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md (thêm 1 hàng vào bảng Tổng quan)
 Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
-Next (APPROVED) : /qc-design-script {UC-ID}
-     (NEEDS_FIX → sửa TC bị gắn cờ bằng /qc-design-test {UC-ID}, rồi chạy lại lệnh này)
+Next (≥ APPROVED_WITH_SUGGESTIONS) : /qc-design-script {UC-ID}
+     (REVISION_REQUIRED | REJECTED → sửa TC bị gắn cờ bằng /qc-design-test {UC-ID}, rồi chạy lại lệnh này)
 ```

package/core/commands/qc-run-manualtest.md

@@ -5,7 +5,7 @@ updated: 2026-09-16
 
 # /qc-run-manualtest — Ghi kết quả test TAY vào sổ trace
 
-> Stage 7b. QC chạy tay các TC mang `Automatable: N`, lệnh **hỏi từng TC** rồi ghi `qc_status`
+> Trạm 8b/9 của dây chuyền QC automation — song song với trạm 8. QC chạy tay các TC mang `Automatable: N`, lệnh **hỏi từng TC** rồi ghi `qc_status`
 > vào sổ trace. Không có lệnh này thì những scenario ấy nằm `not_run` vĩnh viễn — và `/qc-report`
 > sẽ chấm cả PRD là **FAIL**, không cách nào sửa.
 

package/core/commands/qc-run-script.md

@@ -6,7 +6,7 @@ ported_from: ai-automation-qc-base
 
 # /qc-run-script — Chạy automation script (ghi qc_status)
 
-> Stage 7. Chạy script **đã `APPROVED`**, phân loại mỗi FAIL, rồi ghi `qc_status` **chính thức**
+> Trạm 8/9 của dây chuyền QC automation. Chạy script **đã `APPROVED`**, phân loại mỗi FAIL, rồi ghi `qc_status` **chính thức**
 > vào sổ trace. **Không sinh script** — đó là `/qc-design-script`.
 
 ## Gate
@@ -200,8 +200,8 @@ cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắ
 
 | Đọc được | Làm gì |
 |---|---|
-| `APPROVED` | đi tiếp |
-| `NEEDS_FIX` | **DỪNG** — `❌ Script chưa đạt. Sửa rồi soát lại bằng /qc-review-script {UC-ID}.` |
+| `APPROVED` · `APPROVED_WITH_SUGGESTIONS` | **đi tiếp** — in một dòng bằng chứng:<br/>`✅ Cổng script đã soát: {verdict} — {đường dẫn file vừa đọc}` |
+| `REVISION_REQUIRED` · `REJECTED` | **DỪNG** — `❌ Script chưa đạt. Sửa rồi soát lại bằng /qc-review-script {UC-ID}.` |
 | Không có file | **DỪNG** — `❌ Chưa soát script. Chạy /qc-review-script {UC-ID} trước.` |
 
 > **Cổng này là lý do `/qc-review` phải tách đôi** (Đợt 2 · b1). Biên bản cũ không nói nó soát
@@ -222,15 +222,22 @@ cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắ
 > hoặc **chạy 0 test mà vẫn báo xanh** — rồi con số đó đi thẳng vào `/qc-report` thành số liệu
 > người ta tin. Đây là kiểu hỏng tệ nhất: một báo cáo xanh trên một lần chạy **không tồn tại**.
 
-## Role & stack (theo module qc-playwright)
+## Role & stack (module theo nền — bảng §2b của `steps/qc-scope.md`)
 
-Bạn là **QC Script Runner**. Chạy pytest-playwright script đã có, thu bằng chứng, phân loại FAIL,
+Bạn là **QC Script Runner**. Chạy script đã có **theo nền đã phân giải ở §2b**, thu bằng chứng, phân loại FAIL,
 ghi kết quả theo từng scenario. **KHÔNG sửa script, KHÔNG sinh script.**
 
-## Skills — chọn layer, nạp MỘT file (`{paths.qc_skills_dir}/qa-runner/`)
+## Skills — chọn NỀN, nạp MỘT file (`{paths.qc_skills_dir}/qa-script-runner/`)
 
-`functional/{gui-screen,gui-feature,api}.md`, `integration.md`, `e2e.md`,
-`non-functional.md`, `exploratory/session.md`.
+**Nạp theo nền đã phân giải ở `steps/qc-scope.md` §2b:**
+
+| `active_platform` | File |
+|---|---|
+| `web` · `webview` · `system` | `web/run.md` |
+| `app` · `app-ios` · `app-android` | `mobile/run.md` |
+
+Báo cáo sau lượt chạy: `report.md` — reporter **theo nền** *(Playwright HTML Report cho
+web·system, Allure v2.x cho app)*.
 
 ---
 

package/core/modules/qc-playwright-ts/module.yaml

@@ -0,0 +1,13 @@
+name: "QC Playwright (TypeScript)"
+version: "1.0.0"
+description: "QC automation — Playwright + TypeScript. Phục vụ HAI nền: web (automation/) và API/system (api-automation/)"
+language: "TypeScript"
+framework: "Playwright Test"
+stack_type: "qc-automation"
+default_layer_order:
+  - Test case Markdown (.Test.md) — nguồn sự thật, review xong mới sinh code
+  - Test data (data/*.data.ts)
+  - Page Object (pages/*.page.ts)  ·  API Object (api/*.api.ts)
+  - Fixture (fixtures/*.fixture.ts)
+  - Spec (tests/[feature]/*.spec.ts)
+test_framework: "Playwright Test + expect"

package/core/modules/qc-playwright-ts/stack-profile.yaml

@@ -0,0 +1,99 @@
+# QC automation module — Playwright + TypeScript.
+#
+# Nguồn: upstream/qc-base-new/Automation-Standards.md (Approved) §1 §2.3 §3 §6.1 §9.2
+#        upstream/qc-base-new/API-Testing-Standards.md (Approved) §1 §2.1 §7.2 §7.3
+#
+# Module này phục vụ HAI nền — web và system(API) — vì cả hai dùng CÙNG stack
+# (AD-API-001: "Playwright API mode thay vì framework riêng, để tái dùng infrastructure
+# với Web testing"). Tách làm hai module là khai dãy phiên bản Playwright/TS hai lần.
+# Nền mobile ở modules/qc-wdio-appium (stack khác hẳn: WebdriverIO + Appium).
+#
+# CHỌN NỀN LÚC CHẠY: theo `active_platform` đã phân giải ở trạm 1 (steps/qc-scope.md).
+# KHÔNG có key cấu hình riêng cho việc này — một pass QC đã khoá đúng một nền, hỏi lại
+# bằng một field thứ hai là tạo hai đáp án cho một câu.
+#
+#   web · webview  →  layout.web       app · app-ios · …  →  qc-wdio-appium
+#   system         →  layout.api
+
+versions:
+  playwright: "latest"        # Playwright Test — runner + assertion + reporter, không thêm Jest/Mocha
+  typescript: "v5.x"          # strict mode
+
+build:
+  web:
+    test:       "npx playwright test"
+    e2e:        "npx playwright test tests/ --grep @e2e"
+    report:     "npx playwright show-report"
+    show_trace: "npx playwright show-trace test-results/<test>/trace.zip"
+  api:
+    test:       "npx playwright test --config=api-automation/playwright.config.ts"
+    report:     "npx playwright show-report"
+
+layout:
+  # §2.3 của Automation-Standards — mirror test-suites/, KHÔNG đổi tên thư mục.
+  web: |
+    automation/
+    ├── playwright.config.ts
+    ├── package.json  ·  tsconfig.json
+    ├── pages/        ← Page Object: base.page.ts · <feature>.page.ts
+    ├── tests/        ← spec, mirror test-suites/: {TICKET-ID}/<feature>-happy-path.spec.ts
+    ├── data/         ← <feature>.data.ts  (ref TDS artifact)
+    ├── fixtures/     ← base.fixture.ts
+    ├── helpers/      ← <helper>.ts
+    └── reports/      ← sinh ra, gitignored
+
+  # §2.1 của API-Testing-Standards — thư mục gốc RIÊNG, "tách biệt với automation/ (web)
+  # để tránh xung đột config và dependency". api/ thay cho pages/; không có Page Object.
+  api: |
+    api-automation/
+    ├── playwright.config.ts     ← config riêng của API mode
+    ├── package.json  ·  tsconfig.json
+    ├── api/          ← API Object: base.api.ts · <resource>.api.ts
+    ├── tests/        ← {TICKET-ID}/<feature>-{happy-path,negative,security}.spec.ts
+    ├── data/         ← <resource>.data.ts
+    ├── fixtures/     ← api.fixture.ts  (shared API context, auth token)
+    ├── helpers/      ← schema.helper.ts · auth.helper.ts
+    └── reports/      ← sinh ra, gitignored
+
+naming:
+  # §9.2 (web) · §7.2 (api). File kebab-case; class PascalCase; method camelCase verb-first.
+  page_object:  "pages/<feature>.page.ts      → class <Feature>Page extends BasePage"
+  api_object:   "api/<resource>.api.ts        → class <Resource>API extends BaseAPI"
+  spec:         "tests/{TICKET-ID}/<feature>-<scenario>.spec.ts"
+  test_data:    "data/<resource>.data.ts"
+  fixture:      "fixtures/<name>.fixture.ts"
+  helper:       "helpers/<name>.helper.ts"
+  test_case_md: "{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md"
+
+locator_priority:
+  # §6.1 — chỉ áp cho nền web. API không có locator.
+  web: "getByRole → getByLabel → getByPlaceholder → getByTestId → getByText → locator('[css]') (last resort, ghi lý do)"
+  note: "Giá trị test-id lấy từ bảng Test Selectors §4.5.6 của tech-doc, KHÔNG scan runtime.
+         Tên thuộc tính đọc từ `@trace.testid_attr`; nếu ≠ data-testid thì phải gọi
+         `expect.configure`/`selectors.setTestIdAttribute` trước khi dùng getByTestId."
+
+reporting:
+  web: "Playwright HTML Report"     # §1 + OQ-01 đã đóng 2026-06-02: Phase 1 KHÔNG cần Allure
+  api: "Playwright HTML Report"     # Allure defer Phase 2
+
+trace_tags:
+  # Dấu comment là `//` (TypeScript) — stack cũ dùng `#`. Bộ parse bám chuỗi `@trace.*`,
+  # không bám dấu comment (bin/lint-trace.js:733), nên đổi dấu là an toàn; lane DEV đã
+  # dùng `//` từ trước.
+  verifies:  "// @trace.verifies={UC-ID}-SC{N}"
+  source:    "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
+  test_type: "// @trace.test_type=functional|integration|e2e|non-functional"
+
+artifact_id_prefix:
+  # §7.3 API-Testing-Standards — dãy API độc lập với web/mobile.
+  api: "TS-API · SCN-API · TC-API · AUT-API · TDS-API"
+
+# Luật VIẾT CODE (Page Object 3 lớp, assertion, wait, anti-pattern, flaky policy) KHÔNG ở
+# đây — chúng ở skills/qc/qa-script-designer/_shared/web-conventions.md.
+# Ranh giới: hồ sơ này trả lời "chạy ở đâu, đặt tên gì"; skill trả lời "viết thế nào".
+# Vì sao tách: hồ sơ được đọc NGUYÊN vào ngữ cảnh mỗi lần chạy lệnh, còn skill nạp MỘT
+# file theo lane — nhồi luật vào đây bắt mọi lần làm web phải đọc cả luật của nền khác.
+
+# qc_status: /qc-run-script ghi pass|fail|skip|not_run + qc_run_at vào
+# {trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv — song song với dev_selftest,
+# và đây là kết quả QC CHÍNH THỨC hiện trên Living Docs.

package/core/modules/qc-wdio-appium/module.yaml

@@ -0,0 +1,20 @@
+name: "QC WebdriverIO + Appium (mobile)"
+version: "1.0.0"
+description: "QC automation cho nền app — WebdriverIO v9 + Appium v2 + UiAutomator2, TypeScript"
+language: "TypeScript"
+framework: "WebdriverIO + Appium"
+stack_type: "qc-automation"
+default_layer_order:
+  - Test case Markdown (.Test.md) — nguồn sự thật, review xong mới sinh code
+  - Test data (data/*.data.ts)
+  - Screen Object (screens/*.screen.ts)
+  - Helper (api · device · gesture)
+  - Spec (tests/[feature]/*.spec.ts)
+test_framework: "WebdriverIO + Appium + Allure"
+
+# ⚠️ PHẠM VI HẸP — KHAI RÕ (PLAN_v2 §8 luật 4).
+# Module này được port theo KHUNG từ Mobile-Automation-Standards.md (Approved) ở Bước S,
+# và CHƯA được chạy thử trên một dự án mobile thật. Ba mục riêng của nền mobile (§6 API
+# Helper · §9 Gesture Helper · §12 Environment Validation) đã có mặt, nhưng các con số
+# trong đó (toạ độ swipe, timeout) là giá trị mặc định của chuẩn, chưa hiệu chỉnh theo
+# thiết bị thật. Lần đầu chạy thật: đối chiếu lại §12 trước khi tin kết quả.

package/core/modules/qc-wdio-appium/stack-profile.yaml

@@ -0,0 +1,107 @@
+# QC automation module — WebdriverIO + Appium, nền app (mobile).
+#
+# Nguồn: upstream/qc-base-new/Mobile-Automation-Standards.md (Approved)
+#        §1 §2 §3 §6 §7.1 §9 §10.2 §12
+#
+# ⚠️ ĐÂY KHÔNG PHẢI BẢN COPY CỦA qc-playwright-ts. Chuẩn mobile dài hơn chuẩn web 129 dòng,
+# và phần dôi ra không phải văn vẻ: §6 API Helper · §9 Gesture Helper · §12 Environment
+# Validation Checklist. Một hồ sơ mobile copy từ web sẽ im lặng thiếu ba mục đó, và cái
+# thiếu chỉ lộ ra khi có người chạy thật trên máy thật — tức SAU khi đã tin là xong.
+#
+# CHỌN NỀN LÚC CHẠY: theo `active_platform` ở trạm 1 (steps/qc-scope.md).
+#   app · app-ios · app-android  →  module này
+#   web · webview · system       →  qc-playwright-ts
+
+versions:
+  appium:      "v2.x"          # latest
+  webdriverio: "v9.x"          # latest — test runner
+  typescript:  "v5.x"
+  android_driver: "UiAutomator2"   # driver@latest
+  emulator:    "Genymotion"        # trial, latest
+
+build:
+  test:      "npx wdio ./wdio.config.ts"
+  android:   "npx wdio ./wdio.android.config.ts"
+  dry_run:   "npx wdio ./wdio.config.ts --dry-run"
+  appium:    "npx appium"
+  report:    "npx allure generate reports/allure-results --clean && npx allure open"
+
+layout:
+  mobile: |
+    projects/[ProjectName]/mobile-automation/
+    ├── wdio.config.ts            ← WebdriverIO + Appium
+    ├── wdio.android.config.ts    ← override riêng Android
+    ├── package.json              ← dependency mobile RIÊNG
+    ├── tsconfig.json  ·  .env.example
+    ├── screens/      ← Screen Object (≈ Page Object): base.screen.ts · <feature>.screen.ts
+    ├── tests/        ← {TICKET-ID}/<feature>-{happy-path,negative,api-sync}.spec.ts
+    ├── data/         ← <feature>.data.ts  (dùng chung chuẩn với web)
+    ├── fixtures/     ← base.fixture.ts
+    ├── helpers/      ← api.helper.ts · device.helper.ts · gesture.helper.ts
+    └── reports/      ← Allure output, gitignored
+
+naming:
+  # §10.2 — khác web: hậu tố "Screen", không phải "Page".
+  screen_object: "screens/<feature>.screen.ts  → class <Feature>Screen extends BaseScreen"
+  spec:          "tests/{TICKET-ID}/<feature>-<scenario>.spec.ts"
+  test_data:     "data/<feature>.data.ts"
+  helper:        "helpers/<name>.helper.ts"
+  test_case_md:  "{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md"
+
+locator_priority:
+  # §7.1 — KHÁC HẲN web. Không có getByRole/getByLabel.
+  order: "~accessibilityId → id (resource-id) → xpath (last resort, ghi lý do)"
+  note: "`~accessibilityId` dùng Android content-desc và YÊU CẦU dev gán. Giá trị lấy từ
+         bảng Test Selectors §4.5.6 của tech-doc, tên thuộc tính đọc từ `@trace.testid_attr`
+         (RN: testID · Flutter: Key/Semantics(identifier:) · native iOS: accessibilityIdentifier)."
+
+# ── Ba mục CHỈ mobile mới có. Thiếu bất kỳ mục nào là hồ sơ chưa xong. ──
+
+api_helper:
+  # §6 — mobile verify dữ liệu server bằng Playwright request, TÁI DÙNG từ automation/ (web).
+  file: "helpers/api.helper.ts"
+  impl: "class ApiHelper dùng `request`/`APIRequestContext` của @playwright/test;
+         baseUrl = process.env.API_BASE_URL"
+  why:  "spec `*-api-sync.spec.ts` đối chiếu thứ hiện trên màn hình với thứ server thật có —
+         một màn hình hiển thị đúng dữ liệu CŨ vẫn là bug, và UI assertion không bắt được."
+
+gesture_helper:
+  # §9 — web không cần mục này.
+  file: "helpers/gesture.helper.ts"
+  impl: "class GestureHelper — scrollDown · swipeLeft · … dựng bằng
+         browser.action('pointer', { parameters: { pointerType: 'touch' } })"
+  note: "Toạ độ mặc định trong chuẩn (x=540, startY=800, endY=300, duration=500) là giá trị
+         của MỘT cấu hình màn hình. Hiệu chỉnh theo thiết bị thật trước khi tin kết quả."
+
+environment_validation:
+  # §12 — Gate 6B. Chạy TRƯỚC mọi lần execute mobile.
+  gate: "6B"
+  checklist:
+    - "Genymotion emulator đang chạy và `adb devices` thấy thiết bị"
+    - "APK đúng version đã install trên emulator"
+    - "App khởi động thành công (smoke check bằng tay)"
+    - "API_BASE_URL gọi được TỪ emulator: `adb shell curl ${API_BASE_URL}/health`"
+    - "Test data đã seed trên server (nếu cần)"
+    - ".env đã cấu hình đúng environment hiện tại"
+    - "Appium server connect được: `npx appium` chạy không lỗi"
+    - "WDIO dry-run pass: `npx wdio ./wdio.config.ts --dry-run`"
+  why: "Tám mục này là ranh giới giữa 'test đỏ' và 'môi trường chưa sẵn sàng'. Bỏ qua thì
+        mọi FAIL đều trông như product-gap, và QC đi mở bug cho một cái emulator chưa bật."
+
+reporting:
+  # §1 — ⚠️ NGƯỢC với luật "No Allure" của stack cũ và của nền web.
+  tool: "Allure Report v2.x"
+  note: "Nền web dùng Playwright HTML Report (OQ-01 đóng 2026-06-02: Allure defer Phase 2).
+         Nền mobile thì Allure là BẮT BUỘC theo §1. Hai nền khác nhau ở điểm này — đừng
+         'thống nhất' chúng lại; đó là quyết định của chuẩn, không phải chỗ sót."
+
+trace_tags:
+  verifies:  "// @trace.verifies={UC-ID}-SC{N}"
+  source:    "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
+  test_type: "// @trace.test_type=functional|integration|e2e|non-functional"
+
+# Luật VIẾT CODE ở skills/qc/qa-script-designer/_shared/mobile-conventions.md.
+# Ranh giới: hồ sơ này trả lời "chạy ở đâu, đặt tên gì"; skill trả lời "viết thế nào".
+
+# qc_status: /qc-run-script ghi pass|fail|skip|not_run + qc_run_at vào
+# {trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv

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

@@ -60,7 +60,7 @@ Ghi vào **mục Data Flow** của `{qc_artifact_dir}REQUIREMENT_ANALYSIS.md`
 - Sơ đồ/list luồng dữ liệu cho mỗi kịch bản chính.
 - Danh sách integration point + state change + failure point.
 - Gợi ý loại test cần cho từng điểm (gui-feature / integration / e2e) khi sang qa-designer.
-- Dữ liệu/trạng thái cần chuẩn bị & cleanup → đầu vào fixture cho qa-runner.
+- Dữ liệu/trạng thái cần chuẩn bị & cleanup → đầu vào fixture cho `qa-script-designer`.
 
 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 `{qc_artifact_dir}DOC_GAP.md` (loại MISSING / OPEN QUESTION).

package/core/skills/qc/qa-automation-assess/matrix.md

@@ -99,9 +99,12 @@ biến một TC đang `Y` thành `N`.
 tag `@trace.verifies`. Không có cột này thì `/qc-run-script` phải suy đường dẫn từ quy ước đặt
 tên — suy sai thì chạy sai bộ test, hoặc **chạy 0 test mà vẫn báo xanh**.
 
-> **Đường dẫn theo stack HIỆN TẠI** — module `qc-playwright` (Python + pytest-playwright):
-> `tests/<project>/test_<feature>.py` + `pages/<feature>_page.py`, theo
-> `modules/qc-playwright/stack-profile.yaml` §layout.
+> **Đường dẫn theo module đã phân giải ở `steps/qc-scope.md` §2b** — `qc-playwright-ts`
+> *(web · system)* hoặc `qc-wdio-appium` *(app)*, mục `§layout.{web|api|mobile}` của
+> `stack-profile.yaml` tương ứng. **Đừng viết cứng tên module ở đây.**
+>
+> *(Tên file theo `§naming` của module: `<feature>.page.ts` + `<feature>-<scenario>.spec.ts`
+> (web) · `<resource>.api.ts` (system) · `<feature>.screen.ts` (app).)*
 >
 > *(Đề xuất gốc của đội QC viết theo TypeScript + Playwright Test / WebdriverIO. Việc đổi stack
 > là một bước RIÊNG, cố ý tách khỏi đợt tách lệnh — xem quyết định F3, Đợt 2 · b2. Khi stack

package/core/skills/qc/{qa-runner → qa-designer}/exploratory/session.md

@@ -28,9 +28,15 @@ expected/actual) · `#QUESTION`, `#IDEA` placeholder · summary cuối session.
 ## Mode 2 — Convert Findings
 Input: session note (#BUG + #IDEA).
 - **Bug report** mỗi #BUG: title, severity, priority, steps to reproduce, expected/actual, hypothesis root cause.
-- **Functional TC mới:** mỗi #BUG đã fix → 1–2 TC regression; mỗi #IDEA → TC nếu đủ rõ (hoặc backlog).
-  Đặt đúng layer; bám format TC (Test Data list, Trace BR, 🚫 Block); trace "Origin: Exploratory session <date>".
+- **Functional TC mới → KHÔNG viết luật ở đây.** Dùng `explore-to-functional.md` Phase 4 — nó có
+  format `TC_<FEATURE>.Test.md` đầy đủ (metadata list, Trace BR, 🚫 Block, Test Data, Steps,
+  Expected 1 bullet, Trace matrix). Chỉ thêm một điều riêng của đường này: mỗi TC sinh từ session
+  phải mang `Origin: Exploratory session <date>`.
 - **Weekly summary** (nếu yêu cầu): overview, top findings, coverage gap, recommendations.
 
+> **Vì sao Mode 2 trỏ đi chứ không tự viết** *(Bước S · S2, 2026-09-17)*: bản cũ mô tả lại format TC
+> bằng một câu rút gọn, trong khi `explore-to-functional.md` Phase 4 đã có bản đủ. Hai bản của một
+> format thì bản ngắn sẽ lạc hậu trước — và người đọc bản ngắn không biết mình đang đọc bản cũ.
+
 ## Output
 Mode 1: file session note. Mode 2: bug reports + file TC trong `{qc_artifact_dir}test-cases/` + summary.

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

@@ -16,7 +16,7 @@ Nạp cùng `shared/` (khuôn + độ chính xác + từ điển hành động)
 
 ## Khi KHÔNG trigger
 - Test qua giao diện → `functional/gui-screen`/`gui-feature`
-- Luồng dữ liệu API ↔ DB/service khác → `integration/api` · message/event → `integration/kafka`
+- Luồng dữ liệu API ↔ DB/service khác → `integration/api` · message/event → `integration/queue`
 
 ---
 

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`
 
 ---
 

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`
 
 ---
 

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`
 
 ---
 

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)
 ```