pos-system/services/mining-service-net/docs/vi/README.md

Mining Service .NET

Dịch vụ quản lý Mining Point với cơ chế lấy cảm hứng từ Pi Network cho GoodGo Platform.

Tổng Quan

Mining Service cung cấp hệ thống đào điểm thưởng game hóa lấy cảm hứng từ Pi Network, cho phép người dùng tích lũy Mining Points (MP) thông qua hoạt động hàng ngày, giới thiệu bạn bè và xây dựng cộng đồng.

Tính Năng Chính

Tính Năng	Mô Tả
Đào Hàng Ngày	Cơ chế tap-to-mine - người dùng kích hoạt phiên đào hàng ngày
Tỷ Lệ Đào	Tỷ lệ cơ bản tăng thông qua giới thiệu và xây dựng vòng tròn
🔥 Thưởng Streak	Phần thưởng đào liên tục hàng ngày kiểu TikTok
Vòng Tròn An Toàn	Nhóm tin cậy giúp tăng tỷ lệ đào và bảo mật mạng
Hệ Thống Giới Thiệu	Thưởng giới thiệu đa cấp cho sự phát triển mạng lưới
Vai Trò Người Dùng	Các cấp Pioneer, Contributor, Ambassador, Node Operator
Chuyển Đổi Điểm	Chuyển đổi Mining Points thành điểm thưởng nền tảng

---

Thiết Kế Kiến Trúc

Kiến Trúc Hệ Thống

┌─────────────────────────────────────────────────────────────────────┐
│                         API Gateway (Traefik)                        │
└────────────────────────────────────┬────────────────────────────────┘
                                     │
┌────────────────────────────────────▼────────────────────────────────┐
│                     Mining Service .NET                              │
├─────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │   Mining    │  │   Circle    │  │  Referral   │  │    Rate     │ │
│  │   Session   │  │   Manager   │  │   Tracker   │  │  Calculator │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘ │
├─────────────────────────────────────────────────────────────────────┤
│                         Domain Layer                                 │
│  ┌─────────────────────┐  ┌─────────────────────┐                   │
│  │   MinerAggregate    │  │  CircleAggregate    │                   │
│  │   - MiningSession   │  │  - CircleMember     │                   │
│  │   - MiningHistory   │  │  - TrustLevel       │                   │
│  │   - MiningRate      │  │  - CircleBonus      │                   │
│  └─────────────────────┘  └─────────────────────┘                   │
├─────────────────────────────────────────────────────────────────────┤
│                     Infrastructure Layer                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
│  │  PostgreSQL  │  │    Redis     │  │  RabbitMQ    │               │
│  │   (EF Core)  │  │   (Cache)    │  │  (Events)    │               │
│  └──────────────┘  └──────────────┘  └──────────────┘               │
└─────────────────────────────────────────────────────────────────────┘
                                 │
        ┌────────────────────────┼────────────────────────┐
        ▼                        ▼                        ▼
┌───────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  IAM Service  │      │ Wallet Service  │      │ Social Service  │
│  (Auth/Users) │      │ (Chuyển Điểm)   │      │   (Bạn Bè)      │
└───────────────┘      └─────────────────┘      └─────────────────┘

Cấu Trúc Clean Architecture

mining-service-net/
├── src/
│   ├── MiningService.API/              # Tầng API
│   │   ├── Controllers/
│   │   │   ├── MiningController.cs     # APIs phiên đào
│   │   │   ├── CirclesController.cs    # APIs vòng tròn an toàn
│   │   │   └── ReferralsController.cs  # APIs giới thiệu
│   │   └── Application/
│   │       ├── Commands/               # Thao tác ghi
│   │       └── Queries/                # Thao tác đọc
│   │
│   ├── MiningService.Domain/           # Tầng Domain
│   │   ├── AggregatesModel/
│   │   │   ├── MinerAggregate/         # Hồ sơ đào của người dùng
│   │   │   ├── CircleAggregate/        # Vòng tròn an toàn
│   │   │   └── ReferralAggregate/      # Theo dõi giới thiệu
│   │   ├── Events/                     # Domain events
│   │   ├── Exceptions/                 # Domain exceptions
│   │   └── Services/                   # Domain services
│   │
│   └── MiningService.Infrastructure/   # Tầng Infrastructure
│       ├── EntityConfigurations/       # EF Core mappings
│       ├── Repositories/               # Truy cập dữ liệu
│       └── MiningServiceContext.cs     # DbContext
│
├── tests/
│   ├── MiningService.UnitTests/
│   └── MiningService.FunctionalTests/
│
├── docs/
│   ├── en/
│   └── vi/
│
└── Dockerfile

