# 54. Đặc Tả Kiến Trúc: Tương Tác Đồng Thời Hai Tiến Trình (Dual-Process Coexistence) & Cơ Chế Khử Xung Đột Visual (Visual Deconfliction Architecture)

> **Mã Tài Liệu**: `SPEC-DOC-54-DUAL-EXE-COEXISTENCE-AND-VISUAL-DECONFLICTION-ARCHITECTURE-20260913`  
> **Mốc Thời Gian**: `13/09/2026 - 17:30:00` (UTC+7)  
> **Phiên Bản Game Tham Chiếu**: Path of Exile 2 v0.5.5+ (PE TimeDateStamp `0x6AA2213C`, x64 Windows Client)  
> **Phạm Vi Ứng Dụng**: Hệ thống tích hợp giữa `AutoPOE2` (`C:\Projects\AutoPOE2`) và `Poe2VisualTool` (`C:\Projects\Poe2VisualTool`)  
> **Tác Giả**: Dedicated Sub-Agent Documentation & Architecture Specialist (AutoPOE2)  
> **Tuân Thủ Quy Chuẩn**: Rule 1 (Two-Tier Architecture), Rule 2 (Context 2026), Rule 6 (Pre-Implementation Architecture Spec), Rule 8 (4-Step RCA & Anti-Symptom Patching), Rule 10 (Zero-Drift Code-Doc Contract), Rule 12 (Global Invariant Sweep)  
> **Tài Liệu Căn Cứ Trước**:
> - [`docs/development/53_post_visual_split_remaining_system_audit.md`](./53_post_visual_split_remaining_system_audit.md) (Thẩm định nợ tách Visual trong AutoPOE2)
> - [`docs/development/52_commercial_grade_visual_tool_roadmap_and_production_specification.md`](./52_commercial_grade_visual_tool_roadmap_and_production_specification.md) (Đặc tả sản phẩm thương mại Poe2VisualTool)
> - [`docs/development/31_poe2_native_camera_unclamp_and_minimap_fog_architecture.md`](./31_poe2_native_camera_unclamp_and_minimap_fog_architecture.md) (Cơ chế vá DirectX Shaders và Camera)
> - [`docs/development/06_binary_ipc_protocol_spec.md`](./06_binary_ipc_protocol_spec.md) (Đặc tả IPC Seqlock và SPSC Ring Buffer)

---

## 1. Bối Cảnh Hệ Thống & Tuyên Bố Vấn Đề (Executive Summary & Problem Statement)

### 1.1. Bối Cảnh Tách Rời Hai Dự Án Độc Lập
Theo định hướng kiến trúc năm 2026, toàn bộ hệ sinh thái phần mềm hỗ trợ Path of Exile 2 được phân tách thành hai thực thể độc lập với ranh giới trách nhiệm (Separation of Concerns) rõ ràng:
1. **AutoPOE2 (`C:\Projects\AutoPOE2`)**:
   - Vai trò: Động cơ tự hành thông minh (Autonomous Core Engine) & Trợ lý kinh tế (Passive Companion).
   - Trách nhiệm cốt lõi: Đọc bộ nhớ O(1) không rủi ro (`ReadProcessMemory`), quản lý phản xạ sinh tồn dưới 8.33ms (`ReflexManager`), điều hướng không gian Isometric WASD (`QuestNavigator`), máy trạng thái cày cuốc bản đồ (`BotBrain` & `MapDeviceHandler`), và phân tích kinh tế thụ động (`ControlCenter`).
2. **Poe2VisualTool (`C:\Projects\Poe2VisualTool`)**:
   - Vai trò: Công cụ QoL hình ảnh thương mại cao cấp (Commercial Visual QoL Suite).
   - Trách nhiệm cốt lõi: Mở khóa trần zoom góc nhìn 1.0x – 8.0x (`UnlockZoomCap`), làm mượt thao tác lăn chuột native (`WH_MOUSE_LL`), loại bỏ sương mù thể tích (`DisableVolumetricFog`), khai mở toàn cảnh Minimap Fog of War qua việc can thiệp DirectX 12 visibility shaders, và lớp phủ hiển thị chỉ số trang bị khi rê chuột (`ItemInspector HUD`).

