# KẾ HOẠCH TRIỂN KHAI HỆ THỐNG TỰ HÀNH 1-CLICK & VÒNG ĐỜI TIẾN HÓA TOÀN DIỆN (ONE-CLICK AUTONOMOUS LIFECYCLE ENGINE: CAMPAIGN GRIND TO ENDGAME EARNING)

- **Mã Kế Hoạch**: `PLAN-AUTOPOE2-ONE-CLICK-AUTONOMOUS-2026`
- **Mốc Thời Gian Thiết Lập**: `07/09/2026 - 10:30:00`
- **Phiên Bản Áp Dụng**: Path of Exile 2 Early Access v0.5.5 (Patch 0.5.5c/d)
- **Căn Cứ Yêu Cầu Người Dùng**:
  1. *Tối giản hóa trải nghiệm người dùng tối đa*: Chỉ cần mở **1 file thực thi duy nhất (`AutoPOE2.exe`)**, không cần mở nhiều cửa sổ terminal hay thao tác nút bấm phức tạp.
  2. *Triết lý vòng đời tự hành 2 giai đoạn xuyên suốt*:
     - **Giai đoạn 1 (Chưa End Game)**: Duy nhất 1 nhiệm vụ cốt lõi là **Cày cuốc & Làm nhiệm vụ chiến dịch (Campaign Grind & Quest Progression)** từ Level 1 đến Endgame. Tự động mở map bằng phím `U`, tự động di chuyển, tự động đánh boss, tự động nhặt sách kỹ năng (Book of Skill) và nâng cấp nhân vật.
     - **Giai đoạn 2 (Đã Đạt End Game)**: Tự động chuyển tiếp sang **Giai đoạn Kiếm Tiền (Endgame Earning & Farm Maps)**: Tự động chạy map endgame, farm currency (Chaos/Divine/Gold), lọc đồ qua The Hooded One và phân tích thị trường (Market Sniffer / Arbitrage).
  3. *Tuân thủ kiến trúc 2 tầng*: Tier 1 (C++23 Core Engine 120Hz Hot Path) và Tier 2 (Python 3.11 Autonomous Lifecycle Companion) kết nối qua Lock-Free Seqlock Shared Memory IPC.

---

## 1. NGUYÊN TẮC THIẾT KẾ (CORE DESIGN PRINCIPLES)

1. **Zero-Touch 1-Executable Launcher (`AutoPOE2.exe`)**:
   - Người dùng chỉ cần mở 1 file duy nhất `AutoPOE2.exe` tại thư mục gốc.
   - Ứng dụng tự động nâng quyền Administrator (UAC self-elevation), tự động khởi động C++ Core Engine 120Hz ở chế độ nền và mở giao diện Tự Hành.
   - Tự động mở game `PathOfExile.exe` nếu game chưa bật, tự động đăng nhập và tự động chọn nhân vật.

2. **Autonomous Progression State Machine (Vòng Đời Tự Hành Độc Lập)**:
   - Hệ thống liên tục giám sát trạng thái nhân vật (Level, Khu vực hiện tại, Tiến trình nhiệm vụ).
   - Tự động quyết định hành động mà không đòi hỏi bất kỳ cú click chuột thủ công nào từ người dùng:
     - Đang ở Làng (Town Hub) & Chưa End Game $\rightarrow$ Tự bấm `U`, chọn Act, chọn Zone, dịch chuyển.
     - Đang ở Phụ bản (Combat Zone) $\rightarrow$ Tự đánh quái, né đòn, nhặt đồ, diệt boss nhiệm vụ, nhận Book of Skill.
     - Đã đạt End Game (Level $\ge 65$ hoặc mở khóa Maps) $\rightarrow$ Tự động kích hoạt chế độ **Earning & Farm Endgame**.

3. **Bảo Vệ Hiệu Năng & An Toàn Tài Khoản Tuyệt Đối**:
   - Mọi thao tác chuột đều sử dụng quỹ đạo đường cong Bézier bậc 3 (`HumanCurveGenerator`) và tương thích phần cứng KMBox Net.
   - Vòng lặp C++ 120Hz giữ vững nguyên tắc Zero Allocation / Zero Syscall.
   - Cung cấp phím nóng ngắt khẩn cấp toàn cục: **F8 (Bật/Tắt Bot)** và **Pause/Break (Panic Stop)**.

