---
doc_id: "DOC-GDD-014"
title: "Đặc Tả Hệ Thống Túi Đồ, Kho Cá Nhân & Rương Bán Hàng Premium"
category: "game_design"
diataxis_type: "explanation"
status: "canonical"
version: "2026.1"
owner_role: "poe2_game_designer"
last_updated: "2026-09-30"
tags: ["inventory", "personal-stash", "merchant-stash", "megashop-gating", "2pc", "anti-dupe"]
related_code:
  - "server/inventory/inventory_service.py"
  - "server/inventory/inventory_types.py"
  - "server/shop/shop_catalog.py"
related_docs:
  - "docs/game_design/EQUIPMENT_SLOT_AND_SPATIAL_GRID_SYSTEM.md"
  - "docs/adr/0002_two_phase_commit_distributed_ledger.md"
summary: "Kiến trúc 3 tầng lưu trữ: Túi đồ sinh tồn, Kho cá nhân phân tab và Rương bán hàng Premium khóa Coin MegaShop, bảo vệ bằng 2PC chống dupe đồ."
---

# FREEEXILE: CHARACTER INVENTORY, PERSONAL STASH & PREMIUM MERCHANT STASH SYSTEM

Tài liệu đặc tả kiến trúc kỹ thuật hệ thống Túi Đồ Nhân Vật (Inventory Bag), Kho Lưu Trữ Cá Nhân Đa Tab (Personal Stash Tabs) và Rương Bán Hàng Lưu Đày (Premium Merchant Stash Tab) mở khóa bằng Huyết Cổ Tệ trong MegaShop theo chuẩn PoE2 & ARPG Cổ Võ Hoang Dã 2026.

---

## 1. TỔNG QUAN KIẾN TRÚC & PHÂN TẦNG LƯU TRỮ

Hệ thống lưu trữ của nhân vật trong FreeExile được thiết kế theo mô hình **Zero-Trust Server Authority**, phân tách thành 3 phân vùng rõ rệt:

```mermaid
flowchart TD
    A["Nhân Vật Lưu Đày (Character)"] --> B["1. Túi Đồ Sinh Tồn (Inventory Bag - 40 Ô)"]
    A --> C["2. Kho Cá Nhân Đa Tab (Personal Stash - 48 Ô/Tab)"]
    A --> D["3. Rương Bán Hàng (Premium Merchant Stash - 30 Ô)"]

    B <-->|"Trang bị / Gỡ"| E["Khung Trang Bị 8 Vị Trí (Equipment Paperdoll)"]
    B <-->|"Gửi / Rút tức thì"| C
    B <-->|"Niêm yết / Rút hàng"| D

    D -.->|"Bị khóa mặc định"| F["MegaShop Catalog Engine"]
    F -->|"Mua 500 Huyết Cổ Tệ"| D
    D ===|"Tự động niêm yết (2PC Instant Buyout)"| G["Hắc Thị Hoang Vực (Universal Consignment Vault)"]
```

---

## 2. CHI TIẾT CÁC PHÂN VÙNG LƯU TRỮ

