docs: BIZ-PACKAGE-BASED-SYSTEM v3 — per-package commission deep analysis

Major v3 changes:
- Q12-Q18: MaxWeeklyBalancesPerLeg, MaxNetworkLevel, MagicWalletMaxDeposit,
  MagicWalletMaxCredit all become per-package (not global SystemConstants)
- NetworkWeeklyBalance gets PackageId + Unique(UserId,WeekId,PackageId)
- SP changes: @MaxBalancesPerLeg and @MaxNetworkLevel as dynamic params
  (removing hardcoded 300/15)
- SpCommissionCalculationStrategy: pass package settings to SPs
- Carryover per-package: week-shifting only for same PackageId records
- commission.proto: package_id+package_title in 4 message types,
  new CustomerCommissionPackageSummary message, package filter in requests
- FrontOffice: commission dashboard with per-package summary cards
- BackOffice: package filter dropdown in all commission reports + CSV
- Package Create/Edit: Quick Access checkboxes for features inline
- Seed data: silver MaxBalancesPerLeg=30, MagicWalletMax=100M/250M
- Migration: NetworkWeeklyBalances existing records get base PackageId
- Impact Analysis: 39 -> 48+ changes across 6 layers
- Timeline: 14 -> 17 days critical path (+3 days for per-package work)

