# 62. Kiến Trúc Tái Cấu Trúc Toàn Diện & Hạt Nhân Dùng Chung (Common Kernel Architecture Specification)

- **Mã tài liệu**: `DOC-62-COMMON-KERNEL-CONSOLIDATION`
- **Mốc thời gian tham chiếu**: 16/09/2026
- **Trạng thái**: [ACTIVE / PRODUCTION-READY]
- **Tuân thủ quy chuẩn**: Doc 50 (Two-Tier Architecture), Rule 8 (Anti-Symptom Patching), Rule 9 & 14 (Empirical DoD), Rule 16 (Common Kernel SSoT), Rule 18 (Keybinds SSoT).

---

## 1. Bối Cảnh & Động Lực Kiến Trúc (Architecture Motivation)

Qua nhiều giai đoạn mở rộng tính năng liên tục (Doc 29 -> Doc 61), một số tệp nguồn trung tâm đã trở thành các khối nguyên khối (monolithic files) dài hàng nghìn dòng:
- `src/assistant_tool/control_center.py` (~2,800 dòng): Trộn lẫn toàn bộ giao diện Tkinter, xử lý logic telemetry, cài đặt người dùng, OCR và các tab tính năng.
- `tools/autonomous_mapping_coordinator.py` (~1,300 dòng): Trộn lẫn quy trình điều phối mapping với các lệnh gọi cấp thấp Win32 API (`ctypes.windll.user32`) và OCR (`winocr`).
- `src/core/main.cpp` (~1,550 dòng): Chứa hàng trăm dòng mã đọc file INI cấu hình game, định nghĩa struct cài đặt và vòng lặp phân tích tham số dòng lệnh (CLI parsing).
- Sự lặp lại các hàm tiện ích chuột, bàn phím và OCR rải rác giữa các module, vi phạm nguyên tắc SSoT (Single Source of Truth).

Đợt tái cấu trúc này tái thiết lập kiến trúc **Common Kernel (Hạt Nhân Dùng Chung)**, chuẩn hóa các lớp tiện ích dùng chung và phân rã các tệp nguyên khối thành các module độc lập, chuyên biệt nhưng bảo toàn 100% hợp đồng API và tính tương thích ngược với toàn bộ hệ thống kiểm thử.

---

## 2. Kiến Trúc Hạt Nhân Dùng Chung Python (Python Common Kernel)

Tập trung toàn bộ các thao tác Win32 và thị giác máy tính vào `src/common/`:

```mermaid
graph TD
    subgraph "src/common/ (Common Kernel)"
        W32I["win32_input.py<br/>Mouse, Keyboard, Bézier, WASD Dwell"]
        VOCR["vision_ocr.py<br/>OCR Engine, Atlas UI, Map Device Screen"]
        W32W["win32_window.py<br/>Focus Interlock, Bounds, Coordinates"]
        W32P["win32_process.py<br/>PID, Architecture, Process Enumeration"]
        SCAP["screen_capture.py<br/>Fast BGRA Screen Grabber"]
    end

    subgraph "Consumers (Tầng Ứng Dụng & Điều Phối)"
        AMC["autonomous_mapping_coordinator.py"]
        CC["control_center.py & UI Tabs"]
        OG["overlay_gui.py"]
        WSC["waystone_auto_crafter.py"]
    end

    AMC --> W32I
    AMC --> VOCR
    CC --> W32I
    CC --> VOCR
    WSC --> W32I
    OG --> W32I
```

### 2.1. `src/common/win32_input.py` (Win32 Input SSoT)
- **Chuẩn hóa thao tác chuột**: `click(x, y)`, `ctrl_click(x, y)`, `hover(x, y)`, `mouse_wheel(steps, x, y)`.
- **An toàn Focus Interlock**: Tích hợp kiểm tra `ensure_window_active` trước khi gửi phím/chuột.
- **Tuân thủ Bất biến SSoT**:
  - `INV-INPUT-ABS-MOUSE`: Sử dụng tọa độ chuột tuyệt đối.
  - `INV-WASD-MIN-DWELL`: Hàm `send_wasd_direction(dx, dy, duration_sec)` bảo đảm dwell time tối thiểu $\ge 300\text{ms}$, cấm micro-tap $< 150\text{ms}$.
  - `INV-KEY-NO-F-FOR-INTERACT`: Tương tác thực thể bằng click chuột trái, cấm gửi phím `F` (phím `F` là Skill 8).

