# 🌐 FrontOffice - پرتال مشتری

> **FrontOffice**: رابط کاربری Blazor Server برای مشتریان نهایی سیستم FourSat
> 
> **آخرین بروزرسانی**: ۶ دی ۱۴۰۴ (26 دسامبر 2025)

---

## 🆕 تغییرات اخیر (۶ دی ۱۴۰۴)

### ✅ نمایش کد معرف در درخت شبکه
- **کد معرف**: نمایش ReferralCode برای کاربران فعال باشگاه
- **دکمه کپی**: امکان کپی کد معرف با یک کلیک
- **استایل**: طراحی زیبا با رنگ سبز برای کد معرف
- **فایل‌های تغییر یافته**:
  - `Utilities/NetworkMembershipDtos.cs` - فیلد ReferralCode
  - `Utilities/NetworkMembershipService.cs` - Mapping
  - `wwwroot/js/org-chart.js` - نمایش در نود
  - `wwwroot/css/org-chart.css` - استایل‌ها

---

## 🆕 تغییرات قبلی (۲۸ آذر ۱۴۰۴)

### ✅ نمودار درختی شبکه با d3-org-chart
- **کتابخانه**: d3-org-chart v3 + d3.js v7 + d3-flextree
- **OrganizationChart.razor**: بازنویسی کامل با JS Interop
- **امکانات**:
  - نمایش درختی باینری شبکه
  - دکمه‌های: باز کردن همه، بستن همه، مرکز، نمایش کامل، بروزرسانی
  - انتخاب عمق درخت (2-10 سطح)
  - کلیک روی نود برای دیدن زیرمجموعه‌ها
  - دکمه‌های بازگشت و "درخت من"
  - طراحی ریسپانسیو با MudBlazor

### ✅ API جدید: GetSubordinateTree
- **Proto**: `GetSubordinateTreeRequest` با `target_user_id`
- **BFF Handler**: `GetSubordinateTreeQueryHandler`
- **Frontend Service**: `GetSubordinateTreeAsync(targetUserId, maxDepth)`
- **امنیت**: Authentication با JWT (بدون بار اضافی چک زیرمجموعه)

### ✅ فایل‌های جدید/آپدیت شده:
- `wwwroot/js/org-chart.js` - JS Interop برای d3-org-chart
- `wwwroot/css/org-chart.css` - استایل‌های سفارشی نمودار
- `Pages/Profile/Components/OrganizationChart.razor` - کامپوننت نمودار
- `Pages/Profile/Components/OrganizationChart.razor.cs` - لاجیک کامپوننت
- `Utilities/NetworkMembershipService.cs` - متد جدید GetSubordinateTreeAsync

---

## 📊 وضعیت پروژه

| بخش | وضعیت | درصد تکمیل | فایل‌ها |
|-----|-------|------------|---------|
| **UI Pages** | ✅ Build موفق | 85% | 24 صفحه |
| **BFF Handlers** | ✅ اصلاح شده | 80% | 14 Handler |
| **Protobuf Packages** | ✅ کامل | 90% | 5 Package |
| **Services** | ✅ اتصال واقعی | 80% | 8 Service |
| **gRPC Connection** | ✅ فعال | 90% | - |

**🎉 آخرین موفقیت**: نمودار درختی d3-org-chart با کلیک روی نودها (۲۸ آذر)

---

## 🗂️ ساختار پروژه

