admin/pos-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
529c92e0e1ad54ebe8f16e3a3019f1a07713d45c
pos-system/services/mission-service-net/docs/vi
History

README.md

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

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

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

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

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

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

%%{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)

%%{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è

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

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

%%{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ụ

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

%%{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)

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

%%{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
Reference in New Issue View Git Blame Copy Permalink