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,236 @@
+# 👤 سفر کاربر، ثبت‌نام و چرخه عضویت
+
+> **منابع ادغام‌شده:** `club-membership-contract-system.md`, `REGISTRATION-FLOW-FIXES.md`, `chatika-integration.md`, `club-feature-management-services.md`, `ADMIN-CUSTOMER-SEPARATION-FIX.md`, `ICURRENTUSERSERVICE-IMPLEMENTATION.md`  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴
+
+---
+
+## ۱. فلوی کامل چرخه کاربر
+
+```
+ورود به سایت
+    │
+    ▼
+ثبت‌نام (موبایل + OTP)
+    │
+    ▼
+تکمیل پروفایل
+    │
+    ▼
+┌─────────────────────┬────────────────────────┐
+│ مسیر عادی           │ مسیر باشگاه            │
+├─────────────────────┼────────────────────────┤
+│ خرید از فروشگاه     │ خرید پکیج طلایی (56M)  │
+│ مشاهده بلاگ         │ امضای قرارداد (OTP)     │
+│ استفاده از خدمات    │ فعالسازی (25M)          │
+│                     │ عضویت در درخت باینری    │
+│                     │ دسترسی فروشگاه تخفیفی  │
+│                     │ دسترسی فیچرهای باشگاه  │
+│                     │ کسب کمیسیون هفتگی      │
+└─────────────────────┴────────────────────────┘
+```
+
+---
+
+## ۲. ثبت‌نام و احراز هویت
+
+### ۲.۱ فلوی ثبت‌نام
+
+```
+صفحه ثبت‌نام
+    │
+    ▼
+ورود شماره موبایل
+    │
+    ▼
+ارسال OTP (Kavenegar SMS API)
+    │
+    ▼
+تأیید کد OTP
+    │
+    ├─→ کاربر جدید: ساخت User + JWT Token
+    └─→ کاربر موجود: ورود + JWT Token
+
+JWT Claims:
+    • UserId
+    • PhoneNumber
+    • IsClubMember (bool)
+    • Roles[] (Admin, Customer)
+    • ReferralCode
+```
+
+### ۲.۲ اصلاحات ثبت‌نام
+
+| مشکل | راه‌حل | وضعیت |
+|------|---------|--------|
+| OTP تکراری | Rate limiting: ۱ درخواست هر ۶۰ ثانیه | ✅ |
+| شماره نامعتبر | Regex validation ایران `^09\d{9}$` | ✅ |
+| حمله brute-force | قفل حساب بعد از ۵ تلاش ناموفق | ✅ |
+| Race condition ثبت‌نام | Unique constraint + transaction | ✅ |
+
+---
+
+## ۳. جداسازی Admin/Customer
+
+### ۳.۱ مشکل قبلی
+
+```
+قبل:
+    Admin و Customer هر دو از یک DbContext و Identity استفاده می‌کردند
+    یک ادمین می‌توانست به صورت Customer هم ظاهر شود ← تداخل Claims
+
+بعد (اصلاح‌شده):
+    ✅ ICurrentUserService → تشخیص دقیق نقش فعلی
+    ✅ جداسازی Authorization Policy
+    ✅ Admin claims فقط در BackOffice
+    ✅ Customer claims فقط در FrontOffice
+```
+
+### ۳.۲ ICurrentUserService
+
+```csharp
+public interface ICurrentUserService {
+    Guid UserId { get; }
+    string PhoneNumber { get; }
+    bool IsClubMember { get; }
+    bool IsAdmin { get; }
+    string[] Roles { get; }
+    Guid? ReferrerId { get; }
+}
+
+// پیاده‌سازی: از HttpContext.User.Claims خوانده می‌شود
+// ثبت: services.AddScoped<ICurrentUserService, CurrentUserService>()
+```
+
+---
+
+## ۴. قرارداد عضویت باشگاه
+
+### ۴.۱ فلوی امضای قرارداد
+
+```
+خرید پکیج طلایی → Redirect به صفحه قرارداد
+    │
+    ▼
+نمایش Modal غیرقابل‌بسته‌شدن
+    │
+    ▼
+ReadContract RPC → نمایش متن قرارداد (Markdown/HTML)
+    │
+    ▼
+کاربر باید تا انتهای متن اسکرول کند
+    │
+    ▼
+فعال شدن دکمه "ارسال کد تأیید"
+    │
+    ▼
+RequestContractOtp → ارسال SMS
+    │
+    ▼
+ورود کد ← VerifyContractOtp
+    │
+    ├─→ معتبر: AcceptContract → فعالسازی عضویت
+    └─→ نامعتبر: پیام خطا (حداکثر ۵ تلاش)
+```
+
+### ۴.۲ ذخیره‌سازی قرارداد
+
+```csharp
+public class UserContract {
+    public Guid Id { get; set; }
+    public Guid UserId { get; set; }
+    public string ContractVersion { get; set; }    // e.g., "v1.2"
+    public string ContractText { get; set; }        // snapshot متن
+    public DateTime AcceptedAt { get; set; }
+    public string OtpVerificationId { get; set; }
+    public string IpAddress { get; set; }
+    public string UserAgent { get; set; }
+}
+```
+
+---
+
+## ۵. فیچرهای باشگاه (Club Features)
+
+### ۵.۱ سرویس مدیریت
+
+```csharp
+public interface IClubFeatureService {
+    Task<List<ClubFeature>> GetUserFeaturesAsync(Guid userId);
+    Task ActivateFeatureAsync(Guid userId, string featureCode);
+    Task DeactivateFeatureAsync(Guid userId, string featureCode);
+    Task<bool> HasFeatureAsync(Guid userId, string featureCode);
+}
+```
+
+### ۵.۲ فیچرهای موجود
+
+| کد فیچر | نام | توضیح | وضعیت |
+|----------|------|--------|--------|
+| `DISCOUNT_STORE` | فروشگاه تخفیفی | دسترسی به فروشگاه ۳۰% تخفیف | ✅ فعال |
+| `CHATIKA_AI` | چاتیکا | مشاوره هوش مصنوعی | ✅ فعال |
+| `COMMISSION` | کمیسیون | دریافت کمیسیون هفتگی | ✅ فعال |
+| `NETWORK_VIEW` | نمای شبکه | مشاهده درخت باینری | ✅ فعال |
+| `DAYA_LOAN` | وام دایا | درخواست وام | ⚠️ بلاک‌شده |
+
+### ۵.۳ UserClubFeature Entity
+
+```csharp
+public class UserClubFeature {
+    public Guid Id { get; set; }
+    public Guid UserId { get; set; }
+    public string FeatureCode { get; set; }
+    public bool IsActive { get; set; }
+    public DateTime ActivatedAt { get; set; }
+    public DateTime? DeactivatedAt { get; set; }
+}
+```
+
+---
+
+## ۶. ناوبری Auth-Aware
+
+```csharp
+// صفحه اصلی — مسیردهی هوشمند
+if (IsAuthenticated && IsClubMember)
+    → نمایش داشبورد باشگاه + فروشگاه تخفیفی
+else if (IsAuthenticated)
+    → نمایش فروشگاه عادی + پروفایل
+else
+    → نمایش Landing Page + ثبت‌نام
+```
+
+---
+
+## ۷. کدهای معرف (Referral)
+
+```
+هر عضو باشگاه → یک ReferralCode یکتا
+لینک: https://foursat.ir/register?ref={ReferralCode}
+
+ثبت‌نام با لینک:
+    │
+    ▼
+    ذخیره ReferrerId در پروفایل کاربر جدید
+    │
+    ▼
+    هنگام خرید پکیج → زیرمجموعه Referrer در درخت باینری
+    │
+    ▼
+    Referrer → دریافت bonus (طبق شرایط باشگاه)
+```
+
+---
+
+## ۸. خلاصه وضعیت
+
+| ماژول | وضعیت | درصد |
+|-------|--------|------|
+| ثبت‌نام OTP | ✅ | 100% |
+| جداسازی Admin/Customer | ✅ | 100% |
+| ICurrentUserService | ✅ | 100% |
+| قرارداد باشگاه + OTP | ✅ | 100% |
+| فیچرهای باشگاه | ✅ | 100% |
+| Referral System | ✅ | 100% |
+| ناوبری Auth-Aware | ✅ | 100% |
+| مشاهده درخت شبکه (FrontOffice) | ✅ | 100% |