```
FrontOffice/
├── FrontOffice.sln
└── src/
    ├── FrontOffice.Main/          # Blazor Server UI
    │   ├── Pages/
    │   │   ├── Profile/           # صفحات پروفایل (6 صفحه)
    │   │   │   ├── Index.razor
    │   │   │   ├── Tree.razor     # ⚠️ نیاز به بروزرسانی
    │   │   │   ├── Wallet.razor
    │   │   │   └── ...
    │   │   ├── Store/             # فروشگاه (7 صفحه)
    │   │   ├── Club/              # ✅ باشگاه مشتریان (2 صفحه + 1 component)
    │   │   │   ├── MembershipPage.razor
    │   │   │   ├── FeaturesPage.razor
    │   │   │   └── Components/ActivationSection.razor
    │   │   ├── Network/           # ✅ شبکه (2 صفحه)
    │   │   │   ├── NetworkStatisticsPage.razor
    │   │   │   └── (Tree در Profile است)
    │   │   └── Commission/        # ✅ کمیسیون (3 صفحه)
    │   │       ├── CommissionDashboardPage.razor
    │   │       ├── CommissionHistoryPage.razor
    │   │       └── WeeklyBalancePage.razor
    │   └── Utilities/             # Services & DTOs
    │       ├── ClubMembershipService.cs        # ⚠️ Mock Data
    │       ├── NetworkMembershipService.cs     # ⚠️ Mock Data
    │       ├── CommissionService.cs            # ⚠️ Mock Data
    │       └── WalletService.cs                # ⚠️ 4 متد کامنت شده
    └── FrontOffice.BFF/           # Backend for Frontend
        ├── FrontOffice.BFF.sln
        └── src/
            ├── FrontOffice.BFF.Application/
            │   ├── ClubMembershipCQ/           # ⚠️ نیاز به اصلاح
            │   │   ├── Queries/GetMyClubMembership/
            │   │   └── Commands/ActivateMyClubMembership/
            │   ├── NetworkMembershipCQ/        # ⚠️ نیاز به اصلاح
            │   │   ├── Queries/GetMyNetworkTree/
            │   │   └── Queries/GetMyNetworkStatistics/
            │   ├── CommissionCQ/               # ⚠️ نیاز به اصلاح
            │   │   ├── Queries/GetMyCommissionPayouts/
            │   │   └── Queries/GetMyWeeklyBalances/
            │   └── UserWalletCQ/               # ⚠️ ناقص
            │       └── Queries/GetUserWallet/
            └── Protobufs/
                ├── FrontOffice.BFF.Package.Protobuf/
                ├── FrontOffice.BFF.UserWallet.Protobuf/
                └── (سایر Protobuf ها...)
```

---

## 🚀 صفحات موجود (24 صفحه)

### 🏪 Store (7 صفحه - از قبل موجود)
- ✅ ProductListPage
- ✅ ProductDetailPage
- ✅ CartPage
- ✅ CheckoutPage
- ✅ OrderHistoryPage
- ✅ OrderDetailPage
- ✅ (و سایر صفحات فروشگاه)

### 👤 Profile (6 صفحه)
- ✅ Index.razor - داشبورد پروفایل
- ⚠️ Tree.razor - درخت شبکه (نیاز به اتصال واقعی)
- ✅ Wallet.razor - کیف پول (با Mock DiscountBalance)
- ✅ EditProfile.razor
- ✅ ChangePassword.razor
- ✅ Addresses.razor

### 🎖️ Club (3 صفحه) - **جدید** ✨
- ✅ **MembershipPage.razor**: نمایش وضعیت عضویت باشگاه
  - Badge وضعیت (Active/Inactive/Trial)
  - شمارش روزهای باقی‌مانده
  - کارت‌های مزایا (تخفیف، امتیاز، ارسال رایگان)
  - بخش فعال‌سازی (ActivationSection) برای اعضای غیرفعال
  
- ✅ **FeaturesPage.razor**: معرفی مزایا و ویژگی‌ها
  - 6 کارت ویژگی (تخفیف، امتیاز، ارسال، پشتیبانی، درآمد، رویدادها)
  - MudStepper نمایش فرآیند ثبت‌نام
  - دکمه CTA برای عضویت
  
- ✅ **Components/ActivationSection.razor**: فرم فعال‌سازی عضویت
  - ورودی PackageId, DurationMonths, ActivationCode
  - محاسبه خودکار هزینه (56M × ماه)
  - ولیدیشن فرم و رویداد OnActivationSuccess

### 🌳 Network (2 صفحه) - **بروزرسانی شده** ✨
- ✅ **Tree.razor** (در Profile): نمایش درخت دودویی
  - **d3-org-chart v3**: کتابخانه حرفه‌ای نمودار سازمانی
  - **JS Interop**: ارتباط Blazor با JavaScript
  - **امکانات**:
    - نمایش درختی با zoom و pan
    - کلیک روی نود → نمایش زیرمجموعه‌ها
    - دکمه‌های عملیاتی (باز کردن، بستن، مرکز، نمایش کامل)
    - انتخاب عمق (2-10 سطح)
    - دکمه‌های بازگشت و "درخت من"
    - طراحی ریسپانسیو
  - **متصل به**: `NetworkMembershipService.GetMyNetworkTreeAsync` و `GetSubordinateTreeAsync`
  
