CMS/README.md

# CMS Microservice - Network & Club Commission System

[![Status](https://img.shields.io/badge/Status-Production%20Ready-success)]()
[![Progress](https://img.shields.io/badge/Progress-85%25-blue)]()
[![MVP](https://img.shields.io/badge/MVP-100%25%20Complete-brightgreen)]()

## 📊 Project Status (2025-12-01)

**Overall Progress**: 85% Complete (7/10 phases)  
**Production Readiness**: 95%  
**MVP Status**: ✅ 100% Complete

### ✅ Completed Phases (7)
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

### 🟡 Partially Complete (1)
- Phase 10: Withdrawal & Settlement (40%)
  - ✅ Commands & Database
  - ❌ Payment Gateway Integration

### ❌ Not Started (1)
- Phase 9: Club Shop & Product Integration (0%)

### ⏸️ Postponed (1)
- Phase 7: Testing (Unit, Integration, Load tests)

---

## 🚀 Recent Updates (2025-12-01)

### Email & SMS Notifications - COMPLETED ✅
- ✅ **MailKit 4.14.1** for Email (SMTP with HTML templates)
- ✅ **Kavenegar 1.2.5** for SMS (Iranian SMS gateway)
- ✅ User.Email field added with migration
- ✅ 3 notification types: Commission, Club activation, Errors
- ✅ Persian RTL templates with rich formatting
- ✅ Production configuration guide created

### Hangfire Job Scheduling - COMPLETED ✅
- ✅ Dashboard UI at `/hangfire`
- ✅ Cron schedule: Sunday 00:05 UTC
- ✅ SQL Server persistence
- ✅ Manual trigger API endpoints
- ✅ Distributed execution support

### Infrastructure Enhancements - COMPLETED ✅
- ✅ Health Check endpoints (`/health`, `/health/ready`, `/health/live`)
- ✅ AlertService (structured logging for Sentry/Slack)
- ✅ Retry logic (Polly 8.5.0 with exponential backoff)
- ✅ WorkerExecutionLog (database audit trail)
- ✅ CurrentUserService (JWT authentication context)

---

## 🏗️ 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](docs/implementation-progress.md)** - Detailed phase-by-phase progress
- **[Email/SMS Configuration Guide](docs/email-sms-configuration-guide.md)** - Production setup instructions
- **[Balance Calculation Logic](docs/balance-calculation-carryover-logic.md)** - Commission algorithm details
- **[Binary Tree Registration](docs/binary-tree-registration-guide.md)** - Network tree guide
- **[Network Club Commission System](docs/network-club-commission-system-v1.1.md)** - 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
```bash
cd /home/masoud/Apps/project/FourSat/CMS/src
dotnet build
```

### 2. Configure Database
Update `appsettings.json` with your SQL Server connection:
```json
"ConnectionStrings": {
  "DefaultConnection": "Server=YOUR_SERVER;Database=Foursat_CMS;..."
}
```

### 3. Apply Migrations
```bash
cd CMSMicroservice.WebApi
dotnet ef database update
```

### 4. Configure Notifications (Optional)
See [Email/SMS Configuration Guide](docs/email-sms-configuration-guide.md)

### 5. Run
```bash
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)
```json
"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)
```json
"Sms": {
  "Enabled": true,
  "Provider": "Kavenegar",
  "KavenegarApiKey": "YOUR_API_KEY",
  "Sender": "10008663"
}
```

### Background Worker
```csharp
// 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)
```bash
# 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
```bash
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 or Bank Mellat API integration
   - 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