---
doc_id: "DOC-GDD-009"
title: "Đặc Tả Hệ Thống Bang Hội Gọn Nhẹ & Rương Chung 2PC"
category: "game_design"
diataxis_type: "reference"
status: "canonical"
version: "2026.1"
owner_role: "poe2_game_designer"
last_updated: "2026-09-29"
tags: ["guild-system", "shared-stash", "anti-dupe", "2pc", "lightweight-guild"]
related_code:
  - "server/guild/guild_service.py"
  - "server/guild/guild_stash_2pc.py"
related_docs:
  - "docs/adr/0003_lightweight_guild_vs_faction_territory_wars.md"
summary: "Thiết kế Bang hội tinh gọn (Guild Chat + Rương chia sẻ phân quyền), khóa 2PC chống dupe, không công thành chiếm đất."
---

# ĐẶC TẢ HỆ THỐNG BANG HỘI GỌN NHẸ & RƯƠNG CHUNG BANG HỘI (GUILD SYSTEM & SHARED STASH)
# DỰ ÁN FREEEXILE: DARK MARTIAL ASTRAL ARPG 2.5D
*(Copyright FreeExile Project 2026 - Chuẩn Diátaxis Reference & Architecture)*

> **Bộ phận phụ trách**: Trưởng Bộ Phận Thiết Kế Hệ Thống (`lead_systems_designer`), Kiến Trúc Sư Server (`server_systems_architect`), Giám Đốc An Ninh (`ciso_agent`).  
> **Mã nguồn triển khai**: [`server/trade/guild_stash_service.py`](file:///c:/Projects/FreeExile/server/trade/guild_stash_service.py)  
> **Độ bao phủ kiểm thử**: 100% Green ([`tests/unit/test_guild_stash_2pc.py`](file:///c:/Projects/FreeExile/tests/unit/test_guild_stash_2pc.py)).

---

## 1. TRIẾT LÝ THIẾT KẾ: KẾT NỐI XÃ HỘI TINH GỌN (LIGHTWEIGHT SOCIAL PHILOSOPHY)

Trong `FreeExile`, trải nghiệm cá nhân (khám phá thế giới mở, cày cuốc bí cảnh, tối ưu hóa build nhân vật) là trung tâm tuyệt đối. Vì vậy, hệ thống Bang Hội được thiết kế theo phong cách **tinh gọn, hướng tới tình bằng hữu và tương trợ**:

```
[TUYỆT ĐỐI KHÔNG CÔNG THÀNH CHIẾN / TRANH ĐOẠT LÃNH THỔ NGŨ HÀNH]
                               │
                               ▼
        ┌──────────────────────────────────────────────┐
        │       HỆ THỐNG BANG HỘI GỌN NHẸ 2026         │
        ├──────────────────────┬───────────────────────┤
        │ KÊNH CHAT BANG HỘI   │ RƯƠNG CHUNG BANG HỘI  │
        │ • Hỏi đáp bí cảnh    │ • Chia sẻ phôi đồ quý │
        │ • Chia sẻ cách build │ • Góp đan dược vượt ải│
        │ • Khoe đồ hiếm       │ • Phân quyền bảo mật  │
        └──────────────────────┴───────────────────────┘
```

1. **Tuyệt Đối Không Làm Loãng Gameplay ARPG**:
   - Không có hoạt động điểm danh bắt buộc, không có chiến tranh phe phái tranh giành thành trì gây áp lực thời gian cho người chơi.
2. **Tương Trợ Đồ Đạc Không Vụ Lợi**:
   - Người chơi cày được phôi kiếm hoặc đan dược không dùng tới có thể gửi vào Rương Bang để các thành viên khác lấy dùng, gia tăng tình đoàn kết.

---

## 2. PHÂN QUYỀN HẠN THÀNH VIÊN BANG HỘI (GUILD ROLE HIERARCHY)

Hệ thống thiết lập 3 cấp bậc rõ ràng qua `GuildRole`:

| Cấp Bậc | Quyền Hạn Kênh Chat | Quyền Hạn Tab Công Khai (`PUBLIC`) | Quyền Hạn Tab Trưởng Lão (`OFFICER_ONLY`) | Quyền Hạn Tab Đóng Góp (`DEPOSIT_ONLY`) |
| :--- | :--- | :--- | :--- | :--- |
| **Bang Chủ (`GUILD_MASTER`)** | Toàn quyền, ghim thông báo | Nạp & Rút | Nạp & Rút | Nạp & Rút |
| **Trưởng Lão (`OFFICER`)** | Chat, mời/kích thành viên | Nạp & Rút | Nạp & Rút | Nạp & Rút |
| **Thành Viên (`MEMBER`)** | Chat thông thường | Nạp & Rút | Chỉ Xem (Không Rút) | Chỉ Nạp Đóng Góp (Không Rút) |

---

## 3. CƠ CHẾ KHÓA HAI PHA (2PC) VÀ BẢO ĐẢM 0% DUPE ĐỒ

Mọi thao tác rút vật phẩm từ Rương Bang Hội được bảo vệ bằng thuật toán khóa hai pha nghiêm ngặt:

```mermaid
sequenceDiagram
    autonumber
    actor PlayerA as Thành Viên A
    actor PlayerB as Thành Viên B
    participant LockManager as Bộ Quản Lý Khóa Phân Tán (2PC Lock)
    participant StashService as GuildStashService
    participant AuditLog as Sổ Cái Nhật Ký Bất Biến

    Note over PlayerA,PlayerB: Cùng nhấn Rút 'Thanh Long Đao' tại cùng 1 tích tắc (Tick 30Hz)
    PlayerA->>StashService: withdraw_item(guild_id, tab_id, 'item_sword_01')
    PlayerB->>StashService: withdraw_item(guild_id, tab_id, 'item_sword_01')
    
    StashService->>LockManager: acquire_lock('item_sword_01', tx_A)
    LockManager-->>StashService: True (Cấp khóa thành công cho A)
    
    StashService->>LockManager: acquire_lock('item_sword_01', tx_B)
    LockManager-->>StashService: False (Vật phẩm đã bị khóa bởi tx_A)
    
    StashService-->>PlayerB: REJECTED: ITEM_LOCKED_CONCURRENT_TRANSACTION (Thất bại, không mất đồ)
    
    StashService->>StashService: Atomic Tab.items.pop('item_sword_01')
    StashService->>AuditLog: Ghi nhận log: [PlayerA] đã RÚT [Thanh Long Đao]
    StashService->>LockManager: release_lock('item_sword_01', tx_A)
    StashService-->>PlayerA: SUCCESS: Trao vật phẩm cho Player A
```

### Bảo Đảm Của Khối Bảo Mật:
1. **Triệt tiêu Race Condition**: Khi hai hoặc nhiều thành viên click rút cùng một vật phẩm tại cùng microsecond, chỉ đúng $1$ yêu cầu được cấp phát khóa, các yêu cầu còn lại bị hủy ngay lập tức mà không gây sai lệch dữ liệu.
2. **Nhật Ký Minh Bạch Không Thể Chối Cãi**: Toàn bộ thao tác nạp/rút đều ghi lại thời gian, ID người chơi, tên vật phẩm. Bang Chủ và Trưởng Lão có thể tra cứu lịch sử bất kỳ lúc nào để phát hiện thành viên lạm dụng rút đồ bừa bãi.

---

## 4. KÊNH CHAT BANG HỘI THỜI GIAN THỰC (REALTIME GUILD CHAT)

- **Giao Thức**: Sử dụng Redis Pub/Sub trên kênh `guild:{guild_id}`.
- **Tính Năng Độc Đáo**:
  - Hỗ trợ gửi thẻ vật phẩm tương tác: Người chơi có thể gõ cú pháp `[ItemLink: <item_id>]` trong khung chat bang, các thành viên khác nhấp vào thẻ này sẽ hiển thị bảng thông số đầy đủ (Prefix, Suffix, Item Level).
  - Tự động lưu trữ 100 tin nhắn gần nhất khi thành viên offline, giúp không bỏ lỡ các cuộc thảo luận quan trọng của anh em trong bang.
  - Bộ lọc chống spam tần suất: Tối đa 5 tin nhắn / 3 giây nhằm ngăn chặn các hành vi flood chat phá hoại.