- Added last updated date and refined project status for Backend and Frontend. - Updated completion percentages for FrontOffice UI and BFF. - Documented completed tasks for BackOffice in the current sprint. - Added new high-priority tasks related to commission calculation fixes. - Resolved blockers and minor issues, providing a clearer progress summary. docs: Create commission-calculation-fix.md for weekly commission calculation analysis - Documented critical issues affecting commission calculations. - Provided a detailed plan for fixing the commission calculation logic. - Included code analysis, affected files, and step-by-step tasks for implementation. - Outlined the expected timeline and important notes regarding changes.
22 KiB
BackOffice.BFF - Discount Shop Integration Plan
تاریخ ایجاد: 1403/09/13 (2024-12-04)
آخرین بروزرسانی: 1403/09/14 (2024-12-05)
وضعیت: ✅ پیادهسازی شده (Plan اجرا شده است)
اولویت در زمان طراحی: 🔴 بالا
📊 خلاصه وضعیت
✅ تکمیل شده در 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
⏳ وضعیت در BackOffice.BFF (بهروزرسانی)
- 19 Handler برای 4 سرویس جدید → ✅ پیادهسازی و متصل به CMS
- 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: مشاهده تاریخچه سفارشات کاربر
📋 لیست کامل Handlerهای مورد نیاز
✅ موجود در BackOffice.BFF (35 Handler)
- User Management (7)
- Product Management (5)
- Order Management (5)
- Category/Tag (4)
- Role & Permission (3)
- Commission System (4)
- Network Membership (3)
- Club Membership (4)
⏳ نیاز به ایجاد (19 Handler)
گروه 1: Discount Product (5 Handlers)
- ✅
CreateDiscountProductHandler - ✅
UpdateDiscountProductHandler - ✅
DeleteDiscountProductHandler - ✅
GetDiscountProductByIdHandler - ✅
GetDiscountProductsHandler
گروه 2: Discount Category (4 Handlers)
- ✅
CreateDiscountCategoryHandler - ✅
UpdateDiscountCategoryHandler - ✅
DeleteDiscountCategoryHandler - ✅
GetDiscountCategoriesHandler
گروه 3: Discount Shopping Cart (5 Handlers)
- ✅
AddToCartHandler(برای Support) - ✅
RemoveFromCartHandler(برای Support) - ✅
UpdateCartItemCountHandler(برای Support) - ✅
GetUserCartHandler⭐ - ✅
ClearCartHandler
گروه 4: Discount Order (5 Handlers)
- ✅
PlaceOrderHandler(کمتر استفاده میشود) - ✅
CompleteOrderPaymentHandler(کمتر استفاده میشود) - ✅
UpdateOrderStatusHandler⭐⭐⭐ خیلی مهم - ✅
GetOrderByIdHandler⭐⭐⭐ خیلی مهم - ✅
GetUserOrdersHandler⭐⭐ مهم
🏗️ تغییرات مورد نیاز در 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 صفحه)
-
صفحه لیست محصولات فروشگاه تخفیفی (2 روز)
Pages/DiscountShop/Products/ProductsList.razor- DataGrid با فیلترها
- دکمههای Create, Edit, Delete
- نمایش موجودی و MaxDiscountPercent
-
صفحه ایجاد/ویرایش محصول (1 روز)
Pages/DiscountShop/Products/ProductForm.razor- فرم کامل با تمام فیلدها
- انتخاب چندتایی دستهبندی
- آپلود تصویر
-
صفحه مدیریت دستهبندیها (1.5 روز)
Pages/DiscountShop/Categories/CategoriesList.razor- نمایش درختی (Tree View)
- قابلیت Drag & Drop برای تغییر Parent
- Dialog ایجاد/ویرایش
-
صفحه لیست سفارشات فروشگاه (2 روز)
Pages/DiscountShop/Orders/OrdersList.razor- DataGrid با فیلترها (Status, Date Range, User)
- نمایش خلاصه: TotalPrice, DiscountUsed, GatewayAmount
- دکمه View Details
-
صفحه جزئیات سفارش (1.5 روز)
Pages/DiscountShop/Orders/OrderDetails.razor- نمایش کامل اطلاعات سفارش
- لیست آیتمهای سفارش
- تغییر وضعیت ارسال (Dropdown)
- ثبت کد رهگیری
- یادداشت ادمین
-
صفحه مشاهده سبد خرید کاربر (1 روز)
Pages/DiscountShop/Support/UserCart.razor- برای Support و Troubleshooting
- نمایش محاسبات تخفیف
- قابلیت اصلاح (Add/Remove/Update)
جمع زمان UI: 9 روز
📊 گزارشات مالی جدید (اختیاری - اولویت متوسط)
گزارشات پیشنهادی:
-
گزارش فروش فروشگاه تخفیفی
- مجموع فروش (TotalPrice)
- مجموع تخفیف استفاده شده (DiscountBalanceUsed)
- مجموع پرداخت از درگاه (GatewayAmount)
- تفکیک بر اساس تاریخ، محصول، دستهبندی
-
گزارش محبوبترین محصولات
- تعداد فروش هر محصول
- مجموع درآمد
- میانگین استفاده از تخفیف
-
گزارش وضعیت موجودی
- محصولات کم موجودی (RemainingCount < حد آستانه)
- هشدار اتمام موجودی
-
گزارش استفاده از کیف پول تخفیف
- کاربران برتر در استفاده از تخفیف
- میانگین درصد استفاده از تخفیف
- مقایسه با فروش کل
⏱️ تخمین زمان پیادهسازی
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 روز
✅ اولویت بالا
- Handlerهای مدیریت محصولات (5)
- Handlerهای مدیریت دستهبندی (4)
- Handler مشاهده جزئیات سفارش (1)
- Handler تغییر وضعیت سفارش (1)
- صفحه لیست محصولات + فرم
- صفحه لیست سفارشات + جزئیات
فاز 2: قابلیتهای Support - 3 روز
🟡 اولویت متوسط
- Handlerهای سبد خرید (5)
- Handler لیست سفارشات کاربر (1)
- صفحه مدیریت دستهبندی
- صفحه Support سبد خرید
فاز 3: گزارشات و آمار - 5 روز
🟢 اولویت پایین (میتواند بعداً اضافه شود)
- گزارشات مالی
- داشبورد فروش فروشگاه
- چارتهای تحلیلی
📝 نکات مهم
⚠️ نکته 1: MaxDiscountPercent
این فیلد بسیار مهم است:
- مشخص میکند کاربر حداکثر چند درصد از قیمت محصول را میتواند با کیف پول تخفیف پرداخت کند
- مثال: قیمت = 1,000,000 تومان، MaxDiscountPercent = 70%
- حداکثر تخفیف: 700,000 تومان
- مبلغ باقیمانده (300,000 تومان) باید از درگاه پرداخت شود
⚠️ نکته 2: Snapshot محصول
وقتی سفارش ثبت میشود، اطلاعات محصول (عنوان، قیمت، MaxDiscountPercent) در جدول DiscountOrderItem ذخیره میشود:
- این اطلاعات Snapshot هستند و حتی اگر محصول بعداً ویرایش شود، سفارش تغییر نمیکند
- برای گزارشگیری دقیق مالی ضروری است
⚠️ نکته 3: Hybrid Payment Flow
جریان پرداخت ترکیبی:
- کاربر سفارش ثبت میکند →
PlaceOrder - CMS محاسبه میکند چقدر از کیف پول تخفیف استفاده شود
- مبلغ باقیمانده (GatewayAmount) به کاربر نمایش داده میشود
- کاربر به درگاه پرداخت میرود
- بعد از بازگشت از درگاه →
CompleteOrderPayment - CMS تراکنش را Verify میکند و DiscountBalance را کم میکند
⚠️ نکته 4: Stock Management
- هنگام
PlaceOrder: RemainingCount کم میشود (Reserve) - اگر پرداخت ناموفق باشد: باید موجودی برگردانده شود (در CompleteOrderPayment)
- Admin باید بتواند موجودی را دستی تغییر دهد
📚 مستندات مرتبط
- CMS Implementation Progress - Phase 9 Details
- REMAINING-TASKS-CONSOLIDATED - Overall Project Status
- BackOffice.BFF CMS Integration - Existing Integration Guide
✅ Checklist پیادهسازی
Backend (BackOffice.BFF)
- آپدیت IApplicationContractContext (4 Client)
- آپدیت ApplicationContractContext (Implementation)
- ایجاد 5 Handler محصولات
- ایجاد 4 Handler دستهبندی
- ایجاد 5 Handler سبد خرید
- ایجاد 5 Handler سفارشات
- تست تمام Handlerها
- آپدیت مستندات cms-integration.md
Frontend (BackOffice UI)
- صفحه لیست محصولات
- صفحه فرم محصول (Create/Edit)
- صفحه مدیریت دستهبندیها
- صفحه لیست سفارشات
- صفحه جزئیات سفارش
- صفحه Support سبد خرید
- تست UI با داده واقعی
آماده شروع پیادهسازی؟ 🚀