update

2026-01-03 18:27:49 +03:30
parent 0369292d7f
commit 5965b98728
156 changed files with 16082 additions and 0 deletions
@@ -0,0 +1,270 @@
+# 🏢 CMS Microservice Documentation
+
+> **آخرین بروزرسانی**: January 3, 2026  
+> **Framework**: .NET 9.0 + Clean Architecture + CQRS  
+> **Database**: PostgreSQL  
+> **Build Status**: ✅ SUCCESS
+
+---
+
+## 📊 وضعیت کلی
+
+| سیستم | پیشرفت | وضعیت |
+|-------|--------|--------|
+| Commission System | 85% | ✅ Production Ready |
+| Network System | 90% | ✅ Production Ready |
+| Club Membership | 95% | ✅ Production Ready |
+| Inventory System | 80% | ✅ Phase 2 Complete |
+| Email/SMS | 100% | ✅ Complete |
+
+---
+
+## 🏗️ معماری
+
+### Clean Architecture (4 لایه)
+
+```
+CMSMicroservice/
+├── CMSMicroservice.Domain/           # Entities, Enums, Interfaces
+├── CMSMicroservice.Application/      # CQRS Commands/Queries, MediatR
+├── CMSMicroservice.Infrastructure/   # DbContext, Services, Repositories
+└── CMSMicroservice.WebApi/           # Controllers, gRPC Services
+```
+
+### الگوی استاندارد
+
+- ✅ **CQRS** با MediatR
+- ✅ **IApplicationDbContext** برای دسترسی به DB (بدون Repository Pattern)
+- ✅ **Mapster** برای mapping
+- ✅ **FluentValidation** برای validation
+
+---
+
+## 💼 Commission System
+
+### ویژگی‌های اصلی:
+- ✅ Binary network tree با placement خودکار
+- ✅ عضویت باشگاه (Member/Trial) با نرخ‌های کمیسیون
+- ✅ محاسبه کمیسیون هفتگی (الگوریتم Lesser Leg)
+- ✅ Background worker با Hangfire
+- ✅ Health check endpoints
+
+### الگوریتم محاسبه:
+
+```
+Weekly Commission = (Lesser Leg Balance × Rate) / Total Balances
+```
+
+**نرخ‌ها**:
+| عضویت | نرخ |
+|-------|-----|
+| Member | 10% |
+| Trial | 5% |
+
+---
+
+## 🏪 Inventory System
+
+### Domain Layer:
+
+| Entity | توضیحات |
+|--------|---------|
+| `InventoryItem` | ردیابی موجودی محصول در هر انبار |
+| `StockMovement` | تاریخچه حرکات موجودی |
+| `Warehouse` | مدیریت انبارها |
+
+### StockMovementType:
+
+| Type | Code | توضیحات |
+|------|------|---------|
+| `MovementTypeUnspecified` | 0 | نامشخص |
+| `InitialStock` | 10 | موجودی اولیه |
+| `Purchase` | 20 | خرید از تامین‌کننده |
+| `Sale` | 30 | فروش به مشتری |
+| `Return` | 40 | برگشت از فروش |
+| `Adjustment` | 50 | تنظیم موجودی |
+| `Loss` | 60 | ضایعات/خسارت |
+| `Transfer` | 70 | انتقال بین انبار |
+| `Reservation` | 80 | رزرو برای سفارش |
+
+### CQRS Commands (17):
+
+**Inventory:**
+- `CreateInventoryItem`
+- `UpdateInventoryItem`
+- `DeleteInventoryItem`
+- `UpdateInventoryQuantity`
+- `ReserveInventory`
+- `ReleaseReservedInventory`
+- `ReduceInventory`
+- `IncreaseInventory`
+
+**Movement:**
+- `CreateStockMovement`
+- `BulkCreateStockMovement`
+- `DeleteStockMovement`
+
+**Warehouse:**
+- `CreateWarehouse`
+- `UpdateWarehouse`
+- `DeleteWarehouse`
+- `SetDefaultWarehouse`
+- `ActivateWarehouse`
+- `BulkCreateWarehouse`
+
+### CQRS Queries (35):
+
+**Inventory:**
+- `GetInventoryItem`
+- `GetInventoryByProduct`
+- `GetAllInventoryItems`
+- `GetLowStockItems`
+- `GetOutOfStockItems`
+- `CheckAvailability`
+- `SearchInventory`
+
+**Movement:**
+- `GetStockMovements`
+- `GetStockMovementsByInventoryItem`
+- `GetMovementHistory`
+- `GetDailyVolume`
+- `GetTopMovingProducts`
+- `SearchStockMovements`
+
+**Warehouse:**
+- `GetWarehouse`
+- `GetAllWarehouses`
+- `GetWarehouseStats`
+- `GetWarehouseLowStock`
+- `SearchWarehouses`
+
+---
+
+## 📧 Email & SMS Notifications
+
+### پیکربندی:
+
+**Email (MailKit 4.14.1)**:
+```json
+{
+  "Email": {
+    "Host": "smtp.example.com",
+    "Port": 587,
+    "Username": "noreply@foursat.com",
+    "Password": "xxx",
+    "SenderName": "FourSat System"
+  }
+}
+```
+
+**SMS (Kavenegar 1.2.5)**:
+```json
+{
+  "Kavenegar": {
+    "ApiKey": "xxx",
+    "Sender": "10008663"
+  }
+}
+```
+
+### انواع نوتیفیکیشن:
+- ✅ Commission notification (هفتگی)
+- ✅ Club activation notification
+- ✅ Error alerts
+
+---
+
+## ⏰ Hangfire Job Scheduling
+
+### داشبورد:
+```
+URL: https://cms.se.kbs1.ir/hangfire
+```
+
+### Job های زمان‌بندی شده:
+
+| Job | Schedule | توضیحات |
+|-----|----------|---------|
+| WeeklyCommissionCalculation | یکشنبه 00:05 UTC | محاسبه کمیسیون هفتگی |
+
+### API های Manual Trigger:
+```
+POST /api/commission/calculate
+POST /api/commission/process-week?weekNumber=2026-W01
+```
+
+---
+
+## 🏥 Health Checks
+
+### Endpoints:
+
+| Endpoint | استفاده |
+|----------|---------|
+| `/health` | وضعیت کلی |
+| `/health/ready` | Readiness probe (K8s) |
+| `/health/live` | Liveness probe (K8s) |
+
+### Example Response:
+```json
+{
+  "status": "Healthy",
+  "checks": [
+    { "name": "database", "status": "Healthy" },
+    { "name": "redis", "status": "Healthy" }
+  ]
+}
+```
+
+---
+
+## 🔧 Proto Sync (January 3, 2026)
+
+### تغییرات enum در Inventory:
+
+| آیتم | قبل | بعد |
+|------|-----|-----|
+| ProductType | `REGULAR`, `DISCOUNT` | `REGULAR_PRODUCT`, `DISCOUNT_PRODUCT` |
+| StockMovementType | Sequential (0-9) | Grouped (10, 20, 30...) |
+
+### تغییرات فیلد:
+
+| قبل | بعد |
+|-----|-----|
+| `page_index` | `page` |
+| `search_term` | `search` |
+| `product_name` | `product_title` |
+| `active_only` | `is_active` |
+| `created_at` | `created` |
+
+---
+
+## 🚀 Build & Run
+
+### Local Development:
+```bash
+cd CMS/src
+dotnet build CMS.sln
+dotnet run --project CMSMicroservice.WebApi
+```
+
+### Docker:
+```bash
+cd CMS
+docker build -t cms:latest .
+docker run -p 5000:80 cms:latest
+```
+
+### Environment Variables:
+```bash
+ASPNETCORE_ENVIRONMENT=Staging
+ConnectionStrings__DefaultConnection=Host=...;Database=...
+```
+
+---
+
+## 📚 مستندات مرتبط
+
+- [BackOffice Documentation](./01-BACKOFFICE.md)
+- [Proto Guide](./02-PROTO-GUIDE.md)
+- [Deployment Guide](./05-DEPLOYMENT.md)