docs/03-BACKEND/BackOffice.BFF/discount-shop-integration.md

BackOffice.BFF - Discount Shop Integration Plan

تاریخ ایجاد: 1403/09/13 (2024-12-04)
آخرین بروزرسانی: 1403/10/11 (2024-12-31)
وضعیت: ✅ پیاده‌سازی کامل (شامل Image Gallery و Admin Reports)
اولویت در زمان طراحی: 🔴 بالا

---

📊 خلاصه وضعیت

✅ تکمیل شده در CMS

• Phase 9: Club Discount Shop System - 100% ✅

  • 6 Entities (Category, Product, Cart, Order)
  • 13 Commands + 6 Queries + 9 Validators
  • 4 Proto Files (19 gRPC RPCs)
  • 4 gRPC Services
  • Migration: AddDiscountShopSystem

• Phase 10: Product Image Gallery - 100% ✅ (جدید)

  • 5 عملیات جدید: Add/Update/Delete/Reorder/Get Images
  • 2 Command + 3 RPC جدید
  • پشتیبانی از چندین تصویر برای هر محصول

• Phase 11: Admin Order Reports - 100% ✅ (جدید)

  • GetAllDiscountOrders: لیست کامل سفارشات با فیلتر و صفحه‌بندی
  • GetDiscountSalesReport: گزارش فروش با فیلتر تاریخ و نوع گزارش

✅ وضعیت در BackOffice.BFF (تکمیل شده)

• 26 Handler برای 6 سرویس → ✅ پیاده‌سازی و متصل به CMS
  • 19 Handler اصلی + 5 Handler گالری تصاویر + 2 Handler گزارش سفارشات
• 2 gRPC Service در WebApi → ✅ جدید
  • DiscountProductService.cs با 10 RPC endpoint
  • DiscountOrderService.cs با 7 RPC endpoint
• 4 Client Interface در IApplicationContractContext → ✅ اضافه و در ApplicationContractContext پیاده‌سازی شده
• Test و Validation → ✅ در BackOffice UI (DiscountShop صفحات و سرویس‌ها) در حال استفاده عملی

این سند به‌عنوان طرح اولیه نگه‌داری می‌شود؛ برای وضعیت نهایی به totalDoc/05-TASKS/BACKLOG.md (بخش Discount Shop - BackOffice Integration ✅) و totalDoc/04-FRONTEND/BackOffice/ui-status.md مراجعه شود.

---

🎯 امکانات جدید برای Admin Panel

1️⃣ مدیریت محصولات فروشگاه تخفیفی (5 API)

سرویس: DiscountProductContract

الف. ایجاد محصول جدید

• Handler: CreateDiscountProductHandler
• Request:

  - Title (عنوان محصول)
  - ShortInfomation (توضیحات کوتاه)
  - FullInformation (توضیحات کامل)
  - Price (قیمت به تومان)
  - MaxDiscountPercent (حداکثر درصد تخفیف قابل استفاده از کیف پول تخفیف - 0 تا 100)
  - ImagePath (مسیر تصویر اصلی)
  - ThumbnailPath (مسیر تصویر کوچک)
  - InitialCount (تعداد اولیه موجودی)
  - SortOrder (ترتیب نمایش)
  - IsActive (فعال/غیرفعال)
  - CategoryIds (لیست شناسه دسته‌بندی‌ها)
  

• Response: ProductId (شناسه محصول ایجاد شده)
• کاربرد Admin: ایجاد محصول جدید در فروشگاه تخفیفی

ب. ویرایش محصول

• Handler: UpdateDiscountProductHandler
• Request: همان فیلدهای بالا + ProductId
• کاربرد Admin: ویرایش اطلاعات محصول موجود

ج. حذف محصول

• Handler: DeleteDiscountProductHandler
• Request: ProductId
• کاربرد Admin: حذف محصول از فروشگاه

د. دریافت جزئیات محصول

