# AutoPOE2 - Đặc Tả Kỹ Thuật Node Đặc Biệt, Chuỗi Nhiệm Vụ & Tiến Trình Điểm Atlas POE2 v0.5.5+ (Doc 65)
*(Atlas Special Nodes, Questlines, Passive Point Progression & Autonomous Navigation Specification)*

> **Phiên bản**: 1.0.0 (SSoT 2026)  
> **Áp dụng**: Client Path of Exile 2 (2560x1440, Patch 0.5.5+), C++23 Core, Python 3.11 Companion  
> **Liên kết kiến trúc**: [Doc 50 (Two-Tier Asymmetric Architecture)](50_two_tier_asymmetric_hybrid_architecture_specification.md), [Doc 56 (Atlas Node Selector)](56_spec_atlas_node_selector_and_map_device_orchestration.md), [Doc 61 (Autonomy Gap Audit)](61_autonomy_gap_audit_and_next_development_basis.md), [Doc 64 (Supervised Real Test)](64_supervised_real_test_procedure_and_autonomous_recovery.md)

---

## 1. Bối Cảnh & Mục Tiêu Kỹ Thuật (Timestamp Protocol 2026)

Trong quá trình vận hành tự hành trên client *Path of Exile 2* v0.5.5+ (Endgame Atlas System), hệ thống gặp phải các bài toán phân loại node trọng yếu:
1. **Lỗi click nhầm đền thờ trung tâm (The Well of Souls)**:
   - Thuật toán quang học cũ chọn node gần tâm nhất hoặc cụm màu xanh lá cây mà không phân biệt loại node, dẫn tới việc click vào `The Well of Souls` (nằm tại tâm đền thờ `(1250, 480)` @1440p).
   - `The Well of Souls` là đền thờ đặc biệt (Sanctuary / Arena), **hoàn toàn không có khay nạp Waystone hay Tablet**, mở trực tiếp bằng nút `TRAVERSE`. Khi tool cố gắng nạp Waystone bằng `Ctrl + Click`, chu trình bị fail-closed.
2. **Nhu cầu làm chuỗi nhiệm vụ cộng điểm nội tại Atlas (Atlas Passive Points)**:
   - POE2 v0.5.5+ phân bổ các điểm kỹ năng Atlas thông qua việc hoàn thành các Quest Node độc nhất trên bản đồ (như *Enigma Chamber*, *Corrupted Nexus*, *Great Beast Lair*, *The Withered Willow*, *Ruins of Kingsmarch*).
   - Tool tự hành cần có một **Hệ Thống Tri Thức (Atlas Knowledge Base)** vững chắc để hiểu bản chất của từng node, điều kiện kích hoạt, và phục vụ hai chế độ chiến lược khác nhau: **Cày Map (Farming)** và **Đi Quest Mở Điểm (Atlas Quest Rush)**.

---

## 2. Phân Loại 5 Chủng Loại Node Trên Bản Đồ Atlas POE2 v0.5.5+

```mermaid
graph TD
    Root["Atlas Map Nodes v0.5.5+"] --> Regular["1. Regular Waystone Maps<br/>Tier 1-16 | Cắm 1 Waystone | 6 Cổng Portal"]
    Root --> Tower["2. Precursor Towers<br/>Tháp Tiền Thân | Cắm 1-3 Tablets | Lan tỏa Aura"]
    Root --> SpecialArena["3. Đền Thờ & Đấu Trường Tối Cao<br/>Well of Souls/Heart of the Well, Burning Monolith, Origin Tower, Reactor, Citadels, Trials"]
    Root --> UniqueMap["4. 8 Bản Đồ Độc Bản (Unique Maps)<br/>Untainted, Zen, Kamasa, Phaaryl, Lake, Cave, Wildwood, Castaway | +2 Atlas Points"]
    Root --> QuestNode["5. Atlas Quest Nodes<br/>Enigma, Nexus, Great Beast, Willow, Kingsmarch | Mở cơ chế & +1 Atlas Point"]
```

### A. Bản Đồ Cày Thông Thường (Regular Waystone Maps)
- **Đặc điểm**: Các node bản đồ rải rác trên mạng lưới Atlas (ví dụ: *Deserted*, *Fortress*, *Creek*, *Augury*, *Wharf*).
- **Điều kiện kích hoạt**: Bắt buộc nạp 1 Waystone phù hợp với Tier map vào khay trung tâm.
- **Cơ chế hoạt động**: Bấm `TRAVERSE` tạo ra 6 cổng Portal quanh bệ đá Map Device trong Hideout.
- **Cờ hệ thống**: `accepts_waystone = True`, `accepts_tablet = False`, `is_quest_node = False`.

