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`  
> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: UserAutoComplete + فعال‌سازی درگاه)

---

## ۱. 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

```csharp
// 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  ← 🪄 کیف‌پول جادویی (NEW)
│   ├── 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
    └── 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)

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

```razor
@* 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

```csharp
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

```css
/* 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)

```csharp
// 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% |
| Mobile Responsive (Phase 7) | ⬜ | 0% |
| Dark Mode | ⬜ | 0% |
| PWA | ⬜ | 0% |