docs/overview/OVERVIEW-01-FLOWCHARTS.md

# 📊 فلوچارت‌ها و دیاگرام‌های کلان

> **دید بالا (Big Picture): فلوی کاربر، مالی، داده و کیف‌پول جادویی**  
> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet + VAT 10%)

---

## ۱. فلوی کلان کاربر (User Journey)

```mermaid
flowchart TD
    A["🌐 ورود به سایت"] --> B{"آیا ثبت‌نام کرده؟"}
    B -->|خیر| C["Landing Page"]
    C --> D["ثبت‌نام\nموبایل + OTP"]
    D --> E["پروفایل"]
    E --> F

    B -->|بله| G["Login + JWT"]
    G --> H{"عضو باشگاه؟"}
    H -->|خیر| F["🛒 Regular Store\nخرید عادی — پرداخت از کیف‌پول"]
    H -->|بله| I["🏆 Club Member Dashboard"]

    I --> J["فروشگاه اعتباری\nper-product MaxDiscount%"]
    I --> K["درخت شبکه\nباینری"]
    I --> L["کمیسیون\nهفتگی"]
    I --> M["Chatika AI"]
    I --> N["🪄 کیف‌پول جادویی\nشارژ ×2.5"]
```

---

## ۱.۱ فلوی کیف‌پول جادویی (Magic Wallet) ✅

```mermaid
flowchart TD
    A["خرید پکیج 56M\nBalance=56M"] --> B["خرید از فروشگاه\nBalance کم می‌شود"]
    B --> C{"Balance = 0 +\nعضو فعال باشگاه?"}
    C -->|خیر| B
    C -->|بله| D["🪄 Magic Mode\nWalletMode = 1"]
    D --> E["شارژ از درگاه\nواریز × 2.5"]
    E --> F{"Balance=0 AND\nDeposited≥100M?"}
    F -->|خیر| G["خرید یا شارژ ادامه"]
    G --> F
    F -->|بله| H["خروج از Magic\nخرید مجدد پکیج"]
```

---

## ۲. فلوی مالی (Financial Flow)

```mermaid
flowchart TD
    subgraph INPUT["═══ ورودی پول ═══"]
        Z1["ZarinPal IPG"]
        Z2["Daya Loan"]
        Z3["Manual Pay"]
    end

    Z1 --> PYMS["PYMS Service"]
    Z2 --> PYMS
    Z3 --> PYMS
    PYMS --> TX[("DB Transaction")]

    TX --> W1 & W2 & W3

    subgraph WALLETS["═══ توزیع به کیف‌پول‌ها ═══"]
        W1["💰 Balance — نقدی\n• IPG: +56M\n• Daya: +56M\n• فعالسازی: −25.2M\n• خرید فروشگاه"]
        W2["🌟 NetworkBalance — طلایی\n• شارژ نمی‌شود\n• فقط محاسبه کمیسیون\n• سقف 300/هفته"]
        W3["🏷️ DiscountBalance — اعتباری\n• IPG: +112M\n• Daya: +112M\n• per-product MaxDiscount%"]
    end

    W1 & W2 --> POOL

    subgraph POOL["═══ Weekly Commission Pool ═══"]
        P1["هر فعالسازی → 25.2M واریز به Pool"]
        P2["sp_CalculateWeeklyBalances"]
        P3["sp_CalculateWeeklyCommissionPool"]
        P4["UserShare = UserBalance / TotalBalance"]
        P5["Cap: MAX 300 per leg per week"]
        P1 --> P2 --> P3 --> P4 --> P5
    end
```

---

## ۳. فلوی داده (Data Flow)

```mermaid
flowchart TD
    CLIENT["🌐 Browser / Client"] -->|HTTPS| NGINX["nginx / K8s Ingress"]

    NGINX -->|"/"| FO["FrontOffice :5003\nBlazor Server"]
    NGINX -->|"/admin"| BO["BackOffice :5002\nBlazor WASM"]
    NGINX -->|"/hangfire"| CMS

    FO -->|gRPC| CMS["CMS Microservice :5001"]
    BO -->|gRPC| CMS

    CMS --> MEDIATR["MediatR\nCommands / Queries → Handlers"]
    CMS --> HF["Hangfire\n• DayaLoan — */20 min\n• Commission — Sunday 00:05\n• Chatika — */5 min"]
    CMS --> EXT["External Services\n• ZarinPal API\n• Kavenegar API\n• DayaLoan API\n• Chatika API"]

    MEDIATR --> EF["EF Core 9"]
    HF --> EF
    EF --> DB[("SQL Server 2022\nSchema: CMS\n~15 tables + 3 SPs")]
```

---

## ۴. درخت باینری شبکه (Network Tree)