### 2.2. `src/common/vision_ocr.py` (Vision & OCR SSoT)
- **Nhận diện giao diện Atlas**: `is_atlas_ui_open(screenshot)` kiểm tra từ khóa `"ATLAS"`, `"WAYSTONE"`, `"TRAVERSE"`.
- **Nhận diện hành trang**: `is_inventory_open(screenshot)`.
- **Nhận diện nút bấm**: `find_button_by_text(screenshot, text_list)`.
- **Nhận diện Map Device & Node**:
  - `find_map_device_screen_pos(screenshot)`: Nhận diện cụm màu cam/vàng của Map Device.
  - `find_reachable_green_node(screenshot)`: Nhận diện node xanh khả dụng trên cây Atlas.

---

## 3. Phân Rã Giao Diện Điều Khiển (Control Center GUI Modularization)

Tệp `src/assistant_tool/control_center.py` được tinh gọn từ **2,814 dòng xuống còn 1,751 dòng** (giảm hơn 1,060 dòng mã UI nguyên khối). Toàn bộ phần dựng giao diện được chuyển sang package `src/assistant_tool/ui/`:

| Module Mới | Nhiệm Vụ Cụ Thể | Thành Phần Xuất Bản |
|---|---|---|
| `ui/header.py` | Thanh điều khiển trên cùng | `create_header(app, parent)`: Nút Bật/Tắt Bot [F8], Chụp [F9], Định vị [F11], Brain [F10], Panic Stop |
| `ui/hud_strip.py` | Thanh HUD siêu mỏng 44px hiển thị telemetry realtime | `create_hud_strip(app, parent)`: `lbl_hp`, `bar_hp`, `lbl_area`, `lbl_xyz`, `lbl_char_state`, `lbl_mana`, `lbl_vitals_es_ward` |
| `ui/telemetry_panel.py` | Cột bên phải hiển thị trạng thái và logs | `build_right_telemetry_and_logs(app, parent)`: `tactical_card`, `mod_filter_card`, `lbl_movement_plan`, `log_textbox` |
| `ui/settings_manager.py` | Quản lý nạp/lưu cấu hình, vitals & state | `load_user_settings()`, `save_user_settings()`, `get_expected_max_hp_from_str()`, `is_valid_vitals()`, `parse_character_state()` |
| `ui/tabs/tab_quest.py` | Tab Nhiệm Vụ (Campaign, World Map U, Patrol) | `build_tab_quest(app, scroll)`: `chk_quest`, `cmb_quest_act`, `cmb_quest_zone`, `btn_trigger_quest_travel` |
| `ui/tabs/tab_combat.py` | Tab Chiến Đấu (Iframe Dodge, Flasks, Kiting, Finisher) | `build_tab_combat(app, scroll)`: `chk_dodge`, `sld_burst`, `chk_flask`, `sld_flask_hp`, `entry_max_hp` |
| `ui/tabs/tab_client.py` | Tab Client (WASD/Mouse mode, Standalone launcher) | `build_tab_client(app, scroll, detected_mode, cfg_path)`: `rb_move_wasd`, `rb_move_mouse`, `chk_auto_detect_move` |
| `ui/tabs/tab_intel.py` | Tab Tác Vụ (Auto-Loot, Item Triage, WhatIsBetter, A3E Brain) | `build_tab_intel(app, scroll)`: `chk_loot`, `sld_loot_radius`, `lbl_triage_status`, `btn_test_appraisal`, `btn_test_triage` |

> [!IMPORTANT]
> **Nguyên tắc Bảo Toàn Hợp Đồng Kiểm Thử**:
> Mọi hàm trong `ui/` đều nhận tham chiếu `app` và gán trực tiếp widget vào thuộc tính của instance `app` (ví dụ `app.mod_filter_card = ...`, `app.chk_dodge = ...`). Nhờ đó, 100% các bài test trong `tests/test_control_center.py` truy xuất trực tiếp các thuộc tính trên instance `app` đều hoạt động nguyên vẹn mà không cần thay đổi bất kỳ dòng test nào.

---

## 4. Tinh Gọn & Mô-đun Hóa C++ Core Engine