Updated docs:
- business/BIZ-PACKAGE-BASED-SYSTEM.md (v2 -> v3)
- roadmap/PACKAGE-TRANSFORMATION-TASKS.md (synced with v3)
This commit is contained in:
masoodafar-web
2026-02-24 23:48:09 +03:30
parent 01244f426e
commit 33d5ae9305
2 changed files with 650 additions and 168 deletions
+239 -62
View File
@@ -2,8 +2,10 @@
> **وضعیت:** تایید‌شده — آماده شروع
> **تاریخ:** ۱۴۰۴/۱۲/۰۶
> **پیش‌نیاز:** [BIZ-PACKAGE-BASED-SYSTEM.md](../business/BIZ-PACKAGE-BASED-SYSTEM.md) v2
> **هدف:** شکستن ۳۹ تغییر به تسک‌های اتمیک با ترتیب اجرا و وابستگی‌ها
> **پیش‌نیاز:** [BIZ-PACKAGE-BASED-SYSTEM.md](../business/BIZ-PACKAGE-BASED-SYSTEM.md) **v3** (تکمیل پورسانت per-package)
> **هدف:** شکستن **۴۸+ تغییر** به تسک‌های اتمیک با ترتیب اجرا و وابستگی‌ها
> ⚠️ **تغییرات v3:** پورسانت per-package، carryover مجزا، SP parameters داینامیک، گزارش‌دهی FO/BO per-package
---
@@ -11,14 +13,13 @@
```
مرحله ۰: فیکس باگ فوری (۱ روز)
└─→ مرحله ۱: زیرساخت Domain + DB (۳ روز)
└─→ مرحله ۱: زیرساخت Domain + DB (۴ روز) ← +۱ روز (v3: NetworkWeeklyBalance)
├─→ مرحله ۲: منطق کسب‌وکار (۴ روز) ← موازی
│ └─→ مرحله ۴: FrontOffice UI (۳ روز)
└─→ مرحله ۳: پورسانت (۳ روز) ← موازی
└─→ مرحله ۵: BackOffice UI (۳ روز)
└─→ مرحله ۶: تست + استقرار (۲ روز)
│ └─→ مرحله ۴: UI (۵ روز) ← +۲ (v3: FO/BO گزارش per-package)
└─→ مرحله ۳: پورسانت (۴ روز) ← +۱ (v3: SP params + carryover)
└─→ مرحله ۵: تست + استقرار (۳ روز) ← +۱
مسیر بحرانی: ۰→۱→۲→۴→۶ = ~۱۳ روز
مسیر بحرانی: ۰→۱→۲→۴→۵ = ~۱۷ روز (v2: ۱۳ روز)
```
---
@@ -69,7 +70,7 @@
> ⏱️ ۳ روز | وابستگی: مرحله ۰ | ریسک: متوسط (migration)
### T1.1 — بروزرسانی Package Entity
### T1.1 — بروزرسانی Package Entity (۱۱ فیلد جدید — v3)
**فایل:** `CMS/src/CMSMicroservice.Domain/Entities/Package.cs`
@@ -82,6 +83,13 @@
+ public long ActivationFee { get; set; }
+ public decimal DiscountMultiplier { get; set; } = 2.0m;
+ public decimal MagicWalletMultiplier { get; set; } = 2.5m;
+ // === v3: تنظیمات پورسانت per-package ===
+ public int MaxBalancesPerLeg { get; set; } = 300; // نقره‌ای=۳۰
+ public int MaxNetworkLevel { get; set; } = 15;
+ // === v3: سقف کیف‌پول جادویی per-package ===
+ public long MagicWalletMaxDeposit { get; set; } = 1_000_000_000;
+ public long MagicWalletMaxCredit { get; set; } = 2_500_000_000;
+
+ public virtual ICollection<PackageFeature> PackageFeatures { get; set; }
```
@@ -106,14 +114,15 @@ public class PackageFeature : BaseAuditableEntity
### T1.3-T1.6 — اضافه PackageId به entityها
| Entity | فیلد | Required? | توضیح |
|--------|------|-----------|-------|
| ClubMembership | `long? PackageId` | nullable (بعد migration → required) | آخرین پکیج |
| ClubMembershipCycle | `long PackageId` | required | پکیج این چرخه |
| WeeklyCommissionPool | `long PackageId` | required + Unique(WeekDefId, PkgId) | Pool هر پکیج |
| UserCommissionPayout | `long? PackageId` | nullable | ردیابی |
| Entity | فیلد | Required? | توضیح | v3? |
|--------|------|-----------|-------|-----|
| ClubMembership | `long? PackageId` | nullable (بعد migration → required) | آخرین پکیج | |
| ClubMembershipCycle | `long PackageId` | required | پکیج این چرخه | |
| WeeklyCommissionPool | `long PackageId` | required + Unique(WeekDefId, PkgId) | Pool هر پکیج | |
| UserCommissionPayout | `long? PackageId` | nullable + **Unique(UserId, WeekId, PkgId)** | ردیابی | 🔄 |
| **NetworkWeeklyBalance** | **`long PackageId`** | **required + Unique(UserId, WeekId, PkgId)** | **تعادل per-package** | **🆕** |
### T1.7 — حذف SystemConstants
### T1.7 — حذف SystemConstants (v3: ۷ ثابت)
**فایل:** `CMS/src/CMSMicroservice.Domain/Common/SystemConstants.cs`
@@ -122,10 +131,14 @@ public class PackageFeature : BaseAuditableEntity
- public const long DayaLoanAmount = 56_000_000;
- public const long ClubActivationFee = 25_200_000;
- public const long ClubMembershipGiftValue = 25_200_000;
- public const decimal MagicWalletMultiplier = 2.5m; // اگر وجود داشت
- public const decimal MagicWalletMultiplier = 2.5m;
- // === v3: انتقال به Package entity ===
- public const int CommissionMaxWeeklyBalancesPerLeg = 300;
- public const int CommissionMaxNetworkLevel = 15;
```
> ⚠️ **قبل از حذف:** grep تمام مصرف‌کننده‌ها → جایگزین با `Package.Property`
> ⚠️ **قبل از حذف:** grep تمام مصرف‌کننده‌ها → جایگزین با `Package.Property`
> ⚠️ **v3:** `CommissionMaxWeeklyBalancesPerLeg` و `CommissionMaxNetworkLevel` هم باید per-package شوند
### T1.8 — Database Migration
@@ -151,7 +164,12 @@ UPDATE "CMS"."Packages" SET
"SupportsDirectPurchase" = true,
"ActivationFee" = 25200000,
"DiscountMultiplier" = 2.0,
"MagicWalletMultiplier" = 2.5
"MagicWalletMultiplier" = 2.5,
-- v3: تنظیمات پورسانت
"MaxBalancesPerLeg" = 300,
"MaxNetworkLevel" = 15,
"MagicWalletMaxDeposit" = 1000000000,
"MagicWalletMaxCredit" = 2500000000
WHERE "Id" = 4;
-- 2. Link existing data to base package
@@ -159,18 +177,50 @@ UPDATE "CMS"."ClubMemberships" SET "PackageId" = 4 WHERE "PackageId" IS NULL;
UPDATE "CMS"."ClubMembershipCycles" SET "PackageId" = 4 WHERE "PackageId" IS NULL;
UPDATE "CMS"."WeeklyCommissionPools" SET "PackageId" = 4 WHERE "PackageId" IS NULL;
UPDATE "CMS"."UserCommissionPayouts" SET "PackageId" = 4 WHERE "PackageId" IS NULL;
-- v3: NetworkWeeklyBalance هم PackageId می‌گیره
UPDATE "CMS"."NetworkWeeklyBalances" SET "PackageId" = 4 WHERE "PackageId" IS NULL;
-- 3. Seed Silver package
INSERT INTO "CMS"."Packages" (...) VALUES ('پکیج نقره‌ای', 5600000, ...);
-- 3. Seed Silver package (شامل فیلدهای v3)
INSERT INTO "CMS"."Packages" (..., "MaxBalancesPerLeg", "MaxNetworkLevel",
"MagicWalletMaxDeposit", "MagicWalletMaxCredit", ...)
VALUES ('پکیج نقره‌ای', 5600000, ..., 30, 15, 100000000, 250000000, ...);
```
### T1.10 — بروزرسانی Protoها
| Proto File | تغییر |
|-----------|-------|
| package.proto | فیلدهای جدید Package message |
| clubmembership.proto | package_id در request/response |
| commission.proto | package_id در pool/payout messages |
| Proto File | تغیر | v3? |
|-----------|-------|-----|
| package.proto | فیلدهای جدید Package message (۱۱ فیلد) | 🔄 |
| clubmembership.proto | package_id در request/response | |
| commission.proto | **`package_id` + `package_title`** در ۴ message | **🆕** |
| commission.proto | **Message جدید: `CustomerCommissionPackageSummary`** | **🆕** |
| commission.proto | **فیلتر `package_id` در Requestها** | **🆕** |
### T1.11 — اضافه PackageId به NetworkWeeklyBalance (🆕 v3)
**فایل:** `CMS/src/CMSMicroservice.Domain/Entities/NetworkWeeklyBalance.cs`
```diff
+ public long PackageId { get; set; }
+ public virtual Package Package { get; set; }
```
**EF Config:** اضافه Unique Index:
```csharp
builder.HasIndex(e => new { e.UserId, e.WeekDefinitionId, e.PackageId }).IsUnique();
builder.HasOne(e => e.Package).WithMany().HasForeignKey(e => e.PackageId);
```
> ⚠️ **تاثیر حجم:** رکوردهای تعادل ×N (تعداد پکیج). مثلاً ۱۰۰۰ کاربر × ۲ پکیج = ۲۰۰۰ رکورد هفتگی
### T1.12 — Data Migration: NetworkWeeklyBalance (🆕 v3)
```sql
-- رکوردهای موجود → پکیج پایه
UPDATE "CMS"."NetworkWeeklyBalances"
SET "PackageId" = (SELECT "Id" FROM "CMS"."Packages" WHERE "IsBasePackage" = true LIMIT 1)
WHERE "PackageId" IS NULL;
```
---
@@ -256,29 +306,33 @@ INSERT INTO "CMS"."Packages" (...) VALUES ('پکیج نقره‌ای', 5600000,
## مرحله ۳ — محاسبه پورسانت (موازی با مرحله ۲)
> ⏱️ ۳ روز | وابستگی: مرحله ۱ | ریسک: بحرانی (مالی)
> ⏱️ **۴ روز** (v3: +۱) | وابستگی: مرحله ۱ | ریسک: بحرانی (مالی)
### T3.1-T3.2 — SPs + PackageId
### T3.1-T3.2 — SPs + PackageId + پارامترهای داینامیک (🔄 v3)
```sql
-- sp_CalculateWeeklyBalances:
-- sp_CalculateWeeklyBalances — v3: حذف hardcode
ALTER PROCEDURE sp_CalculateWeeklyBalances
@WeekDefinitionId BIGINT,
@PackageId BIGINT -- ← جدید
@PackageId BIGINT,
@MaxBalancesPerLeg INT, -- v3: از Package entity (نه ۳۰۰ hardcode!)
@MaxNetworkLevel INT -- v3: از Package entity (نه ۱۵ hardcode!)
AS
BEGIN
-- فیلتر بالانس‌ها فقط کاربرانی که این پکیج را دارند
INSERT INTO "CMS"."WeeklyBalances" (...)
SELECT ...
-- فیلتر: فقط کاربرانی که این پکیج را دارند
-- carryover: فقط رکوردهای PackageId = @PackageId
-- cap: از @MaxBalancesPerLeg (نه ۳۰۰)
-- depth: CTE تا @MaxNetworkLevel (نه ۱۵)
INSERT INTO "CMS"."NetworkWeeklyBalances" ("PackageId", ...)
SELECT @PackageId, ...
FROM "CMS"."UserWallets" w
INNER JOIN "CMS"."ClubMemberships" m ON m."UserId" = w."UserId"
WHERE m."PackageId" = @PackageId -- ← فیلتر
AND m."IsActive" = true
AND w."WalletMode" = 0; -- Normal only
WHERE m."PackageId" = @PackageId
AND m."IsActive" = true;
END;
```
### T3.3 — Loop Service
### T3.3 — Loop Service (🔄 v3: ارسال تنظیمات پکیج)
```csharp
// WeeklyCommissionCalculationService.cs
@@ -288,14 +342,71 @@ var activePackages = await _context.Packages
foreach (var package in activePackages)
{
_logger.LogInformation("Calculating commission for package {Id}: {Title}",
package.Id, package.Title);
_logger.LogInformation(
"Calculating commission for package {Id}: {Title} " +
"(MaxBalances={Max}, MaxLevel={Level})",
package.Id, package.Title,
package.MaxBalancesPerLeg, package.MaxNetworkLevel);
// v3: پاس دادن تنظیمات پکیج
await strategy.CalculateWeeklyBalancesAsync(
weekId, package.Id,
package.MaxBalancesPerLeg, package.MaxNetworkLevel);
await strategy.CalculateWeeklyBalancesAsync(weekId, package.Id);
await strategy.CalculateWeeklyPoolAsync(weekId, package.Id);
}
```
### T3.4 — OrmCommissionCalculationStrategy (🔄 v3)
**تغییرات:**
```diff
- var maxBalances = SystemConstants.CommissionMaxWeeklyBalancesPerLeg; // 300
- var maxLevel = SystemConstants.CommissionMaxNetworkLevel; // 15
+ // پارامتر از بیرون — per-package
+ int maxBalances = maxBalancesPerLeg; // e.g., نقره‌ای=30, پایه=300
+ int maxLevel = maxNetworkLevel;
- // فیلتر کاربران
+ // فیلتر کاربران بر اساس پکیج
+ .Where(m => m.PackageId == packageId && m.IsActive)
- // carryover
+ // carryover: فقط رکوردهای همان PackageId
+ .Where(b => b.PackageId == packageId && b.WeekDefinitionId == prevWeekId)
```
### T3.5 — SpCommissionCalculationStrategy (🆕 v3)
```csharp
// قبل: فقط WeekDefinitionId
await connection.ExecuteAsync("CMS.sp_CalculateWeeklyBalances",
new { WeekDefinitionId = weekId, ForceRecalculate = true });
// بعد (v3): پکیج + تنظیمات داینامیک
await connection.ExecuteAsync("CMS.sp_CalculateWeeklyBalances",
new {
WeekDefinitionId = weekId,
PackageId = package.Id,
MaxBalancesPerLeg = package.MaxBalancesPerLeg,
MaxNetworkLevel = package.MaxNetworkLevel,
ForceRecalculate = true
});
```
### T3.6 — Carryover per-package (🆕 v3)
> ⚠️ **بحرانی:** week-shifting باید فقط رکوردهای همان PackageId را shift کند
```
هفته ۱۰ → هفته ۱۱:
علی: carryover_پایه = {Left: surplus, Right: surplus} ← جداگانه
علی: carryover_نقره‌ای = {Left: 0, Right: 0} ← جداگانه
✖ اشتباه: قاطی کردن carryover پایه و نقره‌ای!
✔ صحیح: هر PackageId فقط carryover خودش را می‌بینه
```
### ⚠️ نکته بحرانی
> پورسانت = پول واقعی. **هر تغییر در SPs باید:**
@@ -306,9 +417,9 @@ foreach (var package in activePackages)
---
## مرحله ۴ — FrontOffice UI
## مرحله ۴ — UI (FrontOffice + BackOffice)
> ⏱️ ۳ روز | وابستگی: مرحله ۲ | ریسک: متوسط
> ⏱️ **۵ روز** (v3: +۲) | وابستگی: مرحله ۲ + ۳ | ریسک: متوسط
### T4.1 — کاشی‌های پکیج داینامیک
@@ -355,52 +466,118 @@ else
}
```
---
### T4.8 — FrontOffice: CommissionDashboard per-package (🆕 v3)
## مرحله ۵ — BackOffice UI
**فایل:** `FrontOffice/src/.../Pages/Commission/CommissionDashboardPage.razor`
> ⏱️ ۳ روز | وابستگی: مرحله ۳ | ریسک: کم
```razor
@* v3: کارت‌های خلاصه بر اساس پکیج *@
<MudGrid>
@foreach (var summary in _packageSummaries)
{
<MudItem xs="12" md="6">
<MudCard>
<MudCardHeader>@summary.PackageTitle</MudCardHeader>
<MudCardContent>
<p>زیرمجموعه: @summary.DownlineCount نفر</p>
<p>تیم اول: @summary.LeftLegMembers | تیم دوم: @summary.RightLegMembers</p>
<p>تعادل: @summary.TotalBalances</p>
<p>💰 پاداش: @summary.CommissionFormatted</p>
</MudCardContent>
</MudCard>
</MudItem>
}
</MudGrid>
<MudAlert>📦 مجموع پاداش هفته: @_totalCommission</MudAlert>
```
_(تسک‌ها در PACKAGE-TRANSFORMATION-UX.md بخش ۳ مستند شده)_
### T4.9 — FrontOffice: WeeklyBalance per-package (🆕 v3)
> تعادل تیم اول/دوم به تفکیک هر پکیج نمایش داده شود
### T4.10-T4.12 — BackOffice: گزارش‌های پورسانت per-package (🆕 v3)
**تغییرات مشترک:**
- اضافه dropdown فیلتر پکیج (همه / پایه / نقره‌ای / ...)
- اضافه ستون پکیج در جدول‌ها
- CSV export شامل ستون پکیج
| صفحه | تغییر |
|------|-------|
| Commission Dashboard | فیلتر + خلاصه per-package |
| Weekly Reports | فیلتر + CSV per-package |
| Balances Report | فیلتر + ستون پکیج |
| User Payouts | ستون پکیج + فیلتر |
### T4.13 — BackOffice: Package CRUD + Quick Access فیچرها (🆕 v3)
> ادمین موقع ساخت/ویرایش پکیج، فیچرها را با checkbox در همان فرم تعیین کند
```razor
@* در PackageCreateDialog / PackageEditDialog: *@
<MudText Typo="Typo.h6">فیچرهای پکیج</MudText>
@foreach (var feature in _allFeatures)
{
<MudCheckBox @bind-Checked="feature.IsIncluded" Label="@feature.Title" />
}
```
---
## مرحله ۶ — تست و استقرار
## مرحله ۵ — تست و استقرار
> ⏱️ ۲ روز | وابستگی: مرحله ۴ و ۵
> ⏱️ **۳ روز** (v3: +۱) | وابستگی: مرحله ۴
### Checklist تست
**خرید + فعال‌سازی:**
- [ ] خرید پکیج نقره‌ای (ZarinPal)
- [ ] خرید پکیج پایه (ZarinPal)
- [ ] خرید پکیج پایه (Daya Loan)
- [ ] خرید پکیج پایه (Manual Payment)
- [ ] فعالسازی باشگاه با پکیج نقره‌ای → فیچرهای محدود
- [ ] فعالسازی باشگاه با پکیج پایه → همه فیچرها
**چرخه Magic + خرید مجدد:**
- [ ] تکمیل چرخه Magic → ریست وضعیت
- [ ] خرید مجدد بعد تکمیل چرخه
- [ ] خرید مجدد بعد تکمیل چرخه (همان پکیج)
- [ ] خرید مجدد با پکیج متفاوت (پایه → نقره‌ای)
**پورسانت per-package (v3):**
- [ ] Commission Pool جداگانه هر پکیج
- [ ] Data Migration — PackageId در رکوردهای قبلی
- [ ] تعادل per-package: MaxBalancesPerLeg متفاوت (پایه=۳۰۰, نقره‌ای=۳۰)
- [ ] Carryover مجزا: shift فقط رکوردهای همان PackageId
- [ ] SP پارامترها صحیح: @MaxBalancesPerLeg و @MaxNetworkLevel از Package
- [ ] NetworkWeeklyBalance رکوردها: ۲ پکیج = ۲× رکورد
**گزارش per-package (v3):**
- [ ] FO: مشتری کارت‌های خلاصه per-package را می‌بیند
- [ ] FO: مجموع پاداش = جمع همه پکیج‌ها
- [ ] BO: فیلتر dropdown پکیج کار می‌کند
- [ ] BO: CSV export شامل ستون پکیج
**Migration + سایر:**
- [ ] Data Migration — PackageId در رکوردهای قبلی (شامل NetworkWeeklyBalance)
- [ ] JWT claims جدید (CanRepurchase, PackageId)
- [ ] UI: کاشی‌های داینامیک FrontOffice
- [ ] UI: ماتریس فیچر BackOffice
- [ ] UI: ماتریس فیچر + Quick Access BackOffice
- [ ] Rollback: بدون data loss
---
## 📅 تقویم پیشنهادی
## 📅 تقویم پیشنهادی (v3)
| هفته | روز | تسک |
|------|-----|------|
| هفته ۱ | روز ۱ | مرحله ۰: فیکس ۴ باگ |
| | روز ۲-۳ | مرحله ۱: Package entity + PackageFeature |
| | روز ۴ | مرحله ۱: FKها + Migration |
| هفته ۲ | روز ۵-۶ | مرحله ۲: Generic handlers + re-purchase |
| | روز ۵-۶ | مرحله ۳: SP + Loop (موازی) |
| | روز ۷-۸ | مرحله ۲: Guards + JWT + Manual |
| هفته ۳ | روز ۹-۱۰ | مرحله ۴: FrontOffice UI |
| | روز ۱۱ | مرحله ۵: BackOffice UI |
| | روز ۱۲-۱۳ | مرحله ۶: تست + deploy |
| | روز ۲-۳ | مرحله ۱: Package entity (۱۱ فیلد) + PackageFeature |
| | روز ۴-۵ | مرحله ۱: FKها + NetworkWeeklyBalance + Migration |
| هفته ۲ | روز ۶-۷ | مرحله ۲: Generic handlers + re-purchase |
| | روز ۶ | مرحله ۳: SP params + carryover per-package (موازی) |
| | روز ۸-۱۰ | مرحله ۲: Guards + JWT + Manual |
| هفته ۳ | روز ۱۱-۱۲ | مرحله ۴: FrontOffice UI + گزارش per-package |
| | روز ۱۳-۱۴ | مرحله ۴: BackOffice UI + گزارش per-package |
| | روز ۱۵-۱۷ | مرحله ۵: تست + deploy |
---
@@ -408,11 +585,11 @@ _(تسک‌ها در PACKAGE-TRANSFORMATION-UX.md بخش ۳ مستند شده)_
| مستند | محتوا |
|-------|-------|
| [BIZ-PACKAGE-BASED-SYSTEM.md](../business/BIZ-PACKAGE-BASED-SYSTEM.md) | طراحی فنی — ۳۹ تغییر + باگ‌ها |
| [BIZ-PACKAGE-BASED-SYSTEM.md](../business/BIZ-PACKAGE-BASED-SYSTEM.md) | طراحی فنی — **۴۸+ تغییر** (v3) + باگ‌ها |
| [PACKAGE-TRANSFORMATION-UX.md](PACKAGE-TRANSFORMATION-UX.md) | تاثیر UX بر فرانت‌ها |
| [FEATURE-BACKLOG.md](FEATURE-BACKLOG.md) | بکلاگ ۱۲ RPC آماده |
| [GRPC-SERVICES-AUDIT.md](../cms/GRPC-SERVICES-AUDIT.md) | آدیت ۳۴۲ RPC |
---
*آخرین بروزرسانی: ۱۴۰۴/۱۲/۰۶*
*آخرین بروزرسانی: ۱۴۰۴/۱۲/۰۶ — v3 (پورسانت per-package + گزارش‌دهی + carryover)*