# 51. ĐẶC TẢ KIẾN TRÚC HIỆN ĐẠI HÓA & TỐI ƯU MẬT ĐỘ GIAO DIỆN PYTHON 2026 (MODERN COMPACT UI REDESIGN SPECIFICATION)

- **Mã Tài Liệu**: `DOC-51-MODERN-COMPACT-UI-REDESIGN-2026`
- **Mốc Thời Gian Tham Chiếu**: `15/09/2026`
- **Chuyên Trách**: Dedicated Documentation & Architecture Specialist (AutoPOE2 Core & Companion)
- **Phạm Vi Can Thiệp**:
  - `src/assistant_tool/ui_theme.py` (Mở rộng Design Tokens & Helper widgets)
  - `src/assistant_tool/config.py` (`Config.THEME` & Spacing Metrics)
  - `src/assistant_tool/control_center.py` (Control Center GUI 980x680)
  - `src/assistant_tool/overlay_gui.py` (Overlay HUD 510x700)
- **Hợp Đồng Kế Thừa**: Bảo toàn 100% widget attributes, hotkeys (`<F8>`, `<F6>`, `<Pause>`, `<F10>`, `<F9>`, `<F11>`), IPC Shared Memory, và test compatibility với `tests/test_control_center.py`, `tests/test_gui_init.py`, `tests/test_assistant_tool.py`.
- **Trạng Thái**: `CANONICAL SPECIFICATION & PRE-IMPLEMENTATION BLUEPRINT (SSoT)`

---

## 1. TỔNG QUAN & BỐI CẢNH THƯƠNG MẠI 2026 (EXECUTIVE SUMMARY)

### 1.1. Thực Trạng & Món Nợ Kỹ Thuật Giao Diện (UI Technical Debt)
Sau các giai đoạn phát triển vũ bão tích hợp tầng Hot Path C++23 (120Hz), phản xạ sinh tồn (Iframe, Smart Flasks, Emergency Logout), cơ chế giải mã bộ nhớ RPM và các tính năng Agentic A3E, giao diện đồ họa Python Companion (`ControlCenterApp` và `OverlayHUD`) đã xuất hiện hiện tượng **phình to văn bản & lãng phí diện tích hiển thị (Information Bloat & Viewport Waste)**:
1. **Nhãn checkbox dài như bài luận (Essay-length labels)**: Các checkbox mang theo cả dòng mô tả dài ngoặc đơn như `"Iframe Dodge Roll (Lăn né 300ms bất tử khi dính sốc sát thương)"`, `"Smart Flask Sipping (2 bình Máu & Mana POE2 - Chống spam khi HoT)"`, chiếm trọn chiều ngang nhưng giảm tốc độ quét mắt của người dùng.
2. **Lặp lại nhãn thanh trượt (Redundant Sub-Labels)**: Mỗi slider đều kèm theo một nhãn `CTkLabel` riêng biệt chiếm thêm 1 hàng bên trên (`"  ↳ Ngưỡng sốc máu kích hoạt né: 22% maxHP"`), nhân đôi số dòng hiển thị của từng cài đặt.
3. **Khung lồng khung dày đặc (Nested Border Clutter)**: Việc lồng ghép quá nhiều lớp `CTkFrame` có viền bo góc (`auto_card`, `phase_frame`, `move_frame`, `badge_frame`, `quest_card`, `target_frame`, `scenario_frame`) tạo ra những khoảng đệm (padding) vô ích từ 16px đến 24px, đẩy các điều khiển quan trọng trôi khỏi khung nhìn (scroll cutoff).
4. **Hỗn loạn luồng dựng tab (Chaotic Builder Flow)**: Trong `control_center.py`, mã nguồn chuyển đổi luân phiên giữa các tab không theo trình tự (`scroll = quest_scroll` $\rightarrow$ `client_scroll` $\rightarrow$ `combat_scroll` $\rightarrow$ `quest_scroll` $\rightarrow$ `combat_scroll` $\rightarrow$ `client_scroll` $\rightarrow$ `intel_scroll` $\rightarrow$ `client_scroll`), gây khó khăn cho việc bảo trì và tối ưu layout.
5. **HUD Strip cồng kềnh (72px Height)**: Dải trạng thái Vitals trên đỉnh cửa sổ Control Center chiếm tới 72px với 3 hàng riêng lẻ và thanh progress bar quá khổ, làm thu hẹp không gian của khu vực điều khiển bên dưới.
6. **Overlay HUD bị che khuất bởi nhãn tĩnh**: Panel tự động hóa của Overlay HUD (`_create_automation_panel`) hiển thị 4 dòng chữ tĩnh dài ngoằng (`reflex_label`, `loot_label`, `combo_label`, `quest_label`), tiêu tốn hơn 100px chiều cao dọc vốn là "đất vàng" để hiển thị các thẻ giao dịch (Trading Cards & Arbitrage opportunities).

