---
doc_id: "DOC-ARCH-010"
title: "Mật Thất Cá Nhân & Thiết Bị Cổng Vạn Giới"
category: "architecture"
diataxis_type: "explanation"
status: "canonical"
version: "2026.1"
owner_role: "server_systems_architect"
last_updated: "2026-09-29"
tags: ["hideout", "astral-portals", "instance-lifecycle", "map-device"]
related_code:
  - "server/world/hideout_engine.py"
  - "server/world/portal_device.py"
related_docs:
  - "docs/architecture/ENDGAME_WORLD_MAP_AND_MAP_CONTENT_ARCHITECTURE.md"
summary: "Kiến trúc Mật Thất Lưu Đày (Hideout) cá nhân, máy kích hoạt Cổng Vạn Giới (Astral Portals) và vòng đời instance."
---

# TÀI LIỆU KIẾN TRÚC KỸ THUẬT: TIÊN PHỦ ĐỘNG THIÊN & HỆ THỐNG CỔNG VẠN GIỚI (PLAYER HIDEOUT & ASTRAL WAYGATES)
# ARCHITECTURAL DESIGN RECORD (ADR) & TECHNICAL SPECIFICATION 2026

> **Trạng thái**: APPROVED & FULLY IMPLEMENTED  
> **Chủ quản**: [Trưởng Ban Kiến Trúc Server](file:///c:/Projects/FreeExile/AGENTS.md) (`server_systems_architect`), [Trưởng Nhóm Thiết Kế Game](file:///c:/Projects/FreeExile/AGENTS.md) (`poe2_game_designer`), [Kiến Trúc Sư Khách Hàng iOS/Web](file:///c:/Projects/FreeExile/AGENTS.md) (`ios_client_engineer`, `web_client_engineer`), [Trưởng Nhóm Bảo Mật](file:///c:/Projects/FreeExile/AGENTS.md) (`security_anticheat_lead`).  
> **Module liên quan**: [server/world/hideout_engine.py](file:///c:/Projects/FreeExile/server/world/hideout_engine.py), [proto/hideout.proto](file:///c:/Projects/FreeExile/proto/hideout.proto), [server/world/zone_engine.py](file:///c:/Projects/FreeExile/server/world/zone_engine.py), [tests/unit/test_hideout_engine.py](file:///c:/Projects/FreeExile/tests/unit/test_hideout_engine.py).

---

## 1. BỐI CẢNH & QUYẾT ĐỊNH KIẾN TRÚC (CONTEXT & ARCHITECTURAL DECISIONS)

### 1.1. Vấn Đề (Problem Statement)
Trong các tựa game ARPG đỉnh cao như *Path of Exile 2 (PoE2)*, Hideout (Căn Cứ / Động Phủ Cá Nhân) đóng vai trò là "trái tim" của toàn bộ vòng lặp trải nghiệm người chơi:
1. **Thiếu Không Gian Chuẩn Bị Tĩnh Lặng**: Người chơi cần một không gian riêng tư $100\%$ an toàn, không bị quấy rầy bởi quái vật, lag AOI từ hàng nghìn người chơi khác hoặc người lạ can thiệp.
2. **Endgame Map Device Thiếu Quy Chuẩn 6 Cổng**: Cơ chế mở bản đồ bí cảnh phân cấp (Tier 1 - 16) nếu không có giới hạn số lượt vào (Portals) sẽ làm triệt tiêu tính rủi ro (Risk vs Reward) và tạo điều kiện cho bot khai thác vô hạn mạng sống.
3. **Chạy Bộ Cồng Kềnh Đi Nhiệm Vụ**: Nếu bắt người chơi chạy bộ qua 5-10 bản đồ lớn để làm nhiệm vụ hoặc đánh boss truy nã, nhịp độ chơi trên màn hình cảm ứng di động sẽ bị kéo lê thê, gây mệt mỏi.
4. **Phân Tán Tiện Ích**: Rương đồ, lò chế tác linh thạch, điểm đả thông kinh mạch và đài uỷ thác AI nếu bị đặt rải rác ở các thành thị khác nhau sẽ khiến người chơi tốn thời gian di chuyển vô ích.

### 1.2. Quyết Định Thiết Kế (Architectural Decisions)
Dự án `FreeExile` kiến tạo **Tiên Phủ Động Thiên (Astral Hideout)** với kiến trúc phân vùng độc lập và hạ tầng Cổng Dịch Chuyển toàn năng:
- **Server-Authoritative Private Sanctum**: Mỗi người chơi sở hữu một động phủ thuộc loại `SANCTUARY`, phân vùng không gian độc lập qua [SpatialGrid](file:///c:/Projects/FreeExile/server/world/spatial_grid.py). Người chơi có thể mời đồng đội hoặc bang hội ghé thăm.
- **Thiên Đạo Tinh Đồ Nghi (Astral Map Device - Chuẩn PoE2 6 Portals)**:
  - Tiếp nhận **Thiên Đạo Tinh Đồ (Astral Map Tablets)** từ Tier 1 đến Tier 16.
  - Khi kích hoạt, đài bát quái triệu hồi **đúng 6 Cổng Hư Không (6 Portals)** xoay quanh hình lục giác đều.
  - Mỗi lần người chơi hoặc đồng đội bước qua cổng để tiến vào phó bản, 1 cổng bị tiêu hao ($6 \to 5 \to \dots \to 0$). Khi hết 6 cổng, bản đồ tự động niêm phong vĩnh viễn.
- **Vạn Giới Giới Môn (World Exploration Portal)**:
  - Cổng truyền tống cố định nối trực tiếp tới 10 Vùng Đất Mở Canonical trên Thần Châu đại lục (Táng Kiếm Nhai, Cổ Kiếm Trũng, Vô Định Bão Cát, Cổ Trận Huyết Lân, Ngũ Long Đàn, Vạn Trượng Băng Đàm, Vô Cực Huyết Trũng, Luyện Ngục Hỏa Quật, Vô Định Thiên Cung).
- **Thiên Mệnh Bí Cảnh Môn (Quest & Bounty Waygate)**:
  - Tự động liên kết với [QuestEngine](file:///c:/Projects/FreeExile/server/world/quest_engine.py), đồng bộ toạ độ mục tiêu nhiệm vụ đang thực hiện (Cốt truyện, Truy nã Boss, Mật thất kỳ ngộ) để đưa nhân vật nhảy thẳng đến chiến trường.
- **Tập Hợp Tứ Đại Tiện Ích Động Phủ**:
  - **Hắc Thị Hoang Vực & Rương Luân Hồi**: Kho lưu trữ cá nhân và tab Remove-Only từ mùa trước.
  - **Luyện Đan Lô & Lò Đúc Huyết Thạch**: Chế tác Huyết Hồn Thạch, Cổ Cốt Ấn, U Minh Cốt Đinh.
  - **Bát Mạch Đồ Đàn**: Đả tọa đả thông huyệt vị.
  - **Chiến Hồn Tế Cốt Đài**: Uỷ thác phân thân AI (`Agent_Orb`).

```mermaid
flowchart TD
    subgraph Hideout_Sanctum["TIÊN PHỦ ĐỘNG THIÊN (PLAYER PRIVATE HIDEOUT)"]
        SPAWN["Điểm Hồi Quy Động Phủ"]
        
        subgraph Portals_Hub["HẠ TẦNG CỔNG DỊCH CHUYỂN (WAYGATES HUB)"]
            MD["Thiên Đạo Tinh Đồ Nghi<br/>(PoE2 6-Portal Map Device)"]
            WG["Vạn Giới Giới Môn<br/>(World Exploration Gate)"]
            QG["Thiên Mệnh Bí Cảnh Môn<br/>(Quest & Bounty Gate)"]
        end

        subgraph Domestic_Facilities["TỨ ĐẠI CÔNG TRÌNH TƯƠNG TÁC"]
            VAULT["Rương Kỳ Trân & Tab Luân Hồi"]
            FORGE["Luyện Đan Lô & Lò Đúc Huyết Thạch"]
            MAT["Bát Mạch Đồ Đàn (Đả Tọa)"]
            ALTAR["Chiến Hồn Tế Cốt Đài (AI Agent)"]
        end
    end

    subgraph Destinations["ĐÍCH ĐẾN HƯ KHÔNG & THẦN CHÂU ĐẠI LỤC"]
        MAP_TIER["Phó Bản Tinh Đồ Tier 1 - 16<br/>(Hạn ngạch 6 Mạng / 6 Cổng)"]
        OPEN_WORLD["10 Vùng Đất Khám Phá Thế Giới Mở<br/>(Hoang Nguyên, Bão Cát, Núi Lửa, Thiên Cung)"]
        QUEST_ZONE["Chiến Trường Nhiệm Vụ & Trảm Ma Truy Nã<br/>(Cốt Truyện & Mật Thất Cơ Duyên)"]
    end

    MD -- "Kích hoạt Tinh Đồ (6 Portals)" --> MAP_TIER
    WG -- "Chọn Vùng Đất Canonical" --> OPEN_WORLD
    QG -- "Đồng bộ QuestEngine" --> QUEST_ZONE

    SPAWN --> MD
    SPAWN --> WG
    SPAWN --> QG
    SPAWN --> VAULT
    SPAWN --> FORGE
    SPAWN --> MAT
    SPAWN --> ALTAR
```

---

## 2. QUY TRÌNH THỰC THI (DIÁTAXIS FRAMEWORK)

### 2.1. Hướng Dẫn Nhập Môn: Bước Vào Động Phủ & Khởi Động Tinh Đồ Nghi (Tutorial)
Khi nhân vật đạt cấp độ 15 hoặc hoàn thành nhiệm vụ thức tỉnh đầu tiên:
1. Nhấn biểu tượng **🏠 Động Phủ** trên thanh điều khiển.
2. Server khởi tạo phiên Động Phủ riêng biệt với cảnh quan mặc định **Tiêu Dao Trúc Uyển**.
3. Tiến tới **Thiên Đạo Tinh Đồ Nghi** ở trung tâm đài bát quái:
   - Đặt vào Tinh Đồ Thạch (ví dụ: *Vòng Xoáy U Minh Tier 14*).
   - Nhấn **Kích Hoạt Tinh Đồ**: 6 Cổng Hư Không xoay chuyển ánh tím lập tức bừng sáng quanh đài.
4. Bước vào cổng: Hệ thống trừ 1 cổng ($6 \to 5$) và đưa nhân vật vào phó bản bí cảnh.

### 2.2. Hướng Dẫn Thực Hành: Điều Phối Cổng Khám Phá & Nhiệm Vụ (How-To Guide)
Để kết nối Cổng Thế Giới và Cổng Nhiệm Vụ qua API:
```python
from server.world.hideout_engine import HideoutEngine, AstralMap, FacilityType

engine = HideoutEngine()
player_id = "hero_swordsman_01"

# 1. Khởi tạo Động Phủ
hideout = engine.get_or_create_hideout(player_id)

# 2. Định tuyến Cổng Thế Giới tới Vô Định Bão Cát
ok, msg, gate_info = engine.configure_world_gate(player_id, "zone_boundless_sandstorm")

# 3. Đồng bộ Cổng Nhiệm Vụ tới Trảm Diệt Hắc Giao
ok_q, msg_q, q_info = engine.configure_quest_gate(
    player_id=player_id,
    quest_id="quest_story_02_hac_giao",
    quest_title="Trảm Diệt Hắc Giao Long Vương",
    target_zone_id="zone_abyssal_ice_pond",
    objective_x=90.0,
    objective_y=180.0
)

# 4. Kích hoạt Tinh Đồ Nghi Tier 16
map_item = AstralMap(
    map_id="map_t16_celestial",
    name="Vô Định Thiên Cung Bí Cảnh",
    tier=16,
    zone_template_id="zone_boundless_celestial_palace"
)
ok_m, msg_m, portals = engine.activate_map_device(player_id, map_item)

# 5. Bước qua cổng
ok_enter, enter_msg, travel_data = engine.enter_map_portal(player_id)
# travel_data["portals_remaining"] == 5
```

---

## 3. ĐẶC TẢ TRA CỨU THÔNG SỐ (TECHNICAL REFERENCE 100%)

### 3.1. Danh Sách Tứ Đại Cảnh Quan Động Phủ (Hideout Themes)

| Mã Cảnh Quan | Tên Động Phủ | Phong Cách Thẩm Mỹ | Đặc Trưng Thị Giác 2.5D |
| :--- | :--- | :--- | :--- |
| `BAMBOO_SHRINE` | **Tiêu Dao Trúc Uyển** | Kiếm hiệp Cổ Võ VLTK1 kinh điển | Rừng trúc xanh bạt ngàn, đình đài mái ngói hoàng kim, hồ sen hoa súng, lá phong thu rơi. |
| `ASTRAL_PEAK` | **Thái Hư Tiên Phong** | Tiên hiệp lơ lửng chín tầng mây | Đảo đá bay bồng bềnh giữa hư không, thác nước thần quang, tinh đồ sao trời chiếu rọi. |
| `DRAGON_VALLEY` | **Cổ Long U Cốc** | Thâm sơn cùng cốc cổ kính hắc ám | Vách đá tàn tích rồng thiêng, suối nước nóng địa nhiệt, dung nham phát quang huyền bí. |
| `LUNAR_SANCTUARY` | **Minh Nguyệt Hàn Đàm** | Dạ nguyệt tịch mịch thanh u | Ánh trăng vằng vặc soi bóng đầm sen phát quang, hoa súng dạ dạ nở rộ, đom đóm thần tiên. |

### 3.2. Cấu Trúc Toạ Độ 6 Cổng Tinh Đồ Nghi (Hexagonal Portals Layout)

$$\begin{cases}
x_i = x_{\text{center}} + R \cdot \cos\left(i \cdot \frac{2\pi}{6}\right) \\
y_i = y_{\text{center}} + R \cdot \sin\left(i \cdot \frac{2\pi}{6}\right)
\end{cases} \quad \text{với } i \in \{0, 1, 2, 3, 4, 5\}, \, R = 4.2\text{ mét}$$

---

## 4. BẢO MẬT & KIỂM CHỨNG TỰ HÀNH (SECURITY & VALIDATION)

1. **Khóa 6 Cổng Bất Biến (Strict 6-Portal Invariant)**:
   Không một người chơi nào có thể vào bản đồ quá 6 lần. Mọi gói tin giả mạo số lượt cổng đều bị server từ chối ngay lập tức.
2. **Kiểm Thử Khép Kín (TDD 100% Pass)**:
   Đạt chuẩn kiểm thử 7/7 unit tests tại [tests/unit/test_hideout_engine.py](file:///c:/Projects/FreeExile/tests/unit/test_hideout_engine.py) và 124/124 tests toàn hệ thống.