# TÀI LIỆU ĐẶC TẢ KỸ THUẬT: HỆ THỐNG CẬP NHẬT GIÁ THỊ TRƯỜNG THỜI GIAN THỰC & BỘ LỌC NHẶT ĐỒ ĐỘNG (REAL-TIME MARKET PRICING & DYNAMIC PICKIT SPECIFICATION) > **Mã tài liệu**: `ARCH-MARKET-PICKIT-2026-P68` > **Mốc thời gian tham chiếu**: 17/09/2026 > **Trạng thái**: [ACTIVE / SSoT IMPLEMENTED] > **Phạm vi**: `src/assistant_tool/pickit/`, `src/assistant_tool/ui/market_pricing_panel.py`, `src/core/loot/`, `docs/development/` > **Tuân thủ**: Rule 1 (Hai Tầng C++/Python), Rule 4 (Kiến Trúc Module Hóa), Rule 5 (100% Dữ Liệu Thật), Rule 7 (Chuẩn Người Chơi Thật & Non-Hijacking). --- ## 1. BỐI CẢNH & ĐỘNG LỰC PHÁT TRIỂN (CONTEXT & PROBLEM STATEMENT) ### 1.1. Vấn đề kinh tế trong Path of Exile 2 (Dynamic Economy) Trong Path of Exile 2, nền kinh tế vật phẩm biến động liên tục theo ngày và theo từng meta mùa giải: - Các loại tiền tệ (`Chaos Orb`, `Divine Orb`, `Exalted Orb`, `Mirror of Kalandra`), các loại đá khảm (`Runes`, `Essences`), mảnh ghép (`Fragments`, `Vault Keys`) và ngọc kỹ năng chất lượng cao (`Uncut Gems`) có giá trị thay đổi lớn. - Bộ lọc nhặt đồ tĩnh (Static Pickit / Hardcoded Filter) nhanh chóng trở nên lạc hậu: - Bỏ sót các vật phẩm tăng giá đột biến (ví dụ Rune hiếm hoặc mảnh Breach/Delirium giá trị cao). - Tốn thời gian lượm các vật phẩm đã rớt giá thảm hại (dưới 1 Chaos), gây lãng phí không gian ba lô và giảm tốc độ cày map. ### 1.2. Yêu cầu của người dùng 1. Tích hợp API thị trường (`poe2-api` / `poe2scout`) để cập nhật giá cả thị trường thực tế. 2. Tự động đưa toàn bộ các vật phẩm có giá trị thị trường $\ge 1\text{ Chaos}$ vào danh mục ưu tiên nhặt đồ của Pickit. 3. Không làm giảm hiệu năng của Hot Path C++ 120Hz. --- ## 2. KIẾN TRÚC HAI TẦNG ĐỘNG BỘ (TWO-TIER ASYMMETRIC HYBRID ARCHITECTURE) Hệ thống tuân thủ nghiêm ngặt **Doc 50** và **Rule 1**: ``` +-------------------------------------------------------------------------+ | COLD PATH (Python 3.11 - 1/900Hz Background Service) | | | | [ POE2 Scout Public API ] | | | | | v HTTPS GET (12 Categories) | | +-------------------------------------------------------------------+ | | | MarketPriceFetcher (src/assistant_tool/pickit/market_price_fetcher)| | | | - Tự động phát hiện League hiện tại | | | | - Chuẩn hóa tỷ giá: chaos_value = Price_item / Price_chaos | | | | - Lưu cache tại data/market_prices.json (TTL = 30 phút) | | | +-------------------------------------------------------------------+ | | | | | v | | +-------------------------------------------------------------------+ | | | DynamicPickitUpdater (src/assistant_tool/pickit/dynamic_updater) | | | | - Lọc item có chaos_value >= 1.0 Chaos | | | | - Hợp nhất Baseline an toàn (Gold, Waystone, Basic Orbs) | | | | - Ghi file data/pickup_filter.json & bin/Release/pickup_filter.json| | | +-------------------------------------------------------------------+ | +-------------------------------------------------------------------------+ | | Ghi đè file pickup_filter.json (Atomic) v +-------------------------------------------------------------------------+ | HOT PATH (C++23 - 120Hz Native Engine) | | | | +-------------------------------------------------------------------+ | | | LootController (src/core/loot/loot_controller.cpp) | | | | - CheckReloadFilter() thăm dò file mtime mỗi 1000ms | | | | - Hot-reload O(1) unordered_set trong <0.05ms | | | | - ZERO heap allocation trong combat loop | | | | - Quét nhãn quang học & nhặt đồ <5ms (WASD Proximity Interlock) | | | +-------------------------------------------------------------------+ | +-------------------------------------------------------------------------+ ``` --- ## 3. ĐẶC TẢ CANONICAL API & BỘ CHUYỂN ĐỔI TỶ GIÁ (MARKET FETCHER SSoT) ### 3.1. POE2 Scout Endpoint Contract - **Base URL**: `https://api.poe2scout.com` (Lưu ý: Không thêm tiền tố `/api/`). - **Endpoint danh sách League**: `GET /poe2/Leagues` - **Endpoint giá vật phẩm theo Category**: `GET /poe2/Leagues/{league}/Currencies/ByCategory?Category={category}` - **12 danh mục được quét định kỳ**: 1. `currency` 2. `runes` 3. `essences` 4. `ultimatum` 5. `ritual` 6. `delirium` 7. `uncutgems` 8. `fragments` 9. `vaultkeys` 10. `breach` 11. `abyss` 12. `incursion` ### 3.2. Công thức chuẩn hóa tỷ giá Chaos Orb POE2 Scout định giá các vật phẩm bằng đơn vị nội bộ (thường là Shards hoặc điểm quy đổi cơ bản). Để chuẩn hóa về Chaos Orb: 1. Tìm vật phẩm `Text == "Chaos Orb"` trong category `currency`. 2. Lấy giá cơ sở $P_{\text{chaos}}$ (ví dụ: $P_{\text{chaos}} = 50.0$). 3. Với mọi vật phẩm $i$ có đơn giá $P_i$: $$\text{chaos\_value}_i = \frac{P_i}{P_{\text{chaos}}}$$ 4. Vật phẩm được đưa vào danh sách nhặt khi: $$\text{chaos\_value}_i \ge 1.0$$ --- ## 4. QUY TẮC BẢO TOÀN AN TOÀN (SAFETY INVARIANTS & BASELINE) ### 4.1. Baseline Always Pick (Bất biến bảo toàn vật phẩm cốt lõi) Dù giá thị trường biến động thế nào, các vật phẩm nền tảng sau **BẮT BUỘC LUÔN LUÔN ĐƯỢC NHẶT**: - `Gold`: Tiền tệ nâng cấp thị trấn và giao dịch. - `Waystone`: Vé vào bản đồ Endgame (T1 - T16). - `Uncut Skill Gem`, `Uncut Spirit Gem`: Nguồn sức mạnh kỹ năng. - Các loại Orb cơ bản: `Exalted Orb`, `Divine Orb`, `Chaos Orb`, `Vaul Orb`, `Regal Orb`, `Orb of Alchemy`, `Orb of Chance`. - Các loại đá quý: `Greater Jeweller's Orb`, `Perfect Jeweller's Orb`, `Mirror of Kalandra`. ### 4.2. Cấu trúc Schema `pickup_filter.json` ```json { "schema": "autopoE2.pickup_filter.v1", "version": 2, "updated_at": "2026-09-17 03:30:00", "min_chaos_threshold": 1.0, "exact_types": [ "Gold", "Waystone (Tier 1)", "Mirror of Kalandra", "Hinekora's Lock", "Aldur's Legacy", "Raven-Touched Shard", "Divine Orb", "Chaos Orb" ], "name_substrings": [ "Waystone", "Mirror", "Uncut Gem", "Rune", "Splinter", "Shard" ] } ``` --- ## 5. TÍCH HỢP GIAO DIỆN ĐIỀU KHIỂN (CONTROL CENTER INTEGRATION) ### 5.1. Thành phần UI `MarketPricingPanel` Đặt tại `src/assistant_tool/ui/market_pricing_panel.py`: - `lbl_market_league`: Hiển thị League hiện tại (ví dụ `🌐 Mùa giải: Runes of Aldur`). - `lbl_market_rates`: Hiển thị tỷ giá quy đổi và thời điểm cập nhật. - `lbl_market_valuable_count`: Hiển thị số lượng vật phẩm đang được lọc nhặt ($\ge 1\text{ Chaos}$). - `chk_auto_sync_market`: Tự động đồng bộ mỗi 15 phút. - `btn_sync_market_now`: Nút kích hoạt đồng bộ ngay lập tức (chạy worker ngầm qua `threading.Thread(daemon=True)`). - `lbl_market_sync_status`: Trạng thái thực thi. ### 5.2. Tích hợp không xâm lấn (Rule 4A Anti-Monolithic) Tại `src/assistant_tool/ui/tabs/tab_intel.py`: Ủy nhiệm duy nhất bằng 1 dòng lệnh: ```python # Tích hợp thị trường thời gian thực & Dynamic Pickit (>= 1.0 Chaos) build_market_pricing_section(app, scroll) ``` Không nhồi nhét logic API hay xử lý luồng vào file điều khiển trung tâm. --- ## 6. KIỂM THỬ THỰC NGHIỆM & KẾT QUẢ ĐẠT ĐƯỢC (EMPIRICAL VERIFICATION) ### 6.1. Dữ liệu thực tế từ Live POE2 Scout API (17/09/2026) - **Tổng số vật phẩm quét được**: 183 vật phẩm trên 12 danh mục. - **Giá mốc Chaos Orb**: 50.0 đơn vị. - **Số vật phẩm đạt ngưỡng $\ge 1.0\text{ Chaos}$**: **161 vật phẩm**. - **Top vật phẩm giá trị cao nhất**: 1. `Mirror of Kalandra`: 36,000.0 Chaos 2. `Hinekora's Lock`: 7,400.0 Chaos 3. `Aldur's Legacy`: 1,800.0 Chaos 4. `Raven-Touched Shard`: 1,300.0 Chaos 5. `Simulacrum Splinter`: 60.0 Chaos 6. `Divine Orb`: 2.5 Chaos - **Các vật phẩm bị loại bỏ (< 1.0 Chaos)**: - `Transmutation Shard`: 0.01 Chaos - `Lesser Life Flask`: 0.02 Chaos - `Orb of Transmutation`: 0.1 Chaos ### 6.2. Kết quả Unit Tests - `tests/test_market_pickit.py`: - `TestMarketPriceFetcher.test_chaos_calculation_synthetic`: PASS (0.01s) - `TestDynamicPickitUpdater.test_filter_generation_and_threshold`: PASS (0.01s) - `TestMarketPricingPanel.test_build_market_pricing_section`: PASS (0.01s) - `TestMarketPricingPanel.test_run_market_sync_worker`: PASS (0.01s) - **Tổng cộng: 4/4 tests PASS (0.261s)**.