# 01. Kiến trúc Hệ thống Công cụ Hỗ trợ Người chơi (Compliant Assist Tool Architecture)

> **Mô hình**: Kiến trúc Hướng Sự kiện Bất xâm nhập (Non-Intrusive Event-Driven Architecture)  
> **Tiêu chuẩn Tuân thủ**: Chính sách Ứng dụng Bên thứ ba của Grinding Gear Games (GGG Third-Party Developer Policy)  
> **Nguyên tắc Cốt lõi**: Không can thiệp bộ nhớ (Zero Memory Access), Không tiêm mã (No DLL Injection), Tuân thủ Quy tắc 1 Thao tác - 1 Hành động (1-Action Rule).

---

## 1. Triết lý Thiết kế & Mô hình Tổng thể

Để hỗ trợ tối đa cho người chơi Path of Exile 2 mà vẫn bảo vệ an toàn tuyệt đối cho tài khoản game, công cụ được xây dựng theo mô hình **Bên ngoài Hoàn toàn (Out-of-Process External Companion)** tương tự các công cụ cộng đồng tiêu chuẩn cao nhất (như *Awakened PoE Trade*, *PoE Lurker*, *LabCompass*):

```mermaid
graph TB
    subgraph POE2_Client ["Client Trò chơi: Path of Exile 2"]
        Screen["Màn hình Hiển thị (2560x1440 Borderless)"]
        LogFile["Tệp Nhật ký: Client.txt (ưu tiên) / LatestClient.txt (fallback)"]
        Clipboard["Bộ nhớ đệm Hệ thống (Clipboard: Ctrl+C)"]
        ChatInput["Hộp thoại Chat (Nhận tin nhắn/lệnh /hideout)"]
    end

    subgraph Assist_Tool ["Hệ thống Công cụ Hỗ trợ (POE2 Assistant Core)"]
        subgraph Sensors ["Tầng Cảm biến Bất xâm nhập (Non-Intrusive Sensors)"]
            LogEngine["Cảm biến Tệp Nhật ký (Log Tailer Engine)"]
            ClipEngine["Trình bóc tách Clipboard (Item Text Parser)"]
            HotkeyEngine["Bộ lắng nghe Phím tắt Toàn cục (Global Hotkey Hook)"]
        end

        subgraph BusinessLogic ["Tầng Nghiệp vụ & Định giá"]
            MapChecker["Bộ cảnh báo Mod Nguy hiểm trên Waystone (Map Mod Warning)"]
            TradeClient["Trình kết nối Official Trade API (Rate-Limited Client)"]
            PricingEngine["Bộ lọc & Tính giá Trung vị Vật phẩm (Pricing Engine)"]
            TradeManager["Quản lý Giao dịch & Tin nhắn Thì thầm (Trade Workflow)"]
        end

        subgraph Presentation ["Tầng Giao diện Lớp phủ (Overlay Presentation)"]
            TransparentHUD["Lớp phủ Trong suốt (Transparent Overlay Window)"]
            PriceCard["Thẻ Định giá Nhanh (Quick Price Check Card)"]
            TradePanel["Bảng Thông báo Giao dịch 1-Click"]
        end
    end

    subgraph Official_Cloud ["Máy chủ Chính thức của GGG"]
        TradeAPI["Official PoE2 Trade API (pathofexile.com/api/trade2)"]
    end

    LogFile ==>|Đọc luồng I/O ngầm| LogEngine
    Clipboard ==>|Bắt phím tắt Ctrl+D/Ctrl+C| ClipEngine
    HotkeyEngine ==>|Gửi lệnh chat chuẩn| ChatInput

    LogEngine --> MapChecker
    LogEngine --> TradeManager
    ClipEngine --> TradeClient
    TradeClient <==>|Giao thức HTTPS REST| TradeAPI
    TradeClient --> PricingEngine

    PricingEngine --> PriceCard
    MapChecker --> TransparentHUD
    TradeManager --> TradePanel
    TransparentHUD -. Hiển thị trực quan .-> Screen
```