### 1.2. Định Chuẩn Thiết Kế Theo Các Tool Game Thương Mại 2026
Một công cụ chơi game thương mại chuẩn mực (như **Awakened PoE Trade**, **Path of Building**, **Exilence CE**, **Overwolf Gaming Apps**) tuân thủ nghiêm ngặt 3 nguyên lý vàng:
- **Mật độ thông tin cao (High Information Density)**: Tối đa hóa lượng dữ liệu có ích trên mỗi inch vuông màn hình; mỗi dòng điều khiển chỉ cao từ 22px đến 26px.
- **Giá trị tức thời tại chỗ (Inline Metric Displays)**: Slider không dùng nhãn phụ ở dòng riêng; giá trị thay đổi được ghim trực tiếp ở đuôi thanh trượt hoặc dưới dạng mini badge `[ 22% ]` cùng hàng.
- **Dải trạng thái động (Dynamic Ticker / Single-Line Strip)**: Thay thế văn bản giải thích cố định bằng luồng trạng thái động (live status stream) kết hợp các micro-chips đổi màu theo trạng thái thực tế.

```
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                   SO SÁNH MẬT ĐỘ KHÔNG GIAN: CŨ vs MỚI (2026 STANDARD)                  │
├────────────────────────────────────────────────────────────────────────────────────────┤
│ HIỆN TRẠNG (CŨ - 72px HUD + Essay Labels + 100px Overlay Bloat)                        │
│ ┌────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ HP: 495 / 503                                                  [HP Sensor: RPM]    │ │
│ │ [======================================== ProgressBar ===========================] │ │
│ │ ES: 0/0  Ward: 0/0      💧 Mana: 344 / 344 (100%)       Spirit: 0/0                │ │
│ │ [======================================== ProgressBar ===========================] │ │
│ │ Khu vực: Vastiri Outskirts     XYZ: (1240, 890, 15)     [ĐỨNG YÊN]     Radar: ...  │ │
│ └────────────────────────────────────────────────────────────────────────────────────┘ │
│ [Checkbox] Iframe Dodge Roll (Lăn né 300ms bất tử khi dính sốc sát thương)             │
│   ↳ Ngưỡng sốc máu kích hoạt né: 22% maxHP                                             │
│ [======================================== Slider ==================================] │
├────────────────────────────────────────────────────────────────────────────────────────┤
│ THIẾT KẾ MỚI (2026 COMPACT - 44px HUD + Inline Micro-Widgets + Dynamic Ticker)          │
│ ┌────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ [❤️ 495/503 [==]] [🛡️ 0/0] [💧 344/344 [==]] [✨ 0/100]  | 📍 Vastiri L7 | 🟢 IDLE  │ │
│ │ XYZ: 1240, 890, 15 | Radar: 7 Quái · 4 Đồ · 1 Cổng | Sensor: RPM [Verified]        │ │
│ └────────────────────────────────────────────────────────────────────────────────────┘ │
│ [✓] Iframe Dodge [Space] ────────── [========= Slider =========] ─── [ 22% ]           │
└────────────────────────────────────────────────────────────────────────────────────────┘
```

---

## 2. NGUYÊN TẮC TỐI ƯU HÓA MẬT ĐỘ & DIỆN TÍCH (UI DENSITY PRINCIPLES)

### 2.1. Triệt Tiêu Nhãn Dài Như Bài Luận (Elimination of Essay-Length Labels)
Chuyển đổi toàn bộ các chuỗi nhãn văn xuôi thành tiêu đề xúc tích kèm phím tắt hoặc thông số chính trong ngoặc vuông:

| Mã Điều Khiển | Nhãn Cũ (Verbose Essay) | Nhãn Mới Chuẩn 2026 (Compact) | Ghi Chú Tương Thích |
| :--- | :--- | :--- | :--- |
| `chk_dodge` | `Iframe Dodge Roll (Lăn né 300ms bất tử khi dính sốc sát thương)` | `Iframe Dodge Roll [Space]` | Giữ `self.chk_dodge` |
| `chk_flask` | `Smart Flask Sipping (2 bình Máu & Mana POE2 - Chống spam khi HoT)` | `Smart Flasks [1, 2] (HP/MP)` | Giữ `self.chk_flask` |
| `chk_kiting` | `Dynamic Kiting né quái theo tọa độ XYZ (Thả diều quái khi áp sát < 35)` | `Dynamic XYZ Kiting (< 35m)` | Giữ `self.chk_kiting` |
| `chk_chicken` | `Emergency Logout an toàn khi HP <= 18% (Bảo toàn 10% kinh nghiệm)` | `Emergency Logout (HP <= 18%)` | Giữ `self.chk_chicken` |
| `chk_loot` | `Auto Ultra-Fast Loot <5ms (Vàng, Waystones, Uncut Gems, Runes, Orbs)` | `Auto-Loot (Currency & Rare)` | Giữ `self.chk_loot` |
| `chk_combo` | `Combat Combo: Đánh xa [Chuột phải] ⟷ Quái áp sát né [E] \| Finisher [R]` | `Combat Combo [RMB / E / R]` | Giữ `self.chk_combo` |
| `chk_stagger` | `Heavy Stagger Finisher (Tự xả đòn kết liễu khi Poise quái >= 80%)` | `Stagger Finisher (Poise >= 80%)` | Giữ `self.chk_stagger` |
| `chk_quest` | `Tự động làm nhiệm vụ Campaign (Auto-Questing)` | `Auto-Quest Campaign` | Giữ `self.chk_quest` |
| `chk_patrol` | `  ↳ 🧭 Tự Động Dò Map & Tuần Tra (Auto-Patrol Explorer)` | `Auto-Patrol Explorer (A*)` | Giữ `self.chk_patrol` |
| `chk_dynamic_quest` | `  ↳ 🎯 Nhận Diện Làng & Mở World Map 'U' Dịch Chuyển (Town State Machine)` | `Town Portal & World Map 'U'` | Giữ `self.chk_dynamic_quest` |
| `chk_auto_portal` | `Tự động mở Portal (T) về Hideout sau khi diệt Boss (Chờ 2.5s loot)` | `Auto-Portal (T) sau diệt Boss` | Giữ `self.chk_auto_portal` |
| `chk_cap_burst` | `Tự động chụp màn hình khi bị sốc sát thương nặng (Burst Damage)` | `Auto-Capture khi sốc HP` | Giữ `self.chk_cap_burst` |
| `chk_cap_periodic` | `Tự động chụp màn hình định kỳ mỗi 30 giây để thu thập dữ liệu huấn luyện` | `Auto-Capture định kỳ (30s)` | Giữ `self.chk_cap_periodic` |
| `chk_auto_launch` | `Tự động mở PathOfExile.exe Standalone khi bắt đầu bot` | `Tự mở Client Standalone` | Giữ `self.chk_auto_launch` |
| `chk_autologin` | `Tự động kết nối & đăng nhập lại khi rớt mạng (Auto Reconnect)` | `Auto Reconnect khi rớt mạng` | Giữ `self.chk_autologin` |
| `chk_agentic_brain`| `Kích hoạt Agentic Brain (Contextual Bandit & Reflection Critic)` | `A3E Agentic Brain (Bandit & Critic)` | Giữ `self.chk_agentic_brain` |

### 2.2. Hợp Nhất Hàng Điều Khiển: Slider + Giá Trị Inline (Single-Row Inline Control)
- **Vấn đề cũ**:
  ```python
  # Cũ: 2 widget nằm ở 2 hàng tách biệt, tốn ~44px
  self.lbl_burst = ctk.CTkLabel(scroll, text="  ↳ Ngưỡng sốc máu kích hoạt né: 22% maxHP", ...)
  self.lbl_burst.pack(anchor="w", padx=16)
  self.sld_burst = ctk.CTkSlider(scroll, from_=10, to=50, ...)
  self.sld_burst.pack(fill="x", padx=20, pady=(0, 6))
  ```
- **Giải pháp chuẩn 2026**:
  Đặt Checkbox, Slider và Nhãn giá trị trên cùng một Container gọn gàng hoặc lồng ghép nhãn giá trị ngay sát slider, giảm chiều cao tiêu tốn xuống còn **22px**:
  ```python
  # Mới: Container 1 hàng duy nhất (Height = 24px)
  row_burst = ctk.CTkFrame(parent, fg_color="transparent", height=24)
  row_burst.pack(fill="x", padx=6, pady=1)

  # Checkbox chiếm 45% bên trái
  self.chk_dodge.pack(side="left", padx=(4, 8))

  # Value Badge hiển thị giá trị nằm ở góc phải
  self.lbl_burst = ctk.CTkLabel(
      row_burst,
      text="22%",
      font=theme.f(10, "bold"),
      text_color=theme.c("info_cyan"),
      fg_color=theme.c("inset"),
      corner_radius=4,
      width=42,
      height=20
  )
  self.lbl_burst.pack(side="right", padx=(6, 4))

  # Slider co giãn nằm ở giữa
  self.sld_burst = ctk.CTkSlider(row_burst, from_=10, to=50, height=14, ...)
  self.sld_burst.pack(side="right", fill="x", expand=True)
  ```
- **Khả năng tương thích kiểm thử (Test Invariant)**:
  `tests/test_control_center.py` kiểm tra `assert "28%" in app.lbl_burst.cget("text")`. Trong callback `_on_burst_slider_change(val)`, việc cập nhật `self.lbl_burst.configure(text=f"{int(val)}%")` hoàn toàn thỏa mãn assertion `28% in ...` mà không cần đoạn text dài dòng `Ngưỡng sốc máu kích hoạt né:`.

### 2.3. Dải Trạng Thái Vitals Rút Gọn (HUD Strip 72px $\rightarrow$ 44px)
Dải HUD Strip trên đỉnh Control Center được tái thiết kế theo cấu trúc **Dual Micro-Row Grid** siêu mỏng với tổng chiều cao cố định **44px**:

```
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ HÀNG 1 (H = 20px): VITALS BARS & NUMERICS                                               │
│ [❤️ HP: 495/503 (98%)] [MiniBar 4px] │ [🛡️ ES: 0/0] │ [💧 Mana: 344/344] [MiniBar 4px] │ [✨ Sp: 0/100] │ [⚡ RPM: OK]
├─────────────────────────────────────────────────────────────────────────────────────────┤
│ HÀNG 2 (H = 20px): NAVIGATION, STATE & TELEMETRY RADAR                                  │
│ 📍 Vastiri Outskirts (L7) │ XYZ: (1240.2, 890.1, 15.0) │ 🟢 [RUNNING] │ 🎯 Radar: 7 Quái │ 4 Đồ │ 1 Cổng
└─────────────────────────────────────────────────────────────────────────────────────────┘
```

- **Tối ưu hóa không gian**:
  - Tiết kiệm ngay lập tức **28px** chiều cao (giảm 38.8% diện tích HUD strip).
  - Thanh máu (`bar_hp`) và thanh mana (`bar_mana`) giảm chiều cao từ 7px/5px xuống 4px, đặt nội dòng (inline) cạnh chỉ số số học tương ứng.
  - Nhãn `lbl_hp`, `lbl_vitals_es_ward`, `lbl_mana`, `lbl_spirit`, `lbl_area`, `lbl_xyz`, `lbl_char_state`, `lbl_radar` được giữ nguyên vẹn 100% để đảm bảo không gãy bất kỳ câu lệnh đọc dữ liệu nào của test suite.

### 2.4. Tinh Giản Overlay HUD: Dynamic 1-Line Ticker (+100px Viewport)
- **Hiện trạng lãng phí trong `overlay_gui.py`**:
  `_create_automation_panel` chiếm ~120px chiều cao bằng 4 khung nhãn tĩnh màu mè:
  - `self.reflex_label` (`>> [REFLEX] Iframe Dodge [Space]...`)
  - `self.loot_label` (`>> [AUTO-LOOT] Vàng & Currency...`)
  - `self.combo_label` (`>> [COMBAT COMBO] Quái gần [E]...`)
  - `self.quest_label` (`>> [AUTO-QUEST] Sẵn sàng khám phá...`)
  Những nhãn này không đổi nội dung trong suốt phiên chơi, che mất 1/5 chiều cao màn hình Overlay (510x700).
- **Thiết kế mới (Dynamic Ticker 24px)**:
  1. Thay 4 nhãn tĩnh bằng **1 container duy nhất cao 24px**:
     - Cụm **Mini Status Chips**: `[DODGE]` `[FLASK]` `[LOOT]` `[COMBO]` `[QUEST]`. Mỗi chip đổi màu sáng xanh (`#10b981`) khi tính năng đang bật, mờ xám (`#334155`) khi tính năng tắt.
     - Dòng chữ **Dynamic Status Ticker**: Hiển thị hành động thời gian thực từ C++ Core SHM hoặc Autonomous Lifecycle (ví dụ: `🟢 [FARMING] Diệt Rare Pack (Poise 85%) · Loot Waystone T2`).
  2. **Giải phóng không gian**:
     - Thu hồi được **96px đến 100px** chiều cao dọc.
     - Khung danh sách lướt sóng thị trường (`self.arbitrage_frame`) và danh sách Discord Trade Offers được mở rộng chiều cao, hiển thị thêm từ 2 đến 3 thẻ giao dịch (Trading Cards) mà không cần cuộn chuột.
  3. **Hợp đồng tương thích (Compatibility Contract)**:
     - Giữ nguyên thuộc tính `self.reflex_label`, `self.loot_label`, `self.combo_label`, `self.quest_label` dưới dạng các nhãn ẩn (hoặc property alias trỏ vào ticker) để ngăn ngừa hoàn toàn lỗi `AttributeError` nếu có module kiểm thử hoặc phụ thuộc ngoài truy cập.

---

## 3. KIẾN TRÚC THÀNH PHẦN & SSOT DESIGN TOKENS

### 3.1. Bảng Token Thiết Kế Mở Rộng (`ui_theme.py` & `Config.THEME`)
Hệ thống token được đồng bộ hóa tuyệt đối với bảng màu Hot Path C++ Core HUD (`PoE2_Overlay_Theme`):

```python
# Mở rộng trong src/assistant_tool/config.py -> Config.THEME
Config.THEME.update({
    # Mật độ & Nền bổ sung
    "bg_subtle": "#0e131d",
    "card_bg_compact": "#111827",
    "border_subtle": "#1e293b",
    "border_focus": "#38bdf8",
    "badge_bg": "#1e293b",
    "badge_fg": "#94a3b8",
    "ticker_bg": "#0b1017",
    "ticker_border": "#1f2937",
    
    # Mini Chips trạng thái
    "chip_active_bg": "#064e3b",
    "chip_active_fg": "#34d399",
    "chip_inactive_bg": "#1e293b",
    "chip_inactive_fg": "#64748b",
})
```