### B. Tháp Tiền Thân (Precursor Towers)
- **Đặc điểm**: Các cấu trúc tháp thạch anh nằm xen kẽ giữa các cụm bản đồ.
- **Điều kiện kích hoạt**: Chỉ nhận từ 1 đến 3 **Precursor Tablets** (Delirium, Breach, Ritual, Expedition...). **TUYỆT ĐỐI KHÔNG CẮM WAYSTONE**.
- **Tác dụng**: Phóng thích hiệu ứng tăng độ khó và phần thưởng cho toàn bộ các map nằm trong bán kính ảnh hưởng của tháp.
- **Cờ hệ thống**: `accepts_waystone = False`, `accepts_tablet = True`, `activation_type = "SOCKET_TABLET"`.

### C. Đền Thờ & Đấu Trường Tối Cao (Sanctuaries & Pinnacle Arenas)
1. **The Well of Souls / Heart of the Well**:
   - Đền thờ trung tâm Atlas & Chế tác Hư Hoại (vị trí tọa độ màn hình chuẩn: `(1250, 480)` @1440p).
   - Nơi giải mã 4 dòng Desecrated Modifiers trên ngọc Unique *Heart of the Well*.
   - Không nhận Waystone, không nhận Tablet. Kích hoạt trực tiếp qua nút `TRAVERSE`.
   - Bị cấm tuyệt đối trong chu trình cày Waystone tự động (`INV-ATLAS-FARM-NODE`).
2. **The Burning Monolith (Pinnacle Arbiter of Ash)**:
   - Đấu trường Cột Lửa Cổ Đại (tọa độ tham chiếu `(1043, 810)` @1440p).
   - Yêu cầu nạp 3 Mảnh Khủng Hoảng (*Ancient*, *Faded*, *Weathered Crisis Fragments*) thu thập từ 3 Citadels.
3. **Origin Tower & Precursor Reactor (Pinnacle Arbiter of Divinity - v0.5.5+)**:
   - Quần thể Tháp Cội Nguồn (*Ancient Fortress*).
   - *Patriarch Hall* & *Matriarch Hall*: Các phân khu sảnh Boss rơi *Origin Spark* và *Origin Cradle*.
   - *Precursor Reactor*: Lò Phản Ứng Tiền Thân nơi nạp 2 chìa khóa Origin để kích hoạt khiêu chiến Boss tối thượng *Arbiter of Divinity*.
4. **Citadels (Thành Lũy Boss Tối Cao - One-Life)**:
   - *Iron Citadel* (Count Geonor), *Copper Citadel* (Jamanra), *Stone Citadel* (Doryani). Chỉ cho phép vào một mạng duy nhất.
5. **Endgame Trials**:
   - *Trial of the Sekhemas* (Zarokh - Ascendancy 4 & Relics).
   - *Trial of Chaos* (The Trialmaster - Inscribed Ultimatum).
6. **League Pinnacle Arenas**:
   - *Simulacrum*, *Domain of Timeless Conflict*, *Xesht's Domain*, *The Bodach / King in the Mists*.

### D. 8 Bản Đồ Độc Bản (Unique Maps POE2 v0.5.5+)
Các bản đồ độc bản hiếm hoi trên Atlas, hoàn thành lần đầu thưởng **+2 Điểm Nội Tại Atlas** (tối đa 10 điểm từ 5 unique maps):
1. **Untainted Paradise**: Chỉ có EXP cực đại (200-400%), hoàn toàn không rơi vật phẩm, không có Boss.
2. **Moment of Zen**: Map hòa bình, không có quái vật, gặp NPC *Nameless Seer* để nhận 1 món Unique miễn phí, map tự động hoàn thành.
3. **Vaults of Kamasa**: Toàn bộ rương báu & tiền vàng khổng lồ, không có Boss truyền thống.
4. **Phaaryl Megalith**: Đấu trường thử thách liên hoàn 9-10 Boss liên tiếp (Boss Gauntlet), sát thương cực cao.
5. **The Fractured Lake**: Mọi quái Rare đều nhân đôi (mirrored x2), cuối map tương tác Đài Gương để chế tạo nhẫn/dây chuyền độc quyền.
6. **The Silent Cave**: Quái Tinh Anh bị phong ấn trong tinh thể Essence; càng giải phóng nhiều quái thì Boss cuối càng mạnh và rơi đồ xịn.
7. **Viridian Wildwood**: Khám phá rừng sương mù trong bóng tối bằng tài nguyên ánh sáng wisps (kích hoạt bằng Sacred Bloom).
8. **Castaway**: Đảo hải tặc, toàn bộ vật phẩm chuyển hóa thành Vàng, dùng bọc thuốc nổ đào kho báu triệu vàng.

