@trungtamcongnghedigital/vsaf 1.0.0

package/skills/NTAPP/.agent/skills/NTAPP-qa-robot/references/automation/auto_gate_commands.md

@@ -0,0 +1,117 @@
+# CÁC PHÉP KIỂM BẮT BUỘC 
+
+Bản **duy nhất** của các phép kiểm trong skill. Step 02 và Step 03 dùng file này ở cổng ra. Đường dẫn tính từ `{code_repo_root}`.
+
+Mỗi mục có 4 phần: **Phải đúng** (điều cần thoả) · **Đọc gì** (mở file nào) · **Dấu hiệu sai** (nhìn thấy gì là vi phạm) · **Ghi vào báo cáo** (bằng chứng phải có).
+
+## 1. Năm Luật Chung (áp cho mọi mục dưới)
+
+- **Đọc hết, không lấy mẫu**: mục nào ghi "đọc `tests/` và `actions/`" thì phải mở **mọi** file trong đó. Không được kết luận "chắc không có" khi chưa mở hết. *("Hết" = hết phạm vi mà bước gọi file này giao; trong phạm vi đó thì vẫn phải đọc 100%.)*
+- **Bằng chứng là danh sách, không phải lời khẳng định**: mỗi mục ghi `đã đọc <X>/<Y> file (hoặc case) — <n> vi phạm` + liệt kê vị trí `file:dòng` của từng vi phạm. ❌ "Đã xem, không thấy vấn đề" = coi như **chưa kiểm**.
+- **`X` phải bằng `Y`**: đọc thiếu file nào thì nêu rõ thiếu file nào và vì sao; mục đó ghi `UNVERIFIED`.
+- **Không nới điều kiện**: thấy vi phạm thì ghi vi phạm, không tự cho ngoại lệ vì "chạy vẫn được" — [R12: rule skill là ràng buộc cứng](../../principles/iron_rules.md).
+- **Kiểm xong không để lại rác**: mọi phép đối chiếu tập mã làm **trong bộ nhớ, một lệnh** (`Compare-Object` / `awk` một lượt qua 2 file nguồn). CẤM file trung gian, CẤM `<(…)` (trên git-bash Windows nó thành file thật trong `/tmp`), CẤM ghi ra ngoài `{code_repo_root}` + `{qa_artifacts}` — [R6b](../../principles/iron_rules.md).
+
+## 2. Cấm Chờ Tĩnh, Cấm Nhảy URL (R7 · R9)
+
+- **Phải đúng**: không chỗ nào gọi `Sleep`, `Go To`, **`Reload Page`**. Chờ → `Wait Until *`; tới màn → bấm menu/nút như người dùng; reset màn → đóng+mở lại bằng click.
+- **Đọc gì**: mọi file trong `tests/`, `actions/`, `resources/`, `configs/`, **`libraries/`**. Bỏ `libraries/` là bỏ đúng chỗ hay bị lách nhất (keyword bọc đặt ở đó).
+- **Dấu hiệu sai** — dòng **gọi** keyword, tức dòng thụt đầu dòng và tên nằm trong một ô riêng (cách nhau ≥2 space **hoặc 1 tab**):
+  - ❌ `    Sleep    3s` · `<TAB>Sleep<TAB>3s` · `    Go To    ${URL}` · `    Reload Page`
+  - ✅ không tính: `Sleep Until Ready` ở **sát lề** (đó là dòng đặt tên keyword) · `    Verify User Go To Dashboard` (chữ "Go To" nằm giữa tên keyword, cách nhau 1 space) · chữ nằm sau dấu `#` (ghi chú)
+  - ⚠️ **Nhớ soi cả file dùng TAB**: Robot cho phép tách ô bằng tab, nên `Sleep` có thể không nằm sau 4 space như thường thấy. Đây là chỗ đã từng lọt sạch.
+- **Ghi vào báo cáo**: `đã đọc X/Y file — n vi phạm` + `file:dòng` từng chỗ.
+- **Không đạt** → thay chờ tĩnh bằng `Wait Until *`, thay nhảy URL bằng bấm chuột. Ngoại lệ duy nhất được phép: `Open Browser` vào trang login, 1 lần ở Suite Setup.
+- Tên keyword / ghi chú có chứa chữ `Sleep`, `Go To` không tính vi phạm ở đây, nhưng phải **đổi tên** — [convention §4](./auto_coding_convention.md).
+
+## 3. Cấm Lách Bằng Python / JavaScript / Keyword Động (R12)
+
+- **Phải đúng**: việc đã cấm ở mục 2 và 4 thì cấm ở **mọi ngôn ngữ**, không chỉ cấm đúng chữ đó trong `.robot`.
+- **Đọc gì**: mọi file `.py` trong `libraries/`, mọi keyword có gọi JavaScript, mọi chỗ gọi keyword bằng biến.
+- **Dấu hiệu sai**:
+  - chờ tĩnh viết bằng Python: `time.sleep`, `Thread.sleep`, `threading.Event().wait`, `implicitly_wait`
+  - nhảy URL: `driver.get(...)`, `window.location`, `location.href`, `history.go/back`, hoặc `Execute Javascript` / `Execute Async Javascript` làm việc đó
+  - bật headless: `options.add_argument("--headless")`
+  - gọi keyword bằng biến: `Run Keyword    ${ten_keyword}` — cách này làm mọi phép soi theo tên trở nên vô nghĩa
+- **Ghi vào báo cáo**: từng chỗ tìm được + kết luận nó là gì. Chỗ nào là chờ tĩnh / nhảy URL / headless viết bằng ngôn ngữ khác → **vi phạm**, tính vào chính mục nó lách (2 hoặc 4). Chỗ gọi keyword bằng biến → phải liệt kê **mọi giá trị biến đó có thể nhận** và chứng minh không có keyword bị cấm; không chứng minh được = vi phạm.
+- ⚠️ **Mục 2 đọc thấy sạch mà mục này có vi phạm → mục 2 KHÔNG được ghi đạt**: việc bị cấm vẫn còn, chỉ đổi cách viết.
+
+## 4. Cấm Chạy Ẩn Cửa Sổ (headless — R12)
+
+- **Phải đúng**: browser mở thật + phóng to. Thiếu màn hình để chạy → DỪNG báo người dùng, không tự bật headless.
+- **Đọc gì**: `configs/` (nhất là chỗ khai `${BROWSER}` và tham số mở browser), keyword mở browser trong `actions/common/`, mọi `.py` trong `libraries/`.
+- **Dấu hiệu sai**: chữ `headless` ở bất kỳ dạng nào — `--headless`, biến `${HEADLESS}`, biến môi trường `..._HEADLESS`, `Set Variable If ... headless`, `options.add_argument`.
+- **Ghi vào báo cáo**: `đã đọc X/Y file — n vi phạm` + vị trí.
+- **Không đạt** → xoá cách bật headless (kể cả trong `.py`).
+
+## 5. Mã Test Tự Động Phải Trùng Mã Testcase Tay (R3 · R2)
+
+- **Phải đúng**: tập mã `KB-*` trong `.robot` = tập mã các dòng `automate` trong testcase tay **trừ `excluded_ids[]`**. Không thiếu, không thừa.
+- **`excluded_ids[]`** (`datatest/{id}_gen_manifest.yaml`, do Step 01 ghi) = case có **`@target` ∉ {`robot`, vắng}** (hôm nay là `playwright`, giá trị mới upstream thêm cũng tính) — consumer khác sinh, skill này KHÔNG được sinh. `@target` là tag trong `.feature`, **không phải cột trong `.md`** → đừng cố tìm nó ở bảng markdown; lấy nguyên danh sách từ manifest. Không có file/không có `.feature` → coi như rỗng (mặc định `@target: robot`).
+- **Đọc gì**: `tests/*.robot` (lấy mã ở `[Tags]` từng test) và **`{manual_testcase_path}`** (lấy mã ở các dòng có cột `Exec` = `automate`) — path do Step 01 resolve rồi truyền vào, có thể là bản nested `{qa_artifacts}/{id}/{id}_…md` **hoặc** bản flat legacy `{qa_artifacts}/{id}_…md`. ⛔ **KHÔNG tự ghép path**: ghép bản nested ở lane HUB legacy sẽ đọc trống → `B = 0` → FAIL oan.
+- **Cách làm**: so 2 tập mã trong bộ nhớ, rồi ghi **số đếm** `A/B/C` + liệt kê **chỉ mã lệch**. Cấm in cả 2 danh sách mã (suite lớn = hàng nghìn mã in ra vô ích). Chỉ nói "đã đối chiếu, khớp" mà không có số đếm là không đủ.
+- **Dấu hiệu sai**:
+  - mã có trong `.robot` mà không có trong testcase tay → mã thừa hoặc tự đặt → xoá, hoặc sửa về mã đúng.
+  - mã có ở dòng `automate` mà không có test → thiếu test → viết bổ sung.
+- **Ghi vào báo cáo**: `số mã trong .robot = A · số mã automate trong testcase tay (đã TRỪ excluded_ids) = B · số mã bị loại vì @target:playwright = C` + danh sách mã lệch (nếu có). ⚠️ Ghi `B` **trước khi trừ** rồi so với `A` là tự tạo ra lệch giả — phải trừ trước, và nêu `C` riêng để người đọc thấy phần bị loại đi đâu.
+  ⚠️ **A hoặc B bằng 0 là dấu hiệu đọc sai chỗ** (sai file, hoặc cột `Exec` nằm khác vị trí tưởng) — kiểm lại, **đừng kết luận "khớp"**.
+- Case `pending` / `[TBD]` **vẫn phải có test mang mã** → vẫn nằm trong danh sách `.robot`.
+
+## 6. File Test Không Chứa Chi Tiết Kỹ Thuật (R4)
+
+- **Phải đúng**: `tests/*.robot` chỉ gọi keyword. Locator, câu SQL, định nghĩa keyword nằm ở `.resource`.
+- **Đọc gì**: mọi file trong `tests/`.
+- **Dấu hiệu sai**: có mục `*** Keywords ***` trong file test · locator viết thẳng (`xpath=`, `css=`, `css:`, `Get WebElements`) · câu `SELECT ...` · chuỗi kết nối DB (`jdbc:`).
+- **Ghi vào báo cáo**: `đã đọc X/Y file test — n vi phạm` + vị trí.
+- **Không đạt** → chuyển định nghĩa keyword sang `{Page}Keywords.resource`, locator sang `{Page}Variables.resource`, dữ liệu sang `datatest/`.
+
+## 7. Mỗi Case Là Một Test Riêng (R11)
+
+- **Phải đúng**: không gom nhiều case vào một test.
+- **Đọc gì**: mọi file trong `tests/`.
+- **Dấu hiệu sai**: có `[Template]` hoặc `Test Template` · một test chạy vòng lặp qua nhiều bộ dữ liệu của nhiều case khác nhau.
+- **Ghi vào báo cáo**: vị trí từng chỗ.
+- **Không đạt** → tách thành N test riêng, mỗi test kiểm đúng kết quả mong muốn của case đó.
+
+## 8. Test Phải Mang Đủ Nhãn Phân Loại Của Case (R3)
+
+- **Phải đúng**: ngoài mã `KB-*`, mỗi test mang **đúng nguyên văn** `@block:`, `@risk:`, `@rule:` (và `@oracle:` nếu có) của case gốc.
+- **Vì sao quan trọng**: nhiều phép kiểm khác **lọc case theo nhãn** (phép đếm chỉ soi case `@rule:grid-base`; nhóm lỗi và nhóm bảo mật lọc theo `@block:`; oracle-coverage lọc theo `@oracle:`). Test chỉ mang `KB-*` thì các phép kiểm đó soi **0 case rồi báo đạt** — mất phần kiểm mà không ai thấy.
+- **Đọc gì**: `[Tags]` của từng test trong `tests/*.robot` (nhãn có thể **viết tiếp ở dòng dưới bằng `...`** — phải đọc cả dòng tiếp đó, nếu không sẽ kết luận thiếu nhãn oan), đối chiếu với nhãn của scenario cùng mã trong `{qa_artifacts}/{id}/{id}_testspec.feature`.
+
+### 8a. Có đủ 5 nhóm nhãn
+
+- **Dấu hiệu sai**: test có mã `KB-*` nhưng `[Tags]` thiếu **bất kỳ** nhóm nào trong `@block:` · `@tech:` · `@rule:` · `@risk:` · `@oracle:`.
+- **`@oracle:` đếm theo SỐ LƯỢNG, không chỉ có-hay-không**: một scenario mang nhiều `@oracle` (vd `@oracle:ui` + `@oracle:db`) thì test phải mang **đủ số đó**. Thiếu 1 nhãn = mất phép kiểm oracle-coverage của R11 cho tầng đó (nó lọc case theo nhãn → soi 0 case → báo đạt im lặng). So số nhãn `@oracle` của từng mã giữa `.feature` và `.robot`.
+- **Kèm theo — suite-level `Test Tags`**: mỗi file `.robot` phải khai `Test Tags` ở `*** Settings ***` mang unit id (`@scr:<unit_id>` / `@svc:<unit_id>`) theo [step-03 §2](../../steps/step-03-generate-suite.md). Thiếu → vi phạm; dùng `Force Tags` (đã deprecated ở RF 6) → vi phạm, đổi sang `Test Tags`.
+- **Ghi vào báo cáo**: `đã đọc X/Y test — n test thiếu nhãn` + `mã case | nhãn thiếu | file:dòng`.
+- **Không đạt** → thêm nhãn còn thiếu, lấy **đúng giá trị** từ case gốc, không tự đặt giá trị mới.
+
+### 8b. Nhãn đúng nguyên văn (chỉ làm khi có file `.feature`; lane HUB cũ thì dừng ở 8a)
+
+- **Cách làm**: với từng mã case, đặt cạnh nhau nhãn trong `.feature` và nhãn trong `.robot`, so từng nhãn.
+- **Dấu hiệu sai**: nhãn có ở `.feature` mà mất trong `.robot` (nặng nhất là mất `@rule:`) · nhãn có trong `.robot` mà `.feature` không có, hoặc giá trị bị đổi.
+- **Ghi vào báo cáo**: bảng `mã case | nhãn bị mất | nhãn tự thêm/sai giá trị` — chỉ ghi case lệch, **không** kẻ bảng case đạt.
+- **Nhãn do skill tự thêm, KHÔNG tính là "tự thêm"** (đừng chấm vi phạm vì `.feature` không có chúng): `pending` · `tbd` · và **tên bucket đi kèm `pending`**: `timeout` · `mock` · `security` · `destructive` (R10 quy định `[Tags]  pending  <bucket>`).
+
+## 9. Phân Tầng POM Đúng Vai (R4 · robot §1 · structure §2-§3)
+
+- **Phải đúng**: mỗi thứ nằm đúng tầng của nó — locator ở `*Variables.resource`, keyword ở `*Keywords.resource`, chỉ `tests/` có `*** Test Cases ***`, và chiều import đi một hướng từ trên xuống.
+- **Đọc gì**: mọi file trong `tests/`, `actions/pageObject/`, `actions/serviceObject/`, `actions/common/`, `configs/`. Đọc cả phần `*** Settings ***` của từng file — đó là nơi chiều import hiện ra.
+- **Dấu hiệu sai**:
+  - locator (`xpath=`, `css=`, `id=`) khai thẳng trong `*Keywords.resource` thay vì file Variables cùng page · file Variables có mục `*** Keywords ***` · file trong `pageObject/`/`serviceObject/` có `*** Test Cases ***`
+  - `serviceObject/` có locator hoặc gọi keyword SeleniumLibrary
+  - file test import lẻ từng `*Keywords.resource` thay vì `configs/imports.resource` · file Variables import file Keywords · hai page ngang hàng import lẫn nhau
+  - có page/service mới sinh ra mà `configs/imports.resource` không khai — thiếu import thì `robot --dryrun` đỏ ở Step 03, mất trọn 1 vòng
+  - keyword trong `actions/common/` chạm locator / entity / bảng DB của **một màn cụ thể** — kể cả keyword dọn dữ liệu của màn đó (nội dung dọn gì là việc của Page, không phải BaseTest)
+- **Ghi vào báo cáo**: `đã đọc X/Y file — n vi phạm` + `file:dòng`, nêu rõ mỗi chỗ sai tầng nào và phải chuyển sang tầng nào.
+- **Không đạt** → chuyển đúng tầng; sửa `*** Settings ***` về chiều một hướng; khai import còn thiếu.
+
+## 10. Không Viết Lại Cái Đã Có (DRY — robot §4 · §5)
+
+- **Phải đúng**: một hành vi chỉ có một keyword; cụm code lặp được trích ra dùng chung.
+- **Đọc gì**: **danh sách tên keyword của toàn bộ** `actions/` (gồm `common/BasePage`, `common/BaseTest`, mọi Page/Service Keywords), và phần `*** Settings ***` + Setup/Teardown của mọi file trong `tests/`.
+- **Cách làm**: liệt kê tên keyword ra rồi soi hai chiều — trùng **tên**, và trùng **hành vi** dù khác tên (`Wait Until Text Visible` vs `Page Should Contain Text`, `Check X Displayed` vs `Verify X Visible`). Chỉ trùng tên là chưa đủ để kết luận đạt.
+- **Dấu hiệu sai**: hai keyword cùng hành vi · cùng một khối bước xuất hiện ≥3 chỗ mà không có keyword chung · block Suite Setup/điều hướng copy-paste vào từng `.robot` thay vì nằm ở `actions/common/SuiteFixtures.resource` · ≥3 locator chỉ khác một tham số khai thành N biến rời thay vì một template.
+- **Ghi vào báo cáo**: `đã soi X/Y keyword — n cặp trùng` + danh sách cặp trùng kèm `file:dòng` của cả hai, và giữ cái nào.
+- **Không đạt** → giữ một đại diện, sửa mọi chỗ gọi sang nó; trích khối lặp thành keyword chung.