```python
# Mở rộng trong src/assistant_tool/ui_theme.py
from typing import Tuple
import customtkinter as ctk

# Metrics & Density Tokens
PAD_NONE = 0
PAD_TINY = 2
PAD_SM = 4
PAD_MD = 6
PAD_LG = 8

HEIGHT_HEADER = 44       # Giảm từ 48px xuống 44px
HEIGHT_HUD_STRIP = 44     # Giảm từ 72px xuống 44px
HEIGHT_COMPACT_ROW = 24  # Hàng điều khiển tiêu chuẩn
HEIGHT_MICRO_BAR = 4     # Thanh tiến trình mỏng

# Typography Tokens
def font_xs(weight: str = "normal") -> ctk.CTkFont:
    return ctk.CTkFont(family="Segoe UI", size=9, weight=weight)

def font_sm(weight: str = "normal") -> ctk.CTkFont:
    return ctk.CTkFont(family="Segoe UI", size=10, weight=weight)

def font_base(weight: str = "normal") -> ctk.CTkFont:
    return ctk.CTkFont(family="Segoe UI", size=11, weight=weight)

def font_title(weight: str = "bold") -> ctk.CTkFont:
    return ctk.CTkFont(family="Segoe UI", size=13, weight=weight)

def font_mono(size: int = 10) -> ctk.CTkFont:
    return ctk.CTkFont(family="Consolas", size=size)
```

### 3.2. Tiện Ích Giao Diện Dùng Chung (Reusable UI Factory Functions)
Để xóa bỏ mã HTML/Tkinter boilerplate trùng lặp, `ui_theme.py` bổ sung 3 hàm tiện ích chuẩn:

1. `create_badge(parent, text, color_key, ...)`: Tạo nhãn trạng thái bo góc nhỏ gọn với padding chuẩn.
2. `create_compact_slider_row(parent, label_text, from_val, to_val, default_val, unit, on_change)`: Tạo hàng điều khiển đồng nhất gồm Tiêu đề, Slider và Badge giá trị tự động cập nhật.
3. `create_status_chip(parent, text, initial_active)`: Tạo chip hiển thị trạng thái On/Off dạng micro cho thanh Ticker.

---

## 4. CẤU TRÚC TAB & MA TRẬN ÁNH XẠ ĐIỀU KHIỂN (CONTROL MAPPING MATRIX)

### 4.1. Phân Rã Luồng Dựng Tab Hợp Lý (Modular Tab Builders)
Triệt tiêu triệt để việc nhảy cóc biến `scroll = quest_scroll` $\rightarrow$ `client_scroll` $\rightarrow$ `combat_scroll` trong hàm `_build_left_features`. Bóc tách thành 4 phương thức chuyên trách:

```mermaid
graph TD
    A[_build_left_features] --> B[_build_tab_quest: Nhiệm vụ]
    A --> C[_build_tab_combat: Chiến đấu]
    A --> D[_build_tab_client: Client & Di Chuyển]
    A --> E[_build_tab_intel: Trí Tuệ & Thẩm Định]
    
    B --> B1[1-Click Master Lifecycle]
    B --> B2[Campaign World Map 'U' Runner]
    B --> B3[Atlas Endgame Scenarios]
    
    C --> C1[Reflex: Iframe Dodge & Sliders]
    C --> C2[Smart Flasks & Expected HP]
    C --> C3[Dynamic Kiting & Logout]
    C --> C4[Auto-Loot & Combat Combo]
    C --> C5[Auto-Capture Burst/Periodic]
    
    D --> D1[Chế độ Di chuyển WASD / Chuột]
    D --> D2[Standalone Launcher & Auto-Login]
    D --> D3[Poe2VisualTool Launcher]
    
    E --> E1[A3E Agentic Coordinator]
    E --> E2[Item Triage & What Is Better]
    E --> E3[Hover Item Inspector]
```

### 4.2. Ma Trận Ánh Xạ & Bảo Tồn Thuộc Tính (Contract Preservation Matrix)

Mọi thay đổi giao diện **bắt buộc phải duy trì 100% tên biến, kiểu dữ liệu và callback** theo bảng quy chuẩn dưới đây:

| Tên Thuộc Tính (Property) | Kiểu Widget | Vị Trí Tab | Callback / Event Binding | Kiểm Thử Trực Tiếp (Test File) |
| :--- | :--- | :--- | :--- | :--- |
| `btn_toggle_bot` | `CTkButton` | Header | `_on_toggle_bot_clicked`, `<F8>`, `<F6>` | `test_control_center.py:86` |
| `btn_capture_now` | `CTkButton` | Header | `_on_manual_capture_clicked`, `<F9>` | `test_control_center.py:87` |
| `btn_recalibrate` | `CTkButton` | Header | `_on_recalibrate_clicked`, `<F11>` | `test_control_center.py:88` |
| `btn_tactical_brain` | `CTkButton` | Header | `_on_tactical_brain_clicked`, `<F10>` | `test_control_center.py` |
| `btn_panic` | `CTkButton` | Header | `_on_panic_clicked`, `<Pause>` | `test_control_center.py:89` |
| `lbl_hp` | `CTkLabel` | HUD Strip | `_on_auto_detect_vitals_clicked` | `test_control_center.py:140` |
| `lbl_vitals_es_ward` | `CTkLabel` | HUD Strip | N/A | `test_control_center.py` |
| `lbl_mana` | `CTkLabel` | HUD Strip | N/A | `test_control_center.py:141` |
| `lbl_spirit` | `CTkLabel` | HUD Strip | N/A | `test_control_center.py` |
| `lbl_area` | `CTkLabel` | HUD Strip | N/A | `test_control_center.py` |
| `lbl_xyz` | `CTkLabel` | HUD Strip | N/A | `test_control_center.py` |
| `lbl_char_state` | `CTkLabel` | HUD Strip | N/A | `test_control_center.py` |
| `lbl_radar` | `CTkLabel` | HUD Strip | N/A | `test_control_center.py:138` |
| `chk_dodge` | `CTkCheckBox` | Chiến đấu | Checkbox Toggle | `test_control_center.py:92` |
| `sld_burst` | `CTkSlider` | Chiến đấu | `_on_burst_slider_change` | `test_control_center.py:108` |
| `lbl_burst` | `CTkLabel` | Chiến đấu | Text hiển thị `%` | `test_control_center.py:110` |
| `chk_flask` | `CTkCheckBox` | Chiến đấu | Checkbox Toggle | `test_control_center.py:93` |
| `sld_flask_hp` | `CTkSlider` | Chiến đấu | `_on_flask_slider_change` | `test_control_center.py:112` |
| `lbl_flask_hp` | `CTkLabel` | Chiến đấu | Text hiển thị `%` | `test_control_center.py:114` |
| `sld_flask_mana` | `CTkSlider` | Chiến đấu | `_on_flask_mana_slider_change` | `test_control_center.py` |
| `lbl_flask_mana` | `CTkLabel` | Chiến đấu | Text hiển thị `%` | `test_control_center.py` |
| `entry_max_hp` | `CTkEntry` | Chiến đấu | `_on_expected_hp_changed` | `test_optical_hp_sensor.py` |
| `btn_auto_detect_vitals` | `CTkButton` | Chiến đấu | `_on_auto_detect_vitals_clicked` | `test_optical_hp_sensor.py` |
| `chk_kiting` | `CTkCheckBox` | Chiến đấu | Checkbox Toggle | `test_control_center.py` |
| `chk_chicken` | `CTkCheckBox` | Chiến đấu | Checkbox Toggle | `test_control_center.py` |
| `chk_loot` | `CTkCheckBox` | Chiến đấu | Checkbox Toggle | `test_control_center.py:94` |
| `sld_loot_radius` | `CTkSlider` | Chiến đấu | `_on_loot_radius_change` | `test_control_center.py` |
| `lbl_loot_radius` | `CTkLabel` | Chiến đấu | Text hiển thị radius | `test_control_center.py` |
| `chk_combo` | `CTkCheckBox` | Chiến đấu | Checkbox Toggle | `test_control_center.py:95` |
| `chk_stagger` | `CTkCheckBox` | Chiến đấu | Checkbox Toggle | `test_control_center.py` |
| `chk_quest` | `CTkCheckBox` | Nhiệm vụ | Checkbox Toggle | `test_control_center.py:96` |
| `cmb_quest_act` | `CTkComboBox` | Nhiệm vụ | `_on_quest_act_changed` | `test_control_center.py:99` |
| `cmb_quest_zone` | `CTkComboBox` | Nhiệm vụ | Dropdown Selection | `test_control_center.py:102` |
| `var_quest_zone` | `StringVar` | Nhiệm vụ | Trạng thái vùng chọn | `test_control_center.py:105` |
| `chk_auto_detect_move`| `CTkCheckBox` | Client | `_on_auto_detect_toggle` | `test_control_center.py:77` |
| `rb_move_wasd` | `CTkRadioButton` | Client | `var_move_mode` = "wasd" | `test_control_center.py:76` |
| `rb_move_mouse` | `CTkRadioButton` | Client | `var_move_mode` = "mouse" | `test_control_center.py:75` |
| `lbl_move_badge` | `CTkLabel` | Client | Badge hiển thị chế độ | `test_control_center.py:78` |
| `log_textbox` | `CTkTextbox` | Cột phải | `_append_log` | `test_control_center.py:119` |
| `btn_test_appraisal` | `CTkButton` | Tác vụ | `_on_test_item_appraisal_clicked`| `test_control_center.py:151` |
| `btn_test_triage` | `CTkButton` | Tác vụ | `_on_test_item_triage_clicked` | `test_control_center.py:152` |
| `lbl_triage_status` | `CTkLabel` | Tác vụ | Cập nhật số lượng đồ phôi | `test_control_center.py:153` |
| `lbl_item_eval` | `CTkLabel` | Tác vụ | Cập nhật kết quả thẩm định | `test_control_center.py:154` |

