feat: Introduce MiningStreak concept and integrate it into the architecture documentation for both English and Vietnamese.

This commit is contained in:
Ho Ngoc Hai
2026-01-17 17:12:18 +07:00
parent d63afc1790
commit 10d8ba7dbb
4 changed files with 477 additions and 5 deletions

View File

@@ -87,6 +87,7 @@ classDiagram
+decimal TotalMinedPoints
+MiningRate CurrentRate
+MiningSession ActiveSession
+MiningStreak Streak
+string ReferralCode
+Guid ReferredBy
+MinerStatus Status
@@ -109,9 +110,19 @@ classDiagram
+decimal CircleBonus
+decimal ReferralBonus
+decimal RoleBonus
+decimal StreakBonus
+decimal TotalRate
}
class MiningStreak {
+int CurrentStreak
+int LongestStreak
+DateTime LastMiningDate
+int FreezeTokens
+bool IsGracePeriod
+decimal BonusMultiplier
}
class MiningHistory {
+Guid Id
+decimal PointsEarned
@@ -121,6 +132,7 @@ classDiagram
Miner "1" --> "0..1" MiningSession : has
Miner --> MiningRate : uses
Miner --> MiningStreak : tracks
Miner "1" --> "*" MiningHistory : tracks
```

View File

@@ -369,14 +369,204 @@ sequenceDiagram
| `GET` | `/api/v1/referrals/stats` | Get referral statistics |
| `POST` | `/api/v1/referrals/apply` | Apply referral code (during signup) |
### Admin APIs
### Admin Backoffice APIs
#### 🔧 Configuration Management
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/v1/admin/config` | Get all system configuration |
| `PUT` | `/api/v1/admin/config` | Update system configuration |
| `GET` | `/api/v1/admin/config/mining` | Get mining configuration |
| `PUT` | `/api/v1/admin/config/mining` | Update mining rates |
| `GET` | `/api/v1/admin/config/streak` | Get streak configuration |
| `PUT` | `/api/v1/admin/config/streak` | Update streak bonuses |
| `GET` | `/api/v1/admin/config/referral` | Get referral configuration |
| `PUT` | `/api/v1/admin/config/referral` | Update referral bonuses |
#### 👥 User Management
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/v1/admin/miners` | List all miners (paginated) |
| `GET` | `/api/v1/admin/miners/{id}` | Get miner details |
| `PUT` | `/api/v1/admin/miners/{id}/suspend` | Suspend miner |
| `PUT` | `/api/v1/admin/miners/{id}/ban` | Ban miner |
| `PUT` | `/api/v1/admin/config/mining-rate` | Update base mining rate |
| `PUT` | `/api/v1/admin/miners/{id}/restore` | Restore suspended miner |
| `PUT` | `/api/v1/admin/miners/{id}/adjust-points` | Adjust miner points |
| `PUT` | `/api/v1/admin/miners/{id}/reset-streak` | Reset miner streak |
#### 📊 Analytics & Reports
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/v1/admin/analytics/overview` | Dashboard overview stats |
| `GET` | `/api/v1/admin/analytics/mining` | Mining statistics |
| `GET` | `/api/v1/admin/analytics/streaks` | Streak distribution |
| `GET` | `/api/v1/admin/analytics/referrals` | Referral network stats |
| `GET` | `/api/v1/admin/audit-logs` | View configuration change logs |
---
## 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
/// System-wide mining configuration (admin-editable)
public record MiningConfig(
decimal BaseRate, // Default: 0.25 MP/hour
int SessionDurationHours, // Default: 24
bool IsGloballyEnabled // Emergency kill switch
);
/// Streak tiers configuration (admin-editable)
public record StreakConfig(
List<StreakTierConfig> Tiers,
bool GracePeriodEnabled, // Default: true
int GracePeriodHours, // Default: 24
decimal RecoveryCostMp, // Default: 50
int FreezeTokenEarnDays // Default: 7
);
public record StreakTierConfig(
int MinDays,
int MaxDays,
decimal BonusPercent,
string BadgeName,
decimal MilestoneMpBonus
);
/// Referral configuration (admin-editable)
public record ReferralConfig(
decimal BonusPercentPerReferral, // Default: 25%
decimal MaxBonusPercent, // Default: 100%
bool KycRequired, // Default: true
int MaxReferralLevels // Default: 1
);
/// Circle configuration (admin-editable)
public record CircleConfig(
int MinMembers, // Default: 3
int MaxMembers, // Default: 5
decimal ValidCircleBonus // Default: 25%
);
```
### Admin Configuration Flow
```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: All miners will use<br/>new config on next claim
```
### Default Configuration Values
| Category | Parameter | Default | Description |
|----------|-----------|---------|-------------|
| **Mining** | Base Rate | 0.25 MP/hour | Points earned per hour |
| **Mining** | Session Duration | 24 hours | Mining session length |
| **Mining** | Global Enabled | true | Emergency kill switch |
| **Streak** | Day 3-6 Bonus | 10% | Early streak bonus |
| **Streak** | Day 7-13 Bonus | 25% | Week streak bonus |
| **Streak** | Day 14-29 Bonus | 50% | 2-week streak bonus |
| **Streak** | Day 30-59 Bonus | 100% | Month streak bonus |
| **Streak** | Day 60-89 Bonus | 125% | 2-month streak bonus |
| **Streak** | Day 90+ Bonus | 150% | Max streak bonus |
| **Streak** | Grace Period | 24 hours | Time before streak loss |
| **Streak** | Recovery Cost | 50 MP | Cost to restore streak |
| **Streak** | Freeze Token Days | 7 | Days to earn freeze token |
| **Referral** | Bonus Per Referral | 25% | Rate increase per referral |
| **Referral** | Max Bonus | 100% | Maximum referral bonus |
| **Referral** | KYC Required | true | Require KYC for bonus |
| **Circle** | Min Members | 3 | Minimum for valid circle |
| **Circle** | Max Members | 5 | Maximum circle size |
| **Circle** | Valid Circle Bonus | 25% | Bonus for valid circle |
### Audit Logging
All admin configuration changes are logged:
```csharp
public record ConfigAuditLog(
Guid Id,
Guid AdminUserId,
string ConfigType, // "Mining" | "Streak" | "Referral" | "Circle"
string PreviousValue, // JSON of old config
string NewValue, // JSON of new config
string Reason, // Admin's reason for change
DateTime CreatedAt,
string IpAddress
);
```
---

View File

@@ -87,6 +87,7 @@ classDiagram
+decimal TotalMinedPoints
+MiningRate CurrentRate
+MiningSession ActiveSession
+MiningStreak Streak
+string ReferralCode
+Guid ReferredBy
+MinerStatus Status
@@ -109,9 +110,19 @@ classDiagram
+decimal CircleBonus
+decimal ReferralBonus
+decimal RoleBonus
+decimal StreakBonus
+decimal TotalRate
}
class MiningStreak {
+int CurrentStreak
+int LongestStreak
+DateTime LastMiningDate
+int FreezeTokens
+bool IsGracePeriod
+decimal BonusMultiplier
}
class MiningHistory {
+Guid Id
+decimal PointsEarned
@@ -121,6 +132,7 @@ classDiagram
Miner "1" --> "0..1" MiningSession : có
Miner --> MiningRate : sử dụng
Miner --> MiningStreak : theo dõi
Miner "1" --> "*" MiningHistory : theo dõi
```

View File

@@ -13,6 +13,7 @@ Mining Service cung cấp **hệ thống đào điểm thưởng game hóa** l
|-----------|-------|
| **Đà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 |
@@ -214,18 +215,85 @@ public record MiningPoints(
## 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 + Hệ Số Vai Trò) × (1 + Thưởng Vòng Tròn) × (1 + Thưởng Giới Thiệu)
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
@@ -301,14 +369,204 @@ sequenceDiagram
| `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 Quản Trị
### 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/config/mining-rate` | Cập nhật tỷ lệ đào cơ bản |
| `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/mining` | Thống kê đào |
| `GET` | `/api/v1/admin/analytics/streaks` | Phân bố streak |
| `GET` | `/api/v1/admin/analytics/referrals` | Thống kê mạng lưới giới thiệu |
| `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
);
```
---