# Mission Service .NET

> Dịch vụ gamification Mission & Task cho GoodGo Platform.

📖 **Xem thêm:** [Tài liệu Kiến Trúc Chi Tiết](./ARCHITECTURE.md)

## Tổng Quan

**Mission Service** quản lý các nhiệm vụ (missions) và tác vụ (tasks) gamification, cho phép người dùng kiếm phần thưởng thông qua các hoạt động trên nền tảng GoodGo.

### Tính Năng Chính

| Tính Năng | Mô Tả |
|-----------|-------|
| 🎬 **Xem Video** | Kiếm thưởng bằng cách xem video - Pay per view |
| 💰 **Pay Per Click** | Kiếm điểm bằng cách nhấn quảng cáo/liên kết |
| 📤 **Pay Per Upload** | Được thưởng khi tải lên nội dung UGC |
| 👥 **Mời Bạn Bè** | Kiếm bonus khi bạn hoàn thành nhiệm vụ |
| 📅 **Điểm Danh Hàng Ngày** | Điểm danh với thưởng streak |
| ❤️ **Tương Tác Xã Hội** | Like, Share, Subscribe kênh mạng xã hội |

---

## Thiết Kế Kiến Trúc

### Kiến Trúc Hệ Thống

```mermaid
%%{init: {'theme':'dark'}}%%
graph TD
    subgraph Gateway["🌐 API Gateway"]
        Traefik[Traefik]
    end
    
    subgraph Mission["📋 Mission Service"]
        API[Tầng API]
        Domain[Tầng Domain]
        Infra[Tầng Infrastructure]
    end
    
    subgraph External["🔗 Dịch Vụ Liên Quan"]
        IAM[IAM Service]
        Wallet[Wallet Service]
        Mining[Mining Service]
        Social[Social Service]
        Storage[Storage Service]
    end
    
    subgraph Data["💾 Tầng Dữ Liệu"]
        DB[(PostgreSQL)]
        Redis[(Redis)]
        RabbitMQ[RabbitMQ]
    end
    
    Traefik --> API
    API --> Domain
    Domain --> Infra
    Infra --> DB
    Infra --> Redis
    Infra --> RabbitMQ
    
    Mission <--> IAM
    Mission --> Wallet
    Mission <--> Mining
    Mission <--> Social
    Mission <--> Storage
    
    style Gateway fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
    style Mission fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:3px
    style External fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
    style Data fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
```

### Cấu Trúc Clean Architecture

```
mission-service-net/
├── src/
│   ├── MissionService.API/               # Tầng API
│   │   ├── Controllers/
│   │   │   ├── MissionsController.cs     # Quản lý mission
│   │   │   ├── TasksController.cs        # Thực thi task
│   │   │   ├── CheckInController.cs      # Điểm danh
│   │   │   └── RewardsController.cs      # Nhận thưởng
│   │   └── Application/
│   │       ├── Commands/                 # Thao tác ghi
│   │       ├── Queries/                  # Thao tác đọc
│   │       └── IntegrationEvents/        # Sự kiện tích hợp
│   │
│   ├── MissionService.Domain/            # Tầng Domain
│   │   ├── AggregatesModel/
│   │   │   ├── MissionAggregate/         # Định nghĩa mission
│   │   │   ├── TaskAggregate/            # Thực thi task
│   │   │   ├── CheckInAggregate/         # Điểm danh
│   │   │   └── RewardAggregate/          # Theo dõi thưởng
│   │   ├── Events/                       # Domain events
│   │   └── Services/                     # Domain services
│   │
│   └── MissionService.Infrastructure/    # Tầng Infrastructure
│       ├── EntityConfigurations/         # EF Core mappings
│       ├── Repositories/                 # Truy cập dữ liệu
│       └── ExternalServices/             # API clients
│
├── tests/
├── docs/
└── Dockerfile
```

---

## Domain Model

### Các Aggregate Chính

```mermaid
%%{init: {'theme':'dark'}}%%
classDiagram
    class Mission {
        +Guid Id
        +string Code
        +LocalizedString Title
        +MissionType Type
        +MissionReward Reward
        +FrequencyType Frequency
        +MissionStatus Status
        +Activate()
        +Pause()
        +ValidateCompletion()
    }
    
    class UserTask {
        +Guid Id
        +Guid UserId
        +Guid MissionId
        +TaskStatus Status
        +TaskProgress Progress
        +TaskEvidence Evidence
        +Start()
        +UpdateProgress()
        +Complete()
        +ClaimReward()
    }
    
    class UserCheckIn {
        +Guid Id
        +Guid UserId
        +int CurrentStreak
        +int LongestStreak
        +DateOnly LastCheckInDate
        +CheckIn()
        +GetStreakBonus()
    }
    
    Mission "1" --> "*" UserTask : tạo ra
    UserTask --> UserCheckIn : có thể kích hoạt
```

