masoodafar-web
1b04ba5326
Converted 40+ ASCII art diagrams across 12 files to Mermaid: - flowchart TD/LR for process flows and architecture - erDiagram for entity relationships - graph TD for tree structures (binary tree, categories) - gantt for roadmap sprints Files: BUSINESS-01 to 05, TECH-01/03/04/05, OVERVIEW-01/02/05 Directory tree structures kept as plain code blocks (Mermaid N/A)
161 lines
6.4 KiB
Markdown
161 lines
6.4 KiB
Markdown
# 🏆 سیستم باشگاه، کمیسیون و درخت شبکهای
|
||
|
||
> **منابع ادغامشده:** `club-commission-system-complete.md`, `balance-calculation-rules.md`, `club-membership-contract-system.md`
|
||
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
|
||
|
||
---
|
||
|
||
## ۱. مفاهیم کلیدی
|
||
|
||
| مفهوم | توضیح |
|
||
|-------|--------|
|
||
| **عضویت باشگاه** | خرید پکیج طلایی (۵۶M) → فعالسازی (۲۵.۲M) → عضو فعال باشگاه |
|
||
| **درخت باینری** | هر کاربر حداکثر ۲ فرزند مستقیم (چپ/راست) — بدون محدودیت عمق |
|
||
| **کمیسیون هفتگی** | محاسبه بر اساس تعادل چپ/راست — یکشنبه ۰۰:۰۵ (Hangfire cron) |
|
||
| **۳ کیف پول** | `Balance` (نقدی) + `NetworkBalance` (طلایی/کمیسیون) + `DiscountBalance` (تخفیفی) |
|
||
|
||
---
|
||
|
||
## ۲. ساختار درخت باینری
|
||
|
||
```mermaid
|
||
graph TD
|
||
ROOT["Root"] --- L["Left"]
|
||
ROOT --- R["Right"]
|
||
L --- L1["L1"] & L2["L2"]
|
||
R --- R1["R1"] & R2["R2"]
|
||
L1 --- L1a["..."] & L1b["..."]
|
||
L2 --- L2a["..."] & L2b["..."]
|
||
R1 --- R1a["..."] & R1b["..."]
|
||
R2 --- R2a["..."] & R2b["..."]
|
||
```
|
||
|
||
> ← بدون محدودیت عمق
|
||
|
||
**قوانین:**
|
||
- هر نود حداکثر ۲ فرزند (Binary) — `MaxDirectChildrenPerLeg = 1`
|
||
- جایگذاری: `LegPosition` ∈ {Left=0, Right=1} (enum `NetworkLeg`)
|
||
- مدل شبکه مستقیم روی entity `User` — فیلدهای `NetworkParentId`, `LegPosition`, `NetworkChildren`
|
||
- محاسبه کمیسیون تا عمق ۱۵ سطح (`CommissionMaxNetworkLevel = 15`) — اما درخت بدون محدودیت رشد میکند
|
||
|
||
---
|
||
|
||
## ۳. فلوی عضویت و فعالسازی
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["خرید پکیج طلایی — 56M"] --> B["نمایش مودال قرارداد\nغیرقابلبستهشدن"]
|
||
B --> C["مشاهده متن قرارداد\nReadContract RPC"]
|
||
C --> D["درخواست OTP\nRequestContractOtp — Kavenegar"]
|
||
D --> E["وارد کردن کد\nVerifyContractOtp"]
|
||
E --> F["امضای قرارداد\nAcceptContract"]
|
||
|
||
F --> G["شارژ ۲ کیفپول\nBalance += 56M\nDiscountBalance += 112M"]
|
||
F --> H["کسر فعالسازی\n−25.2M از Balance"]
|
||
F --> I["واریز 25.2M\nبه Pool هفتگی"]
|
||
F --> J["قرارگیری در\nدرخت باینری"]
|
||
F --> K["رفرش JWT Token\nclaims جدید"]
|
||
```
|
||
|
||
> ⚠️ در خرید با وام دایا: Balance += 56M, DiscountBalance += 112M (DayaLoanAmount × 2)
|
||
> NetworkBalance شارژ نمیشود — فقط برای کمیسیون
|
||
|
||
---
|
||
|
||
## ۴. الگوریتم محاسبه کمیسیون هفتگی
|
||
|
||
### ۴.۱ فرمول ۴ مرحلهای
|
||
|
||
```
|
||
مرحله ۱: جمع فروش هر پا
|
||
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 هفتگی و توزیع
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A["هر فعالسازی عضو\n25.2M واریز"] --> B["Pool هفتگی"]
|
||
B --> C["sp_CalculateWeeklyBalances"]
|
||
C --> D["sp_CalculateWeeklyCommissionPool"]
|
||
D --> E["توزیع بر اساس\nUserBalance / TotalBalance"]
|
||
```
|
||
|
||
> فرمت هفته: `YYYY-Www` (شمسی، شنبهپایه)
|
||
|
||
---
|
||
|
||
## ۵. تنظیمات سیستمی (SystemConstants)
|
||
|
||
| ثابت (SystemConstants) | مقدار | توضیح |
|
||
|------|-------|--------|
|
||
| `ClubActivationFee` | 25,200,000 | هزینه فعالسازی (ریال) |
|
||
| `ClubMembershipGiftValue` | 25,200,000 | واریز به Pool |
|
||
| `BasePackageAmount` | 56,000,000 | قیمت پکیج طلایی (ریال) |
|
||
| `DayaLoanAmount` | 56,000,000 | مبلغ وام دایا (ریال) |
|
||
| `CommissionMaxWeeklyBalancesPerLeg` | 300 | سقف هفتگی هر پا |
|
||
| `CommissionMaxNetworkLevel` | 15 | عمق محاسبه کمیسیون (نه محدودیت درخت) |
|
||
| `MaxDirectChildrenPerLeg` | 1 | حداکثر فرزند مستقیم هر پا |
|
||
| `MinimumWithdrawAmount` | 1,000,000 | حداقل مبلغ برداشت (ریال) |
|
||
| `ShopVAT` | 0.1 (10%) | مالیات ارزش افزوده |
|
||
| `CommissionCalculationMethod` | "SP" | روش محاسبه = Stored Procedure |
|
||
|
||
---
|
||
|
||
## ۶. ۳ سناریوی خرید پکیج طلایی
|
||
|
||
| سناریو | فلو | وضعیت |
|
||
|--------|------|--------|
|
||
| **وام دایا** | درخواست وام → تأیید → Balance=56M + Discount=112M (مجموع ۱۶۸M) | ✅ پیادهشده |
|
||
| **درگاه مستقیم** | IPG → callback → Balance=56M + Discount=112M (مجموع ۱۶۸M) | ✅ پیادهشده |
|
||
| **پرداخت دستی** | کارتبهکارت → آپلود رسید → تأیید ادمین → شارژ | ⚠️ طراحیشده |
|
||
|
||
---
|
||
|
||
## ۷. یکپارچهسازی وام دایا
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["Hangfire Worker\nهر ۲۰ دقیقه — */20 * * * *"] --> B["بررسی درخواستهای pending"]
|
||
B --> C["ارسال به API دایا\nMock/Real switchable"]
|
||
C --> D["دریافت نتیجه"]
|
||
D --> E["Balance += 56M"]
|
||
D --> F["DiscountBalance += 112M\nDayaLoanAmount × 2"]
|
||
```
|
||
|
||
> مجموع شارژ: 168M — Hangfire retry: `[AutomaticRetry(Attempts = 3)]`
|
||
|
||
---
|
||
|
||
## ۸. Chatika AI — اولین فیچر باشگاه
|
||
|
||
| آیتم | جزئیات |
|
||
|------|---------|
|
||
| **نوع** | Hangfire recurring job |
|
||
| **فرکانس** | هر ۵ دقیقه |
|
||
| **Retry** | Polly — ۳ تلاش، backoff نمایی |
|
||
| **فعالسازی** | فقط برای اعضای فعال باشگاه |
|
||
| **وضعیت** | ✅ Production ready |
|