package/skills/NTAPP/.agent/skills/NTAPP-qa-robot/references/automation/auto_locator_strategy.md

@@ -0,0 +1,99 @@
+# CHIẾN LƯỢC ĐỊNH VỊ PHẦN TỬ (LOCATOR STRATEGY)
+
+> **Chỉ áp cho bề mặt `ui`** (Selenium/Page Object). Bề mặt **`service`** (no-UI, RequestsLibrary) KHÔNG có locator/DOM — "định vị" bằng Contract Map (endpoint/path/field) theo [iron_rules R7s](../../principles/iron_rules.md); bỏ qua toàn bộ file này.
+
+## 1. Thứ Tự Ưu Tiên (Priority Rules)
+- **Mức 1**: Thuộc tính duy nhất (Ví dụ: `id`, `data-testid`, `data-qa`, `name`,...).
+- **Mức 2**: `Class name` (nếu class mang tính định danh rõ ràng, không bị auto-generate dạng mã băm hash).
+- **Mức 3**: `CSS` (ưu tiên do tốc độ truy vấn nhanh và cú pháp gọn gàng).
+- **Mức 4**: `Text / Link Text` (phù hợp cho các element tĩnh không đổi ngôn ngữ).
+- **Mức 5**: `XPath` (chỉ dùng khi cần xác định phần tử cha-con phức tạp hoặc tìm theo text `//div[contains(text(), "xxx")]` hoặc cần truy vấn nhiều điều kiện liên quan nhau trong một câu lệnh).
+
+## 2. Cú Pháp Định Vị Bắt Buộc (Explicit Locator Syntax)
+**Luôn ghi tiền tố tường minh** (`id` · `name` · `identifier` · `class` · `tag` · `css` · `xpath` · `text`) — không để locator trần, tránh mập mờ và tăng tốc engine. Dấu phân cách `:` hoặc `=` đều được nhưng **phải nhất quán trên toàn framework**. Ví dụ: `id:login-button`, `css:.btn-primary > span`, `xpath=//div[@class='menu']`.
+
+## 3. Nguyên Tắc Trích Xuất Bắt Buộc
+- **Cấm Absolute XPath**: Tuyệt đối không dùng XPath tuyệt đối theo cấu trúc DOM (VD: `/html/body/div[1]/div[2]/span`).
+- **ĐÚNG**: Step 02 lấy locator từ source code thật (template/DS), không suy diễn ngoài source; thiếu → `[TBD]`, cấm bịa. Xác minh khớp DOM + sửa khi lệch là ở **Step 05** (chạy thật → fail → self-heal re-derive từ DOM).
+- **TRACE ĐỦ LỚP trước khi `[TBD]`**: với component **wrapper / config-driven** (vd `vt-filter-list` → `vt-filter-button`, `vt-c-table`, `vt-input`), PHẢI đi hết chuỗi tới DOM thật trước khi kết luận thiếu hook: (1) template host → (2) `*.component.ts` (configs/fields định nghĩa control: `controlName`/`fieldName`/`type`) → (3) template component con (`vt-*`/`app-*`) lộ element thật (`input`/`button`/`nz-*` + class/name/aria) → (4) i18n (`*/i18n/*.json`) lấy text/placeholder/label thật cho locator-theo-text. CẤM dừng ở lớp wrapper rồi đánh `[TBD]` chỉ vì "render động" — component động CÀNG bắt buộc đào xuống lớp con tìm DOM. `[TBD]` chỉ hợp lệ sau khi đã đi hết 4 lớp mà source THẬT SỰ không lộ hook ổn định.
+- **CẤM neo vào chuỗi i18n khi còn hook khác**: `placeholder`/text lấy qua `*/i18n/*.json` chỉ đúng với **đúng commit đang đọc** — bản deploy thường mới/cũ hơn repo, và chuỗi hiển thị là thứ CR đổi thường xuyên nhất. Thứ tự neo: `data-testid`/`id`/`name`/`formControlName` → class ngữ nghĩa của DS → **nhãn (`<label>`) do DD quy định** → placeholder → text tự do. Buộc phải neo theo chuỗi thì lấy chuỗi từ **DD/contract**, không lấy từ i18n repo, và phải verify trên DOM thật ở bậc smoke ([step-05 §2.b0](../../steps/step-05-execute-and-analyze-logs.md)) TRƯỚC khi sinh tiếp phần còn lại.
+- **Source phải là mốc ổn định**: file template đang `modified` chưa commit → nêu rõ trong báo cáo và verify DOM thật, KHÔNG coi là nguồn chuẩn.
+- **DUY NHẤT**: locator phải khớp đúng 1 phần tử (để automate trúng). Tránh thứ chỉ duy nhất *tình cờ theo state* (class framework tự sinh, hash, shape/util) — đổi state là hết duy nhất.
+- **CÓ NGHĨA**: trong các cách duy nhất, chọn cái mô tả đúng danh tính/chức năng control (`data-testid` / `id` / `name` / `placeholder` / class ngữ nghĩa do dev đặt / text / `aria-label`).
+- **Độ ổn định**: HẠN CHẾ TỐI ĐA việc định vị theo index/thứ tự; tránh tuyệt đối index *không chắc chắn* (VD: `(//div[@class='item'])[4]`) hoặc các pseudo-class phụ thuộc vị trí như `nth-child()`, `nth-of-type()` trong CSS. Ưu tiên sử dụng các thuộc tính có ý nghĩa như `name`, `formControlName`, `placeholder` hoặc các custom attributes (`data-testid`). Chỉ dùng vị trí khi thật sự không còn thuộc tính nào phân biệt được.
+
+## 4. Chuẩn Đặt Tên Biến Locator
+Tất cả các locator phải được lưu vào file `{Page}Variables.resource` và tuân thủ định dạng:
+`${LOAI_ELEMENT}_${CHUC_NANG}`
+
+**Ví dụ:**
+- Input: `${INPUT_USERNAME}`, `${INPUT_PASSWORD}`, `${INPUT_SEARCH}`
+- Button: `${BTN_LOGIN}`, `${BTN_SUBMIT}`, `${BTN_CANCEL}`
+- Dropdown: `${DDL_COUNTRY}`, `${DDL_STATUS}`
+- Checkbox/Radio: `${CHK_REMEMBER_ME}`, `${RDO_GENDER_MALE}`
+- Text/Label: `${LBL_ERROR_MESSAGE}`, `${TXT_WELCOME}`
+
+## 5. Xử Lý Các Trường Hợp Đặc Biệt
+- **Phần tử động (Dynamic Elements)**: Sử dụng các hàm xpath như `contains()`, `starts-with()` để đối phó với các element sinh tự động có tiền tố/hậu tố random.
+- **Xử lý Dynamic Locator**: Sử dụng biến tích hợp (Embedded Arguments) hoặc từ khóa thuộc thư viện String để định dạng chuỗi (String Formatting), giúp linh hoạt hóa các Locator.
+  - **Đặt tên biến template:** thêm hậu tố `_TPL` để phân biệt với locator tĩnh — `${MENU_ITEM_TPL}`, `${BTN_BY_LABEL_TPL}`, `${ROW_BY_CODE_TPL}`. Nhìn tên là biết phải `Format String` trước khi dùng, không truyền thẳng vào `Click Element`.
+  - **Khi nào BẮT BUỘC chuyển sang template (DRY):** có **≥3 locator chỉ khác nhau đúng một chuỗi** (`${LNK_MENU_ORDER}`, `${LNK_MENU_CUSTOMER}`, `${LNK_MENU_REPORT}`…) → gom về 1 template + 1 keyword nhận `[Arguments]`. Mỗi menu/hàng/tab thêm một biến locator là mỗi lần phải sửa N chỗ khi DOM đổi.
+  - **Khi nào KHÔNG dùng template:** control **đơn nhất** trên màn (nút Lưu, ô tìm kiếm) — template hoá làm mất tính đọc-hiểu mà không tái dùng được gì; và khi tham số truyền vào là **text i18n** dễ đổi trong khi đã có `id`/`data-testid` ổn định (§1 vẫn thắng: ưu tiên id).
+  - *Ví dụ phân tách file theo chuẩn POM:*
+  
+  **File `MenuVariables.resource`:**
+  ```robotframework
+  *** Variables ***
+  ${MENU_ITEM_TPL}    xpath=//div[@class='menu']//a[text()='{menu_name}']
+  ```
+
+  **File `MenuKeywords.resource`:**
+  ```robotframework
+  *** Settings ***
+  Resource    MenuVariables.resource
+  Library     String
+
+  *** Keywords ***
+  Click Menu Item
+      [Arguments]    ${menu_name}
+      ${locator}    Format String    ${MENU_ITEM_TPL}    menu_name=${menu_name}
+      Click Element    ${locator}
+  ```
+- **Phần tử bên ngoài Viewport**: Sử dụng keyword `Scroll Element Into View` trước khi tương tác.
+
+## 6. Nguồn locator khi KHÔNG có code FE (Live-DOM Harvest — `locator_source: live-dom`)
+
+> Áp khi Step 01 detect `locator_source: live-dom` (không có repo FE source, nhưng app staging login được). Đổi **nguồn** locator từ source tĩnh sang **DOM thật của app đang chạy** — cùng thứ tự ưu tiên §1, cùng nguyên tắc trích §3, cùng chuẩn đặt tên §4. Đây là **phiên soi DOM riêng ở Step 02, KHÔNG phải chạy test case**; mục tiêu là ghi `{Page}Variables.resource` đã verify TRƯỚC khi sinh + chạy suite (không phụ thuộc self-heal Step 05).
+
+### 6.1 Quy trình soi (một lần, ở Step 02)
+
+> **Không có chicken-and-egg:** DOM **trang login đọc được TRƯỚC khi đăng nhập** (trang pre-auth, render ngay khi mở browser) → locator login harvest được mà không cần login trước. Thứ tự: (a) nếu repo **đã có keyword login chạy được** → locator login đã tồn tại → bỏ qua, vào thẳng bước 2 dưới; (b) nếu chưa → soi DOM trang login pre-auth lấy `INPUT_USERNAME`/`INPUT_PASSWORD`/`INPUT_CAPTCHA`/`BTN_LOGIN` rồi mới build login. Locator màn chức năng (post-auth) soi sau khi đã login. Locator login KHÔNG phụ thuộc locator màn chức năng.
+
+1. `Open Browser ${BASE_URL}` (1 lần) → login: **TÁI DÙNG keyword login sẵn có của repo automation** (đã tự giải captcha-text qua API gen/verify) nếu tồn tại — KHÔNG dựng lại luồng login. Chỉ khi repo chưa có keyword login mới soi DOM trang login (pre-auth) theo ghi chú trên + `automation_prereq.auth`.
+2. **Click** điều hướng tới từng màn cần locator (theo R9 — CẤM `Go To`; mở modal/màn con bằng nút ở màn cha).
+3. Đưa màn về **đúng state có đủ control** (có data để list/row hiện; mở modal nếu control nằm trong modal). List rỗng → không có locator của row/nút thao tác → cần data (báo nếu thiếu).
+4. Với mỗi control trong `ui_schema` checklist, đọc DOM thật:
+   - `Get WebElements` + `Get Element Attribute`, hoặc `Execute Javascript` trả về danh sách ứng viên kèm thuộc tính (`id`, `data-testid`/`data-qa`, `name`, `formControlName`, `class`, `aria-label`, `placeholder`, `innerText`).
+5. Chọn locator theo **thứ tự ưu tiên §1** (id/data-testid/name → class ngữ nghĩa → css → text → xpath), tuân nguyên tắc §3 (DUY NHẤT + CÓ NGHĨA, cấm index/nth-child, cấm absolute xpath).
+6. **Ghi thẳng** locator đã chọn vào `{Page}Variables.resource` (chuẩn tên §4). Verify mỗi locator resolve đúng 1 element ngay trong phiên soi (vd `Get Element Count == 1`).
+
+### 6.2 Gate
+- Mọi control trong checklist phải có locator verify được từ DOM. Control **thật sự vắng** trên DOM (state chưa đúng / feature chưa build) → `[TBD]` + báo, KHÔNG bịa (R1/R5).
+- Xong phiên soi + Variables.resource sạch `[TBD]` → mới sang Step 03. KHÔNG dùng phiên soi này để assert nghiệp vụ (nó chỉ lấy locator).
+
+### 6.3 Lưu ý
+- Locator live-dom mất "trace về source" (provenance §3 ĐÚNG) — đổi lại khớp DOM thật, ổn định hơn cho black-box. Chấp nhận được khi không có code.
+- Nếu app KHÔNG login được / KHÔNG tới được màn → không harvest được → fallback: nhận **DOM snapshot** (`outerHTML` từng màn do người cung cấp) và trích locator từ HTML thật đó; vẫn KHÔNG có snapshot → `[TBD]` toàn bộ + DỪNG báo thiếu (R5).
+
+### 6.4 Thang fallback khi phiên soi Selenium không dựng được (thiếu driver / không có display)
+
+Đây là **trở ngại runtime** → R12 áp: **DỪNG + báo user TRƯỚC**, không tự đổi công cụ. Sau khi user xác nhận, đi theo thứ tự:
+
+1. **Selenium headed (mặc định)** — cách duy nhất không cần xin phép.
+2. **Tool browser của môi trường agent (vd MCP `playwright`), CHỈ nếu môi trường đang có tool đó** — dùng **read-only để thu DOM**, không phải để chạy test:
+   - Điều hướng vẫn **theo click** như §6.1 bước 1-3 (R9 — cấm deep-link URL tới màn chức năng).
+   - Lấy `outerHTML` / danh sách thuộc tính ứng viên, rồi chọn locator theo **§1-§4 như thường**.
+   - **Locator ghi ra `{Page}Variables.resource` phải là cú pháp SeleniumLibrary** (`id=`, `css=`, `xpath=` — §2). CẤM copy selector đặc thù của Playwright (`get_by_role`, `text=`, `>> nth=`) vào Variables.
+   - Xác minh duy-nhất (đúng 1 element) ngay trong phiên soi; kết quả vẫn phải pass **§6.2 Gate**.
+   - Suite thực thi (Step 03/05) **vẫn là SeleniumLibrary headed** — R12 không nới. Phiên soi này không phải test run nên không tính là lách R12, nhưng **phải ghi rõ trong báo cáo Step 02** là locator harvest bằng tool nào.
+3. **DOM snapshot do người cung cấp** (§6.3) → cuối cùng mới `[TBD]` + DỪNG.