### Các Loại Mission

```mermaid
%%{init: {'theme':'dark'}}%%
flowchart LR
    subgraph Types["📋 Loại Mission"]
        Video["🎬 Xem Video"]
        Click["💰 Pay Per Click"]
        Upload["📤 Pay Per Upload"]
        Invite["👥 Mời Bạn Bè"]
        CheckIn["📅 Điểm Danh"]
        Social["❤️ Tương Tác XH"]
    end
    
    style Video fill:#E74C3C,color:#ECF0F1,stroke:#C0392B,stroke-width:2px
    style Click fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
    style Upload fill:#9B59B6,color:#ECF0F1,stroke:#8E44AD,stroke-width:2px
    style Invite fill:#2ECC71,color:#ECF0F1,stroke:#27AE60,stroke-width:2px
    style CheckIn fill:#F39C12,color:#ECF0F1,stroke:#E67E22,stroke-width:2px
    style Social fill:#E91E63,color:#ECF0F1,stroke:#C2185B,stroke-width:2px
```

---

## Chi Tiết Từng Loại Mission

### 🎬 Xem Video

```mermaid
%%{init: {'theme':'dark'}}%%
sequenceDiagram
    participant U as 📱 User
    participant A as 🌐 Mission API
    participant V as 🎬 Video Player
    participant W as 💰 Wallet

    U->>A: GET /missions?type=VIDEO
    A-->>U: Danh sách video missions
    U->>A: POST /tasks/start {missionId}
    A-->>U: {taskId, videoUrl, requiredDuration}
    
    U->>V: Bắt đầu xem video
    V->>A: POST /tasks/{id}/progress {watchedSeconds}
    Note over V,A: Cập nhật định kỳ (mỗi 5s)
    
    V->>A: POST /tasks/{id}/complete {totalWatched}
    A->>A: Xác thực thời lượng xem ≥ yêu cầu
    A-->>U: Task hoàn thành!
    
    U->>A: POST /tasks/{id}/claim
    A->>W: GrantPoints(userId, amount)
    A-->>U: Đã nhận thưởng!
```

| Tham Số | Giá Trị | Mô Tả |
|---------|---------|-------|
| `minWatchPercent` | 80% | Tỷ lệ xem tối thiểu |
| `skipDetection` | true | Phát hiện tua nhanh |
| `antiBot` | true | CAPTCHA cho hoạt động đáng ngờ |
| `reward` | 5-20 MP | Tùy độ dài video |

---

### 💰 Pay Per Click

```mermaid
%%{init: {'theme':'dark'}}%%
flowchart LR
    U[📱 User] --> M[📋 Xem Mission]
    M --> C{🖱️ Nhấn Link/Ads}
    C --> V[✅ Xác Thực Click]
    V --> R[🎁 Nhận Thưởng]
    
    style R fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
```

| Hành Động | Điểm | Giới Hạn |
|-----------|------|----------|
| Xem quảng cáo | 1 MP | 20/ngày |
| Nhấn link ngoài | 2 MP | 10/ngày |
| Cài đặt app (CPI) | 50 MP | 2/ngày |

**Quy Tắc Chống Gian Lận:**
- Rate Limit: 10 clicks/ngày
- Cooldown: 30 giây giữa các lần
- Chỉ URL unique

---

### 📤 Pay Per Upload (UGC)

```mermaid
%%{init: {'theme':'dark'}}%%
flowchart TD
    U[📱 Upload Nội Dung] --> T{Loại Nội Dung}
    T -->|Ảnh| P[Xem Xét Ảnh]
    T -->|Video| V[Xem Xét Video]
    T -->|Review| R[Xem Xét Text]
    
    P --> AI[🤖 AI Moderation]
    V --> AI
    R --> AI
    
    AI -->|Pass| A[✅ Duyệt]
    AI -->|Flag| M[👨‍💻 Xem Xét Thủ Công]
    M --> A
    M --> X[❌ Từ Chối]
    
    A --> RW[🎁 Cấp Thưởng]
    
    style A fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
    style X fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px
```

| Loại Nội Dung | Yêu Cầu | Review | Thưởng |
|---------------|---------|--------|--------|
| Ảnh | 720p, <5MB | AI + Manual | 5-20 MP |
| Video | 480p, 15-60s | AI + Manual | 20-100 MP |
| Text Review | 50-500 ký tự | AI | 3-10 MP |

---

