# TÀI LIỆU ĐẶC TẢ KỸ THUẬT: HỆ THỐNG TỰ ĐỘNG GẮN KỸ NĂNG VÀO PHÍM TẮT & TÍCH HỢP TRI THỨC REPOE2 (AUTO SKILL BINDER & REPOE2 SPECIFICATION)

> **Mã tài liệu**: `ARCH-SKILL-BINDER-REPOE2-2026-P67`  
> **Mốc thời gian tham chiếu**: 16/09/2026  
> **Trạng thái**: [ACTIVE / SSoT IMPLEMENTED]  
> **Phạm vi**: `src/assistant_tool/skills/`, `src/assistant_tool/ui/skill_binder_panel.py`, `docs/development/`  
> **Tuân thủ**: Rule 1 (Hai Tầng C++/Python), Rule 4 (Kiến Trúc Module Hóa), Rule 5 (100% Dữ Liệu Thật), Rule 7 (Chuẩn Người Chơi Thật & Non-Hijacking).

---

## 1. BỐI CẢNH & ĐỘNG LỰC PHÁT TRIỂN (CONTEXT & PROBLEM STATEMENT)

### 1.1. Rủi ro sai lệch phím tắt kỹ năng (Skill Misalignment Anomaly)
Trong Path of Exile 2, bot chiến đấu kích hoạt các kỹ năng theo quy chuẩn gán phím nhất định (`Q`, `E`, `R`, `T`, `F`, `RMB`, `LMB`). Tuy nhiên:
- Người dùng thường xuyên hoán đổi vị trí skill khi tự chơi thủ công.
- Khi khởi động bot, nếu vị trí skill trên Action Bar không khớp với cấu hình bot:
  - Bot sẽ tung sai chiêu (ví dụ cần né bằng skill di chuyển lại bấm vào buff hoặc xả finisher).
  - Vi phạm bất biến chiến đấu, gây tụt hiệu suất hoặc tử trận trong map.

### 1.2. Mục tiêu hệ thống
1. **Tự động cấu hình & đồng bộ phím tắt (Auto Skill Binder)**: Tự động click vào các ô slot trên Action Bar, mở pop-up `ACTIONS / SKILLS / GEM SKILLS`, quét và chọn chính xác kỹ năng theo cấu hình mong muốn.
2. **Thực thi ngầm không chiếm chuột (Non-Hijacking Execution)**: Toàn bộ quá trình mở slot, chọn ngọc kỹ năng và đóng pop-up phải diễn ra qua Win32 `PostMessageW` và `VK_ESCAPE`, không di chuyển con trỏ chuột vật lý của người dùng đang làm việc ở nửa trái màn hình.
3. **Thích ứng đa độ phân giải (Resolution Agnostic)**: Tự động co giãn theo tỷ lệ Client Area (`1189x891`, `1920x1080`, `2560x1440`).
4. **Nghiên cứu & Tích hợp Kho Dữ Liệu RePoE2 & poe2-api-client**: Tận dụng cơ sở dữ liệu mở để hoàn thiện Base Items, Affixes và Dynamic Market Pricing.

---

## 2. HÌNH HỌC ACTION BAR & POP-UP SKILL MENU (GEOMETRY SSoT)

Dựa trên đo đạc thực nghiệm 100% trên game client thật (`1189x891` windowed mode):

```
Client Width: W, Client Height: H

Action Bar Slots (y_ratio = 0.9652):
- Slot Q  : x_ratio = 0.6686
- Slot E  : x_ratio = 0.7065
- Slot R  : x_ratio = 0.7443
- Slot T  : x_ratio = 0.7822
- Slot F  : x_ratio = 0.8200
- Slot RMB: x_ratio = 0.8663

Pop-up Skill Menu Geometry:
- width_ratio  = 0.2035 (242px / 1189)
- height_ratio = 0.3311 (295px / 891)
- margin_bottom_ratio = 0.0224 (20px / 891, khoảng cách từ đáy popup tới ô slot)

Nội bộ Pop-up (Tọa độ chuẩn hóa [0.0..1.0]):
- Nút Close [X] góc trên phải: x = 0.9628, y = 0.0441
- ACTIONS -> Clear/Unbind [X] to: x = 0.5000, y = 0.2203
- SKILLS (Hàng 3 kỹ năng vũ khí): y = 0.4915, cols_x = (0.186, 0.413, 0.640)
- GEM SKILLS (Lưới ngọc kỹ năng 4 cột): start_y = 0.7797, row_spacing = 0.1864, cols_x = (0.120, 0.343, 0.566, 0.789)
```

---

## 3. THUẬT TOÁN NHẬN DIỆN TRẠNG THÁI POP-UP (DUAL GOLD/DARK DETECTOR)

