# JX Automation Suite — Sổ Tay Kiểm Thử Thực Địa (Live Field Testing Runbook)
*Phiên bản: 2.6 — Bổ sung cơ chế Bắt Tùy Chọn Hội Thoại NPC Theo Nội Dung Text & Phái Đặc Thù*

> **Định chế bắt buộc**: Tuân thủ triệt để bất biến **`INV-LIVE-FIELD-ACCEPTANCE`** và **`INV-EMPIRICAL-VERIFIED`**.  
> Mọi tính năng sau khi vượt qua kiểm thử mô phỏng (Mock QA Track) **bắt buộc** phải được kiểm tra trực tiếp trên tiến trình game thật (`vggame.exe` / `game.exe`) theo đúng quy trình tài liệu này mới được coi là **chính thức nghiệm thu bàn giao**.

---

## 1. Bản Đồ Hiện Trường & Môi Trường Kiểm Thử Thực Tế

Hệ thống đang kết nối trực tiếp với 4 tiến trình game và AutoVLBS đang chạy trên máy:

| STT | Nhân Vật | Môn Phái | PID Game | Vai Trò Trong Đội Hình | Vị Trí Hiện Trường |
| :---: | :--- | :--- | :---: | :--- | :--- |
| **1** | `BoCuaCacCon` | **Cái Bang** | `33884` | Đội trưởng (Chủ công chiến đấu, Buff Túi Điệp) | Bãi train `Lão Hổ Động` / Thành thị |
| **2** | `ConCuaBoMe` | **Võ Đang** | `34360` | Tấn công tầm xa, Tọa Vọng Vô Vi | Bãi train `Lão Hổ Động` |
| **3** | `ConGailCung` | **Ngũ Độc** | `45516` | Hỗ trợ bùa chú suy yếu (Vạn Cổ, U Hồn) | Bãi train `Lão Hổ Động` |
| **4** | `MeCuaCacCon` | **Nga My** | `69240` | Hồi máu nhóm (Từ Hàng Phổ Độ), Hào quang Lưu Thủy | Bãi train `Lão Hổ Động` |
| **Auto**| `AutoVLBS` | N/A | `38488` | AutoVLBS gốc chạy hook engine `core.dll` | Đang giám sát 4 tài khoản |

