# 64. Đặc Tả Kiến Trúc: Multi-Instance, Windowed Background Execution & Desktop Isolation

- **Mã tài liệu**: `SPEC-DOC-64-MULTI-INSTANCE-AND-BACKGROUND-ISOLATION-20260916`
- **Mốc thời gian**: `16/09/2026 20:30:00` (UTC+7)
- **Phiên bản tham chiếu**: Path of Exile 2 **v0.5.5+**, C++23, Python 3.11.9
- **Trạng thái**: `[SSoT KIẾN TRÚC VẬN HÀNH NỀN & KẾ HOẠCH MULTI-INSTANCE]`
- **Tuân thủ quy chuẩn**: Rule 1 (Two-Tier Architecture), Rule 2 (2026 Context), Rule 4 (Common Kernel SSoT), Rule 7 (Controls & Human Interlock)
- **Tài liệu căn cứ trước**:
  - [`docs/development/50_two_tier_asymmetric_hybrid_architecture_specification.md`](./50_two_tier_asymmetric_hybrid_architecture_specification.md)
  - [`docs/development/61_autonomy_gap_audit_and_next_development_basis.md`](./61_autonomy_gap_audit_and_next_development_basis.md)
  - [`docs/development/63_item_inventory_stash_and_gem_lifecycle_specification.md`](./63_item_inventory_stash_and_gem_lifecycle_specification.md)

---

## 1. Tổng Quan Bài Toán Thương Mại Hóa

Để phục vụ đối tượng người dùng số đông và các trang trại cày cuốc tự động (bot farms), hệ thống AutoPOE2 cần giải quyết hai năng lực cốt lõi:
1. **Windowed Non-Hijacking Execution**: Người chơi mở game ở chế độ cửa sổ (Windowed), xếp sang một góc màn hình (ví dụ nửa phải). Tool tự hành cất/rút đồ, chạy map ngầm mà **không chiếm chuột và không cướp tiêu điểm (focus)** của người dùng đang làm việc ở nửa trái màn hình.
2. **Multi-Instance Isolation [PLANNED]**: Chạy song song nhiều instance game Path of Exile 2 trên cùng 1 máy tính vật lý mà không xảy ra xung đột điều khiển (input cross-talk), khóa tiến trình (Mutex), hoặc xung đột tệp tin cấu hình.

---

## 2. Ba Cấp Độ Kiến Trúc Vận Hành Nền (Background Input Architecture)

```
┌──────────────────────────────────────────────────────────────────────────────────────────┐
│               BA CẤP ĐỘ KIẾN TRÚC INPUT VÀ CÁCH LY TIẾN TRÌNH AUTOPOE2                   │
└──────────────────────────────────────────────────────────────────────────────────────────┘
  [CẤP ĐỘ 1: WIN32 MESSAGE QUEUE] -> Triển khai ngay
    │ - Gửi thông điệp chuột/phím trực tiếp tới HWND game: PostMessageW(hwnd, WM_LBUTTONDOWN...)
    │ - Tọa độ client tuyệt đối bù trừ theo get_client_rect(hwnd).
    │ - Con trỏ chuột thật (OS Cursor) tự do 100% cho người dùng thao tác.
    │
  [CẤP ĐỘ 2: VIRTUAL DESKTOP ISOLATION] -> Kế hoạch Multi-Boxing
    │ - Khởi tạo Desktop ảo biệt lập: CreateDesktopW("AutoPOE2_SilentDesktop")
    │ - Gán tiến trình game và worker bot: SetThreadDesktop(hSilentDesk)
    │ - Game chạy Fullscreen/Foreground trên desktop ảo, nhận Full RawInput & KMBox.
    │ - Màn hình vật lý Default của người dùng hoàn toàn không bị ảnh hưởng.
    │
  [CẤP ĐỘ 3: DIRECT MEMORY PACKET DISPATCH] -> Nghiên cứu nội tại
    │ - Gọi trực tiếp hàm nội bộ trong RAM game client hoặc inject packet.
    │ - Thao tác hoàn thành tức thì (0ms), không cần mô phỏng chuột hay render khung hình.
    │ - Đánh giá rủi ro: Khả năng bị phát hiện cao hơn kiến trúc External (Zero-Write).
```