• Handler: GetDiscountProductByIdHandler
• Request: ProductId
• Response: تمام اطلاعات محصول + لیست دسته‌بندی‌ها + موجودی باقی‌مانده
• کاربرد Admin: مشاهده جزئیات کامل یک محصول

ه. لیست محصولات با فیلتر

• Handler: GetDiscountProductsHandler
• Request:

  - CategoryId (nullable - فیلتر بر اساس دسته‌بندی)
  - SearchQuery (nullable - جستجو در عنوان و توضیحات)
  - MinPrice (nullable - حداقل قیمت)
  - MaxPrice (nullable - حداکثر قیمت)
  - IsActive (nullable - فیلتر فعال/غیرفعال)
  - InStock (nullable - فقط موجود در انبار)
  - PageNumber (شماره صفحه)
  - PageSize (تعداد آیتم در صفحه)
  

• Response:

  - MetaData (اطلاعات صفحه‌بندی)
  - Models (لیست محصولات)
  

• کاربرد Admin: مدیریت و جستجوی محصولات

---

2️⃣ مدیریت دسته‌بندی محصولات (4 API)

سرویس: DiscountCategoryContract

الف. ایجاد دسته‌بندی جدید

• Handler: CreateDiscountCategoryHandler
• Request:

  - Name (نام لاتین برای URL)
  - Title (عنوان فارسی)
  - Description (nullable - توضیحات)
  - ImagePath (nullable - تصویر دسته‌بندی)
  - ParentCategoryId (nullable - دسته‌بندی والد برای ساختار درختی)
  - SortOrder (ترتیب نمایش)
  - IsActive (فعال/غیرفعال)
  

• Response: CategoryId
• کاربرد Admin: ایجاد دسته‌بندی جدید (با قابلیت ساختار چند سطحی)

ب. ویرایش دسته‌بندی

• Handler: UpdateDiscountCategoryHandler
• Request: همان فیلدهای بالا + CategoryId
• کاربرد Admin: ویرایش دسته‌بندی موجود

ج. حذف دسته‌بندی

• Handler: DeleteDiscountCategoryHandler
• Request: CategoryId
• Response: Success/Failure
• Logic:
  • چک می‌کند اگر این دسته‌بندی زیرمجموعه دارد → خطا
  • چک می‌کند اگر محصولی به این دسته‌بندی متصل است → خطا
  • در غیر این صورت حذف می‌شود
• کاربرد Admin: حذف ایمن دسته‌بندی

د. دریافت درخت دسته‌بندی‌ها

• Handler: GetDiscountCategoriesHandler
• Request:

  - ParentCategoryId (nullable)
    * اگر null باشد: دسته‌بندی‌های ریشه (Root) برگردانده می‌شود
    * اگر مقدار داشته باشد: زیرمجموعه‌های آن دسته‌بندی برگردانده می‌شود
  - IsActive (nullable - فیلتر فعال/غیرفعال)
  

• Response:

  - List<DiscountCategoryDto> (ساختار recursive با Children)
  

• کاربرد Admin: مشاهده ساختار درختی دسته‌بندی‌ها

---

3️⃣ مدیریت سبد خرید کاربران (5 API)

سرویس: DiscountShoppingCartContract

توجه: این APIها در Admin Panel کمتر استفاده می‌شوند، اما برای Support و Troubleshooting مفید هستند.

الف. افزودن به سبد خرید (Support)

• Handler: AddToCartHandler
• Request: UserId, ProductId, Count
• کاربرد Admin: کمک به کاربر در افزودن محصول به سبد (Support)

ب. حذف از سبد خرید (Support)

• Handler: RemoveFromCartHandler
• Request: UserId, ProductId
• کاربرد Admin: کمک به کاربر در حذف آیتم از سبد

ج. تغییر تعداد آیتم (Support)

• Handler: UpdateCartItemCountHandler
• Request: UserId, ProductId, NewCount
• کاربرد Admin: اصلاح تعداد آیتم در سبد کاربر

د. مشاهده سبد خرید کاربر

