# 63. Đặc Tả Kiến Trúc: Quản Lý Vật Phẩm, Túi Đồ, Rương & Ngọc Kỹ Năng / Hỗ Trợ POE2 (Item, Inventory, Stash & Gem Lifecycle)

- **Mã tài liệu**: `SPEC-DOC-63-ITEM-INVENTORY-STASH-AND-GEM-LIFECYCLE-20260916`
- **Mốc thời gian**: `16/09/2026 09:15:00` (UTC+7)
- **Phiên bản tham chiếu**: Path of Exile 2 **v0.5.5+**, client build `6AA2213C`, AutoPOE2 IPC `PROTOCOL_VERSION = 0x00050005`
- **Nhân vật tham chiếu**: `BEONGUSI#3653` — Monk / Martial Artist CI, Lv 90, Shoreline Hideout
- **Trạng thái**: `[SSoT KIẾN TRÚC & QUY CHUẨN VẬN HÀNH VẬT PHẨM]`
- **Tuân thủ quy chuẩn**: Rule 1 (Two-Tier Asymmetric Architecture), Rule 2 (Context 2026), Rule 4 (Anti-Monolithic Ceiling 500-800 lines & Common Kernel), Rule 5 (Empirical DoD & Authentic Data), Rule 7 (Controls & Human Interlock)
- **Tài liệu căn cứ trước**:
  - [`docs/development/50_two_tier_asymmetric_hybrid_architecture_specification.md`](./50_two_tier_asymmetric_hybrid_architecture_specification.md) (Kiến trúc Hai Tầng Hot/Cold Path)
  - [`docs/development/58_character_management_state_machine_specification.md`](./58_character_management_state_machine_specification.md) (BotLifecycleFSM)
  - [`docs/development/61_autonomy_gap_audit_and_next_development_basis.md`](./61_autonomy_gap_audit_and_next_development_basis.md) (Autonomy Gap Audit)
  - [`docs/development/62_codebase_consolidation_and_common_kernel_architecture.md`](./62_codebase_consolidation_and_common_kernel_architecture.md) (Common Kernel Consolidation)

---

## 1. Bối Cảnh & Sự Khác Biệt Cốt Lõi Của POE2 Đối Với Vật Phẩm & Kỹ Năng

Trong Path of Exile 2, cơ chế vật phẩm và kỹ năng đã được đại tu hoàn toàn so với POE1. Mọi thiết kế tự hành bắt buộc phải phản ánh chính xác các cơ chế sau:

1. **Trang bị không có lỗ ngọc (Socketless Gear)**:
   - Vũ khí, áo giáp, găng tay, mũ, giày trong POE2 **không hề có lỗ ngọc (sockets)**.
   - Toàn bộ Skill Gems và Support Gems được gắn trực tiếp trong giao diện **Bảng Kỹ Năng (Phím `G`)**.
   - Kỹ năng chủ động (Active Skill) sở hữu các lỗ cắm ngọc hỗ trợ (thường từ 2 đến 5 slots tùy cấp độ và vũ khí).
2. **Hệ thống Đá Thô (Uncut Gems)**:
   - Quái vật rơi ra `Uncut Skill Gem`, `Uncut Support Gem`, và `Uncut Spirit Gem` theo các Bậc cấp độ (Tier Level 1-20).
   - Khi nhấp chuột phải vào Uncut Gem, menu Khắc Ngọc (Gem Cutting UI) sẽ xuất hiện để chọn kỹ năng.
3. **Phân bổ Bộ Vũ Khí (Weapon Set 1 vs Weapon Set 2)**:
   - Mỗi kỹ năng chủ động được chỉ định kích hoạt bằng **Weapon Set 1** hoặc **Weapon Set 2**, hoặc cả hai.
   - Đòn đánh của bot phải đồng bộ với trạng thái `activeWeaponSet` đọc từ RAM.
4. **Giám định tại Hideout (1-Click Identify All)**:
   - Game thủ POE2 không dùng Cuộn Giám Định (Scroll of Wisdom) cho từng món đồ trong rương hay túi tại Hideout.
   - Tại Hideout, NPC **The Hooded One** cung cấp tính năng `Identify All Items` miễn phí, giải mã toàn bộ đồ trong túi đồ chỉ với 1 click.

