# KIẾN TRÚC HỆ THỐNG 2 PHÂN TẦNG AUTOPOE2 (2-TIER SYSTEM ARCHITECTURE)
> **Đặc tả kiến trúc chuẩn hóa giữa Tier 1 (C++23 Low-Level Core Engine 120Hz) và Tier 2 (Python 3.11 Passive Companion HUD)**  
> *Mốc thời gian tham chiếu: 07/09/2026 - Path of Exile 2 Early Access Context*

---

## 1. TỔNG QUAN MÔ HÌNH 2 PHÂN TẦNG CHUYÊN BIỆT (2-TIER SEPARATION)

Dự án **AutoPOE2** tuân thủ nghiêm ngặt nguyên lý phân tách trách nhiệm (Separation of Concerns) nhằm tối ưu hóa hiệu năng mili-giây, triệt tiêu độ trễ và bảo vệ tối đa an toàn tài khoản game:

```mermaid
graph TB
    subgraph Game_Process ["Path of Exile 2 (Client 64-bit)"]
        RAM["Game Process Memory (Life, XYZ, Entities)"]
        LogFile["Client.txt (Generating + SCENE; LatestClient fallback)"]
    end

    subgraph Tier1 ["Tier 1: Low-Level Core Engine (C++23 - 120Hz)"]
        RPM["Zero-Risk ReadProcessMemory (120Hz Tick)"]
        Nav["A* NavMesh & Bresenham LoS Engine"]
        HumanCurve["HumanCurveGenerator (Cubic Bézier + Fitts' Law)"]
        Reflex["ReflexManager (Dodge 100-150ms Latency, Smart Flask, Kiting)"]
        NativeOverlay["Win32 Native Transparent Overlay (12 FPS)"]
        LogSens["Zero-Risk LogSensor (FILE_SHARE_READ)"]
        SHM_Writer["Seqlock Double-Buffer Writer (Slot 0 / 1)"]
        SPSC_Consumer["SPSC Command Queue Consumer (16 Slots)"]
        PanicHandler["Panic Killswitch (Pause/Break / Ctrl+Shift+F12)"]
    end

    subgraph IPC ["Inter-Process Communication (Shared Memory 4MB)"]
        Header["SharedMemoryHeader (64 Bytes, Seqlock & Heartbeats)"]
        Slot0["Telemetry Slot 0 (64 KB Ping)"]
        Slot1["Telemetry Slot 1 (64 KB Pong)"]
        CmdQueue["Command Ring Buffer (16 Slots x 64 Bytes @ 0x300000)"]
    end

    subgraph Tier2 ["Tier 2: Passive Companion HUD & A3E Brain (Python 3.11)"]
        ShmReader["CoreShmBridge (Seqlock 30Hz Reader)"]
        CmdProducer["SPSC Command Producer (<QIfffIII)"]
        A3E["A3E Agentic Self-Learning Engine (src/agentic_engine/)<br/>- Contextual Bandit LinUCB (Zero Deps)<br/>- Unidentified Item Lifecycle (The Hooded One)<br/>- WhatIsBetterEvaluator (Pareto Utility)<br/>- Dynamic Reflex Tuner & Critic"]
        CustomGUI["Transparent Overlay HUD (CustomTkinter)"]
        ControlCenter["Control Center (Hotkeys F8 / Pause / F10 / F9)"]
        GoldCalc["Faustus Gold Tax Calculator"]
        MarketAdv["Official Trade 1-Click & Arbitrage Advisor"]
        DiscordSniff["Discord Realtime Trade Sniffer"]
    end

    RAM -->|RPM 120Hz| RPM
    LogFile -->|FILE_SHARE_READ| LogSens
    RPM --> Reflex
    Reflex --> HumanCurve
    HumanCurve -->|Hardware KMBox / Win32| RAM
    RPM --> Nav
    RPM --> SHM_Writer
    LogSens --> SHM_Writer
    SHM_Writer --> Slot0
    SHM_Writer --> Slot1
    Slot0 --> ShmReader
    Slot1 --> ShmReader
    ShmReader --> A3E
    A3E --> CustomGUI
    A3E --> ControlCenter
    ShmReader --> CustomGUI
    ShmReader --> ControlCenter
    GoldCalc --> CustomGUI
    MarketAdv --> CustomGUI
    DiscordSniff --> CustomGUI
    CmdProducer --> CmdQueue
    CmdQueue --> SPSC_Consumer
    PanicHandler --> SPSC_Consumer
```

