@trungtamcongnghedigital/vsaf 1.0.0

package/skills/NTAPP/.agent/skills/NTAPP-qa-robot/agents/agent_robot_reviewer.md

@@ -0,0 +1,27 @@
+# SYSTEM INSTRUCTION: NGƯỜI KIỂM CODE ROBOT (ĐỘC LẬP)
+
+## [B] - BACKGROUND
+Bạn là người kiểm code automation, độc lập với người sinh code. Việc của bạn là **bắt lỗi của người sinh code**. Suite "trông đúng" mà không kiểm đúng thứ nó phải kiểm là nợ, không phải thành quả. Suite đỏ oan cũng là nợ: team sẽ tắt nó đi.
+
+## [M] - MISSION
+Đọc bộ code Robot vừa sinh (Step 02 + 03) **trước khi chạy test**, đối chiếu với `.feature` + fixtures + [Iron Rules](../principles/iron_rules.md), chấm theo **6 Lõi** ở [step-04](../steps/step-04-review-code.md) rồi kết luận `PASS`/`FAIL`. Mục tiêu: chặn **test xanh nhưng không kiểm được gì** (assert vỏ rỗng, thiếu mệnh đề, thiếu tầng oracle, seed thiếu, teardown xoá sai bản ghi) ngay lúc sinh code, thay vì phát hiện sau một vòng chạy tốn thời gian.
+
+## [A] - ACTIONS
+1. **KHÔNG sửa code.** Chỉ ghi vi phạm kèm `file:dòng` + ảnh hưởng thật + cách sửa. Người sinh code mới là người sửa.
+2. **Chấm đúng 6 Lõi, không chấm gì ngoài đó** — đặt tên, cấu trúc file, `Sleep`, headless, import, credential… đã bỏ khỏi phạm vi review.
+3. **Lõi 1, 2, 4 chấm bằng MỘT lượt đọc/case:** mở case 1 lần, đặt cạnh nhau `When`/`Then` của scenario cùng mã ⟷ thân Test Case ⟷ thân keyword nó gọi, trả lời cả 3 lõi. Đọc 3 lượt riêng là lý do phải chấm mẫu rồi để nợ lọt sang vòng sau.
+4. **Nghi ngờ mặc định.** Mọi assert chung chung, mọi keyword tổng, mọi seed 1-bản-ghi đều đáng nghi cho tới khi đối chiếu `.feature` chứng minh ngược lại.
+5. **Bằng chứng, không cảm nhận.** "Đã xem, ổn" trống trơn = chưa review → `UNVERIFIED` → `FAIL`. Đọc chưa hết phạm vi được giao thì nói rõ, không ghi đạt.
+6. **Thấy chữ giống dấu hiệu sai chưa chắc là lỗi** — đọc cả dòng + ngữ cảnh mới được chấm (chữ sau `#`, tên keyword sát lề, chuỗi thông báo thì không tính).
+7. **Rule tính theo VIỆC CODE LÀM, không theo chữ nó viết.** Assert bị bọc trong lệnh bắt lỗi, expected lấy từ i18n của sản phẩm thay vì `.feature`, `@oracle:api` mà chỉ assert UI → vi phạm Lõi 2, không được ghi đạt.
+8. **Thí nghiệm Lõi 4:** tự hỏi *"sản phẩm hỏng đúng điểm case này nhắm tới thì test có đỏ không?"*. Trả lời "không" = test vô dụng = vi phạm.
+9. **Không phân mức nặng nhẹ.** Mọi vi phạm trong 6 lõi đều phải sửa. Đừng thổi phồng chuyện nhỏ (mỗi vòng review thừa ăn mất 1 trong 2 vòng sửa), cũng đừng bỏ qua chuyện nhỏ.
+10. **Không nới rule.** Rule của skill là ràng buộc cứng (R12); không tự cho ngoại lệ vì "chạy được là được".
+11. **Đạt thì nói đạt.** 0 vi phạm là kết quả hợp lệ: nêu lý do đạt kèm bằng chứng, KHÔNG bới lỗi hình thức để review cho có.
+
+## [D] - DELIVERABLES
+1. `results/{id}_robot_review.md` theo đúng template [step-04 §5](../steps/step-04-review-code.md) — 3 phần: **Tóm tắt kết quả** (1-2 câu) · **Danh sách vi phạm theo 6 Lõi** (chỉ lõi FAIL; mỗi vi phạm có Vị trí / Nguyên nhân + ảnh hưởng / Cách sửa đề xuất) · **Nhật ký các vòng sửa**. Không kẻ bảng liệt kê chỗ đạt.
+2. ⛔ **Đúng MỘT file, không có file thứ hai.** Không tách `.yaml` trạng thái, không thêm frontmatter. Ba giá trị `verdict` · `round` · `gen_run_id` đặt ở **dòng trạng thái** ngay dưới tiêu đề; `gen_run_id` là mốc phân biệt lượt sinh code — thiếu nó thì `round` tính sai và trần 2 vòng thành vô nghĩa.
+
+## [🚫] - ĐIỀU LÀM BẢN REVIEW BỊ LOẠI
+> 6 điều: [step-04 §6](../steps/step-04-review-code.md) — nhận xét không kèm `file:dòng` · đoán qua tên keyword chưa đọc thân · ghi đạt khi mới đọc mẫu vài case · chấm vi phạm mà chưa đọc ngữ cảnh · chẻ 1 vấn đề thành nhiều vi phạm · tự sửa code thay vì review.

package/skills/NTAPP/.agent/skills/NTAPP-qa-robot/principles/iron_rules.md

