---
doc_id: "DOC-ARCH-009"
title: "Kiến Trúc Phó Bản & Tứ Đại Bí Thất Man Tộc"
category: "architecture"
diataxis_type: "explanation"
status: "canonical"
version: "2026.1"
owner_role: "server_systems_architect"
last_updated: "2026-09-29"
tags: ["dungeons", "secret-chambers", "instancing", "procedural"]
related_code:
  - "server/world/map_instance_system.py"
  - "server/world/zone_engine.py"
related_docs:
  - "docs/game_design/ITEM_CRAFTING_AND_AFFIX_GUIDE.md"
summary: "Đặc tả các hầm ngục leo tầng vô tận, cơ chế bí thất kỳ ngộ sinh tử và phòng đấu Hardcore 1 mạng sống."
---

# TÀI LIỆU KIẾN TRÚC KỸ THUẬT: HỆ THỐNG BẢN ĐỒ, PHÓ BẢN & MẬT THẤT HOANG VỰC
# 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`), [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 Thiết Kế Game](file:///c:/Projects/FreeExile/AGENTS.md) (`poe2_game_designer`), [Trưởng Nhóm Bảo Mật](file:///c:/Projects/FreeExile/AGENTS.md) (`security_anticheat_lead`).  
> **Phong cách**: Grimdark Savage Primal Exile ARPG (Cổ Võ Hoang Dã & Hắc Ám Lưu Đày - PoE2 Spirit).  
> **Module liên quan**: [server/world/zone_engine.py](file:///c:/Projects/FreeExile/server/world/zone_engine.py), [server/world/zone_catalog.py](file:///c:/Projects/FreeExile/server/world/zone_catalog.py), [server/world/spatial_grid.py](file:///c:/Projects/FreeExile/server/world/spatial_grid.py), [proto/map_zone.proto](file:///c:/Projects/FreeExile/proto/map_zone.proto), [tests/unit/test_map_instance_system.py](file:///c:/Projects/FreeExile/tests/unit/test_map_instance_system.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 MMORPG truyền thống, hệ thống bản đồ và phó bản thường gặp các lỗ hổng chí mạng:
1. **Gian Lận Tọa Độ & Dịch Chuyển (Speedhack / Teleport Hack)**: Client tự gửi gói tin tọa độ đến bất kỳ đâu hoặc vượt tường/vượt ải mà không qua xác thực logic di chuyển liên tục.
2. **Nghẽn Broadcast Toàn Bản Đồ (AOI Explosion)**: Toàn bộ người chơi trong một bản đồ lớn đều gửi gói tin cho nhau, gây quá tải $O(N^2)$ khi mật độ vượt quá vài trăm người.
3. **Rò Rỉ Trạng Thái Phó Bản (Instance Bleed-Through & Data Leakage)**: Dữ liệu thực thể, sát thương quái hoặc nhặt đồ giữa các phiên phó bản độc lập bị can thiệp chéo do dùng chung bộ nhớ phân vùng.
4. **Mật Thất Trở Thành Điểm Farm Cố Định**: Các phòng bí mật có tọa độ cố định bị bot khai thác 24/7, đánh mất hoàn toàn tính chất sinh tồn nghịch cảnh của vùng đất lưu đày hoang dã.

### 1.2. Quyết Định Thiết Kế (Architectural Decisions)
Dự án `FreeExile` áp dụng kiến trúc **Server-Authoritative Multi-Zone & Dynamic Instance Isolation**:
- **Zero-Trust Spatial Authority**: Client chỉ là công cụ hiển thị đồ họa và gửi hướng joystick. Game Server kiểm tra vận tốc tối đa ($v \le v_{\text{max}}$), va chạm đường bao (Boundary Bounds) và cự ly tương tác với Lối Qua Vùng Đất Chết ($r \le 8.0m$) trước khi cho phép dịch chuyển.
- **Phân Vùng Không Gian Độc Bản (Isolated Spatial Grids per Session)**: Mỗi phiên phó bản hoặc mật thất sở hữu một thực thể [SpatialGrid](file:///c:/Projects/FreeExile/server/world/spatial_grid.py) độc lập. Tuyệt đối không thể xảy ra hiện tượng người chơi ở phiên A nhìn thấy hoặc chia sẻ thực thể với phiên B.
- **Bí Thất Cơ Duyên Nghịch Cảnh (Lifespan Auto-Collapse)**: Bí thất chỉ mở ra khi thỏa mãn điều kiện ẩn từ [QuestEngine](file:///c:/Projects/FreeExile/server/world/quest_engine.py) (như thập tử nhất sinh dùng Huyễn Ảnh Bộ, bão cát tế xương, kích hoạt 5 cột thú tổ) và tự động sụp đổ sau thời gian đếm ngược ($10 - 15\text{ phút}$).
- **Mạng Lưới Trụ Thần Hành (Waypoints) Khám Phá Chủ Động**: Khám phá một lần, kích hoạt dịch chuyển nhanh giữa các vùng đất chết với cơ chế kiểm soát vị trí nghiêm ngặt.

```mermaid
flowchart TD
    subgraph Client_Layer["CLIENT LAYER (iOS Metal & Web Simulator)"]
        UI["HUD: Bản Đồ Hoang Vực & Hầm Ngục"]
        ISO["Isometric Renderer 2.5D (Metal / Canvas)"]
        VORTEX["Hiệu Ứng Vòng Xoáy Khe Nứt (Secret Vortex)"]
    end

    subgraph Network_Gateway["GATEWAY & PROTOCOL (proto/map_zone.proto)"]
        REQ["EnterZoneRequest / WaypointTeleportRequest"]
        NOTICE["SecretChamberRevealNotice / InstanceProgressSyncNotice"]
    end

    subgraph Server_Authoritative["SERVER CORE (server/world/zone_engine.py)"]
        AUTH["Boundary Check & Anti-Teleport Authority"]
        REGISTRY["10 Canonical Zones & Waypoint Registry"]
        INST_MGR["Dungeon Instance Lifecycle Manager"]
        SECRET_MGR["Secret Chamber Auto-Collapse Engine"]
    end

    subgraph Subsystems["SUBSYSTEMS INTEGRATION"]
        SPATIAL["SpatialGrid (AOI 9-cell Neighborhood)"]
        QE["QuestEngine (Discovery & Cryptic Trigger Hook)"]
        COMBAT["CombatEngine & Savage World Bosses"]
    end

    UI --> REQ
    REQ --> AUTH
    AUTH --> REGISTRY
    AUTH --> INST_MGR
    AUTH --> SECRET_MGR
    INST_MGR --> SPATIAL
    SECRET_MGR --> QE
    REGISTRY --> SPATIAL
    AUTH --> NOTICE
    NOTICE --> VORTEX
    NOTICE --> ISO
```

---

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

### 2.1. Hướng Dẫn Nhập Môn: Bước Vào Bản Đồ & Trụ Thần Hành (Tutorial)
Khi một nhân vật lưu đày dạt vào Bờ Đá Tàn Xương:
1. Server khởi tạo vị trí mặc định tại tọa độ an toàn: `(x: 50.0, y: 50.0)`.
2. Hệ thống mở khóa mặc định Trụ Thần Hành trung tâm tại `zone_boundless_sanctuary` (Doanh Trại Bến Lưu Đày).
3. Khi người chơi di chuyển đến gần Trụ Xương Thần Hành Bờ Đá Tàn Xương trong bán kính $15.0m$, server tự động kích hoạt trạng thái mở khóa (`unlocked_waypoints.add("wp_tang_kiem_cliff")`).
4. Người chơi có thể mở giao diện [Bản Đồ Hoang Vực](file:///c:/Projects/FreeExile/client/webapp/index.html) và nhấn **Dịch Chuyển Trụ Thần Hành** để di chuyển tức thì đến bất kỳ điểm nào đã phát hiện.

### 2.2. Hướng Dẫn Thực Hành: Kích Hoạt Bí Thất Cơ Duyên (How-To Guide)
Để cấu hình và kích hoạt một Bí Thất Man Tộc:
```python
# 1. Khởi tạo engine
from server.world.zone_engine import ZoneEngine
zone_engine = ZoneEngine()

# 2. Khi QuestEngine đối soát thấy điều kiện hiểm nghèo HP < 10% tại Phế Tích Xẻ Thịt
ok, chamber, msg = zone_engine.spawn_secret_chamber(
    template_id="secret_huyen_anh_to_su",
    player_id="player_hero",
    parent_zone_id="zone_blood_scale_ruins",
    portal_x=120.0,
    portal_y=85.0,
    lifespan_sec=600  # 10 phút tự động sụp đổ
)

# 3. Gửi thông báo SecretChamberRevealNotice về Client để hiển thị Vòng Xoáy Hư Không
# 4. Khi người chơi bước vào khe nứt:
success, enter_msg = zone_engine.enter_secret_chamber("player_hero", chamber.chamber_id)

# 5. Khi người chơi giải mã bia đá cốt ngữ thành công:
zone_engine.complete_secret_chamber("player_hero", chamber.chamber_id)

# 6. Bí thất tự động sụp đổ đưa người chơi an toàn về tọa độ lối vào
zone_engine.collapse_secret_chamber(chamber.chamber_id)
```

---

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

### 3.1. Ma Trận 10 Phân Khu Thế Giới Canonical (10 Canonical Zones)

| Mã Khu Vực (Zone ID) | Tên Khu Vực (Savage Style) | Loại Hình | Khí Hậu & Môi Trường | Cấp Độ | Ranh Giới ($W \times H$) | Trụ Thần Hành (Waypoint) | Lối Qua Vùng Đất Chết |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| `zone_boundless_sanctuary` | **Doanh Trại Bến Lưu Đày** | `SANCTUARY` | Bình Thường (Bến bờ an toàn) | $1 - 100$ | $800 \times 800 m$ | `wp_sanctuary_central` (Mặc định mở) | Cổng đi Bờ Đá, Đầm Lầy, Sa Cốt, Phế Tích |
| `zone_tang_kiem_nhai` | **Bờ Đá Tàn Xương** | `OPEN_WORLD` | Bình Thường (Xác thuyền vỡ) | $1 - 10$ | $1000 \times 1000 m$ | `wp_tang_kiem_cliff` | Về Bến Lưu Đày, vào Đầm Lầy Thối Rữa |
| `zone_ancient_sword_barrow` | **Đầm Lầy Thối Rữa** | `OPEN_WORLD` | Chướng Khí Độc | $8 - 20$ | $1200 \times 1200 m$ | `wp_ancient_sword_barrow` | Về Bờ Đá Tàn Xương, vào Sa Cốt Hoang Mạc |
| `zone_boundless_sandstorm` | **Sa Cốt Hoang Mạc** | `OPEN_WORLD` | Bão Cát Cuồng Phong | $20 - 35$ | $1500 \times 1500 m$ | `wp_sandstorm_oasis` | Về Đầm Lầy, vào Phế Tích Xẻ Thịt |
| `zone_blood_scale_ruins` | **Phế Tích Xẻ Thịt** | `OPEN_WORLD` | Dị Tượng Hư Không | $30 - 45$ | $1600 \times 1600 m$ | `wp_blood_scale_entrance` | Về Sa Cốt, lên Tế Đàn Man Hoang |
| `zone_five_elements_altar` | **Tế Đàn Man Hoang** | `OPEN_WORLD` | Bình Thường (Thạch trận thú tổ) | $40 - 55$ | $1800 \times 1800 m$ | `wp_five_elements_core` | Về Phế Tích, vào Vực Đầm Băng Độc |
| `zone_abyssal_ice_pond` | **Vực Đầm Băng Độc** | `OPEN_WORLD` | Hàn Băng Mật Độc | $50 - 65$ | $2000 \times 2000 m$ | `wp_abyssal_ice_shore` | Về Tế Đàn, vào Vực Đói Nuốt Chửng |
| `zone_infinite_blood_rift` | **Vực Đói Nuốt Chửng** | `OPEN_WORLD` | Vực Thẳm Xương Cạn | $60 - 75$ | $2200 \times 2200 m$ | `wp_infinite_blood_rift` | Về Vực Đầm, vào Miệng Lửa Nung Máu |
| `zone_purgatory_lava_cavern`| **Miệng Lửa Nung Máu** | `OPEN_WORLD` | Nham Thạch Sôi Sục | $70 - 85$ | $2400 \times 2400 m$ | `wp_lava_cavern_crater` | Về Vực Đói, lên Bệ Thờ Quỷ Đoạt Mệnh |
| `zone_boundless_celestial_palace` | **Bệ Thờ Quỷ Đoạt Mệnh** | `OPEN_WORLD` | Dị Tượng Hư Không | $85 - 100$ | $2500 \times 2500 m$ | `wp_celestial_peak` | Về Miệng Lửa, về Bến Lưu Đày |

---

### 3.2. Mẫu Hầm Ngục Leo Tầng Độc Lập (Dungeon Instance Templates)

| Mã Phó Bản | Tên Hầm Ngục | Số Tầng | Cấp Yêu Cầu | Giới Hạn Đội | Thời Gian | Mạng Sống | Đại Boss Trấn Thủ | Nhiệm Vụ Tiền Đề |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| `inst_phong_ma_co_tran` | **Hầm Ngục Phong Thú** | 50 Tầng | Lv 30+ | 4 Người | 30 Phút | 3 Mạng | [Xà Quái Vực Sâu](file:///c:/Projects/FreeExile/wiki/vi/MONSTERS_AND_BOSSES_SPECS.md#41-xà-quái-vực-sâu) (Tầng 50) | `quest_norm_05_khai_mo_van_gioi_cac` |
| `inst_bi_canh_hu_khong` | **Cõi Tuyệt Địa Hư Không** | 100 Tầng | Lv 60+ | 4 Người | 60 Phút | 1 Mạng (Hardcore) | **Viêm Quỷ Cuồng Nộ** (Tầng 100) | `quest_epic_03` |
| `inst_van_gioi_thi_luyen`| **Đấu Trường Sinh Tử Man Tộc** | 3 Đợt | Lv 15+ | 2 Người | 10 Phút | 3 Mạng | Dã Thú Biến Dị Tinh Anh | Không yêu cầu |

---

### 3.3. Tứ Đại Bí Thất Man Tộc Kỳ Ngộ (4 Cryptic Secret Chambers)

```mermaid
stateDiagram-v2
    [*] --> DORMANT: Khởi tạo thế giới
    DORMANT --> SPAWNED: Kích hoạt nghịch cảnh sinh tồn (QuestEngine Event)
    
    note right of SPAWNED
      Cửa Khe Nứt Hư Không xuất hiện
      Bộ đếm sụp đổ bắt đầu đếm lùi
    end note

    SPAWNED --> EXPLORING: Người chơi bước qua khe nứt
    SPAWNED --> COLLAPSED: Hết hạn thời gian (Timeout)
    
    EXPLORING --> CLEARED: Giải mã bia đá / tiêu diệt thủ lĩnh thú cổ
    EXPLORING --> COLLAPSED: Hết hạn thời gian
    
    CLEARED --> COLLAPSED: Thu hoạch di sản man tộc thành công
    COLLAPSED --> [*]: Người chơi an toàn hồi quy bản đồ mẹ
```

1. **Bí Thất Thân Pháp Xà Ảnh (`secret_huyen_anh_to_su`)**:
   - Bản đồ mẹ: `zone_blood_scale_ruins` (Phế Tích Xẻ Thịt).
   - Mục tiêu: Bia Đá Cốt Ngữ (`loc_secret_phantom_shrine`).
   - Thời gian tồn tại: $600\text{ giây}$ ($10\text{ phút}$).
   - Phần thưởng: $+5$ Điểm Thể Phách, $15$ Cổ Cốt Huyết Thạch, $3$ Cổ Cốt Ấn, Danh hiệu: *Huyết Ảnh Bộ Vô Song*.
2. **Hầm Mộ Chiến Binh Man Tộc (`secret_tan_bi_than_tuong`)**:
   - Bản đồ mẹ: `zone_boundless_sandstorm` (Sa Cốt Hoang Mạc).
   - Mục tiêu: Giải mã bia xương cổ (`action_decipher_ancient_stele`).
   - Thời gian tồn tại: $900\text{ giây}$ ($15\text{ phút}$).
   - Phần thưởng: $+6$ Điểm Thể Phách, $3$ U Minh Cốt Đinh, $20$ Cổ Cốt Huyết Thạch, Danh hiệu: *Chiến Hồn Bất Diệt*.
3. **Mắt Trận Thú Tổ Man Hoang (`secret_ngu_hanh_tran_nhan`)**:
   - Bản đồ mẹ: `zone_five_elements_altar` (Tế Đàn Man Hoang).
   - Mục tiêu: Kích hoạt Mắt Trận Thú Tổ (`loc_five_elements_altar`).
   - Thời gian tồn tại: $900\text{ giây}$ ($15\text{ phút}$).
   - Phần thưởng: $+8$ Điểm Thể Phách, $5$ Cổ Cốt Ấn, $5$ U Minh Cốt Đinh, Danh hiệu: *Ngũ Thú Thần Thông*.
4. **Hốc Đá Rửa Đao Oán Huyết (`secret_tang_kiem_kiem_chung`)**:
   - Bản đồ mẹ: `zone_tang_kiem_nhai` (Bờ Đá Tàn Xương).
   - Mục tiêu: Rửa sạch đao gãy rỉ sét (`action_cleanse_rusted_blade`).
   - Thời gian tồn tại: $900\text{ giây}$ ($15\text{ phút}$).
   - Phần thưởng: $+8$ Điểm Thể Phách, $25$ Cổ Cốt Huyết Thạch, $4$ U Minh Cốt Đinh, Danh hiệu: *Huyết Đao Bất Tử*.

---

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

### 4.1. Giao Thức Chống Teleport Hack & Out-of-Bounds
1. **Kiểm Tra Ranh Giới Tuyệt Đối**:
   $$\begin{cases} |x_{\text{target}}| \le \frac{\text{bounds\_width}}{2} \\ |y_{\text{target}}| \le \frac{\text{bounds\_height}}{2} \end{cases}$$
   Mọi gói tin vị trí vượt quá ranh giới đều bị loại bỏ ngay lập tức và đưa nhân vật về điểm hồi sinh.
2. **Kiểm Tra Cự Ly Lối Dịch Chuyển (Portal Interaction Gate)**:
   Người chơi chỉ có thể bước qua Cổng khi khoảng cách Euclidean thỏa mãn:
   $$d = \sqrt{(x_{\text{player}} - x_{\text{portal}})^2 + (y_{\text{player}} - y_{\text{portal}})^2} \le 8.0\text{ mét}$$
3. **Kiểm Thử Khép Kín (TDD 100% Pass)**:
   Toàn bộ logic phân vùng, phó bản và mật thất được kiểm thử tự động tại [tests/unit/test_map_instance_system.py](file:///c:/Projects/FreeExile/tests/unit/test_map_instance_system.py).