---
doc_id: "DOC-ARCH-014"
title: "Kiến Trúc Dịch Chuyển An Toàn & Cổng Sào Huyệt Chuẩn PoE2"
category: "architecture"
diataxis_type: "explanation"
status: "canonical"
version: "2026.1"
owner_role: "server_engineer"
last_updated: "2026-10-02"
tags: ["teleportation", "town-portal", "quarantine-engine", "poe2-map-device", "anti-exploit"]
related_code:
  - "server/world/game_design_matrix_schema.py"
  - "server/world/game_design_matrix_service.py"
  - "proto/portal.proto"
  - "server/world/hideout_engine.py"
related_docs:
  - "docs/game_design/PARTY_AND_SOCIAL_SYSTEM_SPECS.md"
  - "docs/standards/ENGINEERING_STANDARDS_2026.md"
summary: "Kiến trúc kỹ thuật chuẩn Diátaxis Explanation cho hệ thống Dịch Chuyển An Toàn 3.5s, Cổng Sào Huyệt 2 chiều PoE2 và Cổng Kiểm Duyệt Cách Ly chống exploit phòng Boss/Mật Thất."
---

# Kiến Trúc Dịch Chuyển An Toàn & Cổng Sào Huyệt Chuẩn PoE2

Tài liệu giải thích kiến trúc kỹ thuật (Architectural Explanation) cho cơ chế **Dịch Chuyển Tức Thời An Toàn (Safe Teleportation)**, **Cổng Dịch Chuyển Sào Huyệt (PoE2 Town Portal Engine)**, và **Cổng Kiểm Duyệt Cách Ly Chống Khai Thác (Anti-Exploit Quarantine Firewall)** trong dự án FreeExile.

---

## 1. Bối Cảnh & Vấn Đề Kỹ Thuật

Trong các tựa game ARPG nhiều người chơi, dịch chuyển tức thời và mở cổng thị trấn là hai bề mặt tấn công (attack surfaces) nguy hiểm nhất nếu không được kiểm soát chặt chẽ ở cấp độ máy chủ (Server-Authoritative):
- **Boss Combat Cheese**: Người chơi mở portal ngay trong trận đấu boss để trốn thoát khi sắp chết, hồi phục máu tại thị trấn rồi nhảy vào đánh tiếp.
- **Puzzle / Secret Chamber Bypass**: Mở portal trong phòng thử thách giải đố có đếm ngược để né tránh bẫy hoặc nhân bản vật phẩm nhiệm vụ.
- **Combat Teleport Exploit**: Đang bị quái vây hãm thì dịch chuyển tức thời không thời gian niệm (instant teleport) để né sát thương chết người.
- **Cross-Realm Infiltration**: Nhân vật thuộc cõi vĩnh cửu (`Standard Realm`) dịch chuyển vào phụ bản của mùa giải mới (`Seasonal Realm`) phá vỡ tính công bằng kinh tế.

FreeExile giải quyết triệt để các rủi ro trên thông qua mô hình phân tầng **Kênh Niệm 3.5s + 5 Cổng Thẩm Định + Tường Lửa Cách Ly (Quarantine Firewall)**.

---

## 2. Kiến Trúc Kênh Niệm Dịch Chuyển An Toàn (Safe Teleportation)