```mermaid
graph TD
    ROOT["🔵 Root — Admin"]
    ROOT --- A["👤 User A\nL=120 | R=80"]
    ROOT --- B["👤 User B\nL=0 | R=150"]

    A --- C["✅ User C\nActive"]
    A --- D["✅ User D\nActive"]
    B --- E["⏳ User E\nPending"]
    B --- F["✅ User F\nActive"]

    style ROOT fill:#1976D2,color:#fff
    style C fill:#4CAF50,color:#fff
    style D fill:#4CAF50,color:#fff
    style E fill:#FF9800,color:#fff
    style F fill:#4CAF50,color:#fff
```

> **راهنما:**
> - `L` / `R` = فروش پای چپ / راست این هفته
> - **Active** = فعال (قرارداد امضا شده) — **Pending** = در انتظار فعالسازی
> - شبکه روی entity `User` مدل شده (`NetworkParentId`, `LegPosition`)
> - محاسبه کمیسیون تا عمق ۱۵ سطح — درخت بدون محدودیت عمق

---

## ۵. فلوی خرید — Regular vs Discount Store

### ۵.۱ Regular Store

```mermaid
flowchart TD
    A1["مشاهده محصولات"] --> B1["Lazy Load — 12 per page"]
    B1 --> C1["افزودن به سبد"]
    C1 --> D1["بررسی موجودی"]
    D1 --> E1["Checkout Summary\nانتخاب آدرس"]
    E1 --> F1{"Balance کافی؟"}
    F1 -->|بله| G1["کسر از Balance کیف‌پول\n+ VAT"]
    G1 --> H1["ثبت سفارش"]
    H1 --> I1["کسر موجودی"]
    F1 -->|خیر| J1["❌ خطا: موجودی کیف‌پول کافی نیست"]
```

### ۵.۲ Discount Store

```mermaid
flowchart TD
    A2["مشاهده محصولات\nفقط اعضای باشگاه"] --> B2["Lazy Load — 12 per page"]
    B2 --> C2["افزودن به سبد"]
    C2 --> D2["بررسی موجودی + DiscountBalance"]
    D2 --> E2["محاسبه سهم تخفیف\nMaxDiscount% هر محصول"]
    E2 --> F2["محاسبه باقیمانده\ngatewayAmount = total - discountUsed"]
    F2 --> G2{"gatewayAmount > 0?"}
    G2 -->|بله| H2["کسر DiscountBalance\n+ ZarinPal IPG برای باقیمانده + 10% VAT"]
    H2 --> I2["Redirect → ZarinPal\nCallback → ثبت سفارش"]
    G2 -->|خیر| J2["فقط کسر از DiscountBalance\nبدون درگاه"]
    J2 --> K2["ثبت سفارش"]
    I2 --> L2["کسر موجودی + SMS تأیید"]
    K2 --> L2
```

---

## ۶. معماری Deployment

```mermaid
flowchart TD
    subgraph SERVER["🖥️ Production Server — 45.149.79.127"]
        NGINX["nginx\n:80 / :443"]
        subgraph K8S["☸ Kubernetes Cluster"]
            CMS["CMS ×2\n:5001 gRPC"]
            FO["FrontOffice ×2\n:5003 Blazor Server"]
            BO["BackOffice ×1\n:5002 Static"]
            DB[("SQL Server\n:1433")]
            NEXUS["Nexus\n:8081"]
            HF["Hangfire\ninside CMS"]
        end
    end

    NGINX --> CMS
    NGINX --> FO
    NGINX --> BO
    CMS --> DB
    CMS --> HF

    style SERVER fill:#f5f5f5,stroke:#333
    style K8S fill:#e3f2fd,stroke:#1976D2
```

---

## ۷. Entity Relationship (ساده‌شده)

```mermaid
erDiagram
    User ||--o{ ClubMembership : has
    User ||--o| UserWallet : has
    User ||--o{ UserContract : signs
    User ||--o{ UserOrder : places
    User ||--o{ ChatMessage : sends
    User }o--o| User : "NetworkParentId"

    UserOrder ||--|{ OrderItem : contains
    OrderItem }o--|| Product : references
    UserOrder ||--o{ Transaction : has

    Product ||--o| Inventory : has
    Product }o--|| Category : belongs_to
    Product ||--o{ ProductImage : has

    UserWallet ||--o{ UserWalletChangeLog : logs

    ClubMembership ||--o{ ClubMembershipCycle : has

    BlogPost }o--|| Category : belongs_to

    UserWallet {
        long Balance
        long NetworkBalance
        long DiscountBalance
        int WalletMode
        long MagicTotalDeposited
        long MagicTotalCredited
    }
    ClubMembershipCycle {
        int CycleNumber
        datetime PackagePurchasedAt
        bool IsCurrentCycle
    }
    User {
        Guid NetworkParentId
        int LegPosition
    }
    UserContract {
        Guid SignGuid
        string SignedPdfFile
    }
```