---

## 2. Bốn Trụ Cột Kiến Trúc Vận Hành

```
┌──────────────────────────────────────────────────────────────────────────────────────────┐
│                     HỆ THỐNG VẬT PHẨM & TỰ HÀNH TOÀN DIỆN (POE2 SSoT)                    │
└────────────────────────────────────────────┬─────────────────────────────────────────────┘
                                             │
      ┌──────────────────────┬───────────────┴───────────────┬──────────────────────┐
      ▼                      ▼                               ▼                      ▼
┌─────────────┐       ┌─────────────┐                 ┌─────────────┐        ┌─────────────┐
│  TRỤ CỘT 1  │       │  TRỤ CỘT 2  │                 │  TRỤ CỘT 3  │        │  TRỤ CỘT 4  │
│ Ground Loot │       │  Inventory  │                 │    Stash    │        │  Skill &    │
│  Pipeline   │       │  Capacity   │                 │  Lifecycle  │        │ Support Gem │
└──────┬──────┘       └──────┬──────┘                 └──────┬──────┘        └──────┬──────┘
       │                     │                               │                      │
       │ • Pickit Filter     │ • Lưới 12x5 (60 ô)            │ • Tab 1: Currency    │ • Bảng Gem (G)
       │ • Walk-to-Loot      │ • Hàng 1: Waystone/Tablets    │ • Tab 2: Waystones   │ • Uncut Gem Tiers
       │   (WASD <= 22u)     │ • Ngưỡng đầy: >= 48/60        │ • Tab 3: Gems        │ • Support Links
       │ • LMB có chủ đích   │ • Optical / Memory Track      │ • Tab 4: Dump Gear   │ • Weapon Set 1/2
       │ • Kháng click skill │ • The Hooded One (Identify)   │ • Ctrl+Click Jitter  │ • Combo Sync
```

---

### Trụ Cột 1: Quy Trình Nhặt Đồ Mặt Đất (Ground Loot Pipeline)
- **Khoảng cách tiếp cận & Thao tác chuột**:
  - `dist > 22.0u`: WASD di chuyển tiếp cận (dwell $\ge 300\text{ms}$).
  - `dist <= 22.0u`: `MoveMouseSmooth` tới nhãn vật phẩm, thực hiện Click LMB có chủ đích (`INV-WASD-NO-BLIND-LMB`).
- **Thang điểm Ưu Tiên Nhặt Đồ (Priority Scale)**:
  - `100`: Vàng (Gold) - tự động gom nhặt.
  - `95-99`: Mirror, Divine, Perfect/Greater Jeweller's Orbs.
  - `92`: Waystones (Tier 1-16) & Precursor Tablets.
  - `88`: Uncut Skill / Support / Spirit Gems.
  - `85`: Runes & Soul Cores.
  - `80`: Currency phổ thông (Chaos, Exalted, Vaal, Orbs, Shards).
  - `75`: Trang bị Unique.
  - `65`: Trang bị Rare.
  - `10-40`: Trang bị Magic/Normal (bỏ qua nếu không có phôi đặc biệt).
- **Bộ Lọc Dung Lượng Túi Đồ (Inventory Full Gate)**:
  - Khi cờ `isInventoryFull == true`: Từ chối toàn bộ trang bị có kích thước $\ge 2$ ô (Weapons, Body Armours, Shields, Helmets, Boots, Gloves). Chỉ cho phép nhặt đồ 1 ô có priority $\ge 80$ (Vàng, Currency, Waystones, Gems, Runes).

---

### Trụ Cột 2: Quản Trị Túi Đồ Nhân Vật (Inventory Capacity & Dynamic Grid Management)
- **Cấu trúc lưới**: $12 \text{ cột} \times 5 \text{ hàng} = 60 \text{ ô}$.
- **Định vị Động Toàn Diện (Dynamic 60-Slot Item Locator)**:
  - Loại bỏ hoàn toàn sự gò bó ép buộc người chơi phải đặt Waystones ở Hàng 1 (Row 0).
  - Thuật toán `scan_all_waystones` và `find_any_waystone` quét toàn bộ 60 ô ($col \in [0..11], row \in [0..4]$), tự động định vị vị trí của Waystone/Tablet bất kể người chơi đặt ở đâu trong túi để nhặt và kích hoạt Map Device.
