@educa-corp/sdd-framework 0.9.6 → 0.9.8

package/core/skills/qc/qa-reviewer/test-case/functional.md

@@ -12,7 +12,7 @@ Review bộ functional TC và đánh giá chất lượng.
  
 ## Khi nào trigger
 - "review TC cho [Feature]" / "check coverage"
-- Sau khi qa-designer xong, trước khi PO approve hoặc trước khi /qc-run-test
+- Sau khi qa-designer xong, trước khi PO approve hoặc trước khi /qc-design-script
  
 ## Khi KHÔNG trigger
 - Review Python script → dùng qa-reviewer
@@ -117,7 +117,7 @@ hàng của tầng mình, KHÔNG ghi đè tầng khác).
 Mỗi tiêu chí: ✅ PASS | ⚠️ WARN | ❌ FAIL + evidence cụ thể
 
 **Điểm `XX/100`** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
-**Verdict:** `điểm ≥ 80` VÀ không còn `FAIL` chặn → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+**Verdict:** suy từ **số đếm lỗi** theo `shared/review-file-template.md` §Verdict — `≥1 BLOCKER` → `REJECTED` · `≥1 MAJOR` → `REVISION_REQUIRED` · chỉ MINOR/SUGGESTION → `APPROVED_WITH_SUGGESTIONS` · sạch → `APPROVED`. Điểm `XX/100` vẫn ghi, nhưng **không quyết verdict**.
 
 Đề xuất TC cần thêm/sửa/xoá, sắp theo priority. Liệt kê TC thiếu Trace BR (⚠️) cần bổ sung.
 

package/core/skills/qc/qa-reviewer/test-case/integration.md

@@ -12,7 +12,7 @@ Review bộ TC tích hợp (GUI↔Backend, API, DB) và đánh giá chất lư
 
 ## Khi nào trigger
 - "review TC integration cho [Feature]" / "check TC tích hợp"