---

Domain Model

Core Aggregates

1. Miner Aggregate (Hồ Sơ Đào Của Người Dùng)

┌────────────────────────────────────────────────────────────────────┐
│                          Miner (Entity)                             │
├────────────────────────────────────────────────────────────────────┤
│ Thuộc Tính:                                                         │
│   - Id: Guid                                                        │
│   - UserId: Guid (từ IAM Service)                                  │
│   - Role: MinerRole (Pioneer/Contributor/Ambassador/NodeOperator)  │
│   - TotalMinedPoints: decimal                                       │
│   - CurrentMiningRate: MiningRate (Value Object)                   │
│   - CurrentSession: MiningSession?                                  │
│   - SecurityCircle: Circle?                                         │
│   - ReferralCode: string                                            │
│   - ReferredBy: Guid?                                               │
│   - Status: MinerStatus (Active/Suspended/Banned)                  │
│   - CreatedAt: DateTime                                             │
├────────────────────────────────────────────────────────────────────┤
│ Hành Vi:                                                            │
│   - StartMiningSession() → MiningSession                           │
│   - ClaimMiningReward() → MiningPoints                             │
│   - UpgradeRole(role) → void                                        │
│   - JoinCircle(circle) → void                                       │
│   - RecalculateMiningRate() → MiningRate                           │
└────────────────────────────────────────────────────────────────────┘

2. Circle Aggregate (Vòng Tròn An Toàn)

┌────────────────────────────────────────────────────────────────────┐
│                          Circle (Entity)                            │
├────────────────────────────────────────────────────────────────────┤
│ Thuộc Tính:                                                         │
│   - Id: Guid                                                        │
│   - OwnerId: Guid (Miner tạo vòng tròn)                            │
│   - Members: List<CircleMember> (tối đa 5)                         │
│   - Name: string                                                    │
│   - TrustScore: decimal (0-100)                                    │
│   - BonusMultiplier: decimal                                        │
│   - Status: CircleStatus (Active/Incomplete/Disbanded)             │
│   - CreatedAt: DateTime                                             │
├────────────────────────────────────────────────────────────────────┤
│ Hành Vi:                                                            │
│   - AddMember(miner) → void                                         │
│   - RemoveMember(minerId) → void                                    │
│   - CalculateTrustScore() → decimal                                 │
│   - CalculateBonusMultiplier() → decimal                           │
│   - Validate() → bool (tối thiểu 3 thành viên)                     │
└────────────────────────────────────────────────────────────────────┘

3. Referral Aggregate (Giới Thiệu)

┌────────────────────────────────────────────────────────────────────┐
│                        Referral (Entity)                            │
├────────────────────────────────────────────────────────────────────┤
│ Thuộc Tính:                                                         │
│   - Id: Guid                                                        │
│   - ReferrerId: Guid (người mời)                                   │
│   - ReferredId: Guid (người được mời)                              │
│   - ReferralCode: string                                            │
│   - BonusRate: decimal                                              │
│   - IsActive: bool                                                  │
│   - Level: int (1 = trực tiếp, 2 = gián tiếp)                      │
│   - CreatedAt: DateTime                                             │
├────────────────────────────────────────────────────────────────────┤
│ Hành Vi:                                                            │
│   - Activate() → void                                               │
│   - Deactivate() → void                                             │
│   - CalculateBonus(baseRate) → decimal                             │
└────────────────────────────────────────────────────────────────────┘

Value Objects

