# Kiến Trúc Live Sanity Probe & Quy Chuẩn Nghiệm Thu Thực Nghiệm (Empirical DoD)

## 1. Bối Cảnh Kỹ Thuật & Cạm Bẫy "Mockist Trap" (The Problem Statement)

Trong quá trình phát triển hệ thống tự động hóa can thiệp mức thấp **AutoPOE2** (C++23 Core Engine + Python Companion HUD), việc phụ thuộc vào bộ kiểm thử giả lập (Pytest Mocks) đã bộc lộ những khiếm khuyết nghiêm trọng:
1. **Ảo giác kiểm thử xanh (False Positive Illusion)**: Hàng chục unit test sử dụng `MagicMock()`, mock Win32 API (`win32gui`, `win32ui`, `BitBlt`) và chuỗi text nhân tạo (`mock_text="Life: 495/503"`) luôn báo PASS 100%. Tuy nhiên, chúng hoàn toàn mù tịt trước các biến số vật lý in-game (DirectX 12/Vulkan rendering, GPU hardware acceleration gây màn hình đen, font chữ khử răng cưa nhòe nét, Windows DPI Scaling 125%/150%, IPC race condition giữa C++ 120Hz và Python polling).
2. **Lãng phí thời gian vận hành (Operational Friction)**: Mỗi lần sửa code, việc chờ đợi chạy bộ test mock tốn từ 15 đến 30 giây nhưng không mang lại bất kỳ bằng chứng nào về việc tính năng có chạy được trên client thật hay không.
3. **Thất bại thực nghiệm**: Code "test pass" nhưng khi người dùng mở game thật thì bot đứng yên, đọc sai HP, hoặc crash.

---

## 2. Mô Hình Phân Tầng Kiểm Thử Mới (The New 3-Tier Testing Pyramid)

Để triệt tiêu sửa lỗi triệu chứng và bảo đảm tính xác thực thực tế, AutoPOE2 tái cấu trúc toàn bộ quy trình kiểm thử thành 3 tầng ranh giới rõ ràng:

```mermaid
graph TD
    A["Tầng 1: Live Sanity Probe (Empirical Gate)<br/>scripts/live_probe.py (&lt; 1.5s)"] -->|Kiểm tra trực tiếp| B["Client Game POE2 &amp; C++ Core Đang Chạy"]
    C["Tầng 2: Data-Driven Replay (Rule 14)<br/>captures/*.png &amp; captures/*_RAM.json"] -->|Thẩm tra ngoại tuyến| D["Thuật toán Nhận thức OCR / Memory Scanner"]
    E["Tầng 3: Pure Math &amp; Algorithm Unit Tests<br/>pytest -m fast (&lt; 0.5s)"] -->|Kiểm tra logic thuần túy| F["Isometric Projection WorldToScreen / A* Math"]
```

1. **Tầng 1: Live Sanity Probe (`scripts/live_probe.py`)** — **BẮT BUỘC cho mọi tính năng Runtime**:
   - Chạy trực tiếp trên môi trường sống trong **< 1.5 giây**.
   - Kiểm tra 5 trụ cột vật lý: Cửa sổ game/DPI/Black Screen, RPM RAM thật, Shared Memory IPC sang C++ Core, Tệp nhật ký `Client.txt` thật, và Replay ngoại tuyến.
2. **Tầng 2: Data-Driven Replay (Rule 14)**:
   - Khi client game không bật, kiểm chứng bắt buộc phải nạp các file artifact thật trong `captures/` (ảnh PNG 1440p/1080p thật, file JSON dump RAM thật từ PID thật).
   - Tuyệt đối cấm tạo mock data tự chế.
3. **Tầng 3: Pure Math / Algorithm Unit Tests (`pytest -m fast`)**:
   - Chỉ duy trì cho các bài toán hình học và giải thuật thuần CPU: công thức chiếu `WorldToScreen(dx, dy)`, thuật toán tìm đường $A^*$, làm mượt chuột Bézier, toán học bitmask của SPSC queue. Thời gian chạy < 0.5s.

