docs/04-FRONTEND/FrontOffice/README.md

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

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

آخرین بروزرسانی: ۱۴ آذر ۱۴۰۴

---

📊 وضعیت پروژه

بخش	وضعیت	درصد تکمیل	فایل‌ها
UI Pages	✅ Build موفق	75%	24 صفحه
BFF Handlers	⚠️ نیاز به اصلاح	60%	12 Handler
Protobuf Packages	❌ ناقص	40%	3 Package
Services	⚠️ Mock Data	50%	8 Service
gRPC Connection	❌ غیرفعال	0%	-

🎉 آخرین موفقیت: Build موفق با 0 error و 113 warning (۱۴ آذر)

---

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

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): نمایش درخت دودویی

  • از OrganizationChart component استفاده می‌کند
  • TODO: باید به NetworkMembershipService.GetMyNetworkTree متصل شود

• ✅ 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
   • GetMyNetworkStatisticsAsync(): آمار کلی شبکه
   • ⚠️ فعلا Mock: 5 نود نمونه، 15 چپ + 12 راست = 27 عضو

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

• ✅ GetMyNetworkTree (Query)

  • ⚠️ مشکل بزرگ: CMS حالا Flat List بر می‌گرداند نه Tree Structure
  • 🔧 نیاز: باید در BFF یک Tree Builder اضافه شود

• ✅ GetMyNetworkStatistics (Query)

  • ⚠️ مشکل: CMS دیگر UserId نمی‌گیرد (برای کل شبکه است)
  • ⚠️ مشکل: فیلد LastMember وجود ندارد
  • 🔧 راه حل: استفاده از GetUserNetwork + GetNetworkTree

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)