docs/business/BIZ-PACKAGE-BASED-SYSTEM.md

📦 سیستم مبتنی بر پکیج (Package-Based System)

وضعیت: تایید‌شده — آماده پیاده‌سازی
تاریخ بروزرسانی: ۶ اسفند ۱۴۰۴
نسخه: v3 (تکمیل تحلیل پورسانت per-package + گزارش‌دهی + SystemConstants کامل)
تاثیرگذاری: زیاد — ۵۵+ فایل در ۶ لایه

---

۱. خلاصه فیچر

وضعیت فعلی: سیستم فقط یک پکیج پایه (۵۶ میلیون تومان) دارد و همه چیز حول آن hardcode شده.

وضعیت هدف: سیستم چندین پکیج با قیمت‌ها و ویژگی‌های متفاوت پشتیبانی می‌کند. هر پکیج مقادیر مالی، فیچرها و Commission Pool مستقل خود را دارد. کاربر می‌تواند N بار پکیج بخرد (بعد از تکمیل چرخه Magic Wallet).

---

۲. تصمیمات تایید‌شده

#	سوال	تصمیم
Q1	باگ DiscountBalance در VerifyGoldenPackagePurchase	✅ باگه — باید فیکس بشه
Q2	سه مسیر پرداخت موازی	✅ ادغام به سرویس Generic — نه به نام پکیج خاص
Q3	پکیج‌های اولیه	✅ نقره‌ای (۵.۶M) + پایه (۵۶M) — سیستم داینامیک
Q4	ActivationFee و GiftValue	✅ یک فیلد (ActivationFee) — GiftValue حذف (تکراری بود)
Q5	DiscountMultiplier	✅ ×2 برای همه — ولی داینامیک در entity
Q6	Migration کاربران فعلی	✅ Pipeline/Script — کاربران فعلی → PackageId = پکیج پایه
Q7	خرید چند پکیج	✅ N بار — بعد تکمیل Magic Wallet و صفر شدن Balance
Q8	Commission Pool	✅ جدا برای هر پکیج — تمام جداول Commission با PackageId
Q9	MagicWallet Multiplier	✅ داینامیک به‌ازای هر پکیج (فعلاً همه ×2.5)
Q10	کاربران دایا	✅ پکیج پایه گرفتن — "طلایی" اشتباه نام‌گذاری بوده
Q11	فیچرها	✅ داینامیک — ادمین مدیریت می‌کند
Q12	MaxWeeklyBalancesPerLeg (300)	✅ per-package — پکیج نقره‌ای ۳۰، پکیج پایه ۳۰۰
Q13	MaxNetworkLevel (15)	✅ per-package — ادمین تنظیم کند
Q14	MagicWalletMaxDeposit (1B)	✅ per-package — سقف شارژ بر اساس پکیج
Q15	MagicWalletMaxCredit (2.5B)	✅ per-package — سقف اعتبار بر اساس پکیج
Q16	NetworkWeeklyBalance + PackageId	✅ هر رکورد تعادل = per-package — carryover هم جداگانه
Q17	گزارش پورسانت FO	✅ breakdown per-package — مشتری ببیند از هر پکیج چقدر
Q18	گزارش پورسانت BO	✅ فیلتر بر اساس پکیج — ادمین بر اساس پکیج فیلتر کند

---

۳. تحلیل عمیق وضعیت فعلی (AS-IS)

۳.۱ باگ‌های کشف‌شده

#	باگ	شدت	فایل
B1	VerifyGoldenPackagePurchase → DiscountBalance شارژ نمی‌شود	🔴 بحرانی	VerifyGoldenPackagePurchaseCommandHandler.cs
B2	VerifyGoldenPackagePurchase → UserPackagePurchase ساخته نمی‌شود	🔴 بحرانی	VerifyGoldenPackagePurchaseCommandHandler.cs
B3	VerifyPackagePurchase → UserPackagePurchase ساخته نمی‌شود	🔴 بحرانی	VerifyPackagePurchaseCommandHandler.cs
B4	VerifyBasePackagePayment → UserPackagePurchase ساخته نمی‌شود	🔴 بحرانی	VerifyBasePackagePaymentCommandHandler.cs
B5	PackageService.CustomerPurchasePackage → guard برای خرید تکراری ندارد	🟡 متوسط	PackageService.cs
B6	EXIT Magic Mode → PackagePurchaseMethod ریست نمی‌شود (خرید مجدد مسدود)	🔴 بحرانی	UserOrderService.cs

۳.۲ ناسازگاری مسیرهای پرداخت

مسیر	Balance	Discount	UserPackagePurchase	WalletChangeLog
BFF/PYMS (InitiateBase→VerifyBase)	✅	✅	❌	✅
ZarinPal Golden (PurchaseGolden→VerifyGolden)	✅	❌	❌	✅ (فقط Balance)
ZarinPal Generic (Purchase→VerifyPurchase)	✅	✅	❌	✅
Daya Loan (CheckAndProcess)	✅	✅	✅	✅
Manual (CreateManualPayment)	✅	✅	❌	✅

فقط Daya Loan همه مراحل را کامل انجام می‌دهد. بقیه مسیرها ناقص هستند.

۳.۳ مقادیر Hardcoded (۱۵ مورد)

#	مکان	مقدار	باید بشه
H1	InitiateBasePackagePaymentCommandHandler	BasePackageId = 4	خوانش از پکیج فعال
H2	CheckAndProcessDayaLoansCommandHandler	p.Id == 4	خوانش از پکیج پایه
H3	SystemConstants.BasePackageAmount	56_000_000	Package.Price
H4	SystemConstants.DayaLoanAmount	56_000_000	Package.Price
H5	SystemConstants.ClubActivationFee	25_200_000	Package.ActivationFee
H6	SystemConstants.ClubMembershipGiftValue	25_200_000	حذف (= ActivationFee)
H7	VerifyPackagePurchaseCommandHandler	Amount * 2 (×3 جا)	Package.DiscountMultiplier
H8	VerifyBasePackagePaymentCommandHandler	BasePackageAmount * 2 (×2)	Package.DiscountMultiplier
H9	CreateManualPaymentCommandHandler	BasePackageAmount * 2	Package.DiscountMultiplier
H10	CheckAndProcessDayaLoansCommandHandler	DayaLoanAmount * 2	Package.DiscountMultiplier
H11	ActivateClubMembershipCommandHandler	PackageAmount = BasePackageAmount	Package.Price
H12	PurchaseGoldenPackageCommandHandler	Title.Contains("طلایی")	حذف — Generic
H13	ActivateClubMembershipCommandHandler	GetAllFeatureIds()	Package.PackageFeatures
H14	ActivationSection.razor	56_000_000 × months	از پکیج خوانده شود
H15	ClubMembershipContractDialog.razor	متن قرارداد ۵۶M	داینامیک از پکیج

