docs/business/BUSINESS-04-USER-MEMBERSHIP.md

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

منابع ادغام‌شده: 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)

---

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

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

---

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

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

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

۳.۱ مشکل قبلی

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

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>()

---

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

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

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حداکثر ۵ تلاش"]

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

// از کد: 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)

۵.۱ سرویس مدیریت

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

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

// صفحه اصلی — مسیردهی هوشمند
if (IsAuthenticated && IsClubMember)
    → نمایش داشبورد باشگاه + فروشگاه اعتباری
else if (IsAuthenticated)
    → نمایش فروشگاه عادی + پروفایل
else
    → نمایش Landing Page + ثبت‌نام

---

۷. کدهای معرف (Referral)

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%