# TÀI LIỆU THIẾT KẾ KIẾN TRÚC: HỆ THỐNG LỌC MÀU VÀ ĐÁNH GIÁ VẬT PHẨM TỰ ĐỘNG TOÀN DIỆN (UNIVERSAL AUTO-HOVER ITEM INSPECTOR ARCHITECTURE)
> **Mã tài liệu**: `SPEC-DOC-38-UNIVERSAL-AUTO-HOVER-ITEM-INSPECTOR-20260912`
> **Mốc thời gian**: 12/09/2026 (Bối cảnh POE2 v0.5.5 / Endgame Atlas & Economy)
> **Trạng thái**: [COMPLETED / IMPLEMENTED & VERIFIED 100%] (Chi tiết triển khai tại Doc 40: `docs/development/40_item_inspector_hover_watcher_and_overlay_hud.md`)
> **Phạm vi áp dụng**: Tier 2 Python 3.11 Passive Companion HUD / ShmBridge / Overlay (`src/assistant_tool/`)
> **Tác giả**: Sub-Agent Chuyên trách Tài liệu & Kiến trúc (Documentation & Architecture Specialist)
> **Tuân thủ quy chuẩn**: Rule 2 (Mốc thời gian 2026), Rule 6 (Post-Implementation Documentation), Rule 8 (Anti-Symptom RCA), Rule 9 (Mandatory Verification Gate), Rule 10 (Zero-Drift Contract), Rule 14 (100% Authentic Real Data)
---
## 1. MỤC TIÊU & TẦM NHÌN DỰ ÁN (VISION & SCOPE)
### 1.1. Thực trạng & Nhu cầu thực chiến trong Path of Exile 2
Trong Path of Exile 2, hệ thống kinh tế, trang bị và cơ chế rơi đồ (Loot & Gear Progression) có sự phân hóa sâu sắc so với phiên bản tiền nhiệm:
1. **Khối lượng thông tin vật phẩm khổng lồ**: Mỗi phiên cày map hoặc chiến dịch, người chơi phải nhặt, giám định và đối chiếu hàng trăm vật phẩm gồm: Waystones (Bản đồ), Vũ khí, Trang bị phòng thủ, Trang sức, Bùa (Charms), Ngọc (Jewels) và Bình (Flasks).
2. **Cơ chế Chế tác Đột phá (Rune Engraving & Exalted Slamming)**:
- Trong POE2, cơ chế **Rune Forging / Engraving** cho phép đập các loại Rune vào trang bị để bổ sung thuộc tính đặc thù hoặc tạo implicit, với điều kiện vật phẩm phải còn **Open Prefix** hoặc **Open Suffix** hợp lệ.
- **Exalted Orb** trở thành đơn vị tiền tệ chế tạo phổ thông để bổ sung 1 dòng thuộc tính explicit cho vật phẩm hiếm (Rare) còn vị trí trống.
- Một món đồ có 4 hoặc 5 thuộc tính xuất sắc nhưng bị "kín dòng" (Full 6 Affixes: 3 Prefixes + 3 Suffixes) sẽ có giá trị và tiềm năng chế tác hoàn toàn khác biệt so với một món đồ có 4 dòng tương tự nhưng còn **1 Open Prefix** hoặc **1 Open Suffix**.
3. **Hiểm họa từ Thuộc tính Bản đồ (Waystones Brick Mods)**: Các thuộc tính phản đòn (Reflect Damage), triệt tiêu hút máu (No Leech), chặn hồi phục (No Life/Mana/ES Regen), hoặc hạ kháng tối đa (-Max Elemental Resistances) có thể tiêu diệt nhân vật tức thì ($<100\text{ms}$) nếu người chơi vô tình kích hoạt mà không để ý.
4. **Áp lực Thời gian & Nhận thức (Cognitive Overload)**: Việc dừng lại rà mắt đọc từng dòng chữ trong 15-20 dòng mô tả của từng món đồ gây suy giảm nghiêm trọng tốc độ dọn map (Clear Speed) và mệt mỏi cho người chơi.
### 1.2. Tầm nhìn: Universal Auto-Hover Item Inspector
Xây dựng một hệ thống **Lọc màu và Đánh giá vật phẩm tự động hoàn toàn** (Universal Auto-Hover Item Inspector) đáp ứng:
- **Tự động kích hoạt khi di chuột (Auto-Hover Passive Detection)**: Khi người dùng rê chuột lên bất kỳ vật phẩm nào trong túi đồ (Inventory), trên mặt đất, trong hòm đồ (Stash), hoặc trong Map Device và dừng lại $\ge 180\text{ms}$, hệ thống lập tức hiển thị một Tooltip Overlay mini bên cạnh con trỏ chuột.
- **Phủ sóng 100% các nhóm vật phẩm trong POE2**:
1. *Waystones (Bản đồ / Maps)*: T1 đến T16.
2. *Trang bị & Vũ khí (Gear & Weapons)*: Bows, Crossbows, Quarterstaves, Staves, Maces, Swords, Flails, Axes, Daggers, Wands, Body Armours, Helmets, Boots, Gloves, Shields, Quivers.
3. *Trang sức (Jewelry)*: Rings, Amulets, Belts.
4. *Ngọc & Bùa (Jewels & Charms)*: Attribute Jewels, Skill Jewels, Elemental/Defensive Charms.
5. *Bình (Flasks)*: Life Flasks, Mana Flasks, Utility Flasks.
- **Phân loại màu trực quan theo tiêu chuẩn thể thao điện tử**:
- 🟢 **Xanh lá (High Tier / S-Tier Reward)**: Thuộc tính Tier 1-2, DPS cực cao, Max Life/ES vượt trội, tăng mạnh Drop Quantity/Rarity/Pack Size của Map.
- 🟡 **Vàng rực / 🟣 Tím (Open Affix Alert & Crafting Potential)**: Cảnh báo vị trí Prefix/Suffix còn trống có thể đập Rune hoặc Exalted Orb.
- 🔴 **Đỏ rực (Deadly Brick Mod / Conflict)**: Mod nguy hiểm làm hỏng build (Reflect, No Leech, No Regen, -Max Res), hoặc trang bị vi phạm nặng yêu cầu chỉ số.
- ⚪ **Trắng / Xám (Neutral / Trash)**: Thuộc tính trung tính thông thường hoặc rác phân giải (Salvage Trash).
- **Tuyệt đối an toàn (Zero-Ban Risk Architecture)**: 100% Thụ động, không tiêm mã (no DLL injection), không hook đồ họa DirectX, không chỉnh sửa bộ nhớ game (`Content.ggpk`), không bị anti-cheat phát hiện.
---
## 2. KIẾN TRÚC 3 TẦNG THỤ ĐỘNG (ZERO-BAN RISK ARCHITECTURE)
```mermaid
flowchart TD
subgraph TIER1 ["TẦNG 1: SENSORS & HOVER DETECTOR (ItemHoverWatcher)"]
Win32Mouse[Win32 Mouse Hook / Polling GetCursorPos]
FocusCheck{Focus Interlock:\nGetForegroundWindow == poe_hwnd?}
DwellCheck{Dwell Timer:\nChuột đứng yên >= 180ms?}
DebounceGuard{Debounce Guard:\nKhoảng cách >= 400ms\nvới lần parse trước?}
PulseCtrlC[Win32 Keybd Pulse: Ctrl+C\n(SendInput Synthesized Keypress)]
ClipRead[Win32 Clipboard Sniffer:\nExtract CF_UNICODETEXT]
RestoreClip[Restore Previous Clipboard Content]
end
subgraph TIER2 ["TẦNG 2: PARSER & RULE ENGINE (UniversalItemInspector)"]
Sanitize[Text Sanitizer & POE2 Structure Splitter]
HeaderParse[Parse Item Class, Rarity, Name, BaseType]
PropsParse[Parse Quality, Phys/Ele DPS, Armour, ES, Evasion, Block]
ReqsParse[Parse Requirements: Level, Str, Dex, Int]
AffixParser[Affix & Mod Classifier:\nImplicit vs Explicit vs Advanced Tags]
OpenAffixEngine[POE2 Open Affix Engine:\nCount Prefixes/Suffixes & Vacancies]
MatrixScore[5-Group Rule Evaluator:\nColor Tagging & Safety Score]
end
subgraph TIER3 ["TẦNG 3: VIEW & OVERLAY (FloatingTooltipOverlay)"]
ScreenBounds[Cursor Anchor & Smart Viewport Clamping]
Win32Layered[Transparent Win32 Window:\nWS_EX_LAYERED | WS_EX_TRANSPARENT | WS_EX_NOACTIVATE]
ColorRender[High-Contrast Color Palette Rendering:\n🟢 Green | 🟡 Yellow | 🔴 Red | ⚪ Gray]
AutoDismiss[Auto-Dismiss Interlock:\nDelta Mouse > 8px -> Destroy Overlay 0ms]
end
Win32Mouse --> FocusCheck
FocusCheck -- YES --> DwellCheck
FocusCheck -- NO (Alt-Tab) --> AutoDismiss
DwellCheck -- YES --> DebounceGuard
DebounceGuard -- PASS --> PulseCtrlC
PulseCtrlC --> ClipRead
ClipRead --> RestoreClip
ClipRead --> Sanitize
Sanitize --> HeaderParse --> PropsParse --> ReqsParse --> AffixParser
AffixParser --> OpenAffixEngine --> MatrixScore
MatrixScore --> ScreenBounds
ScreenBounds --> Win32Layered
Win32Layered --> ColorRender
Win32Mouse -.->|Mouse moved > 8px| AutoDismiss
AutoDismiss -.->|Close 0ms| Win32Layered
```
### 2.1. Tầng 1: `ItemHoverWatcher` (Win32 Mouse & Clipboard Interlock)
Module chạy trên tiến trình Python Companion (Tier 2 Cold Path), độc lập với C++ Core Hot Path, đảm nhiệm:
1. **Lắng nghe vị trí chuột (Mouse Position Polling & Hooking)**:
- Sử dụng vòng lặp polling tần số $60\text{Hz}$ ($\Delta t \approx 16.6\text{ms}$) thông qua hàm Windows API `win32gui.GetCursorPos()`.
- Đo lường khoảng cách dịch chuyển Euclide giữa 2 nhịp:
$$\Delta r = \sqrt{(x_{t} - x_{t-1})^2 + (y_{t} - y_{t-1})^2}$$
2. **Khóa an toàn tiêu điểm (Focus Interlock)**:
- Trước khi thực hiện bất kỳ thao tác nào, kiểm tra cửa sổ tiền cảnh hiện tại:
$$\text{IsPoeFocused} \iff \text{win32gui.GetForegroundWindow()} == \text{poe\_hwnd}$$
- Nếu người chơi đang Alt-Tab ra trình duyệt Web, Discord, hoặc ứng dụng khác, hệ thống **đóng băng 100% thao tác**, tuyệt đối không gửi phím bấm.
3. **Cơ chế Dwell Time Detection (Ngưỡng dừng chuột)**:
- Khi $\Delta r \le 3\text{px}$, biến đếm `dwell_time_ms` tăng dần.
- Khi $\text{dwell\_time\_ms} \ge 180\text{ms}$ (ngưỡng tối ưu xác nhận người dùng đang dừng mắt đọc tooltip, loại trừ các chuyển động lướt chuột thông thường), bộ kích hoạt được kích hoạt.
4. **Xung phím an toàn (Synthesized Ctrl+C Pulse)**:
- Gửi tổ hợp phím `Ctrl + C` chuẩn xác qua Windows `SendInput` hoặc `keybd_event` với thời gian trễ phím $15\text{ms}$ giữa `KEYDOWN` và `KEYUP`.
- Cơ chế hoàn nguyên Clipboard (Clipboard Preservation): Đọc nội dung hiện tại của Clipboard người dùng, lưu vào biến đệm tạm, lấy text vật phẩm từ POE2, sau đó hoàn trả nội dung cũ lại Clipboard sau $50\text{ms}$ nếu cần để không ảnh hưởng thao tác copy/paste của người dùng.
5. **Debounce Guard (Chống Spam)**:
- Bắt buộc khoảng cách tối thiểu giữa 2 lần kích hoạt `Ctrl+C` là $400\text{ms}$ hoặc vị trí chuột phải dịch chuyển ra khỏi vùng bounding box của vật phẩm cũ trước khi nhận diện vật phẩm mới.
### 2.2. Tầng 2: `UniversalItemInspector` (POE2 Syntactic & Semantic Parser)
Module phân tích cú pháp văn bản từ clipboard của Path of Exile 2:
1. **Sanitizer & Section Splitter**:
- Tách chuỗi theo dấu phân cách chuẩn của POE2: `--------`.
- Nhận diện `Item Class:` (loại vật phẩm) và `Rarity:` (Normal, Magic, Rare, Unique).
2. **Advanced Mod Tags Extraction**:
- Phân tích cú pháp chi tiết khi vật phẩm có kèm Advanced Description (khi người dùng giữ Alt hoặc xuất từ client chuẩn):
`{ Prefix Modifier "..." (Tier: 1) — ... }`
`{ Suffix Modifier "..." (Tier: 2) — ... }`
3. **Open Affix Crafting Detection (Bộ đếm dòng trống)**:
- Xác định tổng số Prefix và Suffix hiện có.
- Đối chiếu với trần tối đa theo độ hiếm của vật phẩm trong POE2 (Magic: Max 1P/1S, Rare: Max 3P/3S).
- Xuất cảnh báo cơ hội chế tác Rune / Exalt nếu còn slot trống.
4. **Scoring & Color Assignment Matrix**:
- Đánh giá từng dòng thuộc tính theo bộ quy tắc đặc thù cho từng nhóm vật phẩm (Waystone, Weapon/Armour, Jewelry, Jewel/Charm, Flask).
### 2.3. Tầng 3: `FloatingTooltipOverlay` (HUD Bán trong suốt Tự triệt tiêu)
Module hiển thị giao diện đồ họa thông minh:
1. **Đặc tính cửa sổ Win32 tàng hình & phi chiếm tiêu điểm**:
- Cửa sổ được khởi tạo với bộ cờ mở rộng:
```c
WS_EX_LAYERED | WS_EX_TRANSPARENT | WS_EX_NOACTIVATE | WS_EX_TOPMOST
```
- `WS_EX_TRANSPARENT`: Chuột xuyên thấu qua cửa sổ 100%, không cản trở việc click vào game.
- `WS_EX_NOACTIVATE`: Cửa sổ không bao giờ cướp focus của game client, nhân vật vẫn nhận lệnh di chuyển WASD mượt mà.
- `WDA_EXCLUDEFROMCAPTURE`: Ẩn hoàn toàn khỏi các phần mềm chụp màn hình / quay video của bên thứ ba (OBS / Discord Stream).
2. **Neo vị trí thông minh (Smart Screen Anchoring)**:
- Tooltip mặc định xuất hiện lệch về phía trên bên phải con trỏ chuột: $(x + 24, y - 10)$.
- Nếu vị trí tràn viền màn hình (Edge Overflow), tự động đảo chiều sang bên trái hoặc bên dưới con trỏ chuột để luôn nằm trọn vẹn trong khung nhìn 16:9 ($1920 \times 1080$ hoặc $2560 \times 1440$).
3. **Cơ chế Tự triệt tiêu tức thì (Zero-Latency Auto-Dismiss Interlock)**:
- Ngay khi con trỏ chuột dịch chuyển $\Delta r > 8\text{px}$ so với tọa độ kích hoạt, cửa sổ overlay lập tức bị ẩn/hủy bỏ tại thời điểm **$0\text{ms}$**, trả lại màn hình thông thoáng cho người chơi.
---
## 3. ĐẶC TẢ CƠ CHẾ NHẬN DIỆN OPEN AFFIX TRONG POE2 (OPEN AFFIX CRAFTING DETECTION)
### 3.1. Tầm quan trọng sống còn của Open Affix trong POE2
Trong Path of Exile 2, hệ thống chế tạo trang bị phụ thuộc mật thiết vào cấu trúc tiền tố (Prefix) và hậu tố (Suffix):
- **Phân bổ Affix**:
- Vật phẩm Phép thuật (**Magic**): Tối đa 1 Prefix và 1 Suffix (Tổng: 2 mods).
- Vật phẩm Hiếm (**Rare**): Tối đa 3 Prefixes và 3 Suffixes (Tổng: 6 mods).
- **Cơ chế Đập Rune (Rune Engraving)**:
- Các loại Rune (ví dụ: *Rune of Power*, *Rune of the Glacial*, *Iron Rune*) khi khắc vào trang bị thường chiếm một vị trí Prefix hoặc Suffix cụ thể. Nếu trang bị đã đủ 3 Prefix, người chơi không thể khắc thêm bất kỳ Rune nào thuộc nhóm Prefix.
- **Cơ chế Exalted Slam**:
- Dùng Exalted Orb bổ sung 1 thuộc tính ngẫu nhiên vào đồ Rare chỉ có thể thực hiện nếu tổng số mod $< 6$ và nhóm mod tương ứng còn slot trống.
- **Giá trị kinh tế**:
- Một trang bị có 2 Prefix cực mạnh (ví dụ: % Physical Damage T1 và Flat Physical Damage T1) và **1 Open Prefix** là "phôi thần thánh" (God Base) có thể bán hàng chục Exalted Orbs hoặc dùng Rune để khóa cứng thuộc tính mong muốn. Nếu trang bị đó bị dính 1 Prefix rác làm đầy 3 Prefix, giá trị của nó tụt dốc 90%.
### 3.2. Thuật toán Phân định Prefix vs Suffix & Đếm Slot Trống
```mermaid
flowchart TD
Input[Dòng văn bản thuộc tính từ Clipboard]
CheckAdv{Có thẻ Advanced Tags?\n'{ Prefix ... }' hoặc '{ Suffix ... }'}
CheckAdv -- CÓ --> ParseTag[Trích xuất trực tiếp nhãn Prefix / Suffix & Tier từ thẻ]
CheckAdv -- KHÔNG --> RegexLookup[Đối chiếu từ điển Regex ngữ nghĩa POE2]
RegexLookup --> IsPrefix{Khớp từ khóa Prefix?}
IsPrefix -- CÓ --> AddPrefix[Gán vào danh sách Prefixes]
IsPrefix -- KHÔNG --> IsSuffix{Khớp từ khóa Suffix?}
IsSuffix -- CÓ --> AddSuffix[Gán vào danh sách Suffixes]
IsSuffix -- KHÔNG --> AddNeutral[Gán vào danh sách Uncategorized]
ParseTag --> AddPrefix
ParseTag --> AddSuffix
AddPrefix --> Calculate[Tổng hợp bộ đếm Affixes]
AddSuffix --> Calculate
Calculate --> EvaluateVacancies["Đếm Slot trống:
Open_Prefix = Max_Prefix - Count(Prefix)
Open_Suffix = Max_Suffix - Count(Suffix)"]
```
#### A. Phân định qua Advanced Mod Description
Khi văn bản có thẻ `{ Prefix Modifier ... }` hoặc `{ Suffix Modifier ... }`:
```regex
# Regex bắt thẻ Prefix
RE_PREFIX_TAG = r"\{\s*Prefix\s+Modifier\s+\"([^\"]+)\"\s*(?:\(Tier:\s*(\d+)\))?.*?\}\s*(.+)"
# Regex bắt thẻ Suffix
RE_SUFFIX_TAG = r"\{\s*Suffix\s+Modifier\s+\"([^\"]+)\"\s*(?:\(Tier:\s*(\d+)\))?.*?\}\s*(.+)"
```
#### B. Phân định theo Từ khóa Ngữ nghĩa Chuẩn POE2 (Fallback Deterministic Lexical Mapping)
Khi người dùng chưa bật tính năng Advanced Mod Tags trong cài đặt game, hệ thống sử dụng bảng đối chiếu ngữ nghĩa xác định $O(1)$:
| Nhóm Affix | Từ khóa Nhận dạng Đặc trưng (Regex Pattern) | Ví dụ Thực tế POE2 |
| :--- | :--- | :--- |
| **PREFIX** | `to maximum Life`, `to maximum Energy Shield`, `increased Armour`, `increased Evasion`, `increased Physical Damage`, `Adds \d+ to \d+ .* Damage`, `to Spirit`, `Movement Speed`, `+[\d]+ to Level of all .* Skill Gems` | `+85 to maximum Life`
`+115% increased Physical Damage`
`Adds 24 to 48 Fire Damage` |
| **SUFFIX** | `to (?:Fire\|Cold\|Lightning\|Chaos) Resistance`, `to all Elemental Resistances`, `increased Attack Speed`, `increased Cast Speed`, `Critical Strike Chance`, `Critical Strike Multiplier`, `to (?:Strength\|Dexterity\|Intelligence\|all Attributes)`, `reduced Attribute Requirements`, `Accuracy Rating` | `+42% to Fire Resistance`
`+18% increased Attack Speed`
`+28 to Strength` |
#### C. Công thức Bất biến Tính toán Vị trí Trống:
```python
def calculate_affix_vacancies(rarity: str, prefixes: list, suffixes: list) -> AffixCount:
if rarity == "Magic":
max_p, max_s = 1, 1
elif rarity == "Rare":
max_p, max_s = 3, 3
else:
return AffixCount(0, 0, 0, 0, 0, 0)
p_count = min(len(prefixes), max_p)
s_count = min(len(suffixes), max_s)
open_p = max_p - p_count
open_s = max_s - s_count
return AffixCount(
prefixes=p_count,
suffixes=s_count,
max_prefixes=max_p,
max_suffixes=max_s,
open_prefixes=open_p,
open_suffixes=open_s
)
```
---
## 4. BẢNG MA TRẬN QUY TẮC LỌC MÀU CHO 5 NHÓM VẬT PHẨM (COLOR FILTERING RULE MATRIX)
Hệ thống chia toàn bộ kho vật phẩm POE2 thành 5 nhóm chuyên biệt với các tiêu chí lọc màu riêng:
```
┌──────────────────────────────────────────────────────────────────────────────────┐
│ BẢNG MÀU QUY CHUẨN │
├──────────────────────────────────────────────────────────────────────────────────┤
│ 🟢 XANH LÁ (Green) : S-Tier / T1-T2 Roll / High Reward / Core Build Enabler │
│ 🟡 VÀNG / 🟣 TÍM : Open Affix Alert (Trống Prefix/Suffix) / Crafting Potential │
│ 🔴 ĐỎ RỰC (Red) : Brick Mod (Tử thần) / Danger Hazard / Stat Penalty │
│ ⚪ TRẮNG / XÁM (Gray): Mod Trung tính / Rác phân giải (Salvage Trash) │
└──────────────────────────────────────────────────────────────────────────────────┘
```
### 4.1. Nhóm 1: Waystones (Bản đồ / Maps)
*Mục tiêu*: Bảo vệ sinh mệnh tối đa, cảnh báo chết sốc khi mở map, và đo lường độ giàu có của map.
| Nhãn Màu | Tiêu chí / Modifier Cụ thể | Mức độ Ưu tiên | Hành vi Hiển thị |
| :---: | :--- | :---: | :--- |
| 🔴 **ĐỎ (Brick)** | - `Reflects (?:Physical\|Elemental) Damage`
- `Cannot Leech Life, Mana or Energy Shield`
- `Cannot Regenerate Life, Mana or Energy Shield`
- `-(?:10-20)% to all maximum Resistances` | **P0 (Tử thần)** | **CẢNH BÁO TỬ THẦN** to đỏ giữa khung, Safety Score tụt về `0/100`, yêu cầu Chaos reroll ngay. |
| 🔴 **ĐỎ (Nguy hiểm)**| - `Monsters deal (?:50-100)% extra Damage as (?:Fire\|Cold\|Lightning)`
- `Monsters have +% increased Critical Strike Chance`
- `Players are Cursed with Temporal Chains / Enfeeble` | **P1 (Cảnh giác)** | Highlight đỏ viền, cảnh báo quái đánh đau hoặc giảm tốc. |
| 🟢 **XANH LÁ (Thưởng)**| - `Waystone Tier >= 15`
- `Item Quantity >= 65%`
- `Item Rarity >= 40%`
- `Monster Pack Size >= 25%` | **Thưởng lớn** | Highlight xanh sáng, hiển thị nhãn `[RICH MAP - TĂNG THƯỞNG]`. |
| 🟡 **VÀNG / TÍM** | - Map Rare có `Affixes < 6` (còn slot để đập Exalt tăng quant).
- Map Magic có `1 Affix` (còn slot để đập Augmentation). | **Chế tác Map** | Hiển thị: `[TIỀM NĂNG EXALT MAP: CÒN TRỐNG SLOT]`. |
| ⚪ **TRẮNG** | Các thuộc tính địa hình hoặc quái thông thường (quái tăng máu, quái có thêm giáp). | **Trung tính** | Chữ xám nhạt, không tạo cảnh báo. |
---
### 4.2. Nhóm 2: Trang bị & Vũ khí (Weapons, Body Armour, Helmets, Boots, Gloves, Shields, Quivers)
*Mục tiêu*: Đánh giá sức mạnh chiến đấu, phẩm cấp chống chịu và tiềm năng chế tác vũ khí.
| Phân loại | 🟢 Xanh lá (S-Tier / T1-T2) | 🟡 Vàng / Tím (Open Affix) | 🔴 Đỏ (Xấu / Kỵ Build) |
| :--- | :--- | :--- | :--- |
| **Vũ khí (Weapons)** | - Physical DPS $\ge 350+$ (hoặc Ele DPS $\ge 450+$)
- `% increased Physical Damage` $\ge 100\%$ (T1-T2)
- `Adds # to # Physical/Cold/Fire/Lightning Damage` T1-T2
- `Attack Speed` $\ge 15\%$ | - Đồ Rare có 2 mod công T1 + **1 Open Prefix** (có thể đập Rune/Exalt Physical).
- Còn **1 Open Suffix** để craft Attack Speed / Crit. | - Roll sát thương quá thấp ($< 100$ DPS).
- Thuộc tính lạc loài (Cầm gậy phép lại có sát thương vật lý nhỏ giọt). |
| **Giáp & Khiên (Armour)**| - Flat Life $\ge 90+$ hoặc Energy Shield $\ge 250+$
- Resistance đơn $\ge 35\%$ hoặc Resistance kép $\ge 60\%$
- Body Armour có `Spirit >= 100+` | - Đồ 4-5 mods có Life/ES cao + **1 Open Prefix** (đập Rune tăng thêm % Defenses).
- Còn **1 Open Suffix** để bù kháng. | - Yêu cầu chỉ số vượt quá chỉ số nhân vật (`Requires Str 160` trong khi nhân vật chỉ có 80). |
| **Giày (Boots)** | - `Movement Speed >= 30%` (T1)
- Life/ES cao + Kháng đôi $\ge 70\%$ | - Có Movement Speed T1/T2 + **1 Open Suffix** để đập kháng nguyên tố. | - Không có Movement Speed ($0\%$). |
| **Găng tay (Gloves)**| - `Attack / Cast Speed >= 12%`
- `+1 to Level of Socketed Gems`
- High Life/ES + Kháng | - Có Attack Speed + Life + **Open Prefix/Suffix**. | - Mod rác không hỗ trợ kỹ năng chính. |
---
### 4.3. Nhóm 3: Trang sức (Rings, Amulets, Belts)
*Mục tiêu*: Tìm kiếm các nguồn cung cấp Spirit, Kháng, Sát thương chí mạng và Kỹ năng then chốt.
| Phân loại | 🟢 Xanh lá (S-Tier / T1-T2) | 🟡 Vàng / Tím (Open Affix) | 🔴 Đỏ (Xấu / Phế) |
| :--- | :--- | :--- | :--- |
| **Dây chuyền (Amulets)**| - `+1 to Level of all Skill Gems` (hoặc All Fire/Cold/Chaos Gems)
- `+ to maximum Spirit >= 80+`
- `+ to Global Critical Strike Multiplier >= 30%`
- Tổng Kháng $\ge 80\%$ | - Có `+1 Skill Gems` hoặc Spirit cao + **1 Open Prefix/Suffix** để khắc Rune độc quyền. | - Không có Spirit, không có +Skill, không có Life/ES. |
| **Nhẫn (Rings)** | - Life $\ge 70+$ hoặc ES $\ge 60+$
- Tổng Kháng $\ge 90\%$ (Triple Res)
- `Cast / Attack Speed >= 10%`
- Flat Damage added to Attacks/Spells | - Nhẫn có Kháng cao + **Open Prefix** (đập Mana/Life/ES).
- Nhẫn có Life cao + **Open Suffix** (đập Kháng còn thiếu). | - Không có kháng, các chỉ số roll bậc thấp (Tier 6-7). |
| **Thắt lưng (Belts)** | - Life $\ge 110+$ hoặc Energy Shield $\ge 120+$
- `Spirit >= 60+`
- Kháng nguyên tố $\ge 80\%$
- Flask Effect / Charges gained | - Thắt lưng có Life/Spirit vượt trội + **Open Suffix** (chế thêm kháng). | - Không có Life, không có Spirit, không có Kháng. |
---
### 4.4. Nhóm 4: Ngọc (Jewels) & Bùa (Charms)
*Mục tiêu*: Nhận diện các mảnh ghép Passive Tree và Bùa phản xạ sinh tồn đột phá.
| Phân loại | 🟢 Xanh lá (S-Tier / T1-T2) | 🟡 Vàng / Tím (Tiềm năng) | 🔴 Đỏ (Rác) |
| :--- | :--- | :--- | :--- |
| **Ngọc (Jewels)** | - `% increased maximum Life` $\ge 6\%$ hoặc `% increased maximum Energy Shield` $\ge 7\%$
- `Critical Strike Multiplier` 2 dòng $\ge 24\%$
- `% increased Damage with ...` kép | - Ngọc Magic 1 mod T1 xịn + **1 Open Suffix** (đập Regal Orb để thành Rare 3 mods). | - Mod không ăn khớp (vừa tăng minion vừa tăng sát thương cung). |
| **Bùa (Charms)** | - `Trigger when you take a Savage Hit` / `Trigger on Stagger`
- `Gain # Flask Charges when you deal a Critical Strike`
- `Elemental Damage taken recouped as Life/ES` | - Bùa có điều kiện kích hoạt trùng khớp hoàn toàn với Build hiện tại. | - Bùa có điều kiện kích hoạt vô hiệu với build (ví dụ: bùa kích hoạt khi Block trên nhân vật dùng Cung). |
---
### 4.5. Nhóm 5: Bình (Flasks)
*Mục tiêu*: Tối ưu hóa bình hồi máu, bình hồi năng lượng và bình hỗ trợ đa dụng.
| Phân loại | 🟢 Xanh lá (S-Tier / Cực xịn) | 🟡 Vàng (Cần đập đồ) | 🔴 Đỏ (Nguy hại / Rác) |
| :--- | :--- | :--- | :--- |
| **Life & Mana Flasks**| - `Instant recovery when on Low Life`
- `Quality: +20%`
- `Grants Immunity to Bleeding / Corrupted Blood`
- `Grants Immunity to Freeze / Chill` | - Bình Magic có 1 dòng xịn (Instant recovery) + **1 Open Suffix** (cần đập Orb of Augmentation để kiếm giải hiệu ứng). | - Thời gian hồi quá dài ($> 7\text{s}$) nhưng lượng hồi ít.
- Không có chất lượng (Quality 0%). |
| **Utility Flasks** | - `increased Duration >= 25%`
- `increased Effect >= 20%`
- `reduced Charges per use >= 20%` | - Bình Trắng có Base Type xịn và `Quality: 20%` (chuẩn bị đập Transmutation). | - Dòng thuộc tính phản tác dụng (ví dụ: giảm thời gian tác dụng bình). |
---
## 5. CƠ CHẾ AN TOÀN & TỰ TRIỆT TIÊU (SAFETY & AUTO-DISMISS PROTOCOL)
Nhằm tuân thủ tuyệt đối quy chuẩn **Rule 8 (Anti-Symptom Patching)** và triệt tiêu nguy cơ rò rỉ thao tác hoặc bị hệ thống chống gian lận gắn cờ, Universal Item Inspector phải tuân thủ nghiêm ngặt 4 chốt chặn an toàn:
### 5.1. Khóa An Toàn Tiêu Điểm Tuyệt Đối (Hardware Focus Interlock)
- Không bao giờ gửi phím tắt `Ctrl + C` ra môi trường Windows nếu không có bảo đảm 100% rằng cửa sổ game đang ở tiền cảnh:
```python
def ensure_poe_focus(poe_hwnd: int) -> bool:
fg_hwnd = win32gui.GetForegroundWindow()
if fg_hwnd != poe_hwnd:
return False
# Kiểm tra thêm Window Title & Class để chống giả mạo
class_name = win32gui.GetClassName(fg_hwnd)
return class_name in ["POEWindowClass", "POEC2_MainWindow"]
```
- Nếu người dùng đang gõ văn bản trên Word, duyệt web Chrome, hoặc chat Discord, phím `Ctrl + C` tuyệt đối **KHÔNG BAO GIỜ** được phát ra tự động.
### 5.2. Cơ Chế Tự Triệt Tiêu 0ms (Zero-Latency Auto-Dismiss Interlock)
- Khi cửa sổ Floating Overlay đang hiển thị:
- Nếu khoảng cách di chuyển của chuột $\Delta r > 8\text{px}$ so với vị trí neo kích hoạt: Cửa sổ lập tức gọi `ShowWindow(SW_HIDE)` hoặc `DestroyWindow()` tại $0\text{ms}$.
- Nếu cửa sổ game bị mất focus (Alt-Tab, phím Win, thông báo Windows): Cửa sổ Overlay lập tức biến mất ngay lập tức.
- Khi phím chuột trái (`VK_LBUTTON`) hoặc chuột phải (`VK_RBUTTON`) được nhấn xuống: Overlay lập tức đóng để nhường màn hình cho thao tác click/di chuyển/tấn công của người chơi.
### 5.3. Bảo Toàn Nội Dung Bộ Nhớ Đệm (Clipboard State Preservation)
- Thao tác quét tooltip sử dụng Clipboard không được làm mất chuỗi văn bản mà người dùng đã copy trước đó:
```python
class ClipboardGuard:
def __enter__(self):
self.previous_text = ""
try:
win32clipboard.OpenClipboard()
if win32clipboard.IsClipboardFormatAvailable(win32clipboard.CF_UNICODETEXT):
self.previous_text = win32clipboard.GetClipboardData(win32clipboard.CF_UNICODETEXT)
win32clipboard.CloseClipboard()
except Exception:
pass
return self
def __exit__(self, exc_type, exc_val, exc_tb):
# Hoàn nguyên lại nội dung cũ sau khi kiểm tra vật phẩm xong
if self.previous_text:
try:
win32clipboard.OpenClipboard()
win32clipboard.EmptyClipboard()
win32clipboard.SetClipboardText(self.previous_text, win32clipboard.CF_UNICODETEXT)
win32clipboard.CloseClipboard()
except Exception:
pass
```
### 5.4. Chống Xung Đột & Hiện Tượng Nháy Hình (Flicker & Thrashing Suppression)
- Khi chuột dừng trên cùng 1 vật phẩm, sau lần parse đầu tiên thành công, hệ thống chuyển sang trạng thái `STATE_DISPLAYING`. Trong trạng thái này:
- Cấm phát lại `Ctrl + C`.
- Giữ nguyên cửa sổ overlay ổn định không nhấp nháy (Zero Flicker).
- Chỉ khi chuột rời khỏi vùng giới hạn $\Delta r > 8\text{px}$ và dừng lại ở một vị trí mới, chu trình Dwell Time mới được tính lại từ đầu.
---
## 6. MA TRẬN BẤT BIẾN KIẾN TRÚC (ARCHITECTURAL INVARIANTS MATRIX)
Mọi dòng mã triển khai cho hệ thống Universal Item Inspector phải tuân thủ nghiêm ngặt 6 bất biến sau:
| Mã Bất Biến | Tên Bất Biến | Nội Dung Quy Định Bắt Buộc | Cơ Chế Khóa Chặn (Enforcement) |
| :--- | :--- | :--- | :--- |
| **`INV-INSPECT-01`** | **Zero Injected Input** | Cấm tiêm cờ phần mềm `LLMHF_INJECTED`. Mọi thao tác gửi phím tắt `Ctrl+C` phải dùng Win32 Synthesized Input an toàn hoặc thông qua KMBox Net phần cứng. | Check cờ input trong hook & log kiểm toán |
| **`INV-INSPECT-02`** | **Strict Focus Interlock** | Tuyệt đối không gửi xung `Ctrl+C` nếu `GetForegroundWindow() != poe_hwnd`. | Precondition check tại dòng đầu của hàm `TriggerInspect()` |
| **`INV-INSPECT-03`** | **Zero-Latency Dismiss** | Cửa sổ HUD phải biến mất trong vòng $<16\text{ms}$ (ngay frame tiếp theo) khi $\Delta r > 8\text{px}$ hoặc click chuột. | Polling loop 60Hz kiểm tra ngưỡng dịch chuyển tọa độ |
| **`INV-INSPECT-04`** | **Affix Count Bound** | Tổng số Prefix $\le 3$ và Suffix $\le 3$ cho đồ Rare; Prefix $\le 1$ và Suffix $\le 1$ cho đồ Magic. `open_affixes >= 0`. | `assert(0 <= open_prefixes <= max_prefixes)` |
| **`INV-INSPECT-05`** | **Zero Clipboard Loss** | Nội dung clipboard trước đó của người dùng phải được phục hồi an toàn sau chu trình inspect. | `ClipboardGuard` context manager bảo vệ dữ liệu |
| **`INV-INSPECT-06`** | **No Game File Touch** | Không đọc, ghi hoặc can thiệp tệp `Content.ggpk`, không hook Direct3D swapchain `Present()`. 100% External Overlay. | Kiến trúc Layered Window độc lập ngoài tiến trình |
---
## 7. ĐẶC TẢ THIẾT KẾ MÔ-ĐUN & GIAO DIỆN LỚP (MODULE SPECIFICATION)
### 7.1. Cấu trúc thư mục mã nguồn triển khai
```text
src/assistant_tool/
├── item_inspector/
│ ├── __init__.py
│ ├── hover_watcher.py # Tầng 1: Win32 Mouse Hook, Dwell Detection, Focus Guard
│ ├── item_parser.py # Tầng 2: POE2 Text Parser, Splitter, Advanced Mod Extractor
│ ├── affix_engine.py # Tầng 2: Phân định Prefix/Suffix, Đếm Open Slots cho POE2
│ ├── rule_evaluator.py # Tầng 2: Ma trận chấm điểm & gắn thẻ màu cho 5 nhóm đồ
│ └── tooltip_overlay.py # Tầng 3: Floating Transparent HUD, Viewport Clamping
└── run_item_inspector.py # Entry point độc lập hoặc tích hợp vào Control Center
```
### 7.2. Giao diện dữ liệu cốt lõi (`item_inspector/schemas.py`)
```python
from dataclasses import dataclass, field
from enum import Enum
from typing import List, Optional
class ItemCategory(Enum):
WAYSTONE = "WAYSTONE"
EQUIPMENT = "EQUIPMENT"
JEWELRY = "JEWELRY"
JEWEL_CHARM = "JEWEL_CHARM"
FLASK = "FLASK"
UNKNOWN = "UNKNOWN"
class HighlightColor(Enum):
GREEN = "#00FF66" # S-Tier / T1-T2 / High Reward
YELLOW = "#FFD700" # Open Affix / Craft Potential
RED = "#FF3333" # Brick Mod / Dangerous
GRAY = "#A0A0A0" # Neutral / Trash
@dataclass
class AffixInfo:
text: str
affix_type: str # "PREFIX", "SUFFIX", "IMPLICIT", "UNKNOWN"
tier: Optional[int] = None
color: HighlightColor = HighlightColor.GRAY
note: str = ""
@dataclass
class InspectionResult:
item_name: str
base_type: str
item_class: str
rarity: str
category: ItemCategory
item_level: int
prefixes_count: int
suffixes_count: int
open_prefixes: int
open_suffixes: int
safety_score: int # 0 to 100
is_brick: bool
summary_badge: str
affixes: List[AffixInfo] = field(default_factory=list)
crafting_tips: List[str] = field(default_factory=list)
```
---
## 8. CỔNG KIỂM THỬ ĐỐI CHIẾU & KẾ HOẠCH NGHIỆM THU (VERIFICATION PLAN)
Tuân thủ nghiêm ngặt **Rule 9 (Mandatory Verification Gate)** và **Rule 14 (Authentic Data Provenance)**:
### 8.1. Kiểm thử Đơn vị & Hồi quy (Unit & Regression Tests)
- Xây dựng bộ kiểm thử `tests/test_universal_item_inspector.py` sử dụng các mẫu văn bản trích xuất 100% từ client Path of Exile 2 thật:
1. `test_waystone_brick_mod_reflect`: Xác nhận Waystone có dòng phản đòn sát thương lập tức bị chấm `is_brick = True`, màu ĐỎ, Safety Score = 0.
2. `test_rare_weapon_open_prefix`: Xác nhận vũ khí Rare có 2 Prefixes T1 và 3 Suffixes tính chính xác `open_prefixes = 1`, `open_suffixes = 0`, gắn nhãn VÀNG `[TIỀM NĂNG RUNE CRAFTING]`.
3. `test_ci_ring_triple_res`: Xác nhận nhẫn có Triple Resistance và Life/ES roll cao được gắn màu XANH LÁ.
4. `test_flask_instant_recovery`: Xác nhận bình máu có dòng Instant Recovery khi Low Life được phân loại đúng nhóm FLASK và gắn màu XANH LÁ.
5. `test_auto_dismiss_distance`: Xác nhận giả lập chuột dịch chuyển $\Delta r = 9\text{px}$ kích hoạt callback ẩn overlay trong $0\text{ms}$.
### 8.2. Tiêu chuẩn Nghiệm thu Hoàn tất (Definition of Done)
- [ ] 100% các ca kiểm thử unit test và regression test vượt qua thành công (`pytest tests/test_universal_item_inspector.py`).
- [ ] Không có hiện tượng rò rỉ tiêu điểm hoặc gửi phím `Ctrl+C` khi người dùng không focus vào cửa sổ game.
- [ ] Thời gian trễ từ khi chuột dừng đủ $180\text{ms}$ đến khi Overlay hiển thị trên màn hình: $\le 45\text{ms}$.
- [ ] Thời gian ẩn Tooltip khi chuột di chuyển $> 8\text{px}$: $\le 16\text{ms}$ (tức thời $0\text{ms}$ logic).
- [ ] Không gây suy giảm FPS của game client hoặc tiêu hao CPU của C++ Core Hot Path.