- **Bản binary kiểm thử thực địa**: `C:\Projects\JX\runtime\JXHelper_Runtime.exe` (đã được hot-swap đồng bộ mới nhất).
- **Thư mục kịch bản Lua AutoVLBS**: `C:\JXVCTK\JxVoCongTruyenKy\_AutoVLBS\VLBS19\Scripts\`.
- **Tệp giám sát hành vi thời gian thực**: `logs/actions.log` và `logs/telemetry.jsonl`.

---

## 2. Kịch Bản Thực Địa 1: Kiểm Thử Hội Thoại NPC Thợ Rèn (Live Blacksmith Text Matching)

### Mục tiêu:
Xác nhận động cơ `NpcDialogTextMatcher` nhận diện và chọn đúng mục "Sửa trang bị" và "Sửa toàn bộ" dựa trên nội dung text, loại bỏ hoàn toàn nguy cơ bấm nhầm khi server game mở sự kiện chèn thêm dòng vào menu NPC.

### Các bước tiến hành:
1. **Chuẩn bị nhân vật**:
   - Chọn tab nhân vật `BoCuaCacCon` (hoặc bất kỳ nhân vật nào).
   - Di chuyển nhân vật đứng gần NPC Thợ Rèn tại Thành thị hoặc Thôn trang (Ví dụ: Thợ rèn Ba Lăng Huyện, Phượng Tường, Biện Kinh).
2. **Thiết lập trên giao diện JXHelper**:
   - Mở `JXHelper_Runtime.exe` -> Chọn tab nhân vật trên ListView đỉnh đầu.
   - Chuyển sang Tab **`Hậu cần`**.
   - Tại cụm **`Hội Thoại NPC (Khớp Text)`**:
     * Tích chọn: `[x] Bắt theo nội dung (chống lỗi thứ tự)`.
     * Ô từ khóa: `Sửa trang bị;Sửa chữa;Sửa đồ;Söa trang bÞ`.
     * Dự phòng (nếu hụt): `1`.
   - Tại cụm **`Sửa Đồ (Thợ Rèn & Rương)`**:
     * Chọn radio: `(o) Thợ Rèn thành thị (Cấp >= 60)`.
     * Bấm nút **`Chỉ NPC`** -> Click chuột trái vào đúng vị trí NPC Thợ Rèn trên màn hình game để lấy tọa độ tự động.
3. **Thực thi lệnh kiểm thử tại hiện trường**:
   - Bấm nút **`Thử`** (btnTestRepair) trong cụm Sửa Đồ.
4. **Quan sát trực quan & Kiểm chứng log**:
   - [ ] Nhân vật click chuột trái ngầm vào NPC Thợ Rèn.
   - [ ] Hộp thoại tùy chọn của NPC bật mở trên màn hình game.
   - [ ] Bot phân tích nội dung text của menu và gửi đúng phím số tương ứng (ví dụ phím `1`, `2` hoặc `3` tùy theo vị trí thực tế của dòng "Sửa trang bị").
   - [ ] Hộp thoại cấp 2 mở ra và bot chọn tiếp mục "Sửa toàn bộ".
   - [ ] Độ bền của tất cả trang bị trên người nhân vật phục hồi 100%.
   - [ ] Kiểm tra file `logs/actions.log` hiển thị chuỗi sự kiện:
     ```text
     [TEST THỢ RÈN] Thử click NPC Thợ Rèn tại (X, Y)...
     [THỢ RÈN] Chọn menu 'Sửa trang bị' (Từ khóa: '...' -> Phím X)...
     [THỢ RÈN] Chọn dòng 'Sửa toàn bộ' (Từ khóa: '...' -> Phím Y)...
     [TEST THỢ RÈN] Hoàn tất thử nghiệm sửa đồ Thợ Rèn.
     ```

---

## 3. Kịch Bản Thực Địa 2: Kiểm Thử Script AutoVLBS `SuaDo_DuocPham_TanThu.lua`

### Mục tiêu:
Xác nhận hàm `tbVulanLib.SelectMenuByKeywords` trong `Scripts/LIB/VulanLib.lua` chạy trực tiếp trong engine AutoVLBS và tự động click trúng option theo text mà không dùng index cố định `(0, 0)`.

### Các bước tiến hành:
1. Mở giao diện `AutoVLBS.exe` (PID `38488`).
2. Chọn tab nhân vật bất kỳ trong AutoVLBS.
3. Chuyển sang Tab **`T.ích` (Tiện ích)**.
4. Tại danh sách kịch bản Lua, chọn: `SuaDo_DuocPham_TanThu.lua`.
5. Bấm nút **`Run` (Chạy)**.
6. **Quan sát trực quan**:
   - [ ] Nhân vật tự sử dụng Thổ Địa Phù về thành.
   - [ ] Nhân vật tự tìm đường đến Thợ Rèn gần nhất (`player.PathMoveTo`).
   - [ ] Menu Thợ Rèn mở ra -> Script đọc `menu.GetText` và click đúng mục "Sửa trang bị".
   - [ ] Menu xác nhận mở ra -> Script click đúng mục "Toàn bộ" / "Sửa toàn bộ".
   - [ ] Nhân vật mở rương F4 và dùng Dược phẩm tân thủ 3h.
   - [ ] Nhân vật tự động quay lại bãi luyện công.

---

## 4. Kịch Bản Thực Địa 3: Kỹ Năng Hỗ Trợ Đặc Thù Phái Nga My (`MeCuaCacCon`)

### Mục tiêu:
Kiểm chứng tính năng hồi máu `Từ Hàng Phổ Độ` khi lượng máu tụt và cơ chế luân chuyển hào quang `Lưu Thủy` - `Mộng Điệp` theo đúng phong cách AutoVLBS.

### Các bước tiến hành:
1. Trên JXHelper, chọn tab nhân vật **`MeCuaCacCon`** (Nga My - PID `69240`).
2. Tab `L.công` -> Nút hỗ trợ hiển thị huy hiệu xanh lam: **`⚙ Nga My (Nhóm)`**.
3. Bấm vào nút `⚙ Nga My (Nhóm)` để mở hộp thoại modal:
   - [x] Tích chọn `Tự động dùng Từ Hàng Phổ Độ (Chuột phải)`.
   - Đặt ngưỡng máu: `75%`.
   - [x] Tích chọn `Bơm cho cả nhóm`.
   - [x] Tích chọn `Luân phiên Hào Quang (Lưu Thủy - Mộng Điệp)`.
   - Đặt chu kỳ: `30s`.
   - Bấm **`Lưu cấu hình`**.
4. Đưa đội hình vào chiến đấu với quái tại `Lão Hổ Động`.
5. **Quan sát trực quan**:
   - [ ] Khi nhân vật hoặc đồng đội bị quái đánh tụt máu dưới 75%, nhân vật Nga My tự động niệm chú `Từ Hàng Phổ Độ` (hiệu ứng hoa sen hồi máu bừng sáng).
   - [ ] Cứ sau đúng 30 giây, vòng hào quang dưới chân nhân vật chuyển đổi luân phiên: Hào quang xanh lướt gió (`Lưu Thủy`) $\leftrightarrow$ Hào quang xoay phục hồi mana (`Mộng Điệp`).

---

## 5. Kịch Bản Thực Địa 4: Bùa Chú Luân Chuyển Phái Ngũ Độc (`ConGailCung`)

### Mục tiêu:
Kiểm chứng động cơ Curse Rotation tự động niệm bùa làm suy yếu đối thủ trước khi đánh chiêu thức chính.

### Các bước tiến hành:
1. Trên JXHelper, chọn tab nhân vật **`ConGailCung`** (Ngũ Độc - PID `45516`).
2. Tab `L.công` -> Nút hỗ trợ hiển thị huy hiệu xanh lá: **`⚙ Ngũ Độc (Bùa)`**.
3. Bấm vào nút `⚙ Ngũ Độc (Bùa)`:
   - [x] Tích chọn `Kích hoạt chiêu thức luân chuyển (Bùa chú)`.
   - Bùa chú #1: `Vạn Cổ Thực Tâm` (hoặc `U Hồn Phệ Phách`), Delay: `3000ms`, Kích hoạt: `T.Gian`.
   - Bùa chú #2: `Hóa Cốt Miên Chưởng`, Delay: `4000ms`, Kích hoạt: `T.Gian`.
   - Bấm **`Lưu cấu hình`**.
4. Cho nhân vật tiếp cận cụm quái trong `Lão Hổ Động` và bấm **`BẮT ĐẦU`**.
5. **Quan sát trực quan**:
   - [ ] Trước khi xuất chiêu tấn công chính, bot tự động click chuột phải thi triển bùa chú lên quái vật.
   - [ ] Hiệu ứng bùa chú màu xanh lá/tím độc môn xuất hiện trên đầu quái vật.
   - [ ] Sau khi bùa chú đã thi triển, nhân vật mới tiếp tục chuỗi xuất chiêu tấn công.

---

## 6. Kịch Bản Thực Địa 5: Bất Biến Không Chiếm Chuột Phím (`INV-BG-INPUT-NO-HIJACK`)

### Mục tiêu:
Đảm bảo 100% người chơi hoàn toàn tự do sử dụng máy tính làm việc khác trong lúc bot tự hành chạy ngầm cả 4 tài khoản.

### Các bước tiến hành:
1. Bấm **`BẮT ĐẦU`** trên JXHelper để kích hoạt toàn bộ 4 tài khoản cùng lúc.
2. Người dùng mở trình duyệt web xem video Youtube, mở Microsoft Word soạn thảo văn bản, hoặc chơi game khác.
3. **Quan sát trực quan**:
   - [ ] Con trỏ chuột của Windows không bao giờ bị giật hay bị kéo sang cửa sổ game.
   - [ ] Khi đang gõ văn bản trong Word, không có bất kỳ phím số (`1`, `2`, `3`...) hay phím Space nào bị gõ nhầm vào văn bản.
   - [ ] 4 cửa sổ game `vggame.exe` vẫn tự động chiến đấu, nhặt đồ, sửa đồ và bơm máu đều đặn dưới nền.

---

## 7. Kịch Bản Thực Địa 6: Kiểm Thử Chiêu Công Kích Cái Bang Kháng Long Hữu Hối (cấp 50) & Kiến Trúc Bảng Kỹ Năng F5

### Mục tiêu:
Xác nhận nhân vật Cái Bang (`BoCuaCacCon` - PID 33884) nạp và xuất chiêu chính xác **`Kháng Long Hữu Hối` (cấp 50 - ID 129)** (xuất hiện 3 rồng lửa), triệt tiêu hoàn toàn việc suy đoán sai chiêu 90 `Phi Long Tại Thiên` khi nhân vật chưa đạt cấp độ. Bảng kỹ năng F5 của 10 môn phái được quản trị chuẩn xác theo cấp độ học kỹ năng (`RequiredLevel`: 10, 20, 30, 40, 50, 60, 90, 120).

### Các bước tiến hành:
1. **Khởi động JXHelper**:
   - Mở `JXHelper_Runtime.exe` -> Chọn tab nhân vật `BoCuaCacCon` (Cái Bang - PID `33884`).
   - Chuyển sang Tab **`L.công`**.
2. **Quan sát giao diện Tab `L.công`**:
   - [ ] Dropdown **`Môn phái`** hiển thị đúng: `Cái Bang`.
   - [ ] Dropdown **`Chiêu:`** (`cboMainAttackSkill`) tự động chọn đúng: **`Kháng Long Hữu Hối (cấp 50)`**.
   - [ ] Danh sách chiêu thức trong dropdown chỉ bao gồm các chiêu công kích của Cái Bang: `Giáng Long Chưởng (cấp 10)`, `Đả Cẩu Trận (cấp 20)`, `Kháng Long Hữu Hối (cấp 50)`, `Bổng Đả Ác Cẩu (cấp 60)`, `Phi Long Tại Thiên (cấp 90)`, `Thiên Hạ Vô Cẩu (cấp 90)`. Tuyệt đối không xuất hiện chiêu của 9 môn phái khác.
   - [ ] Khung Buff B1 hiển thị chiêu: **`Túy Điệp Cuồng Vũ (cấp 60)`** (ID 130).
   - [ ] Nhãn kỹ năng bị động (`lblPassiveSkills`) hiển thị: `Hoạt Bất Lưu Thủ (40) | Tiêu Diêu Công (50)`.
3. **Thực thi lệnh chiến đấu tại hiện trường**:
   - Nhân vật `BoCuaCacCon` đang ở bãi quái `Lão Hổ Động`.
   - Bấm nút **`BẮT ĐẦU`** (F9).
4. **Quan sát trực quan trên màn hình game**:
   - [ ] Nhân vật thi triển chiêu thức công kích bằng chuột trái hoặc chuột phải ngầm.
   - [ ] Hiệu ứng xuất chiêu là **3 rồng lửa màu cam đỏ** bay về phía quái vật (đặc trưng của `Kháng Long Hữu Hối` cấp 50).
   - [ ] Không xuất hiện hoạt ảnh 1 rồng bay lượn trên đầu (của chiêu 90 `Phi Long Tại Thiên`).
   - [ ] Kiểm tra file `logs/actions.log` ghi nhận:
     ```text
     [COMBAT] BoCuaCacCon xuất chiêu 'Kháng Long Hữu Hối (cấp 50)' (ID: 129, Tay Phải/Trái)...
     ```

---

## 8. Kịch Bản Thực Địa 7: Kiểm Thử Tự Động Với BoCuaCacCon — Quản Lý Tài Khoản, Khóa Bãi Nghiệt Long Động 7x & Thần Hành Phù Đầu Cổng

### Mục tiêu:
1. Xác nhận phân hệ **Quản Lý Danh Sách Tài Khoản** (`AccountManagerForm`) và **Bộ Khởi Chạy Tự Động** (`GameLauncher`) vận hành trơn tru: Lưu trữ danh sách SSoT (`config/accounts.json`), nhập/xuất danh sách hàng loạt, và hỗ trợ mở client/auto một chạm.
2. Xác nhận nhân vật **`BoCuaCacCon`** tuân thủ nghiêm ngặt quy chuẩn **KHÓA BÃI ĐỨNG YÊN** (`LockCurrentSpot = true`, `AttackRadius = 0`): Tuyệt đối không di chuyển khỏi bãi `Nghiệt Long Động 7x`.
3. Xác nhận module **`ThanHanhPhuExecutor`** đối soát hộp thoại menu 3 cấp của Thần Hành Phù để đưa nhân vật trở về ngay **ĐẦU CỔNG NGHIỆT LONG ĐỘNG 7X** an toàn khi cần hồi phục vị trí.

### Các bước tiến hành:
1. **Kiểm tra Giao diện Quản lý Tài khoản**:
   - Mở `JXHelper_Runtime.exe` -> Bấm nút **`👤Acc`** trên đỉnh đầu (hoặc nút `👤 Quản Lý Danh Sách Tài Khoản` trong Tab `H.thống`).
   - Cửa sổ `AccountManagerForm` bật mở:
     * [ ] Hiển thị danh sách tài khoản, nhân vật `BoCuaCacCon` in đậm màu đỏ sẫm (Tài khoản: `nguvansi`, Mật khẩu: `••••••••`).
     * [ ] Kiểm tra tính năng nhập dán text hàng loạt dạng `taikhoan|matkhau|ten_nhanvat|monphai|server|bando`.
     * [ ] Nút `🚀 Mở Client & Đăng Nhập`: Gọi `GameLauncher.LaunchGameClient()` mở tiến trình `Game.exe` và tự động gửi thông tin đăng nhập ngầm qua `AutoFillLoginCredentialsAsync`.
     * [ ] Nút `⚡ Mở AutoVLBS`: Gọi `GameLauncher.LaunchAutoVLBS()` mở tiến trình `AutoVLBS.exe`.
2. **Kiểm tra Ràng buộc Bãi Nghiệt Long Động 7x (Đứng yên tại chỗ)**:
   - Chọn nhân vật `BoCuaCacCon` -> Chuyển sang Tab `L.công`.
   - Cự ly `AttackRadius = 0`, chế độ khóa bãi đứng yên kích hoạt.
   - Bấm **`BẮT ĐẦU`** (F9):
     * [ ] Nhân vật đứng yên tại chỗ tại bãi quái `Nghiệt Long Động 7x`, không bước chân đuổi quái.
     * [ ] Xuất chiêu công kích chuột phải ngầm: Tuyệt kỹ `Kháng Long Hữu Hối (cấp 50)` (3 rồng lửa).
     * [ ] Cứ mỗi 60s: Thi triển Buff `Túy Điệp Cuồng Vũ (cấp 60)`.
     * [ ] Tự động nhặt đồ ngầm (Space) và bơm máu/mana khi cần.
3. **Kiểm tra Cơ chế Thần Hành Phù Về Đầu Cổng**:
   - Khi cần hồi phục vị trí: Bot kích hoạt Thần Hành Phù trong rương F4.
   - Menu Thần Hành Phù hiện ra:
     * [ ] Cấp 1: Chọn đúng "Bản đồ luyện công" (Phím 2).
     * [ ] Cấp 2: Chọn đúng "Cấp 70-79" (Phím 7).
     * [ ] Cấp 3: Chọn đúng "Nghiệt Long Động" (Phím 1).
     * [ ] Nhân vật truyền tống về ngay **ĐẦU CỔNG NGHIỆT LONG ĐỘNG 7X**.
4. **Thu thập ảnh chụp màn hình kiểm chứng (Milestone Captures)**:
   - [ ] Ảnh `jxhelper_account_manager_live.png`: Cửa sổ quản lý danh sách tài khoản hiển thị tài khoản `nguvansi`.
   - [ ] Ảnh `jxhelper_cai_bang_khang_long_live.png`: Giao diện MainForm Cái Bang có nút `👤Acc`.
   - [ ] Ảnh `live_automated_field_test_desktop.png`: Toàn cảnh màn hình kiểm thử thực địa.

---

## 9. Bảng Tiêu Chí Nghiệm Thu Thực Địa Chính Thức (Live Sign-Off Sheet)

| Hạng Mục Kiểm Thử Thực Địa | Dấu Hiệu Pass Thực Tế | Trạng Thái | Người Kiểm Thử / Ghi Chú |
| :--- | :--- | :---: | :--- |
| **1. Khớp text Thợ Rèn Cấp 1** | Menu mở ra, chọn đúng mục "Sửa trang bị" theo text | `CHỜ TEST` | Thử tại Ba Lăng Huyện / Phượng Tường |
| **2. Khớp text Thợ Rèn Cấp 2** | Menu xác nhận mở ra, chọn đúng "Sửa toàn bộ" | `CHỜ TEST` | Trang bị phục hồi 100% độ bền |
| **3. Kháng lỗi chèn sự kiện** | Khi server chèn option sự kiện, bot không bấm nhầm | `CHỜ TEST` | Chọn đúng phím số theo nội dung |
| **4. Script Lua AutoVLBS** | `SuaDo_DuocPham_TanThu.lua` chạy trơn tru qua `tbVulanLib` | `CHỜ TEST` | Chạy trực tiếp từ Tab `T.ích` VLBS |
| **5. Phái Nga My (Hồi máu)** | Máu < 75% tự động niệm Từ Hàng Phổ Độ | `CHỜ TEST` | Test tại bãi quái `Lão Hổ Động` |
| **6. Phái Nga My (Hào quang)** | Luân phiên Lưu Thủy $\leftrightarrow$ Mộng Điệp mỗi 30s | `CHỜ TEST` | Quan sát vòng tròn dưới chân |
| **7. Phái Ngũ Độc (Bùa chú)** | Niệm Vạn Cổ / U Hồn lên quái trước khi đánh chiêu chính | `CHỜ TEST` | Quái dính bùa độc màu tím/xanh |
| **8. Tự do chuột phím 100%** | Chuột và phím người dùng không bị can thiệp khi bot chạy | `CHỜ TEST` | Soạn thảo văn bản song song |
| **9. Log viễn thám đầy đủ** | `logs/actions.log` ghi nhận chuẩn xác chuỗi sự kiện | `CHỜ TEST` | Chế độ FileShare.ReadWrite |
| **10. Cái Bang Kháng Long Hữu Hối** | Dropdown nạp `Kháng Long Hữu Hối (cấp 50)`, xuất chiêu 3 rồng lửa | `PASS TEST` | Kiểm chứng thực nghiệm & ảnh live |
| **11. Bảng kỹ năng F5 & Cách ly** | Mỗi môn phái chỉ hiển thị chiêu phái mình, phân định rõ cấp độ | `PASS TEST` | Test Suite 7/7 bài kiểm thử PASS |
| **12. Quản lý Tài Khoản (AccountManager)** | Bảng tài khoản, dán text hàng loạt, tài khoản `nguvansi` xác thực 100% | `PASS TEST` | Đã nghiệm thu ảnh jxhelper_account_manager_live.png |
| **13. Khóa bãi Nghiệt Long Động 7x** | `LockCurrentSpot = true`, `AttackRadius = 0`, đứng yên tại chỗ | `PASS TEST` | Đã tích hợp CombatEngine & test tự động |
| **14. Thần Hành Phù Đầu Cổng** | Menu 3 cấp (Bản đồ luyện công -> 7x -> Nghiệt Long Động) | `PASS TEST` | ThanHanhPhuExecutor phân giải (2, 7, 1) |

---
*Bản quyền tài liệu: JX Automation Suite 2026. Mọi hành vi tự ý nghiệm thu khi chưa thực hiện các bước trên đều bị coi là vi phạm kỷ luật tác chiến.*