---

## 2. CHI TIẾT CÁC PHÂN TẦNG HỆ THỐNG

### 2.1. Tier 1: C++23 Low-Level Core Engine (`AutoPOE2_Core.exe` - 120Hz)
- **Vị trí**: `src/core/`
- **Tần số vận hành**: Chu kỳ tick cố định 120Hz (~8.33ms/tick) nhờ mở khóa độ phân giải Windows Timer qua `timeBeginPeriod(1)`.
- **Nhiệm vụ cốt lõi**:
  1. **Đọc bộ nhớ thụ động (Zero-Risk ReadProcessMemory)**:
     - Truy xuất trạng thái sinh mệnh (`currentHP`, `maxHP`, `currentMana`, `maxMana`, `currentES`, `maxES`).
     - Cập nhật tọa độ không gian thực XYZ (`posX`, `posY`, `posZ`) từ chuỗi con trỏ tĩnh đã được hiệu chuẩn trong `offsets.toml`.
     - Duy trì mảng thực thể lân cận (`EntityTelemetryData[256]`) bao gồm quái vật, boss, item rơi và NPC.
  2. **Động cơ Phản xạ Sinh tồn & Chiến đấu (`ReflexManager`)**:
     - **Iframe Dodge Roll**: Phát hiện sát thương sốc bùng nổ ($\ge 22\%$ maxHP trong tick window), bổ sung độ trễ phản xạ tự nhiên của não bộ (**Human Reaction Latency 100ms - 150ms**) trước khi kích hoạt Spacebar (300ms bất tử).
     - **Smart Flask HoT**: Bơm Life Flask khi $HP \le 55\%$, theo dõi hồi máu theo thời gian (HoT 3000ms), tự động đè ngụm 2 khi rơi vào ngưỡng nguy kịch $\le 28\%$.
     - **Phân phối Gauss cho Dwell Time**: Thời gian giữ phím không cố định mà dao động tự nhiên trong khoảng **35ms - 65ms** theo `std::normal_distribution`.
     - **Dynamic Kiting**: Tự động thả diều lùi ra khỏi tầm áp sát của quái vật ($< 35$ đơn vị) bằng chuột hoặc WASD.
  3. **Mô phỏng Nhập liệu Nhân tính hóa (`HumanCurveGenerator`)**:
     - Sinh quỹ đạo chuột theo đường cong Bézier bậc 3 kết hợp định luật Fitts, vi dao động sinh học Brownian micro-jitter và hiện tượng trượt quá đích (Overshoot correction).
     - Triệt tiêu hoàn toàn hành vi dịch chuyển chuột tức thời (teleport).
  4. **Cảm biến Nhật ký Thụ động (`LogSensor`)**:
     - Đọc file nhật ký `Client.txt` (fallback `LatestClient.txt`) bằng cờ chia sẻ đọc `FILE_SHARE_READ`, bóc tách sự kiện chuyển map, area level, seed địa hình và chat whisper mà không bị anti-cheat phát hiện.
  5. **Ngắt khẩn cấp an toàn (Panic Killswitch)**:
     - Lắng nghe phím phần cứng `Pause/Break` hoặc tổ hợp `Ctrl + Shift + F12` để ngắt khẩn cấp bot và xả toàn bộ phím tránh kẹt phím (Sticky Keys).

