# ĐẶC TẢ THIẾT KẾ & VẬN HÀNH: HẮC THỊ HOANG VỰC (MEGASHOP) & HỆ THỐNG THANH TOÁN ĐA NỀN TẢNG
# DỰ ÁN FREEEXILE: CỔ VÕ HOANG DÃ & HẮC ÁM LƯU ĐÀY 2.5D (GRIMDARK SAVAGE PRIMAL EXILE ARPG)

> **Phòng ban phụ trách**: Ban Giám Đốc Sản Xuất (`studio_producer`), Kiến Trúc Sư Tài Liệu (`lead_documentation_architect`), Kỹ Sư Trưởng Hệ Thống Server (`server_systems_architect`), Trưởng Bộ Phận Bản Địa Hóa (`localization_lead`).  
> **Phiên bản tài liệu**: 1.0.0-RELEASE  
> **Áp dụng cho**: Toàn bộ máy chủ FreeExile, Client iOS (StoreKit 2), Android (Google Play), Web Direct Store & Cổng Thanh Toán Web3 Crypto.

---

## 1. TỔNG QUAN HỆ THỐNG HẮC THỊ HOANG VỰC (MEGASHOP OVERVIEW)

- **Định danh hệ thống**: `Hắc Thị Hoang Vực` (Tiếng Anh: `The Outcast Bazaar`, Tiếng Trung: `荒域黑市`).
- **Bản chất**: Kênh bán lẻ chính thức và trực tiếp duy nhất từ **Nhà Phát Hành (Publisher Direct Store)** đến người chơi, vận hành song song nhưng phân tách hoàn toàn độc lập với sàn giao dịch P2P giữa người chơi mang tên **Ký Gửi Hoang Vực (Consignment Vault)**.
- **Tiền tệ định giá trong cửa hàng**:
  - **Huyết Cổ Tệ (Outcast Blood Coins)**: Tiền tệ nạp (Hard Currency) độc quyền của hệ thống phát hành.
  - **Quy đổi cơ sở**: $\$1.00\text{ USD} = 100\text{ Huyết Cổ Tệ}$.
- **Triết lý Cổ Võ Hoang Dã - Chống Pay-To-Win (Fair Play Primal Philosophy)**:
  - Hắc Thị Hoang Vực **tuyệt đối không bán** các chỉ số lực chiến phá vỡ cân bằng, không bán điểm mở khóa Huyết Cốt Ma Đồ hay vũ khí có dòng chỉ số vượt trần.
  - Danh mục tập trung vào: **Tàn Binh & Chiến Giáp Ngoại Trang (Cosmetic Skins)**, **Vật Phẩm Tiện Ích Hoang Vực (Utility Items)**, **Cốt Hạp Bí Ẩn Minh Bạch (Transparent Bone Chests)**, **Chiến Lệnh Hoang Vực & Khế Ước (Battle Pass & Blessings)**.

---

## 2. NĂM DANH MỤC HÀNG HÓA CHÍNH (PRODUCT CATEGORIES)

