# 👤 سفر کاربر، ثبت‌نام و چرخه عضویت

> **منابع ادغام‌شده:** `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`  
> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet cycle)

---

## ۱. فلوی کامل چرخه کاربر

```mermaid
flowchart TD
    A["ورود به سایت"] --> B["ثبت‌نام — موبایل + OTP"]
    B --> C["تکمیل پروفایل"]
    C --> D{"مسیر؟"}

    D -->|عادی| E["🛒 خرید از فروشگاه\nمشاهده بلاگ\nاستفاده از خدمات"]

    D -->|باشگاه| F["🏆 خرید پکیج طلایی 56M"]
    F --> G["امضای قرارداد OTP"]
    G --> H["فعالسازی 25.2M"]
    H --> I["عضویت درخت باینری"]
    I --> J["دسترسی فروشگاه اعتباری\nفیچرهای باشگاه\nکمیسیون هفتگی"]
    J --> K{"Balance = 0?"}
    K -->|بله| L["🪄 کیف‌پول جادویی\nشارژ ×2.5 از درگاه"]
    L --> M["خروج از Magic\nخرید مجدد پکیج"]
    M --> F
```

---

## ۲. ثبت‌نام و احراز هویت

### ۲.۱ فلوی ثبت‌نام

```mermaid
flowchart TD
    A["صفحه ثبت‌نام"] --> B["ورود شماره موبایل"]
    B --> C["ارسال OTP\nKavenegar SMS API"]
    C --> D["تأیید کد OTP"]
    D -->|کاربر جدید| E["ساخت User\n+ JWT Token"]
    D -->|کاربر موجود| F["ورود\n+ JWT Token"]
```

**JWT Claims:** `UserId`, `PhoneNumber`, `IsClubMember`, `Roles[]`, `ReferralCode`

### ۲.۲ اصلاحات ثبت‌نام

| مشکل | راه‌حل | وضعیت |
|------|---------|--------|
| OTP تکراری | Cooldown: ۶۰ ثانیه بین درخواست‌ها | ✅ |
| شماره نامعتبر | Regex validation ایران `^09\d{9}$` | ✅ |
| حمله brute-force | MaxAttempts: ۵ تلاش برای تأیید کد | ✅ |
| انقضای کد | TTL: ۲ دقیقه | ✅ |
| طول کد | ۶ رقم | ✅ |
| قالب SMS | Kavenegar template: `Afrino` | ✅ |

---

## ۳. جداسازی Admin/Customer

### ۳.۱ مشکل قبلی

```mermaid
flowchart LR
    subgraph BEFORE["قبل — مشکل"]
        A1["Admin + Customer"] --> A2["یک DbContext\nیک Identity\nتداخل Claims"]
    end

    subgraph AFTER["بعد — اصلاح‌شده ✅"]
        B1["ICurrentUserService"] --> B2["جداسازی Policy\nAdmin → BackOffice\nCustomer → FrontOffice"]
    end
```

### ۳.۲ 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>()
```

---

## ۴. قرارداد عضویت باشگاه

### ۴.۱ فلوی امضای قرارداد

```mermaid
flowchart TD
    A["خرید پکیج طلایی\nRedirect به صفحه قرارداد"] --> B["نمایش Modal\nغیرقابل‌بسته‌شدن"]
    B --> C["ReadContract RPC\nنمایش متن قرارداد"]
    C --> D["اسکرول تا انتها"]
    D --> E["فعال شدن دکمه\nارسال کد تأیید"]
    E --> F["RequestContractOtp\nارسال SMS"]
    F --> G["ورود کد\nVerifyContractOtp"]
    G -->|معتبر| H["✅ AcceptContract\nفعالسازی عضویت"]
    G -->|نامعتبر| I["❌ پیام خطا\nحداکثر ۵ تلاش"]
```

### ۴.۲ ذخیره‌سازی قرارداد

```csharp
// از کد: UserContract : BaseAuditableEntity
public class UserContract {
    public long UserId { get; set; }
    public virtual User User { get; set; }
    public long ContractId { get; set; }         // FK → Contract
    public virtual Contract Contract { get; set; }
    public string SignGuid { get; set; }          // GUID یکتای امضا
    public string SignedPdfFile { get; set; }     // فایل PDF امضاشده
    // فیلدهای BaseAuditableEntity: CreatedAt, ModifiedAt, ...
}
```

---

## ۵. فیچرهای باشگاه (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)

```mermaid
flowchart TD
    A["هر عضو باشگاه\nیک ReferralCode یکتا"] --> B["لینک:\nhttps://foursat.ir/register?ref=CODE"]
    B --> C["ثبت‌نام با لینک\nذخیره ReferrerId"]
    C --> D["خرید پکیج\nزیرمجموعه Referrer در درخت"]
    D --> E["Referrer\nدریافت bonus"]
```

---

## ۸. خلاصه وضعیت

| ماژول | وضعیت | درصد |
|-------|--------|------|
| ثبت‌نام OTP | ✅ | 100% |
| جداسازی Admin/Customer | ✅ | 100% |
| ICurrentUserService | ✅ | 100% |
| قرارداد باشگاه + OTP | ✅ | 100% |
| فیچرهای باشگاه | ✅ | 100% |
| Referral System | ✅ | 100% |
| ناوبری Auth-Aware | ✅ | 100% |
| مشاهده درخت شبکه (FrontOffice) | ✅ | 100% |