### 👥 Mời Bạn Bè

```mermaid
%%{init: {'theme':'dark'}}%%
flowchart LR
    subgraph Invite["👥 Mời Bạn Bè"]
        A[Chia Sẻ Code] --> B[Bạn Đăng Ký]
        B --> C[Bạn Hoàn Thành Mission]
        C --> D[✅ Cả Hai Nhận Thưởng]
    end
    
    style D fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
```

| Số Bạn Mời | Thưởng/Bạn | Bonus |
|------------|------------|-------|
| 1-5 người | 10 MP | - |
| 6-20 người | 15 MP | +50% |
| 21+ người | 20 MP | +100% |

**Tích hợp Mining Service:**
- Đồng bộ với `ReferralAggregate`
- Bonus stacking: Mission reward + Mining rate boost

---

### ❤️ Tương Tác Xã Hội

```mermaid
%%{init: {'theme':'dark'}}%%
flowchart TD
    subgraph Actions["Hành Động"]
        L[❤️ Like Post]
        S[🔄 Share Content]  
        F[➕ Follow/Subscribe]
        C[💬 Comment]
    end
    
    subgraph Platforms["Nền Tảng Hỗ Trợ"]
        FB[Facebook]
        TW[Twitter/X]
        IG[Instagram]
        YT[YouTube]
        TK[TikTok]
    end
    
    Actions --> V{Xác Thực}
    V -->|OAuth| API[Platform API]
    V -->|Screenshot| AI[AI Verify]
    V -->|URL Check| SC[Scraper]
    
    style V fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
```

| Phương Thức Xác Thực | Độ Chính Xác | Tốc Độ | Chi Phí |
|---------------------|--------------|--------|---------|
| OAuth API | Cao | Nhanh | Trung bình |
| Screenshot AI | Trung bình | TB | Thấp |
| URL Scraping | Thấp | Nhanh | Miễn phí |

| Hành Động | Điểm | Giới Hạn |
|-----------|------|----------|
| Like | 1 MP | 10/ngày |
| Share | 3 MP | 5/ngày |
| Follow/Subscribe | 5 MP | 3/ngày |
| Comment | 2 MP | 10/ngày |

---

## Hệ Thống Điểm Danh Hàng Ngày

### 🔥 Thưởng Streak

```mermaid
%%{init: {'theme':'dark'}}%%
flowchart LR
    subgraph Streak["📅 Các Cấp Streak"]
        D1["Ngày 1-6<br/>2 MP"] --> D7["Ngày 7<br/>🎁 +20 MP"]
        D7 --> D14["Ngày 14<br/>🎁 +35 MP"]
        D14 --> D21["Ngày 21<br/>🎁 +50 MP"]
        D21 --> D30["Ngày 30<br/>👑 +100 MP"]
    end
    
    style D1 fill:#7F8C8D,color:#ECF0F1,stroke:#5D6D7E,stroke-width:2px
    style D7 fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
    style D14 fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style D21 fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
    style D30 fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:3px
```

| Streak | Điểm Hàng Ngày | Thưởng Mốc |
|--------|----------------|------------|
| Ngày 1-6 | 2 MP | - |
| Ngày 7 | 3 MP | 🎁 20 MP bonus |
| Ngày 8-13 | 3 MP | - |
| Ngày 14 | 4 MP | 🎁 35 MP bonus |
| Ngày 15-20 | 4 MP | - |
| Ngày 21 | 5 MP | 🎁 50 MP bonus |
| Ngày 22-29 | 5 MP | - |
| Ngày 30 | 10 MP | 👑 100 MP + Badge |

---

## API Endpoints

### APIs Mission

| Phương Thức | Endpoint | Mô Tả |
|-------------|----------|-------|
| `GET` | `/api/v1/missions` | Danh sách mission |
| `GET` | `/api/v1/missions/{id}` | Chi tiết mission |
| `GET` | `/api/v1/missions/category/{category}` | Mission theo danh mục |
| `POST` | `/api/v1/missions/{id}/start` | Bắt đầu task |
| `PUT` | `/api/v1/missions/tasks/{taskId}/progress` | Cập nhật tiến độ |
| `POST` | `/api/v1/missions/tasks/{taskId}/claim` | Nhận thưởng task |

### APIs Điểm Danh

| Phương Thức | Endpoint | Mô Tả |
|-------------|----------|-------|
| `POST` | `/api/v1/checkins` | Điểm danh hàng ngày |
| `GET` | `/api/v1/checkins/status` | Trạng thái điểm danh |
| `GET` | `/api/v1/checkins/history` | Lịch sử điểm danh (theo tháng) |
| `GET` | `/api/v1/checkins/leaderboard` | Bảng xếp hạng streak |
| `GET` | `/api/v1/checkins/config` | Cấu hình thưởng streak |

