@educa-corp/sdd-framework 0.9.6 → 0.9.8

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

@@ -0,0 +1,257 @@
+---
+version: 1.0
+updated: 2026-09-09
+source: upstream/qc-base-new/Automation-Standards.md §4 §6 §7 §8 §9 §10 §11 (Approved)
+---
+
+# Web Automation Conventions — TypeScript + Playwright Test
+
+Skill **tự chứa**: quy ước bắt buộc khi sinh automation script web bằng `@playwright/test` +
+TypeScript. Mọi file layer trong `qa-script-designer/web/*` đọc file này trước — không lặp
+lại các quy tắc ở đây, chỉ có phần logic sinh-script riêng của layer.
+
+## 1. Locator Strategy — thứ tự ưu tiên (bắt buộc)
+
+Đây là nguồn lỗi automation phổ biến nhất: locator giòn (fragile) làm script fail không phải
+vì bug sản phẩm mà vì UI đổi CSS/text/thứ tự DOM. Luôn theo đúng thứ tự ưu tiên sau, **dừng ở
+mức đầu tiên khả dụng** — không nhảy xuống mức thấp hơn "cho nhanh":
+
+| # | Locator | Khi dùng | Ví dụ |
+|---|---|---|---|
+| 1 | **Test-ID contract** | Luôn ưu tiên nếu tech-doc có `@trace.testid_attr` + bảng §4.5.6 | `page.getByTestId('login-submit-btn')` |
+| 2 | **Role + Accessible Name** | Không có test-id nhưng element có role/aria chuẩn (button/link/textbox/checkbox…) | `page.getByRole('button', { name: 'Đăng nhập' })` |
+| 3 | **Label** (cho form field) | Input có `<label for>` hoặc `aria-label` | `page.getByLabel('Email')` |
+| 4 | **Text** (chỉ cho element tĩnh, không lặp lại nhiều lần trên trang) | Heading, thông báo, tiêu đề duy nhất | `page.getByText('Đăng nhập thành công')` |
+| 5 | **CSS/XPath theo cấu trúc ổn định** (BEM class, không phải class utility sinh tự động) | Bất khả kháng — không có gì ở trên | `page.locator('.login-form__submit')` |
+
+**Không bao giờ dùng làm mức đầu tiên** (chỉ là fallback bất đắc dĩ, luôn kèm ghi chú
+`// FIXME: cần test-id, xem IMPROVE-xxx`):
+- Class do bundler/CSS-in-JS sinh tự động (`css-1a2b3c`, `sc-hGRVom`, các hash động) — đổi mỗi
+  lần build, **không ổn định giữa các lần deploy**.
+- XPath tuyệt đối/theo vị trí (`/html/body/div[3]/div[2]/button`) — vỡ ngay khi DOM chèn thêm 1
+  node.
+- Index không có điều kiện đi kèm (`.first()`, `nth(2)`) khi danh sách có thể thay đổi thứ tự.
+- Text tiếng Việt cho element có thể đổi copy/đa ngôn ngữ.
+
+**Locator cho danh sách/bảng động:** dùng `locator().filter({ hasText })` hoặc lọc theo
+test-id của row thay vì đếm index cố định; nếu cần verify thứ tự thật (sort/paging), so sánh
+mảng giá trị thay vì giả định vị trí.
+
+### 1.1 Cấu hình test-id attribute (bắt buộc trước khi dùng `getByTestId`)
+
+Đọc `@trace.testid_attr` từ header tech-doc gộp:
+
+| Đọc được | Làm gì |
+|---|---|
+| `data-testid` (mặc định Playwright) | Dùng thẳng `getByTestId()`. |
+| Khác `data-testid` (vd `data-test`, `data-qa`) | **Bắt buộc** cấu hình trước: `playwright.config.ts` → `use: { testIdAttribute: 'data-test' }`. Bỏ bước này → `getByTestId()` luôn tìm `data-testid` mặc định → **locator trượt 100%**, trông giống bug sản phẩm nhưng thực ra là script-bug. |
+| Không có field | Cảnh báo mềm, fallback Role/Text, và ghi `IMPROVE-xxx` đề nghị dev bổ sung field. |
+
+## 2. Page Object Model — 3 lớp (bắt buộc)
+
+```typescript
+// pages/login.page.ts
+import { type Page, type Locator, expect } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class LoginPage extends BasePage {
+  // ── Lớp 1: Locators — chỉ khai báo, KHÔNG hành động ──
+  private readonly emailInput: Locator;
+  private readonly passwordInput: Locator;
+  private readonly submitBtn: Locator;
+
+  constructor(page: Page) {
+    super(page);
+    this.emailInput = page.getByTestId('login-email-input');
+    this.passwordInput = page.getByTestId('login-password-input');
+    this.submitBtn = page.getByTestId('login-submit-btn');
+  }
+
+  // ── Lớp 2: Actions — verb_noun(), trả về Page kế tiếp nếu điều hướng ──
+  async login(email: string, password: string): Promise<DashboardPage> {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    await this.submitBtn.click();
+    return new DashboardPage(this.page);
+  }
+
+  // ── Lớp 3: Assertions — expect(), không bare assert ──
+  async assertValidationError(message: string): Promise<void> {
+    await expect(this.page.getByTestId('login-error')).toHaveText(message);
+  }
+}
+```
+
+- Kế thừa `BasePage` gọn (chứa `page`, helper chung như `screenshot()`), **không** framework
+  report riêng (Allure…) — reporter là của Playwright Test.
+- Điều hướng giữa màn: action trả về Page Object màn kế tiếp (`return new NextPage(this.page)`)
+  — test chuỗi được `const dashboard = await loginPage.login(...)`.
+- Selector khai báo tập trung ở constructor/đầu class — không rải trong action method.
+- Test **không bao giờ** gọi `page.click()`/`page.fill()` trực tiếp — luôn qua method của PO.
+
+## 3. Report Readability — `test.step()` (bắt buộc)
+
+Playwright Test có `test.step()` built-in — report/trace viewer hiển thị từng step rõ ràng,
+thu gọn được, giúp đọc lại 1 test dài dễ hơn nhiều so với đọc thẳng code:
+
+```typescript
+test('TC_LOGIN_001 — đăng nhập thành công', async ({ page }) => {
+  const loginPage = new LoginPage(page);
+
+  await test.step('Nhập thông tin đăng nhập hợp lệ', async () => {
+    await loginPage.login('user@test.com', 'Password123');
+  });
+
+  await test.step('Xác nhận vào được Dashboard', async () => {
+    await expect(page).toHaveURL(/\/dashboard/);
+  });
+});
+```
+
+Bọc **mỗi chặng có ý nghĩa nghiệp vụ** (không phải mỗi dòng code) bằng `test.step()` — đặc
+biệt quan trọng cho test đa bước (feature đa-màn, E2E journey) nơi report cần chỉ đúng bước
+nào fail thay vì chỉ báo cả `test()` fail chung chung.
+
+## 4. Wait & Timing (bắt buộc)
+
+- **Không bao giờ** `page.waitForTimeout(N)` cố định để "chờ cho chắc" — dùng auto-wait của
+  `expect()`/action locator (Playwright tự retry tới khi actionable hoặc timeout).
+- Sau navigation/submit cần chờ mạng ổn định: `page.waitForLoadState('networkidle')` — nhưng
+  **không** gọi `waitForTimeout` ngay sau đó (thừa, che giấu race condition thật).
+  networkidle không tương thích tốt hoặc app poll liên tục.
+- Verify network call thật: `page.waitForResponse(url => ...)` — không mock trong integration
+  test (mock = unit test, không phải test tích hợp).
+
+## 5. Assertion (bắt buộc)
+
+- Dùng `expect(locator).toHaveText/toBeVisible/toHaveValue(...)` — auto-retry, thông báo lỗi rõ.
+- **Không** `assert someCondition` trần trụi không thông điệp; **không** `assert response` mơ hồ.
+- Mỗi test **assert nội dung thật**, không chỉ assert URL sau điều hướng.
+- Negative case: assert đúng thông báo lỗi cụ thể, không chỉ "có lỗi xuất hiện".
+- **`expect.soft()`** khi cần assert nhiều điều độc lập trong 1 test mà không muốn dừng ngay ở
+  assert đầu tiên fail (vd: kiểm tra đồng thời 5 field hiển thị đúng trên 1 form) — Playwright
+  gom hết soft-assertion fail rồi báo 1 lần cuối test, đọc report đỡ mất công chạy lại từng cái
+  một. **Không lạm dụng**: assertion mang tính điều kiện tiên quyết cho bước sau (vd "đã login
+  chưa") vẫn phải dùng `expect()` thường để dừng ngay, tránh test tiếp tục chạy trên state sai.
+
+## 6. Test Independence & Data
+
+- Không hard-code URL/credential/timeout → `process.env.*` hoặc file `config/env.ts`.
+- Mỗi test độc lập: dữ liệu từ `TEST_DATA_PLAN.md` (factory/fixture), cleanup sau khi tạo.
+- Không global state chia sẻ giữa test; gom test theo (role, account) nếu auth tốn chi phí,
+  qua Playwright `test.describe.serial` có chủ đích — không phải mặc định.
+
+### 6.1 Auth reuse — `storageState` (bắt buộc khi feature cần login)
+
+Login qua UI ở **mỗi** test (điền form, submit, chờ redirect) là nguồn chậm + flaky lớn nhất
+của một suite Playwright — mỗi lần login là một chuỗi network call thật. Best practice chuẩn
+của Playwright: **login một lần trong global setup, lưu lại session, mọi test tái sử dụng**:
+
+```typescript
+// auth.setup.ts — chạy 1 lần trước cả suite (khai trong playwright.config.ts: projects: [{ name: 'setup', testMatch: /auth\.setup\.ts/ }])
+import { test as setup } from '@playwright/test';
+
+setup('authenticate as teacher', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByTestId('login-email-input').fill(process.env.TEACHER_EMAIL!);
+  await page.getByTestId('login-password-input').fill(process.env.TEACHER_PASSWORD!);
+  await page.getByTestId('login-submit-btn').click();
+  await page.waitForURL(/\/dashboard/);
+  await page.context().storageState({ path: 'playwright/.auth/teacher.json' });
+});
+```
+
+```typescript
+// playwright.config.ts (trích) — project phụ thuộc setup, dùng lại storageState
+projects: [
+  { name: 'setup', testMatch: /auth\.setup\.ts/ },
+  { name: 'teacher-tests', use: { storageState: 'playwright/.auth/teacher.json' }, dependencies: ['setup'] },
+],
+```
+
+- Mỗi role cần 1 file storageState riêng (`teacher.json`, `admin.json`…) — khớp `Account` trong
+  `TEST_DATA_PLAN.md`.
+- TC **về chính hành vi login** (validate lỗi sai mật khẩu, khoá tài khoản…) **không** dùng
+  storageState — đó là TC test luôn chính flow login qua UI, không phải TC cần login xong mới
+  test cái khác.
+- File storageState chứa session thật → thêm vào `.gitignore`, không commit.
+
+## 7. Retry & Flaky Quarantine (bắt buộc cấu hình)
+
+Test automation **luôn** có một tỷ lệ flaky nền do timing/network/môi trường CI — coi đó là
+bình thường và có quy trình xử lý có hệ thống, thay vì coi mọi lần fail là product-gap hoặc
+mọi lần pass-sau-retry là "không sao":
+
+```typescript
+// playwright.config.ts (trích)
+export default defineConfig({
+  retries: process.env.CI ? 2 : 0,   // CI retry tối đa 2 lần; local KHÔNG retry (fail phải hiện ngay để debug)
+  reporter: [['html'], ['list']],
+});
+```
+
+- **Retry chỉ để hấp thụ nhiễu môi trường CI, không phải để che giấu bug.** Test pass sau
+  retry vẫn hiện trong report là "flaky" (Playwright HTML Report tự đánh dấu `flaky` khác với
+  `passed`) — **không coi là pass sạch**. Đây là tín hiệu `qc-run-script` phải đọc để đưa vào
+  nhóm cần điều tra riêng (xem gate phân loại Fail của `/qc-run-script`), không tự động lờ đi.
+- **Quarantine**: một test flaky lặp lại ≥3 lần chạy gần nhất → tách khỏi suite chính
+  (`test.skip` tạm + tag `@flaky`, hoặc project riêng `flaky-tests` không chặn CI), mở
+  `IMPROVE-xxx`/ghi chú kỹ thuật để điều tra root cause (thường là thiếu `storageState`, thiếu
+  cách ly data, hoặc race condition thật trong sản phẩm) — không để một test flaky nằm mãi
+  trong suite chính làm nhiễu tín hiệu của tất cả lần chạy sau.
+
+## 8. Naming & Structure
+
+Vị trí file + quy tắc slug (`<feature>` từ `TC_<FEATURE>.md`, kiểm tra tồn tại trước khi tạo
+mới khi nhiều UC cùng chạm 1 màn) — xem **`_shared/file-naming-and-folders.md`** (nguồn chuẩn
+duy nhất, không lặp lại bảng path ở đây nữa). Quy ước còn lại riêng cho code:
+
+| Gì | Convention |
+|---|---|
+| Test title | `test('TC_xxx — <mô tả ngắn>', async ({ page }) => {...})` — TC_ID **trong title**, không chỉ comment |
+| Tag | Suy **tự động** từ `Priority` của TC gốc — xem §8.1, không tự chọn tuỳ ý |
+| Comment trace | `// @trace.verifies={UC-ID}-SC{N}` ngay trên mỗi `test(...)` |
+
+### 8.1 Mapping `Priority` (TC) → tag (script) — bắt buộc, suy tự động
+
+`qc-design-script` đọc field `Priority` (`P0`/`P1`/`P2`) đã có sẵn trong `TC_<FEATURE>.md` —
+**không tự đặt tag theo cảm tính**:
+
+| Priority (TC) | Tag gắn vào `test()` | Lý do |
+|:---:|---|---|
+| `P0` | `{ tag: ['@smoke', '@regression'] }` | P0 = tính năng lõi/luồng chính — vừa chạy trong smoke suite (nhanh, mỗi build) vừa nằm trong regression đầy đủ |
+| `P1` | `{ tag: ['@regression'] }` | Quan trọng nhưng không phải lõi — không cần chặn mỗi build, chạy ở regression đầy đủ |
+| `P2` | `{ tag: ['@regression'] }` | Biên/phụ — cùng regression, không vào smoke |
+
+```typescript
+test('TC_LOGIN_001 — đăng nhập thành công', { tag: ['@smoke', '@regression'] }, async ({ page }) => {
+  // ...
+});
+```
+
+**Chạy riêng smoke suite** (xem `/qc-smoke-test`): `npx playwright test --grep @smoke`.
+Review script (`/qc-review`, `qa-reviewer/script/web/*`) đối chiếu đúng mapping này — tag lệch
+Priority (vd P0 nhưng thiếu `@smoke`) là lỗi 🟠 cần sửa, vì nó khiến smoke suite bỏ sót tính
+năng lõi.
+
+## 9. Common Pitfalls — lỗi thường gặp cần tránh (checklist self-review)
+
+| # | Lỗi | Tại sao sai | Sửa |
+|---|---|---|---|
+| 1 | `await page.waitForTimeout(3000)` để "chờ load" | Chậm, flaky (mạng chậm hơn 3s vẫn fail; nhanh hơn thì lãng phí) | `expect(locator).toBeVisible()` / `waitForLoadState` |
+| 2 | Locator theo class hash (`'.css-1x2y3z'`) | Vỡ mỗi lần build lại CSS-in-JS | Test-id contract, hoặc Role/Label |
+| 3 | `test.skip()` không lý do | Không biết TC bị bỏ vì gì, dễ quên xử lý | `test.skip(true, 'GAP-03 — chưa có API reset state')` |
+| 4 | Assertion chỉ ở bước cuối cùng của journey dài | Bug ở giữa flow bị che bởi state cuối đúng "tình cờ" | Assert sau mỗi bước có side-effect quan trọng |
+| 5 | Test phụ thuộc thứ tự chạy (`test B` cần `test A` chạy trước) | Playwright chạy song song mặc định — sinh flaky ngẫu nhiên | Fixture độc lập cho mỗi test, không biến global |
+| 6 | Hard-code data đã tồn tại sẵn trên môi trường (`userId: 42`) | Vỡ khi seed data đổi, không chạy song song được | Tạo qua API/fixture trong `beforeEach`, cleanup `afterEach` |
+| 7 | Bắt exception rồi bỏ qua (`try { ... } catch {}`) để test "luôn xanh" | Che giấu lỗi thật, fake-pass | Không catch; để test fail đúng bản chất |
+| 8 | Dùng `.first()`/`.nth(N)` không kèm filter | Thứ tự phần tử có thể đổi (server-side sort, feature flag) | `.filter({ hasText })`, hoặc locator theo test-id của item |
+| 9 | Test gọi trực tiếp `page.locator(...)` thay vì qua Page Object | Trùng lặp selector nhiều nơi, khó bảo trì khi UI đổi | Mọi interaction qua method PO |
+| 10 | So sánh screenshot toàn trang cho mọi test (visual regression tràn lan) | Flaky theo font/OS/timing render, chi phí review cao | Chỉ dùng visual assertion cho component cụ thể cần, có mask vùng động |
+
+## 10. Compile & Lint (bắt buộc trước khi báo Human approve)
+
+```bash
+npx tsc --noEmit                              # type-check toàn bộ, không build ra file
+npx playwright test --list                    # liệt kê test sẽ chạy — đếm phải khớp số TC Automatable=Y
+```

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

@@ -0,0 +1,43 @@
+---
+version: 1.0
+updated: 2026-09-17
+source: upstream/qc-base-new/API-Testing-Standards.md §5.5 §9.1 · AGT-010 (Approved)
+---
+
+# Sinh script — API xác thực & phân quyền
+
+**Đọc `_shared/api-conventions.md` rồi `endpoint.md` trước.** Đây là phần thêm.
+
+## Khi nào trigger
+- TC kiểm đăng nhập, vòng đời token, hoặc **quyền truy cập theo vai** lên endpoint.
+
+## Phase 1 — Clarify
+Liệt kê **mọi endpoint được bảo vệ** trong phạm vi, và **mọi vai** có trong hợp đồng. Bảng
+vai × endpoint là đầu vào của Phase 2.
+
+## Phase 2 — Generate
+
+**Fixture token theo vai** *(§5.5)* — `fixtures/api.fixture.ts` cấp một context cho mỗi vai.
+Không đăng nhập lại trong từng test: chậm, và dễ chạm rate-limit.
+
+**Mỗi endpoint được bảo vệ sinh đủ 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` |
+
+Không gộp `401` với `403` — 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*. Gộp là mất khả năng phân biệt lỗi cấu hình xác thực với lỗi phân quyền.
+
+**Assert phải là "bị chặn", không phải "không lỗi":** assert đúng mã, **và** assert body không
+rò dữ liệu của tài nguyên bị cấm.
+
+## Phase 3 — Trace tag + cột `Script file`
+Như `endpoint.md` Phase 3 và Phase 4, `@trace.test_type=functional`.
+
+## Self-review
+- Mỗi endpoint được bảo vệ có đủ 3 ca?
+- Fixture phân biệt **theo vai**, không dùng một token cho mọi test?
+- Không token thật nào nằm trong code?

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

@@ -0,0 +1,61 @@
+---
+version: 1.0
+updated: 2026-09-17
+source: upstream/qc-base-new/API-Testing-Standards.md §4 §5 §6 §8 · AGT-010 (Approved)
+---
+
+# Sinh script — API endpoint *(CRUD, mã trạng thái, cấu trúc response)*
+
+**Đọc `_shared/api-conventions.md` trước.** File này chỉ có phần sinh-script riêng của tầng
+endpoint. Lane này dùng khi `active_platform = system`.
+
+## Khi nào trigger
+- Chuyển TC `Automatable: Y` của một endpoint *(từ `AUTOMATION_ASSESSMENT.md`)* thành spec,
+  sau khi `TC_<FEATURE>.Test.md` đã qua `/qc-review-testcase`.
+
+## Khi KHÔNG trigger
+- Xác thực / phân quyền → `auth.md` · biên đầu vào & injection → `security.md`
+- API gọi phụ trợ **bên trong** dự án web *(setup/teardown)* → `web/functional/api.md`
+
+## Phase 1 — Clarify
+
+Đọc `TC_<FEATURE>.Test.md` **chỉ các TC `Automatable: Y`** + `TEST_DATA_PLAN.md`. API Object cho
+resource này đã có chưa → tạo mới nếu chưa. Đọc hợp đồng endpoint từ tech-doc: path · method ·
+payload · mã trạng thái · cấu trúc response.
+
+## Phase 2 — Generate
+
+**Phủ đúng số TC `Automatable: Y`** — đếm trong `AUTOMATION_ASSESSMENT.md` = số `test(...)` phải
+sinh, **không hơn không kém**. TC `Y` mà gặp rào cản kỹ thuật lúc viết → `test.fixme('TC-API-xxx — {lý do}')`
++ ghi `IMPROVE-xxx`, **không âm thầm bỏ qua**.
+
+Gom bằng `test.describe` theo **resource → method**. Mỗi TC một `test()`, tiêu đề mang `TC-API-ID`.
+
+Sinh đủ ba lớp:
+
+| Lớp | File |
+|---|---|
+| API Object | `api-automation/api/<resource>.api.ts` — 1 method = 1 endpoint action |
+| Test data | `api-automation/data/<resource>.data.ts` |
+| Spec | `api-automation/tests/{TICKET-ID}/<feature>-<scenario>.spec.ts` |
+
+## Phase 3 — Trace tag bắt buộc
+
+```typescript
+// @trace.verifies={UC-ID}-SC{N}
+// @trace.source=specs/{domain}/{prd-slug}/bdd/system/{UC-ID}-{slug}.feature
+// @trace.test_type=functional
+```
+
+## Phase 4 — Điền cột `Script file`
+
+Sau khi sinh, **điền đường dẫn thật** vào cột `Script file` của từng TC `Y` trong
+`AUTOMATION_ASSESSMENT.md`. Đây là chỉ mục ngược duy nhất TC → file code; `/qc-run-script` đọc
+đúng cột này để biết chạy file nào.
+
+## Self-review trước khi báo xong
+
+- Số `test()` = số TC `Automatable: Y`?
+- Mọi request đi qua API Object, **không** `request.*` thô trong spec?
+- Mọi test assert **mã trạng thái** + ít nhất một assert về nội dung?
+- `npx tsc --noEmit` sạch và `--list` collect đúng số?

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

@@ -0,0 +1,41 @@
+---
+version: 1.0
+updated: 2026-09-17
+source: upstream/qc-base-new/API-Testing-Standards.md §8 §9.2 · AGT-010 (Approved)
+---
+
+# Sinh script — API biên đầu vào & injection
+
+**Đọc `_shared/api-conventions.md` rồi `endpoint.md` trước.** Đây là phần thêm.
+
+## Khi nào trigger
+- TC kiểm **biên của đầu vào** hoặc các mẫu injection lên endpoint.
+
+## Phase 1 — Clarify
+Với mỗi trường đầu vào, lấy từ hợp đồng: kiểu · bắt buộc/không · giới hạn min–max · tập giá trị
+hợp lệ. Thiếu ràng buộc trong hợp đồng → ghi `IMPROVE-xxx`, **không tự bịa ngưỡng**.
+
+## Phase 2 — Generate
+
+**Ba kỹ thuật phải thấy được trong code** *(§8)*:
+
+| Kỹ thuật | Sinh gì |
+|---|---|
+| **Phân lớp tương đương** | mỗi lớp ít nhất một ca — không chỉ ca hợp lệ |
+| **Giá trị biên** | với trường có giới hạn: `min-1` · `min` · `max` · `max+1` |
+| **Phủ HTTP method** | gọi method không hỗ trợ → mong đợi `405` |
+
+**Payload injection** *(§9.2)* — gom vào `data/<resource>.data.ts` thành **một bộ dùng lại**,
+không rải trong spec. Phủ đủ các họ: SQL · NoSQL · command · path traversal · XSS lưu trữ.
+
+**Mong đợi phải cụ thể:** `400`/`422` + thông điệp lỗi có cấu trúc, hoặc dữ liệu được làm sạch.
+**Không** assert kiểu *"không sập"* — một endpoint trả `200` kèm dữ liệu đã bị nhiễm vẫn "không sập".
+
+Thêm một assert: thông điệp lỗi **không rò** stack trace, tên bảng, hay phiên bản thư viện.
+
+## Phase 3 — Trace tag + cột `Script file`
+Như `endpoint.md`, `@trace.test_type=non-functional`.
+
+## Ranh giới
+Đây **không** phải kiểm thâm nhập. Sinh script theo TC đã duyệt; **không** tự mở rộng sang dò
+quét lỗ hổng, và **không** kết luận gì về mức an toàn của hệ thống.

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

@@ -0,0 +1,35 @@
+---
+version: 1.0
+updated: 2026-09-09
+---
+
+# Gen Script — Mobile E2E Journey (Flutter)
+
+**Đọc `_shared/mobile-conventions.md` trước.**
+
+## Khi nào trigger
+- Convert TC E2E journey (output `qa-designer/e2e/journey.md`, platform `app`), 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 V1…Vn sau mỗi chặng.
+- Journey dài trên thiết bị thật/emulator chậm hơn web đáng kể — timeout cho mỗi bước chờ nên
+  rộng hơn mặc định (cold start, animation transition Flutter).
+- Tiền điều kiện (tài khoản, data) qua fixture riêng (`beforeEach`), reset app state
+  (`driver.reset()`) trước mỗi journey — không dựa vào journey trước "dọn" giúp.
+
+## Phase 1 — Clarify
+Các màn/PO + hệ thống verify ngoài (nếu có); tài khoản/data cần dựng.
+
+## Phase 2 — Generate
+Mỗi journey → 1 test; verify đủ V1…Vn. Journey phụ thuộc gap → `it.skip('...GAP-xx')`.
+
+## Phase 3 — Self-Verify
+```bash
+npx tsc --noEmit
+```
+
+## Output
+`mobile-automation/test/specs/{TICKET-ID}/e2e/<feature>-<scenario>.spec.ts` + Page Object tái dùng.

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.