# 70. Đặc Tả Kỹ Thuật: Thuật Toán Duyệt Đồ Thị Atlas Node Progression, Giải Quyết Triệt Để GAP Doc 61 & Luồng Tự Động Hóa Currency Exchange (Phím '/')

> **Mã Tài Liệu**: `SPEC-DOC-70-ATLAS-GRAPH-PROGRESSION-AND-CURRENCY-EXCHANGE-20260918`  
> **Mốc Thời Gian**: `18/09/2026 - 00:15:00` (UTC+7)  
> **Phiên Bản Game Tham Chiếu**: Path of Exile 2 v0.5.5+ (Build `6AA2213C`, x64 Windows Client)  
> **Đơn Vị Chịu Trách Nhiệm**: Sư đoàn 3 — Lead Economy & Atlas Director (AutoPOE2)  
> **Trạng Thái**: `[APPROVED FOR IMPLEMENTATION / SSoT 2026]`  
> **Phạm Vi**: `src/assistant_tool/atlas/`, `src/assistant_tool/currency_exchange/`, `tools/autonomous_mapping_coordinator.py`, `docs/development/`  
> **Bề Mặt Cấm Chạm (Forbidden Surface)**: `src/core/memory/**`, `src/core/input/**` (Bảo toàn 100% Hot Path)  
> **Tuân Thủ Quy Chuẩn**: Rule 1 (Two-Tier Architecture), Rule 2 (Context 2026), Rule 3 (Living Docs & Atomic Commit), Rule 4 (Kiến Trúc Module Hóa Anti-Monolithic), Rule 5 (Empirical DoD & 100% Dữ Liệu Thật), Rule 7 (Chuẩn Người Chơi Thật & Non-Hijacking).  
> **Tài Liệu Căn Cứ**:
> - [`docs/development/61_autonomy_gap_audit_and_next_development_basis.md`](./61_autonomy_gap_audit_and_next_development_basis.md) (SSoT Hàng Đợi Tự Hành & 7 GAP Gốc)
> - [`docs/development/69_autonomous_endgame_loop_closure_and_resilience_specification.md`](./69_autonomous_endgame_loop_closure_and_resilience_specification.md) (Khép Kín Chu Trình Tự Hành Endgame & Hậu Cần Hòm Đồ)
> - [`docs/development/56_spec_atlas_node_selector_and_map_device_orchestration.md`](./56_spec_atlas_node_selector_and_map_device_orchestration.md) (Bộ Điều Phối Atlas Node Selector & Nạp Precursor Tablet)
> - [`docs/development/65_atlas_special_nodes_questlines_and_progression_specification.md`](./65_atlas_special_nodes_questlines_and_progression_specification.md) (Node Đặc Biệt & Chuỗi Nhiệm Vụ Atlas)
> - [`docs/development/68_poe2_market_pricing_and_dynamic_pickit_specification.md`](./68_poe2_market_pricing_and_dynamic_pickit_specification.md) (Cập Nhật Giá POE2 Scout Real-time & Dynamic Pickit >= 1 Chaos)

---

## 1. BỐI CẢNH & TUYÊN BỐ VẤN ĐỀ (EXECUTIVE SUMMARY & PROBLEM STATEMENT)

### 1.1. Hiện Trạng Hệ Thống Sau Doc 61 & Doc 69
Sau các đợt tái cấu trúc và giải quyết các lỗ hổng căn bản:
- **Hot Path 120Hz (C++23)**: Đã hoàn thiện phản xạ sinh tồn CI (`HP 1/1`), Walk-to-loot $\le 22\text{u}$, Hot-reload bộ lọc Pickit thị trường $\ge 1.0\text{ Chaos}$ dưới 0.05ms, dừng bot an toàn khi F8 PAUSE (`INV-F8-MUTES-BRAIN`).
- **Cold Path Tier 2 (Python 3.11)**: Máy trạng thái [`AutonomousMappingCoordinator`](../../tools/autonomous_mapping_coordinator.py) đã tích hợp tiếp cận bệ đá Map Device 3D bằng WASD (Dwell $\ge 300\text{ms}$), click LMB mở bệ đá (`INV-KEY-NO-F-FOR-INTERACT`), nạp Waystone, bấm TRAVERSE, bước vào Portal, dọn map và mở Town Portal bằng phím `.` (`INV-KEY-PORTAL`) chuyển cảnh về Hideout.

### 1.2. Ba Khoảng Trống Nghiệp Vụ Cần Giải Quyết Triệt Để
1. **Lỗ Hổng Tiến Trình Atlas Node (The Atlas Progression & Graph Traversal Gap)**:
   - Hệ thống cũ (`AtlasNodeSelector`) chỉ chọn node dựa trên danh sách phẳng (flat candidates) trong viewport nhìn thấy tại chỗ.
   - Chưa mô hình hóa cấu trúc **Đồ thị Atlas $G = (V, E)$**: Chưa có thuật toán duyệt đồ thị (Graph Traversal) để mở khóa toàn bộ 115+ nodes từ Tier 1 tới Tier 16.
   - Thiếu cơ chế mở rộng biên (**Frontier Expansion**): Khi hoàn thành một bản đồ, các node tiếp giáp trong sương mù chưa được tự động thăng cấp thành mục tiêu kế tiếp.
   - Chưa tích hợp tối ưu hóa các cơ chế đặc biệt (**Special Encounters**): *Breach, Ritual, Delirium, Expedition*, các Thành Lũy *Citadels* và vùng phủ sóng của Tháp Tiền Thân (*Precursor Towers*).
