# Companion HUD & Trade (docs/assistant_tool/)

> **Cold Path Python** — không mô tả Hot Path 120 Hz. IPC: [Doc 06](../development/06_binary_ipc_protocol_spec.md). Kiến trúc: [Doc 50](../development/50_two_tier_asymmetric_hybrid_architecture_specification.md).  
> Overlay/trade **không** biến Core RPM thành “ToS-safe”. Index: [`docs/README.md`](../README.md).

---

## 1. Mục lục Tài liệu Kỹ thuật Chi tiết

Toàn bộ hệ thống tài liệu hướng dẫn triển khai công cụ hỗ trợ người chơi được biên soạn chuyên sâu tại thư mục `docs/assistant_tool/`:

1. [**`01_system_architecture.md`**](01_system_architecture.md):
   - Thiết kế kiến trúc tổng thể hướng sự kiện bất xâm nhập (Non-Intrusive Event-Driven Architecture).
   - 4 Phân hệ cốt lõi: Cảm biến nhật ký (`Client.txt`), Trình bóc tách clipboard (`Ctrl+C`), Trình kết nối Official Trade API và Lớp phủ trong suốt (Transparent HUD).
   - Bảng kiểm tra tiêu chuẩn tuân thủ chính sách của nhà phát hành (Zero Memory Access, 1-Action Rule).
2. [**`02_clipboard_item_parser.md`**](02_clipboard_item_parser.md):
   - Phân tích cú pháp thẻ văn bản trang bị trong POE2 (Header, Base Type, Quality, DPS, Sockets, Implicit/Explicit Mods, Corrupted).
   - Máy trạng thái xử lý văn bản và mã nguồn Python mẫu hoàn chỉnh `POE2ItemParser` sử dụng Pydantic.
3. [**`03_trade_api_and_pricing.md`**](03_trade_api_and_pricing.md):
   - Tích hợp cổng API giao dịch chính thức của POE2 (`https://www.pathofexile.com/api/trade2/search` và `/fetch`).
   - Kỹ thuật điều tiết lưu lượng Leaky Bucket chống lỗi HTTP 429 và giải pháp tính toán giá trung vị (Median Pricing) loại bỏ giá ảo.
4. [**`04_overlay_and_ui_ux.md`**](04_overlay_and_ui_ux.md):
   - Thiết kế cửa sổ lớp phủ trong suốt (Transparent Overlay Window) bằng Win32 API (`WS_EX_LAYERED | WS_EX_TRANSPARENT`).
   - Bộ cảnh báo các dòng mod chết người trên Waystone (Phản sát, Không hồi máu, Trừ kháng tối đa).
   - Bảng thông báo giao dịch 1-Click (Mời nhóm, Giao dịch, Cảm ơn) và các phím tắt tiện ích F5 Hideout, F6 Quái còn lại.
5. [**`05_implementation_roadmap.md`**](05_implementation_roadmap.md):
   - Lộ trình 5 Sprint phát triển tuần tự từ thu thập sự kiện đến đóng gói sản phẩm độc lập (.exe).
   - Khung mã nguồn điều phối chính (Main Runner Skeleton).

---

## 2. Điểm Khác biệt So với Các Công cụ Can thiệp Trái phép

| Hạng mục | Công cụ Hỗ trợ Hợp lệ (Assistant Companion) | Công cụ Can thiệp Trái phép (Cheat/Bot) |
| :--- | :--- | :--- |
| **Quyền can thiệp bộ nhớ** | **Không chạm vào RAM** (Zero Memory Read/Write). | Đọc/ghi RAM, hook vtable, vá mã shader. |
| **Phương thức thu thập dữ liệu** | Đọc tệp nhật ký `Client.txt` (fallback `LatestClient.txt`) và Clipboard `Ctrl+C`. | Quét con trỏ bộ nhớ động, inject DLL, DMA. |
| **Tự động hóa hành động** | **Người chơi tự điều khiển 100%**; chỉ hỗ trợ phím tắt gửi 1 lệnh chat đơn lẻ. | Tự động di chuyển, tự động bấm skill combo, tự động nhặt đồ. |
| **Mức độ an toàn tài khoản** | **An toàn tuyệt đối 100%**; được cộng đồng và GGG cho phép lưu hành. | Nguy cơ bị cấm vĩnh viễn (Perma-ban) khi bị phát hiện. |

---

## 3. Cấu trúc Mã nguồn Triển khai Thực tế (`src/assistant_tool/`)

Hệ thống mã nguồn thực tế đã hoàn thiện tại thư mục `src/assistant_tool/`:

```
src/assistant_tool/
├── config.py             # SSoT: Client.txt, THEME, kích thước Control Center vs Overlay
├── ui_theme.py           # Accessor màu Control Center (không hex rải rác)
├── core_shm_bridge.py    # Cầu nối IPC đọc Shared Memory C++ (Seqlock 30Hz)
├── log_watcher.py        # Client.txt: whisper, SCENE, seed zone khi mở giữa map
├── visual_tool.py       # GUI Zoom 4x + fog (IPC 48 byte)
├── overlay_gui.py        # Overlay HUD 510×700 (Trading & Market Advisor)
└── control_center.py     # Control Center Dashboard 980×680 (run_full_system.bat → F8 start Core)
```

### Điểm Khởi Chạy Duy Nhất (Single Source of Truth):
- **`run_full_system.bat`**: Khởi chạy toàn bộ hệ thống (tự xin Admin UAC, kiểm tra venv, biên dịch C++ Core nếu thiếu và mở Control Center). Kích hoạt hoặc dừng Bot tự hành 120Hz bằng phím **`F8`** (hoặc nút bấm trên giao diện). Dừng khẩn cấp: **`Pause`** hoặc **`Ctrl + Shift + F12`** (không dùng F12 đơn lẻ để tránh xung đột chụp ảnh Steam).