---
doc_id: "DOC-GDD-010"
title: "Kiến Trúc Hệ Thống Nhiệm Vụ & Mốc Phần Thưởng Server-Authoritative"
category: "game_design"
diataxis_type: "explanation"
status: "canonical"
version: "2026.1"
owner_role: "poe2_game_designer"
last_updated: "2026-09-29"
tags: ["quest-system", "milestones", "lore-progression", "rewards"]
related_code:
  - "server/world/quest_engine.py"
  - "server/world/quest_catalog.py"
related_docs:
  - "docs/game_design/NPC_SYSTEM_ARCHITECTURE.md"
summary: "Cây nhiệm vụ chính tuyến và kỳ ngộ hoang dã, thẩm định điều kiện máy chủ, trả thưởng Cổ Cốt và điểm Huyết Cốt Ma Đồ."
---

# TÀI LIỆU KIẾN TRÚC KỸ THUẬT: HỆ THỐNG NHIỆM VỤ & MỐC PHẦN THƯỞNG SERVER-AUTHORITATIVE
# ARCHITECTURAL DESIGN RECORD (ADR) & TECHNICAL SPECIFICATION 2026

> **Trạng thái**: APPROVED & 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ư Tài Liệu](file:///c:/Projects/FreeExile/AGENTS.md) (`lead_documentation_architect`), [Trưởng Nhóm Bảo Mật](file:///c:/Projects/FreeExile/AGENTS.md) (`security_anticheat_lead`).  
> **Module liên quan**: [server/world/quest_engine.py](file:///c:/Projects/FreeExile/server/world/quest_engine.py), [proto/quest.proto](file:///c:/Projects/FreeExile/proto/quest.proto), [tests/unit/test_quest_engine.py](file:///c:/Projects/FreeExile/tests/unit/test_quest_engine.py).

---

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

### 1.1. Vấn Đề (Problem Statement)
Trong các tựa game MMORPG truyền thống, hệ thống nhiệm vụ thường mắc phải các điểm nghẽn nghiêm trọng:
1. **Lạm Phát Tiền Tệ**: Thưởng tiền vàng vô giá trị dẫn đến lạm phát kinh tế sau 2-4 tuần vận hành.
2. **Gian Lận Phía Client (Client Tampering)**: Client có thể tự gửi gói tin "nhiệm vụ hoàn thành" hoặc can thiệp bộ nhớ để tua nhanh tiến độ.
3. **Trải Nghiệm Đơn Điệu**: Nhiệm vụ chạy theo lối mòn "đến gặp NPC A -> đánh 10 quái -> quay về trả bài", thiếu tính bất ngờ và chiều sâu cổ võ.
4. **Lỗi Trùng Lặp Nhận Thưởng (Double Claim / Race Conditions)**: Spam gói tin claim gây dupe vật phẩm giá trị cao.

### 1.2. Quyết Định Thiết Kế (Architectural Decision)
Dự án `FreeExile` áp dụng kiến trúc **Server-Authoritative Event-Driven Quest Engine**:
- **Zero-Trust Client Authority**: Client chỉ gửi input chuyển động và kích hoạt chiêu thức; tiến độ nhiệm vụ do chính **Tick Simulation Loop (30Hz)** trên Game Server đơn phương cập nhật khi đối soát sự kiện trảm quái, khai mở gân cốt, chế tác cổ cốt huyết thạch hoặc khám phá tọa độ.
- **Kinh Tế Barter Cổ Cốt & Huyết Thạch**: Mọi phần thưởng nhiệm vụ và mốc hoàn thành đều trao tặng các loại [Cổ Cốt & Huyết Thạch Bản Vị](file:///c:/Projects/FreeExile/docs/game_design/ORIGINAL_SYSTEMS_AND_ECONOMY.md) (Huyết Hồn Thạch, Cổ Cốt Ấn, U Minh Cốt Đinh, Huyết Ảnh Cổ Kính) và Điểm Mắt Xích Huyết Cốt Ma Đồ.
- **Phân Tầng Tam Cấp (Three-Tier Classification)**:
  - *Nhiệm Vụ Sinh Tồn (Normal)*: Dẫn dắt thế giới quan hoang dã.
  - *Kỳ Ngộ Đẫm Máu (Cryptic Secret)*: Kích hoạt ngẫu nhiên qua các điều kiện bí ẩn trong tàn tích cổ.
  - *Thử Thách Man Quái (High-Tier Epic)*: Thử thách kỹ năng đỉnh phong, săn Boss Dị Thú.
- **Cây Mốc Bậc Thang (Milestone Progression Tiers I - V)**: Tích lũy số lượng hoàn thành để mở khóa kho báu bản vị và mở rộng dung lượng [Hắc Thị Hoang Vực](file:///c:/Projects/FreeExile/server/trade/consignment_vault.py).
- **Giao Thức Schema-First Protobuf**: Chuẩn hóa thông điệp mạng tại [proto/quest.proto](file:///c:/Projects/FreeExile/proto/quest.proto).

---

## 2. SƠ ĐỒ MÁY TRẠNG THÁI NHIỆM VỤ (QUEST STATE MACHINE)

Mỗi nhiệm vụ trong tiến trình của người chơi tuân thủ máy trạng thái hữu hạn (FSM) nghiêm ngặt:

```mermaid
stateDiagram-v2
    [*] --> LOCKED: Khởi tạo người chơi

    LOCKED --> AVAILABLE: Đạt Level yêu cầu & Hoàn thành Quests tiền đề
    AVAILABLE --> IN_PROGRESS: Người chơi chấp nhận (accept_quest)

    note right of LOCKED
      Nhiệm vụ Ẩn (HIDDEN)
      bỏ qua AVAILABLE,
      chờ kích hoạt cơ duyên
    end note

    LOCKED --> IN_PROGRESS: Thỏa mãn điều kiện bí mật (trigger_hidden_quest)

    IN_PROGRESS --> COMPLETED: Server xác thực 100% mục tiêu (all objectives completed)
    IN_PROGRESS --> FAILED: Hết hạn thời gian hoặc thất bại điều kiện

    COMPLETED --> CLAIMED: Nhận thưởng thành công (claim_quest_reward)
    CLAIMED --> [*]: Lưu trữ tiến trình vĩnh viễn (Event Sourcing)

    FAILED --> IN_PROGRESS: Tái kích hoạt / thử thách lại
```

---

## 3. LUỒNG TƯƠNG TÁC SỰ KIỆN MẠNG (EVENT-DRIVEN INTERACTION FLOW)

### 3.1. Luồng Xác Thực Tiến Độ Zero-Trust

```mermaid
sequenceDiagram
    autonumber
    actor Client as Player Client (iOS Metal)
    participant Gateway as Authoritative Gateway
    participant Combat as Combat Engine
    participant Spatial as Spatial Grid
    participant QE as Quest Engine
    participant Ledger as Event Sourcing Ledger

    Client->>Gateway: Gửi gói tin CastMartialSkillRequest
    Gateway->>Combat: Thực thi sát thương lên Quái Vật
    Combat->>Spatial: Quái vật tử vong (mob_trash_bone_hound)
    Combat->>QE: Broadcast Event: record_kill("mob_trash_bone_hound", count=1)
    
    QE->>QE: Duyệt các quest IN_PROGRESS của player
    QE->>QE: Cập nhật Objective: current_count += 1
    
    alt Toàn bộ mục tiêu đã đạt (current_count >= target_count)
        QE->>QE: Chuyển trạng thái: status = COMPLETED
        QE->>Gateway: Push Notice: QuestProgressSyncNotice (COMPLETED)
        Gateway-->>Client: Hiển thị thông báo hoàn thành & Haptic Pulse
    else Chưa hoàn thành
        QE->>Gateway: Push Notice: QuestProgressSyncNotice (Tiến độ mới)
        Gateway-->>Client: Cập nhật thanh tiến độ HUD UI
    end

    Client->>Gateway: Gửi ClaimQuestRewardRequest(quest_id)
    Gateway->>QE: Thực thi claim_quest_reward(player_id, quest_id)
    QE->>QE: Kiểm tra trạng thái: status == COMPLETED?
    QE->>Ledger: Ghi nhận giao dịch linh thạch nguyên tử
    QE->>QE: Đóng dấu: status = CLAIMED, claimed_at = now()
    QE-->>Gateway: Trả lời ClaimQuestRewardResponse(Success, Rewards)
    Gateway-->>Client: Trao thưởng linh thạch & Cột sáng Loot Beam
```

---

## 4. CHI TIẾT ĐẶC TẢ KỸ THUẬT MỐC HOÀN THÀNH (MILESTONE TIERS)

Hệ thống mốc phần thưởng vận hành độc lập với từng nhiệm vụ riêng lẻ. Khi người chơi tích lũy đủ các chỉ số điều kiện, hệ thống sẽ mở trạng thái nhận thưởng:

$$\text{Eligible}(M) \iff \begin{cases} 
N_{\text{total}} \ge M.\text{req\_total} \\ 
N_{\text{hidden}} \ge M.\text{req\_hidden} \\ 
N_{\text{high\_tier}} \ge M.\text{req\_high\_tier} \\ 
M.\text{id} \notin \text{ClaimedMilestones}
\end{cases}$$

### Ma Trận Điều Kiện & Phần Thưởng Bản Vị

| Bậc Mốc | $N_{\text{total}}$ | $N_{\text{hidden}}$ | $N_{\text{high\_tier}}$ | Phần Thưởng Bản Vị | Điểm Kinh Mạch | Vinh Dự & Đặc Quyền |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **Mốc I: Sơ Nhập Hoang Giới** | $5$ | $0$ | $0$ | • Hắc Sơ Thạch x10<br/>• Uẩn Ma Thạch x5 | $+2$ | Danh hiệu: *Hoang Giới Tân Tú* |
| **Mốc II: Thông Suốt Kinh Mạch** | $7$ | $1$ | $0$ | • Huyết Hồn Thạch x15<br/>• Cổ Cốt Ấn x2 | $+5$ | Danh hiệu: *Thông Mạch Tông Sư*<br/>$+20$ ô ký gửi Kỳ Trân Các |
| **Mốc III: Chân Võ Xuất Thế** | $9$ | $2$ | $1$ | • Huyết Hồn Thạch x30<br/>• Cổ Cốt Ấn x6<br/>• U Minh Cốt Đinh x5 | $+8$ | Danh hiệu: *Chân Võ Chấn Thế*<br/>Giảm $50\%$ phí giao dịch sàn |
| **Mốc IV: Nghịch Mệnh Chuyển Luân** | $11$ | $3$ | $2$ | • Huyết Hồn Thạch x60<br/>• Cổ Cốt Ấn x15<br/>• U Minh Cốt Đinh x10 | $+15$ | Danh hiệu: *Nghịch Mệnh Tiên Phong*<br/>Slot Bí Bảo thứ 2 |
| **Mốc V: Vạn Giới Chí Tôn** | $13$ | $4$ | $4$ | • **Huyết Ảnh Cổ Kính x2**<br/>• Huyết Hồn Thạch x150<br/>• Cổ Cốt Ấn x50<br/>• U Minh Cốt Đinh x30 | $+30$ | Danh hiệu: **Vạn Giới Chí Tôn**<br/>Loot Beam Hào Quang Vô Cực |

---

## 5. BẢO MẬT & PHÒNG CHỐNG RACE CONDITIONS (ANTI-DOUBLE CLAIM)

### 5.1. Cơ Chế Chống Double Claim
Để ngăn chặn tấn công spam gói tin đồng thời nhằm nhận thưởng 2 lần:
```python
def claim_milestone_reward(
    self, player_id: str, milestone_id: str
) -> Tuple[bool, Optional[QuestReward], str]:
    self.initialize_player(player_id)
    milestone = self.get_milestone(milestone_id)
    if not milestone:
        return False, None, "Không tìm thấy thông tin mốc phần thưởng!"

    claimed_set = self._player_milestones[player_id]
    # 1. Kiểm tra tập hợp đã nhận (O(1) lookup)
    if milestone_id in claimed_set:
        return False, None, "Mốc phần thưởng này đã nhận trước đó!"

    # 2. Đối soát điều kiện thời gian thực
    status = self.get_player_milestone_status(player_id)
    if milestone_id not in status["eligible_milestones"]:
        return False, None, "Chưa đạt điều kiện mốc hoàn thành nhiệm vụ!"

    # 3. Đánh dấu nguyên tử trước khi ghi có tài sản
    claimed_set.add(milestone_id)
    return True, milestone.reward, "Nhận phần thưởng mốc thành công!"
```

### 5.2. Chống Can Thiệp Tọa Độ & Điều Kiện Ẩn
- Khi kích hoạt nhiệm vụ ẩn qua thân pháp `EVASION_NEAR_DEATH`:
  - `hp_percent` được đọc trực tiếp từ [CombatActor.current_hp / max_hp](file:///c:/Projects/FreeExile/server/world/combat_engine.py).
  - Tọa độ `zone` được đối soát bởi [Spatial Grid Partitioning](file:///c:/Projects/FreeExile/server/world/spatial_grid.py).
  - Client không thể giả mạo lượng máu hay tọa độ bản đồ để kích hoạt nhiệm vụ ẩn.

---

## 6. HƯỚNG DẪN TÍCH HỢP & KIỂM THỬ (INTEGRATION & TESTING)

Toàn bộ logic đã được bao phủ bởi bộ kiểm thử tự động khép kín (TDD Closed-Loop):
- **Chạy kiểm thử unit test**:
  ```powershell
  pytest tests/unit/test_quest_engine.py -v
  ```
- **Khởi tạo Engine mặc định chuẩn chính quy**:
  ```python
  from server.world.quest_engine import create_default_quest_engine

  quest_engine = create_default_quest_engine()
  quest_engine.initialize_player("player_id_12345", player_level=1)
  ```