docs/04-FRONTEND/FrontOffice/README.md

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

FrontOffice: رابط کاربری Blazor Server برای مشتریان نهایی سیستم FourSat

آخرین بروزرسانی: ۹ دی ۱۴۰۴ (29 دسامبر 2025)

---

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

✅ Commission Data Flow Fix

• مشکل: صفحه weekly-balance مقادیر carryover را 0 نشان می‌داد
• حل: استفاده از مقادیر واقعی سرور به جای محاسبه محلی
• فایل‌ها:
  • CommissionService.cs - استفاده از balance.LeftLegCarryover
  • CommissionDtos.cs - Properties جدید carryover و new_members

✅ WeekSelector Autocomplete

• کامپوننت: MudAutocomplete برای انتخاب هفته
• قابلیت: جستجو در لیست هفته‌ها
• صفحه: CommissionDashboardPage.razor

✅ Responsive UI Improvements

• MudGrid: استفاده از breakpoints (xs, sm, md)
• Summary Stats: کارت‌های آماری در بالای صفحه
• MudHidden: جدول در دسکتاپ، کارت در موبایل

✅ Merged Dashboard & History Pages

• قبل: دو صفحه جداگانه تکراری
• بعد: یک صفحه با dual routing
• فایل حذف شده: CommissionHistoryPage.razor[.cs]

✅ Terminology Cleanup (MLM-Sensitive Words)

جایگزینی کلمات حساس:

قبلی	جدید
کمیسیون	پاداش
شبکه‌سازی	تیم‌سازی
مشاهده شبکه	مشاهده تیم
آمار شبکه	آمار تیم
شبکه‌های فروش	تیم‌های فروش

فایل‌های تغییر یافته: WeeklyBalancePage, CommissionDashboardPage, MyPackages, Packages, Index, About, Footer, NetworkStatisticsPage

---

🆕 تغییرات قبلی (۶ دی ۱۴۰۴)

✅ نمایش کد معرف در درخت شبکه

• کد معرف: نمایش 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/        # ✅ پاداش (2 صفحه)
    │   │       ├── CommissionDashboardPage.razor  # dual: /dashboard + /history
    │   │       └── WeeklyBalancePage.razor
    │   └── Utilities/             # Services & DTOs
    │       ├── ClubMembershipService.cs        # ⚠️ Mock Data
    │       ├── NetworkMembershipService.cs     # ⚠️ Mock Data
    │       ├── CommissionService.cs            # ✅ Real 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 (2 صفحه) - بروزرسانی ۹ دی ✨

• ✅ CommissionDashboardPage.razor: داشبورد پاداش‌ها (merged با History)

  • Dual routing: /commission/dashboard + /commission/history
  • WeekSelector Autocomplete: انتخابگر هفته با جستجو
  • Summary Stats Cards: کل پاداش، پرداخت شده، در انتظار، میانگین
  • جدول + نمای موبایل (MudHidden responsive)
  • Pagination با MudPagination
  • لینک به صفحه تعادل هفتگی

• ✅ WeeklyBalancePage.razor: جزئیات تعادل هفتگی

  • انتخابگر هفته با دکمه "هفته جاری"
  • کارت‌های تعادل تیم اول/دوم با Progress bar
  • Carryover Breakdown: نمایش اعضای جدید + انتقال از هفته قبل
  • پنل محاسبات (Min balance, Count, پاداش)
  • هشدار Carryover (اگر باشد)
  • MudChart.Bar مقایسه تیم اول/دوم/Min
  • پشتیبانی Query parameter (?week=45)

• ❌ CommissionHistoryPage.razor: حذف شده (merged با Dashboard)

---

🛠️ 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

---

🔗 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

---

📦 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

---

🔧 نحوه اجرا

پیش‌نیازها

# .NET 9.0 SDK
dotnet --version

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

اجرای FrontOffice.Main

cd /home/masoud/Apps/project/FourSat/FrontOffice/src
dotnet build FrontOffice.sln
dotnet run --project FrontOffice.Main

اجرای FrontOffice.BFF

cd /home/masoud/Apps/project/FourSat/FrontOffice.BFF/src
dotnet build FrontOffice.BFF.sln
dotnet run --project FrontOffice.BFF.WebApi

اجرای CMS (Backend)

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 برای هر متد با راه حل
   • Checklist اجرایی

2. BFF-CMS-PROTOBUF-MISMATCH-ANALYSIS.md 🔴

   • تحلیل جامع مغایرت‌های Protobuf
   • مقایسه BFF Handler ها با CMS Proto ها
   • راه حل‌های پیشنهادی با کد نمونه
   • تخمین زمان برای هر مرحله

3. UI-DEVELOPMENT-SUMMARY.md (در صورت وجود)

   • خلاصه توسعه UI
   • لیست صفحات و Component ها
   • MudBlazor patterns

📁 اسناد کلی پروژه:

• INDEX.md: راهنمای کلی پروژه FourSat
• QUICK-START-DEVELOPMENT.md: شروع سریع توسعه
• CMS/README.md: مستندات CMS Microservice

---

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

✅ فاز 1: UI Skeleton (تکمیل شد - ۱۴ آذر)

• ساخت صفحات Club (2 صفحه + 1 component)
• ساخت صفحات Network (1 صفحه)
• ساخت صفحات Commission (3 صفحه)
• ساخت Services با Mock data (3 سرویس)
• بروزرسانی RouteConstants و Navigation
• 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)