۳.۴ Guardهای مسدودکننده خرید مجدد

#	فایل	Guard	وضعیت	تغییر
G1	PurchaseGoldenPackageCommandHandler	PackagePurchaseMethod != None → throw	مسدود	✅ اجازه بعد تکمیل چرخه
G2	InitiateBasePackagePaymentCommandHandler	PackagePurchaseMethod != None → fail	مسدود	✅ اجازه بعد تکمیل چرخه
G3	PurchasePackageCommandHandler	PackagePurchaseMethod != None → throw	مسدود	✅ اجازه بعد تکمیل چرخه
G4	CheckAndProcessDayaLoansCommandHandler	hasPreviousCycle → skip	عمدی ✅	❌ حفظ (دایا فقط دور اول)
G5	AcceptClubMembershipContractCommandHandler	IsActive == true → fail	مسدود	✅ اجازه re-contract
G6	ActivateClubMembershipCommandHandler	IsActive == true → return true	short-circuit	✅ باید چرخه جدید بسازه
G7	JWT Claim HasPurchasedPackage	permanent true	UI مسدود	✅ اضافه CanRepurchase

۳.۵ Root Cause — خرید مجدد کار نمی‌کند

EXIT Magic Mode (UserOrderService.cs):
    ✅ wallet.WalletMode = Normal
    ✅ wallet.MagicCompletedAt = now
    ✅ cycle.MagicCompletedAt = now
    
    ❌ MISSING: user.PackagePurchaseMethod = None    ← Guards G1-G3 مسدود می‌مانند
    ❌ MISSING: membership.IsActive = false          ← Guards G5-G6 مسدود می‌مانند
    ❌ MISSING: JWT CanRepurchase = true              ← UI دکمه خرید نشان نمی‌دهد

راه‌حل: در EXIT Magic Mode، وضعیت کاربر ریست شود تا بتواند پکیج جدید بخرد.

---

۴. طراحی نهایی (TO-BE)

۴.۱ تغییرات Entity — Package

public class Package : BaseAuditableEntity
{
    // === فیلدهای فعلی (حفظ) ===
    public string Title { get; set; }
    public string Description { get; set; }
    public string ImagePath { get; set; }
    public long Price { get; set; }                          // قیمت پکیج (ریال)
    
    // === فیلدهای جدید ===
    public int SortOrder { get; set; }                       // ترتیب نمایش
    public bool IsActive { get; set; } = true;               // فعال/غیرفعال
    public bool IsBasePackage { get; set; }                   // پکیج پایه؟ (فقط یکی true)
    public bool SupportsDayaPurchase { get; set; }            // پشتیبانی از خرید دایا
    public bool SupportsDirectPurchase { get; set; } = true;  // پشتیبانی از پرداخت مستقیم
    
    // === محاسبات مالی ===
    public long ActivationFee { get; set; }                  // سهم Commission Pool
    public decimal DiscountMultiplier { get; set; } = 2.0m;  // ضریب شارژ DiscountBalance
    public decimal MagicWalletMultiplier { get; set; } = 2.5m; // ضریب کیف‌پول جادویی
    
    // === تنظیمات پورسانت (v3 — انتقال از SystemConstants) ===
    public int MaxBalancesPerLeg { get; set; } = 300;        // سقف تعادل هر پا (نقره‌ای=۳۰)
    public int MaxNetworkLevel { get; set; } = 15;           // عمق شبکه برای محاسبه
    
    // === تنظیمات کیف‌پول جادویی (v3) ===
    public long MagicWalletMaxDeposit { get; set; } = 1_000_000_000;   // سقف شارژ
    public long MagicWalletMaxCredit { get; set; } = 2_500_000_000;    // سقف اعتبار
    
    // === Navigation ===
    public virtual ICollection<PackageFeature> PackageFeatures { get; set; }
    public virtual ICollection<UserPackagePurchase> Purchases { get; set; }
    public virtual ICollection<UserOrder> UserOrders { get; set; }
}

نسبت به v1:

• ❌ GiftValue حذف (= ActivationFee — تکراری)
• ✅ MagicWalletMultiplier اضافه (داینامیک)
• ❌ PackageType enum نیاز نیست (IsBasePackage کافیست)

۴.۲ Entity جدید — PackageFeature

public class PackageFeature : BaseAuditableEntity
{
    public long PackageId { get; set; }
    public virtual Package Package { get; set; }
    
    public long ClubFeatureId { get; set; }
    public virtual ClubFeature ClubFeature { get; set; }
    
    public bool IsIncluded { get; set; } = true;
}

۴.۳ تغییرات Entity — سایر

Entity	فیلد جدید	توضیح
ClubMembership	long? PackageId + FK	آخرین پکیج خریداری‌شده
ClubMembershipCycle	long PackageId + FK	پکیج این چرخه
WeeklyCommissionPool	long PackageId + FK	Pool جداگانه هر پکیج
UserCommissionPayout	long PackageId + FK	از کدام Pool
NetworkWeeklyBalance	long PackageId + FK ← v3	هر رکورد تعادل = per-package

Constraintهای جدید:

• WeeklyCommissionPool → Unique(WeekDefinitionId, PackageId)
• NetworkWeeklyBalance → Unique(UserId, WeekDefinitionId, PackageId) ← v3
• UserCommissionPayout → Unique(UserId, WeekDefinitionId, PackageId) ← v3