2. **Lỗ Hổng Tự Động Hóa Ngoại Hối & Tối Ưu Hóa Tích Lũy (The Currency Exchange & Apex Wealth Gap)**:
   - Trong POE2 v0.5.5+, NPC Faustus cung cấp sàn giao dịch ngoại hối tích hợp tức thì (**Currency Exchange Market**), mở trực tiếp bằng phím tắt **`/`** (`VK_OEM_2 0xBF`) tại Hideout.
   - Toàn bộ currency phụ (`Orb of Transmutation`, `Alteration`, `Alchemy`, `Regal`, `Exalted`, `Essences`, `Runes`, `Catalysts`, `Splinters`) sau khi dọn map đang bị ứ đọng trong túi đồ hoặc hòm Stash mà không được tái đầu tư.
   - Thiếu một thuật toán tối ưu hóa danh mục tiền tệ (**Currency Cascade Waterfall**) để tự động gom toàn bộ thặng dư sang **Chaos Orb**, nâng cấp lên **Divine Orb**, và tiến tới tài sản tối thượng **Mirror of Kalandra**.
3. **Đối Soát Toàn Diện 7 Lỗ Hổng Gốc Trong Doc 61**:
   - Rà soát, khóa chặn và bảo đảm 100% tuân thủ các bất biến kiến trúc: `INV-INPUT-ABS-MOUSE`, `INV-WASD-NO-BLIND-LMB`, `INV-KEY-NO-F-FOR-INTERACT`, `INV-KEY-NO-U-FOR-MAP-DEVICE`, `INV-WASD-MIN-DWELL`, `INV-FSM-SINGLE-OWNER`, `INV-MAPDEVICE-RETRY-POLL`.

---

## 2. CHU TRÌNH TỰ HÀNH ENDGAME KHÉP KÍN TOÀN DIỆN (THE CLOSED-LOOP V3 PIPELINE)

Hệ thống nâng cấp quy trình tự hành Endgame thành **Chu trình 9 phân hệ tuần hoàn hoàn chỉnh (Closed-Loop V3 Pipeline)**:

```mermaid
flowchart TD
    subgraph HIDEOUT_LOGISTICS["PHÂN HỆ HẬU CẦN HIDEOUT (COLD PATH TIER 2)"]
        S0A["Stage 0A: Giám Định Nhanh<br/>The Hooded One (LMB Click, Opcode 8)"] --> S0B["Stage 0B: Thẩm Định Trang Bị<br/>WhatIsBetter & Lọc Đồ"]
        S0B --> S0C["Stage 0C: Cất Đồ Vào Hòm<br/>StashOrchestrator (Ctrl+Click, Jitter)"]
        S0C --> S0D["Stage 0D: Giao Dịch Ngoại Hối (MỚI)<br/>Faustus Currency Exchange (Phím '/')<br/>Consolidate Chaos -> Divine -> Mirror"]
        S0D --> S0E["Stage 0E: Bổ Sung Waystone<br/>Rút từ Stash Map Tab nếu túi < 2 viên"]
    end

    subgraph MAP_ACTIVATION["PHÂN HỆ KHỞI ĐỘNG & KÍCH HOẠT BẢN ĐỒ"]
        S1["Stage 1: Precheck Túi & Craft Waystone<br/>Alchemy Rare + Chặn Mod Brick (INV-MAP-NO-BRICK)"] --> S2["Stage 2: Tiếp Cận & Mở Map Device 3D<br/>WASD Hold >= 300ms, cự ly <= 18u, Click LMB<br/>CẤM phím F (INV-KEY-NO-F), CẤM phím U (INV-KEY-NO-U)"]
        S2 --> S3["Stage 3: Chọn Node Trên Đồ Thị Atlas & Nạp Đá<br/>AtlasGraphNavigator & AtlasProgressionPlanner<br/>Nạp Waystone + Precursor Tablets -> Click TRAVERSE"]
        S3 --> S4["Stage 4: Bước Vào Portal Chuyển Cảnh<br/>MoveMouseSmooth tới vortex xanh -> Click LMB<br/>Đối soát Client.txt hoàn tất chuyển cảnh"]
    end

    subgraph IN_MAP_LOOP["PHÂN HỆ DỌN MAP TRONG INSTANCE (HOT PATH 120HZ)"]
        S5["Stage 5: Vận Hành Dọn Map Tự Trị<br/>Frontier Fog Exploration, CI Combat, Pickit >= 1C Hot-Reload"] --> S6["Stage 6: Rút Lui An Toàn Về Hideout<br/>Clear quái 10u -> Bấm phím '.' mở Town Portal -> Thoát"]
    end

    subgraph RESILIENCE_WATCHDOG["GIÁM SÁT & PHỤC HỒI SỰ CỐ"]
        DEATH["Tử Trận: Click 'Resurrect in Hideout'<br/>Ghi Incident Dossier & Xử lý số cổng còn lại"]
        CRASH["Crash Game: Poe2ClientLauncher<br/>Tự khởi động lại & Đăng nhập Hideout"]
    end

    HIDEOUT_LOGISTICS --> MAP_ACTIVATION
    MAP_ACTIVATION --> IN_MAP_LOOP
    IN_MAP_LOOP --> HIDEOUT_LOGISTICS
    IN_MAP_LOOP -.->|Tử trận| DEATH
    DEATH --> HIDEOUT_LOGISTICS
    CRASH -.-> HIDEOUT_LOGISTICS
```

