# 05. Lộ trình Triển khai Công cụ Hỗ trợ (Assistant Tool Implementation Roadmap)

> **Mục tiêu**: Hướng dẫn từng bước lập trình và đóng gói công cụ hỗ trợ người chơi hoàn chỉnh, đạt chuẩn công nghiệp.

---

## 1. Các Giai đoạn Phát triển (Implementation Sprints)

```mermaid
gantt
    title Lộ trình Triển khai Công cụ Hỗ trợ POE2
    dateFormat  YYYY-MM-DD
    section Sprint 1: Lắng nghe Sự kiện
    Log Tailer Background Thread        :done, sp1_1, 2026-09-08, 3d
    Global Hotkey Hook (Ctrl+D, F5, F6) :active, sp1_2, after sp1_1, 3d
    section Sprint 2: Bóc tách Vật phẩm
    Regex Tokenizer & POE2 Item Parser  :sp2_1, after sp1_2, 4d
    Affixes & Tier Normalizer           :sp2_2, after sp2_1, 3d
    section Sprint 3: Kết nối Trade API
    Official Trade API Client           :sp3_1, after sp2_2, 4d
    Rate-Limiting & Leaky Bucket Queue  :sp3_2, after sp3_1, 3d
    Median Price Calculation Engine     :sp3_3, after sp3_2, 3d
    section Sprint 4: Lớp phủ Overlay
    Transparent Topmost Window          :sp4_1, after sp3_3, 4d
    Price Check Card & Map Mod Warning  :sp4_2, after sp4_1, 4d
    Trade Notification 1-Click Panel    :sp4_3, after sp4_2, 3d
    section Sprint 5: Đóng gói & Tinh chỉnh
    Packaging Standalone (.exe)         :sp5_1, after sp4_3, 3d
    Thử nghiệm với Game Client Thực tế  :sp5_2, after sp5_1, 4d
```

---

## 2. Danh mục Công nghệ & Thư viện Khuyến nghị

1. **Ngôn ngữ Phát triển**:
   - *Lựa chọn 1 (Nhanh chóng & Linh hoạt)*: **Python 3.11+** kết hợp `PyQt6` / `PySide6` (hỗ trợ cửa sổ trong suốt và xử lý bất đồng bộ `asyncio`).
   - *Lựa chọn 2 (Tối ưu Hiệu năng Cực hạn)*: **Tauri 2.0 (Rust + Webview2)** (dung lượng cài đặt < 10 MB, tiêu thụ < 20 MB RAM).
2. **Các Thư viện Cốt lõi**:
   - `requests` & `urllib3`: Giao tiếp HTTP với máy chủ Trade chính thức.
   - `pydantic`: Kiểm soát cấu trúc dữ liệu vật phẩm và phản hồi API.
   - `keyboard` hoặc `pynput`: Đăng ký phím tắt toàn cục không làm gián đoạn game.
   - `pywin32`: Tương tác cửa sổ Windows, clipboard và kích thước màn hình.

---

## 3. Khung Mã nguồn Bộ khởi chạy Chính (Main Runner Skeleton)

```python
"""
POE2 Assistant Companion - Main Application Entrypoint
"""

import sys
import threading
import time
from POE2ItemParser import POE2ItemParser
from POE2TradeClient import POE2TradeClient
from POE2LogSensor import POE2LogSensor

def on_price_check_triggered():
    print("[Hotkey] Người chơi bấm Ctrl+D - Đang đọc Clipboard...")
    # 1. Đọc văn bản từ Clipboard
    # 2. Bóc tách thuộc tính vật phẩm qua POE2ItemParser
    # 3. Gửi truy vấn tới POE2TradeClient
    # 4. Hiển thị kết quả lên giao diện Lớp phủ (Overlay)

def on_whisper_received(sender: str, message: str):
    print(f"[Trade Alert] Nhận tin nhắn từ {sender}: {message}")
    # Hiển thị thẻ thông báo giao dịch 1-Click trên màn hình

def main():
    print("==================================================")
    print("   POE2 Assistant Companion (v0.5.5 Ready)        ")
    print("   Tuân thủ 100% Điều khoản & Chính sách GGG      ")
    print("==================================================")

    # 1. Khởi chạy luồng đọc log ngầm
    log_sensor = POE2LogSensor()
    log_thread = threading.Thread(
        target=log_sensor.listen,
        args=(lambda area: print(f"Vào khu vực: {area}"), on_whisper_received),
        daemon=True
    )
    log_thread.start()

    print("[Ready] Hệ thống đã sẵn sàng. Hãy bấm Ctrl+D lên trang bị trong game để tra cứu giá.")
    
    # Duy trì ứng dụng chạy
    try:
        while True:
            time.sleep(1)
    except KeyboardInterrupt:
        print("\n[Exit] Đang đóng ứng dụng an toàn...")

if __name__ == "__main__":
    main()
```