⚠️ تاثیر حجم داده: رکوردهای NetworkWeeklyBalance ضربدر تعداد پکیج‌های فعال می‌شوند. مثلاً ۱۰۰۰ کاربر × ۲ پکیج = ۲۰۰۰ رکورد تعادل هفتگی (بجای ۱۰۰۰).

۴.۴ حذف/تغییر SystemConstants

ثابت	تغییر	جایگزین
ClubMembershipGiftValue	❌ حذف	تکراری بود
ClubActivationFee	❌ حذف	Package.ActivationFee
BasePackageAmount	❌ حذف	Package.Price
DayaLoanAmount	❌ حذف	Package.Price (base)
MagicWalletMultiplier	❌ حذف	Package.MagicWalletMultiplier
CommissionMaxWeeklyBalancesPerLeg	❌ حذف ← تغییر از v2	Package.MaxBalancesPerLeg (نقره‌ای=۳۰، پایه=۳۰۰)
CommissionMaxNetworkLevel	❌ حذف ← تغییر از v2	Package.MaxNetworkLevel (قابل تنظیم ادمین)
MagicWalletMaxDeposit	❌ حذف ← جدید v3	Package.MagicWalletMaxDeposit (سقف شارژ)
MagicWalletMaxCredit	❌ حذف ← جدید v3	Package.MagicWalletMaxCredit (سقف اعتبار)
ShopVAT	✅ حفظ	عمومی
CommissionCalculationStrategy	✅ حفظ	عمومی (ORM or SP)
AllowDeletingParentsWithChildren	✅ حفظ	عمومی
MaxDirectChildrenPerLeg	✅ حفظ	عمومی
IsCommissionWithdrawalEnabled	✅ حفظ	عمومی
CommissionMinWithdrawalAmount	✅ حفظ	عمومی
IsMaintenanceMode	✅ حفظ	عمومی
IsAuditLogEnabled	✅ حفظ	عمومی
IsVATEnabled	✅ حفظ	عمومی

۴.۵ فرمول مالی

ActivationFee = Price × 0.45

پکیج نقره‌ای (۵,۶۰۰,۰۰۰ ریال):
    ├── Balance          += ۵,۶۰۰,۰۰۰          (Price)
    ├── DiscountBalance  += ۱۱,۲۰۰,۰۰۰         (Price × DiscountMultiplier)
    └── CommissionPool   += ۲,۵۲۰,۰۰۰          (ActivationFee)

پکیج پایه (۵۶,۰۰۰,۰۰۰ ریال):
    ├── Balance          += ۵۶,۰۰۰,۰۰۰         (Price)
    ├── DiscountBalance  += ۱۱۲,۰۰۰,۰۰۰        (Price × DiscountMultiplier)
    └── CommissionPool   += ۲۵,۲۰۰,۰۰۰         (ActivationFee)

---

۵. فلوی خرید مجدد (Re-Purchase)

۵.۱ چرخه حیات کامل

stateDiagram-v2
    [*] --> NoPurchase: کاربر ثبت‌نام کرده
    
    NoPurchase --> PackagePurchased: خرید پکیج\n(هر پکیجی)
    
    PackagePurchased --> ClubActivated: فعالسازی باشگاه\n(OTP + قرارداد)
    
    ClubActivated --> Shopping: خرج Balance\nدر فروشگاه
    
    Shopping --> MagicMode: Balance == 0
    
    MagicMode --> MagicCharging: شارژ + خرج\n(تا سقف 1B)
    
    MagicCharging --> MagicMode: ادامه
    
    MagicMode --> CycleComplete: Balance == 0\nAND Deposit ≥ 1B
    
    CycleComplete --> NoPurchase: ریست وضعیت\nآماده خرید مجدد

۵.۲ ریست وضعیت بعد تکمیل چرخه (EXIT Magic Mode)

// UserOrderService.cs — EXIT Magic Mode — تغییرات لازم:
wallet.WalletMode = WalletMode.Normal;
wallet.MagicCompletedAt = DateTime.UtcNow;
cycle.MagicCompletedAt = DateTime.UtcNow;

// ✅ اضافه شود:
user.PackagePurchaseMethod = PackagePurchaseMethod.None;   // اجازه خرید مجدد
membership.IsActive = false;                                // اجازه re-contract
cycle.IsCurrentCycle = false;                               // آماده چرخه جدید

۵.۳ نکات مهم

1. دایا فقط دور اول — بعد از دور اول، فقط IPG مجاز
2. هر خرید = Commission contribution — ActivationFee به Pool آن پکیج
3. PackagePurchaseMethod ریست بعد تکمیل چرخه
4. فیچرها بر اساس پکیج جدید — ممکنه متفاوت باشه

---

۶. Commission Pool — تغییرات

۶.۱ ساختار جدید

هفته ۱:
    Pool_نقره‌ای (PackageId=X): TotalAmount = Σ ActivationFee نقره‌ای
    Pool_پایه   (PackageId=Y): TotalAmount = Σ ActivationFee پایه
    
هر Pool مستقل:
    ValuePerBalance = TotalPoolAmount ÷ TotalBalances
    (فقط کاربران همان پکیج)

۶.۲ ساختار شبکه یکی‌ست

                [Ali - پایه]
               /             \
        [Sara - نقره‌ای]    [Reza - پایه]
        
Commission:
  Ali → پاداش از Pool_پایه
  Sara → پاداش از Pool_نقره‌ای  
  Reza → پاداش از Pool_پایه

۶.۳ فلوی کامل چرخه خرید مجدد و تاثیر بر پورسانت (v3)

چرخه ۱ — کاربر "علی" پکیج پایه می‌خرد (۵۶M):
────────────────────────────────────────────────
    ✅ Balance += 56M
    ✅ DiscountBalance += 112M (×2)
    ✅ ActivationFee → Pool_پایه هفته جاری
    ✅ فیچرهای پکیج پایه فعال
    ✅ NetworkWeeklyBalance ساخته می‌شود (PackageId=پایه)
    ✅ بالاسری‌ها: تعادل‌ها بر اساس MaxBalancesPerLeg=300 + MaxNetworkLevel=15
    ✅ پورسانت بالاسری‌ها از Pool_پایه

    ... خرید از فروشگاه → Balance صفر شد → Magic Mode فعال ...
    ... خرید جادویی → MagicBalance صفر + Deposit ≥ MaxDeposit → EXIT Magic ...