### 2.2. Tier 2: Passive Companion HUD & Market Advisor (Python 3.11)
- **Vị trí**: `src/assistant_tool/`
- **Tần số vận hành**: 30Hz đối với ShmBridge Reader, 12-30 FPS đối với giao diện Tkinter.
- **Nhiệm vụ cốt lõi**:
  1. **Cầu nối Bộ nhớ Chia sẻ (`CoreShmBridge`)**:
     - Đọc dữ liệu Telemetry từ Shared Memory bằng thuật toán Seqlock kiểm tra toàn vẹn $s_1 == s_2$ chống rách dữ liệu.
     - Đóng gói và gửi chỉ thị điều khiển vĩ mô xuống hàng đợi SPSC Command Queue theo định dạng chuẩn nhị phân `<QIfffIII`.
  2. **Giao diện Lớp phủ Trong suốt (`Transparent Overlay HUD`)**:
     - Render thanh sinh mệnh, mana, thông tin map, cảnh báo sốc sát thương trực tiếp lên màn hình game.
     - Hỗ trợ chế độ xuyên thấu chuột (Click-Through) hoàn toàn.
  3. **Trợ lý Kinh tế & Giao dịch**:
     - `GoldTracker`: Tính toán chính xác thuế vàng Faustus cho mọi loại currency trong POE2.
     - `MarketAdvisor`: Bắt chênh lệch giá tiền tệ, hỗ trợ mở liên kết 1-click Official Trade.
     - `DiscordMonitor`: Sniffer tin nhắn mua bán thời gian thực từ Discord Web.
  4. **Trung tâm Điều khiển (`ControlCenterApp`)**:
     - Phím tắt điều khiển: `F8` (Bật/Tắt Bot), `Pause/Break` (Panic Stop), `F10` (Bộ Não Chiến Thuật), `F9` (Chụp Màn Hình).
     - Tự động nhận diện cấu hình phím di chuyển của game (`WASD` hoặc `Click-to-Move`).

### 2.3. Não Bộ Tự Học Trực Tuyến & Ra Quyết Định: A3E Engine (`src/agentic_engine/`)
> *Chi tiết toàn diện về thuật toán toán học, vòng đời item và API: Xem tài liệu [05_agentic_self_learning_engine.md](./05_agentic_self_learning_engine.md)*
- **Vị trí**: `src/agentic_engine/` (gói độc lập, giao tiếp với GUI và Shared Memory qua Façade `AgenticCoordinator`).
- **Tần số vận hành**: Asynchronous & Event-Driven (Không gây ảnh hưởng đến chu kỳ 120Hz của Core hay 30Hz của HUD).
- **Trọng tâm kiến trúc**:
  1. **Tối ưu Hóa LinUCB Không Thư Viện Ngoài (Pure Python LinUCB)**:
     - Tự triển khai ma trận $d \times d$ với thuật toán nghịch đảo Gauss-Jordan, thời gian ra quyết định $< 0.05\text{ ms}$, triệt tiêu 100% rủi ro phụ thuộc bên thứ ba (NumPy/SciPy).
     - Cân bằng khai phá (Exploration - $\alpha$) và khai thác (Exploitation) cho các chiến thuật chiến đấu, nhặt đồ và farm bản đồ.
  2. **Vòng đời Xử lý Item Chưa Giám Định (Unidentified Item 4-Stage Lifecycle)**:
     - Giai đoạn 1 (Pre-ID Triage): Phân loại base item dựa trên iLvl, implicit mod và database GGPK.
     - Giai đoạn 2 (Channel Dual-Path): Tiết kiệm Scroll of Wisdom tối đa bằng cách chỉ giám định tại trận cho base S-Tier, toàn bộ đồ còn lại gom cụm về Hideout giám định 1-click miễn phí qua **The Hooded One**.
     - Giai đoạn 3 (Post-ID Appraisal): So sánh Pareto Utility với đồ đang trang bị.
     - Giai đoạn 4 (Online EV Learning): Cập nhật xác suất ra mod xịn và giá trị kỳ vọng (Expected Chaos Value) vào `captures/unidentified_learning_db.json`.
  3. **Hàm Đánh Giá Đa Mục Tiêu Pareto ("What is better?")**:
     - $\mathcal{U} = w_{\text{dps}}\Delta \text{DPS} + w_{\text{ehp}}\Delta \text{EHP} - \text{ResistPenalties}$.
     - Phạt nặng nếu món đồ làm tụt kháng nguyên tố dưới ngưỡng cap $75\%$ hoặc kháng hỗn mang dưới $0\%$.
  4. **Bộ Tự Chỉnh Phản Xạ & Phân Tích Nguyên Nhân Tử Trận (Reflex Tuner & Post-Mortem Critic)**:
     - Tự động thắt chặt ngưỡng bơm máu và tăng nhạy né đòn khi phát hiện chuỗi sát thương bộc phát hoặc số lần suýt chết tăng cao.
     - Phân loại nguyên nhân chết (Slam sốc sát thương, quái bu Swarm, hay rút máu Attrition/DoT) dựa trên 120 tick viễn trắc hộp đen ghi lại từ trước thời điểm tử trận.