```
[HẮC THỊ HOANG VỰC - THE OUTCAST BAZAAR]
┌────────────────────────────────────────────────────────────────────────┐
│ 1. HUYẾT CỔ TỆ (COIN PACKS)                                            │
│    - Gói 100, 500, 1.000, 2.500, 6.000, 13.000 Huyết Cổ Tệ             │
│    - Gói Tiếp Tế Lưu Đày: Giảm 50% lần đầu nạp (Giới hạn 1 lần)         │
├────────────────────────────────────────────────────────────────────────┤
│ 2. TÀN BINH CHIẾN GIÁP & CỔ CỐT HUNG THÚ (COSMETIC SKINS)              │
│    - Tàn Binh · Cổ Thú Huyết Đao (Đại đao răng cưa ghép xương hàm thú) │
│    - Chiến Giáp · Dạ Xoa Huyết Giáp (Giáp ngực da thú đính sừng gai nhọn)│
│    - Toạ Kỵ · Cổ Cốt Hung Thú (Dã thú nanh kiếm quấn xích sắt gai)    │
├────────────────────────────────────────────────────────────────────────┤
│ 3. VẬT PHẨM TIỆN ÍCH HOANG VỰC (UTILITY ITEMS)                         │
│    - Rương Bán Hàng Lưu Đày (Mở khóa Tab Bán Hàng Premium, 500 Coin)   │
│    - Cuộn Da Dịch Chuyển Hoang Vực (50 cuộn da thuộc khắc huyết ấn)    │
│    - Túi Da Cổ Thú (Mở rộng thêm 100 ô túi đồ cá nhân)                 │
│    - Huyết Tủy Hoán Cốt Trấp (Tẩy và hoàn trả điểm thể phách gân cốt)  │
├────────────────────────────────────────────────────────────────────────┤
│ 4. CỔ MAN CỐT HẠP & DI HẠP (TRANSPARENT MYSTERY CHESTS)                │
│    - Cổ Man Cốt Hạp & U Minh Di Hạp (Công khai 100% xác suất)          │
├────────────────────────────────────────────────────────────────────────┤
│ 5. CHIẾN LỆNH HOANG VỰC & KHẾ ƯỚC (BATTLE PASS & BLESSINGS)            │
│    - Khế Ước Lưu Đày (Nhận 100 Huyết Cổ Tệ mỗi ngày x 30 ngày)         │
│    - Chiến Lệnh Hoang Vực Mùa 1 (Battle Pass 100 cấp độ mở khóa Skin)  │
└────────────────────────────────────────────────────────────────────────┘
```

---

## 3. NGUYÊN TẮC MINH BẠCH BẢO RƯƠNG (LOOT BOX TRANSPARENCY GUARANTEE)

Nhằm bảo vệ quyền lợi người chơi và tuân thủ tuyệt đối quy định pháp lý quốc tế cũng như hướng dẫn của Apple App Store & Google Play:
1. **Công khai xác suất toàn diện (100% Disclosed Probability)**: Mọi cốt hạp bày bán trong Hắc Thị đều niêm yết rõ ràng bảng tỉ lệ rớt vật phẩm chính xác tới từng phần trăm ($0.01\%$) ngay tại giao diện xem trước.
2. **Cơ chế Bảo hiểm May mắn (Guaranteed Pity Counter)**:
   - Nếu người chơi mở liên tục $50$ rương không nhận được vật phẩm phẩm cấp Cực Phẩm (Rare), rương thứ $51$ kích hoạt bảo hiểm $100\%$ rớt tối thiểu $1$ dòng Cực Phẩm.
   - Nếu mở liên tục $100$ rương không nhận được Thần Vật Thoại (Unique/Huyết Ảnh Kính), rương thứ $101$ chắc chắn rơi $1$ Thần Vật Thoại.

### Bảng Tỉ Lệ Tiêu Chuẩn: Cổ Man Cốt Hạp (`chest_celestial_fortune`)
| Tên Vật Phẩm | Phẩm Cấp | Khóa Dịch | Tỉ Lệ Xuất Hiện (%) |
| :--- | :--- | :--- | :--- |
| **Mảnh Xương Cổ** | Phàm phẩm (Common) | `loot_manh_xuong_co` | **45.0%** |
| **Đá Lửa Hoang Vực** | Linh phẩm (Magic) | `loot_da_lua_hoang_da` | **30.0%** |
| **Huyết Hồn Thạch** | Cực phẩm (Rare) | `loot_huyet_hon_thach` | **20.0%** |
| **Cổ Cốt Ấn** | Cực phẩm (Rare) | `loot_co_cot_an` | **4.5%** |
| **Huyết Ảnh Cổ Kính** | Thần thoại (Unique) | `loot_huyet_anh_co_kinh` | **0.5% (Bảo hiểm Pity)** |
| **TỔNG XÁC SUẤT** | - | - | **100.0%** |

---

## 4. CHÍNH SÁCH THANH TOÁN ĐA NỀN TẢNG (PLATFORM PAYMENT COMPLIANCE)

Hệ thống FreeExile áp dụng kiến trúc **Authoritative Payment Gateway Router** nhằm giải quyết bài toán tuân thủ chính sách khắt khe của các chợ ứng dụng:

```mermaid
flowchart TD
    Client[Khách Hàng / Thiết Bị Client] --> GatewayRouter{Payment Gateway Router}
    
    GatewayRouter -->|Platform: iOS| AppleIAP[Chỉ duy nhất Apple In-App Purchase StoreKit 2]
    GatewayRouter -->|Platform: Android PlayStore| GooglePlay[Chỉ duy nhất Google Play Billing v6+]
    GatewayRouter -->|Platform: Web Direct / PC / APK| WebDirect[Cổng Đa Năng: Stripe, PayPal, Local QR, Web3 Crypto]
    
    AppleIAP --> Settle[Xác minh Biên Lai Server-Authoritative & Cấp phát 2PC]
    GooglePlay --> Settle
    WebDirect --> Settle
```

### 4.1. Nền tảng iOS (Apple App Store Guideline 3.1.1)
- **Quy tắc bất di bất dịch**: Trên các bản build phân phối qua Apple App Store, client **chỉ được phép tích hợp và hiển thị duy nhất cổng thanh toán Apple In-App Purchase (StoreKit 2)**.
- **Nghiêm cấm tuyệt đối**: Cấm hiển thị nút thanh toán bên thứ ba, cấm đặt link dẫn ra web nạp ngoài, cấm hiển thị địa chỉ ví Crypto trong giao diện ứng dụng iOS. Mọi hành vi vi phạm sẽ bị Apple từ chối duyệt (App Review Rejection) hoặc gỡ bỏ ứng dụng.
- **Xác thực biên lai**: Máy chủ xác thực chữ ký mã hóa `SignedTransaction JWS` trực tiếp qua Apple App Store Server API v2.

### 4.2. Nền tảng Android (Google Play Store)
- Bản build Google Play chính thức sử dụng thư viện **Google Play Billing v6/v7**.
- Đối với các quốc gia triển khai User Choice Billing (UCB), hệ thống hỗ trợ tích hợp luồng UCB theo chỉ định của Google Developer Console.

### 4.3. Nền tảng Web Direct Store & Bản Cài Sideload (APK / PC / Mac)
- Không chịu chiết khấu $30\%$ của Apple/Google.
- Cho phép mở toàn diện các phương thức:
  - Thẻ Quốc Tế (Stripe Visa/Mastercard).
  - PayPal Global.
  - Cổng Thanh Toán Địa Phương (MoMo, VNPay, Chuyển Khoản Ngân Hàng QR tại Việt Nam).
  - **Thanh toán Crypto Web3 (MetaMask, Phantom, WalletConnect)**.

---

## 5. TỈ GIÁ HỐI ĐOÁI & SỨC MUA TƯƠNG ĐƯƠNG (PPP PRICING MATRIX)

Nhằm đảm bảo tính công bằng toàn cầu và hỗ trợ người chơi ở các thị trường mới nổi tiếp cận game một cách tự nhiên, FreeExile áp dụng ma trận định giá theo **Chỉ số Sức mua tương đương (Purchasing Power Parity - PPP)**:

| Phân Vùng Sức Mua | Quốc Gia Tiêu Biểu | Hệ Số PPP | Ví Dụ Gói Gốc \$10.00 USD | Đồng Tiền Hiển Thị |
| :--- | :--- | :--- | :--- | :--- |
| **Tier 1 (Tiêu chuẩn)** | Mỹ (US), Nhật Bản (JP), Anh (GB), Đức (DE) | **1.00** | \$9.99 USD (~1.550 JPY / 9.20 EUR) | USD, JPY, EUR, GBP |
| **Tier 2 (Trung bình)** | Hàn Quốc (KR), Singapore (SG), Đài Loan (TW) | **0.90** | ~12.000 KRW / \$9.00 SGD | KRW, SGD, TWD |
| **Tier 3 (Mới nổi)** | Việt Nam (VN), Thái Lan (TH), Brazil (BR) | **0.50** | **125.000 VND** (~180 THB / 27.5 BRL) | VND, THB, BRL |

