# 62. Đặc Tả Điểm Khởi Động Duy Nhất (Single Source of Truth Launcher Specification)

- **Mã tài liệu**: `SPEC-DOC-62-SSOT-LAUNCHER-SPECIFICATION-20260915`
- **Mốc thời gian**: `15/09/2026 13:45` (UTC+7)
- **Tác giả**: Sub-Agent Chuyên trách Tài liệu & Kiến trúc (AutoPOE2 Senior Orchestrator)
- **Phiên bản tương thích**: Path of Exile 2 (v0.5.5+ Build `6AA2213C`), C++23 / Python 3.11+
- **Trạng thái**: `[ĐÃ BAN HÀNH & HOÀN THIỆN THỰC NGHIỆM 100%]`

---

## 1. Bối Cảnh & Vấn Đề Kỹ Thuật (Problem Statement)

Trước ngày 15/09/2026, dự án AutoPOE2 tồn tại nhiều tệp khởi chạy và hướng dẫn phân mảnh:
1. `run_trading_advisor.bat` (được nhắc đến trong README.md nhưng thực tế không tồn tại trên đĩa).
2. `run_control_center_admin.bat` (chỉ là alias nhưng không có thông báo điều hướng người dùng).
3. `run_visual_tool.bat` (thuộc dự án anh em `Poe2VisualTool`, không nằm trong thư mục gốc của bot).
4. `python run_control_center.py` và `bin\Release\AutoPOE2_Core.exe` (được gọi rời rạc mà không kiểm tra môi trường hoặc quyền Administrator).

Hiện tượng này dẫn đến việc người dùng gặp lỗi phân tán:
- Thiếu quyền High Integrity (Administrator) khiến việc đọc RPM và IPC Seqlock thất bại.
- Thiếu thư viện Python (`customtkinter`, `pywin32`) khiến GUI văng ngay khi khởi động.
- Không có binary C++ Core sẵn sàng khiến phím tắt F8 không kích hoạt được bot.

---

## 2. Nguyên Tắc Cốt Lõi: Một Điểm Khởi Động Duy Nhất (SSoT Principle)

Hệ thống AutoPOE2 quy chuẩn hóa toàn bộ luồng khởi động vào duy nhất một tệp:
$$\mathbf{Entrypoint}_{\text{SSoT}} = \texttt{run\_full\_system.bat}$$

Mọi tính năng của hệ thống (Bot tự hành, Map Device, Combat Reflex, Auto Flask, Auto Loot, Auto Quest, Visual Tool và Market Intelligence) đều được kiểm soát và điều phối từ **Control Center Dashboard** sinh ra bởi launcher này.

---

## 3. Luồng Hoạt Động Của `run_full_system.bat` (Autonomous Pipeline)

```mermaid
graph TD
    A["run_full_system.bat"] --> B{"Kiểm tra Administrator?<br/>net session"}
    B -- "Chưa có Admin" --> C["Kích hoạt UAC Elevation<br/>Start-Process -Verb RunAs"]
    C --> A
    B -- "Đã có Admin" --> D["Thiết lập UTF-8 Console<br/>chcp 65001 & PYTHONUTF8=1"]
    D --> E["Xác định Môi trường Python<br/>.venv / ..venv / System"]
    E --> F{"Kiểm tra Thư viện Python<br/>customtkinter, pywin32"}
    F -- "Thiếu thư viện" --> G["Tự động pip install -r requirements.txt"]
    G --> H["Kiểm tra AutoPOE2_Core.exe"]
    F -- "Đã đủ thư viện" --> H
    H -- "Chưa có Binary" --> I["Tự động build CMake Release<br/>cmake --build build --config Release"]
    I --> J["Mở Control Center Dashboard<br/>run_control_center.py"]
    H -- "Đã có Binary" --> J
    J --> K["Người dùng bấm F8 trong Game<br/>Bot Tự Hành 120Hz Kích Hoạt!"]
```

### Chi tiết các bước tự động:
1. **Thẩm định & Nâng quyền Administrator**: Tự động gọi PowerShell UAC nếu chưa có quyền High Integrity (bắt buộc để đọc RPM từ game client).
2. **Thiết lập UTF-8 Toàn phần**: Mã hóa chuẩn UTF-8 tránh lỗi charmap khi hiển thị tên map hoặc log tiếng Việt.
3. **Quản lý Môi trường Ảo Python**: Ưu tiên `.venv\Scripts\python.exe` nội bộ; nếu thiếu thư viện, tự động cài đặt từ `requirements.txt`.
4. **Tự động Biên dịch C++ Core**: Nếu thiếu `AutoPOE2_Core.exe`, tự động kích hoạt CMake Release để tạo binary sạch trước khi mở giao diện.
5. **Khởi chạy Control Center**: Mở giao diện Dashboard đồ họa 980×680 tích hợp đầy đủ mọi công cụ.

---

## 4. Bảng Tra Cứu Phím Tắt & Tương Tác Chuẩn

| Phím Tắt / Thao Tác | Vị Trí Kích Hoạt | Chức Năng | Ghi Chú |
|---|---|---|---|
| **`F8`** (hoặc `F6`) | Trong game hoặc Control Center | **Bật / Tắt Bot Tự Hành 120Hz** | Kích hoạt Hot Path C++ Core |
| **`Pause`** / **`F12`** | Toàn hệ thống (Global) | **Dừng Khẩn Cấp (Panic Stop)** | Ngắt toàn bộ input vật lý ngay lập tức |
| **`F9`** | Trong game | **Chụp ảnh & Trích xuất Telemetry** | Lưu ảnh + metadata JSON |
| **`F10`** | Trong game | **Bộ Não Chiến Thuật (Tactical Brain)** | Đưa ra khuyến nghị thời gian thực |
| **`F11`** | Trong game | **Định Vị Lại Tọa Độ XYZ** | Quét lại pointer chuỗi bộ nhớ |
| **`LMB Click`** | Trong game (< 18u) | **Tương tác NPC / Map Device** | Chuẩn hóa thay thế phím 'F' ảo |

---

## 5. Danh Mục Tệp Được Đồng Bộ (Synchronized Artifacts)

1. `c:\Projects\AutoPOE2\run_full_system.bat` (SSoT Launcher)
2. `c:\Projects\AutoPOE2\run_control_center_admin.bat` (Redirect Alias)
3. `c:\Projects\AutoPOE2\README.md` (Quick Start Section 4.3)
4. `c:\Projects\AutoPOE2\docs\assistant_tool\README.md` (Directory tree & Launcher Guide)
5. `c:\Projects\AutoPOE2\src\assistant_tool\control_center.py` (UI Label F8/Pause)
6. `c:\Projects\AutoPOE2\src\assistant_tool\config.py` (Overlay theme comment)
7. `c:\Projects\AutoPOE2\docs\development\27_control_center_companion_contract_and_ui.md`