### 1.2. Mối Nguy Xung Đột Khi Hai Tiến Trình Chạy Đồng Thời (Dual-Process Collision Risks)
Trong kịch bản vận hành thực tế của người dùng, cả hai tiến trình `AutoPOE2_Core.exe` (Tier 1 Core Bot) và `Poe2VisualTool.exe` (Standalone Visual Tool) đều chạy đồng thời trên cùng một hệ điều hành Windows và cùng mở handle can thiệp vào một tiến trình mục tiêu duy nhất: `PathOfExile.exe`.

Nếu không có cơ chế khử xung đột kỹ thuật chặt chẽ, hệ thống sẽ đối mặt với 4 thảm họa kỹ thuật:
1. **Tranh chấp ghi vùng nhớ mã máy (Double `.text` Patch Race)**:
   Cả Core và VisualTool đều can thiệp vào các RVA Shader: `kPoe2MinimapGridFillRva` (+0x120D8F8), `kPoe2MinimapUniformRva` (+0x120E480), và `kPoe2MinimapBoundRva` (+0x120E40F). Nếu cả hai cùng gọi `VirtualProtectEx` và `WriteProcessMemory` hoặc một bên gọi `PanicRestoreAll()` trong khi bên kia đang `Maintain()`, xung đột tranh chấp ghi (write race) sẽ gây rách mã máy, kích hoạt lỗi `0xC0000005 ACCESS_VIOLATION` trong luồng DirectX render và làm văng game (CTD) ngay lập tức.
2. **Xung đột giá trị Camera Float Triad (Camera State Fighting)**:
   Core định kỳ ghi giá trị mặc định (`maxDistance = 118.09f`) trong khi VisualTool áp dụng hệ số zoom của người dùng (`maxDistance = 413.3f` ở 3.5x). Hai tiến trình ghi đè liên tục tạo ra hiện tượng giật giật khung hình (camera stutter/flicker) cực kỳ nghiêm trọng.
3. **Chiếm dụng Mutex & Rách Bộ nhớ Chia sẻ IPC (IPC Collision)**:
   Cả hai repo trước đây đều dùng chung định danh `AutoPOE2_VisualTool_v1` và mutex `AutoPOE2_VisualTool_Singleton`, khiến instance thứ hai chiếm nhầm mapping hoặc không thể mở cổng điều khiển.
4. **Lệch pha ngữ nghĩa phím khẩn cấp (Panic Semantic Drift)**:
   Khi người dùng nhấn phím dừng khẩn cấp (`Pause/Break` hoặc `Ctrl+Shift+F12`), Core hiểu là "dừng bot và hoàn nguyên visual mods", trong khi VisualTool hiểu là "hoàn nguyên visual mods và tiếp tục chạy".

---

## 2. Sơ Đồ Kiến Trúc Tương Tác Hai Tiến Trình (Dual-Process Topology)

Hệ thống thiết lập cơ chế **Độc quyền Ghi Hình ảnh (Exclusive Visual Writer)** dành cho `Poe2VisualTool.exe` kết hợp với **Cơ chế Nhượng quyền Thụ động (Passive Delegation)** tích hợp trong `AutoPOE2_Core.exe`.

