masoodafar-web
251 lines
6.8 KiB
Markdown
251 lines
6.8 KiB
Markdown
# 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](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 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
|