- ✅ **NetworkStatisticsPage.razor**: آمار شبکه
  - 4 کارت آماری (کل، چپ، راست، عمق)
  - Progress bar برای تعادل پاها
  - MudChart.Donut برای توزیع
  - کارت آخرین عضو (آواتار، موقعیت، تاریخ)

### 💰 Commission (3 صفحه) - **جدید** ✨
- ✅ **CommissionDashboardPage.razor**: داشبورد پرداخت‌ها
  - فیلترهای هفته و وضعیت
  - جدول + نمای موبایل (MudHidden responsive)
  - Pagination با MudPagination
  - لینک به صفحات تاریخچه و تعادل هفتگی
  
- ✅ **CommissionHistoryPage.razor**: تاریخچه کامل پرداخت‌ها
  - کارت‌های خلاصه (مجموع، تعداد هفته، میانگین)
  - جدول کامل با FixedHeader
  - لینک به جزئیات تعادل هر هفته
  
- ✅ **WeeklyBalancePage.razor**: جزئیات تعادل هفتگی
  - انتخابگر هفته با دکمه "هفته جاری"
  - کارت‌های تعادل چپ/راست با Progress bar
  - پنل محاسبات (Min balance, Count, Commission)
  - هشدار Carryover (اگر باشد)
  - MudChart.Bar مقایسه چپ/راست/Min
  - پشتیبانی Query parameter (?week=45)

---

## 🛠️ Services (8 سرویس)

### ✅ Services موجود (از قبل)
1. **AuthService**: احراز هویت JWT
2. **ProductService**: فراخوانی BFF Products
3. **CartService**: مدیریت سبد خرید
4. **OrderService**: ثبت و پیگیری سفارشات
5. **AddressService**: مدیریت آدرس‌ها

### ✨ Services جدید (Mock Data)
6. **ClubMembershipService**: مدیریت عضویت باشگاه
   - `GetMyMembershipAsync()`: بازگشت وضعیت عضویت
   - `ActivateMembershipAsync(...)`: فعال‌سازی عضویت
   - **⚠️ فعلا Mock**: بازمی‌گرداند `{ IsActive = false }`
   
7. **NetworkMembershipService**: مدیریت شبکه ✅ **بروزرسانی شده**
   - `GetMyNetworkTreeAsync(maxDepth)`: درخت شبکه تا عمق 10
   - `GetSubordinateTreeAsync(targetUserId, maxDepth)`: درخت زیرمجموعه **جدید**
   - `GetMyNetworkStatisticsAsync()`: آمار کلی شبکه
   - **✅ متصل به BFF**: gRPC واقعی
   
8. **CommissionService**: مدیریت کمیسیون
   - `GetMyCommissionPayoutsAsync(...)`: لیست پرداخت‌ها با فیلتر و صفحه‌بندی
   - `GetMyWeeklyBalanceAsync(weekNumber)`: تعادل هفتگی
   - **⚠️ فعلا Mock**: 50 پرداخت نمونه با وضعیت‌های مختلف

### ⚠️ WalletService (4 متد کامنت شده)
- ❌ `GetTransactionsAsync()`: TODO GetAllUserWalletChangeLog
- ❌ `RequestWithdrawalAsync()`: TODO WithdrawBalance
- ❌ `GetWithdrawalsAsync()`: TODO GetUserWithdrawals
- ❌ `GetWithdrawalSettingsAsync()`: TODO GetWithdrawalSettings

**📋 مشاهده جزئیات**: [TODO-COMMENTED-CODE.md](./TODO-COMMENTED-CODE.md)

---

## 🔗 BFF Handlers (12 Handler)

### ✅ موجود و پیاده‌سازی شده:

#### 1. ClubMembershipCQ (2 Handler)
- ✅ **GetMyClubMembership** (Query)
  - ⚠️ **مشکل**: فیلدها `ActivationDate` و `ExpirationDate` در CMS به `ActivatedAt` و `ExpiresAt` تغییر کرده
  - ⚠️ **مشکل**: فیلد `Features` اضافه شده که مپ نشده
  
