docs/archive/03-BACKEND/CMS

CMS Microservice - Network & Club Commission System

📊 Project Status (2025-12-27)

Overall Progress: 98% Complete
Production Readiness: 99%
MVP Status: ✅ 100% Complete

✅ Completed Phases

1. ✅ Domain Layer (Entities, Enums, Value Objects)
2. ✅ Club Membership System
3. ✅ Binary Network Tree
4. ✅ Commission Calculation & Background Worker (MVP)
5. ✅ Protobuf gRPC Services
6. ✅ History & Configuration Management
7. ✅ Database Migration & Seed Data
8. ✅ App Version Management
9. ✅ SMS Templates & SystemConstants

🟡 Partially Complete

• Withdrawal & Settlement (40%)
  • ✅ Commands & Database
  • ❌ Payment Gateway Integration

---

🚀 Recent Updates (2025-12-27 / ۷ دی)

SystemConstants - مقادیر ثابت ✅

• ✅ فایل جدید: Domain/Common/SystemConstants.cs
• ✅ GoldenPackageAmount = 56_000_000 - پکیج طلایی
• ✅ DayaLoanAmount = 56_000_000 - وام دایا
• ✅ حذف مقادیر hardcode از همه handlers

SmsTemplates - قالب‌های پیامک ✅

• ✅ فایل جدید: Domain/Common/SmsTemplates.cs
• ✅ قالب‌ها: DayaLoan, ClubActivated, PackagePurchased, Commission, Withdrawal, OTP, Welcome
• ✅ ارسال SMS خودکار هنگام تأیید وام دایا

Mapping Fixes ✅

• ✅ AppVersionProfile.cs - Map List to GetAllAppVersionsResponse

Previous Updates (2025-12-26)

• ✅ App Version Management: Entity, gRPC, Handlers
• ✅ ReferralCode in Network Tree: SP + Proto update

---

🏗️ Architecture

Clean Architecture with 4 layers:

CMSMicroservice.Domain/          # Entities, Enums, Interfaces
CMSMicroservice.Application/     # CQRS (Commands, Queries, MediatR)
CMSMicroservice.Infrastructure/  # DbContext, Services, Background Jobs
CMSMicroservice.WebApi/          # gRPC Services, Controllers
CMSMicroservice.Protobuf/        # Protocol Buffers definitions

Technology Stack:

• .NET 9.0
• Entity Framework Core 9.0.11
• gRPC + JSON Transcoding
• Hangfire 1.8.22 (Job Scheduling)
• MediatR 13.0.0 (CQRS)
• Polly 8.5.0 (Resilience)
• MailKit 4.14.1 (Email)
• Kavenegar 1.2.5 (SMS)
• SQL Server

---

📖 Documentation

• Implementation Progress - Detailed phase-by-phase progress
• Email/SMS Configuration Guide - Production setup instructions
• Balance Calculation Logic - Commission algorithm details
• Binary Tree Registration - Network tree guide
• Network Club Commission System - Full system specification

---

🚀 Quick Start

Prerequisites

• .NET 9.0 SDK
• SQL Server (local or remote)
• (Optional) Gmail account for Email
• (Optional) Kavenegar account for SMS

1. Clone & Build

cd /home/masoud/Apps/project/FourSat/CMS/src
dotnet build

2. Configure Database

Update appsettings.json with your SQL Server connection:

"ConnectionStrings": {
  "DefaultConnection": "Server=YOUR_SERVER;Database=Foursat_CMS;..."
}

3. Apply Migrations

cd CMSMicroservice.WebApi
dotnet ef database update

4. Configure Notifications (Optional)

See Email/SMS Configuration Guide

5. Run

dotnet run --urls="http://localhost:5133"

6. Access Endpoints

• Health: http://localhost:5133/health
• Hangfire Dashboard: http://localhost:5133/hangfire
• gRPC: localhost:5133 (HTTP/2)

---

🔧 Configuration

Email (SMTP)

"Email": {
  "Enabled": true,
  "SmtpHost": "smtp.gmail.com",
  "SmtpPort": 587,
  "SmtpUsername": "your-email@gmail.com",
  "SmtpPassword": "your-gmail-app-password",
  "FromEmail": "noreply@foursat.com",
  "FromName": "FourSat CMS",
  "EnableSsl": true
}

SMS (Kavenegar)

"Sms": {
  "Enabled": true,
  "Provider": "Kavenegar",
  "KavenegarApiKey": "YOUR_API_KEY",
  "Sender": "10008663"
}

Background Worker

// Cron: "5 0 * * 0" = Every Sunday at 00:05 UTC
RecurringJob.AddOrUpdate<WeeklyCommissionJob>(
    "weekly-commission-calculation",
    job => job.ExecuteAsync(CancellationToken.None),
    "5 0 * * 0");

---

🧪 Testing

Manual Trigger (via API)

# Trigger weekly calculation immediately
curl -X POST http://localhost:5133/api/admin/trigger-weekly-calculation

# Trigger recurring job now
curl -X POST http://localhost:5133/api/admin/trigger-recurring-job-now

# Get recurring jobs status
curl http://localhost:5133/api/admin/recurring-jobs-status

Health Checks

curl http://localhost:5133/health         # Overall health
curl http://localhost:5133/health/ready   # Readiness probe (K8s)
curl http://localhost:5133/health/live    # Liveness probe (K8s)

---

📊 What's Remaining?

High Priority

1. Payment Gateway Integration (Phase 10 - 1 week)

   • Daya API integration (فقط برای Payout)
   • IBAN transfer automation
   • Admin approval UI in BackOffice

2. Production Configuration (30 minutes)

   • Gmail App Password setup
   • Kavenegar API key registration
   • Update appsettings.Production.json

Medium Priority

3. Club Shop Integration (Phase 9 - 2 weeks)
   • Product catalog for club memberships
   • Shopping cart integration
   • Auto-activation on purchase

Low Priority

4. Testing (Phase 7 - Postponed)
   • Unit tests for business logic
   • Integration tests for API
   • Load testing for background worker

Optional Enhancements

• Redis distributed locks (multi-server deployment)
• Sentry error tracking (API key needed)
• Slack notifications (webhook needed)
• FCM push notifications

---

🎯 MVP Features (100% Complete)

✅ Binary network tree with automatic placement
✅ Club membership (Member/Trial) with different commission rates
✅ Weekly commission calculation (Lesser Leg algorithm)
✅ Background worker with Hangfire (cron scheduling)
✅ Balance carryover logic (rollover unused volumes)
✅ MaxWeeklyBalances cap enforcement
✅ Health check endpoints (Kubernetes-ready)
✅ Manual trigger API (admin control)
✅ Email + SMS notifications (MailKit + Kavenegar)
✅ Retry logic with exponential backoff (Polly)
✅ Audit trail (WorkerExecutionLog, History tables)
✅ Structured logging (AlertService for Sentry/Slack)
✅ JWT authentication context (CurrentUserService)

---

👥 Team

Development: FourSat Team
Last Updated: 2025-12-01

---

📝 License

Proprietary - FourSat Company