# 📚 BackOffice (Admin Panel) - Complete Documentation

> **آخرین بروزرسانی**: January 3, 2026  
> **Build Status**: ✅ SUCCESS (0 Errors)  
> **Framework**: Blazor WebAssembly (.NET 9.0) + MudBlazor UI  

---

## 📊 وضعیت کلی سیستم

| Component | Status | Errors |
|-----------|--------|--------|
| BackOffice UI | ✅ SUCCESS | 0 |
| BackOffice.BFF | ✅ SUCCESS | 0 |
| CMS Microservice | ✅ SUCCESS | 0 |

**System Status**: 🟢 **PRODUCTION READY**

---

## 🗂️ ماژول‌های فعال (21 ماژول - 96 صفحه)

### آمار صفحات هر ماژول:

| ماژول | تعداد صفحات | وضعیت |
|-------|-------------|--------|
| DiscountShop | 9 | ✅ |
| Inventory | 9 | ✅ |
| AutoComplete | 7 | ✅ |
| Products | 7 | ✅ |
| UserOrder | 6 | ✅ |
| Commission | 6 | ✅ |
| Club | 5 | ✅ |
| Network | 4 | ✅ |
| Payment | 4 | ✅ |
| PublicMessages | 4 | ✅ |
| Role | 4 | ✅ |
| UserRole | 4 | ✅ |
| SystemManagement | 4 | ✅ |
| Category | 3 | ✅ |
| Package | 3 | ✅ |
| Settings | 3 | ✅ |
| Tag | 3 | ✅ |
| UserAddress | 3 | ✅ |
| Dashboard | 2 | ✅ |
| Login | 2 | ✅ |
| User | 2 | ✅ |

---

## 📦 Proto Projects (24 پروژه)

### Core:
- ✅ `BackOffice.BFF.Common.Protobuf`
- ✅ `BackOffice.BFF.Health.Protobuf`
- ✅ `BackOffice.BFF.Configuration.Protobuf`

### User Management:
- ✅ `BackOffice.BFF.User.Protobuf`
- ✅ `BackOffice.BFF.UserRole.Protobuf`
- ✅ `BackOffice.BFF.Role.Protobuf`
- ✅ `BackOffice.BFF.UserAddress.Protobuf`
- ✅ `BackOffice.BFF.Otp.Protobuf`

### Products & Shop:
- ✅ `BackOffice.BFF.Products.Protobuf`
- ✅ `BackOffice.BFF.Category.Protobuf`
- ✅ `BackOffice.BFF.Tag.Protobuf`
- ✅ `BackOffice.BFF.ProductTag.Protobuf`
- ✅ `BackOffice.BFF.Package.Protobuf`
- ✅ `BackOffice.BFF.Inventory.Protobuf`

### Discount Shop:
- ✅ `BackOffice.BFF.DiscountProduct.Protobuf`
- ✅ `BackOffice.BFF.DiscountCategory.Protobuf`
- ✅ `BackOffice.BFF.DiscountOrder.Protobuf`
- ✅ `BackOffice.BFF.DiscountShoppingCart.Protobuf`

### Network & Commission:
- ✅ `BackOffice.BFF.NetworkMembership.Protobuf`
- ✅ `BackOffice.BFF.ClubMembership.Protobuf`
- ✅ `BackOffice.BFF.Commission.Protobuf`

### Orders & Payments:
- ✅ `BackOffice.BFF.UserOrder.Protobuf`
- ✅ `BackOffice.BFF.ManualPayment.Protobuf`

### Messaging:
- ✅ `BackOffice.BFF.PublicMessage.Protobuf`

---

## 🔧 معماری سیستم

```
┌─────────────────────────────────────────────────────────────┐
│                    BackOffice (Blazor WASM)                 │
│                   96 Pages / 21 Modules                     │
└─────────────────────────────────────────────────────────────┘
                              │
                        gRPC-Web + JWT
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    BackOffice.BFF                           │
│              CQRS Handlers + Proto Contracts                │
└─────────────────────────────────────────────────────────────┘
                              │
                          gRPC
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    CMS Microservice                         │
│            Business Logic + PostgreSQL                       │
└─────────────────────────────────────────────────────────────┘
```

---

## 🚀 راهنمای Build و Deploy

### Local Development:

```bash
cd /home/masoud/Apps/project/FourSat/BackOffice/src
dotnet build BackOffice.sln
dotnet run --project BackOffice/BackOffice.csproj
```

### Production با DLL های Proto:

```bash
# 1. Build proto dependencies
cd /home/masoud/Apps/project/FourSat/BackOffice
./build-deps.sh

# 2. Build & Publish
cd src
dotnet publish BackOffice/BackOffice.csproj -c Release -o ./publish
```

### Docker:

```bash
cd /home/masoud/Apps/project/FourSat/BackOffice
docker build -t backoffice:latest .
```

---

## 📋 جزئیات ماژول‌ها

### 1. Products Module
**مسیر**: `Pages/Products/`

| صفحه | Route | توضیحات |
|------|-------|---------|
| ProductsMainPage | `/products` | لیست + فیلتر + صفحه‌بندی |
| CreateDialog | - | ایجاد محصول + آپلود تصویر |
| UpdateDialog | - | ویرایش محصول |
| GalleryDialog | - | گالری تصاویر محصول |
| BulkEdit | `/products/bulk-edit` | ویرایش گروهی قیمت/موجودی |
| ProductCategoriesDragDropPage | `/products/categories` | تخصیص دسته‌بندی |
| CategoryProductsDragDropPage | `/category/products` | مدیریت محصولات دسته |

**ویژگی‌ها**:
- ✅ ستون موجودی با رنگ‌بندی هوشمند (🔴🟡🟢)
- ✅ DragDrop دسته‌بندی محصولات
- ✅ آپلود تصویر با پیش‌نمایش
- ✅ مدیریت تگ‌های محصول

---

### 2. Inventory Module
**مسیر**: `Pages/Inventory/`

| صفحه | Route | توضیحات |
|------|-------|---------|
| InventoryMainPage | `/inventory` | لیست موجودی‌ها |
| LowStockPage | `/inventory/low-stock` | هشدار موجودی کم |
| MovementsPage | `/inventory/movements` | تاریخچه حرکات |
| WarehousesPage | `/inventory/warehouses` | مدیریت انبارها |
| AddStockDialog | - | اضافه کردن موجودی |
| AdjustStockDialog | - | تنظیم موجودی |
| RecordLossDialog | - | ثبت ضایعات |
| TransferStockDialog | - | انتقال بین انبار |
| InventorySettingsDialog | - | تنظیمات انبار |

**ویژگی‌ها**:
- ✅ انواع حرکت موجودی (ورود، خروج، تنظیم، انتقال، ضایعات)
- ✅ هشدار موجودی کم با threshold قابل تنظیم
- ✅ پشتیبانی از multi-warehouse

---

### 3. Discount Shop Module
**مسیر**: `Pages/DiscountShop/`

| صفحه | Route | توضیحات |
|------|-------|---------|
| DiscountProductsMainPage | `/discount-products` | محصولات تخفیفی |
| DiscountCategoriesMainPage | `/discount-categories` | دسته‌بندی‌ها |
| DiscountOrdersMainPage | `/discount-orders` | سفارشات |

**ویژگی‌ها**:
- ✅ CRUD محصولات تخفیفی
- ✅ گالری تصاویر
- ✅ مدیریت دسته‌بندی سلسله‌مراتبی
- ✅ مشاهده و تغییر وضعیت سفارشات

---

### 4. Commission Module
**مسیر**: `Pages/Commission/`

| صفحه | Route | توضیحات |
|------|-------|---------|
| Dashboard | `/commission` | داشبورد استخر هفتگی |
| WeeklyReports | `/commission/reports` | گزارش‌های هفتگی |
| Payouts | `/commission/payouts` | لیست پرداخت‌ها |
| Withdrawals | `/commission/withdrawals` | لیست برداشت‌ها |
| UserBalances | `/network/balances` | بالانس کاربران |

**ویژگی‌ها**:
- ✅ نمایش استخر هفتگی با جزئیات
- ✅ محاسبه ارزش هر بالانس
- ✅ تاریخچه پرداخت‌ها و برداشت‌ها

---

### 5. Network Module
**مسیر**: `Pages/Network/`

