# 50. ĐẶC TẢ KIẾN TRÚC BẤT ĐỐI XỨNG HAI TẦNG CHUẨN MỰC THƯƠNG MẠI 2026 (TWO-TIER ASYMMETRIC HYBRID ARCHITECTURE SPECIFICATION) - **Mã Tài Liệu**: `DOC-50-TWO-TIER-HYBRID-ARCH-2026` - **Mốc Thời Gian Tham Chiếu**: `13/09/2026` - **Mô Hình Kiến Trúc**: **Two-Tier Asymmetric Hybrid Architecture** *(Tier 1: Data-Oriented Pipeline & Hexagonal Ports/Adapters | Tier 2: Event-Driven Modular Bus | IPC: Mechanical Sympathy Lock-Free Shared Memory)* - **Trạng Thái**: `CANONICAL STANDARD & SSoT (BẮT BUỘC TUÂN THỦ TOÀN DỰ ÁN)` --- ## 1. TRIẾT LÝ KIẾN TRÚC & TẠI SAO PHẢI LÀ BẤT ĐỐI XỨNG (ASYMMETRIC HYBRID)? Trong các hệ thống tự hành và trợ lý thời gian thực phức tạp như **AutoPOE2**, hệ thống phải đối mặt với hai thái cực yêu cầu đối lập hoàn toàn: ``` [THÁI CỰC 1: HARD REAL-TIME HOT PATH] [THÁI CỰC 2: ASYNC COLD PATH & COGNITION] - Chu kỳ phản xạ cực ngắn: < 8.33ms (120Hz) - Chu kỳ phân tích: 100ms – 2000ms - Yêu cầu: Zero Allocation, Zero Jitter - Yêu cầu: Trực quan hóa UI, OCR, AI Reasoning - Nguy cơ: Chết nhân vật nếu trễ 10ms - Nguy cơ: Nghẽn GIL Python, treo giao diện - Công nghệ tối ưu: C++23 DOD & Hexagonal - Công nghệ tối ưu: Python 3.11 Event-Driven Bus ``` ### 1.1. Tại sao Pure OOP thất bại trong Hot Path? - **Phân mảnh bộ nhớ & Cache Miss**: Lập trình hướng đối tượng cổ điển tạo hàng trăm đối tượng rời rạc (`MonsterEntity`, `LifeComponent`, `BuffEffect`) cấp phát rải rác trên heap. Khi CPU duyệt qua 200 quái vật, việc nhảy cóc qua các con trỏ (`pointer chasing`) khiến bộ nhớ đệm CPU L1/L2 liên tục bị xóa rỗng (Cache Miss), làm sụt giảm FPS và kéo dài độ trễ tính toán. - **God Object & Kế thừa sâu**: Dẫn tới các file khổng lồ vi phạm nguyên lý đơn trách nhiệm (như `GameSession` 2.300 dòng hiện tại). - **VTable Indirection**: Hàm ảo làm mất khả năng inlining của compiler và tốn chu kỳ CPU tra cứu vtable trong vòng lặp 120Hz. ### 1.2. Tại sao Pure SOA / Microservices thất bại trong Hot Path? - **Chi phí Serialization/Deserialization**: Đóng gói JSON hoặc Protobuf tiêu tốn 1–3ms CPU. - **Độ trễ Socket / Context Switching**: Giao tiếp qua mạng cục bộ hoặc Socket IPC gây jitter 2–8ms do hàng đợi của hệ điều hành. Nếu một microservice Auto-Flask trễ 10ms để xử lý gRPC, nhân vật đã tử trận ở map Tier 15+! ### 1.3. Lời Giải 2026: Kiến Trúc Bất Đối Xứng Hai Tầng (Two-Tier Asymmetric Hybrid Architecture) - **Tầng Hot Path (C++23)**: Không dùng OOP sâu, áp dụng **Data-Oriented Design (DOD)** để dữ liệu xếp phẳng liên tục (Contiguous Memory Arrays / SoA) đạt tốc độ cache L1 tối đa, kết hợp **Hexagonal Ports & Adapters** để cô lập hoàn toàn Win32 I/O. - **Tầng Cold Path (Python 3.11)**: Không dùng vòng lặp đồng bộ nguyên khối, áp dụng **Event-Driven Architecture (EDA)** trên nền tảng **EventBus** siêu nhẹ, tách rời giao diện người dùng khỏi luồng dữ liệu. - **Kênh IPC**: Áp dụng triết lý **Mechanical Sympathy** (thấu hiểu phần cứng CPU): Lock-Free Seqlock Double-Buffer 39KB khớp kích thước Cache Line, đọc/ghi 0ms tranh chấp khóa. --- ## 2. SƠ ĐỒ KIẾN TRÚC TOÀN CỤC (CANONICAL ARCHITECTURE BLUEPRINT) ``` ┌────────────────────────────────────────────────────────────────────────────────────────┐ │ TIER 1: C++23 CORE ENGINE (HARD REAL-TIME HOT PATH 120HZ) │ │ │ │ [HEXAGONAL IN-PORTS] [DATA-ORIENTED LINEAR PIPELINE] [HEXAGONAL OUT-PORTS]│ │ ┌──────────────────┐ ┌─────────────────────────────┐ ┌───────────────────┐│ │ │ RPMReader │ ──RPM───> │ 1. O(1) Memory Snapshot │ │ KMBoxNet Hardware ││ │ │ (Live Game RAM) │ │ (Flat Entity Arrays/SoA) │ │ (USB HID Direct) ││ │ ├──────────────────┤ ├─────────────────────────────┤ ├───────────────────┤│ │ │ SimulatedReader │ ──Dump──> │ 2. Reflex Manager Guard │ ->│ Win32Simulator ││ │ │ (Headless Test) │ │ (Flask / Iframe / Escape)│ │ (Dev Fallback) ││ │ └──────────────────┘ ├─────────────────────────────┤ └───────────────────┘│ │ │ 3. BotBrain Priority Arbiter│ ▲ │ │ │ (Chicken -> Combat->Nav) │ │ │ │ ├─────────────────────────────┤ │ │ │ │ 4. Subsystem Execution │ ────────────┘ │ │ │ (Combo / Loot / A* JPS) │ (Focus Interlock Safe) │ │ └──────────────┬──────────────┘ │ └────────────────────────────────────────────────┼───────────────────────────────────────┘ │ [LOCK-FREE SHARED MEMORY IPC] ┌───────────────────────────────┴───────────────────────────────┐ │ • Telemetry Channel: Seqlock Double-Buffer 39.112 Bytes (120Hz)│ │ • Command Channel: SPSC Ring Buffer 16 Slots (Lock-Free) │ │ • Alignment: 64-Byte Cache-Line Aligned, Zero-Torn-Read │ └───────────────────────────────┬───────────────────────────────┘ │ ┌────────────────────────────────────────────────┼───────────────────────────────────────┐ │ TIER 2: PYTHON 3.11 COMPANION & AGENTIC ENGINE (COLD PATH 1-30HZ) │ │ │ │ │ ┌───────────────────────▼────────────────────────┐ │ │ │ CENTRAL EVENTBUS & TELEMETRY DISPATCHER │ │ │ └───────┬─────────────────┬───────────────────┬──┘ │ │ │ │ │ │ │ ┌──────────────▼───┐ ┌──────────▼────────┐ ┌───────▼───────────────┐ │ │ │ InvariantSentinel│ │ Modular UI Views │ │ ItemHoverInspector │ │ │ │ (14 Error Codes) │ │ (CustomTkinter) │ │ & Native Tooltip HUD │ │ │ └──────────────────┘ └───────────────────┘ └───────────────────────┘ │ │ │ │ │ ┌─────────────────────▼───────────────────────┐ │ │ │ TIER 3: ASYNC ANCILLARY WORKERS (ASYNCIO)│ │ │ │ • Discord Webhook / Economy Sniffer │ │ │ │ • Gemini LLM Strategic Advisor / Reflection │ │ │ └─────────────────────────────────────────────┘ │ └────────────────────────────────────────────────────────────────────────────────────────┘ ``` --- ## 3. ĐẶC TẢ CHI TIẾT TIER 1: C++23 LOW-LATENCY HOT PATH ENGINE Tầng Tier 1 chịu trách nhiệm sinh tồn độc lập cho nhân vật, duy trì chu kỳ tick cố định **120Hz** (~8.33ms/tick), được khóa cứng bởi `timeBeginPeriod(1)`. ### 3.1. Data-Oriented Design (DOD) Pipeline Mỗi tick 120Hz, luồng thực thi đi theo một đường thẳng tuyến tính, xác định (deterministic), không phân nhánh đệ quy: 1. **Pha 1: O(1) Memory Snapshot**: - `PointerChainResolver` giải mã địa chỉ `PlayerEntity` và `EntityMap` trong **0.051 µs**. - Dữ liệu 256 thực thể được dàn phẳng vào mảng liên tục `std::array` nằm trọn vẹn trong Cache L2 của CPU. 2. **Pha 2: Reflex Manager Guard (Bảo Vệ Sinh Tồn Bất Biến)**: - Đọc trực tiếp HP, ES, Mana, Ward từ bộ nhớ. - Nếu vi phạm ngưỡng nguy kịch: Kích hoạt ngay Smart Life/Mana Flask, né lướt Iframe Space, hoặc ngắt kết nối khẩn cấp (Emergency Logout). - Nếu Reflex tiêu thụ input vật lý (`m_consumedExclusiveInput = true`), toàn bộ các pha phía sau bị bỏ qua trong tick đó. 3. **Pha 3: BotBrain Priority Arbiter (Bộ Phân Định Thứ Bậc Duy Nhất)**: - Các action handler (`CombatManager`, `LootController`, `QuestNavigator`, `AreaEvents`, `MapDeviceHandler`, `UnstuckHandler`) đăng ký `ActionProposal` với priority số học (`constexpr uint32_t`). - Handler có priority cao nhất giành quyền kiểm soát khung hình (`CHICKEN > FLASK > DODGE > UNSTUCK > EMERGENCY_ATTACK > COMBAT > AREA_EVENT > PICKUP > EXPLORE`). 4. **Pha 4: Actuator Output Execution**: - Gửi xung lệnh tới Adapter phần cứng sau khi vượt qua chốt kiểm tra `EnsurePoe2WindowFocus()`. 5. **Pha 5: Telemetry Publishing**: - Xuất bản dữ liệu sang Shared Memory Seqlock Slot với cơ chế store-release. ### 3.2. Hexagonal Architecture (Ports & Adapters) Core logic tính toán hoàn toàn tách biệt khỏi hệ điều hành và phần cứng: - **In-Ports (Cổng nạp dữ liệu)**: - Giao diện trừu tượng `IMemoryReader` định nghĩa hợp đồng: `Read()`, `Write()`, `ForEachHeapRegion()`. - **Adapter 1**: `RpmReader` (Live Client qua Win32 `ReadProcessMemory`). - **Adapter 2**: `SimulatedReader` (Test độc lập qua tệp dump RAM thật, không cần mở game). - **Out-Ports (Cổng điều khiển ngoại vi)**: - Giao diện trừu tượng `IInputActuator` định nghĩa hợp đồng: `MoveMouse()`, `ClickMouse()`, `KeyDown()`, `KeyUp()`. - **Adapter 1**: `KMBoxNetActuator` (Phần cứng USB HID qua cổng mạng LAN). - **Adapter 2**: `Win32InputActuator` (Mô phỏng phần mềm qua `keybd_event` / `mouse_event`). - Cả 2 Adapter đều được bảo vệ bởi **Focus Interlock Port** (`IWindowFocusGuard`). ### 3.3. Bất Biến C++23 Bắt Buộc (Tier 1 Invariants): - **INV-T1-01 (Zero Dynamic Allocation)**: Tuyệt đối cấm `new`, `delete`, `malloc`, `std::vector::push_back` trong vòng lặp 120Hz. Mọi mảng buffer phải pre-allocated. - **INV-T1-02 (Zero Unhandled Exceptions)**: Vòng lặp chính tuyệt đối không được crash. Mọi lỗi bộ nhớ phải được cô lập bằng error codes an toàn. - **INV-T1-03 (Graceful Degrade)**: Mất kết nối Watchdog với Python > 5000ms chỉ khiến Core hạ cấp về `Co-Pilot Passive Mode`, cấm `RequestStop()`. --- ## 4. ĐẶC TẢ CHI TIẾT KÊNH GIAO TIẾP IPC (LOCK-FREE SHARED MEMORY) Kênh IPC kết nối Tier 1 và Tier 2 hoạt động theo nguyên lý **Mechanical Sympathy** — tối ưu hóa theo đúng cấu trúc phần cứng x86-64: ``` [VÙNG NHỚ CHIA SẺ 4MB: Local\POE2_Auto_SharedMem_v1] ├── 0x000000 - 0x00003F : SharedMemoryHeader (64B, Khớp 1 Cache Line L1) │ [magic, version, isRunning, seq_telemetry, seq_cmd, read_idx, heartbeat_core, heartbeat_agent] ├── 0x000040 - 0x0098EF : Telemetry Slot 0 (39.112 Bytes) ├── 0x0098F0 - 0x01319F : Telemetry Slot 1 (39.112 Bytes) └── 0x300000 - 0x3003FF : SPSC Command Ring Buffer (16 Slots * 64B Stride = 1.024 Bytes) ``` ### 4.1. Telemetry Seqlock Double-Buffer Contract - **Cơ chế**: Core C++ ghi luân phiên vào Slot chẵn/lẻ bằng `telemetrySequence` atomic store-release. Python Companion đọc bằng load-acquire và kiểm tra số thứ tự chẵn/lẻ trước và sau khi đọc. - **Cam kết kỹ thuật**: **0 torn-read** (đã được chứng thực qua 2.452.862 lượt đọc ở tần số 2kHz). - **Kích thước chuẩn**: `sizeof(TelemetryPacket) == 39.112 Bytes` (Header 64B + Player 84B + 256 Entities * 88B + Area 96B + Vitals/Buffer metadata). ### 4.2. SPSC Command Ring Buffer Contract - **Cơ chế**: Single Producer (Python Agent) - Single Consumer (C++ Core). - **Lock-Free**: Con trỏ `commandSequence` chỉ do Python tăng; con trỏ `commandReadIndex` chỉ do C++ tăng. Hoàn toàn miễn nhiễm với Deadlock và Starvation. --- ## 5. ĐẶC TẢ CHI TIẾT TIER 2: PYTHON 3.11 COMPANION & AGENTIC ENGINE Tầng Tier 2 vận hành theo mô hình **Event-Driven Architecture (EDA)**, giải phóng hoàn toàn gánh nặng cho giao diện người dùng và mở rộng tính năng theo dạng module cắm/rút. ### 5.1. Central EventBus Architecture Toàn bộ dữ liệu telemetry từ Shared Memory được đẩy vào EventBus nội bộ, phân phối bất đồng bộ tới các subscribers độc lập: ```python # Sơ đồ luồng EventBus trong Tier 2 TelemetryPoller(30Hz) │ ▼ EventBus.emit("TELEMETRY_UPDATED", snapshot) │ ├──> InvariantSentinel.on_telemetry(snapshot) # Giám sát 14 bất biến an toàn ├──> DashboardController.on_telemetry(snapshot) # Cập nhật số liệu UI ├──> ItemHoverWatcher.on_telemetry(snapshot) # Kích hoạt soi đồ khi chuột rê ├──> TacticalBrain.on_telemetry(snapshot) # Phân tích đề xuất vĩ mô └──> FlightRecorder.on_telemetry(snapshot) # Lưu trữ buffer 30 ticks ``` ### 5.2. Giải Phẫu & Mô-Đun Hóa Giao Diện (Decoupled MVC/MVVM) File nguyên khối `control_center.py` (2.680 dòng) được phân rã triệt để thành các thành phần chuyên biệt (< 400 dòng/file): ``` src/assistant_tool/ui/ ├── app.py # Entry point khởi tạo Window & EventBus (< 200 dòng) ├── controllers/ │ ├── telemetry_controller.py# Điều phối dữ liệu SHM và Watchdog │ └── hotkey_controller.py # Lắng nghe phím tắt Win32 non-blocking ├── views/ │ ├── header_view.py # Trạng thái bot, logo, license │ ├── hud_strip_view.py # Thanh thông tin nhanh HP/ES/Zone │ ├── left_panel_view.py # Cấu hình tính năng (Quest, Combat, Pickit) │ └── right_panel_view.py # Log realtime và Invariant status └── widgets/ # Các UI widget tái sử dụng (Slider, Switch, Badge) ``` ### 5.3. Bất Biến Python 3.11 Bắt Buộc (Tier 2 Invariants): - **INV-T2-01 (Zero Silent Swallowing)**: Xóa bỏ 100% các khối `except: pass`. Mọi lỗi phải được ghi log kèm traceback và ngữ cảnh thông qua `src/common/logging_util.py`. - **INV-T2-02 (Anti-GIL Non-Blocking UI)**: Các tác vụ nặng (OCR, Screen Capture, Network Request, Ghi đĩa) tuyệt đối không chạy trên luồng chính của giao diện Tkinter. - **INV-T2-03 (Zero Proxy Shims)**: Nghiêm cấm tạo các file proxy shim 5–10 dòng. Toàn bộ import phải đi trực tiếp tới Single Source of Truth (`src.agentic_engine.*` hoặc `src.common.*`). --- ## 6. ĐẶC TẢ CHI TIẾT TIER 3: ANCILLARY COLD WORKERS (MỞ RỘNG VĨ MÔ) Tầng Tier 3 là các tiến trình hoặc tác vụ bất đồng bộ (`asyncio`) phục vụ các tiện ích mở rộng không ảnh hưởng đến gameplay trực tiếp: - **Discord Webhook Worker**: Gửi ảnh chụp và thống kê khi nhặt Mirror/Divine hoặc khi hạ Boss Act/Map. - **Trade Market Sniffer**: Truy vấn REST API `trade.pathofexile.com` để tự động định giá đồ rơi theo thời giá thực tế của League. - **Gemini / Local LLM Strategic Advisor**: Phân tích cây kỹ năng passive tree, đề xuất nâng cấp đồ và chiến thuật đối phó với Boss có mechanic phức tạp. --- ## 7. LỘ TRÌNH CHUYỂN DỊCH TỪ CODE HIỆN TẠI SANG KIẾN TRÚC MỤC TIÊU Quá trình chuyển dịch diễn ra theo 4 giai đoạn an toàn, khóa chặn bằng bộ kiểm thử thực nghiệm: ```mermaid gantt title Lộ Trình Tái Cấu Trúc Two-Tier Asymmetric Hybrid Architecture 2026 dateFormat YYYY-MM-DD section Giai đoạn 1 (Foundation) Xây dựng thư viện dùng chung src/core/common/ :2026-09-14, 3d Xây dựng thư viện dùng chung src/common/ (Python) :2026-09-17, 3d Khắc phục 5 điểm xung đột P0 (IPC, Kiting, HID) :2026-09-20, 2d section Giai đoạn 2 (Decoupling) Gom cụm Invariant Sentinel & xóa 9 Proxy Shims :2026-09-22, 2d Tách Hexagonal Adapters trong C++ (RPM & KMBox) :2026-09-24, 4d section Giai đoạn 3 (Modularization) Giải phẫu Monolith control_center.py sang MVC :2026-09-28, 5d Bóc tách GameSession thành Data-Oriented Pipeline :2026-10-03, 5d section Giai đoạn 4 (Commercial Hardening) Kiểm thử tải 24/7 trên Headless Test Harness :2026-10-08, 4d Nghiệm thu toàn diện 100% Empirical DoD :2026-10-12, 2d ``` --- ## 8. KẾT LUẬN & ĐIỀU KHOẢN HIỆU LỰC Tài liệu này là **Hiến pháp Kỹ thuật cao nhất (Supreme Technical Constitution)** của dự án AutoPOE2. Mọi can thiệp mã nguồn, thiết kế tính năng mới hoặc tái cấu trúc trong tương lai bắt buộc phải đối chiếu và tuân thủ 100% các nguyên tắc bất biến của **Two-Tier Asymmetric Hybrid Architecture**.