---

## 2. BẢNG TIẾN ĐỘ THỰC HIỆN TỔNG THỂ (PROGRESS DASHBOARD)

| Giai Đoạn (Phase) | Trọng Tâm Kỹ Thuật | Module Cốt Lõi | Số Task | Hoàn Thành | Tỷ Lệ (%) | Trạng Thái |
| :--- | :--- | :--- | :---: | :---: | :---: | :---: |
| **Phase 1: Autonomous Lifecycle Manager** | Xây dựng bộ não quản lý vòng đời 2 giai đoạn (Campaign Grind $\rightarrow$ Endgame Earning) | `autonomous_lifecycle.py` | 1 | 1 | 100% | [x] HOÀN THÀNH (07/09/2026) |
| **Phase 2: Ultra-Simplified 1-Click UI** | Tối giản giao diện Control Center thành Dashboard tự hành 1-Click trực quan | `control_center.py` | 1 | 1 | 100% | [x] HOÀN THÀNH (07/09/2026) |
| **Phase 3: Native Master Launcher `AutoPOE2.exe`** | Viết bộ khởi chạy C++ Master Launcher hợp nhất tự động xin UAC và quản lý 2 tiến trình | `src/launcher/main.cpp`<br/>`CMakeLists.txt` | 1 | 1 | 100% | [x] HOÀN THÀNH (07/09/2026) |
| **Phase 4: Verification & Automated Tests** | Kiểm thử chuyển trạng thái tự động và kiểm thử chạy thực thi file `AutoPOE2.exe` | `test_autonomous_lifecycle.py` | 1 | 1 | 100% | [x] HOÀN THÀNH (07/09/2026) |
| **TỔNG CỘNG** | **Hệ thống Tự Hành 1-Click & Vòng Đời Tiến Hóa** | **Toàn diện 2 tầng** | **4** | **4** | **100%** | **[x] ĐÃ NGHIỆM THU (07/09/2026)** |

---

## 3. THIẾT KẾ KIẾN TRÚC KỸ THUẬT CHI TIẾT (TECHNICAL ARCHITECTURE)

### 3.1. Sơ Đồ Chuyển Trạng Thái Vòng Đời Tự Hành (Autonomous Lifecycle State Diagram)