/// Tính toán tỷ lệ đào
public record MiningRate(
    decimal BaseRate,           // Mặc định: 0.25 MP/giờ
    decimal CircleBonus,        // +0.25x cho vòng tròn hợp lệ
    decimal ReferralBonus,      // +25% mỗi giới thiệu hoạt động
    decimal RoleBonus,          // Dựa trên cấp vai trò
    decimal TotalRate           // Tỷ lệ tổng hợp
);

/// Theo dõi phiên đào
public record MiningSession(
    Guid SessionId,
    DateTime StartTime,
    DateTime EndTime,           // StartTime + 24 giờ
    decimal AccumulatedPoints,
    MiningSessionStatus Status  // Active/Completed/Expired
);

/// Mining Points
public record MiningPoints(
    decimal Amount,
    DateTime EarnedAt,
    string Source               // Mining/Referral/CircleBonus/RoleBonus
);

---

Cơ Chế Đào

🔥 Hệ Thống Thưởng Streak (Kiểu TikTok)

Đào liên tục hàng ngày thưởng cho người dùng với bonus tăng dần:

%%{init: {'theme':'dark'}}%%
flowchart LR
    subgraph Streak["🔥 Các Cấp Streak"]
        D1["Ngày 1-2<br/>+0%"] --> D3["Ngày 3-6<br/>+10%"]
        D3 --> D7["Ngày 7-13<br/>+25%"]
        D7 --> D14["Ngày 14-29<br/>+50%"]
        D14 --> D30["Ngày 30+<br/>+100%"]
    end
    
    style D1 fill:#7F8C8D,color:#ECF0F1,stroke:#5D6D7E,stroke-width:2px
    style D3 fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
    style D7 fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style D14 fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
    style D30 fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:3px

Cơ Chế Streak

Số Ngày Streak	Bonus	Phần Thưởng Mốc
Ngày 1-2	+0%	-
Ngày 3-6	+10%	🎁 Huy hiệu 3 ngày
Ngày 7-13	+25%	🎁 Huy hiệu 7 ngày + 50 MP thưởng
Ngày 14-29	+50%	🎁 Huy hiệu 14 ngày + 100 MP thưởng
Ngày 30-59	+100%	🔥 Huy hiệu 30 ngày + 300 MP thưởng
Ngày 60-89	+125%	🏆 Huy hiệu 60 ngày + 500 MP thưởng
Ngày 90+	+150%	👑 Huy hiệu 90 ngày + 1000 MP thưởng

Quy Tắc Bảo Vệ Streak

• Thời Gian Ân Hạn: Bỏ lỡ 1 ngày → streak tạm dừng (không reset)
• Đóng Băng Streak: Dùng 1 Token Đóng Băng để bảo vệ streak (nhận 1 token mỗi 7 ngày streak)
• Khôi Phục Streak: Trong 24h sau khi bỏ lỡ → trả 50 MP để khôi phục streak
• Streak Tối Đa: Không giới hạn (hiển thị trên bảng xếp hạng)

Streak Value Object

/// Theo dõi streak cho việc đào liên tục
public record MiningStreak(
    int CurrentStreak,          // Số ngày liên tục hiện tại
    int LongestStreak,          // Kỷ lục cá nhân
    DateTime LastMiningDate,    // Ngày nhận thưởng cuối cùng
    int FreezeTokens,           // Số token bảo vệ khả dụng
    bool IsGracePeriod,         // Đang trong thời gian ân hạn
    decimal BonusMultiplier     // Bonus streak hiện tại
);

---

Công Thức Tỷ Lệ Đào

Tỷ Lệ Đào Tổng = Tỷ Lệ Cơ Bản × (1 + Vai Trò) × (1 + Vòng Tròn) × (1 + Giới Thiệu) × (1 + Streak)

Trong đó:
- Tỷ Lệ Cơ Bản: 0.25 MP/giờ (có thể cấu hình)
- Hệ Số Vai Trò: Pioneer=0%, Contributor=10%, Ambassador=25%, Node=50%
- Thưởng Vòng Tròn: 25% nếu vòng tròn hợp lệ (3-5 thành viên tin cậy)
- Thưởng Giới Thiệu: 25% mỗi giới thiệu trực tiếp hoạt động (giới hạn 100%)
- Thưởng Streak: 0-150% dựa trên số ngày đào liên tục