### Chính Sách Ưu Đãi Nạp Web & Crypto (+10% Bonus)
- Do các kênh Web Direct và Web3 Crypto không chịu mức thuế nền tảng $30\%$, FreeExile tri ân trực tiếp cho người chơi bằng chính sách **Tặng Thêm $+10\%$ Huyết Cổ Tệ**:
  - Gói \$9.99 USD trên iOS: Nhận đúng $1.000$ Huyết Cổ Tệ.
  - Gói \$9.99 USD trên Web Direct / Crypto: Nhận ngay **$1.100$ Huyết Cổ Tệ** ($1.000 + 100$ Bonus).

### Lá Chắn Chống Gian Lận Chuyển Vùng (Anti-Region Hopping Shield)
- Máy chủ tự động kiểm tra đối chiếu: `Quốc gia của địa chỉ IP kết nối` so với `Quốc gia phát hành phương thức thanh toán`.
- Nếu phát hiện người chơi dùng VPN vùng Tier 1 để mua với giá trợ cấp Tier 3, giao dịch sẽ bị từ chối với mã lỗi `REGION_MISMATCH`.

---

## 6. THANH TOÁN BẰNG CRYPTO QUA VÍ WEB3 (WEB3 CRYPTO ENGINE)

FreeExile tích hợp giải pháp thanh toán Web3 không lưu ký (Non-Custodial) tiên tiến nhất:

### 6.1. Chuỗi Khối & Loại Token Hỗ Trợ
- **EVM Chains**: Arbitrum One, Polygon PoS, Ethereum Mainnet, BNB Chain.
- **Solana**: Solana Mainnet-Beta.
- **Tài sản thanh toán**:
  - Stablecoins chuẩn: **USDT** (Tether), **USDC** (Circle) — Tỉ giá neo chuẩn $1.00\text{ USD}$.
  - Native Tokens: **ETH** (Ethereum), **SOL** (Solana) — Tỉ giá biến động cập nhật liên tục qua Oracle.

### 6.2. Cơ Chế Định Giá Bằng Oracle Thời Gian Thực (Pyth / Chainlink)
- Giá quy đổi Crypto được chốt tại thời điểm người chơi khởi tạo đơn hàng:
  $$\text{Số lượng Token} = \frac{\text{Giá trị Đơn Hàng (USD)}}{\text{Giá Oracle của Token (USD)}}$$
- Đơn hàng có hiệu lực cố định trong vòng **15 phút** (`validity_seconds = 900`). Nếu quá 15 phút người chơi chưa chuyển tiền, đơn hàng tự động hủy để tránh rủi ro biến động giá token.

### 6.3. Quy Trình Xác Thực On-Chain & Chống Chi Tiêu Kép (Anti-Double-Spending)
1. Người chơi kết nối ví Web3 (MetaMask / Phantom), ký và gửi transaction chuyển Token tới địa chỉ **FreeExile Merchant Vault**.
2. Client gửi `tx_hash` (mã giao dịch) lên Game Server.
3. Server On-Chain Verifier truy vấn trực tiếp RPC Node:
   - Kiểm tra trạng thái giao dịch: Phải đạt trạng thái `confirmed` / `finalized` (tối thiểu 15-20 block confirmations).
   - Kiểm tra địa chỉ ví đích: Phải trùng khớp chính xác `merchant_vault_address`.
   - Kiểm tra địa chỉ smart contract token: Phải đúng hợp đồng USDT/USDC chính thức của chuỗi đó.
   - Kiểm tra số tiền: Phải lớn hơn hoặc bằng số tiền yêu cầu.
   - **Chống gian lận Double-Spending**: Mỗi `tx_hash` duy nhất sau khi xử lý thành công sẽ được ghi vĩnh viễn vào bảng phân tán Redis/DB với distributed lock. Bất kỳ nỗ lực tái sử dụng `tx_hash` nào sẽ bị từ chối ngay lập tức với lỗi `DOUBLE_SPENDING_DETECTED`.
4. Cấp phát Huyết Cổ Tệ hoặc vật phẩm tức thời thông qua giao thức **Two-Phase Commit (2PC)** bất biến.