```mermaid
graph TB
    subgraph POE2_Client ["Tiến Trình Game: PathOfExile.exe (PID Target)"]
        DirectX_Text [".text Shaders Patches<br/>+0x120D8F8, +0x120E480, +0x120E40F"]
        Camera_Heap ["Camera Float Triad<br/>currentDistance, maxDistance, zFar"]
        Fog_Heap ["Fog Density Float<br/>fogDensity = 0.0f"]
        Player_RAM ["Player State & Vitals<br/>LifeComponent, XYZ, AreaInstance"]
    end

    subgraph AutoPOE2_System ["Hệ Thống Tự Hành: AutoPOE2"]
        Core ["AutoPOE2_Core.exe (Tier 1 Core Bot)<br/>- 120Hz Hot Path Loop<br/>- Passive Delegation Active<br/>- RPM Read-Only (Vitals, XYZ)"]
        Companion ["Control Center GUI (Python 3.11)<br/>- Dashboard & Bot Lifecycle<br/>- Launch / Focus Delegation"]
        SHM_Core ["Shared Memory 4MB<br/>'Local\\POE2_Auto_SharedMem_v1'"]
    end

    subgraph Visual_System ["Hệ Thống Hình Ảnh: Poe2VisualTool"]
        VisualExe ["Poe2VisualTool.exe (Standalone C++23)<br/>- EXCLUSIVE MASTER WRITER<br/>- WH_MOUSE_LL Smooth Zoom<br/>- Maintain 50ms & 1-Frame Panic"]
        VisualGUI ["Visual Tool GUI (Python / SysTray)<br/>- Zoom Slider & Fog Toggles"]
        SHM_Visual ["Shared Memory 48 Bytes<br/>'Poe2VisualTool_v1'"]
        Mutex_Visual ["Mutex Singleton<br/>'Poe2VisualTool_Singleton'"]
    end

    %% Giao tiếp AutoPOE2
    Companion <==>|Seqlock 30Hz & SPSC Ring| SHM_Core
    SHM_Core <==>|120Hz Telemetry & Commands| Core
    Core -->|RPM 120Hz O(1) Read-Only| Player_RAM

    %% Giao tiếp Visual System
    VisualGUI <==>|IPC Struct 48B| SHM_Visual
    SHM_Visual <==>|State & Flags| VisualExe
    VisualExe --- Mutex_Visual

    %% Can thiệp bộ nhớ Game
    VisualExe ==>|WPM Exclusive Writer: 50ms Maintain| DirectX_Text
    VisualExe ==>|WPM Exclusive Writer: Native Wheel| Camera_Heap
    VisualExe ==>|WPM Exclusive Writer: Zero Fog| Fog_Heap

    %% Cơ chế Khử Xung Đột & Nhượng Quyền
    Core -.->|1. Probe Mutex / Process Check| Mutex_Visual
    Core -.->|2. Nhượng Quyền Hoàn Toàn (0ms NOP)| DirectX_Text
    Companion -.->|3. Ưu tiên Launch / Focus GUI| VisualGUI

    classDef danger fill:#fee2e2,stroke:#ef4444,stroke-width:2px;
    classDef success fill:#dcfce7,stroke:#22c55e,stroke-width:2px;
    classDef neutral fill:#f1f5f9,stroke:#64748b,stroke-width:1px;

    class DirectX_Text,Camera_Heap,Fog_Heap danger;
    class VisualExe,Mutex_Visual success;
    class Core,Companion,SHM_Core neutral;
```

---

## 3. Ma Trận Khử Xung Đột Toàn Diện (Deconfliction Matrix)

Bảng phân định quyền hạn tuyệt đối giữa hai tiến trình trên toàn bộ tài nguyên bộ nhớ và hệ thống:

| Tài Nguyên / Địa Chỉ | Tiến Trình Làm Chủ (Exclusive Master) | Tiến Trình Nhượng Quyền (Delegated Passive) | Cơ Chế Xảy Ra Xung Đột Nếu Không Khử | Giải Pháp Kỹ Thuật & Khóa Bất Biến |
|---|---|---|---|---|
| **Vùng nhớ `.text` Shaders**<br/>RVA `+0x120D8F8`<br/>RVA `+0x120E480`<br/>RVA `+0x120E40F` | **`Poe2VisualTool.exe`** | **`AutoPOE2_Core.exe`** | Cả hai cùng `VirtualProtectEx` + `WriteProcessMemory`, gây torn-code hoặc khôi phục mã gốc đè lên nhau $\implies$ Crash `0xC0000005`. | `AutoPOE2_Core` vô hiệu hóa hoàn toàn lệnh vá shader khi phát hiện `Poe2VisualTool`. Bất biến **`INV-DUAL-VISUAL-01`**. |
| **Camera Float Triad**<br/>`currentDistance`<br/>`maxDistance`<br/>`zFar` | **`Poe2VisualTool.exe`** | **`AutoPOE2_Core.exe`** | Core ghi triad mặc định (1.0x), VisualTool ghi triad mở rộng (3.5x) $\implies$ Giật hình (camera stutter), rung lắc màn hình liên tục. | `AutoPOE2_Core` ngừng chạy hàm `Maintain()` camera float triad; chỉ thực hiện RPM đọc góc nhìn nếu cần tính toán tọa độ. |
| **Volumetric Fog Density**<br/>`fogDensity = 0.0f` | **`Poe2VisualTool.exe`** | **`AutoPOE2_Core.exe`** | Core và VisualTool cùng ghi đè con trỏ cấu trúc sương mù $\implies$ Xung đột cache dữ liệu heap. | VisualTool độc quyền ghi `0.0f` khi cờ `kVisualFlagDisableFog` bật. Core không can thiệp. |
| **Phím Tắt Panic Killswitch**<br/>`Pause/Break`<br/>`Ctrl+Shift+F12` | **Độc lập hai phân vùng** | **Độc lập hai phân vùng** | Core gọi `PanicRestoreAll()` làm hoàn nguyên camera của VisualTool, hoặc VisualTool ngắt nhầm vòng lặp sinh tồn của bot. | **Phân tách ngữ nghĩa**: Core chỉ dừng bot, thả phím chuột, cấm đụng camera. VisualTool độc quyền hoàn nguyên camera về 1.0x trong 1-frame. Bất biến **`INV-DUAL-PANIC-03`**. |
| **Mutex Singleton Hệ Điều Hành** | `Poe2VisualTool_Singleton` | `Local\AutoPOE2_Core_Singleton` | Dùng chung một mutex khiến instance sau coi instance trước là trùng lặp và tự sát. | Phân tách tên Mutex tường minh: Sibling Visual dùng `Poe2VisualTool_Singleton`, Core dùng namespace riêng. Bất biến **`INV-DUAL-IPC-04`**. |
| **Bộ Nhớ Chia Sẻ IPC** | `Poe2VisualTool_v1` (48B) | `Local\POE2_Auto_SharedMem_v1` (4MB) | Dùng chung tên Shared Memory làm rách header hoặc tràn bộ đệm cấu trúc struct khác nhau. | IPC Bot 4MB phục vụ Telemetry 120Hz; IPC Visual 48B phục vụ nấc zoom và cờ QoL. Không chồng lấn. |

---

## 4. Cơ Chế Nhượng Quyền Thụ Động (Passive Delegation Architecture Trong AutoPOE2_Core)

### 4.1. Thuật Toán Nhận Diện Hiện Diện (Presence Detection Algorithm)
Ngay khi khởi tạo `GameSession` hoặc tại mỗi chu kỳ kiểm tra cảnh nạp (`OnZoneLoadingFinished`), `AutoPOE2_Core` thực hiện kiểm tra đa tầng sự hiện diện của `Poe2VisualTool`:

```cpp
bool CheckPoe2VisualToolRunning() {
    // 1. Kiểm tra qua Named Mutex Singleton (O(1) - Chi phí < 1 microsecond)
    HANDLE hMutex = OpenMutexW(SYNCHRONIZE, FALSE, L"Poe2VisualTool_Singleton");
    if (hMutex != NULL) {
        CloseHandle(hMutex);
        return true; // Poe2VisualTool đang hoạt động!
    }

    // 2. Fallback: Kiểm tra qua tên tiến trình trong snapshot
    return common::FindProcessByName(L"Poe2VisualTool.exe") != 0;
}
```

### 4.2. Khóa Cắt Mạch Can Thiệp (Circuit Breaker Interlock)
Khi phát hiện `Poe2VisualTool` đang chạy:
1. Gán cờ nội bộ `m_isVisualDelegated = true`.
2. Ghi nhật ký hệ thống:
   ```text
   [VisualMods] ⚡ PHÁT HIỆN 'Poe2VisualTool.exe' ĐANG HOẠT ĐỘNG!
   [VisualMods] >> Kích hoạt cơ chế Nhượng Quyền Thụ Động (Passive Delegation).
   [VisualMods] >> Vô hiệu hóa 100% Maintain(), ApplyZoom() và PanicRestoreAll() trong Core Engine.
   ```
3. Mọi lời gọi từ vòng lặp chính 120Hz tới `gameSession.MaintainVisualMods()` hoặc khi nạp cờ `--zoom` / `--no-fog` trên CLI của Core đều bị chặn ngay ở microsecond đầu tiên bằng đoản mạch:
   ```cpp
   void GameSession::MaintainVisualMods() {
       if (m_isVisualDelegated) {
           return; // 0ms NOP - Nhường quyền hoàn toàn cho Poe2VisualTool
       }
       // ... logic cũ chỉ chạy khi CHẮC CHẮN không có Poe2VisualTool ...
   }
   ```