Ví Dụ Với Streak:

Thành Phần	Giá Trị	Hệ Số
Tỷ Lệ Cơ Bản	0.25 MP/giờ	-
Vai Trò (Ambassador)	+25%	× 1.25
Vòng Tròn Hợp Lệ	+25%	× 1.25
2 Giới Thiệu	+50%	× 1.50
Streak 30 Ngày	+100%	× 2.00
Tổng	1.17 MP/giờ	28.12 MP/ngày

Luồng Phiên Đào

%%{init: {'theme':'dark'}}%%
sequenceDiagram
    participant U as 📱 Người Dùng
    participant A as 🌐 Mining API
    participant M as ⚙️ MinerAggregate
    participant R as 🧮 RateCalculator
    participant DB as 💾 PostgreSQL
    participant C as ⚡ Redis Cache

    U->>A: POST /api/v1/mining/start
    A->>M: StartMiningSession()
    M->>R: CalculateMiningRate()
    R-->>M: MiningRate
    M->>M: CreateSession(24 giờ)
    M->>DB: SaveSession()
    M->>C: CacheSessionInfo()
    A-->>U: 200 OK { session_id, rate, end_time }
    
    Note over U: 24 giờ sau...
    
    U->>A: POST /api/v1/mining/claim
    A->>M: ClaimMiningReward()
    M->>M: CalculateEarnedPoints()
    M->>M: AddToTotalPoints()
    M->>DB: SaveMiningHistory()
    A-->>U: 200 OK { earned_points, total_points }

Vai Trò & Quyền Lợi Người Dùng

Vai Trò	Yêu Cầu	Thưởng Đào	Quyền Lợi
Pioneer	Đăng ký	0%	Đào cơ bản
Contributor	Vòng tròn an toàn hợp lệ (3+ thành viên)	+10%	Thưởng vòng tròn hoạt động
Ambassador	5+ giới thiệu hoạt động	+25%	Tăng giới hạn thưởng giới thiệu
Node Operator	Chạy phần mềm node (tương lai)	+50%	Thưởng mạng

---

API Endpoints

APIs Đào

Phương Thức	Endpoint	Mô Tả
GET	/api/v1/mining/me	Lấy trạng thái đào hiện tại
POST	/api/v1/mining/start	Bắt đầu phiên đào 24 giờ
POST	/api/v1/mining/claim	Nhận thưởng đào
GET	/api/v1/mining/history	Lấy lịch sử đào
GET	/api/v1/mining/rate	Lấy chi tiết tỷ lệ đào
GET	/api/v1/mining/leaderboard	Lấy bảng xếp hạng thợ đào hàng đầu

APIs Vòng Tròn An Toàn

Phương Thức	Endpoint	Mô Tả
GET	/api/v1/circles/me	Lấy vòng tròn an toàn của tôi
POST	/api/v1/circles	Tạo vòng tròn an toàn
POST	/api/v1/circles/invite	Mời thành viên vào vòng tròn
POST	/api/v1/circles/accept/{inviteId}	Chấp nhận lời mời vòng tròn
DELETE	/api/v1/circles/members/{memberId}	Xóa thành viên vòng tròn
GET	/api/v1/circles/trust-score	Lấy điểm tin cậy vòng tròn

APIs Giới Thiệu

Phương Thức	Endpoint	Mô Tả
GET	/api/v1/referrals/code	Lấy mã giới thiệu của tôi
GET	/api/v1/referrals	Danh sách giới thiệu của tôi
GET	/api/v1/referrals/stats	Lấy thống kê giới thiệu
POST	/api/v1/referrals/apply	Áp dụng mã giới thiệu (khi đăng ký)

APIs Admin Backoffice

🔧 Quản Lý Cấu Hình

