# Đặc Tả Kỹ Thuật: Cơ Chế Unique Flasks & Duy Trì Rage Khi Đánh Boss (PoE 2 v0.5.5)

- **Mã Đặc Tả**: `SPEC-COMBAT-UNIQUE-FLASKS-BOSS-RAGE-2026`
- **Mốc Thời Gian / Phiên Bản**: `16/09/2026` — Path of Exile 2 v0.5.5b (Client Build `6AA2213C`)
- **Trạng Thái Kiến Trúc**: **HOÀN THÀNH & ĐÃ XÁC MINH (COMPLETED & VERIFIED)**

---

## 1. Bối Cảnh & Phân Tích Hiện Trạng

### 1.1. Hiện Trạng Nhận Diện Trang Bị Đeo Trên Người (Equipped Items)
- **Thực tế bộ nhớ RAM**:
  - Bot hiện tại **CHƯA** quét/đọc trực tiếp con trỏ RAM danh sách các slot trang bị nhân vật đang mặc trên người (`Head`, `Body`, `Gloves`, `Boots`, `MainHand`, `OffHand`, `Amulet`, `Ring1`, `Ring2`, `Belt`, `Flask1..5`).
  - Hệ thống hiện tại đang quản lý vật phẩm thông qua 2 tầng:
    1. **Optical Inventory Scanner**: Quét lưới 60 ô balo (Inventory 12x5) qua thị giác máy tính để phát hiện ô trống/đầy và nhận diện Waystone hàng đầu tiên.
    2. **Item Hover Watcher & Pickit OCR Tooltip**: Phân tích thông số đồ rơi dưới đất (Ground Items) hoặc rê chuột đọc Tooltip trong túi đồ để giám định/phân loại đồ.
- **Giải pháp tiếp cận**:
  - Do chưa tự động đọc mod của 2 bình Unique trực tiếp từ RAM của slot Flask, cơ chế hoạt động của Flask được điều khiển chuẩn hóa thông qua cấu hình trạng thái (`ComboConfig::bossRageFlaskEnabled`, `ReflexConfig::manaEnabled`, `ReflexConfig::flaskEnabled`) và các cờ tham số CLI linh hoạt.

---

## 2. Đặc Tả Chi Tiết Cơ Chế Bình Độc Bản (Unique Flasks)

### 2.1. Unique Mana Flask (Không bấm phím 2)
- **Đặc tính**: Nhân vật trang bị bình Mana Unique có khả năng tự hồi phục liên tục / nội tại, do đó bot không bao giờ được bấm phím `2` (tránh lãng phí ngụm bình, ngắt animation và tránh kick anti-cheat).
- **Quy tắc bất biến (`INV-FLASK-NO-MANA`)**:
  - Khi `ReflexConfig::manaEnabled == false`:
    - `ReflexManager::Update` bỏ qua hoàn toàn `HandleManaFlask`.
    - `ReflexManager::TriggerManaFlask` có chốt chặn `if (!m_config.manaEnabled) return;` triệt tiêu 100% mọi lệnh bấm phím `2` từ bất kỳ subsystem nào (bao gồm cả gợi ý từ `ComboManager`).
  - Khởi động qua CLI: `--no-mana-flask` hoặc nạp cấu hình.

### 2.2. Unique Life Flask Khi Đánh Boss (Duy trì Rage sau chiêu T)
- **Đặc tính nhân vật**: Build Chaos Inoculation (CI - MaxHP 1, MaxES cao) hoặc build sử dụng bình máu Unique kích hoạt hiệu ứng duy trì Rage (Rage Sustain). Bình này không dùng để hồi máu thông thường.
- **Quy tắc bất biến (`INV-COMBAT-BOSS-RAGE-FLASK`)**:
  1. **Nhận diện Boss**: Khi phát hiện mục tiêu có `rarity >= 3` hoặc `extraFlags & 1` (Boss/Unique), bot khóa mục tiêu và lưu `activeBossId`.
  2. **Kích hoạt chiêu T**:
     - Khi giao tranh Boss, chiêu `T` (Bear Warcry / Rage Buff) được kích hoạt bởi người chơi, macro, hoặc bot tự động tung chiêu mở màn.
     - Bot ghi nhận mốc thời gian `lastTCastMs = nowMs`.
  3. **Đếm trễ 4 giây (4000ms)**:
     - Trong suốt thời gian giao tranh với Boss đó, bot liên tục kiểm tra `nowMs - lastTCastMs >= rageFlaskDelayAfterTMs` (mặc định 4000ms).
     - Khi đủ điều kiện và `!bossLifeFlaskUsed`: bot gửi phím `1` (Life Flask) qua phần cứng KMBoxNet (`USB HID 0x1E`, thời gian nhấn 40ms) và đánh dấu `bossLifeFlaskUsed = true;`.
  4. **Quy tắc 1 lần duy nhất**: Trong toàn bộ thời gian con Boss đó còn sống, bot **chỉ bấm đúng 1 lần**, tuyệt đối không bấm lặp lại.
  5. **Reset chu kỳ**: Khi con Boss tử trận (`extraFlags & 4` hoặc `currentHP == 0` hoặc biến mất khỏi radar), bot reset `activeBossId = 0`, `bossLifeFlaskUsed = false`, `lastTCastMs = 0` để sẵn sàng cho Boss tiếp theo.

---

## 3. Các Cờ Dòng Lệnh CLI Mới (Tier 1 C++ Core)

| Cờ CLI | Kiểu Dữ Liệu | Mặc Định | Ý Nghĩa Kỹ Thuật |
| :--- | :--- | :--- | :--- |
| `--no-mana-flask` | Flag | `false` | Vô hiệu hóa hoàn toàn việc bấm bình Mana (phím 2) |
| `--no-life-flask` | Flag | `false` | Vô hiệu hóa việc bấm bình Life Flask thông thường |
| `--boss-rage-flask` | Flag | `false` | Bật cơ chế bấm Life Flask [1] duy trì Rage sau chiêu T 4s khi gặp Boss |
| `--no-boss-rage-flask` | Flag | `true` | Tắt cơ chế Boss Rage Flask |
| `--rage-flask-delay` | Integer (ms) | `4000` | Thời gian trễ sau khi dùng chiêu T mới bấm Life Flask |
| `--rage-buff-vk` | Hex/Int | `0x54` ('T') | Phím tắt của kỹ năng buff Rage |

---

## 4. Kết Quả Kiểm Thử Thực Nghiệm (Definition of Done)

- **Đơn vị kiểm thử C++ (Unit Test 80)**: `TestBossRageFlaskAndUniqueFlaskInvariants` trong `tests/test_combat_reflex.cpp`.
  - Kiểm tra `manaEnabled = false`: `manaUses == 0` trong mọi tình huống.
  - Kiểm tra chuỗi trạng thái Boss: `activeBossId = 8888` $\rightarrow$ cast T $\rightarrow$ t=2000ms (chưa bấm) $\rightarrow$ t=4000ms (bấm bình [1]) $\rightarrow$ t=6000ms (không bấm lần 2) $\rightarrow$ Boss chết (reset về 0).
- **Kết quả CTest**: **844/844 PASS** (100%).
- **Kết quả Pytest**: **261/261 PASS** (100%).