چرخه ۲ — کاربر "علی" دوباره پکیج پایه می‌خرد:
──────────────────────────────────────────────
    ✅ ریست وضعیت: PackagePurchaseMethod=None, membership.IsActive=false
    ✅ Balance += 56M (مجدد شارژ)
    ✅ DiscountBalance += 112M (مجدد شارژ)
    ✅ ActivationFee → Pool_پایه هفته جاری
    ✅ فیچرهای پکیج پایه فعال (مجدد)
    ✅ NetworkWeeklyBalance جدید (PackageId=پایه, WeekId=هفته جاری)
    ✅ carryover از هفته قبل: فقط carryover پکیج پایه (نه نقره‌ای!)
    ✅ بالاسری‌ها: محاسبه مجدد از Pool_پایه
    
    ... همان چرخه Magic Wallet تکرار ...

چرخه ۵ — کاربر "علی" پکیج نقره‌ای می‌خرد (۵.۶M):
────────────────────────────────────────────────────
    ✅ Balance += 5.6M
    ✅ DiscountBalance += 11.2M (×2)
    ✅ ActivationFee → Pool_نقره‌ای هفته جاری (۲,۵۲۰,۰۰۰)
    ✅ فیچرهای پکیج نقره‌ای فعال (ممکنه کمتر از پایه باشه!)
    ✅ NetworkWeeklyBalance جدید (PackageId=نقره‌ای, WeekId=هفته جاری)
    ✅ تعادل‌ها: MaxBalancesPerLeg=30 (نه 300!) + MaxNetworkLevel=15 (از پکیج)
    ✅ carryover: فقط carryover نقره‌ای (جداگانه از پایه)
    ✅ بالاسری‌ها: محاسبه از Pool_نقره‌ای → ValuePerBalance کمتر
    ✅ پاداش بالاسری: ~۲,۵۲۰,۰۰۰ ÷ TotalBalances_نقره‌ای × BalancesEarned

۶.۴ تعادل‌ها (NetworkWeeklyBalance) — per-package (v3)

⚠️ تغییر اساسی: هر کاربر به‌ازای هر پکیج فعال یک رکورد تعادل جداگانه دارد.

قبل (تک‌پکیج):
    NetworkWeeklyBalance: [UserId, WeekId] → یک رکورد

بعد (چند‌پکیج):
    NetworkWeeklyBalance: [UserId, WeekId, PackageId] → N رکورد (N = تعداد پکیج)

الگوریتم محاسبه تعادل per-package:

برای هر پکیج فعال:
    1. واکشی کاربرانی که این پکیج را دارند (PackageId = X)
    2. carryover از هفته قبل: فقط رکوردهای PackageId = X
    3. اعضای جدید: فقط کسانی که PackageId = X خریدند + JoinedAt در بازه هفته
    4. LeftLegTotal = NewLeft + CarryoverLeft
    5. RightLegTotal = NewRight + CarryoverRight
    6. TotalBalances = MIN(Left, Right) → cap at Package.MaxBalancesPerLeg
    7. Remainder → carryover هفته بعد (فقط برای PackageId = X)
    8. SubordinateBalances: مجموع TotalBalances زیرمجموعه (تا Package.MaxNetworkLevel)

مثال عملی:

هفته ۱۰:
    علی (پکیج پایه):
        تعادل_پایه:   Left=45, Right=52, Min=45 (cap 300) → OK
        تعادل_نقره‌ای: Left=0, Right=0 (علی پکیج نقره‌ای نداره)
    
    سارا (پکیج نقره‌ای):
        تعادل_پایه:   Left=0, Right=0
        تعادل_نقره‌ای: Left=12, Right=8, Min=8 (cap 30) → OK
    
    رضا (پکیج پایه + قبلاً نقره‌ای داشته):
        تعادل_پایه:   Left=30, Right=25, Min=25 (cap 300) → OK
        تعادل_نقره‌ای: Left=2 (carryover), Right=0 (carryover) → Min=0
        
هفته ۱۱ (Shift):
    علی: carryover_پایه = {Left: surplus_left, Right: surplus_right}
    سارا: carryover_نقره‌ای = {Left: surplus_left, Right: surplus_right}
    رضا: carryover_پایه = {...}, carryover_نقره‌ای = {Left:2, Right:0}

۶.۵ تغییرات SP (v3 — بروزرسانی)

SP	تغییرات v2	تغییرات اضافی v3
sp_CalculateWeeklyBalances	پارامتر @PackageId	@MaxBalancesPerLeg و @MaxNetworkLevel هم پارامتر شوند (نه hardcoded)
sp_CalculateWeeklyCommissionPool	پارامتر @PackageId	Pool فقط از تعادل‌های همان PackageId

sp_CalculateWeeklyBalances — تغییرات ساختاری:

-- قبل (v2 — فقط PackageId فیلتر):
CREATE PROCEDURE sp_CalculateWeeklyBalances
    @WeekDefinitionId BIGINT,
    @PackageId BIGINT,
    @MaxBalancesPerLeg INT = 300,    -- ← hardcoded!
    @MaxNetworkLevel INT = 15        -- ← hardcoded!

-- بعد (v3 — همه داینامیک):
CREATE PROCEDURE sp_CalculateWeeklyBalances
    @WeekDefinitionId BIGINT,
    @PackageId BIGINT,
    @MaxBalancesPerLeg INT,          -- ← از Package entity خوانده می‌شود
    @MaxNetworkLevel INT,            -- ← از Package entity خوانده می‌شود
    @ForceRecalculate BIT = 0,
    @RowCount INT OUTPUT

StoredProcedureCommissionCalculationStrategy — تغییرات:

// قبل: فقط 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 
    });

۶.۶ تغییرات Service (v3)