-- Sau khi qa-designer/integration/* xong, trước khi /qc-run-test
+- Sau khi qa-designer/integration/* xong, trước khi /qc-design-script
 
 ## Khi KHÔNG trigger
 - Review TC functional 1 màn/endpoint → `test-case/functional`
@@ -113,7 +113,7 @@ hàng của tầng mình, KHÔNG ghi đè tầng khác).
 Mỗi tiêu chí: ✅ PASS | ⚠️ WARN | ❌ FAIL + evidence cụ thể (TC ID / điểm tích hợp)
 
 **Điểm `XX/100`** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
-**Verdict:** `điểm ≥ 80` VÀ không còn `FAIL` chặn → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+**Verdict:** suy từ **số đếm lỗi** theo `shared/review-file-template.md` §Verdict — `≥1 BLOCKER` → `REJECTED` · `≥1 MAJOR` → `REVISION_REQUIRED` · chỉ MINOR/SUGGESTION → `APPROVED_WITH_SUGGESTIONS` · sạch → `APPROVED`. Điểm `XX/100` vẫn ghi, nhưng **không quyết verdict**.
 
 Điểm tích hợp thiếu TC; TC Expected mờ nhạt; TC DB thiếu cleanup.
 Điền thêm bảng **Coverage handshake (Integration)** ở cuối file review.

package/core/skills/qc/qa-reviewer/test-case/non-functional.md

@@ -12,7 +12,7 @@ Review bộ TC phi chức năng (performance, security, accessibility, compatibi
 
 ## Khi nào trigger
 - "review TC non-functional cho [Feature]" / "check TC hiệu năng/bảo mật/accessibility"
-- Sau khi qa-designer/non-functional xong, trước khi /qc-run-test
+- Sau khi qa-designer/non-functional xong, trước khi /qc-design-script
 
 ## Khi KHÔNG trigger
 - Review TC chức năng → `test-case/functional`
@@ -124,7 +124,7 @@ hàng của tầng mình, KHÔNG ghi đè tầng khác).
 Mỗi tiêu chí: ✅ PASS | ⚠️ WARN | ❌ FAIL + evidence cụ thể (TC ID)
 
 **Điểm `XX/100`** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
-**Verdict:** `điểm ≥ 80` VÀ không còn `FAIL` chặn → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+**Verdict:** suy từ **số đếm lỗi** theo `shared/review-file-template.md` §Verdict — `≥1 BLOCKER` → `REJECTED` · `≥1 MAJOR` → `REVISION_REQUIRED` · chỉ MINOR/SUGGESTION → `APPROVED_WITH_SUGGESTIONS` · sạch → `APPROVED`. Điểm `XX/100` vẫn ghi, nhưng **không quyết verdict**.
 
 Danh sách TC Expected mờ nhạt (thiếu ngưỡng); loại non-functional thiếu coverage.
 Ghi rõ TC nào cần môi trường đặc biệt. Điền thêm bảng **Chi tiết NFR** ở cuối file review.

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

@@ -0,0 +1,94 @@
+---
+version: 1.0
+updated: 2026-09-17
+source: upstream/qc-base-new/API-Testing-Standards.md §4 §5 §6 §10 §11 · AGT-010 §2 §3 (Approved)
+---
+
+# Quy ước viết script API — TypeScript + Playwright (API mode)
+
+**Nạp file này trước mọi file lane `api/`.** Nó là bản song song của `web-conventions.md` cho
+nền `system`; hai file **không** kế thừa nhau vì đối tượng khác hẳn.
+
+> ⚠️ **API Object ≠ Page Object.** Không màn hình, không locator, không chờ. Mang thói quen web
+> sang đây là viết ra thứ chạy được nhưng sai kiến trúc — và `/qc-review-script` lane `api` sẽ
+> chặn nó bằng `R01`.
+
+## 1 · API Object *(§4 · AGT-010 §2.2 · R01)*
+
+```typescript
+// api/booking.api.ts
+export class BookingAPI extends BaseAPI {
+  async create(payload: BookingPayload): Promise<APIResponse> {
+    return this.ctx.post('/bookings', { data: payload });
+  }
+}
+```
+
+| Luật | Vi phạm là |
+|---|---|
+| **Mọi HTTP request đi qua API Object** — không `request.post()` thô trong spec | `BLOCKER` |
+| `extends BaseAPI`; class `<Resource>API`; file `<resource>.api.ts` | `MINOR` |
+| **1 method = 1 endpoint action** | `MAJOR` |
+| Trả `Promise<APIResponse>` — **không parse response bên trong** | `MAJOR` |
+| **Không `expect()` trong API Object** — assertion thuộc spec | `MAJOR` |
+| Mỗi resource một API Object, không "God API Object" | `MAJOR` |
+
+**Vì sao cấm `expect()` bên trong:** API Object là *nơi biết gọi đâu*, spec là *nơi biết thế nào
+là đúng*. Trộn hai vai thì một thay đổi hợp đồng phải sửa ở hai chỗ, và cái sót lại nói dối.
+
+## 2 · Cấu trúc spec — AAA *(§5)*
+
+```typescript
+test('TC-API-001 — tạo booking hợp lệ trả 201', async ({ bookingAPI }) => {
+  const payload = validBooking;                    // Arrange
+  const res = await bookingAPI.create(payload);    // Act
+  expect(res.status()).toBe(201);                  // Assert
+  expect(await res.json()).toMatchObject({ id: expect.any(String) });
+});
+```
+
+- Header block mang **TC-ID** + `@trace.verifies` — thiếu là `BLOCKER` *(`R07`)*
+- Ba khối tách rõ; trộn assert vào giữa chuỗi gọi ⇒ `MINOR`
+- Data-driven bằng `for...of` / `test.each`, không chép test năm lần ⇒ `MINOR`
+
+## 3 · Assertion *(§6)*
+
+| Bắt buộc | Mức nếu thiếu |
+|---|---|
+| Assert **mã trạng thái** | `BLOCKER` |
+| Assert **cấu trúc + giá trị** của body, không chỉ status | `MAJOR` |
+| Kiểm schema cho response có cấu trúc *(`helpers/schema.helper.ts`)* | `MINOR` |
+| Assert header khi hợp đồng nêu | `MINOR` |
+
+`expect(res.ok()).toBeTruthy()` làm assertion **duy nhất** ⇒ `MAJOR` — nó đúng cho mọi 2xx/3xx,
+nên nó không phân biệt được thành công với chuyển hướng.
+
+## 4 · Async *(AGT-010 R02)*
+
+- **`waitForTimeout` tuyệt đối không dùng** ⇒ `BLOCKER`. API đồng bộ về bản chất: `await` thẳng.
+- Thiếu `await` trước lời gọi ⇒ `BLOCKER` — test kết thúc trước khi có response và **xanh giả**.
+
+## 5 · Dữ liệu *(AGT-010 R03)*
+
+- Credential · payload · giá trị mong đợi để ở `data/<resource>.data.ts` ⇒ hard-code là `MAJOR`
+- Token qua `fixtures/api.fixture.ts`, phân biệt **theo vai** ⇒ một token cho mọi test là `MAJOR`
+- Bản ghi tạo ra phải xoá ở `afterEach`/`afterAll`, kể cả khi test fail ⇒ thiếu là `MAJOR`
+
+## 6 · Đặt tên và đường dẫn
+
+```
+api-automation/tests/{TICKET-ID}/<feature>-<scenario>.spec.ts
+api-automation/api/<resource>.api.ts        ← PHẲNG, dùng lại xuyên PRD
+api-automation/data/<resource>.data.ts
+api-automation/fixtures/api.fixture.ts
+api-automation/helpers/{schema,auth}.helper.ts
+```
+
+Dãy ID của lane này **độc lập** với web/mobile *(§7.3)*: `TS-API` · `SCN-API` · `TC-API` ·
+`AUT-API` · `TDS-API`.
+
+## 7 · Chất lượng *(§10 · §11)*
+
+- TypeScript strict, không `any` ⇒ `MINOR`
+- `test.only` sót lại ⇒ `BLOCKER` *(CI chạy một test rồi báo xanh)*
+- Test flaky phải mang tag `@flaky` và bị tách khỏi suite chính ⇒ không tag là `MAJOR`

package/core/skills/qc/qa-script-designer/_shared/file-naming-and-folders.md

@@ -0,0 +1,109 @@
+---
+version: 1.0
+updated: 2026-09-09
+new_in: post-review fix — trước đây `<project>` là placeholder không được định nghĩa, và
+  Page Object có 2 quy ước đặt tên mâu thuẫn nhau giữa các file
+---
+
+# Quy ước đặt tên & Folder — Automation Code (nguồn chuẩn duy nhất)
+
+Mọi file khác (`_shared/web-conventions.md`, `_shared/mobile-conventions.md`, `qc-design-script.md`,
+`qc-run-script.md`, mọi layer file trong `qa-script-designer/`, `qa-script-runner/`,
+`qa-reviewer/script/`) **tham chiếu file này** thay vì tự lặp lại quy ước path — sửa path chỉ
+sửa ở một chỗ.
+
+## 0. Vị trí repo (đã chốt)
+
+Automation code nằm trong **repo/module riêng** cho QC — tách biệt spec repo (`spec_source`)
+và repo product code. Root **KHÔNG khai bằng key cấu hình riêng** — nó lấy từ `§layout` của module
+đã phân giải ở `steps/qc-scope.md` §2b: `web`·`webview` → `automation/` · `system` → `api-automation/`
+· `app`·`app-ios`·`app-android` → `mobile-automation/`.
+
+> **Vì sao không có key riêng** *(quyết định `S-PATH`, 2026-09-17)*: `§layout` của module đã nói
+> gốc ở đâu. Thêm một key nữa là **hai nguồn cho một sự thật**; khi chúng lệch, artifact ghi vào
+> thư mục nền này còn script sinh theo layout nền kia — hỏng **im lặng**. Cùng lập luận đã dùng
+> khi bỏ `tech_stack.qc_module`.
+
+```
+automation/
+├── web/                          ← Playwright Test + TypeScript
+│   ├── tests/{TICKET-ID}/{feature-slug}.spec.ts
+│   ├── pages/{TICKET-ID}/{feature-slug}.page.ts
+│   ├── fixtures/                 ← client API/DB/Kafka dùng chung nhiều feature
+│   ├── playwright/.auth/{role}.json   ← storageState per-role (xem web-conventions.md §6.1)
+│   └── playwright.config.ts
+└── mobile/                       ← WebdriverIO + Appium + TypeScript
+    ├── test/specs/{TICKET-ID}/{feature-slug}.spec.ts
+    ├── pageobjects/{TICKET-ID}/{feature-slug}.page.ts
+    ├── fixtures/
+    └── wdio.conf.ts
+```
+
+`{TICKET-ID}` — **dùng lại đúng 2 giá trị đã resolve ở Gate Bước 1** khi target là
+UC-ID (cùng 2 segment đang dùng cho `{paths.specs_dir}/{TICKET-ID}/...`). Automation
+code tổ chức theo **cấu trúc sản phẩm** (domain/feature-package), không theo UC-ID — vì 1 file
+script thường phục vụ nhiều UC-ID cùng lúc (1 màn hình bị nhiều UC verify các khía cạnh khác
+nhau), nên tổ chức theo UC-ID sẽ ép phải chọn 1 UC "sở hữu" file trong khi thực tế không đúng.
+Đây là lý do automation code **KHÔNG** mirror cấu trúc `{paths.qc_dir}/{UC-ID}/...` (khác trục
+tổ chức, không phải thiếu sót).
+
+## 1. Chuyển đổi slug (bắt buộc, một chiều duy nhất)
+
+Nguồn gốc của mọi slug là `<FEATURE>` trong tên file thiết kế manual `TC_<FEATURE>.md`
+(qa-designer, UPPER_SNAKE_CASE, vd `TC_LOGIN.md`, `TC_STUDENT_ENROLLMENT.md`):
+
+| Ngữ cảnh | Transform | Ví dụ (từ `TC_LOGIN.md`) |
+|---|---|---|
+| Tên file script/spec | kebab-case, giữ nguyên | `login.spec.ts` |
+| Tên file Page Object | kebab-case + suffix `.page.ts` | `login.page.ts` |
+| Tên class Page Object | PascalCase + suffix `Page` | `LoginPage` |
+| Tag/tiêu đề test | giữ nguyên `TC_LOGIN_001` (từ TC ID gốc trong `.md`) | `test('TC_LOGIN_001 — ...', ...)` |
+
+**Một chiều duy nhất** — không suy ngược từ code ra `<FEATURE>`, luôn suy từ `TC_<FEATURE>.md`
+đã có sang code. Nếu chưa có TC file (chưa qua phase 3) thì chưa có gì để suy — không tự đặt
+tên trước.
+
+## 2. Nhiều UC cùng chạm 1 màn hình/feature (bắt buộc kiểm tra trước khi tạo file mới)
+
+Feature/màn hình có thể được nhiều UC-ID khác nhau verify các khía cạnh khác nhau (vd UC1
+"login thành công", UC2 "login khoá tài khoản" — cùng chạm màn Login). Trước khi tạo file mới
+ở phase 6 (`qc-design-script`):
+
+1. **Tìm Page Object đã tồn tại chưa** — glob
+   `automation/pages/{TICKET-ID}/*.page.ts` (hoặc mobile tương ứng)
+   theo cùng slug màn hình. Có rồi → tái sử dụng, **không tạo file PO thứ 2** cho cùng 1 màn.
+2. **Tìm file spec đã tồn tại chưa** cùng slug — nếu UC khác đã tạo `login.spec.ts` cho cùng
+   màn hình, **thêm `test.describe()` mới vào file đó** (nhóm theo UC nguồn, vd
+   `test.describe('UC2 — Login lockout', () => {...})`), không tạo file trùng lặp
+   (`login-2.spec.ts`, `login-uc2.spec.ts`…).
+3. Nếu `<FEATURE>` slug của 2 UC khác nhau nhưng cùng route/màn hình (do qa-designer đặt tên
+   khác nhau ở 2 lần chạy) → dùng slug của file **tạo trước** (kiểm tra tồn tại theo route,
+   không chỉ theo tên) để tránh phân mảnh; ghi chú lại trong report của `qc-design-script` nếu
+   phát hiện trường hợp này.
+
+## 3. Ví dụ đầy đủ — UC1 (domain `academic`, prd-slug `student-enrollment`, screen Login)
+
+```
+automation/
+├── tests/academic/student-enrollment/login.spec.ts     # @trace.verifies=UC1-SC1, UC2-SC1...
+├── pages/academic/student-enrollment/login.page.ts      # class LoginPage
+└── playwright/.auth/teacher.json
+```
+
+## 4. Vị trí file "hồ sơ" khác (không phải code) — không đổi so với trước
+
+`AUTOMATION_ASSESSMENT.md`, `TEST_DATA_PLAN.md`, `TESTABILITY_IMPROVEMENTS.md` vẫn ở
+`{paths.qc_dir}/{UC-ID}/{active_platform}/` như các phase 4/5/6 đã định — đây là hồ sơ **theo
+UC-ID** (đúng trục của chúng: đánh giá/dữ liệu/rào cản là quyết định gắn với 1 UC cụ thể tại 1
+thời điểm), khác với code (gắn với màn hình, dùng lại xuyên UC). Hai trục tổ chức khác nhau
+cho hai loại artifact khác nhau — không phải thiếu nhất quán.
+
+> **Trạng thái tích hợp sdd-framework — ĐÃ THI HÀNH** *(Bước S · S1, 2026-09-17)*. Module của stack cũ
+> — `qc-playwright` — đã **gỡ hẳn** *(quyết định `H2`)*, thay bằng hai module:
+> `qc-playwright-ts` *(nền `web` và `system` — hai `layout`, cùng một dãy phiên bản Playwright/TS)*
+> và `qc-wdio-appium` *(nền `app`)*. Không giữ bản deprecated nào: một hồ sơ stack cũ còn
+> sống trong `core/` là một cửa để nó quay lại.
+>
+> Ghi chú gốc của bộ đề xuất từng dự kiến khai tên module qua `tech_stack.qc_module`. **Không
+> làm vậy** — key đó chưa bao giờ tồn tại trong framework, và `active_platform` đã trả lời xong
+> câu "dùng module nào" ngay ở trạm 1.

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

@@ -0,0 +1,196 @@
+---
+version: 1.0
+updated: 2026-09-09
+new_in: QC-Workflow-Proposal (8-phase) — mobile chưa từng có trong skill set cũ
+---
+
+# Mobile Automation Conventions — TypeScript + WebdriverIO + Appium
+
+Skill **tự chứa**: quy ước bắt buộc khi sinh automation script mobile bằng WebdriverIO +
+Appium + TypeScript, cho app **Flutter** (dev team đang dùng). Mọi file layer trong
+`qa-script-designer/mobile/*` đọc file này trước.
+
+## 0. Vì sao Flutter cần driver riêng (đọc trước khi viết locator)
+
+Flutter tự vẽ UI trên một canvas (Skia), **không** map trực tiếp sang native view tree như
+React Native hay app native thật. Hệ quả: Appium driver chuẩn (`UiAutomator2` Android,
+`XCUITest` iOS) chỉ "thấy" các widget mà Flutter **chủ động expose** qua `Semantics`
+(accessibility tree của OS) — nếu widget không bật `Semantics`/không có `label`, driver chuẩn
+coi như nó không tồn tại, dù mắt người thấy rõ trên màn hình.
+
+**Vì vậy dùng `automationName: 'FlutterIntegration'`** (Appium Flutter Integration Driver,
+dựa trên package `integration_test` của Flutter) — driver này đọc **thẳng Flutter widget
+tree** qua `key` (`ValueKey`), không phụ thuộc accessibility tree của OS. Ổn định hơn nhiều
+cho app Flutter, và đây là driver mặc định của mọi skill trong file này.
+
+```typescript
+// wdio.conf.ts (trích)
+export const config: WebdriverIO.Config = {
+  capabilities: [{
+    platformName: 'Android', // hoặc 'iOS'
+    'appium:automationName': 'FlutterIntegration',
+    'appium:app': process.env.APP_PATH,
+  }],
+};
+```
+
+## 1. Locator Strategy — thứ tự ưu tiên (bắt buộc)
+
+| # | Locator | Khi dùng | Ví dụ |
+|---|---|---|---|
+| 1 | **`ValueKey` contract (test-id Flutter)** | Luôn ưu tiên — tương đương `data-testid` bên web | `$('~login_submit_btn')` (FlutterIntegration map `~` → `ValueKey`) hoặc `driver.$('flutter finder', ...)` tuỳ version |
+| 2 | **Semantics label / accessibility-id** | Widget có bật `Semantics(label: ...)` nhưng chưa gán `Key` | `$('~Đăng nhập')` |
+| 3 | **Text hiển thị** (chỉ static, không lặp) | Không có key/label, element tĩnh duy nhất trên màn | `$('android=new UiSelector().text("Đăng nhập")')` |
+| 4 | **XPath theo cấu trúc widget tree** (bất đắc dĩ) | Không còn lựa chọn nào khác | Luôn kèm `// FIXME: cần ValueKey, xem IMPROVE-xxx` |
+
+**Không dùng làm mức đầu tiên:** toạ độ tuyệt đối (tap theo x/y — vỡ ngay khi đổi kích thước
+màn hình/device), index không filter trên danh sách động, text đa ngôn ngữ dễ đổi.
+
+### 1.1 Contract `ValueKey` với dev Flutter (bắt buộc xác nhận trước khi viết locator)
+
+Tương đương `@trace.testid_attr` bên web — dev phải gán `Key(ValueKey('login_submit_btn'))`
+cho mọi widget tương tác được liệt trong tech-doc §4.5.6. Đọc contract này trước khi viết
+Page Object; thiếu → cảnh báo mềm, fallback Semantics label, và ghi `IMPROVE-xxx` đề nghị dev
+bổ sung `ValueKey`.
+
+### 1.2 Probe widget tree thật trước khi viết locator (bắt buộc nếu §4.5.6 không đủ)
+
+Giống bên web phải "Probe DOM thật" khi SPA thiếu `data-testid`, bên mobile **không được đoán
+`ValueKey`/label từ mắt nhìn màn hình** — phải xác nhận bằng công cụ trước khi viết locator:
+
+- **Appium Inspector** (GUI chính thức của Appium): kết nối cùng `automationName:
+  FlutterIntegration` + capability của app đang test, tap vào widget để xem `ValueKey`/label
+  thật nó expose — không phải cấu trúc DOM/View suy đoán.
+- **Flutter DevTools** (`flutter run` + mở DevTools → Widget Inspector): xem trực tiếp widget
+  tree đang chạy, kể cả khi widget chưa gán `Key` (giúp biết chính xác cần đề nghị dev thêm
+  `Key` ở widget nào, thay vì đoán qua ảnh chụp màn hình).
+
+Không có 1 trong 2 công cụ trên khả dụng (vd môi trường không cài được) → fallback: build app
+debug, chạy tay 1 lần, dựa vào Semantics label nếu bật `flutter run --enable-software-rendering
+--dds-port` kèm accessibility bật trên OS — nhưng đây là **fallback chậm hơn**, ưu tiên 2 công
+cụ trên trước.
+
+## 2. Page Object Model — 3 lớp (bắt buộc, giống cấu trúc web)
+
+```typescript
+// pageobjects/login.page.ts
+import { BasePage } from './base.page';
+
+class LoginPage extends BasePage {
+  // ── Lớp 1: Locators ──
+  private get emailInput() { return $('~login_email_input'); }
+  private get passwordInput() { return $('~login_password_input'); }
+  private get submitBtn() { return $('~login_submit_btn'); }
+
+  // ── Lớp 2: Actions ──
+  async login(email: string, password: string) {
+    await (await this.emailInput).setValue(email);
+    await (await this.passwordInput).setValue(password);
+    await (await this.submitBtn).click();
+  }
+
+  // ── Lớp 3: Assertions ──
+  async assertValidationError(message: string) {
+    await expect($('~login_error')).toHaveText(message);
+  }
+}
+export default new LoginPage();
+```
+
+- `BasePage` gọn: chứa helper chung (chờ app foreground, chụp screenshot).
+- Điều hướng đa màn: mỗi màn 1 Page Object riêng, action trả về hoặc test tự import Page Object
+  màn kế tiếp (module singleton pattern WDIO chuẩn — khác Playwright PO là instance theo `page`).
+
+## 3. Wait & Timing (bắt buộc)
+
+- **Không** `browser.pause(N)` cố định — dùng `waitForDisplayed()`, `waitForEnabled()`,
+  `waitUntil()` của WebdriverIO (auto-retry theo điều kiện).
+- App Flutter cần thời gian dựng frame đầu — dùng `waitForDisplayed({ timeout: 10000 })` cho
+  màn hình đầu sau cold start, không phải `pause`.
+- Thao tác vuốt/scroll trên danh sách dài: dùng gesture helper WDIO (`touchAction`/
+  `$.scrollIntoView()`), không lặp `pause` giữa mỗi lần vuốt.
+
+## 4. Assertion (bắt buộc)
+
+- Dùng matcher `expect(element).toBeDisplayed()/toHaveText()/toBeEnabled()` (WDIO
+  `expect-webdriverio`) — auto-retry, thông báo lỗi rõ.
+- Không `assert` trần trụi; mỗi test assert nội dung/state thật, không chỉ "app không crash".
+
+## 5. Test Independence & Data
+
+- Không hard-code device/app path/credential → biến môi trường (`process.env.*`) hoặc
+  `wdio.conf.ts` theo profile.
+- Reset app state giữa test qua `driver.reset()` hoặc deep-link/API riêng — **không** dựa vào
+  thứ tự test để "dọn" state của nhau.
+- Native permission dialog (camera, location, notification) — xử lý qua Appium
+  `mobile: acceptAlert` / capability tự-cấp quyền khi cài, không tap toạ độ mù.
+
+### 5.1 `noReset` / `fullReset` — chọn đúng đánh đổi tốc độ vs. cách ly
+
+Capability quyết định mức "sạch" của app giữa các phiên chạy — chọn sai làm suite chậm không
+cần thiết **hoặc** flaky do rò rỉ state:
+
+| Capability | Hành vi | Khi dùng |
+|---|---|---|
+| `fullReset: true` | Gỡ cài đặt + cài lại app mỗi session | TC cần trạng thái **cài đặt lần đầu** thật (onboarding, permission dialog lần đầu) — chậm nhất, dùng tối thiểu |
+| `noReset: false` (mặc định, không set `fullReset`) | Xoá app data giữa session nhưng **không** gỡ cài đặt | Mặc định hợp lý cho phần lớn TC — cân bằng tốc độ/cách ly |
+| `noReset: true` | Giữ nguyên toàn bộ data/session giữa các lần chạy | Chỉ dùng cho test **đọc** (không side-effect) hoặc khi đã tự quản lý cleanup qua API riêng — nhanh nhất nhưng rủi ro rò rỉ state nếu dùng sai chỗ |
+
+Nguyên tắc chọn: TC có side-effect (tạo/sửa/xoá data, đổi setting) → không dùng `noReset: true`
+trừ khi có cleanup API riêng đáng tin; TC chỉ đọc/verify hiển thị → `noReset: true` để tăng tốc
+đáng kể cho suite lớn.
+
+### 5.2 Device Farm cho Compatibility testing
+
+Emulator/simulator không thay thế được test trên **thiết bị thật đa dạng OS version/hãng máy**
+— đặc biệt quan trọng cho Android (phân mảnh OS/màn hình lớn hơn iOS nhiều). Khi TC
+compatibility yêu cầu phủ nhiều device/OS thật mà không có đủ máy vật lý, dùng device farm
+(BrowserStack App Automate, Sauce Labs, hoặc Firebase Test Lab) — cấu hình `capabilities` trỏ
+tới farm qua remote WebDriver URL thay vì local Appium server, code test không đổi. Ghi rõ
+trong TC non-functional compatibility: farm nào, danh sách device/OS mục tiêu, vì đây là chi
+phí (thường tính phí theo phút chạy) cần PM/lead duyệt trước khi đưa vào CI thường xuyên.
+
+## 6. Naming & Structure
+
+Vị trí file + quy tắc slug — xem **`_shared/file-naming-and-folders.md`** (nguồn chuẩn duy
+nhất). Quy ước còn lại riêng cho code:
+
+| Gì | Convention |
+|---|---|
+| Test title | `it('TC_xxx — <mô tả ngắn>', async () => {...})` — tag Priority nhúng trong title (xem §6.1, WDIO/Mocha không có `tag` option như Playwright) |
+| Comment trace | `// @trace.verifies={UC-ID}-SC{N}` ngay trên mỗi `it(...)` |
+
+### 6.1 Mapping `Priority` (TC) → tag (script) — bắt buộc, suy tự động
+
+WebdriverIO chạy trên Mocha — không có cơ chế `tag` như Playwright Test, nên tag nhúng ngay
+trong title và lọc bằng `--mochaOpts.grep`. Đọc field `Priority` (`P0`/`P1`/`P2`) từ
+`TC_<FEATURE>.md` — **không tự đặt theo cảm tính**:
+
+| Priority (TC) | Title convention | Lý do |
+|:---:|---|---|
+| `P0` | `it('TC_xxx @smoke @regression — <mô tả>', ...)` | Tính năng lõi — vào cả smoke lẫn regression |
+| `P1`/`P2` | `it('TC_xxx @regression — <mô tả>', ...)` | Chỉ vào regression đầy đủ |
+
+**Chạy riêng smoke suite** (xem `/qc-smoke-test`):
+`npx wdio run wdio.conf.ts --mochaOpts.grep "@smoke"`.
+Review script đối chiếu đúng mapping này — P0 thiếu `@smoke` trong title là lỗi 🟠.
+
+## 7. Common Pitfalls — lỗi thường gặp cần tránh (checklist self-review)
+
+| # | Lỗi | Tại sao sai | Sửa |
+|---|---|---|---|
+| 1 | `browser.pause(5000)` sau mọi action | Chậm, flaky theo tốc độ máy/device thật vs emulator | `waitForDisplayed()`/`waitUntil()` |
+| 2 | Locator theo toạ độ (`tap({x: 100, y: 200})`) | Vỡ ngay khi đổi kích thước màn hình/device khác | `ValueKey`/Semantics label |
+| 3 | Dùng driver `UiAutomator2`/`XCUITest` thuần cho app Flutter không bật Semantics | Driver "mù" phần lớn UI, locator not-found sai lệch thành "bug sản phẩm" | `automationName: FlutterIntegration` + `ValueKey` |
+| 4 | Không reset app state giữa test | Test sau phụ thuộc state test trước — flaky khi chạy lẻ | `driver.reset()` hoặc API/deep-link reset riêng |
+| 5 | Bỏ qua xử lý permission dialog native | Test treo chờ dialog vô thời hạn hoặc tap sai nút | Capability tự-cấp quyền, hoặc `mobile: acceptAlert` |
+| 6 | Test giả định luôn chạy trên 1 kích thước màn hình | Vỡ trên device thật khác resolution/aspect ratio | Locator theo key, tránh toạ độ; test responsive riêng nếu cần |
+| 7 | Không phân biệt cold start vs app đã mở sẵn | Timeout sai (cold start chậm hơn nhiều) | Timeout riêng cho bước launch đầu tiên |
+| 8 | Gộp test Android + iOS chung 1 file không parametrize | Trùng lặp code, khó bảo trì khi 1 platform đổi hành vi | Cấu hình `capabilities` theo platform, share Page Object logic, tách config |
+
+## 8. Compile & Lint (bắt buộc trước khi báo Human approve)
+
+```bash
+npx tsc --noEmit                    # type-check toàn bộ
+npx wdio run wdio.conf.ts --spec ... --dryRun    # nếu runner hỗ trợ; nếu không, review danh sách it() thủ công = số TC Automatable=Y
+```