---

## 2. Chi tiết 4 Phân hệ Trọng tâm (Core Subsystems)

### 2.1. Phân hệ Lắng nghe Nhật ký (Log Telemetry Engine)
- **Nguồn dữ liệu**: Đọc luồng ghi của tệp `Client.txt` (ưu tiên) rồi `LatestClient.txt` tại thư mục `logs` của client Path of Exile 2.
- **Cơ chế**: Sử dụng Windows File I/O thông thường với cờ chia sẻ `FILE_SHARE_READ | FILE_SHARE_WRITE`. Không chiếm dụng hay can thiệp vào tiến trình game.
- **Sự kiện Giám sát**:
  1. *Chuyển khu vực (`[SCENE] Set Source [...]`)*: Tự động nhận biết nhân vật vừa bước vào Waystone mới hay quay về Hideout.
  2. *Tin nhắn Giao dịch (`@From [Player]: Hi, I would like to buy...`)*: Tự động trích xuất tên người mua, vật phẩm cần mua, giá niêm yết và tab lưu trữ.
  3. *Mở màn chơi mới (`Generating level X area Y with seed Z`)*: Kích hoạt bộ kiểm tra mod nguy hiểm nếu là bản đồ endgame.

### 2.2. Phân hệ Bóc tách Vật phẩm từ Clipboard (Clipboard Item Parser)
- **Cơ chế Giao tiếp**:
  - Khi người chơi rê chuột vào một trang bị trong game và nhấn tổ hợp phím tắt (mặc định: `Ctrl + D`):
    1. Tool tự động gửi chuỗi phím `Ctrl + C` tới cửa sổ game đang active.
    2. Game client tự động sao chép toàn bộ thuộc tính của trang bị thành văn bản thuần túy (Plaintext Item Card) vào Windows Clipboard.
    3. Tool đọc chuỗi văn bản từ Clipboard và phân tích ngữ pháp (Lexical Parsing).
- **Dữ liệu Trích xuất**:
  - Bậc hiếm (Rarity), Tên vật phẩm, Loại trang bị (Item Class: Quarterstaff, Crossbow, Spear...).
  - Chỉ số chất lượng (Quality), Sát thương cơ bản (Physical, Fire, Cold, Lightning).
  - Danh mục Tiền tố (Prefixes), Hậu tố (Suffixes), và Số lỗ khảm Ngọc (Gem Sockets).

### 2.3. Phân hệ Tra cứu Giá Thị trường Chính thức (Official Trade API Client)
- **Cơ chế Kết nối**: Gọi trực tiếp tới API chính thức của nhà phát hành: `https://www.pathofexile.com/api/trade2/search/{LeagueName}`.
- **Quản lý Hạn mức (Rate-Limiting Compliance)**:
  - Máy chủ GGG áp dụng thuật toán Leaky Bucket với các header giới hạn nghiêm ngặt (ví dụ: tối đa 12 yêu cầu trong 4 giây).
  - Client của tool tích hợp hàng đợi yêu cầu (Token Bucket Queue) để tự động điều tiết tốc độ gọi API, đảm bảo **không bao giờ bị khóa IP hay gặp mã lỗi HTTP 429 (Too Many Requests)**.
- **Bộ lọc Thống kê Giá (Outlier & Median Filtering)**:
  - Loại bỏ các mức giá ảo hoặc giá cố tình treo thấp để phá giá thị trường (Price fixing).
  - Đưa ra khoảng giá trung vị (Median Price) và thời gian niêm yết gần nhất.

### 2.4. Phân hệ Lớp phủ Giao diện (Transparent Overlay HUD)
- **Công nghệ Khuyến nghị**:
  - *Tùy chọn A*: **Tauri 2.0 (Rust + Svelte/React)**: Dung lượng siêu nhẹ (~15 MB RAM), khởi động tức thì, tối ưu tuyệt đối cho giao diện hiện đại.
  - *Tùy chọn B*: **C++23 ImGui + DirectX 11/12 Layered Window**: Độ trễ render < 1ms, tiêu thụ dưới 8 MB RAM.