---

## 3. Kiến Trúc Cấp Độ 1: Windowed Mode & PostMessage Adapter

### 3.1. Chuẩn Hóa Bắt Hình Client Area (Anti-Bleeding Screen Capture)
- **Vấn đề**: Khi game chạy ở chế độ Windowed, gọi `GetWindowRect(hwnd)` sẽ chụp cả thanh tiêu đề (Title Bar ~32px) và viền cửa sổ (Borders ~8px). Khi BitBlt từ Desktop DC, nếu người dùng mở ứng dụng khác đè lên nửa trái màn hình, ảnh chụp sẽ bị dính pixel của ứng dụng ngoài (Desktop Bleed).
- **Quy tắc bất biến (`INV-CAPTURE-CLIENT-ONLY`)**:
  - Screen Capture **BẮT BUỘC** gọi `get_client_rect(hwnd)` lấy `(client_left, client_top, client_w, client_h)`.
  - Chỉ BitBlt đúng diện tích client nội bộ của game.
  - Khi ở chế độ ngầm (`background_mode=True`), **TUYỆT ĐỐI CẤM** gọi `SetForegroundWindow` / `ensure_window_focus` để không cướp tiêu điểm bàn phím/chuột của người dùng.

### 3.2. Chuyển Đổi Tọa Độ Bù Trừ (Client to Screen Mapping)
- **UI In-Game (Stash, Inventory, Map Device)**:
  - Tọa độ trích xuất từ Vision/OCR hoặc Memory Matrix là tọa độ tương đối so với Client Area $(x_{\text{client}}, y_{\text{client}})$.
  - Khi gửi qua `PostMessageW`: `lParam = (y_{\text{client}} << 16) | (x_{\text{client}} & 0xFFFF)`.
  - Khi gửi qua chuột vật lý (`mouse_event` / KMBox): 
    $$x_{\text{screen}} = \text{client\_left} + x_{\text{client}}, \quad y_{\text{screen}} = \text{client\_top} + y_{\text{client}}$$

---

## 4. Kế Hoạch Triển Khai Multi-Instance [PLANNED - ROADMAP]

### 4.1. Vượt Trình Khóa Đơn Tiến Trình (Client Singleton Mutex)
- Client POE2 sử dụng Named Mutex để ngăn người dùng mở nhiều hơn một cửa sổ.
- Quy trình bypass:
  1. Sử dụng Win32 Native API `NtQuerySystemInformation(SystemHandleInformation)` để quét toàn bộ handle trong hệ thống.
  2. Lọc handle thuộc tiến trình `PathOfExile.exe` có kiểu `Mutant` hoặc tên chứa chuỗi định danh Singleton.
  3. Sử dụng `DuplicateHandle` với cờ `DUPLICATE_CLOSE_SOURCE` để giải phóng Mutex trong tiến trình game.
  4. Mở instance game tiếp theo an toàn.

### 4.2. Cách Ly Dữ Liệu Cấu Hình & Tài Khoản
- Mỗi instance game cần nạp file cấu hình đồ họa và token tài khoản riêng:
  - *Phương án A*: Sử dụng Sandboxie-Plus Command Line (`Start.exe /box:Account1 PathOfExile.exe`). Tự động sandbox thư mục `%USERPROFILE%\Documents\My Games\Path of Exile 2\`.
  - *Phương án B*: Khởi chạy tiến trình dưới các tài khoản Windows cục bộ khác nhau (`CreateProcessWithLogonW`).

### 4.3. Quản Trị Input Cho Từng Instance Qua Virtual Desktop
- Mỗi instance game được gán vào một Virtual Desktop:
  - Instance 1: `AutoPOE2_Desktop_1`
  - Instance 2: `AutoPOE2_Desktop_2`
- Mỗi bot worker thread gọi `SetThreadDesktop(hDeskN)` và tương tác độc lập 100%, đạt năng suất cày cuốc tối đa trên 1 GPU RTX đa nhân.