### APIs Admin Backoffice

#### 📋 Quản Lý Mission

| Phương Thức | Endpoint | Mô Tả |
|-------------|----------|-------|
| `GET` | `/api/v1/admin/missions` | Danh sách tất cả missions |
| `POST` | `/api/v1/admin/missions` | Tạo mission mới |
| `GET` | `/api/v1/admin/missions/{id}` | Chi tiết mission |
| `POST` | `/api/v1/admin/missions/{id}/activate` | Kích hoạt mission |
| `POST` | `/api/v1/admin/missions/{id}/pause` | Tạm dừng mission |
| `POST` | `/api/v1/admin/missions/{id}/archive` | Lưu trữ mission |

#### 👥 Quản Lý Check-in

| Phương Thức | Endpoint | Mô Tả |
|-------------|----------|-------|
| `GET` | `/api/v1/admin/checkins/users/{userId}` | Chi tiết check-in user |
| `POST` | `/api/v1/admin/checkins/users/{userId}/reset-streak` | Reset streak user |
| `GET` | `/api/v1/admin/checkins/top-streaks` | Bảng xếp hạng streak cao nhất |

#### ✅ Quản Lý Task

| Phương Thức | Endpoint | Mô Tả |
|-------------|----------|-------|
| `GET` | `/api/v1/admin/tasks/pending-verification` | Tasks chờ xác thực |
| `GET` | `/api/v1/admin/tasks/users/{userId}` | Tasks của user |
| `POST` | `/api/v1/admin/tasks/{taskId}/approve` | Duyệt task |
| `POST` | `/api/v1/admin/tasks/{taskId}/reject` | Từ chối task |

---

## Điểm Tích Hợp

### Phụ Thuộc Dịch Vụ

```mermaid
%%{init: {'theme':'dark'}}%%
flowchart LR
    subgraph Mission["📋 Mission Service"]
        M[Mission Service]
    end
    
    subgraph Auth["🔐 Xác Thực"]
        IAM[IAM Service]
    end
    
    subgraph Rewards["💰 Phần Thưởng"]
        Wallet[Wallet Service]
        Mining[Mining Service]
    end
    
    subgraph Social["👥 Mạng Xã Hội"]
        SocialSvc[Social Service]
        Storage[Storage Service]
    end
    
    IAM -->|JWT Auth| M
    M -->|Cấp Điểm| Wallet
    M <-->|Đồng Bộ Referral| Mining
    M <-->|Kiểm Tra Bạn Bè| SocialSvc
    M <-->|Media| Storage
    
    style Mission fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:3px
    style Auth fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px
    style Rewards fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
    style Social fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
```

### Integration Events

| Sự Kiện | Nhà Xuất Bản | Người Tiêu Thụ | Mô Tả |
|---------|--------------|----------------|-------|
| `MissionCompletedEvent` | Mission | Wallet | Hoàn thành mission |
| `CheckInCompletedEvent` | Mission | Wallet | Điểm danh xong |
| `UserRegisteredEvent` | IAM | Mission | Tạo hồ sơ user |
| `ReferralActivatedEvent` | Mining | Mission | Đồng bộ mời bạ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 | CQRS pattern |
| **Database** | PostgreSQL + EF Core 10 | Lưu trữ dữ liệu |
| **Caching** | Redis + HybridCache | L1+L2 caching |
| **Message Queue** | RabbitMQ (MassTransit) | Integration events |
| **Scheduler** | Hangfire | Background jobs |
| **Validation** | FluentValidation | Validation request |
| **API Docs** | Swagger/OpenAPI | Tài liệu API |

---

## 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 phát hành JWT | Có | - |
| `MAX_DAILY_TASKS` | Số task tối đa/ngày | Không | 50 |
| `CHECKIN_STREAK_ENABLED` | Bật thưởng streak | Không | true |
| `CONTENT_MODERATION_API` | API AI moderation | Không | - |

---

## Admin Configuration Entity

### MissionConfiguration Aggregate