• Handler: GetUserCartHandler
• Request: UserId
• Response:

  - List<CartItemDto>
    * ProductId
    * ProductTitle
    * ProductImagePath
    * UnitPrice (قیمت واحد)
    * MaxDiscountPercent
    * Count (تعداد)
    * TotalPrice (قیمت کل = UnitPrice × Count)
    * DiscountAmount (مقدار تخفیف قابل استفاده)
    * FinalPrice (قیمت نهایی بعد از تخفیف)
    * ProductRemainingCount (موجودی باقی‌مانده)
  - TotalPrice (مجموع قیمت کل سبد)
  - TotalDiscountAmount (مجموع تخفیف قابل استفاده)
  - FinalPrice (مجموع قیمت نهایی)
  

• کاربرد Admin: بررسی سبد خرید کاربر برای Support

ه. پاک کردن سبد خرید

• Handler: ClearCartHandler
• Request: UserId
• کاربرد Admin: پاک کردن کامل سبد خرید کاربر (در صورت نیاز)

---

4️⃣ مدیریت سفارشات فروشگاه تخفیفی (5 API)

سرویس: DiscountOrderContract

الف. ثبت سفارش (کمتر استفاده می‌شود در Admin)

• Handler: PlaceOrderHandler
• Request:

  - UserId
  - UserAddressId
  - DiscountBalanceToUse (مقدار کیف پول تخفیف برای استفاده)
  - Notes (nullable - یادداشت)
  

• Response:

  - Success
  - Message
  - OrderId
  - GatewayAmount (مبلغ باقی‌مانده برای پرداخت از طریق درگاه)
  - PaymentUrl (nullable - لینک پرداخت)
  

• کاربرد Admin: ثبت سفارش دستی برای کاربر (نادر)

ب. تکمیل پرداخت سفارش (کمتر استفاده می‌شود)

• Handler: CompleteOrderPaymentHandler
• Request: OrderId, TransactionId, PaymentSuccess
• کاربرد Admin: تایید دستی پرداخت (در صورت مشکل)

ج. تغییر وضعیت ارسال سفارش ⭐ مهم

• Handler: UpdateOrderStatusHandler
• Request:

  - OrderId
  - NewStatus (enum: Pending, Processing, Shipped, Delivered, Cancelled)
  - TrackingCode (nullable - کد رهگیری پست)
  - AdminNotes (nullable - یادداشت ادمین)
  

• Response: Success, Message
• کاربرد Admin:
  • تغییر وضعیت سفارش به "در حال پردازش"
  • ثبت کد رهگیری پست
  • تغییر وضعیت به "ارسال شده"
  • تایید تحویل
  • لغو سفارش

د. مشاهده جزئیات سفارش ⭐ مهم

• Handler: GetOrderByIdHandler
• Request: OrderId
• Response:

  - OrderId
  - UserId
  - UserName (nullable)
  - Address (AddressInfo)
    * Title
    * Address
    * PostalCode
  - OrderItems (List)
    * ProductId
    * ProductTitle
    * ProductPrice (قیمت اسنپ‌شات در زمان خرید)
    * MaxDiscountPercent
    * Count
    * TotalPrice
    * DiscountAmount
    * FinalPrice
  - TotalPrice (مجموع قیمت)
  - DiscountBalanceUsed (مقدار استفاده شده از کیف پول تخفیف)
  - GatewayAmount (مبلغ پرداخت شده از درگاه)
  - PaymentTransactionId (nullable)
  - DeliveryStatus (enum)
  - TrackingCode (nullable)
  - AdminNotes (nullable)
  - Notes (یادداشت کاربر)
  - OrderDate
  - PaymentDate (nullable)
  

• کاربرد Admin: بررسی کامل سفارش

ه. لیست سفارشات کاربر ⭐ مهم

• Handler: GetUserOrdersHandler
• Request:

  - UserId
  - PageNumber
  - PageSize
  

