docs/technical/TECH-02-BACKOFFICE-FRONTOFFICE.md

🖥️ BackOffice و FrontOffice — معماری UI

منابع ادغام‌شده: BACKOFFICE-ARCHITECTURE.md, BACKOFFICE-STORE-UNIFICATION.md, UI-MODERNIZATION-PLAN.md, UI-UNIFICATION-PLAN.md, PHASE-1-COMPLETE.md, PHASE-3-COMPLETE.md, PRODUCT-IMAGES-SQUARE.md
آخرین بروزرسانی: اسفند ۱۴۰۴ (بروزرسانی: فیکس‌های پرداخت Phase 11 + صفحه موفقیت + تومان/ریال + امنیت Callback)

---

۱. Stack مشترک

آیتم	BackOffice	FrontOffice
Framework	Blazor WebAssembly	Blazor Server
UI Library	MudBlazor v8	MudBlazor v8
ارتباط با CMS	gRPC (مستقیم)	gRPC (مستقیم)
احراز هویت	JWT Bearer	JWT Bearer
Hosting	Static files (nginx)	Kestrel server
Target	ادمین‌ها	کاربران نهایی

---

۲. معماری BackOffice

۲.۱ ساختار فولدرها

BackOffice/src/BackOffice/
├── Layout/
│   ├── MainLayout.razor      ← Sidebar + AppBar
│   └── NavMenu.razor          ← منوی ناوبری
├── Pages/
│   ├── Dashboard/
│   ├── Products/
│   │   ├── ProductList.razor
│   │   ├── ProductList.razor.cs   ← code-behind
│   │   ├── ProductEdit.razor
│   │   └── ProductEdit.razor.cs
│   ├── Orders/
│   ├── Users/
│   ├── Club/
│   │   ├── ClubMembers.razor      ← + UserAutoComplete فیلتر در تولبار
│   │   └── ActivateClubDialog.razor ← UserAutoComplete بجای MudNumericField
│   ├── Wallet/
│   │   └── WalletManagementPage.razor ← TemplateColumn با UserName + ID
│   ├── AutoComplete/
│   │   └── UserAutoComplete.razor  ← کامپوننت مشترک جستجوی کاربر
│   ├── Blog/
│   ├── Inventory/
│   ├── SitePages/
│   │   └── {PageType}Editor.razor  ← Shopify-style typed editors
│   └── Settings/
├── Services/
│   ├── ProductService.cs       ← gRPC client wrapper
│   ├── OrderService.cs
│   ├── UserService.cs
│   └── ...
├── Shared/
│   ├── AppImage.razor          ← کامپوننت تصویر مشترک (1:1)
│   ├── ConfirmDialog.razor
│   └── LoadingIndicator.razor
└── wwwroot/

۲.۲ الگوی Code-Behind

// ProductList.razor.cs
public partial class ProductList : ComponentBase
{
    [Inject] private IProductService ProductService { get; set; }
    [Inject] private ISnackbar Snackbar { get; set; }
    
    private List<ProductDto> _products = new();
    private bool _isLoading = true;
    
    protected override async Task OnInitializedAsync()
    {
        await LoadProducts();
    }
    
    private async Task LoadProducts()
    {
        _isLoading = true;
        try {
            _products = await ProductService.GetProductsAsync();
        } catch (RpcException ex) {
            Snackbar.Add($"خطا: {ex.Status.Detail}", Severity.Error);
        }
        _isLoading = false;
    }
}

---

۳. معماری FrontOffice

۳.۱ ساختار فولدرها

FrontOffice/src/FrontOffice/
├── Layout/
│   ├── MainLayout.razor       ← Header + Footer
│   └── AuthLayout.razor       ← Login/Register pages
├── Pages/
│   ├── Home.razor
│   ├── Landing.razor          ← انیمیشن‌دار
│   ├── Store/
│   │   ├── Products.razor     ← Lazy loading (12 per page)
│   │   ├── Products.razor.cs
│   │   ├── ProductDetail.razor
│   │   └── Cart.razor
│   ├── DiscountStore/
│   │   ├── Products.razor     ← Lazy loading + hybrid payment
│   │   ├── Products.razor.cs
│   │   └── Cart.razor
│   ├── Club/
│   │   ├── Dashboard.razor    ← داشبورد باشگاه
│   │   ├── NetworkTree.razor  ← نمای درخت
│   │   └── Contract.razor     ← امضای قرارداد
│   ├── Profile/
│   │   ├── Index.razor        ← داشبورد پروفایل + تایل Magic
│   │   ├── MagicWallet.razor  ← 🪄 کیف‌پول جادویی
│   │   └── PaymentCallback.razor ← 💳 صفحه نتیجه پرداخت (TransactionId + موجودی واقعی)
│   ├── Blog/
│   ├── Auth/
│   │   ├── Login.razor
│   │   └── Register.razor
│   └── About.razor, Contact.razor, ...
├── Services/
│   ├── ProductService.cs      ← با GetProductsPagedAsync
│   ├── ClubService.cs
│   ├── WalletService.cs       ← + MagicWalletStatus, InitiateMagicChargeAsync
│   ├── VATService.cs          ← VAT 10% از سرور + LocalStorage cache
│   └── ...
└── Shared/
    ├── AppImage.razor
    ├── ProductCard.razor      ← مشترک بین Store و DiscountStore
    ├── PackagePurchaseDialog.razor ← دیالوگ ۲-مرحله‌ای خرید پکیج (NEW)
    └── LoadMoreButton.razor