---

## 3. Đặc Tả Công Cụ Live Sanity Probe (`scripts/live_probe.py`)

### 3.1. Cấu Trúc Kiểm Tra 5 Trụ Cột

| Cờ CLI | Trụ Cột Kiểm Tra | Cơ Chế Thực Thi | Tiêu Chuẩn Đạt (PASS) |
| :--- | :--- | :--- | :--- |
| `--window` | **Cửa Sổ & Đồ Họa** | `ScreenCapturer.find_poe2_window()`, `GetDpiForWindow`, `PrintWindow`/`BitBlt` 16x16 pixel check | HWND hợp lệ, Rect $\ge 800\times 600$, Pixel không bị đen xì toàn bộ (No Black Screen). |
| `--vitals` | **Bộ Nhớ Trực Tiếp (RPM)** | `SyncMemorySnapshotManager.capture_ram_snapshot()` trực tiếp từ PID game thật | $0 < \text{CurHP} \le \text{MaxHP}$, $\text{MaxHP} \le 50000$, bài trừ tuyệt đối mã rác $778/778$ và $779/779$. |
| `--shm` | **Shared Memory IPC** | Mở `Local\POE2_Auto_SharedMem_v1`, đọc header 64 byte | Magic `0x504F45324155544F`, Protocol Version khớp, Heartbeat Age $< 3000\text{ms}$. |
| `--log` | **Nhật Ký Client.txt** | `Config.find_poe2_client_log()`, `LogWatcher.seed_latest_playable_zone()` | Tệp tồn tại, cập nhật gần đây, nhận diện đúng Tên Vùng Đất (Zone) hợp lệ. |
| `--replay` | **Kiểm Chứng Ngoại Tuyến** | Nạp file `*_RAM.json` mới nhất từ `captures/`, chạy `InvariantSentinel` | Toàn bộ các bất biến kiến trúc (Vitals, Bounds, Overflow) đều PASS trên dữ liệu thật. |
| `--all` | **Toàn Diện Tổng Thể** | Chạy toàn bộ 5 bước trên tuần tự | Thời gian thực thi toàn bộ $< 1500\text{ms}$. |

### 3.2. Đo Lường Hiệu Năng Thực Tế (Benchmark 13/09/2026)
* Thời gian Window Probe: ~166ms
* Thời gian Memory Probe: ~15ms
* Thời gian SHM IPC Probe: ~0.2ms
* Thời gian Log Probe: ~210ms
* Thời gian Replay Probe: ~28ms
* **Tổng thời gian thực thi: ~420ms - 450ms** (Nhanh gấp 50 lần so với việc chạy full pytest suite).

---

## 4. Quy Chuẩn Nghiệm Thu Thực Nghiệm (Empirical Definition of Done - DoD)

Một nhiệm vụ kỹ thuật trong AutoPOE2 chỉ được phép đánh dấu `[COMPLETED]` khi thỏa mãn các điều kiện sau:

1. **Điều kiện Cần**:
   - Code biên dịch thành công (C++ build pass, Python không có SyntaxError/Linter Error).
   - Unit test giải thuật thuần toán (`pytest -m fast`) chạy PASS trong $< 1.0$ giây.
2. **Điều kiện Đủ (Bắt buộc phải có bằng chứng thực nghiệm)**:
   - Nếu Client Game đang chạy: Trích xuất trực tiếp stdout từ `python scripts/live_probe.py --all` chứng minh trạng thái thực địa đạt yêu cầu.
   - Nếu Client Game không chạy: Trích xuất stdout từ `python scripts/live_probe.py --replay` chứng minh thuật toán xử lý thành công trên capture artifacts thật từ `captures/`.
   - **Tuyệt đối cấm trích dẫn kết quả pytest mock để tuyên bố hoàn thành tính năng**.