// WeeklyCommissionCalculationService — Loop روی پکیج‌ها:
var activePackages = await _context.Packages
    .Where(p => p.IsActive && !p.IsDeleted)
    .ToListAsync();

foreach (var package in activePackages)
{
    _logger.LogInformation(
        "Calculating commission for package {Id}: {Title} " +
        "(MaxBalances={Max}, MaxLevel={Level})", 
        package.Id, package.Title, 
        package.MaxBalancesPerLeg, package.MaxNetworkLevel);
    
    // محاسبه تعادل‌ها — هر پکیج با تنظیمات خودش
    await strategy.CalculateWeeklyBalancesAsync(
        weekId, package.Id, 
        package.MaxBalancesPerLeg, package.MaxNetworkLevel);
    
    // محاسبه Pool — هر پکیج جداگانه
    await strategy.CalculateWeeklyPoolAsync(weekId, package.Id);
}

۶.۷ گزارش‌دهی پورسانت per-package (v3 — جدید)

⚠️ فعلاً package_id در هیچ‌کدام از پیام‌های commission.proto وجود ندارد!

تغییرات Proto (commission.proto):

message UserWeeklyBalanceModel {
    // ... فیلدهای فعلی ...
+   int64 package_id = 17;
+   string package_title = 18;
}

message UserCommissionPayoutModel {
    // ... فیلدهای فعلی ...
+   int64 package_id = 16;
+   string package_title = 17;
}

message CustomerCommissionPayoutModel {
    // ... فیلدهای فعلی ...
+   int64 package_id = 10;
+   string package_title = 11;
}

message CustomerWeeklyBalanceModel {
    // ... فیلدهای فعلی ...
+   int64 package_id = 15;
+   string package_title = 16;
}

+ // مدل خلاصه پورسانت per-package برای مشتری
+ message CustomerCommissionPackageSummary {
+     int64 package_id = 1;
+     string package_title = 2;
+     int32 downline_count = 3;           // تعداد زیرمجموعه با این پکیج
+     int32 left_leg_members = 4;
+     int32 right_leg_members = 5;
+     int32 total_balances = 6;
+     int64 commission_earned = 7;        // پورسانت کسب‌شده از این پکیج
+     string commission_formatted = 8;
+ }

// Request فیلتر بر اساس پکیج
message GetAllWeeklyBalancesByFilterRequest {
    // ... فیلدهای فعلی ...
+   Int64Value package_id = 7;             // فیلتر اختیاری
}

message GetUserCommissionPayoutsRequest {
    // ... فیلدهای فعلی ...
+   Int64Value package_id = 7;             // فیلتر اختیاری
}

FrontOffice — گزارش پورسانت per-package (صفحه جدید/بهبود):

┌─── پاداش‌های من — هفته ۱۰ ────────────────────────────────────────────┐
│                                                                         │
│  📊 خلاصه بر اساس پکیج:                                                │
│                                                                         │
│  ┌── پکیج پایه ─────────────────┐  ┌── پکیج نقره‌ای ───────────────┐     │
│  │  زیرمجموعه: ۱۲ نفر            │  │  زیرمجموعه: ۵ نفر            │     │
│  │  تیم اول: ۷  │  تیم دوم: ۵    │  │  تیم اول: ۳  │  تیم دوم: ۲   │     │
│  │  تعادل: ۵                     │  │  تعادل: ۲                    │     │
│  │  💰 پاداش: ۱,۲۵۰,۰۰۰ تومان   │  │  💰 پاداش: ۱۸۰,۰۰۰ تومان   │     │
│  └───────────────────────────────┘  └──────────────────────────────┘     │
│                                                                         │
│  📦 مجموع پاداش هفته: ۱,۴۳۰,۰۰۰ تومان                                 │
│     ├── از پکیج پایه: ۱,۲۵۰,۰۰۰                                       │
│     └── از پکیج نقره‌ای: ۱۸۰,۰۰۰                                       │
└─────────────────────────────────────────────────────────────────────────┘

BackOffice — گزارش ادمین با فیلتر پکیج:

┌─── گزارش تعادل‌ها — هفته ۱۰ ───────────────────────────────────────┐
│                                                                      │
│  فیلتر: [▼ پکیج: همه ▼]  [کاربر: ___]  [هفته: ▼ هفته ۱۰ ▼]  [جستجو]│
│         ├── همه                                                      │
│         ├── پکیج پایه                                                │
│         └── پکیج نقره‌ای                                              │
│                                                                      │
│  # │ کاربر    │ پکیج    │ تیم اول │ تیم دوم │ تعادل │ سهم استخر      │
│  ──┼──────────┼─────────┼─────────┼─────────┼───────┼────────────────│
│  1 │ علی      │ پایه    │ ۴۵      │ ۵۲      │ ۴۵    │ ۲,۲۵۰,۰۰۰     │
│  2 │ سارا     │ نقره‌ای  │ ۱۲      │ ۸       │ ۸     │ ۱۴۴,۰۰۰       │
│  3 │ رضا      │ پایه    │ ۳۰      │ ۲۵      │ ۲۵    │ ۱,۲۵۰,۰۰۰     │
│  4 │ رضا      │ نقره‌ای  │ ۲       │ ۰       │ ۰     │ ۰              │
│                                                                      │
│  خلاصه: پکیج پایه: ۷۰ تعادل | پکیج نقره‌ای: ۸ تعادل                 │
└──────────────────────────────────────────────────────────────────────┘

---

۷. Event-Driven Side Effects

۷.۱ ساخت پکیج جدید

flowchart LR
    A["ساخت پکیج جدید<br/>(از BackOffice)"] --> B["PackageCreatedEvent"]
    B --> C["ایجاد Pool خالی<br/>برای هفته جاری"]
    B --> D["لاگ ادمین"]

۷.۲ جدول رویدادها

رویداد	Side Effect
PackageCreated	ساخت WeeklyCommissionPool خالی هفته جاری
PackageDeactivated	هشدار ادمین — Pool موجود تکمیل شود
PackagePurchased	ActivationFee → Pool پکیج + شارژ wallets
MagicCycleCompleted	ریست PackagePurchaseMethod + Deactivate membership