• Response:

  - MetaData (صفحه‌بندی)
  - Models (List<OrderSummaryDto>)
    * OrderId
    * TotalPrice
    * DiscountBalanceUsed
    * GatewayAmount
    * DeliveryStatus
    * ItemsCount (تعداد آیتم‌های سفارش)
    * OrderDate
  

• کاربرد Admin: مشاهده تاریخچه سفارشات کاربر

---

5️⃣ مدیریت گالری تصاویر محصولات (5 API جدید) 🆕

سرویس: DiscountProductContract

توجه: این APIها برای مدیریت چندین تصویر برای هر محصول استفاده می‌شوند (گالری تصاویر).

الف. افزودن تصویر به گالری ⭐ مهم

• Handler: AddDiscountProductImageCommandHandler
• Command: AddDiscountProductImageCommand
• Request:

  - ProductId (Guid)
  - Image (ImageFileModel)
    * File (byte[])
    * FileName (string)
    * Mime (string)
  - SortOrder (int - ترتیب نمایش)
  - IsMain (bool - آیا تصویر اصلی است؟)
  

• Response: ImageId (Guid)
• کاربرد Admin: افزودن تصاویر جدید به گالری محصول

ب. ویرایش تصویر گالری

• Handler: UpdateDiscountProductImageCommandHandler
• Command: UpdateDiscountProductImageCommand
• Request:

  - ImageId (Guid)
  - ProductId (Guid)
  - NewImage (ImageFileModel - اختیاری)
  - SortOrder (int)
  - IsMain (bool)
  

• Response: Success/Failure
• کاربرد Admin: تغییر تصویر موجود یا تغییر ترتیب/اصلی بودن

ج. حذف تصویر از گالری

• Handler: DeleteDiscountProductImageCommandHandler
• Command: DeleteDiscountProductImageCommand
• Request: ImageId (Guid), ProductId (Guid)
• Response: Success/Failure
• کاربرد Admin: حذف تصویر از گالری محصول

د. تغییر ترتیب تصاویر ⭐ مهم

• Handler: ReorderDiscountProductImagesCommandHandler
• Command: ReorderDiscountProductImagesCommand
• Request:

  - ProductId (Guid)
  - ImageOrders (List)
    * ImageId (Guid)
    * SortOrder (int)
  

• Response: Success/Failure
• کاربرد Admin: تغییر ترتیب نمایش تصاویر با drag & drop

ه. دریافت لیست تصاویر محصول

• Handler: GetDiscountProductImagesQueryHandler
• Query: GetDiscountProductImagesQuery
• Request: ProductId (Guid)
• Response:

  - List<ProductImageDto>
    * ImageId (Guid)
    * ImagePath (string)
    * SortOrder (int)
    * IsMain (bool)
    * CreatedAt (DateTime)
  

• کاربرد Admin: نمایش گالری تصاویر محصول

---

6️⃣ گزارشات مدیریتی سفارشات (2 API جدید) 🆕

سرویس: DiscountOrderContract

توجه: این APIها برای گزارش‌گیری و مدیریت کلی سفارشات توسط ادمین استفاده می‌شوند.

الف. لیست کامل سفارشات ⭐⭐⭐ خیلی مهم

• Handler: GetAllDiscountOrdersQueryHandler
• Query: GetAllDiscountOrdersQuery
• Request:

  - PageNumber (int - پیش‌فرض: 1)
  - PageSize (int - پیش‌فرض: 10)
  - UserId (Guid? - فیلتر کاربر)
  - Status (DeliveryStatus? - فیلتر وضعیت)
  - FromDate (DateTime? - از تاریخ)
  - ToDate (DateTime? - تا تاریخ)
  - SearchTerm (string? - جستجو در شماره سفارش/نام کاربر)
  

• Response:

  - MetaData (PaginationMetaData)
    * PageNumber
    * PageSize
    * TotalCount
    * TotalPages
  - Models (List<OrderSummaryDto>)
    * OrderId
    * UserId
    * UserName
    * TotalPrice
    * DiscountBalanceUsed
    * GatewayAmount
    * VatAmount (مالیات ارزش افزوده)
    * DeliveryStatus
    * ItemsCount
    * OrderDate
    * PaymentDate
  

