feat: Add ClearCart command and response, implement CancelOrder command with validation, and enhance DeliveryStatus and User models
This commit is contained in:
masoodafar-web
@@ -1,420 +0,0 @@
|
||||
# Balance Calculation with Carryover Logic - Complete Guide
|
||||
|
||||
**Date**: 2025-12-01
|
||||
**Last Updated**: 2025-12-01 (Added Configuration Integration + MaxWeeklyBalances Cap)
|
||||
**Status**: ✅ Implemented
|
||||
**Migration**: `UpdateNetworkWeeklyBalanceWithCarryover`
|
||||
|
||||
---
|
||||
|
||||
## 📋 Configuration-Based Calculation
|
||||
|
||||
### **System Configurations Used:**
|
||||
|
||||
```csharp
|
||||
// تمام مقادیر از جدول SystemConfigurations خوانده میشوند
|
||||
Club.ActivationFee = 25,000,000 ریال (هزینه فعالسازی)
|
||||
Commission.WeeklyPoolContributionPercent = 20% (سهم استخر)
|
||||
Commission.MaxWeeklyBalancesPerUser = 300 (سقف تعادل هفتگی)
|
||||
```
|
||||
|
||||
### **Pool Contribution Calculation:**
|
||||
|
||||
```csharp
|
||||
totalNewMembers = leftNewMembers + rightNewMembers
|
||||
weeklyPoolContribution = totalNewMembers × activationFee × poolPercent
|
||||
= totalNewMembers × 25,000,000 × 20%
|
||||
= totalNewMembers × 5,000,000
|
||||
```
|
||||
|
||||
**مثال:**
|
||||
اگر 10 نفر جدید جذب شوند: `10 × 5,000,000 = 50,000,000` ریال به استخر اضافه میشود.
|
||||
|
||||
---
|
||||
|
||||
## 🚫 MaxWeeklyBalances Cap (محدودیت سقف)
|
||||
|
||||
### **Logic:**
|
||||
|
||||
```csharp
|
||||
totalBalances = MIN(leftTotal, rightTotal)
|
||||
cappedBalances = MIN(totalBalances, maxWeeklyBalances) // 300
|
||||
|
||||
// اگر بیشتر از سقف بود، مازاد به remainder اضافه میشود
|
||||
excessBalances = totalBalances - cappedBalances
|
||||
```
|
||||
|
||||
### **Example:**
|
||||
|
||||
```
|
||||
Week 5:
|
||||
leftTotal = 350, rightTotal = 400
|
||||
totalBalances = MIN(350, 400) = 350
|
||||
cappedBalances = MIN(350, 300) = 300 ✅ محدود شد!
|
||||
excessBalances = 350 - 300 = 50
|
||||
|
||||
leftRemainder = 0 + 50 = 50 (میرود برای هفته بعد)
|
||||
rightRemainder = 50
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Problem Statement
|
||||
|
||||
### ❌ **Previous (Incorrect) Logic:**
|
||||
|
||||
```csharp
|
||||
// محاسبه تعداد کل اعضا در هر پا
|
||||
leftLegBalances = CountAllMembers(userId, Left);
|
||||
rightLegBalances = CountAllMembers(userId, Right);
|
||||
|
||||
// تعادل = کمترین مقدار
|
||||
TotalBalances = MIN(leftLegBalances, rightLegBalances);
|
||||
```
|
||||
|
||||
**مشکلات:**
|
||||
1. تعداد کل اعضا را میشمارد (نه فقط جدیدها)
|
||||
2. باقیمانده هفته قبل را نادیده میگیرد
|
||||
3. هر هفته از صفر شروع میکند
|
||||
|
||||
---
|
||||
|
||||
## ✅ **Current (Correct) Logic:**
|
||||
|
||||
### **Formula:**
|
||||
```
|
||||
leftTotal = leftNewMembers + leftCarryover
|
||||
rightTotal = rightNewMembers + rightCarryover
|
||||
|
||||
TotalBalances = MIN(leftTotal, rightTotal)
|
||||
|
||||
leftRemainder = leftTotal - TotalBalances
|
||||
rightRemainder = rightTotal - TotalBalances
|
||||
```
|
||||
|
||||
### **Key Principles:**
|
||||
1. **Only count NEW members** activated in current week
|
||||
2. **Add carryover** from previous week
|
||||
3. **Calculate remainder** for next week
|
||||
4. **Recursive counting** through entire tree structure
|
||||
|
||||
---
|
||||
|
||||
## 🔢 Example Calculations
|
||||
|
||||
### **Week 1 (2025-W48):**
|
||||
|
||||
**Tree Structure:**
|
||||
```
|
||||
User A (Activated this week - 25M to pool)
|
||||
├─ Left: User B (Activated this week - 25M)
|
||||
└─ Right: User C (Activated this week - 25M)
|
||||
```
|
||||
|
||||
**Calculations:**
|
||||
```
|
||||
User A:
|
||||
leftNewMembers = 1 (User B activated)
|
||||
rightNewMembers = 1 (User C activated)
|
||||
leftCarryover = 0 (first week)
|
||||
rightCarryover = 0 (first week)
|
||||
|
||||
leftTotal = 1 + 0 = 1
|
||||
rightTotal = 1 + 0 = 1
|
||||
|
||||
TotalBalances = MIN(1, 1) = 1
|
||||
|
||||
leftRemainder = 1 - 1 = 0
|
||||
rightRemainder = 1 - 1 = 0
|
||||
|
||||
User B: TotalBalances = 0 (no children)
|
||||
User C: TotalBalances = 0 (no children)
|
||||
```
|
||||
|
||||
**Pool Calculation:**
|
||||
```
|
||||
Total Pool = 75M (3 activations × 25M)
|
||||
Total Balances = 1 (only User A)
|
||||
Value Per Balance = 75M ÷ 1 = 75M
|
||||
|
||||
Commission:
|
||||
User A = 1 × 75M = 75M
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **Week 2 (2025-W49):**
|
||||
|
||||
**Tree Structure:**
|
||||
```
|
||||
User A
|
||||
├─ Left: User B
|
||||
│ ├─ Left: User D (NEW - activated this week - 25M)
|
||||
│ └─ Right: User E (NEW - activated this week - 25M)
|
||||
└─ Right: User C
|
||||
├─ Left: User F (NEW - activated this week - 25M)
|
||||
└─ Right: User G (NEW - activated this week - 25M)
|
||||
```
|
||||
|
||||
**Calculations:**
|
||||
```
|
||||
User B:
|
||||
leftNewMembers = 1 (User D)
|
||||
rightNewMembers = 1 (User E)
|
||||
leftCarryover = 0
|
||||
rightCarryover = 0
|
||||
|
||||
leftTotal = 1 + 0 = 1
|
||||
rightTotal = 1 + 0 = 1
|
||||
TotalBalances = MIN(1, 1) = 1
|
||||
|
||||
User C:
|
||||
leftNewMembers = 1 (User F)
|
||||
rightNewMembers = 1 (User G)
|
||||
leftCarryover = 0
|
||||
rightCarryover = 0
|
||||
|
||||
leftTotal = 1 + 0 = 1
|
||||
rightTotal = 1 + 0 = 1
|
||||
TotalBalances = MIN(1, 1) = 1
|
||||
|
||||
User A:
|
||||
leftNewMembers = 2 (D & E through B)
|
||||
rightNewMembers = 2 (F & G through C)
|
||||
leftCarryover = 0 (from week 1)
|
||||
rightCarryover = 0 (from week 1)
|
||||
|
||||
leftTotal = 2 + 0 = 2
|
||||
rightTotal = 2 + 0 = 2
|
||||
TotalBalances = MIN(2, 2) = 2 ✅
|
||||
|
||||
leftRemainder = 2 - 2 = 0
|
||||
rightRemainder = 2 - 2 = 0
|
||||
```
|
||||
|
||||
**Pool Calculation:**
|
||||
```
|
||||
Total Pool = 100M (4 new activations × 25M)
|
||||
Total Balances = 4 (A=2, B=1, C=1)
|
||||
Value Per Balance = 100M ÷ 4 = 25M
|
||||
|
||||
Commission:
|
||||
User A = 2 × 25M = 50M ✅ (not 33.33M!)
|
||||
User B = 1 × 25M = 25M
|
||||
User C = 1 × 25M = 25M
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **Week 3 (2025-W50) - With Carryover:**
|
||||
|
||||
**Tree Structure:**
|
||||
```
|
||||
User A
|
||||
├─ Left: User B
|
||||
│ ├─ Left: User D
|
||||
│ │ └─ Left: User H (NEW - 25M)
|
||||
│ └─ Right: User E
|
||||
└─ Right: User C
|
||||
├─ Left: User F
|
||||
└─ Right: User G
|
||||
```
|
||||
|
||||
**Calculations:**
|
||||
```
|
||||
User D:
|
||||
leftNewMembers = 1 (User H)
|
||||
rightNewMembers = 0
|
||||
leftCarryover = 0
|
||||
rightCarryover = 0
|
||||
|
||||
leftTotal = 1 + 0 = 1
|
||||
rightTotal = 0 + 0 = 0
|
||||
TotalBalances = MIN(1, 0) = 0
|
||||
|
||||
leftRemainder = 1 - 0 = 1 ⚠️ (saved for next week)
|
||||
rightRemainder = 0 - 0 = 0
|
||||
|
||||
User B:
|
||||
leftNewMembers = 1 (H through D)
|
||||
rightNewMembers = 0
|
||||
leftCarryover = 0 (from week 2)
|
||||
rightCarryover = 0
|
||||
|
||||
leftTotal = 1 + 0 = 1
|
||||
rightTotal = 0 + 0 = 0
|
||||
TotalBalances = MIN(1, 0) = 0
|
||||
|
||||
leftRemainder = 1 - 0 = 1 ⚠️ (saved for next week)
|
||||
rightRemainder = 0 - 0 = 0
|
||||
|
||||
User A:
|
||||
leftNewMembers = 1 (H through B→D)
|
||||
rightNewMembers = 0
|
||||
leftCarryover = 0 (from week 2)
|
||||
rightCarryover = 0
|
||||
|
||||
leftTotal = 1 + 0 = 1
|
||||
rightTotal = 0 + 0 = 0
|
||||
TotalBalances = MIN(1, 0) = 0
|
||||
|
||||
leftRemainder = 1 - 0 = 1 ⚠️ (saved for next week)
|
||||
rightRemainder = 0 - 0 = 0
|
||||
```
|
||||
|
||||
**Pool Calculation:**
|
||||
```
|
||||
Total Pool = 25M (1 new activation)
|
||||
Total Balances = 0 (no balanced pairs)
|
||||
Value Per Balance = N/A
|
||||
|
||||
Commission: None this week
|
||||
Carryover: User A, B, D each have 1 leftRemainder for week 4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Database Schema
|
||||
|
||||
### **NetworkWeeklyBalance Table:**
|
||||
|
||||
```sql
|
||||
ALTER TABLE NetworkWeeklyBalances ADD:
|
||||
-- New members this week
|
||||
LeftLegNewMembers INT NOT NULL DEFAULT 0,
|
||||
RightLegNewMembers INT NOT NULL DEFAULT 0,
|
||||
|
||||
-- Carryover from previous week
|
||||
LeftLegCarryover INT NOT NULL DEFAULT 0,
|
||||
RightLegCarryover INT NOT NULL DEFAULT 0,
|
||||
|
||||
-- Totals (new + carryover)
|
||||
LeftLegTotal INT NOT NULL DEFAULT 0,
|
||||
RightLegTotal INT NOT NULL DEFAULT 0,
|
||||
|
||||
-- Remainder for next week
|
||||
LeftLegRemainder INT NOT NULL DEFAULT 0,
|
||||
RightLegRemainder INT NOT NULL DEFAULT 0
|
||||
```
|
||||
|
||||
**Deprecated Fields:**
|
||||
- `LeftLegBalances` (still exists for backward compatibility)
|
||||
- `RightLegBalances` (still exists for backward compatibility)
|
||||
|
||||
---
|
||||
|
||||
## 💻 Implementation
|
||||
|
||||
### **Handler: CalculateWeeklyBalancesCommandHandler.cs**
|
||||
|
||||
```csharp
|
||||
public async Task<int> Handle(CalculateWeeklyBalancesCommand request, CancellationToken cancellationToken)
|
||||
{
|
||||
// 1. Load previous week's carryover
|
||||
var previousWeekNumber = GetPreviousWeekNumber(request.WeekNumber);
|
||||
var previousWeekCarryovers = await _context.NetworkWeeklyBalances
|
||||
.Where(x => x.WeekNumber == previousWeekNumber)
|
||||
.ToDictionaryAsync(x => x.UserId, x => new { x.LeftLegRemainder, x.RightLegRemainder });
|
||||
|
||||
// 2. For each user in network
|
||||
foreach (var user in usersInNetwork)
|
||||
{
|
||||
// Get carryover
|
||||
var leftCarryover = previousWeekCarryovers.ContainsKey(user.Id)
|
||||
? previousWeekCarryovers[user.Id].LeftLegRemainder : 0;
|
||||
var rightCarryover = previousWeekCarryovers.ContainsKey(user.Id)
|
||||
? previousWeekCarryovers[user.Id].RightLegRemainder : 0;
|
||||
|
||||
// Count NEW members (activated in this week)
|
||||
var leftNewMembers = await CountNewMembersInLeg(user.Id, NetworkLeg.Left, request.WeekNumber);
|
||||
var rightNewMembers = await CountNewMembersInLeg(user.Id, NetworkLeg.Right, request.WeekNumber);
|
||||
|
||||
// Calculate totals
|
||||
var leftTotal = leftNewMembers + leftCarryover;
|
||||
var rightTotal = rightNewMembers + rightCarryover;
|
||||
|
||||
// Calculate balance (min)
|
||||
var totalBalances = Math.Min(leftTotal, rightTotal);
|
||||
|
||||
// Calculate remainder
|
||||
var leftRemainder = leftTotal - totalBalances;
|
||||
var rightRemainder = rightTotal - totalBalances;
|
||||
|
||||
// Save to database
|
||||
var balance = new NetworkWeeklyBalance
|
||||
{
|
||||
UserId = user.Id,
|
||||
WeekNumber = request.WeekNumber,
|
||||
LeftLegNewMembers = leftNewMembers,
|
||||
RightLegNewMembers = rightNewMembers,
|
||||
LeftLegCarryover = leftCarryover,
|
||||
RightLegCarryover = rightCarryover,
|
||||
LeftLegTotal = leftTotal,
|
||||
RightLegTotal = rightTotal,
|
||||
TotalBalances = totalBalances,
|
||||
LeftLegRemainder = leftRemainder,
|
||||
RightLegRemainder = rightRemainder,
|
||||
// ...
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
private async Task<int> CountNewMembersRecursive(long userId, NetworkLeg leg, DateTime startDate, DateTime endDate)
|
||||
{
|
||||
var child = await _context.Users
|
||||
.FirstOrDefaultAsync(x => x.NetworkParentId == userId && x.LegPosition == leg);
|
||||
|
||||
if (child == null) return 0;
|
||||
|
||||
var count = 0;
|
||||
|
||||
// Check if activated in this week
|
||||
var membership = await _context.ClubMemberships
|
||||
.FirstOrDefaultAsync(x => x.UserId == child.Id && x.IsActive);
|
||||
|
||||
if (membership?.ActivatedAt >= startDate && membership?.ActivatedAt <= endDate)
|
||||
{
|
||||
count = 1;
|
||||
}
|
||||
|
||||
// Recursively count children
|
||||
var childLeft = await CountNewMembersRecursive(child.Id, NetworkLeg.Left, startDate, endDate);
|
||||
var childRight = await CountNewMembersRecursive(child.Id, NetworkLeg.Right, startDate, endDate);
|
||||
|
||||
return count + childLeft + childRight;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Key Points
|
||||
|
||||
1. ✅ **Only NEW activations count** - filtered by `ActivatedAt` date
|
||||
2. ✅ **Carryover persists** - unused balances roll over to next week
|
||||
3. ✅ **Recursive counting** - includes entire subtree under each leg
|
||||
4. ✅ **Week date ranges** - ISO 8601 week format (Saturday to Friday)
|
||||
5. ✅ **Idempotent** - can recalculate with `ForceRecalculate` flag
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Benefits
|
||||
|
||||
1. **Fair commission distribution** - rewards balanced growth
|
||||
2. **No lost balances** - carryover ensures nothing is wasted
|
||||
3. **Accurate tracking** - distinguishes new vs existing members
|
||||
4. **Scalable** - works for large networks with recursive algorithm
|
||||
5. **Auditable** - full history of calculations in database
|
||||
|
||||
---
|
||||
|
||||
## 📞 Reference
|
||||
|
||||
- **Source Code**: `CMSMicroservice.Application/CommissionCQ/Commands/CalculateWeeklyBalances/`
|
||||
- **Migration**: `20251201144400_UpdateNetworkWeeklyBalanceWithCarryover`
|
||||
- **Entity**: `CMSMicroservice.Domain/Entities/Network/NetworkWeeklyBalance.cs`
|
||||
- **Discussion**: Telegram chat with Dr. Seif (2025-12-01)
|
||||
|
||||
---
|
||||
|
||||
**Status**: ✅ Production Ready
|
||||
**Last Updated**: 2025-12-01
|
||||
@@ -1,281 +0,0 @@
|
||||
# 🌳 Binary Tree Network Registration Guide
|
||||
|
||||
## 📋 Overview
|
||||
|
||||
از این پس، هر کاربر جدید که در سیستم ثبت میشود، **همزمان** در دو ساختار قرار میگیرد:
|
||||
|
||||
1. **Old System**: `User.ParentId` (برای Backward Compatibility)
|
||||
2. **New Binary Tree System**: `User.NetworkParentId` + `User.LegPosition` (Left/Right)
|
||||
|
||||
این تغییر تضمین میکند که:
|
||||
- ✅ کاربران جدید بلافاصله در محاسبات Commission شرکت میکنند
|
||||
- ✅ نیازی به Migration اضافی نیست
|
||||
- ✅ Binary Tree Constraint رعایت میشود (حداکثر 2 فرزند)
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Changes in Registration Flow
|
||||
|
||||
### قبل از تغییر:
|
||||
|
||||
```csharp
|
||||
var entity = request.Adapt<User>();
|
||||
entity.ReferralCode = UtilExtensions.Generate(digits: 10);
|
||||
await _context.Users.AddAsync(entity, cancellationToken);
|
||||
```
|
||||
|
||||
**مشکل**: فقط `ParentId` Set میشد، `NetworkParentId` و `LegPosition` خالی میماند.
|
||||
|
||||
---
|
||||
|
||||
### بعد از تغییر:
|
||||
|
||||
```csharp
|
||||
var entity = request.Adapt<User>();
|
||||
entity.ReferralCode = UtilExtensions.Generate(digits: 10);
|
||||
|
||||
// === محاسبه موقعیت در Binary Tree ===
|
||||
if (request.ParentId.HasValue)
|
||||
{
|
||||
var legPosition = await _networkPlacementService.CalculateLegPositionAsync(
|
||||
request.ParentId.Value, cancellationToken);
|
||||
|
||||
if (legPosition.HasValue)
|
||||
{
|
||||
entity.NetworkParentId = request.ParentId.Value;
|
||||
entity.LegPosition = legPosition.Value; // Left یا Right
|
||||
}
|
||||
else
|
||||
{
|
||||
// Parent پر است! Auto-Placement یا Error
|
||||
var availableParent = await _networkPlacementService.FindAvailableParentAsync(
|
||||
request.ParentId.Value, cancellationToken);
|
||||
|
||||
// ... Set کردن NetworkParentId و LegPosition با Parent جدید
|
||||
}
|
||||
}
|
||||
|
||||
await _context.Users.AddAsync(entity, cancellationToken);
|
||||
```
|
||||
|
||||
**مزایا**:
|
||||
- ✅ `NetworkParentId` و `LegPosition` به صورت خودکار محاسبه میشود
|
||||
- ✅ Binary Tree Constraint چک میشود
|
||||
- ✅ اگر Parent پر باشد، Auto-Placement انجام میشود
|
||||
|
||||
---
|
||||
|
||||
## 📐 Binary Tree Logic
|
||||
|
||||
### قوانین:
|
||||
1. هر Parent فقط **2 فرزند** میتواند داشته باشد (Left & Right)
|
||||
2. فرزند اول: `LegPosition = Left`
|
||||
3. فرزند دوم: `LegPosition = Right`
|
||||
4. اگر Parent پر باشد، سیستم به صورت BFS دنبال Parent خالی میگردد
|
||||
|
||||
### مثال:
|
||||
|
||||
```
|
||||
User1 (Root)
|
||||
/ \
|
||||
User2 (L) User3 (R)
|
||||
/ \
|
||||
User4(L) User5(R)
|
||||
```
|
||||
|
||||
- User2 → Parent=User1, Leg=Left
|
||||
- User3 → Parent=User1, Leg=Right
|
||||
- User4 → Parent=User2, Leg=Left
|
||||
- User5 → Parent=User2, Leg=Right
|
||||
|
||||
اگر کاربر جدید با `ParentId=User1` بیاید:
|
||||
- User1 پر است! (دو فرزند دارد)
|
||||
- سیستم به User2 میرود (BFS)
|
||||
- User2 هم پر است!
|
||||
- به User3 میرود → User3 خالی است
|
||||
- کاربر جدید → Parent=User3, Leg=Left
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ NetworkPlacementService API
|
||||
|
||||
### 1. CalculateLegPositionAsync
|
||||
محاسبه موقعیت (Left/Right) برای کاربر جدید زیر یک Parent مشخص.
|
||||
|
||||
```csharp
|
||||
var legPosition = await _networkPlacementService.CalculateLegPositionAsync(parentId);
|
||||
```
|
||||
|
||||
**Return Values**:
|
||||
- `NetworkLeg.Left`: اگر Parent فرزند چپ ندارد
|
||||
- `NetworkLeg.Right`: اگر Parent فرزند راست ندارد
|
||||
- `null`: اگر Parent پر است (دو فرزند دارد)
|
||||
|
||||
---
|
||||
|
||||
### 2. CanAcceptChildAsync
|
||||
بررسی اینکه آیا Parent میتواند فرزند جدید بپذیرد.
|
||||
|
||||
```csharp
|
||||
bool canAccept = await _networkPlacementService.CanAcceptChildAsync(parentId);
|
||||
```
|
||||
|
||||
**Return Values**:
|
||||
- `true`: اگر Parent کمتر از 2 فرزند دارد
|
||||
- `false`: اگر Parent پر است
|
||||
|
||||
---
|
||||
|
||||
### 3. FindAvailableParentAsync (Auto-Placement)
|
||||
پیدا کردن اولین Parent خالی در Binary Tree با استفاده از BFS.
|
||||
|
||||
```csharp
|
||||
long? availableParentId = await _networkPlacementService.FindAvailableParentAsync(rootParentId);
|
||||
```
|
||||
|
||||
**Use Case**:
|
||||
- زمانی که Parent مورد نظر پر است
|
||||
- سیستم به صورت خودکار Parent جایگزین پیدا میکند
|
||||
- از BFS استفاده میکند (Level-by-Level)
|
||||
|
||||
**Return Values**:
|
||||
- `long`: شناسه Parent مناسب
|
||||
- `null`: اگر هیچ Parent خالی پیدا نشد (تمام Binary Tree پر است!)
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Error Handling
|
||||
|
||||
### Scenario 1: Parent پر است و Auto-Placement موفق
|
||||
|
||||
```csharp
|
||||
// Parent اصلی پر است
|
||||
// سیستم Parent جدید پیدا میکند
|
||||
_logger.LogWarning("Parent {ParentId} is full. Auto-placing under {NewParentId}");
|
||||
```
|
||||
|
||||
**نتیجه**: کاربر با موفقیت در جای دیگری قرار میگیرد.
|
||||
|
||||
---
|
||||
|
||||
### Scenario 2: کل Binary Tree پر است
|
||||
|
||||
```csharp
|
||||
throw new InvalidOperationException(
|
||||
$"شبکه Parent با شناسه {parentId} پر است و نمیتواند کاربر جدید بپذیرد.");
|
||||
```
|
||||
|
||||
**نتیجه**: Exception پرتاب میشود، ثبت کاربر انجام نمیشود.
|
||||
|
||||
**راه حل**:
|
||||
- افزایش سطح Binary Tree
|
||||
- یا تخصیص دستی Parent
|
||||
|
||||
---
|
||||
|
||||
### Scenario 3: Parent وجود ندارد
|
||||
|
||||
```csharp
|
||||
var parentExists = await _context.Users.AnyAsync(u => u.Id == parentId);
|
||||
if (!parentExists)
|
||||
{
|
||||
return null; // Parent نامعتبر
|
||||
}
|
||||
```
|
||||
|
||||
**نتیجه**: `null` برگردانده میشود، Exception پرتاب میشود.
|
||||
|
||||
---
|
||||
|
||||
## 📊 Logging & Monitoring
|
||||
|
||||
سیستم Log های زیر را مینویسد:
|
||||
|
||||
### Success:
|
||||
```
|
||||
User 123 placed in Binary Tree: Parent=45, Leg=Left
|
||||
```
|
||||
|
||||
### Warning (Auto-Placement):
|
||||
```
|
||||
Parent 45 has no available leg! Finding alternative parent...
|
||||
User 123 auto-placed under alternative Parent=67, Leg=Right
|
||||
```
|
||||
|
||||
### Error (Binary Tree Full):
|
||||
```
|
||||
No available parent found in network for ParentId=45
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Scenarios
|
||||
|
||||
### Test 1: کاربر اول (Root)
|
||||
```csharp
|
||||
var command = new CreateNewUserCommand { Mobile = "09121234567" }; // No ParentId
|
||||
// Result: ParentId=null, NetworkParentId=null, LegPosition=null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Test 2: فرزند اول
|
||||
```csharp
|
||||
var command = new CreateNewUserCommand { Mobile = "09121234568", ParentId = 1 };
|
||||
// Result: ParentId=1, NetworkParentId=1, LegPosition=Left
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Test 3: فرزند دوم
|
||||
```csharp
|
||||
var command = new CreateNewUserCommand { Mobile = "09121234569", ParentId = 1 };
|
||||
// Result: ParentId=1, NetworkParentId=1, LegPosition=Right
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Test 4: فرزند سوم (Parent پر است)
|
||||
```csharp
|
||||
var command = new CreateNewUserCommand { Mobile = "09121234570", ParentId = 1 };
|
||||
// Result: Auto-Placement → ParentId=1, NetworkParentId=2 (یا 3), LegPosition=Left
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Related Files
|
||||
|
||||
- **Service Interface**: `CMSMicroservice.Application/Common/Interfaces/INetworkPlacementService.cs`
|
||||
- **Service Implementation**: `CMSMicroservice.Infrastructure/Services/NetworkPlacementService.cs`
|
||||
- **Handler**: `CMSMicroservice.Application/UserCQ/Commands/CreateNewUser/CreateNewUserCommandHandler.cs`
|
||||
- **DI Registration**: `CMSMicroservice.Infrastructure/ConfigureServices.cs` (خط 23)
|
||||
|
||||
---
|
||||
|
||||
## ✅ Checklist
|
||||
|
||||
- [x] `INetworkPlacementService` اضافه شد
|
||||
- [x] `NetworkPlacementService` پیادهسازی شد
|
||||
- [x] DI Container تنظیم شد
|
||||
- [x] `CreateNewUserCommandHandler` اصلاح شد
|
||||
- [ ] Unit Tests نوشته شود
|
||||
- [ ] Integration Tests انجام شود
|
||||
- [ ] Manual Testing با Postman/gRPC Client
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
1. **Test کردن**: ثبت چند کاربر با Parent مشابه و بررسی LegPosition
|
||||
2. **Load Testing**: بررسی Performance با 10,000 کاربر
|
||||
3. **Edge Cases**: تست Binary Tree Full scenario
|
||||
4. **Documentation**: Update کردن API Docs
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
اگر مشکلی پیش آمد:
|
||||
- Log های `NetworkPlacementService` را بررسی کنید
|
||||
- چک کنید که DI به درستی تنظیم شده باشد
|
||||
- از `CanAcceptChildAsync` برای Pre-Validation استفاده کنید
|
||||
@@ -1,123 +0,0 @@
|
||||
# مستندات داده و بیزینس مایکروسرویس CMS
|
||||
|
||||
## معماری و لایهها
|
||||
- **پشته فنی**: .NET 9 + ASP.NET Core WebAPI، MediatR برای پیادهسازی CQRS، EF Core برای دسترسی داده، Mapster برای مپینگ DTO و gRPC/Protobuf برای قرارداد سرویس بین BFF ها و FrontOffice.
|
||||
- **ساختار پروژه**: لایههای Domain (موجودیت و قواعد)، Application (CQRS Commands/Queries، ولیدیشن، DTO)، Infrastructure (EF Core + سرویسهای جانبی) و WebApi (ورودی HTTP/gRPC) به همراه پروژه مستقل Protobuf جهت بهاشتراکگذاری قراردادها.
|
||||
- **الگوی کلی**: هر درخواست ورودی از طریق WebApi به MediatR ارسال و Handler مربوطه داده را از DbContext میخواند/مینویسد. تمام موجودیتها از `BaseAuditableEntity` ارث میبرند و ستونهای `Id`, `Created`, `CreatedBy`, `LastModified`, `IsDeleted` را به صورت یکپارچه فراهم میکنند.
|
||||
- **ملاحظات مقیاسپذیری**: Handler ها stateless هستند و میتوانند افقی مقیاس شوند. کنترل تراکنشها توسط EF Core انجام میشود و در عملیات چندمرحلهای (مثلاً ثبت سفارش) تغییرات داخل یک `TransactionScope` واحد اعمال میشود تا سازگاری داده حفظ شود.
|
||||
- **پایش و ردگیری**: رفتارهای `Common/Behaviours` برای لاگگیری و اعتبارسنجی فعالاند و برای هر درخواست یک شناسه ردگیری تولید میکنند تا ارتباط بین لاگ BackOffice و FrontOffice حفظ گردد.
|
||||
|
||||
## مدل داده
|
||||
برای فهم بهتر بیزینس، موجودیتها در پنج خوشه اصلی (هویت، کاتالوگ، سفارش، کیف پول، قرارداد) دستهبندی شدهاند و هر خوشه قواعد و قیود مخصوص خود را دارد.
|
||||
### لایه کاربر و هویت
|
||||
- **User**: اطلاعات هویتی، وضعیت تایید موبایل، تنظیمات اعلان، کد ارجاع و رابطه والد/فرزند. ارتباط یکبهچند با آدرسها، نقشها، سفارشها، قراردادها، کیف پول و سبد خرید.
|
||||
- **Role / UserRole**: تعریف نقشهای سیستمی و نگاشت چند-به-چند کاربر به نقش. جهت کنترل دسترسی BackOffice.
|
||||
- **OtpToken**: ذخیره توکنهای OTP با هش کد، هدف (Purpose)، زمان انقضا، تعداد تلاش و وضعیت مصرف برای جریان لاگین/ثبتنام.
|
||||
|
||||
### لایه محتوا و کاتالوگ محصول
|
||||
- **Category**: ساختار درختی دستهبندی با عنوان، توضیحات، تصویر، ترتیب نمایش و وضعیت فعال بودن. `ParentId` برای تو در تویی و ارتباط با `PruductCategory`.
|
||||
- **Tag / PruductTag**: برچسبهای قابل جستجو برای محصولات با وضعیت فعال و ترتیب. جدول واسط `PruductTag` اتصال چند-به-چند محصول و تگ را نگه میدارد.
|
||||
- **Products**: جزئیات کامل محصول شامل توضیحات کوتاه/طولانی، قیمت، تخفیف، نرخ، تصاویر اصلی/Thumbnail، آمار فروش و موجودی. ارتباط با سبد، گالری، فاکتور، دسته و تگ.
|
||||
- **ProductImages / ProductGallerys**: مدیریت داراییهای تصویری. `ProductImages` مشخصات فایل را نگه میدارد و `ProductGallerys` رابطه هر تصویر با یک محصول را ثبت میکند تا چیدمان گالری قابل کنترل باشد.
|
||||
- **Package**: باندل یا سرویس قابل فروش با عنوان، توضیح، تصویر و قیمت ثابت که میتواند داخل سفارش کاربر قرار گیرد.
|
||||
- **Category–Product Pivot (`PruductCategory`)**: ردیفهای عضویت محصول در دستههای متعدد. هر ردیف شامل `ProductId` و `CategoryId` است.
|
||||
|
||||
### لایه سفارش و تراکنش
|
||||
- **UserCarts**: آیتمهای سبد خرید کاربر، شامل شناسه محصول، کاربر و تعداد. منبع اصلی عملیات افزودن/حذف سبد در FrontOffice.
|
||||
- **UserAddress**: آدرسهای پستی کاربران با عنوان، متن آدرس، کد پستی، شهر، وضعیت پیشفرض و ارتباط با سفارشها.
|
||||
- **UserOrder**: سفارش نهایی شامل مبلغ، ارجاع به پکیج/تراکنش، وضعیت و تاریخ پرداخت، روش پرداخت، وضعیت ارسال، کد رهگیری و توضیحات ارسال. همچنین به آدرس کاربر و آیتمهای فاکتور (`FactorDetails`) متصل است.
|
||||
- **FactorDetails**: اقلام درون سفارش؛ هر ردیف به محصول و سفارش اشاره دارد و تعداد، قیمت واحد، تخفیف و وضعیت تغییر قیمت را نگه میدارد.
|
||||
- **Transactions**: لاگ مالی سطح درگاه با مبلغ، توضیح، وضعیت/تاریخ پرداخت، شناسه مرجع درگاه و نوع تراکنش (Persistent در Enum `TransactionType`). سفارشها میتوانند به یک تراکنش اشاره کنند.
|
||||
|
||||
### لایه کیف پول و تسویه
|
||||
- **UserWallet**: کیف پول ریالی/شبکهای هر کاربر با موجودی جاری و موجودی شبکه (`NetworkBalance`).
|
||||
- **UserWalletChangeLog**: ژورنال تغییرات کیف پول شامل موجودی قبل/بعد، مقدار تغییر، تغییر شبکه، اینکه افزایش یا کاهش بوده و شناسه مرجع (مثلاً تراکنش یا سفارش). ستون `Created` منبع اصلی timestamp فاکتور کیف پول است.
|
||||
|
||||
### لایه قرارداد و رعایت الزامات
|
||||
- **Contract**: قالب قراردادها با عنوان، توضیحات، متن HTML و نوع قرارداد (`ContractType`).
|
||||
- **UserContract**: سوابق موافقت کاربر با قراردادها، شامل فایل PDF امضا شده و `SignGuid` برای ردیابی امضا.
|
||||
|
||||
## ماژولها و بیزینس مفصل
|
||||
### کاربران و هویت
|
||||
- **ثبتنام**: با دریافت موبایل، رکورد `User` ساخته و OTP برای تایید ارسال میشود. شرط یکتایی موبایل در سطح پایگاه داده enforced است و در Handler نیز بررسی میشود.
|
||||
- **تکمیل پروفایل**: کاربر میتواند نام، کد ملی، تاریخ تولد و تنظیمات اعلان را تکمیل کند. فعالسازی اعلانها به BFF اطلاع میدهد تا Subscription در سرویس پوش ثبت شود.
|
||||
- **مدیریت نقش**: Admin میتواند از API `UserRoleCQ` برای افزودن نقش جدید استفاده کند؛ در صورت حذف نقش، ابتدا باید عضویتهای فعال کاربر قطع شود.
|
||||
|
||||
### کاتالوگ و محتوا
|
||||
- **دستهبندی درختی**: سطح بینهایت تو در تو پشتیبانی میشود. حذف یک دسته زمانی مجاز است که هیچ `Categorys` فرزند و هیچ `PruductCategory` فعالی نداشته باشد؛ در غیر این صورت باید انتقال انجام شود.
|
||||
- **چرخه محصول**: ایجاد محصول شامل ثبت داده متنی، بارگذاری تصویر شاخص، تعریف قیمت و تعیین تخفیف است. تغییر قیمت در Handler ثبت شده و قوانین جلوگیری از عدد منفی یا Discount بزرگتر از 100٪ اعمال میشود.
|
||||
- **گالری و تصاویر**: ابتدا تصویر در `ProductImages` ثبت و سپس با `ProductGallerys` به محصول متصل میشود تا یک تصویر بتواند در چند محصول استفاده شود. حذف تصویر اگر در گالری فعال باشد ممنوع است.
|
||||
- **پکیجها**: برای فروش سرویس اشتراکی یا باندل؛ فیلد `Price` مبنای محاسبه سفارشهای نوع Package است و تغییر قیمت روی سفارشهای ثبتشده تاثیر ندارد زیرا مبلغ در `UserOrder.Amount` ذخیره میشود.
|
||||
|
||||
### سفارش، پرداخت و لجستیک
|
||||
- **سبد خرید**: عملیات Add/Update/Delete روی `UserCarts` انجام میشود. در هر لحظه برای ترکیب (User, Product) تنها یک رکورد وجود دارد. اگر Count صفر شود، رکورد حذف منطقی میشود تا تاریخچه حفظ گردد.
|
||||
- **Checkout**: Handler `SubmitShopBuyOrder` اقلام سبد را قفل خوشبینانه کرده، سفارش (`UserOrder`) و اقلام فاکتور (`FactorDetails`) را میسازد، آدرس پیشفرض را نگاشت و وضعیت پرداخت را Pending میگذارد.
|
||||
- **پرداخت آنلاین**: پس از هدایت به درگاه، سیستم CallBack در `TransactionsCQ` را دریافت میکند؛ شناسه مرجع (`RefId`) و مبلغ تطبیق داده میشود. در صورت موفقیت، `PaymentStatus` سفارش و تراکنش Success شده و `PaymentDate` ذخیره میشود. در صورت Reject، سبد به حالت قبل بازگردانده میشود.
|
||||
- **پرداخت با کیف پول**: اگر موجودی کافی باشد، به صورت اتمیک از کیف پول کسر و سفارش Success میشود؛ نیازی به تراکنش درگاه نیست.
|
||||
- **لجستیک**: فیلدهای `DeliveryStatus`, `TrackingCode`, `DeliveryDescription` وضعیت ارسال را پوشش میدهند. هر تغییر وضعیت میتواند Notification برای کاربر یا تیم پشتیبانی ایجاد کند.
|
||||
|
||||
### کیف پول و تسویه داخلی
|
||||
- **ساخت کیف پول**: همزمان با ثبتنام یا اولین تراکنش، رکورد `UserWallet` ساخته میشود. موجودی شبکه برای پشتیبانی از داراییهای خارج از پلتفرم است.
|
||||
- **ChangeLog**: هر تغییر موجودی همراه با مقدار قبل/بعد، مقدار شبکه، نوع عملیات (Increase/Decrease) و `ReferenceId` ثبت میشود تا audit کافی فراهم گردد. Handler ها Idempotency را با بررسی ReferenceId رعایت میکنند.
|
||||
- **واریز**: میتواند از طریق درگاه آنلاین یا عملیات دستی ادمین باشد. پس از تایید بانک، مبلغ به `Balance` افزوده و ChangeLog با نوع Deposit ذخیره میشود.
|
||||
- **برداشت/تسویه**: درخواست Withdrawal ابتدا به صف تایید دستی میرود (Business Rule). پس از تایید، مبلغ از `Balance` کم و اگر نیاز به ارسال به شبکه بلاکچین باشد، `NetworkBalance` نیز بهروزرسانی میشود.
|
||||
- **بازپرداخت سفارش**: در صورت لغو سفارش پرداختشده، مقدار پرداختی با ChangeLog نوع Refund به کیف پول برمیگردد تا کاربر بتواند مجدد خرید کند یا برداشت انجام دهد.
|
||||
|
||||
### قرارداد و انطباق
|
||||
- **مدیریت نسخه**: هر بار که متن قرارداد تغییر کند، رکورد جدیدی در `Contract` ساخته میشود. `UserContract` با نگه داشتن `ContractId` مشخص میکند کاربر کدام نسخه را امضا کرده است.
|
||||
- **فرآیند امضا**: برای امضای دیجیتال، سیستم `SignGuid` را به سرویس امضای بیرونی ارسال میکند. پس از تکمیل، فایل PDF در فضای ذخیرهسازی آپلود و مسیر آن در `UserContract.SignedPdfFile` ثبت میشود.
|
||||
- **کنترل پذیرش قوانین**: فیلدهای `IsRulesAccepted` و `RulesAcceptedAt` در موجودیت User نیز نگهداری میشوند تا بتوان دفعات قبول قوانین عمومی را از قراردادهای اختصاصی تفکیک کرد.
|
||||
|
||||
### گزارش و مانیتورینگ
|
||||
- تمام Queries دارای پارامترهای Paging و Sorting هستند تا BackOffice بتواند داشبورد مدیریتی بسازد.
|
||||
- به کمک Mapster Projection فقط ستونهای مورد نیاز خوانده میشود؛ در موارد خاص (مثل تاریخ تراکنش کیف پول) Projection دستی به DTO اعمال شده است.
|
||||
- ساختار CQRS اجازه میدهد که در آینده Event Handler یا Outbox برای همگامسازی با سرویسهای دیگر اضافه شود.
|
||||
|
||||
## فرایندهای بیزینسی کلیدی
|
||||
### 1. احراز هویت و ورود
|
||||
1. کاربر شماره موبایل را ارسال میکند؛ `OtpTokenCQ` یک رکورد جدید با کد هششده، زمان انقضا و شمارش تلاشها میسازد. درصورت وجود رکورد فعال، ابتدا Attempts چک و درصورت عبور از سقف، خطای تجاری برگردانده میشود.
|
||||
2. کاربر کد را ارسال میکند؛ سیستم hash تولید میکند و با `CodeHash` مقایسه میشود. در صورت موفقیت، `IsUsed` و `IsMobileVerified` تنظیم میشوند و تاریخ تایید موبایل ذخیره میگردد.
|
||||
3. اگر کاربر برای اولینبار وارد شود، کیف پول و Role پیشفرض ایجاد میشود. سپس سرویس JWT توکن امضا شده (همراه با Claims نقشها) را برمیگرداند.
|
||||
|
||||
### 2. مدیریت کاتالوگ و محتوای فروش
|
||||
- اپراتور BackOffice از طریق دستهها، تگها و محصولات API های `CategoryCQ`, `ProductsCQ`, `TagCQ` و … اقلام را CRUD میکند.
|
||||
- تصاویر از طریق `ProductImagesCQ` ثبت و سپس با `ProductGallerysCQ` به محصولات لینک میشوند تا ترتیب نمایش قابل تغییر باشد.
|
||||
- باندلهای اشتراکی یا خدمات از طریق `PackageCQ` تعریف میشوند و در سفارشها استفاده میشوند.
|
||||
- قوانین کیفیت داده: عنوان و توضیح محصول نمیتواند خالی باشد، تصویر شاخص باید پیش از انتشار محصول مشخص شود و حداقل یک دسته فعال برای محصول الزامی است.
|
||||
- وضعیت فعال/غیرفعال دستهها در API لیست محصولات اعمال میشود تا محصولات دسته غیرفعال نمایش داده نشوند.
|
||||
|
||||
### 3. تجربه خرید (Cart → Order → Transaction)
|
||||
1. FrontOffice اقلام را در `UserCarts` ثبت/ویرایش میکند.
|
||||
2. هنگام تسویه، Handler های `UserOrderCQ` سفارش و اقلام `FactorDetails` را میسازند، آدرس پیشفرض UserAddress را ضمیمه میکنند و وضعیت پرداخت را `Pending` قرار میدهند.
|
||||
3. پس از موفقیت درگاه، سرویس تراکنش (`TransactionsCQ`) شناسه مرجع را ذخیره و `PaymentStatus` سفارش و تراکنش را `Success` میکند؛ تاریخ پرداخت نیز ست میشود.
|
||||
4. وضعیت ارسال (`DeliveryStatus`) در طول فرایند Fulfillment آپدیت شده و کد رهگیری پستی داخل سفارش نگهداری میشود.
|
||||
- سناریو شکست درگاه: اگر درگاه خطا دهد، سفارش در حالت Pending باقی میماند و Job زمانبندی شده این سفارشها را بعد از زمان مشخص لغو میکند تا سبد دوباره آزاد شود.
|
||||
- امکان پرداخت ترکیبی (کیف پول + درگاه) وجود دارد؛ ابتدا از کیف پول برداشت و سپس باقیمانده به درگاه ارسال میشود.
|
||||
|
||||
### 4. کیف پول و صورتحساب داخلی
|
||||
- هر کاربر دقیقا یک کیف پول فعال دارد (`UserWalletCQ`).
|
||||
- واریز/برداشت (چه ناشی از پرداخت آنلاین چه عملیات دستی) همیشه یک رکورد در `UserWalletChangeLog` ایجاد میکند تا موجودی قبلی، مقدار تغییر و منبع (ReferenceId) مشخص باشد.
|
||||
- FrontOffice برای نمایش تاریخ دقیق تراکنشها از `Created` لاگ استفاده میکند؛ بنابراین Handler های `UserWalletChangeLogCQ` حتما `CreatedAt` را به DTO و gRPC پاسخ اضافه میکنند.
|
||||
- ChangeLog ها قابلیت فیلتر بر اساس نوع عملیات، بازه تاریخی و ReferenceId دارند و مقادیر در DTO به timestamp یونیکس هم تبدیل میشود تا فرانت به راحتی فرمت کند.
|
||||
- عملیات دستی ادمین حتما توضیح (Description) و شناسه اپراتور را ثبت میکند تا audit کامل باشد.
|
||||
|
||||
### 5. قراردادها و انطباق
|
||||
- محتوای قرارداد (Term of Service، قرارداد نمایندگی و …) در `Contract` نگهداری میشود.
|
||||
- هنگام امضا، یک `UserContract` شامل فایل PDF امضا شده و `SignGuid` ایجاد میگردد تا سوابق حقوقی نگهداری شود. این اطلاعات در درخواستهای بعدی احراز میشوند تا از کاربران فقط یکبار امضا گرفته شود.
|
||||
- در صورت بهروزرسانی متن قرارداد، کاربران باید مجدداً آن را تایید کنند؛ FrontOffice هنگام ورود این شرط را بررسی و کاربر را به صفحه امضا هدایت میکند.
|
||||
- سیستم گزارش میدهد چه تعداد کاربر هر نسخه را امضا کردهاند تا تیم حقوقی مطمئن شود پوشش قانونی کامل است.
|
||||
|
||||
## نکات پیادهسازی و توسعه
|
||||
- **CQRS پوشهبندی**: هر ماژول (مثلاً `UserWalletCQ`) شامل زیرپوشههای Commands و Queries است. درخواستهای gRPC از پروژه Protobuf با DTO های Application نگاشت میشوند.
|
||||
- **همگامسازی قراردادها**: هر زمان فیلد جدیدی به موجودیت اضافه شود باید DTO، Handler و قرارداد Protobuf متناظر نیز بهروزرسانی و `dotnet build` برای تولید مجدد stubs اجرا شود. سپس BFF ها باید پکیج جدید را دریافت کنند.
|
||||
- **اتصال با BFF**: CMS WebApi سرویسهای gRPC را در پورت تعریف شده در `appsettings` اکسپوز میکند. BFF ها با استفاده از Channel مطمئن (TLS داخلی) به آن متصل میشوند و Mapster را برای تبدیل به مدلهای فرانت استفاده میکنند.
|
||||
- **Dependency Injection**: تمام Handler ها و سرویسها در `CMSMicroservice.Application/ConfigureServices.cs` و `CMSMicroservice.Infrastructure/ConfigureServices.cs` ثبت میشوند تا تستپذیری افزایش یابد.
|
||||
- **اعتبارسنجی و لاگ**: Behaviour های مشترک (LoggingBehaviour, ValidationBehaviour) روی Pipeline MediatR نشستهاند تا قبل از اجرای Handler، ورودیها چک و لاگ ساختارمند تولید شود.
|
||||
- **زمانبندی تمیزکاری**: ستون `IsDeleted` برای Soft Delete بهکار میرود. Handler هایی که لیست میدهند معمولا فیلتر `!IsDeleted` را اعمال میکنند؛ برای نمایش آرشیو باید صراحتاً flag درخواست شود.
|
||||
- **Enums مهم**: `PaymentStatus`, `PaymentMethod`, `DeliveryStatus`, `ContractType`, `TransactionType` طیف وضعیتهای مالی/قراردادی را استاندارد میکنند و باید بین FrontOffice و BackOffice همسو نگه داشته شوند.
|
||||
- **آیتمهای Idempotent**: عملیات حساس مثل واریز کیف پول یا ثبت سفارش از ReferenceId استفاده میکنند تا در تکرار درخواستها نتیجهی تکراری ایجاد نشود.
|
||||
|
||||
## مسیرهای مرتبط
|
||||
- ساختار کد: `CMS/src/CMSMicroservice.Domain/Entities`, `CMSMicroservice.Application/*CQ`, `CMSMicroservice.Protobuf/Protos`.
|
||||
- مستند حاضر: `CMS/docs/cms-data-and-business.md`
|
||||
- نقاط تماس بیرونی: gRPC Endpoint های `CMSMicroservice.WebApi` به صورت داخلی مصرف میشوند و از طریق FrontOffice/BackOffice BFF در اختیار UI قرار میگیرند.
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,225 +0,0 @@
|
||||
# 🔄 Migration Guide: ParentId → NetworkParentId
|
||||
|
||||
## 📋 Overview
|
||||
|
||||
در سیستم قدیمی، کاربران با استفاده از `User.ParentId` به هم متصل میشدند (Parent-Child relationship).
|
||||
سیستم جدید **Network-Club-Commission** از یک **Binary Tree** استفاده میکند که نیاز به:
|
||||
- `User.NetworkParentId` (شناسه پدر در شبکه باینری)
|
||||
- `User.LegPosition` (Left یا Right)
|
||||
|
||||
برای اجرای صحیح Worker و محاسبات، **باید** تمام کاربران قدیمی Migrate شوند.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Critical Issues
|
||||
|
||||
### مشکل 1: Binary Tree Constraint
|
||||
- هر Parent فقط میتواند **2 فرزند** داشته باشد (Left & Right)
|
||||
- اگر کاربری در سیستم قدیمی بیشتر از 2 فرزند دارد، Migration فقط **2 فرزند اول** را میگیرد
|
||||
|
||||
### مشکل 2: Orphaned Nodes
|
||||
- اگر `ParentId` اشاره به یک کاربر نامعتبر (حذف شده) باشد، آن User **Orphaned** است
|
||||
- Orphaned nodes در Binary Tree نادیده گرفته میشوند
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Migration Methods
|
||||
|
||||
### روش 1: Automatic (Seeder - توصیه میشود)
|
||||
|
||||
Migration به صورت خودکار در `Program.cs` در حالت **Development** اجرا میشود:
|
||||
|
||||
```csharp
|
||||
// در Program.cs
|
||||
var migrationSeeder = new NetworkParentIdMigrationSeeder(dbContext, logger);
|
||||
await migrationSeeder.SeedAsync();
|
||||
```
|
||||
|
||||
**مزایا:**
|
||||
- ✅ Idempotent (میتوان چندین بار اجرا کرد، فقط یکبار تاثیر میگذارد)
|
||||
- ✅ Validation اتوماتیک
|
||||
- ✅ Logging کامل
|
||||
|
||||
**کجا اجرا میشود؟**
|
||||
- فقط در **Development** environment
|
||||
- هر بار که پروژه Run شود
|
||||
|
||||
---
|
||||
|
||||
### روش 2: Manual (Command)
|
||||
|
||||
اگر نیاز به اجرای دستی دارید:
|
||||
|
||||
```csharp
|
||||
// درخواست از طریق MediatR
|
||||
var result = await _mediator.Send(new MigrateNetworkParentIdCommand());
|
||||
|
||||
if (result.Success)
|
||||
{
|
||||
Console.WriteLine($"Migrated: {result.MigratedCount}");
|
||||
Console.WriteLine($"Skipped: {result.SkippedCount}");
|
||||
}
|
||||
else
|
||||
{
|
||||
Console.WriteLine($"Error: {result.Message}");
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### روش 3: SQL Script
|
||||
|
||||
برای Production یا اجرای مستقیم روی Database:
|
||||
|
||||
```bash
|
||||
# فایل: CMSMicroservice.Infrastructure/Migrations/Scripts/20250601_MigrateParentIdToNetworkParentId.sql
|
||||
```
|
||||
|
||||
**نکته مهم:**
|
||||
قبل از اجرا، **حتماً** بررسی کنید که آیا کاربری بیش از 2 فرزند دارد:
|
||||
|
||||
```sql
|
||||
SELECT
|
||||
ParentId,
|
||||
COUNT(*) as ChildCount,
|
||||
STRING_AGG(CAST(Id AS VARCHAR), ', ') as ChildIds
|
||||
FROM Users
|
||||
WHERE ParentId IS NOT NULL
|
||||
GROUP BY ParentId
|
||||
HAVING COUNT(*) > 2;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Validation After Migration
|
||||
|
||||
### 1. بررسی تعداد کاربران Migrate شده
|
||||
|
||||
```csharp
|
||||
var stats = await _context.Users
|
||||
.GroupBy(u => 1)
|
||||
.Select(g => new
|
||||
{
|
||||
TotalUsers = g.Count(),
|
||||
UsersWithNetworkParent = g.Count(u => u.NetworkParentId != null),
|
||||
LeftChildren = g.Count(u => u.LegPosition == NetworkLeg.Left),
|
||||
RightChildren = g.Count(u => u.LegPosition == NetworkLeg.Right)
|
||||
})
|
||||
.FirstOrDefaultAsync();
|
||||
```
|
||||
|
||||
### 2. بررسی Orphaned Nodes
|
||||
|
||||
```sql
|
||||
SELECT Id, NetworkParentId
|
||||
FROM Users
|
||||
WHERE NetworkParentId IS NOT NULL
|
||||
AND NetworkParentId NOT IN (SELECT Id FROM Users);
|
||||
```
|
||||
|
||||
### 3. بررسی Binary Tree Violation
|
||||
|
||||
```sql
|
||||
SELECT NetworkParentId, COUNT(*) as ChildCount
|
||||
FROM Users
|
||||
WHERE NetworkParentId IS NOT NULL
|
||||
GROUP BY NetworkParentId
|
||||
HAVING COUNT(*) > 2;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Algorithm Details
|
||||
|
||||
### مراحل Migration:
|
||||
|
||||
1. **Find Users**: یافتن کاربران با `ParentId != NULL` و `NetworkParentId == NULL`
|
||||
2. **Group by Parent**: گروهبندی بر اساس ParentId
|
||||
3. **Check Constraint**: اگر Parent بیش از 2 فرزند دارد، فقط 2 تا اول را بگیر
|
||||
4. **Assign Values**:
|
||||
```csharp
|
||||
child.NetworkParentId = parentId;
|
||||
child.LegPosition = (i == 0) ? NetworkLeg.Left : NetworkLeg.Right;
|
||||
```
|
||||
5. **Save & Validate**: ذخیره و اعتبارسنجی Binary Tree
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### مشکل: Parent has more than 2 children
|
||||
|
||||
**راه حل:**
|
||||
تصمیم دستی بگیرید که کدام 2 فرزند را نگه دارید:
|
||||
|
||||
```sql
|
||||
-- بررسی کنید که کدام Parent مشکل دارد
|
||||
SELECT ParentId, COUNT(*) as ChildCount
|
||||
FROM Users
|
||||
WHERE ParentId = 123
|
||||
GROUP BY ParentId;
|
||||
|
||||
-- لیست فرزندان را ببینید
|
||||
SELECT Id, FullName, CreatedAt
|
||||
FROM Users
|
||||
WHERE ParentId = 123
|
||||
ORDER BY CreatedAt;
|
||||
|
||||
-- دستی NetworkParentId را برای 2 فرزند انتخابی Set کنید
|
||||
UPDATE Users
|
||||
SET NetworkParentId = 123, LegPosition = 0 -- Left
|
||||
WHERE Id = 456;
|
||||
|
||||
UPDATE Users
|
||||
SET NetworkParentId = 123, LegPosition = 1 -- Right
|
||||
WHERE Id = 789;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### مشکل: Orphaned Nodes (Parent doesn't exist)
|
||||
|
||||
**راه حل:**
|
||||
ParentId را NULL کنید یا به یک Parent معتبر متصل کنید:
|
||||
|
||||
```sql
|
||||
-- گزینه 1: NULL کردن (Root شدن)
|
||||
UPDATE Users
|
||||
SET ParentId = NULL, NetworkParentId = NULL
|
||||
WHERE ParentId = 999; -- 999 وجود ندارد
|
||||
|
||||
-- گزینه 2: اتصال به Parent دیگر
|
||||
UPDATE Users
|
||||
SET ParentId = 1, NetworkParentId = 1
|
||||
WHERE ParentId = 999;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Checklist Before Production
|
||||
|
||||
- [ ] Migration در Development اجرا شده؟
|
||||
- [ ] Validation Errors بررسی شد؟
|
||||
- [ ] Orphaned Nodes رفع شدند؟
|
||||
- [ ] Binary Tree Violations رفع شدند؟
|
||||
- [ ] Backup از Database گرفته شده؟
|
||||
- [ ] Migration Script برای Production آماده است؟
|
||||
- [ ] Testing کامل انجام شده؟
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Related Files
|
||||
|
||||
- **Seeder**: `CMSMicroservice.Infrastructure/Data/Seeding/NetworkParentIdMigrationSeeder.cs`
|
||||
- **Command**: `CMSMicroservice.Application/UserCQ/Commands/MigrateNetworkParentId/`
|
||||
- **SQL Script**: `CMSMicroservice.Infrastructure/Migrations/Scripts/20250601_MigrateParentIdToNetworkParentId.sql`
|
||||
- **Entity**: `CMSMicroservice.Domain/Entities/User.cs` (خطوط 16, 45, 49)
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
اگر مشکل خاصی با Migration پیدا کردید:
|
||||
1. Log های Seeder را بررسی کنید
|
||||
2. ValidationErrors را چک کنید
|
||||
3. SQL Script را به صورت دستی اجرا کنید
|
||||
@@ -1,732 +0,0 @@
|
||||
# 📊 Monitoring & Alerts System - Consolidated Implementation Report
|
||||
|
||||
**Date**: 2025-11-30
|
||||
**Status**: ✅ Skeleton Implemented (30% Complete)
|
||||
**Build**: ✅ Success
|
||||
|
||||
---
|
||||
|
||||
## 📋 Executive Summary
|
||||
|
||||
اسکلت کامل سیستم Monitoring & Alerts پیادهسازی شد. این سیستم شامل دو بخش اصلی است:
|
||||
1. **Alert System**: اعلانهای مدیریتی (Critical/Warning/Success) برای Admin
|
||||
2. **User Notification System**: اعلانهای کاربری (SMS/Email/Push) برای Users
|
||||
|
||||
فعلاً فقط Logging فعال است. Integration های اصلی (Sentry, Slack, SMS) آماده پیادهسازی هستند.
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Application Layer │
|
||||
│ ┌─────────────────────┐ ┌─────────────────────────┐ │
|
||||
│ │ IAlertService │ │ IUserNotificationService│ │
|
||||
│ │ - Critical │ │ - Commission Received │ │
|
||||
│ │ - Warning │ │ - Club Activation │ │
|
||||
│ │ - Success │ │ - Payout Error │ │
|
||||
│ └─────────────────────┘ └─────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
↓ implements
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Infrastructure Layer │
|
||||
│ ┌─────────────────────┐ ┌─────────────────────────┐ │
|
||||
│ │ AlertService │ │ UserNotificationService │ │
|
||||
│ │ ✅ Logging │ │ ✅ Logging │ │
|
||||
│ │ ⏳ Sentry │ │ ⏳ SMS Gateway │ │
|
||||
│ │ ⏳ Slack │ │ ⏳ Email Service │ │
|
||||
│ │ ⏳ Email │ │ ⏳ Push Notification │ │
|
||||
│ └─────────────────────┘ └─────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ MonitoringSettings (Configuration) │ │
|
||||
│ │ - SentryEnabled, SentryDsn │ │
|
||||
│ │ - SlackEnabled, SlackWebhookUrl │ │
|
||||
│ │ - EmailAlertsEnabled, AdminEmails │ │
|
||||
│ │ - SmsNotificationsEnabled, SmsApiKey │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
↓ used by
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Background Workers / Handlers │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ WeeklyNetworkCommissionWorker │ │
|
||||
│ │ - On Success: SendSuccessNotificationAsync() │ │
|
||||
│ │ - On Error: SendCriticalAlertAsync() │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ ProcessUserPayoutsCommandHandler │ │
|
||||
│ │ - On Payout: SendCommissionReceivedNotification│ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Implementation Details
|
||||
|
||||
### 1️⃣ Alert Service (Admin Notifications)
|
||||
|
||||
**Interface**: `CMSMicroservice.Application/Common/Interfaces/IAlertService.cs`
|
||||
|
||||
```csharp
|
||||
public interface IAlertService
|
||||
{
|
||||
Task SendCriticalAlertAsync(string title, string message, Exception? exception, CancellationToken ct);
|
||||
Task SendWarningAlertAsync(string title, string message, CancellationToken ct);
|
||||
Task SendSuccessNotificationAsync(string title, string message, CancellationToken ct);
|
||||
}
|
||||
```
|
||||
|
||||
**Implementation**: `CMSMicroservice.Infrastructure/Services/Monitoring/AlertService.cs`
|
||||
|
||||
**Current Behavior**:
|
||||
```
|
||||
🚨 CRITICAL ALERT: {Title} - {Message}
|
||||
⚠️ WARNING ALERT: {Title} - {Message}
|
||||
✅ SUCCESS: {Title} - {Message}
|
||||
```
|
||||
|
||||
**Pending Integrations**:
|
||||
- **Sentry**: Exception tracking & aggregation (TODO: `SentrySdk.CaptureException()`)
|
||||
- **Slack**: Real-time alerts to channel (TODO: HTTP POST to webhook)
|
||||
- **Email**: Alert emails to admin list (TODO: SMTP integration)
|
||||
|
||||
---
|
||||
|
||||
### 2️⃣ User Notification Service
|
||||
|
||||
**Interface**: `CMSMicroservice.Application/Common/Interfaces/IAlertService.cs` (same file)
|
||||
|
||||
```csharp
|
||||
public interface IUserNotificationService
|
||||
{
|
||||
Task SendCommissionReceivedNotificationAsync(long userId, decimal amount, int weekNumber, CancellationToken ct);
|
||||
Task SendClubActivationNotificationAsync(long userId, CancellationToken ct);
|
||||
Task SendPayoutErrorNotificationAsync(long userId, string errorMessage, CancellationToken ct);
|
||||
}
|
||||
```
|
||||
|
||||
**Implementation**: `CMSMicroservice.Infrastructure/Services/Monitoring/UserNotificationService.cs`
|
||||
|
||||
**Current Behavior**:
|
||||
```
|
||||
📧 Sending commission notification: User={UserId}, Amount={Amount}, Week={WeekNumber}
|
||||
🎉 Sending club activation notification: User={UserId}
|
||||
⚠️ Sending payout error notification: User={UserId}, Error={Error}
|
||||
```
|
||||
|
||||
**Pending Integrations**:
|
||||
- **SMS Gateway**: Kavenegar/Ghasedak integration (TODO: HTTP API call)
|
||||
- **Email Service**: SMTP/SendGrid integration (TODO: template-based emails)
|
||||
- **Push Notification**: FCM/OneSignal integration (TODO: mobile app notifications)
|
||||
|
||||
---
|
||||
|
||||
### 3️⃣ Configuration Model
|
||||
|
||||
**File**: `CMSMicroservice.Infrastructure/Services/Monitoring/MonitoringSettings.cs`
|
||||
|
||||
```csharp
|
||||
public class MonitoringSettings
|
||||
{
|
||||
public const string SectionName = "Monitoring";
|
||||
|
||||
// Sentry
|
||||
public bool SentryEnabled { get; set; }
|
||||
public string? SentryDsn { get; set; }
|
||||
|
||||
// Slack
|
||||
public bool SlackEnabled { get; set; }
|
||||
public string? SlackWebhookUrl { get; set; }
|
||||
|
||||
// Email Alerts (Admin)
|
||||
public bool EmailAlertsEnabled { get; set; }
|
||||
public List<string> AdminEmails { get; set; }
|
||||
|
||||
// SMS (User Notifications)
|
||||
public bool SmsNotificationsEnabled { get; set; }
|
||||
public string? SmsApiKey { get; set; }
|
||||
public string? SmsGatewayUrl { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
**Config File**: `CMSMicroservice.WebApi/appsettings.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"Monitoring": {
|
||||
"SentryEnabled": false,
|
||||
"SentryDsn": "",
|
||||
"SlackEnabled": false,
|
||||
"SlackWebhookUrl": "",
|
||||
"EmailAlertsEnabled": false,
|
||||
"AdminEmails": ["admin@example.com"],
|
||||
"SmsNotificationsEnabled": false,
|
||||
"SmsApiKey": "",
|
||||
"SmsGatewayUrl": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4️⃣ Dependency Injection
|
||||
|
||||
**File**: `CMSMicroservice.Infrastructure/ConfigureServices.cs`
|
||||
|
||||
```csharp
|
||||
services.AddScoped<IAlertService, AlertService>();
|
||||
services.AddScoped<IUserNotificationService, UserNotificationService>();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5️⃣ Worker Integration
|
||||
|
||||
**File**: `CMSMicroservice.Infrastructure/BackgroundJobs/WeeklyNetworkCommissionWorker.cs`
|
||||
|
||||
**On Success**:
|
||||
```csharp
|
||||
await alertService.SendSuccessNotificationAsync(
|
||||
"Weekly Commission Completed",
|
||||
$"Week {previousWeekNumber}: {payoutsProcessed} payouts, {balancesToExpire.Count} balances expired");
|
||||
```
|
||||
|
||||
**On Error**:
|
||||
```csharp
|
||||
await alertService.SendCriticalAlertAsync(
|
||||
"Weekly Commission Worker Failed",
|
||||
$"Worker execution {executionId} failed for week {GetPreviousWeekNumber()}",
|
||||
ex,
|
||||
cancellationToken);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔌 Integration Roadmap
|
||||
|
||||
### Priority 1: Sentry (High - 1 hour)
|
||||
|
||||
**Why**: Critical error tracking & aggregation برای Production
|
||||
|
||||
**Steps**:
|
||||
1. Install NuGet:
|
||||
```bash
|
||||
dotnet add package Sentry.AspNetCore
|
||||
```
|
||||
|
||||
2. Configure in `Program.cs`:
|
||||
```csharp
|
||||
builder.WebHost.UseSentry(options =>
|
||||
{
|
||||
options.Dsn = builder.Configuration["Monitoring:SentryDsn"];
|
||||
options.Environment = builder.Environment.EnvironmentName;
|
||||
options.TracesSampleRate = 1.0;
|
||||
});
|
||||
```
|
||||
|
||||
3. Update `AlertService.SendCriticalAlertAsync()`:
|
||||
```csharp
|
||||
if (_settings.SentryEnabled && exception != null)
|
||||
{
|
||||
SentrySdk.CaptureException(exception, scope =>
|
||||
{
|
||||
scope.SetTag("alert.title", title);
|
||||
scope.SetExtra("message", message);
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
4. Set DSN in `appsettings.Production.json`:
|
||||
```json
|
||||
{
|
||||
"Monitoring": {
|
||||
"SentryEnabled": true,
|
||||
"SentryDsn": "https://xxxxx@sentry.io/12345"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Priority 2: Slack Webhook (Medium - 2 hours)
|
||||
|
||||
**Why**: Real-time alerts به تیم Development/DevOps
|
||||
|
||||
**Steps**:
|
||||
1. Create Incoming Webhook در Slack:
|
||||
- Go to: `https://api.slack.com/apps`
|
||||
- Create app → Incoming Webhooks → Add to channel
|
||||
- Copy Webhook URL
|
||||
|
||||
2. Update `AlertService`:
|
||||
```csharp
|
||||
private readonly HttpClient _httpClient;
|
||||
|
||||
public async Task SendCriticalAlertAsync(...)
|
||||
{
|
||||
_logger.LogCritical(exception, "🚨 {Title} - {Message}", title, message);
|
||||
|
||||
if (_settings.SlackEnabled)
|
||||
{
|
||||
var payload = new
|
||||
{
|
||||
text = $"🚨 *{title}*",
|
||||
attachments = new[]
|
||||
{
|
||||
new
|
||||
{
|
||||
color = "danger",
|
||||
text = message,
|
||||
fields = exception != null ? new[]
|
||||
{
|
||||
new { title = "Exception", value = exception.Message, @short = false }
|
||||
} : null
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
await _httpClient.PostAsJsonAsync(_settings.SlackWebhookUrl, payload);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. Set Webhook URL in config:
|
||||
```json
|
||||
{
|
||||
"Monitoring": {
|
||||
"SlackEnabled": true,
|
||||
"SlackWebhookUrl": "https://hooks.slack.com/services/T00/B00/XXX"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Priority 3: SMS Gateway - Kavenegar (Medium - 3 hours)
|
||||
|
||||
**Why**: اطلاعرسانی کمیسیون به کاربران
|
||||
|
||||
**Steps**:
|
||||
1. Get API Key from Kavenegar:
|
||||
- Sign up: `https://panel.kavenegar.com`
|
||||
- API Key: Settings → API Key
|
||||
|
||||
2. Create `ISmsGatewayService`:
|
||||
```csharp
|
||||
public interface ISmsGatewayService
|
||||
{
|
||||
Task SendAsync(string mobile, string message, CancellationToken ct = default);
|
||||
}
|
||||
```
|
||||
|
||||
3. Implement `KavenegarSmsService`:
|
||||
```csharp
|
||||
public class KavenegarSmsService : ISmsGatewayService
|
||||
{
|
||||
private readonly HttpClient _httpClient;
|
||||
private readonly string _apiKey;
|
||||
|
||||
public async Task SendAsync(string mobile, string message, CancellationToken ct)
|
||||
{
|
||||
var url = $"https://api.kavenegar.com/v1/{_apiKey}/sms/send.json";
|
||||
var payload = new
|
||||
{
|
||||
receptor = mobile,
|
||||
message = message
|
||||
};
|
||||
|
||||
var response = await _httpClient.PostAsJsonAsync(url, payload, ct);
|
||||
response.EnsureSuccessStatusCode();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
4. Update `UserNotificationService.SendCommissionReceivedNotificationAsync()`:
|
||||
```csharp
|
||||
var user = await _context.Users.FindAsync(userId, ct);
|
||||
|
||||
if (user.SmsNotifications && _settings.SmsNotificationsEnabled)
|
||||
{
|
||||
var message = $"کمیسیون شما: {amount:N0} ریال برای هفته {weekNumber} واریز شد.";
|
||||
await _smsGateway.SendAsync(user.Mobile, message, ct);
|
||||
}
|
||||
```
|
||||
|
||||
5. Configure:
|
||||
```json
|
||||
{
|
||||
"Monitoring": {
|
||||
"SmsNotificationsEnabled": true,
|
||||
"SmsApiKey": "your-kavenegar-api-key"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Priority 4: Email Alerts for Admins (Low - 2 hours)
|
||||
|
||||
**Why**: Backup notification channel
|
||||
|
||||
**Options**:
|
||||
- **A) MailKit (SMTP)**:
|
||||
```csharp
|
||||
using var client = new SmtpClient();
|
||||
await client.ConnectAsync("smtp.gmail.com", 587, SecureSocketOptions.StartTls);
|
||||
await client.AuthenticateAsync("user@example.com", "password");
|
||||
|
||||
var message = new MimeMessage();
|
||||
message.From.Add(new MailboxAddress("CMS Alerts", "noreply@foursat.ir"));
|
||||
message.To.Add(new MailboxAddress("Admin", adminEmail));
|
||||
message.Subject = $"[ALERT] {title}";
|
||||
message.Body = new TextPart("html") { Text = htmlMessage };
|
||||
|
||||
await client.SendAsync(message);
|
||||
```
|
||||
|
||||
- **B) SendGrid API**:
|
||||
```csharp
|
||||
var client = new SendGridClient(_settings.SendGridApiKey);
|
||||
var msg = MailHelper.CreateSingleEmail(
|
||||
from: new EmailAddress("noreply@foursat.ir", "CMS Alerts"),
|
||||
to: new EmailAddress(adminEmail),
|
||||
subject: $"[ALERT] {title}",
|
||||
plainTextContent: message,
|
||||
htmlContent: htmlMessage
|
||||
);
|
||||
await client.SendEmailAsync(msg);
|
||||
```
|
||||
|
||||
**Config**:
|
||||
```json
|
||||
{
|
||||
"Monitoring": {
|
||||
"EmailAlertsEnabled": true,
|
||||
"AdminEmails": ["admin@foursat.ir", "devops@foursat.ir"],
|
||||
"SmtpServer": "smtp.gmail.com",
|
||||
"SmtpPort": 587,
|
||||
"SmtpUsername": "user@example.com",
|
||||
"SmtpPassword": "password"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Priority 5: Retry Logic با Exponential Backoff (Low - 1 hour)
|
||||
|
||||
**Why**: بهبود Reliability در صورت خطاهای Transient
|
||||
|
||||
**Implementation در Worker**:
|
||||
```csharp
|
||||
private async Task<T> RetryWithExponentialBackoffAsync<T>(
|
||||
Func<Task<T>> operation,
|
||||
int maxRetries = 3,
|
||||
CancellationToken ct = default)
|
||||
{
|
||||
for (int attempt = 0; attempt <= maxRetries; attempt++)
|
||||
{
|
||||
try
|
||||
{
|
||||
return await operation();
|
||||
}
|
||||
catch (Exception ex) when (attempt < maxRetries && IsTransientError(ex))
|
||||
{
|
||||
var delay = TimeSpan.FromSeconds(Math.Pow(2, attempt)); // 2^n: 1s, 2s, 4s
|
||||
|
||||
_logger.LogWarning(ex,
|
||||
"Attempt {Attempt}/{MaxRetries} failed. Retrying in {Delay}s...",
|
||||
attempt + 1, maxRetries, delay.TotalSeconds);
|
||||
|
||||
await Task.Delay(delay, ct);
|
||||
}
|
||||
}
|
||||
|
||||
throw new InvalidOperationException($"Operation failed after {maxRetries} retries");
|
||||
}
|
||||
|
||||
private bool IsTransientError(Exception ex)
|
||||
{
|
||||
return ex is TimeoutException
|
||||
|| ex is HttpRequestException
|
||||
|| (ex is SqlException sqlEx && sqlEx.IsTransient);
|
||||
}
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```csharp
|
||||
// در ExecuteWeeklyCalculationAsync():
|
||||
var balancesCalculated = await RetryWithExponentialBackoffAsync(async () =>
|
||||
{
|
||||
return await mediator.Send(new CalculateWeeklyBalancesCommand
|
||||
{
|
||||
WeekNumber = previousWeekNumber
|
||||
}, cancellationToken);
|
||||
}, maxRetries: 3, ct: cancellationToken);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Guide
|
||||
|
||||
### Test 1: Alert Service (Console Logging)
|
||||
```csharp
|
||||
// در Controller یا Handler:
|
||||
var alertService = _serviceProvider.GetRequiredService<IAlertService>();
|
||||
|
||||
await alertService.SendCriticalAlertAsync(
|
||||
"Test Critical Alert",
|
||||
"این یک تست برای Alert Service است",
|
||||
new Exception("Sample exception"));
|
||||
|
||||
await alertService.SendSuccessNotificationAsync(
|
||||
"Test Success",
|
||||
"عملیات با موفقیت انجام شد");
|
||||
```
|
||||
|
||||
**Expected Output**:
|
||||
```
|
||||
🚨 CRITICAL ALERT: Test Critical Alert - این یک تست برای Alert Service است
|
||||
✅ SUCCESS: Test Success - عملیات با موفقیت انجام شد
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Test 2: User Notification Service
|
||||
```csharp
|
||||
var notificationService = _serviceProvider.GetRequiredService<IUserNotificationService>();
|
||||
|
||||
await notificationService.SendCommissionReceivedNotificationAsync(
|
||||
userId: 123,
|
||||
amount: 500_000,
|
||||
weekNumber: 48);
|
||||
```
|
||||
|
||||
**Expected Output**:
|
||||
```
|
||||
📧 Sending commission notification: User=123, Amount=500000, Week=48
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Test 3: Worker Integration
|
||||
```bash
|
||||
# Run Worker manually (for testing)
|
||||
# تغییر زمان اجرا به 1 دقیقه بعد برای تست:
|
||||
# در Worker: var delay = TimeSpan.FromMinutes(1);
|
||||
dotnet run --project CMSMicroservice.WebApi
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- Worker starts
|
||||
- After 1 minute → Executes calculation
|
||||
- On success → Logs: `✅ SUCCESS: Weekly Commission Completed`
|
||||
- On error → Logs: `🚨 CRITICAL ALERT: Weekly Commission Worker Failed`
|
||||
|
||||
---
|
||||
|
||||
### Test 4: Sentry Integration (بعد از پیادهسازی)
|
||||
```csharp
|
||||
// Throw یک exception برای تست:
|
||||
throw new InvalidOperationException("Test Sentry integration");
|
||||
```
|
||||
|
||||
**Check**: Sentry dashboard → Issues → باید exception جدید نمایش داده شود
|
||||
|
||||
---
|
||||
|
||||
### Test 5: Slack Integration (بعد از پیادهسازی)
|
||||
```csharp
|
||||
await alertService.SendCriticalAlertAsync("Test Slack", "Testing webhook integration", null);
|
||||
```
|
||||
|
||||
**Check**: Slack channel → باید پیام جدید نمایش داده شود
|
||||
|
||||
---
|
||||
|
||||
### Test 6: SMS Integration (بعد از پیادهسازی)
|
||||
```csharp
|
||||
await notificationService.SendCommissionReceivedNotificationAsync(
|
||||
userId: YOUR_USER_ID, // با شماره موبایل معتبر
|
||||
amount: 100_000,
|
||||
weekNumber: 48);
|
||||
```
|
||||
|
||||
**Check**: موبایل کاربر → باید SMS دریافت شود
|
||||
|
||||
---
|
||||
|
||||
## 📊 Current Status & Progress
|
||||
|
||||
| Component | Status | Completion | Notes |
|
||||
|-----------|--------|------------|-------|
|
||||
| **Interfaces** | ✅ Done | 100% | `IAlertService`, `IUserNotificationService` |
|
||||
| **Skeleton Implementations** | ✅ Done | 100% | Logging only |
|
||||
| **Configuration Model** | ✅ Done | 100% | `MonitoringSettings` |
|
||||
| **DI Registration** | ✅ Done | 100% | In `ConfigureServices.cs` |
|
||||
| **Worker Integration** | ✅ Done | 100% | Success + Error alerts |
|
||||
| **appsettings Structure** | ✅ Done | 100% | Monitoring section added |
|
||||
| **Sentry Integration** | ⏳ Pending | 0% | Install package + configure DSN |
|
||||
| **Slack Webhook** | ⏳ Pending | 0% | Create webhook + implement POST |
|
||||
| **SMS Gateway** | ⏳ Pending | 0% | Choose provider + get API key |
|
||||
| **Email Alerts** | ⏳ Pending | 0% | SMTP/SendGrid integration |
|
||||
| **Retry Logic** | ⏳ Pending | 0% | Exponential backoff implementation |
|
||||
| **Testing** | ⏳ Pending | 0% | Unit + Integration tests |
|
||||
|
||||
**Overall Progress**: 30% ✅ | 70% ⏳
|
||||
|
||||
---
|
||||
|
||||
## 📝 Important Notes
|
||||
|
||||
### 1. Production Readiness
|
||||
- ⚠️ **فعلاً فقط Logging فعال است**
|
||||
- ⚠️ برای Production **حداقل Sentry** باید فعال شود
|
||||
- ⚠️ برای Critical systems حتماً Slack هم اضافه شود
|
||||
|
||||
### 2. User Preferences
|
||||
- SMS/Email/Push باید بر اساس تنظیمات کاربر (`User.SmsNotifications`, etc.) ارسال شود
|
||||
- در `UserNotificationService` باید ابتدا preferences چک شود
|
||||
|
||||
### 3. Rate Limiting
|
||||
- برای SMS Gateway باید Rate Limiting در نظر گرفته شود
|
||||
- پیشنهاد: استفاده از Queue (Hangfire/RabbitMQ) برای ارسال تعداد زیاد SMS
|
||||
|
||||
### 4. Cost Management
|
||||
- SMS و Email هزینه دارند
|
||||
- پیشنهاد: Batching برای ارسال گروهی
|
||||
- پیشنهاد: Template-based messaging برای کاهش هزینه
|
||||
|
||||
### 5. Security
|
||||
- API Keys در `appsettings.json` نباید commit شوند
|
||||
- استفاده از Environment Variables یا Azure Key Vault
|
||||
- مثال: `SmsApiKey: ${SMS_API_KEY}` در appsettings
|
||||
|
||||
### 6. Monitoring the Monitor
|
||||
- خود Alert System هم باید Monitor شود
|
||||
- اگر Slack/SMS fail شد، باید Fallback به Email یا Log باشد
|
||||
- پیشنهاد: Dead Letter Queue برای failed notifications
|
||||
|
||||
---
|
||||
|
||||
## 🔗 File Reference Map
|
||||
|
||||
```
|
||||
CMS/
|
||||
├── src/
|
||||
│ ├── CMSMicroservice.Application/
|
||||
│ │ └── Common/
|
||||
│ │ └── Interfaces/
|
||||
│ │ └── IAlertService.cs ⭐
|
||||
│ │
|
||||
│ ├── CMSMicroservice.Infrastructure/
|
||||
│ │ ├── Services/
|
||||
│ │ │ └── Monitoring/
|
||||
│ │ │ ├── AlertService.cs ⭐
|
||||
│ │ │ ├── UserNotificationService.cs ⭐
|
||||
│ │ │ └── MonitoringSettings.cs ⭐
|
||||
│ │ │
|
||||
│ │ ├── BackgroundJobs/
|
||||
│ │ │ └── WeeklyNetworkCommissionWorker.cs ✏️ (Modified)
|
||||
│ │ │
|
||||
│ │ └── ConfigureServices.cs ✏️ (Modified)
|
||||
│ │
|
||||
│ └── CMSMicroservice.WebApi/
|
||||
│ └── appsettings.json ✏️ (Modified)
|
||||
│
|
||||
└── docs/
|
||||
└── monitoring-alerts-implementation-report.md 📄 (This file)
|
||||
```
|
||||
|
||||
**Legend**:
|
||||
- ⭐ = New file created
|
||||
- ✏️ = Existing file modified
|
||||
- 📄 = Documentation
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Next Action Items
|
||||
|
||||
### Immediate (این هفته):
|
||||
1. ✅ Review this document
|
||||
2. ⏳ Decision: کدام Integration اول؟ (پیشنهاد: Sentry)
|
||||
3. ⏳ Get credentials:
|
||||
- Sentry DSN
|
||||
- Slack Webhook URL
|
||||
- SMS Gateway API Key
|
||||
|
||||
### Short-term (هفته آینده):
|
||||
4. ⏳ Implement Sentry integration
|
||||
5. ⏳ Implement Slack webhook
|
||||
6. ⏳ Test in Staging environment
|
||||
|
||||
### Long-term (ماه آینده):
|
||||
7. ⏳ Implement SMS Gateway (Kavenegar)
|
||||
8. ⏳ Add Email alerts
|
||||
9. ⏳ Implement Retry logic
|
||||
10. ⏳ Write Unit/Integration tests
|
||||
11. ⏳ Deploy to Production
|
||||
|
||||
---
|
||||
|
||||
## 📞 Contact & Support
|
||||
|
||||
**Implementation Questions**:
|
||||
- Developer: GitHub Copilot (این گزارش)
|
||||
- Review: Development Team
|
||||
|
||||
**Service Providers**:
|
||||
- **Sentry**: https://sentry.io (Error tracking)
|
||||
- **Slack**: https://api.slack.com/messaging/webhooks (Webhooks)
|
||||
- **Kavenegar**: https://kavenegar.com (SMS Gateway - Iran)
|
||||
- **Ghasedak**: https://ghasedak.me (SMS Gateway Alternative)
|
||||
- **SendGrid**: https://sendgrid.com (Email service)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-11-30
|
||||
**Build Status**: ✅ Success
|
||||
**Ready for**: Integration implementation
|
||||
|
||||
---
|
||||
|
||||
## 🎯 TL;DR (خلاصه برای رجوع سریع)
|
||||
|
||||
### چی ساخته شد:
|
||||
- ✅ `IAlertService` + `AlertService` (Admin alerts)
|
||||
- ✅ `IUserNotificationService` + `UserNotificationService` (User notifications)
|
||||
- ✅ `MonitoringSettings` (Configuration model)
|
||||
- ✅ Worker integration (Success/Error alerts)
|
||||
- ✅ DI registration
|
||||
- ✅ appsettings structure
|
||||
|
||||
### فعلاً چی کار میکنه:
|
||||
- Logging به Console (🚨 Critical, ⚠️ Warning, ✅ Success)
|
||||
|
||||
### چی باید اضافه بشه:
|
||||
1. **Sentry** - Error tracking (Priority: High)
|
||||
2. **Slack** - Real-time alerts (Priority: Medium)
|
||||
3. **SMS Gateway** - User notifications (Priority: Medium)
|
||||
4. **Email** - Backup channel (Priority: Low)
|
||||
5. **Retry Logic** - Reliability (Priority: Low)
|
||||
|
||||
### کجا باید نگاه کنی:
|
||||
- Interfaces: `CMSMicroservice.Application/Common/Interfaces/IAlertService.cs`
|
||||
- Implementations: `CMSMicroservice.Infrastructure/Services/Monitoring/`
|
||||
- Worker: `CMSMicroservice.Infrastructure/BackgroundJobs/WeeklyNetworkCommissionWorker.cs`
|
||||
- Config: `CMSMicroservice.WebApi/appsettings.json`
|
||||
|
||||
### چطوری تست کنی:
|
||||
```csharp
|
||||
await alertService.SendCriticalAlertAsync("Test", "Message", null);
|
||||
// Output: 🚨 CRITICAL ALERT: Test - Message
|
||||
```
|
||||
|
||||
### بعدش چیکار کنم:
|
||||
1. Get Sentry DSN → Update appsettings.Production.json
|
||||
2. Install `Sentry.AspNetCore` → Configure in Program.cs
|
||||
3. Update `AlertService.SendCriticalAlertAsync()` → Add `SentrySdk.CaptureException()`
|
||||
4. Test → Deploy
|
||||
@@ -1,333 +0,0 @@
|
||||
# 📊 Monitoring & Alerts System - Implementation Report
|
||||
|
||||
**Date**: 2025-11-30
|
||||
**Status**: ✅ Skeleton Implemented
|
||||
**Completion**: 30% (Structure ready, integrations pending)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Overview
|
||||
|
||||
اسکلت سیستم **Monitoring & Alerts** برای پروژه CMS پیادهسازی شد. این سیستم به دو بخش اصلی تقسیم میشود:
|
||||
|
||||
1. **Alert System**: برای ارسال اعلانهای مدیریتی (Critical Errors, Warnings, Success)
|
||||
2. **User Notification System**: برای ارسال پیام به کاربران (کمیسیون، پرداخت، فعالسازی باشگاه)
|
||||
|
||||
---
|
||||
|
||||
## 📦 Files Created/Modified
|
||||
|
||||
### ✨ New Files:
|
||||
|
||||
1. **`IAlertService.cs`** (Interface)
|
||||
- `SendCriticalAlertAsync()` - برای خطاهای Critical
|
||||
- `SendWarningAlertAsync()` - برای Warning ها
|
||||
- `SendSuccessNotificationAsync()` - برای موفقیتها
|
||||
|
||||
2. **`IUserNotificationService.cs`** (Interface)
|
||||
- `SendCommissionReceivedNotificationAsync()` - اعلان دریافت کمیسیون
|
||||
- `SendClubActivationNotificationAsync()` - اعلان فعالسازی باشگاه
|
||||
- `SendPayoutErrorNotificationAsync()` - اعلان خطا در پرداخت
|
||||
|
||||
3. **`AlertService.cs`** (Implementation - Skeleton)
|
||||
- ✅ Logging به Console
|
||||
- ⏳ TODO: Sentry Integration
|
||||
- ⏳ TODO: Slack Integration
|
||||
- ⏳ TODO: Email Integration
|
||||
|
||||
4. **`UserNotificationService.cs`** (Implementation - Skeleton)
|
||||
- ✅ Logging به Console
|
||||
- ⏳ TODO: SMS Gateway Integration
|
||||
- ⏳ TODO: Email Service Integration
|
||||
- ⏳ TODO: Push Notification Integration
|
||||
|
||||
5. **`MonitoringSettings.cs`** (Configuration Model)
|
||||
- تنظیمات Sentry, Slack, Email, SMS
|
||||
- قابل تنظیم از طریق `appsettings.json`
|
||||
|
||||
---
|
||||
|
||||
### ✏️ Modified Files:
|
||||
|
||||
1. **`ConfigureServices.cs`**
|
||||
```csharp
|
||||
services.AddScoped<IAlertService, AlertService>();
|
||||
services.AddScoped<IUserNotificationService, UserNotificationService>();
|
||||
```
|
||||
|
||||
2. **`WeeklyNetworkCommissionWorker.cs`**
|
||||
- ✅ Integration با `IAlertService`
|
||||
- ✅ ارسال Critical Alert در صورت خطا
|
||||
- ✅ ارسال Success Notification پس از اتمام موفق
|
||||
|
||||
3. **`appsettings.json`**
|
||||
- اضافه شدن بخش `Monitoring` با تنظیمات پیشفرض
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Current Implementation
|
||||
|
||||
### Alert System Usage:
|
||||
|
||||
```csharp
|
||||
// در Worker یا هر Handler دیگر:
|
||||
try
|
||||
{
|
||||
// عملیات خطرناک
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
await _alertService.SendCriticalAlertAsync(
|
||||
"Operation Failed",
|
||||
"Description of what went wrong",
|
||||
ex);
|
||||
}
|
||||
```
|
||||
|
||||
### Current Output:
|
||||
```
|
||||
🚨 CRITICAL ALERT: Weekly Commission Worker Failed - Worker execution abc-123 failed for week 2025-W48
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⏳ Pending Integrations (TODO)
|
||||
|
||||
### 1. Sentry Integration
|
||||
```csharp
|
||||
// در AlertService.SendCriticalAlertAsync():
|
||||
if (_settings.SentryEnabled)
|
||||
{
|
||||
SentrySdk.CaptureException(exception);
|
||||
}
|
||||
```
|
||||
|
||||
**Steps**:
|
||||
- Install NuGet: `Sentry.AspNetCore`
|
||||
- Configure DSN in `appsettings.json`
|
||||
- Add to `Program.cs`: `builder.WebHost.UseSentry()`
|
||||
|
||||
---
|
||||
|
||||
### 2. Slack Integration
|
||||
```csharp
|
||||
// در AlertService:
|
||||
if (_settings.SlackEnabled)
|
||||
{
|
||||
var payload = new
|
||||
{
|
||||
text = $"🚨 {title}",
|
||||
attachments = new[]
|
||||
{
|
||||
new { text = message, color = "danger" }
|
||||
}
|
||||
};
|
||||
|
||||
await _httpClient.PostAsJsonAsync(_settings.SlackWebhookUrl, payload);
|
||||
}
|
||||
```
|
||||
|
||||
**Steps**:
|
||||
- Create Slack Incoming Webhook
|
||||
- Add URL to `appsettings.json`
|
||||
- Install NuGet: `System.Net.Http.Json`
|
||||
|
||||
---
|
||||
|
||||
### 3. Email Alerts (برای Admin)
|
||||
```csharp
|
||||
// در AlertService:
|
||||
if (_settings.EmailAlertsEnabled)
|
||||
{
|
||||
foreach (var email in _settings.AdminEmails)
|
||||
{
|
||||
await _emailService.SendAsync(
|
||||
to: email,
|
||||
subject: $"[ALERT] {title}",
|
||||
body: message);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Steps**:
|
||||
- Configure SMTP settings
|
||||
- Install NuGet: `MailKit` or use existing email service
|
||||
- Add admin emails to config
|
||||
|
||||
---
|
||||
|
||||
### 4. SMS Notifications (برای کاربران)
|
||||
```csharp
|
||||
// در UserNotificationService.SendCommissionReceivedNotificationAsync():
|
||||
var user = await _context.Users.FindAsync(userId);
|
||||
|
||||
if (user.SmsNotifications && _settings.SmsNotificationsEnabled)
|
||||
{
|
||||
var message = $"کمیسیون شما: {amount:N0} ریال برای هفته {weekNumber} واریز شد.";
|
||||
|
||||
await _smsGateway.SendAsync(user.Mobile, message);
|
||||
}
|
||||
```
|
||||
|
||||
**Steps**:
|
||||
- Choose SMS provider (Kavenegar, Ghasedak, etc.)
|
||||
- Get API Key
|
||||
- Implement `ISmsGatewayService`
|
||||
|
||||
---
|
||||
|
||||
### 5. Retry Logic با Exponential Backoff
|
||||
```csharp
|
||||
// در Worker:
|
||||
private async Task<T> RetryWithExponentialBackoff<T>(
|
||||
Func<Task<T>> operation,
|
||||
int maxRetries = 3)
|
||||
{
|
||||
for (int i = 0; i < maxRetries; i++)
|
||||
{
|
||||
try
|
||||
{
|
||||
return await operation();
|
||||
}
|
||||
catch (Exception ex) when (i < maxRetries - 1)
|
||||
{
|
||||
var delay = TimeSpan.FromSeconds(Math.Pow(2, i)); // 2^i seconds
|
||||
_logger.LogWarning("Retry {Attempt}/{Max} after {Delay}s",
|
||||
i + 1, maxRetries, delay.TotalSeconds);
|
||||
await Task.Delay(delay);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Configuration Example
|
||||
|
||||
در `appsettings.Production.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"Monitoring": {
|
||||
"SentryEnabled": true,
|
||||
"SentryDsn": "https://xxxxx@sentry.io/12345",
|
||||
|
||||
"SlackEnabled": true,
|
||||
"SlackWebhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX",
|
||||
|
||||
"EmailAlertsEnabled": true,
|
||||
"AdminEmails": [
|
||||
"admin@foursat.ir",
|
||||
"devops@foursat.ir"
|
||||
],
|
||||
|
||||
"SmsNotificationsEnabled": true,
|
||||
"SmsApiKey": "your-kavenegar-api-key",
|
||||
"SmsGatewayUrl": "https://api.kavenegar.com/v1/{apikey}/sms/send.json"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Test 1: Alert Service
|
||||
```csharp
|
||||
var alertService = serviceProvider.GetRequiredService<IAlertService>();
|
||||
|
||||
await alertService.SendCriticalAlertAsync(
|
||||
"Test Alert",
|
||||
"This is a test critical alert");
|
||||
```
|
||||
|
||||
**Expected**: Log در Console + (در Production) Sentry + Slack
|
||||
|
||||
---
|
||||
|
||||
### Test 2: User Notification
|
||||
```csharp
|
||||
var notificationService = serviceProvider.GetRequiredService<IUserNotificationService>();
|
||||
|
||||
await notificationService.SendCommissionReceivedNotificationAsync(
|
||||
userId: 123,
|
||||
amount: 500_000,
|
||||
weekNumber: 48);
|
||||
```
|
||||
|
||||
**Expected**: Log در Console + (در Production) SMS + Email
|
||||
|
||||
---
|
||||
|
||||
## 📊 Integration Priority
|
||||
|
||||
| Priority | Integration | Effort | Impact |
|
||||
|----------|------------|--------|--------|
|
||||
| 🔴 High | Sentry | 1 hour | Critical error tracking |
|
||||
| 🟡 Medium | Slack | 2 hours | Real-time admin alerts |
|
||||
| 🟡 Medium | SMS (Kavenegar) | 3 hours | User notifications |
|
||||
| 🟢 Low | Email Alerts | 2 hours | Backup notification channel |
|
||||
| 🟢 Low | Retry Logic | 1 hour | Reliability improvement |
|
||||
|
||||
---
|
||||
|
||||
## ✅ Current Status Summary
|
||||
|
||||
### Completed (30%):
|
||||
- ✅ Interface definitions
|
||||
- ✅ Skeleton implementations with Logging
|
||||
- ✅ DI registration
|
||||
- ✅ Worker integration
|
||||
- ✅ Configuration model
|
||||
- ✅ appsettings structure
|
||||
|
||||
### Pending (70%):
|
||||
- ⏳ Sentry integration (5%)
|
||||
- ⏳ Slack webhook (10%)
|
||||
- ⏳ Email service (10%)
|
||||
- ⏳ SMS gateway (15%)
|
||||
- ⏳ Push notifications (10%)
|
||||
- ⏳ Retry logic (5%)
|
||||
- ⏳ Testing (10%)
|
||||
- ⏳ Documentation (5%)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
1. **Immediate** (در صورت نیاز):
|
||||
- Enable Sentry for error tracking
|
||||
- Setup Slack webhook for critical alerts
|
||||
|
||||
2. **Short-term** (هفته آینده):
|
||||
- Integrate SMS gateway (Kavenegar)
|
||||
- Test User notifications
|
||||
|
||||
3. **Long-term** (ماه آینده):
|
||||
- Add Email service
|
||||
- Implement Retry logic
|
||||
- Push notification service
|
||||
|
||||
---
|
||||
|
||||
## 📝 Notes
|
||||
|
||||
- تمام TODO ها در کد با comment مشخص شدهاند
|
||||
- فعلاً فقط Logging فعال است
|
||||
- برای Production باید حتماً یکی از Integration ها (Sentry/Slack) فعال شود
|
||||
- SMS Gateway باید بر اساس پروژه انتخاب شود (Kavenegar, Ghasedak, etc.)
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Related Files
|
||||
|
||||
- **Interfaces**: `CMSMicroservice.Application/Common/Interfaces/IAlertService.cs`
|
||||
- **Implementations**: `CMSMicroservice.Infrastructure/Services/Monitoring/`
|
||||
- **Worker**: `CMSMicroservice.Infrastructure/BackgroundJobs/WeeklyNetworkCommissionWorker.cs`
|
||||
- **Config**: `CMSMicroservice.WebApi/appsettings.json`
|
||||
|
||||
---
|
||||
|
||||
**Report generated**: 2025-11-30
|
||||
**Build Status**: ✅ Success
|
||||
**Ready for**: Development continuation / Integration implementation
|
||||
@@ -1,905 +0,0 @@
|
||||
# سیستم باشگاه مشتریان و محاسبه کمیسیون شبکه
|
||||
|
||||
## خلاصه اجرایی
|
||||
این سند تحلیل جامع و معماری پیشنهادی برای پیادهسازی سیستم باشگاه مشتریان (Club Membership) و محاسبه کمیسیون شبکهای (MLM Binary Plan) را ارائه میدهد. این سیستم امکان مدیریت سه نوع کیف پول، فروشگاه اختصاصی با تخفیف، و توزیع عادلانه کمیسیون بر اساس تعادل شبکه را فراهم میکند.
|
||||
|
||||
---
|
||||
|
||||
## ۱. مفاهیم کلیدی
|
||||
|
||||
### ۱.۱ کیف پولهای سهگانه
|
||||
هر کاربر سه نوع کیف پول دارد:
|
||||
|
||||
1. **کیف پول اصلی (Balance)**: برای خرید از فروشگاه عمومی بازار
|
||||
2. **کیف پول تخفیف (DiscountBalance)**: فقط برای خرید از فروشگاه باشگاه مشتریان (محدود به درصد تخفیف محصولات)
|
||||
3. **کیف پول طلایی/کارمزد (NetworkBalance)**: دریافتی از کمیسیون شبکهای - قابل برداشت نقدی یا خرید الماس از دایا
|
||||
|
||||
### ۱.۲ فعالسازی عضویت
|
||||
- کاربر ۵۶ میلیون تومان پرداخت میکند (از طریق دایا یا درگاه)
|
||||
- سیستم به صورت خودکار:
|
||||
- `Balance += 56M` (کیف پول اصلی)
|
||||
- `DiscountBalance += 56M` (کیف پول تخفیف)
|
||||
- کاربر دکمه «عضویت در باشگاه» را میزند:
|
||||
- `25M` به استخر کمیسیون هفتگی اضافه میشود
|
||||
- کاربر در شبکه باینری (Binary Tree) قرار میگیرد
|
||||
|
||||
### ۱.۳ شبکه باینری (Binary MLM Plan)
|
||||
- هر کاربر حداکثر دو زیرمجموعه دارد: **دست راست** و **دست چپ**
|
||||
- تعادل (Balance): زمانی که هر دو شاخه دارای اعضای جدید شوند، یک تعادل ایجاد میشود
|
||||
- **فرمول تعادل**: `UserBalances = MIN(LeftLegBalances, RightLegBalances)`
|
||||
- تعادلها به صورت هفتگی محاسبه و بعد از توزیع کمیسیون، ریست میشوند
|
||||
|
||||
### ۱.۴ محاسبه کمیسیون هفتگی
|
||||
```text
|
||||
مبلغ ریالی هر امتیاز = (مجموع مبالغ استخر) ÷ (مجموع تعادلهای کل سیستم)
|
||||
کمیسیون هر کاربر = (تعداد تعادل کاربر) × (مبلغ ریالی هر امتیاز)
|
||||
```
|
||||
|
||||
**مثال**:
|
||||
- کاربر A: خودش ۱ تعادل + زیرمجموعههایش ۲ تعادل = **۳ امتیاز**
|
||||
- استخر هفتگی: `175M`
|
||||
- مجموع امتیازهای سیستم: `5`
|
||||
- ارزش هر امتیاز: `175M ÷ 5 = 35M`
|
||||
- کمیسیون کاربر A: `3 × 35M = 105M`
|
||||
|
||||
---
|
||||
|
||||
## ۲. موجودیتهای جدید (Domain Entities)
|
||||
|
||||
### ۲.۱ `ClubMembership` (عضویت باشگاه مشتریان)
|
||||
```csharp
|
||||
public class ClubMembership : BaseAuditableEntity
|
||||
{
|
||||
public long UserId { get; set; }
|
||||
public virtual User User { get; set; }
|
||||
|
||||
public bool IsActive { get; set; }
|
||||
public DateTime? ActivatedAt { get; set; }
|
||||
|
||||
// مبلغ اولیه پرداختی برای فعالسازی (معمولاً ۲۵ میلیون)
|
||||
public long InitialContribution { get; set; }
|
||||
|
||||
// مجموع درآمد کارمزد تاکنون
|
||||
public long TotalEarned { get; set; }
|
||||
|
||||
public virtual ICollection<UserClubFeature> UserClubFeatures { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
### ۲.۲ `ClubFeature` (امکانات باشگاه)
|
||||
```csharp
|
||||
public class ClubFeature : BaseAuditableEntity
|
||||
{
|
||||
public string Title { get; set; }
|
||||
public string? Description { get; set; }
|
||||
|
||||
public bool IsActive { get; set; }
|
||||
|
||||
public int? RequiredPoints { get; set; }
|
||||
public int SortOrder { get; set; }
|
||||
|
||||
public virtual ICollection<UserClubFeature> UserClubFeatures { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
### ۲.۳ `UserClubFeature` (امتیاز/فیچرهای فعال برای کاربر)
|
||||
```csharp
|
||||
public class UserClubFeature : BaseAuditableEntity
|
||||
{
|
||||
public long UserId { get; set; }
|
||||
public virtual User User { get; set; }
|
||||
|
||||
public long ClubFeatureId { get; set; }
|
||||
public virtual ClubFeature ClubFeature { get; set; }
|
||||
|
||||
public DateTime GrantedAt { get; set; }
|
||||
public string? Notes { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
### ۲.۴ `NetworkWeeklyBalance` (تعادل هفتگی شبکه)
|
||||
```csharp
|
||||
public class NetworkWeeklyBalance : BaseAuditableEntity
|
||||
{
|
||||
public long UserId { get; set; }
|
||||
public virtual User User { get; set; }
|
||||
|
||||
// مثلاً "2025-W48"
|
||||
public string WeekNumber { get; set; }
|
||||
|
||||
public int LeftLegBalances { get; set; }
|
||||
public int RightLegBalances { get; set; }
|
||||
public int TotalBalances { get; set; }
|
||||
|
||||
// مبلغی که این کاربر همان هفته به استخر اضافه کرده (معمولاً InitialContribution)
|
||||
public long WeeklyPoolContribution { get; set; }
|
||||
|
||||
public DateTime? CalculatedAt { get; set; }
|
||||
public bool IsExpired { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
### ۲.۵ `WeeklyCommissionPool` (استخر کمیسیون هفتگی)
|
||||
```csharp
|
||||
public class WeeklyCommissionPool : BaseAuditableEntity
|
||||
{
|
||||
public string WeekNumber { get; set; }
|
||||
|
||||
public long TotalPoolAmount { get; set; }
|
||||
public int TotalBalances { get; set; }
|
||||
public long ValuePerBalance { get; set; }
|
||||
|
||||
public bool IsCalculated { get; set; }
|
||||
public DateTime? CalculatedAt { get; set; }
|
||||
|
||||
public virtual ICollection<UserCommissionPayout> UserCommissionPayouts { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
### ۲.۶ `UserCommissionPayout` (پرداخت کمیسیون به کاربر)
|
||||
```csharp
|
||||
public class UserCommissionPayout : BaseAuditableEntity
|
||||
{
|
||||
public long UserId { get; set; }
|
||||
public virtual User User { get; set; }
|
||||
|
||||
public string WeekNumber { get; set; }
|
||||
|
||||
public long WeeklyPoolId { get; set; }
|
||||
public virtual WeeklyCommissionPool WeeklyPool { get; set; }
|
||||
|
||||
public int BalancesEarned { get; set; }
|
||||
public long ValuePerBalance { get; set; }
|
||||
public long TotalAmount { get; set; }
|
||||
|
||||
public CommissionPayoutStatus Status { get; set; }
|
||||
|
||||
public DateTime? PaidAt { get; set; }
|
||||
|
||||
public WithdrawalMethod? WithdrawalMethod { get; set; }
|
||||
public string? IbanNumber { get; set; }
|
||||
public DateTime? WithdrawnAt { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ۲.۷ موجودیتهای History (جداول لاگ)
|
||||
|
||||
#### ۲.۷.۱ `ClubMembershipHistory`
|
||||
لاگ تغییرات مهم روی عضویت باشگاه (فعالسازی، غیرفعالسازی، ویرایش):
|
||||
|
||||
```csharp
|
||||
public class ClubMembershipHistory : BaseAuditableEntity
|
||||
{
|
||||
public long ClubMembershipId { get; set; }
|
||||
public long UserId { get; set; }
|
||||
|
||||
public bool OldIsActive { get; set; }
|
||||
public bool NewIsActive { get; set; }
|
||||
|
||||
public long? OldInitialContribution { get; set; }
|
||||
public long? NewInitialContribution { get; set; }
|
||||
|
||||
// Activated / Deactivated / Updated / ManualFix
|
||||
public string Action { get; set; }
|
||||
public string? Reason { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
#### ۲.۷.۲ `NetworkMembershipHistory`
|
||||
برای اینکه همیشه بدانیم «چه کسی زیرمجموعهی کی شده، چه زمانی، و اگر بعداً جابهجا شد چه اتفاقی افتاده»:
|
||||
|
||||
```csharp
|
||||
public class NetworkMembershipHistory : BaseAuditableEntity
|
||||
{
|
||||
public long UserId { get; set; }
|
||||
|
||||
public long? OldParentId { get; set; }
|
||||
public long? NewParentId { get; set; }
|
||||
|
||||
public NetworkLeg? OldLegPosition { get; set; }
|
||||
public NetworkLeg? NewLegPosition { get; set; }
|
||||
|
||||
// Join / Move / Remove
|
||||
public string Action { get; set; }
|
||||
public string? Reason { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
- هر بار `RecordNetworkJoin` یا `UpdateNetworkPosition` صدا زده میشود، باید یک رکورد در این جدول نوشته شود.
|
||||
- این جدول مرجع اصلی برای بازسازی درخت شبکه در زمانهای گذشته است.
|
||||
|
||||
#### ۲.۷.۳ `CommissionPayoutHistory`
|
||||
برای لاگ کامل همهی تغییرات روی پرداخت کمیسیونها (ایجاد، ویرایش دستی، تغییر وضعیت، برداشت و ...):
|
||||
|
||||
```csharp
|
||||
public class CommissionPayoutHistory : BaseAuditableEntity
|
||||
{
|
||||
public long UserCommissionPayoutId { get; set; }
|
||||
public long UserId { get; set; }
|
||||
public string WeekNumber { get; set; }
|
||||
|
||||
public long AmountBefore { get; set; }
|
||||
public long AmountAfter { get; set; }
|
||||
|
||||
public CommissionPayoutStatus OldStatus { get; set; }
|
||||
public CommissionPayoutStatus NewStatus { get; set; }
|
||||
|
||||
// Created / Paid / WithdrawRequested / Withdrawn / Cancelled / ManualFix
|
||||
public string Action { get; set; }
|
||||
public string? PerformedBy { get; set; } // UserId یا System
|
||||
public string? Reason { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
- اگر بعداً بفهمیم یک پرداخت اشتباه بوده و اصلاحش کنیم، اینجا قابل ردیابی است.
|
||||
- برای گزارشگیری Audit کامل پرداختها، این جدول استفاده میشود.
|
||||
|
||||
#### ۲.۷.۴ `SystemConfigurationHistory`
|
||||
تاریخچه تغییرات تنظیمات (Config) برای اینکه بعداً بدانیم در هر زمان چه محدودیتی فعال بوده:
|
||||
|
||||
```csharp
|
||||
public class SystemConfigurationHistory : BaseAuditableEntity
|
||||
{
|
||||
public long ConfigurationId { get; set; }
|
||||
|
||||
public ConfigurationScope Scope { get; set; }
|
||||
public string Key { get; set; }
|
||||
|
||||
public string OldValue { get; set; }
|
||||
public string NewValue { get; set; }
|
||||
|
||||
public string? Reason { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ۲.۸ موجودیتهای Configuration (تنظیمات پویا)
|
||||
|
||||
#### ۲.۸.۱ `ConfigurationScope` (Enum)
|
||||
```csharp
|
||||
public enum ConfigurationScope
|
||||
{
|
||||
System = 0,
|
||||
Network = 1,
|
||||
Club = 2,
|
||||
Commission = 3
|
||||
}
|
||||
```
|
||||
|
||||
#### ۲.۸.۲ `SystemConfiguration`
|
||||
جدولی برای نگهداری تنظیمات پویا. هم تنظیمات عمومی سیستم، هم تنظیمات مخصوص شبکه، باشگاه و کمیسیون:
|
||||
|
||||
```csharp
|
||||
public class SystemConfiguration : BaseAuditableEntity
|
||||
{
|
||||
public ConfigurationScope Scope { get; set; } // System / Network / Club / Commission
|
||||
|
||||
// مثل: "MaxWeeklyBalancesPerUser", "MinContributionAmount", ...
|
||||
public string Key { get; set; }
|
||||
|
||||
// مقدار بهصورت رشته - تفسیر در لایه Application
|
||||
public string Value { get; set; }
|
||||
|
||||
// برای UI و Validation (Int / Decimal / Bool / String / Json)
|
||||
public string? DataType { get; set; }
|
||||
|
||||
public string? Description { get; set; }
|
||||
public bool IsActive { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
**مثال کانفیگهای مرتبط با شبکه:**
|
||||
|
||||
- `Scope = Network`, `Key = "MaxWeeklyBalancesPerUser"`, `Value = "300"`
|
||||
- `Scope = Network`, `Key = "MaxChildrenPerLeg"`, `Value = "1"`
|
||||
- `Scope = Commission`, `Key = "DefaultInitialContribution"`, `Value = "25000000"`
|
||||
|
||||
> نکته: هر بار که مقدار `SystemConfiguration` تغییر میکند، یک رکورد در `SystemConfigurationHistory` ثبت میشود تا تنظیمات گذشته قابل ردیابی باشد.
|
||||
|
||||
---
|
||||
|
||||
### ۲.۹ Enums جدید
|
||||
```csharp
|
||||
public enum CommissionPayoutStatus
|
||||
{
|
||||
Pending = 0,
|
||||
Paid = 1,
|
||||
WithdrawRequested = 2,
|
||||
Withdrawn = 3,
|
||||
Cancelled = 4
|
||||
}
|
||||
|
||||
public enum WithdrawalMethod
|
||||
{
|
||||
Cash = 0,
|
||||
Diamond = 1
|
||||
}
|
||||
|
||||
public enum NetworkLeg
|
||||
{
|
||||
Left = 0,
|
||||
Right = 1
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ۳. تغییرات در موجودیتهای موجود
|
||||
|
||||
### ۳.۱ `User`
|
||||
افزودن فیلدهای مربوط به شبکه باینری و ناوبری:
|
||||
|
||||
```csharp
|
||||
public class User : BaseAuditableEntity
|
||||
{
|
||||
// ...
|
||||
|
||||
public long? NetworkParentId { get; set; }
|
||||
public virtual User? NetworkParent { get; set; }
|
||||
|
||||
public NetworkLeg? LegPosition { get; set; }
|
||||
|
||||
public virtual ICollection<User> NetworkChildren { get; set; }
|
||||
|
||||
public virtual ClubMembership? ClubMembership { get; set; }
|
||||
public virtual ICollection<NetworkWeeklyBalance> NetworkWeeklyBalances { get; set; }
|
||||
public virtual ICollection<UserCommissionPayout> CommissionPayouts { get; set; }
|
||||
|
||||
public virtual ICollection<UserClubFeature> UserClubFeatures { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
### ۳.۲ `UserWallet`
|
||||
```csharp
|
||||
public class UserWallet : BaseAuditableEntity
|
||||
{
|
||||
// موجودی ریالی اصلی
|
||||
public long Balance { get; set; }
|
||||
|
||||
// موجودی شبکه/کارمزد (کیف پول طلایی)
|
||||
public long NetworkBalance { get; set; }
|
||||
|
||||
// موجودی تخفیف (فقط برای خرید از فروشگاه باشگاه)
|
||||
public long DiscountBalance { get; set; }
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### ۳.۳ `Products`
|
||||
```csharp
|
||||
public class Product : BaseAuditableEntity
|
||||
{
|
||||
// ...
|
||||
|
||||
// آیا این محصول فقط در فروشگاه باشگاه موجود است
|
||||
public bool IsClubExclusive { get; set; }
|
||||
|
||||
// درصد تخفیف باشگاه (0 تا 100)
|
||||
public int ClubDiscountPercent { get; set; }
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### ۳.۴ `UserWalletChangeLog`
|
||||
افزودن نوع جدید تراکنش:
|
||||
```csharp
|
||||
public enum TransactionType
|
||||
{
|
||||
// ...
|
||||
|
||||
NetworkCommission = 10, // دریافت کمیسیون شبکه
|
||||
ClubActivation = 11, // فعالسازی عضویت باشگاه
|
||||
DiscountWalletCharge = 12, // شارژ کیف پول تخفیف
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ۴. معماری ماژولهای جدید (Application / CQRS)
|
||||
|
||||
### ۴.۱ `ClubMembershipCQ/`
|
||||
#### Commands
|
||||
- **ActivateClubMembership**: فعالسازی عضویت باشگاه (کسر ۲۵ میلیون و اضافه به استخر)
|
||||
- **DeactivateClubMembership**: غیرفعالسازی عضویت
|
||||
- **UpdateClubMembership**: بهروزرسانی اطلاعات عضویت
|
||||
|
||||
#### Queries
|
||||
- **GetUserClubStatus**: دریافت وضعیت عضویت کاربر
|
||||
- **GetAllClubMembersByFilter**: لیست اعضای باشگاه با فیلتر
|
||||
|
||||
### ۴.۲ `ClubFeatureCQ/`
|
||||
#### Commands
|
||||
- **CreateClubFeature**: ایجاد فیچر جدید
|
||||
- **UpdateClubFeature**: ویرایش فیچر
|
||||
- **DeleteClubFeature**: حذف فیچر
|
||||
- **GrantFeatureToUser**: فعالسازی فیچر برای کاربر
|
||||
- **RevokeFeatureFromUser**: غیرفعالسازی فیچر از کاربر
|
||||
|
||||
#### Queries
|
||||
- **GetAllClubFeatures**: لیست تمام فیچرها
|
||||
- **GetUserClubFeatures**: لیست فیچرهای فعال یک کاربر
|
||||
|
||||
### ۴.۳ `NetworkBalanceCQ/`
|
||||
#### Commands
|
||||
- **RecordNetworkJoin**: ثبت ورود کاربر به شبکه باینری (تعیین والد و شاخه)
|
||||
- حتماً باید یک رکورد در `NetworkMembershipHistory` ایجاد کند.
|
||||
- **UpdateNetworkPosition**: تغییر موقعیت در شبکه (مدیریتی)
|
||||
- هر تغییر، یک رکورد History.
|
||||
- **CalculateWeeklyBalances**: محاسبه تعادلهای هفتگی (فراخوانی از Worker)
|
||||
|
||||
#### Queries
|
||||
- **GetUserNetworkTree**: دریافت درخت زیرمجموعههای کاربر (چند سطح)
|
||||
- **GetUserWeeklyBalances**: دریافت تعادلهای هفتگی یک کاربر
|
||||
- **GetNetworkStatistics**: آمار کلی شبکه (تعداد اعضا، عمق، تعادل)
|
||||
|
||||
### ۴.۴ `CommissionPoolCQ/`
|
||||
#### Commands
|
||||
- **InitializeWeeklyPool**: ایجاد استخر جدید برای هفته
|
||||
- **AddToWeeklyPool**: افزودن مبلغ به استخر هفتگی (هنگام فعالسازی عضویت)
|
||||
- **CalculatePoolValue**: محاسبه ارزش هر امتیاز
|
||||
- **DistributeCommissions**: توزیع کمیسیونها به کاربران (Worker)
|
||||
- **CloseWeeklyPool**: بستن استخر پس از توزیع
|
||||
|
||||
#### Queries
|
||||
- **GetCurrentWeekPool**: دریافت اطلاعات استخر هفته جاری
|
||||
- **GetPoolHistory**: تاریخچه استخرهای قبلی با فیلتر
|
||||
|
||||
### ۴.۵ `CommissionPayoutCQ/`
|
||||
#### Commands
|
||||
- **CreatePayoutRecord**: ثبت پرداخت کمیسیون (اتوماتیک از Worker)
|
||||
- همراه با ایجاد رکورد در `CommissionPayoutHistory` (Action = Created).
|
||||
- **RequestWithdrawal**: درخواست برداشت کمیسیون (نقدی یا الماس)
|
||||
- History با Action = WithdrawRequested.
|
||||
- **ProcessWithdrawal**: پردازش درخواست برداشت (تایید/رد ادمین)
|
||||
- تغییر Status + History.
|
||||
- **CancelPayout**: لغو پرداخت
|
||||
|
||||
#### Queries
|
||||
- **GetUserCommissionHistory**: تاریخچه کمیسیونهای دریافتی کاربر
|
||||
- **GetPendingWithdrawals**: لیست درخواستهای برداشت در انتظار (برای ادمین)
|
||||
- **GetCommissionSummary**: خلاصه درآمد کمیسیون (مجموع، ماهانه، سالانه)
|
||||
|
||||
### ۴.۶ `ConfigurationCQ/`
|
||||
#### Commands
|
||||
- **SetConfigurationValue**: ثبت/ویرایش یک تنظیم (SystemConfiguration)
|
||||
- هر تغییر باید در `SystemConfigurationHistory` ثبت شود.
|
||||
- **DeactivateConfiguration**: غیرفعالسازی یک تنظیم
|
||||
|
||||
#### Queries
|
||||
- **GetConfigurationValue**: دریافت مقدار یک Key
|
||||
- **GetConfigurationByScope**: لیست تنظیمات یک Scope (مثلاً Network)
|
||||
|
||||
---
|
||||
|
||||
## ۵. Background Worker/Job (محاسبات هفتگی)
|
||||
|
||||
### ۵.۱ `WeeklyNetworkCommissionWorker`
|
||||
**زمانبندی**: هر یکشنبه ساعت ۲۳:۵۹ (یا دوشنبه ۰۰:۰۱)
|
||||
|
||||
**مراحل اجرایی (High-level):**
|
||||
|
||||
#### گام ۱: بستن هفته قبل و ایجاد استخر جدید
|
||||
```csharp
|
||||
var currentWeek = GetCurrentWeekNumber(); // مثلاً "2025-W48"
|
||||
var previousWeek = GetPreviousWeekNumber();
|
||||
|
||||
await CloseWeeklyPool(previousWeek);
|
||||
await InitializeWeeklyPool(currentWeek);
|
||||
```
|
||||
|
||||
#### گام ۲: محاسبه تعادلهای شبکه
|
||||
```csharp
|
||||
var maxBalancesPerUser = GetConfig<int>("MaxWeeklyBalancesPerUser", scope: ConfigurationScope.Network);
|
||||
|
||||
var activeMembers = await GetActiveClubMembers();
|
||||
|
||||
foreach (var member in activeMembers)
|
||||
{
|
||||
var leftBalances = await CalculateLegBalances(member.UserId, NetworkLeg.Left, previousWeek);
|
||||
var rightBalances = await CalculateLegBalances(member.UserId, NetworkLeg.Right, previousWeek);
|
||||
|
||||
var totalBalances = Math.Min(leftBalances, rightBalances);
|
||||
|
||||
// اعمال محدودیت کانفیگ (مثلاً حداکثر 300 تعادل برای هر کاربر)
|
||||
if (totalBalances > maxBalancesPerUser)
|
||||
totalBalances = maxBalancesPerUser;
|
||||
|
||||
await RecordWeeklyBalance(new NetworkWeeklyBalance {
|
||||
UserId = member.UserId,
|
||||
WeekNumber = previousWeek,
|
||||
LeftLegBalances = leftBalances,
|
||||
RightLegBalances = rightBalances,
|
||||
TotalBalances = totalBalances,
|
||||
WeeklyPoolContribution = member.InitialContribution,
|
||||
CalculatedAt = DateTime.UtcNow
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
#### الگوریتم بازگشتی محاسبه تعادل شاخه
|
||||
```csharp
|
||||
private async Task<int> CalculateLegBalances(long userId, NetworkLeg leg, string weekNumber)
|
||||
{
|
||||
var children = await GetNetworkChildren(userId, leg);
|
||||
int totalBalances = 0;
|
||||
|
||||
foreach (var child in children)
|
||||
{
|
||||
var childMembership = await GetClubMembership(child.Id);
|
||||
if (childMembership != null && IsInWeek(childMembership.ActivatedAt, weekNumber))
|
||||
{
|
||||
totalBalances++;
|
||||
}
|
||||
|
||||
var childLeftBalances = await CalculateLegBalances(child.Id, NetworkLeg.Left, weekNumber);
|
||||
var childRightBalances = await CalculateLegBalances(child.Id, NetworkLeg.Right, weekNumber);
|
||||
|
||||
totalBalances += Math.Min(childLeftBalances, childRightBalances);
|
||||
}
|
||||
|
||||
return totalBalances;
|
||||
}
|
||||
```
|
||||
|
||||
#### گام ۳: محاسبه استخر و ارزش امتیاز
|
||||
```csharp
|
||||
var totalPoolAmount = await SumPoolContributions(previousWeek);
|
||||
var totalBalances = await SumTotalBalances(previousWeek);
|
||||
|
||||
var valuePerBalance = totalBalances > 0 ? totalPoolAmount / totalBalances : 0;
|
||||
|
||||
await UpdatePoolValue(previousWeek, totalPoolAmount, totalBalances, valuePerBalance);
|
||||
```
|
||||
|
||||
#### گام ۴: توزیع کمیسیونها
|
||||
```csharp
|
||||
var weeklyBalances = await GetWeeklyBalances(previousWeek);
|
||||
|
||||
foreach (var balance in weeklyBalances.Where(b => b.TotalBalances > 0))
|
||||
{
|
||||
var payoutAmount = balance.TotalBalances * valuePerBalance;
|
||||
|
||||
var payout = new UserCommissionPayout {
|
||||
UserId = balance.UserId,
|
||||
WeekNumber = previousWeek,
|
||||
BalancesEarned = balance.TotalBalances,
|
||||
ValuePerBalance = valuePerBalance,
|
||||
TotalAmount = payoutAmount,
|
||||
Status = CommissionPayoutStatus.Pending
|
||||
};
|
||||
await CreatePayoutRecord(payout); // داخلش CommissionPayoutHistory هم ثبت میشود
|
||||
|
||||
await AddToNetworkBalance(balance.UserId, payoutAmount);
|
||||
|
||||
await RecordWalletChange(new UserWalletChangeLog {
|
||||
WalletId = balance.UserId,
|
||||
// PreviousBalance / AfterBalance پر میشود
|
||||
Amount = payoutAmount,
|
||||
TransactionType = TransactionType.NetworkCommission,
|
||||
ReferenceId = payout.Id.ToString()
|
||||
});
|
||||
|
||||
payout.Status = CommissionPayoutStatus.Paid;
|
||||
payout.PaidAt = DateTime.UtcNow;
|
||||
await UpdatePayout(payout);
|
||||
|
||||
await AddCommissionHistory(payout, "Paid");
|
||||
}
|
||||
```
|
||||
|
||||
#### گام ۵: ریست تعادلها
|
||||
```csharp
|
||||
await ExpireWeeklyBalances(previousWeek);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ۶. لاجیک فروشگاه و سبد خرید
|
||||
|
||||
### ۶.۱ نمایش محصولات
|
||||
```csharp
|
||||
var query = _context.Products.Where(p => !p.IsDeleted);
|
||||
|
||||
if (!user.ClubMembership?.IsActive ?? true)
|
||||
{
|
||||
query = query.Where(p => !p.IsClubExclusive);
|
||||
}
|
||||
|
||||
// اگر کاربر عضو است، قیمت با تخفیف باشگاه محاسبه میشود
|
||||
```
|
||||
|
||||
### ۶.۲ استفاده از کیف پول تخفیف در Checkout
|
||||
(خلاصهسازی شده – در کد اصلی از DiscountBalance استفاده میشود و ChangeLog ثبت میگردد.)
|
||||
|
||||
---
|
||||
|
||||
## ۷. سناریوی کامل فعالسازی عضویت
|
||||
|
||||
### مرحله ۱: شارژ اولیه
|
||||
```text
|
||||
کاربر → پرداخت ۵۶ میلیون (دایا/درگاه)
|
||||
↓
|
||||
UserWallet.Balance += 56,000,000
|
||||
UserWallet.DiscountBalance += 56,000,000
|
||||
```
|
||||
|
||||
### مرحله ۲: فعالسازی عضویت
|
||||
```text
|
||||
کاربر → کلیک روی دکمه «عضویت در باشگاه»
|
||||
↓
|
||||
API: ActivateClubMembership
|
||||
↓
|
||||
1. ایجاد رکورد ClubMembership:
|
||||
- IsActive = true
|
||||
- InitialContribution = 25,000,000
|
||||
|
||||
2. افزودن به استخر هفتگی:
|
||||
- WeeklyCommissionPool.TotalPoolAmount += 25,000,000
|
||||
|
||||
3. تعیین موقعیت در شبکه:
|
||||
- User.NetworkParentId = والد
|
||||
- User.LegPosition = Left یا Right
|
||||
|
||||
4. ثبت ChangeLog برای استخر:
|
||||
- TransactionType = ClubActivation
|
||||
|
||||
5. ثبت ClubMembershipHistory:
|
||||
- Action = "Activated"
|
||||
```
|
||||
|
||||
### مرحله ۳: محاسبه هفتگی (Worker)
|
||||
(مطابق بخش ۵)
|
||||
|
||||
### مرحله ۴: برداشت کمیسیون
|
||||
```text
|
||||
کاربر → درخواست برداشت
|
||||
↓
|
||||
API: RequestWithdrawal (Cash یا Diamond)
|
||||
↓
|
||||
ادمین → تایید درخواست
|
||||
↓
|
||||
1. اگر Cash:
|
||||
- واریز به حساب بانکی
|
||||
- NetworkBalance -= مبلغ
|
||||
|
||||
2. اگر Diamond:
|
||||
- خرید الماس از دایا
|
||||
- NetworkBalance -= مبلغ
|
||||
```
|
||||
|
||||
همراه با ثبت رکورد در `CommissionPayoutHistory` (Action = WithdrawRequested / Withdrawn).
|
||||
|
||||
---
|
||||
|
||||
## ۸. پروتوباف و gRPC Services
|
||||
|
||||
### ۸.۱ `clubmembership.proto`
|
||||
```protobuf
|
||||
syntax = "proto3";
|
||||
import "google/protobuf/timestamp.proto";
|
||||
|
||||
package clubmembership;
|
||||
|
||||
service ClubMembershipService {
|
||||
rpc ActivateMembership (ActivateMembershipRequest) returns (ActivateMembershipResponse);
|
||||
rpc GetClubStatus (GetClubStatusRequest) returns (GetClubStatusResponse);
|
||||
rpc GrantFeature (GrantFeatureRequest) returns (GrantFeatureResponse);
|
||||
rpc GetUserFeatures (GetUserFeaturesRequest) returns (GetUserFeaturesResponse);
|
||||
}
|
||||
|
||||
message ActivateMembershipRequest {
|
||||
int64 user_id = 1;
|
||||
int64 contribution_amount = 2;
|
||||
int64 network_parent_id = 3;
|
||||
NetworkLeg leg_position = 4;
|
||||
}
|
||||
|
||||
message ActivateMembershipResponse {
|
||||
bool success = 1;
|
||||
string message = 2;
|
||||
ClubMembershipDto membership = 3;
|
||||
}
|
||||
|
||||
message GetClubStatusRequest {
|
||||
int64 user_id = 1;
|
||||
}
|
||||
|
||||
message GetClubStatusResponse {
|
||||
bool is_member = 1;
|
||||
ClubMembershipDto membership = 2;
|
||||
}
|
||||
|
||||
message ClubMembershipDto {
|
||||
int64 id = 1;
|
||||
int64 user_id = 2;
|
||||
bool is_active = 3;
|
||||
google.protobuf.Timestamp activated_at = 4;
|
||||
int64 initial_contribution = 5;
|
||||
int64 total_earned = 6;
|
||||
}
|
||||
|
||||
enum NetworkLeg {
|
||||
LEFT = 0;
|
||||
RIGHT = 1;
|
||||
}
|
||||
```
|
||||
|
||||
### ۸.۲ `networkbalance.proto`
|
||||
```protobuf
|
||||
syntax = "proto3";
|
||||
|
||||
package networkbalance;
|
||||
|
||||
service NetworkBalanceService {
|
||||
rpc GetNetworkTree (GetNetworkTreeRequest) returns (GetNetworkTreeResponse);
|
||||
rpc GetWeeklyBalances (GetWeeklyBalancesRequest) returns (GetWeeklyBalancesResponse);
|
||||
rpc GetNetworkStats (GetNetworkStatsRequest) returns (GetNetworkStatsResponse);
|
||||
}
|
||||
|
||||
message GetNetworkTreeRequest {
|
||||
int64 user_id = 1;
|
||||
int32 max_depth = 2;
|
||||
}
|
||||
|
||||
message GetNetworkTreeResponse {
|
||||
NetworkNodeDto root = 1;
|
||||
}
|
||||
|
||||
message NetworkNodeDto {
|
||||
int64 user_id = 1;
|
||||
string full_name = 2;
|
||||
NetworkLeg leg_position = 3;
|
||||
bool is_active = 4;
|
||||
repeated NetworkNodeDto children = 5;
|
||||
}
|
||||
|
||||
message GetWeeklyBalancesRequest {
|
||||
int64 user_id = 1;
|
||||
string week_number = 2;
|
||||
}
|
||||
|
||||
message GetWeeklyBalancesResponse {
|
||||
int32 left_leg_balances = 1;
|
||||
int32 right_leg_balances = 2;
|
||||
int32 total_balances = 3;
|
||||
int64 pool_contribution = 4;
|
||||
}
|
||||
```
|
||||
|
||||
### ۸.۳ `commissionpayout.proto`
|
||||
```protobuf
|
||||
syntax = "proto3";
|
||||
import "google/protobuf/timestamp.proto";
|
||||
|
||||
package commissionpayout;
|
||||
|
||||
service CommissionPayoutService {
|
||||
rpc RequestWithdrawal (RequestWithdrawalRequest) returns (RequestWithdrawalResponse);
|
||||
rpc GetCommissionHistory (GetCommissionHistoryRequest) returns (GetCommissionHistoryResponse);
|
||||
rpc GetPendingWithdrawals (GetPendingWithdrawalsRequest) returns (GetPendingWithdrawalsResponse);
|
||||
rpc ProcessWithdrawal (ProcessWithdrawalRequest) returns (ProcessWithdrawalResponse);
|
||||
}
|
||||
|
||||
message RequestWithdrawalRequest {
|
||||
int64 user_id = 1;
|
||||
int64 amount = 2;
|
||||
WithdrawalMethod method = 3;
|
||||
string iban_number = 4;
|
||||
}
|
||||
|
||||
message RequestWithdrawalResponse {
|
||||
bool success = 1;
|
||||
string message = 2;
|
||||
int64 request_id = 3;
|
||||
}
|
||||
|
||||
message GetCommissionHistoryRequest {
|
||||
int64 user_id = 1;
|
||||
int32 page_number = 2;
|
||||
int32 page_size = 3;
|
||||
}
|
||||
|
||||
message GetCommissionHistoryResponse {
|
||||
repeated CommissionPayoutDto payouts = 1;
|
||||
int32 total_count = 2;
|
||||
}
|
||||
|
||||
message CommissionPayoutDto {
|
||||
int64 id = 1;
|
||||
string week_number = 2;
|
||||
int32 balances_earned = 3;
|
||||
int64 value_per_balance = 4;
|
||||
int64 total_amount = 5;
|
||||
CommissionPayoutStatus status = 6;
|
||||
google.protobuf.Timestamp paid_at = 7;
|
||||
WithdrawalMethod withdrawal_method = 8;
|
||||
}
|
||||
|
||||
enum WithdrawalMethod {
|
||||
CASH = 0;
|
||||
DIAMOND = 1;
|
||||
}
|
||||
|
||||
enum CommissionPayoutStatus {
|
||||
PENDING = 0;
|
||||
PAID = 1;
|
||||
WITHDRAW_REQUESTED = 2;
|
||||
WITHDRAWN = 3;
|
||||
CANCELLED = 4;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ۹. نکات حیاتی و بهترین رویهها
|
||||
|
||||
### ۹.۱ یکپارچگی شبکه باینری
|
||||
- هر کاربر حداکثر دو فرزند (یکی Left، یکی Right)
|
||||
- هنگام اضافه کردن فرزند، کنترل Race Condition
|
||||
- حذف کاربر نباید ساختار شبکه را خراب کند
|
||||
|
||||
### ۹.۲ Transaction Management
|
||||
- Worker باید تمام مراحل را در یک TransactionScope انجام دهد
|
||||
- در صورت شکست، Rollback کامل
|
||||
|
||||
### ۹.۳ Idempotency
|
||||
- محاسبه هفتگی برای یک WeekNumber فقط یکبار
|
||||
- بررسی `WeeklyCommissionPool.IsCalculated` قبل از شروع
|
||||
|
||||
### ۹.۴ Performance
|
||||
- Caching درخت شبکه برای کاربران پرحجم
|
||||
- Index روی `WeekNumber`, `UserId`, `NetworkParentId`
|
||||
|
||||
### ۹.۵ Audit و Compliance
|
||||
- همه تغییرات کیف پول در `UserWalletChangeLog`
|
||||
- همه پرداختهای کمیسیون در `UserCommissionPayout` + `CommissionPayoutHistory`
|
||||
- تغییرات شبکه در `NetworkMembershipHistory`
|
||||
- تغییرات تنظیمات در `SystemConfigurationHistory`
|
||||
|
||||
### ۹.۶ Security
|
||||
- محدودیت تعداد درخواست برداشت
|
||||
- تایید دو مرحلهای برای برداشتهای بالا
|
||||
- Audit Log برای عملیات حساس
|
||||
|
||||
---
|
||||
|
||||
## ۱۰. مراحل پیادهسازی (Roadmap)
|
||||
(مطابق نسخه قبلی – فاز ۱ تا ۶)
|
||||
|
||||
---
|
||||
|
||||
## ۱۱. متریکهای کلیدی (KPIs)
|
||||
- تعداد اعضای فعال باشگاه
|
||||
- مجموع کمیسیونهای پرداختی هر ماه
|
||||
- میانگین تعادل هر کاربر در هفته
|
||||
- نرخ تبدیل به عضویت باشگاه
|
||||
- زمان اجرای Worker، تعداد خطاها، عمق درخت، حجم داده History و …
|
||||
|
||||
---
|
||||
|
||||
## ۱۲. سوالات متداول (FAQ)
|
||||
(همان سوالات قبلی + میتوان سوالات مربوط به سقف تعادل و تنظیمات را اضافه کرد.)
|
||||
|
||||
---
|
||||
|
||||
## ۱۳. ضمیمه: مثال عددی کامل
|
||||
(مثال دو هفتهای A, B, C, D, E, F, G مثل نسخه قبلی.)
|
||||
|
||||
---
|
||||
|
||||
## ۱۴. مسیرهای مرتبط
|
||||
- Domain: `CMS/src/CMSMicroservice.Domain/Entities/`
|
||||
- Application: `CMS/src/CMSMicroservice.Application/ClubMembershipCQ/`, `NetworkBalanceCQ/`, `CommissionPoolCQ/`, `CommissionPayoutCQ/`, `ConfigurationCQ/`
|
||||
- Protobuf: `CMS/src/CMSMicroservice.Protobuf/Protos/`
|
||||
- Worker: `CMS/src/CMSMicroservice.Infrastructure/BackgroundJobs/`
|
||||
- مستند حاضر: `CMS/docs/network-club-commission-system.md`
|
||||
|
||||
**نسخه**: 1.1
|
||||
**تاریخ**: 2025-11-29
|
||||
**نویسنده**: تیم توسعه CMS
|
||||
**وضعیت**: آماده پیادهسازی (با History و Config)
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user