---

۸. Seed Data

-- پکیج پایه (۵۶ میلیون تومان)
INSERT INTO "CMS"."Packages" (
    "Title", "Description", "Price", "IsActive", "IsBasePackage",
    "SupportsDayaPurchase", "SupportsDirectPurchase", 
    "ActivationFee", "DiscountMultiplier", "MagicWalletMultiplier",
    "MaxBalancesPerLeg", "MaxNetworkLevel",
    "MagicWalletMaxDeposit", "MagicWalletMaxCredit",
    "SortOrder", "ImagePath"
) VALUES (
    'پکیج پایه', 'پکیج اصلی باشگاه مشتریان کارا بازار سلامت',
    56000000, true, true,
    true, true,
    25200000, 2.0, 2.5,
    300, 15,
    1000000000, 2500000000,
    2, ''
);

-- پکیج نقره‌ای (۵.۶ میلیون تومان)
INSERT INTO "CMS"."Packages" (
    "Title", "Description", "Price", "IsActive", "IsBasePackage",
    "SupportsDayaPurchase", "SupportsDirectPurchase",
    "ActivationFee", "DiscountMultiplier", "MagicWalletMultiplier",
    "MaxBalancesPerLeg", "MaxNetworkLevel",
    "MagicWalletMaxDeposit", "MagicWalletMaxCredit",
    "SortOrder", "ImagePath"
) VALUES (
    'پکیج نقره‌ای', 'پکیج سطح نقره‌ای باشگاه مشتریان',
    5600000, true, false,
    false, true,
    2520000, 2.0, 2.5,
    30, 15,
    100000000, 250000000,
    1, ''
);

-- فیچرهای پکیج پایه: همه فیچرها
INSERT INTO "CMS"."PackageFeatures" ("PackageId", "ClubFeatureId", "IsIncluded")
SELECT base."Id", cf."Id", true
FROM "CMS"."Packages" base
CROSS JOIN "CMS"."ClubFeatures" cf
WHERE base."IsBasePackage" = true AND cf."IsDeleted" = false;

-- فیچرهای پکیج نقره‌ای: تعیین می‌شود از BackOffice

---

۹. Migration داده‌های فعلی

-- ========================================
-- STEP 1: مشخص کردن ID پکیج پایه
-- ========================================
DO $$
DECLARE base_pkg_id BIGINT;
BEGIN
    SELECT "Id" INTO base_pkg_id 
    FROM "CMS"."Packages" WHERE "IsBasePackage" = true LIMIT 1;
    
    -- STEP 2: ClubMembership
    UPDATE "CMS"."ClubMemberships" 
    SET "PackageId" = base_pkg_id WHERE "PackageId" IS NULL;
    
    -- STEP 3: ClubMembershipCycle
    UPDATE "CMS"."ClubMembershipCycles" 
    SET "PackageId" = base_pkg_id WHERE "PackageId" IS NULL;
    
    -- STEP 4: WeeklyCommissionPool
    UPDATE "CMS"."WeeklyCommissionPools" 
    SET "PackageId" = base_pkg_id WHERE "PackageId" IS NULL;
    
    -- STEP 5: UserCommissionPayout
    UPDATE "CMS"."UserCommissionPayouts"
    SET "PackageId" = base_pkg_id WHERE "PackageId" IS NULL;
    
    -- STEP 6: NetworkWeeklyBalance (v3 — جدید)
    UPDATE "CMS"."NetworkWeeklyBalances"
    SET "PackageId" = base_pkg_id WHERE "PackageId" IS NULL;
    
    RAISE NOTICE 'Migration completed for PackageId=%', base_pkg_id;
END $$;

-- STEP 7: Verify — همه باید 0 باشند
SELECT 'ClubMemberships' AS tbl, COUNT(*) FROM "CMS"."ClubMemberships" WHERE "PackageId" IS NULL
UNION ALL
SELECT 'Cycles', COUNT(*) FROM "CMS"."ClubMembershipCycles" WHERE "PackageId" IS NULL
UNION ALL
SELECT 'Pools', COUNT(*) FROM "CMS"."WeeklyCommissionPools" WHERE "PackageId" IS NULL
UNION ALL
SELECT 'Payouts', COUNT(*) FROM "CMS"."UserCommissionPayouts" WHERE "PackageId" IS NULL
UNION ALL
SELECT 'Balances', COUNT(*) FROM "CMS"."NetworkWeeklyBalances" WHERE "PackageId" IS NULL;

---

۱۰. Impact Analysis — ۴۸+ تغییر در ۶ لایه (v3)

۱۰.۱ لایه Domain (۱۰ تغییر)

#	فایل	نوع	شدت	v3?
D1	Package.cs	اضافه ۱۱ فیلد جدید (v2: ۷ + v3: ۴)	🟡	🔄
D2	PackageFeature.cs	Entity جدید + EF Config	🔴
D3	ClubMembership.cs	اضافه PackageId	🟡
D4	ClubMembershipCycle.cs	اضافه PackageId	🟡
D5	WeeklyCommissionPool.cs	اضافه PackageId + Unique	🔴
D6	UserCommissionPayout.cs	اضافه PackageId + Unique(UserId,WeekId,PackageId)	🟡	🔄
D7	SystemConstants.cs	حذف ۷ ثابت (v2: ۵ + v3: ۲)، حفظ ۱۱	🟡	🔄
D8	EF Migration + Seed	schema + data migration	🔴
D9	NetworkWeeklyBalance.cs	اضافه PackageId + Unique(UserId,WeekId,PackageId)	🔴	🆕
D10	Data volume impact	رکوردهای تعادل ×N (تعداد پکیج)	🟡	🆕

۱۰.۲ لایه Application (۱۲ تغییر)