---

## 3. RÀ SOÁT & GIẢI QUYẾT TRIỆT ĐỂ 7 LỖ HỔNG GỐC TRONG DOC 61

Bảng đối soát việc giải quyết triệt để và khóa chặn các bất biến trong Doc 61:

| Mã GAP | Tên Lỗ Hổng Gốc (Doc 61) | Bất Biến Kiến Trúc Bắt Buộc | Giải Pháp Kỹ Thuật Đã Đóng & Kiểm Chứng | Trạng Thái |
|---|---|---|---|:---:|
| **GAP-1** | Chuột tương đối, phím U, mất TRAVERSE, phím F nhầm skill | `INV-INPUT-ABS-MOUSE`<br/>`INV-WASD-NO-BLIND-LMB`<br/>`INV-KEY-NO-F-FOR-INTERACT`<br/>`INV-KEY-NO-U-FOR-MAP-DEVICE` | - 100% click dùng `MoveMouseSmooth` tọa độ tuyệt đối.<br/>- Xóa sạch `press_key(VK_U)` tại Hideout.<br/>- CẤM phím F (phím F là Skill 8 của Monk). Tương tác bệ đá Map Device, Portal, NPC bằng: **WASD áp sát $\le 18\text{u} \rightarrow$ `MoveMouseSmooth` $\rightarrow$ Click LMB có chủ đích**.<br/>- Nhận diện tab ENDGAME, chọn node, nạp Waystone, chờ nút TRAVERSE sáng mới click. | `LIVE-PROVEN` & `CODE-PRESENT` |
| **GAP-2** | WASD micro-tap (<150ms), nhân vật xoay tại chỗ | `INV-WASD-MIN-DWELL` | - Triệt tiêu hoàn toàn nhấp nhả 75ms/85ms.<br/>- Áp dụng cơ chế **Hold-Until-Waypoint**: giữ phím WASD liên tục khi di chuyển cùng hướng, dwell đổi hướng $\ge 300\text{ms}$ (ngắn) / $\ge 1000\text{ms}$ (dài). | `LIVE-PROVEN` & `CODE-PRESENT` |
| **GAP-3** | Terrain origin 0, resample null grid | `INV-TERRAIN-ORIGIN` | - Calibrate `worldOrigin` từ struct địa hình thật.<br/>- `TerrainGrid::RecenterIfNeeded` nạp lại ô mới từ `NativeTerrainData.IsWalkableWorld`.<br/>- Tiếp cận Map Device cấm `grid == nullptr`. | `CODE-PRESENT` |
| **GAP-4** | Combat ngắm-bấm giả, combo đếm cục bộ | `INV-CI-01`<br/>`INV-SKILL-GENUINE` | - Lọc quái vật sống thật (`type == 1 && !(flags & 4)`).<br/>- Gọi `OnSkillCastStarted` trước `AimAndCast`.<br/>- CI Reflex kích hoạt né đòn / bảo vệ theo Energy Shield thay vì Life Flask. | `LIVE-PROVEN` |
| **GAP-5** | Bán kính loot 35u không walk-to, radar thiếu | `INV-LOOT-WALK-TO` | - Mở rộng bán kính nhận diện loot lên 120u.<br/>- Nếu khoảng cách tới đồ $> 22\text{u}$: Kích hoạt **Walk-To-Loot** qua phím WASD áp sát $\le 22\text{u}$ rồi mới nhấp LMB nhặt đồ. | `CODE-PRESENT` |
| **GAP-6** | Một FSM chủ, F8 không mute BotBrain, thiếu hậu cần | `INV-FSM-SINGLE-OWNER`<br/>`INV-F8-MUTES-BRAIN`<br/>`INV-STASH-LOGISTICS-SAFE` | - `CharacterFSM` C++ ghi trạng thái vào 16-bit cao của `movementFlags` trong SHM.<br/>- F8 PAUSE tắt ngay lập tức `botBrain.Process` và nhả phím WASD.<br/>- Bổ sung Stage 0 hậu cần hòm đồ (Stash) và bán rác (Vendor) trước khi sang Map Device. | `CODE-PRESENT` |
| **GAP-7** | Xung đột hai não (Opcode 96 tại Hideout) & Map Device timeout 2500ms | `INV-BRAIN-CONFLICT-GATEKEEPER`<br/>`INV-MAPDEVICE-RETRY-POLL` | - C++ Core và TownQuestEngine từ chối nhận Opcode 96 khi ở Hideout.<br/>- `MapDeviceHandler::WaitForPortals` mở rộng cửa sổ retry polling lên 8000ms bao quát toàn bộ hoạt ảnh mở cổng portal của POE2. | `CODE-PRESENT` |

---

