Refactor code structure for improved readability and maintainability

2026-02-16 00:59:16 +03:30
parent 956a9ff6d6
commit ad31c8be97
10 changed files with 3388 additions and 3 deletions
@@ -0,0 +1,196 @@
+# فروشگاه تخفیفی — وضعیت پیاده‌سازی و تسک‌ها
+
+> **تاریخ:** ۱۴۰۴/۱۱/۲۲ (2026-02-11)
+> **آخرین بروزرسانی:** ۱۴۰۴/۱۱/۲۳
+> **وضعیت کلی:** بکند کامل ✅ | بک‌آفیس کامل ✅ | فرانت‌آفیس کامل ✅
+
+---
+
+## ۱. خلاصه بیزینس
+
+فروشگاه تخفیفی یک فروشگاه **مجزا** از فروشگاه معمولی است که:
+- محصولات خاص خود را دارد (`DiscountProduct` — نه `Product`)
+- پرداخت **ترکیبی** (Hybrid) دارد:
+  - بخشی از **موجودی کیف پول تخفیفی** (`DiscountBalance`) کسر می‌شود
+  - مابقی از **درگاه پرداخت** (IPG) پرداخت می‌شود
+- هر محصول یک `MaxDiscountPercent` دارد (مثلاً ۳۰٪) — حداکثر درصدی که از کیف تخفیفی قابل پرداخت است
+- مالیات فقط روی مبلغ درگاه محاسبه می‌شود
+
+---
+
+## ۲. وضعیت لایه‌ها
+
+### ✅ Domain Entities — کامل (۷ entity)
+
+| Entity | مسیر | توضیح |
+|--------|------|-------|
+| `DiscountProduct` | `CMS/.../Entities/DiscountStore/` | محصول (Title, Price, MaxDiscountPercent, RemainingCount, ...) |
+| `DiscountProductCategory` | ↑ | دسته‌بندی درختی |
+| `DiscountProductCategoryMapping` | ↑ | M:N محصول ↔ دسته‌بندی |
+| `DiscountProductImage` | ↑ | گالری تصاویر |
+| `DiscountShoppingCart` | ↑ | سبد خرید (UserId, ProductId, Count) |
+| `DiscountOrder` | ↑ | سفارش (TotalAmount, DiscountBalanceUsed, GatewayAmountPaid, VAT) |
+| `DiscountOrderDetail` | ↑ | جزئیات سفارش (UnitPrice, DiscountPercent, DiscountAmount, FinalPrice) |
+
+### ✅ EF Configurations — کامل (۷ فایل + ۶ migration)
+
+### ✅ Application (CQRS) — کامل (~۵۰ فایل)
+- DiscountProductCQ: Create, Update, Delete, GetById, GetProducts + Image CRUD
+- DiscountCategoryCQ: Create, Update, Delete, GetCategories
+- DiscountOrderCQ: PlaceOrder, CompleteOrderPayment, UpdateOrderStatus, GetById, GetUserOrders, GetAll, SalesReport
+- DiscountShoppingCartCQ: AddToCart, RemoveFromCart, UpdateCount, GetUserCart, ClearCart
+- WalletCQ: ChargeDiscountWallet, VerifyDiscountWalletCharge
+
+### ✅ Proto Definitions — کامل (۴ فایل)
+
+| Proto | Namespace | RPCs |
+|-------|-----------|------|
+| `discountproduct.proto` | `CMSMicroservice.Protobuf.Protos.DiscountProduct` | DiscountProductContract (10 RPCs) |
+| `discountcategory.proto` | `CMSMicroservice.Protobuf.Protos.DiscountCategory` | DiscountCategoryContract (4 RPCs) |
+| `discountshoppingcart.proto` | `CMSMicroservice.Protobuf.Protos.DiscountShoppingCart` | DiscountShoppingCartContract (5 RPCs) |
+| `discountorder.proto` | `CMSMicroservice.Protobuf.Protos.DiscountOrder` | DiscountOrderContract (7 RPCs) |
+
+### ✅ gRPC Services (CMS WebApi) — کامل (۴ سرویس + mapping)
+
+### ✅ BackOffice (Admin Panel) — کامل
+- ۴ صفحه: محصولات، دسته‌بندی‌ها، سفارشات، گزارش فروش
+- ۵ کامپوننت: فرم محصول، فرم دسته‌بندی، گالری، جزئیات سفارش، تغییر وضعیت
+- ۶ سرویس: DiscountProduct, DiscountCategory, DiscountOrder (+ interfaces)
+- NavMenu: بخش "فروشگاه تخفیفی" با ۳ لینک (محصولات، دسته‌بندی‌ها، سفارشات و گزارش)
+- **یکسان‌سازی UI (بهمن ۱۴۰۴):** تمام صفحات فروشگاه تخفیفی بازنویسی شدند تا از `BasePageComponent` استفاده کنند و ظاهری یکسان با فروشگاه عادی داشته باشند → [جزئیات](../ui-modernization/BACKOFFICE-STORE-UNIFICATION.md)
+
+### ✅ FrontOffice (مشتری) — پیاده‌سازی شده!
+
+**فایل‌های اضافه/ویرایش شده:**
+
+| فایل | نوع | توضیح |
+|------|------|-------|
+| `Utilities/RouteConstants.cs` | ویرایش | اضافه شدن بخش `DiscountStore` (6 مسیر) |
+| `ConfigureServices.cs` | ویرایش | ثبت 3 سرویس + 4 gRPC client |
+| `Utilities/DiscountProductService.cs` | جدید | سرویس محصولات تخفیفی (GetProducts, GetById, GetCategories) |
+| `Utilities/DiscountCartService.cs` | جدید | سرویس سبد خرید تخفیفی (Add, Remove, Update, Clear) |
+| `Utilities/DiscountOrderService.cs` | جدید | سرویس سفارش تخفیفی (PlaceOrder, CompletePayment, GetOrders) |
+| `Pages/DiscountStore/Products.razor(.cs)` | جدید | لیست محصولات (جستجو + فیلتر دسته‌بندی + صفحه‌بندی) |
+| `Pages/DiscountStore/ProductDetail.razor(.cs)` | جدید | جزئیات محصول + گالری + افزودن به سبد |
+| `Pages/DiscountStore/Cart.razor(.cs)` | جدید | سبد خرید (Desktop: Table / Mobile: Cards) |
+| `Pages/DiscountStore/Checkout.razor(.cs)` | جدید | پرداخت ترکیبی (آدرس + اسلایدر تخفیف + درگاه) |
+| `Pages/DiscountStore/Orders.razor(.cs)` | جدید | لیست سفارشات (پرداخت/ارسال) |
+| `Pages/DiscountStore/OrderDetail.razor(.cs)` | جدید | جزئیات سفارش + خلاصه مالی |
+| `Pages/Profile/Index.razor.cs` | ویرایش | تایل "فروشگاه تخفیفی" در داشبورد |
+| `Shared/MainLayout.razor` | ویرایش | لینک ناوبری دسکتاپ + drawer موبایل |
+| `wwwroot/css/site.css` | ویرایش | ریجن CSS اختصاصی Discount Store |
+
+---
+
+## ۳. تسک‌های FrontOffice (ترتیب اجرا)
+
+### تسک ۱: Routes — اضافه کردن مسیرها
+```
+فایل: RouteConstants.cs
+اضافه: public static class DiscountStore {
+    Products = "/discount-store"
+    ProductDetail = "/discount-store/product/"
+    Cart = "/discount-store/cart"
+    Checkout = "/discount-store/checkout"
+    Orders = "/discount-store/orders"
+    OrderDetail = "/discount-store/order/"
+}
+```
+
+### تسک ۲: gRPC Clients — ثبت DI
+```
+فایل: ConfigureServices.cs
+اضافه:
+  using CMSMicroservice.Protobuf.Protos.DiscountProduct;
+  using CMSMicroservice.Protobuf.Protos.DiscountCategory;
+  using CMSMicroservice.Protobuf.Protos.DiscountShoppingCart;
+  using CMSMicroservice.Protobuf.Protos.DiscountOrder;
+  
+  services.AddScoped(CreateAuthenticatedClient<DiscountProductContract.DiscountProductContractClient>);
+  services.AddScoped(CreateAuthenticatedClient<DiscountCategoryContract.DiscountCategoryContractClient>);
+  services.AddScoped(CreateAuthenticatedClient<DiscountShoppingCartContract.DiscountShoppingCartContractClient>);
+  services.AddScoped(CreateAuthenticatedClient<DiscountOrderContract.DiscountOrderContractClient>);
+```
+
+### تسک ۳: Services — سرویس‌های FrontOffice
+```
+فایل‌های جدید در Utilities/:
+  DiscountProductService.cs — GetProducts (فیلتر + صفحه‌بندی), GetById, GetCategories
+  DiscountCartService.cs    — Add, Remove, Update, GetCart, Clear + event OnChange
+  DiscountOrderService.cs   — PlaceOrder, CompletePayment, GetUserOrders, GetOrderById
+```
+
+### تسک ۴: صفحات Blazor
+```
+فایل‌های جدید در Pages/DiscountStore/:
+  Products.razor + .cs      — لیست محصولات (فیلتر دسته‌بندی + جستجو + صفحه‌بندی)
+  ProductDetail.razor + .cs — جزئیات محصول + گالری + افزودن به سبد
+  Cart.razor + .cs          — سبد خرید (نمایش تخفیف هر آیتم)
+  Checkout.razor + .cs      — پرداخت (انتخاب آدرس + تعیین مبلغ از تخفیفی + درگاه)
+  Orders.razor + .cs        — لیست سفارشات
+  OrderDetail.razor + .cs   — جزئیات سفارش + وضعیت ارسال
+```
+
+### تسک ۵: Dashboard Tile
+```
+فایل: Profile/Index.razor.cs
+اضافه: تایل "فروشگاه تخفیفی" بعد از تایل "فروشگاه" موجود
+```
+
+### تسک ۶: Navigation
+```
+فایل: MainLayout.razor
+اضافه: لینک "فروشگاه تخفیفی" در drawer موبایل + bottom nav (اختیاری)
+```
+
+### تسک ۷: CSS
+```
+فایل: site.css
+اضافه: استایل‌های اختصاصی (checkout progress, discount badge, ...)
+```
+
+---
+
+## ۴. فلوی پرداخت (مهم!)
+
+```
+کاربر سبد خرید دارد
+         ↓
+صفحه Checkout:
+  ├─ انتخاب آدرس تحویل
+  ├─ نمایش خلاصه سبد:
+  │     هر محصول: قیمت × تعداد
+  │     تخفیف هر محصول: price × count × maxDiscountPercent / 100
+  │     جمع کل / جمع تخفیف / مبلغ درگاه
+  ├─ موجودی تخفیفی کاربر: XXX تومان
+  ├─ کاربر تعیین می‌کند چقدر از تخفیفی استفاده کند (≤ سقف مجاز)
+  └─ [پرداخت]
+         ↓
+PlaceOrder RPC:
+  ├─ بررسی موجودی + محاسبه
+  ├─ ساخت سفارش (Pending)
+  ├─ رزرو موجودی انبار
+  ├─ اگر gateway_amount > 0 → payment_url برگردانده می‌شود
+  └─ اگر gateway_amount = 0 → سفارش مستقیم تکمیل
+         ↓
+ریدایرکت به درگاه (اگر لازم باشد)
+         ↓
+CompleteOrderPayment RPC (بعد از callback):
+  ├─ success → کسر DiscountBalance + تأیید فروش + ثبت تراکنش
+  └─ failure → آزادسازی رزرو انبار + لغو سفارش
+```
+
+---
+
+## ۵. تخمین زمان
+
+| تسک | تخمین |
+|-----|-------|
+| Routes + DI + Services | ۱ ساعت |
+| Products + ProductDetail | ۲ ساعت |
+| Cart | ۱ ساعت |
+| Checkout (پیچیده‌ترین بخش) | ۲ ساعت |
+| Orders + OrderDetail | ۱ ساعت |
+| Dashboard tile + Nav | ۰.۵ ساعت |
+| CSS + Polish | ۰.۵ ساعت |
+| **مجموع** | **~۸ ساعت** |