```mermaid
stateDiagram-v2
    [*] --> LaunchAutoPOE2: Người dùng chạy AutoPOE2.exe
    
    state LaunchAutoPOE2 {
        [*] --> CheckAdmin: Kiểm tra quyền Administrator
        CheckAdmin --> SelfElevate: Chưa có Admin -> Tự kích hoạt UAC (runas)
        CheckAdmin --> StartProcesses: Đã có Admin
        SelfElevate --> StartProcesses
        StartProcesses --> LaunchCoreEngine: Khởi chạy nền AutoPOE2_Core.exe (120Hz)
        StartProcesses --> LaunchCompanion: Khởi chạy Python Lifecycle Engine
    }

    LaunchAutoPOE2 --> CheckClientRunning: Kiểm tra PathOfExile.exe
    
    state CheckClientRunning {
        [*] --> IsClientActive: Game đang chạy?
        IsClientActive --> AutoLaunchClient: Chưa -> Mở PathOfExile.exe
        AutoLaunchClient --> AutoLoginRoutine: Tự nhập mật khẩu & Đăng nhập
        AutoLoginRoutine --> AutoSelectChar: Tự chọn nhân vật cấu hình
        IsClientActive --> ReadyInGame: Đã trong game
        AutoSelectChar --> ReadyInGame
    }

    ReadyInGame --> EvaluateProgressionState: Đọc RAM & Log Telemetry
    
    state EvaluateProgressionState {
        [*] --> CheckLevelAndArea: Kiểm tra Level, Map & Quest
        CheckLevelAndArea --> PreEndgameCampaign: Level < 65 & Đang làm Campaign
        CheckLevelAndArea --> EndgameEarning: Level >= 65 hoặc In Map Device / Hideout
    }

    state "GIAI ĐOẠN 1: CÀY CUỐC & LÀM NHIỆM VỤ (CAMPAIGN GRIND)" as PreEndgameCampaign {
        [*] --> CheckLocation
        CheckLocation --> TownActions: Đang ở Làng (Town Hub)
        TownActions --> PressUWorldMap: Tự gửi phím U mở World Map
        PressUWorldMap --> SelectNextQuestNode: Tự click Tab Act & Zone kế tiếp
        SelectNextQuestNode --> TravelToCombatZone: Tự bấm Travel
        
        CheckLocation --> CombatActions: Đang ở Phụ bản chiến đấu
        CombatActions --> AutoPathfindQuest: Dò đường theo mục tiêu nhiệm vụ
        AutoPathfindQuest --> AutoCombatAndDodge: Tự đánh quái & né đòn (120Hz)
        AutoCombatAndDodge --> SlayQuestBoss: Tiêu diệt Boss nhiệm vụ
        SlayQuestBoss --> AutoLootSkillBooks: Nhặt Book of Skill & Đồ giá trị
        AutoLootSkillBooks --> CheckQuestComplete: Nhiệm vụ hoàn thành?
        CheckQuestComplete --> TownActions: Mở Portal về Làng trả quest / qua map mới
    }

    PreEndgameCampaign --> EndgameEarning: Hoàn thành Campaign / Đạt cấp độ Endgame
    
    state "GIAI ĐOẠN 2: EARNING & ENDGAME FARMING" as EndgameEarning {
        [*] --> FarmEndgameMaps: Tự động chạy Map Endgame
        FarmEndgameMaps --> MaximizeCurrency: Gom Chaos, Divine, Exalted, Gold
        MaximizeCurrency --> ItemTriageTheHoodedOne: Giám định đồ với The Hooded One
        ItemTriageTheHoodedOne --> RealtimeArbitrageSniffer: Bật Market Sniffer & Discord Trader
        RealtimeArbitrageSniffer --> DumpToStashAndProfit: Cất hòm & Bán đồ sinh lời
    }
```

---

### 3.2. Phân Rã Nhiệm Vụ Kỹ Thuật (Work Breakdown Structure)