---

## 5. ĐẶC TẢ CHI TIẾT TỪNG MODULE (MODULE REFACTORING SPECS)

### 5.1. Module `ui_theme.py` & `config.py`
1. Khai báo các hằng số kích thước chuẩn trong `ui_theme.py`:
   - Chiều cao Control Center mặc định: 980x680 (giữ nguyên kích thước tổng thể, tái cấu trúc mật độ bên trong).
   - `ROW_HEIGHT_COMPACT = 24`.
   - `PAD_CONTAINER = 6`.
2. Mở rộng `REQUIRED_THEME_KEYS` để bao gồm các token mới (`badge_bg`, `badge_fg`, `ticker_bg`, `ticker_border`, `chip_active_bg`, `chip_active_fg`, `chip_inactive_bg`, `chip_inactive_fg`).

### 5.2. Module `control_center.py`
1. **Header Refactoring**:
   - Thu nhỏ chiều cao từ 48px xuống 44px.
   - Nút `btn_toggle_bot`: `width=150`, `height=28`, font size 11 bold.
   - Các nút phụ (`btn_capture_now`, `btn_recalibrate`, `btn_tactical_brain`, `btn_panic`): chiều cao đồng nhất 28px, padding gọn 2px.
2. **HUD Strip Refactoring**:
   - `height=44` (cố định bằng `pack_propagate(False)`).
   - Chia thành 2 hàng ngang (Top Row: Vitals & Micro-Bars; Bottom Row: Area & Radar).
   - Thanh tiến trình HP & Mana (`bar_hp`, `bar_mana`) gắn kết trực tiếp cạnh nhãn số liệu, chiều cao `4px`.
3. **Tab Organization**:
   - Viết lại `_build_left_features`: Khởi tạo tab view, sau đó gọi tuần tự 4 phương thức chuyên biệt `_build_tab_quest`, `_build_tab_combat`, `_build_tab_client`, `_build_tab_intel`.
   - Xóa bỏ hoàn toàn việc chuyển đổi biến `scroll` qua lại giữa các tab.
   - Tất cả các slider được đưa vào container hàng đơn (`height=24`), đưa `lbl_burst`, `lbl_flask_hp`, `lbl_flask_mana`, `lbl_loot_radius` thành inline badges ở cuối thanh slider.

### 5.3. Module `overlay_gui.py`
1. **Streamline Automation Panel**:
   - Thu gọn `_create_automation_panel` từ chiều cao ~120px xuống **26px**.
   - Tạo khung `self.automation_frame` với `height=26`, `fg_color="#0d1117"`, viền mỏng 1px.
   - Tích hợp 5 status chips: `DODGE`, `FLASK`, `LOOT`, `COMBO`, `QUEST`.
   - Tạo nhãn `self.lbl_automation_ticker` hiển thị trạng thái động thời gian thực (ví dụ: `🟢 Bot Active · Core 120Hz · Loot R30`).
   - Duy trì thuộc tính cũ `self.reflex_label`, `self.loot_label`, `self.combo_label`, `self.quest_label` như các nhãn vô hình hoặc trỏ nội dung đồng bộ để đảm bảo 100% tương thích mã nguồn khác.
2. **Bảo tồn Tuyệt Đối Luồng Sự Kiện Đăng Ký (Critical Thread Safety Contract)**:
   - Theo yêu cầu kiểm thử của `tests/test_assistant_tool.py:325` (`test_task_opt_08_overlay_thread_safety`), cấu trúc khởi tạo trong `OverlayHUD.__init__` **BẮT BUỘC PHẢI CHỨA NGUYÊN VĂN** 2 dòng lệnh sau:
     ```python
     self.gold_tracker.register_listener(lambda new_gold: self.after(0, self._on_gold_changed, new_gold))
     self.log_watcher.register_listener(lambda evt: self.after(0, self._on_log_event, evt))
     ```
   - Nghiêm cấm thay đổi cú pháp hoặc tách dòng của 2 lệnh trên để không vi phạm assertion `inspect.getsource(OverlayHUD.__init__)`.

---

## 6. QUY TRÌNH THỰC THI & CHỐNG HỒI QUY (IMPLEMENTATION ROADMAP)

Quá trình triển khai thực tế sẽ diễn ra theo 4 giai đoạn độc lập:

```
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                        LỘ TRÌNH TRIỂN KHAI 4 GIAI ĐOẠN (ROADMAP)                       │
├────────────────────────────────────────────────────────────────────────────────────────┤
│ GIAI ĐOẠN 1: MỞ RỘNG TOKENS & DESIGN SYSTEM                                            │
│ - Bổ sung token màu sắc và metrics vào Config.THEME trong config.py.                   │
│ - Thêm helper functions (font_*, create_badge, create_compact_row) vào ui_theme.py.    │
│                                                                                        │
│ GIAI ĐOẠN 2: TÁI CẤU TRÚC CONTROL CENTER (TAB BUILDERS & HUD STRIP)                    │
│ - Thu gọn HUD Strip từ 72px xuống 44px (Dual Micro-Row Grid).                          │
│ - Bóc tách _build_left_features thành 4 hàm con chuyên biệt.                           │
│ - Rút gọn nhãn văn xuôi, chuyển đổi slider thành hàng đơn inline.                      │
│                                                                                        │
│ GIAI ĐOẠN 3: TINH GIẢN OVERLAY HUD (DYNAMIC TICKER +100PX VIEWPORT)                    │
│ - Thay thế 4 nhãn tĩnh bằng dynamic 1-line ticker 26px.                                │
│ - Mở rộng chiều cao cho arbitrage_frame & trading cards.                              │
│ - Giữ nguyên vẹn 100% thread-safety listener hooks.                                    │
│                                                                                        │
│ GIAI ĐOẠN 4: NGHIỆM THU THỰC NGHIỆM & KIỂM THỬ KHÉP KÍN (DOD GATE)                     │
│ - Chạy toàn bộ test suite pytest (Control Center, GUI Init, Assistant Tool, Sensor).   │
│ - Khẳng định zero regression (100% test pass).                                         │
└────────────────────────────────────────────────────────────────────────────────────────┘
```

---

## 7. TIÊU CHUẨN NGHIỆM THU THỰC NGHIỆM (EMPIRICAL DEFINITION OF DONE - DOD)

Theo đúng tôn chỉ Rule 9 & 10 của AutoPOE2, việc tái cấu trúc giao diện chỉ được coi là hoàn tất khi vượt qua toàn bộ các tiêu chí nghiệm thu độc lập dưới đây:

### 7.1. Cổng Kiểm Thử Dòng Lệnh Tự Động (Automated CLI Test Gate)
Phải thực thi thành công và ghi nhận đầu ra pass 100% trên các bộ kiểm thử:
```bash
python -m pytest tests/test_control_center.py tests/test_gui_init.py tests/test_assistant_tool.py tests/test_optical_hp_sensor.py tests/test_ipc_gui_nonblocking.py -v
```
- Không có bất kỳ lỗi `AttributeError` nào do thiếu thuộc tính widget.
- Không có bất kỳ lỗi `KeyError` nào trong `Config.THEME`.
- Kiểm thử luồng thread safety `test_task_opt_08_overlay_thread_safety` đạt PASS.
- Toàn bộ 25+ test cases của các bộ kiểm thử GUI và Helper đều đạt PASS tuyệt đối.

### 7.2. Đo Kiểm Kích Thước Hình Học Thực Nghiệm (Empirical Layout Metrics)
1. **HUD Strip Height**: Đo đạc hình học thực tế của `strip` trên Control Center đạt $\le 44\text{px}$ (giảm $\ge 38\%$ so với 72px ban đầu).
2. **Overlay Automation Panel Height**: Đo đạc hình học của `automation_frame` đạt $\le 26\text{px}$ (giảm $\ge 75\%$ so với 120px ban đầu).
3. **Trading Cards Viewport Gain**: Không gian hiển thị dọc cho danh sách lướt sóng thị trường tăng thêm tối thiểu **94px**, cho phép hiển thị thêm 2-3 cơ hội mua bán mà không cần cuộn trang.
4. **Header Height**: Chiều cao header thanh điều khiển đạt $44\text{px}$ (giảm 4px).

### 7.3. Tính Năng & An Toàn Tương Tác (Operational Invariants)
1. **Phím tắt toàn cục**: F8 (Bật/Tắt Bot), F6 (Bật/Tắt Bot phụ), Pause (Panic Stop), F10 (Tactical Brain), F9 (Chụp màn hình), F11 (Định vị XYZ) phản hồi ngay lập tức, không bị gián đoạn hay mất focus.
2. **IPC Đồng bộ Hot Path**: Nhịp tim và gói tin Telemetry từ C++ Core SHM cập nhật lên giao diện với độ trễ $\le 1.5\text{ms}$ per tick, không gây hiện tượng nghẽn GIL hoặc giật lag giao diện Tkinter.
3. **Zero Magic Numbers & Zero Mock Data**: Mọi thông số hiển thị đều ánh xạ trực tiếp từ dữ liệu thực (`CoreTelemetrySnapshot`, `GoldTracker`, `LogWatcher`).

---
*Tài liệu được biên soạn và bảo chứng bởi Dedicated Documentation & Architecture Specialist AutoPOE2 — Chuẩn mực Kỹ nghệ Phần mềm 2026.*