- **Thuật Toán Sắp Xếp Gọn Gàng Theo Chiều Dọc (Vertical Column-Major Inventory Packing)**:
  - Khắc phục triệt để lỗi **phân mảnh không gian (Fragmentation)** của việc xếp theo hàng ngang (xếp ngang làm bẻ gãy các ô trống liên tục, làm mất chỗ cho các trang bị lớn 12 slot hoặc 2x4, 2x3, 2x6 như áo giáp và vũ khí 2 tay).
  - Quy tắc xếp dọc:
    - Gom toàn bộ đồ nhỏ 1x1 (Currency, Gems, Waystones, Charms, Rings, Amulets) dồn về các cột ngoài cùng bên phải (Cột 11 dồn sang Cột 10, từ trên xuống dưới).
    - Các cột dọc bên trái (Cột 0..9) luôn được bảo toàn nguyên vẹn chiều cao 5 hàng, cho phép đặt thoải mái các trang bị lớn 2x4 (Quarterstaff, Bow, Crossbow), 2x3 (Body Armour) và 2x2 (Mũ, Giày, Găng).

---

### Trụ Cột 3: Vòng Đời Rương Đồ Hybrid, Stash Affinity & Restock Waystones (Doc 63)
- **Kiến Trúc Lai Hybrid 3 Tầng (RAM Cache + Optical WinOCR + Clipboard Ground-Truth)**:
  1. **Tầng 1 (RAM Memory Cache - `StashMemoryReader`)**:
     - Đọc trực tiếp từ tiến trình game qua Windows API `ReadProcessMemory` (100% User Mode, Zero-Write).
     - Quản lý bộ nhớ đệm `SlotMemoryData` cho 60 ô túi đồ cá nhân, truy xuất $O(1)$ (< 0.05ms).
     - Cơ chế Fail-Soft: Tự động suy thoái mượt mà sang Optical/Clipboard nếu memory shift sau patch.
  2. **Tầng 2 (Optical WinOCR - `StashUiScanner`)**:
     - Quét thanh Tab Bar và danh sách Tab dọc hiệu chuẩn trên 2560x1440.
     - Nhận diện chính xác 100% các tab: Currency, Gem, Map (Waystones), Ritual, Dump...
     - Chốt chặn an toàn: Bắt buộc `is_inventory_open == True` kết hợp kiểm tra header Stash để xác minh giao diện đã mở thực tế, triệt tiêu hoàn toàn false positive do nhãn 3D 'STASH' dưới sàn.
  3. **Tầng 3 (Clipboard Ground-Truth & Stash Affinity)**:
     - Tận dụng tính năng Stash Affinity sẵn có trong POE2 (`use_stash_affinity = True`): `Ctrl + Click` lập tức game tự định tuyến vật phẩm về đúng tab chuyên dụng mà không cần duyệt pointer chain lồng nhau.
     - Chiết xuất thuộc tính chi tiết (Rarity, Item Class, Tier) qua clipboard tooltip khi cần thẩm định sâu.
- **Quy Trình Rút Bổ Sung Waystone Tự Hành (Restock Routine)**:
  - Chỉ tiêu bảo lưu cố định: `keep_waystones_count = 5` viên Waystone trong túi đồ để vận hành chu trình mapping liên tục.
  - Hỗ trợ toàn diện **Dedicated Map Stash Tab**:
    - Nhấp chọn Tier XV (`X=678, Y=325` trên 1440p) để kích hoạt danh sách bản đồ bậc cao nhất.
    - Quét lưới subgrid 8 cột x 9 hàng bắt đầu từ `(72, 490)`.
    - Tự động rút đủ số lượng Waystone còn thiếu (`needed = keep_waystones_count - current_waystones_in_bag`).
  - Hỗ trợ Fallback sang lưới 12x12 nếu người chơi sử dụng Regular hoặc Quad Stash Tab.
- **Quy Chuẩn Điều Khiển Tương Tác**:
  - Mở Stash bằng Click chuột trái (LMB) tuyệt đối (`INV-KEY-NO-F-FOR-INTERACT`, cấm phím F).
  - Tiếp cận bằng WASD Isometric nếu khoảng cách $> 200\text{px}$ (`INV-WASD-NO-BLIND-LMB`).
  - Dùng `Ctrl + Click` với độ trễ chuyển đồ $180\text{ms} \pm 40\text{ms}$ jitter tự nhiên (`INV-STASH-CTRL-CLICK`).
  - Đóng giao diện an toàn bằng phím `Spacebar`.