Phương Thức	Endpoint	Mô Tả
GET	/api/v1/admin/config	Lấy toàn bộ cấu hình hệ thống
PUT	/api/v1/admin/config	Cập nhật cấu hình hệ thống
GET	/api/v1/admin/config/mining	Lấy cấu hình đào
PUT	/api/v1/admin/config/mining	Cập nhật tỷ lệ đào
GET	/api/v1/admin/config/streak	Lấy cấu hình streak
PUT	/api/v1/admin/config/streak	Cập nhật thưởng streak
GET	/api/v1/admin/config/referral	Lấy cấu hình giới thiệu
PUT	/api/v1/admin/config/referral	Cập nhật thưởng giới thiệu

👥 Quản Lý Người Dùng

Phương Thức	Endpoint	Mô Tả
GET	/api/v1/admin/miners	Danh sách tất cả thợ đào (phân trang)
GET	/api/v1/admin/miners/{id}	Lấy chi tiết thợ đào
PUT	/api/v1/admin/miners/{id}/suspend	Tạm ngừng thợ đào
PUT	/api/v1/admin/miners/{id}/ban	Cấm thợ đào
PUT	/api/v1/admin/miners/{id}/restore	Khôi phục thợ đào bị tạm ngừng
PUT	/api/v1/admin/miners/{id}/adjust-points	Điều chỉnh điểm thợ đào
PUT	/api/v1/admin/miners/{id}/reset-streak	Reset streak thợ đào

📊 Phân Tích & Báo Cáo

Phương Thức	Endpoint	Mô Tả
GET	/api/v1/admin/analytics/overview	Thống kê tổng quan dashboard
GET	/api/v1/admin/analytics/miners	Thống kê thợ đào
GET	/api/v1/admin/analytics/circles	Thống kê vòng tròn an toàn
GET	/api/v1/admin/analytics/referrals	Thống kê mạng lưới giới thiệu
GET	/api/v1/admin/analytics/points	Thống kê điểm số
GET	/api/v1/admin/analytics/streaks	Phân bố streak
GET	/api/v1/admin/audit-logs	Xem nhật ký thay đổi cấu hình

---

Admin Configuration Entity

MiningConfiguration Aggregate

%%{init: {'theme':'dark'}}%%
classDiagram
    class MiningConfiguration {
        +Guid Id
        +decimal BaseRate
        +int SessionDurationHours
        +bool IsGloballyEnabled
        +DateTime UpdatedAt
        +Guid UpdatedBy
    }
    
    class StreakConfiguration {
        +Guid Id
        +List~StreakTier~ Tiers
        +bool GracePeriodEnabled
        +int GracePeriodHours
        +decimal RecoveryCost
        +int FreezeTokenDays
    }
    
    class StreakTier {
        +int MinDays
        +int MaxDays
        +decimal BonusPercent
        +string BadgeName
        +decimal MilestoneMpBonus
    }
    
    class ReferralConfiguration {
        +Guid Id
        +decimal BonusPercentPerReferral
        +decimal MaxBonusPercent
        +bool KycRequired
        +int MaxReferralLevels
    }
    
    class CircleConfiguration {
        +Guid Id
        +int MinMembers
        +int MaxMembers
        +decimal ValidCircleBonus
    }
    
    MiningConfiguration --> StreakConfiguration
    MiningConfiguration --> ReferralConfiguration
    MiningConfiguration --> CircleConfiguration
    StreakConfiguration --> "*" StreakTier

Configuration Value Objects

/// Cấu hình đào toàn hệ thống (admin có thể chỉnh sửa)
public record MiningConfig(
    decimal BaseRate,              // Mặc định: 0.25 MP/giờ
    int SessionDurationHours,      // Mặc định: 24
    bool IsGloballyEnabled         // Công tắc khẩn cấp
);

/// Cấu hình các cấp streak (admin có thể chỉnh sửa)
public record StreakConfig(
    List<StreakTierConfig> Tiers,
    bool GracePeriodEnabled,       // Mặc định: true
    int GracePeriodHours,          // Mặc định: 24
    decimal RecoveryCostMp,        // Mặc định: 50
    int FreezeTokenEarnDays        // Mặc định: 7
);

public record StreakTierConfig(
    int MinDays,
    int MaxDays,
    decimal BonusPercent,
    string BadgeName,
    decimal MilestoneMpBonus
);