## 4. THIẾT KẾ KỸ THUẬT: THUẬT TOÁN DUYỆT ĐỒ THỊ ATLAS NODE PROGRESSION

Hạt nhân được tổ chức theo cấu trúc module hóa chuẩn mực tại `src/assistant_tool/atlas/`:

```
src/assistant_tool/atlas/
├── __init__.py                # Export API: AtlasGraph, AtlasPathfinder, AtlasProgressionPlanner, EncounterMatcher
├── graph.py                   # Đồ thị G = (V, E), đỉnh AtlasGraphNode, trạng thái NodeProgressionState
├── encounter_matcher.py       # Nhận diện & phân loại cơ chế Breach, Ritual, Delirium, Expedition, Citadels
├── pathfinder.py              # Thuật toán tìm đường Dijkstra / Frontier Search với hàm chi phí đa mục tiêu
└── progression_planner.py     # Bộ hoạch định chiến lược mở 100% full nodes và tối ưu hóa Precursor Towers
```

### 4.1. Cấu Trúc Đồ Thị Atlas $G = (V, E)$ & Mở Rộng Biên (Frontier Expansion)
- **Tập đỉnh $V$**: Đại diện cho các bản đồ (Tier 1 đến Tier 16), Đền thờ, Thành lũy Citadels, Unique Maps và Quest Nodes.
- **Tập cạnh $E$**: Các đường nối vật lý giữa các bản đồ kề cận trên giao diện cây Atlas.
- **4 trạng thái tiến trình (`NodeProgressionState`)**:
  1. `LOCKED`: Bản đồ đang bị khóa trong sương mù hoặc chưa có đường nối từ vùng đã đi qua.
  2. `REACHABLE_FRONTIER`: Bản đồ tiếp giáp trực tiếp với ít nhất một bản đồ đã hoàn thành, sẵn sàng kích hoạt để mở rộng biên lãnh thổ.
  3. `COMPLETED`: Đã hoàn thành bản đồ nhưng chưa đạt điều kiện thưởng Bonus Point (cần chạy lại với độ hiếm Rare).
  4. `BONUS_COMPLETED`: Đã hoàn thành bản đồ và nhận thành công +1 Điểm Nội Tại Atlas.
- **Cơ chế Mở rộng biên tự động (`mark_node_completed`)**:
  Khi một node $u$ được ghi nhận hoàn thành:
  $$\forall v \in \text{Neighbors}(u): \quad \text{If } \text{State}(v) == \text{LOCKED} \implies \text{State}(v) \leftarrow \text{REACHABLE\_FRONTIER}$$

### 4.2. Hàm Chi Phí Đa Mục Tiêu Trên Cạnh Đồ Thị (Multi-Objective Cost Function)
Chi phí di chuyển giữa 2 node kề cận $u \rightarrow v$ được lượng hóa:
$$\text{Cost}(u, v) = \max\Big(0.1, \; \text{BaseCost} + \text{StateCost}(v) + \Delta_{\text{tier}}(u, v) \cdot w_{\text{tier}} - \text{Discount}_{\text{enc}}(v)\Big)$$

Trong đó:
- $\text{BaseCost} = 1.0$.
- $\text{StateCost}(v)$:
  * $v$ là `REACHABLE_FRONTIER`: $0.2$ (Ưu tiên tối thượng mở bản đồ mới).
  * $v$ là `BONUS_COMPLETED`: $0.5$ (Đường an toàn đã mở).
  * $v$ là `COMPLETED`: $0.6$ (Cần chạy lại lấy điểm bonus).
  * $v$ là `LOCKED`: $2.0$.
- $\Delta_{\text{tier}}(u, v) = |\text{Tier}(v) - \text{Tier}(u)|$: Phạt nếu bước nhảy cấp độ quá lớn.
- $\text{Discount}_{\text{enc}}(v)$: Giảm giá chi phí đường đi nếu $v$ sở hữu các cơ chế giá trị cao (*Breach, Delirium, Ritual, Questlines*), dẫn hướng thuật toán tự nhiên uốn lượn qua các vùng đất sinh lời nhất!

### 4.3. Bốn Chiến Lược Hoạch Định Tiến Trình Atlas (`ProgressionStrategy`)
1. **`FULL_COMPLETION_RUSH` (Mở khóa 100% Full Nodes)**:
   - Quét danh sách `REACHABLE_FRONTIER`, ưu tiên dọn sạch các dải tier từ thấp đến cao (Tier 1 $\rightarrow$ Tier 16) theo nguyên lý vết dầu loang.
   - Khi không còn frontier trong giới hạn tier, tự động kích hoạt `Bonus Catchup` để hoàn thành các node chưa lấy điểm Bonus.
2. **`BONUS_POINTS_RUSH` (Săn Điểm Nội Tại Atlas)**:
   - Ưu tiên tìm đường ngắn nhất tới các Node Nhiệm Vụ cốt truyện (+1 Point: *Enigma Chamber, Corrupted Nexus, Great Beast Lair, The Withered Willow, Ruins of Kingsmarch*) và 8 Unique Maps (+2 Points).
3. **`SPECIAL_ENCOUNTER_FARM` (Khai Thác Cơ Chế Đặc Biệt)**:
   - Chấm điểm trọng số lợi nhuận: Delirium (3.2), Breach (3.0), Ritual (2.8), Expedition (2.7), nạp Precursor Tablets tương thích.