Quy chuẩn dịch chuyển được lưu tại bảng `teleport_configs` trong [`server/world/game_design_matrix_schema.py`](file:///c:/Projects/FreeExile/server/world/game_design_matrix_schema.py) và giao thức mạng tại [`proto/portal.proto`](file:///c:/Projects/FreeExile/proto/portal.proto).

### 2.1. Tham Số Niệm Chú Chuẩn

```
+--------------------------------------------------------------------------+
|                     SAFE TELEPORTATION SPECIFICATIONS                    |
+--------------------------------------------------------------------------+
|  Cast Time (Thời gian niệm)    : 3.5 giây (Tick 30Hz kiểm tra liên tục)   |
|  Cooldown (Thời gian hồi)      : 10.0 giây sau khi hoàn tất / bị ngắt     |
|  Interrupt on Movement (Di chuyển): CÓ (Ngưỡng magnitude > 0.05)          |
|  Interrupt on Damage (Sát thương): CÓ (Bất kỳ sát thương > 0 từ quái/môi trường) |
+--------------------------------------------------------------------------+
```

### 2.2. Máy Trạng Thái Kênh Niệm (Channeling State Machine)

```mermaid
stateDiagram-v2
    [*] --> IDLE
    IDLE --> CASTING: start_teleport(target) [Qua 5 Cổng Thẩm Định]
    
    CASTING --> CASTING: Tick 30Hz (Cập nhật tiến trình progress_ratio)
    CASTING --> INTERRUPTED: Di chuyển (mag > 0.05)
    CASTING --> INTERRUPTED: Nhận sát thương (Damage > 0)
    CASTING --> INTERRUPTED: Người chơi hủy bằng tay
    
    CASTING --> COMPLETED: Đủ 3.5 giây thành công
    INTERRUPTED --> IDLE: Kích hoạt Cooldown 10s
    COMPLETED --> IDLE: Thực thi dịch chuyển vị trí nhân vật
```

### 2.3. Quy Trình 5 Cổng Thẩm Định Đích Đến (5-Gate Destination Validation)

Trước khi cho phép bắt đầu niệm chú dịch chuyển, Server kiểm tra tuần tự 5 điều kiện nghiêm ngặt:

1. **Gate 1 - Target Liveness**: Mục tiêu (Đồng đội/Bạn bè/Hội viên) phải đang Online và có vị trí hợp lệ trong `ZoneEngine`.
2. **Gate 2 - Relationship Authorization**: Xác thực quyền quan hệ qua `SocialService` (Không bị chặn hai chiều, có trong Party/Friends/Guild).
3. **Gate 3 - Zone Capacity Limit**: Kiểm tra số người chơi hiện tại trong phân vùng đích $\text{CurrentPlayers} < \text{MaxCapacity}$ (Tối đa 6 người).
4. **Gate 4 - Instance Lifecycle**: Phân vùng thế giới đích phải còn sống (Chưa đóng, chưa hết hạn thời gian sụp đổ `collapse_timestamp_ms`).
5. **Gate 5 - Strict Realm Firewall**: Cấm tuyệt đối dịch chuyển giữa Cõi Bị Lãng Quên (`Standard Realm`) và Đại Nạn Hoang Vực (`Seasonal Realm`).

---

## 3. Kiến Trúc Cổng Sào Huyệt Hai Chiều (PoE2 Town Portal Engine)

### 3.1. Liên Kết Hai Chiều (2-Way Portal Link)

Khi người chơi mở Cổng Dịch Chuyển tại vùng hoang dã hoặc ngục tối, hệ thống thiết lập một đối tượng `TownPortalLink`:
- **Đầu A (Wilderness Anchor)**: Tọa độ thực `(wx, wy)` tại vị trí nhân vật đang đứng trong bản đồ dã ngoại.
- **Đầu B (Sanctuary Anchor)**: Điểm neo tại Vòng Tròn Dịch Chuyển của Sào Huyệt Cá Nhân (`zone_player_hideout`) hoặc Doanh Trại Hub (`zone_boundless_sanctuary`).
- **Khả dụng đồng đội**: Đồng đội trong cùng Party có thể sử dụng cổng của nhau để di chuyển tương hỗ.

### 3.2. Quản Lý Lượt Cổng & Bản Đồ Tinh Đồ Nghi (6-Portal Map Device)

Tuân thủ nghiêm ngặt mô hình endgame của Path of Exile 2:
- **Ngân sách 6 Cổng**: Bản đồ Bí Cảnh Tàn Đồ mở tối đa 6 cổng ra vào (`max_portals = 6`).
- **Khấu trừ lượt cổng**: Mỗi lần một người chơi bước qua cổng từ Hideout vào Map, số lượng cổng giảm đi 1 ($6 \to 5 \to \dots \to 0$).
- **Xử lý tử vong (Death Penalty)**:
  - Khi nhân vật tử vong trong Map Instance: Hồi sinh tại Hideout/Sanctuary và tiêu hao 1 cổng.
  - Khi còn 0 cổng: Bản đồ bị phong ấn vĩnh viễn, không thể quay lại phụ bản.
  - Khi nhân vật tử vong ở dã ngoại tự do (Open World): Cổng Town Portal cá nhân tự động đóng lại.

---

## 4. Tường Lửa Cách Ly Chống Khai Thác (Quarantine Firewall)

Quy tắc cách ly được lưu tại bảng `portal_quarantine_rules`:

```sql
CREATE TABLE IF NOT EXISTS portal_quarantine_rules (
    rule_id TEXT PRIMARY KEY,
    zone_type TEXT NOT NULL,
    boss_lockout INTEGER NOT NULL,
    secret_chamber_lockout INTEGER NOT NULL,
    max_portals INTEGER NOT NULL,
    description TEXT NOT NULL
);
```

### 4.1. Khóa Giao Tranh Boss (`boss_lockout = 1`)

- **Cơ chế**: Khi người chơi bước vào Đấu Trường Boss (Boss Arena), cờ `boss_encounter_in_progress = True` được bật.
- **Hành vi chặn**:
  - Lệnh `open_town_portal` bị từ chối dứt khoát với mã lỗi `QUARANTINE_BOSS_COMBAT_ACTIVE`.
  - Lệnh dịch chuyển từ bên ngoài nhảy vào vị trí đồng đội đang đánh Boss bị hủy bỏ.
- **Mở khóa**: Chỉ khi Boss bị tiêu diệt hoàn toàn hoặc toàn bộ tổ đội bị quét sạch (Wipe), cờ mới được gỡ bỏ.

### 4.2. Khóa Mật Thất Đếm Ngược (`secret_chamber_lockout = 1`)

- **Cơ chế**: Trong các buồng mật thất giải đố cơ quan hoặc thử thách đếm ngược thời gian sụp đổ (`secret_chamber_active = True`):
  - Cấm hoàn toàn việc mở Town Portal (`allow_town_portal = 0`).
  - Cấm người ngoài nhảy vào hỗ trợ nhằm bảo toàn tính toàn vẹn của câu đố.

---

## 5. Sơ Đồ Trình Tự Mở Cổng & Kiểm Duyệt Cách Ly

```mermaid
sequenceDiagram
    autonumber
    actor Player as Người Chơi
    participant PE as TownPortalEngine
    participant ZE as ZoneEngine
    participant QF as QuarantineFirewall
    participant DB as GameDesignMatrix

    Player->>PE: open_town_portal(wx, wy)
    PE->>ZE: get_zone_state(current_zone_id, instance_id)
    ZE-->>PE: {is_boss_active, is_secret_active}
    
    PE->>DB: get_portal_quarantine_rule(zone_type)
    DB-->>PE: PortalQuarantineRow
    
    PE->>QF: check_quarantine(is_boss_active, is_secret_active)
    alt Boss đang kích hoạt (is_boss_active == True)
        QF-->>PE: REJECT (QUARANTINE_BOSS_COMBAT_ACTIVE)
        PE-->>Player: Báo lỗi "Không thể mở cổng khi đang giao tranh Boss!"
    else Buồng mật thất đang chạy (is_secret_active == True)
        QF-->>PE: REJECT (QUARANTINE_SECRET_CHAMBER_ACTIVE)
        PE-->>Player: Báo lỗi "Không thể mở cổng trong Mật Thất Thử Thách!"
    else Hợp lệ
        QF-->>PE: APPROVED (QUARANTINE_OK)
        PE->>PE: Khởi tạo TownPortalLink (Wilderness <-> Hideout)
        PE-->>Player: Mở cổng thành công (Visual Rune xoay 2 chiều)
    end
```

---

## 6. Tra Cứu Protocol Buffers & Schema

- [`proto/portal.proto`](file:///c:/Projects/FreeExile/proto/portal.proto): Hợp đồng mạng cho trạng thái niệm chú, hủy niệm chú, liên kết cổng 2 chiều và mã lỗi cách ly.
- [`server/world/game_design_matrix_schema.py`](file:///c:/Projects/FreeExile/server/world/game_design_matrix_schema.py): Định nghĩa DDL bảng `teleport_configs` và `portal_quarantine_rules`.