- **Thuộc tính Cửa sổ Windows**:
  ```cpp
  // Thiết lập cửa sổ luôn nổi lên trên và cho phép bấm xuyên qua khi cần
  SetWindowLong(hWnd, GWL_EXSTYLE, WS_EX_TOPMOST | WS_EX_LAYERED | WS_EX_TRANSPARENT);
  ```

---

## 3. Tiêu chuẩn Tuân thủ Chính sách GGG (Terms of Service Checklist)

Mọi tính năng được thiết kế phải vượt qua danh sách kiểm tra tuân thủ sau:

| Tiêu chí Kiểm tra | Trạng thái Thiết kế | Cơ sở Kỹ thuật |
| :--- | :---: | :--- |
| **Không đọc/ghi bộ nhớ RAM** | **ĐẠT** | Toàn bộ dữ liệu thu thập qua File I/O (`LatestClient.txt`) và System Clipboard (`Ctrl+C`). |
| **Không sửa đổi tệp tin cài đặt của game** | **ĐẠT** | Thư mục `Content.ggpk` và các tệp DLL gốc được giữ nguyên vẹn 100%. |
| **Quy tắc 1 Phím = 1 Thao tác Máy chủ** | **ĐẠT** | Các phím tắt tiện ích chỉ thực hiện đúng 1 lệnh chat (ví dụ: bấm F5 gửi `/hideout`, bấm F6 gửi `/remaining`). Không chứa macro combo nhiều lệnh cùng lúc. |
| **Không can thiệp vào Camera/Fog** | **ĐẠT** | Giữ nguyên hiển thị chuẩn của game, lớp phủ chỉ hiển thị thẻ thông tin trợ giúp bên ngoài. |
| **Không tự động hóa di chuyển/chiến đấu** | **ĐẠT** | Người chơi toàn quyền điều khiển nhân vật; công cụ đóng vai trò cố vấn thông tin và định giá. |

---

## 4. Kiến trúc Hiện thực Thực tế (Implemented Telemetry & Overlay Architecture)

Trong mã nguồn thực tế tại thư mục `src/assistant_tool/`, hệ thống đã được triển khai hoàn chỉnh với sự kết hợp giữa **Lớp phủ Trợ lý Thụ động (Passive Overlay HUD)** và **Cầu nối Bộ nhớ Chia sẻ (CoreShmBridge)**:

```mermaid
graph TB
    subgraph CoreEngine ["AutoPOE2 Core Engine (C++23)"]
        RPM["RPM Reader (UAC Elevated)"]
        LogTailer["Log Sensor (LatestClient.txt)"]
        SHM["Lock-Free IPC Shared Memory (4MB)"]
        RingBuf["SPSC Command Queue (16 slots)"]
        RPM --> SHM
        LogTailer --> SHM
        RingBuf --> RPM
    end

    subgraph AssistantApp ["POE2 Assistant Companion (Python 3.11)"]
        Bridge["CoreShmBridge (30Hz Seqlock Reader)"]
        GoldTrk["GoldTracker (Faustus Tax Engine)"]
        Advisor["MarketAdvisor (Trade Arbitrage)"]
        DiscordMon["DiscordMonitor (Live Trade Sniffer)"]
        Overlay["OverlayHUD (CustomTkinter Transparent GUI)"]
        
        SHM ==>|Đọc Double-Buffer| Bridge
        Bridge ==>|Cập nhật Heartbeat| SHM
        Bridge ==>|Gửi PANIC_STOP (OpCode 99)| RingBuf
        
        Bridge -->|Live HP, Mana, Area| Overlay
        GoldTrk -->|Số dư vàng & Khả năng chịu thuế| Overlay
        Advisor -->|Cảnh báo chênh lệch giá| Overlay
        DiscordMon -->|Kèo thơm WTS/WTB từ Discord| Overlay
    end

    subgraph UserInterface ["Giao diện Người chơi (In-Game Overlay)"]
        HPBar["❤️ Live HP Bar + Alert < 35%"]
        ZoneBadge["🗺️ Khu vực & Level Hiện tại"]
        GoldTax["💰 Máy tính Thuế Vàng Faustus"]
        TradeLinks["🔗 1-Click POE2 Official Trade"]
        PanicBtn["🛑 Panic Killswitch Button"]
    end

    Overlay --> HPBar
    Overlay --> ZoneBadge
    Overlay --> GoldTax
    Overlay --> TradeLinks
    Overlay --> PanicBtn
```

