masoodafar-web
421a651975
- All 14 totalDoc files updated with Magic Wallet additions - MAGIC-WALLET-PLAN.md: Phase 1-6 checklist fully marked complete - Business docs: Magic Wallet section, commission filter, new entities - Payment docs: VAT 9%→10%, TransactionType 14+15, ZarinPal 4th usage - Technical docs: UserWallet fields, ClubMembershipCycle, gRPC RPCs - Overview docs: Magic flowchart, ER diagram, changelog, glossary, roadmap
272 lines
8.1 KiB
Markdown
272 lines
8.1 KiB
Markdown
# ⚙️ معماری CMS و زیرساخت فنی
|
||
|
||
> **منابع ادغامشده:** `CMS-README.md`, `ICURRENTUSERSERVICE-IMPLEMENTATION.md`, `FILE-MANAGEMENT-ARCHITECTURE.md`, `FRONTOFFICE-CMS-API-COMPATIBILITY.md`, `BFF-REMOVAL-PLAN.md`, `system-constants.md`
|
||
> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet entities + gRPC)
|
||
|
||
---
|
||
|
||
## ۱. Stack فنی
|
||
|
||
| لایه | تکنولوژی | نسخه |
|
||
|------|----------|------|
|
||
| **Runtime** | .NET | 9.0 |
|
||
| **ORM** | Entity Framework Core | 9.0 |
|
||
| **Communication** | gRPC (Protobuf) | v3 |
|
||
| **Pattern** | CQRS + MediatR | — |
|
||
| **Database** | SQL Server (MSSQL) | 2022-CU16 |
|
||
| **Job Scheduler** | Hangfire | — |
|
||
| **Auth** | JWT Bearer + Identity | — |
|
||
| **API Gateway** | حذفشده (Direct gRPC) | — |
|
||
|
||
---
|
||
|
||
## ۲. معماری لایهای CMS
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
subgraph PRES["💻 Presentation Layer"]
|
||
FO["FrontOffice\nBlazor Server"]
|
||
BO["BackOffice\nBlazor WASM"]
|
||
end
|
||
|
||
FO & BO -->|gRPC| APP
|
||
|
||
subgraph APP["⚙️ Application Layer"]
|
||
CMD["Commands\nMediatR IRequest"]
|
||
QRY["Queries\nMediatR IRequest"]
|
||
VAL["Validators\nFluentValidation"]
|
||
HND["Handlers\nIRequestHandler"]
|
||
end
|
||
|
||
APP --> DOM
|
||
|
||
subgraph DOM["📦 Domain Layer"]
|
||
ENT["Entities, Enums\nValue Objects\nDomain Events"]
|
||
end
|
||
|
||
DOM --> INF
|
||
|
||
subgraph INF["🔧 Infrastructure Layer"]
|
||
EF["EF Core DbContext"]
|
||
SVC["External Services"]
|
||
HF["Hangfire Jobs"]
|
||
FS["File Storage"]
|
||
end
|
||
|
||
INF --> DB[("🗄️ SQL Server\nSchema: CMS")]
|
||
```
|
||
|
||
---
|
||
|
||
## ۳. CQRS با MediatR
|
||
|
||
### ۳.۱ ساختار فولدرها
|
||
|
||
```
|
||
CMS/src/
|
||
├── CMSMicroservice/
|
||
│ ├── Features/
|
||
│ │ ├── Products/
|
||
│ │ │ ├── Commands/
|
||
│ │ │ │ ├── CreateProductCommand.cs
|
||
│ │ │ │ └── CreateProductCommandHandler.cs
|
||
│ │ │ ├── Queries/
|
||
│ │ │ │ ├── GetProductsQuery.cs
|
||
│ │ │ │ └── GetProductsQueryHandler.cs
|
||
│ │ │ └── Validators/
|
||
│ │ │ └── CreateProductCommandValidator.cs
|
||
│ │ ├── Orders/
|
||
│ │ ├── Users/
|
||
│ │ ├── Club/
|
||
│ │ ├── Payment/
|
||
│ │ └── Blog/
|
||
│ ├── Services/
|
||
│ │ ├── gRPC/ ← gRPC service implementations
|
||
│ │ ├── Background/ ← Hangfire jobs
|
||
│ │ └── External/ ← ZarinPal, Kavenegar, Daya, Chatika
|
||
│ ├── Infrastructure/
|
||
│ │ ├── Persistence/ ← DbContext, Migrations
|
||
│ │ └── Identity/ ← JWT, Claims, ICurrentUserService
|
||
│ └── Protos/ ← .proto files
|
||
```
|
||
|
||
### ۳.۲ مثال Command
|
||
|
||
```csharp
|
||
// Command
|
||
public record CreateProductCommand(
|
||
string Name, string Description, decimal Price,
|
||
Guid CategoryId, string ImageUrl
|
||
) : IRequest<Guid>;
|
||
|
||
// Handler
|
||
public class CreateProductCommandHandler
|
||
: IRequestHandler<CreateProductCommand, Guid>
|
||
{
|
||
private readonly CMSDbContext _db;
|
||
|
||
public async Task<Guid> Handle(
|
||
CreateProductCommand request, CancellationToken ct)
|
||
{
|
||
var product = new Product { /* map fields */ };
|
||
_db.Products.Add(product);
|
||
|
||
// Auto-create inventory record
|
||
_db.Inventories.Add(new Inventory { ProductId = product.Id });
|
||
|
||
await _db.SaveChangesAsync(ct);
|
||
return product.Id;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## ۴. gRPC Services
|
||
|
||
### ۴.۱ لیست سرویسها
|
||
|
||
| سرویس | proto | متدهای اصلی |
|
||
|--------|-------|-------------|
|
||
| `ProductService` | product.proto | GetProducts, GetProduct, Create, Update, Delete |
|
||
| `OrderService` | order.proto | CreateOrder, GetOrders, UpdateStatus |
|
||
| `UserService` | user.proto | Register, Login, GetProfile, UpdateProfile |
|
||
| `ClubService` | club.proto | GetNetworkTree, GetBalance, AcceptContract |
|
||
| `PaymentService` | payment.proto | CreatePayment, VerifyPayment |
|
||
| `BlogService` | blog.proto | GetPosts, GetPost, Create, Update |
|
||
| `InventoryService` | inventory.proto | GetInventory, UpdateStock |
|
||
| `FileService` | file.proto | Upload, Download, Delete |
|
||
| `SitePageService` | sitepage.proto | GetPage, SaveSettings |
|
||
| `CategoryService` | category.proto | GetCategories, Create, Update |
|
||
| `SystemConfigService` | config.proto | GetConfig, UpdateConfig |
|
||
| `UserWalletService` | userwallet.proto | GetCustomerWallet, InitiateMagicCharge, GetMagicWalletStatus |
|
||
|
||
### ۴.۲ PaginationState (مشترک)
|
||
|
||
```protobuf
|
||
message PaginationState {
|
||
int32 skip = 1;
|
||
int32 take = 2;
|
||
}
|
||
```
|
||
|
||
**Namespace صحیح:**
|
||
```csharp
|
||
using CMSMicroservice.Protobuf.Protos.PaginationState;
|
||
// ⚠️ نه: CMSMicroservice.Protobuf.Protos.PublicMessages.PaginationState
|
||
```
|
||
|
||
---
|
||
|
||
## ۵. Database
|
||
|
||
### ۵.۱ اتصال
|
||
|
||
```
|
||
Staging: Server=194.5.195.53; Database=FourSatCMS; Schema=CMS
|
||
Production: Server=45.149.79.127; Database=FourSatCMS; Schema=CMS
|
||
Engine: MSSQL 2022-CU16, Collation=Arabic_CI_AS
|
||
```
|
||
|
||
### ۵.۲ جداول اصلی
|
||
|
||
| جدول | توضیح | رکوردهای تقریبی |
|
||
|------|--------|----------------|
|
||
| Users | کاربران + فیلدهای شبکه (NetworkParentId, LegPosition) | ~5K |
|
||
| Products | محصولات (+ MaxDiscountPercent) | ~200 |
|
||
| Categories | دستهبندیها | ~30 |
|
||
| Orders | سفارشات | ~2K |
|
||
| Inventories | موجودی | ~200 |
|
||
| BlogPosts | پستهای بلاگ | ~50 |
|
||
| SitePages | صفحات سایت | ~10 |
|
||
| UserClubMemberships | عضویت باشگاه | ~500 |
|
||
| UserContracts | قراردادها (SignGuid, SignedPdfFile) | ~500 |
|
||
| UserWallets | کیفپول (Balance, NetworkBalance, DiscountBalance, WalletMode) | ~5K |
|
||
| ClubMembershipCycles | دورههای عضویت (CycleNumber, PackagePurchasedAt, IsCurrentCycle) | ~500 |
|
||
| Transactions | تراکنشها | ~5K |
|
||
| SystemConfigurations | تنظیمات | ~30 |
|
||
| ChatMessages | پیامهای چاتیکا | ~1K |
|
||
|
||
### ۵.۳ Stored Procedures
|
||
|
||
| SP | کاربرد |
|
||
|----|--------|
|
||
| `SP_GetNetworkTree` | بازگشتی — استخراج درخت باینری |
|
||
| `sp_CalculateWeeklyBalances` | محاسبه بالانس هفتگی هر عضو |
|
||
| `sp_CalculateWeeklyCommissionPool` | توزیع Pool هفتگی |
|
||
|
||
---
|
||
|
||
## ۶. حذف BFF / Gateway
|
||
|
||
### ۶.۱ قبل vs بعد
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph BEFORE["قبل"]
|
||
F1["FrontOffice"] -->|REST| BFF1["BFF"]
|
||
B1["BackOffice"] -->|REST| BFF1
|
||
BFF1 -->|gRPC| C1["CMS"]
|
||
end
|
||
|
||
subgraph AFTER["بعد — فعلی ✅"]
|
||
F2["FrontOffice"] -->|gRPC| C2["CMS"]
|
||
B2["BackOffice"] -->|gRPC| C2
|
||
end
|
||
```
|
||
|
||
> مزایا: حذف لایه واسط → کاهش latency • Type-safe از proto تا UI • کاهش ۱ سرویس در deployment
|
||
|
||
### ۶.۲ سازگاری API
|
||
|
||
```
|
||
FrontOffice Service Layer:
|
||
• ProductService.cs → gRPC client wrapper
|
||
• OrderService.cs → gRPC client wrapper
|
||
• UserService.cs → gRPC client wrapper
|
||
|
||
هر Service:
|
||
• Constructor: inject GrpcChannel
|
||
• Methods: wrap gRPC calls + map to DTOs
|
||
• Error handling: try/catch RpcException
|
||
```
|
||
|
||
---
|
||
|
||
## ۷. Hangfire Jobs
|
||
|
||
| Job | فرکانس (cron) | کاربرد |
|
||
|-----|---------|--------|
|
||
| `WeeklyCommissionCalculation` | `5 0 * * 0` (یکشنبه ۰۰:۰۵) | محاسبه و توزیع کمیسیون |
|
||
| `DayaLoanProcessorJob` | `*/20 * * * *` (هر ۲۰ دقیقه) | پردازش درخواستهای وام |
|
||
| `ChatikaAccountActivation` | `*/5 * * * *` (هر ۵ دقیقه) | فعالسازی حساب چاتیکا |
|
||
|
||
---
|
||
|
||
## ۸. پیکربندی
|
||
|
||
### ۸.۱ appsettings.json ساختار
|
||
|
||
```json
|
||
{
|
||
"ConnectionStrings": {
|
||
"DefaultConnection": "Server=...;Database=FourSatCMS"
|
||
},
|
||
"Jwt": {
|
||
"Secret": "***",
|
||
"Issuer": "FourSat",
|
||
"ExpiryMinutes": 1440
|
||
},
|
||
"Grpc": {
|
||
"CmsUrl": "https://localhost:5001"
|
||
},
|
||
"Hangfire": {
|
||
"DashboardPath": "/hangfire",
|
||
"WorkerCount": 4
|
||
},
|
||
"Kavenegar": { "ApiKey": "***" },
|
||
"ZarinPal": { "MerchantId": "***" },
|
||
"DayaLoan": { "UseMock": true }
|
||
}
|
||
```
|