docs: consolidate 53 files into 15 structured files in 3 folders

- 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
2026-02-18 22:29:37 +03:30
parent d7c32dab2a
commit efff5e9cd5
71 changed files with 3632 additions and 32267 deletions
@@ -0,0 +1,167 @@
+# 🏆 سیستم باشگاه، کمیسیون و درخت شبکه‌ای
+
+> **منابع ادغام‌شده:** `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 |