/// Cấu hình giới thiệu (admin có thể chỉnh sửa)
public record ReferralConfig(
    decimal BonusPercentPerReferral, // Mặc định: 25%
    decimal MaxBonusPercent,         // Mặc định: 100%
    bool KycRequired,                // Mặc định: true
    int MaxReferralLevels            // Mặc định: 1
);

/// Cấu hình vòng tròn (admin có thể chỉnh sửa)
public record CircleConfig(
    int MinMembers,                // Mặc định: 3
    int MaxMembers,                // Mặc định: 5
    decimal ValidCircleBonus       // Mặc định: 25%
);

Luồng Cấu Hình Admin

%%{init: {'theme':'dark'}}%%
sequenceDiagram
    participant Admin as 🔐 Admin Backoffice
    participant API as 🌐 Mining API
    participant Config as ⚙️ ConfigService
    participant Cache as ⚡ Redis
    participant DB as 💾 PostgreSQL
    participant MQ as 📨 RabbitMQ
    
    Admin->>API: PUT /api/v1/admin/config/streak
    API->>Config: UpdateStreakConfig(newConfig)
    Config->>DB: SaveConfiguration()
    Config->>Cache: InvalidateConfigCache()
    Config->>MQ: Publish ConfigUpdatedEvent
    Config->>DB: SaveAuditLog(adminId, changes)
    API-->>Admin: 200 OK { updated_config }
    
    Note over Cache: Tất cả thợ đào sẽ dùng<br/>cấu hình mới khi claim tiếp

Giá Trị Cấu Hình Mặc Định

Danh Mục	Tham Số	Mặc Định	Mô Tả
Đào	Tỷ Lệ Cơ Bản	0.25 MP/giờ	Điểm kiếm được mỗi giờ
Đào	Thời Gian Phiên	24 giờ	Độ dài phiên đào
Đào	Bật Toàn Cục	true	Công tắc khẩn cấp
Streak	Thưởng Ngày 3-6	10%	Thưởng streak sớm
Streak	Thưởng Ngày 7-13	25%	Thưởng streak tuần
Streak	Thưởng Ngày 14-29	50%	Thưởng streak 2 tuần
Streak	Thưởng Ngày 30-59	100%	Thưởng streak tháng
Streak	Thưởng Ngày 60-89	125%	Thưởng streak 2 tháng
Streak	Thưởng Ngày 90+	150%	Thưởng streak tối đa
Streak	Thời Gian Ân Hạn	24 giờ	Thời gian trước khi mất streak
Streak	Chi Phí Khôi Phục	50 MP	Chi phí để khôi phục streak
Streak	Ngày Nhận Token	7	Số ngày để nhận freeze token
Giới Thiệu	Thưởng Mỗi Giới Thiệu	25%	Tăng tỷ lệ mỗi giới thiệu
Giới Thiệu	Thưởng Tối Đa	100%	Thưởng giới thiệu tối đa
Giới Thiệu	Yêu Cầu KYC	true	Yêu cầu KYC cho thưởng
Vòng Tròn	Thành Viên Tối Thiểu	3	Tối thiểu cho vòng tròn hợp lệ
Vòng Tròn	Thành Viên Tối Đa	5	Kích thước vòng tròn tối đa
Vòng Tròn	Thưởng Vòng Tròn Hợp Lệ	25%	Thưởng cho vòng tròn hợp lệ

Nhật Ký Kiểm Toán

Tất cả thay đổi cấu hình admin đều được ghi nhật ký:

public record ConfigAuditLog(
    Guid Id,
    Guid AdminUserId,
    string ConfigType,          // "Mining" | "Streak" | "Referral" | "Circle"
    string PreviousValue,       // JSON của cấu hình cũ
    string NewValue,            // JSON của cấu hình mới
    string Reason,              // Lý do admin thay đổi
    DateTime CreatedAt,
    string IpAddress
);

---

Điểm Tích Hợp

Phụ Thuộc Dịch Vụ