---

### Trụ Cột 4: Hệ Thống Ngọc Kỹ Năng & Hỗ Trợ (Skill & Support Gem Representation)
- **Cấu trúc Dữ Liệu Ngọc Kỹ Năng POE2**:
  - `ActiveSkillGem`: Tên kỹ năng, cấp độ, phím gán (`Q, W, E, R, T, LMB, RMB, MMB`), `weapon_set` tương thích (1 hoặc 2), danh sách support gem linked.
  - `SupportGem`: Tên ngọc hỗ trợ, cấp độ, thuộc tính bổ trợ (ví dụ: `Martial Tempo`, `Faster Attacks`, `Brutality`).
- **Khóa An Toàn Tuyệt Đối (Safety Invariant)**:
  - `INV-NO-AUTO-EQUIP-IN-COMBAT`: Bot tự hành **CẤM TUYỆT ĐỐI** tự ý thay đổi trang bị đang mặc hoặc tháo lắp Skill/Support Gems trong lúc chạy map.
  - Việc đánh giá đồ rơi (`WhatIsBetterEvaluator`) chỉ ghi nhận vào báo cáo hoặc cất riêng vào Tab Dump, để người chơi quyết định nâng cấp.

---

## 3. Danh Mục Bất Biến Kiến Trúc Mới (SSoT Invariants)

| Mã Bất Biến | Mô Tả Quy Tắc | Module Giám Sát |
| :--- | :--- | :--- |
| **INV-INVENTORY-VERTICAL-PACK** | Túi đồ và rương đồ được sắp xếp dồn theo chiều dọc (Column-Major Packing): đồ 1x1 dồn về cột phải, đồ lớn dồn cột trái để bảo toàn không gian cho item 2x3 và 2x4. | `VerticalInventoryPacker` |
| **INV-INVENTORY-DYNAMIC-LOCATE** | Tự động quét toàn bộ 60 ô túi đồ để định vị Waystones/Tablets ở bất kỳ vị trí nào, không ép người chơi phải đặt cố định ở hàng 1. | `OpticalInventoryScanner`, `StashMemoryReader` |
| **INV-FIELD-ID-DISCARD** | Giám định dã chiến bằng Scroll of Wisdom ngay trong map; nếu đồ rác thì vứt ngay ra đất (`FIELD_DISCARD`) để giải phóng ô túi đồ cho loot xịn. | `ItemLifecycleManager` |
| **INV-STASH-CTRL-CLICK** | Cất/rút đồ Stash dùng tổ hợp phím `Ctrl + Click` với cự ly giãn cách $180\text{ms} \pm 40\text{ms}$ jitter tự nhiên. Đóng giao diện bằng phím `Spacebar`. | `StashOrchestrator`, `win32_input` |
| **INV-STASH-WAYSTONE-RESTOCK** | Duy trì đúng 5 Waystones (`keep_waystones_count = 5`) trong túi đồ: thiếu rút từ Dedicated Map Tab (Tier XV subgrid), thừa cất vào Stash. | `StashEvaluator`, `StashOrchestrator` |
| **INV-STASH-HYBRID-CACHE** | Quản lý trạng thái 60 ô túi đồ qua RAM Memory Cache $O(1)$, kiểm tra an toàn chốt chặn quang học trước khi advance FSM. | `StashMemoryReader`, `StashItemMatrix` |
| **INV-NO-AUTO-EQUIP-IN-COMBAT** | Cấm bot tự ý thay trang bị hoặc tráo đổi Skill/Support Gems trong lúc đang farm. Chỉ nhặt và cất trữ an toàn. | `LootController`, `GemManager` |
| **INV-LOOT-PROXIMITY-22U** | Khoảng cách tới vật phẩm $> 22\text{u}$ bắt buộc dùng WASD tiếp cận; $\le 22\text{u}$ mới được click chuột nhặt. Khi túi đầy, từ chối nhặt trang bị $\ge 2$ ô. | `LootController` |