### 2.1. Túi Đồ Sinh Tồn & Khung Trang Bị (Character Inventory & Equipment)
- **Mã nguồn**: [`server/inventory/inventory_types.py`](file:///c:/Projects/FreeExile/server/inventory/inventory_types.py), [`server/inventory/inventory_service.py`](file:///c:/Projects/FreeExile/server/inventory/inventory_service.py)
- **Dung lượng**: Mặc định 40 ô (`slots: Dict[int, InventoryItem]`), có thể mở rộng qua vật phẩm `item_inventory_expansion_vault`.
- **Khung trang bị (Paperdoll - 8 vị trí)**:
  - `MAIN_HAND`: Vũ khí chính (Trọng Kiếm, Cự Phủ, Cung, Kích, Ma Trượng).
  - `OFF_HAND`: Khiên hộ thân / Binh khí phụ.
  - `SWAP_MAIN_HAND`, `SWAP_OFF_HAND`: Bộ song binh dự phòng (chuyển đổi bằng phím `Tab` / `X`).
  - `HELMET`, `BODY_ARMOR`, `GLOVES`, `BOOTS`: Bộ tứ đại chiến giáp sinh tồn.
  - `AMULET`, `RING_1`, `RING_2`, `BELT`: Cốt phù, ma giới chỉ và đai lưng chứa bình dược.
- **Hỗ trợ Stackable**: Tự động gộp các loại đá huyết chế tác (`curr_blood_soul_gem`, `curr_chaos_stone`...) tối đa 5.000 viên/ô.

### 2.2. Kho Cá Nhân Đa Tab (Personal Stash Tabs)
- **Đặc điểm**: Kho cất giữ đặt tại Động Thiên Lưu Đày (Hideout) hoặc Doanh Trại Người Sống Sót.
- **Cấu trúc Tab mặc định**:
  1. `tab_general` (Kho Chung - 48 ô): Chứa trang bị, dược thảo, cuộn da dịch chuyển.
  2. `tab_currency` (Kho Huyết Thạch & Tiền Tệ - 48 ô): Chuyên dụng lưu trữ các loại đá barter (Khai Linh Châu, Hỗn Nguyên Thạch, Thiên Mệnh Đan, Huyết Ảnh Cổ Kính).
  3. `tab_equipment` (Kho Binh Khí & Thần Cốt - 48 ô): Chứa phôi đồ iLvl 85+, tàn cốt võ học và cổ phù.

---

## 3. RƯƠNG BÁN HÀNG LƯU ĐÀY (PREMIUM MERCHANT STASH TAB)

### 3.1. Ràng Buộc Kỹ Thuật & Mô Hình Premium
- **Quy tắc bắt buộc**: Rương Bán Hàng là tính năng **Premium**, mặc định ở trạng thái **LOCKED** (`is_unlocked: False`).
- **Hình thức mở khóa**: Người chơi phải sở hữu hoặc mua sản phẩm `item_premium_merchant_stash_tab` với giá **500 Huyết Cổ Tệ (Gold Cores)** từ MegaShop.
- **Cấu hình Catalog MegaShop**:
  - `product_id`: `item_premium_merchant_stash_tab`
  - `category`: `ProductCategory.ITEMS`
  - `coin_price`: 500
  - `purchase_limit_per_account`: 1
  - `badge_label`: `PREMIUM_TRADE`

### 3.2. Cơ Chế Bán Hàng & Liên Thông Hắc Thị Hoang Vực
- Khi chưa mở khóa: Giao diện hiển thị biểu tượng ổ khóa cổ hoàng kim, mô tả đặc quyền và nút điều hướng thẳng vào MegaShop (`window.openMegaShopToItem('items')`).
- Khi đã mở khóa:
  - Cung cấp 30 ô niêm yết bán hàng.
  - Người chơi chọn vật phẩm từ túi đồ, thiết lập giá bán bằng đơn vị Tiền Tệ Barter (ví dụ: `25 Hỗn Nguyên Thạch` hoặc `10 Thiên Mệnh Đan`).
  - Hệ thống tự động đẩy niêm yết sang [`server/trade/consignment_vault.py`](file:///c:/Projects/FreeExile/server/trade/consignment_vault.py) và bảo vệ bằng thuật toán khóa hai pha 2PC ([`two_phase_commit.py`](file:///c:/Projects/FreeExile/server/trade/two_phase_commit.py)).
  - Khớp lệnh tức thì (Instant Buyout) ngay cả khi chủ nhân rương đang offline.

```mermaid
sequenceDiagram
    autonumber
    actor Player as Kẻ Bán (Seller)
    participant Stash as Rương Bán Hàng (Merchant Stash)
    participant Vault as Vạn Giới Kỳ Trân (Consignment Vault)
    participant Engine as 2PC Buyout Engine
    actor Buyer as Kẻ Mua (Buyer)

    Player->>Stash: Đặt kiếm iLvl 85 + Đặt giá 50 Hỗn Nguyên Thạch
    Stash->>Vault: Đăng ký Listing niêm yết công khai
    Buyer->>Vault: Tìm kiếm và bấm Mua Tức Thì (Instant Buyout)
    Vault->>Engine: Kích hoạt Phase 1 (Prepare & Distributed Lock)
    Engine->>Engine: Khóa vật phẩm & Khóa 50 Hỗn Nguyên của Buyer
    Engine->>Engine: Phase 2 (Commit & Atomic Swap, khấu trừ thuế sàn 5%)
    Engine->>Stash: Xóa vật phẩm khỏi ô rương bán hàng
    Engine->>Player: Cộng tiền vào tài khoản người bán
    Engine->>Buyer: Chuyển kiếm vào hòm đồ người mua
```

---

## 4. MA TRẬN API & PHƯƠNG THỨC NGHIỆP VỤ

| Phương Thức | Tham Số Chính | Chức Năng |
| :--- | :--- | :--- |
| `add_item_to_inventory` | `account_id, char_id, item, preferred_slot` | Thêm vật phẩm vào túi đồ (tự động gộp stack nếu có). |
| `move_inventory_item` | `account_id, char_id, from_slot, to_slot` | Di chuyển hoặc hoán đổi vị trí giữa 2 ô trong túi. |
| `equip_item` | `account_id, char_id, inv_slot, equip_slot` | Trang bị vũ khí/giáp từ túi đồ vào ô trang bị tương ứng. |
| `unequip_item` | `account_id, char_id, equip_slot, target_inv_slot` | Gỡ trang bị cất lại vào túi đồ sinh tồn. |
| `deposit_to_stash` | `account_id, char_id, inv_slot, tab_id, stash_slot` | Chuyển vật phẩm từ túi đồ vào một Tab kho cá nhân. |
| `withdraw_from_stash` | `account_id, char_id, tab_id, stash_slot, target_inv_slot` | Rút vật phẩm từ kho cá nhân về lại túi đồ. |
| `is_merchant_stash_unlocked` | `account_id, char_id` | Kiểm tra trạng thái đã mua Premium Merchant Tab chưa. |
| `unlock_merchant_stash_with_coins` | `account_id, char_id` | Trừ 500 Huyết Cổ Tệ qua MegaShop để kích hoạt rương bán hàng. |
| `place_item_in_merchant_stash` | `account_id, char_id, inv_slot, m_slot, price_cur, price_amt` | Niêm yết đồ lên rương bán hàng (từ chối nếu tab đang bị khóa). |
| `update_merchant_item_price` | `account_id, char_id, m_slot, new_cur, new_amt` | Cập nhật giá niêm yết của vật phẩm đang bày bán. |
| `remove_item_from_merchant_stash` | `account_id, char_id, m_slot, target_inv_slot` | Rút vật phẩm chưa bán về túi đồ sinh tồn. |

---

## 5. TỔ CHỨC MÃ NGUỒN & GIAO DIỆN CLIENT

- **Server Backend**:
  - [`server/inventory/inventory_types.py`](file:///c:/Projects/FreeExile/server/inventory/inventory_types.py): DTOs & Models (`@dataclass(slots=True)`).
  - [`server/inventory/inventory_helpers.py`](file:///c:/Projects/FreeExile/server/inventory/inventory_helpers.py): Thuật toán tìm ô trống, kiểm tra tương thích gear, gộp stack.
  - [`server/inventory/inventory_service.py`](file:///c:/Projects/FreeExile/server/inventory/inventory_service.py): Bộ điều phối logic nghiệp vụ 100% Server Authority.
  - [`server/shop/shop_catalog.py`](file:///c:/Projects/FreeExile/server/shop/shop_catalog.py): Đăng ký sản phẩm SKU `item_premium_merchant_stash_tab`.
- **Client Frontend**:
  - [`client/webapp/index.html`](file:///c:/Projects/FreeExile/client/webapp/index.html): Nút bấm HUD `btn-open-inventory` (phím tắt `I`) & Modal toàn diện `#modal-inventory`.
  - [`client/webapp/js/ui/inventory_stash.js`](file:///c:/Projects/FreeExile/client/webapp/js/ui/inventory_stash.js): Module xử lý giao diện túi đồ, kho, và rương bán hàng có khóa/mở khóa tương tác.
  - [`client/webapp/js/ui/shop_megashop.js`](file:///c:/Projects/FreeExile/client/webapp/js/ui/shop_megashop.js): Kết nối sự kiện mua hàng trong MegaShop và mở khóa tức thì.
- **Kiểm thử tự hành (TDD)**:
  - [`tests/unit/test_inventory_service.py`](file:///c:/Projects/FreeExile/tests/unit/test_inventory_service.py): 6 bài test nghiệp vụ khép kín.
  - [`tests/unit/test_shop_catalog.py`](file:///c:/Projects/FreeExile/tests/unit/test_shop_catalog.py): Kiểm thử SKU sản phẩm trong danh mục MegaShop.