> [!CAUTION]
> Trong chế độ cày Waystone thông thường (`farm_whitelist`), toàn bộ 8 Unique Maps này bị khóa chặn (`INV-ATLAS-FARM-NODE`) để tránh việc bot tự động vào nhầm map không có quái (*Moment of Zen*), map không rơi đồ (*Untainted Paradise*), hoặc bị tử nạn trước gauntlet 10 boss (*Phaaryl Megalith*).

### E. Chuỗi Node Nhiệm Vụ Atlas (Atlas Quest Nodes)
Các node cốt truyện Endgame mở khóa tính năng cơ chế và thưởng điểm nội tại Atlas (+1 Atlas Passive Point):

| Tên Node Bản Đồ | Chuỗi Nhiệm Vụ (Quest Title) | Phần Thưởng Mở Khóa | Điểm Atlas | Phương Thức Kích Hoạt |
|---|---|---|:---:|---|
| **Enigma Chamber** | *Legacy of the Precursors* | Mở khóa hệ thống Tháp Tiền Thân | **+1** | Direct Traverse |
| **Corrupted Nexus** | *Doryani's Science* | Cơ chế Hư Hoại & Nghiên cứu Doryani | **+1** | Direct Traverse |
| **Great Beast Lair** | *Hilda's Hunting* | Mở khóa săn quái & Beastcrafting | **+1** | Direct Traverse |
| **The Withered Willow** | *Strange Reflection* | Cơ chế Gương Biến Ảo Reflection | **+1** | Direct Traverse |
| **Ruins of Kingsmarch** | *The Grand Expedition* | Cơ chế Tàn Tích Viễn Chinh Expedition | **+1** | Direct Traverse |

---

## 3. Kiến Trúc Hạt Nhân Tri Thức: `AtlasKnowledgeBase`

Hạt nhân tri thức được đóng gói độc lập tại `src/assistant_tool/atlas_knowledge_base.py` tuân thủ nghiêm ngặt **Rule 4** (Module hóa, trần file < 500 dòng, không gộp monolithic):

```python
class AtlasNodeType(str, Enum):
    REGULAR_WAYSTONE_MAP = "REGULAR_WAYSTONE_MAP"
    PRECURSOR_TOWER = "PRECURSOR_TOWER"
    WELL_OF_SOULS = "WELL_OF_SOULS"
    QUEST_ENIGMA_CHAMBER = "QUEST_ENIGMA_CHAMBER"
    QUEST_CORRUPTED_NEXUS = "QUEST_CORRUPTED_NEXUS"
    QUEST_GREAT_BEAST = "QUEST_GREAT_BEAST"
    QUEST_WITHERED_WILLOW = "QUEST_WITHERED_WILLOW"
    QUEST_KINGSMARCH_RUINS = "QUEST_KINGSMARCH_RUINS"
    CITADEL_BOSS = "CITADEL_BOSS"
    TRIAL_OF_SEKHEMAS = "TRIAL_OF_SEKHEMAS"
    TRIAL_OF_CHAOS = "TRIAL_OF_CHAOS"
    GATEWAY_CHECKPOINT = "GATEWAY_CHECKPOINT"
    NOTABLE_PASSIVE_SHRINE = "NOTABLE_PASSIVE_SHRINE"
    BURNING_MONOLITH = "BURNING_MONOLITH"
    ORIGIN_TOWER = "ORIGIN_TOWER"
    PRECURSOR_REACTOR = "PRECURSOR_REACTOR"
    PATRIARCH_HALL = "PATRIARCH_HALL"
    MATRIARCH_HALL = "MATRIARCH_HALL"
    UNIQUE_MAP = "UNIQUE_MAP"
    LEAGUE_PINNACLE_ARENA = "LEAGUE_PINNACLE_ARENA"
    UNKNOWN = "UNKNOWN"
```

