masoodafar-web
efff5e9cd5
- business/ (5): club-commission, payment, ecommerce, membership, content - technical/ (5): cms-arch, ui, deployment, migration, api - overview/ (5): flowcharts, index, changelog, glossary, roadmap - Removed all old folders: backoffice, cms, deployment, docs, frontoffice, migration, ui-modernization, business (old) - Updated internal links with relative folder paths
168 lines
5.6 KiB
Markdown
168 lines
5.6 KiB
Markdown
# 🏆 سیستم باشگاه، کمیسیون و درخت شبکهای
|
||
|
||
> **منابع ادغامشده:** `club-commission-system-complete.md`, `balance-calculation-rules.md`, `club-membership-contract-system.md`
|
||
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
|
||
|
||
---
|
||
|
||
## ۱. مفاهیم کلیدی
|
||
|
||
| مفهوم | توضیح |
|
||
|-------|--------|
|
||
| **عضویت باشگاه** | خرید پکیج طلایی (۵۶M) → فعالسازی (۲۵M) → عضو فعال باشگاه |
|
||
| **درخت باینری** | هر کاربر حداکثر ۲ فرزند مستقیم (چپ/راست) — حداکثر ۱۵ سطح |
|
||
| **کمیسیون هفتگی** | محاسبه بر اساس تعادل چپ/راست — هفته شمسی شنبهتاجمعه |
|
||
| **۳ کیف پول** | `Balance` (نقدی) + `NetworkBalance` (شبکهای) + `DiscountBalance` (تخفیفی) |
|
||
|
||
---
|
||
|
||
## ۲. ساختار درخت باینری
|
||
|
||
```
|
||
Root
|
||
/ \
|
||
Left Right
|
||
/ \ / \
|
||
L1 L2 R1 R2
|
||
/ \ / \ / \ / \
|
||
... ... ... ... ... ← حداکثر ۱۵ سطح
|
||
```
|
||
|
||
**قوانین:**
|
||
- هر نود حداکثر ۲ فرزند (Binary)
|
||
- جایگذاری: `LegPosition` ∈ {Left, Right}
|
||
- عضو جدید → در اولین جای خالی از چپترین مسیر قرار میگیرد
|
||
- `SP_GetNetworkTree` — Stored Procedure بازگشتی
|
||
|
||
---
|
||
|
||
## ۳. فلوی عضویت و فعالسازی
|
||
|
||
```
|
||
خرید پکیج طلایی (56M تومان)
|
||
│
|
||
▼
|
||
نمایش مودال قرارداد (غیرقابلبستهشدن)
|
||
│
|
||
▼
|
||
مشاهده متن قرارداد ← ReadContract RPC
|
||
│
|
||
▼
|
||
درخواست OTP ← RequestContractOtp (Kavenegar SMS)
|
||
│
|
||
▼
|
||
وارد کردن کد ← VerifyContractOtp
|
||
│
|
||
▼
|
||
امضای قرارداد ← AcceptContract
|
||
│
|
||
├─→ شارژ ۳ کیف پول (Balance=56M, Network=56M, Discount=56M)
|
||
├─→ کسر هزینه فعالسازی (25M از Balance)
|
||
├─→ واریز 25.2M به Pool هفتگی
|
||
├─→ قرارگیری در درخت باینری
|
||
└─→ رفرش JWT Token (claims جدید)
|
||
```
|
||
|
||
---
|
||
|
||
## ۴. الگوریتم محاسبه کمیسیون هفتگی
|
||
|
||
### ۴.۱ فرمول ۴ مرحلهای
|
||
|
||
```
|
||
مرحله ۱: جمع فروش هر پا
|
||
SumLeft = Σ(فروشهای پای چپ در هفته جاری + CanOverLeft)
|
||
SumRight = Σ(فروشهای پای راست در هفته جاری + CanOverRight)
|
||
|
||
مرحله ۲: محاسبه تعادل
|
||
WeeklyBalance = MIN(SumLeft, SumRight)
|
||
|
||
مرحله ۳: محاسبه باقیمانده (Carryover)
|
||
CanOverLeft = SumLeft - WeeklyBalance
|
||
CanOverRight = SumRight - WeeklyBalance
|
||
|
||
مرحله ۴: سقف هفتگی
|
||
IF WeeklyBalance > 300 → WeeklyBalance = 300
|
||
IF CanOverLeft > 300 → Flush (CanOverLeft = 0)
|
||
IF CanOverRight > 300 → Flush (CanOverRight = 0)
|
||
```
|
||
|
||
### ۴.۲ مثال عددی (درخت ۵ سطحی)
|
||
|
||
```
|
||
هفته ۱: چپ=120, راست=80 → Balance=80, Over(L=40, R=0)
|
||
هفته ۲: چپ=90+40=130, راست=150 → Balance=130, Over(L=0, R=20)
|
||
هفته ۳: چپ=200, راست=180+20=200 → Balance=200, Over(L=0, R=0)
|
||
هفته ۴: چپ=500, راست=100 → Balance=100, Over(L=400→FLUSH=0, R=0)
|
||
```
|
||
|
||
### ۴.۳ Pool هفتگی و توزیع
|
||
|
||
```
|
||
منبع Pool: هر فعالسازی عضو → 25.2M واریز به Pool
|
||
توزیع: بر اساس WeeklyBalance هر عضو / مجموع WeeklyBalanceها
|
||
SP: sp_CalculateWeeklyBalances → sp_CalculateWeeklyCommissionPool
|
||
فرمت هفته: "YYYY-Www" (شمسی، شنبهپایه)
|
||
```
|
||
|
||
---
|
||
|
||
## ۵. تنظیمات سیستمی (SystemConstants)
|
||
|
||
| ثابت | مقدار | توضیح |
|
||
|------|-------|--------|
|
||
| `Club.ActivationFee` | 25,000,000 | هزینه فعالسازی (تومان) |
|
||
| `Club.GiftValue` | 25,200,000 | واریز به Pool |
|
||
| `GoldenPackageAmount` | 56,000,000 | قیمت پکیج طلایی |
|
||
| `DayaLoanAmount` | 56,000,000 | مبلغ وام دایا |
|
||
| `MaxWeeklyBalancesPerLeg` | 300 | سقف هفتگی هر پا |
|
||
| `MaxNetworkLevel` | 15 | حداکثر عمق درخت |
|
||
| `ClubJoiningPercentage` | 0.35 | درصد پیوستن |
|
||
| `ClubActivationThreshold` | 0.5 | آستانه فعالسازی |
|
||
| `MaxCalculationAttempts` | 3 | حداکثر تلاش محاسبه |
|
||
|
||
---
|
||
|
||
## ۶. ۳ سناریوی خرید پکیج طلایی
|
||
|
||
| سناریو | فلو | وضعیت |
|
||
|--------|------|--------|
|
||
| **وام دایا** | درخواست وام → تأیید خودکار → شارژ ۳ کیفپول (۱۶۸M) | ✅ پیادهشده |
|
||
| **درگاه مستقیم** | IPG (ZarinPal) → callback → شارژ | ✅ پیادهشده |
|
||
| **پرداخت دستی** | کارتبهکارت → آپلود رسید → تأیید ادمین → شارژ | ⚠️ طراحیشده |
|
||
|
||
---
|
||
|
||
## ۷. یکپارچهسازی وام دایا
|
||
|
||
```
|
||
Hangfire Worker (هر ۱۵ دقیقه)
|
||
│
|
||
▼
|
||
بررسی درخواستهای pending
|
||
│
|
||
▼
|
||
ارسال به API دایا (Mock/Real switchable)
|
||
│
|
||
▼
|
||
دریافت نتیجه → شارژ ۳ کیفپول
|
||
│
|
||
├─→ Balance = 56M
|
||
├─→ NetworkBalance = 56M
|
||
└─→ DiscountBalance = 56M (مجموع: 168M)
|
||
|
||
Polly Retry: 3 attempts, Exponential backoff
|
||
```
|
||
|
||
---
|
||
|
||
## ۸. Chatika AI — اولین فیچر باشگاه
|
||
|
||
| آیتم | جزئیات |
|
||
|------|---------|
|
||
| **نوع** | Hangfire recurring job |
|
||
| **فرکانس** | هر ۵ دقیقه |
|
||
| **Retry** | Polly — ۳ تلاش، backoff نمایی |
|
||
| **فعالسازی** | فقط برای اعضای فعال باشگاه |
|
||
| **وضعیت** | ✅ Production ready |
|