#	فایل	نوع	شدت
A1	ActivateClubMembershipCommandHandler	فیچر از PackageFeature + ActivationFee + re-activate	🔴
A2	VerifyPackagePurchaseCommandHandler	DiscountMultiplier + UserPackagePurchase + generic	🔴
A3	VerifyBasePackagePaymentCommandHandler	DiscountMultiplier + UserPackagePurchase + generic	🔴
A4	VerifyGoldenPackagePurchaseCommandHandler	فیکس DiscountBalance + UserPackagePurchase + generic	🔴
A5	InitiateBasePackagePaymentCommandHandler	حذف ID=4 + generic	🟡
A6	PurchaseGoldenPackageCommandHandler	حذف فیلتر "طلایی" + generic	🟡
A7	PurchasePackageCommandHandler	اجازه re-purchase	🟡
A8	CreateManualPaymentCommandHandler	DiscountMultiplier از Package	🟡
A9	CheckAndProcessDayaLoansCommandHandler	حذف ID=4 + DiscountMultiplier	🟡
A10	AcceptClubMembershipContractCommandHandler	اجازه re-contract بعد چرخه	🟡
A11	UserOrderService (EXIT Magic)	ریست PackagePurchaseMethod + Deactivate	🔴
A12	Package CRUD handlers	فیلدهای جدید + PackageFeature CRUD	🟡

۱۰.۳ لایه Infrastructure (۶ تغییر)

#	فایل	نوع	شدت	v3?
I1	sp_CalculateWeeklyBalances	پارامتر @PackageId + @MaxBalancesPerLeg + @MaxNetworkLevel (حذف hardcode)	🔴	🔄
I2	sp_CalculateWeeklyCommissionPool	پارامتر @PackageId + فیلتر تعادل‌های همان پکیج	🔴	🔄
I3	WeeklyCommissionCalculationService	Loop روی پکیج‌ها + ارسال تنظیمات هر پکیج	🟡	🔄
I4	OrmCommissionCalculationStrategy	فیلتر PackageId + خواندن MaxBalancesPerLeg/MaxNetworkLevel از Package	🔴	🔄
I5	SpCommissionCalculationStrategy	پاس دادن PackageId + MaxBalancesPerLeg + MaxNetworkLevel	🟡	🔄
I6	Carryover logic	Week-shifting per-package: carryover فقط رکوردهای همان PackageId	🔴	🆕

۱۰.۴ لایه Proto/gRPC (۶ تغییر)

#	فایل	نوع	شدت	v3?
P1	package.proto	فیلدهای جدید Package (۱۱ فیلد)	🟡	🔄
P2	clubmembership.proto	package_id در request/response	🟡
P3	commission.proto	package_id + package_title در ۴ message: UserWeeklyBalance, UserCommissionPayout, CustomerCommissionPayout, CustomerWeeklyBalance	🔴	🔄
P4	PackageGrpcService.cs	Generic purchase + CRUD	🟡
P5	commission.proto	Message جدید: CustomerCommissionPackageSummary (خلاصه per-package)	🟡	🆕
P6	commission.proto	فیلتر اختیاری package_id در Request‌های GetWeeklyBalances + GetPayouts	🟡	🆕

۱۰.۵ لایه FrontOffice (۸ تغییر)

#	فایل	نوع	شدت	v3?
F1	Packages.razor	کاشی‌های پکیج از API	🔴
F2	PackageDetail.razor	فیچرها از PackageFeature	🟡
F3	ActivationSection.razor	حذف hardcoded 56M	🟡
F4	ClubMembershipContractDialog.razor	متن قرارداد داینامیک	🟡
F5	MyPackages.razor	نمایش نوع پکیج + re-purchase	🟡
F6	PackageService.cs	فیکس stub GetPurchaseHistory	🟡
F7	CommissionDashboardPage.razor	خلاصه پاداش per-package (کارت‌های جداگانه هر پکیج)	🔴	🆕
F8	WeeklyBalancePage.razor	تعادل‌ها per-package (تیم اول/دوم بر اساس پکیج)	🟡	🆕

۱۰.۶ لایه BackOffice (۸ تغییر)

#	فایل	نوع	شدت	v3?
BO1	PackageCreateDialog.razor	فیلدهای جدید (۱۱ فیلد شامل MaxBalancesPerLeg, MaxNetworkLevel, MagicWallet limits)	🟡	🔄
BO2	PackageEditDialog.razor	فیلدهای جدید + Quick Access فیچرها (checkbox فیچرها در همان فرم)	🟡	🔄
BO3	PackageFeatureMatrixPage — جدید	ماتریس پکیج×فیچر	🔴
BO4	ActivateClubDialog.razor	dropdown انتخاب پکیج	🟡
BO5	Dashboard.razor (Commission)	فیلتر dropdown پکیج + خلاصه per-package	🟡	🆕
BO6	WeeklyReportsPage.razor	فیلتر پکیج + CSV export per-package	🟡	🆕
BO7	BalancesReportPage.razor	فیلتر پکیج + ستون پکیج در جدول تعادل‌ها	🟡	🆕
BO8	UserPayoutsPage.razor	ستون پکیج در لیست پرداخت‌ها + فیلتر	🟡	🆕

---

۱۱. فازبندی پیاده‌سازی

فاز ۰ — فیکس باگ‌های فوری ≈ ۱ روز

تسک	شرح
T0.1	فیکس VerifyGoldenPackagePurchase — اضافه DiscountBalance (Amount × 2)
T0.2	فیکس VerifyGoldenPackagePurchase — ساخت UserPackagePurchase
T0.3	فیکس VerifyPackagePurchase — ساخت UserPackagePurchase
T0.4	فیکس VerifyBasePackagePayment — ساخت UserPackagePurchase

فاز ۱ — زیرساخت (Domain + DB) ≈ ۳ روز