- ✅ **ActivateMyClubMembership** (Command)
  - ⚠️ **مشکل**: Response Mock است، باید از `GetClubMembership` گرفته شود

#### 2. NetworkMembershipCQ (3 Handler) ✅ **کامل شده**
- ✅ **GetMyNetworkTree** (Query)
  - Tree Builder پیاده‌سازی شده
  - تبدیل Flat List از CMS به Tree Structure
  
- ✅ **GetMyNetworkStatistics** (Query)
  - آمار کامل شبکه
  
- ✅ **GetSubordinateTree** (Query) **جدید**
  - دریافت درخت یک زیرمجموعه
  - امنیت: فقط با JWT معتبر

#### 3. CommissionCQ (2 Handler)
- ✅ **GetMyCommissionPayouts** (Query)
  - ⚠️ **مشکل**: `WeekNumber` از `int` به `string` تغییر کرده
  - ⚠️ **مشکل**: `PageNumber` باید `PageIndex` باشد
  - ⚠️ **مشکل**: فیلدهای جدید اضافه شده: `ValuePerBalance`, `WithdrawalMethod`, `IbanNumber`, `LastModified`
  
- ✅ **GetMyWeeklyBalances** (Query)
  - ⚠️ **نیاز به بررسی**: باید چک شود نام فیلدها درست است یا خیر

#### 4. UserWalletCQ (5 Handler - 1 کامل، 4 TODO)
- ✅ **GetUserWallet** (Query) - کامل است
  - ⚠️ **مشکل جزئی**: `DiscountBalance` در Response نیست (فعلا 0 بر می‌گرداند)
  
- ❌ **GetAllUserWalletChangeLog** (Query) - TODO
- ❌ **WithdrawBalance** (Command) - TODO
- ❌ **GetUserWithdrawals** (Query) - TODO
- ❌ **GetWithdrawalSettings** (Query) - TODO

**📋 تحلیل کامل مغایرت‌ها**: [BFF-CMS-PROTOBUF-MISMATCH-ANALYSIS.md](./BFF-CMS-PROTOBUF-MISMATCH-ANALYSIS.md)

---

## 📦 Protobuf Packages

### ✅ موجود (از قبل):
- `FrontOffice.BFF.Package.Protobuf`
- `FrontOffice.BFF.UserAddress.Protobuf`
- `FrontOffice.BFF.ShoppingCart.Protobuf`
- `FrontOffice.BFF.UserOrder.Protobuf`
- `FrontOffice.BFF.UserWallet.Protobuf`

### ❌ ناموجود (باید ساخته شوند):
- ❌ `FrontOffice.BFF.ClubMembership.Protobuf` (0.0.1)
- ❌ `FrontOffice.BFF.NetworkMembership.Protobuf` (0.0.1)
- ❌ `FrontOffice.BFF.Commission.Protobuf` (0.0.1)

**زمان تخمینی**: 2-3 ساعت برای هر Package (مجموع 6-9 ساعت)

---

## ⚠️ مشکلات شناسایی شده

### 🔴 اولویت بالا (Blockers)

1. **BFF Handler Mismatches** (تخمین: 7-8 ساعت)
   - ClubMembership: نام فیلدها و Features مپینگ
   - NetworkMembership: Tree Builder و UserNetworkStatistics
   - Commission: نوع داده WeekNumber و فیلدهای جدید
   
2. **Missing Protobuf Packages** (تخمین: 6-9 ساعت)
   - باید 3 Package ساخته و publish شوند
   - بعد به FrontOffice.Main اضافه شوند
   
3. **WalletService Incomplete Methods** (تخمین: 3-4 ساعت)
   - 4 متد کامنت شده باید پیاده‌سازی شوند
   - نیاز به Query/Command جدید در BFF

### 🟡 اولویت متوسط

4. **Tree.razor Update** (تخمین: 2 ساعت)
   - حذف Mock OrganizationChart
   - اتصال به NetworkMembershipService
   - افزودن Depth selector و Lazy loading

5. **Mock Data Replacement** (تخمین: 1 ساعت)
   - بعد از اصلاح BFF، uncomment کردن gRPC calls
   - حذف Mock data از Services

### 🟢 اولویت پایین

