---
id: hardware-focus-interlock-safety
trigger: "khi gửi input qua KMBox / Win32 hoặc xảy ra hiện tượng rò rỉ phím ra màn hình Desktop"
confidence: 0.99
domain: "hardware_safety"
scope: "project"
summary: "Chỉ chặn KeyDown/MouseDown khi unfocused. TUYỆT ĐỐI CẤM chặn KeyUp/MouseUp để tránh kẹt phím vi điều khiển KMBox. Tự động gọi ReleaseAllKeys() khi mất focus."
---

# Instinct: Khóa An Toàn Phần Cứng Tiền Cảnh (INV-FOCUS-INTERLOCK-HARDWARE-SAFETY)

**SSoT đầy đủ:** [`docs/development/72_hardware_safety_and_focus_interlock_specification.md`](../../docs/development/72_hardware_safety_and_focus_interlock_specification.md). File này chỉ là phản xạ ngắn.

## 1. Bối Cảnh & Hiện Tượng
Khi người dùng chuyển cửa sổ (Alt+Tab sang trình duyệt, IDE hoặc Desktop làm việc), xuất hiện hiện tượng các phím `aswd` hoặc click chuột tự động gõ bất thường vào cửa sổ đang làm việc của người dùng.

## 2. Nguyên Nhân Gốc Rễ (RCA)
1. **Lỗi Kẹt Phím Phần Cứng (Hardware Key Latch)**:
   - Các hàm `KeyUp(hidScanCode)` và `KeyUpVk(vkCode)` kiểm tra `if (!IsGameWindowFocused()) return false;`.
   - Khi mất focus, `KeyUp` bị TỪ CHỐI THỰC THI. Phần cứng KMBox (USB HID) tiếp tục giữ trạng thái đè phím trong bộ nhớ vi điều khiển, khiến hệ điều hành ghi nhận phím bị kẹt và gõ liên tục vào Desktop.
2. **Ngộ nhận tiêu đề cửa sổ (Browser False Positive)**:
   - Dùng `wcsstr(title, L"Path of Exile")` ngộ nhận các tab trình duyệt tra cứu POE Trade / Wiki là game POE2.
3. **Nghẽn Action Gatekeeper**:
   - `KeyUp` và `MouseUp` gọi `RecordAction()` làm ngốn hết hạn mức APM của người dùng, khiến các phím tiếp theo bị từ chối.
4. **Nhầm lẫn giữa Simulation Mode và Physical Input (Simulation Leakage - 19/09/2026)**:
   - Hàm `_is_focus_allowed` trả về `True` khi `is_simulated=True` hoặc `_GLOBAL_SIMULATED_FOCUS=True` để FSM advance trong headless tests.
   - Các hàm gửi input hiểu nhầm giá trị này là `allow_physical=True`, gọi thẳng `SendInput` và `keybd_event` vào terminal IDE / trình duyệt của người dùng.
5. **Thiếu Real-Time Sentinel trong vòng lặp Dwell**:
   - Vòng lặp WASD 350ms chỉ kiểm tra focus 1 lần ở đầu hàm, không kiểm tra lại từng nhịp 35ms khi người dùng alt-tab giữa chừng.

## 3. Phản Xạ Hành Động Chuẩn Mực (Standard Operating Procedure)
1. **Quy tắc Vàng Cấp Thấp**:
   - **Chỉ chặn `KeyDown` và `MouseDown` khi unfocused**.
   - **TUYỆT ĐỐI CẤM chặn `KeyUp` và `MouseUp`**: Mọi yêu cầu nhả phím và nhả chuột phải luôn được gửi 100% xuống phần cứng KMBox để giải phóng thanh ghi vi điều khiển USB HID!
2. **Tự động kích hoạt `ReleaseAllKeys()` khi mất Focus**:
   - Khi phát hiện cửa sổ game chuyển trạng thái `m_lastGameFocused == true` sang `currentlyFocused == false`, KMBoxNet tự động giải phóng toàn bộ phím đang giữ và gửi xung nhả danh sách phím cốt lõi (`WASD`, `Move-Only`, `Space`, `Ctrl`, `Shift`, `Alt`, `Q`, `E`, `R`, `1-5`).
3. **Phân tách tuyệt đối giữa Simulation Mode và Physical Input (`INV-FOCUS-SAFETY-SEPARATION`)**:
   - Khi `is_simulated=True` hoặc `_GLOBAL_SIMULATED_FOCUS is not None`: Logic test trả về `True`, nhưng `allow_physical` BẮT BUỘC bằng `False`. **TUYỆT ĐỐI 0 BYTE INPUT CHẠM VÀO WINDOWS OS TRONG QUÁ TRÌNH CHẠY TEST HOẶC MÔ PHỎNG**.
   - `_is_physical_allowed` chỉ trả về `True` khi: `not is_simulated and _GLOBAL_SIMULATED_FOCUS is None and is_poe2_window_focused(hwnd)`.
4. **Kiểm tra Focus thời gian thực trong từng nhịp 35ms (Real-Time Focus Sentinel)**:
   - Trong mọi vòng lặp di chuyển WASD, kiểm tra focus mỗi nhịp 35ms. Nếu mất focus dù chỉ 1ms, lập tức `break`, gọi `emergency_release_wasd_keys()` và dừng xả phím.
5. **Chốt chặn độc lập tại các hàm cơ sở (Defense-in-Depth)**:
   - `_send_input_keys`, `set_cursor_pos`, `hover` tự kiểm tra `_is_physical_allowed` độc lập.
6. **Key Release không tính vào Rate Limit Quota**:
   - `KeyUp` và `MouseUp` không gọi `RecordAction()`, đảm bảo giải phóng phím không bao giờ bị nghẽn quota.
7. **Xác thực Cửa Sổ Hai Cấp (Two-Factor Window Validation)**:
   - Kiểm tra kết hợp Win32 ClassName (`POEWindowClass` / `POEC2_MainWindow`) và Process Image Name (`PathOfExile.exe`...). Không bao giờ chỉ kiểm tra chuỗi tiêu đề.

## 4. Bằng Chứng Thực Nghiệm
- Đạt 100% kết quả PASS trên cả 2 tầng:
  * C++23: `TestFocusInterlockHardwareSafety` trong `AutoPOE2_Tests.exe` (1,112/1,112 checks PASS).
  * Python 3.11: `tests/test_focus_interlock.py` (17/17 tests PASS) & `test_autonomous_mapping_coordinator.py` + `test_common.py` (54/54 tests PASS).
- Thực nghiệm hiện trường: 0 ký tự rò rỉ, 0 pixel dịch chuyển chuột trên màn hình người dùng trong suốt quá trình chạy toàn bộ test suites.