4. Khi nhận tín hiệu dừng khẩn cấp Panic (`Pause/Break` hoặc `Ctrl+Shift+F12`):
   ```cpp
   if (m_isVisualDelegated) {
       // CẤM GỌI m_visualModsEngine.PanicRestoreAll()!
       // Chỉ giải phóng input chuột phím và yêu cầu dừng Core
       ReleaseAllInputsFailsafe();
       m_shm.RequestStop();
   } else {
       // Standalone Core fallback cũ
       ReleaseAllInputsFailsafe();
       m_visualModsEngine.PanicRestoreAll();
       m_shm.RequestStop();
   }
   ```

---

## 5. Phân Định Ngữ Nghĩa Hotkeys Toàn Cục (Global Hotkeys Delineation)

Để loại bỏ hoàn toàn sự xung đột khi người dùng thao tác phím nóng trong game, hệ thống quy định hợp đồng phân quyền phím rõ ràng:

```mermaid
graph LR
    User["Người Chơi Thao Tác Phím Nóng"] --> KeyAction{"Phím Nóng Đã Bấm"}

    KeyAction -->|Pause / Break HOẶC Ctrl+Shift+F12| PanicBranch["SỰ KIỆN DỪNG KHẨN CẤP (PANIC)"]
    KeyAction -->|F8 hoặc F6| BotToggle["BẬT / TẮT BOT TỰ HÀNH"]
    KeyAction -->|F11| XYZCalib["TÁI ĐỊNH VỊ TỌA ĐỘ XYZ"]
    KeyAction -->|Numpad + / - HOẶC [ / ]| ZoomAdjust["ĐIỀU CHỈNH TRẦN ZOOM"]
    KeyAction -->|Con Lăn Chuột Wheel| SmoothZoom["ZOOM MƯỢT NATIVE"]

    PanicBranch --> CorePanic["AutoPOE2_Core.exe:<br/>- Xả toàn bộ phím WASD, Space, Chuột<br/>- Ngắt nhận lệnh SPSC Ring<br/>- DỪNG CORE (RequestStop)<br/>- ⚠️ CẤM ĐỤNG VÀO CAMERA/SHADERS"]
    PanicBranch --> VisualPanic["Poe2VisualTool.exe:<br/>- Khôi phục camera về 1.0x (118.09f)<br/>- Hoàn nguyên 8 bytes gốc DirectX Shaders<br/>- Khôi phục mật độ sương mù gốc<br/>- THỰC THI TRONG < 1MS"]

    BotToggle --> CoreToggle["Xử lý độc quyền trong Core Engine"]
    XYZCalib --> CoreCalib["Kích hoạt PlayerFinder 16MB trong Core"]
    ZoomAdjust --> VisualAdjust["Xử lý độc quyền trong Poe2VisualTool"]
    SmoothZoom --> VisualSmooth["Hook WH_MOUSE_LL trong Poe2VisualTool"]
```

---

## 6. Phân Tách Không Gian Tên Mutex & IPC (Namespace Partitioning)