### 4.1. Chi tiết Các Thành phần Đã Hoàn thiện

1. **`CoreShmBridge` (`src/assistant_tool/core_shm_bridge.py`)**:
   - Mở đối tượng ánh xạ bộ nhớ chia sẻ `Local\POE2_Auto_SharedMem_v1`.
   - Áp dụng thuật toán đọc Seqlock (Sequence check 2 đầu `s1 == s2`), tự động chọn slot chẵn/lẻ (`telem_seq & 1`) để đọc dữ liệu không bao giờ bị rách.
   - Ghi nhận `lastAgentHeartbeat` ở offset 48 để C++ Watchdog không ngắt kết nối an toàn.
   - Phát hiện máu tụt dưới ngưỡng nguy hiểm (< 35%) và phát tín hiệu cảnh báo thụ động.
   - Hỗ trợ gửi lệnh dừng khẩn cấp `MacroOpCode::PANIC_STOP` (OpCode 99) vào hàng đợi vòng SPSC 16 slot.

2. **`OverlayHUD` (`src/assistant_tool/overlay_gui.py`)**:
   - Cửa sổ Tkinter trong suốt (`-alpha`, `-topmost`, `wm_overrideredirect`).
   - Phím tắt F9 (Ẩn/Hiện HUD) và F10 (Bật/Tắt tính năng Click-through).
   - Thanh trượt điều chỉnh độ trong suốt từ 20% đến 100%.
   - **Bảng Telemetry Trực tiếp**:
     - Huy hiệu trạng thái kết nối `Core: ONLINE` (xanh lục) / `OFFLINE` (xám).
     - Thanh máu tương thích màu sắc: Xanh lá (>50%), Vàng (35-50%), Đỏ nhấp nháy nguy cấp (<35%).
     - Tự động phát âm thanh cảnh báo tần số 1200Hz (`winsound.Beep`) khi máu rơi vào vùng nguy hiểm.
     - Hiển thị tên khu vực và level hiện tại bóc tách từ nhật ký.

3. **`GoldTracker` & `MarketAdvisor` (`src/assistant_tool/gold_tracker.py`, `market_advisor.py`)**:
   - Theo dõi số dư vàng dự trữ của người chơi.
   - Tính toán biểu thuế vàng Faustus theo từng loại vật phẩm (Mirror, Divine, Pinnacle Key...).
   - Đánh giá khả năng sinh lời và cảnh báo nếu người chơi không đủ vàng trả thuế giao dịch tức thì.
   - Tích hợp liên kết mở trực tiếp trang POE2 Official Trade chỉ với 1 cú click chuột.

4. **`DiscordMonitor` & Chrome Extension (`src/assistant_tool/discord_monitor.py`, `poe2_discord_extension/`)**:
   - Extension Chrome nhẹ nhàng trích xuất nội dung tin nhắn chat từ Discord Web.
   - Bộ phân tích ngôn ngữ tự nhiên bóc tách các tin nhắn `WTS` / `WTB` và chỉ số giá.
   - Tự động so sánh với giá thị trường chuẩn và gắn nhãn: `🔥 KÈO RẺ`, `⚠️ GIÁ CAO`, `⚖️ HỢP LÝ`.