6. **UI Enhancements** (اختیاری)
   - افزودن PersianCalendar برای تاریخ‌ها
   - بهبود نمودارها با ApexCharts
   - افزودن Real-time Notifications با SignalR

---

## 🔧 نحوه اجرا

### پیش‌نیازها
```bash
# .NET 9.0 SDK
dotnet --version

# Packages:
- MudBlazor 8.14.0
- Grpc.Net.Client
- Google.Protobuf
```

### اجرای FrontOffice.Main
```bash
cd /home/masoud/Apps/project/FourSat/FrontOffice/src
dotnet build FrontOffice.sln
dotnet run --project FrontOffice.Main
```

### اجرای FrontOffice.BFF
```bash
cd /home/masoud/Apps/project/FourSat/FrontOffice.BFF/src
dotnet build FrontOffice.BFF.sln
dotnet run --project FrontOffice.BFF.WebApi
```

### اجرای CMS (Backend)
```bash
cd /home/masoud/Apps/project/FourSat/CMS/src
dotnet build CMS.sln
dotnet run --project CMSMicroservice.WebApi
```

**⚠️ توجه**: فعلا UI با Mock data کار می‌کند و نیازی به BFF/CMS ندارد.

---

## 📚 مستندات مرتبط

### 📁 اسناد موجود در `totalDoc/FrontOffice/`:

1. **[TODO-COMMENTED-CODE.md](./TODO-COMMENTED-CODE.md)** 🔴
   - لیست کامل کدهای کامنت شده
   - TODO برای هر متد با راه حل
   - Checklist اجرایی
   
2. **[BFF-CMS-PROTOBUF-MISMATCH-ANALYSIS.md](./BFF-CMS-PROTOBUF-MISMATCH-ANALYSIS.md)** 🔴
   - تحلیل جامع مغایرت‌های Protobuf
   - مقایسه BFF Handler ها با CMS Proto ها
   - راه حل‌های پیشنهادی با کد نمونه
   - تخمین زمان برای هر مرحله
   
3. **[UI-DEVELOPMENT-SUMMARY.md](./UI-DEVELOPMENT-SUMMARY.md)** (در صورت وجود)
   - خلاصه توسعه UI
   - لیست صفحات و Component ها
   - MudBlazor patterns

### 📁 اسناد کلی پروژه:
- **[INDEX.md](../INDEX.md)**: راهنمای کلی پروژه FourSat
- **[QUICK-START-DEVELOPMENT.md](../QUICK-START-DEVELOPMENT.md)**: شروع سریع توسعه
- **[CMS/README.md](../CMS/README.md)**: مستندات CMS Microservice

---

## 🗺️ نقشه راه (Roadmap)

### ✅ فاز 1: UI Skeleton (تکمیل شد - ۱۴ آذر)
- [x] ساخت صفحات Club (2 صفحه + 1 component)
- [x] ساخت صفحات Network (1 صفحه)
- [x] ساخت صفحات Commission (3 صفحه)
- [x] ساخت Services با Mock data (3 سرویس)
- [x] بروزرسانی RouteConstants و Navigation
- [x] Build موفق (0 errors)

### 🔄 فاز 2: BFF Correction (در حال انجام)
- [ ] اصلاح GetMyClubMembershipQueryHandler
- [ ] اصلاح ActivateMyClubMembershipCommandHandler
- [ ] اصلاح GetMyNetworkTreeQueryHandler (Tree Builder)
- [ ] اصلاح GetMyNetworkStatisticsQueryHandler
- [ ] اصلاح GetMyCommissionPayoutsQueryHandler
- [ ] اصلاح GetMyWeeklyBalancesQueryHandler

**زمان تخمینی**: 7-8 ساعت

### ⏳ فاز 3: Protobuf Packages (آینده)
- [ ] ساخت FrontOffice.BFF.ClubMembership.Protobuf
- [ ] ساخت FrontOffice.BFF.NetworkMembership.Protobuf
- [ ] ساخت FrontOffice.BFF.Commission.Protobuf
- [ ] Publish به NuGet/Local Source
- [ ] اضافه کردن به FrontOffice.Main

**زمان تخمینی**: 6-9 ساعت