تسک	شرح	v3?
T1.1	بروزرسانی Package entity (۱۱ فیلد جدید: v2 ۷ + v3 ۴ شامل MaxBalancesPerLeg, MaxNetworkLevel, MagicWalletMaxDeposit, MagicWalletMaxCredit)	🔄
T1.2	ایجاد PackageFeature entity + EF Config
T1.3	اضافه PackageId به ClubMembership
T1.4	اضافه PackageId به ClubMembershipCycle
T1.5	اضافه PackageId به WeeklyCommissionPool + Unique(WeekId,PackageId)
T1.6	اضافه PackageId به UserCommissionPayout + Unique(UserId,WeekId,PackageId)	🔄
T1.7	حذف ۷ ثابت از SystemConstants (v2: ۵ + v3: MaxWeeklyBalancesPerLeg, MaxNetworkLevel)	🔄
T1.8	Database Migration + Seed Data (۲ پکیج + فیچرها)
T1.9	Data Migration: کاربران فعلی → PackageId = پکیج پایه
T1.10	بروزرسانی Proto‌ها (package + clubmembership + commission)	🔄
T1.11	اضافه PackageId به NetworkWeeklyBalance + Unique(UserId,WeekId,PackageId)	🆕
T1.12	Data Migration: NetworkWeeklyBalance موجود → PackageId = پکیج پایه	🆕

فاز ۲ — منطق کسب‌وکار ≈ ۴ روز

تسک	شرح
T2.1	ادغام Verify handlers → Generic (DiscountMultiplier + UserPackagePurchase)
T2.2	ادغام Purchase handlers → Generic (حذف "طلایی"، حذف ID=4)
T2.3	بروزرسانی ActivateClubMembership — فیچر از PackageFeature
T2.4	بروزرسانی ActivateClubMembership — ActivationFee از Package
T2.5	اجازه re-purchase در Guards (G1–G3)
T2.6	ریست وضعیت در EXIT Magic Mode
T2.7	اجازه re-contract (G5) + بروزرسانی JWT (G7)
T2.8	بروزرسانی CreateManualPayment + DayaLoan
T2.9	PackageFeature CRUD
T2.10	Event: PackageCreated → ساخت Pool خالی

فاز ۳ — محاسبه پورسانت ≈ ۴ روز (موازی با فاز ۲)

تسک	شرح	v3?
T3.1	بروزرسانی sp_CalculateWeeklyBalances — @PackageId + @MaxBalancesPerLeg + @MaxNetworkLevel (حذف hardcode ۳۰۰/۱۵)	🔄
T3.2	بروزرسانی sp_CalculateWeeklyCommissionPool — @PackageId + فیلتر تعادل‌های همان پکیج	🔄
T3.3	بروزرسانی WeeklyCommissionCalculationService — Loop روی پکیج‌ها + ارسال تنظیمات	🔄
T3.4	بروزرسانی OrmCommissionCalculationStrategy — فیلتر PackageId + خواندن Max از Package	🔄
T3.5	بروزرسانی SpCommissionCalculationStrategy — پاس دادن PackageId + MaxBalancesPerLeg + MaxNetworkLevel	🆕
T3.6	Carryover per-package: week-shifting فقط رکوردهای همان PackageId	🆕
T3.7	تست محاسبات با داده واقعی (۲ پکیج موازی، carryover مجزا)	🔄

فاز ۴ — UI ≈ ۵ روز

تسک	شرح	v3?
T4.1	FrontOffice: کاشی‌های پکیج (داینامیک)
T4.2	FrontOffice: مدال پرداخت (دایا+مستقیم / فقط مستقیم)
T4.3	FrontOffice: MyPackages — re-purchase
T4.4	FrontOffice: ActivationSection + Contract — داینامیک
T4.5	BackOffice: CRUD پکیج — فیلدهای جدید (۱۱ فیلد)	🔄
T4.6	BackOffice: ماتریس PackageFeature
T4.7	BackOffice: ActivateClubDialog — dropdown
T4.8	FrontOffice: CommissionDashboard — کارت‌های خلاصه per-package + مجموع پاداش	🆕
T4.9	FrontOffice: WeeklyBalance — تعادل تیم اول/دوم per-package	🆕
T4.10	BackOffice: Commission Dashboard — فیلتر dropdown پکیج	🆕
T4.11	BackOffice: Weekly Reports + CSV export — ستون پکیج + فیلتر	🆕
T4.12	BackOffice: BalancesReport + UserPayouts — ستون پکیج + فیلتر	🆕
T4.13	BackOffice: Package Create/Edit — Quick Access فیچرها (checkbox inline)	🆕

فاز ۵ — تست و استقرار ≈ ۳ روز

تسک	شرح	v3?
T5.1	تست خرید هر پکیج
T5.2	تست re-purchase بعد تکمیل چرخه
T5.3	تست Commission Pool جداگانه
T5.4	تست Migration
T5.5	تست تعادل per-package: carryover مجزا، MaxBalancesPerLeg متفاوت	🆕
T5.6	تست گزارش FO per-package: مشتری breakdown صحیح می‌بیند	🆕
T5.7	تست گزارش BO per-package: فیلتر پکیج + CSV	🆕
T5.8	Deploy staging → production

---

۱۲. ریسک‌ها

ریسک	احتمال	شدت	راه‌حل
Migration داده‌ها — PackageId اشتباه	کم	بحرانی	Verify query + بکاپ
SP تغییر → محاسبات اشتباه	متوسط	بحرانی	تست staging قبل production
ادغام handlers → رگرسیون	متوسط	زیاد	E2E test
خرید مجدد بدون تکمیل چرخه	کم	زیاد	Validation: چرخه قبلی MagicCompletedAt
Proto breaking change	قطعی	کم	backward compatible fields

---

۱۳. تخمین زمانی (v3)

فاز	مدت	وابستگی	v3 تغییر
فاز ۰ — فیکس باگ‌ها	۱ روز	—
فاز ۱ — زیرساخت	۴ روز	فاز ۰	+۱ روز (NetworkWeeklyBalance + Unique)
فاز ۲ — منطق	۴ روز	فاز ۱
فاز ۳ — پورسانت	۴ روز	فاز ۱	+۱ روز (SP params + carryover per-package)
فاز ۴ — UI	۵ روز	فاز ۲	+۱ روز (FO/BO گزارش per-package)
فاز ۵ — تست	۳ روز	فاز ۳, ۴	+۱ روز (تست carryover + گزارش)
مجموع	~۲۱ روز

فاز ۲ و ۳ موازی → مسیر بحرانی: ۰→۱→۲→۴→۵ = ~۱۷ روز
نسبت به v2 (۱۴ روز): +۳ روز بخاطر per-package commission + گزارش‌دهی + carryover