┌─────────────────────────────────────────────────────────────────────┐
│                        Mining Service                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────┐     Xác Thực           ┌──────────────────────┐  │
│  │              │◄────────────────────────│    IAM Service       │  │
│  │              │                         │  - Xác thực user     │  │
│  │              │                         │  - JWT tokens        │  │
│  │              │                         └──────────────────────┘  │
│  │              │                                                   │
│  │   Mining     │     Chuyển Đổi Điểm    ┌──────────────────────┐  │
│  │   Service    │────────────────────────►│   Wallet Service    │  │
│  │              │                         │  - Chuyển MP sang LP │  │
│  │              │                         │  - Giao dịch         │  │
│  │              │                         └──────────────────────┘  │
│  │              │                                                   │
│  │              │     Đồ Thị Xã Hội      ┌──────────────────────┐  │
│  │              │◄───────────────────────►│   Social Service    │  │
│  │              │                         │  - Danh sách bạn bè  │  │
│  │              │                         │  - Xác thực tin cậy  │  │
│  └──────────────┘                         └──────────────────────┘  │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Integration Events (RabbitMQ)

Event	Publisher	Consumer(s)	Mô Tả
MinerCreatedEvent	Mining Service	IAM Service	Hồ sơ thợ đào mới được tạo
MiningSessionStartedEvent	Mining Service	-	Phiên đào đã bắt đầu
PointsMinedEvent	Mining Service	Wallet Service	Điểm đã nhận, đồng bộ với ví
CircleCompletedEvent	Mining Service	-	Vòng tròn an toàn trở nên hợp lệ
ReferralActivatedEvent	Mining Service	-	Giới thiệu trở nên hoạt động
UserRegisteredEvent	IAM Service	Mining Service	Tạo hồ sơ thợ đào
FriendAddedEvent	Social Service	Mining Service	Cập nhật gợi ý vòng tròn

---

Tech Stack

Thành Phần	Công Nghệ	Mục Đích
Framework	.NET 10	Framework LTS mới nhất
API Layer	Controllers + MediatR	REST endpoints với CQRS pattern
Database	PostgreSQL + EF Core 10	Lưu trữ với migrations
Caching	Redis + HybridCache	L1+L2 caching với stampede protection
Real-time	SignalR	Cập nhật MP trực tiếp, thông báo phiên
Message Queue	RabbitMQ (MassTransit)	Integration events giữa các dịch vụ
Validation	FluentValidation	Validation pipeline cho request
API Docs	Swagger/OpenAPI	Tài liệu API
Logging	Serilog	Structured logging
Observability	Prometheus + Grafana	Metrics và dashboards

---

Implementation Notes

1. HybridCache cho Mining Rate (Stampede Protection)

%%{init: {'theme':'dark'}}%%
sequenceDiagram
    participant R1 as 📱 Request 1
    participant R2 as 📱 Request 2
    participant R3 as 📱 Request 3
    participant HC as 🔄 HybridCache
    participant DB as 💾 PostgreSQL
    
    Note over R1,R3: Stampede Protection
    R1->>HC: GetMiningRate(userId)
    R2->>HC: GetMiningRate(userId)
    R3->>HC: GetMiningRate(userId)
    HC->>DB: Một truy vấn DB duy nhất
    DB-->>HC: Dữ liệu MiningRate
    HC-->>R1: kết quả cached
    HC-->>R2: kết quả cached
    HC-->>R3: kết quả cached

Lợi ích: Ngăn quá tải DB khi hàng nghìn user claim cùng lúc.

// Configure HybridCache in Program.cs
builder.Services.AddHybridCache(options =>
{
    options.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        LocalCacheExpiration = TimeSpan.FromMinutes(5),
        Expiration = TimeSpan.FromMinutes(30)
    };
});

2. SignalR cho Real-time Updates

// Mining Hub cho cập nhật MP real-time
public class MiningHub : Hub
{
    public async Task JoinMinerGroup(Guid minerId)
    {
        await Groups.AddToGroupAsync(Context.ConnectionId, $"miner:{minerId}");
    }
}

// Thông báo user về cập nhật MP
await _hubContext.Clients.Group($"miner:{minerId}")
    .SendAsync("PointsUpdated", new { earnedPoints, totalPoints, streakDays });

Stateful Reconnect: Giúp trải nghiệm mượt mà khi mạng chập chờn.