• کاربرد Admin: مشاهده و فیلتر تمام سفارشات فروشگاه تخفیفی

ب. گزارش فروش ⭐⭐ مهم

• Handler: GetDiscountSalesReportQueryHandler
• Query: GetDiscountSalesReportQuery
• Request:

  - FromDate (DateTime? - شروع بازه)
  - ToDate (DateTime? - پایان بازه)
  - ReportType (enum: Daily, Weekly, Monthly)
  

• Response:

  - SalesReportDto
    * TotalOrders (int - تعداد کل سفارشات)
    * TotalRevenue (decimal - مجموع درآمد)
    * TotalVat (decimal - مجموع مالیات)
    * TotalDiscountUsed (decimal - مجموع تخفیف استفاده شده)
    * AverageOrderValue (decimal - میانگین ارزش سفارش)
    * TopSellingProducts (List)
      - ProductId
      - ProductTitle
      - TotalSold
      - TotalRevenue
    * OrdersByStatus (Dictionary<DeliveryStatus, int>)
    * DailyBreakdown (List - جزئیات روزانه)
      - Date
      - OrderCount
      - Revenue
      - VatAmount
  

• کاربرد Admin: تحلیل عملکرد فروش و گزارش‌گیری دوره‌ای

---

📋 لیست کامل Handlerهای مورد نیاز

✅ موجود در BackOffice.BFF (35 Handler)

1. User Management (7)
2. Product Management (5)
3. Order Management (5)
4. Category/Tag (4)
5. Role & Permission (3)
6. Commission System (4)
7. Network Membership (3)
8. Club Membership (4)

✅ تکمیل شده (26 Handler)

گروه 1: Discount Product (5 Handlers)

1. ✅ CreateDiscountProductHandler
2. ✅ UpdateDiscountProductHandler
3. ✅ DeleteDiscountProductHandler
4. ✅ GetDiscountProductByIdHandler
5. ✅ GetDiscountProductsHandler

گروه 2: Discount Category (4 Handlers)

6. ✅ CreateDiscountCategoryHandler
7. ✅ UpdateDiscountCategoryHandler
8. ✅ DeleteDiscountCategoryHandler
9. ✅ GetDiscountCategoriesHandler

گروه 3: Discount Shopping Cart (5 Handlers)

10. ✅ AddToCartHandler (برای Support)
11. ✅ RemoveFromCartHandler (برای Support)
12. ✅ UpdateCartItemCountHandler (برای Support)
13. ✅ GetUserCartHandler ⭐
14. ✅ ClearCartHandler

گروه 4: Discount Order (5 Handlers)

15. ✅ PlaceOrderHandler (کمتر استفاده می‌شود)
16. ✅ CompleteOrderPaymentHandler (کمتر استفاده می‌شود)
17. ✅ UpdateOrderStatusHandler ⭐⭐⭐ خیلی مهم
18. ✅ GetOrderByIdHandler ⭐⭐⭐ خیلی مهم
19. ✅ GetUserOrdersHandler ⭐⭐ مهم

گروه 5: Product Image Gallery (5 Handlers) 🆕

20. ✅ AddDiscountProductImageCommandHandler ⭐ جدید
21. ✅ UpdateDiscountProductImageCommandHandler جدید
22. ✅ DeleteDiscountProductImageCommandHandler جدید
23. ✅ ReorderDiscountProductImagesCommandHandler ⭐ جدید
24. ✅ GetDiscountProductImagesQueryHandler جدید

گروه 6: Admin Order Reports (2 Handlers) 🆕

25. ✅ GetAllDiscountOrdersQueryHandler ⭐⭐⭐ جدید - خیلی مهم
26. ✅ GetDiscountSalesReportQueryHandler ⭐⭐ جدید - مهم