#### Task 1 (P0): Xây Dựng `AutonomousLifecycleManager` (Python Tier 2 Brain) - [x] ĐÃ HOÀN THÀNH (07/09/2026)
- **Tệp tạo mới**: [`src/assistant_tool/autonomous_lifecycle.py`](file:///c:/Projects/AutoPOE2/src/assistant_tool/autonomous_lifecycle.py)
- **Trọng tâm**:
  - Định nghĩa các trạng thái: `INITIALIZING`, `WAITING_FOR_GAME`, `AUTO_LOGGING_IN`, `CAMPAIGN_GRIND`, `ENDGAME_EARNING`.
  - Luồng quyết định tự hành (Decision Loop 1Hz - 2Hz):
    - Đánh giá trạng thái game qua `Poe2ClientLauncher.is_client_running()`.
    - Đánh giá vị trí nhân vật (Town vs Combat Zone).
    - Nếu ở Làng và đang trong `CAMPAIGN_GRIND`: Tự động tìm objective chưa hoàn thành từ `AutoQuester`, tự động gọi `send_trigger_world_map_travel(act, zone_index)`.
    - Tự động chuyển pha sang `ENDGAME_EARNING` khi nhân vật đạt Level 65+ hoặc vào Map Device.

#### Task 2 (P0): Tối Giản Hóa Bảng Điều Khiển Giao Diện (1-Click Autonomous UI) - [x] ĐÃ HOÀN THÀNH (07/09/2026)
- **Tệp chỉnh sửa**: [`src/assistant_tool/control_center.py`](file:///c:/Projects/AutoPOE2/src/assistant_tool/control_center.py)
- **Trọng tâm**:
  - Bổ sung Card điều hành Tự Hành Trung Tâm ở vị trí đầu tiên nổi bật nhất.
  - Hiển thị trực quan:
    - Huy hiệu trạng thái: `[🟢 ĐANG TỰ HÀNH TOÀN DIỆN]`.
    - Giai đoạn hiện tại: `🛡️ GIAI ĐOẠN 1: CÀY CUỐC & LÀM QUEST (PRE-ENDGAME)` vs `💰 GIAI ĐOẠN 2: EARNING & FARMING (ENDGAME)`.
    - Mô tả hành vi tự động hiện tại: "Đang tự động di chuyển làm quest: Dreadnought (Boss Jamanra - Book of Skill)".
  - Chỉ duy nhất 1 nút bấm lớn: `▶ BẮT ĐẦU TỰ HÀNH [F8]` (chuyển thành `⏹ DỪNG TỰ HÀNH [F8]`).
  - Mặc định khởi động tự hành mà không cần người dùng phải bấm từng nút lẻ.

#### Task 3 (P0): Xây Dựng File Thực Thi Duy Nhất `AutoPOE2.exe` (Native C++ Master Launcher) - [x] ĐÃ HOÀN THÀNH (07/09/2026)
- **Tệp tạo mới**: [`src/launcher/main.cpp`](file:///c:/Projects/AutoPOE2/src/launcher/main.cpp)
- **Tệp chỉnh sửa**: [`CMakeLists.txt`](file:///c:/Projects/AutoPOE2/CMakeLists.txt)
- **Trọng tâm**:
  - Tạo target `add_executable(AutoPOE2 src/launcher/main.cpp)`.
  - Cấu hình output ra ngay thư mục gốc: `${CMAKE_SOURCE_DIR}/AutoPOE2.exe` (Đã biên dịch thành công file thực thi 50KB).
  - Cơ chế tự nâng quyền UAC: Nếu chạy Standard User, tự động gọi `ShellExecuteExW` với verb `runas` để mở lại với quyền Admin.
  - Tự động định vị Python (`.venv\Scripts\python.exe` hoặc system python) và file thực thi C++ Core (`bin\Release\AutoPOE2_Core.exe`).
  - Khởi chạy song song 2 tiến trình: Core Engine 120Hz (ẩn console hoặc console phụ) và Python Control Center.
  - Đồng bộ vòng đời (Shutdown hooks) khi người dùng thoát launcher.

#### Task 4 (P0): Kiểm Thử Tự Động & Đảm Bảo An Toàn - [x] ĐÃ HOÀN THÀNH (07/09/2026)
- **Tệp tạo mới**: [`tests/test_autonomous_lifecycle.py`](file:///c:/Projects/AutoPOE2/tests/test_autonomous_lifecycle.py)
- **Trọng tâm**:
  - Kiểm thử chuyển đổi trạng thái giữa `CAMPAIGN_GRIND` và `ENDGAME_EARNING` (4/4 tests PASS).
  - Kiểm thử quyết định hành động tự hành trong Làng (tự kích hoạt phím `U` và dịch chuyển).
  - Biên dịch toàn bộ hệ thống bằng CMake/MSBuild tạo file `AutoPOE2.exe`.
  - Chạy bộ kiểm thử regression đảm bảo 100% test case vượt qua (25/25 Python tests PASS, 653/653 C++ assertions PASS).

---

## 4. TIÊU CHÍ NGHIỆM THU (ACCEPTANCE CRITERIA)
1. Người dùng chỉ cần click đúp vào đúng 1 file `AutoPOE2.exe` duy nhất tại thư mục dự án để bắt đầu.
2. Nếu game chưa chạy, hệ thống tự động mở game, đăng nhập và vào nhân vật.
3. Khi nhân vật chưa đạt endgame: Hệ thống tự động làm nhiệm vụ cốt truyện, tự động bấm phím `U` trong làng để mở bản đồ và tự bay tới map làm quest, tự động đánh quái và nhặt Book of Skill.
4. Khi nhân vật đạt endgame: Hệ thống tự động chuyển sang chế độ Earning, farm map và quét kèo giao dịch.
5. Không yêu cầu người dùng phải can thiệp thủ công bất kỳ nút bấm hay chọn act/map nào.