### 4.1. Trích xuất Cấu hình CLI (`src/core/common/cli_options.hpp`)
- Toàn bộ logic đọc cấu hình game `poe2_production_Config.ini` (`GetPoe2ConfigPath`, `Poe2GameSettings`, `ReadPoe2GameSettings`, `DetectMovementModeFromGameConfig`) được đóng gói độc lập trong namespace `poe2::cli`.
- Cấu trúc `CoreCliOptions` và hàm phân tích dòng lệnh `ParseCommandLineArgs(int argc, char* argv[])` tập trung xử lý toàn bộ các cờ CLI (`--move`, `--wasd`, `--mouse`, `--autoflask`, `--autoloot`, `--autododge`, `--boss-rush`, `--ci`, v.v.).
- Giúp `src/core/main.cpp` giảm từ **1,546 dòng xuống còn 1,188 dòng** (giảm gần 400 dòng mã cấu hình phân tán), hàm `main()` trở nên trong sáng, chỉ tập trung vào khởi tạo IPC, phần cứng KMBox và vòng lặp Hot Path 120Hz.

### 4.2. Khắc phục Triệt để Rò rỉ Tài nguyên Tạm (Root-Cause Fix)
- **Vấn đề phát hiện**: Khi chạy kiểm thử bộ nhớ `AutoPOE2_Tests.exe`, 89 tệp rác `live_label_registry_*.toml` bị bỏ lại ở thư mục gốc do hàm `TestRegistryLiveLabel()` trong `tests/test_memory_engine.cpp` tạo file tạm nhưng không xóa sau khi kết thúc.
- **Biện pháp xử lý tận gốc**: Bổ sung lệnh xóa `std::remove(tomlPath.c_str())` ngay khi kiểm tra hoàn tất, triệt tiêu 100% rò rỉ file rác.
- **Sửa lỗi thụt lề `OverlayHUD.__init__`**: Đưa các đăng ký luồng an toàn (`gold_tracker.register_listener`, `log_watcher.register_listener`) về đúng phạm vi `__init__`, đưa toàn bộ 15/15 test `test_assistant_tool.py` về trạng thái PASS 100%.

---

## 5. Bằng Chứng Nghiệm Thu Thực Nghiệm (Empirical DoD Matrix)

Theo quy định nghiêm ngặt của Rule 9 và Rule 14, toàn bộ hệ thống đã được kiểm chứng bằng việc chạy trực tiếp trên môi trường thực tế:

| Bộ Kiểm Thử | Lệnh Thực Thi | Kết Quả Thực Tế | Tỷ Lệ Đạt |
|---|---|---|---|
| **Python Common Kernel** | `pytest tests/test_common.py -v` | 11/11 tests PASSED | **100%** |
| **Autonomous Coordinator** | `pytest tests/test_autonomous_mapping_coordinator.py -v` | 32/32 tests PASSED | **100%** |
| **Control Center GUI** | `pytest tests/test_control_center.py -v` | 9/9 tests PASSED | **100%** |
| **Assistant Tool & Overlay** | `pytest tests/test_assistant_tool.py -v` | 15/15 tests PASSED | **100%** |
| **Toàn Bộ Python Test Suite** | `pytest -q` | **265/265 tests PASSED** (136.12s) | **100%** |
| **Toàn Bộ C++ Core Test Suite** | `build\bin\Release\AutoPOE2_Tests.exe` | **903/903 checks PASSED** (42.5s) | **100%** |
| **Tổng Cộng Toàn Workspace** | **2 Test Runners** | **1,168 / 1,168 checks PASSED** | **100% PASS** |

### Trích xuất kết quả CLI thực tế:
```
pytest -q
........................................................................ [ 27%]
........................................................................ [ 54%]
........................................................................ [ 81%]
.................................................                        [100%]
265 passed in 136.12s (0:02:16)

build\bin\Release\AutoPOE2_Tests.exe
=================================================
[RESULT] TẤT CẢ 903 KIỂM TRA ĐỀU ĐẠT (PASS)
```

---

## 6. Kết Luận & Khuyến Nghị Tiếp Theo

Codebase AutoPOE2 hiện đã đạt độ tinh gọn cao, loại bỏ hoàn toàn các khối mã nguyên khối cồng kềnh, phân định ranh giới rõ ràng giữa Common Kernel (chuột, phím, OCR), GUI Presentation (Modular UI Components) và Core Engine (C++23 Hot Path). Mọi thay đổi đều được kiểm thử tự động khóa chặt chống hồi quy.