# 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

```csharp
/// 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:

```mermaid
%%{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

```csharp
/// 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

```mermaid
%%{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

```mermaid
%%{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

```csharp
/// 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

```mermaid
%%{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ý:

```csharp
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)

```mermaid
%%{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.

```csharp
// 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

```csharp
// 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:**

```csharp
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

```csharp
// 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

- [x] Controllers + MediatR cho CQRS pattern
- [x] FluentValidation với ValidatorBehavior
- [x] HybridCache với stampede protection
- [x] SignalR với Stateful Reconnect cho real-time updates
- [x] EF Core concurrency handling cho point balance
- [x] BackgroundService cho streak/session processing
- [x] 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)
- [x] Tạo hồ sơ thợ đào
- [x] Phiên đào tap-to-mine hàng ngày
- [x] Tính toán tỷ lệ đào cơ bản
- [x] 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](./ARCHITECTURE.md)
- [Tài Liệu GoodGo Platform](../../docs/)
- [Pi Network Whitepaper](https://minepi.com/white-paper) (Nguồn Cảm Hứng)
- [Tích Hợp Wallet Service](../wallet-service-net/)

## Giấy Phép

Proprietary - GoodGo Platform
