---
doc_id: "DOC-OPS-002"
title: "Kiến Trúc Thanh Toán Đa Nền Tảng & Hắc Thị Hoang Vực (MegaShop)"
category: "operations"
diataxis_type: "explanation"
status: "canonical"
version: "2026.1"
owner_role: "server_systems_architect"
last_updated: "2026-09-29"
tags: ["payment", "megashop", "apple-storekit2", "web3-crypto", "anti-p2w"]
related_code:
  - "server/shop/shop_service.py"
  - "server/shop/payment_gateways.py"
related_docs:
  - "docs/game_design/ANTI_INFLATION_SAVAGE_ECONOMY_2026.md"
summary: "Tích hợp Apple StoreKit 2, Web3 Crypto Gateway (USDT/SOL/TON), chính sách 100% Non-Pay-to-Win (chỉ bán cosmetic & tiện ích rương)."
---

# HỆ THỐNG KIẾN TRÚC THANH TOÁN ĐA NỀN TẢNG & HẮC THỊ HOANG VỰC (SAVAGE MEGASHOP)
# DIÁTAXIS ARCHITECTURE & ENGINEERING SPECIFICATIONS 2026

> **Dự án**: FreeExile - Cổ Võ Hoang Dã & Hắc Ám Lưu Đày 2.5D (Grimdark Savage Primal Exile ARPG)  
> **Tài liệu chuẩn hóa**: Diátaxis Framework (Tutorials, How-To, Reference, ADR)  
> **Mã nguồn liên quan**:  
> - Schema Protobuf: [shop.proto](file:///c:/Projects/FreeExile/proto/shop.proto)  
> - Catalog Kho Hàng: [shop_catalog.py](file:///c:/Projects/FreeExile/server/shop/shop_catalog.py)  
> - Công Cụ Định Giá PPP & FX: [currency_exchange.py](file:///c:/Projects/FreeExile/server/shop/currency_exchange.py)  
> - Bộ Điều Hướng Cổng Tuân Thủ Nền Tảng: [payment_gateway_router.py](file:///c:/Projects/FreeExile/server/shop/payment_gateway_router.py)  
> - Trình Xác Thực Web3 Crypto & Receipt: [receipt_verifier.py](file:///c:/Projects/FreeExile/server/shop/receipt_verifier.py)  
> - Điều Phối Tổng Thể MegaShop: [shop_service.py](file:///c:/Projects/FreeExile/server/shop/shop_service.py)  
> - Kiểm Thử Tự Hành TDD: [test_shop_service.py](file:///c:/Projects/FreeExile/tests/unit/test_shop_service.py)

---

## 1. TUTORIAL: NHẬP MÔN TÍCH HỢP THANH TOÁN VÀO GAME CLIENT

Phần hướng dẫn từng bước giúp kỹ sư Client (iOS / Android / Web) tích hợp và gọi API MegaShop:

### Bước 1: Khởi tạo Yêu cầu Lấy Danh Mục Hàng Hóa (Get Catalog)
Client gửi thông tin thiết bị (`PlatformType`, `country_code`, `locale`):
```python
from shop.shop_service import MegaShopService
from shop.payment_gateway_router import PlatformType, PaymentGateway

service = MegaShopService()

# 1. Truy vấn sản phẩm theo danh mục (ví dụ danh mục COINS hoặc SKINS)
catalog_products = service.catalog.get_all_products()
for p in catalog_products:
    print(f"SKU: {p.product_id} | Name: {p.name_i18n_key} | USD: ${p.base_fiat_usd} | Coins: {p.coin_price}")
```

### Bước 2: Truy vấn Cổng Thanh Toán Được Phép Cho Thiết Bị
Hệ thống router tự động lọc cổng thanh toán an toàn, tránh vi phạm chính sách của Apple hoặc Google:
```python
# Thiết bị iPhone người dùng tại Mỹ
allowed_gateways = service.gateway_router.get_allowed_payment_methods(
    platform=PlatformType.PLATFORM_IOS,
    country_code="US"
)
# Kết quả: CHỈ DUY NHẤT GATEWAY_APPLE_IAP!

# Người dùng truy cập qua Web Direct Store tại Việt Nam
web_gateways = service.gateway_router.get_allowed_payment_methods(
    platform=PlatformType.PLATFORM_WEB_PC,
    country_code="VN"
)
# Kết quả: Bao gồm GATEWAY_CRYPTO_WEB3, GATEWAY_STRIPE, GATEWAY_LOCAL_VIETNAM (MoMo/VNPay)
```

### Bước 3: Khởi tạo Đơn Hàng & Xác Thực Biên Lai (Settlement)
```python
# Tạo đơn hàng mua gói 1000 Gold Cores trên iOS
order = service.create_purchase_order(
    account_id="player_001",
    product_id="coin_pack_1000",
    platform=PlatformType.PLATFORM_IOS,
    gateway=PaymentGateway.GATEWAY_APPLE_IAP,
    country_code="US"
)

# Sau khi Apple StoreKit thanh toán thành công, client gửi biên lai JWS về server
settle_result = service.settle_fiat_order(
    order_id=order.order_id,
    receipt_payload="valid_apple_jws_signed_transaction_token"
)
assert settle_result.success is True
print(f"Cộng thành công: {settle_result.coins_credited} Huyết Cổ Tệ!")
```

---

## 2. HOW-TO GUIDES: CÁC KỊCH BẢN THỰC THI THỰC TẾ

### How-To 1: Thêm Một Bảo Rương Gacha Mới Đảm Bảo 100% Xác Suất Minh Bạch
Mọi bảo rương thuộc `ProductCategory.CHESTS` bắt buộc cấu hình danh sách `ChestDropProbability` có tổng xác suất bằng đúng $100.0\%$:
```python
from shop.shop_catalog import ShopProduct, ProductCategory, ChestDropProbability

new_chest = ShopProduct(
    product_id="chest_trieu_hoan_than_thu",
    name_i18n_key="shop.chest.beast_summon.name",
    description_i18n_key="shop.chest.beast_summon.desc",
    category=ProductCategory.CHESTS,
    coin_price=300,
    badge_label="NEW",
    chest_drop_rates=[
        ChestDropProbability("pet_bach_ho_nhi", "pet.white_tiger_cub.name", rarity=1, drop_chance_percent=60.0),
        ChestDropProbability("pet_u_minh_lang", "pet.nether_wolf.name", rarity=2, drop_chance_percent=30.0),
        ChestDropProbability("pet_hac_ky_lan", "pet.black_qilin.name", rarity=3, drop_chance_percent=9.5),
        ChestDropProbability("pet_thai_co_than_long", "pet.primordial_dragon.name", rarity=3, drop_chance_percent=0.5, is_guaranteed_pity=True),
    ]
)
# Tổng: 60.0 + 30.0 + 9.5 + 0.5 = 100.0%
service.catalog.register_product(new_chest)
```

### How-To 2: Khởi Tạo Đơn Hàng Thanh Toán Bằng Crypto Web3
```python
from shop.receipt_verifier import CryptoChain, CryptoToken

order = service.create_purchase_order(
    account_id="player_whale",
    product_id="coin_pack_2500",
    platform=PlatformType.PLATFORM_WEB_PC,
    gateway=PaymentGateway.GATEWAY_CRYPTO_WEB3,
    country_code="VN",
    crypto_chain=CryptoChain.CHAIN_ARBITRUM,
    crypto_token=CryptoToken.TOKEN_USDT,
    buyer_wallet="0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7"
)

# Trả về thông tin cho Web3 Frontend để ký EIP-712 transaction
print(f"Địa chỉ nhận: {order.web3_details.merchant_vault_address}")
print(f"Số token cần chuyển: {order.web3_details.required_token_amount} USDT")
print(f"Hạn thanh toán: {order.web3_details.expires_at_ts} (Thời lượng 15 phút)")
```

---

## 3. REFERENCE: TRA CỨU THÔNG SỐ & MA TRẬN KỸ THUẬT

### 3.1. Bảng Ma Trận Tuân Thủ Cổng Thanh Toán Theo Nền Tảng (Store Compliance Matrix)
| Nền Tảng Client (`PlatformType`) | Cổng Cho Phép (`Allowed Gateways`) | Chính Sách Pháp Lý Áp Dụng | Mức Cắt Phế Nền Tảng | Ưu Đãi Coin Thưởng |
| :--- | :--- | :--- | :--- | :--- |
| **`PLATFORM_IOS`** | **Apple In-App Purchase (StoreKit 2)** | Apple Store Guideline 3.1.1 (Cấm tuyệt đối cổng ngoài) | 30% (hoặc 15% SMB) | 0% Bonus (Đúng giá niêm yết) |
| **`PLATFORM_ANDROID_PLAYSTORE`** | **Google Play Billing v6+** | Google Play Developer Policy (In-App Billing) | 30% (hoặc 15% Tier 1) | 0% Bonus (Đúng giá niêm yết) |
| **`PLATFORM_WEB_PC`** | **Web3 Crypto, Stripe, PayPal, Local QR** | Web Top-Up Direct Publisher Portal | ~0.5% - 2.5% | **+10% Bonus Huyết Cổ Tệ** |
| **`PLATFORM_ANDROID_SIDELOAD`**| **Web3 Crypto, Stripe, PayPal, Local QR** | Trực tiếp từ file APK nhà phát hành | ~0.5% - 2.5% | **+10% Bonus Huyết Cổ Tệ** |

### 3.2. Bảng Tỉ Giá Sức Mua Tương Đương (Purchasing Power Parity - PPP)
| Nhóm Thị Trường (Tier) | Quốc Gia Áp Dụng | Hệ Số PPP | Tỉ Giá Quy Đổi Fiat sang USD | Công Thức Tính Giá Bản Địa |
| :--- | :--- | :--- | :--- | :--- |
| **Tier 1 (Standard)** | US, JP, UK, DE, FR | **1.00** | $1\text{ USD} = 155\text{ JPY} = 0.92\text{ EUR}$ | $\text{Base USD} \times \text{FX} \times 1.00$ |
| **Tier 2 (Moderate)** | KR, SG, TW | **0.90** | $1\text{ USD} = 1.350\text{ KRW}$ | $\text{Base USD} \times \text{FX} \times 0.90$ |
| **Tier 3 (Emerging)** | VN, TH, ID, BR, PH | **0.50** | $1\text{ USD} = 25.000\text{ VND} = 36\text{ THB}$ | $\text{Base USD} \times \text{FX} \times 0.50$ |

---

## 4. EXPLANATION & ARCHITECTURAL DECISION RECORDS (ADR)

### ADR-001: Phân Lập Cổng Thanh Toán Nghiêm Ngặt Trên iOS (Guideline 3.1.1 Compliance)
- **Bối cảnh**: Apple kiểm duyệt cực kỳ gắt gao các ứng dụng trò chơi. Mọi ứng dụng có chứa nút thanh toán bên thứ ba, link nạp thẻ web bên ngoài, hoặc hiển thị địa chỉ ví Crypto trong binary iOS đều bị **từ chối phê duyệt ngay lập tức (Guideline 3.1.1 Rejection)**.
- **Quyết định**:
  - `PaymentGatewayRouter` hoạt động ở tầng máy chủ (Server-Authoritative). Khi nhận diện `PlatformType == PLATFORM_IOS`, server **chỉ trả về duy nhất danh sách chứa `GATEWAY_APPLE_IAP`**.
  - Nếu bất kỳ client iOS nào can thiệp mã nguồn để gửi request tạo đơn hàng Stripe hoặc Web3 Crypto, server ném lỗi ngoại lệ [`PlatformPolicyViolationError`](file:///c:/Projects/FreeExile/server/shop/payment_gateway_router.py) và từ chối xử lý.
- **Kết quả & Lợi ích**: Đảm bảo 100% tỷ lệ vượt qua kỳ kiểm duyệt khắt khe của Apple App Store Review Board.

### ADR-002: Động Lực Thúc Đẩy Nạp Web Portal & Thanh Toán Web3 Crypto
- **Bối cảnh**: Phí hoa hồng $30\%$ của Apple và Google làm giảm đáng kể biên lợi nhuận của Nhà Phát Hành.
- **Giải pháp**:
  - Không vi phạm điều khoản cấm "No Steering" trong app iOS (không quảng cáo link nạp web trong app).
  - Trên kênh Web Direct Store chính thức và các phiên bản APK trực tiếp, người chơi được hưởng chính sách **Tặng Thêm $+10\%$ Huyết Cổ Tệ**.
  - Tích hợp thanh toán Web3 Crypto với phí giao dịch cực thấp ($< 0.1\text{ USD}$ trên Arbitrum/Polygon/Solana), giải quyết bài toán nạp tiền xuyên biên giới cho cộng đồng game thủ quốc tế.

### ADR-003: Thuật Toán Xác Minh On-Chain & Chống Double-Spending Giao Dịch Web3
- **Quy trình luồng xử lý**:

```mermaid
sequenceDiagram
    autonumber
    actor Player as Người Chơi (Web3 Wallet)
    participant Web as Web Top-Up Portal
    participant Server as Game Shop Service
    participant Oracle as Pyth/Chainlink Oracle
    participant RPC as Blockchain RPC Node
    participant 2PC as Two-Phase Commit Ledger

    Player->>Web: Chọn gói SKU & Chọn mạng (Arbitrum/Polygon/Solana)
    Web->>Server: CreatePaymentOrder(account_id, product_id, chain, token)
    Server->>Oracle: Lấy giá thời gian thực (USD/Token)
    Oracle-->>Server: Real-time price feed
    Server-->>Web: Trả về order_id, merchant_vault, required_amount, valid_15m
    Player->>RPC: Ký giao dịch gửi Token tới Merchant Vault
    RPC-->>Player: Trả về tx_hash (Confirmed)
    Player->>Server: SettleCryptoOrder(order_id, tx_hash, chain)
    Server->>RPC: Kiểm tra xác nhận khối (confirmations >= 15)
    Server->>Server: Đối soát recipient_vault, token_contract, amount
    Server->>Server: Kiểm tra anti-double-spending trong UsedTxLedger
    Server->>2PC: Khóa và cộng Huyết Cổ Tệ (+10% Bonus) vào tài khoản
    2PC-->>Server: Giao dịch nguyên tử thành công
    Server-->>Player: Cấp phát hoàn tất, hiển thị số dư mới!
```

- **Cơ chế chống gian lận**:
  - Bộ nhớ `used_tx_hashes` lưu trữ bất biến các mã băm giao dịch đã thanh toán. Mọi yêu cầu tái sử dụng cùng một `tx_hash` sẽ bị ngắt mạch ngay lập tức (`Web3TransactionVerificationError: DOUBLE_SPENDING_DETECTED`).
  - Đơn vị tính tiền tệ được đồng bộ trực tiếp vào hệ thống Two-Phase Commit ([two_phase_commit.py](file:///c:/Projects/FreeExile/server/trade/two_phase_commit.py)), loại trừ 100% nguy cơ trùng lặp (Zero Item Duplication).