4. **`CITADEL_PINNACLE_RUSH` (Chinh Phục Boss Tối Cao)**:
   - Hoạch định đường đi ngắn nhất dẫn thẳng tới 3 Thành Lũy Boss Citadel (*Iron, Copper, Stone Citadels*) để thu thập Mảnh Khủng Hoảng (*Crisis Fragments*).

---

## 5. THIẾT KẾ KỸ THUẬT: SÀN NGOẠI HỐI TỰ ĐỘNG (FAUSTUS CURRENCY EXCHANGE VIA PHÍM '/')

Hạt nhân được đóng gói tại `src/assistant_tool/currency_exchange/`:

```
src/assistant_tool/currency_exchange/
├── __init__.py                # Export API: CurrencyExchangeOrchestrator, CurrencyPortfolioOptimizer, Models
├── models.py                  # Phân tầng tháp tiền tệ, ExchangeOrder, cấu hình dự trữ và Gold Tax
├── portfolio_optimizer.py     # Thuật toán Thác Lũy Tiến Tài Sản (Currency Waterfall Cascade)
└── exchange_orchestrator.py   # Máy trạng thái điều phối phiên giao dịch ngoại hối (Phím '/' và Spacebar)
```

### 5.1. Cơ Chế Sàn Faustus Currency Exchange Trong POE2
- **Phím tắt SSoT**: Nhấn phím **`/`** (`VK_OEM_2 0xBF`) tại Hideout hoặc Town để mở tức thời giao diện sàn.
- **Phí Giao Dịch (Gold Tax)**: Mỗi giao dịch mua/bán đều bị trừ một lượng Vàng (Gold) cố định hoặc theo tỷ lệ.
- **Đóng giao diện an toàn**: Nhấn phím **`Spacebar`** (`VK_SPACE 0x20`) để đóng hoàn toàn sàn trước khi tiếp tục các chu trình khác.

### 5.2. Mô Hình Thác Lũy Tiến Tài Sản (The Currency Waterfall Cascade)

```mermaid
flowchart TD
    subgraph TIER_4_3["TIER 4 & TIER 3: CURRENCY PHỤ & NGUYÊN LIỆU"]
        T4["Transmutation, Augmentation, Alteration<br/>Essences, Runes, Catalysts, Splinters"]
        T3["Exalted, Regal, Alchemy, Scouring<br/>Annulment, Vaal, Gemcutter, Jeweller"]
    end

    subgraph TIER_2["TIER 2: ĐƠN VỊ THANH KHOẢN CƠ SỞ"]
        CHAOS["CHAOS ORB<br/>(Duy trì tối thiểu 50 Chaos chi tiêu cơ bản)"]
    end

    subgraph TIER_1["TIER 1: CHUẨN TÍCH TRỮ GIÁ TRỊ CAO"]
        DIVINE["DIVINE ORB<br/>(1 Divine = ~140-160 Chaos | Duy trì 2 Divine)"]
    end

    subgraph TIER_0["TIER 0: ĐỈNH CAO TÀI SẢN ENDGAME"]
        MIRROR["MIRROR OF KALANDRA<br/>(1 Mirror = ~400-500 Divine Orbs)"]
    end

    T4 -->|Bán thặng dư| CHAOS
    T3 -->|Bán thặng dư| CHAOS
    CHAOS -->|Tích lũy >= 1 Divine Rate| DIVINE
    DIVINE -->|Tích lũy >= 1 Mirror Rate| MIRROR
```

#### Quy Trình 3 Pha Chuyển Đổi:
1. **Phase 1: Thu gom thặng dư Tier 4 & Tier 3 sang Chaos Orb**:
   - Đối soát số lượng sở hữu với định mức dự trữ an toàn (`min_reserve`).
   - Mọi thặng dư có giá trị $\ge 1.0\text{ Chaos}$ (dựa trên tỷ giá POE2 Scout API) được đưa vào lệnh `SELL_TO_CHAOS`.
2. **Phase 2: Gom Chaos Orb chuyển đổi sang Divine Orb**:
   - Khi $\text{Chaos Dự Phóng} - \text{min\_chaos\_reserve} \ge \text{DivineRate}$, tự động sinh lệnh `CONVERT_CHAOS_TO_DIVINE`.
3. **Phase 3: Đỉnh cao tích lũy Divine sang Mirror of Kalandra**:
   - Khi $\text{Divine Dự Phóng} - \text{min\_divine\_reserve} \ge \text{MirrorRate}$, tự động sinh lệnh `CONVERT_DIVINE_TO_MIRROR`.

### 5.3. Khóa Liên Động An Toàn & Bảo Toàn Tài Nguyên (Safety Invariants)
- **`INV-EXCHANGE-GOLD-TAX` (Bảo Toàn Quỹ Vàng)**:
  Bắt buộc kiểm tra: $\text{CurrentGold} - \text{TotalGoldTax} \ge \text{min\_gold\_reserve}$ (mặc định: 5,000 Gold). Nếu quỹ vàng không đủ, hệ thống tự động cắt tỉa các lệnh bán phụ có giá trị thấp nhất để bảo đảm không bao giờ làm cạn kiệt vàng.