---

🏗️ تغییرات مورد نیاز در BackOffice.BFF

1️⃣ آپدیت IApplicationContractContext

فایل: /BackOffice.BFF/src/BackOffice.BFF.Application/Common/Interfaces/IApplicationContractContext.cs

public interface IApplicationContractContext
{
    // ... existing services ...
    
    // Discount Shop System (NEW - Phase 9)
    DiscountProductContract.DiscountProductContractClient DiscountProducts { get; }
    DiscountCategoryContract.DiscountCategoryContractClient DiscountCategories { get; }
    DiscountShoppingCartContract.DiscountShoppingCartContractClient DiscountShoppingCarts { get; }
    DiscountOrderContract.DiscountOrderContractClient DiscountOrders { get; }
}

2️⃣ پیاده‌سازی در ApplicationContractContext

فایل: /BackOffice.BFF/src/BackOffice.BFF.Infrastructure/Persistence/ApplicationContractContext.cs

public class ApplicationContractContext : IApplicationContractContext
{
    // ... existing implementations ...
    
    // Discount Shop System (NEW)
    public DiscountProductContract.DiscountProductContractClient DiscountProducts { get; }
    public DiscountCategoryContract.DiscountCategoryContractClient DiscountCategories { get; }
    public DiscountShoppingCartContract.DiscountShoppingCartContractClient DiscountShoppingCarts { get; }
    public DiscountOrderContract.DiscountOrderContractClient DiscountOrders { get; }
    
    public ApplicationContractContext(GrpcChannel channel)
    {
        // ... existing initializations ...
        
        // Discount Shop System
        DiscountProducts = new DiscountProductContract.DiscountProductContractClient(channel);
        DiscountCategories = new DiscountCategoryContract.DiscountCategoryContractClient(channel);
        DiscountShoppingCarts = new DiscountShoppingCartContract.DiscountShoppingCartContractClient(channel);
        DiscountOrders = new DiscountOrderContract.DiscountOrderContractClient(channel);
    }
}

3️⃣ ایجاد Handlerها

ساختار فولدر:

BackOffice.BFF.Application/
└── DiscountShop/
    ├── Products/
    │   ├── CreateDiscountProduct/
    │   │   ├── CreateDiscountProductCommand.cs
    │   │   └── CreateDiscountProductHandler.cs
    │   ├── UpdateDiscountProduct/
    │   ├── DeleteDiscountProduct/
    │   ├── GetDiscountProductById/
    │   └── GetDiscountProducts/
    ├── Categories/
    │   ├── CreateDiscountCategory/
    │   ├── UpdateDiscountCategory/
    │   ├── DeleteDiscountCategory/
    │   └── GetDiscountCategories/
    ├── Cart/
    │   ├── AddToCart/
    │   ├── RemoveFromCart/
    │   ├── UpdateCartItemCount/
    │   ├── GetUserCart/
    │   └── ClearCart/
    └── Orders/
        ├── PlaceOrder/
        ├── CompleteOrderPayment/
        ├── UpdateOrderStatus/
        ├── GetOrderById/
        └── GetUserOrders/

---

🎨 UI Pages مورد نیاز در BackOffice

صفحات جدید (6 صفحه)

1. صفحه لیست محصولات فروشگاه تخفیفی (2 روز)

   • Pages/DiscountShop/Products/ProductsList.razor
   • DataGrid با فیلترها
   • دکمه‌های Create, Edit, Delete
   • نمایش موجودی و MaxDiscountPercent

2. صفحه ایجاد/ویرایش محصول (1 روز)

   • Pages/DiscountShop/Products/ProductForm.razor
   • فرم کامل با تمام فیلدها
   • انتخاب چندتایی دسته‌بندی
   • آپلود تصویر

3. صفحه مدیریت دسته‌بندی‌ها (1.5 روز)

   • Pages/DiscountShop/Categories/CategoriesList.razor
   • نمایش درختی (Tree View)
   • قابلیت Drag & Drop برای تغییر Parent
   • Dialog ایجاد/ویرایش