Hàm `SkillPopupScanner.is_popup_open()` sử dụng cơ chế kiểm thử kép:
1. **Đường viền vàng đồng trên cùng (`gold_ratio >= 0.55`)**:
   - Quét đường ngang tại `y = top` từ `left + 15` đến `right - 15`.
   - Điều kiện màu viền vàng đồng POE2 UI: `60 < R < 140, 50 < G < 110, B < 80`.
   - Trên ảnh popup mở thực tế: đạt tỷ lệ **92.9%** (so với 28.6% trên nền cát Hideout).
2. **Dải nền nội thất tối đen (`dark_ratio >= 0.40`)**:
   - Quét dải pixel ngay dưới viền tại `y = top + int(center_h * 0.05)`.
   - Điều kiện màu nền UI đen tuyền: `R < 45, G < 40, B < 35`.
   - Trên ảnh popup mở thực tế: đạt tỷ lệ **78.6%** (so với 4.8% trên nền cát Hideout).

---

## 4. QUY CHUẨN ĐIỀU KHIỂN & ĐÓNG POP-UP (RULE 7 SSoT)

- **Mở Pop-up**: Gửi `post_message_click(hwnd, slot_x, slot_y)` với `button="left"`, dwell 40ms, delay 200ms.
- **Chọn Skill**: Gửi `post_message_click(hwnd, skill_x, skill_y)` với `button="left"`.
- **Đóng Pop-up**:
  - Phím `Spacebar` **KHÔNG** đóng được Skill Pop-up.
  - BẮT BUỘC gửi phím **`VK_ESCAPE` (`0x1B`)** qua `post_message_key(hwnd, VK_ESCAPE)`.

---

## 5. ĐÁNH GIÁ & KẾ HOẠCH TÍCH HỢP REPOE2 VÀ POE2-API-CLIENT

### 5.1. RePoE2 (`repoe-fork/repoe` & `repoe-fork.github.io`)
- **Trạng thái**: [ĐÃ TẢI & KIỂM CHỨNG THÀNH CÔNG]
- **Mốc thời gian cập nhật của RePoE2**: `15/09/2026 13:49:18 UTC` (Phiên bản 0.5.5.2 / 4.5.5.2).
- **Kết luận thẩm định**: Dữ liệu được export **SAU KHI** GGG phát hành bản 0.5.5 (05/09/2026). Không cần giải mã lại file `Content.ggpk` 161.9 GB.
- **Danh mục file đã tích hợp vào `data/repoe2/`**:
  - `data/repoe2/gems_minimal.json` (3.99 MB, 1,062 ngọc kỹ năng POE2).
  - `data/repoe2/stat_translations.json` (12.63 MB, 11,257 bản dịch affix chuẩn hóa).
  - `data/repoe2/stat_value_handlers.json` (250 KB).
  - `data/repoe2/uniques.json` (591 KB, cơ sở dữ liệu đồ Unique POE2).
  - `data/repoe2/item_classes.json` (17.6 KB).
  - `data/repoe2/default_monster_stats.json` (18 KB).
  - `data/repoe2/metadata.json` (Ghi nhận nguồn, commit hash và phiên bản game).

### 5.2. poe2-api-client / Market APIs (`api.poe2scout.com`)
- **Bản chất**: REST client kết nối sàn giao dịch POE2 (Trade API / poe2scout / poe.ninja).
- **Tiềm năng ứng dụng**:
  - Cập nhật tỷ giá Currency thời gian thực (Exalted Orb, Divine Orb, Mirror, Chaos Orb).
  - Tự động điều chỉnh ngưỡng lọc nhặt đồ (Dynamic Pickit Threshold) theo diễn biến giá thị trường.
- **Chiến lược triển khai**: Chạy nền dưới dạng worker service độc lập trong Tier 2 (Cold Path 0.05Hz - 1 lần/phút), cache vào `market_advisor.py` và giải phóng GIL.

---

## 6. KẾT QUẢ KIỂM THỬ THỰC NGHIỆM (EMPIRICAL VERIFICATION)

- **Unit Tests**: `tests/test_skill_binder.py` đạt **9/9 tests PASS (0.101s)**.
  - Bao gồm kiểm thử trên 100% dữ liệu ảnh chụp thật `captures/20260916_224410_720_LIVE_CLICK_SLOT_E.png` và `captures/20260916_224834_630_LIVE_CLOSE_POPUP_ESC.png`.
- **Toàn bộ Test Suite**: `tests/` đạt **105/105 tests PASS (19.633s)**, không có bất kỳ hồi quy hay rò rỉ tài nguyên nào.