- **`INV-EXCHANGE-RESERVE-SAFE` (Bảo Toàn Định Mức Sinh Tồn & Craft Map)**:
  Tuyệt đối không bán hết các nguyên liệu thiết yếu: luôn giữ lại tối thiểu 20 Alchemy, 20 Scouring, 5 Waystones, 5 Exalted, 50 Chaos, 2 Divine.
- **`INV-EXCHANGE-SLIPPAGE-GUARD` (Khóa Chống Trượt Giá)**:
  Tỷ giá trên sàn không được lệch quá $10\%$ so với giá thị trường chuẩn của POE2 Scout API. Nếu phát hiện trượt giá bất thường, lệnh bị hủy bỏ ngay lập tức.
### 5.4. Bộ Điều Phối Chốt Lời Tự Động & Phân Tầng Tài Sản (`AutoProfitTaker`)
- **Tập tin đảm nhiệm**: [`src/assistant_tool/currency_exchange/auto_profit_taker.py`](../../src/assistant_tool/currency_exchange/auto_profit_taker.py).
- **Mục tiêu**: Tự động hóa quá trình quét số dư ví và Stash Currency Tab, đối soát với các ngưỡng dự trữ an toàn (`ProfitTakingThresholds`) và tự động sinh lệnh bán thặng dư đổi sang Chaos Orb, tích lũy mua Divine Orb và hướng tới Mirror of Kalandra trên sàn Faustus.
- **Thứ tự ưu tiên lệnh (Order Priority Ranking)**:
  1. *Priority 1*: Bán các loại currency phụ thặng dư vượt ngưỡng (`SELL_TO_CHAOS`), ưu tiên các currency có giá trị Chaos kỳ vọng cao nhất lên trước.
  2. *Priority 2*: Gom Chaos Orb tích lũy mua Divine Orb (`CONVERT_CHAOS_TO_DIVINE`) khi tổng Chaos khả dụng vượt ngưỡng giá Divine.
  3. *Priority 3*: Gom Divine Orb tích lũy mua Mirror of Kalandra (`CONVERT_DIVINE_TO_MIRROR`) khi đạt đủ ngưỡng giá Mirror.
### 5.5. Bộ Quản Trị Hàng Đợi 10 Slots Sàn Faustus & Vòng Bổ Sung Waystone Tự Động (`FaustusOrderManager`)
- **Tập tin đảm nhiệm**: [`src/assistant_tool/currency_exchange/faustus_order_manager.py`](../../src/assistant_tool/currency_exchange/faustus_order_manager.py).
- **Mục tiêu**: Quản trị hàng đợi tối đa 10 slots đặt lệnh trên sàn Faustus, tự động nhận tiền tệ đã khớp khi mở sàn (phím '/') và chủ động bổ sung Waystone cấp cao khi cạn kiệt.
- **Cơ chế hoạt động**:
  1. *Quản trị 10 Slots (`FaustusOrderSlot` 0..9)*: Giám sát trạng thái từng slot (`SUBMITTED`, `COMPLETED`, `READY_TO_CLAIM`). Chặn nộp lệnh mới khi sàn đạt giới hạn 10/10 slots.
  2. *Tự động nhận tiền tệ đã khớp (`claim_all_completed_trades`)*: Quét các slot đã khớp hoàn toàn, tự động nhận tiền tệ và giải phóng slot về trạng thái trống cho phiên tiếp theo.
  3. *Tự động bổ sung Waystone cấp cao (`check_and_generate_waystone_restock`)*: Khi tổng số Waystone sở hữu $\le 3$ viên (**`INV-WAYSTONE-RESTOCK-MIN`**), tự động sinh lệnh mua 5 viên Waystone Tier 16 bằng Chaos Orb trên sàn Faustus, bảo đảm không bao giờ làm đứt gãy chu trình cày map liên tục.

---

## 6. THIẾT KẾ KỸ THUẬT: AUTO-GEM LEVELING & REAL-TIME NET WORTH ESTIMATOR

### 6.1. Module Tự Động Thăng Cấp Ngọc Kỹ Năng (`GemAutoLeveler`)
- **Tập tin đảm nhiệm**: [`src/assistant_tool/gem_auto_leveler.py`](../../src/assistant_tool/gem_auto_leveler.py).
- **Cơ chế hoạt động**:
  * Nhận diện tọa độ icon dấu cộng (+) thăng cấp ngọc ở rìa phải màn hình (1440p: $X=2500, Y=350 + 52 \times \text{slot}$; 1080p: $X=1875, Y=262 + 39 \times \text{slot}$).
  * Bất biến an toàn sinh tồn **`INV-GEM-LEVEL-SAFE-COMBAT`**:
    - Khi ở trong Hideout hoặc Town: Cho phép thăng cấp an toàn ngay lập tức.
    - Khi ở trong Map chiến đấu: Bắt buộc `in_combat == False` và khoảng cách quái vật gần nhất $> 30.0\text{u}$. Nếu quái vật $\le 30.0\text{u}$ hoặc đang giao tranh, hoãn thăng cấp (`DEFERRED_IN_COMBAT` / `DEFERRED_PROXIMITY`), tuyệt đối không gây gián đoạn nhịp combat loop 120Hz.
  * Giãn cách thao tác `cooldown_ms = 500ms` chống spam click và giới hạn tối đa 3 ngọc mỗi chu kỳ.