Hai hệ thống sử dụng không gian tên riêng biệt tuyệt đối trong Windows Object Manager (`Local\` namespace):

```text
========================================================================================
HỆ THỐNG AUTOPОE2 (CORE BOT & COMPANION)
----------------------------------------------------------------------------------------
- Telemetry & Command IPC : "Local\POE2_Auto_SharedMem_v1" (Kích thước: 4,194,304 bytes)
- Core Singleton Mutex    : "Local\AutoPOE2_Core_Singleton"
- Magic Gói Tin           : 0x504F45324155544FULL ("POE2AUTO")
- Giao Thức Đồng Bộ       : Seqlock Double-Buffering (Slot 0 & Slot 1) + SPSC Ring Buffer

========================================================================================
HỆ THỐNG POE2VISUALTOOL (STANDALONE VISUAL SUITE)
----------------------------------------------------------------------------------------
- Visual State IPC        : "Poe2VisualTool_v1" (Kích thước: 48 bytes)
- Legacy Fallback IPC     : "AutoPOE2_VisualTool_v1" (Hỗ trợ tương thích ngược)
- Visual Singleton Mutex  : "Poe2VisualTool_Singleton"
- Magic Gói Tin           : 0x56543031u ('VT01')
- Giao Thức Đồng Bộ       : Atomic Flags Bitmask + Seqlock 32-bit
========================================================================================
```

---

## 7. Luồng Khởi Chạy Từ Giao Diện Control Center GUI (Companion Integration Flow)

Trong giao diện `control_center.py` của AutoPOE2, khi người dùng nhấp vào nút **"👁️ Mở Visual Tool"**:
1. **Kiểm tra tiêu điểm cửa sổ hiện hữu (`_focus_existing_gui`)**:
   Tìm kiếm cửa sổ có tiêu đề `"Path of Exile 2 - Visual Tool"` hoặc `"AutoPOE2 Visual Tool"`. Nếu cửa sổ đã mở, đưa ngay lên tiền cảnh (`SetForegroundWindow`) và không tạo thêm tiến trình mới.
2. **Ưu tiên khởi chạy Executable độc lập (`Poe2VisualTool.exe`)**:
   Hệ thống dò tìm theo thứ tự ưu tiên:
   - Đường dẫn cấu hình tuỳ chọn trong `user_settings.json`.
   - `C:\Projects\Poe2VisualTool\build\Release\Poe2VisualTool.exe`.
   - `C:\Projects\Poe2VisualTool\bin\Release\Poe2VisualTool.exe`.
   - Các thư mục cài đặt thương mại (`Program Files\Poe2VisualTool\Poe2VisualTool.exe`).
3. **Fallback cục bộ**:
   Chỉ khi không tìm thấy executable của dự án sibling, Control Center mới kích hoạt kịch bản fallback chạy script nội bộ `run_visual_tool.py`.

```mermaid
sequenceDiagram
    autonumber
    actor User as Người Chơi
    participant GUI as ControlCenter GUI (Python)
    participant Win32 as Win32 Window API
    participant Sibling as Poe2VisualTool.exe
    participant Fallback as run_visual_tool.py

    User->>GUI: Bấm nút '👁️ Mở Visual Tool'
    GUI->>Win32: _focus_existing_gui('Poe2VisualTool')
    alt Cửa sổ Visual Tool đã tồn tại
        Win32-->>GUI: Window Handle (HWND) hợp lệ
        GUI->>Win32: SetForegroundWindow(hwnd)
        GUI-->>User: Đưa giao diện hiện hữu lên trước
    else Chưa có cửa sổ mở sẵn
        GUI->>GUI: Dò tìm Poe2VisualTool.exe (Sibling build/installed)
        alt Tìm thấy Poe2VisualTool.exe
            GUI->>Sibling: subprocess.Popen(['Poe2VisualTool.exe'])
            Sibling-->>User: Giao diện thương mại độc lập khởi động
        else Không tìm thấy Standalone Exe
            GUI->>Fallback: subprocess.Popen([python, run_visual_tool.py])
            Fallback-->>User: Chạy GUI nội bộ tương thích cũ
        end
    end
```

---

## 8. Danh Mục Các Bất Biến Kiến Trúc Bắt Buộc (Architectural Invariants Matrix)

Mọi dòng mã bổ sung hoặc hiệu chỉnh trong cả hai dự án bắt buộc phải tuân thủ nghiêm ngặt 5 bất biến kiến trúc sau:

| Mã Bất Biến | Tên Bất Biến & Định Nghĩa Toán Học / Kỹ Thuật | Hành Vi Bị CẤM TUYỆT ĐỐI (Zero Tolerance) | Chế Tài Xử Lý Lỗi (Enforcement) |
|---|---|---|---|
| **`INV-DUAL-VISUAL-01`** | **Exclusive Visual Master Writer**<br/>Chỉ duy nhất một tiến trình được phép gọi `WriteProcessMemory` vào vùng Shaders RVA `+0x120D8F8` và Camera Triad tại một thời điểm. | CẤM `AutoPOE2_Core.exe` duy trì luồng ghi định kỳ `Maintain()` khi `Poe2VisualTool` đang gắn vào client. | Core tự động đoản mạch (short-circuit), trả về `0ms NOP`. |
| **`INV-DUAL-DELEGATION-02`**| **Core Passive Delegation**<br/>Khi phát hiện Mutex `Poe2VisualTool_Singleton` hoặc tiến trình `Poe2VisualTool.exe`, Core chuyển sang chế độ nhượng quyền toàn phần. | CẤM Core nạp đè giá trị camera mặc định lên trên giá trị mà người dùng đã chỉnh trong Visual Tool. | Bỏ qua ghi heap, chỉ đọc viễn trắc. |
| **`INV-DUAL-PANIC-03`** | **Decoupled Panic Semantics**<br/>Phím tắt dừng khẩn cấp Panic trong Core chỉ có quyền năng với logic tự hành (Bot actions & Keyboard release). | CẤM Core gọi `PanicRestoreAll()` visual mods khi đang ở trạng thái nhượng quyền thụ động. | Tách rời luồng xử lý `ReleaseAllInputsFailsafe()` khỏi `RestoreVisualMods()`. |
| **`INV-DUAL-IPC-04`** | **Clean Namespace Partitioning**<br/>Không gian tên Mutex và Bộ nhớ chia sẻ IPC phải tách biệt 100% giữa Bot và Visual Tool. | CẤM sử dụng chung một tên IPC struct khác kích thước (`4MB` vs `48B`). | Định danh chuẩn: Core dùng `POE2_Auto_SharedMem_v1`; Sibling dùng `Poe2VisualTool_v1`. |
| **`INV-DUAL-LAUNCH-05`**| **Preferred Standalone Execution**<br/>Control Center luôn ưu tiên mở tiến trình thương mại độc lập của sibling repo thay vì spawn script nội bộ cũ. | CẤM sinh thêm một instance thứ hai gây xung đột mutex singleton. | Gọi `_focus_existing_gui()` trước khi `subprocess.Popen()`. |

---

## 9. Tiêu Chuẩn Nghiệm Thu Thực Nghiệm (Empirical Definition of Done - DoD)

Hợp đồng kỹ thuật DOC-54 chỉ được coi là nghiệm thu thành công khi vượt qua đầy đủ 4 cửa ải kiểm thử:
1. **Kiểm tra Biên dịch & Khớp nối Nhị phân (Compilation & Protocol Gate)**:
   - `protocol.hpp` phía C++ và Python bindings giữ vững `sizeof(VisualToolSharedState) == 48` và `sizeof(TelemetryPacket) == 39112`.
   - `AutoPOE2_Tests.exe` chạy 100% PASS, xác minh logic `CheckPoe2VisualToolRunning()` hoạt động chuẩn xác trên môi trường mô phỏng.
2. **Kiểm thử Đồng thời (Concurrent Coexistence Gate)**:
   - Khởi động đồng thời cả `AutoPOE2_Core.exe` và `Poe2VisualTool.exe` cùng attach vào game client:
     * Log Core hiển thị: `[VisualMods] >> Kích hoạt cơ chế Nhượng Quyền Thụ Động (Passive Delegation)`.
     * Camera in-game zoom mượt mà lên 3.5x qua con lăn chuột mà không hề bị giật giật (0% camera flicker).
     * Tuyệt đối không xảy ra lỗi `0xC0000005 ACCESS_VIOLATION` sau 30 phút chạy liên tục qua 5 bản đồ chuyển cảnh.
3. **Kiểm thử Dừng Khẩn Cấp (Panic Deconfliction Gate)**:
   - Khi bot đang chạy và camera đang ở mức zoom 4.0x:
     * Nhấn tổ hợp `Ctrl + Shift + F12` hoặc phím `Pause/Break`:
     * Bot Core lập tức dừng lại, nhả toàn bộ phím `WASD` và chuột.
     * Góc nhìn camera vẫn giữ nguyên hoặc được hoàn nguyên mượt mà bởi `Poe2VisualTool`, không gây treo game hoặc xung đột bộ nhớ.
4. **Kiểm thử Tích hợp Control Center (GUI Launch Gate)**:
   - Nhấn nút "👁️ Mở Visual Tool" trên Control Center:
     * Lần 1: Khởi động thành công `Poe2VisualTool.exe`.
     * Lần 2: Tự động đưa cửa sổ Visual Tool đã mở lên tiền cảnh, không sinh tiến trình rác thứ hai.