---

## 3. GIAO THỨC TRUYỀN THÔNG LIÊN TIẾN TRÌNH (IPC SPECIFICATION)

Khối nhớ dùng chung `Local\POE2_Auto_SharedMem_v1` có kích thước **4 MB** (4,194,304 bytes), được bố cục như sau:

| Vùng Bộ Nhớ | Offset Bắt Đầu | Kích Thước | Chức Năng Kỹ Thuật |
| :--- | :---: | :---: | :--- |
| **SharedMemoryHeader** | `0x000000` | 64 Bytes | Chứa Magic, Protocol Version, Seqlock sequence, Command cursors, Heartbeats |
| **Telemetry Slot 0 (Ping)** | `0x001000` | 64 KB | Slot dữ liệu Telemetry chẵn (`telem_seq & 1 == 0`), payload 39,096 bytes |
| **Telemetry Slot 1 (Pong)** | `0x011000` | 64 KB | Slot dữ liệu Telemetry lẻ (`telem_seq & 1 == 1`), payload 39,096 bytes |
| *Vùng Đệm Dự Phòng* | `0x021000` | ~2.87 MB | Dành cho mở rộng NavMesh / Texture Cache tương lai |
| **Command Ring Buffer** | `0x300000` | 1024 Bytes | **Hàng đợi SPSC đúng 16 slots x 64 bytes** (gói tin lệnh vĩ mô 36 bytes) |

### Cơ chế Hàng đợi Lệnh SPSC (16 Slots):
- **Producer**: Python Companion (Tier 2) là tiến trình duy nhất ghi lệnh vào hàng đợi.
- **Consumer**: C++ Core Engine (Tier 1) là tiến trình duy nhất đọc và xử lý lệnh.
- **Dung lượng**: Cố định **16 slots** (`COMMAND_QUEUE_CAPACITY = 16`).
- **Khoảng cách bước (Stride)**: 64 bytes (căn chỉnh theo 1 cache line CPU).
- **Cấu trúc gói tin `CommandPacket`**: Kích thước chuẩn **36 bytes**, định dạng nhị phân `<QIfffIII`:
  - `commandId` (uint64, 8B)
  - `opCode` (uint32, 4B)
  - `targetX`, `targetY`, `targetZ` (3 x float, 12B)
  - `targetEntityId` (uint32, 4B)
  - `priority` (uint32, 4B)
  - `timeoutMs` (uint32, 4B)
- **Kiểm soát tràn hàng đợi**: Producer phải kiểm tra `commandSequence - commandReadIndex < 16` trước khi ghi, tránh hiện tượng ghi đè khi Core bận.

---

## 3. Full-auto BotBrain (SPEC 29 — chưa implement)

Tick Core hiện tại (`main.cpp`) gọi lần lượt Reflex → Combo → Loot → Quest, **ba module farm đều tự click** trong cùng 8.33ms. Đó không phải kiến trúc đích.

Đích (chi tiết đủ để viết code): [`docs/development/29_botbrain_priority_fsm_pickit_and_closed_farming_loop.md`](../development/29_botbrain_priority_fsm_pickit_and_closed_farming_loop.md).

Tóm tắt bất biến agent phải giữ:

1. **INV-BRAIN-01**: full-auto chỉ **một** click/move thế giới mỗi tick; Reflex flask/dodge/chicken chạy trước và có quyền chặn arbiter (`ConsumedExclusiveInput`).
2. **INV-SAFE-01**: có quái trong `safe_range` (50u) → cấm Pickup/Chest.
3. Pickit WeightedSum / post-ID = Python cold path; Core chỉ nhận `pickup_filter.json`.
4. Opcode 5/6 đã khai báo trong `protocol.hpp` nhưng Core đang `default` bỏ qua — P3 mới được coi là “đã stash”.
5. Cấm đánh dấu farm loop là đã xong khi mới có `MapScenario` (doc 25 = in-map heuristic).