docs/01-BUSINESS/new-business-requirements-2025-12-08.md

توضیحات جدید بیزینس - 2025-12-08

تاریخ دریافت: 2025-12-08
وضعیت: نیاز به تطبیق با کد و داکیومنت موجود
منبع: توضیحات شفاهی از صاحب پروژه

---

1️⃣ فعال‌سازی کاربر و نمایش لینک معرفی

قوانین فعال‌سازی:

کاربر زمانی می‌تواند لینک معرفی خود را ببیند که:

• ✅ وام خود را از دایا گرفته باشه
• ✅ یا پرداخت مستقیم 56 میلیون تومان انجام داده باشه

عضویت باشگاه مشتریان (الزامی):

در هر دو حالت بالا:

1. کاربر اجباراً باید عضو باشگاه مشتریان بشه
2. دیالوگ باشگاه مشتریان و امضای قرارداد الزامی است
3. تا زمانی که این کار انجام نشه → لینک معرفی نمایش داده نمی‌شود

فرآیند:

کاربر ثبت نام می‌کنه
     ↓
پرداخت 56M (دایا یا مستقیم)
     ↓
دیالوگ باشگاه مشتریان (الزامی) ← امضای قرارداد
     ↓
لینک معرفی نمایش داده می‌شود

---

2️⃣ محاسبه تعادل (Balance) شبکه

قانون اصلی:

هر نود شبکه = یک تعادل

تعداد تعادل = MIN(دست راست، دست چپ)

حالت عادی (زیر 300 تعادل):

• اگر دست راست = 200 نفر و دست چپ = 150 نفر
  • ✅ تعادل = MIN(200, 150) = 150 امتیاز
  • ✅ باقیمانده راست = 200 - 150 = 50 → برای هفته بعد

حالت بالای 300 تعادل (سقف):

اگر مجموع کاربران جفت دست یک نفر بیشتر از 600 نفر باشد:

مثال:

دست راست = 600 نفر
دست چپ = 400 نفر

مرحله 1: محاسبه تعادل اولیه

• تعادل = MIN(600, 400) = 400

مرحله 2: محاسبه باقیمانده اولیه

• باقیمانده راست = 600 - 400 = 200 → می‌رود برای هفته بعد

مرحله 3: اعمال سقف 300

• چون تعادل (400) > 300 → فقط 300 امتیاز حساب می‌شود
• از دست راست: 100 نفر فلش می‌شود
• از دست چپ: 100 نفر فلش می‌شود
• مجموع 200 نفر فلش می‌شود (دیگه هیچ جا حساب نمی‌شن)

نتیجه نهایی:

• امتیاز این هفته: 300
• باقیمانده راست برای هفته بعد: 200 (این مجزا از فلش است)
• فلش شده (از بین رفته): 200 (100 چپ + 100 راست)

نکته مهم:

باقیمانده‌ای که از هفته قبل می‌آید فلش نمی‌شود، فقط اضافه‌ای که بزرگتر از 300 تعادل است فلش می‌شود.

---

3️⃣ محاسبه تعادل بازگشتی (Recursive Balance)

قانون مهم:

هر نفر تعداد تعادل‌هاش فقط برای خودش حساب می‌شه

مثال درخت:

        کاربر 1
        /      \
   کاربر 2    کاربر 3
   /      \
کاربر 4  کاربر 5

محاسبات:

1. کاربر 2:

   • جذب کرده: کاربر 4 و کاربر 5
   • تعادل کاربر 2 = MIN(1, 1) = 1 تعادل

2. کاربر 1:

   • دست راست: کاربر 2 = 1 نفر
   • دست چپ: کاربر 3 = 1 نفر
   • تعادل کاربر 1 = MIN(1, 1) = 1 تعادل

⚠️ نکته کلیدی:

کاربر 1 پورسانت کاربر 4 و 5 را نمی‌گیرد!

چرا؟ چون:

• کاربر 3 کسی را جذب نکرده
• برای اینکه کاربر 1 از تعادل کاربر 4 و 5 بهره‌مند شود
• کاربر 3 حتماً باید دو نفر جذب کند

مثال تصحیح شده:

        کاربر 1
        /      \
   کاربر 2    کاربر 3
   /      \    /      \
کاربر 4  5  کاربر 6  7

حالا:

• کاربر 3: تعادل = MIN(1, 1) = 1
• کاربر 2: تعادل = MIN(1, 1) = 1
• کاربر 1: تعادل = MIN(2, 2) = 2 تعادل ✅

---

4️⃣ ارزش امتیاز و توزیع کمیسیون

فرمول:

ارزش هر امتیاز = (مجموع مبلغ صندوق) ÷ (تعداد کل تعادل‌ها)

مبلغ صندوق:

هر کاربری که 56 میلیون تومان واریز می‌کند:

• 25 میلیون تومان وارد صندوق می‌شود

مثال محاسبه:

صندوق هفته = 175 میلیون تومان (7 نفر × 25M)
مجموع تعادل‌های سیستم = 50 امتیاز

ارزش هر امتیاز = 175,000,000 ÷ 50 = 3,500,000 ریال

اگر یک کاربر 5 تعادل داشته باشد:

کمیسیون = 5 × 3,500,000 = 17,500,000 ریال

---

5️⃣ حذف خودکار کاربران غیرفعال (Worker جدید مورد نیاز)

قانون:

کاربری که تا 2 هفته بعد از ثبت نام:

• ❌ وام دایا را نگرفته
• ❌ 56 میلیون تومان مستقیم واریز نکرده