3. EF Core Xử Lý Đồng Thời

Quan trọng cho cập nhật số dư điểm:

public class Miner : Entity
{
    public decimal TotalMinedPoints { get; private set; }
    
    // Token đồng thời
    [Timestamp]
    public byte[] RowVersion { get; set; }
}

// Xử lý cộng điểm đồng thời
try
{
    miner.AddPoints(earnedPoints);
    await _unitOfWork.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException)
{
    await _context.Entry(miner).ReloadAsync();
    miner.AddPoints(earnedPoints);
    await _unitOfWork.SaveChangesAsync();
}

4. Background Tasks

// Xử lý streak hàng ngày
public class StreakProcessingService : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            await ProcessExpiredStreaksAsync();
            await AwardMilestoneRewardsAsync();
            await Task.Delay(TimeSpan.FromHours(1), ct);
        }
    }
}

5. Architecture Checklist

• Controllers + MediatR cho CQRS pattern
• FluentValidation với ValidatorBehavior
• HybridCache với stampede protection
• SignalR với Stateful Reconnect cho real-time updates
• EF Core concurrency handling cho point balance
• BackgroundService cho streak/session processing
• Domain Events + MassTransit cho integration events

---

Cấu Hình

Biến Môi Trường

Biến	Mô Tả	Bắt Buộc	Mặc Định
DATABASE_URL	Kết nối PostgreSQL	Có	-
REDIS_URL	Kết nối Redis	Có	-
RABBITMQ_URL	Kết nối RabbitMQ	Có	-
JWT_AUTHORITY	URL JWT issuer	Có	-
MINING_BASE_RATE	Tỷ lệ đào cơ bản (MP/giờ)	Không	0.25
MINING_SESSION_HOURS	Thời gian phiên	Không	24
CIRCLE_MIN_MEMBERS	Số thành viên tối thiểu vòng tròn	Không	3
CIRCLE_MAX_MEMBERS	Số thành viên tối đa vòng tròn	Không	5
REFERRAL_BONUS_PERCENT	Thưởng mỗi giới thiệu	Không	25
REFERRAL_BONUS_CAP	Giới hạn thưởng giới thiệu	Không	100

---

Xem Xét Bảo Mật

Biện Pháp Chống Gian Lận

1. Giới Hạn Tốc Độ - Tối đa 1 phiên đào mỗi 24 giờ
2. Vân Tay Thiết Bị - Theo dõi thay đổi thiết bị, đánh dấu hoạt động đáng ngờ
3. Giám Sát IP - Phát hiện nhiều tài khoản từ cùng IP
4. Xác Thực Vòng Tròn - Thành viên phải là người dùng thật, hoạt động
5. Xác Minh Giới Thiệu - Giới thiệu phải vượt qua KYC để kích hoạt thưởng
6. Điểm Hoạt Động - Phạt các mẫu không hoạt động hoặc giống bot

Bảo Vệ Dữ Liệu

• Lịch sử đào được mã hóa khi lưu trữ
• Dữ liệu cá nhân tuân thủ GDPR
• Nhật ký kiểm toán cho tất cả hành động quản trị

---

Roadmap

Giai Đoạn 1: Core Mining (MVP)

• Tạo hồ sơ thợ đào
• Phiên đào tap-to-mine hàng ngày
• Tính toán tỷ lệ đào cơ bản
• Lịch sử đào

Giai Đoạn 2: Tính Năng Xã Hội

• Vòng tròn an toàn
• Hệ thống giới thiệu
• Tính toán thưởng vòng tròn

Giai Đoạn 3: Tính Năng Nâng Cao

• Tiến trình vai trò người dùng
• Chuyển đổi điểm sang ví
• Bảng xếp hạng

Giai Đoạn 4: Mạng Node (Tương Lai)

• Vai trò node operator
• Xác thực phi tập trung
• Thưởng mạng

---

Tài Nguyên

• Tài Liệu Kiến Trúc
• Tài Liệu GoodGo Platform
• Pi Network Whitepaper (Nguồn Cảm Hứng)
• Tích Hợp Wallet Service

Giấy Phép

Proprietary - GoodGo Platform