4. صفحه لیست سفارشات فروشگاه (2 روز)

   • Pages/DiscountShop/Orders/OrdersList.razor
   • DataGrid با فیلترها (Status, Date Range, User)
   • نمایش خلاصه: TotalPrice, DiscountUsed, GatewayAmount
   • دکمه View Details

5. صفحه جزئیات سفارش (1.5 روز)

   • Pages/DiscountShop/Orders/OrderDetails.razor
   • نمایش کامل اطلاعات سفارش
   • لیست آیتم‌های سفارش
   • تغییر وضعیت ارسال (Dropdown)
   • ثبت کد رهگیری
   • یادداشت ادمین

6. صفحه مشاهده سبد خرید کاربر (1 روز)

   • Pages/DiscountShop/Support/UserCart.razor
   • برای Support و Troubleshooting
   • نمایش محاسبات تخفیف
   • قابلیت اصلاح (Add/Remove/Update)

جمع زمان UI: 9 روز

---

📊 گزارشات مالی جدید (اختیاری - اولویت متوسط)

گزارشات پیشنهادی:

1. گزارش فروش فروشگاه تخفیفی

   • مجموع فروش (TotalPrice)
   • مجموع تخفیف استفاده شده (DiscountBalanceUsed)
   • مجموع پرداخت از درگاه (GatewayAmount)
   • تفکیک بر اساس تاریخ، محصول، دسته‌بندی

2. گزارش محبوب‌ترین محصولات

   • تعداد فروش هر محصول
   • مجموع درآمد
   • میانگین استفاده از تخفیف

3. گزارش وضعیت موجودی

   • محصولات کم موجودی (RemainingCount < حد آستانه)
   • هشدار اتمام موجودی

4. گزارش استفاده از کیف پول تخفیف

   • کاربران برتر در استفاده از تخفیف
   • میانگین درصد استفاده از تخفیف
   • مقایسه با فروش کل

---

⏱️ تخمین زمان پیاده‌سازی

BackOffice.BFF (Backend)

مرحله	زمان	توضیحات
آپدیت Interface & Context	30 دقیقه	اضافه کردن 4 Client
ایجاد 19 Handler	3 روز	~20 دقیقه هر Handler
Test & Debug	1 روز	تست تمام Handlerها
جمع	4 روز

BackOffice UI (Frontend)

مرحله	زمان	توضیحات
صفحات محصولات (2 صفحه)	3 روز	List + Form
صفحات دسته‌بندی (1 صفحه)	1.5 روز	Tree View
صفحات سفارشات (2 صفحه)	3.5 روز	List + Details
صفحه Support (سبد خرید)	1 روز
جمع	9 روز

جمع کل: 13 روز کاری (~2.5 هفته)

---

🚀 اولویت‌بندی پیاده‌سازی

فاز 1: حداقل قابل استفاده (MVP) - 5 روز

✅ اولویت بالا

1. Handlerهای مدیریت محصولات (5)
2. Handlerهای مدیریت دسته‌بندی (4)
3. Handler مشاهده جزئیات سفارش (1)
4. Handler تغییر وضعیت سفارش (1)
5. صفحه لیست محصولات + فرم
6. صفحه لیست سفارشات + جزئیات

فاز 2: قابلیت‌های Support - 3 روز

🟡 اولویت متوسط

1. Handlerهای سبد خرید (5)
2. Handler لیست سفارشات کاربر (1)
3. صفحه مدیریت دسته‌بندی
4. صفحه Support سبد خرید

فاز 3: گزارشات و آمار - 5 روز

🟢 اولویت پایین (می‌تواند بعداً اضافه شود)

1. گزارشات مالی
2. داشبورد فروش فروشگاه
3. چارت‌های تحلیلی

---

📝 نکات مهم

⚠️ نکته 1: MaxDiscountPercent

این فیلد بسیار مهم است:

• مشخص می‌کند کاربر حداکثر چند درصد از قیمت محصول را می‌تواند با کیف پول تخفیف پرداخت کند
• مثال: قیمت = 1,000,000 تومان، MaxDiscountPercent = 70%
  • حداکثر تخفیف: 700,000 تومان
  • مبلغ باقی‌مانده (300,000 تومان) باید از درگاه پرداخت شود

⚠️ نکته 2: Snapshot محصول

وقتی سفارش ثبت می‌شود، اطلاعات محصول (عنوان، قیمت، MaxDiscountPercent) در جدول DiscountOrderItem ذخیره می‌شود:

• این اطلاعات Snapshot هستند و حتی اگر محصول بعداً ویرایش شود، سفارش تغییر نمی‌کند
• برای گزارش‌گیری دقیق مالی ضروری است

⚠️ نکته 3: Hybrid Payment Flow

جریان پرداخت ترکیبی:

1. کاربر سفارش ثبت می‌کند → PlaceOrder
2. CMS محاسبه می‌کند چقدر از کیف پول تخفیف استفاده شود
3. مبلغ باقی‌مانده (GatewayAmount) به کاربر نمایش داده می‌شود
4. کاربر به درگاه پرداخت می‌رود
5. بعد از بازگشت از درگاه → CompleteOrderPayment
6. CMS تراکنش را Verify می‌کند و DiscountBalance را کم می‌کند

⚠️ نکته 4: Stock Management

• هنگام PlaceOrder: RemainingCount کم می‌شود (Reserve)
• اگر پرداخت ناموفق باشد: باید موجودی برگردانده شود (در CompleteOrderPayment)
• Admin باید بتواند موجودی را دستی تغییر دهد

⚠️ نکته 5: VAT Calculation 🆕

• مالیات ارزش افزوده (VAT) 10% برای هر سفارش محاسبه می‌شود
• VAT روی قیمت نهایی (بعد از تخفیف) محاسبه می‌شود
• فیلد VatAmount در هر سفارش ذخیره می‌شود
• در گزارش فروش، مجموع VAT جداگانه نمایش داده می‌شود

---

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

• CMS Implementation Progress - Phase 9 Details
• REMAINING-TASKS-CONSOLIDATED - Overall Project Status
• BackOffice.BFF CMS Integration - Existing Integration Guide
• CHANGELOG-2025-12-31 - تغییرات این سشن 🆕

---

✅ Checklist پیاده‌سازی

Backend (BackOffice.BFF) - ✅ تکمیل شده

• آپدیت IApplicationContractContext (4 Client)
• آپدیت ApplicationContractContext (Implementation)
• ایجاد 5 Handler محصولات
• ایجاد 4 Handler دسته‌بندی
• ایجاد 5 Handler سبد خرید
• ایجاد 5 Handler سفارشات
• ایجاد 5 Handler گالری تصاویر 🆕
• ایجاد 2 Handler گزارش سفارشات 🆕
• ایجاد DiscountProductService (gRPC) 🆕
• ایجاد DiscountOrderService (gRPC) 🆕
• تست تمام Handlerها
• آپدیت مستندات cms-integration.md

Frontend (BackOffice UI)

• صفحه لیست محصولات
• صفحه فرم محصول (Create/Edit)
• صفحه مدیریت دسته‌بندی‌ها
• صفحه لیست سفارشات
• صفحه جزئیات سفارش
• صفحه Support سبد خرید
• صفحه گالری تصاویر محصول 🆕
• صفحه گزارش فروش 🆕
• تست UI با داده واقعی

---

🎉 وضعیت نهایی

Backend کاملاً آماده! ✅

تمام APIهای لازم برای:

• مدیریت محصولات (CRUD + گالری تصاویر)
• مدیریت دسته‌بندی‌ها
• پشتیبانی سبد خرید
• مدیریت سفارشات
• گزارش‌گیری فروش

در لایه‌های BFF Application و WebApi پیاده‌سازی شده‌اند. 🚀