### ⏳ فاز 4: gRPC Connection (آینده)
- [ ] Uncomment کردن gRPC calls در Services
- [ ] حذف Mock data
- [ ] ConfigureServices.cs: اضافه کردن Clients
- [ ] تست اتصال با BFF
- [ ] تست داده واقعی در UI

**زمان تخمینی**: 2-3 ساعت

### ⏳ فاز 5: UserWalletCQ Completion (آینده)
- [ ] پیاده‌سازی GetAllUserWalletChangeLog
- [ ] پیاده‌سازی WithdrawBalance
- [ ] پیاده‌سازی GetUserWithdrawals
- [ ] پیاده‌سازی GetWithdrawalSettings
- [ ] Uncomment کردن WalletService methods

**زمان تخمینی**: 3-4 ساعت

### ⏳ فاز 6: Tree.razor Update (آینده)
- [ ] حذف Mock OrganizationChart
- [ ] اتصال به NetworkMembershipService
- [ ] Depth selector (1-10)
- [ ] Lazy loading

**زمان تخمینی**: 2 ساعت

---

## 📊 آمار پروژه

### کد نوشته شده (فاز UI Development):
- **Razor Pages**: ~3,500 خط
- **C# Code**: ~1,500 خط
- **DTOs**: 15 کلاس
- **Services**: 3 سرویس جدید
- **Components**: 1 کامپوننت (ActivationSection)

### فایل‌های ایجاد شده (جدید):
- **Razor Files**: 14 فایل (.razor + .razor.cs)
- **Service Files**: 6 فایل (3 Service + 3 Dtos)
- **Component Files**: 2 فایل
- **Modified Files**: 5 فایل (RouteConstants, ConfigureServices, Profile/Index, Profile/Wallet, WalletService)

### Build نتایج:
- ✅ **Errors**: 0
- ⚠️ **Warnings**: 113 (pre-existing, غیرمرتبط با کد جدید)
- ⏱️ **Build Time**: ~3.5 ثانیه

---

## 🤝 مشارکت

برای توسعه این پروژه:

1. تمام TODO ها در `TODO-COMMENTED-CODE.md` مشاهده کنید
2. تمام مغایرت‌ها در `BFF-CMS-PROTOBUF-MISMATCH-ANALYSIS.md` بررسی کنید
3. برای هر تغییر، ابتدا یک Branch جدید بسازید
4. پس از اصلاح، `dotnet build` را اجرا و تست کنید
5. TODO ها را به‌روز کنید

---

## 📞 تماس

**توسعه‌دهنده**: GitHub Copilot (Claude Sonnet 4.5)  
**تاریخ ایجاد**: آذر ۱۴۰۴  
**آخرین بروزرسانی**: ۱۴ آذر ۱۴۰۴

---

## 📝 یادداشت‌ها

### ✨ نکات مهم برای توسعه‌دهنده بعدی:

1. **MudBlazor Syntax**: حتما `T="string"` برای MudChip/MudSelect/MudRadio
2. **Reserved Keywords**: از `Value="@("in")"` برای کلمات رزرو شده استفاده کنید
3. **DI Injections**: _Imports.razor قبلا Snackbar و Navigation را inject کرده
4. **Using Statements**: فولدرهای جدید نیاز به `@using MudBlazor` دارند
5. **Protobuf Versioning**: هر تغییر در CMS Proto، نیاز به بروزرسانی BFF Handler دارد
6. **Mock Data Pattern**: همیشه یک TODO comment بگذارید تا فراموش نشود
7. **Tree Structure**: CMS حالا Flat List برمی‌گرداند، باید در BFF Tree بسازید
8. **WeekNumber Type**: در Commission از `string` استفاده می‌شود نه `int`

### 🐛 مشکلات شناخته شده:

- ⚠️ **WalletService**: 4 متد کامنت شده (نیاز به Query/Command جدید در BFF)
- ⚠️ **Tree.razor**: هنوز Mock data دارد، باید به NetworkMembershipService متصل شود
- ⚠️ **BFF Handlers**: 6 Handler نیاز به اصلاح دارند (مغایرت با CMS Proto)
- ⚠️ **Protobuf Packages**: 3 Package هنوز ساخته نشده‌اند

---

**📅 آخرین بروزرسانی**: ۱۴ آذر ۱۴۰۴  
**👤 توسط**: GitHub Copilot (Claude Sonnet 4.5)