### 6.2. Bộ Ước Lượng Tài Sản Ròng Thời Gian Thực (`NetWorthEstimator`)
- **Tập tin đảm nhiệm**: [`src/assistant_tool/currency_exchange/net_worth_estimator.py`](../../src/assistant_tool/currency_exchange/net_worth_estimator.py).
- **Cơ chế định giá**:
  * Quét toàn bộ số dư ví và hòm đồ Stash.
  * Phân loại 6 nhóm tài sản: *High Currency, Crafting Currency, Materials & Runes, Skill Gems, Endgame Maps, Miscellaneous*.
  * Quy đổi toàn bộ tài sản sang đơn vị mốc **Chaos Orb** và **Divine Orb** dựa trên tỷ giá thị trường thời gian thực từ POE2 Scout API (Doc 68).
  * Định dạng báo cáo ASCII an toàn console và bảng Markdown tổng hợp tài sản ròng sau mỗi map.

---

## 7. THIẾT KẾ KỸ THUẬT: ATLAS PASSIVE TREE PLANNER & MAX PROFIT BLUEPRINT (115+ POINTS)

### 7.1. Cấu Trúc Đồ Thị Phụ Thuộc Cây Nội Tại Atlas (`AtlasTreePlanner`)
- **Tập tin đảm nhiệm**: [`src/assistant_tool/atlas/atlas_tree_planner.py`](../../src/assistant_tool/atlas/atlas_tree_planner.py).
- **Mục tiêu**: Tối đa hóa lợi nhuận tiền tệ (Currency Maximization), tích lũy vàng dồi dào và duy trì tài nguyên bản đồ vô tận (Infinite Map Sustain) qua 115 điểm nội tại.
- **Phân kỳ 3 giai đoạn thăng tiến (Tree Phases)**:
  1. **Giai đoạn 1: Early Sustain (Points 1 - 35)**:
     - Tối ưu hóa tỷ lệ rơi Waystones cấp cao hơn (+1 Tier chance), tỷ lệ rơi bản đồ tiếp giáp và nhân đôi Waystone từ quái vật tinh anh.
     - Đảm bảo nhân vật tự cung tự cấp 100% tài nguyên bản đồ khi vượt từ Tier 1 lên Tier 5 mà không cần mua ngoài.
  2. **Giai đoạn 2: Mid Pack Size & Gold Reserve (Points 36 - 75)**:
     - Tăng mật độ quái vật (+4% Pack Size), tỷ lệ quái Rare (+15% Rare Monsters).
     - Gia tăng sản lượng Vàng rơi (+50% Gold Multiplier) và mở khóa giảm thuế sàn ngoại hối của Faustus, cung cấp nguồn vốn vàng dồi dào phục vụ cơ chế Thác Ngoại Hối (Stage 0D).
  3. **Giai đoạn 3: Endgame League Mechanics & Apex Profit (Points 76 - 115+)**:
     - Tập trung sâu vào 4 cơ chế siêu lợi nhuận: *Breach* (+Tốc độ mở và Splinters), *Delirium* (Sương mù vĩnh cửu, Cluster Jewels), *Ritual* (Giảm phí reroll, tăng tốc deferred items), *Expedition* (+Tỷ lệ Logbook và Quantity hòm đào).
     - Tích hợp *Pinnacle Apex*: Nhân đôi tỷ lệ rơi ngoại tệ cao cấp (Divine, Mirror) từ Thủ lĩnh Thành Lũy (Citadel Bosses).
- **Thuật toán Phân bổ Tự động theo Đồ thị Hướng Không Chu trình (DAG Auto Allocation)**:
  - Mỗi điểm kỹ năng [`AtlasPassiveNode`](../../src/assistant_tool/atlas/atlas_tree_planner.py) mang một danh sách tiền đề `prerequisites` và thứ tự ưu tiên `priority_order` (1..115).
  - Hàm `allocate_next_point()` kiểm tra nghiêm ngặt: Một node chỉ được phân bổ khi 100% các node tiền đề trong nhánh dẫn đường đã được kích hoạt trước đó, bảo đảm tính toàn vẹn của cây kỹ năng.

### 7.2. Dịch Vụ Điều Phối Tiến Trình & Thẩm Định Phần Thưởng Hậu Cần (`AtlasProgressionService`)
- **Tập tin đảm nhiệm**: [`src/assistant_tool/atlas/progression_service.py`](../../src/assistant_tool/atlas/progression_service.py).
- **Mục tiêu**: Tích hợp toàn diện `AtlasGraph`, `AtlasTreePlanner` và `NetWorthEstimator` thành một service hậu cần duy nhất sau khi dọn map, hoàn toàn độc lập và không can thiệp trực tiếp vào mã nguồn Coordinator (Rule 4 Anti-Monolithic).
- **Cơ chế hoạt động của `on_map_completed()`**:
  1. Cập nhật trạng thái hoàn thành bản đồ trên đồ thị `AtlasGraph` (`mark_node_completed`) và tự động kích hoạt cơ chế mở rộng biên (`Frontier Expansion`).
  2. Nếu người chơi đạt điều kiện thưởng (`bonus_completed == True`), service tự động gọi `AtlasTreePlanner.allocate_next_point()` để phân bổ điểm nội tại tiếp theo theo đúng thứ tự DAG và ràng buộc tiền đề (`INV-ATLAS-TREE-DAG`).
  3. Định giá tài sản ròng thời gian thực thông qua `NetWorthEstimator`, tính mức tăng trưởng tức thời ($\Delta \text{Chaos}$, $\Delta \text{Divine}$) so với bản đồ liền trước.
  4. Trả về cấu trúc dữ liệu tổng hợp [`MapCompletionRewardResult`](../../src/assistant_tool/atlas/progression_service.py) và hỗ trợ xuất báo cáo định dạng chuẩn Rule 5 `format_reward_report()`.