→ به صورت اتوماتیک حذف می‌شود

Worker مورد نیاز:

// نام پیشنهادی: DeleteInactiveUsersWorker
// زمان اجرا: روزانه یک بار (مثلاً 3 صبح)

شبه‌کد:
1. کاربرانی که CreatedAt < (Now - 14 روز)
2. IsActive == false (یعنی نه دایا گرفته، نه پرداخت مستقیم)
3. ClubMembershipId == null
4. حذف کاربر
5. آزاد کردن جایگاه در شبکه برای معرف

هدف:

• معرفی که این کاربر را جذب کرده بود، یکی از دست‌هایش آزاد می‌شود
• می‌تواند کاربر جدید جذب کند
• امکان تعادل متعادل دست چپ و راست فراهم می‌شود

---

6️⃣ محدودیت تعداد زیرمجموعه

قانون سخت:

هر کاربر فقط 2 نفر می‌تواند جذب کند (دست چپ + دست راست)

سناریو خطا:

کاربر A: دو نفر زیرمجموعه فعال دارد
کاربر B: با کد معرف کاربر A ثبت نام می‌کند

→ ❌ پیغام خطا:
"این کاربر تعداد زیرمجموعه‌هاش پر شده و شما نمی‌تونید جزو زیرمجموعه این آدم بشید"

نکته:

فعال یعنی:

• وام دایا گرفته یا پرداخت مستقیم کرده
• عضو باشگاه مشتریان شده

---

7️⃣ فرآیند کامل ثبت نام تا فعال‌سازی

1. ثبت نام با کد معرف
   ↓
2. بررسی ظرفیت معرف (حداکثر 2 نفر)
   ↓ (اگر پر بود → خطا)
   ↓
3. درخواست وام دایا یا پرداخت مستقیم (56M)
   ↓
4. تأیید پرداخت 56M
   ↓
5. شارژ کیف پول‌ها:
   - کیف پول اصلی: +56M
   - کیف پول تخفیفی: +56M
   ↓
6. **دیالوگ الزامی باشگاه مشتریان**
   - امضای قرارداد
   - تخصیص 25M به صندوق
   ↓
7. کاربر فعال می‌شود
   ↓
8. لینک معرفی نمایش داده می‌شود
   ↓
9. ورود به فرآیند محاسبه کمیسیون هفتگی

---

8️⃣ خرید از فروشگاه‌ها

دو نوع فروشگاه:

1. فروشگاه اصلی:

   • از کیف پول اصلی کسر می‌شود

2. فروشگاه تخفیفی (باشگاه مشتریان):

   • از کیف پول تخفیفی کسر می‌شود
   • به مقداری که تخفیف دارد

---

9️⃣ جمع‌بندی تعادل و فلش

سناریو کامل:

هفته 1:
- چپ = 500، راست = 600
- تعادل = MIN(500, 600) = 500

چون 500 > 300:
- امتیاز این هفته = 300
- فلش چپ = 500 - 300 = 200
- فلش راست = 600 - 300 = 300
- جمع فلش = 500 (از بین رفت)

قوانین فلش:

1. ❌ باقیمانده‌ای که از هفته قبل می‌آید فلش نمی‌شود
2. ✅ فقط اضافه‌ای که بزرگتر از 300 است فلش می‌شود
3. ✅ هر دو طرف (چپ و راست) فلش می‌شوند
4. ❌ نمی‌تواند فقط یک طرف فلش شود

مثال فلش:

هفته قبل باقیمانده راست = 200
هفته جدید راست = 400
مجموع راست = 600

سقف = 300
فلش راست = 600 - 300 = 300 ✅ (نه 200)

---

🔟 نکات مهم اضافی

چرخش هفتگی:

• محاسبات هر هفته صورت می‌گیرد
• تعادل‌های استفاده شده ریست می‌شوند
• فقط باقیمانده به هفته بعد منتقل می‌شود
• فلش‌ها هیچ جا حساب نمی‌شوند

محدودیت‌های عمق شبکه:

• تا همه کاربرها در زیر شبکه حساب می‌شوند
• بدون محدودیت عمق (تا سطح آخر درخت)

اولویت محاسبه:

1. محاسبه تعادل اولیه
2. محاسبه باقیمانده
3. اعمال سقف 300
4. محاسبه فلش
5. ذخیره باقیمانده برای هفته بعد

---

📊 جدول مقایسه حالات مختلف

چپ	راست	تعادل اولیه	سقف 300	امتیاز	باقی چپ	باقی راست	فلش کل
200	250	200	200	200	0	50	0
400	350	350	300	300	100	50	100
500	600	500	300	300	200	300	400
150	280	150	150	150	0	130	0
350	350	350	300	300	50	50	100

توضیح ستون‌ها:

• تعادل اولیه: MIN(چپ، راست)
• سقف 300: MIN(تعادل اولیه، 300)
• امتیاز: همان سقف 300 (امتیاز نهایی)
• باقی چپ: چپ - سقف چپ (300)
• باقی راست: راست - سقف راست (300)
• فلش کل: (چپ - 300) + (راست - 300) اگر > 0

---

✅ وضعیت پیاده‌سازی فعلی

این سند نیاز به تطبیق کامل با:

1. ✅ کد موجود در CalculateWeeklyBalancesCommandHandler
2. ✅ داکیومنت‌های موجود در totalDoc/01-BUSINESS/
3. ✅ Entity ها در Domain Layer
4. ✅ Worker های پس‌زمینه

→ در مرحله بعد مقایسه و شناسایی تفاوت‌ها انجام می‌شود.