@@ -0,0 +1,123 @@
+# IRON RULES — Quy tắc bất biến của workflow NTAPP QA Robot
+
+## Áp dụng theo `surface_type`
+* **`ui`** (Chrome, `@scr`, có `ui_schema`): Selenium POM, áp dụng R7 và R9 đầy đủ.
+* **`service`** (no-UI, `@svc`, không `ui_schema`): RequestsLibrary POM, R7/R9 thay bằng phiên bản service.
+* **Cả hai:** R1-R6, R7d, R8, R10-R16.
+
+---
+
+## R1. ZERO-FABRICATION (Cấm bịa dữ liệu)
+* Chỉ dùng 3 input tại `{qa_artifacts}/{id}/`: `.feature` (nguồn chính sinh script), `fixtures.yaml` và manual testcase. Expected chỉ lấy từ `.feature`.
+* Cấm tự bịa dữ liệu, URL, endpoint hoặc expected. Thiếu thông tin -> để `[TBD]` và dừng báo user.
+* **Hằng số môi trường** (URL/endpoint/port/tên tài khoản — KHÔNG áp cho expected): lấy thêm từ `data_sources.yaml`, fixtures slice cùng feature, config code repo ([step-01 §2.6e](../steps/step-01-parse.md)). `[TBD]` chỉ hợp lệ sau khi tra hết 3 nguồn.
+
+## R2. MAP 1-1 (Cấm tóm tắt / bỏ scenario)
+* Mỗi scenario automate map 1-1 thành 1 Test Case. Cấm nhồi 2 scenario vào 1 test.
+* Cấm bỏ UI gesture (focus out, blur, tab out, paste, Enter, double-click) — mọi gesture phải được thực thi thật.
+* **Map 1-1 tính theo hành vi được thực thi, không theo số dòng trong `.robot`.** Gom chuỗi micro-step thành 1 keyword nghiệp vụ là ĐÚNG; lặp ở ≥3 case thì BẮT BUỘC gom. Kiểm bằng đọc thân keyword.
+* Mức gom theo [robot §5](../references/automation/auto_robot_rules.md) (1 keyword = 1 trách nhiệm) — cấm gom cả case vào 1 keyword. Chỉ gom bước thao tác; **assert giữ tường minh**: giá trị mong đợi truyền qua tham số, cấm assert tên chung chung (`Should Be Complete` / `Valid` / `Correct`).
+
+## R3. TRACEABILITY (Truy vết)
+* Mã Test Case (`KB-{id}-NN`) ở tag và tên phải khớp 1-1 với manual.
+* Propagate nguyên văn nhãn phân loại: `@block:*`, `@tech:*`, `@rule:*`, `@risk:*`, `@oracle:*`.
+* Tên Page Object / Service Object phải khớp tài liệu L2/L3 / Contract Map, cấm tự phát sinh.
+
+## R4. POM & QUALITY GATE (Bắt buộc Object Model)
+* File `.robot` chỉ chứa Settings, Variables (hằng số suite), và Test Cases. **TUYỆT ĐỐI KHÔNG chứa `*** Keywords ***`** hoặc locator/URL/SQL thô. Đưa hết về `.resource`.
+* Reset state vô điều kiện sau mỗi test case: đóng/mở lại modal bằng click, điều hướng lại từ menu. Cấm dùng `Go To` / `Reload Page` để reset.
+
+## R5. MISSING-INPUT HANDLING
+* Thiếu file input (chưa approve/không readable) -> DỪNG ngay, cấm bịa mock, báo rõ explicit path file thiếu cho user.
+* **Trước MỌI câu hỏi user về data/môi trường: BẮT BUỘC đọc `{qa_artifacts}/data_sources.yaml`** (+ fixtures slice cùng feature + config code repo) rồi mới lập danh sách thiếu. Hỏi thứ file đó đã cấp = vi phạm R5.
+
+## R6. SINGLE-SOURCE PATH
+* Ghi code relative tại `{code_repo_root}` (cấm ghi ngoài dự án/file tạm).
+* File resource đặt tại `actions/pageObject/{Page}/` (ui) hoặc `actions/serviceObject/{Service}/` (service).
+
+### R6b. CẤM FILE RÁC
+* Cấm ghi file ra ngoài dự án (cấm `/tmp`, `AppData`, scratchpad...).
+* Cấm sinh file tạm. So sánh mã parity (R3) thực hiện trực tiếp trong memory.
+
+## R7. LOCATOR STRATEGY & WAITS (UI)
+* Locator dò từ code FE tĩnh. Cấm absolute XPath. Tên biến dạng `${LOAI_ELEMENT}_${CHUC_NANG}`.
+* Dùng Smart Wait, cấm `Sleep` tĩnh, cấm trộn implicit wait với explicit wait.
+* **Self-Healing:** Dò lại locator tĩnh, ghi đè Variables, retry tối đa 3 lần. Ghi manifest `healed: true`.
+* **Biến thể no-source (`live-dom`):** Soi DOM ứng dụng ở Step 02 trước khi generate, cấm suy DOM runtime lúc chạy test (trừ self-heal).
+
+### 5 Stopping Errors (Dừng pipeline ngay):
+1. `id` không có trong WBS/spec.
+2. Spec L2/L3/UX chưa approve.
+3. Drift `.md` ↔ `.feature` -> lấy theo `.feature` và dừng báo user.
+4. Locator không tìm được / không self-heal được.
+5. Assertion fail do app có bug thật -> DỪNG NGAY, cấm retry/self-heal, cấm sửa test để né bug.
+
+### R7s. Biến thể SERVICE (no-UI)
+* Định vị qua Contract (endpoint, path, schema, error code).
+* Chờ async qua `Wait Until Keyword Succeeds`, cấm dùng `Sleep` tĩnh.
+* FAIL do transient -> retry ≤3; FAIL do contract/assert -> bug thật, DỪNG ngay.
+
+### R7b. MULTI-CONNECTION RESOLUTION
+* Mở kết nối ở Suite Setup, đóng ở Suite Teardown.
+* DB query select rỗng -> dừng test. Resolver dynamic data phải reuse trước seed sau, seed đủ số lượng.
+* Tên bản ghi test trên môi trường dùng chung phải unique per-run (`$uuid` / `$timestamp`).
+
+### R7d. TIỀN TỐ `auto_` (áp cho cả `ui` và `service`)
+* Định danh **kiểu chuỗi** automation ghi vào hệ thống dùng chung phải **BẮT ĐẦU** bằng `auto_` (tiền tố, không phải hậu tố). Dạng `auto_<nhãn>_<run-marker>_<uuid8>` → dọn môi trường bằng một mệnh đề `LIKE 'auto\_%'`. Override qua `AUTO_DATA_PREFIX`.
+* **Ngoại lệ:** (1) trường chỉ nhận số — giữ định dạng số, unique bằng phần số ngẫu nhiên; (2) ca biên độ dài (`<char>×N`) — ghi lý do miễn trừ vào manifest.
+* **Không phải ngoại lệ:** payload SQL-like / XSS / khoảng trắng VẪN gắn tiền tố (payload còn nguyên trong chuỗi).
+
+## R8. DATA-DRIVEN & DYNAMIC RESOLUTION
+* Lấy dữ liệu từ fixtures, cấm hardcode.
+* 1 case = 1 Test Case tường minh, cấm dùng `[Template]`. **"Tường minh" = 1 test cho 1 mã case (giữ tag + traceability), KHÔNG có nghĩa phải inline từng bước** — thân test gọi keyword nghiệp vụ với data của case đó; chuỗi bước đã có keyword thì tái dùng.
+* Ký tự biên `<char>×N` expand qua `Evaluate  "char" * N`.
+
+## R9. NAV-BY-CLICK (Cấm `Go To` / `Reload Page` UI)
+* Cấm `Go To` / `Reload Page` như **đường tắt điều hướng**. Chỉ dùng `Open Browser` trang login 1 lần ở Suite Setup.
+* Di chuyển tới màn qua Click. Reset state bằng click đóng/mở lại modal.
+
+### R9b. NGOẠI LỆ — khi chính hành vi được kiểm là điều hướng URL
+Scenario mà **đối tượng kiểm thử chính là URL/reload** thì `Go To` / `Reload Page` là *bước nghiệp vụ bắt buộc*, không phải lách rule — được dùng. Ba nhóm hợp lệ:
+1. **Deep-link**: `.feature` yêu cầu mở URL kèm queryParam để kiểm prefill / hydrate filter / nhảy trang.
+2. **Tải lại trang**: ca kiểm giữ trạng thái sau F5 (vd "giữ bộ lọc sau khi tải lại trang").
+3. **Lịch sử trình duyệt**: ca kiểm back/forward giữ state.
+
+Điều kiện áp dụng — thiếu 1 trong 3 là quay về cấm:
+* Mệnh đề `When` của scenario nêu rõ mở URL / reload / back-forward. Suy diễn "cho nhanh" không tính.
+* Chỉ dùng đúng ở bước tái hiện hành vi đó, KHÔNG dùng để tới màn hay reset state ở bước khác trong cùng test.
+* Test mang tag `nav-by-url` để gate cơ học lọc ra và người đọc biết đây là ngoại lệ có chủ đích.
+
+Ngoài 3 nhóm trên: cấm như cũ. Cần tới màn thì click.
+
+## R10. DEFERRED-RUN SAFETY GATE
+* Phân nhóm nhạy cảm (`timeout`, `mock`, `security`, `destructive`) -> Hỏi user **từng bucket một**: mỗi bucket = 1 câu hỏi riêng (chạy / hoãn), chờ trả lời xong mới hỏi bucket kế. CẤM gộp nhiều bucket vào 1 câu, CẤM gộp bucket với câu hỏi khác (env, prereq…) -> Nếu chọn hoãn -> gắn tag `pending <bucket>`, đặt bước đầu là `Skip PENDING (<bucket>)`.
+* `deferred_run_policy`: `ask` (default — hỏi từng bucket một) · `run-all` / `defer-all` (non-interactive, không hỏi). Mọi mode ghi quyết định vào `run_state` + `r10_decisions`.
+
+## R11. ANTI-STUB / ORACLE-FIDELITY
+* Expected/Assert lấy duy nhất từ `.feature`, cấm dùng expected từ code implementation. Cấm dùng assert baseline.
+* Executor nhận `${expected}` phải tiêu thụ trong assert.
+* Mỗi `@oracle` tag phải assert đầy đủ (ui, api, db, msg, log).
+* Dòng chứa `[TBD-spec/data]` -> gán `Skip [TBD]` + tag `tbd`, cấm fake pass.
+
+## R12. RULE SKILL > GIẢI PHÁP RUNTIME (Cấm lách)
+* Rule skill là ràng buộc **CỨNG**. Gặp trở ngại runtime (thiếu display/driver/proxy) -> DỪNG báo user + đề xuất trong khuôn khổ rule, cấm tự lách. Chỉ vượt rule khi user yêu cầu rõ bằng lời.
+* **CẤM headless mọi hình thức:** `--headless`, `${HEADLESS}`, env var, `Set Variable If ... headless`, `options.add_argument`. Browser giữ HEADED + `Maximize Browser Window`. Môi trường không có desktop (viewport 0px -> `element has zero size`) -> DỪNG báo user chạy máy có desktop, KHÔNG bật headless để "sửa".
+* Việc bị cấm ở R7/R9 thì cấm ở **mọi ngôn ngữ**: `time.sleep`/`Thread.sleep`/`implicitly_wait`, `driver.get`/`window.location`/`history.back`, hoặc gọi keyword bằng biến để giấu tên. *(Ngoại lệ R9b áp cho cả mục này — ca deep-link/reload/back-forward được dùng đúng lệnh điều hướng của nó.)*
+* Gate cơ học ở Step 02 + Step 03: quét theo [gate_commands §3-§4](../references/automation/auto_gate_commands.md).
+
+## R13. COMPOUND ORACLE
+* 1 mệnh đề expected = 1 assert. Đếm `k` mệnh đề expected -> sinh `≥k` assert. Miễn trừ style thị giác.
+
+## R14. VOLUME/COUNT FIDELITY
+* Ca grid/list phải bảo đảm đủ N bản ghi khả dụng, assert theo COUNT thực tế.
+* Cấm assert tautology (so actual với chính actual). Vế kỳ vọng phải là hằng số hoặc fixture.
+
+## R15. SEED CODE ROBUST
+* Resolver phải query reuse trước, seed sau, honor count.
+* File `.py` sinh ra phải chứa header hợp lệ: `# id: <ID> | dd_version: vN` ở 10 dòng đầu.
+
+## R16. SINH LẠI THEO TỪNG CASE
+* Ghi manifest `datatest/{id}_gen_manifest.yaml` — **file trạng thái duy nhất** của skill (schema: `id`, `gen_run_id`, `generated_at`, `excluded_ids`, `r10_decisions`, `touched_files` (`path`, `round` — lượt sinh đầu = `0`), `cases` (`run_state`, `bucket`, `reason`, `sync_action`, `src_hash`, `last_gen_run`), `locators` (`healed: true`)). Step 01 tạo, Step 02/03 merge thêm — cấm rewrite, cấm tách file thứ hai.
+* So sánh `src_hash` và `run_state` để phân loại: Giữ nguyên / Sinh lại / Thêm / Xoá.
+* Giữ nguyên healed locator. Cấm xoá file suite rồi ghi lại từ đầu.
+* Báo cáo thống kê: `giữ nguyên: k · sinh lại: m · thêm: n · xoá: p`.

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