```mermaid
%%{init: {'theme':'dark'}}%%
classDiagram
    class MissionConfiguration {
        +Guid Id
        +bool IsGloballyEnabled
        +int MaxDailyTasks
        +int TaskCooldownSeconds
        +DateTime UpdatedAt
        +Guid UpdatedBy
    }
    
    class CheckInConfiguration {
        +Guid Id
        +List~StreakTier~ Tiers
        +int BasePoints
        +bool StreakEnabled
    }
    
    class StreakTier {
        +int MinDays
        +int MaxDays
        +int DailyPoints
        +int MilestoneBonus
        +string BadgeName
    }
    
    class RewardConfiguration {
        +Guid Id
        +decimal VideoRewardMin
        +decimal VideoRewardMax
        +decimal ClickReward
        +decimal UploadRewardMin
        +decimal UploadRewardMax
        +decimal InviteReward
        +decimal SocialReward
    }
    
    MissionConfiguration --> CheckInConfiguration
    MissionConfiguration --> RewardConfiguration
    CheckInConfiguration --> "*" StreakTier
```

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

| Danh Mục | Tham Số | Mặc Định | Mô Tả |
|----------|---------|----------|-------|
| **Hệ Thống** | Bật Toàn Cục | true | Công tắc khẩn cấp |
| **Hệ Thống** | Task Tối Đa/Ngày | 50 | Giới hạn tasks |
| **Hệ Thống** | Cooldown Tasks | 60 giây | Thời gian chờ |
| **Video** | Thưởng Min | 5 MP | Video ngắn |
| **Video** | Thưởng Max | 20 MP | Video dài |
| **Video** | Tỷ Lệ Xem Min | 80% | Phần trăm xem tối thiểu |
| **Click** | Thưởng/Click | 1-2 MP | Tùy loại link |
| **Click** | Giới Hạn/Ngày | 20 | Số clicks tối đa |
| **Upload** | Thưởng Ảnh | 5-20 MP | Tùy chất lượng |
| **Upload** | Thưởng Video | 20-100 MP | Tùy độ dài |
| **Invite** | Thưởng/Bạn | 10-20 MP | Tùy số lượng |
| **Social** | Like/Share | 1-3 MP | Tùy hành động |
| **Check-in** | Điểm Ngày 1-6 | 2 MP | Điểm cơ bản |
| **Check-in** | Bonus Ngày 7 | 20 MP | Mốc tuần đầu |
| **Check-in** | Bonus Ngày 30 | 100 MP | Mốc tháng |

### Nhật Ký Cấu Hình (Audit Log)

```csharp
public record ConfigAuditLog(
    Guid Id,
    Guid AdminUserId,
    string ConfigType,          // "Mission" | "CheckIn" | "Reward"
    string PreviousValue,       // JSON cấu hình cũ
    string NewValue,            // JSON cấu hình mới
    string Reason,              // Lý do admin thay đổi
    DateTime CreatedAt,
    string IpAddress
);
```

---

## Bảo Mật & Chống Gian Lận

### Phòng Chống Gian Lận

```mermaid
%%{init: {'theme':'dark'}}%%
flowchart TD
    Request([🚀 Yêu Cầu]) --> Rate{⏱️ Rate Limit}
    Rate -->|Vượt Quá| Block[❌ Chặn]
    Rate -->|OK| Device{🔍 Kiểm Tra Thiết Bị}
    Device -->|Đáng Ngờ| Flag[⚠️ Đánh Dấu]
    Device -->|OK| Verify{✅ Xác Thực Bằng Chứng}
    Verify -->|Không Hợp Lệ| Reject[❌ Từ Chối]
    Verify -->|Hợp Lệ| Reward[🎁 Cấp Thưởng]
    
    style Block fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px
    style Reject fill:#E74C3C,color:#ECF0F1,stroke:#C0392B,stroke-width:2px
    style Reward fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
```

| Biện Pháp | Mô Tả |
|-----------|-------|
| **Rate Limiting** | Số task tối đa mỗi ngày |
| **Cooldown** | Thời gian chờ giữa các lần hoàn thành |
| **Device Fingerprint** | Theo dõi đa tài khoản |
| **Evidence Validation** | AI + Manual review cho UGC |

---

## Lộ Trình

### Giai Đoạn 1: Core (Tuần 1-2)
- [ ] Thiết lập project
- [ ] Domain model
- [ ] Database schema

### Giai Đoạn 2: Điểm Danh (Tuần 3)
- [ ] Check-in aggregate
- [ ] Tính toán streak
- [ ] Phần thưởng mốc

### Giai Đoạn 3: Xem Video (Tuần 4-5)
- [ ] Loại mission video
- [ ] Theo dõi tiến độ
- [ ] Xác thực thời lượng

### Giai Đoạn 4: Tương Tác XH (Tuần 6-7)
- [ ] Cấu hình nền tảng xã hội
- [ ] Phương thức xác thực
- [ ] Tích hợp OAuth

### Giai Đoạn 5: Nâng Cao (Tuần 8+)
- [ ] Pay per click/upload
- [ ] Mời bạn bè
- [ ] Admin analytics
