@educa-corp/sdd-framework 0.9.7 → 0.9.8

package/core/skills/qc/qa-script-designer/mobile/functional/feature.md

@@ -0,0 +1,32 @@
+---
+version: 1.0
+updated: 2026-09-09
+---
+
+# Gen Script — Mobile Functional Feature (đa màn hình, Flutter)
+
+**Đọc `_shared/mobile-conventions.md` trước.**
+
+## Khi nào trigger
+- Convert TC feature đa-màn (output `qa-designer/functional/gui-feature.md`, platform `app`),
+  TC Automatable=Y.
+
+## Khi KHÔNG trigger
+- Gọn 1 màn → `functional/screen.md` · đầu-cuối xuyên hệ thống ngoài → `e2e.md`
+
+## Phase 1 — Clarify
+Liệt kê các màn/Page Object cần; state truyền giữa màn (đặc biệt qua navigation Flutter —
+argument truyền route, không phải chỉ URL như web).
+
+## Phase 2 — Generate
+Điều hướng giữa Page Object: test tự import Page Object màn kế tiếp sau action điều hướng
+(singleton pattern WDIO — khác Playwright là PO theo instance `page`). Phủ đúng TC
+Automatable=Y. Assert sau mỗi chặng có side-effect, không dồn về cuối.
+
+## Phase 3 — Self-Verify
+```bash
+npx tsc --noEmit
+```
+
+## Output
+Script + nhiều Page Object (mỗi màn) trong `mobile-automation/pageobjects/{TICKET-ID}/...`.

package/core/skills/qc/qa-script-designer/mobile/functional/screen.md

@@ -0,0 +1,42 @@
+---
+version: 1.0
+updated: 2026-09-09
+---
+
+# Gen Script — Mobile Functional Screen (1 màn hình, Flutter)
+
+**Đọc `_shared/mobile-conventions.md` trước** (Locator Strategy — vì sao cần
+`FlutterIntegration`, Page Object, Wait/Assertion, Common Pitfalls).
+
+## Khi nào trigger
+- Convert TC functional 1 màn (output `qa-designer/functional/gui-screen.md`, platform `app`),
+  TC Automatable=Y, `TC_<FEATURE>.md` đã approve.
+
+## Khi KHÔNG trigger
+- Feature đa-màn → `functional/feature.md` · web → dùng bộ `qa-script-designer/web/*`
+
+## Phase 1 — Clarify
+Đọc `TC_<FEATURE>.md` + `TEST_DATA_PLAN.md`. Page Object cho màn này đã có chưa. Đọc contract
+`ValueKey` §4.5.6 tech-doc gộp cho màn này (xem `_shared/mobile-conventions.md` §1.1).
+**§4.5.6 không đủ/không có** → probe widget tree thật bằng Appium Inspector/Flutter DevTools
+trước khi viết locator (xem `_shared/mobile-conventions.md` §1.2) — không đoán `ValueKey` từ
+ảnh chụp màn hình.
+
+## Phase 2 — Generate
+Phủ đúng TC Automatable=Y của màn này (đếm khớp `AUTOMATION_ASSESSMENT.md`). Rào cản kỹ
+thuật (thiếu `ValueKey`, permission dialog chặn) → viết test tốt nhất có thể + đánh dấu
+`it.skip` có lý do + ghi `IMPROVE-xxx`, không bỏ sót TC.
+
+Nhóm `describe`: GUI (hiển thị/enable-disable) → Functional (input/validation/action). Data từ
+`TEST_DATA_PLAN.md`.
+
+## Phase 3 — Self-Verify
+```bash
+npx tsc --noEmit
+```
+Đối chiếu thủ công số `it(...)` sinh ra = số TC Automatable=Y của màn này.
+
+## Output
+`mobile-automation/test/specs/{TICKET-ID}/<screen-slug>.spec.ts` +
+`mobile-automation/pageobjects/{TICKET-ID}/<screen-slug>.page.ts`
+(xem quy tắc slug/kiểm tra tồn tại trước khi tạo ở `_shared/file-naming-and-folders.md`).

package/core/skills/qc/qa-script-designer/mobile/integration.md