@@ -0,0 +1,53 @@
+# QUY CHUẨN NAMING & CODING CONVENTIONS
+
+## 1. Ngôn ngữ & Mã nguồn chung (General Rules)
+- **Ngôn ngữ**: Sử dụng tiếng Anh cho toàn bộ code và comment (trừ test cases name có thể phụ thuộc vào test case name của Manual).
+- **Tránh code thừa**: Phần code bị comment không sử dụng nên xóa, nếu muốn giữ lại phải comment rõ ràng mục đích.
+- **Dọn dẹp**: Remove các variables, keywords đã khai báo nhưng không sử dụng.
+
+## 2. Thư mục và File (Files & Folders)
+- **Đặt tên theo page hoặc chức năng**: Ví dụ: `Login`, `HomePage`, `ActivePin`.
+
+- **Tên File**: Viết hoa chữ cái đầu tiên, các chữ còn lại là chữ thường. Các từ được viết liền nhau (PascalCase). Đuôi file: `.resource` cho Variables/Keywords, `.robot` cho Test Suite.
+  - Ví dụ: `LoginKeywords.resource`, `LoginVariables.resource`, `LoginTest.robot`.
+
+## 3. Test Cases & Test Suites
+- **Tên Test Suite**: (Định nghĩa trong phần `*** Settings ***`) Phải viết hoa chữ cái đầu mỗi từ (Title Case), mô tả cụ thể module/tính năng đang test. VD: `Login User Authentication`.
+- **Tên Test Case**: Cấu trúc bắt buộc: [Mã manual `KB-{id}-NN`] - [Mục tiêu test] (không có phần tiền tố tên chức năng). **Số/mã lấy NGUYÊN VĂN từ mã manual — KHÔNG tự đánh số thứ tự riêng** (mã auto phải trùng mã manual, R3). Phần mục tiêu test viết hoa chữ cái đầu tiên (nên bắt đầu bằng từ khóa mô tả kiểm thử như `Kiểm tra`, `Verify`). VD: `KB-SLICE-01-03 - Kiểm tra đăng nhập thành công với thông tin hợp lệ`.
+- **Tags (`[Tags]`)**: Viết thường kebab-case/snake_case cho tag phân loại (vd `smoke`, `regression-test`, `login_flow`). **BẮT BUỘC** mỗi Test Case automate mang **mã manual nguyên văn** `KB-{id}-NN` **+ propagate nguyên văn `@block:*` / `@tech:*` / `@rule:*` / `@risk:*` / `@oracle:*`** của scenario gốc (`@oracle:*` mang **đủ số lượng** khi scenario có nhiều tầng) — các gate cơ học lọc case theo `@rule:*` và `@oracle:*` (R3). VD: `[Tags]    KB-SLICE-06-02    @block:ui    @tech:BVA    @rule:grid-base    @risk:P2    @oracle:ui    @oracle:db` (giữ nguyên độ pad `NN` của mã manual — `-02` ≠ `-002`; `@scr:*`/`@svc:*` đặt ở suite-level `Test Tags`, không per-test).
+
+## 4. Keywords
+- **Nguyên tắc tái sử dụng**: Khi viết keyword mới, xem lại các keyword hiện có xem đã có hay có thể tái sử dụng một phần keyword khác không.
+- **Xác nhận hành động ≠ assert oracle** (đọc kèm [structure §2.1](./auto_framework_structure.md) — hai chỗ này nói về hai thứ khác nhau, đừng chấm ngược):
+  - Keyword thao tác **được và nên** chờ xác nhận thao tác đã xảy ra, bằng **`Wait Until *`** trên dấu hiệu kỹ thuật (trang đích đã render, overlay loading đã tan, nút đã enable) — vd `Click Button Login` chờ tới khi form login biến mất. Đây là **chống race**, không phải verify kết quả nghiệp vụ.
+  - Keyword thao tác **KHÔNG** assert `Kết quả mong muốn` của case (`Should Be Equal`, so message/giá trị/count) — thứ đó trả về hoặc để keyword **verify riêng** (`<Field> Value Should Be`) làm, và Test Case là nơi gọi. Nhồi oracle của case vào keyword thao tác làm `${expected}` biến mất khỏi tầng test → vi phạm [R11 — anti-stub: `${expected}` phải được tiêu thụ trong assert](../../principles/iron_rules.md).
+- **Tên Keyword**: Được đặt tên theo chức năng của keyword (V + N/N phrase).
+  - Ví dụ: `Add...`, `Login...`, `Check...`, `Get...`, `Verify...`.
+  - Những hàm nào trả về Boolean thì thêm tiền tố Is (ví dụ: Is Login Form Displayed).
+  - Viết hoa các chữ cái đầu tiên, các chữ còn lại là chữ thường. Các từ được viết cách nhau bởi 1 SPACE (Title Case).
+  - Ví dụ: `Get Customer Infomation`, `Register Account`, `Access Homepage`.
+- **CẤM "gate-breaking name"** — tên keyword (và comment) KHÔNG được chứa cụm token bị cấm: `Sleep`, `Go To`, `Reload Page`. Phép kiểm R7/R9 ([gate_commands §2](./auto_gate_commands.md)) chỉ tính **dòng gọi** keyword, nên tên như `Sleep Until Ready` / `Verify User Go To Dashboard` **không** bị chấm là vi phạm điều hướng — nhưng người kiểm sau cứ phải dừng lại đọc rồi loại nó ra, nên **phải đổi tên** (vd `Wait Until Ready`, `Verify Dashboard Opened`).
+- **Độ dài Keyword**: Chứa tối đa 20 steps (nếu nhiều hơn nên chia nhỏ keyword).
+- **CẤM `[Documentation]`** ở Test Case và Keyword (header `Documentation` mức `*** Settings ***` vẫn giữ). Ý nghĩa nằm ở tên keyword / tên Test Case — chưa rõ thì đổi tên. Sửa file cũ → xoá kèm dòng nối `...`.
+- **CẤM comment `#`**: không emit dòng comment nào trong code sinh tự động — không chú thích mô tả, không banner phân mục (`# ==== ... ====`). Cần diễn giải thì viết vào `Documentation` mức `*** Settings ***`.
+
+## 5. Biến (Variables) & Đối số (Arguments)
+- **Tên ngắn gọn, gắn với đối tượng** (ý nghĩa + mục đích sử dụng), từ dài nối bằng snake_case.
+- **Các ký hiệu Prefix**: `$` (Scalar), `@` (List), `&` (Dictionary) viết thường.
+- **Biến toàn cục (Global Variables) & Environment Variables**: Ký hiệu `%` và nội dung viết hoa tất cả các chữ cái (SCREAMING_SNAKE_CASE).
+  - Ví dụ: `%{PATH}`, `${BROWSER}`, `${BASE_URL}`.
+- **Biến Locator**: theo [locator_strategy §4](./auto_locator_strategy.md#4-chuẩn-đặt-tên-biến-locator) — **UPPER_SNAKE_CASE** `${LOAI_ELEMENT}_${CHUC_NANG}` (`${BTN_LOGIN}`, `${INPUT_USERNAME}`, `${LBL_ERROR_MESSAGE}`). Quy tắc snake_case chữ thường ở trên chỉ áp cho biến/đối số thường, KHÔNG áp cho locator.
+- **Biến tích hợp ngoại lệ (Built-in variables)**: Chú ý sử dụng đúng chuẩn: `${True}`, `${False}`, `${None}`, `${EMPTY}`, `${SPACE}`, `${SUITE NAME}`, `${TEST_NAME}`, `${TEST STATUS}`.
+
+## 6. Coding Convention Cụ Thể (Syntax Rules)
+- **Khoảng cách (Spacing)**:
+  - BẮT BUỘC sử dụng ít nhất 2 khoảng trắng (spaces) hoặc 1 tab (khuyến nghị dùng 4 spaces) để phân tách giữa các khai báo (biến, keywords, arguments, tham số locator).
+  - TUYỆT ĐỐI không sử dụng 1 khoảng trắng duy nhất để ngăn cách, vì Robot Framework sẽ coi đó là một chuỗi liền mạch.
+  - Không nên: `${btn_login} css:button` (sai vì chỉ có 1 space).
+  - **Nên dùng**: `${btn_login}    css:button` (4 spaces).
+- **IF Conditions**:
+  - Không nên: `IF '${is_checked}'=='${True}'` ➔ **Nên dùng**: `IF ${is_checked}`
+  - Không nên: `IF '${is_checked}'=='${False}'` ➔ **Nên dùng**: `IF not ${is_checked}`
+- **Gán biến (Assignment)**:
+  - Không dùng dấu `=` sát biến.
+  - Không nên: `${OTP}=    Set Variable    ${get_otp}` ➔ **Nên dùng**: `${OTP}    Set Variable    ${get_otp}`

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

@@ -0,0 +1,150 @@
+# QUY TẮC ORACLE DATABASE (DB VERIFICATION RULES)
+
+Áp dụng khi scenario có tag `@oracle:db` + dòng `Then DB: ...` (vd "chỉ 1 composite_requests được tạo", "lưu đủ 100 ký tự"). Mục tiêu: thay placeholder `Verify DB` (chỉ `Log`) bằng query + assert thật. Map 1-1: mỗi dòng `DB: ...` → 1 keyword DB.
+
+## 1. Vị trí trong POM — KHÔNG tách file DB riêng
+Theo [auto_framework_structure.md §2.1](./auto_framework_structure.md) (common = function dùng chung; GlobalConstants chứa "Database config"):
+
+| Tầng | Nội dung | Đặt ở |
+|---|---|---|
+| **Hạ tầng chung** | `Library DatabaseLibrary`; keyword `Connect To Database` / `Disconnect From Database` (tên keyword **tiếng Anh** — [auto_robot_rules §4](./auto_robot_rules.md)) | `actions/common/BasePage.resource` (chung như SeleniumLibrary) |
+| **Tham số kết nối** | host/port/db/user/pass | `actions/common/GlobalConstants.resource` |
+| **Verify DB theo CHỨC NĂNG** | SQL + assert riêng từng màn/operation (`composite_requests`, `transfers`...) | *(ui)* viết trong `<Page>Keywords.resource`, cạnh keyword verify UI · *(service)* viết trong `<Service>Keywords.resource`, cạnh keyword verify response (KHÔNG có verify UI) |
+| Connect / Disconnect | gọi ở Suite Setup / Suite Teardown | `tests/*.robot` |
+
+→ Hạ tầng connect viết 1 lần ở BasePage, dùng lại. Check DB nghiệp vụ nằm **cùng file Page** với keyword UI của màn đó. Test Suite `.robot` chỉ gọi high-level keyword, KHÔNG chứa SQL (đồng nhất R4 — `.robot` cấm kỹ thuật DOM/locator, áp tương tự cho SQL).
+
+## 2. Khi nào wire — quyết định theo REGISTRY, không phán đoán env lúc generate
+Wire khi `@oracle:db` (KHÔNG phải `@manual-verify`) **và** `source_id` liên quan có khai báo trong `data_sources.yaml`. Env var chỉ tồn tại lúc **RUN** — generator CẤM lấy "lúc generate chưa thấy env" làm lý do bỏ resolver rồi thay bằng biến env đặt tay:
+
+- **Registry CÓ source** (`db:` env_prefix / `create_api`) → PHẢI sinh resolver thật đọc `${<env_prefix>_*}` theo pattern **Tier 0 → Tier 1: check DB tìm bản ghi có sẵn trước, không có thì seed qua API** ([iron_rules R7b](../../principles/iron_rules.md)). Runtime thiếu env → resolver tự fail rõ ràng (`Should Not Be Empty ... msg=cần env <PREFIX>_*`) đúng case đó — không kéo đổ case khác.
+- **Registry KHÔNG có source** → giữ stub `Log` + ghi chú "thiếu registry entry" ([iron_rules](../../principles/iron_rules.md) R1 cấm bịa, R5 thiếu input thì dừng).
+- **Biến env đặt tay** (vd `<ENV_PREFIX>_*_SUBID`) chỉ được sinh làm **override tùy chọn** (user set thì tôn trọng — check trước rồi mới resolve). TUYỆT ĐỐI không để env tay là đường lấy data DUY NHẤT khi registry đã có nguồn.
+- **Field `[TBD]` trong body `create_api`** (registry thiếu giá trị, không có cách tra) → vẫn sinh resolver, đọc field đó từ env `${<env_prefix>_<FIELD>}` + liệt kê vào mục "Data gaps" của generation report — KHÔNG âm thầm bỏ cả operation.
+
+TUYỆT ĐỐI không hardcode connection để "chạy cho có".
+
+## 3. Thư viện + driver
+Driver theo **DB thật** khai ở `data_sources.yaml` (`<source>.db`) hoặc user cung cấp — **CẤM mặc định cứng Postgres**. `${DB_API}` để `[TBD]`, user set qua env `<ENV_PREFIX>_DB_API` (`psycopg2` Postgres · `pymysql` MySQL/MariaDB · `oracledb` Oracle). Cài driver tương ứng.
+```
+pip install robotframework-databaselibrary
+pip install <driver>   # theo DB thật: psycopg2-binary | pymysql | oracledb
+```
+
+## 4. Connection — KHÔNG hardcode (R1)
+Trong `GlobalConstants.resource`, đọc từ env var (SCREAMING_SNAKE_CASE, giống `${BASE_URL}` — [coding_convention §5](./auto_coding_convention.md)):
+```robotframework
+${DB_API}     %{<ENV_PREFIX>_DB_API=[TBD]}   # theo DB thật, KHÔNG mặc định Postgres
+${DB_NAME}    %{<ENV_PREFIX>_DB_NAME=[TBD]}
+${DB_USER}    %{<ENV_PREFIX>_DB_USER=[TBD]}
+${DB_PASS}    %{<ENV_PREFIX>_DB_PASS=[TBD]}
+${DB_HOST}    %{<ENV_PREFIX>_DB_HOST=[TBD]}
+${DB_PORT}    %{<ENV_PREFIX>_DB_PORT=[TBD]}   # theo DB thật: 5432 Postgres · 3306 MySQL · 1521 Oracle — KHÔNG mặc định cứng (§3)
+```
+- Credential CẤM commit git — chỉ truyền qua env lúc chạy.
+- Connect 1 lần ở **Suite Setup**, disconnect ở **Suite Teardown** — KHÔNG connect/disconnect mỗi test case.
+
+## 5. Query — luôn parameterize
+Dùng tham số `%s` (hoặc `:name`) + truyền value qua **`parameters=${list}`** (tạo bằng `Create List`), CẤM nối chuỗi vào SQL. ⚠️ **CẤM truyền value positional** (`Query  SELECT ... %s  ${name}`) — arg thứ 2 của `Query` là `sansTran`, không phải param → `%s` không bind → lỗi SQL `near '%s'`.
+
+## 6. Template
+
+**Hạ tầng — thêm vào `actions/common/BasePage.resource`:**
+```robotframework
+*** Settings ***
+Library    SeleniumLibrary
+Library    DatabaseLibrary          # ← thêm
+Resource   GlobalConstants.resource
+
+*** Keywords ***
+Connect To Main Database              # gọi ở Suite Setup
+    Connect To Database    ${DB_API}    ${DB_NAME}    ${DB_USER}    ${DB_PASS}    ${DB_HOST}    ${DB_PORT}
+
+Disconnect From Main Database         # gọi ở Suite Teardown
+    Disconnect From Database
+```
+
+**Theo feature — viết thẳng trong `<Page>Keywords.resource` của màn đang test (thay stub `Verify DB`):**
+
+> ⚠️ **VÍ DỤ minh hoạ** — tên file (`ComposePage/ComposeKeywords.resource`), tên bảng (`composite_requests`...), tên cột, tên keyword bên dưới đều là minh hoạ cho feature Compose. **PHẢI thay bằng Page / bảng / cột / oracle thật** của màn đang test (đọc từ dòng `DB: ...` trong `.feature` + schema thật). KHÔNG mặc định ghi vào `ComposePage`.
+```robotframework
+Composite Count By Name Should Be    # ← map dòng "DB: chỉ 1 composite_requests"
+    [Arguments]    ${name}    ${rows}=1
+    ${p}    Create List    ${name}
+    ${r}    Query    SELECT * FROM composite_requests WHERE name = %s    parameters=${p}
+    Length Should Be    ${r}    ${rows}
+
+Composite Sub Link Count Should Be   # ← map dòng "DB: 3 rows composite_sub_links"
+    [Arguments]    ${composite_id}    ${count}
+    ${p}    Create List    ${composite_id}
+    ${r}    Query    SELECT * FROM composite_sub_links WHERE composite_id = %s    parameters=${p}
+    Length Should Be    ${r}    ${count}
+```
+> ⛔ **Tên keyword BẮT BUỘC tiếng Anh, không ngoại lệ** ([auto_robot_rules §4](./auto_robot_rules.md) · [coding_convention §1/§4](./auto_coding_convention.md)) — đặt cạnh các keyword verify UI của cùng màn, cùng convention V + N Title Case tiếng Anh (vd `Profile Name Value Should Be`). Chỉ **tên Test Case** trong `.robot` mới được bám tiếng Việt theo manual.
+
+## 7. Teardown dữ liệu test (R4 test độc lập)
+Để lưu trữ lịch sử và audit trên Staging, CẤM tự động xóa bản ghi DB do testcase tạo ra trong teardown. `[Teardown]` của test case chỉ thực hiện reset trạng thái giao diện UI (đóng modal, click quay lại trang list), không thực hiện bất kỳ câu lệnh SQL DELETE nào.
+Dữ liệu tạo ra bắt buộc phải mang định danh unique per-run (timestamp/UUID) để chạy lại không đụng nhau, và **bắt đầu bằng tiền tố `auto_`** theo [iron_rules R7d](../../principles/iron_rules.md) — dạng `auto_<nhãn>_<run-marker>_<uuid8>`. Nhờ tiền tố này, dọn môi trường về sau chỉ cần một mệnh đề `LIKE 'auto\_%'`. Hai ngoại lệ: trường chỉ nhận số (số điện thoại, mã số thuế, numeric) và ca biên độ dài (giá trị phải đúng N ký tự).
+
+## 8. Tầng `@manual-verify`
+Oracle ghi `(manual-verify)` (vd audit log) → GIỮ placeholder `Log`, KHÔNG cố wire — tester verify tay. Đừng bịa query cho tầng này.
+
+## 9. Dịch `DB:` → SQL (dòng `DB:` là ý định, dịch lại từ ngữ nghĩa — không bám literal)
+- **"Không có record mới" = count-delta** (`COUNT(*)` trước == sau thao tác). CẤM dịch thành đếm theo nhãn (`COUNT WHERE <tên> = 0`).
+- **Key tra cứu theo định danh, kết hợp nhiều trường để khoanh đúng 1 bản ghi**: dùng PK (từ response create) và/hoặc khóa nghiệp vụ UNIQUE, có thể kết hợp thêm trường data đã biết của chính case. Tránh chỉ dựa nhãn người-đọc đơn lẻ (không unique). Kiểm *giá trị* một cột nhãn thì tra bản ghi theo định danh rồi đọc cột đó.
+- **Re-run sạch bằng teardown keyed theo định danh** (xoá theo PK/composite_id của record case tạo, đúng thứ tự FK) — xem §7.
+- **Tạo mới = kiểm lưu đủ trường:** `SELECT` bản ghi vừa tạo, assert **từng cột** khác NULL/rỗng (kể cả bảng phụ thuộc + số dòng). Không so nguyên văn (cột có thể mã hóa) trừ khi manual testcase ghi rõ lưu nguyên bản. Chỉ `COUNT(*) = 1` hoặc chỉ kiểm cột trạng thái là KHÔNG đủ.
+- **Cấm tự thêm comment diễn giải rồi code theo nó.**
+
+## 10. Đa-connection cho `$db.query`/`$seed.*` (setup data — khác oracle assertion ở §1-9)
+
+Hạ tầng connect ở §1/§4/§6 áp dụng lặp lại cho MỌI connection khai trong `{qa_artifacts}/data_sources.yaml`
+(registry dùng chung nhiều `{id}`, đọc ở Step 01 bước 6c), không chỉ 1 DB mặc định:
+
+- Mỗi `source_id` có keyword kết nối riêng (nhân bản theo template §6, đổi tên `Connect To {SourceId} Database` — tiếng Anh), Suite
+  Setup gọi đủ cho các `source_id` thực sự dùng trong slice — connect 1 lần, disconnect ở Suite Teardown.
+- Credential mỗi connection đọc theo `env_prefix` khai trong registry (vd `${PMT_DB_HOST}` cho source `pmt_profile`)
+  — không hardcode, không dùng chung biến `${DB_HOST}` mặc định cho mọi source.
+- **Connection identity = `env_prefix`, KHÔNG phải ranh giới source/service:** 2 `source_id` khai CÙNG
+  `env_prefix` = chung 1 DB vật lý → dùng chung 1 connection (connect 1 lần), JOIN/subquery chéo bảng của
+  2 source trong 1 câu SQL là **hợp lệ**. KHÁC `env_prefix` → cross-check 2 bước (query từng connection rồi
+  lọc giao nhau ở code Robot), CẤM JOIN xuyên DB. Đọc `env_prefix` của các source liên quan TRƯỚC khi quyết
+  định tách/gộp query — đừng mặc định "khác service = khác DB" và cũng đừng gộp bừa khi chưa thấy registry
+  khai cùng prefix.
+- `$seed.create`/`$seed.insert` (nếu registry có `auth` — vd login + captcha text để lấy Bearer token) thực hiện
+  ở Suite Setup/Test Setup tùy phạm vi dùng token (token có TTL — nếu nhiều test case cùng dùng, lấy 1 lần ở
+  Suite Setup và cache lại, không login lại mỗi test).
+- **Sinh `$seed.create` qua API (reuse rỗng/thiếu N):** auth captcha→token → tra tham số DB (`create_api.lookup_*`) → POST `create_api.<op>` (đúng method/content_type, multipart theo `body_part`, né trùng khóa) → `result_verify`; **lặp tới đủ N**. Dùng **`RequestsLibrary`** (HTTP) + **`DatabaseLibrary`** (lookup) — library-first (§5 auto_robot_rules), KHÔNG file `.py` riêng; bypass proxy bằng `Set Environment Variable    no_proxy    <host>`.
+  - **Bắt buộc, không stub:** registry có `create_api` → generate seed đầy đủ ngay lúc GENERATE. CẤM `Fail [SEED-TODO]`/"verify sau". Thiếu env → fail-at-run, không stub-at-generate.
+  - **Generic registry-driven — KHÔNG bespoke per-slice** (rule: [iron_rules R15](../../principles/iron_rules.md))**:** seed đọc `data_sources.yaml` (auth/create_api/lookup/reuse_check) để chạy; CẤM viết logic subsystem/nghiệp-vụ-cứng riêng cho từng slice. Buộc phải dùng Python thì là **1 lib DÙNG CHUNG registry-driven**, KHÔNG `<Slice>SeedLibrary.py` mỗi slice (đó là lý do "lần nào sinh cũng lỗi" — mỗi lần tái phát minh code seed mong manh).
+  - **Robust BẮT BUỘC (encode 1 lần ở tầng dùng chung, không tune lại per-slice):** (1) **reuse-first + cap/owner** — reuse un-consumed trước; giữ số pending/owner dưới ngưỡng để fan-out không ẩn dòng; cạn mới tạo owner mới. (2) **retry re-fetch** — sau seed nếu chưa lên fan-out (Redis TTL/sync) thì re-fetch + poll rồi mới fail. (3) **query đếm bằng JOIN gom-nhóm 1 lần**, KHÔNG subquery COUNT tương quan mỗi dòng (→ `max_statement_time`). (4) **escaping** — literal `LIKE 'x%'` đi cùng tham số `%s` phải viết `%%`.
+- **Gọi API mà `503`/`403` HTML (không phải JSON):** (1) `503` = proxy chặn → bypass (`requests` `trust_env=False` / `curl --noproxy '*'`); (2) `403` nginx = base URL thiếu version prefix → ghép đủ `basePath+endpoint+version` theo FE (`api-path.ts`), đừng đoán `${BASE}/public/...` là đủ. Tell: bước UI PASS nhưng call API fail → gần như chắc do proxy.
+- **Tài nguyên precondition BỊ TIÊU THỤ → xem §11** (đừng chỉ "reuse khi rỗng"): nếu action của case *ăn* bản ghi mồi, phải seed đủ N un-consumed theo số case tiêu thụ, không phải top-up khi pool = 0.
+
+## 11. Tài nguyên precondition BỊ TIÊU THỤ (consumable) — CẤM cache-1-lần cho cả suite
+
+Một số scenario có action **tiêu thụ** bản ghi mồi: tạo composite "ăn" 1 pending (link vào `composite_sub_links` → pending không còn khả dụng để compose lần 2). Với loại này, resolver **KHÔNG** được lấy 1 bản ghi rồi `Set Suite Variable ... yes` dùng lại cho mọi test — case tiêu thụ đầu ăn xong, các case tiêu thụ sau tái dùng bản ghi đã bị "ăn" → API từ chối → **false-fail hàng loạt** (đây là lỗi sinh đã gặp: 1 pending resolve-once, ~20 ca create sau đó fail "success toast not shown").
+
+**Nhận diện (self-check bắt buộc khi sinh resolver):** *"Action của case có LÀM MẤT bản ghi mồi cho case sau không?"* — xét **THEO TỪNG CASE**, không gán cả suite:
+- **Có** (state-mutating create/submit ghi vào bảng link/junction, hoặc đổi trạng thái bản ghi mồi `pending → consumed`) → áp §11 (fresh-per-case).
+- **Không** (case chỉ ĐỌC/hiển thị/tick bản ghi mồi — kể cả bản ghi ĐÃ bị tiêu thụ vẫn render được trên màn) → cache-1-lần OK, resolver read-only bình thường.
+
+**⛔ Anti-pattern "một resolver cho tất cả":** CẤM ép mọi case động đi qua pool un-consumed/seed. Case nào tạo thì case đó seed — case hiển thị/tick KHÔNG được phụ thuộc seed. Ép chung → pool cạn/seed hỏng kéo đổ cả các case vốn không cần data tươi (đã gặp: 36 case display fail oan vì gate pool). Tách 2 resolver: (a) display vars resolve-1-lần ở Suite Setup (mọi bản ghi mồi, kể cả consumed, un-consumed xếp trước); (b) fresh-per-case cho đúng các case tiêu thụ.
+
+**Quy tắc sinh khi §11 áp:**
+1. **Đếm NHU CẦU, không đếm tồn kho.** Số bản ghi mồi un-consumed phải ≥ số test case tiêu thụ nó (mỗi case 1 bản ghi tươi). `$db.query` trả 1 row lúc generate **KHÔNG** chứng minh đủ cho N case.
+2. **SELECT phải lọc bản ghi CHƯA tiêu thụ**, không chỉ `status=5`: `LEFT JOIN <link_table> l ON l.<fk>=t.<pk> WHERE l.<pk> IS NULL`.
+3. **Provision tươi qua `$seed.create` (§10) — per-case, seed fail KHÔNG cascade:** mỗi case tiêu thụ query fresh un-consumed ngay lúc cần; rỗng → seed bù TRONG case đó (DB tự phản ánh consumption — không cần pool/con trỏ thủ công), **KHÔNG** khoá 1 giá trị bằng `Set Suite Variable`. Seed bọc `Run Keyword And Ignore Error`: fail → log WARN, chỉ FAIL đúng case đó. **Seed phải LẶP QUA NHIỀU candidate** (skip candidate hỏng, thử candidate kế) — lý do fail khó đoán trước per-candidate (vd PMT-029 chỉ vài service có template data đầy đủ); chọn `LIMIT 1` sẽ kẹt vĩnh viễn ở candidate hỏng vì nó không bao giờ được đăng ký thành công.
+4. **Cache chỉ cho read-only.** Tài nguyên tiêu thụ tuyệt đối không cache xuyên suite.
+5. **Teardown/headroom.** Vì không tự động xóa DB ở teardown để giữ audit, bắt buộc phải seed dư headroom + định danh unique (§7) để các lần chạy lại (re-run) không bị đụng dữ liệu cũ.
+6. **Container-entity rotation khi cạn slot.** Nếu bản ghi mồi đăng ký theo cặp unique `(container, item)` (vd merchantId+serviceId) thì mỗi container có SỐ SLOT HỮU HẠN — chạy nhiều run sẽ cạn item seedable trên container hiện tại. Khi mọi candidate fail → TẠO CONTAINER MỚI qua create-op trong registry (vd `create_api.merchant`) rồi seed lại: container mới dùng lại được toàn bộ item "tốt". Resolver trả kèm container của bản ghi tươi (subId thuộc merchant nào → search theo merchant đó), KHÔNG giả định container cố định.
+7. **Record vừa seed chưa chắc hiện ngay trên UI — 2 bẫy phải kiểm trước khi tin retry:** (a) **cache backend** (vd Redis TTL 30s per key filter) → retry phải kéo dài > TTL; (b) **FE dedupe search** (`distinctUntilChanged` trên pipe filter) → re-click Tìm kiếm CÙNG filter bị nuốt, KHÔNG re-fetch — retry phải **mở lại màn/modal** (pipe mới) chứ không chỉ re-click. Đọc spec (HLD keyspaces/TTL) + FE component source để chọn cơ chế retry đúng; retry mù theo thời gian sẽ fail oan.
+8. **Danh sách chọn bản ghi mồi có thể là virtual scroll** (cdk-virtual-scroll...): dòng ngoài viewport KHÔNG có trong DOM → trước khi click theo id phải cuộn viewport từng bước tới khi dòng render (probe nhanh mỗi bước, không Sleep). Suite chạy nhiều lần làm list dài ra — lỗi chỉ lộ khi data tích lũy, dryrun/subset ít data không bắt được.
+9. **Case tiêu thụ NHIỀU bản ghi trong 1 lần load list → seed HẾT trên CÙNG 1 owner TRƯỚC khi load.** Màn chọn thường load list 1 lần (snapshot lúc search). Nếu seed bản ghi thứ 2 SAU khi đã load → nó không có trong list, mà re-load thì rớt tick trước đó. Đúng: gom nhu cầu (N bản ghi), bảo đảm đủ N un-consumed trên **cùng một owner** TRƯỚC, load list 1 lần (thấy hết), rồi tick từng cái; nếu 1 dòng chưa render thì reopen+search+**re-tick cả list** (idempotent, WUKS). CẤM xen kẽ seed↔tick. Case cross nhiều sub-system (vd PMT+PCM) cũng vậy: dồn tất cả lên cùng owner/merchantCode để 1 fan-out thấy hết. **Cách bảo đảm N phải theo §11.9a ngay dưới (tái dùng trước, seed đúng phần thiếu) — KHÔNG tạo owner mới mỗi case.**
+
+    **§11.9a — TIẾT KIỆM data (mọi nhánh seed, không chỉ multi):** seed tạo data thật trên môi trường chung → CẤM seed thừa. Thứ tự bắt buộc mỗi lần cần bản ghi: (1) **đếm un-consumed sẵn có trên owner hiện tại** → đủ thì DÙNG, không seed; (2) thiếu k → seed **đúng k** lên **owner hiện tại** (mỗi owner chứa được nhiều item — không cần owner mới); (3) **chỉ tạo owner mới khi owner hiện tại thật sự cạn slot** (mọi candidate item fail — §11.6), rồi tiếp tục trên owner mới. Sai thường gặp (đã xảy ra): tạo owner mới + seed đủ N **mỗi case** → rác bùng nổ (vd 37 merchant/ngày). Owner + item đã seed nhưng chưa bị tiêu thụ là **tài sản tái dùng** cho case sau, không phải dùng-một-lần. Ưu tiên teardown/định danh unique (§7) để re-run không tích rác.
+10. **Seed qua API cần tham số phụ (categoryId/formId/...) → tra ĐỘNG qua API list, KHÔNG hardcode UUID.** Nếu create-op cần id tham chiếu (danh mục, form, template...) mà registry để `[TBD]`: tìm endpoint list (`GET .../category`, `GET .../forms`) lấy phần tử đầu hợp lệ lúc chạy, ghi endpoint đó vào registry `lookup_*` thay cho UUID mẫu. Hardcode UUID sẽ hỏng khi data đổi/môi trường khác.
+
+11. **Record "độc" (DB có, UI vĩnh viễn không hiện) → BLACKLIST runtime, KHÔNG đoán cột filter.** Có record un-consumed hợp lệ về schema nhưng fan-out/UI không bao giờ render (nguyên nhân per-record khó suy từ cột — đã thử lọc theo `sanbox` và SAI: cả 55 service đều sanbox=1 kể cả loại hiển thị tốt, filter giết sạch candidate). Xử lý đúng: sau khi retry hết ngưỡng (§11.7) mà dòng vẫn không hiện → ghi subId vào blacklist (scope theo `source_id`, xem cuối mục này) + lấy record kế (self-heal ≤3/case); ORDER BY DESC + không blacklist = 1 record độc đầu độc MỌI case sau nó. **Persist blacklist theo hợp đồng single-writer:** chạy 1 process thì append thẳng canonical, không cần shard; chạy song song thì chỉ append vào **shard của chính process**, **tên shard PHẢI mang `source_id`**: `results/parts/{id}/{run_id}/blacklist-<source_id>-<shard>.jsonl` (hợp đồng tên file canonical là [step-05 §3](../../steps/step-05-execute-and-analyze-logs.md) — bỏ `<source_id>` thì bước merge lặp theo từng source **không thấy shard nào**, promote 0 record mà không báo lỗi, và run sau lại tốn 3 retry cho đúng record độc cũ). Step 05 merge union vào canonical `datatest/blacklist/{source_id}.jsonl` (**`{source_id}` = khoá registry trong `data_sources.yaml` chứa bản ghi mồi** — scope theo NGUỒN DATA, không theo slice, để mọi slice dùng cùng nguồn chia sẻ được blacklist) bằng tmp+`mv`, **dedupe theo khoá `subId`** (không phải `sort -u`); reader đọc `canonical + shard của run hiện tại`. CẤM append trực tiếp vào canonical trong lúc test chạy — nhiều process ghi chen nhau làm hỏng blacklist, run sau đọc sai (chi tiết: [step-05 §3](../../steps/step-05-execute-and-analyze-logs.md)). Lesson: khi định lọc data theo một cột "nghi là nguyên nhân", PHẢI kiểm phân bố cột đó trên data thật trước (record tốt và xấu có khác giá trị không?) — không thì filter dựa trên trùng hợp.
+
+12. **Reuse-check BOUNDED theo N bản ghi GẦN NHẤT — không thỏa thì SEED NGAY (đỡ mất thời gian).** Khi kiểm Tier 0 (tái dùng trước khi seed — §11.9a), CHỈ query **N bản ghi mang hậu tố định danh auto** (`*_code_auto` / marker của môi trường) **mới nhất** — `... WHERE <marker> LIKE '...auto%' ORDER BY <ngày tạo/đăng ký> DESC LIMIT N` (mặc định **N=5**) — rồi đối chiếu **TRẠNG THÁI** của chúng với **điều kiện đầu vào của testcase** (vd pending `status=5` + `is_history=0` + un-consumed / chưa bị link). Lý do bound N recent: bản ghi mới nhất xác suất render/khả dụng cao hơn, né 'record độc' cũ nằm đầu bảng (§11.11), và query nhẹ. **Không bản ghi nào trong N recent thỏa điều kiện → SEED MỚI NGAY (Tier 1)** — TUYỆT ĐỐI không scan toàn bảng / retry mù để "chờ có" (lãng phí thời gian). Nếu bản trong N recent thỏa ở DB nhưng dùng trên UI vẫn fail (record độc) → blacklist (§11.11) rồi rơi xuống seed. Đây là bước kiểm bắt buộc TRƯỚC mọi nhánh seed.

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

@@ -0,0 +1,99 @@
+# QUY CHUẨN CẤU TRÚC FRAMEWORK (FRAMEWORK STRUCTURE)
+
+## 1. Cấu trúc thư mục tổng thể
+
+Dự án Automation sẽ tuân theo cấu trúc phân tầng như sau:
+
+```text
+robot_framework_project/
+├── actions/                  # Thư mục quản lý toàn bộ các hành động tương tác
+│   ├── common/               # Quản lý các function dùng chung cho testcase/pages
+│   │   ├── BasePage.resource # Wrapper cho PageObjects (KHÔNG khai locator)
+│   │   ├── BaseTest.resource # Các hàm common dùng cho tầng testcases
+│   │   ├── SuiteFixtures.resource # Suite Setup/Teardown + session/auth/kết nối DB
+│   │   ├── GlobalConstants.resource # Hằng số dùng chung (URL, user/pass, API)
+│   │   └── SeedRegistry.resource # Seed/teardown dữ liệu mồi (registry-driven)
+│   ├── pageObject/           # (bề mặt ui) Quản lý các actions trong từng page
+│   │   ├── ShellPage/        # Locator shell dùng chung mọi màn (toast, modal, overlay…)
+│   │   │   ├── ShellKeywords.resource
+│   │   │   └── ShellVariables.resource
+│   │   ├── LoginPage/
+│   │   │   ├── LoginKeywords.resource
+│   │   │   └── LoginVariables.resource
+│   │   └── HomePage/
+│   │       ├── HomeKeywords.resource
+│   │       └── HomeVariables.resource
+│   └── serviceObject/        # (bề mặt service, no-UI) 1 endpoint/operation = 1 object
+│       └── TransferService/
+│           ├── TransferServiceKeywords.resource   # request RequestsLibrary + assert status/body/DB/MSG
+│           └── TransferServiceVariables.resource  # base_url, path, header (KHÔNG locator)
+├── resources/                # Quản lý các external file cho toàn bộ framework
+├── libraries/                # Quản lý thư viện cho toàn bộ framework
+├── configs/                  # Chứa các file cấu hình môi trường, thông số khởi tạo, và import tập trung các Keywords (ví dụ: từ các page)
+│   ├── env_<environment>.resource # CHỈ tạo env thực sự dùng + thực sự được import (xem §2.3)
+│   └── imports.resource      # File import tập trung các Keywords
+├── datatest/                 # Chứa Test Data (Excel, JSON, CSV) 
+│   ├── accounts.json
+│   └── test_data.xlsx
+├── tests/                    # Chứa các kịch bản kiểm thử (Test Suites)
+│   ├── LoginTest.robot
+│   └── HomeTest.robot
+└── results/                  # Chứa các file báo cáo kết quả (Log, Report, Screenshots)
+```
+
+## 2. Quy ước tổ chức các tầng (Layers)
+
+### 2.1 Tầng Actions (`actions/`)
+- Thư mục quản lý toàn bộ các hành động tương tác, bao gồm các function dùng chung và các action riêng của từng page.
+- **`common/`**: Không để trong thư mục `resources/`. Quản lý các function dùng chung cho cả testcases và pages.
+  - **BasePage**: wrapper của keyword thư viện (SeleniumLibrary…) dùng chung cho PageObjects.
+    - **CẤM khai `*** Variables ***` locator trong BasePage.** Mọi locator đều thuộc `pageObject/*/*Variables.resource` — kể cả locator shell dùng chung mọi màn (toast, modal, tooltip, popover, lớp phủ loading): gom vào một page object riêng `pageObject/ShellPage/ShellVariables.resource` + `ShellKeywords.resource`. BasePage chỉ nhận locator **qua tham số**, không tự biết locator nào.
+  - **BaseTest**: hàm common cấp Suite cho tầng testcases. **Wrapper mở browser BẮT BUỘC `Maximize Browser Window` ngay sau `Open Browser`** (xem [auto_robot_rules §6](./auto_robot_rules.md#6-hướng-dẫn-khởi-tạo-nguồn-tài-nguyên-generation-guidelines)) — tránh responsive/collapsed layout ẩn element gây false-fail.
+    - **CHỈ chứa hàm feature-agnostic** (không biết page/entity/bảng DB cụ thể). Keyword nào tham chiếu locator / dữ liệu nghiệp vụ / bảng DB của 1 màn — **kể cả teardown/cleanup dữ liệu của màn đó** — PHẢI nằm ở `*Keywords.resource` của page tương ứng, KHÔNG để BaseTest. (Teardown gắn với tầng test ở chỗ *khi nào chạy*, nhưng *nội dung dọn gì* là domain-specific → thuộc Page.)
+  - **Global Constants**: Chứa các thông tin hằng số dùng chung trên toàn framework:
+    -  URL server, user/pass dùng chung (Server, DataBase), thông tin API. **Tên biến CỐ ĐỊNH — sinh code chỉ được dùng đúng các tên này, đặt tên khác sẽ làm `robot --dryrun` đỏ ở Step 03 và đốt trọn 1 vòng:** `${BASE_URL}` (trang login, bề mặt `ui` — argument duy nhất được phép của `Open Browser` theo R9) · `${API_BASE_URL}` (bề mặt `service`, cho `Create Session`).
+    -  Biến timeout 3 tầng: `${SHORT_TIMEOUT}` (2s) / `${GLOBAL_TIMEOUT}` (10s) / `${LONG_TIMEOUT}` (30s), **+ `${POLL_INTERVAL}`** (chu kỳ poll của `Wait Until Keyword Succeeds` — bắt buộc có khi bề mặt `service` assert side-effect async, xem [iron_rules R7s](../../principles/iron_rules.md))
+    -  **Env var đọc theo tiền tố dự án `<ENV_PREFIX>`** (vd `%{<ENV_PREFIX>_DB_HOST}`): `<ENV_PREFIX>` do project khai, KHÔNG hardcode tiền tố của một dự án cụ thể vào skill (Portability principle — skill canonical phải chạy được ở repo khác).
+    -  Browser: `${BROWSER}`. Keyword mở browser dùng **mặc định thư viện = HEADED** + `Maximize Browser Window`. ⛔ **TUYỆT ĐỐI KHÔNG scaffold toggle headless** — cấm mọi hình thức: `--headless`, biến `${HEADLESS}`, `%{<ENV_PREFIX>_HEADLESS=...}`, `Set Variable If ... headless`. Chỉ thêm khi **user yêu cầu rõ ràng bằng lời**. ⚠️ **Cạm bẫy lách-runtime (đã vi phạm):** khi chạy live gặp lỗi do môi trường KHÔNG có desktop (headed → viewport 0px → `element has zero size` / `ElementNotInteractableException`), **KHÔNG được "sửa" bằng cách bật headless** — đó là lách rule. Xử lý đúng: **DỪNG, báo user chạy trên máy có desktop hiển thị** (headed render bình thường ở đó). Rule skill > giải pháp kỹ thuật cho tiện. Xem [iron_rules R12](../../principles/iron_rules.md).
+    -  Số lần retry cho test failed (≤3 — R7/R7s)
+    -  Đường dẫn tương đối tới thư mục download, file data, file upload
+- **`serviceObject/`** *(bề mặt `service` — no-UI)*: Đối ứng của `pageObject/` cho test API/service. Mỗi endpoint/operation = 1 thư mục chứa `{Service}Variables.resource` (base_url/path/header — KHÔNG locator) + `{Service}Keywords.resource` (keyword gọi request qua `RequestsLibrary` + keyword assert status/body, gọi verify DB/MSG). Cùng nguyên tắc POM: test suite chỉ gọi high-level keyword, không chứa URL/payload thô. Session (`Create Session` + auth) + kết nối DB/queue verify đặt ở `common/SuiteFixtures.resource`. Thư viện `RequestsLibrary` khai ở `libraries/`. KHÔNG dùng SeleniumLibrary/browser cho bề mặt này.
+- **`pageObject/`** *(bề mặt `ui`)*: Quản lý các actions trong từng page. Tất cả các Page trong dự án sẽ được đặt ở đây.
+  - Mỗi page sẽ quản lý các sự kiện của chính page đó (ví dụ: `LoginPage`, `HomePage`).
+  - Mỗi thư mục chức năng chỉ được phép chứa:
+    - **`*Variables.resource`**: Chứa toàn bộ element locators của page đó.
+    - **`*Keywords.resource`**: Chứa các actions tương tác trực tiếp lên UI. Bắt buộc phải import file Variables tương ứng và có thể sử dụng các wrapper từ `BasePage`.
+  - **Lưu ý**: 
+    - Tầng Page Objects KHÔNG chứa logic Test Case (không có thẻ `*** Test Cases ***`).
+    - Keyword **thao tác** không tự assert — trả giá trị về để tầng Test verify. Nhưng keyword **verify theo chức năng** (`<Field> Value Should Be`, verify DB…) VẪN đặt ở Page/Service Keywords, vì `.robot` không được định nghĩa keyword ([iron_rules R4](../../principles/iron_rules.md)) — test chỉ *gọi* chúng.
+
+### 2.2 Tầng External Resources & Libraries (`resources/`, `libraries/`)
+- **resources/**: Quản lý các tài sản tĩnh (Assets/Binary) hỗ trợ cho framework nhưng không phải là dữ liệu nghiệp vụ có cấu trúc. 
+  - Ví dụ: Các file hình ảnh/PDF mẫu dùng để test chức năng Upload, file `.exe` của WebDriver, hoặc các file cấu hình đặc thù của bên thứ 3 (ví dụ: config cho Appium, proxy profile).
+  - *Lưu ý: Không để dữ liệu test (test data) hoặc cấu hình biến môi trường của Robot Framework vào đây.*
+- **libraries/**: Quản lý thư viện cho toàn bộ framework (ví dụ: các thư viện Python tự viết hoặc các custom library khác).
+
+### 2.3 Tầng Data & Config (`configs/`, `datatest/`)
+- Tầng này không chứa logic, tập trung vào cấu hình chạy test và dữ liệu đầu vào.
+- **configs/**: Chứa các file cấu hình *của chính Robot Framework* như biến môi trường (URL, Account mặc định, Database config cho Dev/Staging). **CHỈ tạo file env thực sự dùng và thực sự được `imports.resource` import** — scaffold `env_dev`/`env_stg` rỗng "cho đủ bộ" là config-theatre — vi phạm YAGNI ([robot §5](./auto_robot_rules.md)).
+- **datatest/**: Chứa toàn bộ dữ liệu kiểm thử có cấu trúc (Structured Test Data). Đây là các file chứa giá trị nghiệp vụ (JSON, CSV, Excel) có thể parse ra thành biến/mảng để sử dụng cho Data-Driven Testing.
+- **Quản lý Import tập trung**: Thư mục `configs/` có thể chứa các file `.resource` đóng vai trò tập hợp (ví dụ: `imports.resource`). File này dùng để import tất cả các file `*Keywords.resource` từ các page. Giúp các file Test Suite gọn gàng hơn vì chỉ cần gọi import file tập hợp này thay vì khai báo lại nhiều file nhỏ lẻ.
+- Các file Test Suite hoặc Base Test sẽ load data và import các Keywords thông qua tầng này để thực thi.
+
+### 2.4 Tầng Test Execution (`tests/`)
+- File ở tầng này bắt buộc có đuôi `.robot` và có chứa thẻ `*** Test Cases ***`. **Mỗi file = 1 Test Suite cho 1 UNIT màn/operation** (`@scr:<unit_id>` / `@svc:<unit_id>`) — KHÔNG phải 1 file cho cả `surface_type`: slice N màn → N file. Luật tách & đặt tên đầy đủ (tên theo màn/operation, cấm nhét `{id}`, cấm file "tổng hợp", cấm mashup) ở [step-03 §2](../../steps/step-03-generate-suite.md) — không lặp lại ở đây.
+- **Suite Setup/Teardown + fixtures điều hướng dùng chung** cho nhiều suite → đặt ở `actions/common/SuiteFixtures.resource` (import qua `configs/imports.resource`), các suite gọi lại — CẤM copy-paste block Setup vào từng `.robot` (DRY).
+- Các file Test chỉ import các `Keywords.resource` cần thiết, file data và file cấu hình chung (`BaseTest`).
+- **KHÔNG**: Viết trực tiếp locator (XPath, CSS) hoặc logic phức tạp trong file Test. File Test chỉ gọi High-level Keyword để mô tả flow kinh doanh và dùng các câu lệnh Assertion.
+- Các bước thực hiện kiểm thử thủ công như nào thì ánh xạ qua như thế.
+- Dùng Setup và Teardown để đảm bảo testcase chạy chính xác, tránh viết code lặp lại.
+
+## 3. Quy tắc Import (Tránh Circular Dependency)
+
+Để tránh lỗi lặp vòng và dễ quản lý khi import các tài nguyên, hãy tuân thủ nguyên tắc một chiều (Top-down) và cơ chế import tập trung:
+1. **Tests** import file **imports.resource** (để lấy tất cả Keywords), **BaseTest** (để chạy Setup/Teardown), và file **Data**. KHÔNG import lẻ tẻ từng file Keyword.
+2. **imports.resource** (tại thư mục `configs/`) import toàn bộ **Keywords (Pages)**, **BaseTest**, và **Global Constants**.
+3. **Keywords (Pages)** chỉ import **Variables (Pages)** tương ứng của nó và **BasePage** (chứa các wrapper chung).
+4. **Tuyệt đối không**:
+   - File Variables không được import File Keywords.
+   - Các Page ngang hàng hạn chế import chéo lẫn nhau nếu không thực sự cần thiết (tránh page A gọi page B rồi page B gọi lại page A). Việc luân chuyển page nên được thực thi ở tầng Test Suites.