---

۴. UI Modernization — فازها

۴.۱ نقشه فازها

فاز	عنوان	شامل	وضعیت
Phase 1	پایه MudBlazor v8	ارتقا MudBlazor، Layout اصلی	✅ 100%
Phase 2	صفحات محصول	Card grid، فیلتر، جزئیات	✅ 100%
Phase 3	فروشگاه اعتباری	UI DiscountStore + hybrid pay	✅ 100%
Phase 4	باشگاه	داشبورد، درخت، قرارداد	✅ 100%
Phase 5	محتوا	بلاگ، Site Pages	✅ 100%
Phase 6	نهایی‌سازی	تصاویر 1:1، lazy load، landing fix	✅ 100%
Phase 7	موبایل	Responsive، PWA، Bottom nav	⬜ 0%

۴.۲ جزئیات Phase 1-6 (تکمیل‌شده)

✅ Phase 1: ارتقا MudBlazor v7→v8, AppBar, Drawer, Theme
✅ Phase 2: ProductCard (1:1), CategoryFilter, MudGrid
✅ Phase 3: DiscountStore pages, HybridPayment component
✅ Phase 4: NetworkTree visualization, Contract modal
✅ Phase 5: Blog pagination, SitePageEditors (Shopify)
✅ Phase 6: AppImage shared, lazy load, counter animation fix

---

۵. یکپارچه‌سازی فروشگاه (Store Unification)

۵.۱ کامپوننت‌های مشترک

@* AppImage.razor — مشترک بین همه پروژه‌ها *@
<MudImage 
    Src="@ImageUrl" 
    Alt="@Alt"
    ObjectFit="ObjectFit.Cover"
    Style="aspect-ratio: 1/1; width: 100%;"
    loading="lazy" />

@code {
    [Parameter] public string? ImageUrl { get; set; }
    [Parameter] public string Alt { get; set; } = "";
}

۵.۲ تغییرات BackOffice

صفحه	قبل	بعد
Product List	<img> ساده	<AppImage> مربعی
Product Edit	فرم ساده	MudForm + Validation
Inventory	بدون Autocomplete	با MudAutocomplete
SitePages	جدول Settings	Typed Editors

---

۶. تم و استایل

۶.۱ MudBlazor Theme

var theme = new MudTheme {
    PaletteLight = new PaletteLight {
        Primary = "#1976D2",
        Secondary = "#FF9800",
        Background = "#F5F5F5",
        Surface = "#FFFFFF",
        AppbarBackground = "#1976D2"
    },
    Typography = new Typography {
        Default = new DefaultTypography {
            FontFamily = new[] { "Vazirmatn", "Roboto", "sans-serif" }
        }
    }
};

۶.۲ RTL Support

/* wwwroot/css/app.css */
body { direction: rtl; font-family: 'Vazirmatn', sans-serif; }
.mud-drawer--open-responsive-lg-left { right: 0; left: auto; }

---

۷. ناوبری Auth-Aware (FrontOffice)

// MainLayout.razor.cs
@inject AuthenticationStateProvider AuthState

var authState = await AuthState.GetAuthenticationStateAsync();
var user = authState.User;

if (user.Identity?.IsAuthenticated == true) {
    var isClub = user.HasClaim("IsClubMember", "true");
    // Show: Dashboard, Store, DiscountStore (if club), Profile
} else {
    // Show: Landing, Store, Register, Login
}

---

۸. خلاصه وضعیت

ماژول	وضعیت	درصد
BackOffice MudBlazor v8	✅	100%
FrontOffice MudBlazor v8	✅	100%
Code-behind pattern	✅	100%
AppImage component	✅	100%
Lazy loading	✅	100%
Store Unification	✅	100%
SitePage Typed Editors	✅	100%
RTL Support	✅	100%
Magic Wallet UI	✅	100%
Proto ProjectReference	✅	100%
UserAutoComplete کامپوننت	✅	100%
نمایش نام کاربر در Wallet	✅	100%
فعال‌سازی دکمه‌های درگاه	✅	100%
PackagePurchaseDialog	✅	100%
Toman/Rial فیکس نمایش قیمت	✅	100%
صفحه نتیجه پرداخت (PaymentCallback)	✅	100%
امنیت Callback URL	✅	100%
Mobile Responsive (Phase 7)	⬜	0%
Dark Mode	⬜	0%
PWA	⬜	0%