### Các Phương Thức Thẩm Định SSoT:
1. `AtlasKnowledgeBase.classify_node(name_or_text: str) -> AtlasNodeProfile`:
   - Phân tích tên hoặc chuỗi OCR, đối soát với danh mục alias và từ khóa để trả về hồ sơ `AtlasNodeProfile`.
2. `AtlasKnowledgeBase.accepts_waystone(name_or_text: str) -> bool`:
   - Trả về `True` nếu node cho phép cắm Waystone (chỉ `REGULAR_WAYSTONE_MAP` và `UNIQUE_MAP`).
3. `AtlasKnowledgeBase.accepts_tablet(name_or_text: str) -> bool`:
   - Trả về `True` nếu node là `PRECURSOR_TOWER`.
4. `AtlasKnowledgeBase.is_quest_node(name_or_text: str) -> bool`:
   - Xác định xem node có thuộc nhóm nhiệm vụ mở điểm kỹ năng Atlas hay không.
5. `AtlasKnowledgeBase.is_unique_map(name_or_text: str) -> bool`:
   - Xác định xem node có thuộc nhóm 8 Unique Maps hay không.
6. `AtlasKnowledgeBase.is_forbidden_for_waystone_farming(name_or_text: str) -> bool`:
   - Khóa chặn cứng (`INV-ATLAS-FARM-NODE`): Trả về `True` cho mọi node không nhận Waystone, toàn bộ Unique Maps, và Citadel Bosses khi đang chạy `farm_whitelist`.

---

## 4. Tích Hợp Hai Chế Độ Hoạch Định Chiến Lược (`AtlasStrategyPlanner`)

Module `src/assistant_tool/atlas_node_selector.py` tích hợp `AtlasKnowledgeBase` và cung cấp 2 chế độ tác chiến thông minh:

### Chế độ 1: Cày Map Kiếm Tiền (`mode = "farm_whitelist"`)
- **Mục tiêu**: Cày tối ưu các map ngon trong danh sách `preferred_maps` (ví dụ: *Deserted Map*, *Fortress Map*).
- **Hành vi lọc**:
  - Tự động loại trừ toàn bộ các map nằm trong `ignored_maps`.
  - Tự động loại trừ các node cấm qua `AtlasKnowledgeBase.is_forbidden_for_waystone_farming()`.
  - Loại trừ bán kính 200px quanh đền thờ trung tâm `(1250, 480)`.
- **Hành động**: Nạp Waystone từ ô bất kỳ trong túi đồ -> Bấm `TRAVERSE`.

### Chế độ 2: Quét Nhiệm Vụ Mở Điểm Atlas (`mode = "atlas_quest_rush"`)
- **Mục tiêu**: Nhanh chóng đưa nhân vật cày full điểm thụ động Atlas (Atlas Passive Tree).
- **Hành vi lọc**:
  - Ưu tiên số 1: Tìm kiếm các `AtlasNode` thỏa mãn `is_quest_node == True` và `is_reachable == True`.
  - Bỏ qua yêu cầu nạp Waystone đối với các Quest Node Direct Traverse.
- **Hành động**: Click chọn Quest Node -> Bấm trực tiếp nút `TRAVERSE` để vào đấu trường nhiệm vụ.

---

## 5. Bảng Tổng Hợp Mã Bất Biến Kiến Trúc Bổ Sung (Master Invariant Extensions)

| Mã Bất Biến | Quy Tắc Thực Thi | Module Giám Sát |
|---|---|---|
| **INV-ATLAS-FARM-NODE** | Tuyệt đối CẤM chọn The Well of Souls, Precursor Tower, hoặc Pinnacle Arenas cho chu trình cày Waystone tự động. Nếu OCR phát hiện 'WELL OF SOULS' sau khi click, lập tức hủy chọn và chuyển node. | `vision_ocr.py`, `autonomous_mapping_coordinator.py`, `atlas_node_selector.py` |
| **INV-ATLAS-QUEST-PROG** | Nhận diện đúng điều kiện kích hoạt giữa Direct Traverse, Socket Waystone và Socket Tablet. Không cố gắng cắm Waystone vào node Direct Traverse. | `atlas_knowledge_base.py`, `atlas_node_selector.py` |
| **INV-ATLAS-HOVER-VERIFY** | Phải hover chuột tối thiểu 150ms và xác nhận nhãn node trên màn hình trước khi phát lệnh kích hoạt. | `atlas_node_selector.py`, `MapDeviceHandler` |