@@ -0,0 +1,39 @@
+---
+version: 1.0
+updated: 2026-09-09
+---
+
+# Gen Script — Mobile Integration (App↔Backend)
+
+**Đọc `_shared/mobile-conventions.md` trước.** Phần backend (DB/Kafka/API thuần) dùng lại
+đúng client/fixture của `qa-script-designer/web/integration.md` — chỉ khác **phía trigger**
+là thao tác trên app qua WebdriverIO thay vì Playwright.
+
+## Khi nào trigger
+- TC integration app↔backend (output `qa-designer/integration/gui.md` cho platform `app`),
+  TC Automatable=Y.
+
+## Quy ước riêng — không mock
+Giống nguyên tắc web: gọi API/DB thật trên môi trường test, không mock response. Khác biệt
+mobile: capture network request từ app khó hơn web (không có `page.waitForResponse()`) —
+dùng 1 trong 2 cách:
+- **Proxy chặn network của thiết bị/emulator** (mitmproxy hoặc tương đương) để verify request
+  thật gửi đi — cần setup riêng trong `wdio.conf.ts`.
+- **Verify gián tiếp qua backend**: sau action trên app, query API/DB để xác nhận state đã
+  đổi đúng — đơn giản hơn, đủ dùng cho phần lớn TC integration.
+
+## Phase 1 — Clarify
+Chuỗi tích hợp & chặng cần verify; client/fixture backend đã có chưa (tái dùng từ web nếu đã
+tồn tại trong cùng project).
+
+## Phase 2 — Generate
+Mỗi TC → 1 test: action trên app → verify chặng backend (API/DB). Nhóm happy → contract-negative
+→ concurrency (nếu áp dụng).
+
+## Phase 3 — Self-Verify
+```bash
+npx tsc --noEmit
+```
+
+## Output
+Script trong `mobile-automation/test/specs/{TICKET-ID}/integration/` + client/fixture backend tái dùng.

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

@@ -0,0 +1,39 @@
+---
+version: 1.0
+updated: 2026-09-09
+---
+
+# Gen Script — Mobile Non-Functional (Performance/Security/Compatibility)
+
+**Đọc `_shared/mobile-conventions.md` trước.**
+
+## Công cụ theo loại
+
+| Loại | Công cụ | Assert |
+|---|---|---|
+| **Performance** | Thời gian cold start (`driver.startActivity`/launch time), thời gian render màn hình đo qua timestamp trước/sau `waitForDisplayed` | Ngưỡng cụ thể (vd cold start < 3s) |
+| **Security** | Test lưu trữ local không mã hoá (kiểm tra file app data qua ADB/`driver.execute('mobile: shell', ...)`), test deep-link injection | Assert dữ liệu nhạy cảm không tồn tại dạng plaintext |
+| **Compatibility** | `capabilities` parametrize theo OS version/device profile trong `wdio.conf.ts`; dùng Device Farm (BrowserStack/Sauce Labs/Firebase Test Lab, xem `_shared/mobile-conventions.md` §5.2) khi cần phủ device thật ngoài máy sẵn có | Mỗi profile = 1 target trong TC |
+
+Mobile **không có** hạng mục accessibility qua axe-core (đó là công cụ web); nếu TC yêu cầu
+accessibility mobile, dùng công cụ nền tảng riêng (Android Accessibility Scanner API/iOS
+Accessibility Inspector) — thường vẫn cần một phần thao tác thủ công, đánh dấu rõ trong TC
+gốc thay vì cố automate 100%.
+
+## Quy ước riêng
+- Ngưỡng cụ thể khớp TC gốc; đo elapsed không gồm thời gian setup fixture/app install.
+- Test cần thiết bị/profile đặc biệt → `it.skip(!deviceReady, 'lý do')`.
+
+## Phase 1 — Clarify
+Loại + ngưỡng + công cụ; profile thiết bị cần test.
+
+## Phase 2 — Generate
+Mỗi TC → 1 test đo + assert ngưỡng.
+
+## Phase 3 — Self-Verify
+```bash
+npx tsc --noEmit
+```
+
+## Output
+`mobile-automation/test/specs/{TICKET-ID}/non-functional/<feature>-<scenario>.spec.ts` + helper đo (`utils/measure.ts`).

package/core/skills/qc/qa-script-designer/web/e2e.md

