docs: move README to totalDoc, replace with placeholder

2026-02-18 21:44:39 +03:30
parent bc710fdb7b
commit f968a6c005
2 changed files with 2 additions and 528 deletions
@@ -1,445 +1,3 @@
-# CMS Microservice - Network & Club Commission + Inventory Management System
+# CMS Microservice
-[![Status](https://img.shields.io/badge/Status-Active%20Development-success)]()
+Documentation moved to [totalDoc/INDEX.md](../totalDoc/INDEX.md).
 [![Progress](https://img.shields.io/badge/Inventory%20System-Phase%202%20Complete-blue)]()
 [![Phase](https://img.shields.io/badge/Next-Business%20Services-orange)]()
 ## 📊 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
@@ -1,84 +0,0 @@
 {
  "PaymentProvider": "zarinpal",
  "ZarinPal": {
    "MerchantId": "00000000-0000-0000-0000-000000000000",
    "UseSandbox": true
  },
  "CmsBaseUrl": "http://localhost:32847",
  "FrontOfficeBaseUrl": "http://localhost:5268",
  "JwtSecurityKey": "TvlZVx5TJaHs8e9HgUdGzhGP2CIidoI444nAj+8+g7c=",
  "JwtIssuer": "https://localhost",
  "JwtAudience": "https://localhost",
  "JwtExpiryInDays": 5,
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=194.5.195.53,31433; Initial Catalog=Foursat;User ID=sa;Password=87zH26nbqT;Connection Timeout=300000;MultipleActiveResultSets=True;Encrypt=False",
    "providerName": "System.Data.SqlClient"
  },
  "Otp": {
    "Secret": "K2w8k1h1mH2Qz1kqWk0c8kQ2Pq8q9H1eE2nqN1qQ8x7M="
  },
  "Monitoring": {
    "SentryEnabled": false,
    "SentryDsn": "",
    "SlackEnabled": false,
    "SlackWebhookUrl": "",
    "EmailAlertsEnabled": false,
    "AdminEmails": [
      "admin@example.com"
    ],
    "SmsNotificationsEnabled": false,
    "SmsApiKey": "",
    "SmsGatewayUrl": ""
  },
  "Email": {
    "Enabled": true,
    "SmtpHost": "smtp.gmail.com",
    "SmtpPort": 587,
    "SmtpUsername": "your-email@gmail.com",
    "SmtpPassword": "your-app-password",
    "FromEmail": "noreply@foursat.com",
    "FromName": "FourSat CMS",
    "EnableSsl": true
  },
  "Sms": {
    "Enabled": true,
    "Provider": "Kavenegar",
    "KavenegarApiKey": "497263626F32626A48685A6137524C4F78575A766E4C74694A556B79317648424964655030682B554545413D",
    "Sender": "1000001110100"
  },
  "DayaPayment": {
    "BaseUrl": "https://api.daya.ir",
    "ApiKey": "YOUR_DAYA_API_KEY"
  },
  "DayaApi": {
    "UseMock": false,
    "BaseAddress": "https://Dayadiamond.ir",
    "MerchantPermissionKey": "56146364$04sXjethI5WxhItR1Q9xnmFdJzl2BB8Bclsq8dAy7YVSZp3vtt-wP7ivrcCvmKLq",
    "CacheDurationMinutes": 20
  },
  "Chatika": {
    "Enabled": true,
    "BaseUrl": "https://api.chatika.ir",
    "ApiKey": "tIukvL8dnV4cB3yVWcCD9Xyfbj8rBxm5wPt2mLyJCgTsBBoMTWjt6mFEqQwpw-er"
  },
  "BackgroundJobs": {
    "WeeklyCommissionCalculation": {
      "Enabled": true,
      "CronExpression": "5 0 * * 0"
    }
  },
  "AllowedHosts": "*",
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http2"
    }
  },
  "Authentication": {
    "Authority": "https://ids.domain.com/",
    "Audience": "domain_api"
  },
  "Seq": {
    "ServerUrl": "https://seq.afrino.co",
    "ApiKey": "oxpvpUzU1pZxMS4s3Fqq"
  }
 }