update
This commit is contained in:
masoodafar-web
@@ -0,0 +1,445 @@
|
||||
# CMS Microservice - Network & Club Commission + Inventory Management System
|
||||
|
||||
[]()
|
||||
[]()
|
||||
[]()
|
||||
|
||||
## 📊 Project Status (January 2026)
|
||||
|
||||
### 🏪 Inventory Management System - NEW!
|
||||
**Progress**: Phase 2 Complete (50%)
|
||||
**Architecture**: Clean Architecture + CQRS + Repository Pattern
|
||||
|
||||
#### ✅ Completed Phases
|
||||
1. ✅ **Phase 1: Infrastructure & Domain Layer**
|
||||
- Domain Entities: `InventoryItem`, `StockMovement`, `Warehouse`
|
||||
- Domain Enums: `StockMovementType`
|
||||
- EF Core Configurations with proper indexing
|
||||
- Database migration applied
|
||||
|
||||
2. ✅ **Phase 2: Repository Pattern & CQRS**
|
||||
- Repository Interfaces & Implementations
|
||||
- CQRS Commands (17 commands)
|
||||
- CQRS Queries (35 queries)
|
||||
- MediatR Handlers (52 handlers)
|
||||
|
||||
#### 🔄 In Progress
|
||||
3. 🔄 **Phase 3: Business Services Layer**
|
||||
4. ⏳ **Phase 4: DTOs & AutoMapper**
|
||||
5. ⏳ **Phase 5: API Controllers**
|
||||
|
||||
---
|
||||
|
||||
### 💼 Commission System - Production Ready
|
||||
**Progress**: 85% Complete
|
||||
**MVP Status**: ✅ 100% Complete
|
||||
|
||||
#### ✅ Completed Features
|
||||
- ✅ Binary network tree with automatic placement
|
||||
- ✅ Club membership (Member/Trial) with commission rates
|
||||
- ✅ Weekly commission calculation (Lesser Leg algorithm)
|
||||
- ✅ Background worker with Hangfire
|
||||
- ✅ Email + SMS notifications (MailKit + Kavenegar)
|
||||
- ✅ Health check endpoints (Kubernetes-ready)
|
||||
|
||||
### 🟡 Partially Complete
|
||||
- Phase 10: Withdrawal & Settlement (40%)
|
||||
- ✅ Commands & Database
|
||||
- ❌ Payment Gateway Integration
|
||||
|
||||
### ❌ Not Started
|
||||
- Phase 9: Club Shop & Product Integration (0%)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Recent Updates (January 2026)
|
||||
|
||||
### 🏪 Inventory Management System - NEW! ✅
|
||||
**Complete CQRS-based inventory management with:**
|
||||
|
||||
#### Domain Layer:
|
||||
- ✅ `InventoryItem` - Multi-warehouse product tracking with min/max thresholds
|
||||
- ✅ `StockMovement` - Complete audit trail with 8 movement types
|
||||
- ✅ `Warehouse` - Multi-location support with default warehouse
|
||||
|
||||
#### Repository Pattern:
|
||||
- ✅ `IInventoryItemRepository` - 25+ methods for inventory operations
|
||||
- ✅ `IStockMovementRepository` - Movement tracking & analytics
|
||||
- ✅ `IWarehouseRepository` - Warehouse management & statistics
|
||||
|
||||
#### CQRS Commands (17 total):
|
||||
- **Inventory:** Create, Update, Delete, Reserve, Release, Reduce, Increase
|
||||
- **Movement:** Create, BulkCreate, Delete
|
||||
- **Warehouse:** Create, Update, Delete, SetDefault, Activate, BulkCreate
|
||||
|
||||
#### CQRS Queries (35 total):
|
||||
- **Inventory:** GetById, Search, LowStock, OutOfStock, CheckAvailability
|
||||
- **Movement:** GetHistory, GetByOrder, Search, Analytics, DailyVolume, TopMoving
|
||||
- **Warehouse:** GetById, Search, GetStats, GetLowStock, GetAllStats
|
||||
|
||||
#### Business Features:
|
||||
- ✅ Multi-warehouse inventory management
|
||||
- ✅ Stock reservation system for orders
|
||||
- ✅ Automatic movement tracking
|
||||
- ✅ Low stock & out-of-stock alerts
|
||||
- ✅ Advanced analytics & reporting
|
||||
- ✅ Bulk operations support
|
||||
- ✅ Transaction-safe operations
|
||||
|
||||
---
|
||||
|
||||
### 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
|
||||
├── Entities/
|
||||
│ ├── InventoryItem.cs # NEW: Inventory tracking
|
||||
│ ├── StockMovement.cs # NEW: Movement audit
|
||||
│ └── Warehouse.cs # NEW: Multi-warehouse
|
||||
├── Enums/
|
||||
│ └── StockMovementType.cs # NEW: Movement types
|
||||
|
||||
CMSMicroservice.Application/ # CQRS (Commands, Queries, MediatR)
|
||||
├── Features/
|
||||
│ ├── InventoryItems/ # NEW: Inventory CQRS
|
||||
│ │ ├── Commands/
|
||||
│ │ ├── Queries/
|
||||
│ │ └── Handlers/
|
||||
│ ├── StockMovements/ # NEW: Movement CQRS
|
||||
│ │ ├── Commands/
|
||||
│ │ ├── Queries/
|
||||
│ │ └── Handlers/
|
||||
│ └── Warehouses/ # NEW: Warehouse CQRS
|
||||
│ ├── Commands/
|
||||
│ ├── Queries/
|
||||
│ └── Handlers/
|
||||
└── Common/Interfaces/
|
||||
└── Repositories/ # NEW: Repository interfaces
|
||||
|
||||
CMSMicroservice.Infrastructure/ # DbContext, Services, Background Jobs
|
||||
├── Persistence/
|
||||
│ ├── Context/
|
||||
│ ├── Configurations/ # NEW: EF Core configs
|
||||
│ ├── Repositories/ # NEW: Repository implementations
|
||||
│ └── Migrations/
|
||||
└── DependencyInjection.cs # NEW: DI setup
|
||||
|
||||
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
|
||||
|
||||
- **[Development Plan](docs/development-plan.md)** - NEW: Inventory system roadmap
|
||||
- **[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
|
||||
|
||||
---
|
||||
|
||||
## 🏪 Inventory System Usage
|
||||
|
||||
### Create Warehouse
|
||||
```csharp
|
||||
await mediator.Send(new CreateWarehouseCommand
|
||||
{
|
||||
Name = "Main Warehouse",
|
||||
Code = "WH-001",
|
||||
IsDefault = true,
|
||||
IsActive = true
|
||||
});
|
||||
```
|
||||
|
||||
### Create Inventory Item
|
||||
```csharp
|
||||
await mediator.Send(new CreateInventoryItemCommand
|
||||
{
|
||||
ProductId = 1,
|
||||
WarehouseId = 1,
|
||||
Quantity = 100,
|
||||
MinQuantity = 10,
|
||||
MaxQuantity = 1000
|
||||
});
|
||||
```
|
||||
|
||||
### Reserve Stock for Order
|
||||
```csharp
|
||||
await mediator.Send(new ReserveInventoryCommand
|
||||
{
|
||||
Id = inventoryId,
|
||||
Quantity = 5,
|
||||
OrderId = 12345
|
||||
});
|
||||
```
|
||||
|
||||
### Check Availability
|
||||
```csharp
|
||||
bool available = await mediator.Send(
|
||||
new CheckInventoryAvailabilityQuery(inventoryId, 10));
|
||||
```
|
||||
|
||||
### Get Low Stock Alerts
|
||||
```csharp
|
||||
var lowStock = await mediator.Send(new GetLowStockItemsQuery
|
||||
{
|
||||
WarehouseId = 1,
|
||||
Count = 50
|
||||
});
|
||||
```
|
||||
|
||||
### Get Movement Analytics
|
||||
```csharp
|
||||
var summary = await mediator.Send(new GetMovementSummaryQuery
|
||||
{
|
||||
FromDate = DateTime.Now.AddDays(-7),
|
||||
ToDate = DateTime.Now
|
||||
});
|
||||
|
||||
var topProducts = await mediator.Send(new GetTopMovingProductsQuery
|
||||
{
|
||||
FromDate = DateTime.Now.AddDays(-30),
|
||||
ToDate = DateTime.Now,
|
||||
Count = 10
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 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?
|
||||
|
||||
### 🏪 Inventory System (Current Focus)
|
||||
1. **Phase 3: Business Services** (In Progress)
|
||||
- `IInventoryManagementService` - High-level operations
|
||||
- `IStockMovementService` - Movement orchestration
|
||||
- `IWarehouseService` - Warehouse business logic
|
||||
- `IInventoryReportingService` - Advanced reporting
|
||||
|
||||
2. **Phase 4: DTOs & AutoMapper** (Next)
|
||||
- Request/Response DTOs
|
||||
- AutoMapper profiles
|
||||
- Validation rules
|
||||
|
||||
3. **Phase 5: API Controllers** (Planned)
|
||||
- `InventoryController` - REST API
|
||||
- `WarehouseController` - Warehouse management
|
||||
- `StockMovementController` - Movement tracking
|
||||
- Swagger documentation
|
||||
|
||||
### 💼 Commission System
|
||||
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)
|
||||
|
||||
### 💼 Commission System:
|
||||
✅ 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)
|
||||
|
||||
### 🏪 Inventory System (Phase 2 Complete):
|
||||
✅ Domain entities (InventoryItem, StockMovement, Warehouse)
|
||||
✅ Multi-warehouse inventory management
|
||||
✅ Stock reservation system for orders
|
||||
✅ 8 movement types with complete audit trail
|
||||
✅ Repository pattern with 25+ methods per repository
|
||||
✅ CQRS with 17 commands and 35 queries
|
||||
✅ 52 MediatR handlers with business logic
|
||||
✅ Low stock and out-of-stock alerts
|
||||
✅ Advanced analytics (top products, daily volume)
|
||||
✅ Bulk operations support
|
||||
✅ Transaction-safe operations with rollback
|
||||
✅ DI container configuration
|
||||
|
||||
---
|
||||
|
||||
## 👥 Team
|
||||
|
||||
**Development**: FourSat Team
|
||||
**Last Updated**: January 2026
|
||||
|
||||
---
|
||||
|
||||
## 📝 License
|
||||
|
||||
Proprietary - FourSat Company
|
||||
# Multi-remote push enabled
|
||||
Reference in New Issue
Block a user