---

## 8. MA TRẬN BẤT BIẾN MỚI (NEW INVARIANTS ADDED)

| Mã Bất Biến | Mô Tả Quy Tắc | Module Giám Sát |
|---|---|---|
| **INV-ATLAS-GRAPH-PROG** | Tiến trình Atlas phải dựa trên đồ thị $G=(V,E)$ và cơ chế Frontier Expansion. Cấm chọn node nhảy cóc không liên thông trừ khi sử dụng Gateway. | `AtlasGraph`, `AtlasProgressionPlanner` |
| **INV-ATLAS-TREE-DAG** | Phân bổ điểm Cây Nội Tại Atlas phải tuân thủ nghiêm ngặt đồ thị phụ thuộc DAG. Không phân bổ node khi chưa thỏa mãn 100% prerequisites. | `AtlasTreePlanner`, `AtlasProgressionService` |
| **INV-EXCHANGE-GOLD-TAX** | Giao dịch trên sàn Currency Exchange chỉ được phép thực thi khi quỹ Vàng sau giao dịch $\ge 5,000$ Gold. | `CurrencyPortfolioOptimizer`, `CurrencyExchangeOrchestrator` |
| **INV-EXCHANGE-RESERVE-SAFE** | Nghiêm cấm bán sạch nguyên liệu cày map: luôn giữ tối thiểu 20 Alchemy, 20 Scouring, 50 Chaos, 2 Divine, 5 Waystones. | `CurrencyPortfolioOptimizer` |
| **INV-EXCHANGE-SLIPPAGE-GUARD** | Từ chối lệnh giao dịch nếu tỷ giá thực tế trượt giá $>10\%$ so với giá POE2 Scout API. | `CurrencyExchangeOrchestrator` |
| **INV-EXCHANGE-KEY-SAFE** | Mở sàn duy nhất bằng phím tắt **`/`** (`VK_OEM_2 0xBF`), đóng hoàn toàn bằng **`Spacebar`** (`VK_SPACE 0x20`) trước khi sang Stage khác. | `CurrencyExchangeOrchestrator`, `AutonomousMappingCoordinator` |
| **INV-GEM-LEVEL-SAFE-COMBAT** | Chỉ cho phép nhấp thăng cấp ngọc kỹ năng khi ngoài giao tranh và cự ly quái vật $> 30.0\text{u}$ hoặc tại Hideout/Town. Tuyệt đối không gián đoạn combat loop. | `GemAutoLeveler` |
| **INV-WAYSTONE-RESTOCK-MIN** | Khi tổng Waystone khả dụng $\le 3$ viên, tự động sinh lệnh mua Waystone Tier cao (Tier 15-16) bằng Chaos Orb trên sàn Faustus, bảo đảm không gián đoạn chu trình cày map. | `FaustusOrderManager`, `AutonomousMappingCoordinator` |

---

## 9. BẰNG CHỨNG THỰC NGHIỆM ĐỊNH LƯỢNG (EMPIRICAL DOD & TEST SUITE)

Toàn bộ các module mới được kiểm chứng thông qua bộ test tự động (User-Mode Test Harness - [MÔ PHỎNG THUẬT TOÁN HEADLESS - KHÔNG PHẢI LIVE GAME]), đạt kết quả **100% PASSED (97/97 Tests)**:

```text
============================= test session starts =============================
platform win32 -- Python 3.11.9, pytest-9.1.1, pluggy-1.6.0
rootdir: C:\Projects\AutoPOE2
configfile: pyproject.toml

collected 97 items:
- tests/test_faustus_order_manager.py: ..... (5/5 PASSED)
- tests/test_auto_profit_taker.py: ...... (6/6 PASSED)
- tests/test_atlas_progression_service.py: ..... (5/5 PASSED)
- tests/test_atlas_tree_planner.py: ..... (5/5 PASSED)
- tests/test_atlas_graph_progression.py: ........... (11/11 PASSED)
- tests/test_currency_exchange.py: ....... (7/7 PASSED)
- tests/test_closed_loop_endgame_autonomy.py: .. (2/2 PASSED)
- tests/test_closed_loop_10maps_simulation.py: . (1/1 PASSED)
- tests/test_gem_leveling_and_net_worth.py: ......... (9/9 PASSED)
- tests/test_autonomous_mapping_coordinator.py: 35/35 PASSED
- tests/test_market_pickit.py: 4/4 PASSED
- tests/test_pickit_evaluator.py: 7/7 PASSED

============================= 97 passed in 44.09s =============================
```