| صفحه | Route | توضیحات |
|------|-------|---------|
| NetworkMembersList | `/network/members` | لیست اعضای شبکه |
| NetworkTreeViewer | `/network/tree` | نمای درختی شبکه |
| NetworkStats | `/network/stats` | آمار شبکه |

**ویژگی‌ها**:
- ✅ نمایش درختی شبکه بازاریابی
- ✅ جستجو و فیلتر اعضا
- ✅ آمار و گزارش‌گیری

---

### 6. Club Module
**مسیر**: `Pages/Club/`

| صفحه | Route | توضیحات |
|------|-------|---------|
| ClubMembersList | `/club/members` | لیست اعضای باشگاه |
| ClubFeatures | `/club/features` | مدیریت ویژگی‌ها |
| ManualActivation | `/club/activate` | فعال‌سازی دستی |

**ویژگی‌ها**:
- ✅ مدیریت اعضای باشگاه مشتریان
- ✅ فعال/غیرفعال کردن ویژگی‌ها برای هر کاربر
- ✅ فعال‌سازی دستی با آپلود فیش پرداخت

---

### 7. User Order Module
**مسیر**: `Pages/UserOrder/`

| صفحه | Route | توضیحات |
|------|-------|---------|
| UserOrderMainPage | `/orders` | لیست سفارشات |
| UserOrderDetailsDialog | - | جزئیات سفارش |
| ChangeOrderStatusDialog | - | تغییر وضعیت |
| CancelOrderDialog | - | لغو سفارش |
| ApplyDiscountDialog | - | اعمال تخفیف |

**ویژگی‌ها**:
- ✅ مدیریت کامل سفارشات
- ✅ نمایش جزئیات با VAT
- ✅ تغییر وضعیت و لغو سفارش

---

### 8. System Management Module
**مسیر**: `Pages/SystemManagement/`

| صفحه | Route | توضیحات |
|------|-------|---------|
| Configuration | `/system/config` | تنظیمات سیستم |
| EmailConfig | `/system/email` | پیکربندی ایمیل |
| SmsConfig | `/system/sms` | پیکربندی SMS |
| Logs | `/system/logs` | لاگ‌های سیستم |

---

## 🔗 دامنه‌ها و آدرس‌ها (محیط Stage)

| سرویس | آدرس |
|-------|------|
| BackOffice UI | `https://backoffice.se.kbs1.ir` |
| BackOffice BFF | `https://backoffice-bff.se.kbs1.ir` |
| FrontOffice UI | `https://frontoffice.se.kbs1.ir` |
| FrontOffice BFF | `https://frontoffice-bff.se.kbs1.ir` |
| CMS | `https://cms.se.kbs1.ir` |
| Git Registry | `git.se.kbs1.ir` |

---

## 📝 تاریخچه تغییرات اخیر

### January 3, 2026
- ✅ مایگریشن Proto References به DLL-based Approach
- ✅ تغییر دامنه‌ها از `*.foursat.afrino.co` به `*.se.kbs1.ir`
- ✅ بروزرسانی Git Remote URLs
- ✅ ایجاد `build-deps.sh` برای CI/CD

### January 1, 2026
- ✅ فعال‌سازی ماژول DiscountShop Frontend
- ✅ فعال‌سازی ماژول Tag
- ✅ فعال‌سازی ماژول PublicMessages

### December 20, 2025
- ✅ رفع مشکل صفحه `/network/balances`
- ✅ رفع مشکل صفحه `/club/members`
- ✅ تکمیل Mapster Mappings

---

## 🛠️ Troubleshooting

### Build Errors

**مشکل**: Missing Proto DLLs
```bash
# راه‌حل: Rebuild proto dependencies
cd BackOffice
rm -rf libs/
./build-deps.sh
```

**مشکل**: Package Version Conflict
```bash
# بررسی ورژن‌ها
# Google.Protobuf: 3.28.3
# Grpc.Core.Api: 2.71.0
```

### Runtime Errors

**مشکل**: gRPC Connection Failed
```
# بررسی آدرس BFF در appsettings.json
"GwUrl": "https://backoffice-bff.se.kbs1.ir"
```

---

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

- [Proto Packaging Guide](./02-PROTO-GUIDE.md)
- [Data Migration Guide](./03-DATA-MIGRATION.md)
- [CMS Documentation](./04-CMS.md)
- [Deployment Guide](./05-DEPLOYMENT.md)
