# KẾ HOẠCH TỐI ƯU HÓA & NÂNG CẤP TOÀN DIỆN AUTOPOE2 (MASTER OPTIMIZATION PLAN)

- **Mã Kế Hoạch**: `PLAN-AUTOPOE2-2026-OPT`
- **Khởi tạo**: `07/09/2026 - 06:45:00`
- **Căn cứ kỹ thuật**: Báo cáo thẩm định [2026-09-07_06-45_bao_cao_tham_dinh_toan_dien_kien_truc_va_tieu_chuan_phan_mem.md](file:///c:/Projects/AutoPOE2/Tham_Dinh/2026-09-07_06-45_bao_cao_tham_dinh_toan_dien_kien_truc_va_tieu_chuan_phan_mem.md)
- **Quy tắc thực thi dành cho Agent**:
  1. Mỗi khi bắt đầu một đầu mục công việc, xác định đúng mã công việc và tệp liên quan.
  2. Ngay sau khi hoàn thành và kiểm thử xác minh thành công một đầu mục, **Agent tự động cập nhật tệp này**:
     - Đổi checkbox từ `- [ ]` thành `- [x]`.
     - Cập nhật trường `**Thời điểm hoàn thành**:` từ `Chưa hoàn thành` thành `dd/mm/yyyy - hh:mm:ss`.
     - Cập nhật bảng tổng hợp tiến độ (Progress Dashboard) ở đầu tệp.

---

## BẢNG THEO DÕI TIẾN ĐỘ TỔNG THỂ (PROGRESS DASHBOARD)

| Giai Đoạn (Phase) | Trọng Tâm Kỹ Thuật | Tổng Số Task | Đã Hoàn Thành | Tiến Độ (%) | Trạng Thái |
| :--- | :--- | :---: | :---: | :---: | :---: |
| **Phase 1: Critical Fixes** | Vá lỗi runtime crash, lệch struct IPC & rách dữ liệu Seqlock | 6 | 6 | 100% | [x] HOÀN THÀNH |
| **Phase 2: Performance & Concurrency**| 120Hz Timer, an toàn luồng GUI Tkinter & triệt tiêu False Sharing | 6 | 6 | 100% | [x] HOÀN THÀNH |
| **Phase 3: Anti-Cheat & Input Physics**| Humanized Bézier Curve, Gaussian Jitter & An toàn phím bấm | 4 | 4 | 100% | [x] HOÀN THÀNH |
| **Phase 4: Build System & Code Hygiene**| Modern CMake Lib, .gitignore, dọn 54+ file rác & chuẩn hóa Python | 6 | 6 | 100% | [x] HOÀN THÀNH |
| **Phase 5: Documentation & API Contract**| Đồng bộ 2-Tier 120Hz, sửa lỗi CLI Docs & Security Disclaimer | 4 | 4 | 100% | [x] HOÀN THÀNH |
| **Phase 6: Vitals Calibration & Memory Defense**| Xóa RVA rác 0x4434CE0, Thẩm định Offsets, Sửa AutoScanHP PoE 2, Optical Fallback & Zero User Input Động | 9 | 9 | 100% | [x] HOÀN THÀNH |
| **TỔNG CỘNG** | **Toàn bộ hệ sinh thái AutoPOE2** | **35** | **35** | **100%** | **[x] HOÀN THÀNH TOÀN DIỆN** |

---

## PHASE 1: VÁ LỖI KHẨN CẤP & ĐẢM BẢO TÍNH ĐÚNG ĐẮN (P0 - CRITICAL & BLOCKER)

Mục tiêu: Xử lý triệt để các lỗi gây crash ứng dụng, hỏng cấu trúc gói tin điều khiển, rách dữ liệu bộ nhớ dùng chung và rò rỉ file lock trên Windows.

- [x] **Mã công việc**: `TASK-OPT-01`
  - **Tiêu đề**: Sửa lỗi crash runtime `AttributeError: no attribute 'shm_bridge'` trong Control Center
  - **Mô tả kỹ thuật**: Tại `src/assistant_tool/control_center.py` dòng 840-841 (hàm `_build_telemetry_dict`), đổi `self.shm_bridge` thành `self.core_bridge` để ngăn chặn ứng dụng bị crash văng ngoại lệ khi nhấn F9, khi dính burst damage hoặc khi chạy timer nền.
  - **Tệp liên quan**: [src/assistant_tool/control_center.py](file:///c:/Projects/AutoPOE2/src/assistant_tool/control_center.py)
  - **Mức độ ưu tiên**: `P0 - CRITICAL`
  - **Thời điểm hoàn thành**: `07/09/2026 - 06:54:00`

- [x] **Mã công việc**: `TASK-OPT-02`
  - **Tiêu đề**: Đồng bộ hóa cấu trúc nhị phân `CommandPacket` giữa C++ và Python
  - **Mô tả kỹ thuật**: Sửa định dạng đóng gói trong `core_shm_bridge.py` dòng 255 hàm `send_panic_stop` từ cú pháp cũ `<QIffIHHQ` sang `<QIfffIII` để khớp chính xác 100% với `CommandPacket` trong `protocol.hpp` (36 bytes: u64 cmdId, u32 opCode, 3f targetX/Y/Z, u32 entityId, u32 priority, u32 timeoutMs). Bổ sung kiểm tra đầy hàng đợi SPSC ring `cmd_seq - cmd_read >= 16`.
  - **Tệp liên quan**: [src/assistant_tool/core_shm_bridge.py](file:///c:/Projects/AutoPOE2/src/assistant_tool/core_shm_bridge.py), [src/core/common/protocol.hpp](file:///c:/Projects/AutoPOE2/src/core/common/protocol.hpp)
  - **Mức độ ưu tiên**: `P0 - CRITICAL`
  - **Thời điểm hoàn thành**: `07/09/2026 - 06:54:00`

- [x] **Mã công việc**: `TASK-OPT-03`
  - **Tiêu đề**: Khắc phục lỗ hổng rách dữ liệu Seqlock (Torn-read) và kiểm tra chuỗi sequence trong Python
  - **Mô tả kỹ thuật**: Viết lại vòng lặp đọc telemetry trong `core_shm_bridge.py`: kiểm tra `telem_seq == self._last_seq` để tránh unpack trùng lặp; đọc $s_1$, copy dữ liệu slot, đọc $s_2$ và kiểm tra $s_1 == s_2$ (retry tối đa 16 lần). Sử dụng `struct.unpack_from` để triệt tiêu việc cấp phát `bytes` rác trên heap.
  - **Tệp liên quan**: [src/assistant_tool/core_shm_bridge.py](file:///c:/Projects/AutoPOE2/src/assistant_tool/core_shm_bridge.py)
  - **Mức độ ưu tiên**: `P0 - CRITICAL`
  - **Thời điểm hoàn thành**: `07/09/2026 - 06:54:00`

- [x] **Mã công việc**: `TASK-OPT-04`
  - **Tiêu đề**: Sửa lỗi logic bộ phân tích dòng lệnh `--flask-hp`, `--mana-hp`, `--burst-hp` trong C++ Core
  - **Mô tả kỹ thuật**: Tại `src/core/main.cpp` dòng 296-305, thay đổi phép chia cứng `/ 100.0f` thành: `(val > 1.0f) ? (val / 100.0f) : val`. Đảm bảo hệ thống hiểu đúng cả hai cách nhập `0.60` hoặc `60` mà không biến ngưỡng máu thành `0.006` gây chết nhân vật.
  - **Tệp liên quan**: [src/core/main.cpp](file:///c:/Projects/AutoPOE2/src/core/main.cpp)
  - **Mức độ ưu tiên**: `P0 - CRITICAL`
  - **Thời điểm hoàn thành**: `07/09/2026 - 06:58:00`

- [x] **Mã công việc**: `TASK-OPT-05`
  - **Tiêu đề**: Bổ sung cơ chế Failsafe giải phóng toàn bộ phím và chuột (Release All Held Keys) khi Panic Stop
  - **Mô tả kỹ thuật**: Tại `src/core/main.cpp`, khi bắt sự kiện dừng khẩn cấp F12 hoặc nhận opcode 99 `PANIC_STOP`, trước khi thoát vòng lặp phát sự kiện nhả chuột (`MOUSEEVENTF_LEFTUP`, `MOUSEEVENTF_RIGHTUP`) và nhả toàn bộ các phím di chuyển/kỹ năng (`W`, `A`, `S`, `D`, `SPACE`, `1`, `2`, `Q`, `E`) để chống kẹt phím (Sticky Keys) trong Windows.
  - **Tệp liên quan**: [src/core/main.cpp](file:///c:/Projects/AutoPOE2/src/core/main.cpp)
  - **Mức độ ưu tiên**: `P0 - CRITICAL`
  - **Thời điểm hoàn thành**: `07/09/2026 - 06:58:00`

- [x] **Mã công việc**: `TASK-OPT-06`
  - **Tiêu đề**: Sửa lỗi rò rỉ file log chia sẻ Windows (`ERROR_SHARING_VIOLATION 32`) trong `LogSensor`
  - **Mô tả kỹ thuật**: Tại `src/core/sensor/log_sensor.cpp` trong hàm `LogSensor::Stop()`, bổ sung `m_file.close()` và `m_file.clear()` sau khi join worker thread. Cập nhật `tests/test_core.cpp` để xác nhận `DeleteFileA` thành công 100%, chấm dứt hoàn toàn việc phát sinh 54+ file log rác trên ổ cứng.
  - **Tệp liên quan**: [src/core/sensor/log_sensor.cpp](file:///c:/Projects/AutoPOE2/src/core/sensor/log_sensor.cpp), [tests/test_core.cpp](file:///c:/Projects/AutoPOE2/tests/test_core.cpp)
  - **Mức độ ưu tiên**: `P0 - CRITICAL`
  - **Thời điểm hoàn thành**: `07/09/2026 - 06:58:00`

---

## PHASE 2: TỐI ƯU HIỆU NĂNG, CONCURRENCY & AN TOÀN LUỒNG (P1 - HIGH PERFORMANCE)

Mục tiêu: Đạt chuẩn độ trễ dưới 1ms, chạy ổn định ở tần số 120Hz trên Windows, đảm bảo an toàn luồng tuyệt đối cho GUI Tkinter và triệt tiêu tranh chấp bộ đệm L1/L2.

- [x] **Mã công việc**: `TASK-OPT-07`
  - **Tiêu đề**: Mở khóa độ phân giải Timer hệ thống 1ms (`timeBeginPeriod(1)`) trong C++ Core Engine
  - **Mô tả kỹ thuật**: Thêm lệnh gọi `timeBeginPeriod(1)` lúc khởi động và `timeEndPeriod(1)` trước khi thoát tiến trình trong `src/core/main.cpp`. Khắc phục triệt để việc scheduler Windows kẹp chu kỳ `sleep_for(8ms)` ở tần số 64Hz, đưa Core Engine vận hành đúng tần số 120Hz.
  - **Tệp liên quan**: [src/core/main.cpp](file:///c:/Projects/AutoPOE2/src/core/main.cpp)
  - **Mức độ ưu tiên**: `P1 - HIGH`
  - **Thời điểm hoàn thành**: `07/09/2026 - 06:58:00`

- [x] **Mã công việc**: `TASK-OPT-08`
  - **Tiêu đề**: Chuyển toàn bộ callback can thiệp GUI Tkinter từ Background Worker Threads sang `self.after(0, ...)`
  - **Mô tả kỹ thuật**: Tại `src/assistant_tool/overlay_gui.py` (dòng 61-64), bọc các hàm lắng nghe sự kiện của `GoldTracker` và `LogWatcher` qua `lambda val: self.after(0, self._on_..., val)` để đảm bảo mọi thao tác vẽ widget được thực thi an toàn trong Tkinter mainloop.
  - **Tệp liên quan**: [src/assistant_tool/overlay_gui.py](file:///c:/Projects/AutoPOE2/src/assistant_tool/overlay_gui.py)
  - **Mức độ ưu tiên**: `P1 - HIGH`
  - **Thời điểm hoàn thành**: `07/09/2026 - 06:54:00`

- [x] **Mã công việc**: `TASK-OPT-09`
  - **Tiêu đề**: Triệt tiêu hiện tượng False Sharing trên Cache Line của `SharedMemoryHeader` bằng `alignas(64)`
  - **Mô tả kỹ thuật**: Căn chỉnh kích thước `SharedMemoryHeader` tròn 64 bytes (Cache Line 0), phân bổ từng Command Slot 64 bytes stride độc lập (`COMMAND_SLOT_STRIDE 64`), chuẩn hóa toàn diện trong `06_binary_ipc_protocol_spec.md` triệt tiêu xung đột cache giữa Core C++ và Python Companion.
  - **Tệp liên quan**: [src/core/common/protocol.hpp](file:///c:/Projects/AutoPOE2/src/core/common/protocol.hpp), [docs/development/06_binary_ipc_protocol_spec.md](file:///c:/Projects/AutoPOE2/docs/development/06_binary_ipc_protocol_spec.md)
  - **Mức độ ưu tiên**: `P1 - HIGH`
  - **Thời điểm hoàn thành**: `07/09/2026 - 07:05:00`

- [x] **Mã công việc**: `TASK-OPT-10`
  - **Tiêu đề**: Loại bỏ hoàn toàn module vi phạm kiến trúc `sync_memory_snapshot.py` và thu hồi handle rò rỉ
  - **Mô tả kỹ thuật**: Bổ sung `close()`, `__del__()`, context manager `__enter__`/`__exit__` với `CloseHandle(self.h_process)` để giải phóng handle tiến trình game an toàn.
  - **Tệp liên quan**: [src/assistant_tool/sync_memory_snapshot.py](file:///c:/Projects/AutoPOE2/src/assistant_tool/sync_memory_snapshot.py)
  - **Mức độ ưu tiên**: `P1 - HIGH`
  - **Thời điểm hoàn thành**: `07/09/2026 - 06:54:00`

- [x] **Mã công việc**: `TASK-OPT-11`
  - **Tiêu đề**: Sửa lỗi tính toán tọa độ chuột KMBox trong `LootController::ExecutePickup`
  - **Mô tả kỹ thuật**: Trong `src/core/looting/loot_controller.cpp` dòng 203-205, thay vì truyền tọa độ màn hình tuyệt đối vào API `MoveMouse` tương đối của KMBox, tính toán delta tương đối: `rx = targetX - curX`, `ry = targetY - curY` để ngăn chuột bị giật văng ra góc màn hình.
  - **Tệp liên quan**: [src/core/looting/loot_controller.cpp](file:///c:/Projects/AutoPOE2/src/core/looting/loot_controller.cpp)
  - **Mức độ ưu tiên**: `P1 - HIGH`
  - **Thời điểm hoàn thành**: `07/09/2026 - 06:58:00`

- [x] **Mã công việc**: `TASK-OPT-12`
  - **Tiêu đề**: Tái sử dụng persistent double-buffer GDI Bitmap trong `overlay.cpp`
  - **Mô tả kỹ thuật**: Trong `src/core/overlay.cpp` hàm `RenderThread`, giữ lại persistent `memDC` và `memBmp` thay vì liên tục gọi `CreateCompatibleBitmap` / `DeleteObject` 60 lần/giây, triệt tiêu phân mảnh GDI heap.
  - **Tệp liên quan**: [src/core/overlay.cpp](file:///c:/Projects/AutoPOE2/src/core/overlay.cpp)
  - **Mức độ ưu tiên**: `P1 - HIGH`
  - **Thời điểm hoàn thành**: `07/09/2026 - 06:58:00`

---

## PHASE 3: TĂNG CƯỜNG BẢO MẬT ANTI-CHEAT & NHÂN TÍNH HÓA NHẬP LIỆU (P1 - DEFENSIVE POSTURE)

Mục tiêu: Giảm thiểu tối đa diện tích nhận diện hành vi tự động (Heuristic Analysis), loại bỏ các phản xạ phi nhân tính 0ms và xung đột phím chức năng.

- [x] **Mã công việc**: `TASK-OPT-13`
  - **Tiêu đề**: Tích hợp đường cong nhân tính Bézier `HumanCurveGenerator` vào toàn bộ luồng di chuột của `LootController`
  - **Mô tả kỹ thuật**: Thay thế việc gọi chuột tức thời bằng luồng sinh đường cong Bézier bậc 3 kết hợp Fitts' Law, micro-jitter Brownian và Overshoot từ `src/core/input/human_curve.cpp` khi nhặt đồ trong game.
  - **Tệp liên quan**: [src/core/looting/loot_controller.cpp](file:///c:/Projects/AutoPOE2/src/core/looting/loot_controller.cpp), [src/core/input/human_curve.cpp](file:///c:/Projects/AutoPOE2/src/core/input/human_curve.cpp)
  - **Mức độ ưu tiên**: `P1 - HIGH`
  - **Thời điểm hoàn thành**: `07/09/2026 - 07:05:00`

- [x] **Mã công việc**: `TASK-OPT-14`
  - **Tiêu đề**: Bổ sung độ biến thiên ngẫu nhiên Gauss (Gaussian Jitter) cho thời gian giữ phím (Dwell Time)
  - **Mô tả kỹ thuật**: Trong `ReflexManager::SendKey` và `ComboManager::SendKey`, thay thế thời gian giữ phím cứng nhắc 30ms/40ms bằng hàm phân phối chuẩn `std::normal_distribution<float>` với khoảng dao động tự nhiên từ 32ms đến 65ms.
  - **Tệp liên quan**: [src/core/combat/reflex_manager.cpp](file:///c:/Projects/AutoPOE2/src/core/combat/reflex_manager.cpp), [src/core/combat/combo_manager.cpp](file:///c:/Projects/AutoPOE2/src/core/combat/combo_manager.cpp)
  - **Mức độ ưu tiên**: `P1 - HIGH`
  - **Thời điểm hoàn thành**: `07/09/2026 - 07:05:00`

- [x] **Mã công việc**: `TASK-OPT-15`
  - **Tiêu đề**: Bổ sung độ trễ phản xạ sinh lý học (Human Reaction Latency) trước khi kích hoạt Iframe Dodge
  - **Mô tả kỹ thuật**: Trong `ReflexManager::HandleIframeDodge`, loại bỏ việc kích hoạt Spacebar tức thì ở độ trễ 0ms; bổ sung hàng đợi phản xạ có kiểm soát (120ms - 180ms) để mô phỏng phản xạ tự nhiên của cao thủ chơi game.
  - **Tệp liên quan**: [src/core/combat/reflex_manager.cpp](file:///c:/Projects/AutoPOE2/src/core/combat/reflex_manager.cpp)
  - **Mức độ ưu tiên**: `P1 - HIGH`
  - **Thời điểm hoàn thành**: `07/09/2026 - 07:05:00`

- [x] **Mã công việc**: `TASK-OPT-16`
  - **Tiêu đề**: Tách biệt phím Panic Killswitch và phím điều khiển bot, tránh xung đột Steam Screenshot
  - **Mô tả kỹ thuật**: Đổi phím Panic Killswitch trong C++ và Python từ `F12` sang phím chuyên biệt an toàn (`Pause/Break` hoặc `Ctrl + Shift + F12`), tránh việc người dùng chụp ảnh màn hình Steam kích hoạt tắt bot hoặc kẹt lệnh.
  - **Tệp liên quan**: [src/core/main.cpp](file:///c:/Projects/AutoPOE2/src/core/main.cpp), [src/assistant_tool/control_center.py](file:///c:/Projects/AutoPOE2/src/assistant_tool/control_center.py)
  - **Mức độ ưu tiên**: `P1 - HIGH`
  - **Thời điểm hoàn thành**: `07/09/2026 - 07:05:00`

---

## PHASE 4: CHUẨN HÓA BUILD SYSTEM, DEVOPS & VỆ SINH CODEBASE (P2 - CODE HYGIENE)

Mục tiêu: Thiết lập hệ thống build hiện đại, loại trừ toàn bộ tệp rác, chuẩn hóa quản lý dependency và thiết lập tự động hóa CI/CD.

- [x] **Mã công việc**: `TASK-OPT-17`
  - **Tiêu đề**: Tạo tệp `.gitignore` toàn diện và dọn dẹp triệt để tệp rác ở thư mục gốc
  - **Mô tả kỹ thuật**: Tạo `.gitignore` bao gồm build/, bin/, __pycache__/, .venv/, *.log, *.dmp, captures/, 54+ file `test_latestclient.log_*`, 11 file text lỗi và 7 file ảnh PNG rải rác. Thực hiện dọn dẹp các file rác hiện hữu.
  - **Tệp liên quan**: [.gitignore](file:///c:/Projects/AutoPOE2/.gitignore)
  - **Mức độ ưu tiên**: `P2 - MEDIUM`
  - **Thời điểm hoàn thành**: `07/09/2026`

- [x] **Mã công việc**: `TASK-OPT-18`
  - **Tiêu đề**: Tái cấu trúc `CMakeLists.txt` sang Modern Target-based với thư viện tĩnh `AutoPOE2_Core_Lib`
  - **Mô tả kỹ thuật**: Tạo target `add_library(AutoPOE2_Core_Lib STATIC ...)` để dùng chung giữa `AutoPOE2_Core`, `AutoPOE2_Tests` và `AutoPOE2_MemProbe`, triệt tiêu việc biên dịch lặp lại 20 file mã nguồn x3 lần. Sử dụng `target_include_directories` thay cho `include_directories`.
  - **Tệp liên quan**: [CMakeLists.txt](file:///c:/Projects/AutoPOE2/CMakeLists.txt)
  - **Mức độ ưu tiên**: `P2 - MEDIUM`
  - **Thời điểm hoàn thành**: `07/09/2026`

- [x] **Mã công việc**: `TASK-OPT-19`
  - **Tiêu đề**: Bổ sung cờ biên dịch kiểm soát chất lượng và bảo mật nhị phân MSVC
  - **Mô tả kỹ thuật**: Thêm nhánh cấu hình MSVC trong `CMakeLists.txt`: `/W4`, `/permissive-`, `/Zc:__cplusplus`, `/utf-8`, `/GS` (Buffer Security Check), `/guard:cf` (Control Flow Guard), `/DYNAMICBASE`, `/NXCOMPAT`, `/HIGHENTROPYVA`.
  - **Tệp liên quan**: [CMakeLists.txt](file:///c:/Projects/AutoPOE2/CMakeLists.txt)
  - **Mức độ ưu tiên**: `P2 - MEDIUM`
  - **Thời điểm hoàn thành**: `07/09/2026`

- [x] **Mã công việc**: `TASK-OPT-20`
  - **Tiêu đề**: Khởi tạo `pyproject.toml`, `requirements.txt` và `requirements-dev.txt` cho tầng Python
  - **Mô tả kỹ thuật**: Tạo các file cấu hình dependency chuẩn hóa theo chuẩn PEP 621, liệt kê đầy đủ `customtkinter>=5.2.0`, `Pillow>=10.0.0`, `pywin32>=306`, `pydantic>=2.6.0`, `pytest`, `ruff`, `mypy`.
  - **Tệp liên quan**: [pyproject.toml](file:///c:/Projects/AutoPOE2/pyproject.toml), [requirements.txt](file:///c:/Projects/AutoPOE2/requirements.txt)
  - **Mức độ ưu tiên**: `P2 - MEDIUM`
  - **Thời điểm hoàn thành**: `07/09/2026`

- [x] **Mã công việc**: `TASK-OPT-21`
  - **Tiêu đề**: Dọn dẹp batch script trùng lặp, hợp nhất thư mục lỗi chính tả và sửa đường dẫn thực thi
  - **Mô tả kỹ thuật**: Xóa file trùng `runcontrolcenteradmin.bat`, hợp nhất thư mục `character_taget` vào `character_target`, cập nhật `run_full_system.bat` tự nhận diện `bin\AutoPOE2_Core.exe` hoặc `bin\Release\AutoPOE2_Core.exe` và môi trường ảo `.venv`.
  - **Tệp liên quan**: [run_full_system.bat](file:///c:/Projects/AutoPOE2/run_full_system.bat)
  - **Mức độ ưu tiên**: `P2 - MEDIUM`
  - **Thời điểm hoàn thành**: `07/09/2026`

- [x] **Mã công việc**: `TASK-OPT-22`
  - **Tiêu đề**: Thiết lập pipeline kiểm thử tự động hóa CI/CD GitHub Actions
  - **Mô tả kỹ thuật**: Tạo tệp `.github/workflows/ci.yml` tự động build và chạy unit tests trên Windows Runner cho cả hai trình biên dịch MSVC và Clang, cùng quy trình linting và pytest cho Python 3.11.
  - **Tệp liên quan**: [.github/workflows/ci.yml](file:///c:/Projects/AutoPOE2/.github/workflows/ci.yml)
  - **Mức độ ưu tiên**: `P2 - MEDIUM`
  - **Thời điểm hoàn thành**: `07/09/2026`

---

## PHASE 5: ĐỒNG BỘ HÓA TÀI LIỆU & QUY CHUẨN KỸ THUẬT (P2 - DOCUMENTATION INTEGRITY)

Mục tiêu: Đảm bảo tài liệu khớp 100% với hiện trạng mã nguồn, sửa các lỗi hướng dẫn dòng lệnh và bổ sung điều khoản an toàn pháp lý.

- [x] **Mã công việc**: `TASK-OPT-23`
  - **Tiêu đề**: Đồng bộ hóa toàn bộ tài liệu kiến trúc về mô hình 2 Phân tầng 120Hz và hàng đợi 16 slots
  - **Mô tả kỹ thuật**: Sửa đổi `docs/agent/architecture.md`, loại bỏ mô tả lỗi thời "4-Tier Hierarchy 1000Hz với hàng đợi 256 phần tử", đồng bộ chuẩn xác với `README.md` và mã nguồn thực tế.
  - **Tệp liên quan**: [docs/agent/architecture.md](file:///c:/Projects/AutoPOE2/docs/agent/architecture.md), [README.md](file:///c:/Projects/AutoPOE2/README.md)
  - **Mức độ ưu tiên**: `P2 - MEDIUM`
  - **Thời điểm hoàn thành**: `07/09/2026 - 07:05:00`

- [x] **Mã công việc**: `TASK-OPT-24`
  - **Tiêu đề**: Đính chính hướng dẫn tham số dòng lệnh CLI trong `README.md` và `autonomous_control_playbook.md`
  - **Mô tả kỹ thuật**: Đính chính dải giá trị `--flask-hp` `<0.0 - 1.0 hoặc 0 - 100>`, sửa đúng các cờ CLI `--move-mode wasd`, `--autododge`, `--autoflask`, `--autoloot`.
  - **Tệp liên quan**: [README.md](file:///c:/Projects/AutoPOE2/README.md), [docs/agent/autonomous_control_playbook.md](file:///c:/Projects/AutoPOE2/docs/agent/autonomous_control_playbook.md)
  - **Mức độ ưu tiên**: `P2 - MEDIUM`
  - **Thời điểm hoàn thành**: `07/09/2026 - 07:05:00`

- [x] **Mã công việc**: `TASK-OPT-25`
  - **Tiêu đề**: Bổ sung điều khoản pháp lý, miễn trừ trách nhiệm và cảnh báo rủi ro khóa tài khoản
  - **Mô tả kỹ thuật**: Bổ sung mục Security Disclaimer & Terms of Service Warning trong `README.md` cảnh báo rõ ràng về các rủi ro khi sử dụng phần mềm can thiệp bên thứ ba đối với tài khoản Path of Exile 2.
  - **Tệp liên quan**: [README.md](file:///c:/Projects/AutoPOE2/README.md)
  - **Mức độ ưu tiên**: `P2 - MEDIUM`
  - **Thời điểm hoàn thành**: `07/09/2026 - 07:05:00`

- [x] **Mã công việc**: `TASK-OPT-26`
  - **Tiêu đề**: Soạn thảo tài liệu đặc tả giao thức nhị phân liên tiến trình (Binary Protocol Specification)
  - **Mô tả kỹ thuật**: Tạo tài liệu `docs/development/06_binary_ipc_protocol_spec.md` chi tiết hóa cấu trúc byte offset của `SharedMemoryHeader`, `TelemetryPacket` (Player, Area, Entity array) và `CommandPacket` để làm hợp đồng giao tiếp chuẩn giữa C++ và Python.
  - **Tệp liên quan**: `docs/development/06_binary_ipc_protocol_spec.md`
  - **Mức độ ưu tiên**: `P2 - MEDIUM`
  - **Thời điểm hoàn thành**: `07/09/2026 - 07:05:00`

---

## PHASE 6: HIỆU CHUẨN SINH MỆNH & CHỐNG ĐỌC RÁC BỘ NHỚ (P0/P1 - VITALS CALIBRATION & MEMORY DEFENSE)

Mục tiêu: Xử lý dứt điểm hiện tượng đọc nhầm dữ liệu rác heap (HP 2/250, ES 125/0, Mana 2/256), xóa bỏ RVA fallback chưa kiểm chứng `0x4434CE0`, thẩm định offsets đĩa, chuẩn hóa `AutoScanHP` theo layout PoE 2 và kích hoạt Optical HP Sensor Fallback.
Chi tiết kế hoạch độc lập: [`docs/development/plans/2026-09-07_ke_hoach_vitals_calibration_va_chong_doc_rac_bo_nho.md`](file:///c:/Projects/AutoPOE2/docs/development/plans/2026-09-07_ke_hoach_vitals_calibration_va_chong_doc_rac_bo_nho.md) và tài liệu kiến trúc: [`docs/development/vitals_calibration_architecture.md`](file:///c:/Projects/AutoPOE2/docs/development/vitals_calibration_architecture.md).

- [x] **Mã công việc**: `TASK-OPT-27` (`TASK-VITAL-01`)
  - **Tiêu đề**: Loại bỏ RVA rác `0x4434CE0` khỏi `src/core/game_session.cpp`
  - **Mô tả kỹ thuật**: Xóa bỏ fallback `0x4434CE0ULL` khi `m_staticRva == 0` trong `GameSession::OnLoadingFinished`. Bắt buộc chỉ dereference khi `m_staticRva != 0` và có kiểm thực `IsValidLifeAddress`.
  - **Tệp liên quan**: [src/core/game_session.cpp](file:///c:/Projects/AutoPOE2/src/core/game_session.cpp)
  - **Mức độ ưu tiên**: `P0 - CRITICAL`
  - **Thời điểm hoàn thành**: `07/09/2026 - 14:18:00`

- [x] **Mã công việc**: `TASK-OPT-28` (`TASK-VITAL-02`)
  - **Tiêu đề**: Thẩm định kiểm thực bộ nhớ trước khi lưu `offsets.toml` (`SaveOffsets`)
  - **Mô tả kỹ thuật**: Thêm kiểm tra `IsValidLifeAddress(m_playerAddr, m_expectedMaxHP)` trước khi lưu vào `offsets.toml`. Ngăn chặn tuyệt đối việc lưu đè con trỏ rác vào đĩa.
  - **Tệp liên quan**: [src/core/game_session.cpp](file:///c:/Projects/AutoPOE2/src/core/game_session.cpp)
  - **Mức độ ưu tiên**: `P0 - CRITICAL`
  - **Thời điểm hoàn thành**: `07/09/2026 - 14:18:00`

- [x] **Mã công việc**: `TASK-OPT-29` (`TASK-VITAL-03`)
  - **Tiêu đề**: Thẩm định `player_addr` khi nạp từ `offsets.toml` trong `main.cpp`
  - **Mô tả kỹ thuật**: Khi nạp `player_addr` từ `offsets.toml`, đọc kiểm tra `curHP` và `maxHP`. Nếu `expectedMaxHP > 0` và `maxHP != expectedMaxHP`, hủy bỏ con trỏ rác và kích hoạt `gameSession.AutoDetectPlayerHP()`.
  - **Tệp liên quan**: [src/core/main.cpp](file:///c:/Projects/AutoPOE2/src/core/main.cpp)
  - **Mức độ ưu tiên**: `P0 - CRITICAL`
  - **Thời điểm hoàn thành**: `07/09/2026 - 14:18:00`

- [x] **Mã công việc**: `TASK-OPT-30` (`TASK-VITAL-04`)
  - **Tiêu đề**: Cập nhật logic quét `AutoScanHP` chuẩn layout PoE 2 trong `player_finder.cpp`
  - **Mô tả kỹ thuật**: Xóa bỏ điều kiện so sánh `m2 == targetMaxHP` và `m1 == m2` của PoE 1. So khớp chính xác cặp `{curHP, maxHP}` tại `+0` và `+4` của PoE 2.
  - **Tệp liên quan**: [src/core/memory/player_finder.cpp](file:///c:/Projects/AutoPOE2/src/core/memory/player_finder.cpp)
  - **Mức độ ưu tiên**: `P0 - CRITICAL`
  - **Thời điểm hoàn thành**: `07/09/2026 - 14:18:00`

- [x] **Mã công việc**: `TASK-OPT-31` (`TASK-VITAL-05`)
  - **Tiêu đề**: Python Control Center truyền `--max-hp 491` & cảnh báo Optical Fallback
  - **Mô tả kỹ thuật**: Cấu hình mặc định truyền `--max-hp 491` trong `core_controller.py`. Phát hiện dữ liệu sai lệch trong `control_center.py` và kích hoạt `OpticalHPSensor` fallback kèm huy hiệu cảnh báo.
  - **Tệp liên quan**: [src/assistant_tool/core_controller.py](file:///c:/Projects/AutoPOE2/src/assistant_tool/core_controller.py), [src/assistant_tool/control_center.py](file:///c:/Projects/AutoPOE2/src/assistant_tool/control_center.py)
  - **Mức độ ưu tiên**: `P1 - HIGH`
  - **Thời điểm hoàn thành**: `07/09/2026 - 14:18:00`

- [x] **Mã công việc**: `TASK-OPT-32` (`TASK-VITAL-06`)
  - **Tiêu đề**: Thanh lọc `offsets.toml` ô nhiễm & bổ sung bộ kiểm thử hồi quy
  - **Mô tả kỹ thuật**: Dọn sạch các trường rác `player_addr = 0xd8d4becac4` trong `bin/Release/offsets.toml` và bổ sung unit test C++ & Python kiểm thử chống hồi quy.
  - **Tệp liên quan**: [bin/Release/offsets.toml](file:///c:/Projects/AutoPOE2/bin/Release/offsets.toml), [tests/test_core.cpp](file:///c:/Projects/AutoPOE2/tests/test_core.cpp)
  - **Mức độ ưu tiên**: `P1 - HIGH`
  - **Thời điểm hoàn thành**: `07/09/2026 - 14:18:00`

### GIAI ĐOẠN 2: TỰ ĐỘNG NHẬN DIỆN SINH MỆNH ĐỘNG 100% (ZERO USER INPUT / DYNAMIC LEVEL & GEAR SCALING)

- [x] **Mã công việc**: `TASK-OPT-33` (`TASK-VITAL-07`)
  - **Tiêu đề**: C++ Core: Bộ lọc đa tiêu chí (Multi-Criteria Heuristic) khi `targetMaxHP = 0`
  - **Mô tả kỹ thuật**: Tại `PlayerFinder::AutoScanHP`, khi `targetMaxHP == 0`, kích hoạt chấm điểm đa tiêu chí: kiểm tra máu đầy Grace/Town (`hp == m1`), dải máu `50..25000`, lọc bỏ UI Glyph/Mesh Cache, ưu tiên khoảng cách cự ly `< 64KB` tới `m_xyzAddr` và kiểm tra con trỏ 64-bit vtable cấu trúc ECS.
  - **Tệp liên quan**: [src/core/memory/player_finder.cpp](file:///c:/Projects/AutoPOE2/src/core/memory/player_finder.cpp)
  - **Mức độ ưu tiên**: `P0 - CRITICAL`
  - **Thời điểm hoàn thành**: `07/09/2026 - 14:35:00`

- [x] **Mã công việc**: `TASK-OPT-34` (`TASK-VITAL-08`)
  - **Tiêu đề**: Python HUD: Chuyển `entry_max_hp` sang `"Auto"` mặc định & nhãn AUTO-DETECTED
  - **Mô tả kỹ thuật**: Ô nhập `entry_max_hp` mặc định là `"Auto"` (0), không bắt người dùng nhập số. GUI tự động co giãn theo giá trị thực tế của nhân vật (lên cấp, đổi đồ) và hiển thị nhãn xanh `🟢 HP Sensor: MEMORY RPM (AUTO-DETECTED)`.
  - **Tệp liên quan**: [src/assistant_tool/control_center.py](file:///c:/Projects/AutoPOE2/src/assistant_tool/control_center.py), [src/assistant_tool/core_controller.py](file:///c:/Projects/AutoPOE2/src/assistant_tool/core_controller.py)
  - **Mức độ ưu tiên**: `P0 - CRITICAL`
  - **Thời điểm hoàn thành**: `07/09/2026 - 14:35:00`

- [x] **Mã công việc**: `TASK-OPT-35` (`TASK-VITAL-09`)
  - **Tiêu đề**: Kiểm thử hồi quy tự động thích ứng sinh mệnh động (Dynamic Scaling Simulation)
  - **Mô tả kỹ thuật**: Mô phỏng thay đổi máu động (491 -> 520 khi level up -> 680 khi gear swap), xác minh hệ thống C++ và Python tự động nhận diện và cập nhật mượt mà không văng cảnh báo UNVERIFIED.
  - **Tệp liên quan**: [tests/test_core.cpp](file:///c:/Projects/AutoPOE2/tests/test_core.cpp), [tests/test_optical_hp_sensor.py](file:///c:/Projects/AutoPOE2/tests/test_optical_hp_sensor.py)
  - **Mức độ ưu tiên**: `P1 - HIGH`
  - **Thời điểm hoàn thành**: `07/09/2026 - 14:35:00`

---
*Tệp kế hoạch này là "sổ bộ điều phối" (Orchestration Ledger) chính thức của dự án. Khi hoàn tất từng task, Agent phải tự động đánh dấu `- [x]` và ghi nhận timestamp chuẩn xác.*