package/skills/NTAPP/.agent/skills/NTAPP-qa-robot/references/automation/auto_robot_rules.md

@@ -0,0 +1,90 @@
+# QUY TẮC TỰ ĐỘNG HÓA ROBOT FRAMEWORK (ROBOT AUTOMATION RULES)
+
+> **Phạm vi bề mặt:** phần lớn quy tắc dưới đây viết cho bề mặt **`ui`** (Selenium: locator, `Open Browser`/`Maximize`, `Input Text`, `Page Contains`, Smart Wait element). Các nguyên tắc **feature-agnostic áp cho cả `service`**: POM (§1 — đổi Page↔Service Object), library-first (§5, dùng `RequestsLibrary`), DRY/KISS, cấm `Sleep`, data-driven (không hardcode). Các mục thuần-UI (mở browser/maximize, gõ element, `Page Contains`) **KHÔNG áp** cho bề mặt `service` — thay bằng `Create Session` + `... On Session` + assert status/body/DB/MSG, async dùng `Wait Until Keyword Succeeds` (xem [iron_rules R7s](../../principles/iron_rules.md) + step-02 nhánh service).
+
+## 1. Page Object Model (POM)
+- **Cấu trúc Thư mục**: Tổ chức source code phân mảnh rõ ràng theo cấu trúc Page.
+- **Variables Resource (`{Page}Variables.resource`)**: Chứa 100% locator của giao diện đang test.
+- **Keywords Resource (`{Page}Keywords.resource`)**: Chứa các action tương tác UI và các hàm logic kiểm tra.
+- **Test Suite (`[Screen]Test.robot`)**: Chỉ chứa `*** Settings ***` + `*** Test Cases ***` (+ tối đa `*** Variables ***`) — **GỌI** high-level keyword, **KHÔNG có section `*** Keywords ***`** (mọi định nghĩa keyword nằm ở `.resource` — xem [iron_rules R4](../../principles/iron_rules.md)). TUYỆT ĐỐI không khai báo định danh/locator/SQL ở đây.
+
+## 2. Quản Lý Dữ Liệu Test (Test Data Management)
+- **Tách biệt dữ liệu**: Tách dữ liệu khỏi script logic bằng file định dạng `.yaml`, `.json` (nạp dataset theo `@id` mỗi case). "Data-driven" ở đây = *tách nguồn dữ liệu*, KHÔNG phải dùng `Test Template`/`[Template]` để gom nhiều case vào 1 test — mỗi case là 1 Test Case riêng (per-case, xem [iron_rules R8/R11](../../principles/iron_rules.md)).
+- **Tính tự sinh**: Các dữ liệu mang tính định danh duy nhất (email, username, ID) bắt buộc phải được sinh ngẫu nhiên (ví dụ bằng Faker) để tránh trùng lặp dữ liệu khi chạy lại.
+- **Tiền tố `auto_`**: Mọi giá trị định danh kiểu chuỗi sinh ra và ghi vào hệ thống phải BẮT ĐẦU bằng `auto_` — dạng `auto_<nhãn>_<run-marker>_<uuid8>` (xem [iron_rules R7d](../../principles/iron_rules.md)). Miễn trừ: trường chỉ nhận số và ca biên độ dài. Keyword sinh tên đặt tập trung một chỗ trong `actions/common/`, cấm mỗi test tự nối chuỗi tên riêng.
+- **Biến môi trường**: Các thông số về Server URL, Browser type, Global Timeout phải được đặt tại file config chung của dự án.
+- **Escape ký tự đặc biệt khi emit data vào step** (lỗi sinh thường gặp):
+  - **Khoảng trắng trọng yếu**: giá trị chứa ≥2 space liên tiếp, hoặc space đầu/cuối có ý nghĩa, BẮT BUỘC dùng `${SPACE}` cho từng space (vd `Hồ${SPACE}${SPACE}sơ A`). Robot Framework tách argument theo 2+ space → để literal `Hồ  sơ A` sẽ bị tách thành 2 argument → keyword nhận sai số tham số.
+  - **Ký tự ngoài BMP (astral, vd emoji 🚀 U+1F680)**: ChromeDriver `send_keys` KHÔNG gửi được → `WebDriverException: only supports characters in the BMP`. Nếu data nguồn chứa astral char: route case sang `manual` (ghi rõ lý do giới hạn driver) HOẶC dùng JS set-value; KHÔNG emit `Input Text` với astral char. Ký tự BMP (©®™€§…) thì gõ bình thường.
+  - **Xoá field validation phải bắn event**: `Clear Element Text` không bắn `input` → Angular không `dirty/touched` → lỗi required/regex không hiện. Cần xoá để test required: dùng `Press Keys ${locator}    CTRL+a    DELETE` (+`TAB` nếu cần touched).
+
+## 3. Quản Lý Thời Gian Chờ (Wait Strategies)
+- **Cấm Sleep tĩnh**: Cấm sử dụng từ khóa `Sleep` với thời gian cứng.
+- **Smart Wait**: Bắt buộc sử dụng các keyword thăm dò trạng thái như `Wait Until Element Is Visible`, `Wait Until Element Is Enabled`, hoặc `Wait Until Keyword Succeeds`.
+- **Click bị lớp phủ che**: element `Visible`+`Enabled` VẪN có thể bị lớp phủ loading (spinner/overlay/backdrop) chặn → click ném `ElementClickInterceptedException`. Wrapper click/input phải **chờ lớp phủ biến mất trước khi thao tác** (vd `Wait Until Keyword Succeeds` kiểm không còn overlay hiển thị). Chỉ `Wait Until Enabled` là KHÔNG đủ — đây là lỗi hay lọt.
+- **Cấm Hardcode Timeout**: Khi sử dụng Smart Wait, KHÔNG được hardcode thời gian. Ví dụ: `timeout=10s`. BẮT BUỘC truyền biến từ `GlobalConstants.resource`, chọn 1 trong 3 tầng theo bản chất thao tác:
+  - `${SHORT_TIMEOUT}` (2s) — probe element **có thể không xuất hiện** (đi kèm `Run Keyword And Return Status`). Ví dụ: kiểm tra form login đã hiện chưa.
+  - `${GLOBAL_TIMEOUT}` (10s) — **mặc định**, chờ element load bình thường. Ví dụ: `Wait Until Element Is Visible    ${locator}    timeout=${GLOBAL_TIMEOUT}`.
+  - `${LONG_TIMEOUT}` (30s) — thao tác biết trước sẽ chậm. Ví dụ: submit nặng, chờ bảng lớn render, gọi API/downstream.
+- **CẤM IMPLICIT WAIT — và CẤM TRỘN implicit với explicit.** `Set Selenium Implicit Wait`, `Open Browser ... implicit_wait=`, `driver.implicitly_wait()` trong Python library: KHÔNG dùng, giữ implicit wait = **0**. Chỉ chờ bằng explicit (`Wait Until *`).
+  - **Vì sao:** trộn hai loại làm thời gian chờ **không đoán được** (driver đã chờ ngầm rồi explicit chờ tiếp), và mọi phép kiểm **phủ định** (`Element Should Not Be Visible`, probe `Run Keyword And Return Status`) bị đội lên trọn implicit timeout — suite chậm gấp N lần số assert phủ định, đồng thời che race condition thật vì cái gì cũng "kịp" hiện.
+  - **Bẫy đã thấy ngoài thực tế:** khung base set `implicitlyWait(30s)` ở tầng khởi tạo driver trong khi tầng page dùng `WebDriverWait(30s)` — không ai chỉnh vì test vẫn xanh, nhưng mỗi negative check tốn 30s và số đo timeout trong code không còn phản ánh hành vi thật.
+  - **Chọn tier theo bản chất phép kiểm, không theo thói quen:** kiểm **có xuất hiện** → `${GLOBAL_TIMEOUT}` (hoặc `${LONG_TIMEOUT}` nếu biết chậm); kiểm **không/chưa xuất hiện** → `${SHORT_TIMEOUT}`. Dùng `${LONG_TIMEOUT}` cho check phủ định là lỗi hiệu năng, không phải "cho chắc".
+
+## 4. Quy Tắc Chống Mẫu Nghiêm Cấm (Anti-Patterns)
+- ❌ **Tự chế dữ liệu (Data Fabrication)**: Tuyệt đối KHÔNG tự ý sinh ra dữ liệu giả (fake data) khi chưa có file dữ liệu gốc. Mọi dữ liệu (hằng số môi trường, payload test) BẮT BUỘC phải được kế thừa từ file cấu hình hoặc dữ liệu thực tế (từ Manual Testcase, `{id}_fixtures.yaml`). Nếu không có, để rỗng hoặc báo lỗi.
+- ❌ **Hardcode dữ liệu**: Nhúng thẳng chuỗi text/password/username trực tiếp vào các Test Case.
+- ❌ **Locator rác**: Khai báo Xpath/CSS rải rác ngay trong file `.robot` hoặc file `{Page}Keywords.resource`.
+- ❌ **Thiếu Assertion**: Test steps chỉ thực hiện hành động click/input nhưng không có bước kiểm tra kết quả (thiếu các keyword `Should Be ...`).
+- ❌ **Test Case Phụ Thuộc Nhau**: Kịch bản Test 2 không thể chạy nếu Kịch bản Test 1 fail. Bắt buộc: mỗi Test Case phải hoàn toàn độc lập, có Setup và Teardown tự dọn dẹp trạng thái. **Trường hợp ẩn — tài nguyên precondition BỊ TIÊU THỤ** (vd tạo composite ăn 1 pending): CẤM resolve-once + `Set Suite Variable` dùng lại cho mọi case; case đầu tiêu thụ xong thì case sau fail. Phải seed/rotate bản ghi tươi cho từng case tiêu thụ — xem [auto_db_oracle_rules §11](./auto_db_oracle_rules.md#11-tài-nguyên-precondition-bị-tiêu-thụ-consumable--cấm-cache-1-lần-cho-cả-suite).
+  - **Teardown Variable Safety**: BẮT BUỘC dùng `Get Variable Value` trong Teardown cho các biến được khởi tạo trễ (hoặc có thể chưa gán) để tránh lỗi `Variable not found` làm ngắt quãng việc dọn dẹp dữ liệu/DB.
+  - **Chọn dòng trên danh sách UI**: Khi dữ liệu cũ trong DB không được dọn dẹp tự động: CẤM chọn dòng theo vị trí cố định (như dòng đầu tiên) ở happy path. BẮT BUỘC truy vấn DB lấy ID bản ghi chưa sử dụng (unconsumed) và thực hiện chọn theo ID đó.
+  - **Duy trì Access Token**: Khi reload/navigation làm mới đối tượng `window` (mất JS hook/sniffer): BẮT BUỘC lưu Access Token vào biến Suite ngay sau khi login và cấu hình hàm đọc Token tự động fallback về biến này.
+- ❌ **Trùng lặp keyword**: Tạo nhiều keyword có cùng hành vi/chức năng (ví dụ `Wait Until Text Visible` và `Page Should Contain Text`). Chỉ dùng duy nhất một đại diện.
+- ❌ **Đặt tên Keyword bằng tiếng Việt**: Tên Keyword trong `.resource` (định nghĩa ở `*** Keywords ***`) BẮT BUỘC tiếng Anh — không có ngoại lệ (xem `auto_coding_convention.md` §1). Không tự dịch/paraphrase business term sang tiếng Việt để "dễ đọc" — vẫn giữ nguyên ngữ nghĩa bằng tiếng Anh (vd `Open Compose Screen`, không phải `Mở Màn Compose`).
+
+
+
+## 5. Nguyên tắc lập trình (Design Principles)
+- **Library-first**: Ưu tiên keyword của thư viện Robot chuẩn (SeleniumLibrary, RequestsLibrary, DatabaseLibrary, String, Collections, DateTime…) cho MỌI thao tác (UI / HTTP / DB / chuỗi / ngày). KHÔNG tự viết Python library hay logic riêng khi đã có keyword thư viện làm được.
+- **DRY**: **Trước khi sinh keyword mới, BẮT BUỘC quét toàn bộ keyword hiện có (BasePage, BaseTest, các Page Object Keywords liên quan). Đã có keyword cùng chức năng → tái sử dụng, TUYỆT ĐỐI không sinh thêm keyword mới.** Cụm code lặp → trích ra common keyword.
+- **KISS + YAGNI**: **Mỗi keyword chỉ mang DUY NHẤT 1 trách nhiệm** — tên nói đúng những gì nó làm, không hơn; vừa làm A vừa làm B → tách 2 keyword (vd `Open App Browser` chỉ mở browser, không kiêm lưu path điều hướng). Chỉ implement trong phạm vi yêu cầu hiện tại: TUYỆT ĐỐI không nhồi `[Arguments]` / `Set Suite Variable` "dự phòng cho sau này" khi chưa keyword nào đọc tới (dead code).
+
+## 6. Hướng Dẫn Khởi Tạo Nguồn Tài Nguyên (Generation Guidelines)
+- **Base Components**:
+  - actions/common/GlobalConstants.resource: Khai báo các hằng số cấu hình. CHỈ khởi tạo khi thực sự cần thiết và ĐÃ CÓ SẴN thông tin. Tuyệt đối không tự chế mock data.
+  - actions/common/BasePage.resource: Wrapper bọc lại các lệnh gốc (VD: SeleniumLibrary). CHỈ thêm các Custom Keywords khi kịch bản test thực sự dùng đến. Phải kết hợp sẵn Smart Wait và Log/Exception.
+    - **Mở browser BẮT BUỘC phóng to cửa sổ**: keyword wrapper mở browser (vd `Open App Browser`) phải gọi `Maximize Browser Window` NGAY SAU `Open Browser`, trước mọi thao tác điều hướng. Lý do: cửa sổ mặc định/nhỏ dễ đẩy element vào responsive/collapsed layout (menu ẩn sau hamburger, cột bảng bị ẩn) → locator không visible → false-fail. KHÔNG dựa vào `--window-size` cứng thay cho maximize. Ví dụ:
+      ```robotframework
+      Open App Browser
+          Open Browser    ${BASE_URL}    ${BROWSER}    options=...
+          Maximize Browser Window
+          Register Keyword To Run On Failure    NONE
+      ```
+  - actions/common/BaseTest.resource: Chứa các hàm tiện ích cấp độ Suite. Tránh khai báo hàm thừa thãi.
+- **Suite & Imports**:
+  - configs/imports.resource: Nơi tập trung import của dự án. Tự động khai báo thêm đường dẫn import tới các file Page Keywords mới tạo.
+  - [FeatureName]Test.robot: Trong file Suite, phần *** Settings *** chỉ import duy nhất configs/imports.resource (nguyên tắc Top-down).
+  - TUYỆT ĐỐI không khai báo trực tiếp locator trong file .robot. Nếu chưa có data thực tế, bắt buộc phải dừng lại hoặc để rỗng.
+
+---
+
+## 7. Chọn Oracle Kiểm Chứng (Verification Strategy)
+
+Chọn keyword assertion theo **bản chất nơi kết quả hiển thị** — sai oracle là lỗi sinh thường gặp gây false-fail:
+
+- **Giá trị NẰM TRONG input/textarea** (verify field giữ/echo đúng text đã nhập: maxlength, space-handling, unicode echo) → assert bằng **`Get Value`** của field đó (vd keyword `<Field> Value Should Be/Contain`). **CẤM** dùng `Page Should Contain` / `Wait Until Page Contains` — value của input KHÔNG phải text-node của trang nên Page-Contains luôn FAIL.
+- **Text render ra trang** (toast, ô trong list/grid, **inline error message**, banner) → mới dùng `Page Should Contain` / `Wait Until Page Contains` hoặc `Element Should Be Visible` trên locator của phần tử đó.
+- **Trạng thái element** (enabled/disabled/visible) → `Element Should Be Enabled/Disabled`, `Element Should Be Visible`.
+- **Tập kết quả** (list/grid/panel — Expected "mọi bản ghi khớp filter" / "hiển thị đủ N") → lấy tập dòng (`Get WebElements`) rồi assert TỪNG dòng khớp điều kiện + `Length Should Be`/count. CẤM coi `Page Should Contain` 1 giá trị là đủ (list đúng một phần vẫn pass sai).
+- **Phản hồi lỗi độc quyền** (Expected exclusivity) → assert đúng 1 phản hồi đặc tả, kèm `Page Should Not Contain` message generic/khác bị cấm.
+- Quy tắc nhanh: *"Mình đang gõ vào ô và kiểm ô có giữ đúng không?"* → `Get Value`. *"Mình kiểm hệ thống có hiện chữ/thông báo ra màn không?"* → `Page Contains`.
+
+---
+
+## 8. Chụp Ảnh
+
+CHỈ chụp khi test FAIL. Mặc định `run_on_failure` chụp mọi keyword fail (kể cả fail bị nuốt bởi `Run Keyword And Return Status`) → case PASS vẫn ra ảnh thừa.
+
+- Suite Setup: `Register Keyword To Run On Failure    NONE`
+- Test Teardown: `Run Keyword If Test Failed    Capture Page Screenshot`

package/skills/NTAPP/.agent/skills/NTAPP-qa-robot/references/automation/automation_standards.md

@@ -0,0 +1,19 @@
+# Robot Automation Standards (Facade)
+
+Tài liệu này là Mục lục tiêu chuẩn dành cho việc Sinh mã nguồn Kiểm thử Tự động bằng Robot Framework.
+
+Mọi Agent liên quan đến việc viết code Automation **bắt buộc** phải tuân thủ các quy định được định nghĩa chi tiết tại thư viện lõi:
+
+1. **Coding Convention:** [auto_coding_convention.md](./auto_coding_convention.md)
+
+2. **Framework Structure:** [auto_framework_structure.md](./auto_framework_structure.md)
+
+3. **Locator Strategy:** [auto_locator_strategy.md](./auto_locator_strategy.md)
+
+4. **Robot Rules:** [auto_robot_rules.md](./auto_robot_rules.md)
+
+5. **DB Oracle Rules:** [auto_db_oracle_rules.md](./auto_db_oracle_rules.md) — wire tầng `@oracle:db` (query + assert thật thay stub `Verify DB`)
+
+6. **Các phép kiểm bắt buộc:** [auto_gate_commands.md](./auto_gate_commands.md) — **bản DUY NHẤT**: mỗi phép kiểm ghi rõ *phải đúng gì · đọc file nào · dấu hiệu sai là gì · ghi bằng chứng thế nào* (chờ tĩnh/nhảy URL, lách bằng Python-JS, headless, mã trùng testcase tay, file test sạch, `[Template]`, nhãn phân loại, phân tầng POM, DRY). **Kiểm bằng ĐỌC CODE, không chạy lệnh.** Đọc ở **Step 02 + 03**; cấm copy sang file khác, cấm tự nới phạm vi.
+
+*(Lưu ý cho AI Agent: Khi được yêu cầu sinh mã nguồn, bạn phải chủ động truy cập các link trên để đọc tiêu chuẩn trước khi viết code).*

package/skills/NTAPP/.agent/skills/NTAPP-qa-robot/steps/step-01-parse.md

@@ -0,0 +1,79 @@
+# STEP 01: ĐỌC MANUAL TESTCASE & LẬP KẾ HOẠCH SINH CODE
+
+> **Acting as:** [Agent Robot Generator](../agents/agent_robot_generator.md)
+> **Tuân thủ:** [Iron Rules](../principles/iron_rules.md) — R1, R2, R3, R5, R6, R10, R11, R16. Chi tiết: [Robot Rules](../references/automation/auto_robot_rules.md), [Framework Structure](../references/automation/auto_framework_structure.md).
+> ⛔ Chỉ đọc step kế qua con trỏ Next ở CUỐI file — sau khi qua đủ 4 cổng ra.
+
+**Step này CHƯA sinh code.** Nó chốt 7 thứ cho Step 02/03/04: `{code_repo_root}` · `manual_testcase_path` · `surface_type` · `locator_source` · `excluded_ids[]` · case nào `run`/`pending`/`tbd` · case nào giữ/sinh lại/thêm/xoá.
+
+## 1. Input
+
+`{id}` = ID đầy đủ (`SLICE-06` / `WGT-SIDEBAR` / `HUB-01`); 3 file đầu ở `{qa_artifacts}/{id}/`.
+
+| File | Vai trò | Thiếu thì |
+|---|---|---|
+| `{id}_detailed_test_manual_testcase.md` | Bản QA ký — dùng **cột mã** + **cột `Exec`**; cột "Data Test" chỉ khi vắng fixtures. KHÔNG phải nguồn assert | DỪNG (R5) |
+| `{id}_testspec.feature` | Gherkin + tag — **nguồn DUY NHẤT sinh script**, canonical khi lệch `.md` | **DỪNG (R5)**. Chỉ bỏ qua ở lane HUB legacy vốn không có file này |
+| `{id}_fixtures.yaml` | Nguồn data mồi duy nhất (`datasets[]` + `automation_prereq` + marker `$…`) | rơi về nhánh 6b |
+| `{ui_schema_root}/ui_schema_{id}.json` *(ui)* | Checklist control cho selector | DỪNG (R5) nếu `automation_prereq.ui_schema_required` khai. Lane HUB legacy: DỪNG khi bề mặt `ui` không có checklist nào |
+| `{detailed_design_root}/*_detailed_design.md` | Tham chiếu bổ trợ khi `.feature` nói vắn. Lane SLICE dùng DD **từng unit** (`@scr`/`@svc`), KHÔNG có `{slice_id}_detailed_design.md` | **KHÔNG DỪNG** — bỏ qua, nêu 1 dòng |
+| `{qa_artifacts}/data_sources.yaml` | Registry sinh **data động** (auth · create_api · lookup · reuse_check · teardown) — vai trò chính. Kèm theo đó là base URL / env prefix / tài khoản đã verify của chính nguồn seed: có sẵn thì dùng, cấm hỏi lại | DỪNG (R5) nếu fixture có `$db.query`/`$seed.*` |
+| `project_wbs.md` (`{planning_artifacts}`) | `{id}` có trong WBS — R7 #1 | Không có trong WBS → **DỪNG**. WBS chưa tồn tại → bỏ qua, nêu 1 dòng |
+
+Tag / marker lạ → propagate nguyên văn + nêu trong báo cáo, KHÔNG suy nghĩa (R1).
+
+## 2. Trình tự thực thi — đúng thứ tự này
+
+**1. Chốt nơi ghi code (R6).** Resolve `{code_repo_root}`; chưa chốt → **KHÔNG sinh file nào**. Mọi path output relative theo biến này.
+
+**2. Tìm testcase.** Tìm `{qa_artifacts}/{id}/{id}_detailed_test_manual_testcase.md` (hoặc `{qa_artifacts}/{id}_*.md` flat legacy). Nếu thiếu → **DỪNG (R5)**. Chốt đường dẫn tuyệt đối vào `manual_testcase_path`. Nếu vắng `.feature`, lấy mã từ `.md` và điền `N/A` cho nhãn thiếu, cấm bịa (R1).
+
+**2b. R7 #3 — so khớp tập mã `.feature` ↔ `.md`.** Mã có bên này thiếu bên kia → **DỪNG**, báo `@id`. Bám theo `.feature` làm canonical, ghi nhận lệch trong báo cáo.
+
+**3. Lọc phạm vi automation (R2).** Lọc dòng có `Exec = automate` VÀ `@target` ∈ {`robot`, vắng} (nếu không có cột `Exec` -> coi tất cả là automate). Các case có `@target` khác lưu vào `excluded_ids[]`.
+
+**4. Xác định `surface_type`.** Đọc tag scenario thật (`@scr` -> UI, `@svc` -> Service).
+- Một scenario mang cả hai tag → **DỪNG (R5)**.
+- Có cả scenario `@scr` và `@svc` riêng biệt → `surface_type` là **TẬP** (chạy cả hai nhánh).
+
+**5. Detect `locator_source`** *(chỉ `ui`)*: `source` (đọc được `*.component.html`) · `live-dom` (app staging login được + `automation_prereq` có `base_url`/`auth`/đường click) · không có cả hai → **DỪNG (R5)**.
+
+**6. Chép dữ liệu mồi sang code repo.** Suite chạy ở code repo, CI không thấy spec repo (R6) → data phải đi cùng code. Đây là bước **sao chép**, không giải mã.
+
+- **a. Có `fixtures.yaml`** → chép `datasets[]` + `automation_prereq.mocks` sang `datatest/{id}_dynamic_fixtures.json` **nguyên giá trị** (YAML→JSON, runtime đọc bằng stdlib). Kèm `source_fixtures` (path) + **`source_sha256`** (hash nguồn — thứ duy nhất phát hiện bản sao cũ khi chạy lại). `<ký-tự>×N` và marker `$…` **giữ nguyên văn** — runtime xử (`Resolve Fixture Value` + `SeedRegistry`).
+- **b. Không có fixtures** → chuyển cột "Data Test" thành cùng file đó, mỗi `@id` → 1 object `field: value`. Prose không đủ → ghi "Data gaps", KHÔNG bịa (R1).
+- **c. Có `$db.query`/`$seed.*`** → kiểm `data_sources.yaml` có entry; thiếu → **DỪNG (R5)**. Chép marker vào khoá `bindings`.
+- **d. Đọc `automation_prereq`** → thiếu prereq theo bề mặt (`ui`: `base_url`/`auth` · `service`: `api`/`mocks`) → **DỪNG (R5)**.
+- **e. Hằng số môi trường** (base URL, endpoint, port, tên tài khoản): `[TBD]` cấm bê thẳng vào code. Tra 3 nguồn — (1) `data_sources.yaml` (phụ phẩm của registry seed: base URL, env prefix, tài khoản) · (2) `*_fixtures.yaml` slice cùng feature · (3) config code repo (`environment*.ts`, `proxy.conf*.json`, `application*.yml`) + DD "Stag environment". Tra ra → làm **default biến env** + comment nguồn `file:dòng`; cả 3 rỗng mới `[TBD]`. Secret luôn chỉ đọc env. Chỉ hỏi user phần đã tra hết vẫn rỗng.
+
+*Tên file output bắt buộc là `datatest/{id}_dynamic_fixtures.json`, chứa 2 khoá `datasets` + `bindings`.*
+
+**7. Xác định Object cần tạo.**
+- `ui`: Mỗi màn hình = 1 Page Object PascalCase.
+- `service`: Mỗi endpoint/operation = 1 Service Object. Cấm tự phát sinh Object ngoài spec (R3).
+
+**8. Quyết định chạy/hoãn (R10).** Phân nhóm nhạy cảm theo R10, áp dụng `deferred_run_policy` (`ask`/`run-all`/`defer-all`) và gán `run_state: run|pending` kèm `bucket` + `reason`.
+
+**8a2. Quét emoji trong expected.** `Then` chứa emoji (U+2600-27BF, U+1F300-1FAFF) → nghi bị chép từ wireframe (UI code cấm emoji, Rule 9). Đối chiếu mô tả text/i18n của DD: lệch → dừng báo user sửa `.feature`, KHÔNG tự bỏ emoji trong assert.
+
+**8b. Quét [TBD] (R11).** Trường hợp expected chứa `[TBD-spec]` hoặc `[TBD-data]` → gán `run_state: tbd` (không gắn tag `pending`).
+
+**9. Kế hoạch đồng bộ (R16).** Đối chiếu manifest cũ `datatest/{id}_gen_manifest.yaml` (nếu có) để phân chia case: giữ nguyên / sinh lại / thêm / xoá.
+
+**9b. Quản lý `gen_run_id`.** Kế thừa `gen_run_id` từ `results/{id}_robot_review.md` nếu có (để giữ vòng sửa), ngược lại tạo mới. Cấm dùng `generated_at` làm mốc tính round.
+
+**10. Kết quả bước 1.** In ra chat: qa_artifacts, code_repo_root, manual_testcase_path, surface_type, locator_source, gen_run_id, số case loại và kế hoạch đồng bộ (giữ nguyên/sinh lại/thêm/xoá).
+
+## 3. Đầu ra
+* **`datatest/{id}_dynamic_fixtures.json`** (luôn có): Chứa dữ liệu mồi (`datasets` + `bindings`).
+* **`datatest/{id}_gen_manifest.yaml`** (**luôn ghi** — chưa có thì tạo): Step 01 ghi các khoá `id`, `gen_run_id`, `generated_at`, `excluded_ids` (rỗng thì ghi `[]`), `r10_decisions`, và `cases[]` — mỗi case `id`, `run_state` (`run|pending|tbd`), `bucket`, `reason`, `sync_action` (`giữ nguyên` | `sinh lại` | `thêm` | `xoá`). Step 02/03 bổ sung `src_hash`, `last_gen_run`, `touched_files`, `locators` vào **cùng file** (merge, cấm rewrite).
+  > ⛔ Một chiều `manifest → [Tags]`. Sau Step 03, **tag là nguồn sự thật**; lệch nhau thì manifest sai → cập nhật manifest theo suite, không sửa suite theo manifest.
+* *Cấm ghi file rác ngoài whitelist (R6b).*
+
+## 4. Cổng ra
+1. **Resolved `{code_repo_root}`** (R6) đã chốt + in ra chat.
+2. **Đọc được đầy đủ input** (R5, R7), không lỗi drift mã `.md` ↔ `.feature`.
+3. **Mọi case đã phân loại `run_state`** (R10, R11).
+4. **Có kế hoạch đồng bộ tăng dần (R16)** khi chạy lại.
+
+**Next:** Đọc và thực hiện theo `./step-02-generate-resources.md`

package/skills/NTAPP/.agent/skills/NTAPP-qa-robot/steps/step-02-generate-resources.md

@@ -0,0 +1,75 @@
+# STEP 02: SINH PAGE/SERVICE RESOURCES (VARIABLES & KEYWORDS)
+
+> **Acting as:** [Agent Robot Generator](../agents/agent_robot_generator.md)
+> **Tuân thủ:** [Iron Rules](../principles/iron_rules.md) — R4, R7/R7s, R9, R16. Chi tiết: [Locator Strategy](../references/automation/auto_locator_strategy.md), [Robot Rules](../references/automation/auto_robot_rules.md) (§6 Generation Guidelines — **BẮT BUỘC đọc**), [Coding Convention](../references/automation/auto_coding_convention.md).
+> ⛔ Chỉ đọc step kế qua con trỏ Next ở CUỐI file — sau khi qua đủ cổng ra.
+
+**Sinh 1 folder + 2 file `.resource` cho mỗi Object mà Step 01 đã chốt.** `surface_type` quyết định nhánh: `ui` → §2 · `service` → §3. *(Unit hỗn hợp — TẬP `{ui, service}` → chạy **cả** §2 và §3, mỗi nhánh cho nhóm Object của nó.)*
+
+## 1. Input
+
+| Nguồn | Dùng để |
+|---|---|
+| Danh sách Object + `surface_type` + `locator_source` + `gen_run_id` | Từ [Step 01](step-01-parse.md) — quyết định sinh gì, lấy locator ở đâu, ghi manifest dưới mốc nào |
+| `ui_schema_{id}.json` | **Checklist độ phủ control** — KHÔNG phải nguồn locator |
+| `**/*.component.html` (template màn + component con) | Nguồn locator lớp 1-3 |
+| `**/*.component.ts` | Field/cột config-driven |
+| `**/i18n/*.json` | Text/aria/placeholder thật cho locator-theo-text |
+| `{id}_testspec.feature` | Tên control + chuỗi hiển thị mà `Then` nêu → suy ra control nào cần locator |
+| DD **per-unit** (`SCR-*`/`WGT-*`/`HUB-*`) | Fallback checklist control · schema hợp đồng. Thiếu thì bỏ qua, KHÔNG DỪNG |
+
+> **Có fixture `$db.query`/`$seed.*`?** BẮT BUỘC đọc [DB/Oracle Rules §10-§11](../references/automation/auto_db_oracle_rules.md) **trước khi** viết resolver ở §4. Step 01 chỉ *lập kế hoạch* tier; step này *viết code* nên phải theo §11.
+
+**Áp cho cả 2 nhánh — [R16] Variables.resource đã có từ run trước thì GIỮ, chỉ THÊM:** biến locator đã có → **giữ giá trị cũ**, KHÔNG đè bằng giá trị suy từ source lần này; biến `healed: true` trong `gen_manifest.yaml` → **tuyệt đối không đè**. Chỉ **thêm** biến cho control mới; locator trỏ control đã bị xoá khỏi màn → xoá kèm nêu trong báo cáo. Làm lại từ đầu chỉ khi user yêu cầu rõ hoặc file bị xoá tay ([R16 §16.3](../principles/iron_rules.md)).
+
+## 2. Nhánh `ui` — Page Object (Selenium)
+
+**a. Lấy locator theo `locator_source`:**
+- **`source`** (có code FE): Đào đủ 4 lớp theo [Locator Strategy §1-5](../references/automation/auto_locator_strategy.md). Cấm absolute XPath.
+- **`live-dom`** (không code FE): Chạy phiên soi DOM bằng Selenium (không phải test suite). Nếu thiếu driver/display -> DỪNG báo user, áp dụng fallback [§6.4](../references/automation/auto_locator_strategy.md).
+
+**b. Điều hướng (R9):**
+- Login và điều hướng sidebar đặt ở `Suite Setup` (1 lần/suite).
+- Mỗi Test Case chỉ thao tác element của màn hình và reset state bằng click đóng/mở lại modal (R4). Cấm dùng `Go To` / `Reload Page`.
+
+## 3. Nhánh `service` — Service Object (RequestsLibrary)
+
+**a. Cấu trúc (R4):** 1 endpoint/operation = `{Service}Variables.resource` (base_url, path, headers) + `{Service}Keywords.resource` (keyword request + keyword assert).
+
+**b. Quản lý phiên:** Khởi tạo session (`Create Session`) ở `Suite Setup`, lấy token gán header. Đóng session ở `Suite Teardown`.
+
+**c. Keyword request:** Nhận payload qua `[Arguments]` lấy từ `datatest/` (R8), cấm hardcode. Keyword assert tách riêng (assert status code, JSON path, DB, MSG).
+
+**d. Side-effect async:** Dùng `Wait Until Keyword Succeeds`, cấm dùng `Sleep` tĩnh (R7s).
+
+**e. Mock downstream:** Dựng stub theo `automation_prereq.api.mocks` trước khi chạy.
+
+## 4. Resolver dữ liệu mồi (Khi có `$db.query`/`$seed.*`)
+
+Viết resolver theo [DB/Oracle Rules §10-§11](../references/automation/auto_db_oracle_rules.md):
+1. Tách resolver đọc/hiển thị (đọc và cache) khỏi resolver tiêu thụ/tạo mới (KHÔNG cache).
+2. Tra DB tái dùng bản ghi un-consumed trước. Thiếu bao nhiêu seed bù bấy nhiêu.
+3. Tái dùng owner/container, cấm tạo owner mới ở mỗi case.
+4. Sinh keyword seed đầy đủ, cấm sử dụng stub (`SEED-TODO` / placeholder).
+
+## 5. Đầu ra yêu cầu
+- Thư mục tuân thủ [Framework Structure](../references/automation/auto_framework_structure.md).
+- File resource được tạo tại `actions/pageObject/` (ui) hoặc `actions/serviceObject/` (service).
+- **Whitelist `actions/common/` — đúng 5 file:** `BasePage` (helper UI + shell dùng chung mọi màn: toast/modal/alert) · `BaseTest` (cấp suite + wrapper mở browser) · `GlobalConstants` (timeout/env) · `SuiteFixtures` (Setup/Teardown + session + auth + kết nối DB) · `SeedRegistry` (seed/teardown data). Keyword dùng chung 2+ màn xếp vào đúng 1 ô; **cấm file thứ 6** trừ khi nêu lý do trong báo cáo.
+- Cập nhật import vào `configs/imports.resource`.
+- Manifest `datatest/{id}_gen_manifest.yaml` được cập nhật: ghi nhận locator mới (healed: false, giữ nguyên healed: true cũ) và append vào `touched_files` kèm `round` (lượt sinh đầu = `0`, vòng sửa sau review = số vòng đó).
+- File Python `.py` (nếu có) phải mang header quy định để pass pre-commit hook (R15).
+
+## 6. Cổng ra
+
+| Cổng | Rule | Pass khi |
+|---|---|---|
+| **Locator valid + Smart Wait** *(ui)* | R7 | Locator dò đúng nguồn, dùng explicit wait, cấm `Sleep` tĩnh. |
+| **Contract valid + no Sleep** *(service)* | R7s | Endpoint/field khớp Contract Map, cấm `Sleep` tĩnh. |
+| **Seed đầy đủ** | R15 | Keyword seed được sinh đầy đủ cho các `$seed.*`, không dùng stub. |
+| **Không headless / lách gate** | R12 | Quét code theo [gate_commands §3 và §4](../references/automation/auto_gate_commands.md), không chứa vi phạm. |
+
+**Next:**
+- **Lượt sinh mới** -> `./step-03-generate-suite.md`.
+- **Chỉ sửa resource** (sau review FAIL) -> Quay lại `./step-04-review-code.md` (chạy trực tiếp review cho touched files).
+- **Sửa cả file suite `.robot`** -> Chạy tiếp sang `./step-03-generate-suite.md`.

package/skills/NTAPP/.agent/skills/NTAPP-qa-robot/steps/step-03-generate-suite.md

@@ -0,0 +1,77 @@
+# STEP 03: SINH TEST SUITE
+
+> **Acting as:** [Agent Robot Generator](../agents/agent_robot_generator.md)
+> **Tuân thủ:** [Iron Rules](../principles/iron_rules.md) — R2, R3, R4, R8, R10, R11, R13/R14, R16. Chi tiết: [Robot Rules](../references/automation/auto_robot_rules.md) (§6 Suite & Imports — **BẮT BUỘC đọc**; §7 chọn oracle), [Framework Structure](../references/automation/auto_framework_structure.md), [Coding Convention §3](../references/automation/auto_coding_convention.md) (tên Test Case = `[mã KB-{id}-NN] - [mục tiêu]`, tag kebab-case).
+> ⛔ Chỉ đọc step kế qua con trỏ Next ở CUỐI file — sau khi qua đủ cổng ra.
+
+**Sinh `.robot` gọi các Keyword đã có từ Step 02.** `.robot` chỉ chứa logic nghiệp vụ — zero locator/URL/SQL/keyword-definition.
+
+## 1. Input
+Các `[Page|Service]Keywords.resource` từ [Step 02](step-02-generate-resources.md) · **`{qa_artifacts}/{id}/{id}_testspec.feature`** · manual testcase tại **`manual_testcase_path`** · `{id}_fixtures.yaml` + `datatest/` · `datatest/{id}_gen_manifest.yaml` từ [Step 01](step-01-parse.md) — `gen_run_id`, `excluded_ids`, `r10_decisions`, `cases[]`.
+
+⛔ **`.feature` là nguồn CHÍNH của step này, phải ĐỌC THÂN scenario — không chỉ grep tag.** Nó canonical khi lệch `.md` (Step 01 §2) và là **nguồn duy nhất** của nhãn phân loại (R3). Cụ thể: `When/And` → chuỗi step (§3b) · `Then` → assert (§3c-d, R13) · tag → `[Tags]`. Mọi chỗ dưới đây viết "cột Kết quả mong muốn" đọc là **`Then` của scenario cùng mã**; `.md` chỉ dùng khi `.feature` vắng (lane HUB legacy) hoặc để lấy cột `Exec`/`Data Test`.
+
+## 2. Tách file & đặt tên (CỨNG)
+
+- **1 file `.robot` cho mỗi unit màn/operation**: UI chia theo `@scr:<unit_id>`, Service chia theo `@svc:<unit_id>`. Cấm gộp chung.
+- **Tên file**: PascalCase theo tên màn/operation (vd: `LoginTest.robot`), cấm nhét ID slice/unit vào tên file. Mã unit đặt ở suite `Test Tags`; mã case `KB-{id}-NN` và các tag phân loại đặt ở per-test `[Tags]`.
+- **Suite Setup/Teardown chung**: Tách ra `actions/common/SuiteFixtures.resource`, cấm copy-paste block Setup vào từng file suite.
+
+## 3. Sinh Test Case
+
+**a. Đồng bộ tăng dần (R16):** Case giữ nguyên không đụng, chỉ viết lại đúng khối Test Case của case `sinh lại` hoặc `thêm`. Cấm xoá trắng file.
+
+**b. Map 1-1 theo hành vi (R2):** Mọi mệnh đề `When/And` phải được thực thi thật, cấm bỏ gesture (focus out, paste, Enter, double-click). **Gom chuỗi bước thao tác thành 1 keyword nghiệp vụ** (`Open Detail Tab    Sub-links`) thay vì bung từng dòng; lặp ở ≥3 case thì bắt buộc gom. Mức gom theo [robot §5](../references/automation/auto_robot_rules.md) — cấm gom cả case vào 1 keyword. **Assert giữ tường minh**: 1 assert / 1 mệnh đề `Then`, giá trị mong đợi qua tham số (`Sub Link Row Count Should Be    11`); cấm tên chung chung (`Should Be Complete` / `Valid` / `Correct`).
+
+**c. Chọn oracle (R11 · R13):** UI assert render/value; Service assert status code + JSON path. Đếm `k` mệnh đề trong `Then` → sinh **≥ k assert**. Mỗi nhãn `@oracle:` (`ui`/`api`/`db`/`log`/`msg`) phải có khối assert của tầng đó.
+
+**c2. Nhãn (R3):** Propagate nguyên văn `@block:` `@tech:` `@rule:` `@risk:` `@oracle:` của scenario gốc vào `[Tags]`, `@oracle` đủ **số lượng**; suite khai `Test Tags` mang `@scr:`/`@svc:`.
+
+**c3. Đếm số lượng (R14):** Vế mong muốn là hằng số kịch bản hoặc giá trị fixtures. Cấm `> 0` / `>= 1`, cấm so số vừa đo với chính nó.
+
+**c4. Test độc lập (R4 · R7b):** Mỗi test tự reset state bằng click (modal: đóng + mở lại). Để lưu lịch sử/audit, cấm xóa dữ liệu DB trong teardown; dữ liệu tạo ra mang định danh unique per-run và **bắt đầu bằng tiền tố `auto_`** (R7d) — sinh qua keyword dùng chung `Build Unique Name`, cấm test tự nối tên. Ngoại lệ: trường chỉ nhận số, ca biên độ dài. Tài nguyên precondition bị tiêu thụ: cấm resolve 1 lần rồi `Set Suite Variable`.
+
+**c5. Dynamic-binding (db §11):** Marker `$db.query` / `$seed.*` gọi resolver keyword thật từ Step 02. Marker chưa resolve ghi ở "Data gaps", cấm stub.
+
+**d. Toast/Error-path toast (R11):** Bắt buộc dùng phủ định `Page Should Not Contain` hoặc đếm `Get Element Count ... == 1`. Với toast biến mất nhanh, dùng MutationObserver trong JS lưu vào biến rồi assert.
+
+**e. Dữ liệu (R8):** Lấy từ fixtures, cấm hardcode. Escape khoảng trắng bằng `${SPACE}`, chuỗi dài biên `<ký-tự>×N` expand qua `Evaluate  "a" * N`.
+
+**f. Case pending/tbd (R10/R11):** Vẫn sinh Test Case, thêm tag `pending <bucket>` hoặc `tbd` và đặt bước đầu tiên là `Skip PENDING (<bucket>)` hoặc `Skip [TBD]`.
+
+**g. Manifest `datatest/{id}_gen_manifest.yaml` (R16):** Merge thay vì rewrite.
+- `cases`: Mỗi case có `src_hash` (hash dòng manual) + `last_gen_run` (gen_run_id hiện tại). Giữ nguyên entry case không đổi.
+- `touched_files`: Mỗi entry `path` + `round` (vòng sửa hiện tại; lượt sinh đầu = `0`). Gộp file resource Step 02 và file suite Step 03 đụng trong lượt, KHÔNG xoá entry vòng cũ.
+- `locators`: Giữ nguyên tuyệt đối các entry có `healed: true`.
+- `gen_run_id`: Giữ nguyên mốc Step 01, cấm dùng `generated_at` làm mốc round.
+
+## 4. Đầu ra yêu cầu
+- `[Screen]Test.robot` (chỉ chứa settings, variables và test cases).
+- `actions/common/SuiteFixtures.resource` (nếu tách).
+- Cập nhật manifest `datatest/{id}_gen_manifest.yaml` theo định dạng merge (R16).
+
+## 5. Cổng ra
+
+Yêu cầu sinh nằm ở §3. Cổng ra chỉ **4 phép kiểm cơ học** — phần ngữ nghĩa (oracle, seed, test độc lập, phân tầng POM) do [Step 04](./step-04-review-code.md) chấm, KHÔNG tự chấm lại ở đây.
+
+| # | Cổng | Rule | Pass khi |
+|---|---|---|---|
+| 1 | **Mã parity** | R3, R2 | Tập mã `.robot` = tập mã manual `automate` trừ `excluded_ids`. Ghi **số đếm** `A/B/C` + liệt kê **chỉ mã lệch** ([gate_commands §5](../references/automation/auto_gate_commands.md)); cấm in cả 2 danh sách mã. |
+| 2 | **Nhãn đủ** | R3 | Mỗi test có đủ 5 nhóm nhãn (§3c2), `@oracle` đủ số lượng, suite có `Test Tags`. |
+| 3 | **POM purity** | R4 | Suite không có `*** Keywords ***`, không locator/SQL/payload thô, không `[Template]`. |
+| 4 | **No Sleep, no jump URL** | R9, R9b, R7s, R12 | Không `Sleep`/`Go To`/`Reload Page` (kể cả `.py`/JS). Chỉ 1 `Open Browser` ở Suite Setup. **Miễn trừ R9b:** test mang tag `nav-by-url` được dùng `Go To`/`Reload Page` — kiểm ngược lại: mọi test có `nav-by-url` phải có `When` nêu rõ deep-link/reload/back-forward, và mọi lời gọi `Go To`/`Reload Page` phải nằm trong test mang tag đó. |
+| 5 | **Compile sạch** | R12 | `robot --dryrun --output NONE --log NONE --report NONE tests/` → **0 ERROR / 0 WARN**, không ghi file nào. Đỏ thì sửa tại đây, cấm sang Step 04/05. |
+| 6 | **Manifest tồn tại** | R16 | `datatest/{id}_gen_manifest.yaml` **có thật trên đĩa**, đủ `cases` (mọi mã có `src_hash` + `last_gen_run`) + `touched_files` (có `round`) + `excluded_ids` + `r10_decisions`. Thiếu → FAIL, ghi tại đây, cấm sang Step 04 — không có manifest thì mọi vòng review đều phải đọc `full`. |
+
+## 6. Cổng HITL trước khi sang Step 04
+
+Qua đủ 6 cổng §5 rồi mới tới cổng này. `review_gate`: `ask` (default) · `auto` (đi thẳng) · `skip` (bỏ review, sang Step 05).
+
+`ask` → **DỪNG hỏi user 1 câu** có chạy review không, kèm số case + số file trong `touched_files`:
+
+- **Có** → đọc `./step-04-review-code.md`.
+- **Không** → ghi `review_skipped: <lý do user>` vào `datatest/{id}_gen_manifest.yaml`, nêu trong báo cáo, đọc thẳng `./step-05-execute-and-analyze-logs.md`.
+
+⛔ Chưa có trả lời thì KHÔNG đọc step kế.
+
+**Next:** Theo lựa chọn ở §6.