@@ -0,0 +1,36 @@
+---
+version: 1.0
+updated: 2026-09-09
+---
+
+# Gen Script — Web E2E Journey
+
+**Đọc `_shared/web-conventions.md` trước.**
+
+## Khi nào trigger
+- Convert TC E2E journey (output `qa-designer/e2e/journey.md`), TC Automatable=Y.
+
+## Khi KHÔNG trigger
+- Test 1 màn/field → `functional/*` · 1 điểm tích hợp → `integration.md`
+
+## Quy ước riêng
+- Chuỗi Page Object xuyên các màn; verify points (V1…Vn của journey) thành `expect()` rõ ràng
+  **sau mỗi chặng**, không dồn hết về cuối (Common Pitfall #4).
+- Tiền điều kiện phức tạp (tài khoản role, dữ liệu buổi/lớp) qua fixture Playwright riêng,
+  không inline trong test; cleanup sau journey.
+- Cần verify hệ thống ngoài (DB/CRM) → client/fixture riêng, giống `integration.md`.
+
+## Phase 1 — Clarify
+Các màn/PO + hệ thống verify; tài khoản/data cần dựng; điểm cleanup.
+
+## Phase 2 — Generate
+Mỗi journey → 1 test; verify đủ V1…Vn. Journey phụ thuộc gap → `test.fixme('...GAP-xx')`.
+
+## Phase 3 — Self-Verify
+```bash
+npx tsc --noEmit
+npx playwright test automation/tests/{TICKET-ID}/e2e/<feature>-<scenario>.spec.ts --list
+```
+
+## Output
+`automation/tests/{TICKET-ID}/e2e/<feature>-<scenario>.spec.ts` + Page Object/client tái dùng.

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

@@ -0,0 +1,39 @@
+---
+version: 1.0
+updated: 2026-09-09
+---
+
+# Gen Script — API (dùng chung mọi platform)
+
+Skill sinh script test API thuần (không qua UI), dùng `@playwright/test` `APIRequestContext`.
+Test API **không phân biệt platform gọi nó là web hay mobile** — backend là một, nên file này
+dùng chung cho cả pipeline web và mobile (không có bản mobile riêng).
+
+## Khi nào trigger
+- Convert TC API (output `qa-designer/functional/api.md`), TC Automatable=Y, `TC_<FEATURE>.md` đã approve.
+
+## Khi KHÔNG trigger
+- Test qua UI → `functional/gui-screen.md`/mobile tương ứng · tích hợp đa thành phần → `integration.md`
+
+## Quy ước riêng (ngoài Locator/Wait/Assertion chung — API không có locator)
+- Client API gói trong fixture Playwright (`test.extend`) — base URL + auth header từ
+  `process.env.*`, KHÔNG rải request rời rạc trong test.
+- Assertion: status code **và** field response (JSON path) — không chỉ status code.
+- Test độc lập: tạo data qua API → dùng → cleanup qua API (`test.afterEach`), không phụ thuộc
+  thứ tự chạy.
+
+## Phase 1 — Clarify
+Base URL/auth/role theo `TEST_DATA_PLAN.md`; client fixture đã có chưa.
+
+## Phase 2 — Generate
+Mỗi TC Automatable=Y → 1 test gọi endpoint với request từ `TEST_DATA_PLAN.md`; assert status +
+field. Nhóm `test.describe`: happy → validation → auth → not-found → edge.
+
+## Phase 3 — Self-Verify
+```bash
+npx tsc --noEmit
+npx playwright test automation/tests/{TICKET-ID}/functional/api/<feature>-<scenario>.spec.ts --list
+```
+
+## Output
+`automation/tests/{TICKET-ID}/functional/api/<feature>-<scenario>.spec.ts` + client fixture (`fixtures/api-client.ts`) nếu mới.

package/core/skills/qc/qa-script-designer/web/functional/gui-feature.md

@@ -0,0 +1,34 @@
+---
+version: 1.0
+updated: 2026-09-09
+---
+
+# Gen Script — Web Functional GUI Feature (đa màn hình)
+
+Skill sinh script cho feature span ≥2 màn. **Đọc `_shared/web-conventions.md` trước.**
+
+## Khi nào trigger
+- Convert TC feature đa-màn (output `qa-designer/functional/gui-feature.md`), TC Automatable=Y,
+  `TC_<FEATURE>.md` đã approve.
+
+## Khi KHÔNG trigger
+- Gọn 1 màn → `functional/gui-screen.md` · đầu-cuối xuyên hệ thống ngoài → `e2e.md`
+
+## Phase 1 — Clarify
+Liệt kê các màn/Page Object cần; state truyền giữa màn (giá trị nhập màn A hiển thị đúng ở
+màn B); data từ `TEST_DATA_PLAN.md`.
+
+## Phase 2 — Generate
+Mỗi Page Object action điều hướng **trả về PO màn kế tiếp** (`return new NextPage(this.page)`)
+— test chuỗi `const p2 = await p1.doAction()`. Phủ đúng TC Automatable=Y (đếm khớp
+`AUTOMATION_ASSESSMENT.md`). Assert **sau mỗi chặng có side-effect**, không chỉ ở bước cuối
+(xem Common Pitfall #4 trong `_shared/web-conventions.md`).
+
+## Phase 3 — Self-Verify
+```bash
+npx tsc --noEmit
+npx playwright test automation/tests/{TICKET-ID}/<feature>-<scenario>.spec.ts --list
+```
+
+## Output
+Script + nhiều Page Object (mỗi màn) trong `automation/pages/{TICKET-ID}/...`.

package/core/skills/qc/qa-script-designer/web/functional/gui-screen.md

@@ -0,0 +1,42 @@
+---
+version: 1.0
+updated: 2026-09-09
+---
+
+# Gen Script — Web Functional GUI Screen (1 màn hình)
+
+Skill sinh script cho 1 màn hình đơn. **Đọc `_shared/web-conventions.md` trước** (Locator
+Strategy, Page Object, Wait/Assertion, Common Pitfalls) — file này chỉ có phần sinh-script
+riêng của layer.
+
+## Khi nào trigger
+- Convert TC functional 1 màn (output `qa-designer/functional/gui-screen.md`), TC đã
+  `Automatable: Y` (từ `AUTOMATION_ASSESSMENT.md`) và `TC_<FEATURE>.md` đã approve.
+
+## Khi KHÔNG trigger
+- Feature đa-màn → `functional/gui-feature.md` · API thuần → `functional/api.md`
+
+## Phase 1 — Clarify
+Đọc `TC_<FEATURE>.md` (chỉ TC Automatable=Y) + `TEST_DATA_PLAN.md`. Page Object cho màn này đã có
+chưa → tạo mới nếu chưa. Đọc bảng test-id §4.5.6 tech-doc gộp cho màn này.
+
+## Phase 2 — Generate
+**Phủ đúng các TC Automatable=Y** — đếm TC trong `AUTOMATION_ASSESSMENT.md` có `Y` cho màn
+này = số `test(...)` phải sinh (không hơn, không kém). TC Automatable=Y nhưng phát hiện rào
+cản kỹ thuật lúc viết → `test.fixme('TC_xxx — {lý do}')` + ghi `IMPROVE-xxx` (xem command
+`/qc-design-script` §Testability Improvement List), không âm thầm bỏ qua.
+
+Nhóm theo `test.describe`: GUI (hiển thị/enable-disable) → Functional (input/validation/action).
+Data lấy từ `TEST_DATA_PLAN.md` (theo `TD-xxx` map ở cột "Dùng bởi").
+
+## Phase 3 — Self-Verify (trước khi báo Human approve)
+```bash
+npx tsc --noEmit
+npx playwright test automation/tests/{TICKET-ID}/<screen>.spec.ts --list
+```
+Số test liệt kê = số TC Automatable=Y của màn này. Thiếu → quay lại Phase 2.
+
+## Output
+`automation/tests/{TICKET-ID}/<screen-slug>.spec.ts` +
+`automation/pages/{TICKET-ID}/<screen-slug>.page.ts` (mới nếu cần —
+xem quy tắc slug/kiểm tra tồn tại trước khi tạo ở `_shared/file-naming-and-folders.md`).

package/core/skills/qc/qa-script-designer/web/integration.md

@@ -0,0 +1,43 @@
+---
+version: 1.0
+updated: 2026-09-09
+---
+
+# Gen Script — Web Integration (API↔DB↔service↔queue↔UI)
+
+**Đọc `_shared/web-conventions.md` trước.**
+
+## Khi nào trigger
+- Convert TC integration (output `qa-designer/integration/*`), TC Automatable=Y.
+
+## Khi KHÔNG trigger
+- Chỉ 1 endpoint/UI đơn → `functional/*` · hành trình đầu-cuối → `e2e.md`
+
+## Quy ước riêng — không mock (nguyên tắc quan trọng nhất của integration test)
+Mock API/DB trong integration test biến nó thành **unit test trá hình** — không còn verify
+được tích hợp thật. Luôn gọi network/DB thật trên môi trường test:
+- **GUI↔Backend**: `page.waitForResponse(url)` để capture request/response thật khi thao tác UI.
+- **DB**: client DB thật (qua fixture, connection string từ `process.env.*`), verify trực tiếp
+  bảng/cột — không chỉ verify qua UI hiển thị đúng (UI có thể cache sai mà DB đã đúng, hoặc
+  ngược lại).
+- **Kafka/queue**: producer/consumer thật trong fixture, verify payload nhận được, không
+  giả lập message.
+
+## Phase 1 — Clarify
+Chuỗi tích hợp & chặng cần verify; client/fixture (API/DB/Kafka) đã có chưa; data từ
+`TEST_DATA_PLAN.md`.
+
+## Phase 2 — Generate
+Mỗi TC → 1 test theo data flow: action → verify từng chặng (response → DB → event → UI).
+Nhóm: happy → contract-negative (4xx/5xx + UI hiển thị đúng message) → concurrency (mô tả rõ
+số request đồng thời, assert không race condition — vd unique constraint giữ nguyên).
+
+## Phase 3 — Self-Verify
+```bash
+npx tsc --noEmit
+npx playwright test automation/tests/{TICKET-ID}/integration/<feature>-<scenario>.spec.ts --list
+```
+(Cần môi trường staging/DB/Kafka test khả dụng để chạy thật sau khi generate.)
+
+## Output
+Script + client/fixture (DB/Kafka/API) trong `automation/tests/{TICKET-ID}/integration/` + `fixtures/`.

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

@@ -0,0 +1,42 @@
+---
+version: 1.0
+updated: 2026-09-09
+---
+
+# Gen Script — Web Non-Functional (Performance/Security/Accessibility/Compatibility)
+
+**Đọc `_shared/web-conventions.md` trước** (locator/wait/assertion nền tảng vẫn áp dụng).
+
+## Khi nào trigger
+- Convert TC non-functional (output `qa-designer/non-functional.md`), TC Automatable=Y, có
+  **ngưỡng đo cụ thể** trong `TC_<FEATURE>.md`.
+
+## Công cụ theo loại
+
+| Loại | Công cụ | Assert |
+|---|---|---|
+| **Performance** | `performance.timing`/`page.evaluate` đo, hoặc tích hợp k6/Artillery cho load thật | Ngưỡng cụ thể (`expect(elapsed).toBeLessThan(2000)`), không assert mơ hồ |
+| **Security** | Payload injection trong constant/fixture; test trên môi trường test, KHÔNG production | Status 4xx + không tạo được record + response không lộ PII |
+| **Accessibility** | `@axe-core/playwright` (`AxeBuilder`) | `expect(results.violations).toHaveLength(0)` hoặc filter đúng WCAG level (`wcag2a`/`wcag2aa`) |
+| **Compatibility** | Playwright `projects` trong config (chromium/firefox/webkit), hoặc device emulation | Mỗi project = 1 target trong TC; không hardcode 1 browser |
+
+## Quy ước riêng
+- Assertion **luôn có ngưỡng cụ thể khớp TC gốc** — không tự đặt ngưỡng khác, không
+  `expect(response).toBeTruthy()` mơ hồ.
+- Đo elapsed time: bắt đầu/kết thúc rõ ràng, **không** bao gồm thời gian fixture setup.
+- Test cần môi trường đặc biệt (load server, scanner) → `test.skip(!envReady, 'lý do')`.
+
+## Phase 1 — Clarify
+Loại + ngưỡng + công cụ; môi trường/tải mẫu; data đặc biệt từ `TEST_DATA_PLAN.md`.
+
+## Phase 2 — Generate
+Mỗi TC → 1 test đo + assert ngưỡng; đánh dấu test cần môi trường riêng bằng tag `@slow`.
+
+## Phase 3 — Self-Verify
+```bash
+npx tsc --noEmit
+npx playwright test automation/tests/{TICKET-ID}/non-functional/<feature>-<scenario>.spec.ts --list
+```
+
+## Output
+`automation/tests/{TICKET-ID}/non-functional/<feature>-<scenario>.spec.ts` + helper đo/scan (`utils/measure.ts`).

package/core/skills/qc/qa-script-runner/mobile/run.md

@@ -0,0 +1,38 @@
+---
+version: 1.0
+updated: 2026-09-09
+new_in: QC-Workflow-Proposal (8-phase)
+---
+
+# Run — Mobile (WebdriverIO + Appium)
+
+Skill **tự chứa** cho `/qc-run-script` khi `active_platform = app`.
+
+## Lệnh chạy
+
+```bash
+npx wdio run wdio.conf.ts --spec mobile-automation/test/specs/{TICKET-ID}/...
+```
+
+Video/screenshot on-fail cấu hình qua `afterTest` hook trong `wdio.conf.ts` (chụp screenshot
+khi `passed === false`; ghi video nếu dùng service `wdio-video-reporter` hoặc quay màn hình
+qua `driver.saveRecordingScreen`/tương đương simulator/emulator).
+
+## Đọc kết quả trước khi đề xuất phân loại Fail
+
+Với mỗi FAIL, xem screenshot/video tại thời điểm fail + log Appium server (`appium.log`)
+trước khi đoán:
+
+| Dấu hiệu | Khả năng cao là |
+|---|---|
+| Element "not found" nhưng screenshot cho thấy nó **hiển thị rõ trên màn hình** | **script-bug** — sai `ValueKey`/locator, hoặc app chưa bật `Semantics` đúng cho driver `FlutterIntegration` đọc |
+| Log Appium báo `automationName` không khớp app (vd dùng `UiAutomator2` cho app Flutter không bật accessibility) | **script-bug** — sai cấu hình driver, xem `_shared/mobile-conventions.md` §0 |
+| Hành động đúng (tap đúng nút, đúng data) nhưng app **không phản hồi đúng spec** (không điều hướng, không lưu data) | **product-gap** |
+| Permission dialog native chặn action, test không xử lý | **script-bug** — thiếu xử lý dialog, không phải bug sản phẩm |
+| Fail chỉ xảy ra trên 1 device/OS version cụ thể | Có thể **product-gap** riêng cho compatibility đó — không quy chung là flaky |
+
+## Retry trước khi kết luận (bắt buộc — bước 0 của gate phân loại Fail)
+Mobile vốn có độ trễ/nhiễu cao hơn web (cold start, animation, tốc độ máy) — trước khi đề xuất
+phân loại bất kỳ Fail nào, chạy lại riêng test đó tối đa 2 lần trên cùng device/emulator. Kết
+quả không nhất quán → đề xuất `flaky` (xem `/qc-run-script` §Phân loại mỗi Fail), không phải
+script-bug/product-gap ngay.

package/core/skills/qc/qa-script-runner/report.md

@@ -0,0 +1,41 @@
+---
+version: 1.0
+updated: 2026-09-09
+source: upstream/qc-base-new/Automation-Standards.md §1 + OQ-01 · Mobile-Automation-Standards.md §1 (Approved)
+---
+
+# Report skill — TypeScript stack (Playwright HTML Report / WDIO Allure Report)
+
+Skill **tự chứa** cho `/qc-report`. Báo cáo do **công cụ sinh** — Playwright HTML Report (web·system) hoặc Allure v2.x (app) — **không** dashboard tự viết.
+
+## Web — Playwright HTML Report + Trace Viewer
+
+```bash
+npx playwright test automation/tests/{TICKET-ID}/... --reporter=html
+npx playwright show-report                      # mở report HTML tương tác
+npx playwright show-trace test-results/<nodeid>/trace.zip   # debug 1 test cụ thể
+```
+
+- Report HTML mặc định ở `playwright-report/` (self-contained, mở trực tiếp trong browser).
+- Mỗi test fail có sẵn trace + screenshot đính kèm (cấu hình qua
+  `use: { trace: 'on-first-retry', screenshot: 'only-on-failure' }` trong `playwright.config.ts`).
+
+## Mobile — WebdriverIO Allure Report
+
+```bash
+npx wdio run wdio.conf.ts --spec ...
+npx allure generate ./allure-results --clean -o ./allure-report
+npx allure open ./allure-report
+```
+
+- Cần reporter `@wdio/allure-reporter` khai trong `wdio.conf.ts` (`reporters: ['allure']`).
+- Screenshot/video on-fail đính kèm tự động vào report qua `afterTest` hook (xem
+  `qa-script-runner/mobile/run.md`).
+
+## Nguyên tắc chung (cả hai platform)
+- Evidence trung thực: report phản ánh đúng lần chạy gần nhất, không chỉnh sửa số liệu.
+- FAIL giữ nguyên trạng thái thật cho tới khi fix + chạy lại — **không fake-pass**.
+- `playwright-report/`, `test-results/`, `allure-results/`, `allure-report/` đã gitignore
+  (artifact nặng) — không commit vào repo.
+- Tóm tắt bắt buộc: **TOTAL / PASS / FAIL / SKIP / FLAKY** + duration, và với mỗi FAIL: phân
+  loại đã xác nhận (script-bug/product-gap/flaky) từ `/qc-run-script`, kèm `BUG-{id}` nếu đã file.

package/core/skills/qc/qa-script-runner/web/run.md

@@ -0,0 +1,48 @@
+---
+version: 1.0
+updated: 2026-09-09
+new_in: QC-Workflow-Proposal (8-phase)
+---
+
+# Run — Web (Playwright Test)
+
+Skill **tự chứa** cho `/qc-run-script` khi `active_platform = web`.
+
+## Lệnh chạy
+
+```bash
+npx playwright test automation/tests/{TICKET-ID}/... --reporter=html,list
+```
+
+Trace tự động bật qua `playwright.config.ts` (`use: { trace: 'on-first-retry' }` hoặc `'on'`
+nếu muốn trace mọi lần) → mỗi test có `test-results/<nodeid>/trace.zip` khi fail.
+
+## Đọc kết quả trước khi đề xuất phân loại Fail
+
+Với mỗi FAIL, **mở trace trước khi đoán**:
+
+```bash
+npx playwright show-trace test-results/<nodeid>/trace.zip
+```
+
+Trace viewer cho: timeline hành động, DOM snapshot tại từng bước, network request/response,
+console log. Dấu hiệu phân biệt:
+
+| Dấu hiệu trong trace | Khả năng cao là |
+|---|---|
+| Locator "not found" nhưng DOM snapshot cho thấy element **có tồn tại** với selector khác | **script-bug** — selector sai/lỗi thời do UI đổi cấu trúc, không phải bug sản phẩm |
+| Element thực sự **không xuất hiện** sau hành động đúng spec (nút bấm không có phản hồi, API trả lỗi mà spec nói phải thành công) | **product-gap** — hành vi thực tế ≠ spec |
+| Timeout chờ network response, response **không bao giờ tới** | **product-gap** nếu spec yêu cầu response — hoặc **script-bug** nếu URL/endpoint chờ sai |
+| Assertion so giá trị: actual đúng theo spec nhưng expected trong test viết sai | **script-bug** |
+| Flaky ngẫu nhiên (pass khi chạy lẻ, fail khi chạy song song) | **script-bug** — thiếu cách ly data/test independence, xem `_shared/web-conventions.md` §Common Pitfalls #5-6 |
+
+Không kết luận nếu bằng chứng không đủ rõ — báo "không chắc, cần điều tra thêm" thay vì đoán.
+
+## Retry trước khi kết luận (bắt buộc — bước 0 của gate phân loại Fail)
+Trước khi đề xuất phân loại bất kỳ Fail nào, chạy lại riêng test đó tối đa 2 lần:
+```bash
+npx playwright test <file> -g "<title>" --repeat-each=1
+```
+Kết quả không nhất quán (fail→pass hoặc ngược lại) → đề xuất `flaky`, không phải
+script-bug/product-gap (xem `/qc-run-script` §Phân loại mỗi Fail). Chỉ khi fail **nhất quán**
+qua các lần retry mới tiếp tục điều tra để phân biệt script-bug/product-gap.

package/core/steps/qc-scope.md

@@ -58,6 +58,49 @@ Theo thứ tự, dừng ở cái đầu tiên khớp:
 Lưu `active_platform`. Từ đây, **mọi** phép đọc `.feature` chỉ đọc thư mục
 `bdd/{active_platform}/` — không trộn SC chéo nền.
 
+> **Nền `system` còn MỘT câu hỏi nữa, và nó ở trạm 3.** `system` không đồng nghĩa với API — nó
+> còn chứa **job tự chạy** và **consumer hàng đợi**, hai thứ không có endpoint nào. Khi không suy
+> được, `/qc-design-test` hỏi QC rồi ghi câu trả lời vào `Tags` của TC. Xem
+> `/qc-design-test` §Nền `system`. Ghi ở đây để người đọc luật nền biết **còn một câu chưa xong**,
+> chứ không phải phân giải xong nền là hết.
+
+### 2b — Nền → module QC → lane skill *(bảng DUY NHẤT, đừng chép lại ở lệnh)*
+
+| `active_platform` | module QC | `layout` | lane skill |
+|---|---|---|---|
+| `web` · `webview` | `qc-playwright-ts` | `layout.web` — `automation/` | `qa-script-designer/web/*` |
+| `app` · `app-ios` · `app-android` | `qc-wdio-appium` | `layout.mobile` — `mobile-automation/` | `qa-script-designer/mobile/*` |
+| `system` + lane `api` | `qc-playwright-ts` | `layout.api` — `api-automation/` | `qa-script-designer/api/*` |
+| `system` + lane `job` · `queue` | `qc-playwright-ts` | `layout.api` — `api-automation/` | ⚠️ **chưa có lane script** — xem dưới |
+
+> **Vì sao bảng này ở đây chứ không ở lệnh.** Cùng lý do mục §2 tồn tại: luật phân giải nền
+> từng được copy-paste ở 5 lệnh rồi câu chữ lệch nhau. Ba lệnh script trỏ vào đây, **không
+> chép lại**.
+>
+> **Vì sao KHÔNG có key cấu hình riêng.** Từng có một lời hứa `tech_stack.qc_module` trong
+> comment của module cũ, nhưng nó **chưa bao giờ được cài** — và không nên cài: `active_platform`
+> đã trả lời xong câu này ở §2 và đã **khoá cho cả pass QC**. Một field thứ hai là hai đáp án
+> cho một câu hỏi, và khi chúng lệch nhau thì artifact ghi vào thư mục của nền này trong khi
+> script sinh theo layout của nền kia — hỏng **im lặng**.
+>
+> 🔴 **`system` KHÔNG đồng nghĩa với API — sửa 2026-09-17 sau ca thật LESS-22.** Quyết định
+> `S-API` ánh xạ `system → lane api` vô điều kiện, và nó **sai**: `system` còn chứa **job tự
+> chạy** *(không ai gọi)* và **consumer hàng đợi** *(nằm chờ message)*. Cả ba tài liệu chuẩn dùng
+> để chốt `S-API` đều **chỉ nói về API**, nên không ai thấy hai hình dạng kia.
+>
+> **Tầng thiết kế TC đã có đủ ba** *(trạm 3 hỏi QC rồi ghi lane — xem `/qc-design-test` §Nền
+> `system`)*: `functional/api` · `functional/job` · `integration/queue`.
+>
+> **Tầng sinh script mới có một** — `qa-script-designer/api/*`. Lane `job` và `queue` chạy tới
+> trạm 6 thì **chưa có skill**. Đây là **lỗ đã biết, ghi ra thay vì để trạm 6 lặng lẽ dùng lane
+> `api`**: gặp TC lane `job`/`queue`, trạm 6 phải **DỪNG** và nói rõ chưa hỗ trợ, không được
+> sinh API Object cho một thứ không có endpoint.
+
+> **`web` và `system` dùng chung module, khác `layout`.** Đó là chủ ý: cùng Playwright + TS
+> *(AD-API-001 — "tái dùng infrastructure với Web testing")*, nên tách làm hai module là khai
+> dãy phiên bản hai lần. Nhưng **API Object ≠ Page Object** và `api-automation/` là thư mục
+> gốc riêng, nên `layout` và lane skill phải tách.
+
 ---
 
 ## 3 — `qc_artifact_dir`

package/core/steps/report-footer.md

@@ -99,9 +99,9 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /qc-plan                | `/qc-design-test {UC-ID}`                     |
 | /qc-design-test         | `/qc-review-testcase {UC-ID}`                 |
 | /qc-automation-assess   | `/qc-design-script {TICKET-ID}` (Automatable: Y) · `/qc-run-manualtest {UC-ID}` (N) |
-| /qc-review-testcase     | `/qc-automation-assess {TICKET-ID}` nếu APPROVED; sửa TC bằng `/qc-design-test` nếu NEEDS_FIX |
+| /qc-review-testcase     | `/qc-automation-assess {TICKET-ID}` nếu `APPROVED` hoặc `APPROVED_WITH_SUGGESTIONS`; sửa TC bằng `/qc-design-test` nếu `REVISION_REQUIRED` · `REJECTED` |
 | /qc-run-script          | `/qc-run-manualtest {UC-ID}` (TC Automatable: N) rồi `/qc-report {UC-ID}` |
-| /qc-review-script       | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED; sửa script nếu NEEDS_FIX |
+| /qc-review-script       | `/qc-report {UC-ID}` rồi tạo PR nếu `APPROVED` hoặc `APPROVED_WITH_SUGGESTIONS`; sửa script nếu `REVISION_REQUIRED` · `REJECTED` |
 | /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
 | /generate-tech-docs     | `/map-testids {UC-ID}` — chốt hợp đồng test-id §4.5.6 **trước** khi review |
 | /map-testids            | `/review-tech-docs {tech-design-file}` (review CẢ hợp đồng vừa ghi) |

package/docs/02-concepts/pipeline-steps/07-dev-selftest.md

@@ -25,7 +25,7 @@ Trước khi đẩy sang QC chính thức, Dev cần một vòng **kiểm nhanh
 
 > **`dev_selftest` ≠ `qc_status`.** Hai trục **độc lập**: dev smoke (nhanh, tự kiểm) vs QC chính thức (Playwright, evidence). Không lấn quyền nhau.
 >
-> ⚠️ **Nhưng "độc lập" chỉ đúng với `status` về KẾT QUẢ CHẠY, không đúng về QUYỀN KHẲNG ĐỊNH** *(GAPS-v4 G55)*. `pass` mang nghĩa *"scenario này đã được nghiệm thu theo spec **hiện tại**"* — nên trên row `DRIFT`/`ORPHANED`, `/dev-run-test` và `/qc-design-script` → `/qc-run-script` **không được** ghi `pass`; chúng hạ về `not_run`. `fail`/`skip` thì ghi bình thường. `lint-trace` **T12** bắt trạng thái `DRIFT + pass` ở sổ thật, bất kể ai ghi ra.
+> ⚠️ **Nhưng "độc lập" chỉ đúng với `status` về KẾT QUẢ CHẠY, không đúng về QUYỀN KHẲNG ĐỊNH** *(GAPS-v4 G55)*. `pass` mang nghĩa *"scenario này đã được nghiệm thu theo spec **hiện tại**"* — nên trên row `DRIFT`/`ORPHANED`, `/dev-run-test` và `/qc-run-script` và `/qc-run-manualtest` **không được** ghi `pass`; chúng hạ về `not_run`. `fail`/`skip` thì ghi bình thường. `lint-trace` **T12** bắt trạng thái `DRIFT + pass` ở sổ thật, bất kể ai ghi ra.
 
 ---