docs: add session log for 2026-05-13 (guest browsing + top-seller landing sections)

Co-authored-by: Cursor <cursoragent@cursor.com>

INDEX.md

@@ -1,108 +0,0 @@
-# 📚 FourSat Documentation Index
-
-> آخرین بروزرسانی: February 17, 2026  
-> ۲۲۰ فایل → ۳۰ فایل (تجمیع ۳ فازی + cleanup نهایی)
-
----
-
-## 🔍 راهنمای سریع — کدام مستند را باید ببینم؟
-
-| می‌خواهم بدانم... | مستند |
-|-------------------|-------|
-| **کل تغییرات BackOffice چه بوده؟** | [`BackOffice/docs/BACKOFFICE-CHANGELOG.md`](../BackOffice/docs/BACKOFFICE-CHANGELOG.md) |
-| **ساختار و معماری BackOffice چیست؟** | [`ui-modernization/BACKOFFICE-ARCHITECTURE.md`](ui-modernization/BACKOFFICE-ARCHITECTURE.md) |
-| **یکسان‌سازی فروشگاه‌ها چه بوده؟** | [`ui-modernization/BACKOFFICE-STORE-UNIFICATION.md`](ui-modernization/BACKOFFICE-STORE-UNIFICATION.md) |
-| **وضعیت فروشگاه تخفیفی؟** | [`business/DISCOUNT-STORE-STATUS.md`](business/DISCOUNT-STORE-STATUS.md) |
-| **بیزینس فروشگاه تخفیفی چگونه کار می‌کند؟** | [`business/discount-shop-business.md`](business/discount-shop-business.md) |
-| **سیستم کمیسیون چگونه کار می‌کند؟** | [`business/club-commission-system-complete.md`](business/club-commission-system-complete.md) |
-| **چگونه deploy کنم؟** | [`deployment/OFFLINE-DEPLOYMENT-GUIDE.md`](deployment/OFFLINE-DEPLOYMENT-GUIDE.md) |
-| **وضعیت CI/CD چیست؟** | [`deployment/CICD-PIPELINE-GUIDE.md`](deployment/CICD-PIPELINE-GUIDE.md) |
-| **مشخصات سرور و زیرساخت؟** | [`deployment/INFRASTRUCTURE-GUIDE.md`](deployment/INFRASTRUCTURE-GUIDE.md) |
-| **مهاجرت BFF→CMS چگونه بوده؟** | [`migration/BACKOFFICE-BFF-MIGRATION.md`](migration/BACKOFFICE-BFF-MIGRATION.md) |
-| **مهاجرت FrontOffice→CMS؟** | [`migration/FRONTOFFICE-TO-CMS-MIGRATION.md`](migration/FRONTOFFICE-TO-CMS-MIGRATION.md) |
-| **نقشه نوسازی UI فرانت؟** | [`ui-modernization/UI-MODERNIZATION-PLAN.md`](ui-modernization/UI-MODERNIZATION-PLAN.md) |
-| **معماری مدیریت فایل و تصاویر؟** | [`cms/FILE-MANAGEMENT-ARCHITECTURE.md`](cms/FILE-MANAGEMENT-ARCHITECTURE.md) |
-| **فیکس فلوی ثبت‌نام FrontOffice؟** | [`cms/REGISTRATION-FLOW-FIXES.md`](cms/REGISTRATION-FLOW-FIXES.md) |
-| **Audit report کامل BackOffice؟** | [`BackOffice/docs/BACKOFFICE-AUDIT.md`](../BackOffice/docs/BACKOFFICE-AUDIT.md) |
-
----
-
-## 📂 business/ — مستندات بیزنسی (۷ فایل)
-
-| فایل | توضیح |
-|------|-------|
-| [club-commission-system-complete.md](business/club-commission-system-complete.md) | 🏆 سیستم جامع کمیسیون باشگاه: کیف پول‌ها، درخت باینری، الگوریتم کمیسیون، توزیع Pool |
-| [balance-calculation-rules.md](business/balance-calculation-rules.md) | قوانین محاسبه تعادل + فرمول‌های Excel + مثال‌های ۵ سطحی |
-| [club-membership-contract-system.md](business/club-membership-contract-system.md) | سیستم قرارداد عضویت: امضا، OTP، رفرش توکن |
-| [package-purchase-system.md](business/package-purchase-system.md) | ۳ سناریو خرید پکیج: وام دایا، پرداخت دستی، درگاه |
-| [daya-loan-integration.md](business/daya-loan-integration.md) | یکپارچه‌سازی وام دایا + جزئیات API + پیاده‌سازی CMS |
-| [discount-shop-business.md](business/discount-shop-business.md) | فروشگاه تخفیفی: پرداخت ترکیبی، درصد تخفیف، entity design |
-| [manual-payment-system.md](business/manual-payment-system.md) | پرداخت دستی: کارت به کارت، تأیید ادمین، آپلود FMS |
-
-## 📂 cms/ — مستندات فنی CMS (۱۵ فایل)
-
-| فایل | توضیح |
-|------|-------|
-| [BFF-REMOVAL-PLAN.md](cms/BFF-REMOVAL-PLAN.md) | ✅ پلن حذف BFF — Permission Interceptor + تغییرات config |
-| [REMAINING-TASKS.md](cms/REMAINING-TASKS.md) | وضعیت ۴۹/۴۹ متد — همه انجام شده ✅ |
-| [FRONTOFFICE-CMS-API-COMPATIBILITY.md](cms/FRONTOFFICE-CMS-API-COMPATIBILITY.md) | ماتریس سازگاری API بین FrontOffice و CMS |
-| [ICURRENTUSERSERVICE-IMPLEMENTATION.md](cms/ICURRENTUSERSERVICE-IMPLEMENTATION.md) | پترن JWT + ICurrentUserService در endpointهای Customer |
-| [ADMIN-CUSTOMER-SEPARATION-FIX.md](cms/ADMIN-CUSTOMER-SEPARATION-FIX.md) | 🆕 فیکس جداسازی Admin/Customer: حذف JWT fallback از ۸ handler + resolve صریح در ۴ endpoint |
-| [payment-gateway.md](cms/payment-gateway.md) | IPaymentGatewayService: Mock vs Daya، پیاده‌سازی payout |
-| [payment-architecture-pyms.md](cms/payment-architecture-pyms.md) | معماری PYMS: جریان پرداخت BFF→PYMS→Gateway→CMS |
-| [chatika-integration.md](cms/chatika-integration.md) | یکپارچه‌سازی Chatika AI: Hangfire worker، retry logic |
-| [club-feature-management-services.md](cms/club-feature-management-services.md) | CQRS سرویس‌های مدیریت ClubFeature |
-| [INVENTORY-REFACTORING-STATUS.md](cms/INVENTORY-REFACTORING-STATUS.md) | ریفکتور Inventory: حذف Repository، ساختار CQ |
-| [system-constants.md](cms/system-constants.md) | مرجع SystemConstants.cs (مبالغ، درصدها) |
-| [email-sms-configuration.md](cms/email-sms-configuration.md) | تنظیمات SMS/Email: Kavenegar templates، Gmail |
-| [PRODUCT-BUNDLE-FEATURE.md](cms/PRODUCT-BUNDLE-FEATURE.md) | 🟡 فیچر آینده: طراحی Product Bundle |
-| [FRONTOFFICE-RELEASE-NOTES-v1.5.0.md](cms/FRONTOFFICE-RELEASE-NOTES-v1.5.0.md) | 🆕 یادداشت انتشار FrontOffice v1.5.0 (فارسی): هفته‌نما، گزارش هفتگی، امتیاز انتقالی |
-| [FILE-MANAGEMENT-ARCHITECTURE.md](cms/FILE-MANAGEMENT-ARCHITECTURE.md) | 🆕 معماری جامع مدیریت فایل: IFileManager, LocalFileManager, ImagePathResolverInterceptor, UploadsController (HTTP سرو عمومی + FMS Fallback), ذخیره دیسکی |
-| [REGISTRATION-FLOW-FIXES.md](cms/REGISTRATION-FLOW-FIXES.md) | 🆕 فیکس فلوی ثبت‌نام: ایجاد کاربر جدید در VerifyOtpToken، رفع lookup موبایل AcceptContract، رفع sync IsCompleteRegister |
-
-## 📂 deployment/ — مستندات استقرار (۴ فایل)
-
-| فایل | توضیح |
-|------|-------|
-| [OFFLINE-DEPLOYMENT-GUIDE.md](deployment/OFFLINE-DEPLOYMENT-GUIDE.md) | راهنمای جامع استقرار آفلاین + تنظیمات Nexus |
-| [CICD-PIPELINE-GUIDE.md](deployment/CICD-PIPELINE-GUIDE.md) | 🆕 راهنمای CI/CD Pipeline: معماری DinD، فیکس‌های dockerd، Runner ConfigMap، عیب‌یابی |
-| [INFRASTRUCTURE-GUIDE.md](deployment/INFRASTRUCTURE-GUIDE.md) | مشخصات سرور، DB credentials، Gitea، وضعیت استقرار |
-| [SERVER-MIRRORS-CONFIG.md](deployment/SERVER-MIRRORS-CONFIG.md) | تنظیمات mirror: K3s registries.yaml، containerd |
-| [INGRESS-NGINX-WARNING.md](deployment/INGRESS-NGINX-WARNING.md) | ⚠️ هشدار K3s: مشکل hostNetwork در ingress-nginx |
-
-## 📂 ui-modernization/ — مستندات نوسازی UI (۳ فایل)
-
-| فایل | توضیح |
-|------|-------|
-| [UI-MODERNIZATION-PLAN.md](ui-modernization/UI-MODERNIZATION-PLAN.md) | 🆕 طرح جامع نوسازی UI فرانت‌آفیس: سیستم بلاگ، صفحات دینامیک، لندینگ، Mobile-First — ۷ فاز، ~۱۲۴ فایل جدید |
-| [BACKOFFICE-ARCHITECTURE.md](ui-modernization/BACKOFFICE-ARCHITECTURE.md) | 🆕 مرجع معماری BackOffice: ساختار پوشه‌ها، الگوهای BasePageComponent/Hub/CodeBehind/ExcelExport، مسیرها، permission‌ها، نقشه NavMenu |
-| [BACKOFFICE-STORE-UNIFICATION.md](ui-modernization/BACKOFFICE-STORE-UNIFICATION.md) | 🆕 یکسان‌سازی فروشگاه عادی و تخفیفی: NavMenu restructure، حذف آمار سفارشات، رفع PaymentDate، بازنویسی ۴ صفحه |
-
-## 📂 migration/ — مستندات مهاجرت BFF→CMS (۶ فایل)
-
-| فایل | توضیح |
-|------|-------|
-| [GATEWAY-REMOVAL-MIGRATION-PLAN.md](migration/GATEWAY-REMOVAL-MIGRATION-PLAN.md) | پلن استراتژیک حذف هر دو Gateway (BFF) |
-| [FRONTOFFICE-TO-CMS-MIGRATION.md](migration/FRONTOFFICE-TO-CMS-MIGRATION.md) | مهاجرت کامل FrontOffice: proto changes، field aliasing + لاگ تغییرات |
-| [MIGRATION-PROGRESS.md](migration/MIGRATION-PROGRESS.md) | لاگ پیشرفت مهاجرت: نسخه‌های proto، خطاها، وضعیت سرویس‌ها |
-| [BACKOFFICE-BFF-MIGRATION.md](migration/BACKOFFICE-BFF-MIGRATION.md) | مهاجرت BackOffice: Strategy C، تغییرات namespace |
-| [customer-facing-capabilities-codex.md](migration/customer-facing-capabilities-codex.md) | تحلیل جامع قابلیت‌های مشتری‌مدار + gap analysis |
-| [DATA-TABLE-MAPPINGS.md](migration/DATA-TABLE-MAPPINGS.md) | 🆕 نگاشت ۳۳ جدول source→target + تبدیل Binary Tree |
-
----
-
-## 📊 آمار تجمیع
-
-| مرحله | تعداد فایل | حذف شده |
-|-------|-----------|---------|
-| اولیه | 220 | — |
-| فاز ۱ (حذف duplicate/expired) | 135 | ۸۵ |
-| فاز ۲ (حذف obsolete عمیق) | 41 | ۹۴ |
-| فاز ۳ (ساختاردهی + merge) | **28** | ۱۳ |
-| cleanup نهایی (+2 فایل جدید) | **30** | — |
-| session CI/CD + Admin fix (+2) | **32** | — |
-| session UI Modernization plan (+1) | **33** | — |
-| session Store Unification (+2 docs) | **35** | — |
-| session File Mgmt + Content (+1 doc) | **36** | — |
-| session Registration Flow Fix (+1 doc) | **37** | — |
-| **نهایی** | **37 + INDEX** | **۱۹۱ فایل حذف/ادغام** |

SHOP-UNIFICATION.md

@@ -1,521 +0,0 @@
-# یکسان‌سازی فروشگاه عادی و فروشگاه تخفیفی (BackOffice)
-
-**تاریخ:** ۱۳۹۴/۱۱/۲۴ (2026-02-13)  
-**وضعیت:** ✅ فاز ۱ تا ۶ — تکمیل شده (CMS + BackOffice Build Succeeded — 0 Error)
-
----
-
-## هدف
-
-هر دو فروشگاه (عادی و تخفیفی) از نظر **UI/UX، ساختار صفحات، اکشن‌ها و قابلیت‌ها** عین‌به‌عین یکسان باشند.  
-**تنها تفاوت مجاز:** منطق پرداخت — فروشگاه تخفیفی از کیف‌پول تخفیفی + درگاه، فروشگاه عادی فقط از کیف‌پول عادی.
-
-### معیار یکسان‌سازی
-- **مبنا:** فروشگاه عادی (Products, Category, UserOrder)
-- **استثنا:** مزایای بدیهی فروشگاه تخفیفی به فروشگاه عادی هم اضافه شد
-- **Bulk Operations:** بیخیال شد (طبق درخواست کاربر)
-
----
-
-## تفاوت‌های زیرساختی (تغییر نکرده — بی‌تأثیر روی UX)
-
-| موضوع | فروشگاه عادی | فروشگاه تخفیفی |
-|---|---|---|
-| ارتباط با سرور | gRPC مستقیم (`ProductsContractClient`) | سرویس اینترفیس (`IDiscountProductService`) که داخلاً gRPC صدا می‌زنه |
-| مدل داده | Protobuf models | C# DTOs |
-
-> **نکته:** هر دو در نهایت از همان gRPC backend استفاده می‌کنند. تفاوت فقط در لایه abstraction است و تأثیری روی UX ندارد.
-
----
-
-## تغییرات انجام‌شده
-
-### ۱. صفحه محصولات (`DiscountProductsMainPage`)
-
-| تغییر | قبل | بعد |
-|---|---|---|
-| نمایش تصویر | `MudAvatar` | کامپوننت `Image` (مطابق فروشگاه عادی) |
-| برش عنوان | `Substring(0, 20) + "…"` | `Truncate(20, true)` (extension method مشترک) |
-| گالری تصاویر | `ProductFormDialog` (کلاینت‌ساید) | `GalleryDialog` سرور-محور (مطابق فروشگاه عادی) |
-| پیش‌نمایش تصویر | HTML inline در `ShowMessageBox` | `ImagePreviewDialog` (مطابق فروشگاه عادی) |
-| عنوان تولبار | «مدیریت محصولات تخفیفی» | «مدیریت محصولات» |
-
-**اکشن‌های جدید اضافه‌شده:**
-- ✅ دکمه «مدیریت دسته‌بندی (درگ و دراپ)» → ناوبری به `ProductCategoriesDragDropPage`
-
-**فایل‌های تغییر یافته:**
-- `Pages/DiscountShop/DiscountProductsMainPage.razor`
-- `Pages/DiscountShop/DiscountProductsMainPage.razor.cs`
-
----
-
-### ۲. صفحه دسته‌بندی‌ها (`DiscountCategoriesMainPage`)
-
-**اکشن‌های جدید اضافه‌شده:**
-- ✅ دکمه «مدیریت محصولات این دسته (درگ و دراپ)» → ناوبری به `CategoryProductsDragDropPage`
-
-**فایل‌های تغییر یافته:**
-- `Pages/DiscountShop/DiscountCategoriesMainPage.razor`
-- `Pages/DiscountShop/DiscountCategoriesMainPage.razor.cs`
-
----
-
-### ۳. صفحه سفارشات (`DiscountOrdersMainPage`) — بازنویسی کامل
-
-| تغییر | قبل | بعد |
-|---|---|---|
-| الگوی فیلتر | فیلترهای inline با دکمه جستجو | `BasePageComponent` با OnSubmit/OnClear (مطابق فروشگاه عادی) |
-| لایه‌بندی | `MudPaper` تو در تو | `BasePageComponent > Filters + Content` |
-| اکشن‌ها | فقط مشاهده جزئیات + تغییر وضعیت | جزئیات + تغییر وضعیت + حذف (مطابق فروشگاه عادی) |
-| آیکون‌های اکشن | `Visibility` + `Edit` | `Info` + `LocalShipping` + `DeleteOutline` (مطابق فروشگاه عادی) |
-| ساختار تولبار | بدون تولبار | تولبار با عنوان + دکمه Excel (مطابق فروشگاه عادی) |
-
-**ستون‌ها (حفظ شده — خاص فروشگاه تخفیفی):**
-- شماره سفارش، تاریخ ثبت، مبلغ کل، **تخفیف کیف‌پول**، **پرداخت درگاه**، تعداد آیتم، وضعیت، پرداخت
-
-**فایل‌های تغییر یافته:**
-- `Pages/DiscountShop/DiscountOrdersMainPage.razor` ← بازنویسی کامل
-- `Pages/DiscountShop/DiscountOrdersMainPage.razor.cs` ← بازنویسی کامل
-
----
-
-### ۴. گزارش فروش (`SalesReports`)
-
-| تغییر | قبل | بعد |
-|---|---|---|
-| نمودارها | روند فروش + محصولات پرفروش | روند فروش + محصولات پرفروش + **وضعیت سفارش‌ها** |
-| عنوان | «گزارش فروش فروشگاه تخفیفی» | «گزارش فروش فروشگاه» |
-| توضیح | «آمار فروش، تخفیف و وضعیت سفارش‌های فروشگاه تخفیفی...» | «آمار فروش و وضعیت سفارش‌ها بر اساس بازه تاریخ و وضعیت سفارش» |
-
-**نمودار جدید:**
-- ✅ «وضعیت سفارش‌ها» — نمودار میله‌ای تعداد سفارش بر اساس وضعیت (مطابق فروشگاه عادی)
-
-**فایل‌های تغییر یافته:**
-- `Pages/DiscountShop/SalesReports.razor`
-
----
-
-### ۵. هاب سفارشات (`DiscountShopHub`)
-
-| تغییر | قبل | بعد |
-|---|---|---|
-| عنوان | «فروشگاه تخفیفی» | «سفارشات فروشگاه تخفیفی» |
-| آیکون تب سفارشات | `ShoppingCart` | `ReceiptLong` (مطابق `OrdersHub` فروشگاه عادی) |
-
-**فایل‌های تغییر یافته:**
-- `Pages/DiscountShop/DiscountShopHub.razor`
-
----
-
-### ۶. تغییرات فروشگاه عادی (مزایای تخفیفی ← عادی)
-
-#### CategoryMainPage
-- ✅ ستون **«ترتیب»** (`SortOrder`) اضافه شد (از تخفیفی)
-- ✅ **غیرفعال‌سازی حذف** دسته‌بندی دارای زیردسته (از تخفیفی)
-
-**فایل‌های تغییر یافته:**
-- `Pages/Category/CategoryMainPage.razor`
-- `Pages/Category/CategoryMainPage.razor.cs`
-
----
-
-## تغییرات فاز ۲ — ارتقاء به Admin RPC و فیلدهای پیشرفته
-
-### ۷. سرویس سفارشات تخفیفی — سوئیچ به Admin RPC
-
-| تغییر | قبل | بعد |
-|---|---|---|
-| RPC مورد استفاده | `GetUserOrders` (user-scoped) | `GetAllDiscountOrders` (admin-scoped) |
-| DTO | `OrderSummaryDto` (محدود) | `AdminOrderDto` (کامل با user_full_name, user_mobile, shipping_address, payment_date, vat_amount...) |
-| فیلترها | فقط userId, paymentCompleted, deliveryStatus | userId, paymentStatus, deliveryStatus, userMobile, trackingCode, fromDate, toDate, minAmount, maxAmount |
-| گزارش فروش | محاسبه کلاینت‌ساید + N+1 (۵۰ فراخوان gRPC جداگانه!) | `GetDiscountSalesReport` RPC سرور-ساید با fallback |
-
-**فایل‌های تغییر یافته:**
-- `Services/DiscountOrder/IDiscountOrderService.cs` ← فیلترهای جدید + DTOهای گزارش فروش
-- `Services/DiscountOrder/DiscountOrderService.cs` ← سوئیچ به `GetAllDiscountOrdersAsync` + `GetDiscountSalesReportAsync`
-
-### ۸. ستون‌ها و فیلترهای ادمین در سفارشات تخفیفی
-
-**ستون‌های جدید اضافه‌شده:**
-- ✅ **نام کاربر** (لینک به پروفایل — مطابق فروشگاه عادی)
-- ✅ **موبایل کاربر**
-- ✅ **وضعیت پرداخت** (Pending/Completed/Failed/Refunded — مطابق فروشگاه عادی)
-- ✅ **تاریخ پرداخت**
-- ✅ **آدرس** (truncated با tooltip — مطابق فروشگاه عادی)
-- ✅ **وضعیت ارسال** (جدا از وضعیت پرداخت — مطابق فروشگاه عادی)
-
-**فیلترهای جدید اضافه‌شده:**
-- ✅ شناسه سفارش
-- ✅ جستجوی کاربر (UserAutoComplete)
-- ✅ موبایل کاربر
-- ✅ کد رهگیری
-- ✅ از تاریخ / تا تاریخ
-- ✅ وضعیت پرداخت (Pending/Completed/Failed/Refunded)
-- ✅ وضعیت ارسال
-
-**فایل‌های تغییر یافته:**
-- `Pages/DiscountShop/DiscountOrdersMainPage.razor` ← ستون‌ها + فیلترها
-- `Pages/DiscountShop/DiscountOrdersMainPage.razor.cs` ← فیلدها + متدهای وضعیت پرداخت
-
-### ۹. گزارش فروش تخفیفی — حذف مشکل N+1
-
-| تغییر | قبل | بعد |
-|---|---|---|
-| محصولات پرفروش | ۵۰ فراخوان gRPC جداگانه (`GetByIdAsync` × 50) | یک فراخوان `GetDiscountSalesReport` |
-| خلاصه آماری | محاسبه کلاینت‌ساید | سرور-ساید (دقیق‌تر + سریع‌تر) |
-| نمودار روند | GroupBy کلاینت‌ساید | `SalesPeriodDto` از سرور |
-| جدول سفارش‌ها | فقط شماره سفارش | شناسه + نام کاربر (لینک) |
-| خروجی Excel/PDF | فقط OrderNumber | شناسه + نام کاربر + موبایل |
-
-**فایل‌های تغییر یافته:**
-- `Pages/DiscountShop/SalesReports.razor`
-
-### ۱۰. دسته‌بندی فروشگاه عادی — فیلد ImagePath
-
-- ✅ فیلد `ImagePath` به دیالوگ ایجاد/ویرایش دسته‌بندی اضافه شد (مطابق فروشگاه تخفیفی)
-
-**فایل‌های تغییر یافته:**
-- `Pages/Category/Components/CreateOrUpdateCategoryDialog.razor`
-- `Pages/Category/Components/CreateOrUpdateCategoryDialog.razor.cs`
-
-### ۱۱. گزارش فروش عادی — نمودار محصولات پرفروش + خروجی PDF
-
-- ✅ نمودار «محصولات پرفروش (بر اساس مبلغ)» از FactorDetails سفارشات
-- ✅ دکمه خروجی PDF (نسخه متنی) — مطابق فروشگاه تخفیفی
-
-**فایل‌های تغییر یافته:**
-- `Pages/UserOrder/OrderSalesReports.razor`
-- `Pages/UserOrder/OrderSalesReports.razor.cs`
-
----
-
-## تغییرات فاز ۳ — تگ‌های محصول و نهایی‌سازی
-
-### ۱۲. تگ‌های محصول در فروشگاه تخفیفی
-
-- ✅ دکمه «تگ‌های محصول» (`Label` icon) به ستون عملیات صفحه محصولات تخفیفی اضافه شد
-- ✅ از همان `AssignTagsDialog` فروشگاه عادی استفاده شد (کامپوننت مشترک)
-- ✅ سرویس `ProductTagContract` مشترک بین هر دو فروشگاه — بدون نیاز به API جدید
-
-> **نکته:** `ProductTagContract` یک سرویس ژنریک `product_id ↔ tag_id` است و محدود به فروشگاه خاصی نیست.
-
-**فایل‌های تغییر یافته:**
-- `Pages/DiscountShop/DiscountProductsMainPage.razor` ← دکمه تگ
-- `Pages/DiscountShop/DiscountProductsMainPage.razor.cs` ← متد `OpenTagAssignment` + using
-
----
-
-## تغییرات فاز ۴ — یکسان‌سازی دیالوگ‌ها و جزئیات تکمیلی
-
-### ۱۳. دیالوگ جزئیات سفارش تخفیفی — Timeline + ویرایش Inline
-
-| تغییر | قبل | بعد |
-|---|---|---|
-| Timeline وضعیت | ❌ فاقد | ✅ ۵ مرحله (ثبت → پرداخت → آماده‌سازی → ارسال → تحویل/مرجوعی) |
-| ویرایش وضعیت | ❌ فقط خواندنی | ✅ درون‌خطی (وضعیت + کد رهگیری + یادداشت ادمین) |
-| دکمه ذخیره | ❌ فقط «بستن» | ✅ «ثبت تغییرات» + اسپینر بارگذاری |
-| هشدارهای شرطی | ❌ فاقد | ✅ هشدار لغو/مرجوعی + اطلاع‌رسانی ارسال |
-| Code-behind | `@code` درون‌خطی | فایل جداگانه `.razor.cs` |
-
-**فایل‌های تغییر یافته:**
-- `Pages/DiscountShop/Components/OrderDetailsDialog.razor` ← Timeline + ویرایش inline
-- `Pages/DiscountShop/Components/OrderDetailsDialog.razor.cs` ← فایل جدید — timeline + save logic
-
-### ۱۴. دیالوگ تغییر وضعیت فروشگاه عادی — ارتقاء
-
-| تغییر | قبل | بعد |
-|---|---|---|
-| فرم | `MudStack` ساده | `MudForm` با validation |
-| فیلدها | فقط وضعیت | ✅ وضعیت + **کد رهگیری** + **توضیحات ارسال** |
-| هشدارهای شرطی | ❌ فاقد | ✅ هشدار مرجوعی + اطلاع‌رسانی ارسال |
-| دکمه | رنگ ثابت `Primary` | ✅ رنگ داینامیک بر اساس وضعیت + اسپینر |
-| عنوان | بدون آیکون | ✅ آیکون `Edit` + عنوان |
-| RPC | فقط `UpdateOrderStatusAsync` | ✅ `UpdateOrderStatusAsync` + `UpdateUserOrderAsync` (کد رهگیری + توضیحات) |
-
-**فایل‌های تغییر یافته:**
-- `Pages/UserOrder/Components/ChangeOrderStatusDialog.razor`
-- `Pages/UserOrder/Components/ChangeOrderStatusDialog.razor.cs`
-
-### ۱۵. گزارش فروش تخفیفی — Empty chart guard + ترتیب نمودارها
-
-| تغییر | قبل | بعد |
-|---|---|---|
-| نمودار روند فروش | بدون بررسی خالی بودن | ✅ نمایش «داده کافی برای نمایش نمودار وجود ندارد» |
-| ترتیب نمودارها | روند → پرفروش → وضعیت | ✅ روند → **وضعیت** → پرفروش (مطابق فروشگاه عادی) |
-
-**فایل‌های تغییر یافته:**
-- `Pages/DiscountShop/SalesReports.razor`
-
-### ۱۶. گزارش فروش عادی — لینک نام کاربر
-
-- ✅ نام کاربر در جدول سفارش‌ها از متن ساده به `MudLink` تبدیل شد (لینک به پروفایل کاربر)
-
-**فایل‌های تغییر یافته:**
-- `Pages/UserOrder/OrderSalesReports.razor`
-
-### ۱۷. دیالوگ دسته‌بندی فروشگاه عادی — MudForm + UX
-
-| تغییر | قبل | بعد |
-|---|---|---|
-| اعتبارسنجی | ❌ بدون validation | ✅ `MudForm` با `Required` + `RequiredError` |
-| فیلد فعال | `MudCheckBox` | ✅ `MudSwitch` رنگی (مطابق فروشگاه تخفیفی) |
-| Helper text | ❌ فاقد | ✅ «عدد کمتر = اولویت بالاتر» + «برای دسته اصلی خالی بگذارید» |
-| دکمه ذخیره | همیشه «ثبت» | ✅ «ذخیره تغییرات» / «ایجاد دسته‌بندی» (داینامیک) |
-| اسپینر بارگذاری | ❌ فاقد | ✅ `MudProgressCircular` + غیرفعال‌سازی دکمه |
-| عنوان | بدون آیکون | ✅ آیکون `Edit`/`Add` + عنوان داینامیک |
-| غیرفعال‌سازی دکمه | ❌ فاقد | ✅ غیرفعال تا validation سبز نشود |
-
-**فایل‌های تغییر یافته:**
-- `Pages/Category/CreateOrUpdateCategoryDialog.razor`
-- `Pages/Category/CreateOrUpdateCategoryDialog.razor.cs`
-
-### ۱۸. سفارشات تخفیفی — لغو سفارش واقعی
-
-| تغییر | قبل | بعد |
-|---|---|---|
-| دکمه «حذف» | آیکون `DeleteOutline` — فقط snackbar (بدون API) | ✅ آیکون `Cancel` — فراخوان `UpdateStatusAsync` با `Cancelled` |
-| متن تأییدیه | «آیا از حذف مطمئن هستید؟» | «آیا از لغو سفارش مطمئن هستید؟ وضعیت به لغو شده تغییر می‌کند» |
-| عملکرد | ❌ هیچ | ✅ واقعی — `UpdateStatusAsync(Cancelled)` |
-
-**فایل‌های تغییر یافته:**
-- `Pages/DiscountShop/DiscountOrdersMainPage.razor` ← آیکون + tooltip
-- `Pages/DiscountShop/DiscountOrdersMainPage.razor.cs` ← فراخوان API
-
----
-
-## تغییرات فاز ۵ — فرمت‌بندی قیمت، زیردسته و برچسب فیلدها
-
-### ۵.۱ فرمت‌بندی قیمت در لیست محصولات عادی
-
-**مشکل:** ستون قیمت عدد خام بدون separator و بدون واحد نشان می‌داد.  
-**راه‌حل:** تبدیل `PropertyColumn` به `TemplateColumn` با `Price.ToString("N0") ریال` — مطابق فروشگاه تخفیفی.
-
-**فایل تغییر یافته:**
-- `Pages/Products/ProductsMainPage.razor` ← TemplateColumn + فرمت N0 + ریال
-
-### ۵.۲ دکمه «افزودن زیردسته» در دسته‌بندی‌های عادی
-
-**مشکل:** فروشگاه تخفیفی دکمه «افزودن زیردسته» در ستون عملیات داشت ولی فروشگاه عادی نداشت.  
-**راه‌حل:** افزودن `MudIconButton` با آیکون `CreateNewFolder` + رنگ `Color.Primary` + متد `CreateSubcategory(parent)` که دیالوگ را با `ParentId = parent.Id` باز می‌کند.
-
-**فایل‌های تغییر یافته:**
-- `Pages/Category/CategoryMainPage.razor` ← دکمه جدید در ستون عملیات
-- `Pages/Category/CategoryMainPage.razor.cs` ← متد `CreateSubcategory`
-
-### ۵.۳ برچسب واحد ریال در دیالوگ‌های محصول
-
-**مشکل:** فیلد قیمت در دیالوگ‌های ایجاد/ویرایش محصول عادی `Label="قیمت"` داشت — بدون واحد.  
-**راه‌حل:** تغییر به `Label="قیمت (ریال)"` — مطابق فروشگاه تخفیفی.
-
-**فایل‌های تغییر یافته:**
-- `Pages/Products/Components/CreateDialog.razor` ← قیمت (ریال)
-- `Pages/Products/Components/UpdateDialog.razor` ← قیمت (ریال)
-
----
-
-## تغییرات فاز ۶ — تغییرات بکند (Proto + Handler + gRPC Service)
-
-این فاز تمام موارد "محدودیت API" که در فازهای قبلی شناسایی شده بودند را حل می‌کند.
-
-### ۶.۱ ستون وضعیت فعال/غیرفعال محصولات (`is_active`)
-
-**مشکل:** پروتوباف `GetAllProductsByFilterResponseModel` فیلد `is_active` نداشت. محصولات عادی ستون وضعیت نداشتند.  
-**راه‌حل (end-to-end):**
-- **Proto:** افزودن `bool is_active = 15` به `GetAllProductsByFilterResponseModel` + `google.protobuf.BoolValue is_active = 15` به `GetAllProductsByFilterFilter`
-- **DTO:** افزودن `bool IsActive` به `CustomerProductModel`
-- **Query:** افزودن `bool? IsActive` به `GetCustomerProductsByFilterQuery`
-- **Handler:** فیلتر `IsDeleted != IsActive` + مپ `IsActive = !p.IsDeleted`
-- **gRPC Service:** مپ `IsActive` در فیلتر و ریسپانس `ProductsService`
-- **Frontend:** ستون `TemplateColumn` با `MudChip` رنگی در `ProductsMainPage.razor`
-
-**فایل‌های تغییر یافته:**
-- `CMS/.../Protos/products.proto`
-- `CMS/.../GetCustomerProductsByFilterResponseDto.cs`
-- `CMS/.../GetCustomerProductsByFilterQuery.cs`
-- `CMS/.../GetCustomerProductsByFilterQueryHandler.cs`
-- `CMS/.../Services/ProductsService.cs`
-- `BackOffice/.../Pages/Products/ProductsMainPage.razor`
-
-### ۶.۲ ستون تعداد محصولات دسته‌بندی (`product_count`)
-
-**مشکل:** پروتوباف `GetAllCategoryByFilterResponseModel` فیلد `product_count` نداشت.  
-**راه‌حل (end-to-end):**
-- **Proto:** افزودن `int32 product_count = 9` به `GetAllCategoryByFilterResponseModel`
-- **DTO:** افزودن `int ProductCount` به `GetAllCategoryByFilterResponseModel` (C#)
-- **Handler:** تغییر از `ProjectToType<>()` (Mapster auto-map) به manual `Select()` با `ProductCount = x.ProductCategories.Count`
-- **gRPC Service:** auto-map Mapster (نام یکسان)
-- **Frontend:** ستون `PropertyColumn` جدید در `CategoryMainPage.razor`
-
-**فایل‌های تغییر یافته:**
-- `CMS/.../Protos/category.proto`
-- `CMS/.../GetAllCategoryByFilterResponseDto.cs`
-- `CMS/.../GetAllCategoryByFilterQueryHandler.cs`
-- `BackOffice/.../Pages/Category/CategoryMainPage.razor`
-
-### ۶.۳ فیلتر بازه تاریخ سفارشات (`from_date` / `to_date`)
-
-**مشکل:** پروتوباف `GetAllUserOrderByFilterFilter` فقط یک `payment_date` داشت. امکان فیلتر بازه تاریخ وجود نداشت.  
-**راه‌حل (end-to-end):**
-- **Proto:** افزودن `google.protobuf.Timestamp from_date = 11` و `google.protobuf.Timestamp to_date = 12` به فیلتر
-- **gRPC Service:** مپ `FromDate` از `from_date` (با fallback به `payment_date`)، `ToDate` از `to_date`
-- **Handler:** بدون تغییر — از قبل `FromDate`/`ToDate` را ساپورت می‌کرد
-- **Frontend:** افزودن `MudDatePicker` دوم (تا تاریخ)، مپ به `Filter.FromDate`/`Filter.ToDate`
-
-**فایل‌های تغییر یافته:**
-- `CMS/.../Protos/userorder.proto`
-- `CMS/.../Services/UserOrderService.cs`
-- `BackOffice/.../Pages/UserOrder/UserOrderMainPage.razor`
-- `BackOffice/.../Pages/UserOrder/UserOrderMainPage.razor.cs`
-
-### ۶.۴ تصویر محصول در آیتم‌های سفارش تخفیفی (`image_path`)
-
-**مشکل:** `OrderItemDto` در proto و C# فیلد `image_path` نداشت. آیتم‌های سفارش بدون تصویر بودند.  
-**راه‌حل (end-to-end):**
-- **Proto:** افزودن `string image_path = 9` و `string thumbnail_path = 10` به `OrderItemDto` در `discountorder.proto`
-- **Backend DTO:** افزودن `ImagePath`/`ThumbnailPath` به `OrderItemDto` (C# Application layer)
-- **Handler:** مپ `ImagePath = od.Product.ImagePath` در `GetOrderByIdQueryHandler` (Product nav property از قبل Include شده بود)
-- **Frontend DTO:** افزودن فیلدها به `IDiscountOrderService.OrderItemDto`
-- **Frontend Service:** مپ در `DiscountOrderService`
-- **Frontend Dialog:** `MudImage` + `MudStack` برای نمایش تصویر کنار نام محصول
-
-**فایل‌های تغییر یافته:**
-- `CMS/.../Protos/discountorder.proto`
-- `CMS/.../GetOrderByIdQuery.cs` (OrderItemDto)
-- `CMS/.../GetOrderByIdQueryHandler.cs`
-- `BackOffice/.../Services/DiscountOrder/IDiscountOrderService.cs`
-- `BackOffice/.../Services/DiscountOrder/DiscountOrderService.cs`
-- `BackOffice/.../Pages/DiscountShop/Components/OrderDetailsDialog.razor`
-
----
-
-## وضعیت مقایسه‌ای نهایی
-
-### محصولات
-| قابلیت | عادی | تخفیفی |
-|---|:---:|:---:|
-| لیست با MudDataGrid + server-side | ✅ | ✅ |
-| فیلتر با BasePageComponent | ✅ | ✅ |
-| نمایش تصویر (Image component) | ✅ | ✅ |
-| برش عنوان (Truncate) | ✅ | ✅ |
-| ایجاد/ویرایش/حذف | ✅ | ✅ |
-| گالری تصاویر (GalleryDialog سرور-محور) | ✅ | ✅ |
-| پیش‌نمایش تصویر (ImagePreviewDialog) | ✅ | ✅ |
-| مدیریت دسته‌بندی (درگ و دراپ) | ✅ | ✅ |
-| خروجی Excel | ✅ | ✅ |
-| تگ‌های محصول (AssignTagsDialog مشترک) | ✅ | ✅ |
-| فرمت قیمت (N0 + ریال) | ✅ | ✅ |
-| ستون وضعیت فعال/غیرفعال | ✅ | ✅ |
-| Bulk Edit/Delete/Toggle | ✅ | ❌ (طبق درخواست — بیخیال) |
-
-### دسته‌بندی‌ها
-| قابلیت | عادی | تخفیفی |
-|---|:---:|:---:|
-| درخت سایدبار | ✅ | ✅ |
-| گرید با MudDataGrid | ✅ | ✅ |
-| ستون‌ها: شناسه، نام لاتین، عنوان، والد، ترتیب، فعال | ✅ | ✅ |
-| ستون تعداد محصولات | ✅ | ✅ |
-| ایجاد/ویرایش/حذف | ✅ | ✅ |
-| غیرفعال‌سازی حذف دارای زیردسته | ✅ | ✅ |
-| افزودن زیردسته | ✅ | ✅ |
-| درگ‌اندراپ محصولات دسته | ✅ | ✅ |
-
-### سفارشات
-| قابلیت | عادی | تخفیفی |
-|---|:---:|:---:|
-| BasePageComponent با فیلتر | ✅ | ✅ |
-| MudDataGrid + تولبار | ✅ | ✅ |
-| فیلتر شناسه / کاربر / تاریخ / وضعیت | ✅ | ✅ |
-| فیلتر بازه تاریخ (از تاریخ + تا تاریخ) | ✅ | ✅ |
-| ستون نام کاربر (لینک به پروفایل) | ✅ | ✅ |
-| ستون وضعیت پرداخت (Chip رنگی) | ✅ | ✅ |
-| ستون وضعیت ارسال (Chip رنگی) | ✅ | ✅ |
-| ستون تاریخ پرداخت | ✅ | ✅ |
-| ستون آدرس (truncated + tooltip) | ✅ | ✅ |
-| جزئیات سفارش (Timeline + ویرایش inline) | ✅ | ✅ |
-| تصویر محصول در آیتم‌های سفارش | ✅ | ✅ |
-| تغییر وضعیت (MudForm + کد رهگیری + هشدار) | ✅ | ✅ |
-| لغو سفارش | ✅ | ✅ (via UpdateStatus) |
-| خروجی Excel | ✅ | ✅ |
-| ستون‌های مالی تخفیف (DiscountBalanceUsed/GatewayAmount) | ❌ (مربوط نیست) | ✅ |
-| اعمال تخفیف | ✅ | ❌ (API ندارد) |
-
-### گزارش فروش
-| قابلیت | عادی | تخفیفی |
-|---|:---:|:---:|
-| فیلتر تاریخ + وضعیت | ✅ | ✅ |
-| کارت‌های خلاصه | ✅ | ✅ |
-| نمودار روند فروش | ✅ | ✅ |
-| نمودار وضعیت سفارش‌ها | ✅ | ✅ |
-| نمودار محصولات پرفروش | ✅ | ✅ |
-| خروجی Excel | ✅ | ✅ |
-| خروجی PDF | ✅ | ✅ |
-
----
-
-## موارد باقی‌مانده
-
-این موارد نیاز به تغییرات بیشتر دارند:
-
-| مورد | جزئیات | وضعیت |
-|---|---|---|
-| **اعمال تخفیف سفارش تخفیفی** | `discountorder.proto` فاقد `ApplyDiscountToOrder` RPC | نیاز به RPC جدید + لاجیک سرور |
-| **لغو سفارش با بازپرداخت** | لغو وضعیت ✅ ولی refund/بازگشت موجودی نیاز به RPC اختصاصی | نیاز به `CancelOrder` RPC |
-
-> **نکته:** موارد قبلی (is_active، product_count، from_date/to_date، image_path) در **فاز ۶** حل شدند.
-
----
-
-## ساختار فایل‌های تغییریافته
-
-```
-CMS/src/
-├── CMSMicroservice.Protobuf/Protos/
-│   ├── products.proto              ← is_active (filter + response field 15)
-│   ├── category.proto              ← product_count (response field 9)
-│   ├── userorder.proto             ← from_date/to_date (filter fields 11,12)
-│   └── discountorder.proto         ← image_path/thumbnail_path (OrderItemDto fields 9,10)
-├── CMSMicroservice.Application/
-│   ├── ProductsCQ/Queries/GetCustomerProductsByFilter/
-│   │   ├── GetCustomerProductsByFilterQuery.cs          ← IsActive filter
-│   │   ├── GetCustomerProductsByFilterQueryHandler.cs   ← IsActive filter + mapping
-│   │   └── GetCustomerProductsByFilterResponseDto.cs    ← IsActive field
-│   ├── CategoryCQ/Queries/GetAllCategoryByFilter/
-│   │   ├── GetAllCategoryByFilterQueryHandler.cs        ← manual Select + ProductCount
-│   │   └── GetAllCategoryByFilterResponseDto.cs         ← ProductCount field
-│   └── DiscountShopCQ/Queries/GetOrderById/
-│       ├── GetOrderByIdQuery.cs                         ← ImagePath/ThumbnailPath
-│       └── GetOrderByIdQueryHandler.cs                  ← Product image mapping
-└── CMSMicroservice.WebApi/Services/
-    ├── ProductsService.cs          ← IsActive filter + response mapping
-    └── UserOrderService.cs         ← FromDate/ToDate mapping
-
-BackOffice/src/BackOffice/
-├── Services/DiscountOrder/
-│   ├── IDiscountOrderService.cs        ← OrderItemDto + ImagePath/ThumbnailPath
-│   └── DiscountOrderService.cs         ← image mapping
-├── Pages/
-│   ├── Category/
-│   │   ├── CategoryMainPage.razor      ← ستون ProductCount + SortOrder + زیردسته
-│   │   ├── CategoryMainPage.razor.cs   ← HasChildren + CreateSubcategory
-│   │   ├── CreateOrUpdateCategoryDialog.razor    ← MudForm + ImagePath
-│   │   └── CreateOrUpdateCategoryDialog.razor.cs ← validation + loading
-│   ├── DiscountShop/
-│   │   ├── DiscountShopHub.razor
-│   │   ├── DiscountProductsMainPage.razor/.cs
-│   │   ├── DiscountCategoriesMainPage.razor/.cs
-│   │   ├── DiscountOrdersMainPage.razor/.cs
-│   │   ├── SalesReports.razor
-│   │   └── Components/
-│   │       ├── OrderDetailsDialog.razor     ← تصویر محصول + Timeline
-│   │       └── OrderDetailsDialog.razor.cs
-│   ├── UserOrder/
-│   │   ├── UserOrderMainPage.razor         ← فیلتر بازه تاریخ (از + تا)
-│   │   ├── UserOrderMainPage.razor.cs      ← FromDate/ToDate mapping
-│   │   ├── OrderSalesReports.razor/.cs
-│   │   └── Components/ChangeOrderStatusDialog.razor/.cs
-│   └── Products/
-│       ├── ProductsMainPage.razor         ← ستون IsActive + فرمت قیمت
-│       └── Components/
-│           ├── CreateDialog.razor         ← قیمت (ریال)
-│           └── UpdateDialog.razor         ← قیمت (ریال)
-```

business/BIZ-PACKAGE-BASED-SYSTEM-v1-draft.md

@@ -0,0 +1,554 @@
+# 📦 سیستم مبتنی بر پکیج (Package-Based System)
+
+> **وضعیت:** تحلیل و بررسی — منتظر تایید  
+> **تاریخ:** اسفند ۱۴۰۴  
+> **تاثیرگذاری:** زیاد — بخش‌های متعدد سیستم تحت تاثیر قرار می‌گیرد
+
+---
+
+## ۱. خلاصه فیچر
+
+**وضعیت فعلی:** سیستم فقط یک پکیج پایه (۵۶ میلیون تومان) دارد و همه چیز حول آن می‌چرخد.
+
+**وضعیت هدف:** سیستم چندین پکیج با قیمت‌ها و ویژگی‌های متفاوت پشتیبانی می‌کند. هر پکیج روش‌های پرداخت، محاسبه پورسانت، شارژ کیف پول و فیچرهای مختص خود را دارد.
+
+```
+مثال پکیج‌ها:
+┌──────────────┬──────────────┬──────────────┬──────────────┐
+│  🥈 نقره‌ای   │  🥇 طلایی     │  💎 الماسی    │   ⭐ ویژه     │
+│  ۵.۶M تومان  │  ۵۶M تومان   │   ؟؟ تومان   │   ؟؟ تومان   │
+│              │  (پکیج پایه) │              │              │
+│ فقط مستقیم   │ دایا+مستقیم  │ فقط مستقیم   │ فقط مستقیم   │
+│ فیچر محدود   │ همه فیچرها   │ همه فیچرها   │ همه+اختصاصی  │
+└──────────────┴──────────────┴──────────────┴──────────────┘
+```
+
+---
+
+## ۲. وضعیت فعلی سیستم (AS-IS)
+
+### ۲.۱ فلوی فعلی فعالسازی
+
+```mermaid
+flowchart TD
+    A["کاربر وارد سیستم می‌شود"] --> B{"روش پرداخت"}
+    B -->|"خرید الماس دایا"| C["DayaLoan — ۵۶M"]
+    B -->|"پرداخت مستقیم"| D["درگاه بانکی — ۵۶M"]
+    C --> E["بررسی موفقیت پرداخت"]
+    D --> E
+    E --> F["شارژ کیف پول"]
+    F --> G["مدال قرارداد باشگاه مشتریان"]
+    G --> H["تایید OTP + امضا"]
+    H --> I["فعال‌سازی عضویت باشگاه"]
+    I --> J["اختصاص فیچرها"]
+    I --> K["ایجاد Cycle"]
+    I --> L["اضافه به Commission Pool"]
+    J --> M["✅ کاربر فعال — لینک معرف"]
+```
+
+### ۲.۲ جریان پول فعلی
+
+```
+کاربر ۵۶M پرداخت می‌کند
+    │
+    ├── Balance (کیف پول عادی)     += ۵۶,۰۰۰,۰۰۰ ریال
+    ├── DiscountBalance (اعتباری)  += ۱۱۲,۰۰۰,۰۰۰ ریال (×۲)
+    │
+    └── Club Activation:
+        ├── CommissionPool          += ۲۵,۲۰۰,۰۰۰ ریال (ClubActivationFee)
+        └── GiftValue               = ۲۵,۲۰۰,۰۰۰ ریال (اطلاع‌رسانی)
+```
+
+### ۲.۳ مقادیر Hardcoded فعلی (`SystemConstants.cs`)
+
+| ثابت | مقدار | کاربرد |
+|------|-------|--------|
+| `BasePackageAmount` | ۵۶,۰۰۰,۰۰۰ | قیمت پکیج |
+| `DayaLoanAmount` | ۵۶,۰۰۰,۰۰۰ | مبلغ وام دایا |
+| `ClubActivationFee` | ۲۵,۲۰۰,۰۰۰ | سهم هفتگی Commission Pool |
+| `ClubMembershipGiftValue` | ۲۵,۲۰۰,۰۰۰ | ارزش هدیه حق عضویت |
+| `MagicWalletMultiplier` | ×۲.۵ | ضریب کیف پول جادویی |
+
+### ۲.۴ مشکلات فعلی
+
+| # | مشکل | فایل |
+|---|------|------|
+| ۱ | پکیج ID=4 **hardcoded** در `InitiateBasePackagePaymentCommandHandler` | Application/Commands |
+| ۲ | مبلغ ۵۶M **hardcoded** در `SystemConstants` و چندین handler | Domain/Common |
+| ۳ | فیچرها **همه یکجا** assign می‌شن (۴ فیچر ثابت: چتیکا، بیمه، تریپ، لرن) | ActivateClubMembershipHandler |
+| ۴ | Commission Pool فقط با `ClubActivationFee` ثابت پر می‌شه | ActivateClubMembershipHandler |
+| ۵ | `DiscountBalance = Amount × 2` — ضریب hardcoded | VerifyPayment handlers |
+| ۶ | فرانت‌اند فقط یک مسیر خرید نشون میده | FrontOffice pages |
+
+---
+
+## ۳. طراحی پیشنهادی (TO-BE)
+
+### ۳.۱ فلوی جدید فعالسازی
+
+```mermaid
+flowchart TD
+    A["کاربر وارد سیستم"] --> B["صفحه پکیج‌ها<br/>(کاشی‌های نقره‌ای/طلایی/الماسی/...)"]
+    
+    B -->|"کلیک روی پکیج"| C{"نوع پکیج"}
+    
+    C -->|"پکیج پایه (طلایی)"| D["مدال با دو گزینه:<br/>۱. خرید الماس دایا<br/>۲. پرداخت مستقیم"]
+    C -->|"پکیج‌های دیگر"| E["مدال با یک گزینه:<br/>فقط پرداخت مستقیم<br/>+ توضیحات + قیمت"]
+    
+    D -->|"دایا"| F["فلوی دایا"]
+    D -->|"مستقیم"| G["درگاه پرداخت"]
+    E --> G
+    
+    F --> H["پرداخت موفق"]
+    G --> H
+    
+    H --> I["شارژ کیف پول<br/>(متناسب با قیمت پکیج)"]
+    I --> J["مدال قرارداد باشگاه"]
+    J --> K["OTP + امضا"]
+    K --> L["فعال‌سازی<br/>+ اختصاص فیچرهای پکیج"]
+    L --> M["✅ کاربر فعال"]
+```
+
+### ۳.۲ تغییرات Entity — Package
+
+**فعلی:**
+```csharp
+public class Package : BaseAuditableEntity
+{
+    public string Title { get; set; }
+    public string Description { get; set; }
+    public string ImagePath { get; set; }
+    public long Price { get; set; }
+}
+```
+
+**پیشنهادی:**
+```csharp
+public class Package : BaseAuditableEntity
+{
+    public string Title { get; set; }
+    public string Description { get; set; }
+    public string ImagePath { get; set; }
+    public long Price { get; set; }                          // قیمت پکیج (ریال)
+    
+    // === فیلدهای جدید ===
+    public int SortOrder { get; set; }                       // ترتیب نمایش
+    public bool IsActive { get; set; } = true;               // فعال/غیرفعال
+    public bool IsBasePackage { get; set; }                   // آیا پکیج پایه است؟
+    public bool SupportsDayaPurchase { get; set; }            // پشتیبانی از خرید دایا
+    public bool SupportsDirectPurchase { get; set; } = true;  // پشتیبانی از پرداخت مستقیم
+    
+    // === محاسبات مالی ===
+    public long ActivationFee { get; set; }                  // سهم Commission Pool
+    public long GiftValue { get; set; }                      // ارزش هدیه
+    public decimal DiscountMultiplier { get; set; } = 2.0m;  // ضریب شارژ DiscountBalance
+    
+    // === Navigation ===
+    public virtual ICollection<PackageFeature> PackageFeatures { get; set; }
+    public virtual ICollection<UserPackagePurchase> Purchases { get; set; }
+}
+```
+
+### ۳.۳ Entity جدید — PackageFeature (پل بین پکیج و فیچر)
+
+```csharp
+/// <summary>
+/// مشخص می‌کند هر پکیج چه فیچرهایی را فعال می‌کند
+/// </summary>
+public class PackageFeature : BaseAuditableEntity
+{
+    public long PackageId { get; set; }
+    public virtual Package Package { get; set; }
+    
+    public long ClubFeatureId { get; set; }
+    public virtual ClubFeature ClubFeature { get; set; }
+    
+    public bool IsIncluded { get; set; } = true;  // آیا این فیچر در پکیج هست؟
+}
+```
+
+### ۳.۴ تغییرات Entity — ClubMembership
+
+```csharp
+public class ClubMembership : BaseAuditableEntity
+{
+    // ... فیلدهای فعلی حفظ می‌شوند ...
+    
+    // === فیلد جدید ===
+    public long PackageId { get; set; }              // کدام پکیج خریداری شده
+    public virtual Package Package { get; set; }
+}
+```
+
+### ۳.۵ تغییرات Entity — ClubMembershipCycle
+
+```csharp
+public class ClubMembershipCycle : BaseAuditableEntity
+{
+    // ... فیلدهای فعلی حفظ می‌شوند ...
+    
+    // === فیلد جدید ===
+    public long PackageId { get; set; }              // پکیج این سایکل
+    public virtual Package Package { get; set; }
+    // PackageAmount قبلاً وجود دارد — از Package.Price پر می‌شود
+}
+```
+
+### ۳.۶ تغییرات Entity — WeeklyCommissionPool
+
+```csharp
+public class WeeklyCommissionPool : BaseAuditableEntity
+{
+    // ... فیلدهای فعلی حفظ می‌شوند ...
+    
+    // === فیلد جدید ===
+    public long PackageId { get; set; }              // Pool جداگانه برای هر پکیج
+    public virtual Package Package { get; set; }
+}
+```
+
+### ۳.۷ جریان پول جدید
+
+```
+پکیج نقره‌ای (۵.۶M):
+    ├── Balance        += ۵,۶۰۰,۰۰۰
+    ├── DiscountBalance += ۱۱,۲۰۰,۰۰۰ (×۲)
+    └── CommissionPool += ActivationFee مخصوص نقره‌ای
+
+پکیج طلایی/پایه (۵۶M):
+    ├── Balance        += ۵۶,۰۰۰,۰۰۰
+    ├── DiscountBalance += ۱۱۲,۰۰۰,۰۰۰ (×۲)
+    └── CommissionPool += ۲۵,۲۰۰,۰۰۰
+
+پکیج الماسی (??M):
+    ├── Balance        += ??
+    ├── DiscountBalance += ?? (×۲)
+    └── CommissionPool += ActivationFee مخصوص الماسی
+```
+
+---
+
+## ۴. محاسبه پورسانت — تغییرات
+
+### ۴.۱ وضعیت فعلی
+
+```
+یک WeeklyCommissionPool برای کل هفته
+    ↓
+TotalAmount = مجموع ActivationFee همه فعالسازی‌ها
+    ↓
+ValuePerBalance = TotalAmount ÷ مجموع Balance‌ها
+    ↓
+همه یکسان محاسبه می‌شوند
+```
+
+### ۴.۲ وضعیت هدف
+
+```
+برای هر پکیج، یک WeeklyCommissionPool جداگانه:
+
+Pool_نقره‌ای:
+    TotalAmount = مجموع ActivationFee خریداران نقره‌ای این هفته
+    Balance‌ها = فقط از شبکه خریداران نقره‌ای
+    ValuePerBalance = Pool_نقره‌ای ÷ Balance_نقره‌ای
+
+Pool_طلایی:
+    TotalAmount = مجموع ActivationFee خریداران طلایی این هفته
+    Balance‌ها = فقط از شبکه خریداران طلایی
+    ValuePerBalance = Pool_طلایی ÷ Balance_طلایی
+```
+
+### ۴.۳ نکته مهم: ساختار شبکه یکی است
+
+```
+                    [Ali]
+                   /     \
+              [Sara]     [Reza]        ← شبکه باینری یکی‌ست
+             /    \      /    \
+          [M1]  [M2]  [M3]  [M4]
+
+ولی محاسبات جدا:
+  - Ali با پکیج طلایی → پورسانت از Pool طلایی
+  - Sara با پکیج نقره‌ای → پورسانت از Pool نقره‌ای
+  - Reza با پکیج طلایی → پورسانت از Pool طلایی
+```
+
+### ۴.۴ تغییرات Stored Procedure
+
+**`sp_CalculateWeeklyBalances`** باید:
+- پارامتر `@PackageId` بگیرد
+- فقط کاربرانی که این پکیج را خریده‌اند فیلتر کند
+- برای هر پکیج جداگانه اجرا شود
+
+**`sp_CalculateWeeklyCommissionPool`** باید:
+- پارامتر `@PackageId` بگیرد
+- Pool مخصوص آن پکیج را بخواند
+- پرداخت‌ها فقط به خریداران آن پکیج اختصاص یابد
+
+---
+
+## ۵. فیچرهای باشگاه مشتریان بر اساس پکیج
+
+### ۵.۱ وضعیت فعلی
+
+وقتی کاربر فعال می‌شود، **همه ۴ فیچر** یکجا assign می‌شوند:
+```csharp
+// ActivateClubMembershipCommandHandler — خط ~350
+var allFeatureIds = ClubFeatureTypeExtensions.GetAllFeatureIds();
+foreach (var featureId in allFeatureIds)
+{
+    userClubFeatures.Add(new UserClubFeature { ... });
+}
+```
+
+### ۵.۲ وضعیت هدف
+
+فیچرها بر اساس جدول `PackageFeature` تعیین می‌شوند:
+
+| فیچر | نقره‌ای | طلایی (پایه) | الماسی |
+|------|---------|-------------|--------|
+| چتیکا | ❌ | ✅ | ✅ |
+| بیمه | ❌ | ✅ | ✅ |
+| تریپ | ✅ | ✅ | ✅ |
+| لرن | ✅ | ✅ | ✅ |
+| فیچر VIP | ❌ | ❌ | ✅ |
+
+*مقادیر بالا نمونه‌ای هستند — قابل تنظیم از BackOffice*
+
+### ۵.۳ تغییر در ActivateClubMembershipHandler
+
+```
+قبلی:
+  GetAllFeatureIds() → assign all
+
+جدید:
+  Package.PackageFeatures
+    .Where(pf => pf.IsIncluded)
+    .Select(pf => pf.ClubFeatureId)
+    → assign only included features
+```
+
+---
+
+## ۶. تغییرات UI — FrontOffice
+
+### ۶.۱ صفحه پکیج‌ها (کاشی‌ها)
+
+```
+┌─────────────────────────────────────────────────────┐
+│              انتخاب پکیج باشگاه مشتریان              │
+├─────────────┬──────────────┬──────────────┬─────────┤
+│             │              │              │         │
+│  🥈 نقره‌ای  │  🥇 طلایی     │  💎 الماسی    │  ⭐ ویژه │
+│  ۵.۶M       │  ۵۶M         │  ؟؟M         │  ؟؟M   │
+│             │              │              │         │
+│ ● لرن       │ ● چتیکا      │ ● همه        │ ● همه  │
+│ ● تریپ      │ ● بیمه       │ ● + VIP      │ ● +... │
+│             │ ● تریپ       │              │         │
+│             │ ● لرن        │              │         │
+│             │              │              │         │
+│ [انتخاب]    │ [انتخاب]     │ [انتخاب]     │[انتخاب]│
+└─────────────┴──────────────┴──────────────┴─────────┘
+```
+
+### ۶.۲ مدال پرداخت — پکیج پایه (طلایی)
+
+```
+┌─────────────────────────────────────────┐
+│        خرید پکیج طلایی — ۵۶M تومان       │
+│                                         │
+│  توضیحات: ...                            │
+│                                         │
+│  روش‌های پرداخت:                         │
+│  ┌─────────────────────────────────┐    │
+│  │  💎 خرید از طریق الماس دایا      │    │
+│  └─────────────────────────────────┘    │
+│  ┌─────────────────────────────────┐    │
+│  │  💳 پرداخت مستقیم (درگاه بانکی) │    │
+│  └─────────────────────────────────┘    │
+└─────────────────────────────────────────┘
+```
+
+### ۶.۳ مدال پرداخت — پکیج‌های دیگر (نقره‌ای و بالاتر)
+
+```
+┌─────────────────────────────────────────┐
+│      خرید پکیج نقره‌ای — ۵.۶M تومان      │
+│                                         │
+│  توضیحات: ...                            │
+│  ویژگی‌ها: لرن، تریپ                     │
+│                                         │
+│  ┌─────────────────────────────────┐    │
+│  │  💳 پرداخت و فعال‌سازی           │    │
+│  └─────────────────────────────────┘    │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## ۷. بخش‌های تحت تاثیر (Impact Analysis)
+
+### ۷.۱ جدول تاثیرپذیری
+
+| # | لایه | فایل/بخش | نوع تغییر | شدت |
+|---|------|----------|-----------|-----|
+| ۱ | **Domain** | `Package.cs` | اضافه فیلد | 🟡 متوسط |
+| ۲ | **Domain** | `PackageFeature.cs` — **جدید** | Entity جدید | 🔴 زیاد |
+| ۳ | **Domain** | `ClubMembership.cs` | اضافه `PackageId` | 🟡 متوسط |
+| ۴ | **Domain** | `ClubMembershipCycle.cs` | اضافه `PackageId` | 🟡 متوسط |
+| ۵ | **Domain** | `WeeklyCommissionPool.cs` | اضافه `PackageId` | 🔴 زیاد |
+| ۶ | **Domain** | `SystemConstants.cs` | حذف hardcode‌ها → خوانش از Package | 🟡 متوسط |
+| ۷ | **Application** | `ActivateClubMembershipCommandHandler` | فیچر بر اساس پکیج | 🔴 زیاد |
+| ۸ | **Application** | `InitiateBasePackagePaymentCommandHandler` | حذف ID=4 hardcoded | 🟡 متوسط |
+| ۹ | **Application** | `VerifyBasePackagePaymentCommandHandler` | شارژ متناسب با پکیج | 🔴 زیاد |
+| ۱۰ | **Application** | `VerifyPackagePurchasePaymentCommandHandler` | شارژ متناسب با پکیج | 🔴 زیاد |
+| ۱۱ | **Application** | `ManualPaymentCommandHandler` | شارژ متناسب با پکیج | 🟡 متوسط |
+| ۱۲ | **Application** | `CustomerPurchasePackageCommandHandler` | پشتیبانی روش‌های پرداخت پکیج | 🟡 متوسط |
+| ۱۳ | **Infra** | `sp_CalculateWeeklyBalances` | پارامتر PackageId | 🔴 زیاد |
+| ۱۴ | **Infra** | `sp_CalculateWeeklyCommissionPool` | Pool جداگانه هر پکیج | 🔴 زیاد |
+| ۱۵ | **Infra** | `WeeklyCommissionCalculationService` | Loop روی پکیج‌ها | 🟡 متوسط |
+| ۱۶ | **Infra** | EF Configurations | جدول جدید + FK‌ها | 🟡 متوسط |
+| ۱۷ | **Infra** | Database Migration | schema changes | 🟡 متوسط |
+| ۱۸ | **Proto** | `package.proto` | فیلدهای جدید پکیج | 🟢 کم |
+| ۱۹ | **Proto** | `clubmembership.proto` | PackageId در response | 🟢 کم |
+| ۲۰ | **Proto** | `commission.proto` | PackageId در pool/payout | 🟢 کم |
+| ۲۱ | **FrontOffice** | صفحه انتخاب پکیج | UI جدید (کاشی‌ها) | 🔴 زیاد |
+| ۲۲ | **FrontOffice** | مدال پرداخت | دو مدال متفاوت | 🔴 زیاد |
+| ۲۳ | **FrontOffice** | `MyPackages.razor` | نمایش نوع پکیج | 🟡 متوسط |
+| ۲۴ | **FrontOffice** | `ActivateClubDialog.razor` | ارتباط با پکیج | 🟡 متوسط |
+| ۲۵ | **BackOffice** | صفحه مدیریت پکیج‌ها | CRUD فیلدهای جدید | 🟡 متوسط |
+| ۲۶ | **BackOffice** | صفحه فیچر پکیج‌ها — **جدید** | ماتریس پکیج×فیچر | 🔴 زیاد |
+| ۲۷ | **BackOffice** | `ActivateClubDialog.razor` | انتخاب پکیج | 🟡 متوسط |
+
+### ۷.۲ ریسک‌ها
+
+| ریسک | احتمال | شدت | راه‌حل |
+|------|--------|-----|--------|
+| داده‌های فعلی — کاربران بدون PackageId | قطعی | زیاد | Migration: کاربران فعلی → PackageId = پکیج پایه |
+| Commission Pool فعلی بدون PackageId | قطعی | زیاد | Migration: Pool‌های موجود → PackageId = پکیج پایه |
+| SP تغییر → محاسبات اشتباه | متوسط | بحرانی | تست جامع + محیط staging |
+| مبالغ hardcoded در جاهای پراکنده | زیاد | متوسط | Audit کامل کدبیس |
+| عدم سازگاری FrontOffice/BackOffice | متوسط | متوسط | تست end-to-end |
+
+---
+
+## ۸. فازبندی پیاده‌سازی
+
+### فاز ۱ — زیرساخت (Domain + DB) ≈ ۳-۴ روز
+
+| تسک | شرح |
+|-----|------|
+| T1.1 | بروزرسانی `Package` entity (فیلدهای جدید) |
+| T1.2 | ایجاد `PackageFeature` entity + EF Configuration |
+| T1.3 | اضافه کردن `PackageId` به `ClubMembership` |
+| T1.4 | اضافه کردن `PackageId` به `ClubMembershipCycle` |
+| T1.5 | اضافه کردن `PackageId` به `WeeklyCommissionPool` |
+| T1.6 | Database Migration + Seed data (پکیج پایه + فیچرها) |
+| T1.7 | Migration: کاربران/Pool‌های فعلی → PackageId = پکیج پایه |
+| T1.8 | بروزرسانی Proto‌ها |
+
+### فاز ۲ — منطق کسب‌وکار (Application) ≈ ۴-۵ روز
+
+| تسک | شرح |
+|-----|------|
+| T2.1 | بروزرسانی `ActivateClubMembershipCommandHandler` — فیچر بر اساس پکیج |
+| T2.2 | بروزرسانی Verify handlers — شارژ کیف پول متناسب با پکیج |
+| T2.3 | حذف مقادیر hardcoded از `SystemConstants` → خوانش از Package |
+| T2.4 | بروزرسانی `InitiateBasePackagePayment` → Generic `InitiatePackagePayment` |
+| T2.5 | بروزرسانی `ManualPaymentCommandHandler` — پشتیبانی پکیج متغیر |
+| T2.6 | CRUD پکیج با فیلدهای جدید (gRPC handlers) |
+| T2.7 | CRUD `PackageFeature` (ماتریس پکیج×فیچر) |
+
+### فاز ۳ — محاسبه پورسانت ≈ ۳-۴ روز
+
+| تسک | شرح |
+|-----|------|
+| T3.1 | بروزرسانی `sp_CalculateWeeklyBalances` — فیلتر بر اساس PackageId |
+| T3.2 | بروزرسانی `sp_CalculateWeeklyCommissionPool` — Pool جداگانه |
+| T3.3 | بروزرسانی `WeeklyCommissionCalculationService` — Loop روی پکیج‌ها |
+| T3.4 | تست محاسبات با داده واقعی |
+
+### فاز ۴ — UI (FrontOffice + BackOffice) ≈ ۴-۵ روز
+
+| تسک | شرح |
+|-----|------|
+| T4.1 | صفحه کاشی‌های پکیج (FrontOffice) |
+| T4.2 | مدال پرداخت پکیج پایه (دایا + مستقیم) |
+| T4.3 | مدال پرداخت پکیج‌های دیگر (فقط مستقیم) |
+| T4.4 | بروزرسانی `MyPackages.razor` — نمایش نوع پکیج |
+| T4.5 | بروزرسانی `ActivateClubDialog.razor` — ارتباط با پکیج |
+| T4.6 | BackOffice: CRUD پکیج با فیلدهای جدید |
+| T4.7 | BackOffice: صفحه ماتریس فیچرهای پکیج |
+| T4.8 | BackOffice: `ActivateClubDialog` — انتخاب پکیج |
+
+### فاز ۵ — تست و استقرار ≈ ۲-۳ روز
+
+| تسک | شرح |
+|-----|------|
+| T5.1 | تست end-to-end فلوی خرید هر پکیج |
+| T5.2 | تست محاسبه پورسانت جداگانه |
+| T5.3 | تست migration داده‌های فعلی |
+| T5.4 | Deploy به staging + تست |
+| T5.5 | Deploy به production |
+
+---
+
+## ۹. Seed Data — پکیج‌های اولیه
+
+```sql
+-- Migration: Seed packages
+INSERT INTO Packages (Title, Description, Price, IsActive, IsBasePackage, 
+    SupportsDayaPurchase, SupportsDirectPurchase, ActivationFee, GiftValue, 
+    DiscountMultiplier, SortOrder)
+VALUES
+    ('نقره‌ای', 'پکیج نقره‌ای باشگاه مشتریان', 5600000, 1, 0, 
+     0, 1, ???, ???, 2.0, 1),
+    ('طلایی', 'پکیج طلایی باشگاه مشتریان (پایه)', 56000000, 1, 1, 
+     1, 1, 25200000, 25200000, 2.0, 2);
+
+-- Migration: ربط فیچرها به پکیج‌ها
+INSERT INTO PackageFeatures (PackageId, ClubFeatureId, IsIncluded) VALUES
+    -- نقره‌ای: فقط تریپ و لرن
+    (@silverId, @tripId, 1),
+    (@silverId, @learnId, 1),
+    -- طلایی: همه فیچرها
+    (@goldId, @chatikaId, 1),
+    (@goldId, @bimeId, 1),
+    (@goldId, @tripId, 1),
+    (@goldId, @learnId, 1);
+
+-- Migration: کاربران فعلی → پکیج پایه
+UPDATE ClubMemberships SET PackageId = @goldId WHERE PackageId IS NULL;
+UPDATE ClubMembershipCycles SET PackageId = @goldId WHERE PackageId IS NULL;
+UPDATE WeeklyCommissionPools SET PackageId = @goldId WHERE PackageId IS NULL;
+```
+
+---
+
+## ۱۰. سوالات باز (نیاز به تصمیم‌گیری)
+
+| # | سوال | گزینه‌ها |
+|---|------|---------|
+| ۱ | `ActivationFee` و `GiftValue` پکیج نقره‌ای چقدر باشد؟ | نسبت به قیمت؟ مقدار ثابت؟ |
+| ۲ | آیا کاربر می‌تواند بعداً پکیج خود را ارتقا دهد (upgrade)؟ | بله → فقط مابه‌التفاوت / خیر |
+| ۳ | `DiscountMultiplier` برای همه پکیج‌ها ×۲ باشد؟ | یکسان / متفاوت به ازای هر پکیج |
+| ۴ | ضریب `MagicWallet` (×۲.۵) برای پکیج‌های کوچکتر هم همان باشد؟ | بله / خیر |
+| ۵ | فیچرهای پکیج نقره‌ای دقیقاً کدام‌ها هستند؟ | لرن+تریپ؟ فقط لرن؟ |
+| ۶ | آیا یک کاربر می‌تواند چند پکیج همزمان داشته باشد؟ | فقط یکی / امکان خرید چندتا |
+| ۷ | نام و تعداد دقیق پکیج‌ها چیست؟ | نقره‌ای+طلایی؟ بیشتر؟ |
+| ۸ | کاربرانی که با دایا فعال شدن، چه پکیجی دارند؟ | طلایی (پایه) |
+
+---
+
+## ۱۱. تخمین زمانی
+
+| فاز | مدت | وابستگی |
+|-----|------|---------|
+| فاز ۱ — زیرساخت | ۳-۴ روز | — |
+| فاز ۲ — منطق | ۴-۵ روز | فاز ۱ |
+| فاز ۳ — پورسانت | ۳-۴ روز | فاز ۱ |
+| فاز ۴ — UI | ۴-۵ روز | فاز ۲ |
+| فاز ۵ — تست | ۲-۳ روز | فاز ۳, ۴ |
+| **مجموع** | **~۱۶-۲۱ روز کاری** | |
+
+> فازهای ۲ و ۳ قابل موازی‌سازی هستند.

business/BUSINESS-01-CLUB-COMMISSION.md

@@ -0,0 +1,236 @@
+# 🏆 سیستم باشگاه، کمیسیون و درخت شبکه‌ای
+
+> **منابع ادغام‌شده:** `club-commission-system-complete.md`, `balance-calculation-rules.md`, `club-membership-contract-system.md`  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet کامل + بهبود مدیریت اعضا)
+
+---
+
+## ۱. مفاهیم کلیدی
+
+| مفهوم | توضیح |
+|-------|--------|
+| **عضویت باشگاه** | خرید پکیج طلایی (۵۶M) → فعالسازی (۲۵.۲M) → عضو فعال باشگاه |
+| **درخت باینری** | هر کاربر حداکثر ۲ فرزند مستقیم (چپ/راست) — بدون محدودیت عمق |
+| **کمیسیون هفتگی** | محاسبه بر اساس تعادل چپ/راست — یکشنبه ۰۰:۰۵ (Hangfire cron) |
+| **۳ کیف پول** | `Balance` (نقدی) + `NetworkBalance` (طلایی/کمیسیون) + `DiscountBalance` (اعتباری) |
+| **کیف‌پول جادویی** | وقتی Balance=0 → حالت Magic فعال → شارژ ×2.5 → سقف 100M/دور |
+| **چرخه عضویت** | `ClubMembershipCycle` — هر خرید پکیج = یک دور جدید (برای تاریخ کمیسیون) |
+
+---
+
+## ۲. ساختار درخت باینری
+
+```mermaid
+graph TD
+    ROOT["Root"] --- L["Left"]
+    ROOT --- R["Right"]
+    L --- L1["L1"] & L2["L2"]
+    R --- R1["R1"] & R2["R2"]
+    L1 --- L1a["..."] & L1b["..."]
+    L2 --- L2a["..."] & L2b["..."]
+    R1 --- R1a["..."] & R1b["..."]
+    R2 --- R2a["..."] & R2b["..."]
+```
+
+> ← بدون محدودیت عمق
+
+**قوانین:**
+- هر نود حداکثر ۲ فرزند (Binary) — `MaxDirectChildrenPerLeg = 1`
+- جایگذاری: `LegPosition` ∈ {Left=0, Right=1} (enum `NetworkLeg`)
+- مدل شبکه مستقیم روی entity `User` — فیلدهای `NetworkParentId`, `LegPosition`, `NetworkChildren`
+- محاسبه کمیسیون تا عمق ۱۵ سطح (`CommissionMaxNetworkLevel = 15`) — اما درخت بدون محدودیت رشد می‌کند
+
+---
+
+## ۳. فلوی عضویت و فعالسازی
+
+```mermaid
+flowchart TD
+    A["خرید پکیج طلایی — 56M"] --> B["نمایش مودال قرارداد\nغیرقابل‌بسته‌شدن"]
+    B --> C["مشاهده متن قرارداد\nReadContract RPC"]
+    C --> D["درخواست OTP\nRequestContractOtp — Kavenegar"]
+    D --> E["وارد کردن کد\nVerifyContractOtp"]
+    E --> F["امضای قرارداد\nAcceptContract"]
+
+    F --> G["شارژ ۲ کیف‌پول\nBalance += 56M\nDiscountBalance += 112M"]
+    F --> H["کسر فعالسازی\n−25.2M از Balance"]
+    F --> I["واریز 25.2M\nبه Pool هفتگی"]
+    F --> J["قرارگیری در\nدرخت باینری"]
+    F --> K["رفرش JWT Token\nclaims جدید"]
+```
+
+> ⚠️ در خرید با وام دایا: Balance += 56M, DiscountBalance += 112M (DayaLoanAmount × 2)  
+> NetworkBalance شارژ نمی‌شود — فقط برای کمیسیون
+
+---
+
+## ۴. الگوریتم محاسبه کمیسیون هفتگی
+
+### ۴.۱ فرمول ۴ مرحله‌ای
+
+```
+مرحله ۱: جمع فروش هر پا
+  SumLeft  = Σ(فروش‌های پای چپ در هفته جاری + CanOverLeft)
+  SumRight = Σ(فروش‌های پای راست در هفته جاری + CanOverRight)
+
+مرحله ۲: محاسبه تعادل
+  WeeklyBalance = MIN(SumLeft, SumRight)
+
+مرحله ۳: محاسبه باقیمانده (Carryover)
+  CanOverLeft  = SumLeft  - WeeklyBalance
+  CanOverRight = SumRight - WeeklyBalance
+
+مرحله ۴: سقف هفتگی
+  IF WeeklyBalance > 300  →  WeeklyBalance = 300
+  IF CanOverLeft > 300    →  Flush (CanOverLeft = 0)
+  IF CanOverRight > 300   →  Flush (CanOverRight = 0)
+```
+
+### ۴.۲ مثال عددی (درخت ۵ سطحی)
+
+```
+هفته ۱:  چپ=120, راست=80  →  Balance=80, Over(L=40, R=0)
+هفته ۲:  چپ=90+40=130, راست=150  →  Balance=130, Over(L=0, R=20)
+هفته ۳:  چپ=200, راست=180+20=200  →  Balance=200, Over(L=0, R=0)
+هفته ۴:  چپ=500, راست=100  →  Balance=100, Over(L=400→FLUSH=0, R=0)
+```
+
+### ۴.۳ Pool هفتگی و توزیع
+
+```mermaid
+flowchart LR
+    A["هر فعالسازی عضو\n25.2M واریز"] --> B["Pool هفتگی"]
+    B --> C["sp_CalculateWeeklyBalances"]
+    C --> D["sp_CalculateWeeklyCommissionPool"]
+    D --> E["توزیع بر اساس\nUserBalance / TotalBalance"]
+```
+
+> فرمت هفته: `YYYY-Www` (شمسی، شنبه‌پایه)
+
+### ۴.۴ فیلتر کاربران Magic از کمیسیون
+
+> ⚠️ **کاربرانی که در حالت Magic هستند (`WalletMode = 1`) از محاسبات کمیسیون هفتگی خارج می‌شوند.**
+
+```
+فیلتر در ۳ نقطه:
+  ✅ CalculateWeeklyBalancesCommandHandler.cs  →  WHERE wallet.WalletMode != Magic
+  ✅ OrmCommissionCalculationStrategy.cs       →  فیلتر LINQ
+  ✅ sp_CalculateWeeklyBalances.sql            →  NOT EXISTS (WalletMode=1)
+
+تاریخ محاسبه:
+  قبل:  ClubMembership.ActivatedAt (مشکل: بعد از خرید مجدد overwrite می‌شد)
+  بعد:  ClubMembershipCycle.PackagePurchasedAt (هر دور تاریخ مستقل)
+```
+
+---
+
+## ۵. تنظیمات سیستمی (SystemConstants)
+
+| ثابت (SystemConstants) | مقدار | توضیح |
+|------|-------|--------|
+| `ClubActivationFee` | 25,200,000 | هزینه فعالسازی (ریال) |
+| `ClubMembershipGiftValue` | 25,200,000 | واریز به Pool |
+| `BasePackageAmount` | 56,000,000 | قیمت پکیج طلایی (ریال) |
+| `DayaLoanAmount` | 56,000,000 | مبلغ وام دایا (ریال) |
+| `CommissionMaxWeeklyBalancesPerLeg` | 300 | سقف هفتگی هر پا |
+| `CommissionMaxNetworkLevel` | 15 | عمق محاسبه کمیسیون (نه محدودیت درخت) |
+| `MaxDirectChildrenPerLeg` | 1 | حداکثر فرزند مستقیم هر پا |
+| `MinimumWithdrawAmount` | 1,000,000 | حداقل مبلغ برداشت (ریال) |
+| `ShopVAT` | 0.1 (10%) | مالیات ارزش افزوده |
+| `MagicWalletMultiplier` | 2.5 | ضریب شارژ جادویی (واریز × 2.5) |
+| `MagicWalletMaxDeposit` | 1,000,000,000 | سقف واریز هر دور (100M تومان = 1B ریال) |
+| `MagicWalletMaxCredit` | 2,500,000,000 | سقف اعتبار هر دور (250M تومان) |
+| `CommissionCalculationMethod` | "SP" | روش محاسبه = Stored Procedure |
+
+---
+
+## ۶. ۳ سناریوی خرید پکیج طلایی
+
+| سناریو | فلو | وضعیت |
+|--------|------|--------|
+| **وام دایا** | درخواست وام → تأیید → Balance=56M + Discount=112M (مجموع ۱۶۸M) | ✅ پیاده‌شده |
+| **درگاه مستقیم** | IPG → callback → Balance=56M + Discount=112M (مجموع ۱۶۸M) | ✅ پیاده‌شده |
+| **پرداخت دستی** | کارت‌به‌کارت → آپلود رسید → تأیید ادمین → شارژ | ⚠️ طراحی‌شده |
+
+---
+
+## ۷. یکپارچه‌سازی وام دایا
+
+```mermaid
+flowchart TD
+    A["Hangfire Worker\nهر ۲۰ دقیقه — */20 * * * *"] --> B["بررسی درخواست‌های pending"]
+    B --> C["ارسال به API دایا\nMock/Real switchable"]
+    C --> D["دریافت نتیجه"]
+    D --> E["Balance += 56M"]
+    D --> F["DiscountBalance += 112M\nDayaLoanAmount × 2"]
+```
+
+> مجموع شارژ: 168M — Hangfire retry: `[AutomaticRetry(Attempts = 3)]`
+
+---
+
+## ۸. Chatika AI — اولین فیچر باشگاه
+
+| آیتم | جزئیات |
+|------|---------|
+| **نوع** | Hangfire recurring job |
+| **فرکانس** | هر ۵ دقیقه |
+| **Retry** | Polly — ۳ تلاش، backoff نمایی |
+| **فعال‌سازی** | فقط برای اعضای فعال باشگاه |
+| **وضعیت** | ✅ Production ready |
+
+---
+
+## ۹. کیف‌پول جادویی (Magic Wallet) ✅
+
+> **وضعیت: فاز ۱ تا ۵ پیاده‌سازی شده — فاز ۶ باقیمانده**  
+> **مرجع کامل:** [MAGIC-WALLET-SPEC](../roadmap/MAGIC-WALLET-SPEC.md)
+
+### ۹.۱ چرخه کامل
+
+```mermaid
+flowchart TD
+    A["خرید پکیج 56M\nBalance=56M, Discount=112M"] --> B["خرید از فروشگاه\nBalance کم می‌شود"]
+    B --> C{"Balance = 0?"}
+    C -->|خیر| B
+    C -->|بله| D{"عضو باشگاه فعال؟"}
+    D -->|خیر| E["حالت عادی باقی بمان"]
+    D -->|بله| F["🪄 ورود به حالت جادویی\nWalletMode = Magic"]
+    F --> G["شارژ از درگاه\nواریز × 2.5 = اعتبار Balance"]
+    G --> H{"Balance=0 AND\nTotalDeposited≥100M?"}
+    H -->|خیر| G
+    H -->|بله| I["خروج از جادویی\nWalletMode = Normal"]
+    I --> J["خرید مجدد پکیج\nفقط IPG — بدون دایا"]
+    J --> A
+```
+
+### ۹.۲ قوانین کلیدی
+
+| قانون | مقدار |
+|-------|-------|
+| ضریب شارژ | واریز × 2.5 = اعتبار Balance |
+| سقف واریز/دور | 100M تومان (1B ریال) |
+| سقف اعتبار/دور | 250M تومان (2.5B ریال) |
+| کمیسیون در Magic | ❌ غیرفعال |
+| شرط خروج | Balance=0 **و** TotalDeposited≥100M (هر دو همزمان) |
+| ریست سقف | هر خرید مجدد پکیج → سقف از صفر |
+
+### ۹.۳ Entity‌های جدید
+
+```csharp
+// فیلدهای جدید UserWallet
+public WalletMode WalletMode { get; set; }           // Normal=0, Magic=1
+public long MagicTotalDeposited { get; set; }         // مجموع واریزی دور فعلی
+public long MagicTotalCredited { get; set; }          // مجموع اعتبار دریافتی
+public DateTime? MagicActivatedAt { get; set; }
+public DateTime? MagicCompletedAt { get; set; }
+
+// Entity جدید — حل مشکل تاریخ کمیسیون
+public class ClubMembershipCycle {
+    public long Id { get; set; }
+    public long ClubMembershipId { get; set; }
+    public int CycleNumber { get; set; }               // شماره دور (1, 2, 3, ...)
+    public DateTime PackagePurchasedAt { get; set; }   // تاریخ خرید این دور
+    public bool IsCurrentCycle { get; set; }           // دور فعلی
+}
+```

business/BUSINESS-02-PAYMENT-FINANCE.md

@@ -0,0 +1,284 @@
+# 💰 سیستم مالی، پرداخت و درگاه‌ها
+
+> **منابع ادغام‌شده:** `payment-gateway.md`, `payment-architecture-pyms.md`, `daya-loan-integration.md`, `manual-payment-system.md`, `discount-shop-business.md`  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: تصحیح مدل تومان/ریال + فیکس ZarinPal Verify + امنیت Callback URL)
+
+---
+
+## ۱. معماری کلی مالی
+
+```mermaid
+flowchart TD
+    subgraph GATEWAYS["درگاه‌ها"]
+        ZP["ZarinPal\nIPG"]
+        DL["Daya Loan\nAPI"]
+        MP["Manual Pay\nCard2Card"]
+        DW["Discount Wallet\nInternal"]
+    end
+
+    ZP --> PYMS["PYMS — Payment Service\ngRPC ↔ CMS ↔ FrontOffice/BackOffice"]
+    DL --> PYMS
+    MP --> PYMS
+    DW --> PYMS
+
+    PYMS --> WALLETS
+
+    subgraph WALLETS["3 Wallet System"]
+        W1["💰 Balance\nکیف پول اصلی"]
+        W2["🌟 NetworkBalance\nپاداش تیمی"]
+        W3["🏷️ DiscountBalance\nکیف پول اعتباری"]
+    end
+```
+
+---
+
+## ۲. درگاه ZarinPal (IPG)
+
+> **✅ محل استفاده:** ZarinPal در چهار جا فعال است:
+> 1. **فروشگاه اعتباری** — باقیمانده بعد از کسر DiscountBalance (اگر > 0)
+> 2. **شارژ کیف‌پول اعتباری** — واریز مستقیم از پروفایل کاربر
+> 3. **خرید پکیج** — پرداخت مستقیم با کارت بانکی (هر دو شاخه فعال)
+> 4. **شارژ کیف‌پول جادویی** — واریز با ضریب ×2.5 (فقط در حالت Magic)
+>
+> ❌ **فروشگاه عادی (Regular Store) از ZarinPal استفاده نمی‌کند** — فقط کسر از Balance کیف‌پول
+
+### ۲.۱ فلوی پرداخت
+
+```mermaid
+flowchart TD
+    A["کاربر → انتخاب محصول\nدرخواست پرداخت"] --> B["CMS → CreatePaymentRequest\ngRPC to PYMS"]
+    B --> C["PYMS → ZarinPal API\nمبلغ ×۱۰ (تومان→ریال)\nدریافت Authority"]
+    C --> D["Redirect کاربر\nصفحه پرداخت ZarinPal"]
+    D --> E["بازگشت با Authority\nCMS VerifyPayment (مبلغ ×۱۰)"]
+    E -->|موفق| F["✅ ثبت سفارش\n+ شارژ کیف‌پول"]
+    E -->|ناموفق| G["❌ نمایش پیام خطا"]
+```
+
+> **✅ فیکس ZarinPal Verify (اسفند ۱۴۰۴ — `721661a`):**
+> - **باگ:** `VerifyPaymentAsync(authority)` با ۲ آرگومان → amount=0 → ZarinPal Code=-1
+> - **فیکس:** lookup `PaymentTransaction.Amount` از DB + استفاده از overload ۳ آرگومانه `VerifyPaymentAsync(authority, orderId, amount)`
+> - `IPaymentGatewayService` — default impl ۳ آرگومانه اضافه شد
+> - ۷ فایل تغییر: PackageService, TransactionsService, VerifyDiscountWalletChargeCommandHandler, VerifyPackagePurchaseCommandHandler, IPaymentGatewayService, MockPaymentGatewayService, DayaPaymentService
+
+### ۲.۲ تنظیمات ZarinPal
+
+| پارامتر | مقدار |
+|----------|-------|
+| `MerchantId` | `4225d555-5fa9-4df0-9b61-1ce152cbbba8` |
+| `CallbackUrl` | از `appsettings.json` خوانده می‌شود (نه از ورودی کاربر) |
+| `Sandbox` | `true` (staging) / `false` (production) |
+| `Currency` | DB: تومان — ZarinPal: ریال (×۱۰ هنگام ارسال) |
+
+> **✅ مدل ارزی (تصحیح اسفند ۱۴۰۴):**
+> - **DB:** `Package.Price` و همه مبالغ مالی به **تومان** ذخیره می‌شوند
+> - **CMS → ZarinPal:** `ZarinPalPaymentService` مبلغ را ×۱۰ می‌کند (`amountInRials = amount * 10`)
+> - **FrontOffice UI:** مبالغ مستقیم به تومان نمایش داده می‌شوند (بدون تبدیل)
+> - **FrontOffice → CMS:** مبالغ به تومان ارسال می‌شوند (FO هیچ تبدیلی انجام نمی‌دهد)
+> - **باگ قبلی ۱:** FO مبلغ تومان را ×۱۰ تبدیل می‌کرد + CMS/ZarinPal دوباره ×۱۰ → مبلغ ۱۰۰ برابر (فیکس: `2f9ef15`)
+> - **باگ قبلی ۲:** `FormattedPrice = Price / 10` اشتباه بود — Price از قبل تومان است (فیکس: `3c1a8ff` اصلاح شد)
+
+> **✅ امنیت Callback URL (اسفند ۱۴۰۴):**
+> - هیچ callback URL از ورودی کاربر خوانده نمی‌شود — همه از `appsettings.json` خوانده می‌شوند
+> - `PackageService` و `TransactionsService`: از `FrontOfficeBaseUrl` config
+> - `MagicWallet` و `DiscountWallet`: از `CmsBaseUrl` config
+> - جلوگیری از حمله Open Redirect
+
+> **تنظیمات محیطی:**
+> - `appsettings.json` + `appsettings.Staging.json`: `UseSandbox: true` (تست)
+> - `appsettings.Production.json`: `UseSandbox: false` (واقعی)
+> - Production URL: `cms.kbs1.ir` | FrontOffice GwUrl: `cms.kbs2.ir`
+
+---
+
+## ۳. سیستم وام دایا (DayaLoan)
+
+### ۳.۱ معماری
+
+```mermaid
+flowchart TD
+    A["Hangfire Recurring Job\nهر ۲۰ دقیقه — */20 * * * *"] --> B["DayaLoanProcessorJob.Execute"]
+    B --> C["بررسی LoanRequests\nStatus = Pending"]
+    C --> D["برای هر درخواست:"]
+    D --> E["ارسال به DayaLoan API\nAutomaticRetry Attempts=3"]
+    E -->|تأیید| F["✅ Balance += 56M\nDiscountBalance += 112M\n+ ثبت Transaction + Log"]
+    E -->|رد| G["❌ Status = Rejected\n+ ارسال SMS"]
+```
+
+### ۳.۲ Mock Mode
+
+```csharp
+// appsettings.json
+"DayaLoan": {
+    "UseMock": true,         // staging
+    "BaseUrl": "https://api.dayaloan.ir",
+    "ApiKey": "***",
+    "AutoApproveInMock": true
+}
+```
+
+### ۳.۳ مقادیر
+
+| آیتم | مقدار |
+|------|-------|
+| مبلغ وام (DayaLoanAmount) | ۵۶,۰۰۰,۰۰۰ ریال |
+| شارژ Balance | ۵۶,۰۰۰,۰۰۰ ریال |
+| شارژ DiscountBalance | ۱۱۲,۰۰۰,۰۰۰ ریال (دو برابر — DayaLoanAmount × 2) |
+| مجموع شارژ | ۱۶۸,۰۰۰,۰۰۰ ریال |
+| NetworkBalance | شارژ نمی‌شود |
+| بازپرداخت | طبق شرایط دایا |
+
+---
+
+## ۴. پرداخت دستی (کارت‌به‌کارت)
+
+> ⚠️ **وضعیت: طراحی‌شده — پیاده‌سازی نشده**
+
+```mermaid
+flowchart TD
+    A["کاربر → انتخاب کارت‌به‌کارت"] --> B["نمایش شماره‌کارت مقصد\n+ مبلغ"]
+    B --> C["کاربر → واریز\n+ آپلود تصویر رسید"]
+    C --> D["ادمین BackOffice\nمشاهده لیست درخواست‌ها"]
+    D --> E{"تأیید / رد؟"}
+    E -->|تأیید| F["✅ شارژ خودکار کیف‌پول"]
+    E -->|رد| G["❌ اطلاع‌رسانی به کاربر"]
+```
+
+**موجودیت‌های مورد نیاز:**
+- `ManualPaymentRequest` (UserId, Amount, ReceiptImage, Status, AdminNote)
+- `ManualPaymentStatus` enum: Pending, Approved, Rejected
+
+---
+
+## ۵. پرداخت ترکیبی فروشگاه اعتباری (Hybrid Payment)
+
+### ۵.۱ فرمول
+
+```
+قیمت محصول = 1,000,000 ریال
+MaxDiscountPercent محصول = 40%  (هر محصول درصد تخفیف مخصوص خود را دارد)
+
+سهم تخفیف = قیمت × MaxDiscountPercent% = 400,000
+
+⚠️ اگر DiscountBalance < سهم تخفیف → خطا: «موجودی کیف پول اعتباری کافی نیست»
+   (دیگر MIN استفاده نمی‌شود — کاربر باید موجودی کافی داشته باشد)
+
+باقیمانده → ZarinPal IPG = 1,000,000 - 400,000 = 600,000
+                                            ─────────
+                          مجموع             = 1,000,000
+
+ℹ️ تخفیف ثابت ۳۰% نیست — فیلد Product.MaxDiscountPercent (0-100) تعیین‌کننده است.
+```
+
+### ۵.۲ فلوی خرید فروشگاه اعتباری
+
+```mermaid
+flowchart TD
+    A["کاربر عضو باشگاه\nمشاهده محصول"] --> B["قیمت تخفیف‌خورده نمایش داده می‌شود"]
+    B --> C["افزودن به سبد\nمحاسبه MaxDiscount% هر محصول"]
+    C --> D["سهم تخفیف = قیمت × MaxDiscount%"]
+    D --> V{"DiscountBalance >= سهم تخفیف?"}
+    V -->|خیر| X["❌ خطا: موجودی کیف پول اعتباری کافی نیست"]
+    V -->|بله| E["باقیمانده = مجموع - سهم تخفیف"]
+    E --> F{"باقیمانده > 0?"}
+    F -->|بله| G["کسر DiscountBalance\n+ Redirect → ZarinPal IPG\nباقیمانده + 10% VAT"]
+    F -->|خیر| H["فقط کسر از DiscountBalance\nبدون درگاه → ثبت مستقیم"]
+    G --> LOG["ثبت UserWalletChangeLog"]
+    H --> LOG
+```
+
+### ۵.۳ دسترسی فروشگاه اعتباری
+
+| شرط | نتیجه |
+|------|--------|
+| `IsClubMember = true` | دسترسی به Discount Store |
+| `IsClubMember = false` | فقط Regular Store |
+| `DiscountBalance >= سهم تخفیف` | خرید مجاز |
+| `DiscountBalance < سهم تخفیف` | ❌ خطا: موجودی کیف پول اعتباری کافی نیست |
+
+### ۵.۴ UserWalletChangeLog (اسفند ۱۴۰۴ — فیکس)
+
+> **باگ:** هنگام خرید از فروشگاه اعتباری، `DiscountBalance` در دیتابیس کم می‌شد ولی هیچ
+> `UserWalletChangeLog` ثبت نمی‌شد → کاربر در تاریخچه کیف‌پول چیزی نمی‌دید.
+
+فیکس در ۳ هندلر:
+
+| هندلر | سناریو | فیکس |
+|--------|---------|------|
+| `PlaceOrderCommandHandler` | پرداخت کامل با DiscountBalance (بدون درگاه) | ✅ ثبت log با `ChangeDiscountValue = -amount` |
+| `CompleteOrderPaymentCommandHandler` | پرداخت ترکیبی (درگاه + DiscountBalance) | ✅ ثبت log بعد از verify موفق درگاه |
+| `VerifyDiscountWalletChargeCommandHandler` | شارژ کیف‌پول اعتباری | ✅ ثبت log با `ChangeDiscountValue = +amount` |
+
+---
+
+## ۶. PYMS — سرویس پرداخت مرکزی
+
+### ۶.۱ gRPC Services
+
+```protobuf
+service PaymentService {
+    rpc CreatePayment (CreatePaymentRequest) returns (CreatePaymentResponse);
+    rpc VerifyPayment (VerifyPaymentRequest) returns (VerifyPaymentResponse);
+    rpc GetPaymentStatus (GetPaymentStatusRequest) returns (PaymentStatusResponse);
+    rpc RefundPayment (RefundPaymentRequest) returns (RefundPaymentResponse);
+}
+```
+
+### ۶.۲ Transaction Types
+
+| نوع | کد | توضیح |
+|-----|-----|--------|
+| PackagePurchase | 1 | خرید پکیج طلایی |
+| StorePurchase | 2 | خرید از فروشگاه |
+| DiscountStorePurchase | 3 | خرید از فروشگاه اعتباری |
+| CommissionPayout | 4 | واریز کمیسیون هفتگی |
+| WalletCharge | 5 | شارژ مستقیم کیف‌پول |
+| ActivationFee | 6 | هزینه فعالسازی |
+| DayaLoanCharge | 7 | شارژ از وام دایا |
+| MagicWalletDeposit | 14 | واریز به کیف‌پول جادویی |
+| MagicWalletBonus | 15 | بونوس ضریب ×2.5 کیف‌پول جادویی |
+
+---
+
+## ۷. مالیات و VAT
+
+```
+هر دو فروشگاه از نرخ 10% استفاده می‌کنند:
+
+  Regular Store  → const vatRate = 0.10m  (hardcoded در SubmitShopBuyOrderCommandHandler)
+  Discount Store → VatCalculator.VAT_RATE = 0.10m
+  SystemConstants.ShopVAT = 0.1 (10%)
+
+قیمت نمایشی = قیمت پایه × (1 + 0.10)
+در صورتحساب: قیمت پایه + مالیات جداگانه نمایش داده می‌شود
+```
+
+---
+
+## ۸. خلاصه وضعیت پیاده‌سازی
+
+| ماژول | وضعیت | یادداشت |
+|-------|--------|---------|
+| ZarinPal IPG | ✅ کامل | **Production فعال** — MerchantId: `4225d555...` |
+| ZarinPal Verify | ✅ فیکس شده | رفع amount=0 با overload ۳ آرگومانه (`721661a`) |
+| Callback URL امنیت | ✅ فیکس شده | همه از config خوانده می‌شوند — جلوگیری از Open Redirect |
+| وام دایا | ✅ کامل | Mock mode فعال در staging |
+| پرداخت ترکیبی | ✅ کامل | Discount + IPG |
+| Pool هفتگی | ✅ کامل | SP + Hangfire |
+| WalletChangeLog | ✅ فیکس شده | لاگ تغییرات کیف‌پول در ۳ هندلر اضافه شد |
+| Validation کیف‌پول اعتباری | ✅ فیکس شده | ارور اگر موجودی کافی نباشد |
+| Toman/Rial مدل | ✅ تصحیح شده | DB=تومان، فقط ZarinPal ریال (×۱۰) — FO بدون تبدیل |
+| صفحه موفقیت پرداخت | ✅ بهبود | TransactionId + موجودی واقعی + دکمه بازگشت |
+| PackagePurchaseDialog | ✅ کامل | دیالوگ داینامیک کاشی‌ای با انتخاب روش پرداخت |
+| پرداخت دستی | ⬜ طراحی | نیاز به تصمیم مدیریت |
+| Refund | ⬜ طراحی | فقط در PYMS تعریف‌شده |
+| کیف‌پول جادویی (Magic) | ✅ کامل | فاز 1-6 پیاده‌سازی شده — Production فعال |
+
+### ۸.۱ نام‌گذاری استاندارد کیف‌پول‌ها (اسفند ۱۴۰۴)
+
+| فیلد دیتابیس | نام قدیم (UI) | نام جدید (UI) |
+|-------------|--------------|---------------|
+| `Balance` | عادی / اعتباری / نقدی | **کیف پول اصلی** |
+| `DiscountBalance` | تخفیفی / تخفیف | **کیف پول اعتباری** |
+| `NetworkBalance` | شبکه / طلایی / پورسانت | **پاداش تیمی** |
+
+> تغییرات UI در ۱۲ فایل (FrontOffice: 5, BackOffice: 7) اعمال شد.

business/BUSINESS-03-ECOMMERCE-STORES.md

@@ -0,0 +1,269 @@
+# 🛒 فروشگاه، موجودی و محصولات
+
+> **منابع ادغام‌شده:** `discount-shop-business.md`, `DISCOUNT-STORE-STATUS.md`, `package-purchase-system.md`, `INVENTORY-IMPROVEMENTS.md`, `INVENTORY-REFACTORING-STATUS.md`, `PRODUCT-BUNDLE-FEATURE.md`, `SHOP-UNIFICATION.md`  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: ExpirePendingOrders ۱۵ دقیقه + فروشگاه اعتباری نام‌گذاری)
+
+---
+
+## ۱. دو فروشگاه FourSat
+
+```mermaid
+flowchart LR
+    subgraph RS["Regular Store — /store"]
+        R1["همه کاربران"]
+        R2["پرداخت از Balance کیف‌پول"]
+        R3["قیمت عادی"]
+        R4["VAT = 10%"]
+    end
+
+    subgraph DS["Discount Store — /discount-store"]
+        D1["فقط اعضای باشگاه"]
+        D2["پرداخت ترکیبی تخفیف+نقد"]
+        D3["تخفیف بر اساس MaxDiscountPercent"]
+        D4["VAT = 10%"]
+    end
+
+    subgraph SHARED["مشترک"]
+        S1["Products"]
+        S2["Categories"]
+        S3["Inventory"]
+        S4["ProductImages 1:1"]
+    end
+
+    RS --> SHARED
+    DS --> SHARED
+```
+
+---
+
+## ۲. Lazy Loading محصولات
+
+### ۲.۱ API
+
+```csharp
+// ProductService.cs
+public record ProductListResult(List<ProductDto> Products, int TotalCount);
+
+public async Task<ProductListResult> GetProductsPagedAsync(
+    int skip, int take, 
+    Guid? categoryId = null, 
+    string? search = null)
+{
+    var request = new GetProductsRequest {
+        Pagination = new PaginationState { Skip = skip, Take = take },
+        CategoryId = categoryId?.ToString() ?? "",
+        SearchTerm = search ?? ""
+    };
+    // gRPC call...
+}
+```
+
+### ۲.۲ پیاده‌سازی UI (هر دو فروشگاه)
+
+```mermaid
+flowchart TD
+    A["بارگذاری اولیه: 12 محصول"] --> B["اسکرول → نمایش دکمه\nنمایش محصولات بیشتر"]
+    B --> C["کلیک → LoadMore\nskip += 12"]
+    C --> D["محصولات جدید append به لیست"]
+    D --> E{"Products.Count >= TotalCount?"}
+    E -->|خیر| B
+    E -->|بله| F["مخفی‌شدن دکمه"]
+```
+
+---
+
+## ۳. مدیریت موجودی (Inventory)
+
+### ۳.۱ بهبودهای اخیر
+
+| بهبود | توضیح | وضعیت |
+|-------|--------|--------|
+| Auto-Create | ایجاد خودکار رکورد موجودی هنگام ساخت محصول | ✅ |
+| Hangfire Worker | `InventorySyncJob` — بررسی دوره‌ای و ایجاد رکوردهای گمشده | ✅ |
+| Autocomplete | جستجوی محصول در صفحه موجودی BackOffice با autocomplete | ✅ |
+| Lazy Load | بارگذاری تنبل محصولات در هر دو فروشگاه | ✅ |
+
+### ۳.۲ Entity ها
+
+```csharp
+public class Inventory {
+    public Guid Id { get; set; }
+    public Guid ProductId { get; set; }         // FK → Product
+    public int Quantity { get; set; }            // موجودی فعلی
+    public int ReservedQuantity { get; set; }    // رزرو‌شده
+    public int MinimumStock { get; set; }        // حداقل موجودی (هشدار)
+    public bool TrackInventory { get; set; }     // آیا موجودی رصد شود؟
+}
+
+// فیلد کلیدی در Product:
+public int MaxDiscountPercent { get; set; }  // 0 تا 100 — درصد تخفیف در فروشگاه اعتباری
+```
+
+### ۳.۳ فلوی سفارش و موجودی
+
+```mermaid
+flowchart TD
+    A["سفارش جدید"] --> B{"Quantity - Reserved >= OrderQty?"}
+    B -->|بله| C["Reserved += OrderQty"]
+    C --> D{"پرداخت موفق؟"}
+    D -->|موفق| E["✅ Quantity -= OrderQty\nReserved -= OrderQty"]
+    D -->|ناموفق| F["❌ Reserved -= OrderQty\nآزادسازی"]
+    B -->|خیر| G["نمایش: موجودی کافی نیست"]
+```
+
+---
+
+## ۴. تصاویر محصول (۱:۱ مربعی)
+
+```
+AppImage Component (Shared):
+    • ObjectFit = Cover
+    • AspectRatio = 1:1 (مربع)
+    • Fallback = آیکون پیش‌فرض MudBlazor
+    • LazyLoading = true
+    
+اعمال در:
+    ✅ Regular Store — ProductCard
+    ✅ Discount Store — ProductCard
+    ✅ BackOffice — Product List
+    ✅ Product Detail Pages
+```
+
+---
+
+## ۵. باندل محصولات (Product Bundle)
+
+> ⚠️ **وضعیت: طراحی کامل — پیاده‌سازی نشده**
+
+### ۵.۱ مدل داده
+
+```csharp
+public class ProductBundle {
+    public Guid Id { get; set; }
+    public string Name { get; set; }
+    public string Description { get; set; }
+    public decimal OriginalPrice { get; set; }    // مجموع قیمت تکی
+    public decimal BundlePrice { get; set; }       // قیمت باندل
+    public decimal DiscountPercentage { get; set; }
+    public bool IsActive { get; set; }
+    public List<BundleItem> Items { get; set; }
+}
+
+public class BundleItem {
+    public Guid ProductId { get; set; }
+    public int Quantity { get; set; }
+}
+```
+
+### ۵.۲ فلو
+
+```mermaid
+flowchart TD
+    A["ادمین → ساخت باندل\nانتخاب محصولات + تعیین قیمت"] --> B["نمایش در فروشگاه\nبا تگ باندل"]
+    B --> C["خرید → تمام محصولات\nیکجا به سبد"]
+    C --> D["پرداخت → کسر موجودی\nهر محصول جداگانه"]
+```
+
+---
+
+## ۶. یکپارچه‌سازی فروشگاه‌ها (Shop Unification)
+
+### ۶.۱ اجزای مشترک
+
+| کامپوننت | کاربرد | وضعیت |
+|----------|--------|--------|
+| `ProductCard` | کارت محصول (۱:۱) | ✅ مشترک |
+| `AppImage` | نمایش تصویر | ✅ مشترک |
+| `CategoryFilter` | فیلتر دسته‌بندی | ✅ مشترک |
+| `SearchBar` | جستجوی محصول | ✅ مشترک |
+| `LoadMoreButton` | Lazy loading | ✅ مشترک |
+| `CartSummary` | خلاصه سبد | ⬜ جداگانه |
+
+### ۶.۲ مسیرهای Navigation
+
+```
+فروشگاه عادی:
+  /store                    → لیست محصولات
+  /store/product/{id}       → جزئیات محصول
+  /store/cart               → سبد خرید
+  /store/checkout            → پرداخت
+
+فروشگاه اعتباری:
+  /discount-store            → لیست محصولات
+  /discount-store/product/{id} → جزئیات
+  /discount-store/cart        → سبد (ترکیبی)
+  /discount-store/checkout    → پرداخت ترکیبی
+```
+
+---
+
+## ۷. دسته‌بندی‌ها (Categories)
+
+```mermaid
+graph TD
+    ROOT["دسته‌بندی‌ها"] --> A["سلامت و زیبایی"]
+    ROOT --> B["تغذیه"]
+    ROOT --> C["ورزشی"]
+
+    A --> A1["مکمل‌ها"]
+    A --> A2["مراقبت پوست"]
+    A --> A3["مراقبت مو"]
+
+    B --> B1["ارگانیک"]
+    B --> B2["رژیمی"]
+```
+
+> مدل: `Category (Id, Name, ParentId?, ImageUrl, IsActive, SortOrder)`
+
+---
+
+## ۸. خلاصه وضعیت
+
+| ماژول | وضعیت | درصد |
+|-------|--------|------|
+| فروشگاه عادی | ✅ کامل | 100% |
+| فروشگاه اعتباری | ✅ کامل | 100% |
+| Lazy Loading | ✅ کامل | 100% |
+| موجودی خودکار | ✅ کامل | 100% |
+| تصاویر مربعی | ✅ کامل | 100% |
+| انقضای سفارشات Pending | ✅ کامل | 100% |
+| باندل محصولات | ⬜ طراحی | 30% |
+| مقایسه محصول | ⬜ ایده | 0% |
+
+---
+
+## ۹. انقضای خودکار سفارشات Pending (ExpirePendingOrdersService)
+
+> سرویس پس‌زمینه‌ای که سفارشات فروشگاه اعتباری را بعد از ۱۵ دقیقه منقضی می‌کند.
+
+### ۹.۱ پارامترها
+
+| پارامتر | مقدار | توضیح |
+|---------|-------|-------|
+| `ExpirationTime` | **۱۵ دقیقه** | مدت زمان مجاز برای پرداخت |
+| `CheckInterval` | ۵ دقیقه | فاصله بررسی |
+
+### ۹.۲ عملکرد
+
+```mermaid
+flowchart TD
+    A["هر ۵ دقیقه\nExpirePendingOrdersService"] --> B["جستجوی DiscountOrders\nPaymentStatus=Pending\nCreated < (now - 15 min)"]
+    B --> C{"سفارشی یافت شد?"}
+    C -->|خیر| A
+    C -->|بله| D["آزادسازی رزرو موجودی\nReleaseReservationAsync"]
+    D --> E["PaymentStatus → Reject\nDeliveryStatus → Cancelled"]
+    E --> F["Transaction.PaymentStatus → Reject"]
+    F --> G["Log: Expired order #X"]
+    G --> A
+```
+
+### ۹.۳ فایل
+
+```
+CMS/src/CMSMicroservice.Infrastructure/BackgroundServices/ExpirePendingOrdersService.cs
+```
+
+رجیستر شده در `ConfigureServices.cs`:
+```csharp
+services.AddHostedService<ExpirePendingOrdersService>();
+```

business/BUSINESS-04-USER-MEMBERSHIP.md

@@ -0,0 +1,200 @@
+# 👤 سفر کاربر، ثبت‌نام و چرخه عضویت
+
+> **منابع ادغام‌شده:** `club-membership-contract-system.md`, `REGISTRATION-FLOW-FIXES.md`, `chatika-integration.md`, `club-feature-management-services.md`, `ADMIN-CUSTOMER-SEPARATION-FIX.md`, `ICURRENTUSERSERVICE-IMPLEMENTATION.md`  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet cycle)
+
+---
+
+## ۱. فلوی کامل چرخه کاربر
+
+```mermaid
+flowchart TD
+    A["ورود به سایت"] --> B["ثبت‌نام — موبایل + OTP"]
+    B --> C["تکمیل پروفایل"]
+    C --> D{"مسیر؟"}
+
+    D -->|عادی| E["🛒 خرید از فروشگاه\nمشاهده بلاگ\nاستفاده از خدمات"]
+
+    D -->|باشگاه| F["🏆 خرید پکیج طلایی 56M"]
+    F --> G["امضای قرارداد OTP"]
+    G --> H["فعالسازی 25.2M"]
+    H --> I["عضویت درخت باینری"]
+    I --> J["دسترسی فروشگاه اعتباری\nفیچرهای باشگاه\nکمیسیون هفتگی"]
+    J --> K{"Balance = 0?"}
+    K -->|بله| L["🪄 کیف‌پول جادویی\nشارژ ×2.5 از درگاه"]
+    L --> M["خروج از Magic\nخرید مجدد پکیج"]
+    M --> F
+```
+
+---
+
+## ۲. ثبت‌نام و احراز هویت
+
+### ۲.۱ فلوی ثبت‌نام
+
+```mermaid
+flowchart TD
+    A["صفحه ثبت‌نام"] --> B["ورود شماره موبایل"]
+    B --> C["ارسال OTP\nKavenegar SMS API"]
+    C --> D["تأیید کد OTP"]
+    D -->|کاربر جدید| E["ساخت User\n+ JWT Token"]
+    D -->|کاربر موجود| F["ورود\n+ JWT Token"]
+```
+
+**JWT Claims:** `UserId`, `PhoneNumber`, `IsClubMember`, `Roles[]`, `ReferralCode`
+
+### ۲.۲ اصلاحات ثبت‌نام
+
+| مشکل | راه‌حل | وضعیت |
+|------|---------|--------|
+| OTP تکراری | Cooldown: ۶۰ ثانیه بین درخواست‌ها | ✅ |
+| شماره نامعتبر | Regex validation ایران `^09\d{9}$` | ✅ |
+| حمله brute-force | MaxAttempts: ۵ تلاش برای تأیید کد | ✅ |
+| انقضای کد | TTL: ۲ دقیقه | ✅ |
+| طول کد | ۶ رقم | ✅ |
+| قالب SMS | Kavenegar template: `Afrino` | ✅ |
+
+---
+
+## ۳. جداسازی Admin/Customer
+
+### ۳.۱ مشکل قبلی
+
+```mermaid
+flowchart LR
+    subgraph BEFORE["قبل — مشکل"]
+        A1["Admin + Customer"] --> A2["یک DbContext\nیک Identity\nتداخل Claims"]
+    end
+
+    subgraph AFTER["بعد — اصلاح‌شده ✅"]
+        B1["ICurrentUserService"] --> B2["جداسازی Policy\nAdmin → BackOffice\nCustomer → FrontOffice"]
+    end
+```
+
+### ۳.۲ ICurrentUserService
+
+```csharp
+public interface ICurrentUserService {
+    Guid UserId { get; }
+    string PhoneNumber { get; }
+    bool IsClubMember { get; }
+    bool IsAdmin { get; }
+    string[] Roles { get; }
+    Guid? ReferrerId { get; }
+}
+
+// پیاده‌سازی: از HttpContext.User.Claims خوانده می‌شود
+// ثبت: services.AddScoped<ICurrentUserService, CurrentUserService>()
+```
+
+---
+
+## ۴. قرارداد عضویت باشگاه
+
+### ۴.۱ فلوی امضای قرارداد
+
+```mermaid
+flowchart TD
+    A["خرید پکیج طلایی\nRedirect به صفحه قرارداد"] --> B["نمایش Modal\nغیرقابل‌بسته‌شدن"]
+    B --> C["ReadContract RPC\nنمایش متن قرارداد"]
+    C --> D["اسکرول تا انتها"]
+    D --> E["فعال شدن دکمه\nارسال کد تأیید"]
+    E --> F["RequestContractOtp\nارسال SMS"]
+    F --> G["ورود کد\nVerifyContractOtp"]
+    G -->|معتبر| H["✅ AcceptContract\nفعالسازی عضویت"]
+    G -->|نامعتبر| I["❌ پیام خطا\nحداکثر ۵ تلاش"]
+```
+
+### ۴.۲ ذخیره‌سازی قرارداد
+
+```csharp
+// از کد: UserContract : BaseAuditableEntity
+public class UserContract {
+    public long UserId { get; set; }
+    public virtual User User { get; set; }
+    public long ContractId { get; set; }         // FK → Contract
+    public virtual Contract Contract { get; set; }
+    public string SignGuid { get; set; }          // GUID یکتای امضا
+    public string SignedPdfFile { get; set; }     // فایل PDF امضاشده
+    // فیلدهای BaseAuditableEntity: CreatedAt, ModifiedAt, ...
+}
+```
+
+---
+
+## ۵. فیچرهای باشگاه (Club Features)
+
+### ۵.۱ سرویس مدیریت
+
+```csharp
+public interface IClubFeatureService {
+    Task<List<ClubFeature>> GetUserFeaturesAsync(Guid userId);
+    Task ActivateFeatureAsync(Guid userId, string featureCode);
+    Task DeactivateFeatureAsync(Guid userId, string featureCode);
+    Task<bool> HasFeatureAsync(Guid userId, string featureCode);
+}
+```
+
+### ۵.۲ فیچرهای موجود
+
+| کد فیچر | نام | توضیح | وضعیت |
+|----------|------|--------|--------|
+| `DISCOUNT_STORE` | فروشگاه اعتباری | دسترسی به فروشگاه اعتباری | ✅ فعال |
+| `CHATIKA_AI` | چاتیکا | مشاوره هوش مصنوعی | ✅ فعال |
+| `COMMISSION` | کمیسیون | دریافت کمیسیون هفتگی | ✅ فعال |
+| `NETWORK_VIEW` | نمای شبکه | مشاهده درخت باینری | ✅ فعال |
+| `DAYA_LOAN` | وام دایا | درخواست وام | ⚠️ بلاک‌شده |
+
+### ۵.۳ UserClubFeature Entity
+
+```csharp
+public class UserClubFeature {
+    public Guid Id { get; set; }
+    public Guid UserId { get; set; }
+    public string FeatureCode { get; set; }
+    public bool IsActive { get; set; }
+    public DateTime ActivatedAt { get; set; }
+    public DateTime? DeactivatedAt { get; set; }
+}
+```
+
+---
+
+## ۶. ناوبری Auth-Aware
+
+```csharp
+// صفحه اصلی — مسیردهی هوشمند
+if (IsAuthenticated && IsClubMember)
+    → نمایش داشبورد باشگاه + فروشگاه اعتباری
+else if (IsAuthenticated)
+    → نمایش فروشگاه عادی + پروفایل
+else
+    → نمایش Landing Page + ثبت‌نام
+```
+
+---
+
+## ۷. کدهای معرف (Referral)
+
+```mermaid
+flowchart TD
+    A["هر عضو باشگاه\nیک ReferralCode یکتا"] --> B["لینک:\nhttps://foursat.ir/register?ref=CODE"]
+    B --> C["ثبت‌نام با لینک\nذخیره ReferrerId"]
+    C --> D["خرید پکیج\nزیرمجموعه Referrer در درخت"]
+    D --> E["Referrer\nدریافت bonus"]
+```
+
+---
+
+## ۸. خلاصه وضعیت
+
+| ماژول | وضعیت | درصد |
+|-------|--------|------|
+| ثبت‌نام OTP | ✅ | 100% |
+| جداسازی Admin/Customer | ✅ | 100% |
+| ICurrentUserService | ✅ | 100% |
+| قرارداد باشگاه + OTP | ✅ | 100% |
+| فیچرهای باشگاه | ✅ | 100% |
+| Referral System | ✅ | 100% |
+| ناوبری Auth-Aware | ✅ | 100% |
+| مشاهده درخت شبکه (FrontOffice) | ✅ | 100% |

business/BUSINESS-05-CONTENT-MANAGEMENT.md

@@ -0,0 +1,250 @@
+# 📄 محتوا، صفحات، بلاگ و ایمیل/SMS
+
+> **منابع ادغام‌شده:** `SITE-PAGES-SIMPLIFICATION.md`, `system-constants.md`, `email-sms-configuration.md`, `chatika-integration.md`, `CMS-README.md`  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet + VAT 10%)
+
+---
+
+## ۱. مدیریت صفحات سایت (Site Pages)
+
+### ۱.۱ معماری ساده‌شده (Shopify-style)
+
+```mermaid
+flowchart LR
+    subgraph BEFORE["قبل — پیچیده"]
+        X1["SitePage"] --> X2["SitePageSetting"] --> X3["SitePageContent"] --> X4["Template\n... 7 جدول"]
+    end
+
+    subgraph AFTER["بعد — ساده ✅"]
+        Y1["SitePage\nPageType + JsonSettings"] --> Y2["هر PageType\nیک typed editor"]
+    end
+```
+
+### ۱.۲ انواع صفحات
+
+| PageType | Route | Editor | وضعیت |
+|----------|-------|--------|--------|
+| `Home` | `/` | HomePageEditor | ✅ |
+| `About` | `/about` | AboutPageEditor | ✅ |
+| `Contact` | `/contact` | ContactPageEditor | ✅ |
+| `Landing` | `/landing` | LandingPageEditor | ✅ |
+| `Licenses` | `/licenses` | LicensesPageEditor | ✅ |
+| `FAQ` | `/faq` | FAQPageEditor | ✅ |
+| `Terms` | `/terms` | MarkdownEditor | ✅ |
+| `Privacy` | `/privacy` | MarkdownEditor | ✅ |
+
+### ۱.۳ SitePageSettingsService
+
+```csharp
+public interface ISitePageSettingsService {
+    Task<T> GetSettingsAsync<T>(string pageType) where T : class, new();
+    Task SaveSettingsAsync<T>(string pageType, T settings) where T : class;
+}
+
+// ذخیره‌سازی: JSON serialization در فیلد Settings
+// Cache: MemoryCache با Expiry 15 دقیقه
+```
+
+### ۱.۴ مثال — تنظیمات صفحه اصلی
+
+```json
+{
+    "heroTitle": "کارا بازار سلامت",
+    "heroSubtitle": "سلامتی در دستان شما",
+    "heroImageUrl": "/images/hero.jpg",
+    "featuredCategories": ["guid1", "guid2"],
+    "showPromotionBanner": true,
+    "promotionText": "تخفیف ویژه زمستانه"
+}
+```
+
+---
+
+## ۲. سیستم بلاگ
+
+### ۲.۱ Entity
+
+```csharp
+public class BlogPost {
+    public Guid Id { get; set; }
+    public string Title { get; set; }
+    public string Slug { get; set; }           // URL-friendly
+    public string Content { get; set; }         // HTML/Markdown
+    public string Summary { get; set; }
+    public string FeaturedImageUrl { get; set; }
+    public Guid AuthorId { get; set; }
+    public Guid? CategoryId { get; set; }
+    public bool IsPublished { get; set; }
+    public DateTime PublishedAt { get; set; }
+    public List<string> Tags { get; set; }
+    public int ViewCount { get; set; }
+}
+```
+
+### ۲.۲ Pagination (gRPC)
+
+```protobuf
+message GetBlogPostsRequest {
+    PaginationState pagination = 1;
+    string categoryId = 2;
+    string searchTerm = 3;
+    bool publishedOnly = 4;
+}
+```
+
+---
+
+## ۳. مدیریت فایل (File Management)
+
+### ۳.۱ معماری
+
+```mermaid
+flowchart TD
+    A["آپلود فایل\nتصویر / سند"] --> B["FileManagementService"]
+    B --> C["ذخیره در فایل‌سیستم\n+ ثبت در DB"]
+    C --> D["مسیر: /app/uploads/year/month/guid.ext\nURL: /api/files/guid"]
+```
+
+> محدودیت: حداکثر 10MB • jpg, png, webp, pdf, doc, docx • Resize: 800×800 (محصولات)
+
+### ۳.۲ Storage Strategy
+
+| محیط | ذخیره‌سازی |
+|------|------------|
+| Development | Local filesystem |
+| Staging | Local filesystem (server) |
+| Production | Local filesystem (server) |
+| آینده | MinIO / S3 compatible (planned) |
+
+---
+
+## ۴. تنظیمات ایمیل و SMS
+
+### ۴.۱ SMS (Kavenegar)
+
+```json
+{
+    "Kavenegar": {
+        "ApiKey": "***",
+        "SenderNumber": "1000001110100",
+        "DefaultTemplate": "Afrino",
+        "_note": "تمام OTPها با قالب Afrino ارسال می‌شوند"
+    }
+}
+```
+
+### ۴.۲ ایمیل
+
+```json
+{
+    "Email": {
+        "SmtpHost": "smtp.example.com",
+        "SmtpPort": 587,
+        "Username": "noreply@foursat.ir",
+        "FromName": "کارا بازار سلامت",
+        "UseSsl": true,
+        "Templates": {
+            "WelcomeEmail": "welcome.html",
+            "OrderReceipt": "order-receipt.html"
+        }
+    }
+}
+```
+
+> ⚠️ ایمیل فعلاً فقط برای اطلاع‌رسانی ادمین استفاده می‌شود — SMS کانال اصلی کاربران
+
+---
+
+## ۵. ثوابت سیستمی (SystemConstants)
+
+### ۵.۱ جدول اصلی
+
+```sql
+CREATE TABLE SystemConfigurations (
+    [Key] NVARCHAR(200) PRIMARY KEY,
+    [Value] NVARCHAR(MAX),
+    [Description] NVARCHAR(500),
+    [Category] NVARCHAR(100),
+    [LastModified] DATETIME2
+);
+```
+
+### ۵.۲ مقادیر کلیدی
+
+| Category | Key | Value | توضیح |
+|----------|-----|-------|--------|
+| Club | `ClubActivationFee` | 25200000 | هزینه فعالسازی (ریال) |
+| Club | `ClubMembershipGiftValue` | 25200000 | واریز Pool |
+| Club | `BasePackageAmount` | 56000000 | قیمت پکیج طلایی (ریال) |
+| Club | `CommissionMaxNetworkLevel` | 15 | عمق محاسبه کمیسیون |
+| Club | `CommissionMaxWeeklyBalancesPerLeg` | 300 | سقف هفتگی |
+| Payment | `ShopVAT` | 0.1 (10%) | مالیات ارزش افزوده (هر دو فروشگاه) |
+| Magic | `MagicWalletMultiplier` | 2.5 | ضریب شارژ جادویی |
+| Magic | `MagicWalletMaxDeposit` | 1,000,000,000 | سقف واریز/دور (100M تومان) |
+| Magic | `MagicWalletMaxCredit` | 2,500,000,000 | سقف اعتبار/دور (250M تومان) |
+| Payment | `DayaLoanAmount` | 56000000 | مبلغ وام (ریال) |
+| Payment | `MinimumWithdrawAmount` | 1000000 | حداقل برداشت (ریال) |
+| Store | `MaxDiscountPercent` | per-product | 0-100، هر محصول جداگانه |
+| Store | `ProductsPerPage` | 12 (FO) / 10 (CMS) | تعداد در صفحه |
+| System | `CommissionCalculationMethod` | "SP" | Stored Procedure |
+| System | `MaintenanceMode` | false | حالت تعمیر |
+
+---
+
+## ۶. Chatika AI Integration
+
+### ۶.۱ معماری
+
+```mermaid
+flowchart TD
+    A["Hangfire Recurring Job\nهر ۵ دقیقه"] --> B["ChatikaJob\nبررسی پیام‌های جدید"]
+    B --> C["ارسال به Chatika API\nPolly retry ×3"]
+    C --> D["دریافت پاسخ\nذخیره در ChatMessages"]
+    D --> E["نمایش در UI باشگاه\nSignalR planned"]
+```
+
+### ۶.۲ فعلی vs آینده
+
+| آیتم | فعلی | آینده |
+|------|-------|-------|
+| ارتباط | Polling (Hangfire) | SignalR real-time |
+| دسترسی | فقط اعضای باشگاه | تعمیم به همه؟ |
+| نوع پیام | متنی | متنی + تصویری |
+
+---
+
+## ۷. Landing Page
+
+### ۷.۱ ساختار
+
+```mermaid
+flowchart TD
+    A["🎨 Hero Section\nانیمیشن fade-in"] --> B["✨ ویژگی‌ها\nFeatures Grid — 3 ستونه"]
+    B --> C["📦 محصولات ویژه\nCarousel"]
+    C --> D["📊 آمار\nCounter animation\nlinear interpolation"]
+    D --> E["🚀 CTA\nثبت‌نام / ورود"]
+```
+
+### ۷.۲ اصلاح انیمیشن Counter
+
+```
+مشکل: اعداد به صورت exponential افزایش پیدا می‌کردند
+راه‌حل: linear interpolation با requestAnimationFrame
+    start → target در ۲ ثانیه، مساوی‌الفاصله
+```
+
+---
+
+## ۸. خلاصه وضعیت
+
+| ماژول | وضعیت | درصد |
+|-------|--------|------|
+| Site Pages (Shopify-style) | ✅ | 100% |
+| بلاگ + Pagination | ✅ | 100% |
+| مدیریت فایل | ✅ | 100% |
+| SMS (Kavenegar) | ✅ | 100% |
+| ایمیل | ⚠️ محدود | 50% |
+| Chatika AI | ✅ | 100% |
+| Landing Page | ✅ | 100% |
+| SystemConstants | ✅ | 100% |
+| SEO Meta Tags | ⬜ | 20% |

business/DISCOUNT-STORE-STATUS.md

@@ -1,196 +0,0 @@
-# فروشگاه تخفیفی — وضعیت پیاده‌سازی و تسک‌ها
-
-> **تاریخ:** ۱۴۰۴/۱۱/۲۲ (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 | ۰.۵ ساعت |
-| **مجموع** | **~۸ ساعت** |

business/discount-shop-business.md

@@ -1,750 +0,0 @@
-# Club Discount Shop System - سیستم فروشگاه باشگاه مشتریان با تخفیف ترکیبی
-
-**تاریخ ایجاد:** 2024-12-02  
-**تاریخ آپدیت:** 2024-12-02  
-**وضعیت:** طراحی (Phase 9)  
-**اولویت:** 🔴 بالا (یکی از دو فاز باقیمانده)
-
----
-
-## 📋 فهرست
-
-1. [مقدمه](#مقدمه)
-2. [مفهوم اصلی: پرداخت ترکیبی](#مفهوم-اصلی-پرداخت-ترکیبی)
-3. [تفاوت با Regular Shop](#تفاوت-با-regular-shop)
-4. [معماری جداسازی](#معماری-جداسازی)
-5. [Entity Design](#entity-design)
-6. [Business Rules](#business-rules)
-7. [تسک‌های پیاده‌سازی](#تسک-های-پیاده-سازی)
-
----
-
-## 🎯 مقدمه
-
-### هدف:
-ایجاد **فروشگاه باشگاه مشتریان** که در آن کاربران می‌توانند با **پرداخت ترکیبی** خرید کنند:
-
-**🔑 قانون اصلی**: 
-- کاربر **نمی‌تواند** کل محصول را فقط با `DiscountBalance` بخرد
-- کاربر می‌تواند **درصدی از قیمت** را با `DiscountBalance` پرداخت کند
-- **مابقی مبلغ** باید از طریق **درگاه پرداخت واقعی در Gateway/PYMS** پرداخت شود (نه در CMS)
-
-### مثال عملی:
-```
-قیمت محصول: 1,000,000 تومان
-حداکثر تخفیف مجاز: 30%
-DiscountBalance کاربر: 500,000 تومان
-
-محاسبه:
-- حداکثر تخفیف قابل استفاده: 1,000,000 × 30% = 300,000 تومان
-- DiscountBalance کاربر: 500,000 تومان (بیشتر از 300,000)
-- مبلغ تخفیف نهایی: 300,000 تومان (محدود به 30%)
-- مبلغ قابل پرداخت از درگاه: 1,000,000 - 300,000 = 700,000 تومان
-
-نتیجه:
-✅ کسر از DiscountBalance: 300,000 تومان
-✅ پرداخت از درگاه: 700,000 تومان
-✅ DiscountBalance باقیمانده: 200,000 تومان
-```
-
----
-
-## 🔄 مفهوم اصلی: پرداخت ترکیبی
-
-### Flow خرید:
-
-```
-1. کاربر محصول را انتخاب می‌کند
-2. سیستم چک می‌کند:
-   - قیمت محصول: X تومان
-   - حداکثر تخفیف مجاز: Y%
-   - DiscountBalance کاربر: Z تومان
-   
-3. محاسبه تخفیف:
-   MaxDiscountAmount = X × (Y / 100)
-   ActualDiscountAmount = Min(Z, MaxDiscountAmount)
-   
-4. محاسبه مبلغ درگاه:
-   GatewayAmount = X - ActualDiscountAmount
-   
-5. ریدایرکت به درگاه پرداخت (GatewayAmount)
-
-6. بعد از بازگشت موفق از درگاه:
-   - Verify payment از درگاه
-   - کسر ActualDiscountAmount از DiscountBalance
-   - ثبت سفارش با دو مبلغ جدا
-   - ارسال اطلاعیه به کاربر
-```
-
-### مزایا:
-✅ کاربر نمی‌تواند کل محصول را با تخفیف بخرد (محدودیت درصد)  
-✅ کاربر می‌تواند از موجودی تخفیف خود استفاده کند  
-✅ فروشنده مطمئن است مبلغی واقعی دریافت می‌کند  
-✅ سیستم از سوء‌استفاده جلوگیری می‌کند  
-
----
-
-## 🔄 تفاوت با Regular Shop
-
-| ویژگی | فروشگاه عادی (Regular) | فروشگاه تخفیفی (Club Discount) |
-|-------|------------------------|---------------------------|
-| **نوع کیف پول** | `UserWallet.Balance` | `UserWallet.DiscountBalance` + درگاه |
-| **نحوه پرداخت** | 100% از Balance یا IPG | **ترکیبی**: X% از DiscountBalance + مابقی از IPG |
-| **محدودیت تخفیف** | ندارد | **دارد** (MaxDiscountPercent per product) |
-| **نحوه شارژ** | خرید پکیج طلایی (56M) | کمیسیون برداشت Diamond |
-| **ارتباط با باشگاه** | ✅ دارد | ✅ دارد (اعضای باشگاه) |
-| **محصولات** | `Products` | `DiscountProduct` (یا flag در Products) |
-| **سفارش** | `UserOrder` | `DiscountOrder` (با دو مبلغ جدا) |
-| **پرداخت** | یک مرحله‌ای | **دو مرحله‌ای**: 1) Verify IPG، 2) Deduct DiscountBalance |
-| **TransactionType** | `DepositIpg` | `DiscountPurchase` (hybrid) |
-
----
-
-## 🏗️ معماری جداسازی
-
-### اصل طراحی:
-> **"همه چیز جدا، جز درگاه پرداخت و کیف پول"**
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                         User                                     │
-│  - Id                                                            │
-│  - FirstName, LastName, Mobile                                  │
-│  - PackagePurchaseMethod                                        │
-└────────────┬────────────────────────────────────────────────────┘
-             │
-             ├──────────────────────────────────────────┐
-             │                                          │
-             ▼                                          ▼
-┌────────────────────────────┐          ┌──────────────────────────┐
-│       UserWallet           │          │    Transactions (مشترک)  │
-│  - Balance                 │          │  - Type                  │
-│  - DiscountBalance         │          │  - RefId                 │
-│  - NetworkBalance          │          │  - Amount                │
-└────────────┬───────────────┘          └──────────────────────────┘
-             │
-             ├──────────────────────────────────────────┐
-             │                                          │
-             ▼                                          ▼
-┌────────────────────────────┐          ┌──────────────────────────┐
-│    Regular Shop            │          │    Discount Shop         │
-│  - Products                │          │  - DiscountProduct       │
-│  - Category                │          │  - DiscountCategory      │
-│  - UserCarts               │          │  - DiscountShoppingCart  │
-│  - UserOrder               │          │  - DiscountOrder         │
-│  - FactorDetails           │          │  - DiscountOrderDetail   │
-└────────────────────────────┘          └──────────────────────────┘
-```
-
----
-
-## 🗄️ Entity Design
-
-### 1️⃣ `DiscountProduct`
-
-```csharp
-namespace CMSMicroservice.Domain.Entities.DiscountShop;
-
-/// <summary>
-/// محصول فروشگاه تخفیفی
-/// </summary>
-public class DiscountProduct : BaseAuditableEntity
-{
-    /// <summary>
-    /// عنوان محصول
-    /// </summary>
-    public string Title { get; set; }
-    
-    /// <summary>
-    /// توضیحات مختصر
-    /// </summary>
-    public string ShortInfomation { get; set; }
-    
-    /// <summary>
-    /// توضیحات کامل
-    /// </summary>
-    public string FullInformation { get; set; }
-    
-    /// <summary>
-    /// قیمت (ریال)
-    /// </summary>
-    public long Price { get; set; }
-    
-    /// <summary>
-    /// درصد تخفیف
-    /// </summary>
-    public int DiscountPercent { get; set; }
-    
-    /// <summary>
-    /// امتیاز (0 تا 5)
-    /// </summary>
-    public int Rate { get; set; }
-    
-    /// <summary>
-    /// آدرس تصویر اصلی
-    /// </summary>
-    public string ImagePath { get; set; }
-    
-    /// <summary>
-    /// آدرس تصویر کوچک
-    /// </summary>
-    public string ThumbnailPath { get; set; }
-    
-    /// <summary>
-    /// تعداد فروش
-    /// </summary>
-    public int SaleCount { get; set; }
-    
-    /// <summary>
-    /// تعداد بازدید
-    /// </summary>
-    public int ViewCount { get; set; }
-    
-    /// <summary>
-    /// موجودی انبار
-    /// </summary>
-    public int RemainingCount { get; set; }
-    
-    /// <summary>
-    /// وضعیت فعال/غیرفعال
-    /// </summary>
-    public bool IsActive { get; set; }
-    
-    // Navigation Properties
-    public virtual ICollection<DiscountShoppingCart> ShoppingCarts { get; set; }
-    public virtual ICollection<DiscountOrderDetail> OrderDetails { get; set; }
-    public virtual ICollection<DiscountProductCategory> ProductCategories { get; set; }
-}
-```
-
----
-
-### 2️⃣ `DiscountCategory`
-
-```csharp
-namespace CMSMicroservice.Domain.Entities.DiscountShop;
-
-/// <summary>
-/// دسته‌بندی فروشگاه تخفیفی
-/// </summary>
-public class DiscountCategory : BaseAuditableEntity
-{
-    /// <summary>
-    /// نام لاتین (برای URL)
-    /// </summary>
-    public string Name { get; set; }
-    
-    /// <summary>
-    /// عنوان فارسی
-    /// </summary>
-    public string Title { get; set; }
-    
-    /// <summary>
-    /// توضیحات
-    /// </summary>
-    public string? Description { get; set; }
-    
-    /// <summary>
-    /// آدرس تصویر
-    /// </summary>
-    public string? ImagePath { get; set; }
-    
-    /// <summary>
-    /// شناسه والد (برای دسته‌بندی چند سطحی)
-    /// </summary>
-    public long? ParentId { get; set; }
-    
-    /// <summary>
-    /// Parent Navigation Property
-    /// </summary>
-    public virtual DiscountCategory? Parent { get; set; }
-    
-    /// <summary>
-    /// فعال/غیرفعال
-    /// </summary>
-    public bool IsActive { get; set; }
-    
-    /// <summary>
-    /// ترتیب نمایش
-    /// </summary>
-    public int SortOrder { get; set; }
-    
-    // Navigation Properties
-    public virtual ICollection<DiscountCategory> Children { get; set; }
-    public virtual ICollection<DiscountProductCategory> ProductCategories { get; set; }
-}
-```
-
----
-
-### 3️⃣ `DiscountProductCategory` (Many-to-Many)
-
-```csharp
-namespace CMSMicroservice.Domain.Entities.DiscountShop;
-
-/// <summary>
-/// رابطه محصول و دسته‌بندی در فروشگاه تخفیفی
-/// </summary>
-public class DiscountProductCategory : BaseAuditableEntity
-{
-    public long DiscountProductId { get; set; }
-    public virtual DiscountProduct DiscountProduct { get; set; }
-    
-    public long DiscountCategoryId { get; set; }
-    public virtual DiscountCategory DiscountCategory { get; set; }
-}
-```
-
----
-
-### 4️⃣ `DiscountShoppingCart`
-
-```csharp
-namespace CMSMicroservice.Domain.Entities.DiscountShop;
-
-/// <summary>
-/// سبد خرید فروشگاه تخفیفی
-/// </summary>
-public class DiscountShoppingCart : BaseAuditableEntity
-{
-    /// <summary>
-    /// شناسه کاربر
-    /// </summary>
-    public long UserId { get; set; }
-    
-    /// <summary>
-    /// User Navigation Property
-    /// </summary>
-    public virtual User User { get; set; }
-    
-    /// <summary>
-    /// شناسه محصول
-    /// </summary>
-    public long DiscountProductId { get; set; }
-    
-    /// <summary>
-    /// DiscountProduct Navigation Property
-    /// </summary>
-    public virtual DiscountProduct DiscountProduct { get; set; }
-    
-    /// <summary>
-    /// تعداد
-    /// </summary>
-    public int Count { get; set; }
-    
-    /// <summary>
-    /// قیمت واحد در زمان افزودن به سبد
-    /// </summary>
-    public long UnitPrice { get; set; }
-}
-```
-
----
-
-### 5️⃣ `DiscountOrder`
-
-```csharp
-namespace CMSMicroservice.Domain.Entities.DiscountShop;
-
-/// <summary>
-/// سفارش از فروشگاه تخفیفی
-/// </summary>
-public class DiscountOrder : BaseAuditableEntity
-{
-    /// <summary>
-    /// شناسه کاربر
-    /// </summary>
-    public long UserId { get; set; }
-    
-    /// <summary>
-    /// User Navigation Property
-    /// </summary>
-    public virtual User User { get; set; }
-    
-    /// <summary>
-    /// مبلغ کل سفارش
-    /// </summary>
-    public long TotalAmount { get; set; }
-    
-    /// <summary>
-    /// مبلغ تخفیف
-    /// </summary>
-    public long DiscountAmount { get; set; }
-    
-    /// <summary>
-    /// مبلغ قابل پرداخت
-    /// </summary>
-    public long PayableAmount { get; set; }
-    
-    /// <summary>
-    /// وضعیت پرداخت
-    /// </summary>
-    public PaymentStatus PaymentStatus { get; set; }
-    
-    /// <summary>
-    /// تاریخ پرداخت
-    /// </summary>
-    public DateTime? PaymentDate { get; set; }
-    
-    /// <summary>
-    /// شناسه تراکنش (اگر پرداخت موفق باشد)
-    /// </summary>
-    public long? TransactionId { get; set; }
-    
-    /// <summary>
-    /// Transaction Navigation Property
-    /// </summary>
-    public virtual Transactions? Transaction { get; set; }
-    
-    /// <summary>
-    /// شناسه آدرس کاربر
-    /// </summary>
-    public long UserAddressId { get; set; }
-    
-    /// <summary>
-    /// UserAddress Navigation Property
-    /// </summary>
-    public virtual UserAddress UserAddress { get; set; }
-    
-    /// <summary>
-    /// وضعیت ارسال
-    /// </summary>
-    public DeliveryStatus DeliveryStatus { get; set; }
-    
-    /// <summary>
-    /// کد رهگیری مرسوله
-    /// </summary>
-    public string? TrackingCode { get; set; }
-    
-    /// <summary>
-    /// توضیحات وضعیت ارسال
-    /// </summary>
-    public string? DeliveryDescription { get; set; }
-    
-    // Navigation Properties
-    public virtual ICollection<DiscountOrderDetail> OrderDetails { get; set; }
-}
-```
-
----
-
-### 6️⃣ `DiscountOrderDetail`
-
-```csharp
-namespace CMSMicroservice.Domain.Entities.DiscountShop;
-
-/// <summary>
-/// جزئیات سفارش از فروشگاه تخفیفی
-/// </summary>
-public class DiscountOrderDetail : BaseAuditableEntity
-{
-    /// <summary>
-    /// شناسه سفارش
-    /// </summary>
-    public long DiscountOrderId { get; set; }
-    
-    /// <summary>
-    /// DiscountOrder Navigation Property
-    /// </summary>
-    public virtual DiscountOrder DiscountOrder { get; set; }
-    
-    /// <summary>
-    /// شناسه محصول
-    /// </summary>
-    public long DiscountProductId { get; set; }
-    
-    /// <summary>
-    /// DiscountProduct Navigation Property
-    /// </summary>
-    public virtual DiscountProduct DiscountProduct { get; set; }
-    
-    /// <summary>
-    /// تعداد
-    /// </summary>
-    public int Quantity { get; set; }
-    
-    /// <summary>
-    /// قیمت واحد در زمان ثبت سفارش
-    /// </summary>
-    public long UnitPrice { get; set; }
-    
-    /// <summary>
-    /// درصد تخفیف در زمان ثبت سفارش
-    /// </summary>
-    public int DiscountPercent { get; set; }
-    
-    /// <summary>
-    /// مبلغ کل این آیتم (بعد از تخفیف)
-    /// </summary>
-    public long TotalPrice { get; set; }
-}
-```
-
----
-
-## 📐 Business Rules
-
-### قانون 1: خرید از Discount Shop فقط با DiscountBalance
-
-```csharp
-// در زمان Checkout از Discount Shop:
-var wallet = await _context.UserWallets
-    .FirstOrDefaultAsync(w => w.UserId == userId);
-
-if (wallet.DiscountBalance < order.PayableAmount)
-{
-    throw new ValidationException(
-        $"موجودی کیف پول تخفیفی شما کافی نیست. " +
-        $"موجودی فعلی: {wallet.DiscountBalance:N0} تومان، " +
-        $"مبلغ مورد نیاز: {order.PayableAmount:N0} تومان"
-    );
-}
-```
-
----
-
-### قانون 2: خرید از Regular Shop فقط با Balance
-
-```csharp
-// در زمان Checkout از Regular Shop:
-var wallet = await _context.UserWallets
-    .FirstOrDefaultAsync(w => w.UserId == userId);
-
-if (wallet.Balance < order.Amount)
-{
-    throw new ValidationException(
-        $"موجودی کیف پول اصلی شما کافی نیست. " +
-        $"موجودی فعلی: {wallet.Balance:N0} تومان، " +
-        $"مبلغ مورد نیاز: {order.Amount:N0} تومان"
-    );
-}
-```
-
----
-
-### قانون 3: شارژ DiscountBalance از طریق درگاه
-
-```csharp
-// در VerifyDiscountWalletChargeCommand:
-wallet.DiscountBalance += amount;
-
-var transaction = new Transactions
-{
-    Type = TransactionType.DiscountWalletCharge,
-    Amount = amount,
-    RefId = verifyResult.RefId
-};
-```
-
----
-
-### قانون 4: محصولات Discount Shop جدا از Regular Shop
-
-- یک محصول **نمی‌تواند** هم در `Products` باشد، هم در `DiscountProduct`
-- Admin باید محصولات را جداگانه مدیریت کند
-- هیچ رابطه‌ای بین `Products` و `DiscountProduct` نیست
-
----
-
-## 🔄 Flow Diagram: خرید از Discount Shop
-
-```
-کاربر → مشاهده محصولات Discount Shop
-  ↓
-افزودن به DiscountShoppingCart
-  ↓
-Checkout (بررسی DiscountBalance)
-  ↓
-ثبت DiscountOrder (PaymentStatus: Pending)
-  ↓
-کم کردن DiscountBalance از کیف پول
-  ↓
-ثبت Transaction (Type: Buy) ← این تراکنش برای خرید است
-  ↓
-ثبت DiscountOrderDetail برای هر محصول
-  ↓
-به‌روزرسانی DiscountOrder (PaymentStatus: Success)
-  ↓
-خالی کردن DiscountShoppingCart
-  ↓
-نمایش پیام موفقیت + کد رهگیری
-```
-
-**نکته:** در این فلو از درگاه استفاده **نمی‌شود** چون موجودی از قبل شارژ شده است.
-
----
-
-## 📝 تسک‌های پیاده‌سازی
-
-### Phase 1: Entity Creation (2 روز)
-
-1. **ایجاد namespace جدید**:
-   - `CMSMicroservice.Domain/Entities/DiscountShop/`
-
-2. **ایجاد Entity‌ها**:
-   - `DiscountProduct`
-   - `DiscountCategory`
-   - `DiscountProductCategory`
-   - `DiscountShoppingCart`
-   - `DiscountOrder`
-   - `DiscountOrderDetail`
-
-3. **ایجاد Configuration‌ها**:
-   - `DiscountProductConfiguration`
-   - `DiscountCategoryConfiguration`
-   - و غیره...
-
-4. **به‌روزرسانی `DbContext`**:
-   ```csharp
-   public DbSet<DiscountProduct> DiscountProducts { get; set; }
-   public DbSet<DiscountCategory> DiscountCategories { get; set; }
-   // ...
-   ```
-
-5. **ایجاد Migration**:
-   ```bash
-   dotnet ef migrations add AddDiscountShopTables
-   ```
-
----
-
-### Phase 2: Commands & Queries (3 روز)
-
-#### DiscountProduct CRUD:
-- `CreateDiscountProductCommand`
-- `UpdateDiscountProductCommand`
-- `DeleteDiscountProductCommand`
-- `GetDiscountProductByIdQuery`
-- `GetDiscountProductsListQuery`
-
-#### DiscountCategory CRUD:
-- `CreateDiscountCategoryCommand`
-- `UpdateDiscountCategoryCommand`
-- `DeleteDiscountCategoryCommand`
-- `GetDiscountCategoriesTreeQuery`
-
-#### Shopping Cart:
-- `AddToDiscountCartCommand`
-- `RemoveFromDiscountCartCommand`
-- `GetDiscountCartQuery`
-
-#### Order:
-- `CreateDiscountOrderCommand` (Checkout)
-- `GetDiscountOrderByIdQuery`
-- `GetMyDiscountOrdersQuery` (برای کاربر)
-- `UpdateDiscountOrderDeliveryCommand` (برای Admin)
-
----
-
-### Phase 3: BackOffice.BFF APIs (1 روز)
-
-**Proto file**: `DiscountShopContract.proto`
-
-```protobuf
-service DiscountShopContract {
-  // Product
-  rpc CreateDiscountProduct(CreateDiscountProductRequest) returns (CreateDiscountProductResponse);
-  rpc UpdateDiscountProduct(UpdateDiscountProductRequest) returns (UpdateDiscountProductResponse);
-  rpc GetDiscountProducts(GetDiscountProductsRequest) returns (GetDiscountProductsResponse);
-  
-  // Category
-  rpc CreateDiscountCategory(CreateDiscountCategoryRequest) returns (CreateDiscountCategoryResponse);
-  rpc GetDiscountCategoriesTree(Empty) returns (GetDiscountCategoriesTreeResponse);
-  
-  // Orders
-  rpc GetDiscountOrders(GetDiscountOrdersRequest) returns (GetDiscountOrdersResponse);
-  rpc UpdateDiscountOrderDelivery(UpdateDiscountOrderDeliveryRequest) returns (UpdateDiscountOrderDeliveryResponse);
-}
-```
-
----
-
-### Phase 4: FrontOffice.BFF APIs (1 روز)
-
-**Proto file**: `DiscountShopContract.proto` (در FrontOffice.BFF)
-
-```protobuf
-service DiscountShopContract {
-  // Browse
-  rpc GetDiscountProducts(GetDiscountProductsRequest) returns (GetDiscountProductsResponse);
-  rpc GetDiscountProductById(GetDiscountProductByIdRequest) returns (GetDiscountProductByIdResponse);
-  
-  // Cart
-  rpc AddToDiscountCart(AddToDiscountCartRequest) returns (AddToDiscountCartResponse);
-  rpc GetMyDiscountCart(Empty) returns (GetMyDiscountCartResponse);
-  rpc RemoveFromDiscountCart(RemoveFromDiscountCartRequest) returns (RemoveFromDiscountCartResponse);
-  
-  // Order
-  rpc CheckoutDiscountCart(CheckoutDiscountCartRequest) returns (CheckoutDiscountCartResponse);
-  rpc GetMyDiscountOrders(Empty) returns (GetMyDiscountOrdersResponse);
-}
-```
-
----
-
-### Phase 5: BackOffice UI (3 روز)
-
-**صفحات مدیریت:**
-1. **لیست محصولات تخفیفی** + CRUD
-2. **دسته‌بندی‌ها** (Tree View) + CRUD
-3. **سفارشات تخفیفی** + تغییر وضعیت ارسال
-4. **گزارش فروش** Discount Shop
-
----
-
-### Phase 6: FrontOffice UI (3 روز)
-
-**صفحات کاربر:**
-1. **لیست محصولات تخفیفی** (با فیلتر دسته‌بندی)
-2. **جزئیات محصول تخفیفی**
-3. **سبد خرید تخفیفی**
-4. **Checkout** (با نمایش `DiscountBalance`)
-5. **لیست سفارشات تخفیفی کاربر**
-
----
-
-### Phase 7: Unit Tests (2 روز)
-
-1. تست **CRUD محصولات تخفیفی**
-2. تست **AddToDiscountCart**
-3. تست **CheckoutDiscountCart**:
-   - کاربر با موجودی کافی → موفق
-   - کاربر با موجودی ناکافی → خطا
-
----
-
-### Phase 8: Documentation (0.5 روز)
-
-- به‌روزرسانی `implementation-progress.md`
-- لینک از `REMAINING-TASKS-CONSOLIDATED.md`
-
----
-
-## 📊 خلاصه Timeline
-
-| Phase | عنوان | زمان |
-|-------|-------|------|
-| 1 | Entity Creation | 2 روز |
-| 2 | Commands & Queries (CMS) | 3 روز |
-| 3 | BackOffice.BFF APIs | 1 روز |
-| 4 | FrontOffice.BFF APIs | 1 روز |
-| 5 | BackOffice UI | 3 روز |
-| 6 | FrontOffice UI | 3 روز |
-| 7 | Unit Tests | 2 روز |
-| 8 | Documentation | 0.5 روز |
-| **جمع** | | **15.5 روز** (~3 هفته) |
-
----
-
-## 🔗 مراجع
-
-- [Package Purchase System](./package-purchase-system.md)
-- [Manual Payment System](./manual-payment-system.md)
-- [Implementation Progress](./implementation-progress.md)
-- [REMAINING-TASKS](../REMAINING-TASKS-CONSOLIDATED.md)
-
----
-
-**تاریخ آخرین به‌روزرسانی:** 2024-12-02  
-**نویسنده:** GitHub Copilot  
-**وضعیت:** ✅ تایید شده توسط کاربر

business/manual-payment-system.md

@@ -1,548 +0,0 @@
-# Manual Payment System (سیستم پرداخت دستی مشتریان)
-
-## 📌 Overview
-
-سیستم پرداخت دستی برای مشتریانی که **بدون خرید وام دایا** می‌خواهند مستقیماً 56 میلیون تومان پرداخت کنند و همان مزایا را دریافت کنند.
-
-### 🎯 سناریوها
-
-#### سناریو 1: پرداخت آنلاین (درگاه پرداخت)
-```
-کاربر → انتخاب گزینه "پرداخت دستی" در فرانت‌آفیس
-  ↓
-ایجاد Transaction با Type=ManualPaymentOnline, Amount=56M, Status=Pending
-  ↓
-ریدایرکت به درگاه پرداخت (Zarinpal/Mellat/...)
-  ↓
-Callback از درگاه با RefId
-  ↓
-VerifyManualPaymentCommand → تایید تراکنش
-  ↓
-شارژ کیف‌پول‌ها (Balance=56M, NetworkBalance=56M, DiscountBalance=56M)
-  ↓
-فعال‌سازی عضویت باشگاه (ClubMembership)
-```
-
-#### سناریو 2: کارت‌به‌کارت با تایید ادمین
-```
-کاربر → کارت‌به‌کارت 56 میلیون + ارسال تصویر رسید
-  ↓
-CreateManualPaymentRequestCommand → ثبت درخواست با Status=PendingAdminApproval
-  - تصویر رسید + کد پیگیری استخراج شده توسط کاربر
-  ↓
-ادمین → بررسی درخواست در BackOffice
-  ↓
-ApproveManualPaymentCommand یا RejectManualPaymentCommand
-  ↓
-در صورت تایید: 
-  - ایجاد Transaction با RefId=کد پیگیری
-  - شارژ کیف‌پول‌ها
-  - فعال‌سازی عضویت باشگاه
-  ↓
-در صورت رد:
-  - ثبت دلیل رد
-  - اطلاع‌رسانی به کاربر
-```
-
----
-
-## 🗂️ Architecture
-
-### Domain Layer
-
-> **وضعیت فعلی پیاده‌سازی (CMS)**  
-> در نسخه‌ای که الآن در CMS داریم، سناریوی «درخواست پرداخت دستی توسط کاربر» (ManualPaymentRequest + Verify از درگاه) هنوز پیاده‌سازی نشده و فقط بخش **پرداخت دستی توسط Admin/SuperAdmin** با Entity ساده‌تر `ManualPayment` و Enumهای `ManualPaymentType` و `ManualPaymentStatus` (Pending/Approved/Rejected/Cancelled) اجرا شده است.  
-> بخش‌های زیر که با `ManualPaymentRequest`، `ManualPaymentMethod` و Verify/ProcessManualPayment توضیح داده شده‌اند، طراحی کامل سیستم هستند و برای فاز بعدی (FrontOffice + OnlineGateway/CardToCard) استفاده خواهند شد.
-
-#### **ManualPaymentStatus Enum (طراحی کامل – برای Requestها)**
-```csharp
-public enum ManualPaymentStatus
-{
-    PendingAdminApproval = 0,  // در انتظار تایید ادمین (کارت‌به‌کارت)
-    PendingPayment = 1,         // در انتظار پرداخت (درگاه آنلاین)
-    PaymentVerified = 2,        // پرداخت تایید شده (از درگاه)
-    AdminApproved = 3,          // تایید شده توسط ادمین
-    AdminRejected = 4,          // رد شده توسط ادمین
-    Completed = 5,              // تکمیل شده (کیف‌پول شارژ شده)
-    Failed = 6                  // خطا در پردازش
-}
-```
-
-#### **ManualPaymentMethod Enum**
-```csharp
-public enum ManualPaymentMethod
-{
-    OnlineGateway = 0,     // درگاه آنلاین
-    CardToCard = 1         // کارت‌به‌کارت
-}
-```
-
-#### **ManualPaymentRequest Entity (طراحی کامل – هنوز پیاده نشده)**
-```csharp
-public class ManualPaymentRequest : BaseAuditableEntity
-{
-    public long UserId { get; set; }
-    public ManualPaymentMethod Method { get; set; }
-    public ManualPaymentStatus Status { get; set; }
-    public long Amount { get; set; } = 56_000_000; // مبلغ ثابت
-    
-    // آنلاین Gateway
-    public string? GatewayName { get; set; }        // Zarinpal, Mellat, etc.
-    public string? GatewayTrackingCode { get; set; } // کد پیگیری درگاه
-    public DateTime? GatewayPaymentDate { get; set; }
-    
-    // کارت‌به‌کارت
-    public string? ReceiptImageUrl { get; set; }     // مسیر تصویر رسید
-    public string? UserProvidedTrackingCode { get; set; } // کد پیگیری که کاربر داده
-    public DateTime? CardToCardDate { get; set; }
-    
-    // تایید/رد ادمین
-    public long? ApprovedByAdminId { get; set; }
-    public DateTime? AdminDecisionDate { get; set; }
-    public string? AdminNotes { get; set; }         // توضیحات ادمین (دلیل رد)
-    
-    // تراکنش نهایی
-    public long? TransactionId { get; set; }
-    public bool IsProcessed { get; set; }
-    public DateTime? ProcessedDate { get; set; }
-    
-    // Navigation Properties
-    public virtual User User { get; set; }
-    public virtual User? ApprovedByAdmin { get; set; }
-    public virtual Transactions? Transaction { get; set; }
-}
-```
-
----
-
-### Application Layer
-
-#### **Commands**
-
-##### 1. CreateManualPaymentRequestCommand (FrontOffice)
-ایجاد درخواست پرداخت دستی توسط کاربر
-
-**Request:**
-```csharp
-public record CreateManualPaymentRequestCommand : IRequest<CreateManualPaymentRequestResponseDto>
-{
-    public long UserId { get; init; }
-    public ManualPaymentMethod Method { get; init; }
-    
-    // برای OnlineGateway
-    public string? GatewayName { get; init; }
-    public string? ReturnUrl { get; init; } // URL بازگشت بعد از پرداخت
-    
-    // برای CardToCard
-    public IFormFile? ReceiptImage { get; init; }     // فایل تصویر رسید
-    public string? TrackingCode { get; init; }         // کد پیگیری
-    public DateTime? TransactionDate { get; init; }
-}
-```
-
-**Response:**
-```csharp
-public class CreateManualPaymentRequestResponseDto
-{
-    public long RequestId { get; set; }
-    public ManualPaymentStatus Status { get; set; }
-    
-    // برای OnlineGateway: URL پرداخت
-    public string? PaymentUrl { get; set; }
-    
-    // برای CardToCard: پیام موفقیت
-    public string Message { get; set; }
-}
-```
-
-**Business Logic:**
-1. بررسی اینکه کاربر قبلاً درخواست Pending ندارد
-2. اگر Method=OnlineGateway:
-   - ایجاد ManualPaymentRequest با Status=PendingPayment
-   - فراخوانی Gateway Service برای دریافت URL پرداخت
-   - ذخیره GatewayName و کد درخواست
-   - برگرداندن PaymentUrl به کاربر
-3. اگر Method=CardToCard:
-   - آپلود تصویر رسید به Storage
-   - ایجاد ManualPaymentRequest با Status=PendingAdminApproval
-   - ذخیره UserProvidedTrackingCode و CardToCardDate
-   - ارسال نوتیفیکیشن به ادمین‌ها
-
-##### 2. VerifyManualPaymentCommand (Callback از درگاه)
-تایید پرداخت آنلاین بعد از بازگشت از درگاه
-
-**Request:**
-```csharp
-public record VerifyManualPaymentCommand : IRequest<VerifyManualPaymentResponseDto>
-{
-    public long RequestId { get; init; }
-    public string GatewayTrackingCode { get; init; }
-    public string? Authority { get; init; } // پارامتر درگاه
-}
-```
-
-**Business Logic:**
-1. یافتن ManualPaymentRequest با Status=PendingPayment
-2. فراخوانی Gateway Service برای Verify کردن تراکنش
-3. اگر تایید شد:
-   - به‌روزرسانی Status → PaymentVerified
-   - ذخیره GatewayTrackingCode و GatewayPaymentDate
-   - فراخوانی ProcessManualPaymentCommand برای شارژ کیف‌پول
-4. اگر رد شد:
-   - به‌روزرسانی Status → Failed
-
-##### 3. ApproveManualPaymentCommand (Admin)
-تایید درخواست کارت‌به‌کارت توسط ادمین
-
-**Request:**
-```csharp
-public record ApproveManualPaymentCommand : IRequest<ApproveManualPaymentResponseDto>
-{
-    public long RequestId { get; init; }
-    public long AdminUserId { get; init; }
-    public string? AdminNotes { get; init; }
-}
-```
-
-**Business Logic:**
-1. بررسی RequestId موجود با Status=PendingAdminApproval
-2. بررسی دسترسی ادمین
-3. به‌روزرسانی:
-   - Status → AdminApproved
-   - ApprovedByAdminId, AdminDecisionDate, AdminNotes
-4. فراخوانی ProcessManualPaymentCommand برای شارژ کیف‌پول
-
-##### 4. RejectManualPaymentCommand (Admin)
-رد درخواست کارت‌به‌کارت توسط ادمین
-
-**Request:**
-```csharp
-public record RejectManualPaymentCommand : IRequest<RejectManualPaymentResponseDto>
-{
-    public long RequestId { get; init; }
-    public long AdminUserId { get; init; }
-    public string RejectionReason { get; init; } // الزامی
-}
-```
-
-**Business Logic:**
-1. بررسی RequestId موجود
-2. به‌روزرسانی:
-   - Status → AdminRejected
-   - ApprovedByAdminId, AdminDecisionDate
-   - AdminNotes = RejectionReason
-3. ارسال نوتیفیکیشن به کاربر با دلیل رد
-
-##### 5. ProcessManualPaymentCommand (Internal)
-شارژ کیف‌پول‌ها بعد از تایید پرداخت
-
-**این Command داخلی است و فقط توسط Verify یا Approve فراخوانی می‌شود.**
-
-**Business Logic:**
-1. ایجاد Transaction:
-   - Type: DepositManual
-   - Amount: 56M
-   - RefId: GatewayTrackingCode یا UserProvidedTrackingCode
-2. شارژ Balance: +56M
-3. شارژ NetworkBalance: +56M
-4. شارژ DiscountBalance: +56M
-5. فعال‌سازی ClubMembership (اگر غیرفعال باشد)
-6. ثبت UserWalletChangeLog
-7. به‌روزرسانی ManualPaymentRequest:
-   - Status → Completed
-   - TransactionId, IsProcessed=true, ProcessedDate
-8. ارسال نوتیفیکیشن موفقیت به کاربر
-
-##### 6. GetUserManualPaymentHistoryQuery
-دریافت تاریخچه پرداخت‌های دستی کاربر
-
-**Request:**
-```csharp
-public record GetUserManualPaymentHistoryQuery : IRequest<List<ManualPaymentHistoryDto>>
-{
-    public long UserId { get; init; }
-}
-```
-
-##### 7. GetPendingManualPaymentsQuery (Admin)
-دریافت لیست درخواست‌های در انتظار تایید
-
-**Request:**
-```csharp
-public record GetPendingManualPaymentsQuery : IRequest<List<PendingManualPaymentDto>>
-{
-    public ManualPaymentStatus? StatusFilter { get; init; } = ManualPaymentStatus.PendingAdminApproval;
-    public int PageNumber { get; init; } = 1;
-    public int PageSize { get; init; } = 20;
-}
-```
-
----
-
-## 💾 Database Schema
-
-### ManualPaymentRequests Table
-```sql
-CREATE TABLE [CMS].[ManualPaymentRequests] (
-    [Id] bigint IDENTITY(1,1) PRIMARY KEY,
-    [UserId] bigint NOT NULL FOREIGN KEY REFERENCES Users(Id),
-    [Method] int NOT NULL,
-    [Status] int NOT NULL,
-    [Amount] bigint NOT NULL DEFAULT 56000000,
-    
-    -- آنلاین Gateway
-    [GatewayName] nvarchar(50) NULL,
-    [GatewayTrackingCode] nvarchar(200) NULL,
-    [GatewayPaymentDate] datetime2 NULL,
-    
-    -- کارت‌به‌کارت
-    [ReceiptImageUrl] nvarchar(500) NULL,
-    [UserProvidedTrackingCode] nvarchar(200) NULL,
-    [CardToCardDate] datetime2 NULL,
-    
-    -- تایید ادمین
-    [ApprovedByAdminId] bigint NULL FOREIGN KEY REFERENCES Users(Id),
-    [AdminDecisionDate] datetime2 NULL,
-    [AdminNotes] nvarchar(max) NULL,
-    
-    -- تراکنش
-    [TransactionId] bigint NULL FOREIGN KEY REFERENCES Transactionss(Id),
-    [IsProcessed] bit NOT NULL DEFAULT 0,
-    [ProcessedDate] datetime2 NULL,
-    
-    -- Audit
-    [Created] datetime2 NOT NULL,
-    [CreatedBy] nvarchar(max) NULL,
-    [LastModified] datetime2 NULL,
-    [LastModifiedBy] nvarchar(max) NULL,
-    [IsDeleted] bit NOT NULL DEFAULT 0
-);
-
-CREATE INDEX IX_ManualPaymentRequests_UserId ON ManualPaymentRequests(UserId);
-CREATE INDEX IX_ManualPaymentRequests_Status ON ManualPaymentRequests(Status);
-CREATE INDEX IX_ManualPaymentRequests_TransactionId ON ManualPaymentRequests(TransactionId);
-```
-
----
-
-## 🔄 Process Flows
-
-### Flow 1: پرداخت آنلاین
-```mermaid
-sequenceDiagram
-    participant User as کاربر
-    participant FrontOffice as FrontOffice
-    participant CMS as CMS API
-    participant Gateway as درگاه پرداخت
-    
-    User->>FrontOffice: انتخاب "پرداخت دستی"
-    FrontOffice->>CMS: CreateManualPaymentRequest (Method=OnlineGateway)
-    CMS->>Gateway: ایجاد درخواست پرداخت
-    Gateway-->>CMS: PaymentUrl
-    CMS-->>FrontOffice: PaymentUrl
-    FrontOffice->>Gateway: ریدایرکت کاربر
-    User->>Gateway: پرداخت 56M
-    Gateway->>CMS: Callback (RefId, Authority)
-    CMS->>Gateway: Verify Payment
-    Gateway-->>CMS: تایید پرداخت
-    CMS->>CMS: ProcessManualPayment (شارژ کیف‌پول)
-    CMS-->>FrontOffice: موفقیت
-    FrontOffice-->>User: پرداخت موفق
-```
-
-### Flow 2: کارت‌به‌کارت
-```mermaid
-sequenceDiagram
-    participant User as کاربر
-    participant FrontOffice as FrontOffice
-    participant CMS as CMS API
-    participant Admin as ادمین (BackOffice)
-    
-    User->>User: کارت‌به‌کارت 56M
-    User->>FrontOffice: آپلود رسید + کد پیگیری
-    FrontOffice->>CMS: CreateManualPaymentRequest (Method=CardToCard)
-    CMS->>CMS: ذخیره تصویر + Status=PendingAdminApproval
-    CMS-->>Admin: نوتیفیکیشن (درخواست جدید)
-    Admin->>CMS: GetPendingManualPayments
-    CMS-->>Admin: لیست درخواست‌ها
-    Admin->>Admin: بررسی رسید و کد پیگیری
-    
-    alt تایید
-        Admin->>CMS: ApproveManualPayment
-        CMS->>CMS: ProcessManualPayment (شارژ کیف‌پول)
-        CMS-->>User: نوتیفیکیشن موفقیت
-    else رد
-        Admin->>CMS: RejectManualPayment (دلیل رد)
-        CMS-->>User: نوتیفیکیشن رد با دلیل
-    end
-```
-
----
-
-## 🧪 Testing Scenarios
-
-### Test 1: پرداخت آنلاین موفق
-```bash
-# Step 1: ایجاد درخواست
-POST /api/manualpayment/create
-{
-  "userId": 123,
-  "method": 0,
-  "gatewayName": "Zarinpal",
-  "returnUrl": "https://example.com/callback"
-}
-
-# Response: PaymentUrl
-
-# Step 2: کاربر پرداخت می‌کند (Mock Gateway)
-
-# Step 3: Callback
-POST /api/manualpayment/verify
-{
-  "requestId": 456,
-  "gatewayTrackingCode": "ZP-12345",
-  "authority": "A00000000..."
-}
-
-# Result: کیف‌پول شارژ شده، باشگاه فعال
-```
-
-### Test 2: کارت‌به‌کارت با تایید ادمین
-```bash
-# Step 1: ایجاد درخواست کاربر
-POST /api/manualpayment/create
-{
-  "userId": 123,
-  "method": 1,
-  "receiptImage": <file>,
-  "trackingCode": "REF-98765",
-  "transactionDate": "2024-12-01T10:00:00Z"
-}
-
-# Step 2: ادمین بررسی می‌کند
-GET /api/admin/manualpayment/pending
-
-# Step 3: ادمین تایید می‌کند
-POST /api/admin/manualpayment/approve
-{
-  "requestId": 456,
-  "adminUserId": 1,
-  "adminNotes": "رسید معتبر است"
-}
-
-# Result: کیف‌پول شارژ شده
-```
-
----
-
-## 📋 Implementation Tasks
-
-### CMS Microservice
-
-#### Domain Layer
-- [ ] ایجاد `ManualPaymentStatus` enum
-- [ ] ایجاد `ManualPaymentMethod` enum
-- [ ] ایجاد `ManualPaymentRequest` entity
-- [ ] اضافه کردن به `ApplicationDbContext`
-
-#### Application Layer
-- [ ] `CreateManualPaymentRequestCommand` + Handler + Validator
-- [ ] `VerifyManualPaymentCommand` + Handler
-- [ ] `ApproveManualPaymentCommand` + Handler
-- [ ] `RejectManualPaymentCommand` + Handler
-- [ ] `ProcessManualPaymentCommand` + Handler (Internal)
-- [ ] `GetUserManualPaymentHistoryQuery` + Handler
-- [ ] `GetPendingManualPaymentsQuery` + Handler
-- [ ] Interface: `IPaymentGatewayService`
-- [ ] Interface: `IFileStorageService` (برای آپلود تصویر)
-
-#### Infrastructure Layer
-- [ ] `ZarinpalGatewayService` : IPaymentGatewayService
-- [ ] `LocalFileStorageService` : IFileStorageService
-- [ ] Migration: `AddManualPaymentSystem`
-
-#### WebApi Layer (Protobuf/gRPC)
-- [ ] Proto definitions: `ManualPayment.proto`
-- [ ] gRPC Service: `ManualPaymentService`
-
-### FrontOffice
-
-#### Components
-- [ ] `ManualPaymentPage.razor` - صفحه انتخاب روش پرداخت
-- [ ] `OnlinePaymentForm.razor` - فرم پرداخت آنلاین
-- [ ] `CardToCardForm.razor` - فرم کارت‌به‌کارت (آپلود رسید)
-- [ ] `PaymentCallbackPage.razor` - صفحه بازگشت از درگاه
-- [ ] `PaymentHistoryPage.razor` - تاریخچه پرداخت‌های کاربر
-
-#### Services
-- [ ] `ManualPaymentService.cs` - فراخوانی BFF
-
-### FrontOffice.BFF
-
-#### Application Layer
-- [ ] CQRS Handlers برای مپ کردن gRPC به REST
-- [ ] DTOs برای API های REST
-
-#### WebApi Layer
-- [ ] `ManualPaymentController.cs` - REST endpoints
-
-### BackOffice
-
-#### Components
-- [ ] `PendingPaymentsPage.razor` - لیست درخواست‌های در انتظار
-- [ ] `PaymentRequestDetailsModal.razor` - جزئیات + نمایش رسید
-- [ ] `ApproveRejectButtons.razor` - دکمه‌های تایید/رد
-
-#### Services
-- [ ] `ManualPaymentAdminService.cs` - فراخوانی BFF
-
-### BackOffice.BFF
-
-#### Application Layer
-- [ ] Admin CQRS Handlers
-- [ ] Admin DTOs
-
-#### WebApi Layer
-- [ ] `AdminManualPaymentController.cs` - REST endpoints برای ادمین
-
----
-
-## ⚠️ Important Notes
-
-### 1. Transaction Type
-- برای پرداخت دستی از `TransactionType.DepositManual` استفاده شود
-- RefId = GatewayTrackingCode (آنلاین) یا UserProvidedTrackingCode (کارت‌به‌کارت)
-
-### 2. Security
-- تایید پرداخت درگاه باید با Signature Verification انجام شود
-- تصاویر رسید باید با Validation بارگذاری شوند (حجم، فرمت، محتوا)
-- فقط ادمین‌ها حق تایید/رد کارت‌به‌کارت دارند
-
-### 3. Idempotency
-- نباید کاربر بتواند چند درخواست همزمان Pending داشته باشد
-- هر RequestId فقط یک بار قابل Verify است
-
-### 4. Notifications
-- SMS/Email به کاربر بعد از:
-  - ایجاد درخواست کارت‌به‌کارت
-  - تایید/رد ادمین
-  - موفقیت پرداخت آنلاین
-
-### 5. File Storage
-- تصاویر رسید باید با GUID ذخیره شوند
-- مسیر: `/uploads/receipts/{year}/{month}/{guid}.jpg`
-- حداکثر حجم: 2MB
-- فرمت‌های مجاز: JPG, PNG, PDF
-
----
-
-## 🔗 Related Documentation
-
-- [daya-loan-integration.md](./daya-loan-integration.md) - سیستم وام دایا
-- [network-club-commission-system-v1.1.md](./network-club-commission-system-v1.1.md) - بیزینس کلی
-
----
-
-**Created:** 2024-12-01  
-**Status:** ⚠️ Not Implemented Yet (Design Complete)  
-**Priority:** High (برای کاربران بدون وام دایا ضروری است)

business/package-purchase-system.md

@@ -1,967 +0,0 @@
-# Package Purchase System - سیستم خرید پکیج طلایی
-
-**تاریخ ایجاد:** 2024-12-02  
-**وضعیت:** در حال طراحی  
-**اولویت:** 🔴 بسیار بالا
-
----
-
-## 📋 فهرست
-
-1. [مقدمه](#مقدمه)
-2. [سه سناریوی اصلی](#سه-سناریوی-اصلی)
-3. [Entity Changes](#entity-changes)
-4. [Business Rules](#business-rules)
-5. [Flow Diagrams](#flow-diagrams)
-6. [Commands & Handlers](#commands--handlers)
-7. [تسک‌های پیاده‌سازی](#تسک-های-پیاده-سازی)
-
----
-
-## 🎯 مقدمه
-
-سیستم خرید پکیج طلایی سه سناریوی مختلف دارد که باید به درستی از هم تفکیک شوند:
-
-### هدف کلی:
-- **سناریو 1 و 2**: خرید پکیج طلایی (56 میلیون تومان) → امکان فعالسازی باشگاه مشتریان
-- **سناریو 3**: شارژ عادی کیف پول تخفیفی → فقط برای خرید از فروشگاه تخفیفی
-
-### نکات کلیدی:
-1. کاربر فقط **یک بار** می‌تواند پکیج طلایی خریداری کند (سناریو 1 یا 2)
-2. بعد از خرید پکیج، کاربر **باید خودش** دکمه فعالسازی باشگاه را بزند
-3. فعالسازی باشگاه **نیاز به تایید Admin ندارد**
-4. عضویت در شبکه (NetworkMembership) **جدا** از عضویت در باشگاه (ClubMembership) است
-5. کمیسیون‌ها **فقط بعد** از فعالسازی باشگاه محاسبه می‌شوند
-
----
-
-## 🔄 سه سناریوی اصلی
-
-### 📌 سناریو 1: دریافت وام دایا (DayaLoan)
-
-```
-کاربر → درخواست وام از دایا → دایا وام را تایید می‌کند
-  ↓
-شارژ Balance در UserWallet (56,000,000 تومان)
-  ↓
-ثبت UserWalletChangeLog (Amount: +56M, Type: DepositExternal1)
-  ↓
-ثبت Transaction (Type: DepositExternal1, RefId: شماره قرارداد دایا)
-  ↓
-ثبت UserOrder (PackageId: پکیج طلایی, TransactionId: xxx, Amount: 56M)
-  ↓
-کاربر می‌تواند با این 56M از فروشگاه عادی خرید کند
-  ↓
-[کاربر باید خودش دکمه "فعالسازی باشگاه مشتریان" را بزند]
-  ↓
-ثبت/به‌روزرسانی ClubMembership (IsActive: true, PurchaseMethod: DayaLoan)
-  ↓
-شروع محاسبه کمیسیون‌ها
-```
-
-**نکات:**
-- `Transaction.Type` = `DepositExternal1` (وام دایا)
-- `Transaction.RefId` = شماره قرارداد دایا
-- `UserOrder.PackageId` پر می‌شود
-- `User.PackagePurchaseMethod` = `DayaLoan`
-
----
-
-### 📌 سناریو 2: خرید پکیج طلایی از درگاه (Direct Purchase)
-
-```
-کاربر → انتخاب پکیج طلایی (56M) → کلیک "پرداخت"
-  ↓
-ثبت UserOrder (PackageId: پکیج طلایی, Amount: 56M, PaymentStatus: Pending)
-  ↓
-Redirect به درگاه بانکی (IPG)
-  ↓
-کاربر پرداخت می‌کند و بر می‌گردد
-  ↓
-Verify پرداخت با بانک
-  ↓
-شارژ Balance در UserWallet (56,000,000 تومان)
-  ↓
-ثبت UserWalletChangeLog (Amount: +56M, Type: DepositIpg)
-  ↓
-ثبت Transaction (Type: DepositIpg, RefId: کد پیگیری بانک)
-  ↓
-به‌روزرسانی UserOrder (TransactionId: xxx, PaymentStatus: Success)
-  ↓
-کاربر می‌تواند با این 56M از فروشگاه عادی خرید کند
-  ↓
-[کاربر باید خودش دکمه "فعالسازی باشگاه مشتریان" را بزند]
-  ↓
-ثبت/به‌روزرسانی ClubMembership (IsActive: true, PurchaseMethod: DirectPurchase)
-  ↓
-شروع محاسبه کمیسیون‌ها
-```
-
-**نکات:**
-- `Transaction.Type` = `DepositIpg` (پرداخت از درگاه)
-- `Transaction.RefId` = کد پیگیری بانک
-- `UserOrder.PackageId` پر می‌شود
-- `User.PackagePurchaseMethod` = `DirectPurchase`
-
----
-
-### 📌 سناریو 3: شارژ عادی کیف پول تخفیفی (Regular Wallet Charge)
-
-```
-کاربر → انتخاب مبلغ دلخواه → کلیک "شارژ کیف پول"
-  ↓
-Redirect به درگاه بانکی (IPG)
-  ↓
-کاربر پرداخت می‌کند و بر می‌گردد
-  ↓
-Verify پرداخت با بانک
-  ↓
-شارژ DiscountBalance در UserWallet (مبلغ دلخواه)
-  ↓
-ثبت UserWalletChangeLog (Amount: +xxx, Type: DiscountWalletCharge)
-  ↓
-ثبت Transaction (Type: DiscountWalletCharge, RefId: کد پیگیری بانک)
-  ↓
-کاربر می‌تواند فقط از فروشگاه تخفیفی خرید کند
-  ↓
-[هیچ ارتباطی با باشگاه مشتریان ندارد]
-```
-
-**نکات:**
-- `Transaction.Type` = `DiscountWalletCharge`
-- `Transaction.RefId` = کد پیگیری بانک
-- **PackageId در هیچ جا ثبت نمی‌شود**
-- فقط `DiscountBalance` شارژ می‌شود، نه `Balance`
-- هیچ `UserOrder` با `PackageId` ثبت نمی‌شود
-
----
-
-## 🗄️ Entity Changes
-
-### 1️⃣ **Enum جدید: `PackagePurchaseMethod`**
-
-```csharp
-namespace CMSMicroservice.Domain.Enums;
-
-/// <summary>
-/// نحوه خرید پکیج طلایی توسط کاربر
-/// </summary>
-public enum PackagePurchaseMethod
-{
-    /// <summary>
-    /// هنوز پکیج خریداری نکرده
-    /// </summary>
-    None = 0,
-    
-    /// <summary>
-    /// از طریق وام دایا
-    /// </summary>
-    DayaLoan = 1,
-    
-    /// <summary>
-    /// از طریق پرداخت مستقیم درگاه بانکی
-    /// </summary>
-    DirectPurchase = 2
-}
-```
-
-**محل:** `CMS/src/CMSMicroservice.Domain/Enums/PackagePurchaseMethod.cs`
-
----
-
-### 2️⃣ **تغییرات `User` Entity**
-
-```csharp
-// اضافه کردن این فیلد به User.cs:
-
-/// <summary>
-/// نحوه خرید پکیج طلایی (برای جلوگیری از خرید مجدد)
-/// </summary>
-public PackagePurchaseMethod PackagePurchaseMethod { get; set; } = PackagePurchaseMethod.None;
-```
-
-**منطق:**
-- وقتی کاربر سناریو 1 یا 2 را انجام می‌دهد، این فیلد تغییر می‌کند
-- اگر `PackagePurchaseMethod != None` باشد، کاربر نمی‌تواند دوباره پکیج خریداری کند
-
----
-
-### 3️⃣ **تغییرات `ClubMembership` Entity**
-
-```csharp
-// اضافه کردن این فیلد به ClubMembership.cs:
-
-/// <summary>
-/// نحوه خرید پکیج که منجر به فعالسازی باشگاه شد
-/// </summary>
-public PackagePurchaseMethod PurchaseMethod { get; set; }
-```
-
-**منطق:**
-- وقتی کاربر دکمه "فعالسازی باشگاه" را می‌زند، این فیلد از `User.PackagePurchaseMethod` کپی می‌شود
-- برای گزارش‌گیری و تحلیل: چند نفر از طریق وام دایا و چند نفر از طریق خرید مستقیم عضو شدند
-
----
-
-### 4️⃣ **تغییرات `TransactionType` Enum**
-
-```csharp
-// فعلاً موجود است:
-public enum TransactionType
-{
-    Buy = 0,
-    DepositIpg = 1,            // پرداخت از درگاه (سناریو 2)
-    DepositExternal1 = 2,      // وام دایا (سناریو 1)
-    Withdraw = 3,
-    NetworkCommission = 10,
-    ClubActivation = 11,
-    DiscountWalletCharge = 12  // شارژ کیف پول تخفیفی (سناریو 3) ✅
-}
-```
-
-**نکته:** `DiscountWalletCharge` از قبل وجود دارد، پس نیازی به تغییر نیست.
-
----
-
-## 📐 Business Rules
-
-### قانون 1: یک کاربر فقط یک بار می‌تواند پکیج طلایی خریداری کند
-
-```csharp
-// Check قبل از خرید پکیج:
-if (user.PackagePurchaseMethod != PackagePurchaseMethod.None)
-{
-    throw new ValidationException("شما قبلاً پکیج طلایی را خریداری کرده‌اید.");
-}
-```
-
----
-
-### قانون 2: فعالسازی باشگاه فقط با موجودی اصلی (Balance) امکان‌پذیر است
-
-```csharp
-// Check موقع فعالسازی باشگاه:
-var userWallet = await _context.UserWallets
-    .FirstOrDefaultAsync(w => w.UserId == userId);
-
-if (userWallet.Balance < 56_000_000)
-{
-    throw new ValidationException("برای فعالسازی باشگاه مشتریان باید حداقل 56 میلیون تومان موجودی اصلی داشته باشید.");
-}
-```
-
----
-
-### قانون 3: فعالسازی باشگاه فقط برای کسانی که پکیج خریده‌اند
-
-```csharp
-// Check موقع فعالسازی باشگاه:
-if (user.PackagePurchaseMethod == PackagePurchaseMethod.None)
-{
-    throw new ValidationException("برای فعالسازی باشگاه مشتریان ابتدا باید پکیج طلایی خریداری کنید.");
-}
-
-// پیدا کردن UserOrder مربوط به پکیج:
-var packageOrder = await _context.UserOrders
-    .FirstOrDefaultAsync(o => 
-        o.UserId == userId && 
-        o.PackageId != null &&
-        o.PaymentStatus == PaymentStatus.Success
-    );
-
-if (packageOrder == null)
-{
-    throw new ValidationException("سفارش پکیج طلایی یافت نشد.");
-}
-
-// پیدا کردن Transaction مربوطه:
-var transaction = await _context.Transactions
-    .FirstOrDefaultAsync(t => t.Id == packageOrder.TransactionId);
-
-if (transaction == null || 
-    (transaction.Type != TransactionType.DepositIpg && 
-     transaction.Type != TransactionType.DepositExternal1))
-{
-    throw new ValidationException("تراکنش معتبر برای فعالسازی باشگاه یافت نشد.");
-}
-```
-
----
-
-### قانون 4: NetworkMembership جدا از ClubMembership است
-
-- **NetworkMembership**: موقع ثبت‌نام کاربر خودکار ایجاد می‌شود (با `ParentId`)
-- **ClubMembership**: فقط وقتی کاربر دکمه "فعالسازی باشگاه" را بزند ایجاد می‌شود
-- کاربر می‌تواند زیرمجموعه بگیرد بدون اینکه جزو باشگاه باشد (ولی سیاست‌گذاری می‌کنیم که قبل از گرفتن زیرمجموعه باید باشگاه را فعال کرده باشد)
-
----
-
-### قانون 5: محاسبه کمیسیون فقط بعد از فعالسازی باشگاه
-
-```csharp
-// در محاسبه کمیسیون:
-var clubMembership = await _context.ClubMemberships
-    .FirstOrDefaultAsync(c => c.UserId == userId && c.IsActive);
-
-if (clubMembership == null)
-{
-    // این کاربر کمیسیون نمی‌گیرد چون جزو باشگاه نیست
-    return;
-}
-
-// ادامه محاسبه کمیسیون...
-```
-
----
-
-## 📊 Flow Diagrams
-
-### 🔹 Flow 1: خرید پکیج از درگاه (سناریو 2)
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                  FrontOffice UI (کاربر)                     │
-└──────────────────────┬──────────────────────────────────────┘
-                       │
-                       ▼
-         ┌─────────────────────────┐
-         │ انتخاب پکیج طلایی (56M) │
-         └────────────┬─────────────┘
-                      │
-                      ▼
-   ┌──────────────────────────────────────┐
-   │ PurchaseGoldenPackageCommand          │
-   │ - بررسی User.PackagePurchaseMethod   │
-   │ - ثبت UserOrder (Pending)            │
-   │ - Redirect به درگاه                  │
-   └────────────┬─────────────────────────┘
-                │
-                ▼
-   ┌──────────────────────────────────────┐
-   │         درگاه بانکی (IPG)            │
-   │     کاربر پرداخت می‌کند              │
-   └────────────┬─────────────────────────┘
-                │
-                ▼
-   ┌──────────────────────────────────────┐
-   │ VerifyGoldenPackagePurchaseCommand    │
-   │ - Verify با بانک                     │
-   │ - شارژ UserWallet.Balance (56M)      │
-   │ - ثبت Transaction (DepositIpg)       │
-   │ - ثبت UserWalletChangeLog            │
-   │ - Set User.PackagePurchaseMethod     │
-   │   = DirectPurchase                    │
-   │ - به‌روزرسانی UserOrder (Success)     │
-   └────────────┬─────────────────────────┘
-                │
-                ▼
-   ┌──────────────────────────────────────┐
-   │  کاربر می‌تواند از فروشگاه عادی    │
-   │       خرید کند (با Balance)          │
-   └──────────────────────────────────────┘
-```
-
----
-
-### 🔹 Flow 2: فعالسازی باشگاه مشتریان
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│            FrontOffice UI (کاربر وارد شده)                  │
-│         کاربر دکمه "فعالسازی باشگاه" را می‌زند             │
-└──────────────────────┬──────────────────────────────────────┘
-                       │
-                       ▼
-   ┌──────────────────────────────────────┐
-   │ ActivateClubMembershipCommand         │
-   │                                       │
-   │ 1. بررسی User.PackagePurchaseMethod  │
-   │    → باید != None باشد               │
-   │                                       │
-   │ 2. بررسی UserWallet.Balance          │
-   │    → باید >= 56M باشد                │
-   │                                       │
-   │ 3. پیدا کردن UserOrder با PackageId  │
-   │    → PaymentStatus = Success         │
-   │                                       │
-   │ 4. پیدا کردن Transaction             │
-   │    → Type = DepositIpg یا            │
-   │             DepositExternal1         │
-   │                                       │
-   │ 5. ثبت/به‌روزرسانی ClubMembership     │
-   │    - IsActive = true                 │
-   │    - ActivatedAt = DateTime.Now      │
-   │    - PurchaseMethod = کپی از User    │
-   │                                       │
-   └────────────┬─────────────────────────┘
-                │
-                ▼
-   ┌──────────────────────────────────────┐
-   │   کاربر جزو باشگاه مشتریان شد       │
-   │   کمیسیون‌ها شروع به محاسبه می‌کنند │
-   └──────────────────────────────────────┘
-```
-
----
-
-### 🔹 Flow 3: شارژ کیف پول تخفیفی (سناریو 3)
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                  FrontOffice UI (کاربر)                     │
-└──────────────────────┬──────────────────────────────────────┘
-                       │
-                       ▼
-         ┌─────────────────────────┐
-         │ انتخاب مبلغ دلخواه      │
-         │ (برای فروشگاه تخفیفی)   │
-         └────────────┬─────────────┘
-                      │
-                      ▼
-   ┌──────────────────────────────────────┐
-   │ ChargeDiscountWalletCommand           │
-   │ - Redirect به درگاه                  │
-   └────────────┬─────────────────────────┘
-                │
-                ▼
-   ┌──────────────────────────────────────┐
-   │         درگاه بانکی (IPG)            │
-   │     کاربر پرداخت می‌کند              │
-   └────────────┬─────────────────────────┘
-                │
-                ▼
-   ┌──────────────────────────────────────┐
-   │ VerifyDiscountWalletChargeCommand     │
-   │ - Verify با بانک                     │
-   │ - شارژ UserWallet.DiscountBalance    │
-   │ - ثبت Transaction                    │
-   │   (Type: DiscountWalletCharge)        │
-   │ - ثبت UserWalletChangeLog            │
-   └────────────┬─────────────────────────┘
-                │
-                ▼
-   ┌──────────────────────────────────────┐
-   │  کاربر می‌تواند از فروشگاه تخفیفی  │
-   │    خرید کند (با DiscountBalance)     │
-   └──────────────────────────────────────┘
-```
-
-**نکته:** در این سناریو هیچ `UserOrder` با `PackageId` ثبت نمی‌شود.
-
----
-
-## 💻 Commands & Handlers
-
-### 1️⃣ `PurchaseGoldenPackageCommand`
-
-**مسئولیت:** ایجاد سفارش پکیج طلایی و Redirect به درگاه
-
-```csharp
-public class PurchaseGoldenPackageCommand : IRequest<PaymentInitiateResult>
-{
-    public long UserId { get; set; }
-}
-
-public class PurchaseGoldenPackageCommandHandler 
-    : IRequestHandler<PurchaseGoldenPackageCommand, PaymentInitiateResult>
-{
-    private readonly IApplicationDbContext _context;
-    private readonly IPaymentGatewayService _paymentGateway;
-
-    public async Task<PaymentInitiateResult> Handle(
-        PurchaseGoldenPackageCommand request, 
-        CancellationToken cancellationToken)
-    {
-        // 1. بررسی User
-        var user = await _context.Users
-            .FirstOrDefaultAsync(u => u.Id == request.UserId, cancellationToken);
-        
-        if (user == null)
-            throw new NotFoundException(nameof(User), request.UserId);
-        
-        // 2. بررسی اینکه قبلاً پکیج نخریده باشد
-        if (user.PackagePurchaseMethod != PackagePurchaseMethod.None)
-        {
-            throw new ValidationException("شما قبلاً پکیج طلایی را خریداری کرده‌اید.");
-        }
-        
-        // 3. پیدا کردن پکیج طلایی
-        var goldenPackage = await _context.Packages
-            .FirstOrDefaultAsync(p => p.Title.Contains("طلایی"), cancellationToken);
-        
-        if (goldenPackage == null)
-            throw new NotFoundException("پکیج طلایی یافت نشد.");
-        
-        // 4. ایجاد UserOrder
-        var order = new UserOrder
-        {
-            UserId = user.Id,
-            PackageId = goldenPackage.Id,
-            Amount = goldenPackage.Price, // 56,000,000
-            PaymentStatus = PaymentStatus.Pending,
-            DeliveryStatus = DeliveryStatus.None,
-            UserAddressId = 0 // پکیج نیاز به آدرس ندارد
-        };
-        
-        _context.UserOrders.Add(order);
-        await _context.SaveChangesAsync(cancellationToken);
-        
-        // 5. Redirect به درگاه
-        var paymentRequest = new PaymentRequest
-        {
-            Amount = order.Amount,
-            OrderId = order.Id.ToString(),
-            CallbackUrl = "https://yourdomain.com/verify-golden-package",
-            Description = $"خرید پکیج طلایی"
-        };
-        
-        var result = await _paymentGateway.InitiatePaymentAsync(paymentRequest);
-        
-        return result;
-    }
-}
-```
-
----
-
-### 2️⃣ `VerifyGoldenPackagePurchaseCommand`
-
-**مسئولیت:** Verify پرداخت و شارژ کیف پول
-
-```csharp
-public class VerifyGoldenPackagePurchaseCommand : IRequest<bool>
-{
-    public long OrderId { get; set; }
-    public string Authority { get; set; } // از درگاه
-}
-
-public class VerifyGoldenPackagePurchaseCommandHandler 
-    : IRequestHandler<VerifyGoldenPackagePurchaseCommand, bool>
-{
-    private readonly IApplicationDbContext _context;
-    private readonly IPaymentGatewayService _paymentGateway;
-
-    public async Task<bool> Handle(
-        VerifyGoldenPackagePurchaseCommand request, 
-        CancellationToken cancellationToken)
-    {
-        // 1. پیدا کردن Order
-        var order = await _context.UserOrders
-            .Include(o => o.Package)
-            .Include(o => o.User)
-            .FirstOrDefaultAsync(o => o.Id == request.OrderId, cancellationToken);
-        
-        if (order == null)
-            throw new NotFoundException(nameof(UserOrder), request.OrderId);
-        
-        // 2. Verify با بانک
-        var verifyResult = await _paymentGateway.VerifyPaymentAsync(
-            request.Authority, 
-            order.Amount
-        );
-        
-        if (!verifyResult.IsSuccess)
-        {
-            order.PaymentStatus = PaymentStatus.Failed;
-            await _context.SaveChangesAsync(cancellationToken);
-            return false;
-        }
-        
-        // 3. شارژ کیف پول
-        var wallet = await _context.UserWallets
-            .FirstOrDefaultAsync(w => w.UserId == order.UserId, cancellationToken);
-        
-        wallet.Balance += order.Amount; // 56,000,000
-        
-        // 4. ثبت Transaction
-        var transaction = new Transactions
-        {
-            Amount = order.Amount,
-            Description = "خرید پکیج طلایی از درگاه",
-            PaymentStatus = PaymentStatus.Success,
-            PaymentDate = DateTime.Now,
-            RefId = verifyResult.RefId,
-            Type = TransactionType.DepositIpg
-        };
-        
-        _context.Transactions.Add(transaction);
-        await _context.SaveChangesAsync(cancellationToken);
-        
-        // 5. ثبت ChangeLog
-        var changeLog = new UserWalletChangeLog
-        {
-            UserId = order.UserId,
-            Amount = order.Amount,
-            ChangeType = WalletChangeType.Deposit,
-            Description = "شارژ موجودی از پکیج طلایی",
-            BalanceBefore = wallet.Balance - order.Amount,
-            BalanceAfter = wallet.Balance
-        };
-        
-        _context.UserWalletChangeLogs.Add(changeLog);
-        
-        // 6. به‌روزرسانی Order
-        order.TransactionId = transaction.Id;
-        order.PaymentStatus = PaymentStatus.Success;
-        order.PaymentDate = DateTime.Now;
-        order.PaymentMethod = PaymentMethod.Online;
-        
-        // 7. تغییر User.PackagePurchaseMethod
-        order.User.PackagePurchaseMethod = PackagePurchaseMethod.DirectPurchase;
-        
-        await _context.SaveChangesAsync(cancellationToken);
-        
-        return true;
-    }
-}
-```
-
----
-
-### 3️⃣ `ActivateClubMembershipCommand`
-
-**مسئولیت:** فعالسازی عضویت در باشگاه مشتریان
-
-```csharp
-public class ActivateClubMembershipCommand : IRequest<bool>
-{
-    public long UserId { get; set; }
-}
-
-public class ActivateClubMembershipCommandHandler 
-    : IRequestHandler<ActivateClubMembershipCommand, bool>
-{
-    private readonly IApplicationDbContext _context;
-
-    public async Task<bool> Handle(
-        ActivateClubMembershipCommand request, 
-        CancellationToken cancellationToken)
-    {
-        // 1. بررسی User
-        var user = await _context.Users
-            .FirstOrDefaultAsync(u => u.Id == request.UserId, cancellationToken);
-        
-        if (user == null)
-            throw new NotFoundException(nameof(User), request.UserId);
-        
-        // 2. بررسی اینکه پکیج خریده باشد
-        if (user.PackagePurchaseMethod == PackagePurchaseMethod.None)
-        {
-            throw new ValidationException(
-                "برای فعالسازی باشگاه مشتریان ابتدا باید پکیج طلایی خریداری کنید."
-            );
-        }
-        
-        // 3. بررسی موجودی
-        var wallet = await _context.UserWallets
-            .FirstOrDefaultAsync(w => w.UserId == user.Id, cancellationToken);
-        
-        if (wallet.Balance < 56_000_000)
-        {
-            throw new ValidationException(
-                "برای فعالسازی باشگاه مشتریان باید حداقل 56 میلیون تومان موجودی اصلی داشته باشید."
-            );
-        }
-        
-        // 4. بررسی UserOrder
-        var packageOrder = await _context.UserOrders
-            .FirstOrDefaultAsync(o => 
-                o.UserId == user.Id && 
-                o.PackageId != null &&
-                o.PaymentStatus == PaymentStatus.Success,
-                cancellationToken
-            );
-        
-        if (packageOrder == null)
-        {
-            throw new ValidationException("سفارش پکیج طلایی یافت نشد.");
-        }
-        
-        // 5. بررسی Transaction
-        var transaction = await _context.Transactions
-            .FirstOrDefaultAsync(t => t.Id == packageOrder.TransactionId, cancellationToken);
-        
-        if (transaction == null || 
-            (transaction.Type != TransactionType.DepositIpg && 
-             transaction.Type != TransactionType.DepositExternal1))
-        {
-            throw new ValidationException("تراکنش معتبر برای فعالسازی باشگاه یافت نشد.");
-        }
-        
-        // 6. بررسی اینکه قبلاً فعال نکرده باشد
-        var existingMembership = await _context.ClubMemberships
-            .FirstOrDefaultAsync(c => c.UserId == user.Id, cancellationToken);
-        
-        if (existingMembership != null && existingMembership.IsActive)
-        {
-            throw new ValidationException("شما قبلاً عضو باشگاه مشتریان هستید.");
-        }
-        
-        // 7. ثبت یا به‌روزرسانی ClubMembership
-        if (existingMembership == null)
-        {
-            existingMembership = new ClubMembership
-            {
-                UserId = user.Id,
-                IsActive = true,
-                ActivatedAt = DateTime.Now,
-                InitialContribution = 56_000_000,
-                TotalEarned = 0,
-                PurchaseMethod = user.PackagePurchaseMethod
-            };
-            
-            _context.ClubMemberships.Add(existingMembership);
-        }
-        else
-        {
-            existingMembership.IsActive = true;
-            existingMembership.ActivatedAt = DateTime.Now;
-            existingMembership.PurchaseMethod = user.PackagePurchaseMethod;
-        }
-        
-        await _context.SaveChangesAsync(cancellationToken);
-        
-        return true;
-    }
-}
-```
-
----
-
-### 4️⃣ `ChargeDiscountWalletCommand` (سناریو 3)
-
-**مسئولیت:** شارژ کیف پول تخفیفی
-
-```csharp
-public class ChargeDiscountWalletCommand : IRequest<PaymentInitiateResult>
-{
-    public long UserId { get; set; }
-    public long Amount { get; set; }
-}
-
-public class ChargeDiscountWalletCommandHandler 
-    : IRequestHandler<ChargeDiscountWalletCommand, PaymentInitiateResult>
-{
-    private readonly IApplicationDbContext _context;
-    private readonly IPaymentGatewayService _paymentGateway;
-
-    public async Task<PaymentInitiateResult> Handle(
-        ChargeDiscountWalletCommand request, 
-        CancellationToken cancellationToken)
-    {
-        // 1. بررسی User
-        var user = await _context.Users
-            .FirstOrDefaultAsync(u => u.Id == request.UserId, cancellationToken);
-        
-        if (user == null)
-            throw new NotFoundException(nameof(User), request.UserId);
-        
-        // 2. بررسی مبلغ (حداقل 10,000 تومان)
-        if (request.Amount < 10_000)
-        {
-            throw new ValidationException("حداقل مبلغ شارژ 10,000 تومان است.");
-        }
-        
-        // 3. Redirect به درگاه
-        var paymentRequest = new PaymentRequest
-        {
-            Amount = request.Amount,
-            OrderId = $"DISCOUNT_{user.Id}_{DateTime.Now:yyyyMMddHHmmss}",
-            CallbackUrl = "https://yourdomain.com/verify-discount-wallet",
-            Description = $"شارژ کیف پول تخفیفی"
-        };
-        
-        var result = await _paymentGateway.InitiatePaymentAsync(paymentRequest);
-        
-        return result;
-    }
-}
-```
-
----
-
-### 5️⃣ `VerifyDiscountWalletChargeCommand` (سناریو 3)
-
-**مسئولیت:** Verify و شارژ DiscountBalance
-
-```csharp
-public class VerifyDiscountWalletChargeCommand : IRequest<bool>
-{
-    public long UserId { get; set; }
-    public long Amount { get; set; }
-    public string Authority { get; set; }
-}
-
-public class VerifyDiscountWalletChargeCommandHandler 
-    : IRequestHandler<VerifyDiscountWalletChargeCommand, bool>
-{
-    private readonly IApplicationDbContext _context;
-    private readonly IPaymentGatewayService _paymentGateway;
-
-    public async Task<bool> Handle(
-        VerifyDiscountWalletChargeCommand request, 
-        CancellationToken cancellationToken)
-    {
-        // 1. پیدا کردن User
-        var user = await _context.Users
-            .FirstOrDefaultAsync(u => u.Id == request.UserId, cancellationToken);
-        
-        if (user == null)
-            throw new NotFoundException(nameof(User), request.UserId);
-        
-        // 2. Verify با بانک
-        var verifyResult = await _paymentGateway.VerifyPaymentAsync(
-            request.Authority, 
-            request.Amount
-        );
-        
-        if (!verifyResult.IsSuccess)
-        {
-            return false;
-        }
-        
-        // 3. شارژ DiscountBalance
-        var wallet = await _context.UserWallets
-            .FirstOrDefaultAsync(w => w.UserId == user.Id, cancellationToken);
-        
-        wallet.DiscountBalance += request.Amount;
-        
-        // 4. ثبت Transaction
-        var transaction = new Transactions
-        {
-            Amount = request.Amount,
-            Description = "شارژ کیف پول تخفیفی",
-            PaymentStatus = PaymentStatus.Success,
-            PaymentDate = DateTime.Now,
-            RefId = verifyResult.RefId,
-            Type = TransactionType.DiscountWalletCharge
-        };
-        
-        _context.Transactions.Add(transaction);
-        await _context.SaveChangesAsync(cancellationToken);
-        
-        // 5. ثبت ChangeLog
-        var changeLog = new UserWalletChangeLog
-        {
-            UserId = user.Id,
-            Amount = request.Amount,
-            ChangeType = WalletChangeType.Deposit,
-            Description = "شارژ موجودی تخفیفی",
-            BalanceBefore = wallet.DiscountBalance - request.Amount,
-            BalanceAfter = wallet.DiscountBalance
-        };
-        
-        _context.UserWalletChangeLogs.Add(changeLog);
-        
-        await _context.SaveChangesAsync(cancellationToken);
-        
-        return true;
-    }
-}
-```
-
----
-
-## 📝 تسک‌های پیاده‌سازی
-
-### Phase 1: Entity Changes (1 روز)
-
-1. **ایجاد `PackagePurchaseMethod` Enum**
-   - محل: `CMSMicroservice.Domain/Enums/PackagePurchaseMethod.cs`
-   - مقادیر: None, DayaLoan, DirectPurchase
-
-2. **اضافه کردن فیلد به `User`**
-   - فیلد: `PackagePurchaseMethod PackagePurchaseMethod`
-   - مقدار پیش‌فرض: `PackagePurchaseMethod.None`
-
-3. **اضافه کردن فیلد به `ClubMembership`**
-   - فیلد: `PackagePurchaseMethod PurchaseMethod`
-
-4. **ایجاد Migration**
-   ```bash
-   dotnet ef migrations add AddPackagePurchaseMethod
-   ```
-
----
-
-### Phase 2: Commands (2 روز)
-
-1. **`PurchaseGoldenPackageCommand`**
-   - بررسی `User.PackagePurchaseMethod`
-   - ثبت `UserOrder` با `PackageId`
-   - Redirect به درگاه
-
-2. **`VerifyGoldenPackagePurchaseCommand`**
-   - Verify پرداخت
-   - شارژ `Balance`
-   - ثبت `Transaction` (DepositIpg)
-   - Set `User.PackagePurchaseMethod = DirectPurchase`
-
-3. **`ActivateClubMembershipCommand`**
-   - چک‌های امنیتی (UserOrder + Transaction)
-   - ثبت/به‌روزرسانی `ClubMembership`
-
-4. **`ChargeDiscountWalletCommand` + `VerifyDiscountWalletChargeCommand`**
-   - شارژ `DiscountBalance`
-   - ثبت `Transaction` (DiscountWalletCharge)
-
----
-
-### Phase 3: به‌روزرسانی DayaLoan Flow (0.5 روز)
-
-- تغییر `ProcessDayaLoanCommandHandler`:
-  ```csharp
-  user.PackagePurchaseMethod = PackagePurchaseMethod.DayaLoan;
-  ```
-
----
-
-### Phase 4: Unit Tests (1 روز)
-
-1. تست `PurchaseGoldenPackageCommand`:
-   - کاربری که قبلاً پکیج خریده → باید خطا بدهد
-   - کاربر جدید → باید Order ایجاد شود
-
-2. تست `ActivateClubMembershipCommand`:
-   - کاربر بدون پکیج → خطا
-   - کاربر با موجودی کمتر از 56M → خطا
-   - کاربر معتبر → موفق
-
-3. تست `VerifyDiscountWalletChargeCommand`:
-   - پرداخت موفق → `DiscountBalance` افزایش یابد
-   - پرداخت ناموفق → هیچ تغییری نکند
-
----
-
-### Phase 5: Documentation (0.5 روز)
-
-- به‌روزرسانی `implementation-progress.md`
-- لینک از `REMAINING-TASKS-CONSOLIDATED.md`
-
----
-
-## 📊 خلاصه Timeline
-
-| Phase | عنوان | زمان |
-|-------|-------|------|
-| 1 | Entity Changes | 1 روز |
-| 2 | Commands & Handlers | 2 روز |
-| 3 | DayaLoan Flow Update | 0.5 روز |
-| 4 | Unit Tests | 1 روز |
-| 5 | Documentation | 0.5 روز |
-| **جمع** | | **5 روز** |
-
----
-
-## 🔗 مراجع
-
-- [DayaLoan Integration](./daya-loan-integration.md)
-- [Manual Payment System](./manual-payment-system.md)
-- [Implementation Progress](./implementation-progress.md)
-- [REMAINING-TASKS](../REMAINING-TASKS-CONSOLIDATED.md)
-
----
-
-**تاریخ آخرین به‌روزرسانی:** 2024-12-02  
-**نویسنده:** GitHub Copilot  
-**وضعیت:** ✅ تایید شده توسط کاربر

cms/ADMIN-CUSTOMER-SEPARATION-FIX.md

@@ -1,153 +0,0 @@
-# 🔀 جداسازی سرویس‌های Admin و Customer
-
-> آخرین بروزرسانی: February 10, 2026  
-> مرتبط با: [ICURRENTUSERSERVICE-IMPLEMENTATION.md](ICURRENTUSERSERVICE-IMPLEMENTATION.md)
-
----
-
-## 🐛 مشکل
-
-پنل ادمین BackOffice بجای نمایش اطلاعات **همه کاربران**، فقط اطلاعات **خود ادمین** رو نشان میداد.
-
-### علت ریشه‌ای:
-Query Handler ها وقتی `UserId = 0` دریافت می‌کردند، بجای اینکه "همه کاربران" رو برگردانند، به JWT fallback می‌کردند و UserId ادمین رو از توکن استخراج می‌کردند:
-
-```csharp
-// ❌ الگوی قدیمی (مشکل‌دار)
-var userId = request.UserId == 0
-    ? (long.TryParse(_currentUser.UserId, out var uid) ? uid : 0)  // ← fallback به JWT
-    : request.UserId;
-```
-
-### مشکل:
-- **BackOffice (Admin)** → `UserId = 0` ارسال میکنه → Handler از JWT ادمین میخونه → فقط اطلاعات ادمین برمیگرده
-- **FrontOffice (Customer)** → `UserId = 0` ارسال میکنه → Handler از JWT مشتری میخونه → اتفاقاً درسته، ولی دلیلش اشتباهه
-
----
-
-## ✅ الگوی جدید
-
-### اصل طراحی:
-> **Handler ها بی‌خبر از JWT هستند.** وظیفه resolve کردن کاربر، به عهده **Service Layer (gRPC endpoint)** است.
-
-### الگوی Handler:
-```csharp
-// ✅ الگوی جدید
-// UserId = 0 → بدون فیلتر (نمایش همه) — مناسب Admin
-// UserId > 0 → فیلتر بر اساس کاربر خاص — مناسب Customer یا Admin
-
-public async Task<Result> Handle(SomeQuery request, CancellationToken ct)
-{
-    var userId = request.UserId;
-    
-    var query = _context.SomeEntity.AsNoTracking();
-    
-    if (userId > 0)
-        query = query.Where(x => x.UserId == userId);
-    
-    // userId == 0 → no filter → return all
-    return await query.ToListAsync(ct);
-}
-```
-
-### الگوی Customer Service (JWT رو خودش resolve میکنه):
-```csharp
-// ✅ Customer endpoint → حتماً JWT resolve میکنه
-public override async Task<Response> GetMyData(Request request, ServerCallContext context)
-{
-    if (!long.TryParse(_currentUserService.UserId, out var userId) || userId == 0)
-        throw new RpcException(new Status(StatusCode.Unauthenticated, "User not authenticated"));
-    
-    var query = new GetDataQuery { UserId = userId };  // ← userId صریح
-    var result = await _sender.Send(query, context.CancellationToken);
-    return MapToResponse(result);
-}
-```
-
-### الگوی Admin Service (UserId رو از request میگیره):
-```csharp
-// ✅ Admin endpoint → UserId از request (0 = همه)
-public override async Task<Response> GetAllData(Request request, ServerCallContext context)
-{
-    // request.UserId = 0 → handler همه رو برمیگردونه
-    // request.UserId > 0 → handler فیلتر میکنه
-    var result = await _dispatcher.Send(request, context);
-    return result;
-}
-```
-
----
-
-## 📝 لیست تغییرات
-
-### 🔧 ۸ Query Handler اصلاح‌شده:
-
-| # | Handler | تغییر | رفتار `UserId = 0` |
-|---|---------|-------|---------------------|
-| 1 | `GetCustomerOrdersQueryHandler` | حذف `ICurrentUserService` + JWT fallback | بدون فیلتر → همه سفارشات |
-| 2 | `GetCustomerOrderQueryHandler` | حذف `ICurrentUserService` + JWT fallback | هر سفارشی با OrderId |
-| 3 | `GetUserWeeklyBalancesQueryHandler` | حذف `ICurrentUserService` + JWT fallback | بدون فیلتر → همه تعادل‌ها |
-| 4 | `GetUserCommissionPayoutsQueryHandler` | حذف `ICurrentUserService` + JWT fallback | بدون فیلتر → همه پرداخت‌ها |
-| 5 | `GetNetworkStatisticsQueryHandler` | حذف `ICurrentUserService` + JWT fallback | آمار root user (کل شبکه) |
-| 6 | `GetNetworkTreeQueryHandler` | حذف JWT fallback + خطا اگر UserId نباشد | `ArgumentException` (الزامی) |
-| 7 | `GetUserQueryHandler` | حذف JWT fallback + خطا اگر UserId نباشد | `ArgumentException` (الزامی) |
-| 8 | `GetUserWalletQueryHandler` | حذف JWT fallback + خطا اگر UserId نباشد | `ArgumentException` (الزامی) |
-
-### 🌐 ۴ Customer Service Endpoint اصلاح‌شده:
-
-| # | Service / Method | تغییر |
-|---|-----------------|-------|
-| 1 | `UserOrderService.GetCustomerOrders` | JWT resolve → ارسال `customerUserId` به handler |
-| 2 | `UserOrderService.GetCustomerOrder` | JWT resolve → ارسال `customerUserId` به handler |
-| 3 | `NetworkMembershipService.GetMyNetworkStatistics` | افزودن `ICurrentUserService` + JWT resolve |
-| 4 | `UserWalletService.GetCustomerWallet` | تغییر از `Id = 0` به `Id = userId` (از JWT) |
-
----
-
-## 📐 دیاگرام جریان
-
-### درخواست Admin (BackOffice):
-```
-BackOffice Panel → gRPC (UserId=0) → Admin Service → Handler (UserId=0 → no filter → ALL users) ✅
-BackOffice Panel → gRPC (UserId=42) → Admin Service → Handler (UserId=42 → filter → one user) ✅
-```
-
-### درخواست Customer (FrontOffice):
-```
-FrontOffice App → gRPC → Customer Service → JWT resolve (UserId=42) → Handler (UserId=42 → filter) ✅
-```
-
----
-
-## ⚠️ نکات مهم
-
-1. **Handler ها هرگز `ICurrentUserService` رو inject نمیکنند** (بعد از این فیکس)
-2. فقط **Customer Service endpoints** مسئول JWT resolve هستند
-3. **Admin endpoints** از `IDispatchRequestToCQRS` استفاده میکنند و UserId مستقیم از proto request میاد
-4. Handler هایی که UserId **الزامی** دارند (مثل GetUser, GetUserWallet, GetNetworkTree) → `ArgumentException` پرتاب میکنند
-5. Handler هایی که لیست برمیگردونند (مثل GetCustomerOrders, GetWeeklyBalances) → `UserId = 0` یعنی "بدون فیلتر"
-
----
-
-## 🔗 فایل‌های تغییر‌یافته
-
-### Application Layer:
-```
-CMS/src/CMSMicroservice.Application/
-├── OrdersCQ/Queries/GetCustomerOrders/GetCustomerOrdersQueryHandler.cs
-├── OrdersCQ/Queries/GetCustomerOrder/GetCustomerOrderQueryHandler.cs
-├── UserWeeklyBalanceCQ/Queries/GetUserWeeklyBalances/GetUserWeeklyBalancesQueryHandler.cs
-├── CommissionPayoutCQ/Queries/GetUserCommissionPayouts/GetUserCommissionPayoutsQueryHandler.cs
-├── NetworkStatisticsCQ/Queries/GetNetworkStatistics/GetNetworkStatisticsQueryHandler.cs
-├── NetworkTreeCQ/Queries/GetNetworkTree/GetNetworkTreeQueryHandler.cs
-├── UserCQ/Queries/GetUser/GetUserQueryHandler.cs
-└── UserWalletCQ/Queries/GetUserWallet/GetUserWalletQueryHandler.cs
-```
-
-### WebApi Layer:
-```
-CMS/src/CMSMicroservice.WebApi/Services/
-├── UserOrderService.cs          (GetCustomerOrders + GetCustomerOrder)
-├── NetworkMembershipService.cs  (GetMyNetworkStatistics)
-└── UserWalletService.cs         (GetCustomerWallet)
-```

cms/BFF-REMOVAL-PLAN.md

@@ -1,131 +0,0 @@
-# پلن حذف BFF‌ها — اتصال مستقیم فرانت‌اند به CMS
-
-> تاریخ: February 10, 2026
-
----
-
-## 📊 خلاصه وضعیت
-
-### یافته‌های کلیدی:
-1. **هر دو فرانت (BackOffice + FrontOffice) الان از proto‌های CMS مستقیم استفاده میکنن** — مهاجرت proto انجام شده
-2. **CMS خودش `VerifyOtpToken` و `AcceptContract` composite handler داره** — فقط یه `TODO` در AcceptContract برای JWT generation
-3. **CMS خودش `IPaymentGatewayService` + `DayaPaymentService` داره** — PYMS جداگانه لازم نیست
-4. **CMS خودش Kavenegar + SignalR Hub داره** — آماده‌ست
-5. **CMS خودش `ICurrentUserService` داره** — Security logic آماده‌ست
-
----
-
-## فاز ۱ — حذف BackOffice.BFF ✅ (انجام میشه الان)
-
-### ✅ تسک ۱.۱ — Permission Interceptor (انتقال)
-**وضعیت**: ✅ **انجام شد**
-
-**چیزی که هست (BFF)**:
-- `RequiresPermissionAttribute` — Attribute برای mark کردن gRPC methods
-- `PermissionInterceptor` — gRPC interceptor که attribute ها رو چک میکنه
-- `IPermissionService` + `PermissionService` — Role رو از JWT میخونه
-- `RolePermissionConfig` — ماتریس Role→Permission (3 نقش × 34 permission)
-
-**نقش‌ها**: SuperAdmin (Administrator), Admin, Inspector  
-**مجوزها**: 34 مجوز در 9 دسته (Dashboard, Orders, Products, Users, Commission, PublicMessages, ManualPayments, Settings, Reports)
-
-**فایل‌های ساخته شده:**
-- `Application/Common/Authorization/RequiresPermissionAttribute.cs`
-- `Application/Common/Authorization/PermissionDefinitions.cs`
-- `Application/Common/Authorization/IPermissionService.cs`
-- `Infrastructure/Services/Authorization/PermissionService.cs`
-- `WebApi/Interceptors/PermissionInterceptor.cs`
-
-**Attribute‌های اضافه شده (۲۱ عدد بر روی ۴ سرویس):**
-- `AppVersionService`: GetAppVersion(settings.view), GetAllAppVersions(settings.view), UpdateAppVersion(settings.manage_configuration)
-- `ConfigurationService`: GetAllConfigurations(settings.view), CreateOrUpdateConfiguration(settings.manage_configuration), DeactivateConfiguration(settings.manage_configuration)
-- `ManualPaymentService`: CreateManualPayment(manualpayments.create), ApproveManualPayment(manualpayments.approve), RejectManualPayment(manualpayments.approve), GetAllManualPayments(manualpayments.view), ProcessManualMembershipPayment(manualpayments.create)
-- `UserOrderService`: CreateNewUserOrder(orders.create), UpdateUserOrder(orders.update), DeleteUserOrder(orders.delete), GetUserOrder(orders.view), GetAllUserOrderByFilter(orders.view), UpdateOrderStatus(orders.update), GetOrdersByDateRange(reports.view), ApplyDiscountToOrder(orders.update), CalculateOrderPV(orders.view), CancelOrder(orders.cancel)
-
-### ❌ تسک ۱.۲ — AfrinoIDP OTP (بعداً)
-**وضعیت**: **پلن شده — فعلاً نیاز نیست**
-
-BackOffice ادمین لاگین از طریق `https://ids.afrino.co` (AfrinoIDP) انجام میشه.
-این یه external identity provider هست — فرانت BackOffice خودش مستقیم با AfrinoIDP ارتباط داره (OIDC flow).
-CMS فقط JWT رو validate میکنه — نیازی به proxy نداره.
-
-### ✅ تسک ۱.۳ — تغییر GwUrl
-**وضعیت**: ✅ **نیاز نبود — قبلاً انجام شده بود**
-
-| فایل | از | به |
-|------|-----|-----|
-| `BackOffice/wwwroot/appsettings.json` | `https://localhost:32846` | `https://localhost:32846` (بدون تغییر — dev) |
-| `BackOffice/wwwroot/appsettings.Staging.json` | ✅ **قبلاً** `https://cms.se.kbs1.ir` | بدون تغییر |
-
-> BackOffice Staging **قبلاً مستقیم به CMS وصله!** فقط dev (localhost) هنوز BFF روی همون پورته.
-
----
-
-## فاز ۲ — حذف FrontOffice.BFF ✅ (انجام میشه الان)
-
-### ✅ تسک ۲.۱ — Kavenegar SMS
-**وضعیت**: ✅ **قبلاً در CMS هست** — `IKavenegarService` + `KavenegarService`
-
-### ✅ تسک ۲.۲ — SignalR Token Relay
-**وضعیت**: ✅ **انجام شد** — آلیاس `/hubs/token-relay` در CMS اضافه شد
-
-**وضعیت فعلی**:
-- CMS Hub: `/hubs/token-notification` (اصلی ✅)
-- CMS Hub: `/hubs/token-relay` (آلیاس برای backward compatibility ✅)
-- FrontOffice Staging: `HubPath` → `/hubs/token-notification` ✅
-
-### ✅ تسک ۲.۳ — VerifyOtp + AcceptContract composite
-**وضعیت**: ✅ **کامل شد**
-
-- `VerifyOtpTokenCommandHandler` — OTP verify + JWT generation ✅
-- `AcceptContractCommandHandler` — Contract create + OTP verify + JWT generation ✅ (TODO فیکس شد → `IGenerateJwtToken` واقعی)
-
-### ✅ تسک ۲.۴ — PYMS (Zarinpal Payment)
-**وضعیت**: ✅ **نیاز نیست** 
-
-**دلیل**: FrontOffice **الان از CMS `TransactionsContract.CustomerPaymentRequest/Verification` استفاده میکنه** — مستقیم PYMS صدا نمیزنه.
-CMS هم از `IPaymentGatewayService` (DayaPaymentService) برای payment استفاده میکنه.
-PYMS فقط در BFF بود — فرانت هیچوقت مستقیم PYMS صدا نمیزنه.
-
-### ✅ تسک ۲.۵ — Security Logic (currentUserId injection)
-**وضعیت**: ✅ **قبلاً در CMS هست**
-
-CMS `ICurrentUserService` رو inject میکنه و `GetCurrentUserId()` helper در همه Customer سرویس‌ها هست:
-- UserService ✅
-- UserOrderService ✅
-- UserWalletService ✅
-- TransactionsService ✅
-- PackageService ✅
-- ClubMembershipService ✅
-- ConfigurationService ✅
-
-### ✅ تسک ۲.۶ — تغییر GwUrl FrontOffice
-**وضعیت**: ✅ **انجام شد**
-
-| فایل | از | به |
-|------|-----|-----|
-| `FrontOffice/appsettings.Staging.json` | `https://frontoffice-bff.se.kbs1.ir` | ✅ `https://cms.se.kbs1.ir` |
-| `FrontOffice/appsettings.Staging.json` HubPath | `/hubs/token-relay` | ✅ `/hubs/token-notification` |
-| `FrontOffice/appsettings.json` | `https://localhost:32846` | بدون تغییر (dev) |
-
----
-
-## خلاصه کارهای واقعی
-
-### ✅ همه تسک‌ها انجام شد:
-1. ✅ Permission Interceptor infrastructure + DI + gRPC pipeline
-2. ✅ `[RequiresPermission]` attributes روی ۲۱ endpoint در ۴ سرویس BackOffice
-3. ✅ فیکس `TODO` JWT generation در AcceptContractCommandHandler
-4. ✅ تغییر GwUrl FrontOffice Staging → `cms.se.kbs1.ir`
-5. ✅ مپ `/hubs/token-relay` → آلیاس در CMS (backward compatibility)
-6. ✅ Kavenegar — قبلاً در CMS بود
-7. ✅ Security Logic (ICurrentUserService) — قبلاً در CMS بود
-8. ✅ VerifyOtp/AcceptContract composite — قبلاً در CMS بود + JWT فیکس شد
-9. ✅ PYMS — فرانت مستقیم CMS protos استفاده میکنه
-
-### ❌ نیاز نیست:
-1. AfrinoIDP — BackOffice خودش OIDC flow مستقیم داره
-
-### 📋 تست‌های لازم قبل از حذف نهایی BFF:
-1. BackOffice Staging → اتصال مستقیم به CMS + تست Permission Interceptor
-2. FrontOffice Staging → اتصال به `cms.se.kbs1.ir` + تست SignalR + تست OTP/AcceptContract

cms/FILE-MANAGEMENT-ARCHITECTURE.md

@@ -1,251 +0,0 @@
-# 📁 معماری مدیریت فایل و تصاویر — CMS
-
-> **تاریخ:** ۱۴۰۴/۱۱/۲۸ (February 17, 2026)  
-> **وضعیت:** ✅ عملیاتی  
-> **Build:** 0 Error (هر ۳ پروژه) ✅
-
----
-
-## ۱. پیش‌زمینه
-
-سیستم قبلی از **FMS (File Management Service)** در آدرس `https://dl.afrino.co` استفاده می‌کرد که غیرقابل دسترس/ناسازگار شده بود. در چندین فاز، معماری فایل‌ها به صورت کامل بازنویسی شد:
-
-| فاز | شرح | وضعیت |
-|-----|------|-------|
-| ۱. حذف FMS | حذف کامل ۳ فایل مرده FMS | ✅ |
-| ۲. حالت base64 | ذخیره data URI مستقیم در DB | ✅ (بازنشسته) |
-| ۳. ذخیره دیسکی | فایل در دیسک + مسیر در DB + تبدیل به base64 هنگام serve | ✅ |
-| ۴. **سرو HTTP عمومی** | **اندپوینت `/uploads/{path}` + Fallback FMS** | **✅ جدید** |
-
----
-
-## ۲. معماری نهایی
-
-```
-BackOffice (Blazor WASM)
-    │
-    │  MudFileUpload → IBrowserFile → byte[] → gRPC ImageFileModel
-    │
-    ▼
-CMS gRPC Service
-    │
-    │  proto ImageFileModel → Command.ImageFileBytes
-    │
-    ▼
-MediatR Handler
-    │
-    │  IFileManager.UploadImageAsync(folder, bytes, mime, name)
-    │
-    ▼
-LocalFileManager
-    │
-    ├─ Main Image    → Uploads/Images/{folder}/{guid}.jpg  (1200×1200, JPEG Q75)
-    ├─ Thumbnail     → Uploads/Images/{folder}/{guid}_thumb.jpg  (300×300, JPEG Q75)
-    │
-    │  Returns: { Main.Path, Thumbnail.Path }  (relative paths stored in DB)
-    │
-    ▼
-ImagePathResolverInterceptor (gRPC response)
-    │
-    │  Walks all response fields → reads file from disk → data:{mime};base64,{bytes}
-    │
-    ▼
-BackOffice / FrontOffice  ← receives base64 data URI directly in proto fields
-```
-
----
-
-## ۳. اجزای کلیدی
-
-### ۳.۱ `IFileManager` — Interface
-
-**مسیر:** `Application/Common/FileManager/IFileManager.cs`
-
-```csharp
-public interface IFileManager
-{
-    Task<UploadResult> UploadAsync(string folder, byte[] file, string mime, string? fileName, CancellationToken ct);
-    Task<ImageUploadResult> UploadImageAsync(string folder, byte[] file, string mime, string? fileName, CancellationToken ct);
-    Task DeleteAsync(string path, CancellationToken ct);
-    string? ResolveImageUrl(string? path);
-}
-```
-
-- **`UploadAsync`** — آپلود فایل خام
-- **`UploadImageAsync`** — بهینه‌سازی + ساخت thumbnail خودکار (SixLabors.ImageSharp)
-- **`ResolveImageUrl`** — تبدیل مسیر نسبی به data URI (base64)
-
-### ۳.۲ `LocalFileManager` — پیاده‌سازی
-
-**مسیر:** `Infrastructure/Services/LocalFileManager.cs`
-
-| ویژگی | مقدار |
-|-------|-------|
-| ریشه آپلود | `FileStorage:UploadPath` یا `AppContext.BaseDirectory/Uploads` |
-| فرمت تصویر اصلی | JPEG, Quality 75, حداکثر 1200×1200 |
-| فرمت thumbnail | JPEG, Quality 75, حداکثر 300×300 |
-| نام‌گذاری فایل | `{Guid}.jpg` + `{Guid}_thumb.jpg` |
-| DI Registration | `services.AddSingleton<IFileManager, LocalFileManager>()` |
-
-### ۳.۳ `ImagePathResolverInterceptor` — gRPC Interceptor
-
-**مسیر:** `WebApi/Interceptors/ImagePathResolverInterceptor.cs`
-
-اینترسپتور **خودکار** تمام فیلدهای تصویری را در response‌های gRPC پیدا کرده و مسیر نسبی را به data URI تبدیل می‌کند.
-
-**فیلدهای شناسایی‌شده:**
-- `image_path`, `thumbnail_path`, `image_thumbnail_path`
-- `featured_image_path`, `featured_image_thumbnail_path`
-- `hero_image_path`, `product_thumbnail_path`
-- `avatar_path`, `avatar_url`
-
-**قابلیت‌ها:**
-- Walk بازگشتی پیام‌های proto
-- پشتیبانی از `string` ساده و `Google.Protobuf.WellKnownTypes.StringValue`
-- پشتیبانی از فیلدهای `repeated` (collection‌های تو در تو)
-- اگر مقدار `data:` یا `http` باشد → رد می‌شود (تبدیل نمی‌شود)
-
-### ۳.۴ `LoggingBehaviour` — پاکسازی لاگ
-
-**مسیر:** `WebApi/Common/Behaviours/LoggingBehaviour.cs`
-
-- فرمت لاگ: `JsonFormatter.Default.Format()` به جای `{@Request}`
-- پاکسازی فیلدهای باینری با regex (`File`, `ImageFile`, `image_file`, `file`)
-- محدودیت طول لاگ: حداکثر 2000 کاراکتر
-
-### ۳.۵ `UploadsController` — سرو عمومی فایل‌ها (HTTP) 🆕
-
-**مسیر:** `WebApi/Controllers/UploadsController.cs`
-
-اندپوینت عمومی REST برای سرو مستقیم تصاویر بدون نیاز به base64. مناسب برای بارگذاری تصاویر در تگ `<img>` و کاهش پهنای باند.
-
-| ویژگی | مقدار |
-|-------|-------|
-| مسیر | `GET /uploads/{**path}` |
-| احراز هویت | `[AllowAnonymous]` — عمومی |
-| کش مرورگر | `ResponseCache 86400` ثانیه (۲۴ ساعت) |
-| Content-Type | تشخیص خودکار از پسوند فایل (`FileExtensionContentTypeProvider`) |
-| Range Requests | ✅ فعال (`enableRangeProcessing: true`) |
-| محافظت مسیر | جلوگیری از path traversal (`..`, `\`, `Path.GetFullPath` validation) |
-
-**FMS Fallback:**
-اگر فایل محلی وجود نداشته باشد و تنظیم `FMS:Address` پر باشد:
-1. فایل از `{FMS:Address}/{relativePath}` دانلود می‌شود
-2. Content-Type بررسی می‌شود (فقط `image/*` و `application/pdf` مجاز)
-3. فایل روی دیسک محلی ذخیره و کش می‌شود
-4. سپس فایل محلی سرو می‌شود
-
-```
-Client → GET /uploads/Images/BlogPosts/abc.jpg
-         │
-         ├─ فایل محلی وجود دارد? → سرو مستقیم از دیسک
-         │
-         └─ فایل محلی وجود ندارد?
-              └─ FMS:Address تنظیم شده?
-                   ├─ بله → دانلود از dl.afrino.co → ذخیره محلی → سرو
-                   └─ خیر → 404 Not Found
-```
-
-**وابستگی‌ها:**
-- `IHttpClientFactory` با named client `"FMS"` (timeout: 30 ثانیه)
-- ثبت در `Program.cs`: `builder.Services.AddHttpClient("FMS", ...)`
-
----
-
-## ۴. Proto Messages — ImageFileModel
-
-هر حوزه (DiscountProduct, BlogPost, SitePage) پیام مستقل `ImageFileModel` خود را دارد:
-
-### DiscountProduct
-```protobuf
-message ImageFileModel {
-    bytes file = 1;
-    string mime = 2;
-    string file_name = 3;
-}
-```
-**استفاده در:** `CreateDiscountProductRequest`, `UpdateDiscountProductRequest`
-
-### BlogPost
-```protobuf
-message BlogImageFileModel {
-    bytes file = 1;
-    string mime = 2;
-    string file_name = 3;
-}
-```
-**استفاده در:** `CreateBlogPostRequest`, `UpdateBlogPostRequest`
-
-### SitePage
-```protobuf
-message SitePageImageFileModel {
-    bytes file = 1;
-    string mime = 2;
-    string file_name = 3;
-}
-```
-**استفاده در:** `UpdateSitePageRequest`, `CreateSitePageSectionRequest`, `UpdateSitePageSectionRequest`
-
----
-
-## ۵. جریان آپلود تصویر (مثال: BlogPost)
-
-```
-1. کاربر در BackOffice → MudFileUpload → انتخاب فایل
-2. BlogPostEditDialog.OnImageSelected()
-   → IBrowserFile.OpenReadStream() → byte[] + ContentType + FileName
-   → پیش‌نمایش base64 در UI
-3. Submit → BlogPostEditDto { ImageFile = bytes, ImageMime, ImageFileName }
-4. BlogPostService.CreateAsync()
-   → BlogImageFileModel { File = ByteString.CopyFrom(bytes), Mime, FileName }
-   → gRPC CreateBlogPostRequest
-5. CMS BlogPostService (gRPC) → CreateBlogPostCommand
-   { ImageFileBytes = request.ImageFile.File.ToByteArray(), ... }
-6. CreateBlogPostCommandHandler.Handle()
-   → _fileManager.UploadImageAsync("Images/BlogPosts", bytes, mime, name)
-   → post.FeaturedImagePath = result.Main.Path
-   → post.FeaturedImageThumbnailPath = result.Thumbnail.Path
-7. Response → ImagePathResolverInterceptor
-   → featured_image_path → data:image/jpeg;base64,...
-   → featured_image_thumbnail_path → data:image/jpeg;base64,...
-8. BackOffice / FrontOffice → نمایش مستقیم base64 data URI
-```
-
----
-
-## ۶. فایل‌های حذف‌شده (کد مرده FMS)
-
-| فایل | شرح |
-|------|------|
-| `Infrastructure/Services/FmsFileManager.cs` | پیاده‌سازی قدیمی FMS (HTTP upload) |
-| `Application/Common/FileManager/FileManagementService.cs` | سرویس قدیمی مدیریت فایل |
-| `Application/Common/FileManager/IFileManagementService.cs` | اینترفیس قدیمی |
-
----
-
-## ۷. تنظیمات
-
-### `appsettings.json` (CMS)
-```json
-{
-  "FileStorage": {
-    "UploadPath": "/app/Uploads"
-  }
-}
-```
-
-### محدودیت حجم gRPC
-```csharp
-// Program.cs
-services.AddGrpc(o => o.MaxReceiveMessageSize = 50 * 1024 * 1024); // 50MB
-```
-
-### FrontOffice — `UrlUtility.GetImageUrl()`
-```csharp
-public static string GetImageUrl(string? path)
-{
-    if (string.IsNullOrWhiteSpace(path)) return string.Empty;
-    if (path.StartsWith("data:") || path.StartsWith("http")) return path;
-    return $"{DownloadUrl?.TrimEnd('/')}/{path.TrimStart('/')}";
-}
-```

cms/FRONTOFFICE-CMS-API-COMPATIBILITY.md

@@ -1,619 +0,0 @@
-# FrontOffice to CMS API Compatibility Analysis
-
-**تاریخ:** 6 فوریه 2026
-**وضعیت:** در حال بررسی
-
-## خلاصه اجرایی
-
-این سند مقایسه API‌های مورد نیاز FrontOffice با API‌های موجود در CMS را نشان می‌دهد.
-
----
-
-## 1. User APIs (Authentication & Profile)
-
-### استفاده شده در FrontOffice
-
-| API Method | استفاده در Service | Status در CMS | یادداشت |
-|------------|-------------------|---------------|---------|
-| `GetUser()` | AuthService, Personal.razor | ✅ موجود | `GetUser(GetUserRequest)` |
-| `UpdateUser()` | Personal.razor | ✅ موجود | `UpdateUser(UpdateUserRequest)` |
-| `RefreshToken()` | AuthService | ✅ موجود | `RefreshToken(RefreshTokenRequest)` |
-| `CreateNewOtpToken()` | AuthDialog | ✅ موجود | `CreateNewOtpToken(CreateNewOtpTokenRequest)` |
-| `VerifyOtpToken()` | AuthDialog | ✅ موجود | `VerifyOtpToken(VerifyOtpTokenRequest)` |
-| `AcceptContract()` | RegisterWizard | ✅ موجود | `AcceptContract(AcceptContractRequest)` |
-| `GetCustomerProfile()` | Profile Pages | ✅ موجود | **پیاده شد در Task قبل** |
-| `GetCustomerReferrals()` | Tree.razor | ✅ موجود | **پیاده شد در Task قبل** |
-| `GetCustomerSettings()` | Settings.razor | ✅ موجود | **پیاده شد در Task قبل** |
-| `UpdateCustomerProfile()` | Personal.razor | ✅ موجود | Proto موجود است |
-| `ChangeCustomerPassword()` | ChangePassword.razor | ✅ موجود | Proto موجود است |
-| `UpdateCustomerSettings()` | Settings.razor | ✅ موجود | Proto موجود است |
-
-**نتیجه:** ✅ تمام User APIs موجود است
-
----
-
-## 2. Products APIs
-
-### استفاده شده در FrontOffice
-
-| API Method | استفاده در Service | Status در CMS | یادداشت |
-|------------|-------------------|---------------|---------|
-| `GetCustomerProducts()` | ProductService | ✅ موجود | **پیاده شد در Task قبل** |
-| `GetCustomerProductsByFilter()` | ProductService | ✅ موجود | **پیاده شد در Task قبل** |
-| `GetAllProductsByFilter()` | Products.razor | ✅ پیاده شد | **Public API - Feb 6, 2026** |
-
-**GetAllProductsByFilter Details:**
-- از `GetCustomerProductsByFilterQuery` استفاده می‌کند
-- پشتیبانی از فیلترها: Title, Price, Discount, CategoryId, SaleCount, و...
-- Sorting: پشتیبانی کامل (مثلاً "price desc")
-- Pagination: با MetaData کامل
-- CategoryIds: لیست شناسه دسته‌بندی‌های محصول
-
-**نتیجه:** ✅ تمام Products APIs موجود و پیاده شده
-
----
-
-## 3. Category APIs
-
-### استفاده شده در FrontOffice
-
-| API Method | استفاده در Service | Status در CMS | یادداشت |
-|------------|-------------------|---------------|---------|
-| `GetAllCategoriesForCustomer()` | CategoryService | ✅ پیاده شد | **Customer API - Feb 6, 2026** |
-| `GetCategoryById()` | CategoryService | ✅ موجود | Admin API: `GetCategory()` |
-
-**GetAllCategoriesForCustomer Details:**
-- از `GetAllCategoryByFilterQuery` استفاده می‌کند
-- فقط دسته‌بندی‌های فعال (IsActive = true)
-- مرتب‌سازی بر اساس SortOrder
-- پشتیبانی Pagination (default: PageSize=100)
-- شامل: Id, Name, Title, Description, ImagePath, ParentId, IsActive, SortOrder
-- ISender به CategoryService اضافه شد
-
-**نتیجه:** ✅ تمام Category APIs پیاده شده
-
----
-
-## 4. UserOrder APIs
-
-### استفاده شده در FrontOffice
-
-| API Method | استفاده در Service | Status در CMS | یادداشت |
-|------------|-------------------|---------------|---------|
-| `GetAllUserOrderByFilter()` | OrderService, Orders.razor | ✅ پیاده شد | **Feb 6, 2026** - Admin API |
-| `GetUserOrder()` | OrderService, OrderDetail.razor | ✅ پیاده شد | **Feb 6, 2026** - جزئیات کامل سفارش |
-| `GetCustomerOrders()` | OrderService | ✅ موجود | Customer API با فیلتر UserId |
-| `GetCustomerOrder()` | OrderService | ✅ موجود | Customer API با فیلتر UserId |
-| `GetUserOrderHistory()` | OrderService | ✅ موجود | Proto: `GetCustomerOrderHistory()` |
-| `GetVATRate()` | VATService, OrderService | ✅ پیاده شد | **Feb 6, 2026** |
-| `SubmitShopBuyOrder()` | CheckoutSummary.razor | ✅ پیاده شد | **Feb 6, 2026** - تکمیل فرآیند خرید |
-
-**GetVATRate Details:**
-- نرخ مالیات بر ارزش افزوده ایران: 9%
-- `VatRate = 0.09` (decimal)
-- `VatPercentage = 9` (int)
-- `IsEnabled = true`
-- استفاده در VATService برای محاسبه مالیات محصولات
-
-**SubmitShopBuyOrder Details (Feb 6, 2026 - Updated with Wallet Payment):**
-تبدیل سبد خرید به سفارش نهایی با پرداخت از کیف پول:
-
-1. **احراز هویت**: استخراج UserId از JWT Token (ICurrentUserService)
-2. **اعتبارسنجی سبد خرید**:
-   - بازیابی محصولات سبد خرید با Include(Product)
-   - چک کردن خالی نبودن سبد
-3. **اعتبارسنجی آدرس**:
-   - دریافت آدرس پیش‌فرض کاربر
-   - اجباری بودن وجود آدرس
-4. **محاسبات مالی**:
-   - مبلغ پایه: جمع (قیمت × تعداد) تمام آیتم‌ها
-   - مالیات: 9% از مبلغ پایه
-   - مبلغ کل: مبلغ پایه + مالیات
-   - اعتبارسنجی مبلغ: |serverTotal - clientTotal| < 100
-5. **اعتبارسنجی کیف پول (New - Feb 6)**:
-   - بازیابی کیف پول کاربر (UserWallet)
-   - چک موجودی: Balance >= TotalAmount
-   - خطا در صورت کمبود موجودی با نمایش موجودی فعلی و مبلغ مورد نیاز
-6. **ایجاد تراکنش (New - Feb 6)**:
-   - Type: TransactionType.Buy (0)
-   - Amount: TotalAmount
-   - PaymentStatus: Success
-   - PaymentDate: DateTime.UtcNow
-   - RefId: SHOP_{timestamp}
-   - Description: "خرید محصولات - سفارش #{OrderId}"
-7. **کسر از کیف پول (New - Feb 6)**:
-   - Balance -= TotalAmount
-   - ثبت موجودی جدید در UserWallet
-8. **لاگ تغییرات کیف پول (New - Feb 6)**:
-   - CurrentBalance: موجودی جدید
-   - ChangeValue: -TotalAmount (منفی برای برداشت)
-   - CurrentNetworkBalance: بدون تغییر
-   - CurrentDiscountBalance: بدون تغییر
-   - IsIncrease: false (برداشت)
-   - RefrenceId: TransactionId
-9. **ایجاد سفارش (UserOrder) - Updated**:
-   - TransactionId: لینک به تراکنش (New)
-   - PaymentStatus: Success (Changed from Pending)
-   - PaymentDate: DateTime.UtcNow (New)
-   - PaymentMethod: Wallet (New)
-   - DeliveryStatus: Pending
-   - HasVAT: true
-10. **ثبت مالیات (OrderVAT)**:
-    - VATRate: 0.09m (decimal)
-    - BaseAmount: مبلغ قبل از مالیات
-    - VATAmount: مبلغ مالیات
-    - TotalAmount: مبلغ کل
-11. **جزئیات فاکتور (FactorDetails)**:
-    - یک رکورد برای هر آیتم سبد خرید
-    - ذخیره ProductId, Count, UnitPrice, UnitDiscountPrice
-12. **پاکسازی سبد خرید**:
-    - Soft delete تمام آیتم‌های سبد (IsDeleted = true)
-
-**Transaction Flow:**
-```
-User → Cart → SubmitShopBuyOrder →
-1. Validate Cart
-2. Validate Address
-3. Calculate Amount (Base + 9% VAT)
-4. Validate Wallet Balance
-5. Create Transaction (Type=Buy, Status=Success)
-6. Deduct from Wallet.Balance
-7. Create UserWalletChangeLog (audit trail)
-8. Create Order (linked to Transaction, PaymentStatus=Success, PaymentMethod=Wallet)
-9. Create OrderVAT
-10. Create FactorDetails
-11. Clear Cart
-→ Return OrderId
-```
-
-**Wallet Types:**
-- **Balance** (موجودی عادی): Used for purchases - deducted in this flow
-- **NetworkBalance** (موجودی شبکه): Commission wallet - not touched
-- **DiscountBalance** (موجودی تخفیف): Discount-only wallet - not touched
-
-**Error Handling:**
-- "کیف پول یافت نشد": User has no wallet record
-- "موجودی کیف پول کافی نیست. موجودی: X تومان، مورد نیاز: Y تومان": Insufficient funds
-
-**خروجی**: شناسه سفارش (OrderId) برای redirect به صفحه جزئیات
-
-**GetUserOrder Details (Feb 6, 2026):**
-نمایش جزئیات کامل یک سفارش:
-- اطلاعات سفارش: Id, Amount, PaymentStatus, PaymentDate, DeliveryStatus
-- اطلاعات کاربر: UserFullName, UserNationalCode
-- آدرس: UserAddressText
-- مالیات (OrderVAT): VATRate, BaseAmount, VATAmount, TotalAmount, IsPaid
-- ردیابی: TrackingCode, DeliveryDescription
-- محصولات (FactorDetails): ProductId, ProductTitle, ProductThumbnailPath, UnitPrice, Count, UnitDiscountPrice
-
-**اصلاحات صفحه OrderDetail.razor:**
-- ✅ رفع NullReferenceException برای PaymentDate
-- ✅ نمایش "تاریخ ثبت" برای سفارشات Pending (بدون PaymentDate)
-- ✅ رفع نمایش اشتباه ProductThumbnailPath به جای ProductTitle
-- ✅ رفع خطاهای nullable value access (.Value → ?? 0)
-- ✅ محاسبه صحیح subtotal با nullable handling
-
-**GetAllUserOrderByFilter Details (Feb 6, 2026):**
-لیست تمام سفارشات با فیلترهای پیشرفته:
-- فیلترها: UserId (optional - 0 = همه کاربران), PaymentStatus, DeliveryStatus, PaymentDate
-- Pagination: MetaData کامل
-- Sorting: بر اساس فیلدهای مختلف
-- جزئیات هر سفارش: اطلاعات کاربر، آدرس، مالیات، محصولات، وضعیت ارسال
-
-**نتیجه:** ✅ تمام UserOrder APIs پیاده شده - فرآیند خرید کامل است
-
----
-
-## 5. UserWallet APIs
-
-### استفاده شده در FrontOffice
-
-| API Method | استفاده در Service | Status در CMS | یادداشت |
-|------------|-------------------|---------------|---------|
-| `GetCustomerWallet()` | WalletService | ✅ موجود | 3 نوع کیف پول: Balance, NetworkBalance, DiscountBalance |
-| `GetCustomerWalletChangeLog()` | WalletService | ✅ موجود | 6 فیلد موجودی: Current+Change برای هر 3 کیف پول |
-| `CustomerWithdrawBalance()` | WalletService | ✅ موجود | Proto موجود است |
-| `GetCustomerWithdrawals()` | WithdrawalRequests.razor | ✅ موجود | لیست درخواست‌های برداشت |
-| `GetCustomerWithdrawalSettings()` | WalletService | ✅ موجود | حداقل مبلغ برداشت |
-
-**سه نوع کیف پول:**
-1. **عادی (Regular)**: Balance & ChangeValue - برای خرید و شارژ عادی
-2. **شبکه (Network)**: NetworkBalance & ChangeNerworkValue - پاداش تیمی و کمیسیون
-3. **تخفیفی (Discount)**: DiscountBalance & ChangeDiscountValue - برای خرید تخفیفی
-
-**ساختار تراکنش (CustomerWalletChangeLogModel):**
-- `CurrentBalance` + `ChangeValue` - موجودی و تغییر کیف پول عادی
-- `CurrentNetworkBalance` + `ChangeNerworkValue` - موجودی و تغییر کیف پول شبکه
-- `CurrentDiscountBalance` + `ChangeDiscountValue` - موجودی و تغییر کیف پول تخفیفی
-- `IsIncrease` - آیا افزایش است یا کاهش
-- `RefrenceId` - شناسه ارجاع (سفارش، پرداخت، و...)
-- `CreatedAt` - تاریخ تراکنش (UTC Timestamp)
-
-**UI تراکنش‌ها:**
-- Desktop: جدول با ستون‌های جداگانه برای هر 3 کیف پول (تغییرات/مانده)
-- Mobile: کارت‌ها با 3 باکس افقی (عادی آبی، شبکه سبز، تخفیفی زرد)
-- تاریخ: تبدیل UTC به Local Time و نمایش جلالی
-- توضیحات: نمایش اینکه کدام کیف پول‌ها تغییر کرده‌اند
-
-**نتیجه:** ✅ تمام UserWallet APIs موجود و پیاده شده با UI کامل (Feb 5, 2026)
-
----
-
-## 6. Transaction APIs
-
-### استفاده شده در FrontOffice
-
-| API Method | استفاده در Service | Status در CMS | یادداشت |
-|------------|-------------------|---------------|---------|
-| `GetCustomerTransaction()` | TransactionService (در BFF) | ✅ موجود | **پیاده شد در Task قبل** |
-| `GetCustomerTransactionsByFilter()` | TransactionService | ✅ موجود | **پیاده شد در Task قبل** |
-| `CustomerPaymentRequest()` | Checkout workflow | ✅ موجود | Proto موجود است |
-| `CustomerPaymentVerification()` | PaymentCallback.razor | ✅ موجود | Proto موجود است |
-
-**نتیجه:** ✅ تمام Transaction APIs موجود است
-
----
-
-## 7. UserCarts APIs
-
-### استفاده شده در FrontOffice
-
-| API Method | استفاده در Service | Status در CMS | یادداشت |
-|------------|-------------------|---------------|---------|
-| `GetCustomerCart()` | CartService | ✅ پیاده شد | **Query Handler تکمیل شد - Feb 5** |
-| `AddToCustomerCart()` | CartService | ✅ پیاده شد | **Command Handler تکمیل شد - Feb 5** |
-| `UpdateCustomerCartItem()` | CartService | ✅ پیاده شد | **Command Handler تکمیل شد - Feb 5** |
-| `RemoveFromCustomerCart()` | CartService | ✅ پیاده شد | **Command Handler تکمیل شد - Feb 5** |
-
-**اصلاحات Feb 6, 2026:**
-- ✅ **رفع باگ Cart APIs در CheckoutSummary**: تمام صفحات از Admin APIs استفاده می‌کردند
-- ✅ تغییر `AddNewUserCartAsync` → `AddNewUserCartForCustomerAsync`
-- ✅ تغییر `UpdateUserCartAsync` → `UpdateUserCartForCustomerAsync`
-- ✅ تغییر request model: `AddNewUserCartRequest` → `AddNewUserCartForCustomerRequest`
-- ✅ تغییر request model: `UpdateUserCartRequest` → `UpdateUserCartForCustomerRequest`
-- ✅ اضافه `RemoveUserCartForCustomerAsync` برای حذف صحیح آیتم
-- ✅ اصلاح field name: `UserCartId` → `CartItemId` (Proto: cart_item_id)
-- ✅ رفع منطق حذف: از Update با Count=0 به RemoveUserCartForCustomer تغییر یافت
-
-**Field Naming Convention:**
-- Proto: `cart_item_id` (snake_case)
-- C# Generated: `CartItemId` (PascalCase)
-- ❌ نباید: `UserCartId` (نام قدیمی Admin API)
-
-**تاثیر:** حالا عملیات سبد خرید (افزودن/ویرایش/حذف) صحیح کار می‌کند و فقط سبد کاربر جاری را تغییر می‌دهد
-
-**نتیجه:** ✅ تمام UserCart Customer APIs پیاده شده و باگ‌های Security و Field Naming رفع شد
-
----
-
-## 8. UserAddress APIs
-
-### استفاده شده در FrontOffice
-
-| API Method | استفاده در Service | Status در CMS | یادداشت |
-|------------|-------------------|---------------|---------|
-| `GetCustomerAddresses()` | Addresses.razor | ✅ پیاده شد | **Query Handler تکمیل شد - Feb 5** |
-| `CreateCustomerAddress()` | AddAddressDialog.razor | ✅ پیاده شد | **Command Handler تکمیل شد - Feb 5** |
-| `UpdateCustomerAddress()` | EditAddressDialog.razor | ✅ پیاده شد | **Command Handler تکمیل شد - Feb 5** |
-| `DeleteCustomerAddress()` | Addresses.razor | ✅ پیاده شد | **Command Handler تکمیل شد - Feb 5** |
-| `SetCustomerDefaultAddress()` | Addresses.razor | ✅ پیاده شد | **Command Handler تکمیل شد - Feb 5** |
-
-**یادداشت:** CityName و ProvinceName در response خالی است - FrontOffice باید از City API جداگانه استفاده کند.
-
-**اصلاحات Feb 6, 2026:**
-- ✅ **رفع باگ صفحه Addresses**: تمام صفحات FrontOffice از Admin APIs استفاده می‌کردند
-- ✅ تغییر `GetAllUserAddressByFilter` → `GetCustomerAddresses` در Addresses.razor
-- ✅ تغییر `CreateNewUserAddress` → `CreateCustomerAddress` در AddAddressDialog
-- ✅ تغییر `UpdateUserAddress` → `UpdateCustomerAddress` در EditAddressDialog  
-- ✅ تغییر `DeleteUserAddress` → `DeleteCustomerAddress` در Addresses.razor
-- ✅ تغییر `SetAddressAsDefault` → `SetCustomerDefaultAddress` در Addresses.razor
-- ✅ اصلاح Model type: `GetAllUserAddressByFilterResponseModel` → `CustomerAddressModel`
-- ✅ اصلاح field name: `response.Addresses` → `response.Models`
-
-**تاثیر:** حالا کاربران فقط آدرس‌های خودشان را می‌بینند (قبلاً همه آدرس‌ها نمایش داده می‌شد)
-
-**نتیجه:** ✅ تمام UserAddress Customer APIs پیاده شده و باگ Security رفع شد
-
----
-
-## 9. City APIs
-
-### استفاده شده در FrontOffice
-
-| API Method | استفاده در Service | Status در CMS | یادداشت |
-|------------|-------------------|---------------|---------|
-| `GetAllCities()` | AddressDialog components | ✅ موجود | Public API |
-
-**نتیجه:** ✅ City APIs موجود است
-
----
-
-## 10. Package APIs
-
-### استفاده شده در FrontOffice
-
-| API Method | استفاده در Service | Status در CMS | یادداشت |
-|------------|-------------------|---------------|---------|
-| `GetCustomerPackages()` | PackageService | ✅ موجود | **پیاده شد در Task قبل** |
-| `GetCustomerPackageDetails()` | PackageService | ✅ موجود | **پیاده شد در Task قبل** |
-| `CustomerPurchasePackage()` | Package purchase flow | ✅ موجود | Proto موجود است |
-| `CustomerVerifyPackagePurchase()` | Package verification | ✅ موجود | Proto موجود است |
-| `GetCustomerPurchaseHistory()` | MyPackages.razor | ✅ موجود | **پیاده شد در Task قبل** |
-
-**نتیجه:** ✅ تمام Package APIs موجود است
-
----
-
-## 11. NetworkMembership APIs
-
-### استفاده شده در FrontOffice
-
-| API Method | استفاده در Service | Status در CMS | یادداشت |
-|------------|-------------------|---------------|---------|
-| `GetMyNetworkTree()` | NetworkMembershipService | ✅ موجود | Customer Query جداگانه با ICurrentUserService |
-| `GetSubordinateTree()` | NetworkMembershipService | ✅ موجود | Recursive tree traversal |
-| `GetMyNetworkStatistics()` | NetworkStatisticsPage.razor | ✅ موجود | با شمارش recursive تمام descendants |
-
-**اصلاحات انجام شده (Feb 5, 2026):**
-1. ✅ **GetMyNetworkTree Customer Query**: 
-   - ایجاد Query و Handler جداگانه برای Customer
-   - استفاده از ICurrentUserService به جای UserId در request
-   - رفع خطای Validation (UserId=0 قبلاً غیرمجاز بود)
-
-2. ✅ **GetNetworkStatistics Bug Fix**:
-   - قبلاً: فقط direct children (depth=1) شمارش می‌شد
-   - بعد: recursive counting تمام descendants در leftLeg و rightLeg
-   - متدهای کمکی: `GetAllDescendants()` و `CalculateDepths()`
-   - فرمول: `leftLegCount = GetAllDescendants(leftChild).Count + 1`
-
-**نتیجه:** ✅ تمام NetworkMembership APIs موجود و اصلاح شده
-
----
-
-## 12. Commission APIs
-
-### استفاده شده در FrontOffice
-
-| API Method | استفاده در Service | Status در CMS | یادداشت |
-|------------|-------------------|---------------|---------|
-| `GetWeekDefinitions()` | CommissionService | ✅ موجود | **پیاده شد در Task قبل** |
-| `GetCommissionBalances()` | CommissionDashboardPage | ✅ موجود | **پیاده شد در Task قبل** |
-
-**نتیجه:** ✅ تمام Commission APIs موجود است
-
----
-
-## 13. ClubMembership APIs
-
-### استفاده شده در FrontOffice
-
-| API Method | استفاده در Service | Status در CMS | یادداشت |
-|------------|-------------------|---------------|---------|
-| `ActivateClubMembership()` | ClubMembershipService | ✅ موجود | Proto موجود در CMS |
-| `GetClubMembershipStatus()` | MembershipPage.razor | ✅ موجود | Proto موجود در CMS |
-
-**نتیجه:** ✅ ClubMembership APIs موجود است
-
----
-
-## 14. Configuration APIs
-
-### استفاده شده در FrontOffice
-
-| API Method | استفاده در Service | Status در CMS | یادداشت |
-|------------|-------------------|---------------|---------|
-| `GetClubConfiguration()` | ClubConfigurationService | ✅ موجود | Proto موجود در CMS |
-| `GetClubFeatures()` | FeaturesPage.razor | ✅ موجود | Proto موجود در CMS |
-
-**نتیجه:** ✅ Configuration APIs موجود است
-
----
-
-## 15. AppVersion APIs
-
-### استفاده شده در FrontOffice
-
-| API Method | استفاده در Service | Status در CMS | یادداشت |
-|------------|-------------------|---------------|---------|
-| `GetAppVersion()` | AppVersionService | ✅ موجود | Proto موجود در CMS |
-
-**نتیجه:** ✅ AppVersion APIs موجود است
-
----
-
-## نتیجه‌گیری کلی
-
-### ✅ API های کامل (100% پیاده شده)
-1. ✅ User APIs - همه Customer endpoints پیاده شده
-2. ✅ Products APIs - GetCustomerProducts و Filter پیاده شده
-3. ✅ UserWallet APIs - تمام Customer endpoints پیاده شده
-4. ✅ Transaction APIs - Customer endpoints پیاده شده
-5. ✅ Package APIs - تمام Customer endpoints پیاده شده
-6. ✅ NetworkMembership APIs - پیاده شده
-7. ✅ Commission APIs - پیاده شده
-8. ✅ Category APIs - GetAllCategoriesForCustomer پیاده شد (Feb 6, 2026)
-9. ✅ City APIs - Public API موجود
-10. ✅ ClubMembership APIs - Proto موجود
-11. ✅ Configuration APIs - Proto موجود
-12. ✅ AppVersion APIs - Proto موجود
-13. ✅ **UserCarts APIs - تمام Customer endpoints پیاده شد (Feb 5, 2026) + اصلاحات Feb 6** 🆕
-14. ✅ **UserAddress APIs - تمام Customer endpoints پیاده شد (Feb 5, 2026) + باگ Security رفع شد Feb 6** 🆕
-15. ✅ **UserOrder APIs - Checkout workflow کامل شد (Feb 6, 2026)** 🆕
-16. ✅ **Products APIs - GetAllProductsByFilter پیاده شد (Feb 6, 2026)** 🆕
-
-### ⚠️ نیاز به توجه
-
-~~1. **UserCarts APIs** - نیاز به Customer-specific endpoints~~  
-   **✅ تکمیل شد - Feb 5, 2026 + اصلاحات Feb 6, 2026**
-
-~~2. **UserAddress APIs** - نیاز به Customer-specific endpoints~~  
-   **✅ تکمیل شد - Feb 5, 2026 + باگ Security رفع شد Feb 6, 2026**
-
-~~3. **UserOrder/Checkout APIs** - نیاز به بررسی~~  
-   **✅ تکمیل شد - Feb 6, 2026:**
-   - ✅ SubmitShopBuyOrder - تبدیل سبد خرید به سفارش
-   - ✅ GetUserOrder - نمایش جزئیات سفارش
-   - ✅ GetAllUserOrderByFilter - لیست سفارشات
-   - ✅ GetVATRate - دریافت نرخ مالیات 9%
-   - ✅ OrderDetail.razor - رفع باگ‌های NullReference
-
-4. **UpdateCustomerProfile, ChangeCustomerPassword, UpdateCustomerSettings** - Proto موجود اما Query/Handler نیاز است
-
----
-
-## اقدامات لازم
-
-~~### Priority 1: UserCarts Customer Endpoints~~  
-~~این APIs برای سبد خرید ضروری هستند.~~  
-**✅ تکمیل شد - Feb 5, 2026:**
-- ✅ GetCustomerCartQuery و Handler
-- ✅ AddToCustomerCartCommand و Handler
-- ✅ UpdateCustomerCartItemCommand و Handler
-- ✅ RemoveFromCustomerCartCommand و Handler
-- ✅ UserCartsService با ISender
-
-**✅ اصلاحات Security - Feb 6, 2026:**
-- ✅ CartService.cs: تمام عملیات به Customer APIs تغییر یافت
-- ✅ رفع باگ Field Naming: UserCartId → CartItemId
-- ✅ رفع منطق حذف: از Update به RemoveUserCartForCustomer
-
-~~### Priority 2: UserAddress Customer Endpoints~~  
-~~این APIs برای Checkout و مدیریت آدرس‌ها ضروری هستند.~~  
-**✅ تکمیل شد - Feb 5, 2026:**
-- ✅ GetCustomerAddressesQuery و Handler
-- ✅ CreateCustomerAddressCommand و Handler
-- ✅ UpdateCustomerAddressCommand و Handler
-- ✅ DeleteCustomerAddressCommand و Handler
-- ✅ SetCustomerDefaultAddressCommand و Handler
-- ✅ UserAddressService با ISender
-- ⚠️ **یادداشت:** CityName/ProvinceName در response خالی است - FrontOffice باید از City API استفاده کند
-
-**✅ اصلاحات Security - Feb 6, 2026:**
-- ✅ Addresses.razor: GetCustomerAddresses (قبلاً تمام آدرس‌ها نمایش می‌یافت)
-- ✅ Index.razor (Profile): GetCustomerAddresses
-- ✅ CheckoutSummary.razor: GetCustomerAddresses
-- ✅ Checkout.razor: GetCustomerAddresses
-- ✅ AddAddressDialog.razor: CreateCustomerAddress
-- ✅ EditAddressDialog.razor: UpdateCustomerAddress
-
-~~### Priority 3: Checkout/Order Creation~~
-باید workflow ثبت سفارش بررسی شود.
-
-### Priority 4: Customer Profile Updates
-پیاده‌سازی Handler های Update برای Customer.
-
----
-
-## وضعیت پروژه
-
-**تکمیل شده:** ~97%  
-**آخرین به‌روزرسانی:** 6 فوریه 2026  
-
-**تغییرات Feb 6, 2026:**
-
-**Phase 1: رفع باگ‌های Critical Security در FrontOffice**
-- ✅ **UserAddress Security Bug Fix**: تغییر از Admin APIs به Customer APIs در تمام صفحات
-  - Addresses.razor, Index.razor (Profile), CheckoutSummary.razor, Checkout.razor
-  - AddAddressDialog, EditAddressDialog
-  - قبلاً همه آدرس‌های تمام کاربران نمایش داده می‌شد ⚠️
-  - حالا فقط آدرس‌های کاربر لاگین شده (با ICurrentUserService)
-
-- ✅ **UserCart Security Bug Fix**: تغییر از Admin APIs به Customer APIs در CartService
-  - تمام عملیات: Add, Update, Remove, Clear
-  - رفع باگ Field Naming: UserCartId → CartItemId (Proto: cart_item_id)
-  - رفع منطق حذف: از UpdateUserCart با Count=0 به RemoveUserCartForCustomer
-  - قبلاً تمام سبدهای خرید تمام کاربران قابل دسترسی بود ⚠️
-
-**Phase 2: پیاده‌سازی APIs گم‌شده**
-- ✅ **GetVATRate**: پیاده‌سازی در UserOrderService
-  - نرخ مالیات بر ارزش افزوده ایران: 9%
-  - استفاده در VATService و Products page
-  
-- ✅ **GetAllProductsByFilter**: پیاده‌سازی در ProductsService
-  - استفاده از GetCustomerProductsByFilterQuery
-  - پشتیبانی کامل از filtering, sorting, pagination
-  - CategoryIds mapping به درستی
-  
-- ✅ **GetAllCategoriesForCustomer**: پیاده‌سازی در CategoryService
-  - استفاده از GetAllCategoryByFilterQuery
-  - فقط دسته‌بندی‌های فعال (IsActive = true)
-  - ISender به CategoryService اضافه شد
-  - مرتب‌سازی بر اساس SortOrder
-
-**Phase 3: تکمیل Checkout Workflow**
-- ✅ **SubmitShopBuyOrder**: تبدیل سبد خرید به سفارش نهایی با **پرداخت از کیف پول** (Updated Feb 6)
-  - احراز هویت با ICurrentUserService (UserId از JWT)
-  - اعتبارسنجی سبد خرید (خالی نباشد) و آدرس پیش‌فرض
-  - محاسبات مالی: مبلغ پایه + مالیات 9% = مبلغ کل
-  - **اعتبارسنجی موجودی کیف پول**: Balance >= TotalAmount 🆕
-  - **ایجاد تراکنش**: Type=Buy, PaymentStatus=Success, RefId=SHOP_{timestamp} 🆕
-  - **کسر از کیف پول**: Balance -= TotalAmount 🆕
-  - **ثبت لاگ تغییرات**: UserWalletChangeLog با تمام جزئیات (audit trail) 🆕
-  - ایجاد سفارش (UserOrder): **PaymentStatus=Success, PaymentMethod=Wallet, TransactionId** (Updated from Pending)
-  - ثبت مالیات (OrderVAT): VATRate, BaseAmount, VATAmount, TotalAmount
-  - ایجاد جزئیات فاکتور (FactorDetails) برای هر محصول
-  - پاکسازی سبد خرید (soft delete)
-  - بازگشت OrderId برای redirect
-  - **خطاها**: "کیف پول یافت نشد", "موجودی کیف پول کافی نیست"
-
-- ✅ **GetUserOrder**: نمایش جزئیات کامل سفارش
-  - استفاده از GetCustomerOrderQuery
-  - اطلاعات سفارش + کاربر + آدرس + مالیات + محصولات + ردیابی
-  - پشتیبانی از nullable fields (PaymentDate, PaymentMethod)
-
-- ✅ **GetAllUserOrderByFilter**: لیست سفارشات با فیلتر
-  - Admin API - می‌تواند همه سفارشات را ببیند
-  - فیلترها: UserId, PaymentStatus, DeliveryStatus, PaymentDate
-  - Pagination + Sorting کامل
-
-- ✅ **OrderDetail.razor - رفع باگ‌های UI**:
-  - رفع NullReferenceException برای PaymentDate (null برای سفارشات Pending)
-  - نمایش "تاریخ ثبت" به جای "تاریخ پرداخت" برای سفارشات بدون پرداخت
-  - رفع نمایش ProductThumbnailPath به جای ProductTitle
-  - رفع خطاهای nullable value access: .Value → ?? 0
-  - محاسبه صحیح subtotal با null coalescing
-
-**خلاصه تغییرات:**
-- 🔒 **Security**: رفع باگ‌های critical در UserAddress و UserCart (همه کاربران قابل مشاهده بودند)
-- 📦 **Products**: GetAllProductsByFilter + GetAllCategoriesForCustomer پیاده شد
-- 💰 **VAT**: GetVATRate با نرخ 9% ایران
-- 🛒 **Checkout**: workflow کامل - سبد خرید → سفارش → نمایش جزئیات
-- 🐛 **Bug Fixes**: OrderDetail null handling + Field naming (UserCartId → CartItemId)
-
-**تغییرات قبلی (Feb 5, 2026):**
-
-**Phase 1: UserCart & UserAddress Customer Endpoints**
-- ✅ پیاده‌سازی کامل UserCart Customer endpoints (4 Handler + Service)
-- ✅ پیاده‌سازی کامل UserAddress Customer endpoints (5 Handler + Service)
-- ✅ اضافه کردن Proto definitions برای Customer Address
-
-**Phase 2: NetworkMembership Bug Fixes**
-- ✅ GetMyNetworkTree Customer Query (رفع خطای Validation)
-- ✅ GetNetworkStatistics Recursive Counting (رفع باگ شمارش نادرست)
-
-**Phase 3: UserWallet UI Enhancement**
-- ✅ رفع باگ نمایش 0 در مبالغ تراکنش‌ها
-- ✅ اضافه کردن CurrentDiscountBalance و ChangeDiscountValue به Proto (v0.0.177)
-- ✅ جداسازی تراکنش‌ها به 3 نوع کیف پول (عادی، شبکه، تخفیفی)
-- ✅ اصلاح نام‌گذاری: "اعتباری" → "عادی"
-- ✅ رفع باگ تاریخ: اضافه کردن ToLocalTime() برای تبدیل UTC
-- ✅ UI Desktop: جدول با ستون‌های جداگانه برای هر 3 کیف پول
-- ✅ UI Mobile: کارت‌ها با 3 باکس افقی (عادی آبی، شبکه سبز، تخفیفی زرد)
-- ✅ نمایش همزمان تغییرات و موجودی مانده برای هر کیف پول
-- ✅ تغییر FrontOffice.Main.csproj: PackageReference → ProjectReference
-
-**باقی مانده:** 
-- ⚠️ Checkout workflow و Order creation (نیاز به بررسی)
-- ⚠️ Profile update handlers (UpdateCustomerProfile, ChangePassword, UpdateSettings)
-- 📝 CityName/ProvinceName در GetCustomerAddresses خالی است (نیاز به City API lookup در FrontOffice)
-
-**Build Status:**
-- ✅ CMS: 0 Errors, ~60 Warnings (unused proto imports)
-- ✅ FrontOffice: 0 Errors, ~120 Warnings (nullable references)
-
-**صفحات تست شده (Feb 6):**
-- ✅ /profile/addresses - کار می‌کند (فقط آدرس‌های خود کاربر)
-- ✅ /products - کار می‌کند (لیست محصولات با filtering و sorting)
-- ✅ /categories - کار می‌کند (لیست دسته‌بندی‌های فعال)
-- ✅ /profile/wallet - کار می‌کند (3 کیف پول با تراکنش‌های کامل)
-

cms/FRONTOFFICE-RELEASE-NOTES-v1.5.0.md

@@ -1,38 +0,0 @@
-# 🎉 به‌روزرسانی جدید - نسخه ۱.۵.۰
-
-**تاریخ انتشار**: ۹ دی ۱۴۰۴
-
----
-
-## ✨ امکانات جدید
-
-### 💰 بهبود صفحه پاداش‌ها
-- **انتخابگر هفته هوشمند**: حالا می‌تونید با تایپ کردن، هفته مورد نظر رو سریع‌تر پیدا کنید
-- **نمایش خلاصه**: در بالای صفحه، مجموع پاداش‌ها، مبلغ پرداخت شده و در انتظار رو ببینید
-- **طراحی جدید موبایل**: تجربه بهتر در گوشی موبایل
-
-### 📊 جزئیات بیشتر در گزارش هفتگی
-- **نمایش اعضای جدید**: تعداد اعضای جدید هر تیم در هفته
-- **انتقال از هفته قبل**: مشاهده امتیازات منتقل شده از هفته گذشته
-
-### 🎨 بهبود رابط کاربری
-- طراحی زیباتر کارت‌ها و جداول
-- نمایش بهتر در تمام اندازه‌های صفحه نمایش
-
----
-
-## 🐛 رفع اشکال
-
-- رفع مشکل نمایش نادرست امتیازات منتقل شده
-- بهبود سرعت بارگذاری صفحات
-
----
-
-## 💡 نکته
-
-برای دسترسی به پاداش‌های خود، از منوی **پروفایل** گزینه **پاداش‌های من** را انتخاب کنید.
-
----
-
-با تشکر از همراهی شما 🙏
-**تیم کارا بازار سلامت**

cms/GRPC-SERVICES-AUDIT.md

@@ -0,0 +1,219 @@
+# آدیت سرویس‌های gRPC — CMS
+
+> تاریخ: ۱۴۰۴/۰۴  
+> آخرین بروزرسانی: ۱۴۰۴/۱۲/۰۶  
+> هدف: شناسایی RPCهایی که از هیچ‌کدام از فرانت‌ها (FrontOffice مشتری + BackOffice ادمین) فراخوانی نمی‌شوند + تصمیم‌گیری نگهداری vs آرشیو
+
+---
+
+## 📊 خلاصه آمار
+
+| متریک | تعداد |
+|--------|-------|
+| کل فایل‌های proto | 43 (بدون google/) |
+| کل سرویس‌های gRPC | 42 |
+| **کل RPC متدها** | **342** |
+| استفاده‌شده در FrontOffice | 92 |
+| استفاده‌شده در BackOffice | 159 |
+| **استفاده‌شده (مجموع یکتا)** | **217** |
+| **استفاده‌نشده از فرانت‌ها** | **125** |
+| ↳ استفاده‌شده داخلی CMS | 101 |
+| ↳ **کد مُرده واقعی** | **24** |
+
+---
+
+## 🔴 بخش ۱ — تحلیل ۲۴ RPC مُرده: نگهداری vs آرشیو
+
+### ✅ نگهداری (آینده‌نگرانه — ۱۲ عدد)
+
+> این RPCها پیاده‌سازی کامل دارند و در نقشه‌راه آینده محصول کاربرد دارند.
+
+| # | RPC | فایل Proto | کیفیت کد | دلیل نگهداری |
+|---|-----|-----------|---------|-------------|
+| 1 | `CustomerReorderPreviousOrder` | userorder.proto | ✅ **کامل** — آیتم‌های سفارش قبلی به سبد اضافه می‌شود | UX حیاتی: «تکرار سفارش قبلی» — فیچر رایج فروشگاهی، فقط نیاز به دکمه در FrontOffice |
+| 2 | `CustomerTrackOrder` | userorder.proto | ✅ **کامل** — وضعیت + TrackingCode + DeliveryInfo | UX حیاتی: «ردیابی سفارش» — وقتی ارسال پستی فعال شود ضروری است |
+| 3 | `CalculateOrderPV` | userorder.proto | ✅ **کامل** — PV هر آیتم + جمع کل | سیستم MLM: محاسبه PV (Point Value) سفارش — برای فاز بعدی کمیسیون بر اساس خرید |
+| 4 | `GetInventorySummary` | inventory.proto | ✅ **کامل** — آمار تعداد + ارزش کل | داشبورد ادمین: خلاصه موجودی انبار — نیاز به کارت در BackOffice Dashboard |
+| 5 | `GetStockValueReport` | inventory.proto | ✅ **کامل** — گزارش ارزش ریالی موجودی | گزارش مالی: ارزش دارایی انبار — برای حسابداری ضروری |
+| 6 | `BulkAddStock` | inventory.proto | ✅ **کامل** — loop با error handling | عملیات انبوه: افزودن موجودی دسته‌ای — بعد از ورود کالای فیزیکی |
+| 7 | `BulkUpdateProductStock` | products.proto | ✅ **کامل** — Set/Add/Subtract با error handling | عملیات انبوه: بروزرسانی دسته‌ای موجودی محصول |
+| 8 | `GetConfigurationByKey` | configuration.proto | ✅ **کامل** — خواندن از SystemConstants | API مفید: دریافت یک تنظیم خاص بدون بارگذاری همه — performance بهتر |
+| 9 | `UpdateCustomerSettings` | user.proto | ✅ **کامل** — Email/SMS/Push notifications | تنظیمات اعلان‌ها: وقتی پنل تنظیمات مشتری ساخته شود |
+| 10 | `ChangeNetworkParent` | networkmembership.proto | ✅ **CQRS کامل** → MoveInNetworkCommand | مدیریت شبکه: جابجایی کاربر در درخت — ابزار ادمین ضروری |
+| 11 | `AssignFeatureToMembership` | clubmembership.proto | ✅ **CQRS کامل** → AssignClubFeatureCommand | مدیریت عضویت: اختصاص فیچر به عضویت — برای فاز بسته‌بندی پویا |
+| 12 | `GetLowStockProducts` | products.proto | ✅ **کامل** — فیلتر threshold + pagination | هشدار موجودی: مکمل GetLowStockItems — فیلتر ClubExclusive اضافه دارد |
+
+### 🗑️ آرشیو (حذف امن — ۱۲ عدد)
+
+> این RPCها یا stub خالی هستند، یا جایگزین بهتری دارند، یا هرگز ساخته نشدند.
+
+| # | RPC | فایل Proto | وضعیت کد | دلیل آرشیو |
+|---|-----|-----------|---------|-----------|
+| 1 | `CreateNewFileInfo` | fms.proto | ❌ **۰ رفرنس** — هیچ Service/Handler ندارد | سرویس FMS هرگز طراحی نشد — فایل‌ها از imageresolver استفاده می‌کنند |
+| 2 | `DeleteFileInfo` | fms.proto | ❌ **۰ رفرنس** — هیچ Service/Handler ندارد | همان — کل fms.proto حذف‌شدنی |
+| 3 | `BulkAdjustStock` | inventory.proto | ❌ **۰ رفرنس** — حتی Service method ندارد | هرگز پیاده‌سازی نشد — از AdjustStock تکی استفاده می‌شود |
+| 4 | `CreateNewOrderForCustomer` | userorder.proto | ❌ **Stub خالی** — `return new()` | مسیر سفارش مشتری از SubmitShopBuyOrder می‌گذرد — تکراری |
+| 5 | `SubmitOrderForCustomer` | userorder.proto | ❌ **Stub خالی** — `return new()` | مسیر سفارش مشتری از SubmitShopBuyOrder می‌گذرد — تکراری |
+| 6 | `DeactivateConfiguration` | configuration.proto | ❌ **throw میکند** — «تنظیمات فقط خواندنی هستند» | عمداً غیرفعال شده — SystemConstants ثابت هستند |
+| 7 | `GetConfigurationHistory` | configuration.proto | ❌ **خالی برمی‌گرداند** — `return new()` | SystemConstants تاریخچه ندارند — بی‌معنی |
+| 8 | `DeleteCity` | City.proto | ✅ کامل ولی **بی‌نیاز** | شهرها seed دیتا هستند — حذف شهر باعث خرابی آدرس‌ها می‌شود |
+| 9 | `UpdateCity` | City.proto | ✅ کامل ولی **بی‌نیاز** | شهرها از سرویس خارجی seed شده‌اند — ویرایش دستی نیاز نیست |
+| 10 | `GetOrdersByDateRange` | userorder.proto | ✅ کامل ولی **تکراری** | `GetAllUserOrderByFilter` همین قابلیت + فیلترهای بیشتر دارد |
+| 11 | `GetServiceHealth` | health.proto | ✅ کامل ولی **تکراری** | `GetSystemHealth` کل سیستم را برمی‌گرداند — فیلتر client-side کافی است |
+| 12 | `GetCategoryByIdForCustomer` | category.proto | ✅ کامل ولی **تکراری** | `GetCategory` (admin) + `GetAllCategoriesForCustomer` کافی است |
+
+---
+
+## 🟡 بخش ۲ — استفاده داخلی CMS (Internal Only — ۱۰۱ عدد)
+
+> این RPCها از فرانت‌ها فراخوانی نمی‌شوند ولی **در کد بکند CMS فعال هستند** (background services, handlers, internal flows). **حذف نشوند!**
+
+### B1. احراز هویت و کاربر (user.proto)
+
+| RPC | رفرنس CMS | علت |
+|-----|-----------|-----|
+| `CreateNewUser` | 175 | ثبت‌نام کاربر — اصلی‌ترین فلو |
+| `GetJwtToken` | 38 | صدور توکن JWT |
+| `AdminGetJwtToken` | 19 | لاگین ادمین |
+| `SetPasswordForUser` | 24 | تنظیم رمز عبور |
+| `ChangeCustomerPassword` | 5 | تغییر رمز مشتری |
+| `UploadCustomerAvatar` | 6 | آپلود آواتار |
+| `GetCustomerProfile` | 13 | پروفایل مشتری |
+| `GetCustomerReferrals` | 13 | لیست معرفی‌شدگان |
+| `GetCustomerSettings` | 13 | تنظیمات مشتری |
+
+### B2. بسته‌ها و پرداخت (package.proto / manualpayment.proto)
+
+| RPC | رفرنس CMS | علت |
+|-----|-----------|-----|
+| `PurchaseGoldenPackage` | 21 | خرید بسته طلایی — فلو فعال |
+| `VerifyGoldenPackagePurchase` | 22 | تأیید خرید بسته طلایی |
+| `CustomerPurchasePackage` | 3 | خرید مشتری (proto-generated + service) |
+| `CustomerVerifyPackagePurchase` | 3 | تأیید خرید مشتری |
+| `GetCustomerPurchaseHistory` | 13 | تاریخچه خرید |
+| `ProcessManualMembershipPayment` | 20 | پرداخت دستی عضویت |
+
+### B3. شبکه و عضویت (networkmembership.proto / clubmembership.proto)
+
+| RPC | رفرنس CMS | علت |
+|-----|-----------|-----|
+| `JoinNetwork` | 14 | پیوستن به شبکه — فراخوانی خودکار |
+| `RemoveFromNetwork` | 14 | حذف از شبکه |
+
+### B4. کمیسیون (commission.proto)
+
+| RPC | رفرنس CMS | علت |
+|-----|-----------|-----|
+| `CalculateWeeklyBalances` | 26 | سرویس پس‌زمینه هفتگی |
+| `CalculateWeeklyCommissionPool` | 22 | سرویس پس‌زمینه هفتگی |
+| `ProcessUserPayouts` | 15 | پردازش پرداخت‌ها |
+| `GetCommissionPayoutHistory` | 20 | تاریخچه پرداخت کمیسیون |
+
+### B5. انبارداری (inventory.proto)
+
+| RPC | رفرنس CMS | علت |
+|-----|-----------|-----|
+| `ConfirmSale` | 10 | تأیید فروش — فلو سفارش |
+| `ReserveStock` | 12 | رزرو موجودی — فلو سفارش |
+| `ReleaseReservation` | 10 | آزادسازی رزرو |
+| `ProcessReturn` | 6 | پردازش مرجوعی |
+| `DeleteWarehouse` | 18 | حذف انبار |
+| `GetInventoryByProduct` | 26 | موجودی بر اساس محصول |
+| `GetInventoryItem` | 19 | آیتم انبار |
+| `GetWarehouse` | 18 | دریافت انبار |
+| `SetDefaultWarehouse` | 18 | تنظیم انبار پیش‌فرض |
+| `UpdateWarehouse` | 18 | بروزرسانی انبار |
+| `GetStockMovementsByInventoryItem` | 17 | حرکات موجودی |
+
+### B6. تراکنش‌ها (transactions.proto)
+
+| RPC | رفرنس CMS | علت |
+|-----|-----------|-----|
+| `CreateNewTransactions` | 26 | ایجاد تراکنش — فلو پرداخت |
+| `DeleteTransactions` | 23 | حذف تراکنش |
+| `GetAllTransactionsByFilter` | 25 | لیست تراکنش‌ها |
+| `CustomerPaymentVerification` | 3 | تأیید پرداخت مشتری |
+| `GetCustomerTransaction` | 27 | تراکنش مشتری |
+| `GetCustomerTransactionsByFilter` | 14 | فیلتر تراکنش‌ها |
+| `RefundTransaction` | 31 | استرداد تراکنش |
+| `UpdateTransactions` | 23 | بروزرسانی تراکنش |
+| `VerifyTransaction` | 24 | تأیید تراکنش |
+
+### B7. سایر CRUD داخلی (خلاصه)
+
+> ۵۸ RPC در فایل‌های contract, usercontract, factordetails, productcategory, productgalleries, productimages, userwallet, userwalletchangelog, otptoken, usercarts, discountproduct, public_messages, category, products, producttag, tag, City, useraddress, userorder — همه CRUD داخلی با ≥3 رفرنس در CMS.
+
+---
+
+## 🟢 بخش ۳ — سرویس‌های کاملاً مورد استفاده
+
+### فایل‌های proto که تمام RPCهایشان استفاده می‌شود:
+
+| فایل Proto | کل RPC | استفاده FO | استفاده BO |
+|-----------|--------|-----------|-----------|
+| appversion.proto | 3 | ✅ 1 | ✅ 3 |
+| blogcategory.proto | 6 | ✅ 2 | ✅ 6 |
+| blogpost.proto | 11 | ✅ 5 | ✅ 9 |
+| blogpostimage.proto | 4 | ✅ 0 | ✅ 4 |
+| discountcategory.proto | 4 | ✅ 1 | ✅ 4 |
+| discountorder.proto | 7 | ✅ 3 | ✅ 4 |
+| discountshoppingcart.proto | 5 | ✅ 5 | ✅ 0 |
+| manualpayment.proto | 5 | ✅ 0 | ✅ 4 |
+| public_messages.proto | 8 | ✅ 0 | ✅ 7 |
+| role.proto | 5 | ✅ 0 | ✅ 5 |
+| sitepage.proto | 10 | ✅ 2 | ✅ 10 |
+| sitepagesettings.proto | 5 | ✅ 1 | ✅ 5 |
+| tag.proto | 6 | ✅ 0 | ✅ 5 |
+| userrole.proto | 5 | ✅ 0 | ✅ 5 |
+
+---
+
+## 📋 بخش ۴ — خلاصه تصمیمات
+
+### ماتریکس نهایی ۲۴ RPC مُرده
+
+```
+✅ نگهداری (12):  CustomerReorderPreviousOrder, CustomerTrackOrder,
+                   CalculateOrderPV, GetInventorySummary, GetStockValueReport,
+                   BulkAddStock, BulkUpdateProductStock, GetConfigurationByKey,
+                   UpdateCustomerSettings, ChangeNetworkParent,
+                   AssignFeatureToMembership, GetLowStockProducts
+
+🗑️ آرشیو (12):   CreateNewFileInfo, DeleteFileInfo, BulkAdjustStock,
+                   CreateNewOrderForCustomer, SubmitOrderForCustomer,
+                   DeactivateConfiguration, GetConfigurationHistory,
+                   DeleteCity, UpdateCity, GetOrdersByDateRange,
+                   GetServiceHealth, GetCategoryByIdForCustomer
+```
+
+### فایل‌های proto آرشیو‌شدنی (کامل)
+
+| فایل | وضعیت | اقدام |
+|------|-------|-------|
+| **fms.proto** | کل فایل مُرده (2 RPC) | حذف از csproj — ساخته نشود |
+
+### RPCهای آرشیو‌شدنی (جزئی — داخل فایل‌های فعال)
+
+| فایل Proto | RPCهای آرشیو | RPCهای فعال |
+|-----------|-------------|-------------|
+| inventory.proto | `BulkAdjustStock` (1) | 23 فعال |
+| userorder.proto | `CreateNewOrderForCustomer`, `SubmitOrderForCustomer` (2) | 18 فعال |
+| configuration.proto | `DeactivateConfiguration`, `GetConfigurationHistory` (2) | 5 فعال |
+| City.proto | `DeleteCity`, `UpdateCity` (2) | 6 فعال |
+| health.proto | `GetServiceHealth` (1) | 1 فعال |
+| category.proto | `GetCategoryByIdForCustomer` (1) | 7 فعال |
+
+---
+
+## ⚠️ نکات مهم
+
+1. **آرشیو ≠ حذف!** — RPCهای آرشیو‌شده با `[Obsolete]` + `#region [ARCHIVED]` علامت‌گذاری شدند (کامیت `13dd0f5`)
+2. RPCهای دسته B (Internal — ۱۰۱ عدد) **حیاتی** هستند — بدون آنها سیستم از کار می‌افتد
+3. RPCهای «نگهداری» (۱۲ عدد) کد **کامل و آماده** دارند — بکلاگ فیچر: [FEATURE-BACKLOG.md](../roadmap/FEATURE-BACKLOG.md)
+4. **fms.proto** از csproj اکسکلود شد (کامیت `13dd0f5`)
+5. نقشه‌راه تحول پکیج‌بیس: [PACKAGE-TRANSFORMATION-TASKS.md](../roadmap/PACKAGE-TRANSFORMATION-TASKS.md)
+6. قبل از هر تغییر، حتماً `grep -rn "RpcName" CMS/src/` بزنید تا مطمئن شوید
+
+---
+
+*آخرین بروزرسانی: ۱۴۰۴/۱۲/۰۶*

cms/ICURRENTUSERSERVICE-IMPLEMENTATION.md

@@ -1,591 +0,0 @@
-# پیاده‌سازی ICurrentUserService در سرویس‌های Customer
-
-## خلاصه تغییرات
-این سند تمام تغییرات انجام شده برای پیاده‌سازی احراز هویت مبتنی بر JWT در endpoint‌های Customer را مستند می‌کند. هدف اصلی حذف نیاز به ارسال صریح UserId از سمت کلاینت و استخراج خودکار آن از JWT Claims است.
-
-## الگوی پیاده‌سازی
-
-### الگوی Query Handler (با ICurrentUserService)
-```csharp
-public class SomeQueryHandler : IRequestHandler<SomeQuery, SomeResponseDto>
-{
-    private readonly IApplicationDbContext _context;
-    private readonly ICurrentUserService _currentUser;
-
-    public SomeQueryHandler(IApplicationDbContext context, ICurrentUserService currentUser)
-    {
-        _context = context;
-        _currentUser = currentUser;
-    }
-
-    public async Task<SomeResponseDto> Handle(SomeQuery request, CancellationToken cancellationToken)
-    {
-        // رزولو کردن UserId از JWT اگر در request مشخص نشده باشد
-        var userId = request.UserId == 0
-            ? (long.TryParse(_currentUser.UserId, out var currentUserId) ? currentUserId : 0)
-            : request.UserId;
-
-        if (userId == 0)
-            throw new UnauthorizedAccessException("User ID not found");
-
-        var query = _context.SomeEntity
-            .Where(x => x.UserId == userId)
-            .AsNoTracking();
-
-        // ... ادامه پیاده‌سازی
-    }
-}
-```
-
-### الگوی Service (استفاده از ISender)
-```csharp
-public class SomeService : SomeContract.SomeContractBase
-{
-    private readonly ISender _sender;
-
-    public SomeService(ISender sender)
-    {
-        _sender = sender;
-    }
-
-    public override async Task<Response> CustomerEndpoint(Request request, ServerCallContext context)
-    {
-        var query = new SomeQuery { UserId = 0 }; // 0 = استفاده از ICurrentUserService
-        var result = await _sender.Send(query, context.CancellationToken);
-        return MapToProtoResponse(result);
-    }
-}
-```
-
-## تصمیمات معماری
-
-### 1. ISender vs IDispatchRequestToCQRS
-- **IDispatchRequestToCQRS**: برای endpoint‌های Admin که ساختار Proto به‌طور مستقیم به CQRS نگاشت می‌شود
-- **ISender**: برای endpoint‌های Customer که نیاز به ساخت دستی Query و ساختار متفاوت دارند
-
-### 2. قرارداد UserId = 0
-- `0` یا مقدار مشخص نشده = استفاده از ICurrentUserService برای دریافت کاربر فعلی از JWT
-- مقدار غیر صفر = کاربر صریح (برای عملیات admin/support)
-
-### 3. مسئولیت Query Handler
-- Query Handler باید پس از رزولو کردن userId، وجود آن را validate کند
-- در صورت عدم موفقیت در تعیین userId، UnauthorizedAccessException پرتاب شود
-
-## سرویس‌های پیاده‌سازی شده
-
-### ✅ 1. UserWallet Service (5 endpoints)
-
-#### 1.1 GetUserWalletQueryHandler
-**فایل**: `CMSMicroservice.Application/UserWalletCQ/Queries/GetUserWallet/GetUserWalletQueryHandler.cs`
-
-**تغییرات**:
-- افزودن `ICurrentUserService` به constructor
-- اضافه شدن فیلد `DiscountBalance` به DTO
-- پشتیبانی از `Id = 0` برای استفاده از کاربر فعلی
-
-```csharp
-var userId = request.Id == 0 
-    ? (long.TryParse(_currentUser.UserId, out var currentUserId) ? currentUserId : 0)
-    : request.Id;
-```
-
-#### 1.2 GetCustomerWalletChangeLogQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/UserWalletCQ/Queries/GetCustomerWalletChangeLog/`
-
-**پیاده‌سازی**:
-- Query/Handler جدید برای دریافت تاریخچه تغییرات کیف پول
-- استفاده از entity `UserWalletChangeLog`
-- پشتیبانی از Pagination
-- فیلتر بر اساس userId از ICurrentUserService
-
-#### 1.3 GetCustomerWithdrawalsQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/UserWalletCQ/Queries/GetCustomerWithdrawals/`
-
-**پیاده‌سازی**:
-- Query/Handler جدید برای دریافت درخواست‌های برداشت
-- استفاده از entity `UserCommissionPayout`
-- فیلتر بر اساس `WithdrawalRequestDate` و `status = PayoutRequested`
-- پشتیبانی از Pagination
-
-#### 1.4 GetCustomerWithdrawalSettingsQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/UserWalletCQ/Queries/GetCustomerWithdrawalSettings/`
-
-**پیاده‌سازی**:
-- Query/Handler جدید برای دریافت تنظیمات برداشت
-- مقدار ثابت `MIN_WITHDRAWAL_AMOUNT = 50000`
-- برگرداندن موجودی کیف پول کاربر فعلی
-
-#### 1.5 UserWalletService
-**فایل**: `CMSMicroservice.WebApi/Services/UserWalletService.cs`
-
-**تغییرات**:
-- افزودن `ISender` به constructor
-- پیاده‌سازی 4 متد Customer با استفاده از Query Handler‌های واقعی:
-  - `GetCustomerWallet`
-  - `GetCustomerWalletChangeLog`
-  - `GetCustomerWithdrawals`
-  - `GetCustomerWithdrawalSettings`
-
----
-
-### ✅ 2. Commission Service (2 endpoints)
-
-#### 2.1 GetUserCommissionPayoutsQueryHandler
-**فایل**: `CMSMicroservice.Application/CommissionCQ/Queries/GetUserCommissionPayouts/GetUserCommissionPayoutsQueryHandler.cs`
-
-**تغییرات**:
-- افزودن `ICurrentUserService` به constructor
-- پشتیبانی از `UserId = null` یا `0` برای استفاده از کاربر فعلی
-- کوئری از `UserCommissionPayouts` با Include کردن `WeekDefinition`
-
-#### 2.2 GetUserWeeklyBalancesQueryHandler
-**فایل**: `CMSMicroservice.Application/CommissionCQ/Queries/GetUserWeeklyBalances/GetUserWeeklyBalancesQueryHandler.cs`
-
-**تغییرات**:
-- افزودن `ICurrentUserService` به constructor
-- همان الگوی رزولو UserId
-- کوئری از `UserWeeklyBalances` با Include کردن `WeekDefinition`
-
----
-
-### ✅ 3. NetworkMembership Service (3 endpoints)
-
-#### 3.1 GetNetworkTreeQueryHandler
-**فایل**: `CMSMicroservice.Application/NetworkMembershipCQ/Queries/GetNetworkTree/GetNetworkTreeQueryHandler.cs`
-
-**تغییرات**:
-- افزودن `ICurrentUserService` به constructor
-- پشتیبانی از `UserId = 0` برای استفاده از کاربر فعلی
-- اجرای Stored Procedure `[CMS].[GetNetworkTree]`
-- تبدیل نتایج flat SP به ساختار درختی hierarchical
-
-#### 3.2 GetNetworkStatisticsQueryHandler
-**فایل**: `CMSMicroservice.Application/NetworkMembershipCQ/Queries/GetNetworkStatistics/GetNetworkStatisticsQueryHandler.cs`
-
-**تغییرات**:
-- افزودن پارامتر `UserId` به Query
-- افزودن `ICurrentUserService` به constructor
-- تغییر منطق از آمار کل سیستم به آمار شبکه زیرمجموعه کاربر
-- فیلتر: `x.NetworkParentId == userId` (نه `x.NetworkParentId != null`)
-
-#### 3.3 NetworkMembershipService
-**فایل**: `CMSMicroservice.WebApi/Services/NetworkMembershipService.cs`
-
-**تغییرات**:
-- افزودن `ISender` به constructor
-- پیاده‌سازی 3 متد Customer:
-  - `GetMyNetworkTree`: درخت شبکه کاربر فعلی با UserId=0
-  - `GetSubordinateTree`: درخت زیرمجموعه خاص (برای admin)
-  - `GetMyNetworkStatistics`: آمار شبکه کاربر فعلی
-- متدهای helper:
-  - `ConvertToNodeModel()`: تبدیل بازگشتی DTO به Proto Model
-  - `CountNodes()`: شمارش بازگشتی node‌های درخت
-
-**رفع باگ**:
-- حذف فیلدهای `IsClubActive` و `ActivationWeekDefinitionId` که در Proto request وجود نداشتند
-
----
-
-### ✅ 4. Package Service (3 query endpoints)
-
-#### 4.1 GetCustomerPackagesQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/PackageCQ/Queries/GetCustomerPackages/`
-
-**پیاده‌سازی**:
-- Query/Handler جدید برای دریافت لیست پکیج‌ها
-- کوئری از entity `Package`
-- نگاشت فیلدهای اضافی:
-  - `Name = Title`
-  - `ImageUrl = ImagePath`
-  - `Currency = "IRR"`
-  - `ValidityDays = 365`
-- پشتیبانی از فیلتر `PackageType` (در صورت وجود در entity)
-
-#### 4.2 GetCustomerPackageDetailsQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/PackageCQ/Queries/GetCustomerPackageDetails/`
-
-**پیاده‌سازی**:
-- Query/Handler جدید برای دریافت جزئیات یک پکیج
-- کوئری بر اساس `PackageId`
-- افزودن Features (کمیسیون، پشتیبانی، آموزش)
-- افزودن Requirements (عضویت، موجودی کیف پول، محدودیت‌ها)
-
-#### 4.3 GetCustomerPurchaseHistoryQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/PackageCQ/Queries/GetCustomerPurchaseHistory/`
-
-**پیاده‌سازی**:
-- Query/Handler جدید با ICurrentUserService
-- کوئری از `UserOrders` با فیلتر `PackageId != null`
-- Include کردن navigation property `Package`
-- پشتیبانی از:
-  - Pagination
-  - فیلتر تاریخ (FromDate, ToDate)
-  - فیلتر نوع پکیج
-- نگاشت `PaymentStatus` صحیح (Success/Reject/Pending)
-- دریافت `RefId` از Transaction (نه `ReferenceId`)
-
-#### 4.4 PackageService
-**فایل**: `CMSMicroservice.WebApi/Services/PackageService.cs`
-
-**تغییرات**:
-- افزودن `ISender` به constructor
-- افزودن namespace alias: `using AppModels = CMSMicroservice.Application.Common.Models;`
-- جایگزینی 3 متد MOCK با Query Handler واقعی:
-  - `GetCustomerPackages`
-  - `GetCustomerPackageDetails`
-  - `GetCustomerPurchaseHistory`
-- رفع ابهام در type‌های `PaginationState` و `MetaData` با استفاده از alias
-- متدهای Command (Purchase, Verify) همچنان MOCK باقی ماندند
-
----
-
-## مشکلات رفع شده
-
-### 1. خطای Type Inference با IDispatchRequestToCQRS
-**خطا**: `CS1061: 'Empty' does not contain definition for 'Balance'`
-
-**علت**: استفاده از overload نادرست `Handle<TCommand, TResponse>` که compiler نوع‌ها را اشتباه استنباط می‌کرد
-
-**راه حل**: استفاده از `ISender.Send()` به‌جای `IDispatchRequestToCQRS` برای endpoint‌های Customer
-
-### 2. عدم تطابق فیلدهای Proto
-**خطا**: `CS1061: GetSubordinateTreeRequest doesn't have ActivationWeekDefinitionId`
-
-**علت**: کد سرویس فیلدهایی را فرض می‌کرد که در Proto تعریف نشده بودند
-
-**راه حل**: حذف فیلدهای غیرموجود از نگاشت request
-
-### 3. خطای Nullable Protobuf Wrapper
-**خطا**: `CS1061: 'long' doesn't contain 'Value' property`
-
-**علت**: تلاش برای فراخوانی `.Value` روی type‌های non-nullable
-
-**راه حل**: حذف فراخوانی `.Value` و انتساب مستقیم
-
-### 4. خطای Transaction.ReferenceId
-**خطا**: `CS1061: 'Transaction' does not contain a definition for 'ReferenceId'`
-
-**علت**: نام صحیح فیلد `RefId` است نه `ReferenceId`
-
-**راه حل**: تغییر به `Transaction.RefId`
-
-### 5. خطای PaymentStatus Enum Values
-**خطا**: `CS0117: 'PaymentStatus' does not contain a definition for 'Failed'/'Refunded'`
-
-**علت**: enum فقط دارای مقادیر `Success`, `Reject`, `Pending` است
-
-**راه حل**: تصحیح switch statement به مقادیر صحیح
-
-### 6. خطای Ambiguous Reference
-**خطا**: `CS0104: 'PaginationState'/'MetaData' is ambiguous`
-
-**علت**: type‌ها هم در `CMSMicroservice.Application.Common.Models` و هم در `CMSMicroservice.Protobuf.Protos` وجود دارند
-
-**راه حل**: افزودن namespace alias: `using AppModels = CMSMicroservice.Application.Common.Models;`
-
-### 7. خطای MetaData Constructor
-**خطا**: `CS1729: 'MetaData' does not contain a constructor that takes 3 arguments`
-
-**علت**: MetaData class در Application layer بدون constructor است
-
-**راه حل**: استفاده از object initializer به‌جای constructor:
-```csharp
-var metaData = new MetaData
-{
-    TotalCount = totalCount,
-    CurrentPage = pageNumber,
-    PageSize = pageSize,
-    TotalPage = (int)Math.Ceiling((double)totalCount / pageSize),
-    HasPrevious = pageNumber > 1,
-    HasNext = pageNumber < totalPages
-};
-```
-
-### 8. خطای CategoryIds در Proto
-**خطا**: `CS1061: 'GetAllProductsByFilterFilter' does not contain 'CategoryIds'`
-
-**علت**: Proto فقط `category_id` (singular) دارد نه `category_ids`
-
-**راه حل**: تبدیل single value به List:
-```csharp
-CategoryIds = request.Filter?.CategoryId != null 
-    ? new List<long> { request.Filter.CategoryId.Value } 
-    : null
-```
-
-### 9. خطای OrderVAT و DeliveryStatus
-**خطا**: `CS1061: 'OrderVAT' does not contain 'VATPercentage'`
-
-**علت**: 
-- فیلد صحیح `VATRate` است (decimal)
-- enum‌های `Processing` و `Shipped` وجود ندارند
-
-**راه حل**:
-- استفاده از `VATRate * 100` برای درصد
-- تصحیح enum values: `Pending`, `InTransit`, `Delivered`, `Cancelled`, `Returned`
-
-### 10. خطای Transaction/UserWalletChangeLog بدون UserId
-**خطا**: `CS1061: 'Transaction/UserWalletChangeLog' does not contain 'UserId'`
-
-**علت**: این entity‌ها direct UserId ندارند
-
-**راه حل**: query از طریق navigation properties:
-```csharp
-// Transaction
-.Include(x => x.UserOrders)
-.Where(x => x.UserOrders.Any(o => o.UserId == userId))
-
-// UserWalletChangeLog
-.Include(x => x.Wallet)
-.Where(x => x.Wallet.UserId == userId)
-```
-
----
-
-### ✅ 5. UserOrder Service (3 endpoints)
-
-#### 5.1 GetCustomerOrdersQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/UserOrderCQ/Queries/GetCustomerOrders/`
-
-**پیاده‌سازی**:
-- Query/Handler جدید با ICurrentUserService
-- کوئری از `UserOrders` با Include:
-  - Package, Transaction, UserAddress, User, FactorDetails, OrderVAT
-- پشتیبانی از Pagination
-- محاسبه `TotalAmount` با احتساب مالیات (`VATRate * 100`)
-
-**رفع باگ**:
-- `OrderVAT.VATPercentage` وجود ندارد → استفاده از `VATRate * 100`
-- `DeliveryStatus.Processing/Shipped` وجود ندارد → `Pending/InTransit`
-
-#### 5.2 GetCustomerOrderQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/UserOrderCQ/Queries/GetCustomerOrder/`
-
-**پیاده‌سازی**:
-- Query/Handler برای دریافت یک سفارش با OrderId
-- Validation: بررسی تعلق Order به UserId فعلی
-- Include همان navigation properties
-
-#### 5.3 GetCustomerOrderHistoryQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/UserOrderCQ/Queries/GetCustomerOrderHistory/`
-
-**پیاده‌سازی**:
-- Query/Handler با Pagination و فیلترها
-- فیلترهای پشتیبانی شده:
-  - FromDate, ToDate
-  - PaymentStatus, DeliveryStatus
-- محاسبه `CanCancelOrder` بر اساس شرایط:
-  - PaymentStatus = Pending
-  - DeliveryStatus = None یا Pending
-
-#### 5.4 UserOrderService
-**فایل**: `CMSMicroservice.WebApi/Services/UserOrderService.cs`
-
-**تغییرات**:
-- افزودن ISender به constructor
-- پیاده‌سازی 3 متد Customer با Query Handler واقعی
-- استفاده از namespace alias برای حل ambiguity
-
----
-
-### ✅ 6. Transaction Service (2 endpoints)
-
-#### 6.1 GetCustomerTransactionQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/TransactionsCQ/Queries/GetCustomerTransaction/`
-
-**پیاده‌سازی**:
-- Query/Handler با ICurrentUserService
-- **چالش**: Transaction entity بدون UserId
-- **راه حل**: query از طریق `UserOrders` navigation:
-  ```csharp
-  .Include(x => x.UserOrders)
-  .Where(x => x.UserOrders.Any(o => o.UserId == userId))
-  ```
-- فیلتر بر اساس Id یا Authority
-
-#### 6.2 GetCustomerTransactionsByFilterQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/TransactionsCQ/Queries/GetCustomerTransactionsByFilter/`
-
-**پیاده‌سازی**:
-- Query/Handler با Pagination
-- فیلترهای پشتیبانی شده:
-  - Id, Amount, Description
-  - PaymentStatus (bool), RefId, Type
-- همان الگوی query از طریق UserOrders
-
-#### 6.3 TransactionsService
-**فایل**: `CMSMicroservice.WebApi/Services/TransactionsService.cs`
-
-**تغییرات**:
-- افزودن ISender و Query imports
-- جایگزینی MOCK با Query Handler واقعی
-- mapping صحیح Proto enums
-
----
-
-### ✅ 7. Products Service (2 endpoints)
-
-#### 7.1 GetCustomerProductsQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/ProductsCQ/Queries/GetCustomerProducts/`
-
-**پیاده‌سازی**:
-- Query/Handler بدون ICurrentUserService (محصولات عمومی)
-- کوئری از `Products` با Include:
-  - ProductGalleries.ProductImage
-  - ProductCategories.Category
-- ساخت درختی Category Path با متد `BuildCategoryPath()`
-- بازگشت بازگشتی به parent categories
-
-#### 7.2 GetCustomerProductsByFilterQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/ProductsCQ/Queries/GetCustomerProductsByFilter/`
-
-**پیاده‌سازی**:
-- Query/Handler با Pagination
-- فیلترهای کامل:
-  - Id, Title, Description, ShortInfomation, FullInformation
-  - Price, Discount, Rate
-  - SaleCount, ViewCount, RemainingCount
-  - CategoryIds (لیست شناسه دسته‌بندی‌ها)
-- Sorting پویا با `ApplyOrder()`
-
-#### 7.3 ProductsService
-**فایل**: `CMSMicroservice.WebApi/Services/ProductsService.cs`
-
-**تغییرات**:
-- افزودن ISender به constructor
-- پیاده‌سازی 2 متد Customer
-- mapping دستی Gallery و Categories به Proto structures
-- **رفع باگ**: Proto فقط `category_id` دارد نه `category_ids`
-  - تبدیل single value به List<long>
-
----
-
-### ✅ 8. User Service (3 endpoints)
-
-#### 8.1 GetCustomerProfileQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/UserCQ/Queries/GetCustomerProfile/`
-
-**پیاده‌سازی**:
-- Query/Handler با ICurrentUserService
-- دریافت پروفایل کامل کاربر فعلی
-- محاسبه `ProfileCompletionPercentage` بر اساس 10 فیلد:
-  - FirstName, LastName, Mobile, Email, NationalCode
-  - AvatarPath, BirthDate, IsMobileVerified
-  - NetworkParentId, ReferralCode
-- محاسبه `FullName` از FirstName + LastName
-
-#### 8.2 GetCustomerReferralsQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/UserCQ/Queries/GetCustomerReferrals/`
-
-**پیاده‌سازی**:
-- Query/Handler با ICurrentUserService و Pagination
-- کوئری کاربران با `NetworkParentId == userId`
-- فیلتر بر اساس StatusFilter (ACTIVE/INACTIVE/ALL)
-- محاسبه آمار:
-  - TotalReferrals, ActiveReferrals
-  - TotalCommissionEarned از `UserWallet.NetworkBalance`
-  - ThisMonthCommission از `UserWalletChangeLog`
-- **رفع باگ**: UserWalletChangeLog بدون UserId
-  - راه حل: `.Include(x => x.Wallet).Where(x => x.Wallet.UserId == userId)`
-
-#### 8.3 GetCustomerSettingsQueryHandler (جدید)
-**فایل**: `CMSMicroservice.Application/UserCQ/Queries/GetCustomerSettings/`
-
-**پیاده‌سازی**:
-- Query/Handler ساده برای دریافت تنظیمات کاربر
-- فیلدهای موجود در User entity:
-  - EmailNotifications, SmsNotifications, PushNotifications
-- مقادیر پیش‌فرض برای فیلدهای ناموجود:
-  - MarketingNotifications = false
-  - PreferredLanguage = "fa"
-  - TimeZone = "Asia/Tehran"
-  - TwoFactorAuthEnabled = false
-
-#### 8.4 UserService
-**فایل**: `CMSMicroservice.WebApi/Services/UserService.cs`
-
-**تغییرات**:
-- افزودن ISender و Query imports
-- پیاده‌سازی 3 متد Customer با Query Handler واقعی
-- تبدیل DateTime به Timestamp با `SpecifyKind(DateTimeKind.Utc)`
-- **رفع ambiguity**: fully qualified names برای CustomerReferralStats و CustomerReferralModel
-
----
-
-## آمار پیشرفت
-
-### سرویس‌های تکمیل شده (8/8): ✅ 100%
-✅ **UserWallet** (5 endpoints)
-✅ **Commission** (2 endpoints)  
-✅ **NetworkMembership** (3 endpoints)
-✅ **Package** (3 endpoints)
-✅ **UserOrder** (3 endpoints)
-✅ **Transaction** (2 endpoints)
-✅ **Products** (2 endpoints)
-✅ **User** (3 endpoints)
-
-**جمع کل**: **25 endpoint** با الگوی ICurrentUserService پیاده‌سازی شد
-
----
-
-## نکات فنی
-
-### Entity Navigation Properties
-همیشه از `.Include()` برای load کردن navigation property‌های مورد نیاز استفاده شود:
-```csharp
-query = query.Include(x => x.Package)
-           .Include(x => x.Transaction);
-```
-
-### Pagination
-از extension method‌های `GetMetaData` و `PaginatedListAsync` استفاده شود:
-```csharp
-var metaData = await query.GetMetaData(request.PaginationState, cancellationToken);
-var items = await query.PaginatedListAsync(request.PaginationState).ToListAsync(cancellationToken);
-```
-
-### DateTime Mapping
-برای تبدیل به Protobuf Timestamp، DateTime باید UTC باشد:
-```csharp
-Timestamp.FromDateTime(DateTime.SpecifyKind(dateTime, DateTimeKind.Utc))
-```
-
-### Enum Casting
-برای نگاشت enum‌ها بین Application و Proto:
-```csharp
-Status = (PaymentStatusEnum)order.PaymentStatus
-```
-
----
-
-## Build Status
-✅ **آخرین Build موفق**: 0 Error(s), 66 Warning(s) - Time Elapsed 00:00:03.55
-
----
-
-## تاریخ آخرین به‌روزرسانی
-5 فوریه 2026
-
----
-
-## نتیجه‌گیری
-پیاده‌سازی ICurrentUserService در **25 endpoint** مربوط به **8 سرویس** با موفقیت کامل شد. 
-
-### دستاوردها:
-- ✅ **100% Coverage**: تمام endpoint‌های Customer پیاده‌سازی شدند
-- ✅ **الگوی Consistent**: pattern مشخص برای تمام سرویس‌ها
-- ✅ **امنیت بالا**: استخراج خودکار UserId از JWT
-- ✅ **قابلیت نگهداری**: کد تمیز و قابل فهم
-- ✅ **Build موفق**: بدون هیچ خطا
-
-### چالش‌های حل شده:
-- Entity‌های بدون UserId (Transaction, UserWalletChangeLog)
-- Proto/Application type ambiguity
-- MetaData بدون constructor
-- Category path building
-- Proto enum mapping
-- DateTime UTC conversion
-
-تمام تغییرات compile می‌شوند و آماده تست و deployment هستند.
-
-

cms/INVENTORY-REFACTORING-STATUS.md

@@ -1,190 +0,0 @@
-# وضعیت Refactoring سیستم انبارداری (Inventory)
-
-**تاریخ:** ۳ ژانویه ۲۰۲۶  
-**وضعیت:** ✅ تکمیل شده - Build موفق
-
----
-
-## 📊 وضعیت Build
-
-| پروژه | وضعیت |
-|-------|--------|
-| CMSMicroservice.Domain | ✅ OK |
-| CMSMicroservice.Application | ✅ OK |
-| CMSMicroservice.Infrastructure | ✅ OK |
-| CMSMicroservice.WebApi | ✅ OK |
-
----
-
-## ✅ کارهای انجام شده
-
-### 1. حذف Repository Pattern
-فایل‌های حذف شده:
-- `Application/Common/Interfaces/Repositories/IInventoryItemRepository.cs`
-- `Application/Common/Interfaces/Repositories/IStockMovementRepository.cs`
-- `Application/Common/Interfaces/Repositories/IWarehouseRepository.cs`
-- `Infrastructure/Persistence/Repositories/InventoryItemRepository.cs`
-- `Infrastructure/Persistence/Repositories/StockMovementRepository.cs`
-- `Infrastructure/Persistence/Repositories/WarehouseRepository.cs`
-
-### 2. حذف Features قدیمی
-فولدر حذف شده:
-- `Application/Features/` (کل فولدر)
-
-### 3. ایجاد ساختار CQ جدید
-
-#### WarehouseCQ/
-```
-WarehouseCQ/
-├── Commands/
-│   ├── CreateWarehouse/
-│   ├── UpdateWarehouse/
-│   ├── DeleteWarehouse/
-│   └── SetDefaultWarehouse/
-└── Queries/
-    ├── GetWarehouse/
-    ├── GetAllWarehouses/
-    └── SearchWarehouses/
-```
-
-#### InventoryItemCQ/
-```
-InventoryItemCQ/
-├── Commands/
-│   ├── CreateInventoryItem/
-│   ├── UpdateInventoryItem/
-│   ├── DeleteInventoryItem/
-│   ├── UpdateInventoryQuantity/
-│   ├── ReserveInventory/
-│   ├── ReleaseReservedInventory/
-│   ├── ReduceInventory/
-│   └── IncreaseInventory/
-└── Queries/
-    ├── GetInventoryItem/
-    ├── GetInventoryByProduct/
-    ├── GetAllInventoryItems/
-    └── GetLowStockItems/
-```
-
-#### StockMovementCQ/
-```
-StockMovementCQ/
-├── Commands/
-│   └── CreateStockMovement/
-└── Queries/
-    ├── GetStockMovements/
-    └── GetStockMovementsByInventoryItem/
-```
-
-### 4. Fix شدن InventoryProfile.cs
-- اصلاح enum names: `ProtoProductType.Unspecified` بجای `ProductTypeUnspecified`
-- حذف `new Int64Value` - Proto مستقیم `long?` میگیره
-- اصلاح expression tree برای `?.` operator
-
-### 5. ساده‌سازی InventoryService.cs
-- متدهای اصلی (Warehouse, Query ها) کامل پیاده‌سازی شدن
-- متدهای پیچیده که نیاز به lookup دارن فعلاً TODO هستن
-
----
-
-## ⚠️ متدهای TODO در InventoryService
-
-این متدها نیاز به پیاده‌سازی دارن (وقتی لازم شد):
-
-| متد | دلیل TODO |
-|-----|-----------|
-| `AddStock` | نیاز به lookup با ProductId/ProductType |
-| `AdjustStock` | نیاز به lookup با ProductId/ProductType |
-| `ReserveStock` | نیاز به lookup با ProductId/ProductType |
-| `ReleaseReservation` | نیاز به lookup با ProductId/ProductType |
-| `ConfirmSale` | نیاز به lookup با ProductId/ProductType |
-| `ProcessReturn` | نیاز به lookup با ProductId/ProductType |
-| `RecordLoss` | نیاز به lookup با ProductId/ProductType |
-| `BulkAddStock` | نیاز به loop و lookup |
-| `BulkAdjustStock` | نیاز به loop و lookup |
-| `GetInventorySummary` | نیاز به Query جدید |
-| `GetStockValueReport` | نیاز به Query جدید |
-
----
-
-## 🎯 درس‌های آموخته شده
-
-1. **همیشه اول Proto رو بررسی کن** - Proto مرجع اصلی API هست
-2. **ساختار موجود رو تحلیل کن** - قبل از ساختن فایل جدید، نمونه‌های موجود رو ببین
-3. **Mapping از Proto به Command** - نه برعکس!
-4. **IApplicationDbContext** - الگوی استاندارد این پروژه برای دسترسی به DB
-5. **بدون Repository** - این پروژه از Repository pattern استفاده نمیکنه
-6. **Proto enum names** - نام‌ها در C# متفاوت هستن (مثلاً `Unspecified` بجای `PRODUCT_TYPE_UNSPECIFIED`)
-7. **Int64Value در Proto** - در C# به `long?` تبدیل میشه، نیازی به `new Int64Value` نیست
-
----
-
-## 🔄 همگام‌سازی BFF با CMS (۳ ژانویه ۲۰۲۶)
-
-### تغییرات Proto
-BackOffice.BFF.Inventory.Protobuf با CMS همگام شد:
-
-| آیتم | قبل | بعد |
-|------|-----|-----|
-| ProductType enum | `REGULAR`, `DISCOUNT` | `REGULAR_PRODUCT`, `DISCOUNT_PRODUCT` |
-| StockMovementType | Sequential (0-9) | Grouped (10, 20, 30, 40, 50) |
-| Pagination | `page_index` | `page` |
-| Search | `search_term` | `search` |
-| Product name | `product_name` | `product_title` |
-
-### فایل‌های آپدیت شده در BFF
-
-**Commands:**
-- `AddStock` - حذف Success, Message از Response
-- `AdjustStock` - Note→Reason, +ReferenceNumber
-- `RecordLoss` - Note→Reason, +ReferenceNumber
-- `UpdateInventorySettings` - InventoryItemId→Id
-
-**Queries:**
-- `GetAllInventoryItems` - PageIndex→Page, SearchTerm→Search, +ProductPrice
-- `GetStockMovements` - PageIndex→Page, +ProductTitle, +Created
-- `GetLowStockItems` - حذف Count، استفاده از Page/PageSize
-- `GetAllWarehouses` - ActiveOnly→IsActive, +Created, +LastModified
-
-**Mappings:**
-- `InventoryProfile.cs` - بازنویسی کامل برای فیلدهای جدید
-
-### وضعیت Build BFF
-```
-Build succeeded.
-    0 Warning(s)
-    0 Error(s)
-```
-
----
-
-## 📊 پوشش API - مقایسه CMS و BFF
-
-| عملیات | CMS | BFF | یادداشت |
-|--------|-----|-----|---------|
-| GetAllInventoryItems | ✅ | ✅ | همگام |
-| GetInventoryItem | ✅ | ✅ | همگام |
-| GetLowStockItems | ✅ | ✅ | همگام |
-| GetStockMovements | ✅ | ✅ | همگام |
-| GetAllWarehouses | ✅ | ✅ | همگام |
-| AddStock | ✅ | ✅ | همگام |
-| AdjustStock | ✅ | ✅ | همگام |
-| RecordLoss | ✅ | ✅ | همگام |
-| CreateWarehouse | ✅ | ✅ | همگام |
-| UpdateWarehouse | ✅ | ❌ | نیاز به پیاده‌سازی |
-| UpdateInventorySettings | ✅ | ✅ | همگام |
-| GetInventorySummary | TODO | ❌ | اولویت بالا |
-| GetStockValueReport | TODO | ❌ | اولویت بالا |
-| ProcessReturn | TODO | ❌ | اولویت متوسط |
-
----
-
-## 📝 نتیجه‌گیری
-
-✅ **Refactoring با موفقیت تکمیل شد!**
-
-- Application layer با ساختار `*CQ/Commands/[Action]/` سازگار شد
-- Repository pattern کاملاً حذف شد
-- WebApi layer با Proto سازگار شد
-- Build همه پروژه‌ها موفق هست
-- **BFF کاملاً با CMS همگام شد (۳ ژانویه ۲۰۲۶)**

cms/PRODUCT-BUNDLE-FEATURE.md

@@ -1,303 +0,0 @@
-# 📦 Product Bundle Feature (پکیج محصولات)
-
-> **وضعیت:** ⏸️ Postponed - مستند شده برای پیاده‌سازی آینده
-> 
-> **تاریخ:** ۱۲ دی ۱۴۰۴ (1 January 2026)
-
----
-
-## 📋 خلاصه نیازمندی
-
-امکان ایجاد **پکیج محصولات** که:
-- یک محصول با نوع "پکیج" ایجاد می‌شود (همه فیلدها مثل محصول عادی)
-- این پکیج شامل **چند محصول** است
-- هنگام **خرید پکیج**، موجودی **تمام محصولات داخل** کم می‌شود
-- هنگام **مرجوعی**، موجودی تمام محصولات برمی‌گردد
-
----
-
-## 🏗️ تغییرات مورد نیاز
-
-### 1. Domain Layer
-
-#### 1.1 Enum جدید: `ProductTypeCategory`
-```csharp
-// CMSMicroservice.Domain/Enums/ProductTypeCategory.cs
-public enum ProductTypeCategory
-{
-    Simple = 1,   // محصول ساده
-    Bundle = 2    // پکیج (بسته محصولات)
-}
-```
-
-#### 1.2 فیلد جدید در `Product` Entity
-```csharp
-// Product.cs - اضافه کردن فیلد
-public ProductTypeCategory TypeCategory { get; set; } = ProductTypeCategory.Simple;
-```
-
-#### 1.3 Entity جدید: `ProductBundleItem` (جدول واسط)
-```csharp
-// CMSMicroservice.Domain/Entities/ProductBundleItem.cs
-public class ProductBundleItem : BaseAuditableEntity
-{
-    /// <summary>
-    /// شناسه محصول پکیج (والد)
-    /// </summary>
-    public long BundleProductId { get; set; }
-    public virtual Product BundleProduct { get; set; } = null!;
-    
-    /// <summary>
-    /// شناسه محصول داخل پکیج (فرزند)
-    /// </summary>
-    public long ChildProductId { get; set; }
-    public virtual Product ChildProduct { get; set; } = null!;
-    
-    /// <summary>
-    /// تعداد این محصول در پکیج
-    /// </summary>
-    public int Quantity { get; set; } = 1;
-}
-```
-
-### 2. Infrastructure Layer
-
-#### 2.1 DbContext Configuration
-```csharp
-// ApplicationDbContext.cs
-public DbSet<ProductBundleItem> ProductBundleItems => Set<ProductBundleItem>();
-
-// Configuration
-modelBuilder.Entity<ProductBundleItem>(entity =>
-{
-    entity.ToTable("ProductBundleItems", "CMS");
-    
-    entity.HasOne(x => x.BundleProduct)
-        .WithMany(p => p.BundleItems)
-        .HasForeignKey(x => x.BundleProductId)
-        .OnDelete(DeleteBehavior.Cascade);
-    
-    entity.HasOne(x => x.ChildProduct)
-        .WithMany()
-        .HasForeignKey(x => x.ChildProductId)
-        .OnDelete(DeleteBehavior.Restrict);
-    
-    // یک محصول فقط یکبار در یک پکیج
-    entity.HasIndex(x => new { x.BundleProductId, x.ChildProductId }).IsUnique();
-});
-```
-
-#### 2.2 آپدیت `InventoryService.ConfirmSaleAsync()`
-```csharp
-public async Task<bool> ConfirmSaleAsync(
-    long productId,
-    ProductType productType,
-    int quantity,
-    long? orderId = null,
-    CancellationToken ct = default)
-{
-    // چک کردن آیا محصول پکیج است
-    var product = await _dbContext.Products
-        .Include(p => p.BundleItems)
-            .ThenInclude(bi => bi.ChildProduct)
-        .FirstOrDefaultAsync(p => p.Id == productId, ct);
-    
-    if (product?.TypeCategory == ProductTypeCategory.Bundle)
-    {
-        // کم کردن موجودی تمام محصولات داخل پکیج
-        foreach (var bundleItem in product.BundleItems)
-        {
-            await ConfirmSaleForSingleProduct(
-                bundleItem.ChildProductId,
-                productType,
-                quantity * bundleItem.Quantity,  // ضرب در تعداد خرید شده
-                orderId,
-                ct);
-        }
-        return true;
-    }
-    
-    // محصول ساده - روال عادی
-    return await ConfirmSaleForSingleProduct(productId, productType, quantity, orderId, ct);
-}
-```
-
-### 3. Application Layer
-
-#### 3.1 آپدیت `CreateNewProductsCommand`
-```csharp
-public record CreateNewProductsCommand : IRequest<long>
-{
-    // ... existing fields ...
-    
-    public ProductTypeCategory TypeCategory { get; init; } = ProductTypeCategory.Simple;
-    
-    /// <summary>
-    /// لیست محصولات داخل پکیج (فقط وقتی TypeCategory == Bundle)
-    /// </summary>
-    public List<BundleItemDto>? BundleItems { get; init; }
-}
-
-public record BundleItemDto
-{
-    public long ProductId { get; init; }
-    public int Quantity { get; init; } = 1;
-}
-```
-
-#### 3.2 Repository جدید: `IProductBundleItemRepository`
-```csharp
-public interface IProductBundleItemRepository : IRepository<ProductBundleItem>
-{
-    Task<List<ProductBundleItem>> GetByBundleProductIdAsync(long bundleProductId, CancellationToken ct = default);
-    Task SetBundleItemsAsync(long bundleProductId, List<(long ProductId, int Quantity)> items, CancellationToken ct = default);
-}
-```
-
-### 4. Proto/gRPC Layer
-
-#### 4.1 آپدیت `products.proto`
-```protobuf
-enum ProductTypeCategory {
-    PRODUCT_TYPE_SIMPLE = 0;
-    PRODUCT_TYPE_BUNDLE = 1;
-}
-
-message BundleItemMessage {
-    int64 product_id = 1;
-    int32 quantity = 2;
-}
-
-message CreateNewProductsRequest {
-    // ... existing fields ...
-    ProductTypeCategory type_category = 15;
-    repeated BundleItemMessage bundle_items = 16;
-}
-
-message ProductDto {
-    // ... existing fields ...
-    ProductTypeCategory type_category = 20;
-    repeated BundleItemMessage bundle_items = 21;
-}
-```
-
----
-
-## 📊 دیاگرام رابطه‌ها
-
-```
-┌─────────────────┐
-│    Products     │
-├─────────────────┤
-│ Id              │◄──────────────────┐
-│ Title           │                   │
-│ TypeCategory    │ ← Simple/Bundle   │
-│ ...             │                   │
-└────────┬────────┘                   │
-         │                            │
-         │ 1:N (Bundle → Items)       │
-         ▼                            │
-┌─────────────────────┐               │
-│  ProductBundleItems │               │
-├─────────────────────┤               │
-│ Id                  │               │
-│ BundleProductId (FK)│───────────────┘
-│ ChildProductId (FK) │───────────────┐
-│ Quantity            │               │
-└─────────────────────┘               │
-                                      │
-         ┌────────────────────────────┘
-         ▼
-┌─────────────────┐
-│    Products     │
-│  (Child Item)   │
-└─────────────────┘
-```
-
----
-
-## 🔄 Flow خرید پکیج
-
-```
-1. کاربر پکیج را به سبد اضافه می‌کند
-   └── CartItem { ProductId: 100, Count: 2 }  // پکیج شامل 3 محصول
-
-2. سفارش ثبت می‌شود
-   └── PlaceOrderCommandHandler.ReserveStock()
-       ├── Check: Product.TypeCategory == Bundle
-       ├── Get: BundleItems = [
-       │     { ChildProductId: 10, Quantity: 1 },
-       │     { ChildProductId: 20, Quantity: 2 },
-       │     { ChildProductId: 30, Quantity: 1 }
-       │   ]
-       └── Reserve:
-           ├── Product 10: Reserve 2×1 = 2 عدد
-           ├── Product 20: Reserve 2×2 = 4 عدد
-           └── Product 30: Reserve 2×1 = 2 عدد
-
-3. پرداخت موفق
-   └── ConfirmSaleAsync()
-       ├── Product 10: -2 از موجودی
-       ├── Product 20: -4 از موجودی
-       └── Product 30: -2 از موجودی
-
-4. مرجوعی (در صورت نیاز)
-   └── ProcessReturnAsync()
-       ├── Product 10: +2 به موجودی
-       ├── Product 20: +4 به موجودی
-       └── Product 30: +2 به موجودی
-```
-
----
-
-## ⚠️ محدودیت‌ها و قوانین
-
-1. **محصول پکیج خودش موجودی ندارد** - فقط موجودی محصولات داخلش مهم است
-2. **پکیج داخل پکیج ممنوع** - فقط محصولات ساده (`Simple`) می‌توانند داخل پکیج باشند
-3. **حذف محصول از پکیج** - اگر محصولی در پکیج استفاده شده، نمی‌تواند حذف شود
-4. **موجودی قابل فروش پکیج** = `MIN(موجودی هر محصول داخل / تعداد آن در پکیج)`
-
----
-
-## 📁 فایل‌های جدید/تغییریافته
-
-### فایل‌های جدید:
-- `CMSMicroservice.Domain/Enums/ProductTypeCategory.cs`
-- `CMSMicroservice.Domain/Entities/ProductBundleItem.cs`
-- `CMSMicroservice.Application/Features/ProductBundleItems/*`
-- `CMSMicroservice.Infrastructure/Repositories/ProductBundleItemRepository.cs`
-
-### فایل‌های تغییریافته:
-- `CMSMicroservice.Domain/Entities/Product.cs` - اضافه کردن `TypeCategory` و `BundleItems`
-- `CMSMicroservice.Infrastructure/Persistence/ApplicationDbContext.cs` - DbSet و Configuration
-- `CMSMicroservice.Infrastructure/Services/InventoryService.cs` - منطق پکیج
-- `CMSMicroservice.Application/ProductsCQ/Commands/CreateNewProducts/*`
-- `CMSMicroservice.Protobuf/Protos/products.proto`
-- Order Handlers (Reserve, Confirm, Release)
-
----
-
-## ⏱️ تخمین زمان
-
-| تسک | زمان تخمینی |
-|-----|-------------|
-| Domain entities & enums | 30 دقیقه |
-| EF Migration | 15 دقیقه |
-| Repository | 30 دقیقه |
-| InventoryService update | 1 ساعت |
-| CQRS handlers | 1 ساعت |
-| Proto & gRPC | 45 دقیقه |
-| تست و دیباگ | 1 ساعت |
-| **جمع** | **~5 ساعت** |
-
----
-
-## 📝 یادداشت‌ها
-
-- این فیچر با پکیج عضویت (`Package` entity موجود) متفاوت است
-- نیاز به تست دقیق منطق انبارداری دارد
-- UI نیاز به multi-select برای انتخاب محصولات داخل پکیج دارد
-
----
-
-*این داکیومنت برای پیاده‌سازی آینده نگهداری می‌شود.*

cms/REGISTRATION-FLOW-FIXES.md

@@ -1,187 +0,0 @@
-# 🔐 فیکس فلوی ثبت‌نام / ورود FrontOffice
-
-**تاریخ:** بهمن ۱۴۰۴ (February 2026)
-
----
-
-## 📋 خلاصه
-
-بررسی کامل فلوی ثبت‌نام و ورود FrontOffice از UI تا دیتابیس انجام شد. **۳ باگ بحرانی** شناسایی و رفع شده:
-
-| # | شدت | مشکل | فایل |
-|---|------|-------|------|
-| 1 | 🔴 بحرانی | کاربران جدید ثبت‌نام نمی‌شوند | `UserCQ/VerifyOtpToken/VerifyOtpTokenCommandHandler.cs` |
-| 2 | 🔴 بحرانی | امضای قرارداد همیشه شکست می‌خورد | `UserCQ/AcceptContract/AcceptContractCommandHandler.cs` |
-| 3 | 🟡 متوسط | منوی کناری وضعیت نادرست نشان می‌دهد | `FrontOffice.Main/Utilities/AuthService.cs` |
-
----
-
-## 🔴 باگ ۱ — کاربران جدید ثبت‌نام نمی‌شوند
-
-### مشکل
-
-FrontOffice از `UserContract.UserContractClient` (user.proto) استفاده می‌کند → `UserCQ/VerifyOtpTokenCommandHandler`. این handler وقتی کاربر یافت نمی‌شد فقط خطای **«کاربر یافت نشد»** برمی‌گرداند و کاربر جدید ایجاد **نمی‌کرد**.
-
-لاجیک ایجاد کاربر (شامل: اعتبارسنجی کد معرف، درخت باینری، موقعیت شاخه) در `OtpTokenCQ/VerifyOtpTokenCommandHandler` بود — سرویسی که FrontOffice اصلاً از آن استفاده نمی‌کند.
-
-### رفع
-
-اضافه شدن لاجیک کامل ایجاد کاربر جدید به `UserCQ/VerifyOtpTokenCommandHandler`:
-
-```
-if (user == null)
-{
-    // ۱. اعتبارسنجی کد معرف (ParentReferralCode) — الزامی
-    // ۲. بررسی وجود معرف و فعال بودن عضویت باشگاه
-    // ۳. بررسی ظرفیت (حداکثر ۲ زیرمجموعه مستقیم)
-    // ۴. تعیین شاخه (چپ اول، بعد راست)
-    // ۵. ایجاد User + UserRole + UserWallet
-    // ۶. رویدادهای دامنه: CreateNewUserEvent, CreateNewUserRoleEvent, CreateNewUserWalletEvent
-    // ۷. بارگذاری مجدد کاربر با روابط کامل
-    // ۸. تولید JWT token
-}
-```
-
-### اعتبارسنجی‌ها
-
-| مرحله | شرط | پیام خطا |
-|-------|------|---------|
-| کد معرف | خالی یا null | «کد معرف الزامی است» |
-| معرف | وجود نداشته باشد | «معرف وجود ندارد» |
-| عضویت باشگاه | غیرفعال باشد | «لینک دعوت معرف فعال نیست» |
-| ظرفیت | بیش از ۱ فرزند | «ظرفیت معرف تکمیل است» |
-| شاخه | هر دو پُر باشند | «ظرفیت معرف تکمیل است» |
-
-### فایل
-
-`CMS/src/CMSMicroservice.Application/UserCQ/Commands/VerifyOtpToken/VerifyOtpTokenCommandHandler.cs`
-
----
-
-## 🔴 باگ ۲ — امضای قرارداد همیشه شکست می‌خورد
-
-### مشکل
-
-`AcceptContractCommandHandler` از `_currentUserService.Username` برای پیدا کردن OTP و کاربر بر اساس شماره موبایل استفاده می‌کرد:
-
-```csharp
-// ❌ قبل — Username = "{FirstName} {LastName}" نه شماره موبایل!
-var otpToken = await _context.OtpTokens
-    .Where(x => x.Mobile == _currentUserService.Username ...)
-var user = await _context.Users
-    .Where(x => x.Mobile == _currentUserService.Username ...)
-```
-
-**`CurrentUserService.Username`** مقدار `ClaimTypes.Name` را برمی‌گرداند که در JWT به صورت `"{FirstName} {LastName}"` ذخیره شده — **نه شماره موبایل!**
-
-### رفع
-
-اول کاربر بر اساس `UserId` (از `ClaimTypes.NameIdentifier`) پیدا شود، سپس از `user.Mobile` برای جستجوی OTP استفاده شود:
-
-```csharp
-// ✅ بعد — ابتدا کاربر از UserId پیدا شود
-var userId = long.Parse(_currentUserService.UserId);
-var user = await _context.Users
-    .Where(x => x.Id == userId)...
-
-var otpToken = await _context.OtpTokens
-    .Where(x => x.Mobile == user.Mobile ...)
-```
-
-### فایل
-
-`CMS/src/CMSMicroservice.Application/UserCQ/Commands/AcceptContract/AcceptContractCommandHandler.cs`
-
----
-
-## 🟡 باگ ۳ — `IsCompleteRegister()` داده قدیمی می‌خواند
-
-### مشکل
-
-متد sync در `AuthService`:
-
-```csharp
-// ❌ قبل — GetAwaiter() بدون GetResult() عملیات async را اجرا نمی‌کند
-InitUserAuthInfo().GetAwaiter();
-```
-
-`GetAwaiter()` فقط یک شیء awaiter برمی‌گرداند ولی عملیات را اجرا **نمی‌کند**. در نتیجه `_userAuthInfo` مقداردهی نمی‌شود و منوی کناری (`MainLayout.razor`) وضعیت نادرست نشان می‌دهد.
-
-### رفع
-
-```csharp
-// ✅ بعد — عملیات async را همگام اجرا می‌کند
-InitUserAuthInfo().GetAwaiter().GetResult();
-```
-
-### محل استفاده
-
-`MainLayout.razor` خطوط ۱۰۶ و ۱۰۹:
-```razor
-Disabled="@(!AuthService.IsCompleteRegister())"
-```
-
-### فایل
-
-`FrontOffice/src/FrontOffice.Main/Utilities/AuthService.cs`
-
----
-
-## 🏗️ معماری فلوی ثبت‌نام (بعد از فیکس)
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    FrontOffice (Blazor WASM)                 │
-│                                                             │
-│  LoginPage → SendOtp → VerifyOtp(mobile, code, referral)   │
-│      ↓ gRPC-Web                                            │
-├─────────────────────────────────────────────────────────────┤
-│                CMS Backend (gRPC)                           │
-│                                                             │
-│  UserContract.VerifyOtpToken                                │
-│      ↓                                                      │
-│  UserCQ/VerifyOtpTokenCommandHandler                        │
-│      │                                                      │
-│      ├── OTP صحیح؟ → ❌ خطا                                │
-│      │                                                      │
-│      ├── کاربر موجود؟ → ✅ تولید JWT Token                 │
-│      │                                                      │
-│      └── کاربر جدید؟                                       │
-│           ├── اعتبارسنجی کد معرف                           │
-│           ├── بررسی ظرفیت درخت باینری                      │
-│           ├── ایجاد User + UserRole + UserWallet            │
-│           ├── رویدادهای دامنه                              │
-│           └── تولید JWT Token                               │
-│                                                             │
-│  بعد از ثبت‌نام → RegisterWizard:                          │
-│    Step 1: اطلاعات شخصی                                    │
-│    Step 2: امضای قرارداد (AcceptContract + OTP)             │
-│    Step 3: خرید پکیج                                       │
-├─────────────────────────────────────────────────────────────┤
-│                     Database                                │
-│                                                             │
-│  Users ─── UserRoles ─── UserWallets                        │
-│    └── NetworkParentId, LegPosition (Binary Tree)           │
-│    └── UserContracts, ClubMembership                        │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 📝 فایل‌های تغییر یافته
-
-| فایل | تغییر |
-|------|-------|
-| `CMS/.../UserCQ/Commands/VerifyOtpToken/VerifyOtpTokenCommandHandler.cs` | اضافه شدن لاجیک ایجاد کاربر جدید (86→165 خط) |
-| `CMS/.../UserCQ/Commands/AcceptContract/AcceptContractCommandHandler.cs` | تغییر lookup از Username به UserId |
-| `FrontOffice/.../Utilities/AuthService.cs` | اضافه شدن `.GetResult()` به `GetAwaiter()` |
-
----
-
-## ✅ بیلد
-
-```
-CMS:         0 Error(s)  ✅
-FrontOffice: 0 Error(s)  ✅
-BackOffice:  0 Error(s)  ✅
-```

cms/REMAINING-TASKS.md

@@ -1,158 +0,0 @@
-# کارهای باقیمانده - CMS Microservice
-
-> آخرین بروزرسانی: February 10, 2026  
-> Build Status: ✅ SUCCESS (0 Errors)
-
----
-
-## 📊 خلاصه وضعیت
-
-| دسته | تعداد | وضعیت |
-|------|--------|--------|
-| ~~متدهای Unimplemented~~ | ~~30~~ → **0** | ✅ همه انجام شد |
-| ~~متدهای Mock/جعلی~~ | ~~13~~ → **0** | ✅ همه انجام شد |
-| ~~گزارش‌های TODO (صفر برمی‌گردونه)~~ | ~~2~~ → **0** | ✅ هر دو پیاده شد |
-| ~~فایل تنظیمات اشتباه (Staging)~~ | ~~1~~ → **0** | ✅ فیکس شد |
-| ~~Entity‌های تکراری مُرده~~ | ~~3~~ → **0** | ✅ حذف شد |
-| **مجموع باقیمانده** | **0** | ✅ 🎉 |
-
----
-
-## ✅ کارهای انجام‌شده
-
-### فاز ۱ — فیکس‌های فوری ✅
-- [x] اصلاح `appsettings.Staging.json` — URL از `backoffice-bff` به `cms` تغییر کرد
-- [x] حذف `Products.cs`, `ProductImages.cs`, `ProductGalleries.cs` (Entity‌های تکراری)
-- [x] اصلاح `nameof(Products)` → `nameof(Product)` در `GetCustomerProductsQueryHandler`
-
-### فاز ۲ — ProductsService ✅ (8 متد)
-- [x] `BulkUpdateProductPrices` — بروزرسانی قیمت/تخفیف/تخفیف باشگاه
-- [x] `BulkUpdateProductStock` — بروزرسانی موجودی (SET/ADD/SUBTRACT)
-- [x] `GetLowStockProducts` — محصولات کم‌موجودی با صفحه‌بندی
-- [x] `ToggleProductStatus` — فعال/غیرفعال محصول
-- [x] `GetProductsForCategory` — DragDrop: محصولات برای دسته‌بندی
-- [x] `GetCategories` — DragDrop: دسته‌بندی‌ها برای محصول
-- [x] `UpdateProductCategories` — DragDrop: بروزرسانی دسته‌بندی‌های محصول
-- [x] `UpdateCategoryProducts` — DragDrop: بروزرسانی محصولات دسته‌بندی
-
-### فاز ۳ — CityService ✅ (6 متد) + CategoryService ✅ (1 متد)
-- [x] `GetCitiesForCustomer` — لیست شهرها با فیلتر و صفحه‌بندی
-- [x] `GetCityByIdForCustomer` — شهر با ID
-- [x] `GetCitiesByStateForCustomer` — شهرهای استان
-- [x] `CreateCity` — ایجاد شهر
-- [x] `UpdateCity` — بروزرسانی شهر
-- [x] `DeleteCity` — حذف نرم شهر
-- [x] `GetCategoryByIdForCustomer` — دسته‌بندی با ID
-
-### فاز ۴ — UserCartsService ✅ (5 متد)
-- [x] `AddNewUserCart` — افزودن به سبد خرید
-- [x] `UpdateUserCart` — بروزرسانی تعداد
-- [x] `DeleteUserCart` — حذف نرم
-- [x] `GetUserCart` — دریافت آیتم سبد
-- [x] `GetAllUserCartsByFilter` — لیست سبد خرید با فیلتر و صفحه‌بندی
-
-### فاز ۵ — InventoryService ✅ (7 متد)
-- [x] `ReserveStock` — رزرو موجودی
-- [x] `ReleaseReservation` — آزادسازی رزرو
-- [x] `ConfirmSale` — تأیید فروش
-- [x] `ProcessReturn` — پردازش مرجوعی
-- [x] `BulkAddStock` — افزودن موجودی انبوه
-- [x] `GetInventorySummary` — خلاصه انبارداری (واقعی با DB)
-- [x] `GetStockValueReport` — گزارش ارزش موجودی (واقعی با DB)
-
-### فاز ۶ — UserOrderService ✅ (8 Unimplemented + 3 Mock)
-- [x] `CreateNewUserOrder` — ایجاد سفارش
-- [x] `UpdateUserOrder` — بروزرسانی سفارش
-- [x] `DeleteUserOrder` — حذف نرم
-- [x] `CancelOrder` — لغو سفارش (ادمین)
-- [x] `UpdateOrderStatus` — بروزرسانی وضعیت
-- [x] `GetOrdersByDateRange` — سفارشات بازه زمانی
-- [x] `ApplyDiscountToOrder` — اعمال تخفیف
-- [x] `CalculateOrderPV` — محاسبه PV
-- [x] `CustomerCancelOrder` — لغو سفارش مشتری (با ریفاند کیف پول)
-- [x] `CustomerTrackOrder` — پیگیری سفارش واقعی
-- [x] `CustomerReorderPreviousOrder` — سفارش مجدد واقعی
-
-### فاز ۷ — ConfigurationService ✅ (2 متد)
-- [x] `CreateOrUpdateConfiguration` → `FailedPrecondition` (عمداً read-only)
-- [x] `DeactivateConfiguration` → `FailedPrecondition` (عمداً read-only)
-
-### فاز ۸ — UserService ✅ (5 متد Mock → واقعی)
-- [x] `GetCustomerUser` — خواندن از DB با `_context.Users` + JWT userId
-- [x] `UpdateCustomerProfile` — بروزرسانی FirstName/LastName/Email/NationalCode/BirthDate
-- [x] `ChangeCustomerPassword` — PBKDF2 verify + hash با `IHashService`
-- [x] `UploadCustomerAvatar` — ارسال به FMS با `IFileManagementService` + ذخیره URL
-- [x] `UpdateCustomerSettings` — بروزرسانی EmailNotifications/SmsNotifications/PushNotifications
-
-### فاز ۹ — TransactionsService ✅ (2 متد Mock → واقعی)
-- [x] `CustomerPaymentRequest` — ایجاد Transaction + `IPaymentGatewayService.InitiatePaymentAsync`
-- [x] `CustomerPaymentVerification` — `IPaymentGatewayService.VerifyPaymentAsync` + آپدیت Transaction
-
-### فاز ۱۰ — PackageService ✅ (2 متد Mock → واقعی)
-- [x] `CustomerPurchasePackage` — ایجاد Transaction + UserPackagePurchase + payment initiate
-- [x] `CustomerVerifyPackagePurchase` — verify payment + آپدیت Transaction و Purchase
-
-### فاز ۱۱ — UserWalletService ✅ (1 متد Mock → واقعی)
-- [x] `CustomerWithdrawBalance` — آپدیت UserCommissionPayout با WithdrawalMethod/IbanNumber + Status=WithdrawRequested
-
----
-
-## ✅ همه ۴۹ آیتم تکمیل شد! 🎉
-
-> هیچ Mock یا Unimplemented متدی باقی نمانده.
-
----
-
-## 📝 نکات فنی مهم
-
-### سایر آیتم‌ها (غیر‌بحرانی)
-- `Infrastructure/Services/InventoryService.cs:L546` — یک `TODO: Implement rollback logic` (در لایه Infrastructure، نه WebApi)
-- `Infrastructure/Services/DayaLoanApiService.cs` — `MockDayaLoanApiService` (سرویس شبیه‌سازی API دایا — عمدی برای تست)
-
-### الگوهای فنی استفاده‌شده
-- **oneof در protobuf**: باید از `request.HasPaymentStatus` استفاده بشه (نه `request.PaymentStatusItem != null`)
-- **StringValue wrapper**: در C# مستقیم `string` هست (بدون `.Value`)
-- **Int64Value wrapper**: در C# `long?` هست (`.Value` برای unwrap)
-- **DeliveryStatus**: در proto فقط ۵ مقدار (None تا Returned)، در Domain ۶ مقدار (+ Cancelled)
-- **ProductType**: در C# protobuf `ProductType.Unspecified` هست (نه `ProductTypeUnspecified`)
-- **ICurrentUserService.UserId**: `string?` — همیشه با `long.TryParse` تبدیل بشه
-- **IPaymentGatewayService**: ثبت‌شده در DI (`DayaPaymentService` واقعی / `MockPaymentGatewayService` تست)
-- **IHashService**: PBKDF2 — `HashPassword()` / `VerifyPassword()`
-- **IFileManagementService**: FMS gRPC — `UploadFileAsync(dir, bytes, mime, name, ct)`
-
----
-
-## 📋 ترتیب انجام کارها (تکمیل‌شده)
-
-- [x] فاز ۱ — فیکس‌های فوری (Staging URL, Dead Entities)
-- [x] فاز ۲ — ProductsService (8 متد)
-- [x] فاز ۳ — CityService (6 متد) + CategoryService (1 متد)
-- [x] فاز ۴ — UserCartsService (5 متد)
-- [x] فاز ۵ — InventoryService (7 متد)
-- [x] فاز ۶ — UserOrderService (8 Unimplemented + 3 Mock)
-- [x] فاز ۷ — ConfigurationService (2 متد)
-- [x] فاز ۸ — UserService (5 Mock → واقعی)
-- [x] فاز ۹ — TransactionsService (2 Mock → واقعی)
-- [x] فاز ۱۰ — PackageService (2 Mock → واقعی)
-- [x] فاز ۱۱ — UserWalletService (1 Mock → واقعی)
-
----
-
-## ✅ تاریخچه انجام کارها
-
-| تاریخ | کار | وضعیت |
-|-------|------|--------|
-| Dec 2025 | مهاجرت ۲۰/۲۰ سرویس BackOffice BFF→CMS | ✅ |
-| Jan 2026 | فعال‌سازی ماژول‌های DiscountShop | ✅ |
-| Feb 2026 | یکپارچه‌سازی FMS (آپلود فایل با ImageSharp) | ✅ |
-| Feb 2026 | رفع باگ OTP SMS (Kavenegar) | ✅ |
-| Feb 2026 | رفع باگ BCrypt Invalid Salt Version | ✅ |
-| Feb 2026 | شناسایی مشکل Token/Roles (`_Imports.razor`) | ✅ |
-| Feb 2026 | پیاده‌سازی ۳۰ متد Unimplemented | ✅ |
-| Feb 2026 | جایگزینی ۳ متد Mock (UserOrder مشتری) | ✅ |
-| Feb 2026 | فیکس Staging URL, Dead Entities, Build Errors | ✅ |
-| Feb 2026 | جایگزینی ۵ متد Mock (UserService) — DB+JWT+FMS+Hash | ✅ |
-| Feb 2026 | جایگزینی ۲ متد Mock (TransactionsService) — PaymentGateway | ✅ |
-| Feb 2026 | جایگزینی ۲ متد Mock (PackageService) — Purchase+Verify | ✅ |
-| Feb 2026 | جایگزینی ۱ متد Mock (UserWalletService) — Withdraw | ✅ |
-| Feb 2026 | **همه ۴۹/۴۹ آیتم تکمیل — Build بدون خطا** | ✅ 🎉 |

cms/chatika-integration.md

@@ -1,424 +0,0 @@
-# 🤖 Chatika Integration Guide
-
-> **آخرین بروزرسانی**: ۳ دی ۱۴۰۴ (23 December 2025)  
-> **وضعیت**: ✅ Production Ready
-
----
-
-## 📋 فهرست
-
-1. [معرفی](#معرفی)
-2. [معماری](#معماری)
-3. [API چتیکا](#api-چتیکا)
-4. [پیاده‌سازی](#پیاده‌سازی)
-5. [تنظیمات](#تنظیمات)
-6. [نحوه کار Worker](#نحوه-کار-worker)
-7. [Troubleshooting](#troubleshooting)
-
----
-
-## معرفی
-
-چتیکا یک سرویس هوش مصنوعی است که به عنوان اولین فیچر باشگاه مشتریان به کاربران ارائه می‌شود. هنگام فعال‌سازی باشگاه، به صورت خودکار یک حساب در چتیکا برای کاربر ایجاد می‌شود.
-
-### ویژگی‌ها:
-- ✅ فعال‌سازی خودکار حساب
-- ✅ جلوگیری از ثبت تکراری
-- ✅ Retry با Exponential Backoff
-- ✅ Logging کامل
-
----
-
-## معماری
-
-```
-┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
-│   User Activates │───▶│  ClubMembership  │───▶│ UserClubFeature │
-│   Club Package   │    │  (IsActive=true) │    │  (Chatika, Id=1)│
-└─────────────────┘    └──────────────────┘    │  Notes = NULL   │
-                                                └────────┬────────┘
-                                                         │
-                                                         ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                    Hangfire Scheduler                            │
-│                   Cron: */5 * * * * (Every 5 minutes)            │
-└─────────────────────────────┬───────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│               ChatikaAccountActivationJob                        │
-│                                                                  │
-│  Query: SELECT * FROM UserClubFeatures                           │
-│         WHERE ClubFeatureId = 1 (Chatika)                        │
-│         AND ClubMembership.IsActive = true                       │
-│         AND Notes IS NULL                                        │
-└─────────────────────────────┬───────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                    ChatikaApiService                             │
-│  POST https://api.chatika.ir/api/v1/organizations/register-user  │
-│  Header: X-API-Key: {ApiKey}                                     │
-│  Body: { "mobile_number": "09123456789" }                        │
-└─────────────────────────────┬───────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                    Update UserClubFeature                        │
-│  Notes = "🎉 تبریک! حساب هوش مصنوعی چتیکا شما فعال شد..."        │
-│  IsActive = true                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## API چتیکا
-
-### Endpoint
-
-```
-POST /api/v1/organizations/register-user
-```
-
-### Headers
-
-| Header | Value |
-|--------|-------|
-| `X-API-Key` | Organization API Key |
-| `Content-Type` | `application/json` |
-
-### Request Body
-
-```json
-{
-    "mobile_number": "09123456789"
-}
-```
-
-### Success Response (200 OK)
-
-```json
-{
-    "id": 1,
-    "mobile_number": "09123456789",
-    "organization_id": 1,
-    "organization_title": "FourSat",
-    "wallet_balance": 100.0,
-    "is_new_user": true,
-    "credit_charged": 100.0
-}
-```
-
-### Error Responses
-
-| Status | Error Code | Description |
-|--------|-----------|-------------|
-| 401 | `INVALID_API_KEY` | API Key نامعتبر |
-| 403 | `ORGANIZATION_DISABLED` | سازمان غیرفعال شده |
-| 403 | `ORGANIZATION_EXPIRED` | سازمان منقضی شده |
-| 400 | `INVALID_MOBILE_FORMAT` | فرمت شماره موبایل نامعتبر |
-
----
-
-## پیاده‌سازی
-
-### 1. Interface
-
-**فایل**: `CMSMicroservice.Application/Common/Interfaces/IChatikaApiService.cs`
-
-```csharp
-public interface IChatikaApiService
-{
-    Task<ChatikaAccountResult> CreateAccountAsync(
-        string mobileNumber, 
-        string fullName,
-        CancellationToken cancellationToken = default);
-}
-
-public class ChatikaAccountResult
-{
-    public bool IsSuccess { get; set; }
-    public string? ErrorMessage { get; set; }
-    public string? ChatikaUserId { get; set; }
-    public string? AccessUrl { get; set; }
-    
-    public static ChatikaAccountResult Success(...) => ...;
-    public static ChatikaAccountResult Failure(string error) => ...;
-}
-```
-
-### 2. Service Implementation
-
-**فایل**: `CMSMicroservice.Infrastructure/Services/ChatikaApiService.cs`
-
-```csharp
-public class ChatikaApiService : IChatikaApiService
-{
-    private readonly HttpClient _httpClient;
-    private readonly ILogger<ChatikaApiService> _logger;
-
-    public async Task<ChatikaAccountResult> CreateAccountAsync(
-        string mobileNumber, 
-        string fullName,
-        CancellationToken cancellationToken = default)
-    {
-        var request = new { mobile_number = mobileNumber };
-        
-        var response = await _httpClient.PostAsJsonAsync(
-            "/api/v1/organizations/register-user", 
-            request, 
-            cancellationToken);
-
-        if (response.IsSuccessStatusCode)
-        {
-            var result = await response.Content.ReadFromJsonAsync<ChatikaRegisterResponse>();
-            return ChatikaAccountResult.Success(result?.Id.ToString(), "https://chatika.ir");
-        }
-        
-        return ChatikaAccountResult.Failure($"Error: {response.StatusCode}");
-    }
-}
-```
-
-### 3. Background Job
-
-**فایل**: `CMSMicroservice.Infrastructure/BackgroundJobs/ChatikaAccountActivationJob.cs`
-
-```csharp
-public class ChatikaAccountActivationJob
-{
-    private const string ChatikaFeatureDescription = 
-        "🎉 تبریک! حساب هوش مصنوعی چتیکا شما فعال شد.\n\n" +
-        "برای استفاده از امکانات رایگان چتیکا:\n" +
-        "1️⃣ به وب‌سایت chatika.ir مراجعه کنید\n" +
-        "2️⃣ شماره موبایل خود را وارد کنید\n" +
-        "3️⃣ از دستیار هوشمند چتیکا لذت ببرید!\n\n" +
-        "🔗 لینک ورود: https://chatika.ir";
-
-    public async Task ExecuteAsync(CancellationToken cancellationToken = default)
-    {
-        // 1. پیدا کردن کاربران در انتظار
-        var pendingUsers = await _context.UserClubFeatures
-            .Include(ucf => ucf.User)
-            .Include(ucf => ucf.ClubMembership)
-            .Where(ucf => 
-                ucf.ClubFeatureId == (long)ClubFeatureType.Chatika &&
-                ucf.ClubMembership.IsActive &&
-                !ucf.IsDeleted &&
-                ucf.IsActive &&
-                (ucf.Notes == null || ucf.Notes == ""))
-            .ToListAsync(cancellationToken);
-
-        // 2. پردازش هر کاربر
-        foreach (var userFeature in pendingUsers)
-        {
-            var user = userFeature.User;
-            var fullName = $"{user.FirstName} {user.LastName}".Trim();
-            
-            // 3. کال API با Retry
-            var result = await _retryPipeline.ExecuteAsync(
-                async ct => await _chatikaApiService.CreateAccountAsync(
-                    user.Mobile, fullName, ct),
-                cancellationToken);
-
-            // 4. آپدیت فیچر
-            if (result.IsSuccess)
-            {
-                userFeature.Notes = ChatikaFeatureDescription;
-                userFeature.IsActive = true;
-                await _context.SaveChangesAsync(cancellationToken);
-            }
-        }
-    }
-}
-```
-
----
-
-## تنظیمات
-
-### appsettings.json
-
-```json
-{
-  "Chatika": {
-    "BaseUrl": "https://api.chatika.ir",
-    "ApiKey": "YOUR_ORGANIZATION_API_KEY"
-  }
-}
-```
-
-### DI Registration
-
-**فایل**: `ConfigureServices.cs`
-
-```csharp
-// Chatika API Service
-services.AddHttpClient<IChatikaApiService, ChatikaApiService>()
-    .SetHandlerLifetime(TimeSpan.FromMinutes(5))
-    .ConfigureHttpClient((sp, client) =>
-    {
-        client.Timeout = TimeSpan.FromSeconds(30);
-    });
-
-// Background Job
-services.AddScoped<ChatikaAccountActivationJob>();
-```
-
-### Hangfire Registration
-
-**فایل**: `Program.cs`
-
-```csharp
-// Chatika Account Activation: Every 5 minutes
-recurringJobManager.AddOrUpdate<ChatikaAccountActivationJob>(
-    recurringJobId: "chatika-account-activation",
-    methodCall: job => job.ExecuteAsync(CancellationToken.None),
-    cronExpression: "*/5 * * * *",
-    options: new RecurringJobOptions { TimeZone = TimeZoneInfo.Utc });
-```
-
----
-
-## نحوه کار Worker
-
-### Flowchart
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│                    START (Every 5 min)                        │
-└──────────────────────────┬───────────────────────────────────┘
-                           │
-                           ▼
-┌──────────────────────────────────────────────────────────────┐
-│  Query: Users with Chatika feature & Notes = NULL             │
-└──────────────────────────┬───────────────────────────────────┘
-                           │
-                           ▼
-                    ┌─────────────┐
-                    │ Any Users?  │
-                    └──────┬──────┘
-                           │
-              ┌────────────┴────────────┐
-              │ NO                      │ YES
-              ▼                         ▼
-        ┌──────────┐            ┌───────────────┐
-        │   END    │            │ For each user │
-        └──────────┘            └───────┬───────┘
-                                        │
-                                        ▼
-                               ┌────────────────────┐
-                               │ Call Chatika API   │
-                               │ (with 3x Retry)    │
-                               └────────┬───────────┘
-                                        │
-                              ┌─────────┴─────────┐
-                              │ SUCCESS           │ FAILURE
-                              ▼                   ▼
-                      ┌───────────────┐   ┌───────────────┐
-                      │ Update Notes  │   │ Log Warning   │
-                      │ IsActive=true │   │ Continue      │
-                      └───────────────┘   └───────────────┘
-                                        │
-                                        ▼
-                               ┌────────────────┐
-                               │  Next User     │
-                               └────────────────┘
-```
-
-### Retry Policy
-
-```csharp
-// Polly Retry: 3 attempts with exponential backoff
-_retryPipeline = new ResiliencePipelineBuilder()
-    .AddRetry(new RetryStrategyOptions
-    {
-        MaxRetryAttempts = 3,
-        Delay = TimeSpan.FromSeconds(30),
-        BackoffType = DelayBackoffType.Exponential,
-        UseJitter = true
-    })
-    .Build();
-```
-
-**Retry Timeline:**
-- Attempt 1: Immediate
-- Attempt 2: ~30 seconds later
-- Attempt 3: ~60 seconds later
-
----
-
-## Troubleshooting
-
-### 1. API Key Invalid
-
-**خطا**: `INVALID_API_KEY`
-
-**راه‌حل**:
-1. بررسی `appsettings.json`
-2. تأیید API Key در داشبورد چتیکا
-3. چک کردن header name: باید `X-API-Key` باشد
-
-### 2. Users Not Being Processed
-
-**علت احتمالی**:
-1. `ClubMembership.IsActive = false`
-2. `UserClubFeature.Notes` قبلاً پر شده
-3. `ClubFeatureId != 1`
-
-**Debug Query**:
-```sql
-SELECT ucf.*, u.Mobile, cm.IsActive
-FROM UserClubFeatures ucf
-JOIN Users u ON ucf.UserId = u.Id
-JOIN ClubMemberships cm ON ucf.ClubMembershipId = cm.Id
-WHERE ucf.ClubFeatureId = 1
-  AND ucf.IsDeleted = 0
-  AND (ucf.Notes IS NULL OR ucf.Notes = '')
-```
-
-### 3. Hangfire Job Not Running
-
-**راه‌حل**:
-1. چک کردن Hangfire Dashboard: `/hangfire`
-2. بررسی لاگ‌ها در Seq
-3. تأیید ثبت Job در `Program.cs`
-
-### 4. Network Timeout
-
-**علت**: سرور چتیکا در دسترس نیست
-
-**راه‌حل**:
-- Retry Policy خودکار 3 بار تلاش می‌کند
-- بررسی لاگ‌ها برای خطای دقیق
-- تماس با پشتیبانی چتیکا
-
----
-
-## 📊 Monitoring
-
-### Logs to Watch
-
-```
-🚀 Starting Chatika account activation job
-📋 Found {Count} users pending Chatika activation
-🤖 Creating Chatika account for mobile: 0912***
-✅ Chatika account activated for user {UserId}
-⚠️ Failed to create Chatika account for user {UserId}: {Error}
-❌ Network error calling Chatika API
-🏁 Chatika activation job completed. Success: {X}, Failed: {Y}
-```
-
-### Seq Query
-
-```
-ApplicationName = "CMSMicroservice" AND Message LIKE "%Chatika%"
-```
-
----
-
-## 📚 مستندات مرتبط
-
-- [Club Features System](./club-features-system.md)
-- [Hangfire Jobs Guide](./hangfire-jobs.md)
-- [Commission System](./commission-system.md)

cms/club-feature-management-services.md

@@ -1,490 +0,0 @@
-# Club Feature Management Services - Implementation Guide
-
-## Overview
-Admin services for managing user club features (enable/disable features per user).
-
-## Created Files
-
-### 1. CQRS Layer (Application)
-
-#### Query: GetUserClubFeatures
-**Location:** `/CMS/src/CMSMicroservice.Application/ClubFeatureCQ/Queries/GetUserClubFeatures/`
-
-**Files:**
-- `GetUserClubFeaturesQuery.cs` - Query definition
-- `GetUserClubFeaturesQueryHandler.cs` - Query handler
-- `UserClubFeatureDto.cs` - Response DTO
-
-**Purpose:** Get list of all club features for a specific user with their active status.
-
-**Input:**
-```csharp
-public record GetUserClubFeaturesQuery : IRequest<List<UserClubFeatureDto>>
-{
-    public long UserId { get; init; }
-}
-```
-
-**Output:**
-```csharp
-public class UserClubFeatureDto
-{
-    public long Id { get; set; }
-    public long UserId { get; set; }
-    public long ClubMembershipId { get; set; }
-    public long ClubFeatureId { get; set; }
-    public string FeatureTitle { get; set; }
-    public string? FeatureDescription { get; set; }
-    public bool IsActive { get; set; }
-    public DateTime GrantedAt { get; set; }
-    public string? Notes { get; set; }
-}
-```
-
-**Logic:**
-- Joins `UserClubFeatures` with `ClubFeature` table
-- Filters by `UserId` and `!IsDeleted`
-- Returns list of features with their active status
-
----
-
-#### Command: ToggleUserClubFeature
-**Location:** `/CMS/src/CMSMicroservice.Application/ClubFeatureCQ/Commands/ToggleUserClubFeature/`
-
-**Files:**
-- `ToggleUserClubFeatureCommand.cs` - Command definition
-- `ToggleUserClubFeatureCommandHandler.cs` - Command handler
-- `ToggleUserClubFeatureResponse.cs` - Response DTO
-
-**Purpose:** Enable or disable a specific club feature for a user.
-
-**Input:**
-```csharp
-public record ToggleUserClubFeatureCommand : IRequest<ToggleUserClubFeatureResponse>
-{
-    public long UserId { get; init; }
-    public long ClubFeatureId { get; init; }
-    public bool IsActive { get; init; }
-}
-```
-
-**Output:**
-```csharp
-public class ToggleUserClubFeatureResponse
-{
-    public bool Success { get; set; }
-    public string Message { get; set; }
-    public long? UserClubFeatureId { get; set; }
-    public bool? IsActive { get; set; }
-}
-```
-
-**Validations:**
-1. ✅ User exists and not deleted
-2. ✅ Club feature exists and not deleted
-3. ✅ User has this feature assigned (exists in UserClubFeatures)
-
-**Logic:**
-- Find `UserClubFeature` record by `UserId` + `ClubFeatureId`
-- Update `IsActive` field
-- Set `LastModified` timestamp
-- Save changes
-
-**Error Messages:**
-- "کاربر یافت نشد" - User not found
-- "ویژگی باشگاه یافت نشد" - Club feature not found
-- "این ویژگی برای کاربر یافت نشد" - User doesn't have this feature
-
-**Success Messages:**
-- "ویژگی با موفقیت فعال شد" - Feature activated successfully
-- "ویژگی با موفقیت غیرفعال شد" - Feature deactivated successfully
-
----
-
-### 2. gRPC Layer (Protobuf + WebApi)
-
-#### Proto Definition
-**File:** `/CMS/src/CMSMicroservice.Protobuf/Protos/clubmembership.proto`
-
-**Added RPC Methods:**
-```protobuf
-rpc GetUserClubFeatures(GetUserClubFeaturesRequest) returns (GetUserClubFeaturesResponse){
-    option (google.api.http) = {
-        get: "/ClubFeature/GetUserFeatures"
-    };
-};
-
-rpc ToggleUserClubFeature(ToggleUserClubFeatureRequest) returns (ToggleUserClubFeatureResponse){
-    option (google.api.http) = {
-        post: "/ClubFeature/ToggleFeature"
-        body: "*"
-    };
-};
-```
-
-**Message Definitions:**
-```protobuf
-message GetUserClubFeaturesRequest {
-    int64 user_id = 1;
-}
-
-message GetUserClubFeaturesResponse {
-    repeated UserClubFeatureModel features = 1;
-}
-
-message UserClubFeatureModel {
-    int64 id = 1;
-    int64 user_id = 2;
-    int64 club_membership_id = 3;
-    int64 club_feature_id = 4;
-    string feature_title = 5;
-    string feature_description = 6;
-    bool is_active = 7;
-    google.protobuf.Timestamp granted_at = 8;
-    string notes = 9;
-}
-
-message ToggleUserClubFeatureRequest {
-    int64 user_id = 1;
-    int64 club_feature_id = 2;
-    bool is_active = 3;
-}
-
-message ToggleUserClubFeatureResponse {
-    bool success = 1;
-    string message = 2;
-    google.protobuf.Int64Value user_club_feature_id = 3;
-    google.protobuf.BoolValue is_active = 4;
-}
-```
-
----
-
-#### gRPC Service Implementation
-**File:** `/CMS/src/CMSMicroservice.WebApi/Services/ClubMembershipService.cs`
-
-**Added Methods:**
-```csharp
-public override async Task<GetUserClubFeaturesResponse> GetUserClubFeatures(
-    GetUserClubFeaturesRequest request, 
-    ServerCallContext context)
-{
-    return await _dispatchRequestToCQRS.Handle<
-        GetUserClubFeaturesRequest, 
-        GetUserClubFeaturesQuery, 
-        GetUserClubFeaturesResponse>(request, context);
-}
-
-public override async Task<Protobuf.Protos.ClubMembership.ToggleUserClubFeatureResponse> 
-    ToggleUserClubFeature(
-        ToggleUserClubFeatureRequest request, 
-        ServerCallContext context)
-{
-    return await _dispatchRequestToCQRS.Handle<
-        ToggleUserClubFeatureRequest, 
-        ToggleUserClubFeatureCommand, 
-        Protobuf.Protos.ClubMembership.ToggleUserClubFeatureResponse>(request, context);
-}
-```
-
----
-
-#### AutoMapper Profile
-**File:** `/CMS/src/CMSMicroservice.WebApi/Common/Mappings/ClubFeatureProfile.cs`
-
-**Mappings:**
-1. `GetUserClubFeaturesRequest` → `GetUserClubFeaturesQuery`
-2. `UserClubFeatureDto` → `UserClubFeatureModel` (Proto)
-3. `List<UserClubFeatureDto>` → `GetUserClubFeaturesResponse`
-4. `ToggleUserClubFeatureRequest` → `ToggleUserClubFeatureCommand`
-5. `ToggleUserClubFeatureResponse` (App) → `ToggleUserClubFeatureResponse` (Proto)
-
-**Special Handling:**
-- DateTime conversion to `Timestamp` (Protobuf format)
-- Null-safe mapping for optional fields
-- Fully qualified type names to avoid ambiguity
-
----
-
-## API Endpoints
-
-### 1. Get User Club Features
-**Method:** GET  
-**Endpoint:** `/ClubFeature/GetUserFeatures`  
-**Request:**
-```json
-{
-  "user_id": 123
-}
-```
-
-**Response:**
-```json
-{
-  "features": [
-    {
-      "id": 1,
-      "user_id": 123,
-      "club_membership_id": 456,
-      "club_feature_id": 1,
-      "feature_title": "دسترسی به فروشگاه تخفیف",
-      "feature_description": "امکان خرید از فروشگاه تخفیف",
-      "is_active": true,
-      "granted_at": "2025-12-09T18:30:00Z",
-      "notes": "اعطا شده به‌طور خودکار هنگام فعالسازی"
-    }
-  ]
-}
-```
-
----
-
-### 2. Toggle User Club Feature
-**Method:** POST  
-**Endpoint:** `/ClubFeature/ToggleFeature`  
-**Request:**
-```json
-{
-  "user_id": 123,
-  "club_feature_id": 1,
-  "is_active": false
-}
-```
-
-**Response (Success):**
-```json
-{
-  "success": true,
-  "message": "ویژگی با موفقیت غیرفعال شد",
-  "user_club_feature_id": 1,
-  "is_active": false
-}
-```
-
-**Response (Error - User Not Found):**
-```json
-{
-  "success": false,
-  "message": "کاربر یافت نشد"
-}
-```
-
-**Response (Error - Feature Not Found):**
-```json
-{
-  "success": false,
-  "message": "ویژگی باشگاه یافت نشد"
-}
-```
-
-**Response (Error - User Doesn't Have Feature):**
-```json
-{
-  "success": false,
-  "message": "این ویژگی برای کاربر یافت نشد"
-}
-```
-
----
-
-## Database Schema
-
-### Table: UserClubFeatures
-Existing table with newly added `IsActive` field:
-
-```sql
-CREATE TABLE [CMS].[UserClubFeatures]
-(
-    [Id] BIGINT IDENTITY(1,1) PRIMARY KEY,
-    [UserId] BIGINT NOT NULL,
-    [ClubMembershipId] BIGINT NOT NULL,
-    [ClubFeatureId] BIGINT NOT NULL,
-    [GrantedAt] DATETIME2 NOT NULL,
-    [IsActive] BIT NOT NULL DEFAULT 1, -- ← NEW FIELD
-    [Notes] NVARCHAR(MAX) NULL,
-    [Created] DATETIME2 NOT NULL,
-    [CreatedBy] NVARCHAR(MAX) NULL,
-    [LastModified] DATETIME2 NULL,
-    [LastModifiedBy] NVARCHAR(MAX) NULL,
-    [IsDeleted] BIT NOT NULL DEFAULT 0,
-    
-    CONSTRAINT FK_UserClubFeatures_Users FOREIGN KEY ([UserId]) 
-        REFERENCES [Identity].[Users]([Id]),
-    CONSTRAINT FK_UserClubFeatures_ClubMembership FOREIGN KEY ([ClubMembershipId]) 
-        REFERENCES [CMS].[ClubMembership]([Id]),
-    CONSTRAINT FK_UserClubFeatures_ClubFeatures FOREIGN KEY ([ClubFeatureId]) 
-        REFERENCES [CMS].[ClubFeatures]([Id])
-);
-```
-
----
-
-## Usage Examples
-
-### Admin Panel Scenario
-
-#### 1. View User's Club Features
-```csharp
-// Admin selects user ID: 123
-var request = new GetUserClubFeaturesRequest { UserId = 123 };
-var response = await client.GetUserClubFeaturesAsync(request);
-
-// Display in grid:
-foreach (var feature in response.Features)
-{
-    Console.WriteLine($"Feature: {feature.FeatureTitle}");
-    Console.WriteLine($"Status: {(feature.IsActive ? "فعال" : "غیرفعال")}");
-    Console.WriteLine($"Granted: {feature.GrantedAt}");
-    Console.WriteLine("---");
-}
-```
-
-**Output:**
-```
-Feature: دسترسی به فروشگاه تخفیف
-Status: فعال
-Granted: 2025-12-09 18:30:00
----
-Feature: دسترسی به کمیسیون هفتگی
-Status: فعال
-Granted: 2025-12-09 18:30:00
----
-Feature: دسترسی به شارژ شبکه
-Status: غیرفعال
-Granted: 2025-12-09 18:30:00
----
-```
-
----
-
-#### 2. Disable a Feature
-```csharp
-// Admin clicks "Disable" on Feature ID: 3
-var request = new ToggleUserClubFeatureRequest 
-{ 
-    UserId = 123, 
-    ClubFeatureId = 3, 
-    IsActive = false 
-};
-
-var response = await client.ToggleUserClubFeatureAsync(request);
-
-if (response.Success)
-{
-    Console.WriteLine(response.Message); 
-    // Output: ویژگی با موفقیت غیرفعال شد
-}
-```
-
----
-
-#### 3. Re-enable a Feature
-```csharp
-// Admin clicks "Enable" on Feature ID: 3
-var request = new ToggleUserClubFeatureRequest 
-{ 
-    UserId = 123, 
-    ClubFeatureId = 3, 
-    IsActive = true 
-};
-
-var response = await client.ToggleUserClubFeatureAsync(request);
-
-if (response.Success)
-{
-    Console.WriteLine(response.Message); 
-    // Output: ویژگی با موفقیت فعال شد
-}
-```
-
----
-
-## Testing Checklist
-
-### Unit Tests (Recommended)
-- [ ] GetUserClubFeaturesQueryHandler returns correct DTOs
-- [ ] ToggleUserClubFeatureCommandHandler validates user exists
-- [ ] ToggleUserClubFeatureCommandHandler validates feature exists
-- [ ] ToggleUserClubFeatureCommandHandler validates user has feature
-- [ ] ToggleUserClubFeatureCommandHandler updates IsActive correctly
-- [ ] ToggleUserClubFeatureCommandHandler sets LastModified timestamp
-
-### Integration Tests
-- [ ] gRPC GetUserClubFeatures endpoint returns data
-- [ ] gRPC ToggleUserClubFeature endpoint updates database
-- [ ] AutoMapper mappings work correctly
-- [ ] Proto serialization/deserialization works
-
-### Manual Testing
-1. **Get Features:**
-   ```bash
-   grpcurl -d '{"user_id": 123}' \
-     -plaintext localhost:5000 \
-     clubmembership.ClubMembershipContract/GetUserClubFeatures
-   ```
-
-2. **Disable Feature:**
-   ```bash
-   grpcurl -d '{"user_id": 123, "club_feature_id": 1, "is_active": false}' \
-     -plaintext localhost:5000 \
-     clubmembership.ClubMembershipContract/ToggleUserClubFeature
-   ```
-
-3. **Verify in Database:**
-   ```sql
-   SELECT Id, UserId, ClubFeatureId, IsActive, LastModified
-   FROM CMS.UserClubFeatures
-   WHERE UserId = 123;
-   ```
-
----
-
-## Build Status
-✅ **All projects build successfully**
-- CMSMicroservice.Domain: ✅
-- CMSMicroservice.Application: ✅ (0 errors, 274 warnings)
-- CMSMicroservice.Protobuf: ✅
-- CMSMicroservice.WebApi: ✅ (0 errors, 17 warnings)
-
----
-
-## Next Steps (Optional Enhancements)
-
-1. **Authorization:**
-   - Add `[Authorize(Roles = "Admin")]` attribute
-   - Validate admin permissions before toggling
-
-2. **Audit Logging:**
-   - Log who changed the feature status
-   - Track `LastModifiedBy` field
-
-3. **Bulk Operations:**
-   - Add endpoint to toggle multiple features at once
-   - Add endpoint to enable/disable all features for a user
-
-4. **History Tracking:**
-   - Create `UserClubFeatureHistory` table
-   - Log every status change with timestamp and reason
-
-5. **Notifications:**
-   - Send notification to user when feature is disabled
-   - Email/SMS alert for important features
-
-6. **Business Rules:**
-   - Add validation: prevent disabling critical features
-   - Add expiration dates for features
-   - Add feature dependencies (e.g., Feature B requires Feature A)
-
----
-
-## Summary
-✅ Created CQRS Query + Command for club feature management  
-✅ Created gRPC Proto definitions and services  
-✅ Created AutoMapper mappings  
-✅ All builds successful  
-✅ Ready for deployment and testing  
-
-**Total Files Created:** 8  
-**Total Lines of Code:** ~350  
-**Build Errors:** 0  
-**Status:** ✅ Complete and ready for use

cms/email-sms-configuration.md

@@ -1,191 +0,0 @@
-# راهنمای پیکربندی Email و SMS
-
-## قالب‌های پیامک (SmsTemplates)
-
-> **فایل**: `CMSMicroservice.Domain/Common/SmsTemplates.cs`
-
-همه قالب‌های پیامک در یک کلاس متمرکز شده‌اند:
-
-```csharp
-public static class SmsTemplates
-{
-    // وام دایا
-    public static string DayaLoanReceived(string? firstName, long amount)
-        => $"{GetUserName(firstName)} عزیز، مبلغ {amount:N0} ریال وام دایا به کیف پول شما واریز شد. کارابازار";
-
-    // فعال‌سازی باشگاه
-    public static string ClubActivated(string? firstName)
-        => $"{GetUserName(firstName)} عزیز، حساب باشگاه شما فعال شد. کارابازار";
-
-    // خرید پکیج
-    public static string PackagePurchased(string? firstName, string packageName)
-        => $"{GetUserName(firstName)} عزیز، پکیج {packageName} با موفقیت خریداری شد. کارابازار";
-
-    // واریز کمیسیون
-    public static string CommissionDeposited(string? firstName, long amount)
-        => $"{GetUserName(firstName)} عزیز، مبلغ {amount:N0} ریال کمیسیون به کیف پول شما واریز شد. کارابازار";
-
-    // برداشت موفق
-    public static string WithdrawalSuccess(string? firstName, long amount)
-        => $"{GetUserName(firstName)} عزیز، درخواست برداشت {amount:N0} ریال با موفقیت انجام شد. کارابازار";
-
-    // پیوستن به شبکه
-    public static string NetworkJoined(string? firstName, string referrerName)
-        => $"{GetUserName(firstName)} عزیز، به شبکه {referrerName} پیوستید. کارابازار";
-
-    // زیرمجموعه جدید
-    public static string NewDownline(string? firstName, string newMemberName)
-        => $"{GetUserName(firstName)} عزیز، {newMemberName} به زیرمجموعه شما اضافه شد. کارابازار";
-
-    // کد OTP
-    public static string OtpCode(string code)
-        => $"کد تأیید شما: {code}\nکارابازار";
-
-    // خوش‌آمدگویی
-    public static string Welcome(string? firstName)
-        => $"{GetUserName(firstName)} عزیز، به کارابازار خوش آمدید!";
-}
-```
-
-### نحوه استفاده:
-
-```csharp
-// تزریق سرویس
-private readonly IKavenegarService _smsService;
-
-// ارسال پیامک
-var message = SmsTemplates.DayaLoanReceived(user.FirstName, 56_000_000);
-await _smsService.SendAsync(user.PhoneNumber, message);
-```
-
----
-
-## تنظیمات Email (Gmail)
-
-### مرحله 1: ایجاد App Password در Gmail
-
-1. به [Google Account Security](https://myaccount.google.com/security) بروید
-2. گزینه "2-Step Verification" را فعال کنید
-3. به بخش "App passwords" بروید
-4. یک App Password جدید با نام "FourSat CMS" ایجاد کنید
-5. پسورد 16 رقمی را در `appsettings.Production.json` در فیلد `SmtpPassword` قرار دهید
-
-### مرحله 2: تنظیم appsettings.Production.json
-
-```json
-"Email": {
-  "Enabled": true,
-  "SmtpHost": "smtp.gmail.com",
-  "SmtpPort": 587,
-  "SmtpUsername": "your-email@gmail.com",  // ایمیل Gmail خود
-  "SmtpPassword": "your-16-digit-app-password",  // App Password از مرحله 1
-  "FromEmail": "noreply@foursat.com",  // ایمیل فرستنده (می‌تواند همان Gmail باشد)
-  "FromName": "FourSat CMS",
-  "EnableSsl": true
-}
-```
-
-### سایر سرویس‌های SMTP:
-
-#### Outlook/Microsoft 365:
-```json
-"SmtpHost": "smtp.office365.com",
-"SmtpPort": 587
-```
-
-#### Yahoo Mail:
-```json
-"SmtpHost": "smtp.mail.yahoo.com",
-"SmtpPort": 587
-```
-
----
-
-## تنظیمات SMS (کاوه نگار)
-
-### مرحله 1: ثبت‌نام در کاوه نگار
-
-1. به [Kavenegar.com](https://panel.kavenegar.com/client/membership/register) بروید
-2. ثبت‌نام کنید و حساب خود را تأیید کنید
-3. از پنل، API Key خود را کپی کنید
-
-### مرحله 2: تنظیم appsettings.Production.json
-
-```json
-"Sms": {
-  "Enabled": true,
-  "Provider": "Kavenegar",
-  "KavenegarApiKey": "YOUR_KAVENEGAR_API_KEY",  // API Key از پنل کاوه نگار
-  "Sender": "10008663"  // شماره ارسال‌کننده (از پنل کاوه نگار)
-}
-```
-
-### نکات مهم:
-- شماره `Sender` باید از پنل کاوه نگار تهیه شود
-- برای تست می‌توانید از شماره‌های رایگان استفاده کنید
-- هزینه هر پیامک بسته به نوع خط متفاوت است
-
----
-
-## تست کردن
-
-### تست Email:
-```bash
-# در محیط Development
-curl -X POST "http://localhost:5133/api/admin/trigger-weekly-calculation"
-```
-
-### تست SMS:
-همان دستور بالا را اجرا کنید. سیستم به صورت خودکار:
-- Email ارسال می‌کند (اگر User.Email پر باشد)
-- SMS ارسال می‌کند (اگر User.Mobile پر باشد)
-
-### بررسی Log ها:
-```bash
-# در ترمینال سرویس CMS
-# پیام‌های زیر را مشاهده کنید:
-# 📧 Email sent to {Email}: {Subject}
-# 📱 SMS sent to {PhoneNumber}: {MessageId}
-```
-
----
-
-## امنیت
-
-### ⚠️ مهم:
-1. فایل `appsettings.Production.json` را به Git اضافه نکنید
-2. از Environment Variables یا Azure Key Vault استفاده کنید
-3. API Key ها را هرگز در کد سورس قرار ندهید
-
-### استفاده از Environment Variables:
-
-```bash
-# Linux/Mac
-export Email__SmtpPassword="your-app-password"
-export Sms__KavenegarApiKey="your-api-key"
-
-# Windows
-set Email__SmtpPassword=your-app-password
-set Sms__KavenegarApiKey=your-api-key
-```
-
----
-
-## خطایابی (Troubleshooting)
-
-### Email ارسال نمی‌شود:
-1. App Password را صحیح وارد کرده‌اید؟
-2. 2-Step Verification در Gmail فعال است؟
-3. Port 587 باز است؟
-4. `EnableSsl: true` تنظیم شده؟
-
-### SMS ارسال نمی‌شود:
-1. API Key صحیح است؟
-2. اعتبار حساب کاوه نگار کافی است؟
-3. شماره `Sender` معتبر است؟
-4. فرمت شماره موبایل صحیح است؟ (09xxxxxxxxx)
-
-### Log ها را بررسی کنید:
-```bash
-tail -f /tmp/cms_run.log
-```

cms/payment-architecture-pyms.md

@@ -1,410 +0,0 @@
-# Payment Architecture with PYMS Microservice
-
-**تاریخ**: 2024-12-02  
-**وضعیت**: Architecture Document  
-**اولویت**: 🔴 بالا (اطلاعات مهم برای Phase 9)
-
----
-
-## 📋 خلاصه
-
-**درگاه پرداخت** در این پروژه از طریق **مایکروسرویس PYMS** (`Afrino.PYMSMicroservice.Protobuf`) مدیریت می‌شود.
-
-**CMS Microservice** فقط **نتیجه نهایی پرداخت** را ثبت می‌کند و خودش درگاه پرداخت را پیاده‌سازی نمی‌کند.
-
----
-
-## 🏗️ معماری کلی
-
-```
-[User Frontend] 
-      ↓
-[FrontOffice.BFF]  ← درخواست خرید از اینجا شروع می‌شود
-      ↓
-[PYMS Microservice] ← مدیریت درگاه پرداخت (Afrino.PYMSMicroservice.Protobuf)
-      ↓
-[Payment Gateway: در PYMS/Gateway - نه CMS]
-      ↓ (Callback)
-[PYMS Microservice] ← تایید پرداخت
-      ↓
-[CMS Microservice] ← **فقط ثبت نتیجه** (Transaction با RefId)
-```
-
-### توضیح جریان:
-
-1. **کاربر** محصول را در Frontend انتخاب می‌کند
-2. **FrontOffice.BFF** درخواست خرید را به **PYMS Microservice** می‌فرستد
-3. **PYMS/Gateway** با درگاه پرداخت (بانک) ارتباط برقرار می‌کند و پرداخت را انجام می‌دهد
-4. **Gateway** نتیجه پرداخت را به **CMS Callback** می‌فرستد
-5. **CMS** تراکنش را تایید و عملیات بعدی (فعال‌سازی، اضافه PV، Wallet) را انجام می‌دهد
-4. **PYMS** URL درگاه را برمی‌گرداند
-5. کاربر به درگاه ریدایرکت می‌شود و پرداخت می‌کند
-6. بعد از پرداخت، **Callback** به **PYMS** برمی‌گردد
-7. **PYMS** پرداخت را Verify می‌کند
-8. **FrontOffice.BFF** نتیجه را به **CMS** می‌فرستد
-9. **CMS** Transaction را با RefId و وضعیت نهایی ثبت می‌کند
-
----
-
-## 📦 Package: `Afrino.PYMSMicroservice.Protobuf`
-
-**Version**: 0.0.11  
-**Type**: gRPC Protobuf Client  
-**Namespace**: `PYMSMicroservice.Protobuf.Protos.Transaction`
-
-### Dependencies:
-- Google.Protobuf (3.23.3)
-- Grpc.Core.Api (2.54.0)
-- FluentValidation (11.2.2)
-- Google.Api.CommonProtos (2.10.0)
-
----
-
-## 🔧 TransactionContract Service
-
-### Client Class:
-```csharp
-using PYMSMicroservice.Protobuf.Protos.Transaction;
-using Grpc.Core;
-
-var client = new TransactionContract.TransactionContractClient(channel);
-```
-
-### Available Methods:
-
-#### 1. **PaymentRequest** (شروع پرداخت)
-```csharp
-// Request
-var request = new PaymentRequestRequest
-{
-    MerchantId = "YOUR_MERCHANT_ID",        // شناسه فروشنده
-    Amount = 100000,                         // مبلغ به ریال (یا تومان - بستگی به Currency)
-    CallbackUrl = "https://yoursite.com/payment/callback",
-    Description = "خرید بسته طلایی",
-    Mobile = "09123456789",                  // اختیاری
-    Email = "user@example.com",              // اختیاری
-    Currency = CurrencyEnum.Irt,             // IRR (ریال) یا IRT (تومان)
-    Type = TransactionTypeEnum.Real,         // Real یا Sandbox
-    OrderId = "ORDER_123456"                 // اختیاری - شناسه سفارش خودمان
-};
-
-// Call
-var response = await client.PaymentRequestAsync(request);
-
-// Response
-Console.WriteLine(response.PaymentGWUrl); 
-// مثال: "https://bpm.shaparak.ir/pgwchannel/startpay.mellat?RefId=123456"
-```
-
-**Response Fields**:
-- `PaymentGWUrl` (string): URL درگاه پرداخت که کاربر باید به آن ریدایرکت شود
-
-#### 2. **PaymentVerification** (تایید پرداخت)
-```csharp
-// Request
-var request = new PaymentVerificationRequest
-{
-    Authority = "AUTHORITY_FROM_CALLBACK",   // Authority که از callback می‌آید
-    Status = "OK"                             // Status که از callback می‌آید (OK/NOK)
-};
-
-// Call
-var response = await client.PaymentVerificationAsync(request);
-
-// Response
-if (response.PaymentStatus)
-{
-    Console.WriteLine($"پرداخت موفق!");
-    Console.WriteLine($"RefId: {response.RefId}");
-    Console.WriteLine($"OrderId: {response.OrderId}");
-    Console.WriteLine($"Message: {response.Message}");
-    Console.WriteLine($"VerificationStatusCode: {response.VerificationStatusCode}");
-}
-else
-{
-    Console.WriteLine($"پرداخت ناموفق: {response.Message}");
-}
-```
-
-**Response Fields**:
-- `Id` (long): شناسه تراکنش در سیستم PYMS
-- `PaymentStatus` (bool): وضعیت پرداخت (true = موفق، false = ناموفق)
-- `Message` (string): پیام وضعیت
-- `RefId` (string): شناسه مرجع از درگاه پرداخت
-- `OrderId` (string): شناسه سفارش که در PaymentRequest ارسال شده
-- `VerificationStatusCode` (int): کد وضعیت تایید
-
-#### 3. **CreateNewTransaction** (ثبت تراکنش جدید)
-```csharp
-var request = new CreateNewTransactionRequest
-{
-    MerchantId = "...",
-    Amount = 100000,
-    CallbackUrl = "...",
-    Description = "...",
-    Currency = CurrencyEnum.Irt,
-    PaymentStatus = false,  // false در ابتدا
-    Type = TransactionTypeEnum.Real
-};
-
-var response = await client.CreateNewTransactionAsync(request);
-Console.WriteLine($"Transaction Id: {response.Id}");
-```
-
-#### 4. **UpdateTransaction** (به‌روزرسانی تراکنش)
-```csharp
-var request = new UpdateTransactionRequest
-{
-    Id = transactionId,
-    PaymentStatus = true,  // بعد از verify
-    RefId = "...",
-    VerificationStatusCode = 100,
-    VerificationStatusMessage = "تراکنش موفق"
-};
-
-await client.UpdateTransactionAsync(request);
-```
-
-#### 5. **GetTransaction** (دریافت تراکنش)
-```csharp
-var request = new GetTransactionRequest
-{
-    Id = transactionId,
-    // یا
-    Authority = "AUTHORITY_FROM_CALLBACK"
-};
-
-var response = await client.GetTransactionAsync(request);
-```
-
-#### 6. **GetAllTransactionByFilter** (لیست تراکنش‌ها)
-```csharp
-var request = new GetAllTransactionByFilterRequest
-{
-    PaginationState = new PaginationState { PageNumber = 1, PageSize = 10 },
-    Filter = new GetAllTransactionByFilterFilter
-    {
-        MerchantId = "...",
-        PaymentStatus = true
-    }
-};
-
-var response = await client.GetAllTransactionByFilterAsync(request);
-// response.Models: لیست تراکنش‌ها
-// response.MetaData: اطلاعات صفحه‌بندی
-```
-
----
-
-## 🔑 Enums
-
-### CurrencyEnum
-```csharp
-public enum CurrencyEnum
-{
-    Irr = 0,  // ریال
-    Irt = 1   // تومان
-}
-```
-
-### TransactionTypeEnum
-```csharp
-public enum TransactionTypeEnum
-{
-    Real = 0,     // تراکنش واقعی
-    Sandbox = 1   // تراکنش تستی
-}
-```
-
----
-
-## 💡 نکات مهم برای CMS
-
-### 1. **CMS فقط نتیجه را ثبت می‌کند**
-CMS نباید خودش با درگاه پرداخت ارتباط برقرار کند. این کار توسط **PYMS Microservice** انجام می‌شود.
-
-### 2. **Flow پیشنهادی برای Phase 9 (Club Discount Shop)**:
-
-#### در FrontOffice.BFF:
-```csharp
-// 1. کاربر محصول را انتخاب می‌کند
-var product = await cmsClient.GetProductAsync(productId);
-
-// 2. محاسبه تخفیف
-var userWallet = await cmsClient.GetUserWalletAsync(userId);
-var maxDiscountAmount = product.Price * (product.MaxDiscountPercent / 100);
-var actualDiscountAmount = Math.Min(userWallet.DiscountBalance, maxDiscountAmount);
-var gatewayAmount = product.Price - actualDiscountAmount;
-
-// 3. ثبت Order در CMS با وضعیت Pending
-var order = await cmsClient.CreateDiscountOrderAsync(new CreateDiscountOrderRequest
-{
-    UserId = userId,
-    ProductId = productId,
-    TotalAmount = product.Price,
-    DiscountAmount = actualDiscountAmount,
-    GatewayAmount = gatewayAmount,
-    Status = OrderStatus.Pending
-});
-
-// 4. درخواست پرداخت از PYMS
-var paymentResponse = await pymsClient.PaymentRequestAsync(new PaymentRequestRequest
-{
-    MerchantId = "YOUR_MERCHANT_ID",
-    Amount = (long)gatewayAmount,  // مبلغی که باید از درگاه پرداخت شود
-    CallbackUrl = $"https://yoursite.com/payment/verify?orderId={order.Id}",
-    Description = $"خرید {product.Title}",
-    Currency = CurrencyEnum.Irt,
-    Type = TransactionTypeEnum.Real,
-    OrderId = order.Id.ToString()
-});
-
-// 5. ریدایرکت به درگاه
-return Redirect(paymentResponse.PaymentGWUrl);
-```
-
-#### در Callback (بعد از بازگشت از درگاه):
-```csharp
-// 1. دریافت Authority و Status از Query String
-var authority = Request.Query["Authority"];
-var status = Request.Query["Status"];
-var orderId = Request.Query["orderId"];
-
-// 2. تایید پرداخت از PYMS
-var verifyResponse = await pymsClient.PaymentVerificationAsync(new PaymentVerificationRequest
-{
-    Authority = authority,
-    Status = status
-});
-
-// 3. ثبت نتیجه در CMS
-if (verifyResponse.PaymentStatus)
-{
-    // 3.1. کسر DiscountBalance
-    await cmsClient.DeductDiscountBalanceAsync(new DeductDiscountBalanceRequest
-    {
-        UserId = userId,
-        Amount = order.DiscountAmount,
-        Description = $"خرید محصول {product.Title}",
-        RefId = verifyResponse.RefId
-    });
-
-    // 3.2. ثبت Transaction در CMS
-    await cmsClient.CreateTransactionAsync(new CreateTransactionRequest
-    {
-        UserId = userId,
-        Type = TransactionType.DiscountPurchase,
-        Amount = order.TotalAmount,
-        DiscountAmount = order.DiscountAmount,
-        GatewayAmount = order.GatewayAmount,
-        RefId = verifyResponse.RefId,
-        Status = TransactionStatus.Completed,
-        Description = $"خرید {product.Title}"
-    });
-
-    // 3.3. تغییر وضعیت Order به Completed
-    await cmsClient.CompleteDiscountOrderAsync(new CompleteDiscountOrderRequest
-    {
-        OrderId = orderId,
-        RefId = verifyResponse.RefId
-    });
-
-    return View("PaymentSuccess");
-}
-else
-{
-    // 3.4. تغییر وضعیت Order به Failed
-    await cmsClient.FailDiscountOrderAsync(new FailDiscountOrderRequest
-    {
-        OrderId = orderId,
-        ErrorMessage = verifyResponse.Message
-    });
-
-    return View("PaymentFailed", verifyResponse.Message);
-}
-```
-
-### 3. **Entity های مورد نیاز در CMS**:
-
-```csharp
-// Domain/Entities/DiscountOrder.cs
-public class DiscountOrder
-{
-    public long Id { get; set; }
-    public long UserId { get; set; }
-    public long ProductId { get; set; }
-    public decimal TotalAmount { get; set; }
-    public decimal DiscountAmount { get; set; }  // مبلغ از DiscountBalance
-    public decimal GatewayAmount { get; set; }    // مبلغ از درگاه
-    public OrderStatus Status { get; set; }       // Pending/Completed/Failed
-    public string? RefId { get; set; }            // RefId از PYMS
-    public string? ErrorMessage { get; set; }
-    public DateTime CreatedAt { get; set; }
-    public DateTime? CompletedAt { get; set; }
-    
-    // Navigation
-    public User User { get; set; }
-    public Product Product { get; set; }
-}
-
-// Domain/Enums/OrderStatus.cs
-public enum OrderStatus
-{
-    Pending = 0,      // در انتظار پرداخت
-    Completed = 1,    // پرداخت موفق
-    Failed = 2        // پرداخت ناموفق
-}
-```
-
-### 4. **Commands مورد نیاز در CMS**:
-
-- `CreateDiscountOrderCommand`: ثبت سفارش اولیه
-- `CompleteDiscountOrderCommand`: تکمیل سفارش بعد از پرداخت موفق
-- `FailDiscountOrderCommand`: شکست سفارش
-- `DeductDiscountBalanceCommand`: کسر از DiscountBalance
-
----
-
-## ✅ مزایای این معماری
-
-1. ✅ **Separation of Concerns**: CMS فقط روی business logic خودش تمرکز دارد
-2. ✅ **Single Responsibility**: PYMS مسئول پرداخت است، CMS مسئول ثبت نتیجه
-3. ✅ **Easy Testing**: می‌توان PYMS را با Mock جایگزین کرد
-4. ✅ **Scalability**: هر microservice به‌صورت مستقل scale می‌شود
-5. ✅ **Maintainability**: تغییرات در درگاه پرداخت فقط در PYMS انجام می‌شود
-
----
-
-## ⚠️ نکات امنیتی
-
-1. **همیشه Verify کنید**: حتی اگر Status=OK باشد، حتماً PaymentVerification را صدا بزنید
-2. **Callback را Validate کنید**: مطمئن شوید request واقعاً از درگاه آمده (IP whitelisting)
-3. **OrderId را Validate کنید**: مطمئن شوید OrderId متعلق به همان کاربری است که لاگین کرده
-4. **مبلغ را چک کنید**: مبلغ پرداخت شده با مبلغ سفارش مطابقت داشته باشد
-5. **Idempotency**: از ثبت تکراری تراکنش جلوگیری کنید (با RefId)
-
----
-
-## 📚 مثال کامل برای Phase 9
-
-در فاز 9، باید:
-1. ✅ **FrontOffice.BFF** درخواست پرداخت را به **PYMS** بفرستد
-2. ✅ **PYMS** URL درگاه را برگرداند
-3. ✅ بعد از بازگشت، **FrontOffice.BFF** verify کند
-4. ✅ نتیجه را به **CMS** بفرستد تا:
-   - DiscountBalance کسر شود
-   - Transaction ثبت شود
-   - Order تکمیل شود
-
----
-
-**نتیجه‌گیری**: 
-- ✅ **Payment Gateway Service** (فقط DayaPaymentService برای Payout) **فقط برای پرداخت به کاربران است**
-- ✅ **Transaction System در CMS** برای دریافت نتیجه پرداخت از Gateway و ادامه عملیات:
-  - Entity: `Transaction` (ReferenceId, Amount, Status, Gateway)
-  - Commands: `CreateTransaction`, `VerifyTransaction` (Callback), `RefundTransaction`
-  - Queries: `GetTransactions`, `GetUserTransactions`
-  - جریان: User → Gateway (پرداخت) → Callback به CMS → CMS (فعال‌سازی)
-- ✅ این سرویس‌ها فقط برای **مستندسازی** و **درک معماری** نوشته شدند
-- ✅ در عمل، **PYMS Microservice** مسئول ارتباط با درگاه است
-- ✅ **CMS فقط نتیجه را ثبت می‌کند**

cms/payment-gateway.md

@@ -1,777 +0,0 @@
-# Payment Gateway Integration Guide
-
-## 📋 Overview
-
-## 🔄 جریان پرداخت در سیستم
-
-### 1️⃣ دریافت پول از کاربر (Payment IN)
-```
-کاربر → Gateway/PYMS → بانک → پرداخت موفق
-                              ↓
-                      Callback به CMS
-                              ↓
-          CMS: VerifyTransaction + فعال‌سازی عضویت
-```
-**توضیح**: 
-- درگاه اینترنتی در **Gateway/PYMS** است (نه CMS)
-- CMS فقط **نتیجه پرداخت را دریافت** می‌کند (از طریق Callback)
-- سپس عملیات بعدی (فعال‌سازی، اضافه PV، Wallet) را انجام می‌دهد
-- **Transaction System** در CMS برای این کار طراحی شده
-
-### 2️⃣ پرداخت به کاربر (Payout)
-```
-ادمین تایید برداشت → CMS → DayaPaymentService → واریز به حساب کاربر
-```
-**توضیح**:
-- این سند فقط برای **Payout** است
-- سیستم از دو پیاده‌سازی پشتیبانی می‌کند:
-
-1. **MockPaymentGatewayService** - برای Development و Testing
-2. **DayaPaymentService** - API واقعی Daya (برای واریز به حساب کاربران)
-
----
-
-## 🏗️ Architecture
-
-### Interface Design
-
-```csharp
-public interface IPaymentGatewayService
-{
-    // پرداخت (خرید بسته)
-    Task<PaymentInitiateResult> InitiatePaymentAsync(
-        PaymentRequest request, 
-        CancellationToken cancellationToken = default);
-
-    // تایید پرداخت (Callback)
-    Task<PaymentVerificationResult> VerifyPaymentAsync(
-        string refId, 
-        string verificationToken, 
-        CancellationToken cancellationToken = default);
-
-    // برداشت/پرداخت به کاربر (Withdrawal)
-    Task<PayoutResult> ProcessPayoutAsync(
-        PayoutRequest request, 
-        CancellationToken cancellationToken = default);
-}
-```
-
-### DTO Models
-
-#### PaymentRequest
-```csharp
-public class PaymentRequest
-{
-    public long UserId { get; set; }
-    public string Mobile { get; set; }
-    public decimal Amount { get; set; }
-    public string Description { get; set; }
-    public string CallbackUrl { get; set; }
-}
-```
-
-#### PaymentInitiateResult
-```csharp
-public class PaymentInitiateResult
-{
-    public bool IsSuccess { get; set; }
-    public string? RefId { get; set; }
-    public string? GatewayUrl { get; set; }
-    public string? ErrorMessage { get; set; }
-}
-```
-
-#### PaymentVerificationResult
-```csharp
-public class PaymentVerificationResult
-{
-    public bool IsSuccess { get; set; }
-    public string RefId { get; set; }
-    public string? TrackingCode { get; set; }
-    public decimal Amount { get; set; }
-    public string? Message { get; set; }
-}
-```
-
-#### PayoutRequest
-```csharp
-public class PayoutRequest
-{
-    public long UserId { get; set; }
-    public string Iban { get; set; }
-    public decimal Amount { get; set; }
-    public string? Description { get; set; }
-}
-```
-
-#### PayoutResult
-```csharp
-public class PayoutResult
-{
-    public bool IsSuccess { get; set; }
-    public string? TransactionId { get; set; }
-    public string Message { get; set; }
-    public DateTime ProcessedAt { get; set; }
-}
-```
-
----
-
-## 🔧 Implementation Details
-
-### 1. MockPaymentGatewayService
-
-**Purpose**: Development و Testing بدون نیاز به API واقعی
-
-**Features**:
-- ✅ IBAN validation (IR prefix, 26 characters)
-- ✅ Amount validation (min 10,000 Toman)
-- ✅ Mock RefId generation (MockRef_{timestamp})
-- ✅ Simulated network delay (500ms)
-- ✅ Comprehensive logging
-- ✅ Gateway URL generation (mock://payment)
-
-**Usage**:
-```json
-{
-  "UseRealPaymentGateway": false
-}
-```
-
-**Example**:
-```csharp
-var result = await _paymentGateway.InitiatePaymentAsync(new PaymentRequest
-{
-    UserId = 123,
-    Mobile = "09123456789",
-    Amount = 100000,
-    Description = "خرید بسته طلایی",
-    CallbackUrl = "https://yoursite.com/payment/callback"
-});
-
-// result.IsSuccess = true
-// result.RefId = "MockRef_1701619200"
-// result.GatewayUrl = "mock://payment/MockRef_1701619200"
-```
-
----
-
-### 2. DayaPaymentService
-
-**Purpose**: یکپارچه‌سازی با API واقعی Daya برای پرداخت و برداشت
-
-**Configuration**:
-```json
-{
-  "UseRealPaymentGateway": true,
-  "PaymentProvider": "Daya",
-  "DayaPayment": {
-    "BaseUrl": "https://api.daya.ir",
-    "ApiKey": "YOUR_DAYA_API_KEY"
-  }
-}
-```
-
-**API Endpoints**:
-
-#### Initiate Payment
-```http
-POST {BaseUrl}/api/v1/payment/initiate
-Content-Type: application/json
-X-API-Key: {ApiKey}
-
-{
-  "userId": 123,
-  "mobile": "09123456789",
-  "amount": 100000,
-  "description": "خرید بسته طلایی",
-  "callbackUrl": "https://yoursite.com/payment/callback"
-}
-
-Response:
-{
-  "success": true,
-  "refId": "DAYA123456789",
-  "gatewayUrl": "https://gateway.daya.ir/pay/DAYA123456789",
-  "errorMessage": null
-}
-```
-
-#### Verify Payment
-```http
-POST {BaseUrl}/api/v1/payment/verify
-Content-Type: application/json
-X-API-Key: {ApiKey}
-
-{
-  "refId": "DAYA123456789",
-  "token": "DAYA123456789"
-}
-
-Response:
-{
-  "success": true,
-  "refId": "DAYA123456789",
-  "trackingCode": "TRACK987654321",
-  "amount": 100000,
-  "message": "تراکنش موفق"
-}
-```
-
-#### Process Payout
-```http
-POST {BaseUrl}/api/v1/payout/process
-Content-Type: application/json
-X-API-Key: {ApiKey}
-
-{
-  "userId": 123,
-  "iban": "IR123456789012345678901234",
-  "amount": 50000,
-  "description": "برداشت کمیسیون"
-}
-
-Response:
-{
-  "success": true,
-  "transactionId": "TXN_123456789",
-  "message": "پرداخت با موفقیت انجام شد",
-  "processedAt": "2024-12-02T10:30:00Z"
-}
-```
-
-**Error Handling**:
-```csharp
-try
-{
-    var response = await _httpClient.PostAsJsonAsync(url, request, cancellationToken);
-    
-    if (!response.IsSuccessStatusCode)
-    {
-        _logger.LogError("Daya API error: StatusCode={StatusCode}", response.StatusCode);
-        return new PaymentInitiateResult
-        {
-            IsSuccess = false,
-            ErrorMessage = $"خطا در ارتباط با سرویس پرداخت: {response.StatusCode}"
-        };
-    }
-    
-    var result = await response.Content.ReadFromJsonAsync<DayaInitiateResponse>(cancellationToken);
-    // Process result...
-}
-catch (Exception ex)
-{
-    _logger.LogError(ex, "Error in InitiatePaymentAsync");
-    return new PaymentInitiateResult
-    {
-        IsSuccess = false,
-        ErrorMessage = "خطای غیرمنتظره در برقراری ارتباط با سرویس پرداخت"
-    };
-}
-```
-
----
-
-### 3. BankMellatPaymentService
-
-**Purpose**: یکپارچه‌سازی با IPG بانک ملت (SOAP Web Service)
-
-**Configuration**:
-```json
-{
-  "UseRealPaymentGateway": true,
-  "PaymentProvider": "BankMellat",
-  "BankMellat": {
-    "ServiceUrl": "https://bpm.shaparak.ir/pgwchannel/services/pgw",
-    "TerminalId": "YOUR_TERMINAL_ID",
-    "Username": "YOUR_USERNAME",
-    "Password": "YOUR_PASSWORD"
-  }
-}
-```
-
-**SOAP Operations**:
-
-#### bpPayRequest (Initiate Payment)
-```xml
-<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
-               xmlns:ns="http://interfaces.core.sw.bps.com/">
-    <soap:Body>
-        <ns:bpPayRequest>
-            <terminalId>{TERMINAL_ID}</terminalId>
-            <userName>{USERNAME}</userName>
-            <userPassword>{PASSWORD}</userPassword>
-            <orderId>{ORDER_ID}</orderId>
-            <amount>{AMOUNT_IN_RIALS}</amount>
-            <localDate>{yyyyMMdd}</localDate>
-            <localTime>{HHmmss}</localTime>
-            <additionalData>{DESCRIPTION}</additionalData>
-            <callBackUrl>{CALLBACK_URL}</callBackUrl>
-            <payerId>0</payerId>
-        </ns:bpPayRequest>
-    </soap:Body>
-</soap:Envelope>
-```
-
-**Response**:
-```xml
-<soap:Envelope>
-    <soap:Body>
-        <ns:bpPayRequestResponse>
-            <return>{REF_ID}</return>  <!-- Success: positive number, Error: negative number -->
-        </ns:bpPayRequestResponse>
-    </soap:Body>
-</soap:Envelope>
-```
-
-#### bpVerifyRequest (Verify Payment)
-```xml
-<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
-               xmlns:ns="http://interfaces.core.sw.bps.com/">
-    <soap:Body>
-        <ns:bpVerifyRequest>
-            <terminalId>{TERMINAL_ID}</terminalId>
-            <userName>{USERNAME}</userName>
-            <userPassword>{PASSWORD}</userPassword>
-            <orderId>{ORDER_ID}</orderId>
-            <saleOrderId>{ORDER_ID}</saleOrderId>
-            <saleReferenceId>{REF_ID}</saleReferenceId>
-        </ns:bpVerifyRequest>
-    </soap:Body>
-</soap:Envelope>
-```
-
-#### bpSettleRequest (Settle Payment)
-```xml
-<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
-               xmlns:ns="http://interfaces.core.sw.bps.com/">
-    <soap:Body>
-        <ns:bpSettleRequest>
-            <terminalId>{TERMINAL_ID}</terminalId>
-            <userName>{USERNAME}</userName>
-            <userPassword>{PASSWORD}</userPassword>
-            <orderId>{ORDER_ID}</orderId>
-            <saleOrderId>{ORDER_ID}</saleOrderId>
-            <saleReferenceId>{REF_ID}</saleReferenceId>
-        </ns:bpSettleRequest>
-    </soap:Body>
-</soap:Envelope>
-```
-
-**Error Codes**:
-
-| Code | Description (Persian) |
-|------|----------------------|
-| 0 | تراکنش موفق |
-| 11 | شماره کارت نامعتبر است |
-| 12 | موجودی کافی نیست |
-| 13 | رمز نادرست است |
-| 14 | تعداد دفعات وارد کردن رمز بیش از حد مجاز است |
-| 15 | کارت نامعتبر است |
-| 17 | کاربر از انجام تراکنش منصرف شده است |
-| 18 | تاریخ انقضای کارت گذشته است |
-| 21 | پذیرنده نامعتبر است |
-| 23 | خطای امنیتی رخ داده است |
-| 24 | اطلاعات کاربری پذیرنده نامعتبر است |
-| 25 | مبلغ نامعتبر است |
-| 41 | شماره درخواست تکراری است |
-| 43 | قبلا درخواست Verify داده شده است |
-| 51 | تراکنش تکراری است |
-
-**Limitations**:
-- ⚠️ Direct payout (ProcessPayoutAsync) **not supported** by Bank Mellat IPG
-- ℹ️ For withdrawals, use **Shaparak Paya** or third-party services like Fanapay, IPG.ir
-
----
-
-## ⚙️ Service Registration (ConfigureServices.cs)
-
-```csharp
-// Payment Gateway Service - برای Development از Mock استفاده می‌شود
-var useRealPaymentGateway = configuration.GetValue<bool>("UseRealPaymentGateway", false);
-
-if (useRealPaymentGateway)
-{
-    var paymentProvider = configuration.GetValue<string>("PaymentProvider", "BankMellat");
-    
-    if (paymentProvider == "Daya")
-    {
-        services.AddHttpClient<IPaymentGatewayService, DayaPaymentService>()
-            .SetHandlerLifetime(TimeSpan.FromMinutes(5));
-    }
-    else if (paymentProvider == "BankMellat")
-    {
-        services.AddHttpClient<IPaymentGatewayService, BankMellatPaymentService>()
-            .SetHandlerLifetime(TimeSpan.FromMinutes(5));
-    }
-    else
-    {
-        throw new InvalidOperationException($"Invalid PaymentProvider: {paymentProvider}");
-    }
-}
-else
-{
-    // Mock برای Development و Testing
-    services.AddScoped<IPaymentGatewayService, MockPaymentGatewayService>();
-}
-```
-
----
-
-## 📝 Usage Examples
-
-### Purchase Package (InitiatePaymentAsync)
-
-```csharp
-// In Command Handler
-public class PurchaseGoldenPackageCommandHandler : IRequestHandler<PurchaseGoldenPackageCommand, long>
-{
-    private readonly IPaymentGatewayService _paymentGateway;
-
-    public async Task<long> Handle(PurchaseGoldenPackageCommand request, CancellationToken ct)
-    {
-        // Initiate payment
-        var paymentResult = await _paymentGateway.InitiatePaymentAsync(new PaymentRequest
-        {
-            UserId = request.UserId,
-            Mobile = user.Mobile,
-            Amount = packagePrice,
-            Description = "خرید بسته طلایی",
-            CallbackUrl = "https://yoursite.com/payment/callback"
-        }, ct);
-
-        if (!paymentResult.IsSuccess)
-        {
-            throw new InvalidOperationException(paymentResult.ErrorMessage);
-        }
-
-        // Create transaction record
-        var transaction = new Transaction
-        {
-            UserId = request.UserId,
-            Type = TransactionType.PackagePurchase,
-            Amount = packagePrice,
-            Status = TransactionStatus.Pending,
-            RefId = paymentResult.RefId,
-            Description = "خرید بسته طلایی"
-        };
-
-        await _context.Transactions.AddAsync(transaction, ct);
-        await _context.SaveChangesAsync(ct);
-
-        // Redirect user to gateway
-        return transaction.Id; // Return transaction ID for frontend to track
-    }
-}
-```
-
-### Verify Payment (Callback)
-
-```csharp
-public class VerifyGoldenPackagePurchaseCommandHandler : IRequestHandler<VerifyGoldenPackagePurchaseCommand>
-{
-    private readonly IPaymentGatewayService _paymentGateway;
-
-    public async Task Handle(VerifyGoldenPackagePurchaseCommand request, CancellationToken ct)
-    {
-        // Verify payment
-        var verifyResult = await _paymentGateway.VerifyPaymentAsync(
-            request.Authority, 
-            request.Authority, 
-            ct);
-
-        if (!verifyResult.IsSuccess)
-        {
-            transaction.Status = TransactionStatus.Failed;
-            transaction.ErrorMessage = verifyResult.Message;
-            throw new InvalidOperationException(verifyResult.Message);
-        }
-
-        // Update transaction
-        transaction.Status = TransactionStatus.Completed;
-        transaction.CompletedAt = DateTime.UtcNow;
-
-        // Activate club membership
-        var clubMembership = new ClubMembership
-        {
-            UserId = transaction.UserId,
-            Status = ClubMembershipStatus.Active,
-            StartDate = DateTime.UtcNow,
-            EndDate = DateTime.UtcNow.AddMonths(1),
-            PurchaseMethod = PackagePurchaseMethod.DirectPurchase
-        };
-
-        await _context.ClubMemberships.AddAsync(clubMembership, ct);
-        await _context.SaveChangesAsync(ct);
-    }
-}
-```
-
-### Process Withdrawal (ProcessPayoutAsync)
-
-```csharp
-public class ProcessWithdrawalCommandHandler : IRequestHandler<ProcessWithdrawalCommand>
-{
-    private readonly IPaymentGatewayService _paymentGateway;
-
-    public async Task Handle(ProcessWithdrawalCommand request, CancellationToken ct)
-    {
-        if (request.IsApproved)
-        {
-            if (payout.WithdrawalMethod == WithdrawalMethod.Diamond)
-            {
-                // Credit user wallet
-                userWallet.DiscountBalance += payout.TotalAmount;
-            }
-            else if (payout.WithdrawalMethod == WithdrawalMethod.Cash)
-            {
-                // Process bank transfer
-                var payoutResult = await _paymentGateway.ProcessPayoutAsync(new PayoutRequest
-                {
-                    UserId = payout.UserId,
-                    Iban = payout.Iban,
-                    Amount = payout.TotalAmount,
-                    Description = $"برداشت کمیسیون هفته {payout.WeekNumber}"
-                }, ct);
-
-                if (payoutResult.IsSuccess)
-                {
-                    payout.Status = CommissionStatus.Withdrawn;
-                    payout.CompletedAt = DateTime.UtcNow;
-                    payout.TransactionId = payoutResult.TransactionId;
-                }
-                else
-                {
-                    payout.Status = CommissionStatus.PaymentFailed;
-                    payout.ErrorMessage = payoutResult.Message;
-                }
-            }
-
-            // Record history
-            await _context.CommissionPayoutHistories.AddAsync(new CommissionPayoutHistory
-            {
-                PayoutId = payout.Id,
-                TransactionType = payout.Status == CommissionStatus.Withdrawn 
-                    ? TransactionType.Withdrawn 
-                    : TransactionType.PaymentFailed,
-                Amount = payout.TotalAmount,
-                ProcessedBy = _currentUserService.UserId,
-                ProcessedAt = DateTime.UtcNow
-            }, ct);
-
-            await _context.SaveChangesAsync(ct);
-        }
-    }
-}
-```
-
----
-
-## 🧪 Testing Guide
-
-### Unit Testing with Mock
-
-```csharp
-[Fact]
-public async Task InitiatePayment_Should_Return_Success_With_Valid_Data()
-{
-    // Arrange
-    var mockLogger = new Mock<ILogger<MockPaymentGatewayService>>();
-    var service = new MockPaymentGatewayService(mockLogger.Object);
-    
-    var request = new PaymentRequest
-    {
-        UserId = 123,
-        Mobile = "09123456789",
-        Amount = 100000,
-        Description = "Test payment",
-        CallbackUrl = "https://test.com/callback"
-    };
-
-    // Act
-    var result = await service.InitiatePaymentAsync(request);
-
-    // Assert
-    Assert.True(result.IsSuccess);
-    Assert.NotNull(result.RefId);
-    Assert.StartsWith("MockRef_", result.RefId);
-    Assert.NotNull(result.GatewayUrl);
-}
-
-[Fact]
-public async Task ProcessPayout_Should_Fail_With_Invalid_IBAN()
-{
-    // Arrange
-    var mockLogger = new Mock<ILogger<MockPaymentGatewayService>>();
-    var service = new MockPaymentGatewayService(mockLogger.Object);
-    
-    var request = new PayoutRequest
-    {
-        UserId = 123,
-        Iban = "INVALID_IBAN",
-        Amount = 50000,
-        Description = "Test payout"
-    };
-
-    // Act
-    var result = await service.ProcessPayoutAsync(request);
-
-    // Assert
-    Assert.False(result.IsSuccess);
-    Assert.Contains("فرمت شماره شبا نامعتبر", result.Message);
-}
-```
-
-### Integration Testing
-
-```csharp
-public class PaymentGatewayIntegrationTests : IClassFixture<WebApplicationFactory<Program>>
-{
-    private readonly HttpClient _client;
-
-    public PaymentGatewayIntegrationTests(WebApplicationFactory<Program> factory)
-    {
-        _client = factory.CreateClient();
-    }
-
-    [Fact]
-    public async Task PurchaseGoldenPackage_Should_Initiate_Payment()
-    {
-        // Arrange
-        var command = new PurchaseGoldenPackageCommand
-        {
-            UserId = 123,
-            PaymentMethod = PackagePurchaseMethod.DirectPurchase
-        };
-
-        // Act
-        var response = await _client.PostAsJsonAsync("/api/package/purchase", command);
-
-        // Assert
-        response.EnsureSuccessStatusCode();
-        var transactionId = await response.Content.ReadFromJsonAsync<long>();
-        Assert.True(transactionId > 0);
-    }
-}
-```
-
----
-
-## 🔒 Security Best Practices
-
-1. **Configuration Security**:
-   - ✅ Store API keys in `appsettings.json` (excluded from git)
-   - ✅ Use Azure Key Vault or AWS Secrets Manager in production
-   - ✅ Never hardcode credentials in code
-
-2. **HTTPS Only**:
-   - ✅ Enforce HTTPS for all payment callbacks
-   - ✅ Validate SSL certificates
-
-3. **Amount Validation**:
-   - ✅ Validate min/max amounts before API call
-   - ✅ Verify amounts match on callback
-
-4. **IBAN Validation**:
-   - ✅ Format: IR + 24 digits = 26 characters
-   - ✅ Validate before payout processing
-
-5. **Idempotency**:
-   - ✅ Use unique OrderId for each payment
-   - ✅ Store RefId to prevent duplicate processing
-
-6. **Error Handling**:
-   - ✅ Never expose internal errors to users
-   - ✅ Log detailed errors for debugging
-   - ✅ Return user-friendly error messages
-
----
-
-## 📊 Monitoring & Logging
-
-### Recommended Logs
-
-```csharp
-// Success
-_logger.LogInformation(
-    "Payment initiated successfully: UserId={UserId}, Amount={Amount}, RefId={RefId}",
-    request.UserId, request.Amount, result.RefId);
-
-// Failure
-_logger.LogError(
-    "Payment initiation failed: UserId={UserId}, Amount={Amount}, Error={Error}",
-    request.UserId, request.Amount, result.ErrorMessage);
-
-// API Error
-_logger.LogError(
-    "Payment gateway API error: StatusCode={StatusCode}, Response={Response}",
-    response.StatusCode, responseContent);
-```
-
-### Sentry Integration
-
-```csharp
-try
-{
-    var result = await _paymentGateway.InitiatePaymentAsync(request, ct);
-}
-catch (Exception ex)
-{
-    SentrySdk.CaptureException(ex, scope =>
-    {
-        scope.SetTag("payment_provider", "Daya");
-        scope.SetExtra("user_id", request.UserId);
-        scope.SetExtra("amount", request.Amount);
-    });
-    throw;
-}
-```
-
----
-
-## 🚀 Production Deployment Checklist
-
-- [ ] Obtain Daya API credentials (BaseUrl + ApiKey)
-- [ ] Obtain Bank Mellat credentials (TerminalId, Username, Password)
-- [ ] Test in sandbox environment
-- [ ] Update `appsettings.Production.json` with credentials
-- [ ] Set `UseRealPaymentGateway = true`
-- [ ] Configure HTTPS callback URLs
-- [ ] Set up monitoring (Sentry/Application Insights)
-- [ ] Configure retry policies (Polly)
-- [ ] Test full payment flow (Initiate → Callback → Verify)
-- [ ] Test withdrawal flow (Request → Approve → Payout)
-- [ ] Document production URLs and credentials (secure location)
-
----
-
-## 📞 Support & Troubleshooting
-
-### Common Issues
-
-**Issue**: "Payment gateway API error: 401 Unauthorized"
-- **Solution**: Check API key in `appsettings.json`, verify credentials
-
-**Issue**: "IBAN validation failed"
-- **Solution**: Ensure IBAN starts with "IR" and is exactly 26 characters
-
-**Issue**: "Bank Mellat returns negative RefId"
-- **Solution**: Check error code mapping, verify TerminalId/Username/Password
-
-**Issue**: "HttpClient timeout"
-- **Solution**: Increase timeout in `ConfigureServices.cs`, check network connectivity
-
----
-
-## 📚 References
-
-- [Daya API Documentation](https://api.daya.ir/docs) (placeholder)
-- [Bank Mellat IPG Guide](https://bpm.shaparak.ir/) (official)
-- [Shaparak Paya Documentation](https://www.shaparak.ir/)
-- [ISO 8601 Week Numbering](https://en.wikipedia.org/wiki/ISO_8601)
-
----
-
-**Last Updated**: 2024-12-02  
-**Version**: 1.0  
-**Status**: ✅ Production Ready

cms/system-constants.md

@@ -1,120 +0,0 @@
-# 🔧 SystemConstants - مقادیر ثابت سیستم
-
-> **فایل**: `CMSMicroservice.Domain/Common/SystemConstants.cs`  
-> **آخرین بروزرسانی**: ۷ دی ۱۴۰۴
-
----
-
-## 📋 هدف
-
-این کلاس شامل تمام مقادیر ثابت سیستم است که در چندین جای مختلف استفاده می‌شوند.
-به جای hardcode کردن اعداد در کد، از این ثابت‌ها استفاده کنید.
-
----
-
-## 📊 مقادیر موجود
-
-### Club Configuration
-
-| ثابت | مقدار | توضیح |
-|------|-------|-------|
-| `ClubJoiningPercentage` | 0.35 (35%) | درصد کمیسیون پیوستن به باشگاه |
-| `ClubActivationThreshold` | 0.5 (50%) | آستانه فعال‌سازی باشگاه |
-
-### Commission Configuration
-
-| ثابت | مقدار | توضیح |
-|------|-------|-------|
-| `MaxCalculationAttempts` | 3 | حداکثر تلاش برای محاسبه کمیسیون |
-| `DefaultCommissionPoolDays` | 7 | تعداد روزهای استخر کمیسیون |
-
-### Package Amounts
-
-| ثابت | مقدار | توضیح |
-|------|-------|-------|
-| `GoldenPackageAmount` | 56,000,000 | مبلغ پکیج طلایی (56 میلیون ریال) |
-| `DayaLoanAmount` | 56,000,000 | مبلغ وام دایا (56 میلیون ریال) |
-
----
-
-## 💻 کد
-
-```csharp
-namespace CMSMicroservice.Domain.Common;
-
-/// <summary>
-/// مقادیر ثابت سیستم که در چند جای مختلف استفاده می‌شوند
-/// </summary>
-public static class SystemConstants
-{
-    // Club Configuration
-    public const decimal ClubJoiningPercentage = 0.35m;    // 35% کمیسیون پیوستن به باشگاه
-    public const decimal ClubActivationThreshold = 0.5m;   // 50% آستانه فعال‌سازی
-    
-    // Commission Configuration
-    public const int MaxCalculationAttempts = 3;           // حداکثر تلاش محاسبه
-    public const int DefaultCommissionPoolDays = 7;        // روزهای استخر کمیسیون
-    
-    // Package Amounts
-    public const long GoldenPackageAmount = 56_000_000;    // 56 میلیون - پکیج طلایی
-    public const long DayaLoanAmount = 56_000_000;         // 56 میلیون - وام دایا
-}
-```
-
----
-
-## 🔍 نحوه استفاده
-
-### در Handler ها:
-
-```csharp
-using CMSMicroservice.Domain.Common;
-
-public class ProcessDayaLoanApprovalCommandHandler
-{
-    public async Task<Unit> Handle(...)
-    {
-        // به جای: var amount = 56_000_000;
-        var amount = SystemConstants.DayaLoanAmount;
-        
-        await DepositToWallet(userId, amount);
-    }
-}
-```
-
-### در Validation ها:
-
-```csharp
-public class ValidateGoldenPackagePurchaseQueryHandler
-{
-    public async Task<bool> Handle(...)
-    {
-        var requiredAmount = SystemConstants.GoldenPackageAmount;
-        return user.WalletBalance >= requiredAmount;
-    }
-}
-```
-
----
-
-## ⚠️ قوانین
-
-1. **همیشه از ثابت‌ها استفاده کنید** - هرگز مقادیر magic number در کد ننویسید
-2. **تغییر مقادیر** - برای تغییر یک مقدار، فقط این فایل را تغییر دهید
-3. **ثابت‌های جدید** - اگر مقداری در بیش از یک جا استفاده می‌شود، به این فایل اضافه کنید
-4. **نام‌گذاری** - از نام‌های توصیفی استفاده کنید (مثلاً `GoldenPackageAmount` نه `Amount1`)
-
----
-
-## 📁 فایل‌های مرتبط
-
-- `SmsTemplates.cs` - قالب‌های پیامک
-- `ProcessDayaLoanApprovalCommandHandler.cs` - استفاده از DayaLoanAmount
-- `ValidateGoldenPackagePurchaseQueryHandler.cs` - استفاده از GoldenPackageAmount
-
----
-
-## 🔗 Related Docs
-
-- [email-sms-configuration.md](email-sms-configuration.md) - تنظیمات SMS و قالب‌ها
-- [CHANGELOG-2025-12-27.md](../../CHANGELOG-2025-12-27.md) - تاریخچه تغییرات

deployment/CICD-PIPELINE-GUIDE.md

@@ -1,418 +0,0 @@
-# 🔧 راهنمای CI/CD Pipeline — Gitea Actions + K3s
-
-> آخرین بروزرسانی: February 11, 2026
-
----
-
-## 📐 معماری کلی
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  K3s Cluster (194.5.195.53)                             │
-│                                                         │
-│  ┌─────────────────────────────────────────────────┐    │
-│  │  gitea-runner Pod (2 containers)                 │    │
-│  │                                                  │    │
-│  │  ┌──────────────────┐  ┌──────────────────────┐ │    │
-│  │  │  docker (DinD)   │  │  runner (act_runner)  │ │    │
-│  │  │  docker:dind      │  │  gitea/act_runner    │ │    │
-│  │  │  privileged: true │  │  DOCKER_HOST=        │ │    │
-│  │  │  port: 2375       │  │  tcp://localhost:2375│ │    │
-│  │  └──────────────────┘  └──────────────────────┘ │    │
-│  │       ▲ shared volumes: docker-storage           │    │
-│  └─────────────────────────────────────────────────┘    │
-│                                                         │
-│  ┌─────────────┐  ┌───────────┐  ┌────────────────┐    │
-│  │  Gitea       │  │  Nexus    │  │  Docker Reg.   │    │
-│  │  :3000       │  │  :32081   │  │  :32082 (pull) │    │
-│  │              │  │  (NuGet)  │  │  :30080 (push) │    │
-│  └─────────────┘  └───────────┘  └────────────────┘    │
-└─────────────────────────────────────────────────────────┘
-```
-
-### سه لایه Docker-in-Docker:
-```
-K3s containerd (لایه ۱)
-  └── gitea-runner Pod → docker container (DinD daemon) (لایه ۲)
-        └── workflow: docker run / docker build (لایه ۳)
-```
-
----
-
-## 📁 فایل‌های Workflow
-
-### 🐳 K8s Pipelines (Docker + K3s) — آفلاین
-
-| سرویس | فایل | Branch | Image | Deploy |
-|--------|------|--------|-------|--------|
-| CMS | `kub-deploy.yml` | `kub-stage` | `admin/cms` | SSH → kubectl |
-| BackOffice | `kub-deploy.yml` | `kub-stage` | `admin/backoffice` | SSH → kubectl |
-| FrontOffice | `kub-deploy.yml` | `kub-stage` | `admin/frontoffice` | SSH → kubectl |
-| CMS | `prod-deploy.yml` | `production` | `admin/cms:prod` | SSH → kubectl |
-| BackOffice | `prod-deploy.yml` | `production` | `admin/backoffice:prod` | SSH → kubectl |
-| FrontOffice | `prod-deploy.yml` | `production` | `admin/frontoffice:prod` | SSH → kubectl |
-
-### 🪟 Windows/IIS Pipelines (Legacy) — آنلاین
-
-| سرویس | فایل | Branch | Target |
-|--------|------|--------|--------|
-| CMS | `cms-stage.yml` | `stage_new` | IIS → `cms.kbs1.ir` |
-| BackOffice | `bo-stage.yml` | `stage-new` | IIS → `admin.kbs1.ir` |
-| FrontOffice | `fo-stage.yml` | `stage-new` | IIS → `kbs1.ir` |
-
-> ⚠️ Stage pipeline ها از Windows runner + IIS استفاده میکنن و Docker ندارن.
-
-### ساختار مشترک Pipeline:
-```
-1. Start Docker daemon (DinD)
-2. Checkout code (git clone)
-3. Login to Docker registries (32082 + 30080)
-4. [CMS only] Publish Protobuf packages
-5. Build Docker Image
-6. Push to Registry
-7. Deploy to Kubernetes (SSH → kubectl rollout restart)
-```
-
----
-
-## 🐛 مشکلات حل‌شده و راه‌حل‌ها
-
-### مشکل ۱: `iptables failed: Permission denied`
-
-**خطا:**
-```
-iptables v1.8.10 (nf_tables): Could not fetch rule set generation id: Permission denied
-```
-
-**علت:** K3s containerd به Docker daemon اجازه تغییر iptables نمیده.
-
-**راه‌حل:** غیرفعال کردن networking در dockerd:
-```bash
-dockerd --iptables=false --ip6tables=false --bridge=none --storage-driver=vfs &
-```
-
-> ⚠️ با `--bridge=none` نیاز به شبکه‌سازی Docker نیست چون فقط build و push انجام میشه.
-
----
-
-### مشکل ۲: `failed to unmount overlayfs: operation not permitted`
-
-**خطا:**
-```
-failed to register layer: unshare: operation not permitted
-```
-
-**علت:** `overlay2` storage driver نیاز به mount namespace داره که داخل K3s مجاز نیست.
-
-**راه‌حل:** استفاده از `vfs` storage driver:
-```bash
-dockerd --storage-driver=vfs &
-```
-
-> ⚠️ `vfs` کندتره ولی هیچ mount syscall خاصی نیاز نداره. برای CI/CD کافیه.
-
----
-
-### مشکل ۳: `no basic auth credentials` هنگام pull ایمیج
-
-**خطا:**
-```
-Error response from daemon: Head "https://194.5.195.53:32082/v2/dotnet/sdk/manifests/9.0": 
-no basic auth credentials
-```
-
-**علت:** `docker login` فقط قبل از push انجام میشد، ولی `docker build` (یا `docker run`) هم از `32082` ایمیج pull میکنه.
-
-**راه‌حل:** اضافه کردن step "Login to Docker registries" بلافاصله بعد از Checkout:
-```yaml
-- name: Login to Docker registries
-  run: |
-    echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login 194.5.195.53:32082 -u admin --password-stdin
-    echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login ${{ env.REGISTRY }} -u admin --password-stdin
-```
-
----
-
-### مشکل ۴: `unshare: operation not permitted` هنگام extract لایه‌ها
-
-**خطا:**
-```
-docker: failed to register layer: unshare: operation not permitted
-```
-
-**علت اصلی (دو بخش):**
-
-**بخش ۱:** Gitea act_runner دیفالت `container.privileged: false` داره. یعنی job container ها بدون privileged ساخته میشن — حتی اگه workflow بنویسه `options: --privileged`.
-
-**بخش ۲:** env var `CONFIG_FILE` در runner container ست نبود → `run.sh` فلگ `--config` رو به `act_runner daemon` پاس نمیداد → config.yaml اصلاً لود نمیشد!
-
-**راه‌حل (سمت سرور):**
-
-۱. ساخت ConfigMap:
-```yaml
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: runner-config
-  namespace: default
-data:
-  config.yaml: |
-    log:
-      level: info
-    runner:
-      file: .runner
-      capacity: 1
-      timeout: 3h
-    container:
-      privileged: true
-      options: "--security-opt seccomp=unconfined --security-opt apparmor=unconfined"
-      valid_volumes:
-        - "**"
-```
-
-۲. Mount کردن در Deployment + env var:
-```bash
-kubectl patch deployment gitea-runner --type=json -p='[
-  {"op":"add","path":"/spec/template/spec/containers/1/env/-",
-   "value":{"name":"CONFIG_FILE","value":"/data/config.yaml"}},
-  {"op":"add","path":"/spec/template/spec/containers/1/volumeMounts/-",
-   "value":{"name":"runner-config","mountPath":"/data/config.yaml","subPath":"config.yaml"}},
-  {"op":"add","path":"/spec/template/spec/volumes/-",
-   "value":{"name":"runner-config","configMap":{"name":"runner-config"}}}
-]'
-```
-
-> ⚠️ **نکته مهم:** بدون `CONFIG_FILE=/data/config.yaml` env var، فایل `run.sh` داخل act_runner image فلگ `--config` رو پاس نمیده!
-
----
-
-### مشکل ۵: Protobuf restore از nuget.org بجای Nexus
-
-**علت:** `dotnet restore` بدون `--configfile` از دیفالت NuGet sources استفاده میکنه.
-
-**راه‌حل:**
-```bash
-dotnet restore "$proj" --configfile src/NuGet.config
-```
-
----
-
-### مشکل ۶: عدم دسترسی شبکه با `--bridge=none`
-
-**علت:** `dockerd --bridge=none` شبکه Docker bridge رو غیرفعال میکنه. در نتیجه container هایی که با `docker run` یا `docker build` ساخته میشن، دسترسی شبکه ندارن (مثلاً `dotnet restore` نمیتونه به Nexus وصل بشه).
-
-**راه‌حل:** استفاده از `--network host` در `docker run` و `docker build`:
-```bash
-# Protobuf step
-docker run --rm --network host -v $(pwd):/src -w /src ...
-
-# Build step
-DOCKER_BUILDKIT=0 docker build --network host -t ... .
-```
-
----
-
-### مشکل ۷: `failed to prepare ... as ...: invalid argument` (BuildKit)
-
-**خطا:**
-```
-ERROR: failed to build: failed to solve: failed to prepare xxx as yyy: invalid argument
-```
-
-**علت:** BuildKit (بیلدر پیش‌فرض Docker ≥23) از snapshotter overlay استفاده میکنه که با `--storage-driver=vfs` سازگاری نداره.
-
-**راه‌حل:** غیرفعال کردن BuildKit:
-```bash
-DOCKER_BUILDKIT=0 docker build --network host -t ... .
-```
-
-> ⚠️ Legacy builder از vfs بدون مشکل استفاده میکنه.
-
----
-
-## 🔄 تغییرات prod-deploy (قدیم → جدید)
-
-| مورد | قدیم (prod-deploy) | جدید |
-|------|-------------------|------|
-| Container image | `docker:latest` | `docker-sshpass:latest` (شامل sshpass + git) |
-| Proxy | `HTTP_PROXY` + `HTTPS_PROXY` | حذف شد (آفلاین) |
-| Registry | `gitea-svc:3000` + external | فقط `194.5.195.53:30080` |
-| kubectl | `apk add` + `curl` از اینترنت | SSH → `kubectl` مستقیم روی سرور |
-| Auth | hardcoded password | `secrets.REGISTRY_PASSWORD` + `secrets.SERVER_PASSWORD` |
-| BuildKit | فعال (دیفالت) | `DOCKER_BUILDKIT=0` |
-| Network | Docker bridge (دیفالت) | `--network host` |
-| dockerd | دیفالت | `--iptables=false --ip6tables=false --bridge=none --storage-driver=vfs` |
-| Deploy | `KUBECONFIG_PROD` (base64) | SSH + sshpass (مثل kub-stage) |
-
-> ✅ حالا همه ۶ K8s pipeline (۳ stage + ۳ prod) از **یک الگوی مشترک آفلاین** استفاده میکنن.
-
----
-
-containers:
-  - name: docker          # DinD sidecar
-    image: 194.5.195.53:32082/docker:dind
-    securityContext:
-      privileged: true
-    env:
-      - DOCKER_TLS_CERTDIR: ""
-    volumeMounts:
-      - /var/lib/docker → docker-storage
-      - /etc/docker/daemon.json → docker-config (ConfigMap)
-
-  - name: runner          # Gitea act_runner
-    image: 194.5.195.53:32082/gitea/act_runner:latest
-    env:
-      - GITEA_INSTANCE_URL: http://gitea-svc:3000
-      - DOCKER_HOST: tcp://localhost:2375
-      - CONFIG_FILE: /data/config.yaml    # ← حیاتی! بدون این runner config لود نمیشه
-    volumeMounts:
-      - /data → runner-data
-      - /data/config.yaml → runner-config (ConfigMap)
-```
-
-### ConfigMaps:
-| نام | محتوا | Mount Path |
-|-----|-------|------------|
-| `docker-daemon-config` | `daemon.json` با insecure-registries | `/etc/docker/daemon.json` |
-| `runner-config` | `config.yaml` با privileged + seccomp | `/data/config.yaml` |
-
-### Labels (ثبت‌شده در Gitea):
-```
-ubuntu-latest → docker://docker.gitea.com/runner-images:ubuntu-latest
-ubuntu-24.04  → docker://docker.gitea.com/runner-images:ubuntu-24.04
-ubuntu-22.04  → docker://docker.gitea.com/runner-images:ubuntu-22.04
-```
-
----
-
-## 🔑 Secrets مورد نیاز (Gitea → Settings → Secrets)
-
-| Secret | استفاده |
-|--------|---------|
-| `REGISTRY_PASSWORD` | پسورد Docker registry (admin) |
-| `SERVER_PASSWORD` | پسورد SSH سرور (root) |
-
----
-
-## 🔧 dockerd فلگ‌های نهایی
-
-```bash
-dockerd --iptables=false --ip6tables=false --bridge=none --storage-driver=vfs &
-```
-
-| Flag | دلیل |
-|------|-------|
-| `--iptables=false` | K3s اجازه تغییر iptables نمیده |
-| `--ip6tables=false` | مشابه بالا برای IPv6 |
-| `--bridge=none` | نیازی به Docker bridge network نیست |
-| `--storage-driver=vfs` | overlay2 نمیتونه mount کنه داخل K3s |
-
----
-
-## 🔍 عیب‌یابی Pipeline
-
-### ۱. چک وضعیت Runner:
-```bash
-# SSH به سرور
-ssh root@194.5.195.53
-
-# آیا runner pod بالاست؟
-kubectl get pods -l app=gitea-runner
-
-# لاگ runner
-kubectl logs <pod-name> -c runner --tail=30
-
-# لاگ DinD
-kubectl logs <pod-name> -c docker --tail=30
-```
-
-### ۲. تست Docker داخل Runner:
-```bash
-# exec به DinD container
-kubectl exec <pod-name> -c docker -- docker info
-
-# آیا registry قابل دسترسیه؟
-kubectl exec <pod-name> -c docker -- docker pull 194.5.195.53:32082/dotnet/sdk:9.0
-```
-
-### ۳. چک config runner:
-```bash
-# آیا config.yaml mount شده؟
-kubectl exec <pod-name> -c runner -- cat /data/config.yaml
-
-# آیا privileged فعاله؟
-kubectl exec <pod-name> -c docker -- docker inspect <job-container> \
-  --format '{{.HostConfig.Privileged}} {{.HostConfig.SecurityOpt}}'
-```
-
-### ۴. ری‌استارت runner:
-```bash
-kubectl rollout restart deployment/gitea-runner
-kubectl rollout status deployment/gitea-runner --timeout=120s
-```
-
----
-
-## 📋 Workflow Template (کامل)
-
-```yaml
-name: Build and Deploy to Kubernetes
-
-on:
-  push:
-    branches:
-      - kub-stage
-
-env:
-  REGISTRY: 194.5.195.53:30080
-  IMAGE_NAME: admin/<service-name>
-  K8S_SERVER: 194.5.195.53
-
-jobs:
-  build-and-deploy:
-    runs-on: ubuntu-latest
-    container:
-      image: 194.5.195.53:32082/docker-sshpass:latest
-      options: --privileged
-    steps:
-      - name: Start Docker daemon
-        run: |
-          mkdir -p /etc/docker
-          cat > /etc/docker/daemon.json << 'DAEMON'
-          {
-            "insecure-registries": ["194.5.195.53:30080", "194.5.195.53:32500", "194.5.195.53:32082"]
-          }
-          DAEMON
-          dockerd --iptables=false --ip6tables=false --bridge=none --storage-driver=vfs &
-          for i in $(seq 1 90); do
-            if docker info >/dev/null 2>&1; then
-              echo "✅ Docker ready"; break
-            fi
-            sleep 2
-          done
-
-      - name: Checkout code
-        run: |
-          git clone --depth 1 --branch kub-stage http://gitea-svc:3000/admin/<repo>.git .
-
-      - name: Login to Docker registries
-        run: |
-          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login 194.5.195.53:32082 -u admin --password-stdin
-          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login ${{ env.REGISTRY }} -u admin --password-stdin
-
-      - name: Build Docker Image
-        run: |
-          DOCKER_BUILDKIT=0 docker build --network host -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest .
-
-      - name: Push to Registry
-        run: |
-          docker push ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
-
-      - name: Deploy to Kubernetes
-        run: |
-          export SSHPASS="${{ secrets.SERVER_PASSWORD }}"
-          sshpass -e ssh -o StrictHostKeyChecking=no root@${{ env.K8S_SERVER }} "
-            kubectl rollout restart deployment/<service>
-            kubectl rollout status deployment/<service> --timeout=180s
-          "
-```

deployment/INFRASTRUCTURE-GUIDE.md

@@ -1,510 +0,0 @@
-# FourSat Infrastructure Deployment Guide
-
-## 📌 Server Information
-
-| Item | Value |
-|------|-------|
-| Server IP | `194.5.195.53` |
-| SSH Access | `root / 87zH26nbqT` |
-| Kubernetes | K3s with local-path storage |
-| ServiceLB | K3s svclb (built-in) |
-
----
-
-## 🗄️ Database (MSSQL Server 2022)
-
-| Item | Value |
-|------|-------|
-| Image | `mssql/server:2022-CU16` |
-| Nexus Image | `194.5.195.53:32082/mcr.microsoft.com/mssql/server:2022-CU16` |
-| SA Password | `87zH26nbqT` |
-| Service | `mssql-svc:1433` |
-| PVC | `mssql-pvc` (10Gi) |
-
-### Databases:
-- `gitea` - Gitea metadata
-- `Foursat` - Application database
-- `Hosein` - Application database
-
-### Connection String:
-```
-Server=mssql-svc,1433;Database=Foursat;User Id=sa;Password=87zH26nbqT;TrustServerCertificate=true
-```
-
----
-
-## 📦 Git Server (Gitea)
-
-| Item | Value |
-|------|-------|
-| Image | `gitea/gitea:1.25.3` |
-| Nexus Image | `194.5.195.53:32082/gitea/gitea:1.25.3` |
-| Admin User | `admin` |
-| Admin Email | `admin@afrino.co` |
-| Service | `gitea-svc:3000` |
-| PVC | `gitea-pvc` (10Gi) |
-| Database | MSSQL (`gitea` database) |
-
-### Repositories:
-- `admin/cms.git`
-- `admin/backoffice.git`
-- `admin/backoffice.bff.git`
-- `admin/frontoffice.git`
-- `admin/frontoffice.bff.git`
-- `admin/docs.git`
-
----
-
-## 📚 Package Registry (Nexus)
-
-| Item | Value |
-|------|-------|
-| Image | `sonatype/nexus3:3.38.0` |
-| UI Port | `32081` (NodePort) |
-| Docker Registry Port | `32082` (NodePort, HTTP) |
-| PVC | `nexus-data-pvc` (50Gi) |
-
-### Usage:
-```bash
-# Tag and push image
-ctr -n k8s.io images tag <source> 194.5.195.53:32082/<name>:<tag>
-ctr -n k8s.io images push --plain-http 194.5.195.53:32082/<name>:<tag>
-
-# List images
-curl http://194.5.195.53:32082/v2/_catalog
-```
-
----
-
-## 🌐 Ingress (ingress-nginx)
-
-| Item | Value |
-|------|-------|
-| Image | `registry.k8s.io/ingress-nginx/controller:v1.14.1` |
-| Nexus Image | `194.5.195.53:32082/registry.k8s.io/ingress-nginx/controller:v1.14.1` |
-| HTTP Port | `80` |
-| HTTPS Port | `443` |
-
-### ⚠️ CRITICAL WARNING:
-**DO NOT use `hostNetwork: true` with K3s svclb!**
-
-K3s uses svclb (ServiceLB) for LoadBalancer services. If you add `hostNetwork: true`:
-- Both svclb pods AND ingress-nginx pods will try to bind to ports 80/443
-- This causes conflicts and connection failures
-- svclb is already exposing ports correctly
-
-See: `deployment/docs/INGRESS-NGINX-WARNING.md`
-
----
-
-## 💾 Persistent Volume Claims
-
-| PVC Name | Size | Status | Reclaim Policy |
-|----------|------|--------|----------------|
-| `mssql-pvc` | 10Gi | Bound | Retain |
-| `gitea-pvc` | 10Gi | Bound | Retain |
-| `nexus-data-pvc` | 50Gi | Bound | Retain |
-| `seq-pvc` | 5Gi | Bound | Retain |
-
-### Storage Location (K3s local-path):
-```
-/var/lib/rancher/k3s/storage/pvc-<uuid>_default_<pvc-name>/
-```
-
----
-
-## 🔄 Backup Strategy
-
-### Automatic Backup (CronJob):
-- Runs daily at 2:00 AM
-- Backs up: gitea, Foursat, Hosein databases
-- Retention: 7 days
-- Location: `/backups/` on mssql-pvc
-
-### Manual Backup:
-```bash
-# Trigger manual backup
-kubectl create job --from=cronjob/mssql-backup mssql-backup-manual-$(date +%s)
-
-# Or apply the manual job
-kubectl apply -f k8s-manifests/mssql-backup-cronjob.yaml
-```
-
-### Restore Database:
-```bash
-# Exec into MSSQL pod
-kubectl exec -it deploy/mssql -- /bin/bash
-
-# Restore
-/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P '87zH26nbqT' -C -Q "RESTORE DATABASE [Foursat] FROM DISK = '/backups/Foursat_YYYYMMDD_HHMMSS.bak' WITH REPLACE"
-```
-
----
-
-## 🚀 Deployment Commands
-
-### Deploy All:
-```bash
-# Apply manifests
-kubectl apply -f k8s-manifests/mssql-deployment.yaml
-kubectl apply -f k8s-manifests/gitea-deployment.yaml
-kubectl apply -f k8s-manifests/nexus-deployment.yaml
-kubectl apply -f k8s-manifests/mssql-backup-cronjob.yaml
-```
-
-### Check Status:
-```bash
-kubectl get pods
-kubectl get pvc
-kubectl get svc
-```
-
-### View Logs:
-```bash
-kubectl logs -f deploy/mssql
-kubectl logs -f deploy/gitea
-kubectl logs -f deploy/nexus
-```
-
----
-
-## 🔐 Credentials Summary
-
-| Service | Username | Password |
-|---------|----------|----------|
-| Server SSH | root | 87zH26nbqT |
-| MSSQL | sa | 87zH26nbqT |
-| Gitea | admin | (set during install) |
-
----
-
-## 📋 Troubleshooting
-
-### MSSQL Not Starting:
-1. Check if volumeMounts exists in deployment
-2. Verify password matches stored in database
-3. Use single-user mode to reset password if needed
-
-### Gitea Shows Install Page:
-1. Check if volumeMounts exists (must mount to `/data`)
-2. Verify MSSQL is running and accessible
-3. Check `/data/gitea/conf/app.ini` for database config
-
-### Images Not Pulling:
-1. Ensure Nexus is running
-2. For K3s, add to `/etc/rancher/k3s/registries.yaml`:
-```yaml
-mirrors:
-  "194.5.195.53:32082":
-    endpoint:
-      - "http://194.5.195.53:32082"
-```
-
----
-
-## 📦 Images in Nexus Registry
-
-| Image | Tag | Purpose |
-|-------|-----|---------|
-| `gitea/gitea` | `1.25.3`, `latest` | Git server |
-| `gitea/act_runner` | `0.2.11`, `latest` | CI/CD runner |
-| `mcr.microsoft.com/mssql/server` | `2022-CU16` | Database |
-| `registry.k8s.io/ingress-nginx/controller` | `v1.14.1` | Ingress |
-
-List all images:
-```bash
-curl -s http://194.5.195.53:32082/v2/_catalog
-```
-
----
-
-*Last Updated: 2025-01-18*
-
-
----
-
-# وضعیت استقرار فعلی
-
-# ✅ FourSat Offline Deployment - Complete Status
-
-## 📦 Available Package & Image Repositories
-
-### 1. Docker Registry (Primary - Already Working)
-**Location:** `194.5.195.53:32500`  
-**Status:** ✅ **Active & Working**  
-**Purpose:** Docker image caching for Kubernetes
-
-**Cached Images:**
-```
-✅ nginx:alpine                → localhost:32500/nginx:alpine
-✅ dotnet/aspnet:9.0          → localhost:32500/dotnet/aspnet:9.0
-✅ dotnet/sdk:9.0             → localhost:32500/dotnet/sdk:9.0
-```
-
-**Storage:** 881MB in `/var/lib/registry`
-
-**Usage:**
-```bash
-# Pull from local registry
-crictl pull 194.5.195.53:32500/nginx:alpine
-crictl pull 194.5.195.53:32500/dotnet/aspnet:9.0
-crictl pull 194.5.195.53:32500/dotnet/sdk:9.0
-
-# Or with docker
-docker pull 194.5.195.53:32500/nginx:alpine
-```
-
----
-
-### 2. Nexus Repository Manager (Newly Deployed)
-**Location:** `https://nexus.se.kbs1.ir` (194.5.195.53:32081)  
-**Status:** ✅ **Active & Configured**  
-**Purpose:** NuGet package caching + Docker images (future)
-
-#### NuGet Repositories (✅ Ready)
-- **nuget-all** (Group) - https://nexus.se.kbs1.ir/repository/nuget-all/index.json
-  - Combines: nuget-org-proxy + foursat-nuget-hosted
-  - **Use this in all projects** ← Already configured!
-  
-- **nuget-org-proxy** (Proxy) - Caches packages from nuget.org
-- **foursat-nuget-hosted** (Hosted) - For private packages
-
-#### Docker Repositories (🚧 Configured but not yet populated)
-- **docker-all** (Group) - Port 32084
-  - Combines: docker-hosted + docker-hub-proxy
-  
-- **docker-hosted** (Hosted) - Port 32082
-- **docker-hub-proxy** (Proxy) - Port 32083
-
-**Note:** Docker registry ports in Nexus are not yet externally accessible. Currently using the standalone Docker Registry (32500) instead.
-
----
-
-## 🔧 Current Configuration
-
-### Projects Using Nexus for NuGet
-All NuGet.config files updated to use Nexus as primary source:
-
-```xml
-<packageSources>
-  <clear />
-  <add key="Nexus" value="https://nexus.se.kbs1.ir/repository/nuget-all/index.json" />
-  <!-- Fallback: Direct Gitea -->
-  <add key="FourSat" value="https://git.afrino.co/api/packages/FourSat/nuget/index.json" />
-  <add key="Afrino" value="https://git.afrino.co/api/packages/Afrino/nuget/index.json" />
-</packageSources>
-```
-
-**Updated files:**
-- ✅ BackOffice/src/BackOffice/NuGet.config
-- ✅ BackOffice.BFF/src/BackOffice.BFF.WebApi/NuGet.config
-- ✅ FrontOffice/src/FrontOffice.Main/NuGet.config
-- ✅ FrontOffice.BFF/src/FrontOffice.BFF.WebApi/NuGet.config
-
-### Dockerfiles Using Local Registry
-All Dockerfiles updated to pull from local registry:
-
-```dockerfile
-# Before
-FROM mcr.microsoft.com/dotnet/aspnet:9.0
-
-# After
-FROM 194.5.195.53:32500/dotnet/aspnet:9.0
-```
-
-**Updated files:**
-- ✅ BackOffice/src/BackOffice/Dockerfile
-- ✅ BackOffice.BFF/src/BackOffice.BFF.WebApi/Dockerfile
-- ✅ FrontOffice/src/FrontOffice.Main/Dockerfile
-- ✅ FrontOffice.BFF/src/FrontOffice.BFF.WebApi/Dockerfile
-- ✅ CMS/Dockerfile
-
-### Workflows Using Insecure Registry
-All Gitea Actions workflows configured for local registry:
-
-```yaml
-jobs:
-  build:
-    container:
-      image: 194.5.195.53:32500/dotnet/sdk:9.0
-      options: --add-host=host.docker.internal:host-gateway
-```
-
-**Updated files:**
-- ✅ .gitea/workflows/backoffice-build.yml
-- ✅ .gitea/workflows/backoffice-bff-build.yml
-- ✅ .gitea/workflows/frontoffice-build.yml
-- ✅ .gitea/workflows/frontoffice-bff-build.yml
-- ✅ .gitea/workflows/cms-build.yml
-
----
-
-## 🚀 How It Works
-
-### NuGet Package Workflow
-1. **First restore:** `dotnet restore`
-   - Downloads packages from nuget.org **via Nexus proxy**
-   - Nexus caches packages locally
-   
-2. **Subsequent restores:**
-   - Served from Nexus cache
-   - **No internet required!** ✅
-
-### Docker Image Workflow
-1. **Build time:**
-   ```dockerfile
-   FROM 194.5.195.53:32500/dotnet/aspnet:9.0
-   ```
-   - Pulls from local Docker Registry
-   - **No internet required!** ✅
-
-2. **Runtime (Kubernetes):**
-   ```yaml
-   image: 194.5.195.53:32500/nginx:alpine
-   ```
-   - Pulls from local registry
-   - **No internet required!** ✅
-
----
-
-## 📊 Storage Usage
-
-| Service | Storage Path | Size | Purpose |
-|---------|--------------|------|---------|
-| Docker Registry | `/var/lib/registry` | 881 MB | Cached Docker images |
-| Nexus | `/var/lib/nexus` | ~700 MB | NuGet packages + metadata |
-| Containerd | `/var/lib/containerd` | ~2.4 GB | K8s runtime images |
-
-**Total offline assets:** ~4 GB
-
----
-
-## 🎯 Benefits Achieved
-
-### ✅ Complete Offline Capability
-- Docker images cached locally
-- NuGet packages cached after first download
-- No repeated downloads from internet
-- Faster builds and deployments
-
-### ✅ Bandwidth Savings
-- Each dotnet/sdk:9.0 pull: 859 MB saved
-- Each dotnet/aspnet:9.0 pull: 227 MB saved  
-- Each NuGet package: downloaded once, cached forever
-
-### ✅ Build Speed Improvements
-- Local registry: ~10x faster than Docker Hub
-- Cached NuGet packages: ~5x faster restores
-- CI/CD builds complete in minutes, not hours
-
-### ✅ Reliability
-- No dependency on external services
-- Works even when internet is down
-- Consistent build environment
-
----
-
-## 🔍 Verification Commands
-
-### Check Docker Registry
-```bash
-# List images in registry
-curl -s http://194.5.195.53:32500/v2/_catalog | python3 -m json.tool
-
-# Check storage
-ssh root@194.5.195.53 "du -sh /var/lib/registry"
-```
-
-### Check Nexus NuGet
-```bash
-# Test NuGet connectivity
-dotnet nuget list source
-
-# Test package download
-dotnet add package Newtonsoft.Json
-```
-
-### Check Nexus UI
-```bash
-# Open in browser
-https://nexus.se.kbs1.ir
-
-# Login: admin / 87zH26nbqT
-# Browse → docker-hosted (for future Docker images)
-# Browse → nuget-org-proxy (for cached NuGet packages)
-```
-
----
-
-## 🛠️ Maintenance
-
-### Add New Docker Image to Local Registry
-```bash
-# On server with internet (172.19.101.100)
-docker pull <new-image>
-docker save <new-image> -o /tmp/new-image.tar
-
-# Transfer to main server
-scp /tmp/new-image.tar root@194.5.195.53:/tmp/
-
-# On main server (194.5.195.53)
-ctr -n k8s.io images import /tmp/new-image.tar
-ctr -n k8s.io images tag <new-image> 194.5.195.53:32500/<new-image>
-ctr -n k8s.io images push --plain-http 194.5.195.53:32500/<new-image>
-```
-
-### Clear NuGet Cache (if needed)
-```bash
-# Via Nexus UI
-Settings → Repository → Repositories → nuget-org-proxy → Repair - Invalidate cache
-
-# Or delete and recreate repository
-```
-
-### Backup Cached Assets
-```bash
-# Docker Registry
-tar -czf docker-registry-backup.tar.gz /var/lib/registry/
-
-# Nexus
-kubectl scale deployment nexus --replicas=0
-tar -czf nexus-backup.tar.gz /var/lib/nexus/
-kubectl scale deployment nexus --replicas=1
-```
-
----
-
-## 📝 Files Created/Modified
-
-### Deployment Files
-- ✅ `deployment/docker-registry-k8s.yaml` - Docker Registry deployment
-- ✅ `deployment/nexus-k8s.yaml` - Nexus deployment  
-- ✅ `deployment/nexus-ingress.yaml` - Nexus Ingress with TLS
-- ✅ `deployment/create-nexus-repos.sh` - Repository creation script
-- ✅ `deployment/NEXUS-COMPLETE-SETUP.md` - Nexus setup guide
-- ✅ `deployment/COMPLETE-SETUP-DOCUMENTATION.md` - Full journey documentation
-- ✅ `deployment/DEPLOYMENT-STATUS.md` - This file
-
-### Configuration Files
-- ✅ 4x NuGet.config files (all projects)
-- ✅ 5x Dockerfile files (all services)
-- ✅ 5x Gitea workflow files (all pipelines)
-
----
-
-## 🎉 Summary
-
-**Status:** ✅ **Fully Operational**
-
-You now have:
-1. ✅ **Local Docker Registry** caching all base images
-2. ✅ **Nexus** caching all NuGet packages  
-3. ✅ **All projects configured** to use local sources
-4. ✅ **Complete offline deployment capability**
-
-**Next steps:**
-- Test a full build: `dotnet restore && dotnet build`
-- Deploy a service: Images will pull from local registry
-- Monitor Nexus: Watch NuGet packages cache on first restore
-
-**Result:** Zero downloads required after initial cache population! 🚀

deployment/INGRESS-NGINX-WARNING.md

@@ -1,82 +0,0 @@
-# ⚠️ CRITICAL WARNING: ingress-nginx with K3s
-
-## The Problem
-
-When using **K3s** with the built-in **svclb (ServiceLB)**, DO NOT add `hostNetwork: true` to the ingress-nginx controller.
-
-## Why This Happens
-
-K3s automatically deploys `svclb-*` pods when you create a `LoadBalancer` service. These svclb pods:
-- Use `hostNetwork: true` by design
-- Bind to ports 80 and 443 on the host
-
-If you also add `hostNetwork: true` to ingress-nginx-controller:
-- **Both** svclb pods AND ingress-nginx pods try to bind to ports 80/443
-- This causes bind conflicts
-- External traffic cannot reach the ingress controller
-- You'll see "connection refused" or routing failures
-
-## The Solution
-
-**Remove `hostNetwork: true`** from ingress-nginx-controller DaemonSet/Deployment.
-
-```bash
-# Check current config
-kubectl get ds -n ingress-nginx ingress-nginx-controller -o yaml | grep -A5 hostNetwork
-
-# If hostNetwork is true, patch to remove it:
-kubectl patch ds -n ingress-nginx ingress-nginx-controller --type='json' -p='[{"op":"remove","path":"/spec/template/spec/hostNetwork"}]'
-
-# Restart pods
-kubectl rollout restart ds -n ingress-nginx ingress-nginx-controller
-```
-
-## How K3s svclb Works
-
-```
-External Request (port 80/443)
-        │
-        ▼
-┌───────────────────┐
-│  svclb-* pod      │  ← hostNetwork: true, binds to 80/443
-│  (K3s ServiceLB)  │
-└─────────┬─────────┘
-          │
-          ▼ forwards to service
-┌───────────────────────────────┐
-│  ingress-nginx-controller svc │  (LoadBalancer type)
-│  ClusterIP:10.43.x.x:80/443   │
-└─────────┬─────────────────────┘
-          │
-          ▼
-┌───────────────────────────────┐
-│  ingress-nginx-controller pod │  ← NO hostNetwork needed
-│  Listens on container ports   │
-└───────────────────────────────┘
-```
-
-## Verification
-
-```bash
-# Check svclb pods are running
-kubectl get pods -A | grep svclb
-
-# Should see:
-# kube-system   svclb-ingress-nginx-controller-xxxxx   Running
-
-# Verify ports are accessible
-curl -I http://SERVER_IP
-
-# Should get HTTP response from ingress-nginx
-```
-
-## Related Issues
-
-- If you use `NodePort` instead of `LoadBalancer`, svclb pods won't be created
-- If you disable K3s ServiceLB and use MetalLB, different rules apply
-- Cloud providers with real LoadBalancers also don't need hostNetwork
-
----
-
-*Date: 2025-01-18*
-*Issue discovered while deploying FourSat infrastructure*

deployment/OFFLINE-DEPLOYMENT-GUIDE.md

@@ -1,832 +0,0 @@
-# راهنمای دیپلوی آفلاین FourSat
-
-> تاریخ: 2026-01-29
-> هدف: دیپلوی بدون نیاز به اینترنت خارجی
-
----
-
-## 📋 خلاصه اجرایی
-
-این راهنما شامل تنظیمات لازم برای دیپلوی کامل آفلاین پروژه FourSat است. با استفاده از Nexus به عنوان registry مرکزی و mirror های ایرانی به عنوان fallback، نیازی به اینترنت خارجی نیست.
-
----
-
-## 🖥️ سرورها
-
-| سرور | IP | نقش | رمز عبور |
-|------|-----|------|----------|
-| **Stage** | `194.5.195.53` | Nexus, Gitea, Runner | `87zH26nbqT` |
-| **Production** | `45.149.79.127` | K8S Production | `87zH26nbqT` |
-
----
-
-## 🐳 Nexus Registry
-
-### پورت‌ها
-| سرویس | پورت | پروتکل |
-|--------|------|--------|
-| Nexus UI | `32081` | HTTP |
-| Docker Registry | `32082` | HTTP (insecure) |
-| NuGet | `32081/repository/nuget-group/index.json` | HTTP |
-
-### Credentials
-```
-Username: admin
-Password: 87zH26nbqT
-```
-
-### ریپوزیتوری‌های Docker
-| نام | نوع | توضیح |
-|-----|------|-------|
-| `docker-hosted` | hosted | ایمیج‌های پروژه |
-| `docker-hub-proxy` | proxy | پروکسی Docker Hub |
-| `docker-arvancloud-proxy` | proxy | پروکسی ArvanCloud |
-| `docker-all` | group | گروه همه ریپوها |
-
-### ریپوزیتوری‌های NuGet
-| نام | نوع | توضیح |
-|-----|------|-------|
-| `foursat-nuget-hosted` | hosted | پکیج‌های پروتوباف |
-| `nuget.org-proxy` | proxy | پروکسی NuGet.org |
-| `nuget-runflare-proxy` | proxy | پروکسی Runflare |
-| `nuget-group` | group | گروه همه ریپوها |
-
----
-
-## 🪞 Mirror های ایرانی (Fallback)
-
-### Docker
-```
-https://docker.arvancloud.ir
-```
-
-### APT/Ubuntu
-```
-http://mirror.arvancloud.ir/ubuntu
-```
-
-### NuGet
-```
-https://mirror-nuget.runflare.com/v3/index.json
-```
-
-### PyPI
-```
-https://mirror-pypi.runflare.com/simple
-```
-
-### NPM
-```
-https://mirror-npm.runflare.com
-```
-
----
-
-## 📦 ایمیج‌های ذخیره شده در Nexus
-
-| ایمیج | تگ | سایز تقریبی |
-|-------|-----|-------------|
-| `gitea/gitea` | `1.25.3` | ~78MB |
-| `mcr.microsoft.com/mssql/server` | `2022-CU16-ubuntu-22.04` | ~1.6GB |
-| `gitea/act_runner` | `0.2.11`, `latest` | ~50MB |
-| `registry.k8s.io/ingress-nginx/controller` | `v1.14.1` | ~280MB |
-| `dotnet/sdk` | `9.0` | ~900MB |
-| `dotnet/aspnet` | `9.0` | ~220MB |
-| `library/nginx` | `alpine` | ~40MB |
-| `docker` | `dind` | ~400MB |
-| `docker-sshpass` | `latest` | ~500MB |
-
----
-
-## ⚙️ تنظیمات K3s
-
-### فایل: `/etc/rancher/k3s/registries.yaml`
-
-```yaml
-# Registry Mirrors Configuration
-# Primary: Nexus (194.5.195.53:32082)
-# Fallback: ArvanCloud (docker.arvancloud.ir)
-
-mirrors:
-  "docker.io":
-    endpoint:
-      - "http://194.5.195.53:32082"
-      - "https://docker.arvancloud.ir"
-      - "https://registry-1.docker.io"
-  "194.5.195.53:32082":
-    endpoint:
-      - "http://194.5.195.53:32082"
-  "ghcr.io":
-    endpoint:
-      - "http://194.5.195.53:32082"
-      - "https://docker.arvancloud.ir"
-  "gcr.io":
-    endpoint:
-      - "http://194.5.195.53:32082"
-      - "https://docker.arvancloud.ir"
-  "registry.k8s.io":
-    endpoint:
-      - "http://194.5.195.53:32082"
-      - "https://docker.arvancloud.ir"
-  "quay.io":
-    endpoint:
-      - "http://194.5.195.53:32082"
-      - "https://docker.arvancloud.ir"
-  "mcr.microsoft.com":
-    endpoint:
-      - "http://194.5.195.53:32082"
-      - "https://docker.arvancloud.ir"
-
-configs:
-  "194.5.195.53:32082":
-    auth:
-      username: admin
-      password: 87zH26nbqT
-```
-
-### اعمال تغییرات
-```bash
-sudo systemctl restart k3s
-```
-
----
-
-## 📝 تنظیمات APT
-
-### فایل: `/etc/apt/sources.list.d/ubuntu.sources`
-
-```
-Types: deb
-URIs: http://mirror.arvancloud.ir/ubuntu http://archive.ubuntu.com/ubuntu
-Suites: noble noble-updates noble-backports
-Components: main restricted universe multiverse
-Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
-
-Types: deb
-URIs: http://mirror.arvancloud.ir/ubuntu http://security.ubuntu.com/ubuntu
-Suites: noble-security
-Components: main restricted universe multiverse
-Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
-```
-
----
-
-## 🐍 تنظیمات PIP
-
-### فایل: `/root/.config/pip/pip.conf`
-
-```ini
-[global]
-index-url = https://pypi.org/simple
-extra-index-url = https://mirror-pypi.runflare.com/simple
-trusted-host = mirror-pypi.runflare.com
-timeout = 60
-```
-
----
-
-## 📦 تنظیمات NPM
-
-### فایل: `/root/.npmrc`
-
-```
-registry=https://registry.npmjs.org/
-# Fallback (uncomment if needed):
-# registry=https://mirror-npm.runflare.com
-```
-
----
-
-## 🔧 تنظیمات Gitea Runner
-
-### مشکل: Runner نمیتونه از Nexus (HTTP) pull کنه
-
-**علت:** Docker daemon داخل Runner سعی میکنه با HTTPS وصل بشه.
-
-**راه حل:** ConfigMap برای daemon.json
-
-### ConfigMap
-```yaml
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: docker-daemon-config
-data:
-  daemon.json: |
-    {
-      "insecure-registries": ["194.5.195.53:32082", "194.5.195.53:30080"]
-    }
-```
-
-### Deployment Patch
-```bash
-kubectl patch deployment gitea-runner --type=json -p='[
-  {
-    "op": "add",
-    "path": "/spec/template/spec/volumes/-",
-    "value": {
-      "name": "docker-config",
-      "configMap": {
-        "name": "docker-daemon-config"
-      }
-    }
-  },
-  {
-    "op": "add",
-    "path": "/spec/template/spec/containers/0/volumeMounts/-",
-    "value": {
-      "name": "docker-config",
-      "mountPath": "/etc/docker/daemon.json",
-      "subPath": "daemon.json"
-    }
-  }
-]'
-```
-
-### بررسی
-```bash
-kubectl exec $(kubectl get pods -l app=gitea-runner -o jsonpath='{.items[0].metadata.name}') \
-  -c docker -- docker info | grep -A 5 'Insecure Registries'
-```
-
----
-
-## 📁 ساختار Dockerfile ها
-
-### الگوی استاندارد (با Nexus)
-```dockerfile
-FROM 194.5.195.53:32082/dotnet/sdk:9.0 AS build
-WORKDIR /src
-
-# Copy NuGet config
-COPY src/NuGet.config ./
-
-# Restore and build
-RUN dotnet restore "Project.csproj" --configfile NuGet.config
-RUN dotnet publish "Project.csproj" -c Release -o /app/publish --no-restore
-
-FROM 194.5.195.53:32082/dotnet/aspnet:9.0 AS runtime
-WORKDIR /app
-COPY --from=build /app/publish .
-ENTRYPOINT ["dotnet", "Project.dll"]
-```
-
-### NuGet.config
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<configuration>
-  <packageSources>
-    <clear />
-    <add key="nexus" value="http://194.5.195.53:32081/repository/nuget-group/index.json" />
-  </packageSources>
-</configuration>
-```
-
----
-
-## 🔄 ساختار Workflow (CI/CD)
-
-### الگوی استاندارد `kub-deploy.yml`
-```yaml
-name: Build and Deploy
-
-on:
-  push:
-    branches:
-      - kub-stage  # یا production
-
-env:
-  REGISTRY: 194.5.195.53:30080
-  IMAGE_NAME: admin/project-name
-  K8S_SERVER: 194.5.195.53  # یا 45.149.79.127 برای Production
-
-jobs:
-  build-and-deploy:
-    runs-on: ubuntu-latest
-    container:
-      image: 194.5.195.53:32082/docker-sshpass:latest
-      options: --privileged
-    steps:
-      - name: Start Docker daemon
-        run: |
-          mkdir -p /etc/docker
-          cat > /etc/docker/daemon.json << 'DAEMON'
-          {
-            "insecure-registries": ["194.5.195.53:30080", "194.5.195.53:32082"]
-          }
-          DAEMON
-          dockerd &
-          for i in $(seq 1 90); do 
-            docker info >/dev/null 2>&1 && break || sleep 2
-          done
-
-      - name: Checkout code
-        run: |
-          git clone --depth 1 --branch $BRANCH http://gitea-svc:3000/admin/PROJECT.git .
-
-      - name: Build Docker Image
-        run: |
-          docker build -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest .
-
-      - name: Push to Registry
-        run: |
-          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login ${{ env.REGISTRY }} -u admin --password-stdin
-          docker push ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
-
-      - name: Deploy
-        run: |
-          sshpass -p "${{ secrets.K8S_SSH_PASSWORD }}" ssh -o StrictHostKeyChecking=no root@${{ env.K8S_SERVER }} \
-            "kubectl rollout restart deployment/PROJECT"
-```
-
----
-
-## 🔐 Secrets مورد نیاز در Gitea
-
-| Secret | مقدار | توضیح |
-|--------|-------|-------|
-| `REGISTRY_PASSWORD` | `87zH26nbqT` | رمز Gitea Registry |
-| `K8S_SSH_PASSWORD` | `87zH26nbqT` | رمز SSH سرور |
-
----
-
-## 💾 بکاپ روزانه MSSQL
-
-### CronJob
-```yaml
-apiVersion: batch/v1
-kind: CronJob
-metadata:
-  name: mssql-backup
-spec:
-  schedule: "0 2 * * *"  # هر روز ساعت 2 صبح
-  jobTemplate:
-    spec:
-      template:
-        spec:
-          containers:
-          - name: backup
-            image: 194.5.195.53:32082/mcr.microsoft.com/mssql-tools:latest
-            command:
-            - /bin/bash
-            - -c
-            - |
-              DATE=$(date +%Y%m%d)
-              for DB in gitea Foursat; do
-                /opt/mssql-tools/bin/sqlcmd -S mssql-svc -U sa -P '87zH26nbqT' \
-                  -Q "BACKUP DATABASE [$DB] TO DISK='/backups/${DB}_${DATE}.bak'"
-              done
-            volumeMounts:
-            - name: backup-volume
-              mountPath: /backups
-          volumes:
-          - name: backup-volume
-            hostPath:
-              path: /mnt/mssql-backups
-          restartPolicy: OnFailure
-```
-
----
-
-## 📊 خلاصه پروژه‌ها
-
-| پروژه | Dockerfile | Workflow Stage | Workflow Prod |
-|-------|------------|----------------|---------------|
-| BackOffice | ✅ Nexus | ✅ | ✅ |
-| BackOffice.BFF | ✅ Nexus | ✅ | ✅ |
-| CMS | ✅ Nexus | ✅ | ✅ |
-| FrontOffice | ✅ Nexus | ✅ | ✅ |
-| FrontOffice.BFF | ✅ Nexus | ✅ | ✅ |
-
----
-
-## 🚨 Troubleshooting
-
-### مشکل: Image pull failed - HTTPS error
-```
-Error: http: server gave HTTP response to HTTPS client
-```
-**راه حل:** اضافه کردن registry به insecure-registries
-
-### مشکل: NuGet restore failed
-**راه حل:** بررسی NuGet.config و اتصال به Nexus
-
-### مشکل: Runner CrashLoopBackOff
-**راه حل:** بررسی لاگ‌ها با `kubectl logs`
-
-### مشکل: K3s نمیتونه pull کنه
-**راه حل:** بررسی `/etc/rancher/k3s/registries.yaml` و restart K3s
-
----
-
-## 📞 دستورات مفید
-
-### بررسی وضعیت Runner
-```bash
-kubectl get pods -l app=gitea-runner
-kubectl logs -l app=gitea-runner -c runner --tail=50
-```
-
-### تست pull از Nexus
-```bash
-crictl pull 194.5.195.53:32082/dotnet/sdk:9.0
-```
-
-### بررسی ایمیج‌ها در Nexus
-```bash
-curl -u admin:87zH26nbqT http://194.5.195.53:32082/v2/_catalog
-```
-
-### Restart K3s
-```bash
-sudo systemctl restart k3s
-```
-
----
-
-## 📅 تاریخچه تغییرات
-
-| تاریخ | تغییر |
-|-------|-------|
-| 2026-01-29 | راه‌اندازی اولیه، تنظیم Nexus، Runner، و Mirror ها |
-| 2026-01-29 | تنظیم Production server برای استفاده از Stage Nexus |
-| 2026-01-29 | آپدیت Dockerfile ها و Workflow های production |
-| 2026-01-29 | فیکس insecure registry برای Gitea Runner |
-
----
-
-> 📝 این داکیومنت توسط Copilot تهیه شده و باید با تغییرات پروژه بروزرسانی شود.
-
-
----
-
-# تنظیمات Nexus (جزئیات کامل)
-
-# ✅ Nexus Repository Manager - Complete Setup
-
-## 📦 Deployed Services
-
-### Nexus Repository Manager
-- **Version:** 3.38.0 (Compatible with x86-64-v1 CPU)
-- **Web UI:** https://nexus.se.kbs1.ir
-- **NodePort:** http://194.5.195.53:32081
-- **Credentials:** admin / 87zH26nbqT
-
-### Kubernetes Resources
-```bash
-# Pod
-kubectl get pod | grep nexus
-# nexus-6575454f69-fv29t   1/1   Running
-
-# Service (NodePort)
-kubectl get svc nexus
-# Ports: 8081:32081 (Web UI)
-#        8082:32082 (Docker Hosted)
-#        8083:32083 (Docker Proxy)
-#        8084:32084 (Docker Group)
-
-# Ingress
-kubectl get ingress nexus-ingress
-# Host: nexus.se.kbs1.ir
-# TLS: Self-signed certificate (via cert-manager)
-```
-
----
-
-## 📦 Repositories Created
-
-### NuGet Repositories
-
-1. **nuget-org-proxy** (Proxy)
-   - Proxies: https://api.nuget.org/v3/index.json
-   - Caches packages from nuget.org
-   - URL: https://nexus.se.kbs1.ir/repository/nuget-org-proxy/index.json
-
-2. **foursat-nuget-hosted** (Hosted)
-   - For private FourSat packages
-   - URL: https://nexus.se.kbs1.ir/repository/foursat-nuget-hosted/index.json
-
-3. **nuget-all** (Group)
-   - Combines: nuget-org-proxy + foursat-nuget-hosted
-   - **Use this URL in projects**
-   - URL: https://nexus.se.kbs1.ir/repository/nuget-all/index.json
-
-### Docker Repositories
-
-1. **docker-hosted** (Hosted)
-   - For private Docker images
-   - Port: 32082
-   - URL: 194.5.195.53:32082
-
-2. **docker-hub-proxy** (Proxy)
-   - Proxies: https://registry-1.docker.io (Docker Hub)
-   - Caches images from Docker Hub
-   - Port: 32083
-   - URL: 194.5.195.53:32083
-
-3. **docker-all** (Group)
-   - Combines: docker-hosted + docker-hub-proxy
-   - Port: 32084
-   - **Use this for Kubernetes**
-   - URL: 194.5.195.53:32084
-
----
-
-## 🔧 Project Configuration
-
-### NuGet.config (Already Updated)
-
-All projects now use Nexus as primary source:
-
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<configuration>
-  <packageSources>
-    <clear />
-    <!-- Nexus as primary source (proxies nuget.org + caches packages) -->
-    <add key="Nexus" value="https://nexus.se.kbs1.ir/repository/nuget-all/index.json" />
-    <!-- Backup: Direct Gitea registries -->
-    <add key="FourSat" value="https://git.afrino.co/api/packages/FourSat/nuget/index.json" />
-    <add key="Afrino" value="https://git.afrino.co/api/packages/Afrino/nuget/index.json" />
-  </packageSources>
-  <packageSourceCredentials>
-    <Nexus>
-      <add key="Username" value="admin" />
-      <add key="ClearTextPassword" value="87zH26nbqT" />
-    </Nexus>
-    <FourSat>
-      <add key="Username" value="masoud" />
-      <add key="ClearTextPassword" value="87zH26nbqT" />
-    </FourSat>
-    <Afrino>
-      <add key="Username" value="systemuser" />
-      <add key="ClearTextPassword" value="sZSA7PTiv3pUSQZ" />
-    </Afrino>
-  </packageSourceCredentials>
-</configuration>
-```
-
-**Updated files:**
-- ✅ `/BackOffice/src/BackOffice/NuGet.config`
-- ✅ `/BackOffice.BFF/src/BackOffice.BFF.WebApi/NuGet.config`
-- ✅ `/FrontOffice/src/FrontOffice.Main/NuGet.config`
-- ✅ `/FrontOffice.BFF/src/FrontOffice.BFF.WebApi/NuGet.config`
-
----
-
-## 🐳 Docker Registry Configuration
-
-### For Kubernetes Deployments
-
-Update `/etc/containerd/config.toml` on all nodes:
-
-```toml
-[plugins."io.containerd.grpc.v1.cri".registry]
-  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
-    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."194.5.195.53:32084"]
-      endpoint = ["http://194.5.195.53:32084"]
-    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
-      endpoint = ["http://194.5.195.53:32084"]
-  
-  [plugins."io.containerd.grpc.v1.cri".registry.configs]
-    [plugins."io.containerd.grpc.v1.cri".registry.configs."194.5.195.53:32084".auth]
-      username = "admin"
-      password = "87zH26nbqT"
-```
-
-Then restart containerd:
-```bash
-systemctl restart containerd
-```
-
-### For Docker
-
-Add to `/etc/docker/daemon.json`:
-
-```json
-{
-  "insecure-registries": [
-    "194.5.195.53:32082",
-    "194.5.195.53:32083",
-    "194.5.195.53:32084"
-  ],
-  "registry-mirrors": [
-    "http://194.5.195.53:32084"
-  ]
-}
-```
-
-Then restart Docker:
-```bash
-systemctl restart docker
-```
-
-### Docker Login
-
-```bash
-docker login 194.5.195.53:32084 -u admin -p 87zH26nbqT
-docker login 194.5.195.53:32082 -u admin -p 87zH26nbqT
-docker login 194.5.195.53:32083 -u admin -p 87zH26nbqT
-```
-
----
-
-## 🚀 Usage Examples
-
-### Pull Docker Images via Nexus Proxy
-
-```bash
-# Instead of: docker pull nginx:alpine
-docker pull 194.5.195.53:32084/nginx:alpine
-
-# Instead of: docker pull mcr.microsoft.com/dotnet/aspnet:9.0
-docker pull 194.5.195.53:32084/mcr.microsoft.com/dotnet/aspnet:9.0
-```
-
-**First pull:** Downloads from Docker Hub and caches in Nexus  
-**Subsequent pulls:** Served from Nexus cache (no internet needed)
-
-### Push Private Docker Images
-
-```bash
-# Tag image
-docker tag myapp:latest 194.5.195.53:32082/myapp:latest
-
-# Push to hosted repository
-docker push 194.5.195.53:32082/myapp:latest
-```
-
-### NuGet Package Restore
-
-```bash
-cd /path/to/project
-dotnet restore
-```
-
-**First restore:** Downloads from nuget.org via Nexus proxy  
-**Subsequent restores:** Served from Nexus cache (no internet needed)
-
-### Publish Private NuGet Packages
-
-```bash
-# Pack project
-dotnet pack MyProject.csproj -c Release
-
-# Push to Nexus hosted repository
-dotnet nuget push MyProject.1.0.0.nupkg \
-  --source https://nexus.se.kbs1.ir/repository/foursat-nuget-hosted/ \
-  --api-key admin:87zH26nbqT
-```
-
----
-
-## 🔍 Verification
-
-### Check NuGet Sources
-
-```bash
-dotnet nuget list source
-```
-
-Expected output:
-```
-Registered Sources:
-  1.  Nexus [Enabled]
-      https://nexus.se.kbs1.ir/repository/nuget-all/index.json
-  2.  FourSat [Enabled]
-      https://git.afrino.co/api/packages/FourSat/nuget/index.json
-  3.  Afrino [Enabled]
-      https://git.afrino.co/api/packages/Afrino/nuget/index.json
-```
-
-### Test Package Download
-
-```bash
-# This should use Nexus as primary source
-dotnet add package Newtonsoft.Json
-
-# Check Nexus logs
-kubectl logs nexus-6575454f69-fv29t | tail -20
-```
-
-### Check Cached Packages in Nexus
-
-```bash
-# SSH to server
-ssh root@194.5.195.53
-
-# Check blob storage
-du -sh /var/lib/nexus/blobs/default/content/*
-```
-
----
-
-## 📊 Benefits
-
-### NuGet Caching
-- ✅ Packages download once, cached forever
-- ✅ No repeated downloads from nuget.org
-- ✅ Faster CI/CD builds
-- ✅ Works offline after first download
-
-### Docker Caching
-- ✅ Base images cached locally (aspnet, sdk, nginx, etc.)
-- ✅ No repeated downloads from Docker Hub
-- ✅ Faster Kubernetes deployments
-- ✅ Works offline after first pull
-
-### Private Package Hosting
-- ✅ Host private NuGet packages
-- ✅ Host private Docker images
-- ✅ Version control for artifacts
-- ✅ Access control via credentials
-
----
-
-## 🛠️ Maintenance
-
-### Check Repository Storage
-
-Via UI:
-1. Login to https://nexus.se.kbs1.ir
-2. Go to: ⚙️ Settings → System → Blob Stores
-3. View: Storage usage per blob store
-
-Via API:
-```bash
-curl -u admin:87zH26nbqT \
-  http://194.5.195.53:32081/service/rest/v1/blobstores
-```
-
-### Clear Cache (if needed)
-
-Via UI:
-1. Go to: ⚙️ Settings → Repository → Repositories
-2. Select repository (e.g., `nuget-org-proxy`)
-3. Click: **Delete cache**
-
-### Backup Nexus Data
-
-```bash
-# Stop Nexus
-kubectl scale deployment nexus --replicas=0
-
-# Backup data
-tar -czf nexus-backup-$(date +%Y%m%d).tar.gz /var/lib/nexus/
-
-# Start Nexus
-kubectl scale deployment nexus --replicas=1
-```
-
----
-
-## 📝 Files Created
-
-- ✅ `/deployment/nexus-k8s.yaml` - Kubernetes deployment
-- ✅ `/deployment/nexus-ingress.yaml` - Ingress with TLS
-- ✅ `/deployment/create-nexus-repos.sh` - Repository creation script
-- ✅ `/deployment/NEXUS-COMPLETE-SETUP.md` - This document
-
----
-
-## 🎯 Next Steps
-
-1. **Test NuGet Caching:**
-   ```bash
-   cd BackOffice/src
-   dotnet clean
-   rm -rf ~/.nuget/packages
-   dotnet restore
-   # Check Nexus UI → Browse → nuget-org-proxy
-   ```
-
-2. **Configure Kubernetes to use Docker proxy:**
-   ```bash
-   # Update containerd config (see Docker Registry Configuration above)
-   systemctl restart containerd
-   
-   # Pull image via Nexus
-   crictl pull 194.5.195.53:32084/nginx:alpine
-   ```
-
-3. **Update Dockerfiles to use local images:**
-   ```dockerfile
-   # Instead of: FROM mcr.microsoft.com/dotnet/aspnet:9.0
-   FROM 194.5.195.53:32084/mcr.microsoft.com/dotnet/aspnet:9.0
-   ```
-
-4. **Update CI/CD workflows:**
-   - Already using local registry: `194.5.195.53:32500`
-   - Can migrate to Nexus Docker registry: `194.5.195.53:32084`
-
----
-
-## ✅ Summary
-
-**Deployed:** Nexus Repository Manager 3.38.0  
-**Accessible:** https://nexus.se.kbs1.ir (with TLS)  
-**Repositories:** NuGet (proxy, hosted, group) + Docker (proxy, hosted, group)  
-**Projects Updated:** All 4 NuGet.config files now use Nexus as primary source  
-**Status:** Ready for production use  
-
-**Result:** Complete offline deployment capability for both NuGet packages and Docker images! 🎉

deployment/PACKAGE-MIGRATION-GUIDE.md

@@ -0,0 +1,700 @@
+# 📦 راهنمای مهاجرت سیستم پکیج‌بیس — خلاصه تغییرات و پلن استقرار
+
+> **وضعیت:** آماده تست و استقرار — **Q1-Q30 تکمیل‌شده ✅ | F1-F11 تکمیل‌شده ✅**  
+> **تاریخ:** ۸ اسفند ۱۴۰۴ (27 Feb 2026) — آپدیت ۱۰ اسفند  
+> **نسخه NuGet:** v0.0.189  
+> **تعداد کامیت‌ها:** ۵۱+ کامیت در ۴ ریپازیتوری (۲۱ CMS + ۹ FO + ۷ BO + ۱۴+ docs)  
+> **مدت پیاده‌سازی:** ۶ روز (۲۴ فوریه – ۱ مارس ۲۰۲۶)  
+> **ریپوها:** CMS (`gitea`/`kub-stage`) · FrontOffice (`kub-stage`) · BackOffice (`kub-stage`) · totalDoc (`foursatDocs`/`main`)
+
+---
+
+## فهرست مطالب
+
+1. [خلاصه اجرایی](#1-خلاصه-اجرایی)
+2. [چه چیزی تغییر کرده؟ — نمای بیزینسی](#2-چه-چیزی-تغییر-کرده--نمای-بیزینسی)
+3. [بخش‌های تحت تاثیر سیستم](#3-بخشهای-تحت-تاثیر-سیستم)
+4. [جزئیات تغییرات هر ریپو](#4-جزئیات-تغییرات-هر-ریپو)
+5. [پلن مهاجرت مرحله‌به‌مرحله](#5-پلن-مهاجرت-مرحلهبهمرحله)
+6. [Rollback Plan](#6-rollback-plan)
+7. [چک‌لیست تست قبل از Production](#7-چکلیست-تست-قبل-از-production)
+8. [ریسک‌ها و نکات بحرانی](#8-ریسکها-و-نکات-بحرانی)
+
+---
+
+## 1. خلاصه اجرایی
+
+### قبل (سیستم تک‌پکیج):
+- فقط **یک پکیج پایه** (۵۶ میلیون تومان) وجود داشت
+- تمام مقادیر مالی (قیمت، هزینه فعال‌سازی، ضرایب، سقف‌ها) **hardcoded** در کد بودند
+- خرید مجدد پکیج **غیرممکن** بود (حتی بعد تکمیل چرخه)
+- پورسانت فقط از **یک Pool واحد** محاسبه می‌شد
+- همه کاربران **همه فیچرها** را دریافت می‌کردند
+
+### بعد (سیستم چندپکیجی):
+- سیستم **N پکیج** با قیمت و ویژگی‌های متفاوت پشتیبانی می‌کند
+- تمام مقادیر مالی از **دیتابیس (Package entity)** خوانده می‌شوند
+- خرید مجدد بعد تکمیل چرخه Magic Wallet **فعال** شده
+- هر پکیج **Commission Pool مستقل** خود را دارد
+- فیچرها **per-package** هستند و با الگوریتم **DIFF** مدیریت می‌شوند
+- قرارداد باشگاه **فقط یک بار** (اولین خرید) امضا می‌شود
+
+### آمار تغییرات:
+
+| شاخص | مقدار |
+|-------|-------|
+| فایل‌های تغییریافته | **۲۲۷+ فایل** |
+| خطوط اضافه‌شده | **+۱۷,۰۰۰+** |
+| خطوط حذف‌شده | **−۲,۶۶۰+** |
+| تصمیمات بیزینسی پیاده‌شده | **۳۰ تصمیم** (Q1–Q30) |
+| باگ‌های فیکس‌شده | **۶ باگ بحرانی** |
+| مقادیر hardcoded حذف‌شده | **۱۵+ مورد** |
+| Handlerهای deprecated حذف‌شده | **۴ handler** (۱۲ فایل) |
+| RPCهای deprecated حذف‌شده | **۴ RPC** + ۸ message type |
+| فایل‌های rename شده | **۳۴ فایل** + ۱۱ دایرکتوری (UserWalletChangeLog → UserWalletHistory) |
+| History Tables جدید | **۳ جدول** (PackageHistories, ClubMembershipCycleHistories, UserWalletHistories) |
+
+---
+
+## 2. چه چیزی تغییر کرده؟ — نمای بیزینسی
+
+### 2.1 🏪 مدل فروش پکیج
+
+| قابلیت | قبل | بعد |
+|--------|-----|------|
+| تعداد پکیج | ۱ (پایه ۵۶M) | **N پکیج** (پایه ۵۶M + نقره‌ای ۵.۶M + ...) |
+| قیمت‌گذاری | hardcoded `56_000_000` | از `Package.Price` در دیتابیس |
+| هزینه فعال‌سازی | hardcoded `25_200_000` | از `Package.ActivationFee` |
+| ضریب تخفیف | hardcoded `× 2` | از `Package.DiscountMultiplier` |
+| پشتیبانی دایا | فقط پکیج پایه | بر اساس `Package.SupportsDayaPurchase` |
+| پرداخت مستقیم | همه | بر اساس `Package.SupportsDirectPurchase` |
+
+### 2.2 🔄 چرخه خرید مجدد (Re-Purchase)
+
+| مرحله | قبل | بعد |
+|-------|-----|------|
+| تکمیل چرخه Magic | کاربر در بن‌بست | `PackagePurchaseMethod = None` ریست می‌شود |
+| خرید مجدد | **مسدود** (guard G1-G3) | **مجاز** — بعد تکمیل چرخه Magic |
+| قرارداد باشگاه | هر بار | **فقط یک بار** — خرید مجدد Skip (Q19) |
+| فیچرها | همه فیچرها بدون توجه به پکیج | **DIFF/تفاضل** — فقط اختلاف اعمال می‌شود (Q20) |
+| تاریخچه | فقط `ActivatedAt` | `FirstActivationDate` + `LastActivationDate` (Q21) |
+
+### 2.3 💰 پورسانت و تعادل‌ها
+
+| ویژگی | قبل | بعد |
+|-------|-----|------|
+| Commission Pool | ۱ Pool واحد | **Pool جداگانه هر پکیج** |
+| تعادل هفتگی | ۱ رکورد per user/week | **N رکورد** per user/week/package |
+| MaxBalancesPerLeg | hardcoded `300` | per-package (پایه=۳۰۰, نقره‌ای=۳۰) |
+| MaxNetworkLevel | hardcoded `15` | per-package از دیتابیس |
+| Carryover | یک‌پارچه | **per-downline-package** — بر اساس پکیج زیرمجموعه‌ها (تغییر پکیج خود کاربر تاثیری ندارد) |
+| Stored Procedure | پارامترهای ثابت | پارامترهای داینامیک از Package entity |
+| گزارش مشتری | بدون تفکیک | **breakdown per-package** |
+| گزارش ادمین | بدون فیلتر | **فیلتر بر اساس پکیج** |
+
+### 2.4 🪄 کیف پول جادویی (Magic Wallet)
+
+| ویژگی | قبل | بعد |
+|-------|-----|------|
+| ضریب جادویی | hardcoded `× 2.5` | از `Package.MagicWalletMultiplier` |
+| سقف واریز | hardcoded `1,000,000,000` | از `Package.MagicWalletMaxDeposit` |
+| سقف اعتبار | hardcoded `2,500,000,000` | از `Package.MagicWalletMaxCredit` |
+| شرط EXIT | بررسی سقف global | بررسی سقف **per-package** |
+
+### 2.5 📋 فیچرهای باشگاه
+
+| ویژگی | قبل | بعد |
+|-------|-----|------|
+| تخصیص فیچر | `GetAllFeatureIds()` — همه فیچرها | از `Package.PackageFeatures` — per-package |
+| خرید مجدد | — | الگوریتم **DIFF**: مقایسه فیچرهای فعلی با پکیج جدید |
+| مدیریت ادمین | — | ماتریس checkbox پکیج × فیچر در BackOffice |
+
+---
+
+## 3. بخش‌های تحت تاثیر سیستم
+
+### 3.1 نقشه تاثیرگذاری
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                     🏗️ سیستم پکیج‌بیس — Impact Map                      │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  ┌─── CMS (Backend) ──────────────────────────────────────────────────┐ │
+│  │                                                                     │ │
+│  │  📦 Domain Layer (Entity تغییرات)                                   │ │
+│  │  ├── Package.cs ← +۱۱ فیلد جدید                                    │ │
+│  │  ├── PackageFeature.cs ← Entity کاملاً جدید                        │ │
+│  │  ├── ClubMembership.cs ← ActivatedAt → ۴ فیلد First/Last           │ │
+│  │  ├── ClubMembershipCycle.cs ← +PackageId                           │ │
+│  │  ├── WeeklyCommissionPool.cs ← +PackageId                          │ │
+│  │  ├── UserCommissionPayout.cs ← +PackageId                          │ │
+│  │  ├── NetworkWeeklyBalance.cs ← +PackageId                          │ │
+│  │  └── SystemConstants.cs ← حذف ۹ ثابت منسوخ                         │ │
+│  │                                                                     │ │
+│  │  ⚙️ Application Layer (Handler تغییرات)                             │ │
+│  │  ├── ActivateClubMembershipCommandHandler ← فیچر DIFF + re-activate│ │
+│  │  ├── AcceptClubMembershipContractCommandHandler ← فیچر DIFF         │ │
+│  │  ├── VerifyPackagePurchaseCommandHandler ← حذف fallback 2.0m       │ │
+│  │  ├── CustomerPurchasePackage/Verify ← Generic purchase flow         │ │
+│  │  ├── ChargeMagicWalletCommandHandler ← سقف per-package             │ │
+│  │  ├── VerifyMagicWalletChargeCommandHandler ← ضریب per-package      │ │
+│  │  ├── UserOrderService (EXIT Magic) ← ریست + سقف per-package        │ │
+│  │  ├── CreateManualPaymentCommandHandler ← ضریب از Package           │ │
+│  │  └── CheckAndProcessDayaLoansCommandHandler ← حذف ID=4            │ │
+│  │                                                                     │ │
+│  │  🔌 Infrastructure Layer                                            │ │
+│  │  ├── sp_CalculateWeeklyBalances ← @PackageId + @Max params         │ │
+│  │  ├── sp_CalculateWeeklyCommissionPool ← @PackageId                 │ │
+│  │  ├── WeeklyCommissionCalculationService ← Loop per-package         │ │
+│  │  ├── OrmCommissionCalculationStrategy ← فیلتر PackageId            │ │
+│  │  └── SpCommissionCalculationStrategy ← پارامترهای داینامیک         │ │
+│  │                                                                     │ │
+│  │  📡 Proto/gRPC Layer                                                │ │
+│  │  ├── package.proto ← ۱۱ فیلد + PackageFeature CRUD                │ │
+│  │  ├── commission.proto ← package_id/title در ۴ model + فیلتر       │ │
+│  │  ├── حذف ۴ RPC deprecated (Golden/Base)                            │ │
+│  │  └── حذف ۸ message type deprecated                                 │ │
+│  │                                                                     │ │
+│  └─────────────────────────────────────────────────────────────────────┘ │
+│                                                                         │
+│  ┌─── FrontOffice (مشتری) ─────────────────────────────────────────────┐│
+│  │  ├── Packages.razor ← کاشی‌های داینامیک (نه hardcoded)              ││
+│  │  ├── PackageDetail.razor ← فیچرها از API (نه ثابت)                  ││
+│  │  ├── Checkout.razor ← پرداخت شرطی (دایا/مستقیم)                    ││
+│  │  ├── MyPackages.razor ← خرید مجدد + پیشرفت Magic                   ││
+│  │  ├── ActivationSection.razor ← قیمت داینامیک (نه ۵۶M hardcoded)     ││
+│  │  ├── ClubMembershipContractDialog ← متن قرارداد داینامیک            ││
+│  │  ├── CommissionDashboard ← فیلتر + ستون پکیج                       ││
+│  │  ├── WeeklyBalancePage ← فیلتر per-package                          ││
+│  │  ├── PaymentCallback ← مهاجرت به Customer* RPCs                     ││
+│  │  └── حذف "پکیج طلایی" hardcoded (۵+ جا)                            ││
+│  └─────────────────────────────────────────────────────────────────────┘│
+│                                                                         │
+│  ┌─── BackOffice (ادمین) ──────────────────────────────────────────────┐│
+│  │  ├── Package CRUD ← +۱۲ فیلد جدید در Create/Update                 ││
+│  │  ├── PackageFeature Matrix ← checkbox فیچرها                        ││
+│  │  ├── ManualPaymentDialog ← حذف ۵۶M hardcoded + Amount editable     ││
+│  │  ├── ChangeParentDialog ← جابجایی در شبکه (جدید)                   ││
+│  │  ├── UserPayouts ← فیلتر + ستون پکیج                               ││
+│  │  ├── BalancesReport ← فیلتر + ستون پکیج                            ││
+│  │  ├── PackageSelect Component ← dropdown قابل استفاده مجدد           ││
+│  │  └── حذف "پکیج طلایی" → "خرید پکیج"                               ││
+│  └─────────────────────────────────────────────────────────────────────┘│
+│                                                                         │
+│  ┌─── Database ────────────────────────────────────────────────────────┐│
+│  │  ├── Packages ← ۱۱ ستون جدید + Seed نقره‌ای                        ││
+│  │  ├── PackageFeatures ← جدول جدید                                    ││
+│  │  ├── ClubMemberships ← ۴ ستون First/Last + حذف ActivatedAt         ││
+│  │  ├── ClubMembershipCycles ← +PackageId                              ││
+│  │  ├── WeeklyCommissionPools ← +PackageId + Unique                    ││
+│  │  ├── UserCommissionPayouts ← +PackageId + Unique                    ││
+│  │  ├── NetworkWeeklyBalances ← +PackageId + Unique                    ││
+│  │  └── EF Migration + Data Backfill                                    ││
+│  └─────────────────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### 3.2 خلاصه آماری per-repo
+
+| ریپو | کامیت | فایل | اضافه | حذف | شرح اصلی |
+|-------|-------|------|-------|-----|-----------|
+| **CMS** | ۲۰ | ۱۷۹+ | +۱۳,۵۸۶ | −۲,۳۲۷ | Domain + Business + Commission + Proto + History + Rename + Interceptor |
+| **FrontOffice** | ۸ | ۲۹ | +۵۵۰ | −۱۳۶ | Dynamic UI + Customer RPCs + Per-package Reports + UI Guidance |
+| **BackOffice** | ۶ | ۲۴ | +۵۸۰ | −۳۱ | Package CRUD + Feature Matrix + Per-package Reports + UI Guidance |
+| **totalDoc** | ۱۴ | ۱۳ | +۲,۷۰۰ | −۱۹۴ | مستندات بیزینسی + تکنیکال + Phase 9 |
+
+---
+
+## 4. جزئیات تغییرات هر ریپو
+
+### 4.1 CMS — ۲۰ کامیت
+
+| فاز | کامیت | شرح |
+|-----|--------|------|
+| **Phase 0** | `8b9c317` | فیکس ۴ باگ بحرانی: DiscountBalance + UserPackagePurchase |
+| **Phase 0** | `fe3edd1` | فیکس EXIT Magic Mode — ریست PackagePurchaseMethod + بستن چرخه |
+| **Phase 1** | `ae92ab8` | زیرساخت Domain: Package +۱۱ فیلد، PackageFeature entity، FKهای جدید |
+| **Phase 1.5** | `a9cd2fd` | EF Migration + Seed Data + Data Backfill |
+| **Phase 2** | `8e5c7c5` | جایگزینی همه SystemConstants با Package entity reads |
+| **Phase 3** | `ccb938e` | بازسازی لایه Package + Proto enhancement + باگ‌فیکس |
+| **Phase 4** | `0002a5a` | CRUD DTOs + Legacy fixes |
+| **Phase 5** | `607f791` | پورسانت per-package + حذف ref طلایی |
+| **SP Fix** | `7176fe4` | فیکس SP: `cm.PackageId` → `cm.LastPackageId` |
+| **Phase 6** | `d19c569` | Deprecation cleanup + ConfigurationService MagicWallet |
+| **Phase 7a** | `469d97b` | Cosmetic cleanup + حذف orphan handler |
+| **Phase 7b** | `161f796` | Embed orderId در callback URL |
+| **Phase 7c** | `8446e0e` | حذف ۴ handler deprecated (۱۴ فایل، −۱,۱۲۵ خط) |
+| **Phase 8b** | `ce8e248` | NuGet bump → 0.0.185 |
+| **Phase 8d** | `7554d70` | حذف ۴ RPC + ۸ message deprecated از Proto |
+| **Phase 8e** | `aaaf7fc` | Per-package filtering در Commission queries |
+| **Phase 8f** | `dcd1135` | PackageFeature CRUD support |
+| **Audit** | `1ac2366` | Compliance audit — Feature DIFF + حذف fallbackهای hardcoded |
+| **Phase 9a** | `a1024a3` | Q24: آستانه موجودی `≤1M` ریال + Q26: SP Worker auto-deploy (IHostedService + checksum) |
+| **Phase 9b** | `fdbb91d` | Q27: PackageHistory + ClubMembershipCycleHistory entities + enums + EF configs |
+| **Phase 9d** | `10d2ca2` | Rename UserWalletChangeLog→UserWalletHistory (86 فایل) + IHasHistory + Interceptor + Migration |
+
+### 4.2 FrontOffice — ۸ کامیت
+
+| فاز | کامیت | شرح |
+|-----|--------|------|
+| **Phase 7a** | `b82cac4` | حذف "پکیج طلایی" + PackageTitle در DTO |
+| **Phase 7b** | `71f391a` | مهاجرت به Customer* RPCs |
+| **Phase 8a** | `0bbc11e` | Checkout wire-up به Customer RPCs |
+| **Phase 8c** | `d71d463` | صفحات پکیج — فیچرهای داینامیک |
+| **Phase 8d** | `40882c8` | NuGet bump Proto cleanup |
+| **Phase 8e** | `a956cb9` | Per-package filtering در Commission pages |
+| **Phase 8f** | `3bffc13` | T4.2+T4.3+F3: پرداخت شرطی + خرید مجدد + PV |
+| **Audit** | `816dcb7` | حذف ۵۶M hardcoded — قیمت‌گذاری داینامیک |
+| **Phase 9c** | `474d364` | Q28: UI Guidance alerts (G1-G7) — ۷ صفحه MudAlert آموزشی |
+
+### 4.3 BackOffice — ۶ کامیت
+
+| فاز | کامیت | شرح |
+|-----|--------|------|
+| **Phase 7a** | `f1b0085` | تغییر label "پکیج طلایی" → "خرید پکیج" |
+| **Phase 8b** | `89f5241` | Package CRUD expansion — ۱۲ فیلد جدید |
+| **Phase 8d** | `c96377a` | NuGet bump Proto cleanup |
+| **Phase 8e** | `8be98ae` | Per-package commission filtering + PackageSelect component |
+| **Phase 8f** | `e020354` | ChangeParentDialog + PackageFeature checkbox matrix |
+| **Audit** | `e6cf90e` | ManualPaymentDialog — حذف ۵۶M + Amount editable |
+| **Phase 9c** | `6939780` | Q28: UI Guidance alerts (G8-G13) — ۶ صفحه MudAlert |
+
+---
+
+## 5. پلن مهاجرت مرحله‌به‌مرحله
+
+### 📋 پیش‌نیازها
+
+- [ ] بکاپ کامل از دیتابیس Production
+- [ ] بکاپ از stateهای Kubernetes (Deployments, ConfigMaps)
+- [ ] اطمینان از دسترسی به Container Registry (تصاویر فعلی)
+- [ ] زمان‌بندی Maintenance Window (ترجیحاً شب یا آخر هفته)
+- [ ] اطلاع‌رسانی به کاربران (در صورت نیاز به downtime)
+
+---
+
+### مرحله ۱ از ۶: بکاپ و آماده‌سازی محیط 🛡️
+
+> ⏱️ تخمین: ۳۰ دقیقه
+
+```
+1.1  بکاپ کامل دیتابیس
+     └── pg_dump -Fc cms_db > cms_backup_pre_package_migration.dump
+
+1.2  بکاپ دیتابیس BO (اگر جداست)
+     └── pg_dump -Fc bo_db > bo_backup_pre_package_migration.dump
+
+1.3  ثبت وضعیت فعلی
+     └── تعداد رکوردها:
+         • ClubMemberships: SELECT COUNT(*) ...
+         • ClubMembershipCycles: SELECT COUNT(*) ...
+         • WeeklyCommissionPools: SELECT COUNT(*) ...
+         • UserCommissionPayouts: SELECT COUNT(*) ...
+         • NetworkWeeklyBalances: SELECT COUNT(*) ...
+         • Packages: SELECT COUNT(*) ...
+
+1.4  ذخیره نسخه فعلی Docker images
+     └── docker tag <current-cms> cms:rollback-point
+     └── docker tag <current-fo> fo:rollback-point
+     └── docker tag <current-bo> bo:rollback-point
+```
+
+**✅ Checkpoint:** بکاپ‌ها ذخیره شده‌اند و قابل restore هستند.
+
+---
+
+### مرحله ۲ از ۶: استقرار CMS (Backend) 🏗️
+
+> ⏱️ تخمین: ۴۵ دقیقه  
+> ⚠️ **ترتیب بحرانی:** CMS باید **اول** deploy شود چون FO و BO به آن وابسته‌اند.
+
+```
+2.1  Build CMS Docker image
+     └── cd CMS/src
+     └── docker build -t cms:package-based .
+
+2.2  اجرای EF Migration
+     └── این migration شامل:
+         • ۱۱ ستون جدید به جدول Packages
+         • جدول جدید PackageFeatures  
+         • ستون PackageId به ۵ جدول (ClubMemberships, Cycles, Pools, Payouts, Balances)
+         • ۴ ستون First/Last به ClubMemberships
+         • Unique Indexها
+
+     ⚠️ Migration خودکار اجرا می‌شود در startup اگر EF auto-migration فعال باشد.
+     ✅ اگر دستی: dotnet ef database update
+
+2.3  Data Backfill — مقداردهی پکیج پایه
+     └── اسکریپت SQL:
+     ┌──────────────────────────────────────────────────────────┐
+     │  -- مشخص کردن ID پکیج پایه                               │
+     │  DO $$                                                    │
+     │  DECLARE base_pkg_id BIGINT;                              │
+     │  BEGIN                                                    │
+     │      SELECT "Id" INTO base_pkg_id                         │
+     │      FROM "CMS"."Packages"                                │
+     │      WHERE "IsBasePackage" = true LIMIT 1;                │
+     │                                                           │
+     │      -- ClubMemberships                                   │
+     │      UPDATE "CMS"."ClubMemberships"                       │
+     │      SET "FirstActivationDate" = "ActivatedAt",           │
+     │          "LastActivationDate" = "ActivatedAt",            │
+     │          "FirstPackageId" = base_pkg_id,                  │
+     │          "LastPackageId" = base_pkg_id                    │
+     │      WHERE "FirstActivationDate" IS NULL;                 │
+     │                                                           │
+     │      -- ClubMembershipCycles                              │
+     │      UPDATE "CMS"."ClubMembershipCycles"                  │
+     │      SET "PackageId" = base_pkg_id                        │
+     │      WHERE "PackageId" IS NULL;                           │
+     │                                                           │
+     │      -- WeeklyCommissionPools                             │
+     │      UPDATE "CMS"."WeeklyCommissionPools"                 │
+     │      SET "PackageId" = base_pkg_id                        │
+     │      WHERE "PackageId" IS NULL;                           │
+     │                                                           │
+     │      -- UserCommissionPayouts                             │
+     │      UPDATE "CMS"."UserCommissionPayouts"                 │
+     │      SET "PackageId" = base_pkg_id                        │
+     │      WHERE "PackageId" IS NULL;                           │
+     │                                                           │
+     │      -- NetworkWeeklyBalances                             │
+     │      UPDATE "CMS"."NetworkWeeklyBalances"                 │
+     │      SET "PackageId" = base_pkg_id                        │
+     │      WHERE "PackageId" IS NULL;                           │
+     │                                                           │
+     │      RAISE NOTICE 'Migration done: PackageId=%',          │
+     │          base_pkg_id;                                     │
+     │  END $$;                                                  │
+     └──────────────────────────────────────────────────────────┘
+
+2.4  Verification — بررسی migration
+     ┌──────────────────────────────────────────────────────────┐
+     │  SELECT 'ClubMemberships' AS tbl, COUNT(*)               │
+     │  FROM "CMS"."ClubMemberships"                            │
+     │  WHERE "LastPackageId" IS NULL                            │
+     │  UNION ALL                                                │
+     │  SELECT 'Cycles', COUNT(*)                                │
+     │  FROM "CMS"."ClubMembershipCycles"                       │
+     │  WHERE "PackageId" IS NULL                                │
+     │  UNION ALL                                                │
+     │  SELECT 'Pools', COUNT(*)                                 │
+     │  FROM "CMS"."WeeklyCommissionPools"                      │
+     │  WHERE "PackageId" IS NULL                                │
+     │  UNION ALL                                                │
+     │  SELECT 'Payouts', COUNT(*)                               │
+     │  FROM "CMS"."UserCommissionPayouts"                      │
+     │  WHERE "PackageId" IS NULL                                │
+     │  UNION ALL                                                │
+     │  SELECT 'Balances', COUNT(*)                              │
+     │  FROM "CMS"."NetworkWeeklyBalances"                      │
+     │  WHERE "PackageId" IS NULL;                               │
+     │                                                           │
+     │  -- ✅ همه باید 0 باشند!                                  │
+     └──────────────────────────────────────────────────────────┘
+
+2.5  Seed پکیج نقره‌ای (اگر توسط EF Seed انجام نشده)
+     └── INSERT پکیج نقره‌ای + PackageFeatures
+
+2.5b اجرای Migration دوم: Q27_HistoryTables_And_RenameWalletHistory
+     └── این migration شامل:
+         • RenameTable: UserWalletChangeLogs → UserWalletHistories (حفظ داده‌ها!)
+         • RenameIndex × 2 + sp_rename PK + FK × 2
+         • CreateTable: PackageHistories (فیلدهای Old*/New*)
+         • CreateTable: ClubMembershipCycleHistories (فیلدهای Old*/New*)
+     ⚠️ داده‌های قبلی UserWalletChangeLogs حفظ می‌شوند (RenameTable نه DropTable)
+
+2.6  Deploy CMS به Kubernetes
+     └── kubectl set image deployment/cms cms=cms:package-based
+     └── kubectl rollout status deployment/cms
+
+2.7  Health Check
+     └── curl http://cms-service/health
+     └── بررسی لاگ‌ها: kubectl logs deployment/cms --tail=100
+```
+
+**✅ Checkpoint:** CMS جدید بالا آمده، migration اجرا شده، همه رکوردها PackageId دارند.
+
+---
+
+### مرحله ۳ از ۶: استقرار FrontOffice 🖥️
+
+> ⏱️ تخمین: ۲۰ دقیقه  
+> پیش‌نیاز: CMS باید بالا و سالم باشد
+
+```
+3.1  Build FrontOffice Docker image
+     └── cd FrontOffice/src
+     └── docker build -t fo:package-based .
+
+3.2  Deploy به Kubernetes
+     └── kubectl set image deployment/frontoffice fo=fo:package-based
+     └── kubectl rollout status deployment/frontoffice
+
+3.3  Smoke Test
+     └── ✅ صفحه پکیج‌ها باز می‌شود (کاشی‌های داینامیک)
+     └── ✅ جزئیات پکیج — فیچرها نمایش داده می‌شود
+     └── ✅ صفحه پاداش‌ها — فیلتر پکیج کار می‌کند
+     └── ✅ صفحه تعادل‌ها — per-package نمایش داده می‌شود
+     └── ✅ متن قرارداد — مبلغ داینامیک (نه ۵۶M hardcoded)
+```
+
+**✅ Checkpoint:** FrontOffice جدید بالا آمده و صفحات اصلی کار می‌کنند.
+
+---
+
+### مرحله ۴ از ۶: استقرار BackOffice 🛠️
+
+> ⏱️ تخمین: ۲۰ دقیقه  
+> پیش‌نیاز: CMS باید بالا و سالم باشد
+
+```
+4.1  Build BackOffice Docker image
+     └── cd BackOffice/src
+     └── docker build -t bo:package-based .
+
+4.2  Deploy به Kubernetes
+     └── kubectl set image deployment/backoffice bo=bo:package-based
+     └── kubectl rollout status deployment/backoffice
+
+4.3  Smoke Test
+     └── ✅ CRUD پکیج — ۱۲ فیلد جدید نمایش داده می‌شود
+     └── ✅ ماتریس فیچر — checkboxها load می‌شوند
+     └── ✅ گزارش تعادل‌ها — فیلتر پکیج کار می‌کند
+     └── ✅ گزارش پرداخت‌ها — ستون پکیج نمایش داده می‌شود
+     └── ✅ ManualPayment — مبلغ editable (نه ۵۶M disabled)
+```
+
+**✅ Checkpoint:** BackOffice جدید بالا آمده و CRUD + گزارشات کار می‌کنند.
+
+---
+
+### مرحله ۵ از ۶: بررسی پورسانت (بحرانی!) 💰
+
+> ⏱️ تخمین: ۳۰ دقیقه  
+> ⚠️ پورسانت = پول واقعی — دقت مضاعف لازم است
+
+```
+5.1  بررسی SP پارامترها
+     └── محاسبه پورسانت هفته تستی (staging)
+     └── بررسی: هر پکیج Pool جداگانه دارد
+     └── بررسی: MaxBalancesPerLeg صحیح (پایه=۳۰۰, نقره‌ای=۳۰)
+     └── بررسی: MaxNetworkLevel صحیح
+
+5.2  مقایسه نتایج
+     └── اجرای محاسبه در staging
+     └── مقایسه Pool مبلغ با محاسبه دستی
+     └── ✅ تفاوت < ۱% قابل قبول
+
+5.3  بررسی carryover
+     └── ✅ carryover فقط per-package
+     └── ✅ تغییر پکیج → ریست carryover
+```
+
+**✅ Checkpoint:** محاسبات پورسانت per-package صحیح هستند.
+
+---
+
+### مرحله ۶ از ۶: تنظیمات نهایی و بررسی سلامت ✅
+
+> ⏱️ تخمین: ۱۵ دقیقه
+
+```
+6.1  بررسی PackageFeatures seed شده‌اند
+     └── SELECT * FROM "CMS"."PackageFeatures";
+     └── پکیج پایه: همه فیچرها ✅
+     └── پکیج نقره‌ای: فیچرهای تعیین‌شده ✅
+
+6.2  بررسی JWT Claims (اختیاری)
+     └── لاگین یک کاربر تست → decode JWT
+     └── ✅ PackageId وجود دارد
+     └── ✅ CanRepurchase صحیح
+
+6.3  غیرفعال کردن Maintenance Mode (اگر فعال بود)
+
+6.4  مانیتورینگ ۲۴ ساعته
+     └── بررسی لاگ خطاها
+     └── بررسی response timeها
+     └── بررسی پرداخت‌های جدید
+```
+
+**✅ مهاجرت تکمیل شد!**
+
+---
+
+## 6. Rollback Plan
+
+### سناریو ۱: مشکل در Migration دیتابیس
+
+```bash
+# Restore از بکاپ
+pg_restore -d cms_db cms_backup_pre_package_migration.dump
+
+# Rollback CMS image
+kubectl set image deployment/cms cms=cms:rollback-point
+```
+
+### سناریو ۲: مشکل در CMS (بعد Migration موفق)
+
+```bash
+# ⚠️ نکته: migration undo ممکن نیست (ستون‌های جدید اضافه شده‌اند)
+# اما کد قدیمی با ستون‌های nullable مشکلی ندارد
+
+# Rollback فقط CMS image
+kubectl set image deployment/cms cms=cms:rollback-point
+```
+
+### سناریو ۳: مشکل در FO/BO
+
+```bash
+# FO و BO مستقل از هم هستند — هرکدام جداگانه rollback
+kubectl set image deployment/frontoffice fo=fo:rollback-point
+kubectl set image deployment/backoffice bo=bo:rollback-point
+```
+
+### نکته مهم Rollback:
+- ستون‌های جدید **nullable** هستند → کد قدیمی بدون مشکل کار می‌کند
+- جدول `PackageFeatures` جدید است → کد قدیمی آن را ignore می‌کند
+- **فقط Data Backfill** غیرقابل‌برگشت است (ولی ضرری ندارد — فقط NULL → مقدار)
+
+---
+
+## 7. چک‌لیست تست قبل از Production
+
+### 🛒 خرید و فعال‌سازی
+
+| # | تست | روش | نتیجه مورد انتظار |
+|---|------|------|-------------------|
+| 1 | خرید پکیج نقره‌ای (ZarinPal) | از FO → پکیج‌ها → نقره‌ای → پرداخت | Balance = ۵.۶M, Discount = ۱۱.۲M |
+| 2 | خرید پکیج پایه (ZarinPal) | از FO → پکیج‌ها → پایه → پرداخت | Balance = ۵۶M, Discount = ۱۱۲M |
+| 3 | خرید پکیج پایه (Daya Loan) | از FO → پکیج‌ها → پایه → دایا | Balance = ۵۶M + loan created |
+| 4 | پرداخت دستی (BO) | از BO → ManualPayment → مبلغ دلخواه | Amount editable, not hardcoded |
+| 5 | فعال‌سازی با نقره‌ای | فعال‌سازی باشگاه بعد خرید نقره‌ای | فقط فیچرهای نقره‌ای فعال (نه همه) |
+| 6 | فعال‌سازی با پایه | فعال‌سازی باشگاه بعد خرید پایه | همه فیچرها فعال |
+
+### 🔄 چرخه Magic + خرید مجدد
+
+| # | تست | نتیجه مورد انتظار |
+|---|------|-------------------|
+| 7 | تکمیل چرخه Magic → ریست | PackagePurchaseMethod = None |
+| 8 | خرید مجدد همان پکیج | بدون قرارداد مجدد، فقط شارژ wallet |
+| 9 | خرید مجدد پکیج متفاوت (پایه → نقره‌ای) | DIFF اجرا: فیچرهای اضافی غیرفعال |
+
+### 💰 پورسانت per-package
+
+| # | تست | نتیجه مورد انتظار |
+|---|------|-------------------|
+| 10 | Pool جداگانه هر پکیج | WeeklyCommissionPool با PackageId متفاوت |
+| 11 | MaxBalancesPerLeg متفاوت | پایه=۳۰۰, نقره‌ای=۳۰ |
+| 12 | Carryover per-downline-package | تغییر پکیج خود کاربر → carryover حفظ (بر اساس زیرمجموعه‌ها) |
+| 13 | SP پارامترها از Package | بدون hardcoded ۳۰۰/۱۵ |
+
+### 📊 گزارشات per-package
+
+| # | تست | نتیجه مورد انتظار |
+|---|------|-------------------|
+| 14 | FO — فیلتر dropdown پکیج | فیلتر عملکرد صحیح |
+| 15 | FO — breakdown پاداش per-package | مبالغ صحیح به تفکیک |
+| 16 | BO — فیلتر پکیج در تعادل‌ها | فیلتر عملکرد صحیح |
+| 17 | BO — ستون پکیج در پرداخت‌ها | نام پکیج نمایش داده می‌شود |
+
+### 📋 UI / قرارداد
+
+| # | تست | نتیجه مورد انتظار |
+|---|------|-------------------|
+| 18 | متن قرارداد — مبلغ داینامیک | مبلغ و نام پکیج صحیح (نه ۵۶M hardcoded) |
+| 19 | ActivationSection — قیمت | از API خوانده می‌شود |
+| 20 | BO — ManualPayment editable | مبلغ قابل ویرایش با validation |
+| 21 | BO — Package CRUD ۱۲ فیلد | همه فیلدهای جدید ذخیره/بارگذاری |
+| 22 | BO — Feature Matrix | checkboxها sync با DB |
+
+---
+
+## 8. ریسک‌ها و نکات بحرانی
+
+### 🔴 ریسک‌های بحرانی
+
+| # | ریسک | احتمال | تاثیر | کاهش‌دهنده |
+|---|-------|--------|-------|------------|
+| R1 | Migration دیتابیس — PackageId اشتباه | کم | **فاجعه** | Verification query (مرحله 2.4) + بکاپ |
+| R2 | SP تغییریافته → محاسبات مالی اشتباه | متوسط | **فاجعه** | تست staging + مقایسه دستی |
+| R3 | Magic Wallet EXIT — سقف global به‌جای per-package | متوسط | **بالا** | بررسی MW1-MW3 در CMS handlers |
+| R4 | قرارداد حقوقی — مبلغ اشتباه | کم | **حقوقی** | متن قرارداد داینامیک ✅ فیکس شده |
+
+### 🟡 ریسک‌های متوسط
+
+| # | ریسک | کاهش‌دهنده |
+|---|-------|------------|
+| R5 | Proto breaking change | Field numberها backward compatible (فقط اضافه) |
+| R6 | NuGet version mismatch بین repos | همه روی v0.0.189 ✅ |
+| R7 | JWT claims — cache invalidation | کاربران باید re-login کنند |
+| R8 | ~~Validator hardcoded 1B~~ | ✅ فیکس شد — `SystemConstants.WalletMaxSafeAmount` (10B) حصار ایمنی |
+
+### ⚠️ تغییرات آینده (هنوز پیاده‌نشده — Phase بعدی)
+
+این موارد در BIZ spec شناسایی شده‌اند ولی **هنوز پیاده نشده‌اند**:
+
+| # | مورد | شدت | شرح |
+|---|------|------|------|
+| ~~F1~~ | ~~WalletChangeLog + PackageId~~ | ✅ انجام‌شده | CMS:`e5bc3a9` — PackageId در UserWalletHistory |
+| ~~F2~~ | ~~Notification + PackageId~~ | ✅ انجام‌شده | CMS:`61b7e4f` — SmsTemplates+IUserNotificationService+UserNotificationService با packageName |
+| ~~F3~~ | ~~Background Services + PackageId~~ | ✅ بررسی‌شده | بدون تغییر — هر ۳ worker از قبل per-package صحیح کار می‌کنند |
+| ~~F4~~ | ~~CSV exports + ستون پکیج~~ | ✅ انجام‌شده | CMS:`61b7e4f` BO:`92c9922` — proto+handler+CSV برای ManualPayments/WithdrawalRequests |
+| ~~F5~~ | ~~SystemConfiguration per-package~~ | ✅ بررسی‌شده | بدون تغییر — مقادیر per-package قبلاً به Package entity منتقل شده‌اند |
+| ~~F6~~ | ~~MagicWalletChargePage hardcoded~~ | ✅ انجام‌شده | CMS:`61b7e4f` FO:`ecc4f44` — magic_multiplier+magic_max_credit از API، داشبورد "شارژ چند‌برابری" |
+| ~~F7~~ | ~~Validators async per-package~~ | ✅ انجام‌شده | CMS:`61b7e4f` FO:`ecc4f44` — SystemConstants.WalletMaxSafeAmount (10B) حصار ایمنی، سقف واقعی per-package در هندلر |
+| ~~F8~~ | ~~آستانه موجودی ورود به Magic (Q24)~~ | ✅ انجام‌شده | CMS:`a1024a3` — `Balance <= 1_000_000` |
+| ~~F9~~ | ~~SP Worker — مدیریت خودکار SP (Q26)~~ | ✅ انجام‌شده | CMS:`a1024a3` — `StoredProcedureDeploymentService` |
+| ~~F10~~ | ~~History Tables — یکسان‌سازی + خودکار (Q27)~~ | ✅ انجام‌شده | CMS:`fdbb91d`+`10d2ca2` — IHasHistory + Interceptor + RenameTable migration |
+| ~~F11~~ | ~~UI Guidance — آموزش و هشدار (Q28)~~ | ✅ انجام‌شده | FO:`474d364` BO:`6939780` — ۱۳ صفحه MudAlert |
+
+> ✅ **F1-F11 همه پیاده‌سازی شدند.**
+
+---
+
+## ضمیمه: ۳۰ تصمیم بیزینسی (Q1–Q30)
+
+### پیاده‌شده (Q1–Q23):
+
+| # | تصمیم | وضعیت |
+|---|-------|-------|
+| Q1 | باگ DiscountBalance → فیکس | ✅ `8b9c317` |
+| Q2 | ادغام ۳ مسیر پرداخت → Generic | ✅ `ccb938e` + `8446e0e` |
+| Q3 | پکیج نقره‌ای + پایه — داینامیک | ✅ `ae92ab8` + `a9cd2fd` |
+| Q4 | ActivationFee یک فیلد (حذف GiftValue) | ✅ `ae92ab8` |
+| Q5 | DiscountMultiplier داینامیک | ✅ `8e5c7c5` |
+| Q6 | Migration کاربران فعلی → پکیج پایه | ✅ `a9cd2fd` |
+| Q7 | خرید N بار بعد تکمیل چرخه | ✅ `fe3edd1` + `8e5c7c5` |
+| Q8 | Commission Pool جدا per-package | ✅ `607f791` |
+| Q9 | MagicWallet Multiplier داینامیک | ✅ `8e5c7c5` |
+| Q10 | دایا = پکیج پایه (نه طلایی) | ✅ `ccb938e` |
+| Q11 | فیچرها داینامیک per-package | ✅ `dcd1135` |
+| Q12 | MaxBalancesPerLeg per-package | ✅ `607f791` |
+| Q13 | MaxNetworkLevel per-package | ✅ `607f791` |
+| Q14 | MagicWalletMaxDeposit per-package | ✅ `ae92ab8` |
+| Q15 | MagicWalletMaxCredit per-package | ✅ `ae92ab8` |
+| Q16 | NetworkWeeklyBalance + PackageId | ✅ `ae92ab8` |
+| Q17 | گزارش FO breakdown per-package | ✅ `a956cb9` |
+| Q18 | گزارش BO فیلتر per-package | ✅ `8be98ae` |
+| Q19 | قرارداد فقط یک بار | ✅ `1ac2366` |
+| Q20 | فیچر DIFF/تفاضل | ✅ `1ac2366` |
+| Q21 | First/Last ActivationDate | ✅ `ae92ab8` |
+| Q22 | تشخیص هفته از LastActivationDate | ✅ `607f791` |
+| Q23 | Carryover strictly per-package | ✅ `607f791` |
+
+### تصمیمات v6 (Q24–Q30) — ✅ تکمیل‌شده:
+
+| # | تصمیم | وضعیت | کامیت |
+|---|-------|-------|-------|
+| Q24 | آستانه موجودی ≤ ۱,۰۰۰,۰۰۰ ریال (ورود Magic + خرید مجدد) | ✅ | CMS:`a1024a3` |
+| Q25 | DayaLoans فقط پکیج پایه — تایید (بدون تغییر کد) | ✅ تایید | — |
+| Q26 | SP Worker — auto-deploy با checksum (IHostedService) | ✅ | CMS:`a1024a3` |
+| Q27 | History Tables — PackageHistory + CycleHistory + IHasHistory + Interceptor + Rename UserWalletChangeLog→UserWalletHistory | ✅ | CMS:`fdbb91d`+`10d2ca2` |
+| Q28 | UI Guidance — ۱۳ صفحه MudAlert آموزشی/هشداری در FO/BO | ✅ | FO:`474d364` BO:`6939780` |
+| Q29 | شرط EXIT Magic — تایید: آخرین پکیج فعال (بدون تغییر کد) | ✅ تایید | — |
+| Q30 | Carryover — تایید: توضیح مستند شد (بدون تغییر کد) | ✅ تایید | — |
+
+---
+
+*آخرین بروزرسانی: ۱۰ اسفند ۱۴۰۴ — v7: F1-F7 همه تکمیل‌شده ✅ | ۵۱+ کامیت (۲۱ CMS + ۹ FO + ۷ BO + ۱۴+ docs) | NuGet v0.0.189 | Notifications+PackageName, CSV ستون پکیج, Dynamic MagicWallet, SystemConstants validators*

deployment/SERVER-MIRRORS-CONFIG.md

@@ -1,208 +0,0 @@
-# Server Mirrors Configuration
-
-**Server:** 194.5.195.53  
-**Date:** 2026-01-29
-
----
-
-## 1. Docker Registry Mirrors (K3s)
-
-فایل: `/etc/rancher/k3s/registries.yaml`
-
-### ترتیب Pull کردن ایمیج‌ها:
-1. **Nexus** (194.5.195.53:32082) - لوکال
-2. **ArvanCloud** (docker.arvancloud.ir) - ایران
-3. **Original Registry** - اصلی
-
-### رجیستری‌های پیکربندی شده:
-
-| Registry | Mirrors (به ترتیب اولویت) |
-|----------|--------------------------|
-| `docker.io` | Nexus → ArvanCloud → registry-1.docker.io |
-| `ghcr.io` | Nexus → ArvanCloud |
-| `gcr.io` | Nexus → ArvanCloud |
-| `registry.k8s.io` | Nexus → ArvanCloud |
-| `quay.io` | Nexus → ArvanCloud |
-| `mcr.microsoft.com` | Nexus → ArvanCloud |
-
-### کانفیگ فعلی:
-
-```yaml
-mirrors:
-  "docker.io":
-    endpoint:
-      - "http://194.5.195.53:32082"
-      - "https://docker.arvancloud.ir"
-      - "https://registry-1.docker.io"
-  "ghcr.io":
-    endpoint:
-      - "http://194.5.195.53:32082"
-      - "https://docker.arvancloud.ir"
-  "gcr.io":
-    endpoint:
-      - "http://194.5.195.53:32082"
-      - "https://docker.arvancloud.ir"
-  "registry.k8s.io":
-    endpoint:
-      - "http://194.5.195.53:32082"
-      - "https://docker.arvancloud.ir"
-  "quay.io":
-    endpoint:
-      - "http://194.5.195.53:32082"
-      - "https://docker.arvancloud.ir"
-  "mcr.microsoft.com":
-    endpoint:
-      - "http://194.5.195.53:32082"
-      - "https://docker.arvancloud.ir"
-configs:
-  "194.5.195.53:32082":
-    auth:
-      username: admin
-      password: 87zH26nbqT
-```
-
-### اعمال تغییرات:
-```bash
-systemctl restart k3s
-```
-
----
-
-## 2. APT Package Mirrors (Ubuntu 24.04 Noble)
-
-فایل: `/etc/apt/sources.list.d/ubuntu.sources`
-
-### ترتیب دانلود پکیج‌ها:
-1. **ArvanCloud** (mirror.arvancloud.ir) - ایران
-2. **Ubuntu Official** (archive.ubuntu.com) - اصلی
-
-### کانفیگ فعلی:
-
-```
-Types: deb
-URIs: http://mirror.arvancloud.ir/ubuntu http://archive.ubuntu.com/ubuntu
-Suites: noble noble-updates noble-backports
-Components: main universe restricted multiverse
-Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
-
-Types: deb
-URIs: http://mirror.arvancloud.ir/ubuntu http://security.ubuntu.com/ubuntu
-Suites: noble-security
-Components: main universe restricted multiverse
-Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
-```
-
-### اعمال تغییرات:
-```bash
-apt update
-```
-
-### بکاپ:
-```
-/etc/apt/sources.list.d/ubuntu.sources.bak
-```
-
----
-
-## 3. NPM Mirror (Runflare)
-
-فایل: `/root/.npmrc`
-
-### تنظیم فعلی:
-```
-registry=https://registry.npmjs.org
-# Fallback mirrors (use if main is slow)
-# npm config set registry https://mirror-npm.runflare.com
-```
-
-### برای تغییر به میرور ایرانی:
-```bash
-npm config set registry https://mirror-npm.runflare.com
-```
-
-### برای برگشت به اصلی:
-```bash
-npm config set registry https://registry.npmjs.org
-```
-
----
-
-## 4. PIP/PyPI Mirror (Runflare)
-
-فایل: `/root/.config/pip/pip.conf`
-
-### تنظیم فعلی (با fallback خودکار):
-```ini
-[global]
-index-url = https://pypi.org/simple
-extra-index-url = https://mirror-pypi.runflare.com/simple
-trusted-host = mirror-pypi.runflare.com
-               pypi.org
-```
-
-**توضیح:** PIP اول از `pypi.org` میگیره، اگه نبود از `mirror-pypi.runflare.com` میگیره.
-
----
-
-## 5. Nexus Repository Manager
-
-| Item | Value |
-|------|-------|
-| URL | http://194.5.195.53:32082 |
-| UI | http://194.5.195.53:32081 |
-| Username | admin |
-| Password | 87zH26nbqT |
-
-### Docker Repositories:
-
-| Name | Type | Remote URL |
-|------|------|------------|
-| `docker-hosted` | hosted | - |
-| `docker-arvancloud-proxy` | proxy | https://docker.arvancloud.ir |
-| `docker-hub-proxy` | proxy | https://registry-1.docker.io |
-| `docker-all` | group | hosted → arvancloud → docker-hub |
-
-### NuGet Repositories:
-
-| Name | Type | Remote URL |
-|------|------|------------|
-| `nuget-hosted` | hosted | - |
-| `foursat-nuget-hosted` | hosted | - |
-| `nuget-runflare-proxy` | proxy | https://mirror-nuget.runflare.com/v3/index.json |
-| `nuget.org-proxy` | proxy | https://api.nuget.org/v3/index.json |
-| `nuget-group` | group | hosted → runflare → nuget.org |
-
-### ایمیج‌های ذخیره شده با ورژن:
-
-| Image | Tags |
-|-------|------|
-| `mcr.microsoft.com/mssql/server` | `2022-CU16`, `2022-latest` |
-| `gitea/gitea` | `1.25.3`, `latest` |
-| `gitea/act_runner` | `0.2.11`, `latest` |
-| `registry.k8s.io/ingress-nginx/controller` | `v1.14.1` |
-
----
-
-## 6. Iranian Mirror URLs Summary
-
-| سرویس | URL | استفاده |
-|-------|-----|---------|
-| Docker | `https://docker.arvancloud.ir` | K3s + Nexus |
-| Ubuntu APT | `http://mirror.arvancloud.ir/ubuntu` | apt sources |
-| NuGet | `https://mirror-nuget.runflare.com/v3/index.json` | Nexus proxy |
-| NPM | `https://mirror-npm.runflare.com` | npmrc (دستی) |
-| PyPI | `https://mirror-pypi.runflare.com/simple` | pip.conf (fallback) |
-
----
-
-## 7. مزایای این پیکربندی
-
-✅ **سرعت بالا** - میرورهای ایرانی سریع‌ترن  
-✅ **Fallback خودکار** - اگه میرور در دسترس نبود، اصلی استفاده میشه  
-✅ **Offline Support** - ایمیج‌های مهم در Nexus لوکال هستن  
-✅ **کاهش ترافیک خارجی** - اول از سرورهای داخلی استفاده میشه  
-✅ **Cache در Nexus** - پکیج‌ها و ایمیج‌ها cache میشن  
-
----
-
-*Last Updated: 2026-01-29*

docs/DB-INTEGRITY-AUDIT-20260417.md

@@ -0,0 +1,356 @@
+# گزارش ممیزی صحت داده‌های دیتابیس CMS
+
+**تاریخ بررسی:** 1405/01/28 (2026-04-17)  
+**فایل بکاپ:** `dbbkup/CMS-20260417.sql` (4.9MB, 21,397 خط)  
+**تعداد جداول:** ~47 جدول | **تعداد کاربران:** 115 | **تعداد سفارشات:** 72
+
+---
+
+## فهرست مطالب
+
+1. [خلاصه اجرایی](#خلاصه-اجرایی)
+2. [اصلاحیه مهم — PaymentStatus](#اصلاحیه-مهم)
+3. [دسته ۱ — ورود دستی / مهاجرت دیتا](#دسته-۱--ورود-دستی--مهاجرت-دیتا)
+4. [دسته ۲ — باگ‌های کد](#دسته-۲--باگهای-کد)
+5. [دسته ۳ — وضعیت Stored Procedure‌ها](#دسته-۳--وضعیت-stored-procedureها)
+6. [آمار کلی جداول](#آمار-کلی-جداول)
+7. [خلاصه مالی](#خلاصه-مالی)
+8. [اقدامات پیشنهادی](#اقدامات-پیشنهادی)
+
+---
+
+## خلاصه اجرایی
+
+بکاپ دیتابیس CMS در تاریخ 17 آوریل 2026 تحلیل شد. تحلیل شامل بررسی صحت داده‌ها، ارجاعات خارجی (FK)، زنجیره مالی، و تطبیق با کد سورس C# و Stored Procedure‌ها بود.
+
+**وضعیت کلی:** سیستم در حال مهاجرت از ساختار استاتیک به پکیج‌محور بوده. بخش عمده مشکلات ناشی از ورود دستی داده و مهاجرت سیستم دایا است. چند باگ کد نیز در SP کمیسیون و Worker دایا شناسایی شد.
+
+---
+
+## اصلاحیه مهم
+
+> **`PaymentStatus=0` در enum کد یعنی `Success` نه `Pending`!**
+> 
+> ```csharp
+> // PaymentStatus.cs
+> Success = 0,
+> Reject = 1,
+> Pending = 2
+> ```
+> 
+> بنابراین تمام 72 سفارش واقعاً **موفق** هستند. این مشکل نیست.
+
+---
+
+## دسته ۱ — ورود دستی / مهاجرت دیتا
+
+### 1A) موجودی 56M بدون فلگ `HasReceivedDayaCredit`
+
+**شدت:** 🟠 متوسط  
+**علت:** ورود دستی / مهاجرت  
+
+- **23 کاربر** دقیقاً 56,000,000 ریال در `Balance` دارند ولی `HasReceivedDayaCredit = 0`
+- فقط **16 کاربر** از طریق Daya Worker صحیح اعتبار گرفتند (`HasReceivedDayaCredit = 1`)
+- بقیه احتمالاً دستی شارژ شدند بدون ثبت تاریخچه
+
+**کاربران آسیب‌پذیر:**
+
+| UserId | نام | Balance | HasReceivedDayaCredit |
+|--------|-----|---------|----------------------|
+| 51 | مرتضی اینالو | 56,000,000 | 0 |
+| 58 | وحید حق‌گو | 56,000,000 | 0 |
+| 87 | امیررضا محمدی | 56,000,000 | 0 |
+| 43 | کریم خادمی | 56,000,000 | 0 |
+| 52 | حمیدرضا اسمعیلی | 56,000,000 | 0 |
+| 88 | کریم رعیت‌پیشه | 56,000,000 | 0 |
+| 91 | رحیم رعیت‌پیشه | 56,000,000 | 0 |
+| 93 | ریحانه سادات هاشمی‌نصر | 56,000,000 | 0 |
+| 99 | هستی خادمی | 56,000,000 | 0 |
+| 110 | علی وفائی | 56,000,000 | 0 |
+| 113 | کاوس بیگ‌اینالو | 56,000,000 | 0 |
+| 119 | علیرضا کریمی‌پیروز | 56,000,000 | 0 |
+| 122 | ابوالقاسم عابدی | 56,000,000 | 0 |
+| 123 | ناصر کریمی‌پیروز | 56,000,000 | 0 |
+| 124 | محمدرضا باغجری | 56,000,000 | 0 |
+| 126 | امیرعباس میرزایی | 56,000,000 | 0 |
+| 138 | سیما اکبرزاده | 56,000,000 | 0 |
+| 139 | مسعود توسلیان | 56,000,000 | 0 |
+| 142 | صغری شبانکاره | 56,000,000 | 0 |
+| 170 | لیلا خدارحمی | 56,000,000 | 0 |
+| 172 | مهرافشان زاهدنیا | 56,000,000 | 0 |
+| 175 | ناهید حسن‌زاده | 56,000,000 | 0 |
+| 176 | مهریدخت میکانیکی | 56,000,000 | 0 |
+
+---
+
+### 1B) کد ملی تکراری — اکانت‌های تستی
+
+**شدت:** 🟡 پایین  
+**علت:** ورود دستی / تست  
+
+| کد ملی | تعداد اکانت | UserIdها | نام |
+|--------|------------|----------|-----|
+| مشترک #1 | 6 | 9, 11, 12, 13, 40, 41 | مهدی مرجانی |
+| مشترک #2 | 3 | 7, 8, 10 | مهدی صیفی |
+| مشترک #3 | 2 | 42, 43 | کریم خادمی |
+| مشترک #4 | 2 | 50, 51 | مرتضی اینالو |
+| مشترک #5 | 2 | 120, 190 | عسلی |
+
+- شماره موبایل تکراری: `09038888074` بین کاربران 120 و 190
+
+---
+
+### 1C) `NetworkInfos` خالی — مهاجرت صحیح انجام شده
+
+**شدت:** ✅ مشکل نیست  
+
+جدول `NetworkInfos` خالی است چون داده‌های شبکه به فیلدهای مستقیم `Users` مهاجرت شدند:
+- `Users.NetworkParentId` ← FK به والد شبکه
+- `Users.LegPosition` ← Left(0) / Right(1)
+
+مهاجرت در `20250601_MigrateParentIdToNetworkParentId.sql` انجام شده. entity `NetworkInfo` در C# وجود ندارد. SP‌ها هم از `Users.NetworkParentId` استفاده می‌کنند.
+
+---
+
+### 1D) `PasswordHash = NULL` برای تمام 115 کاربر
+
+**شدت:** 🟡 نیاز به بررسی  
+**علت:** احتمالاً بکاپ شامل فیلد پسورد نشده، یا سیستم OTP/موبایل استفاده می‌کند  
+
+---
+
+### 1E) دوره‌های عضویت باشگاه — `PaidAmount = 0`
+
+**شدت:** 🟡 نیاز به بررسی  
+
+- 87 دوره `ClubMembershipCycles` همه `PaidAmount = 0`
+- ممکن است عضویت باشگاه خودکار با خرید پکیج فعال شود (نه پرداخت جداگانه)
+
+---
+
+## دسته ۲ — باگ‌های کد
+
+### 2A) تراکنش‌های تکراری دایا — Race Condition در `CheckAndProcessDayaLoansCommandHandler`
+
+**شدت:** 🔴 بحرانی  
+**فایل:** `CMSMicroservice.Application/DayaLoanCQ/Commands/CheckAndProcessDayaLoans/CheckAndProcessDayaLoansCommandHandler.cs`  
+
+**یافته‌ها:**
+- **109 رکورد `DayaLoanContracts`** ولی فقط **16 کاربر** `HasReceivedDayaCredit=1`
+- **64 تراکنش** با «دریافت اعتبار دایا» ساخته شده ولی فقط **11 رکورد `UserPackagePurchases`**
+- تراکنش‌ها با `RefId` منحصربه‌فرد ساخته شدند (مثل `C4_T8579002`) — همه در `2025-11-19 01:24:24` ایجاد شدند
+
+**تحلیل ریشه‌ای:**
+- Daya Worker (Hangfire هر 15 دقیقه) احتمالاً برای بعضی کاربران **چند بار** اجرا شده
+- `CreateTransaction` و `DayaLoanContract` ساخته شده ولی `HasReceivedDayaCredit=true` ست نشده (exception بعد از SaveChanges اول ولی قبل از SaveChanges دوم)
+- یا: چون همه در یک لحظه ساخته شدند (`2025-11-19 01:24:24`)، ممکن است **یک بار bulk import دستی** بوده
+
+**ریسک:** کاربرانی که `HasReceivedDayaCredit=0` دارند ممکن است **دوباره** از Worker اعتبار بگیرند.
+
+---
+
+### 2B) SP `sp_CalculateWeeklyCommissionPool` — `DistributedAmount` آپدیت نمی‌شود
+
+**شدت:** 🔴 بحرانی  
+**فایل:** `dbbkup/CMS-20260417.sql` خط ~18830  
+
+در Step 10 (آپدیت نهایی Pool):
+
+```sql
+-- کد فعلی (باگ‌دار):
+UPDATE CMS.WeeklyCommissionPools 
+SET 
+    IsCalculated = 1, 
+    CalculatedAt = @CalculatedAt,
+    TotalBalances = @TotalBalances,
+    ValuePerBalance = @ValuePerBalance,
+    LastModified = @CalculatedAt,
+    LastModifiedBy = 'SP'
+WHERE Id = @PoolId;
+```
+
+**مشکل:** فیلد `DistributedAmount` **هرگز مقداردهی نمی‌شود** و 0 باقی می‌ماند.
+
+**نتیجه در دیتا:**
+- 15 استخر، مجموع `TotalPoolAmount = 2,016,000,000` ریال
+- همه `DistributedAmount = 0`
+- ولی 46 پرداخت واقعاً ثبت و به `NetworkBalance` اضافه شدند
+
+---
+
+### 2C) `UserWalletChangeLogs` خالی
+
+**شدت:** 🟠 متوسط  
+**فایل:** SP Step 9 + `CalculateWeeklyCommissionPoolCommandHandler.cs`  
+
+- SP باید در Step 9 لاگ تغییرات کیف‌پول را در `UserWalletChangeLogs` ذخیره کند
+- جدول **صفر رکورد** دارد
+- **احتمال 1:** SP هرگز Step 9 را درست اجرا نکرده
+- **احتمال 2:** ORM Strategy (نه SP) استفاده شده و آن `UserWalletChangeLogs` نمی‌نویسد
+- **احتمال 3:** لاگ‌ها در حین ForceRecalculate حذف شدند
+
+---
+
+### 2D) `WalletHistory.ChangeType = NULL` در تمام 239 رکورد
+
+**شدت:** 🟠 متوسط  
+**فایل:** `UserOrderService.cs` و `PackageService.cs` — هرجا `UserWalletHistory` ساخته می‌شود  
+
+- فیلد `ChangeType` هرگز ست نمی‌شود
+- کد از `IsIncrease` (bool) برای تفکیک واریز/برداشت استفاده می‌کند
+- `ChangeType` احتمالاً فیلد قدیمی deprecated شده
+
+---
+
+### 2E) `NetworkWeeklyBalances.WeeklyCommissionPoolId = NULL` (805 رکورد)
+
+**شدت:** 🟡 پایین  
+
+- SP مقدار `WeeklyPoolContribution = 0` ثبت می‌کند و PoolId ست نمی‌شود
+- ارتباط بین `NetworkWeeklyBalances` و `WeeklyCommissionPools` از طریق `WeekDefinitionId` برقرار است، نه FK مستقیم
+- **عملاً مشکل عملکردی ایجاد نمی‌کند** ولی tracking سخت‌تر می‌شود
+
+---
+
+### 2F) 30 سفارش کیف‌پولی — بررسی WalletHistory
+
+**شدت:** 🟠 نیاز به تأیید  
+
+- 30 سفارش با `PaymentMethod=1` (Wallet) ثبت شدند
+- اولین بررسی نشان داد «هیچ برداشتی ثبت نشده» — **اما** این بررسی بر اساس `ChangeType` بود که همه NULL هستند
+- **باید بر اساس `IsIncrease=0` (false = decrease)** دوباره بررسی شود
+- `SubmitShopBuyOrder()` در کد `UserWalletHistory` می‌سازد — احتمالاً رکوردها وجود دارند ولی `ChangeType` NULL است
+
+---
+
+## دسته ۳ — وضعیت Stored Procedure‌ها
+
+### `GetNetworkTree`
+
+| آیتم | وضعیت |
+|------|--------|
+| از `Users.NetworkParentId` استفاده می‌کند | ✅ صحیح (بعد از مهاجرت) |
+| JOIN با `ClubMemberships` | ✅ صحیح |
+| `MAXRECURSION 0` | ✅ صحیح |
+| فیلتر `IsDeleted = 0` | ✅ صحیح |
+
+### `sp_CalculateWeeklyBalances`
+
+| آیتم | وضعیت |
+|------|--------|
+| پارامتر `@PackageId` از `Packages.IsBasePackage` | ✅ صحیح |
+| `MaxBalancesPerLeg` و `MaxNetworkLevel` از Package | ✅ صحیح |
+| Carryover از هفته قبل | ✅ صحیح |
+| CTE recursive برای چپ/راست | ✅ صحیح |
+| `TotalBalances = MIN(left, right)` | ✅ صحیح |
+| `SubordinateBalances` محاسبه | ✅ صحیح |
+| 805 رکورد تولید شده | ✅ کار می‌کند |
+
+### `sp_CalculateWeeklyCommissionPool`
+
+| آیتم | وضعیت |
+|------|--------|
+| `ValuePerBalance = TotalPoolAmount / TotalBalances` | ✅ صحیح |
+| ایجاد `UserCommissionPayouts` | ✅ صحیح (46 رکورد) |
+| ثبت `CommissionPayoutHistories` | ✅ صحیح |
+| شارژ `NetworkBalance` کیف‌پول | ✅ صحیح |
+| آپدیت `DistributedAmount` در Pool | ❌ **انجام نمی‌شود** |
+| ثبت `UserWalletChangeLogs` | ⚠️ نامشخص |
+| ForceRecalculate — Revert | ✅ منطق صحیح |
+
+---
+
+## آمار کلی جداول
+
+| جدول | تعداد | وضعیت |
+|------|--------|--------|
+| Users | 115 | |
+| UserWallets | 115 | |
+| UserWalletHistories | 239 | ChangeType همه NULL |
+| UserWalletChangeLogs | 0 | ⚠️ خالی |
+| UserOrders | 72 | همه PaymentStatus=0 (Success) |
+| FactorDetails | 177 | |
+| Transactions | 175 | 64 تراکنش دایا |
+| PaymentTransactions | 22 | فقط DiscountOrders + شارژ |
+| Products | 163 | |
+| Categories | 14 | |
+| InventoryItems | 175 | |
+| StockMovements | 242 | 11 chain issue |
+| ClubMemberships | 88 | همه IsActive=1 |
+| ClubMembershipCycles | 87 | همه PaidAmount=0 |
+| UserClubFeatures | 249 | |
+| NetworkInfos | 0 | ✅ deprecated — مهاجرت شده |
+| NetworkWeeklyBalances | 805 | PoolId همه NULL |
+| WeeklyCommissionPools | 15 | DistributedAmount همه 0 |
+| UserCommissionPayouts | 46 | Status=3, مبالغ کلان |
+| WeekDefinitions | 59 | |
+| Packages | 2 | Base=56M, Secondary=5.6M |
+| DayaLoanContracts | 109 | |
+| UserPackagePurchases | 11 | |
+| DiscountOrders | 13 | |
+| DiscountOrderDetails | 14 | |
+| DiscountCategories | 8 | |
+| OrderVATs | 44 | ✅ محاسبات صحیح |
+| UserAddresses | 127 | |
+| Roles | 3 | user, admin, Administrator |
+| UserRoles | 119 | 115 user + 2 admin + 2 Administrator |
+| ProductImages | 4 | |
+| ShippingMethods | 0 | ⚠️ خالی |
+| SitePages | 0 | ⚠️ خالی |
+| SystemConfigurations | 0 | ⚠️ خالی |
+| Coupons | 0 | ⚠️ خالی |
+| ProductProperties | 0 | ⚠️ خالی |
+
+---
+
+## خلاصه مالی
+
+### موجودی‌های کل سیستم
+
+| فیلد | مبلغ (ریال) |
+|------|-------------|
+| مجموع `Balance` کل کیف‌پول‌ها | 2,548,684,394 |
+| مجموع `NetworkBalance` (کمیسیون) | 453,599,993 |
+| مجموع `DiscountBalance` (تخفیف) | 7,326,400,000 |
+| مجموع سفارشات (UserOrders) | 1,039,410,812 |
+| مجموع استخر کمیسیون (WeeklyPools) | 2,016,000,000 |
+
+### پکیج‌ها
+
+| Package | قیمت | IsBase | MaxBalancesPerLeg | MaxNetworkLevel | DiscountMultiplier |
+|---------|-------|--------|-------------------|-----------------|-------------------|
+| Package 1 | 56,000,000 | ✅ | 300 | 1,000,000 | 2.0 |
+| Package 4 | 5,600,000 | ❌ | 30 | 1,000,000 | 2.0 |
+
+### ارجاعات شکسته (FK)
+
+| ارجاع | تعداد |
+|-------|--------|
+| FactorDetails → OrderId ناموجود | 2 (DetailId=22,23 → OrderId=21) |
+| InventoryItems ≠ آخرین StockMovement | 3 |
+| StockMovement chain breaks | 11 |
+
+---
+
+## اقدامات پیشنهادی
+
+### اولویت بالا (انجام ندهید تا بررسی بیشتر)
+
+1. **فیکس SP `sp_CalculateWeeklyCommissionPool`:** اضافه کردن `DistributedAmount` به UPDATE نهایی
+2. **بررسی Daya Worker:** race condition در `CheckAndProcessDayaLoansCommandHandler` — ممکن است تراکنش تکراری بسازد
+3. **23 کاربر با 56M بدون فلگ دایا:** تعیین اینکه آیا دستی شارژ شدند یا از Worker — سپس اصلاح `HasReceivedDayaCredit`
+
+### اولویت متوسط
+
+4. **WalletHistory ChangeType:** تأیید اینکه deprecated شده و `IsIncrease` جایگزین است
+5. **UserWalletChangeLogs خالی:** بررسی اینکه ORM Strategy استفاده شده یا SP Strategy
+6. **اکانت‌های تکراری:** تصمیم‌گیری درباره 13 اکانت تکراری (حذف/ادغام)
+
+### اولویت پایین
+
+7. **جداول خالی:** SystemConfigurations, ShippingMethods, SitePages — آیا باید از seed پر شوند؟
+8. **StockMovement chain issues:** 11 ناسازگاری — آیا از ورود دستی موجودی بوده؟
+
+---
+
+*این گزارش فقط مستندات یافته‌ها است. هیچ تغییری در کد یا دیتابیس اعمال نشده است.*

docs/MOVED-TO-TOTALDOC.md

@@ -1 +0,0 @@
-Docs moved to /totalDoc — see totalDoc/INDEX.md

docs/analyze-backoffice-ui.sh

@@ -1,49 +0,0 @@
-#!/bin/bash
-
-echo "=========================================="
-echo "BackOffice UI Services Usage Analysis"
-echo "=========================================="
-
-UI_PATH="/home/masoud/Apps/project/FourSat/BackOffice/src/BackOffice"
-OUTPUT="/home/masoud/Apps/project/FourSat/docs/BACKOFFICE-UI-SERVICES.md"
-
-cat > "$OUTPUT" << 'EOF'
-# BackOffice UI - Services Usage Report
-
-**Generated**: 
-**Purpose**: لیست تمام صفحات و سرویس‌هایی که استفاده می‌کنند
-
----
-
-## Summary
-
-EOF
-
-echo "### Services Used by Pages" >> "$OUTPUT"
-echo "" >> "$OUTPUT"
-
-# تحلیل هر صفحه
-find "$UI_PATH/Pages" -name "*.razor.cs" -type f | while read -r file; do
-    page_name=$(basename "$file" .razor.cs)
-    relative_path=$(echo "$file" | sed "s|$UI_PATH/||")
-    
-    # پیدا کردن Inject شده‌ها
-    services=$(grep -E "\[Inject\].*Service|IService" "$file" 2>/dev/null | grep -v "^//" | sed 's/^[[:space:]]*//')
-    
-    if [ -n "$services" ]; then
-        echo "#### $page_name" >> "$OUTPUT"
-        echo "" >> "$OUTPUT"
-        echo "**Path**: \`$relative_path\`" >> "$OUTPUT"
-        echo "" >> "$OUTPUT"
-        echo "**Services**:" >> "$OUTPUT"
-        echo '```csharp' >> "$OUTPUT"
-        echo "$services" >> "$OUTPUT"
-        echo '```' >> "$OUTPUT"
-        echo "" >> "$OUTPUT"
-    fi
-done
-
-echo ""
-echo "✅ UI Analysis complete!"
-echo "📄 Output: $OUTPUT"
-

docs/analyze-bff-services.sh

@@ -1,65 +0,0 @@
-#!/bin/bash
-
-# BackOffice BFF Services Analyzer
-# این اسکریپت تمام services در BFF رو تحلیل و لیست می‌کنه
-
-echo "=========================================="
-echo "BackOffice BFF Services Analysis"
-echo "=========================================="
-echo ""
-
-BFF_PATH="/home/masoud/Apps/project/FourSat/BackOffice.BFF/src/BackOffice.BFF.WebApi/Services"
-OUTPUT_FILE="/home/masoud/Apps/project/FourSat/docs/BFF-SERVICES-DETAIL.md"
-
-# شروع فایل خروجی
-cat > "$OUTPUT_FILE" << 'EOF'
-# BackOffice BFF Services - Detailed Analysis
-
-**Generated**: $(date +"%Y-%m-%d %H:%M:%S")
-
-این مستند به صورت خودکار تولید شده و شامل تحلیل دقیق هر service در BFF است.
-
----
-
-EOF
-
-# تحلیل هر service
-for service_file in "$BFF_PATH"/*Service.cs; do
-    if [ -f "$service_file" ]; then
-        service_name=$(basename "$service_file" .cs)
-        
-        echo "Processing: $service_name"
-        
-        # اضافه کردن به مستند
-        echo "## $service_name" >> "$OUTPUT_FILE"
-        echo "" >> "$OUTPUT_FILE"
-        echo "**File**: \`$service_file\`" >> "$OUTPUT_FILE"
-        echo "" >> "$OUTPUT_FILE"
-        
-        # پیدا کردن methods
-        echo "### Methods:" >> "$OUTPUT_FILE"
-        echo "" >> "$OUTPUT_FILE"
-        grep -E "public override async Task" "$service_file" | sed 's/^[[:space:]]*//' >> "$OUTPUT_FILE"
-        echo "" >> "$OUTPUT_FILE"
-        
-        # پیدا کردن dependencies (Inject شده‌ها)
-        echo "### Dependencies:" >> "$OUTPUT_FILE"
-        echo "" >> "$OUTPUT_FILE"
-        grep -E "private readonly|private.*_.*;" "$service_file" | head -10 >> "$OUTPUT_FILE"
-        echo "" >> "$OUTPUT_FILE"
-        
-        # تعداد خطوط کد
-        lines=$(wc -l < "$service_file")
-        echo "**Lines of Code**: $lines" >> "$OUTPUT_FILE"
-        echo "" >> "$OUTPUT_FILE"
-        echo "---" >> "$OUTPUT_FILE"
-        echo "" >> "$OUTPUT_FILE"
-    fi
-done
-
-echo ""
-echo "✅ Analysis complete!"
-echo "📄 Output: $OUTPUT_FILE"
-echo ""
-echo "Summary:"
-find "$BFF_PATH" -name "*Service.cs" | wc -l | xargs echo "Total Services:"

docs/migrate-bff-to-cms-proto.sh

@@ -1,162 +0,0 @@
-#!/bin/bash
-# BackOffice BFF to CMS Proto Migration Script
-# This script replaces BFF proto namespaces with CMS proto namespaces
-
-set -e
-
-BACKOFFICE_DIR="/home/masoud/Apps/project/FourSat/BackOffice/src/BackOffice"
-
-echo "🔄 Starting BFF to CMS Proto Migration..."
-
-# Mapping: BFF namespace -> CMS namespace
-# Pattern: BackOffice.BFF.X.Protobuf.Protos.X -> CMSMicroservice.Protobuf.Protos.X
-# Pattern: Foursat.BackOffice.BFF.X.Protos -> CMSMicroservice.Protobuf.Protos.X
-# Pattern: BackOffice.BFF.Protobuf.Common -> CMSMicroservice.Protobuf.Protos
-
-# Category
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.Category\.Protobuf\.Protos\.Category/CMSMicroservice.Protobuf.Protos.Category/g' {} \;
-echo "✅ Category namespace migrated"
-
-# Products
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.Products\.Protobuf\.Protos\.Products/CMSMicroservice.Protobuf.Protos.Products/g' {} \;
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.Products\.Protobuf\.Protos/CMSMicroservice.Protobuf.Protos.Products/g' {} \;
-echo "✅ Products namespace migrated"
-
-# Package
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.Package\.Protobuf\.Protos\.Package/CMSMicroservice.Protobuf.Protos.Package/g' {} \;
-echo "✅ Package namespace migrated"
-
-# User
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.User\.Protobuf\.Protos\.User/CMSMicroservice.Protobuf.Protos.User/g' {} \;
-echo "✅ User namespace migrated"
-
-# UserAddress
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.UserAddress\.Protobuf\.Protos\.UserAddress/CMSMicroservice.Protobuf.Protos.UserAddress/g' {} \;
-echo "✅ UserAddress namespace migrated"
-
-# UserOrder
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.UserOrder\.Protobuf\.Protos\.UserOrder/CMSMicroservice.Protobuf.Protos.UserOrder/g' {} \;
-echo "✅ UserOrder namespace migrated"
-
-# UserRole
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.UserRole\.Protobuf\.Protos\.UserRole/CMSMicroservice.Protobuf.Protos.UserRole/g' {} \;
-echo "✅ UserRole namespace migrated"
-
-# Role
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.Role\.Protobuf\.Protos\.Role/CMSMicroservice.Protobuf.Protos.Role/g' {} \;
-echo "✅ Role namespace migrated"
-
-# Tag
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.Tag\.Protobuf\.Protos\.Tag/CMSMicroservice.Protobuf.Protos.Tag/g' {} \;
-echo "✅ Tag namespace migrated"
-
-# ProductTag
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.ProductTag\.Protobuf\.Protos\.ProductTag/CMSMicroservice.Protobuf.Protos.ProductTag/g' {} \;
-echo "✅ ProductTag namespace migrated"
-
-# Otp -> OtpToken
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.Otp\.Protobuf\.Protos\.Otp/CMSMicroservice.Protobuf.Protos.OtpToken/g' {} \;
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.Otp\.Protobuf\.Validator/CMSMicroservice.Protobuf.Validator.OtpToken/g' {} \;
-echo "✅ Otp namespace migrated"
-
-# Commission (Foursat prefix)
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/Foursat\.BackOffice\.BFF\.Commission\.Protos/CMSMicroservice.Protobuf.Protos.Commission/g' {} \;
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.Commission\.Protos/CMSMicroservice.Protobuf.Protos.Commission/g' {} \;
-echo "✅ Commission namespace migrated"
-
-# ClubMembership (Foursat prefix)
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/Foursat\.BackOffice\.BFF\.ClubMembership\.Protos/CMSMicroservice.Protobuf.Protos.ClubMembership/g' {} \;
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.ClubMembership\.Protos/CMSMicroservice.Protobuf.Protos.ClubMembership/g' {} \;
-echo "✅ ClubMembership namespace migrated"
-
-# NetworkMembership (Foursat prefix)
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/Foursat\.BackOffice\.BFF\.NetworkMembership\.Protos/CMSMicroservice.Protobuf.Protos.NetworkMembership/g' {} \;
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.NetworkMembership\.Protos/CMSMicroservice.Protobuf.Protos.NetworkMembership/g' {} \;
-echo "✅ NetworkMembership namespace migrated"
-
-# Configuration (Foursat prefix)
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/Foursat\.BackOffice\.BFF\.Configuration\.Protos/CMSMicroservice.Protobuf.Protos.Configuration/g' {} \;
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.Configuration\.Protos/CMSMicroservice.Protobuf.Protos.Configuration/g' {} \;
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.Configuration\.Protobuf\.Protos\.AppVersion/CMSMicroservice.Protobuf.Protos.AppVersion/g' {} \;
-echo "✅ Configuration namespace migrated"
-
-# Health (Foursat prefix)
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/Foursat\.BackOffice\.BFF\.Health\.Protobuf/CMSMicroservice.Protobuf.Protos.Health/g' {} \;
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.Health\.Protobuf/CMSMicroservice.Protobuf.Protos.Health/g' {} \;
-echo "✅ Health namespace migrated"
-
-# Inventory (Foursat prefix)
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/Foursat\.BackOffice\.BFF\.Inventory\.Protos/CMSMicroservice.Protobuf.Protos.Inventory/g' {} \;
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.Inventory\.Protos/CMSMicroservice.Protobuf.Protos.Inventory/g' {} \;
-echo "✅ Inventory namespace migrated"
-
-# ManualPayment
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.ManualPayment\.Protobuf/CMSMicroservice.Protobuf.Protos.ManualPayment/g' {} \;
-echo "✅ ManualPayment namespace migrated"
-
-# PublicMessage (Foursat prefix)
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/Foursat\.BackOffice\.BFF\.PublicMessage\.Protobuf/CMSMicroservice.Protobuf.Protos/g' {} \;
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.PublicMessage\.Protobuf/CMSMicroservice.Protobuf.Protos/g' {} \;
-echo "✅ PublicMessage namespace migrated"
-
-# DiscountProduct
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.DiscountProduct\.Protobuf\.Protos\.DiscountProduct/CMSMicroservice.Protobuf.Protos.DiscountProduct/g' {} \;
-echo "✅ DiscountProduct namespace migrated"
-
-# DiscountCategory
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.DiscountCategory\.Protobuf\.Protos\.DiscountCategory/CMSMicroservice.Protobuf.Protos.DiscountCategory/g' {} \;
-echo "✅ DiscountCategory namespace migrated"
-
-# DiscountOrder
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.DiscountOrder\.Protobuf\.Protos\.DiscountOrder/CMSMicroservice.Protobuf.Protos.DiscountOrder/g' {} \;
-echo "✅ DiscountOrder namespace migrated"
-
-# DiscountShoppingCart
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.DiscountShoppingCart\.Protobuf\.Protos\.DiscountShoppingCart/CMSMicroservice.Protobuf.Protos.DiscountShoppingCart/g' {} \;
-echo "✅ DiscountShoppingCart namespace migrated"
-
-# Common types (PaginationState, MetaData)
-find "$BACKOFFICE_DIR" -type f \( -name "*.cs" -o -name "*.razor" \) -exec sed -i \
-    's/BackOffice\.BFF\.Protobuf\.Common/CMSMicroservice.Protobuf.Protos/g' {} \;
-echo "✅ Common types namespace migrated"
-
-echo ""
-echo "🎉 Migration complete!"
-echo ""
-echo "📝 Next steps:"
-echo "1. Update BackOffice.csproj to reference CMS proto instead of BFF proto"
-echo "2. Build and fix any remaining issues"
-echo "3. Update GwUrl in appsettings.json to point to CMS"

migration/BACKOFFICE-BFF-MIGRATION.md

@@ -1,268 +0,0 @@
-# BackOffice BFF to CMS Migration Plan
-
-**هدف**: حذف BackOffice.BFF و ارتباط مستقیم BackOffice (UI) با CMS
-
-**تاریخ شروع**: 2025-02-07  
-**تاریخ تکمیل Build Migration**: 2025-02-08  
-**وضعیت**: ✅ **Build Migration Complete** (0 errors)
-
----
-
-## ✅ خلاصه اجرا
-
-### استراتژی انتخاب‌شده: Strategy C (استفاده مستقیم از Proto های CMS)
-به جای حفظ DLL های BFF، مستقیماً `CMSMicroservice.Protobuf` را به عنوان `ProjectReference` اضافه کردیم و تمام `using` ها را تغییر دادیم.
-
-### نتایج:
-- ✅ تمام 208 reference از `BackOffice.BFF.*` به `CMSMicroservice.Protobuf.Protos.*` تغییر یافت
-- ✅ 24 DLL reference حذف و یک `ProjectReference` جایگزین شد
-- ✅ `appsettings.json` از BFF URL به CMS URL تغییر کرد
-- ✅ ~65 build error رفع شد
-- ✅ **Build Succeeded با 0 خطا**
-
----
-
-## مراحل مهاجرت
-
-### مرحله 1: مستندسازی سرویس‌های BackOffice UI ✅
-- لیست تمام سرویس‌های استفاده شده در UI
-- شناسایی dependency ها
-- مستندسازی هر صفحه و کامپوننت
-
-### مرحله 2: مستندسازی سرویس‌های BackOffice.BFF ✅
-- لیست تمام gRPC services در BFF
-- شناسایی endpoints و methods
-
-### مرحله 3: تحلیل و انتخاب استراتژی ✅
-- تحلیل سه استراتژی ممکن (A, B, C)
-- انتخاب Strategy C: مستقیم از CMS protos
-
-### مرحله 4: مهاجرت کد ✅
-- تغییر namespace ها (208 مورد)
-- رفع خطاهای Build (~65 خطا)
-- اصلاح proto های CMS (اضافه کردن فیلدهای مورد نیاز)
-- آپدیت مستندات
-
----
-
-## 1. سرویس‌های استفاده شده در BackOffice UI
-
-### 1.1 Services مستقیماً از CMS (gRPC Clients)
-
-| Service | Usage Count | Pages/Components |
-|---------|-------------|------------------|
-| `CategoryContract.CategoryContractClient` | 4 | CategoryMultiSelectAutoComplete, CategoryMultiSelectCombo, CategoryAutoComplete |
-| `RoleContract.RoleContractClient` | 3 | RoleAutoComplete, RoleTitleColumn, UserRoleDialog |
-| `ProductsContract.ProductsContractClient` | 1 | ProductsAutoComplete |
-| `UserRoleContract.UserRoleContractClient` | 1 | UserRoleDialog |
-
-### 1.2 Services از طریق BFF (Interface-based)
-
-| Service Interface | Implementation | Purpose |
-|-------------------|----------------|---------|
-| `ITagService` | BFF → CMS | مدیریت تگ‌ها |
-| `IDiscountCategoryService` | BFF → CMS | دسته‌بندی‌های تخفیف |
-| `IPersianDateTimeService` | BFF Local | تبدیل تاریخ شمسی |
-
-### 1.3 صفحات اصلی BackOffice
-
-```
-BackOffice/Pages/
-├── Dashboard/           - داشبورد اصلی
-├── User/                - مدیریت کاربران
-├── UserRole/            - نقش‌های کاربری
-├── Role/                - مدیریت نقش‌ها
-├── Category/            - دسته‌بندی محصولات
-├── Products/            - محصولات
-├── Package/             - پکیج‌ها
-├── Tag/                 - تگ‌ها
-├── UserOrder/           - سفارشات
-├── UserAddress/         - آدرس‌ها
-├── Inventory/           - انبار
-├── Payment/             - پرداخت‌ها
-├── DiscountShop/        - فروشگاه تخفیف
-├── Commission/          - کمیسیون
-├── Network/             - شبکه
-├── Club/                - باشگاه مشتریان
-├── PublicMessages/      - پیام‌های عمومی
-├── Settings/            - تنظیمات
-└── SystemManagement/    - مدیریت سیستم
-```
-
----
-
-## 2. سرویس‌های BackOffice.BFF
-
-### 2.1 لیست کامل gRPC Services در BFF
-
-| # | Service | Proto File | Status | CMS Equivalent |
-|---|---------|------------|--------|----------------|
-| 1 | CategoryService | category.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.Category |
-| 2 | ProductsService | products.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.Products |
-| 3 | TagService | tag.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.Tag |
-| 4 | ProductTagService | producttag.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.ProductTag |
-| 5 | UserService | user.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.User |
-| 6 | RoleService | role.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.Role |
-| 7 | UserRoleService | userrole.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.UserRole |
-| 8 | UserAddressService | useraddress.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.UserAddress |
-| 9 | UserOrderService | userorder.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.UserOrder |
-| 10 | InventoryService | inventory.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.Inventory |
-| 11 | DiscountProductService | discountproduct.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.DiscountProduct |
-| 12 | DiscountOrderService | discountorder.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.DiscountOrder |
-| 13 | DiscountShoppingCartService | discountshoppingcart.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.DiscountCategory |
-| 14 | CommissionService | commission.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.Commission |
-| 15 | NetworkMembershipService | networkmembership.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.NetworkMembership |
-| 16 | ClubMembershipService | clubmembership.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.ClubMembership |
-| 17 | PublicMessageService | publicmessage.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos (PublicMessage) |
-| 18 | ConfigurationService | configuration.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.Configuration |
-| 19 | OtpService | otp.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.OtpToken |
-| 20 | HealthService | health.proto | ✅ Migrated | CMSMicroservice.Protobuf.Protos.Health |
-
-**Status Legend:**
-- ✅ Migrated to CMS (Build compiles successfully)
-
----
-
-## 3. منطق و Business Logic سرویس‌ها
-
-### 3.1 CategoryService
-
-**Path**: `BackOffice.BFF/src/BackOffice.BFF.WebApi/Services/CategoryService.cs`
-
-#### Methods:
-- `GetAllCategories()` - دریافت تمام دسته‌بندی‌ها
-- `GetCategory(id)` - دریافت یک دسته‌بندی
-- `CreateCategory()` - ایجاد دسته‌بندی جدید
-- `UpdateCategory()` - ویرایش دسته‌بندی
-- `DeleteCategory()` - حذف دسته‌بندی
-
-#### Business Logic:
-```
-[در انتظار تحلیل دقیق]
-```
-
-#### Dependencies:
-- CMS CategoryContract
-
----
-
-### 3.2 TagService
-
-**Path**: `BackOffice.BFF/src/BackOffice.BFF.WebApi/Services/TagService.cs`
-
-#### Methods:
-[در انتظار تحلیل]
-
-#### Business Logic:
-[در انتظار تحلیل]
-
----
-
-## 4. پیشرفت مهاجرت
-
-### Services Migration Progress: 20/20 (100%) ✅
-
-| Service | Analysis | Implementation | Testing | Docs Updated | Completed |
-|---------|----------|----------------|---------|--------------|-----------|
-| CategoryService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| ProductsService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| TagService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| ProductTagService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| UserService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| RoleService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| UserRoleService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| UserAddressService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| UserOrderService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| InventoryService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| DiscountProductService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| DiscountOrderService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| CommissionService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| NetworkMembershipService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| ClubMembershipService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| PublicMessageService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| ConfigurationService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| OtpService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| HealthService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-| AppVersionService | ✅ | ✅ | ⬜ | ✅ | ✅ |
-
-> ⚠️ **توجه**: ستون Testing هنوز انجام نشده - تست Runtime باید انجام شود.
-
----
-
-## 5. تغییرات اعمال‌شده
-
-### 5.1 تغییرات اصلی
-- **csproj**: حذف 24 رفرنس DLL و اضافه کردن یک `ProjectReference` به `CMSMicroservice.Protobuf.csproj`
-- **appsettings.json**: تغییر `GwUrl` از `https://backoffice-bff.se.kbs1.ir` به `https://cms.se.kbs1.ir`
-- **ConfigureService.cs**: تغییر تمام 24 `using` و اصلاح نام contract ها (`OtpContract` → `OtpTokenContract`, `InventoryBFFContract` → `InventoryContract`)
-- **208 فایل**: تغییر namespace از `BackOffice.BFF.*` به `CMSMicroservice.Protobuf.Protos.*`
-
-### 5.2 تغییرات Proto های CMS
-فیلدهای زیر به proto های CMS اضافه شدند (چون BackOffice UI به آنها نیاز داشت):
-
-| Proto File | Field Added | Message |
-|-----------|------------|---------|
-| `products.proto` | `ImageFileModel image_file`, `ImageFileModel thumbnail_file` | CreateNewProductsRequest, UpdateProductsRequest |
-| `inventory.proto` | `bool is_low_stock = 18` | InventoryItemDto |
-| `discountproduct.proto` | `ImageFileModel` message + fields | CreateDiscountProductRequest, UpdateDiscountProductRequest |
-| `package.proto` | `BoostCardFileModel` message + fields | CreateNewPackageRequest, UpdatePackageRequest |
-| `manualpayment.proto` | `FileUploadModel` message + fields | CreateManualPaymentRequest |
-
-### 5.3 تغییرات خاص فیلد/منطق
-
-| فایل | تغییر |
-|------|------|
-| LoginPage.razor.cs | `SendOtpRequest` → `CreateNewOtpTokenRequest` + `Purpose = "login"` |
-| VerifyCodePage.razor.cs | `VerifyOtpCodeRequest` → `VerifyOtpTokenRequest` + verify via `UserClient` |
-| PublicMessageService.cs | بازنویسی کامل: `MessageId`→`Id`, `MessageType`→`Type`, `Status`→`IsActive`, `TotalCount`→`MetaData.TotalCount` |
-| UserPayouts.razor.cs | تغییر از nested `PaginationState`/`GetUserPayoutsFilter` به فیلدهای flat |
-| Configuration.razor | تغییر از `PageIndex`/`PageSize` به nested `PaginationState` |
-| HealthDashboard.razor | `GetSystemHealthRequest` → `google.protobuf.Empty` + `HealthStatus` enum handling |
-| NetworkTreeViewer.razor | `ActivationWeekDefinitionId` از `long?` به `string` (StringValue) |
-| PayoutDetailsDialog.razor | `Payout.LastModified` → `Payout.Created` (CMS فیلد LastModified ندارد) |
-| UserOrderDetailsDialog.razor | VAT فیلدها از flat به nested `VatInfo.*` |
-| AppVersionService.cs | حذف wrapper `Item` و تغییر فیلدهای response |
-| ManualPayments.razor | `GetManualPaymentsRequest` → `GetAllManualPaymentsRequest` + enum casts |
-| UserOrderMainPage.razor.cs | `PaymentStatus`/`DeliveryStatus`/`PaymentMethod` enum casts + `Clear*Item()` |
-
-### 5.4 نکات فنی
-- BackOffice UI از gRPC Web استفاده می‌کند
-- Proto codegen rule: مقادیر enum با prefix، prefix آنها در C# حذف می‌شود (مثلاً `DeliveryStatus_Pending` → `DeliveryStatus.Pending`)
-- الگوی `oneof` در CMS: `oneof PaymentStatus_item { ... }` → property accessor مستقیم `PaymentStatus`
-
-### 5.5 چالش‌ها و حل‌شده‌ها
-- ✅ Authentication/Authorization: CMS از IdentityServer استفاده می‌کند
-- ✅ Proto incompatibility: فیلدهای جدید به CMS protos اضافه شدند
-- ✅ Nested vs Flat field pattern: هر سرویس به الگوی CMS proto خودش تبدیل شد
-- ✅ Enum handling: Cast های صریح اضافه شدند
-
-### 5.6 مزایای حاصل‌شده
-- کاهش latency (حذف یک لایه میانی BFF)
-- ساده‌تر شدن معماری
-- کاهش هزینه deployment (یک سرویس کمتر)
-- بهبود performance
-
----
-
-## 6. مراحل بعدی
-
-### Immediate Next Steps:
-1. ✅ ایجاد این مستند
-2. ✅ تحلیل دقیق هر service در BFF
-3. ✅ مهاجرت namespace ها (208 مورد)
-4. ✅ رفع خطاهای Build (~65 خطا)
-5. ✅ Build Succeeded با 0 خطا
-6. ⏳ **تست Runtime** - deploy و تست عملکرد واقعی هر صفحه
-7. ⏳ **بررسی CMS backend** - فیلدهای جدید اضافه‌شده به proto ها نیاز به handler در CMS دارند
-8. ⏳ **حذف BackOffice.BFF** - بعد از تست موفق، سرویس BFF از deployment حذف شود
-
-### ⚠️ نکات مهم برای Runtime:
-- فیلدهایی مثل `is_low_stock` در Inventory و `image_file`/`thumbnail_file` در Products فقط در proto اضافه شده‌اند
-- CMS backend باید handler آنها را برای populate کردن داده پیاده‌سازی کند
-- فیلدهای PublicMessage (`IsDismissible`, `TargetAudience`, `Tags`) در CMS وجود ندارند و به مقادیر default تنظیم شده‌اند
-
----
-
-**Last Updated**: 2025-02-08  
-**Document Version**: 2.0  
-**Status**: ✅ Build Migration Complete - Runtime Testing Pending

migration/DATA-TABLE-MAPPINGS.md

@@ -1,483 +0,0 @@
-# 📋 لیست کامل جداول و Mapping ها
-
-## تعداد کل: 33 جدول
-
-### جداول با تغییر نام (10 جدول)
-
-این جداول در دیتابیس قدیمی نام‌گذاری اشتباه دارند و در دیتابیس جدید اصلاح می‌شوند:
-
-| # | نام قدیمی (Source) | نام جدید (Target) | دلیل تغییر |
-|---|-------------------|-------------------|-----------|
-| 1 | `Categorys` | `Categories` | جمع صحیح Category |
-| 2 | `FactorDetailss` | `FactorDetails` | Detail تکی نیست، s اضافی |
-| 3 | `ProductGalleryss` | `ProductGalleries` | Gallery → Galleries، s اضافی |
-| 4 | `ProductImagess` | `ProductImages` | Image → Images، s اضافی |
-| 5 | `Productss` | `Products` | s اضافی |
-| 6 | `PruductCategorys` | `ProductCategories` | Pruduct → Product + جمع صحیح |
-| 7 | `PruductTags` | `ProductTags` | Pruduct → Product |
-| 8 | `Transactionss` | `Transactions` | s اضافی |
-| 9 | `UserAddresss` | `UserAddresses` | Address → Addresses، s اضافی |
-| 10 | `UserCartss` | `UserCarts` | s اضافی |
-
----
-
-### جداول بدون تغییر نام (23 جدول)
-
-این جداول نام‌گذاری صحیحی دارند:
-
-| # | نام جدول |
-|---|----------|
-| 1 | `ClubFeatures` |
-| 2 | `ClubMembershipHistories` |
-| 3 | `ClubMemberships` |
-| 4 | `CommissionPayoutHistories` |
-| 5 | `Contracts` |
-| 6 | `NetworkMembershipHistories` |
-| 7 | `NetworkWeeklyBalances` |
-| 8 | `OtpTokens` |
-| 9 | `Packages` |
-| 10 | `Roles` |
-| 11 | `SystemConfigurationHistories` |
-| 12 | `SystemConfigurations` |
-| 13 | `Tags` |
-| 14 | `UserClubFeatures` |
-| 15 | `UserCommissionPayouts` |
-| 16 | `UserContracts` |
-| 17 | `UserOrders` |
-| 18 | `UserRoles` |
-| 19 | `Users` |
-| 20 | `UserWalletChangeLogs` |
-| 21 | `UserWallets` |
-| 22 | `WeeklyCommissionPools` |
-| 23 | `WorkerExecutionLogs` |
-
----
-
-## ترتیب پیشنهادی برای Migration
-
-### مرحله 1: جداول پایه (Independent Tables)
-بدون FK، می‌توانند اول migrate شوند:
-
-1. `Roles`
-2. `Tags`
-3. `SystemConfigurations`
-4. `ClubFeatures`
-5. `Packages`
-
-### مرحله 2: جداول کاربری
-FK به Users:
-
-6. `Users` ⚠️ **مهم**: پس از migration → Post-Migration Transformation
-7. `OtpTokens`
-8. `UserRoles`
-9. `UserWallets`
-10. `UserWalletChangeLogs`
-11. `UserAddresses`
-12. `UserCarts`
-
-### مرحله 3: جداول محصولات
-FK به Categories و Products:
-
-13. `Categories`
-14. `Products`
-15. `ProductImages`
-16. `ProductGalleries`
-17. `ProductCategories`
-18. `ProductTags`
-
-### مرحله 4: جداول عضویت و کمیسیون
-
-19. `ClubMemberships`
-20. `ClubMembershipHistories`
-21. `NetworkWeeklyBalances`
-22. `NetworkMembershipHistories`
-23. `CommissionPayoutHistories`
-24. `UserCommissionPayouts`
-25. `WeeklyCommissionPools`
-
-### مرحله 5: جداول قراردادها و تراکنش‌ها
-
-26. `Contracts`
-27. `UserContracts`
-28. `Transactions`
-29. `FactorDetails`
-
-### مرحله 6: جداول کاربری پیشرفته
-
-30. `UserOrders`
-31. `UserClubFeatures`
-
-### مرحله 7: جداول سیستمی
-
-32. `SystemConfigurationHistories`
-33. `WorkerExecutionLogs`
-
----
-
-## تغییرات ساختاری مهم
-
-### 1. Users Table
-**تبدیل Binary Tree:**
-- **قدیمی**: `ParentId` (یک Parent ساده)
-- **جدید**: `NetworkParentId` + `LegPosition` (Binary Tree)
-
-**Post-Migration Script:**
-```sql
--- Script: Scripts/PostMigration_DataTransformation.sql
--- اجرا: خودکار بعد از migration (اگر RunPostMigrationTransformation=true)
-```
-
-**چه کاری انجام می‌دهد:**
-1. ✅ بررسی: آیا Parent ها بیشتر از 2 فرزند دارند؟ (ROLLBACK اگر دارند)
-2. ✅ کپی: `ParentId` → `NetworkParentId`
-3. ✅ تخصیص: `LegPosition` (فرزند اول=Left, فرزند دوم=Right)
-4. ✅ حل Orphan ها: Parent نداشته → `NetworkParentId=NULL`
-5. ✅ Validation نهایی: Binary Tree درست است؟
-6. ✅ آمار: تعداد کل، Left/Right distribution
-
----
-
-## Configuration در appsettings.json
-
-```json
-{
-  "TableMappings": {
-    "Categorys": "Categories",
-    "ClubFeatures": "ClubFeatures",
-    "ClubMembershipHistories": "ClubMembershipHistories",
-    "ClubMemberships": "ClubMemberships",
-    "CommissionPayoutHistories": "CommissionPayoutHistories",
-    "Contracts": "Contracts",
-    "FactorDetailss": "FactorDetails",
-    "NetworkMembershipHistories": "NetworkMembershipHistories",
-    "NetworkWeeklyBalances": "NetworkWeeklyBalances",
-    "OtpTokens": "OtpTokens",
-    "Packages": "Packages",
-    "ProductGalleryss": "ProductGalleries",
-    "ProductImagess": "ProductImages",
-    "Productss": "Products",
-    "PruductCategorys": "ProductCategories",
-    "PruductTags": "ProductTags",
-    "Roles": "Roles",
-    "SystemConfigurationHistories": "SystemConfigurationHistories",
-    "SystemConfigurations": "SystemConfigurations",
-    "Tags": "Tags",
-    "Transactionss": "Transactions",
-    "UserAddresss": "UserAddresses",
-    "UserCartss": "UserCarts",
-    "UserClubFeatures": "UserClubFeatures",
-    "UserCommissionPayouts": "UserCommissionPayouts",
-    "UserContracts": "UserContracts",
-    "UserOrders": "UserOrders",
-    "UserRoles": "UserRoles",
-    "Users": "Users",
-    "UserWalletChangeLogs": "UserWalletChangeLogs",
-    "UserWallets": "UserWallets",
-    "WeeklyCommissionPools": "WeeklyCommissionPools",
-    "WorkerExecutionLogs": "WorkerExecutionLogs"
-  }
-}
-```
-
----
-
-## چک‌لیست قبل از Migration
-
-### 1. ساختار Target Database
-- [ ] همه 33 جدول در Target ایجاد شده‌اند
-- [ ] Schema صحیح است: `[CMS].[TableName]`
-- [ ] Column ها مطابقت دارند
-- [ ] `Users` دارای `NetworkParentId` و `LegPosition` است
-
-### 2. Connection Strings
-- [ ] `SourceDatabase`: IP, Port, Username, Password صحیح
-- [ ] `TargetDatabase`: IP, Port, Username, Password صحیح
-- [ ] Firewall: IP شما مجاز است
-- [ ] SQL User دسترسی `db_datareader` (Source) دارد
-- [ ] SQL User دسترسی `db_datawriter` (Target) دارد
-
-### 3. تنظیمات Migration
-- [ ] `BatchSize`: مناسب با Network شما
-- [ ] `MaxConcurrentTables`: 3 (پیشنهادی)
-- [ ] `RunPostMigrationTransformation`: true
-- [ ] `TableMappings`: همه 33 جدول لیست شده
-
-### 4. Backup
-- [ ] ⚠️ **حتماً** Target Database را Backup بگیرید
-- [ ] فضای کافی روی Disk دارید
-
----
-
-## آمار تخمینی
-
-بر اساس backup file (`dbbkup/CMS.sql`):
-
-| دسته | تعداد جداول | تخمین رکوردها |
-|------|------------|---------------|
-| **Core** (Users, Roles, etc.) | 5 | ~2,000 |
-| **Products** (Categories, Products, etc.) | 8 | ~5,000 |
-| **Club & Network** | 7 | ~10,000 |
-| **Transactions & Orders** | 6 | ~20,000 |
-| **System & Logs** | 7 | ~15,000 |
-| **جمع کل** | **33** | **~50,000+** |
-
-**زمان تخمینی:** 5-10 دقیقه (بسته به Network)
-
----
-
-**نسخه:** 1.0  
-**تاریخ:** December 6, 2025  
-**وضعیت:** ✅ آماده برای Production
-
----
-
-## Post-Migration Binary Tree Transformation
-
-> Merged from `DataMigration/POST-MIGRATION-TRANSFORMATION.md`
-
-## تغییرات اعمال شده
-
-### 1. اضافه شدن SQL Script
-
-**فایل**: `Scripts/PostMigration_DataTransformation.sql`
-
-این اسکریپت **بعد از migration داده‌ها** اجرا می‌شود و تبدیلات زیر را انجام می‌دهد:
-
-#### تبدیل Users Table: `ParentId` → `NetworkParentId + LegPosition`
-
-**مراحل:**
-
-1. **Validation**: بررسی کاربرانی که بیشتر از 2 فرزند دارند (❌ برای binary tree نامعتبر)
-2. **Copy**: کپی `ParentId` به `NetworkParentId`
-3. **Assign LegPosition**:
-   - فرزند اول → Left (0)
-   - فرزند دوم → Right (1)
-4. **Orphan Detection**: پیدا کردن کاربرانی که Parent آنها وجود ندارد
-5. **Final Validation**: تایید یکپارچگی binary tree (هر Parent حداکثر 2 فرزند)
-6. **Statistics**: آمار نهایی
-
----
-
-## جریان کار Migration (بروزرسانی شده)
-
-```
-1. خواندن تنظیمات
-   ↓
-2. اتصال به Source و Target databases
-   ↓
-3. کشف و نگاشت جداول (Table Mappings)
-   ↓
-4. Migration داده‌ها (Batch Processing + Retry)
-   ↓
-5. گزارش نتایج Migration
-   ↓
-6. ✨ Post-Migration Transformation (جدید!)
-   ├─ اجرای Scripts/PostMigration_DataTransformation.sql
-   ├─ تبدیل ParentId → NetworkParentId
-   ├─ تخصیص LegPosition
-   ├─ Validation
-   └─ Log نتایج
-   ↓
-7. پایان
-```
-
----
-
-## تنظیمات جدید
-
-### `appsettings.json`
-
-```json
-{
-  "MigrationSettings": {
-    ...
-    "RunPostMigrationTransformation": true  // ✨ جدید
-  }
-}
-```
-
-**گزینه‌ها:**
-- `true` (پیشفرض): اسکریپت تبدیل بعد از migration اجرا می‌شود
-- `false`: فقط migration داده‌ها انجام می‌شود (تبدیل دستی)
-
----
-
-## خروجی Migration
-
-### قبل:
-```
-[12:35:42 INF] === Migration Complete ===
-[12:35:42 INF] Success: 33 tables, 50,000+ records
-[12:35:42 INF] Failed: 0 tables
-[12:35:42 INF] Duration: 00:05:27
-```
-
-### بعد (با Transformation):
-```
-[12:35:42 INF] === Migration Complete ===
-[12:35:42 INF] Success: 33 tables, 50,000+ records
-[12:35:42 INF] Failed: 0 tables
-[12:35:42 INF] Duration: 00:05:27
-
-[12:35:42 INF] === Starting Post-Migration Data Transformation ===
-[12:35:43 INF] Executing post-migration transformation script...
-[12:35:43 INF] SQL: === Starting Post-Migration Data Transformation ===
-[12:35:43 INF] SQL: Step 1: Validating Users for binary tree conversion...
-[12:35:44 INF] SQL: Step 2: Copying ParentId → NetworkParentId...
-[12:35:44 INF] SQL:   - Updated: 1,250 users
-[12:35:44 INF] SQL: Step 3: Assigning LegPosition (Left/Right)...
-[12:35:45 INF] SQL:   - Updated: 1,250 users
-[12:35:45 INF] SQL: Step 4: Checking for orphaned nodes...
-[12:35:45 INF] SQL:   - No orphaned nodes found
-[12:35:45 INF] SQL: Step 5: Verifying binary tree integrity...
-[12:35:45 INF] SQL:   - Binary tree integrity: OK
-[12:35:45 INF] SQL: Step 6: Migration Statistics:
-[12:35:46 INF] SQL: === Post-Migration Data Transformation Complete ===
-[12:35:46 INF] Post-migration transformation completed successfully
-```
-
----
-
-## Validation Checks
-
-### 1. Binary Tree Violation Check
-
-اگر کاربری بیشتر از 2 فرزند داشته باشد:
-
-```
-ERROR: Cannot proceed with binary tree migration. Please resolve manually.
-
-ParentId  ChildCount  ChildIds
---------  ----------  ----------
-12345     3           67890, 67891, 67892
-```
-
-**راه حل دستی:**
-1. تصمیم بگیرید کدام 2 فرزند در binary tree بمانند
-2. فرزند سوم را به Parent دیگری منتقل کنید
-3. Migration را دوباره اجرا کنید
-
-### 2. Orphaned Nodes Detection
-
-اگر Parent کاربر وجود نداشته باشد:
-
-```
-WARNING: Found orphaned nodes (parent does not exist)!
-
-Id     NetworkParentId  Issue
------  ---------------  -----------------------------
-99999  88888            Orphaned: Parent does not exist
-```
-
-**راه حل خودکار:**
-- اسکریپت این کاربران را به `NetworkParentId = NULL` تبدیل می‌کند (root level)
-
----
-
-## خطاها و عیب‌یابی
-
-### خطا: "Post-migration script not found"
-
-```
-[12:35:46 WRN] Post-migration script not found: /path/to/Scripts/PostMigration_DataTransformation.sql
-[12:35:46 INF] Skipping data transformation. Users table will need manual ParentId→NetworkParentId migration.
-```
-
-**راه حل:**
-- Script را manually اجرا کنید از SQL Server Management Studio
-- یا فایل را در مسیر `Scripts/` قرار دهید و دوباره اجرا کنید
-
-### خطا: "Binary tree integrity violation"
-
-```
-ERROR: Binary tree integrity violation! Some parents have more than 2 children.
-```
-
-**راه حل:**
-1. Query زیر را اجرا کنید تا والدین مشکل‌دار را ببینید:
-```sql
-SELECT 
-    ParentId, 
-    COUNT(*) as ChildCount,
-    STRING_AGG(CAST(Id AS VARCHAR), ', ') as ChildIds
-FROM [CMS].[Users]
-WHERE ParentId IS NOT NULL
-GROUP BY ParentId
-HAVING COUNT(*) > 2;
-```
-
-2. فرزندان اضافی را دستی حل کنید
-3. Migration را دوباره اجرا کنید
-
----
-
-## غیرفعال کردن Transformation
-
-اگر می‌خواهید فقط داده‌ها migrate شوند بدون تبدیل:
-
-```json
-{
-  "MigrationSettings": {
-    "RunPostMigrationTransformation": false
-  }
-}
-```
-
-سپس می‌توانید اسکریپت را **دستی** از SSMS اجرا کنید:
-
-```sql
--- فایل: Scripts/PostMigration_DataTransformation.sql
--- اجرا در: Target Database
-```
-
----
-
-## آمار نهایی
-
-بعد از transformation، این آمار نمایش داده می‌شود:
-
-| Metric | Count |
-|--------|-------|
-| Total Users | 2,500 |
-| Users with NetworkParentId | 1,250 |
-| Users with LegPosition Left | 625 |
-| Users with LegPosition Right | 625 |
-| Root users (no parent) | 1,250 |
-
----
-
-## تغییرات کد
-
-### `MigrationService.cs`
-
-**متد جدید:**
-```csharp
-private async Task RunPostMigrationTransformationAsync(string targetConn, CancellationToken cancellationToken)
-{
-    // 1. خواندن SQL script
-    // 2. اتصال به Target database
-    // 3. اجرای script با handling PRINT messages
-    // 4. Log کردن نتایج
-}
-```
-
-**Integration:**
-- بعد از اتمام موفق migration، اگر `RunPostMigrationTransformation = true` باشد، این متد اجرا می‌شود
-- اگر script یافت نشود، فقط یک warning نمایش داده می‌شود (Migration fail نمی‌شود)
-- اگر transformation fail شود، Migration موفق تلقی می‌شود ولی warning نمایش داده می‌شود
-
----
-
-## مزایا
-
-✅ **خودکار**: نیازی به اجرای دستی script نیست
-✅ **Safe**: اگر fail شود، Migration rollback نمی‌شود
-✅ **Logged**: تمام مراحل در console و file log می‌شود
-✅ **Configurable**: می‌توان غیرفعال کرد
-✅ **Validated**: قبل از commit، تمام validationها انجام می‌شود
-
----
-
-**نسخه:** 1.1  
-**تاریخ:** December 6, 2025  
-**وضعیت:** ✅ Build موفق

migration/GATEWAY-REMOVAL-MIGRATION-PLAN.md

@@ -1,350 +0,0 @@
-# 🚀 نقشه‌راه حذف Gateway ها و انتقال به CMS
-
-> تاریخ: ۳۰ ژانویه ۲۰۲۶
-
-## 🎯 هدف کلی
-
-حذف پیچیدگی معماری با انتقال همه سرویس‌های Gateway به CMS microservice. این کار مزایای زیر داره:
-
-- **Performance بهتر**: حذف network hop اضافی
-- **Simplicity**: کمتر dependency، آسان‌تر maintenance
-- **Cost**: کمتر resource و deployment complexity
-- **Modularity**: ساختار ماژولار در CMS که بعداً قابل جداسازی باشه
-
----
-
-## 📊 وضعیت موجود
-
-### BackOffice.BFF - Services List ✅
-
-| Service | Proto | وضعیت در CMS | Type |
-|---------|-------|-------------|------|
-| AppVersionService | ✅ | ✅ موجود | Direct |
-| CategoryService | ✅ | ✅ موجود | Direct |
-| ClubMembershipService | ✅ | ✅ موجود | Direct |
-| CommissionService | ✅ | ✅ موجود | Direct |
-| ConfigurationService | ✅ | ✅ موجود | Direct |
-| DiscountCategoryService | ✅ | ✅ موجود | Direct |
-| DiscountOrderService | ✅ | ✅ موجود | Direct |
-| DiscountProductService | ✅ | ✅ موجود | Direct |
-| DiscountShoppingCartService | ✅ | ✅ موجود | Direct |
-| HealthService | ✅ | ❌ ندارد | **New** |
-| InventoryService | ✅ | ✅ موجود | Direct |
-| ManualPaymentService | ✅ | ✅ موجود | Direct |
-| NetworkMembershipService | ✅ | ❌ ندارد | **New** |
-| OtpService | ✅ | ✅ موجود (OtpTokenService) | Direct |
-| PackageService | ✅ | ✅ موجود | Direct |
-| ProductTagService | ✅ | ✅ موجود | Direct |
-| ProductsService | ✅ | ✅ موجود | Direct |
-| PublicMessageService | ✅ | ✅ موجود | Direct |
-| RoleService | ✅ | ✅ موجود | Direct |
-| TagService | ✅ | ✅ موجود | Direct |
-| UserAddressService | ✅ | ✅ موجود | Direct |
-| UserOrderService | ✅ | ✅ موجود | Direct |
-| UserRoleService | ✅ | ✅ موجود | Direct |
-| UserService | ✅ | ✅ موجود | Direct |
-
-**خلاصه BackOffice.BFF**: 24 سرویس - 22 موجود در CMS، 2 نیاز به ایجاد
-
----
-
-### FrontOffice.BFF - Services List 🔄
-
-| Service | Proto | وضعیت در CMS | Type | توضیحات |
-|---------|-------|-------------|------|---------|
-| AppVersionGrpcService | ✅ | ✅ موجود | Direct | |
-| CategoriesService | ✅ | ✅ موجود | Direct | |
-| CityService | ✅ | ✅ موجود | Direct | |
-| ClubMembershipService | ✅ | ✅ موجود | Direct | |
-| ClubMembershipGrpcService | ✅ | ✅ موجود | Direct | |
-| CommissionService | ✅ | ✅ موجود | Direct | |
-| ConfigurationGrpcService | ✅ | ✅ موجود | Direct | |
-| DiscountShopService | ✅ | ✅ موجود (partial) | **Extend** | نیاز ترکیب با DiscountProduct/Category/Cart |
-| NetworkMembershipService | ✅ | ❌ ندارد | **New** | |
-| PackageService | ✅ | ✅ موجود | Direct | |
-| ProductsService | ✅ | ✅ موجود | Direct | |
-| ShopingCartService | ✅ | ✅ موجود (UserCartsService) | Direct | |
-| TransactionService | ✅ | ✅ موجود (TransactionsService) | Direct | |
-| UserAddressService | ✅ | ✅ موجود | Direct | |
-| UserOrderService | ✅ | ✅ موجود | Direct | |
-| UserService | ✅ | ✅ موجود | **Customer** | نیاز Customer-specific logic |
-| UserWalletService | ✅ | ✅ موجود | Direct | |
-
-**خلاصه FrontOffice.BFF**: 17 سرویس - 15 موجود، 1 نیاز ایجاد، 1 نیاز extend
-
----
-
-## 🛠️ Migration Strategy
-
-### Phase 1: سرویس‌های جدید در CMS
-
-#### 1.1 HealthService (BackOffice.BFF → CMS)
-
-**مسیر**: `CMS/src/CMSMicroservice.WebApi/Services/HealthService.cs`
-
-```csharp
-// الگوی پیاده‌سازی
-public class HealthService : HealthContract.HealthContractBase
-{
-    public override async Task<HealthCheckResponse> CheckHealth(Empty request, ServerCallContext context)
-    {
-        // Logic: Database connectivity, external services, etc.
-        return new HealthCheckResponse { ... };
-    }
-}
-```
-
-**Dependencies**: 
-- Proto: `CMS/src/CMSMicroservice.Protobuf/Protos/Health.proto`
-- Application Layer: `CMS/src/CMSMicroservice.Application/HealthCQ/`
-
-#### 1.2 NetworkMembershipService (Both → CMS)
-
-**مسیر**: `CMS/src/CMSMicroservice.WebApi/Services/NetworkMembershipService.cs`
-
-```csharp
-public class NetworkMembershipService : NetworkMembershipContract.NetworkMembershipContractBase
-{
-    // Binary Tree Management
-    // User Placement Logic  
-    // Network Statistics
-}
-```
-
-**Dependencies**:
-- Proto: `CMS/src/CMSMicroservice.Protobuf/Protos/NetworkMembership.proto`
-- Application: `CMS/src/CMSMicroservice.Application/NetworkMembershipCQ/`
-- Domain: احتمالاً موجوده، نیاز بررسی
-
----
-
-### Phase 2: ماژولار کردن در CMS
-
-#### ساختار پیشنهادی:
-
-```
-CMS/src/CMSMicroservice.WebApi/Services/
-├── Core/              # سرویس‌های پایه
-│   ├── HealthService.cs
-│   ├── ConfigurationService.cs
-│   └── AppVersionService.cs
-├── UserManagement/    # مدیریت کاربران
-│   ├── UserService.cs
-│   ├── UserRoleService.cs
-│   ├── UserAddressService.cs
-│   ├── UserOrderService.cs
-│   ├── UserWalletService.cs
-│   ├── UserCartsService.cs
-│   └── OtpTokenService.cs
-├── ProductCatalog/    # کاتالوگ محصولات
-│   ├── ProductsService.cs
-│   ├── CategoryService.cs
-│   ├── ProductTagService.cs
-│   ├── TagService.cs
-│   ├── ProductGalleriesService.cs
-│   └── ProductImagesService.cs
-├── DiscountShop/      # فروشگاه تخفیف
-│   ├── DiscountProductService.cs
-│   ├── DiscountCategoryService.cs
-│   ├── DiscountOrderService.cs
-│   └── DiscountShoppingCartService.cs
-├── Commission/        # کمیسیون و شبکه
-│   ├── CommissionService.cs
-│   ├── NetworkMembershipService.cs    # جدید
-│   └── ClubMembershipService.cs
-├── Inventory/         # انبارداری
-│   └── InventoryService.cs
-├── Payment/           # پرداخت
-│   ├── ManualPaymentService.cs
-│   ├── TransactionsService.cs
-│   └── UserWalletChangeLogService.cs
-└── Content/           # محتوا
-    ├── PublicMessageService.cs
-    ├── CityService.cs
-    └── PackageService.cs
-```
-
----
-
-### Phase 3: Proto Files Management
-
-#### موجود در CMS که نیاز تغییر نداره:
-- `Category.proto` ✅
-- `Commission.proto` ✅  
-- `Products.proto` ✅
-- `User.proto` ✅
-- `Configuration.proto` ✅
-- ... (بیشتر protos موجودن)
-
-#### نیاز به اضافه کردن:
-1. **`Health.proto`** - برای health check endpoints
-2. **`NetworkMembership.proto`** - اگر موجود نیست
-
-#### Proto files در Gateway ها که نیاز consolidation دارن:
-```
-BackOffice.BFF/src/Protobufs/ → CMS/src/CMSMicroservice.Protobuf/
-FrontOffice.BFF/src/Protobufs/ → CMS/src/CMSMicroservice.Protobuf/
-```
-
----
-
-### Phase 4: Application Layer Integration  
-
-#### BackOffice.BFF Application CQ → CMS Application
-
-```
-BackOffice.BFF/src/BackOffice.BFF.Application/
-├── CommissionCQ/ → CMS/Application/CommissionCQ/
-├── ProductsCQ/ → CMS/Application/ProductsCQ/
-├── UserCQ/ → CMS/Application/UserCQ/
-└── ...
-```
-
-**Strategy**: 
-- مرج کردن Commands/Queries مشابه
-- حفظ Business Logic موجود در CMS
-- اضافه کردن Gateway-specific logic به CMS
-
-#### مثال: CommissionCQ Migration
-
-**BackOffice.BFF موجود**:
-- `TriggerWeeklyCalculationCommand`
-- `GetUserCommissionPayoutsQuery`  
-- `ApproveWithdrawalCommand`
-
-**CMS موجود**:
-- `CalculateWeeklyCommissionCommand`
-- `GetCommissionPayoutsQuery`
-
-**Strategy**: ترکیب و تکمیل در CMS
-
----
-
-### Phase 5: Client-Side Changes
-
-#### BackOffice UI Changes
-
-```csharp
-// Before (BackOffice → BackOffice.BFF)
-services.AddGrpcClient<UserContract.UserContractClient>(options =>
-{
-    options.Address = new Uri("https://backoffice-bff:443");
-});
-
-// After (BackOffice → CMS)
-services.AddGrpcClient<UserContract.UserContractClient>(options =>
-{
-    options.Address = new Uri("https://cms:443");  
-});
-```
-
-#### FrontOffice UI Changes
-
-```csharp
-// Before (FrontOffice → FrontOffice.BFF)
-services.AddGrpcClient<ProductsContract.ProductsContractClient>(options =>
-{
-    options.Address = new Uri("https://frontoffice-bff:443");
-});
-
-// After (FrontOffice → CMS)  
-services.AddGrpcClient<ProductsContract.ProductsContractClient>(options =>
-{
-    options.Address = new Uri("https://cms:443");
-});
-```
-
----
-
-## 📋 Implementation Plan
-
-### Week 1: Analysis & Proto Consolidation
-- [ ] **Day 1**: تحلیل کامل Dependencies بین Gateway ها و CMS
-- [ ] **Day 2**: Merge کردن Proto files مشابه
-- [ ] **Day 3**: شناسایی Business Logic های unique در Gateway ها  
-- [ ] **Day 4**: ایجاد migration scripts برای Application Layer
-- [ ] **Day 5**: طراحی namespace جدید در CMS
-
-### Week 2: Core Services Migration  
-- [ ] **Day 1-2**: پیاده‌سازی HealthService و NetworkMembershipService در CMS
-- [ ] **Day 3-4**: Migration UserService (با Customer-specific logic)
-- [ ] **Day 5**: تست و validation سرویس‌های جدید
-
-### Week 3: Application Layer Migration
-- [ ] **Day 1-2**: انتقال CommissionCQ از Gateway ها به CMS
-- [ ] **Day 3**: انتقال ProductsCQ
-- [ ] **Day 4**: انتقال UserCQ  
-- [ ] **Day 5**: انتقال باقی CQ modules
-
-### Week 4: Client Integration & Testing
-- [ ] **Day 1-2**: تغییر BackOffice client configuration
-- [ ] **Day 3**: تغییر FrontOffice client configuration  
-- [ ] **Day 4**: End-to-end testing
-- [ ] **Day 5**: Performance testing و optimization
-
-### Week 5: Cleanup & Documentation  
-- [ ] **Day 1-2**: حذف Gateway projects از repository
-- [ ] **Day 3**: بروزرسانی Docker compose و K8s configs
-- [ ] **Day 4**: بروزرسانی deployment scripts
-- [ ] **Day 5**: مستندسازی نهایی
-
----
-
-## ⚠️ Risks & Considerations
-
-### High Risk
-1. **Breaking Changes**: تغییر endpoint URLs در client ها
-2. **Business Logic Loss**: احتمال از دست رفتن logic خاص Gateway ها
-3. **Performance Impact**: CMS ممکنه bottleneck بشه
-
-### Medium Risk  
-1. **Proto Conflicts**: تداخل message names در Proto files
-2. **Authorization**: تفاوت در Authorization logic بین Gateway ها
-3. **Testing Complexity**: نیاز تست کامل همه endpoints
-
-### Mitigation Strategies
-- **Gradual Migration**: یک سرویس در هر مرحله
-- **Feature Flags**: قابلیت switch بین Gateway و CMS
-- **Comprehensive Testing**: Unit + Integration + End-to-end
-- **Rollback Plan**: امکان بازگشت سریع در صورت مشکل
-
----
-
-## 🎯 Success Metrics
-
-### Performance
-- [ ] Response time کاهش یافته (حذف network hop)
-- [ ] Throughput افزایش یافته
-- [ ] Resource usage بهینه شده
-
-### Architecture  
-- [ ] کد duplication کاهش یافته
-- [ ] Maintenance complexity کمتر شده
-- [ ] Deployment pipeline ساده‌تر شده
-
-### Developer Experience
-- [ ] کمتر project برای کار روی یک feature
-- [ ] Debug و troubleshoot آسان‌تر
-- [ ] Documentation کامل و به‌روز
-
----
-
-## 📝 Notes
-
-### Critical Dependencies
-- همه Proto messages باید compatible باشن
-- Authorization و Authentication logic حفظ بشه  
-- Database migration نیازی نیست (همون دیتابیس رو استفاده می‌کنیم)
-
-### Future Modularity
-ساختار ماژولار پیشنهادی باعث میشه بعداً بتونیم:
-- هر ماژول رو به microservice جداگانه تبدیل کنیم
-- Load balancing بین ماژول‌ها داشته باشیم
-- Feature-based deployment انجام بدیم
-
----
-
-**Status**: 🔍 Analysis Complete - Ready for Implementation  
-**Next Step**: شروع Phase 1 - سرویس‌های جدید  
-**Owner**: Development Team  
-**Estimated Duration**: 5 weeks  

migration/MIGRATION-PROGRESS.md

@@ -1,431 +0,0 @@
-# Migration Progress: FrontOffice.BFF → CMS Direct Integration
-
-## Date: 2026-02-01
-
-## Overview
-Migration of FrontOffice from BFF layer to direct CMS microservice integration to eliminate unnecessary abstraction layer and improve architecture.
-
----
-
-## Migration Strategy
-
-### Discovery Phase
-- **Key Finding**: BFF was acting as a DTO transformation layer
-- **Insight**: BFF proto files serve as specification for frontend requirements
-- **Approach**: Systematically compare BFF proto structures with CMS and add missing fields
-
-### Field Aliasing Strategy
-Proto3 doesn't support field number reuse, so we use unique field numbers for alias fields:
-- Original fields keep their numbers (e.g., `name = 2`, `image_url = 8`)
-- Alias fields get new numbers (e.g., `title = 12`, `image_path = 13`)
-- Both fields must be populated in service implementations
-
----
-
-## Completed Work
-
-### ✅ Phase 1: Infrastructure Setup
-- Changed URL from `localhost:32845` (BFF) to `localhost:32846` (CMS)
-- Consolidated multiple BFF proto packages into single `Foursat.CMSMicroservice.Protobuf`
-- Implemented Customer-prefixed API methods for frontend access
-
-### ✅ Phase 2: Proto Package Updates
-
-#### Version 0.0.171 (Successful)
-- Added `models` field aliases in response types:
-  - `GetAllCategoriesForCustomerResponse`: `categories` → `models` (field 2)
-  - `GetCustomerPackagesResponse`: `packages` → `models` (field 1)
-  - `GetAllUserCartsResponse`: `items` → `models` (field 1)
-- Added missing fields:
-  - `GetUserForCustomerResponse.token` (field 16)
-  - `GetClubMembershipResponse.status` (field 11)
-  - `GetClubMembershipResponse.days_remaining` (field 12)
-- Removed duplicate validators in `CMSMicroservice.Protobuf/Validator/UserCarts/`
-
-#### Version 0.0.172 (Current)
-**Proto Changes:**
-- **package.proto**: Added `title` (field 12) and `image_path` (field 13) to `CustomerPackageModel`
-- **usercarts.proto**: 
-  - Added `user_cart_id` (field 11) alias to `UpdateUserCartRequest`
-  - Added `product_short_infomation` (field 14) typo alias to `UserCartItem`
-  - Added `created` timestamp (field 10) to `UserCartItem`
-- **networkmembership.proto**: Added to `NetworkTreeNodeModel`:
-  - `full_name` (field 20) - alias for user_name
-  - `level` (field 21) - alias for network_level
-  - `mobile` (field 14)
-  - `avatar` (field 15)
-  - `position` (field 16)
-  - `left_child` (field 17)
-  - `right_child` (field 18)
-
-**Service Implementation Changes:**
-- Updated `PackageService.GetCustomerPackageDetails` to populate:
-  - `Title = "پکیج طلایی"` (duplicate of Name)
-  - `ImagePath = "/images/packages/golden-detail.jpg"` (duplicate of ImageUrl)
-
-**Build Status:**
-```bash
-✅ Proto build: Success
-✅ Pack version 0.0.172: Success
-✅ Package location: /home/masoud/Apps/project/FourSat/nupkg/Foursat.CMSMicroservice.Protobuf.0.0.172.nupkg
-✅ FrontOffice.Main.csproj updated to version 0.0.172
-```
-
-### ✅ Phase 3: Error Reduction
-- **Initial**: 250+ compilation errors
-- **After 0.0.171**: 217 errors
-- **After 0.0.172**: **170 errors** ⬇️ (32% reduction)
-
----
-
-## Remaining Work
-
-### ⚠️ Critical Issues (170 Errors)
-
-#### 1. Missing Service Methods (8 methods)
-Need to be added to CMS proto services:
-
-**ConfigurationContract:**
-- `GetClubConfigurationAsync`
-- `GetClubFeaturesAsync`
-
-**CommissionContract:**
-- `GetMyCommissionPayoutsAsync`
-- `GetMyWeeklyBalancesAsync`
-
-**NetworkMembershipContract:**
-- `GetMyNetworkTreeAsync`
-- `GetSubordinateTreeAsync`
-- `GetMyNetworkStatisticsAsync`
-
-**UserOrderContract:**
-- `GetVATRateAsync`
-
-#### 2. Missing Proto Fields
-
-**GetWeekDefinitionsRequest** (5 fields):
-```protobuf
-int32 page_number = ?;
-int32 page_size = ?;
-string search_text = ?;
-google.protobuf.Int32Value persian_year = ?;
-google.protobuf.Int32Value gregorian_year = ?;
-google.protobuf.BoolValue is_active = ?;
-```
-
-**WeekDefinitionItem** (2 fields):
-```protobuf
-string start_date_persian = ?;
-string end_date_persian = ?;
-```
-
-#### 3. Type Conversion Issues
-
-**PaginationState conflict:**
-```
-Cannot implicitly convert type 'CMSMicroservice.Protobuf.Protos.PaginationState' 
-to 'CMSMicroservice.Protobuf.Protos.City.PaginationState'
-```
-Location: `Pages/Profile/Components/EditAddressDialog.razor.cs(45,35)`
-
-#### 4. Incomplete Alias Population
-
-Fields with aliases need population in ALL service methods:
-- `CustomerPackageModel.Title` / `ImagePath` (partially done)
-- `NetworkTreeNodeModel.FullName` / `Level`
-- Other alias fields across services
-
----
-
-## Technical Decisions
-
-### Proto Field Number Strategy
-**Problem**: Proto3 doesn't allow field number reuse for aliases
-```protobuf
-// ❌ This doesn't work:
-string name = 2;
-string title = 2; // ERROR: Field number 2 already used
-
-// ✅ Solution:
-string name = 2;
-string title = 12;  // New unique number
-```
-
-### Why Not Update Frontend?
-**Preserving Business Logic**: User requirement is "چیزی کم نشه از بیزینس" (don't lose any business logic). Changing frontend field names risks:
-- Breaking existing functionality
-- Missing edge cases in BFF transformation logic
-- Extensive testing burden
-
-**Field Aliasing Benefits**:
-- Zero frontend changes required
-- Gradual migration path
-- Easy rollback if needed
-- Maintains backward compatibility
-
----
-
-## Next Steps
-
-### Priority 1: Add Missing Methods
-1. Define proto service methods in CMS `.proto` files
-2. Implement method stubs in CMS service classes
-3. Return mock/default data initially
-
-### Priority 2: Add Missing Fields
-1. Add fields to `GetWeekDefinitionsRequest`
-2. Add fields to `WeekDefinitionItem`
-3. Rebuild proto package as version 0.0.173
-
-### Priority 3: Fix Type Issues
-1. Resolve `PaginationState` namespace conflict
-2. Add missing `PaymentGatewayUrl` field
-3. Fix `PaymentMethod` enum reference
-
-### Priority 4: Complete Alias Population
-1. Populate all alias fields in service responses
-2. Ensure data consistency between original and alias fields
-
----
-
-## Package Version History
-
-| Version | Status | Changes | Errors |
-|---------|--------|---------|--------|
-| 0.0.170 | Baseline | Initial BFF → CMS migration | 250+ |
-| 0.0.171 | ✅ Success | Models aliases, Token field | 217 |
-| 0.0.172 | ✅ Success | Title/ImagePath aliases, Network fields | 170 |
-| 0.0.173 | Planned | Missing methods and fields | TBD |
-
----
-
-## Commands Reference
-
-### Build Proto Package
-```bash
-cd /home/masoud/Apps/project/FourSat/CMS/src/CMSMicroservice.Protobuf
-dotnet build
-dotnet pack -c Release -p:PackageVersion=0.0.172 -o ../../../nupkg -p:RunPushTarget=false
-```
-
-### Update FrontOffice
-```bash
-cd /home/masoud/Apps/project/FourSat/FrontOffice/src/FrontOffice.Main
-# Edit .csproj to update version number
-dotnet build
-```
-
-### Check Errors
-```bash
-cd /home/masoud/Apps/project/FourSat/FrontOffice/src/FrontOffice.Main
-dotnet build 2>&1 | grep "error CS" | wc -l
-dotnet build 2>&1 | grep "error CS" | head -20
-```
-
----
-
-## Lessons Learned
-
-1. **BFF Transformation Discovery**: BFF wasn't just routing - it was transforming DTOs. This is critical business logic.
-
-2. **Proto Field Aliasing**: Proto3 requires unique field numbers. Can't reuse numbers for aliases.
-
-3. **Systematic Approach**: Comparing BFF proto files as specification prevented missing fields.
-
-4. **Incremental Progress**: Breaking work into small packages (0.0.171 → 0.0.172) made debugging easier.
-
-5. **Package Naming**: Real package name is `Foursat.CMSMicroservice.Protobuf`, not `CMSMicroservice.Protobuf`.
-
----
-
-## Notes
-
-- Post-build push to Nexus disabled with `-p:RunPushTarget=false` due to `--allow-insecure-connections` flag incompatibility
-- All changes preserve existing business logic per user requirement
-- Field aliases provide backward compatibility during migration
-- Final cleanup phase will update frontend to use CMS field names directly (optional future work)
-
-
----
-
-# سابقه مهاجرت اولیه (سرویس‌های اولیه)
-
-# FrontOffice.BFF to CMS Migration Progress
-
-## Migration Overview
-مهاجرت سرویس‌های FrontOffice.BFF به CMS Microservice با معماری Clean Architecture و gRPC.
-
-## ✅ Completed Services
-
-### 1. Categories Service
-- **Status**: ✅ Complete
-- **Proto Definition**: `categories.proto`
-- **Service Implementation**: `CategoryService.cs`
-- **Methods Migrated**:
-  - Admin Methods:
-    - `AddNewCategory` - افزودن دسته‌بندی جدید
-    - `UpdateCategory` - بروزرسانی دسته‌بندی
-    - `DeleteCategory` - حذف دسته‌بندی
-    - `GetCategory` - دریافت یک دسته‌بندی
-    - `GetAllCategoriesByFilter` - دریافت لیست دسته‌بندی‌ها
-  - Customer Methods:
-    - `GetActiveCategoriesForCustomer` - دریافت دسته‌بندی‌های فعال برای مشتری
-
-### 2. City Service
-- **Status**: ✅ Complete
-- **Proto Definition**: `city.proto`
-- **Service Implementation**: `CityService.cs`
-- **Methods Migrated**:
-  - Admin Methods:
-    - `AddNewCity` - افزودن شهر جدید
-    - `UpdateCity` - بروزرسانی شهر
-    - `DeleteCity` - حذف شهر
-    - `GetCity` - دریافت یک شهر
-    - `GetAllCitiesByFilter` - دریافت لیست شهرها
-  - Customer Methods:
-    - `GetActiveCitiesForCustomer` - دریافت شهرهای فعال برای مشتری
-
-### 3. UserCarts Service
-- **Status**: ✅ Complete
-- **Proto Definition**: `usercarts.proto`
-- **Service Implementation**: `UserCartsService.cs`
-- **Methods Migrated**:
-  - Admin Methods:
-    - `AddNewUserCart` - افزودن سبد خرید جدید
-    - `UpdateUserCart` - بروزرسانی سبد خرید
-    - `DeleteUserCart` - حذف سبد خرید
-    - `GetUserCart` - دریافت سبد خرید (Admin)
-    - `GetAllUserCartsByFilter` - دریافت لیست سبدهای خرید
-  - Customer Methods:
-    - `AddNewUserCartForCustomer` - افزودن محصول به سبد (Customer)
-    - `UpdateUserCartForCustomer` - بروزرسانی تعداد محصول در سبد
-    - `RemoveUserCartForCustomer` - حذف محصول از سبد
-    - `GetCustomerCart` - دریافت سبد خرید مشتری
-
-## 🛠️ Technical Implementation Details
-
-### gRPC HTTP Annotations
-تمام سرویس‌ها با HTTP annotations تعریف شده‌اند:
-- Admin endpoints: `/ServiceName` pattern
-- Customer endpoints: `/Customer/Action` pattern
-
-### Clean Architecture Structure
-```
-CMSMicroservice.Domain/       # Core business entities
-CMSMicroservice.Application/  # Business logic & CQRS
-CMSMicroservice.Infrastructure/ # Data access & external services
-CMSMicroservice.WebApi/       # gRPC services & controllers
-CMSMicroservice.Protobuf/     # Protocol buffer definitions
-```
-
-### Swagger Integration
-- Multiple Swagger documents: cms, admin, customer, unified
-- gRPC HTTP transcoding enabled
-- Custom CSS styling applied
-- Conflict resolution implemented
-
-## 🔧 Issues Resolved
-
-### 1. Swagger Conflict Resolution
-**Problem**: 
-```
-Swashbuckle.AspNetCore.SwaggerGen.SwaggerGeneratorException: 
-Conflicting method/path combination "GET GetUserCart"
-```
-
-**Root Cause**: 
-- دو method با operation ID یکسان: `GetUserCart` و `GetUserCartForCustomer`
-- Swagger از method name برای operation ID استفاده می‌کند
-
-**Solutions Attempted**:
-1. ❌ `CustomOperationIds` - ineffective
-2. ❌ `ResolveConflictingActions` - incomplete resolution
-3. ✅ **Method Renaming** - successful
-
-**Final Solution**:
-```protobuf
-// Before (conflicting):
-rpc GetUserCartForCustomer(GetUserCartForCustomerRequest) returns (GetUserCartForCustomerResponse)
-
-// After (resolved):
-rpc GetCustomerCart(GetUserCartForCustomerRequest) returns (GetUserCartForCustomerResponse)
-```
-
-### 2. Application Layer Dependencies
-**Problem**: Build errors در Application layer
-**Solution**: پاکسازی dependencies و rebuild پروژه
-
-## 📊 Migration Status Summary
-
-| Service | Proto ✅ | Implementation ✅ | Build ✅ | Swagger ✅ |
-|---------|----------|-------------------|----------|------------|
-| Categories | ✅ | ✅ | ✅ | ✅ |
-| City | ✅ | ✅ | ✅ | ✅ |
-| UserCarts | ✅ | ✅ | ✅ | ✅ |
-
-## 🎯 Next Steps
-1. **Service Integration Testing** - تست عملکرد سرویس‌های migrate شده
-2. **Business Logic Implementation** - پیاده‌سازی منطق کسب‌وکار واقعی
-3. **Database Integration** - اتصال به لایه دیتا
-4. **Continue Migration** - ادامه migration سایر سرویس‌ها
-
-## 🏗️ Technical Architecture
-
-### gRPC Service Pattern
-```csharp
-public class ServiceName : ServiceContract.ServiceContractBase
-{
-    private readonly IDispatchRequestToCQRS _dispatcher;
-    
-    // Customer Methods Section
-    #region Customer Methods
-    public override async Task<Response> CustomerMethod(Request request, ServerCallContext context)
-    {
-        // Implementation
-    }
-    #endregion
-    
-    // Admin Methods Section  
-    #region Admin Methods
-    public override async Task<Response> AdminMethod(Request request, ServerCallContext context)
-    {
-        // Implementation
-    }
-    #endregion
-}
-```
-
-### Proto File Structure
-```protobuf
-syntax = "proto3";
-import "google/api/annotations.proto";
-
-service ServiceContract {
-    // ============= Admin Methods =============
-    rpc AdminMethod(Request) returns (Response) {
-        option (google.api.http) = {
-            post: "/AdminEndpoint"
-            body: "*"
-        };
-    };
-    
-    // ============= Customer Methods =============
-    rpc CustomerMethod(Request) returns (Response) {
-        option (google.api.http) = {
-            get: "/Customer/Endpoint"
-        };
-    };
-}
-```
-
-## 📈 Performance & Quality
-- ✅ All services compile successfully
-- ✅ Swagger documentation accessible
-- ✅ gRPC HTTP transcoding working
-- ✅ Clean separation of Admin/Customer concerns
-- ✅ Consistent naming conventions applied
-
----
-**Last Updated**: January 30, 2026  
-**Migration Phase**: Foundation Services Complete  
-**Next Milestone**: Business Logic Implementation

overview/OVERVIEW-01-FLOWCHARTS.md

@@ -0,0 +1,249 @@
+# 📊 فلوچارت‌ها و دیاگرام‌های کلان
+
+> **دید بالا (Big Picture): فلوی کاربر، مالی، داده و کیف‌پول جادویی**  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet + VAT 10%)
+
+---
+
+## ۱. فلوی کلان کاربر (User Journey)
+
+```mermaid
+flowchart TD
+    A["🌐 ورود به سایت"] --> B{"آیا ثبت‌نام کرده؟"}
+    B -->|خیر| C["Landing Page"]
+    C --> D["ثبت‌نام\nموبایل + OTP"]
+    D --> E["پروفایل"]
+    E --> F
+
+    B -->|بله| G["Login + JWT"]
+    G --> H{"عضو باشگاه؟"}
+    H -->|خیر| F["🛒 Regular Store\nخرید عادی — پرداخت از کیف‌پول"]
+    H -->|بله| I["🏆 Club Member Dashboard"]
+
+    I --> J["فروشگاه اعتباری\nper-product MaxDiscount%"]
+    I --> K["درخت شبکه\nباینری"]
+    I --> L["کمیسیون\nهفتگی"]
+    I --> M["Chatika AI"]
+    I --> N["🪄 کیف‌پول جادویی\nشارژ ×2.5"]
+```
+
+---
+
+## ۱.۱ فلوی کیف‌پول جادویی (Magic Wallet) ✅
+
+```mermaid
+flowchart TD
+    A["خرید پکیج 56M\nBalance=56M"] --> B["خرید از فروشگاه\nBalance کم می‌شود"]
+    B --> C{"Balance = 0 +\nعضو فعال باشگاه?"}
+    C -->|خیر| B
+    C -->|بله| D["🪄 Magic Mode\nWalletMode = 1"]
+    D --> E["شارژ از درگاه\nواریز × 2.5"]
+    E --> F{"Balance=0 AND\nDeposited≥100M?"}
+    F -->|خیر| G["خرید یا شارژ ادامه"]
+    G --> F
+    F -->|بله| H["خروج از Magic\nخرید مجدد پکیج"]
+```
+
+---
+
+## ۲. فلوی مالی (Financial Flow)
+
+```mermaid
+flowchart TD
+    subgraph INPUT["═══ ورودی پول ═══"]
+        Z1["ZarinPal IPG"]
+        Z2["Daya Loan"]
+        Z3["Manual Pay"]
+    end
+
+    Z1 --> PYMS["PYMS Service"]
+    Z2 --> PYMS
+    Z3 --> PYMS
+    PYMS --> TX[("DB Transaction")]
+
+    TX --> W1 & W2 & W3
+
+    subgraph WALLETS["═══ توزیع به کیف‌پول‌ها ═══"]
+        W1["💰 Balance — نقدی\n• IPG: +56M\n• Daya: +56M\n• فعالسازی: −25.2M\n• خرید فروشگاه"]
+        W2["🌟 NetworkBalance — طلایی\n• شارژ نمی‌شود\n• فقط محاسبه کمیسیون\n• سقف 300/هفته"]
+        W3["🏷️ DiscountBalance — اعتباری\n• IPG: +112M\n• Daya: +112M\n• per-product MaxDiscount%"]
+    end
+
+    W1 & W2 --> POOL
+
+    subgraph POOL["═══ Weekly Commission Pool ═══"]
+        P1["هر فعالسازی → 25.2M واریز به Pool"]
+        P2["sp_CalculateWeeklyBalances"]
+        P3["sp_CalculateWeeklyCommissionPool"]
+        P4["UserShare = UserBalance / TotalBalance"]
+        P5["Cap: MAX 300 per leg per week"]
+        P1 --> P2 --> P3 --> P4 --> P5
+    end
+```
+
+---
+
+## ۳. فلوی داده (Data Flow)
+
+```mermaid
+flowchart TD
+    CLIENT["🌐 Browser / Client"] -->|HTTPS| NGINX["nginx / K8s Ingress"]
+
+    NGINX -->|"/"| FO["FrontOffice :5003\nBlazor Server"]
+    NGINX -->|"/admin"| BO["BackOffice :5002\nBlazor WASM"]
+    NGINX -->|"/hangfire"| CMS
+
+    FO -->|gRPC| CMS["CMS Microservice :5001"]
+    BO -->|gRPC| CMS
+
+    CMS --> MEDIATR["MediatR\nCommands / Queries → Handlers"]
+    CMS --> HF["Hangfire\n• DayaLoan — */20 min\n• Commission — Sunday 00:05\n• Chatika — */5 min"]
+    CMS --> EXT["External Services\n• ZarinPal API\n• Kavenegar API\n• DayaLoan API\n• Chatika API"]
+
+    MEDIATR --> EF["EF Core 9"]
+    HF --> EF
+    EF --> DB[("SQL Server 2022\nSchema: CMS\n~15 tables + 3 SPs")]
+```
+
+---
+
+## ۴. درخت باینری شبکه (Network Tree)
+
+```mermaid
+graph TD
+    ROOT["🔵 Root — Admin"]
+    ROOT --- A["👤 User A\nL=120 | R=80"]
+    ROOT --- B["👤 User B\nL=0 | R=150"]
+
+    A --- C["✅ User C\nActive"]
+    A --- D["✅ User D\nActive"]
+    B --- E["⏳ User E\nPending"]
+    B --- F["✅ User F\nActive"]
+
+    style ROOT fill:#1976D2,color:#fff
+    style C fill:#4CAF50,color:#fff
+    style D fill:#4CAF50,color:#fff
+    style E fill:#FF9800,color:#fff
+    style F fill:#4CAF50,color:#fff
+```
+
+> **راهنما:**
+> - `L` / `R` = فروش پای چپ / راست این هفته
+> - **Active** = فعال (قرارداد امضا شده) — **Pending** = در انتظار فعالسازی
+> - شبکه روی entity `User` مدل شده (`NetworkParentId`, `LegPosition`)
+> - محاسبه کمیسیون تا عمق ۱۵ سطح — درخت بدون محدودیت عمق
+
+---
+
+## ۵. فلوی خرید — Regular vs Discount Store
+
+### ۵.۱ Regular Store
+
+```mermaid
+flowchart TD
+    A1["مشاهده محصولات"] --> B1["Lazy Load — 12 per page"]
+    B1 --> C1["افزودن به سبد"]
+    C1 --> D1["بررسی موجودی"]
+    D1 --> E1["Checkout Summary\nانتخاب آدرس"]
+    E1 --> F1{"Balance کافی؟"}
+    F1 -->|بله| G1["کسر از Balance کیف‌پول\n+ VAT"]
+    G1 --> H1["ثبت سفارش"]
+    H1 --> I1["کسر موجودی"]
+    F1 -->|خیر| J1["❌ خطا: موجودی کیف‌پول کافی نیست"]
+```
+
+### ۵.۲ Discount Store
+
+```mermaid
+flowchart TD
+    A2["مشاهده محصولات\nفقط اعضای باشگاه"] --> B2["Lazy Load — 12 per page"]
+    B2 --> C2["افزودن به سبد"]
+    C2 --> D2["بررسی موجودی + DiscountBalance"]
+    D2 --> E2["محاسبه سهم تخفیف\nMaxDiscount% هر محصول"]
+    E2 --> F2["محاسبه باقیمانده\ngatewayAmount = total - discountUsed"]
+    F2 --> G2{"gatewayAmount > 0?"}
+    G2 -->|بله| H2["کسر DiscountBalance\n+ ZarinPal IPG برای باقیمانده + 10% VAT"]
+    H2 --> I2["Redirect → ZarinPal\nCallback → ثبت سفارش"]
+    G2 -->|خیر| J2["فقط کسر از DiscountBalance\nبدون درگاه"]
+    J2 --> K2["ثبت سفارش"]
+    I2 --> L2["کسر موجودی + SMS تأیید"]
+    K2 --> L2
+```
+
+---
+
+## ۶. معماری Deployment
+
+```mermaid
+flowchart TD
+    subgraph SERVER["🖥️ Production Server — 45.149.79.127"]
+        NGINX["nginx\n:80 / :443"]
+        subgraph K8S["☸ Kubernetes Cluster"]
+            CMS["CMS ×2\n:5001 gRPC"]
+            FO["FrontOffice ×2\n:5003 Blazor Server"]
+            BO["BackOffice ×1\n:5002 Static"]
+            DB[("SQL Server\n:1433")]
+            NEXUS["Nexus\n:8081"]
+            HF["Hangfire\ninside CMS"]
+        end
+    end
+
+    NGINX --> CMS
+    NGINX --> FO
+    NGINX --> BO
+    CMS --> DB
+    CMS --> HF
+
+    style SERVER fill:#f5f5f5,stroke:#333
+    style K8S fill:#e3f2fd,stroke:#1976D2
+```
+
+---
+
+## ۷. Entity Relationship (ساده‌شده)
+
+```mermaid
+erDiagram
+    User ||--o{ ClubMembership : has
+    User ||--o| UserWallet : has
+    User ||--o{ UserContract : signs
+    User ||--o{ UserOrder : places
+    User ||--o{ ChatMessage : sends
+    User }o--o| User : "NetworkParentId"
+
+    UserOrder ||--|{ OrderItem : contains
+    OrderItem }o--|| Product : references
+    UserOrder ||--o{ Transaction : has
+
+    Product ||--o| Inventory : has
+    Product }o--|| Category : belongs_to
+    Product ||--o{ ProductImage : has
+
+    UserWallet ||--o{ UserWalletChangeLog : logs
+
+    ClubMembership ||--o{ ClubMembershipCycle : has
+
+    BlogPost }o--|| Category : belongs_to
+
+    UserWallet {
+        long Balance
+        long NetworkBalance
+        long DiscountBalance
+        int WalletMode
+        long MagicTotalDeposited
+        long MagicTotalCredited
+    }
+    ClubMembershipCycle {
+        int CycleNumber
+        datetime PackagePurchasedAt
+        bool IsCurrentCycle
+    }
+    User {
+        Guid NetworkParentId
+        int LegPosition
+    }
+    UserContract {
+        Guid SignGuid
+        string SignedPdfFile
+    }
+```

overview/OVERVIEW-02-INDEX.md

@@ -0,0 +1,177 @@
+# 📋 شاخص اصلی مستندات (Master Index)
+
+> **فهرست کامل ۱۵ فایل مستند پروژه FourSat (کارا بازار سلامت)**  
+> **تاریخ تجمیع:** اسفند ۱۴۰۴  
+> **تعداد فایل‌های مبدأ:** ۵۳ فایل (~۳۲,۰۰۰ خط)  
+> **تعداد فایل‌های نهایی:** ۲۲ فایل (۱۵ اصلی + ۷ roadmap/business)  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (فاز ۱۰: DataMigration + EF Staging + PackagePurchaseDialog + UI Fixes | NuGet v0.0.189)
+
+---
+
+## ساختار مستندات
+
+```
+totalDoc/
+├── 📁 business/   (سطح بیزینسی — ۵ فایل)
+│   ├── BUSINESS-01-CLUB-COMMISSION.md      سیستم باشگاه و کمیسیون
+│   ├── BUSINESS-02-PAYMENT-FINANCE.md      مالی و درگاه‌ها
+│   ├── BUSINESS-03-ECOMMERCE-STORES.md     فروشگاه و موجودی
+│   ├── BUSINESS-04-USER-MEMBERSHIP.md      چرخه کاربر و عضویت
+│   └── BUSINESS-05-CONTENT-MANAGEMENT.md   محتوا و صفحات
+│
+├── 📁 technical/  (سطح فنی — ۵ فایل)
+│   ├── TECH-01-CMS-ARCHITECTURE.md         معماری CMS
+│   ├── TECH-02-BACKOFFICE-FRONTOFFICE.md   معماری UI
+│   ├── TECH-03-DEPLOYMENT-INFRA.md         استقرار و زیرساخت
+│   ├── TECH-04-MIGRATION.md                مهاجرت داده
+│   └── TECH-05-API-INTEGRATION.md          API و یکپارچه‌سازی
+│
+├── 📁 overview/   (نمای کلان — ۵ فایل)
+│   ├── OVERVIEW-01-FLOWCHARTS.md           فلوچارت‌ها و دیاگرام‌ها
+│   ├── OVERVIEW-02-INDEX.md                ← همین فایل
+│   ├── OVERVIEW-03-CHANGELOG.md            تاریخچه و درصد تکمیل
+│   ├── OVERVIEW-04-GLOSSARY.md             واژه‌نامه و استانداردها
+│   └── OVERVIEW-05-ROADMAP.md              نقشه راه و ریسک‌ها
+│
+└── 📁 roadmap/    (فیچرهای جدید — در حال توسعه)
+    ├── MAGIC-WALLET-SPEC.md                مشخصات کیف‌پول جادویی
+    ├── MAGIC-WALLET-PLAN.md                پلن پیاده‌سازی + checklist
+    ├── PACKAGE-TRANSFORMATION-TASKS.md     تسک‌های تحول پکیج‌بیس (فاز 0-5)
+    ├── PACKAGE-TRANSFORMATION-UX.md        تاثیر بر UX فرانت‌ها
+    └── FEATURE-BACKLOG.md                  بکلاگ ۱۲ RPC آماده
+```
+
+---
+
+## خلاصه هر فایل
+
+### 🏆 Business Level
+
+| # | فایل | موضوع | خلاصه |
+|---|------|--------|--------|
+| B1 | [BUSINESS-01-CLUB-COMMISSION](../business/BUSINESS-01-CLUB-COMMISSION.md) | باشگاه و کمیسیون | درخت باینری، فرمول ۴مرحله‌ای، Pool هفتگی، وام دایا، Chatika، **🪄 کیف‌پول جادویی** |
+| B2 | [BUSINESS-02-PAYMENT-FINANCE](../business/BUSINESS-02-PAYMENT-FINANCE.md) | مالی و پرداخت | ZarinPal IPG، ۳ کیف‌پول، PYMS، پرداخت ترکیبی، VAT 10%، **Magic Charge** |
+| B3 | [BUSINESS-03-ECOMMERCE-STORES](../business/BUSINESS-03-ECOMMERCE-STORES.md) | فروشگاه | Regular + Discount Store، Lazy Load، موجودی خودکار، باندل |
+| B4 | [BUSINESS-04-USER-MEMBERSHIP](../business/BUSINESS-04-USER-MEMBERSHIP.md) | کاربر و عضویت | ثبت‌نام OTP، قرارداد، فیچرهای باشگاه، Auth-Aware، Referral |
+| B5 | [BUSINESS-05-CONTENT-MANAGEMENT](../business/BUSINESS-05-CONTENT-MANAGEMENT.md) | محتوا | Site Pages (Shopify)، بلاگ، مدیریت فایل، SMS/Email، Landing |
+
+### ⚙️ Technical Level
+
+| # | فایل | موضوع | خلاصه |
+|---|------|--------|--------|
+| T1 | [TECH-01-CMS-ARCHITECTURE](../technical/TECH-01-CMS-ARCHITECTURE.md) | معماری CMS | .NET 9، CQRS/MediatR، gRPC، EF Core 9، Hangfire، DB schema |
+| T2 | [TECH-02-BACKOFFICE-FRONTOFFICE](../technical/TECH-02-BACKOFFICE-FRONTOFFICE.md) | معماری UI | Blazor WASM/Server، MudBlazor v8، Code-behind، RTL، Theme |
+| T3 | [TECH-03-DEPLOYMENT-INFRA](../technical/TECH-03-DEPLOYMENT-INFRA.md) | استقرار | Docker، K8s، CI/CD، Nexus، Offline deployment، Mirrors |
+| T4 | [TECH-04-MIGRATION](../technical/TECH-04-MIGRATION.md) | مهاجرت | BFF removal، Gateway removal، Data migration، SQL scripts |
+| T5 | [TECH-05-API-INTEGRATION](../technical/TECH-05-API-INTEGRATION.md) | API | Proto definitions، ZarinPal/Kavenegar/Daya/Chatika، Error handling |
+
+### 📊 Overview / Meta
+
+| # | فایل | موضوع | خلاصه |
+|---|------|--------|--------|
+| O1 | [OVERVIEW-01-FLOWCHARTS](OVERVIEW-01-FLOWCHARTS.md) | دیاگرام‌ها | User Journey، Financial Flow، Data Flow، ER Diagram، Network Tree |
+| O2 | [OVERVIEW-02-INDEX](OVERVIEW-02-INDEX.md) | شاخص | همین فایل — فهرست و نقشه ۱۵ فایل |
+| O3 | [OVERVIEW-03-CHANGELOG](OVERVIEW-03-CHANGELOG.md) | تاریخچه | همه کارهای انجام‌شده با بولت + درصد تکمیل |
+| O4 | [OVERVIEW-04-GLOSSARY](OVERVIEW-04-GLOSSARY.md) | واژه‌نامه | اصطلاحات فارسی/انگلیسی، استانداردهای کد |
+| O5 | [OVERVIEW-05-ROADMAP](OVERVIEW-05-ROADMAP.md) | نقشه راه | ریسک‌ها، وابستگی‌ها، کارهای باقیمانده، اولویت‌ها |
+
+### 🪄 Roadmap (فیچرهای جدید)
+
+| # | فایل | موضوع | خلاصه |
+|---|------|--------|--------|
+| R1 | [MAGIC-WALLET-SPEC](../roadmap/MAGIC-WALLET-SPEC.md) | کیف‌پول جادویی — مشخصات | State Machine، ضریب ×2.5، سقف 100M، قوانین، API، مدل داده |
+| R2 | [MAGIC-WALLET-PLAN](../roadmap/MAGIC-WALLET-PLAN.md) | کیف‌پول جادویی — پلن | ۶ فاز، **فاز 1-6 تکمیل ✅** |
+| R3 | [PACKAGE-TRANSFORMATION-TASKS](../roadmap/PACKAGE-TRANSFORMATION-TASKS.md) | تحول پکیج‌بیس — تسک‌ها | ۱۰ فاز، **فاز 0-10 تکمیل ✅**، تست + deploy در انتظار |
+| R4 | [PACKAGE-TRANSFORMATION-UX](../roadmap/PACKAGE-TRANSFORMATION-UX.md) | تاثیر بر UX | تحلیل تاثیر بر FrontOffice + BackOffice |
+| R5 | [FEATURE-BACKLOG](../roadmap/FEATURE-BACKLOG.md) | بکلاگ فیچرها | ۱۲ RPC آماده بدون UI، اولویت‌بندی‌شده |
+| R6 | [BIZ-PACKAGE-BASED-SYSTEM](../business/BIZ-PACKAGE-BASED-SYSTEM.md) | طراحی سیستم پکیج‌بیس | v6، ۳۰ تصمیم (Q1-Q30) + ۵۱ تغییر + ۴۴ سایدافکت |
+
+---
+
+## نقشه ارتباط فایل‌ها
+
+```mermaid
+graph TD
+    INDEX["📋 O2: INDEX\nشما اینجا هستید"]
+    INDEX --> BIZ["📁 Business\nB1-B5"]
+    INDEX --> TECH["📁 Technical\nT1-T5"]
+    INDEX --> OVR["📁 Overview\nO1-O5"]
+
+    BIZ --- B12["B1 ↔ B2\nمالی / باشگاه"]
+    BIZ --- B23["B2 ↔ B3\nپرداخت / فروشگاه"]
+    BIZ --- B34["B3 ↔ B4\nفروشگاه / کاربر"]
+    BIZ --- B45["B4 ↔ B5\nکاربر / محتوا"]
+
+    BIZ --- TECH
+    TECH --- T12["T1 ↔ T2 — CMS/UI"]
+    TECH --- T13["T1 ↔ T3 — CMS/Deploy"]
+    TECH --- T34["T3 ↔ T4 — Deploy/Migration"]
+    TECH --- T15["T1 ↔ T5 — CMS/API"]
+
+    OVR --- OX["O1: دیاگرام‌ها\nO3: تاریخچه\nO5: نقشه راه"]
+```
+
+---
+
+## نقشه ادغام (53 فایل → 15 فایل)
+
+<details>
+<summary>کلیک برای مشاهده mapping کامل</summary>
+
+| فایل مبدأ | فایل مقصد |
+|-----------|-----------|
+| `business/club-commission-system-complete.md` | B1 |
+| `business/balance-calculation-rules.md` | B1 |
+| `business/club-membership-contract-system.md` | B1, B4 |
+| `business/daya-loan-integration.md` | B1, B2 |
+| `business/discount-shop-business.md` | B2, B3 |
+| `business/DISCOUNT-STORE-STATUS.md` | B3 |
+| `business/manual-payment-system.md` | B2 |
+| `business/package-purchase-system.md` | B1, B2 |
+| `cms/payment-gateway.md` | B2, T5 |
+| `cms/payment-architecture-pyms.md` | B2, T1 |
+| `cms/SITE-PAGES-SIMPLIFICATION.md` | B5 |
+| `cms/system-constants.md` | B5, T1 |
+| `cms/email-sms-configuration.md` | B5 |
+| `cms/chatika-integration.md` | B1, B5, T5 |
+| `cms/club-feature-management-services.md` | B4, T5 |
+| `cms/CMS-README.md` | T1 |
+| `cms/ICURRENTUSERSERVICE-IMPLEMENTATION.md` | B4, T1 |
+| `cms/FILE-MANAGEMENT-ARCHITECTURE.md` | B5, T1 |
+| `cms/FRONTOFFICE-CMS-API-COMPATIBILITY.md` | T5 |
+| `cms/BFF-REMOVAL-PLAN.md` | T1, T4 |
+| `cms/ADMIN-CUSTOMER-SEPARATION-FIX.md` | B4 |
+| `cms/REGISTRATION-FLOW-FIXES.md` | B4 |
+| `cms/INVENTORY-IMPROVEMENTS.md` | B3 |
+| `cms/INVENTORY-REFACTORING-STATUS.md` | B3 |
+| `cms/PRODUCT-BUNDLE-FEATURE.md` | B3 |
+| `cms/REMAINING-TASKS.md` | O5 |
+| `cms/FRONTOFFICE-RELEASE-NOTES-v1.5.0.md` | O3 |
+| `deployment/CICD-PIPELINE-GUIDE.md` | T3 |
+| `deployment/DEPLOYMENT-README.md` | T3 |
+| `deployment/INFRASTRUCTURE-GUIDE.md` | T3 |
+| `deployment/INGRESS-NGINX-WARNING.md` | T3 |
+| `deployment/OFFLINE-DEPLOYMENT-GUIDE.md` | T3 |
+| `deployment/SERVER-MIRRORS-CONFIG.md` | T3 |
+| `migration/BACKOFFICE-BFF-MIGRATION.md` | T4 |
+| `migration/customer-facing-capabilities-codex.md` | T4 |
+| `migration/DATA-TABLE-MAPPINGS.md` | T4 |
+| `migration/DATAMIGRATION-README.md` | T4 |
+| `migration/FRONTOFFICE-TO-CMS-MIGRATION.md` | T4 |
+| `migration/GATEWAY-REMOVAL-MIGRATION-PLAN.md` | T4 |
+| `migration/MIGRATION-PROGRESS.md` | T4, O3 |
+| `ui-modernization/BACKOFFICE-ARCHITECTURE.md` | T2 |
+| `ui-modernization/BACKOFFICE-STORE-UNIFICATION.md` | T2, B3 |
+| `ui-modernization/UI-MODERNIZATION-PLAN.md` | T2 |
+| `ui-modernization/PHASE-1-COMPLETE.md` | T2, O3 |
+| `ui-modernization/PHASE-3-COMPLETE.md` | T2, O3 |
+| `ui-modernization/PRODUCT-IMAGES-SQUARE.md` | T2, B3 |
+| `backoffice/BACKOFFICE-AUDIT.md` | T2, O3 |
+| `backoffice/BACKOFFICE-CHANGELOG.md` | T2, O3 |
+| `frontoffice/CHANGELOG.md` | T2, O3 |
+| `frontoffice/UI-UNIFICATION-PLAN.md` | T2 |
+| `SHOP-UNIFICATION.md` | B3 |
+| `INDEX.md` | O2 |
+| `docs/MOVED-TO-TOTALDOC.md` | — (deleted) |
+
+</details>

overview/OVERVIEW-03-CHANGELOG.md

@@ -0,0 +1,502 @@
+# 📜 تاریخچه کارهای انجام‌شده
+
+> **همه فعالیت‌های پروژه به صورت بولت با توضیح یک‌خطی و درصد تکمیل**  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: فاز ۱۱ — فیکس‌های پرداخت ZarinPal + امنیت Callback URL + اصلاح تومان/ریال)
+
+---
+
+## خلاصه کلی
+
+| حوزه | تعداد آیتم | تکمیل‌شده | درصد کل |
+|------|-----------|----------|---------|
+| **BackOffice** | 67 | 67 | **100%** |
+| **FrontOffice** | 60 | 60 | **100%** |
+| **CMS Core** | 89 | 89 | **100%** |
+| **Package-Based System** | 52 | 52 | **100%** |
+| **Deployment** | 22 | 21 | **95%** |
+| **Migration** | 21 | 21 | **100%** |
+| **مجموع** | **311** | **310** | **99.5%** |
+
+---
+
+## ۱. BackOffice — فازها (98% کامل)
+
+### Phase 1-3: پایه و ساختار
+- ✅ ارتقا به MudBlazor v8 — تغییر تمام کامپوننت‌ها به API جدید
+- ✅ پیاده‌سازی MainLayout با Drawer و AppBar — RTL support
+- ✅ ایجاد NavMenu با آیکون‌ها و گروه‌بندی — دسته‌بندی منطقی
+- ✅ پیاده‌سازی الگوی Code-behind — جدا کردن logic از markup
+- ✅ اضافه کردن Theme سفارشی — رنگ‌ها و فونت Vazirmatn
+
+### Phase 4-6: محصولات و فروشگاه
+- ✅ صفحه لیست محصولات — MudDataGrid با pagination
+- ✅ فرم ایجاد/ویرایش محصول — MudForm با FluentValidation
+- ✅ آپلود تصویر محصول — Drag & drop با preview
+- ✅ مدیریت دسته‌بندی‌ها — CRUD درختی
+- ✅ AppImage کامپوننت — تصاویر مربعی ۱:۱ همه‌جا
+
+### Phase 7-9: سفارشات و مالی
+- ✅ لیست سفارشات — فیلتر وضعیت، تاریخ، مبلغ
+- ✅ جزئیات سفارش — آیتم‌ها + تراکنش‌ها
+- ✅ تغییر وضعیت سفارش — با تأیید دیالوگ
+- ✅ گزارش مالی — خلاصه تراکنش‌ها
+
+### Phase 10-12: کاربران و باشگاه
+- ✅ لیست کاربران — جستجو + فیلتر نقش
+- ✅ مدیریت عضویت باشگاه — فعال/غیرفعال
+- ✅ نمای درخت شبکه — نمایش باینری با سطوح
+- ✅ مدیریت کمیسیون — مشاهده Pool هفتگی
+
+### Phase 13-15: محتوا و تنظیمات
+- ✅ مدیریت بلاگ — CRUD پست‌ها با ادیتور HTML
+- ✅ مدیریت صفحات سایت — Shopify-style typed editors
+- ✅ HomePageEditor — ویرایش Hero, Featured, Promotion
+- ✅ AboutPageEditor — ویرایش متن درباره‌ما
+- ✅ ContactPageEditor — اطلاعات تماس
+- ✅ LicensesPageEditor — مجوزها
+- ✅ ادیتور SystemConstants — تنظیمات key-value
+
+### Phase 16-17: موجودی و نهایی‌سازی
+- ✅ صفحه موجودی — با MudAutocomplete برای انتخاب محصول
+- ✅ ایجاد خودکار رکورد موجودی — هنگام ساخت محصول
+- ✅ Hangfire InventorySync — ایجاد رکوردهای گمشده
+- ⬜ Dark Mode — طراحی نشده (Phase آینده)
+
+### Phase 18: بهبود UI ادمین (اسفند ۱۴۰۴)
+- ✅ UserAutoComplete در ActivateClubDialog — جایگزین MudNumericField برای انتخاب کاربر
+- ✅ فیلتر کاربر در صفحه ClubMembers — UserAutoComplete در تولبار جستجو
+- ✅ نمایش نام کاربر در WalletManagementPage — TemplateColumn با UserName + ID
+
+### Phase 8b: CRUD پکیج کامل (اسفند ۱۴۰۴)
+- ✅ CreateDialog: اضافه ۱۲ فیلد جدید — SortOrder, ActivationFee, DiscountMultiplier, MagicWallet*, MaxBalancesPerLeg, MaxNetworkLevel, IsActive, IsBasePackage, SupportsDirectPurchase, SupportsDayaPurchase
+- ✅ UpdateDialog: همان ۱۲ فیلد جدید — ایجاد فرم کامل ادمین
+- ✅ PackageMainPage Grid: ۴ ستون جدید — قیمت (N0), ترتیب, وضعیت (فعال/غیرفعال chip), نوع (پایه/عادی chip)
+- ✅ فیکس `HasPurchasedGoldenPackage` → `HasPurchasedPackage` — UserNetworkInfo.razor
+- ✅ NuGet bump 0.0.184 → 0.0.186 + local feed source
+
+---
+
+## ۲. FrontOffice — فازها (95% کامل)
+
+### UI Modernization Phase 1-3
+- ✅ ارتقا به MudBlazor v8 — همه کامپوننت‌ها
+- ✅ MainLayout جدید — Header + Footer + RTL
+- ✅ AuthLayout — صفحات Login/Register
+- ✅ Landing Page — Hero + Features + Counter + CTA
+- ✅ اصلاح انیمیشن Counter — linear interpolation
+
+### فروشگاه (Phase 4-5)
+- ✅ Regular Store — لیست محصولات با Lazy Load (12/page)
+- ✅ Discount Store — لیست با Lazy Load + hybrid payment
+- ✅ ProductCard مشترک — تصویر مربعی + قیمت + دکمه
+- ✅ CategoryFilter — فیلتر دسته‌بندی sidebar
+- ✅ ProductDetail — جزئیات + تصویر بزرگ + سبد
+- ✅ سبد خرید — Regular + Discount جداگانه
+- ✅ Checkout — پرداخت ZarinPal + ترکیبی
+
+### باشگاه (Phase 6)
+- ✅ داشبورد باشگاه — ۳ کیف‌پول + آمار
+- ✅ نمای درخت شبکه — باینری بصری
+- ✅ امضای قرارداد — OTP + scroll-to-bottom
+- ✅ صفحه Chatika — چت AI
+- ✅ کیف‌پول جادویی — MagicWallet.razor + فرم شارژ + پروگرس‌بار سقف
+
+### فعال‌سازی درگاه پرداخت (اسفند ۱۴۰۴)
+- ✅ دکمه پرداخت شارژ کیف‌پول اعتباری — ChargeDiscountWallet.razor فعال شد (حذف «بزودی»)
+- ✅ دکمه پرداخت شارژ کیف‌پول جادویی — MagicWallet.razor فعال شد (حذف «بزودی»)
+- ✅ دکمه‌های پرداخت مستقیم خرید پکیج — Index.razor هر دو شاخه فعال شدند (حذف «بزودی»)
+
+### فیکس‌های پرداخت و UX (اسفند ۱۴۰۴ — Phase 11)
+- ✅ **صفحه موفقیت پرداخت** — `TransactionId` بجای `RefId` + موجودی واقعی + `Href="/profile"` (FO:`5ded91a`)
+- ✅ **حذف دوبار ×۱۰** — FO مستقیم تومان ارسال می‌کند، CMS/ZarinPal ×۱۰ می‌کند (FO:`2f9ef15`)
+- ✅ **حذف CallbackUrl از درخواست** — `Index.razor.cs` و `Checkout.razor.cs` دیگر URL ارسال نمی‌کنند (FO:`2b1dc47`)
+- ✅ ۳ کامیت، ۷ فایل تغییر
+
+### Phase 8a+8c: Checkout + Package Pages (اسفند ۱۴۰۴)
+- ✅ Checkout wire-up — مهاجرت به `CustomerPurchasePackageAsync` (حذف dead code قدیمی)
+- ✅ PackageDetail: `GetPackageAsync` → `GetCustomerPackageDetailsAsync` — features/specs از API (نه hardcoded)
+- ✅ Packages.razor: un-exclude از build + dynamic feature bullets از `CustomerPackageModel`
+- ✅ PackageService: `PackageDto` غنی‌شده با ۸ فیلد جدید + `GetUserPackageStatusAsync` متصل به RPC واقعی
+- ✅ NuGet bump 0.0.182 → 0.0.186 + local feed source
+- ✅ فیکس GwUrl پروداکشن — تصحیح از cms.kbs1.ir به cms.kbs2.ir
+
+### Phase 10a: PackagePurchaseDialog — دیالوگ داینامیک خرید پکیج (اسفند ۱۴۰۴)
+- ✅ `PackagePurchaseDialog.razor` — دیالوگ ۲ مرحله‌ای: مرحله ۱ = کاشی‌های پکیج (responsive grid)، مرحله ۲ = انتخاب روش پرداخت
+- ✅ حذف دیالوگ inline خرید «پکیج پایه» از `Index.razor` — جایگزین با دیالوگ داینامیک
+- ✅ بارگذاری پکیج‌ها از `PackageService.GetAllPackagesAsync()` — نمایش عنوان + قیمت + ویژگی‌ها
+- ✅ پشتیبانی از ۲ روش پرداخت: مستقیم (درگاه بانکی) + اعتبار دایا (فقط پکیج پایه + دور اول)
+- ✅ CSS کلاس‌های جدید: `.pkg-tile`, `.pkg-tile-badge`, `.pkg-payment-option`
+- ✅ کامیت: `a3681a8` (FO)
+
+### Phase 10b: ۴ فیکس UI پکیج (اسفند ۱۴۰۴)
+- ✅ **Toman/Rial**: قیمت از سرور به ریال ← `FormattedPrice` حالا `Price / 10` برای نمایش صحیح تومان
+- ✅ **لیبل**: «ضریب تخفیف» → «ضریب اعتبار» (دیالوگ + صفحه لیست پکیج‌ها)
+- ✅ **دکمه بازگشت**: وجود داشت (`ArrowForward` + `BackToList`) — تأیید عملکرد
+- ✅ **HTML Description**: `@((MarkupString)pkg.Description)` بجای متن ساده
+- ✅ کامیت: `3c1a8ff` (FO)
+
+### Phase 11: فیکس‌های پرداخت + تومان/ریال + امنیت Callback URL (اسفند ۱۴۰۴)
+
+#### 11a: اصلاح مدل تومان/ریال (CMS+FO)
+> **تصحیح مهم:** دیتابیس به **تومان** ذخیره می‌کند نه ریال. فقط درگاه ZarinPal ریال نیاز دارد (×۱۰).
+- ✅ `ZarinPalPaymentService.InitiatePaymentAsync` — مبلغ ×۱۰ تبدیل به ریال فقط هنگام ارسال به ZarinPal
+- ✅ `ZarinPalPaymentService.VerifyPaymentWithAmountAsync` — مبلغ ×۱۰ هنگام verify
+- ✅ FrontOffice نمایش مستقیم مبلغ تومان (بدون `/10`) — فیکس `MagicWallet.razor`, `ChargeDiscountWallet.razor.cs`
+- ✅ حذف `Price / 10` اضافی در `ClubMembershipContractDialog.razor`
+
+#### 11b: فیکس ZarinPal Verify — رفع خطای Code=-1 (CMS:`721661a`)
+> **باگ:** `VerifyPaymentAsync` با ۲ آرگومان مبلغ صفر (0) ارسال می‌کرد → ZarinPal Code=-1 برمی‌گرداند
+- ✅ `PackageService` — lookup `PaymentTransaction.Amount` + استفاده از overload ۳ آرگومانه
+- ✅ `TransactionsService` — همان فیکس
+- ✅ `VerifyDiscountWalletChargeCommandHandler` — مبلغ از `PaymentTransaction` + رفع کپی‌پیست باگ
+- ✅ `VerifyPackagePurchaseCommandHandler` — مبلغ از `PaymentTransaction`
+- ✅ `IPaymentGatewayService` — default impl ۳ آرگومانه با `NotImplementedException`
+- ✅ `MockPaymentGatewayService` + `DayaPaymentService` — اضافه overload ۳ آرگومانه
+- ✅ ۷ فایل تغییر
+
+#### 11c: بهبود صفحه موفقیت پرداخت (FO:`5ded91a`)
+- ✅ `PaymentCallback.razor` — نمایش `TransactionId` بجای `RefId` برای کد رهگیری
+- ✅ نمایش موجودی واقعی کیف‌پول از `WalletService.GetBalancesAsync()` (نه مقدار ثابت)
+- ✅ دکمه بازگشت: `Href="/profile"` بجای `history.back()` (جلوگیری از حلقه بازگشت به درگاه)
+
+#### 11d: حذف دوبار ×۱۰ شارژ کیف‌پول (FO:`2f9ef15`)
+> **باگ:** FO مبلغ تومان را ×۱۰ تبدیل به ریال می‌کرد، سپس CMS/ZarinPal دوباره ×۱۰ → مبلغ ۱۰۰ برابر
+- ✅ `MagicWallet.razor.cs` — حذف تبدیل ×۱۰ (ارسال مستقیم تومان)
+- ✅ `MagicWallet.razor` — فیکس Max و فیلتر preset مبالغ
+- ✅ `ChargeDiscountWallet.razor.cs` — حذف تبدیل ×۱۰
+- ✅ `ClubMembershipContractDialog.razor` — حذف `Price/10` اضافی
+- ✅ ۴ فایل تغییر
+
+#### 11e: فیکس مسیر Callback کیف‌پول (CMS:`ed2b20a`)
+- ✅ `PaymentCallbackController` — مسیر redirect از `/magic-wallet` به `/profile/magic-wallet`
+- ✅ ایجاد `appsettings.Development.json` — URL‌های محلی (`localhost:32846` و `localhost:5268`)
+- ✅ تصحیح کامنت‌های proto: «ریال» → «تومان»
+
+#### 11f: امنیت Callback URL — حذف از ورودی کاربر (CMS:`0107308`, FO:`2b1dc47`)
+> **اصلاح امنیتی:** هیچ callback URL نباید از ورودی کاربر بیاید — همه از `appsettings.json` خوانده شوند
+- ✅ `PackageService` — خواندن `FrontOfficeBaseUrl` از `IConfiguration` بجای `request.CallbackUrl`
+- ✅ `TransactionsService` — همان فیکس، خواندن از config
+- ✅ تأیید: `MagicWallet` و `DiscountWallet` از قبل از `CmsBaseUrl` config می‌خوانند ✅
+- ✅ تأیید: `DiscountShop PlaceOrder` از قبل از `CmsBaseUrl` config می‌خواند ✅
+- ✅ FO: حذف `CallbackUrl` از `Index.razor.cs` و `Checkout.razor.cs`
+- ✅ جدول Callback URL‌ها:
+
+| فلو | Callback URL | منبع |
+|-----|-------------|------|
+| خرید پکیج | `FrontOfficeBaseUrl/profile/payment-callback?orderId=X` | config |
+| کیف‌پول جادویی | `CmsBaseUrl/api/wallet/verify-magic-charge` | config |
+| کیف‌پول اعتباری | `CmsBaseUrl/api/wallet/verify-discount-charge` | config |
+| فروشگاه اعتباری | `CmsBaseUrl/api/payment/discount-order/callback?orderId=X` | config |
+| تراکنش عمومی | `FrontOfficeBaseUrl/profile/payment-callback` | config |
+
+### محتوا و ناوبری
+- ✅ بلاگ — لیست + جزئیات + pagination
+- ✅ صفحات سایت — About, Contact, FAQ, Terms, Privacy, Licenses
+- ✅ ناوبری Auth-Aware — مسیردهی بر اساس نقش
+- ✅ Home → Club Dashboard / Store بر اساس وضعیت
+- ⬜ Mobile Responsive — Phase 7 (برنامه‌ریزی‌شده)
+- ⬜ PWA — نیاز به Service Worker
+- ⬜ Bottom Navigation (موبایل) — طراحی نشده
+
+---
+
+## ۳. CMS Core (97% کامل)
+
+### ساختار و معماری
+- ✅ CQRS با MediatR — Commands + Queries + Handlers
+- ✅ gRPC Services — ۱۱ سرویس اصلی
+- ✅ EF Core 9 — Migrations + Seeding
+- ✅ Hangfire — ۴ Background Job
+- ✅ JWT Authentication — Claims-based
+- ✅ ICurrentUserService — جداسازی Admin/Customer
+
+### محصولات و فروشگاه
+- ✅ Product CRUD — با auto-inventory
+- ✅ Category CRUD — درختی
+- ✅ Inventory management — auto-create + sync job
+- ✅ GetProductsPaged — با PaginationState
+- ✅ File upload/download — streaming gRPC
+
+### مالی و پرداخت
+- ✅ ZarinPal Integration — IPG + Verify
+- ✅ PYMS Service — سرویس مرکزی پرداخت
+- ✅ ۳ Wallet System — Balance, Network, Discount
+- ✅ Transaction logging — همه تراکنش‌ها
+
+### باشگاه
+- ✅ Binary Tree — SP_GetNetworkTree
+- ✅ Weekly Balance Calculation — sp_CalculateWeeklyBalances
+- ✅ Commission Pool — sp_CalculateWeeklyCommissionPool
+- ✅ Contract System — OTP + acceptance
+- ✅ Club Features — activate/deactivate
+- ✅ DayaLoan Integration — Hangfire + Polly
+
+### 🪄 کیف‌پول جادویی (Magic Wallet) — فاز 1-6 ✅
+- ✅ فاز ۱: WalletMode enum + UserWallet fields + ClubMembershipCycle entity + TransactionType (14,15)
+- ✅ فاز ۲: Trigger ورود/خروج Magic در SubmitShopBuyOrder + ActivateClubMembership Cycle
+- ✅ فاز ۳: ChargeMagicWallet + VerifyMagicWalletCharge + HTTP callback + gRPC RPCs
+- ✅ فاز ۴: فیلتر Magic از کمیسیون (C# + SP) + تاریخ Cycle
+- ✅ فاز ۵: MagicWallet.razor UI + WalletService + تایل داشبورد
+- ✅ فاز ۶: محدودیت دایا بعد از دور اول + محدودیت فعالسازی در حالت Magic
+
+### VAT
+- ✅ اصلاح VAT از 9% به 10% در همه فایل‌ها (VatCalculator, UserOrderService, Checkout, VATService)
+
+### فعال‌سازی درگاه و تنظیمات محیطی (اسفند ۱۴۰۴)
+- ✅ تنظیم MerchantId جدید ZarinPal — `4225d555-5fa9-4df0-9b61-1ce152cbbba8`
+- ✅ تنظیمات محیطی — Staging: UseSandbox=true / Production: UseSandbox=false
+- ✅ فعال‌سازی MagicWalletCycleSeed در Production
+- ✅ تنظیم Kestrel Http2 + Seq logging برای Production
+- ✅ بهبود user_name در proto — فیلد جدید در GetAllUserWalletByFilterResponseModel
+- ✅ اغنای پاسخ UserWalletService — join با جدول Users برای نمایش نام کاربر
+- ✅ ارتقای Proto NuGet به نسخه 0.0.183
+
+### فیکس‌های پرداخت و امنیت (اسفند ۱۴۰۴ — Phase 11)
+- ✅ **ZarinPal Verify fix** — رفع باگ amount=0 در VerifyPaymentAsync (Code=-1) — ۳ آرگومانه overload
+- ✅ **تصحیح مدل تومان/ریال** — DB به تومان ذخیره می‌کند، فقط ZarinPal ریال (×۱۰) نیاز دارد
+- ✅ **Callback URL از config** — `PackageService` و `TransactionsService` از `FrontOfficeBaseUrl` config می‌خوانند (نه از ورودی)
+- ✅ **فیکس مسیر redirect** — `/magic-wallet` → `/profile/magic-wallet` در PaymentCallbackController
+- ✅ **appsettings.Development.json** — URL‌های محلی برای توسعه (CmsBaseUrl + FrontOfficeBaseUrl)
+- ✅ کامیت‌ها: `721661a` → `ed2b20a` → `0107308`
+
+### محتوا
+- ✅ Blog CRUD — با pagination
+- ✅ SitePage Settings — JSON typed
+- ✅ SystemConfigurations — key-value
+- ⬜ Product Bundle — طراحی‌شده، پیاده‌سازی نشده
+- ⬜ Manual Payment — طراحی‌شده، پیاده‌سازی نشده
+- ⬜ API Rate Limiting — برنامه‌ریزی‌شده
+
+---
+
+## ۴. Deployment و زیرساخت (95% کامل)
+
+- ✅ Docker Compose — تمام سرویس‌ها
+- ✅ Dockerfile (CMS) — multi-stage build
+- ✅ K8s Manifests — Deployment + Service + Ingress
+- ✅ CI/CD Pipeline — Gitea Actions
+- ✅ Nexus Repository — NuGet + Docker proxy
+- ✅ Offline Deployment — کامل با اسکریپت‌ها
+- ✅ Proto Package — NuGet packaging + distribution
+- ✅ Health Check scripts — K8s + service
+- ✅ Mirror Configuration — Docker + NuGet
+- ✅ Base Image Caching — pull + save + load
+- ✅ مرج پروداکشن CMS — حل conflict در appsettings.Production.json + حذف migration تکراری u21
+- ✅ مرج پروداکشن FrontOffice — ۲۱ فایل، ۴۰۰ insertion + فیکس GwUrl
+- ✅ مرج پروداکشن BackOffice — ۳۶ فایل، بدون conflict
+- ✅ اجرای Migration روی پروداکشن — ExpandDiscountProductFullInformation روی DB کی‌بی‌اس
+- ⬜ Monitoring (Prometheus/Grafana) — برنامه‌ریزی‌شده
+- ⬜ Log Aggregation (ELK/Seq) — Seq تنظیم شده در Production (http://seq-svc:5341)
+
+---
+
+## ۵. Migration (100% کامل)
+
+- ✅ FrontOffice REST → gRPC — همه سرویس‌ها migrate شدند
+- ✅ BackOffice REST → gRPC — همه سرویس‌ها migrate شدند
+- ✅ BFF حذف — یک لایه کمتر در deployment
+- ✅ API Gateway (Ocelot) حذف — K8s Ingress جایگزین
+- ✅ Data Migration — Users, Products, Orders, Club
+- ✅ Geography Seeder — ۳۱ استان + ۱۲۰۰ شهر
+- ✅ SQL Scripts — ۱۴ اسکریپت مهاجرت اجرا شدند
+- ✅ Proto Package Unification — یک package مشترک
+- ✅ Binary Tree Reconstruction — از سیستم قدیم
+
+### DataMigration Tool (اسفند ۱۴۰۴)
+- ✅ ابزار مستقل مهاجرت داده — .NET 9 Console + Dapper + Polly + Serilog
+- ✅ Smart Retry Policy — فقط خطاهای transient SQL (deadlock, timeout, transport) — نه خطاهای منطقی
+- ✅ FK Disable/Enable — `NOCHECK`/`CHECK` حول مهاجرت برای حل FK violation
+- ✅ TruncateTargetTables — حل مشکل duplicate key (IX_ClubMembership_UserId)
+- ✅ Fallback Table Name — اگر جدول مقصد rename شده (`UserWalletChangeLogs` → `UserWalletHistories`)
+- ✅ PostMigration SQL — همه مراحل با `IF COL_LENGTH` / `OBJECT_ID` guard شده
+- ✅ کامیت‌ها: `0e8c6fd` → `8385c90` → `31cc464`
+
+### EF Migration — Staging (اسفند ۱۴۰۴)
+- ✅ اعمال migrations روی DB استیجینگ KBS (`185.252.31.42,2019/KBS`) — موفق
+- ✅ اعمال migrations روی DB اپلیکیشن (`194.5.195.53,31433/Foursat`) — موفق
+- ✅ آخرین migration: `20260227024734_Q27_HistoryTables_And_RenameWalletHistory` (۵۵ migration مجموع)
+- ✅ حل خطای لاگین `Invalid column name 'FirstActivationDate'` — دو DB مختلف بودند
+
+---
+
+## ۶. مستندات (100% کامل)
+
+- ✅ ایجاد totalDoc repository — مخزن مرکزی docs
+- ✅ جمع‌آوری ۵۳ فایل از ۵ مخزن مختلف
+- ✅ تجمیع به ۱۵ فایل ساختارمند — Business + Technical + Overview
+- ✅ Index و Cross-reference — نقشه ارتباطات
+- ✅ واژه‌نامه و استانداردها
+- ✅ نقشه راه آینده
+
+---
+
+## ۷. تحول سیستم پکیج‌بیس (Package-Based Transformation) — 90%
+
+> 📦 تبدیل سیستم تک‌پکیجی hardcoded به معماری چند‌پکیجی داینامیک
+> مرجع: [BIZ-PACKAGE-BASED-SYSTEM.md](../business/BIZ-PACKAGE-BASED-SYSTEM.md) | [PACKAGE-TRANSFORMATION-TASKS.md](../roadmap/PACKAGE-TRANSFORMATION-TASKS.md)
+
+### Phase 0 — فیکس باگ‌های فوری ✅ (`8b9c317`, `fe3edd1`)
+- ✅ B1: DiscountBalance شارژ نمی‌شد در VerifyGoldenPackagePurchase — اضافه `DiscountBalance += Amount × 2` + WalletChangeLog
+- ✅ B2: UserPackagePurchase ساخته نمی‌شد در VerifyGoldenPackagePurchase — ساخت record بعد verify
+- ✅ B3: UserPackagePurchase ساخته نمی‌شد در VerifyPackagePurchase — ساخت record
+- ✅ B4: UserPackagePurchase ساخته نمی‌شد در VerifyBasePackagePayment — ساخت record
+- ✅ B6: EXIT Magic Mode — ریست PackagePurchaseMethod + بستن چرخه فعلی
+
+### Phase 1 — زیرساخت Domain ✅ (`ae92ab8`)
+- ✅ T1.1: Package Entity — ۱۱ فیلد جدید (SortOrder, IsActive, IsBasePackage, DiscountMultiplier, MagicWalletMultiplier, ...)
+- ✅ T1.2: PackageFeature Entity — رابطه M:N بین Package و ClubFeature
+- ✅ T1.3: ClubMembership — ۴ فیلد First/Last Activation + PackageId
+- ✅ T1.4-T1.6: اضافه PackageId به ClubMembershipCycle, WeeklyCommissionPool, UserCommissionPayout, NetworkWeeklyBalance, UserWalletChangeLog
+- ✅ T1.7: علامت‌گذاری ۹ SystemConstants به‌عنوان [Obsolete]
+- ✅ T1.8: EF Configurations — Index, Precision, FK relations
+
+### Phase 1.5 — Migration + Data Seed ✅ (`a9cd2fd`)
+- ✅ EF Migration `AddPackageBasedSystem` — ستون‌ها + جداول + ایندکس‌ها
+- ✅ Golden Package Seed (Id=1) — Price=56M, ActivationFee=25.2M, DiscountMultiplier=2.0, MagicWalletMultiplier=2.5
+- ✅ Data Backfill — تمام رکوردهای موجود → PackageId=1
+- ✅ فیکس nullable DateTime/long در ClubMembership
+- ✅ فیکس Shadow FK PackageId1
+
+### Phase 2 — منطق کسب‌وکار ✅ (`8e5c7c5`)
+- ✅ T2.1: ActivateClubMembership — ActivationFee از Package entity
+- ✅ T2.2: AcceptClubMembershipContract — Package features از DB
+- ✅ T2.3: CalculateWeeklyBalances — MaxBalancesPerLeg per-package
+- ✅ T2.4: ProcessUserPayouts — PackageId tracking
+- ✅ T2.5: DayaLoans — Package.Price بجای hardcoded
+- ✅ T2.6: ManualPayment — Package.Price بجای hardcoded
+- ✅ T2.7: InitiateBasePackage/VerifyBasePackage — Package-based
+- ✅ T2.8: ChargeMagicWallet/VerifyMagicWalletCharge — MagicWalletMultiplier per-package
+- ✅ T2.9: OrmCommissionCalculationStrategy — MaxBalancesPerLeg/MaxNetworkLevel per-package
+- ✅ T2.10: ConfigurationService/UserOrderService/UserWalletService — Package reads
+- ✅ **نتیجه:** صفر مصرف SystemConstants deprecated باقی مانده
+
+### Phase 3 — بازسازی لایه Package ✅ (`ccb938e`)
+- ✅ Proto: ۱۱ فیلد جدید در ۵ message (CreateNewPackageRequest, UpdatePackageRequest, GetPackageResponse, ...)
+- ✅ GetUserPackageStatus — پیاده‌سازی (قبلاً NotImplementedException بود!)
+- ✅ CustomerVerifyPackagePurchase — شارژ کیف‌پول اضافه شد (قبلاً missing بود!)
+- ✅ VerifyGoldenPackagePurchase — `package.DiscountMultiplier` بجای hardcoded ×2
+- ✅ GetAllPackageByFilter — فیلتر IsDeleted
+- ✅ GetCustomerPackages — فیلتر IsDeleted + IncludeInactive + SortOrder
+- ✅ GetCustomerPackageDetails — PackageFeatures از DB
+- ✅ GetCustomerPurchaseHistory — Include Transaction
+- ✅ UpdatePackageCommand — ۱۲ فیلد جدید
+
+### Phase 4 — تکمیل CRUD + Legacy Fixes ✅ (`0002a5a`)
+- ✅ CreateNewPackageCommand — ۱۲ فیلد جدید با default‌های مناسب
+- ✅ GetPackageResponseDto — ۱۲ فیلد جدید (Mapster auto-map)
+- ✅ GetAllPackageByFilterResponseModel — ۱۲ فیلد جدید
+- ✅ PurchaseGoldenPackage — حذف Title string match شکننده (`"طلایی"/"golden"`) → `IsDeleted/IsActive/SupportsDirectPurchase`
+- ✅ VerifyPackagePurchase — حذف hardcoded `order.Amount × 2` → `package.DiscountMultiplier` از DB
+
+### Phase 5 — پورسانت per-package + پاکسازی golden ✅ (`607f791`, `7176fe4`)
+- ✅ ORM Commission: per-user-package calculation via `ClubMembership.LastPackageId`
+  - userPackageMap، per-user maxBalancesPerLeg/maxNetworkLevel
+  - Carryover keyed by (UserId, PackageId) tuple
+- ✅ SP Commission: loop over packages، pass `@PackageId/@InputMaxBalancesPerLeg/@InputMaxNetworkLevel`
+- ✅ sp_CalculateWeeklyBalances: ۳ پارامتر جدید، فیلتر `cm.LastPackageId = @PackageId`، ستون PackageId در INSERT
+- ✅ Fix: `cm.PackageId` → `cm.LastPackageId` — match actual DB column name
+- ✅ Fix golden/طلایی string refs in user-facing messages (ActivateClubMembership)
+- ✅ Rename `HasPurchasedGoldenPackage` → `HasPurchasedPackage` (DTO + Handler + Proto + Mapping)
+
+### Phase 6 — Deprecation cleanup + ConfigurationService ✅ (`d19c569`)
+- ✅ Mark `PurchaseGoldenPackage`/`VerifyGoldenPackagePurchase` RPCs as `deprecated = true`
+- ✅ Mark `InitiateBasePackagePayment`/`VerifyBasePackagePayment` RPCs as `deprecated = true`
+- ✅ Remove deprecated SystemConstants from `GetAllAsDict`/`GetAllWithDescriptions` helpers
+- ✅ Add MagicWallet per-package values to ConfigurationService (Multiplier, MaxDeposit, MaxCredit)
+- ✅ تأیید: صفر رفرنس فعال به ۹ SystemConstants منسوخ — dead code آماده حذف
+
+### Phase 7 — UI ✅ (گزارش per-package)
+- ⬜ FrontOffice: کاشی‌های داینامیک پکیج
+- ⬜ FrontOffice: MyPackages + re-purchase
+- ✅ FrontOffice: Commission Dashboard per-package — فیلتر dropdown پکیج + ستون پکیج + MudChip (دسکتاپ + موبایل)
+- ✅ FrontOffice: WeeklyBalance per-package — فیلتر MudSelect پکیج + MudChip اطلاعات هفته
+- ✅ BackOffice: فیلتر پکیج در گزارش‌ها — PackageSelect component + UserPayouts + BalancesReport
+
+### Phase 8e — Per-Package Commission Reports ✅ (CMS:`aaaf7fc` FO:`a956cb9` BO:`8be98ae`)
+- ✅ Proto: اضافه `package_id` فیلتر به ۴ request + `package_id`/`package_title` به ۴ response model
+- ✅ CMS: اضافه PackageId فیلتر به ۴ query + handler + ۳ DTO + CommissionProfile mapping
+- ✅ BO: کامپوننت PackageSelect + فیلتر و ستون پکیج در UserPayouts + BalancesReport
+- ✅ FO: فیلتر و ستون پکیج در CommissionDashboard + WeeklyBalance
+- ✅ NuGet: `0.0.186` → `0.0.187`
+
+### Phase 9 — Q24-Q30 Business Decisions + History Infrastructure ✅
+
+#### 9a: Q24+Q26 — Balance Threshold + SP Worker ✅ (CMS:`a1024a3`)
+- ✅ Q24: آستانه موجودی `Balance <= 1_000_000` ریال برای ورود Magic و خرید مجدد (بجای `== 0`)
+- ✅ Q26: `StoredProcedureDeploymentService` (IHostedService) — خواندن فایل‌های `.sql` از embedded resource، مقایسه checksum و اعمال خودکار در startup
+
+#### 9b: Q27 — History Tables Entities ✅ (CMS:`fdbb91d`)
+- ✅ `PackageHistory` entity — فیلدهای Old*/New* برای Price, ActivationFee, MagicMultiplier, MagicMaxDeposit, MaxBalancesPerLeg, IsActive
+- ✅ `ClubMembershipCycleHistory` entity — فیلدهای Old*/New* برای IsCurrentCycle, MagicStartedAt, MagicCompletedAt
+- ✅ `PackageAction` و `ClubMembershipCycleAction` enums
+- ✅ EF Configurations + DbSets + Navigation Properties
+
+#### 9c: Q28 — UI Guidance ✅ (FO:`474d364` BO:`6939780`)
+- ✅ FrontOffice: ۷ صفحه با MudAlert (G1-G7) — Packages, Checkout, MyPackages, MagicWallet, Commission, Membership, ActivationSection
+- ✅ BackOffice: ۶ صفحه با MudAlert (G8-G13) — PackageCRUD, ClubFeatures, ManualPayments, Commission Dashboard, UserPayouts, ClubMembers
+
+#### 9d: Rename + History Interceptor + Migration ✅ (CMS:`10d2ca2`)
+- ✅ تغییر نام `UserWalletChangeLog` → `UserWalletHistory` در ۵۴+ فایل (entities, configs, DTOs, commands, queries, protos, services)
+- ✅ تغییر نام ۳۴ فایل و ۱۱ دایرکتوری
+- ✅ تغییر نام proto: `userwalletchangelog.proto` → `userwallethistory.proto`
+- ✅ `IHasHistory<T>` generic interface — متد `CreateHistorySnapshot` برای ثبت خودکار
+- ✅ `HistoryTrackingSaveChangesInterceptor` — reflection-based، auto-fill Old* از OriginalValues
+- ✅ `Package` implements `IHasHistory<PackageHistory>`
+- ✅ EF Migration `Q27_HistoryTables_And_RenameWalletHistory` — **RenameTable** (حفظ داده) + rename PK/FK/Index via sp_rename
+- ✅ NuGet: `0.0.187` → `0.0.188`
+
+### Phase 10 — استقرار + DataMigration + UI خرید پکیج ✅
+
+#### 10a: DataMigration Tool ✅ (Local — بدون remote)
+- ✅ ابزار مستقل مهاجرت داده — .NET 9 Console app + Dapper (bulk copy) + Polly (retry) + Serilog (logging)
+- ✅ مهاجرت ۱۸ جدول از DB پروداکشن (`185.252.31.42,2019/Foursat`) به استیجینگ (`KBS`)
+- ✅ Smart Retry — فقط خطاهای transient (deadlock/timeout/transport)، نه خطاهای منطقی
+- ✅ FK Disable/Enable — `ALTER TABLE NOCHECK/CHECK CONSTRAINT` حول هر مهاجرت
+- ✅ TruncateTargetTables — حل duplicate key (`IX_ClubMembership_UserId`) هنگام اجرای مجدد
+- ✅ Fallback Table Name — جدول مقصد rename شده؟ (`UserWalletChangeLogs` → `UserWalletHistories`)
+- ✅ PostMigration SQL — همه مراحل با `IF COL_LENGTH`/`OBJECT_ID` guard شده (سازگار با هر دو schema)
+- ✅ کامیت‌ها: `0e8c6fd` → `8385c90` (MERGE fix) → `31cc464` (FK+truncate+PostMigration)
+
+#### 10b: EF Migration Staging ✅
+- ✅ اعمال ۵۵ migration روی DB استیجینگ KBS (`185.252.31.42,2019;Database=KBS`)
+- ✅ اعمال ۵۵ migration روی DB اپلیکیشن (`194.5.195.53,31433;Database=Foursat`)
+- ✅ آخرین migration: `20260227024734_Q27_HistoryTables_And_RenameWalletHistory`
+- ✅ حل خطای لاگین: `Invalid column name 'FirstActivationDate'` — CMS به DB دیگری وصل بود
+
+#### 10c: PackagePurchaseDialog — دیالوگ داینامیک خرید (FO:`a3681a8`)
+- ✅ `PackagePurchaseDialog.razor` — دیالوگ ۲ مرحله‌ای جایگزین دیالوگ hardcoded «پکیج پایه»
+- ✅ مرحله ۱: نمایش کاشی‌های پکیج (responsive grid 2-3 ستونه) با عنوان + قیمت + ویژگی‌ها + badge «پایه»
+- ✅ مرحله ۲: انتخاب روش پرداخت (مستقیم + اعتبار دایا) با خلاصه پکیج انتخابی
+- ✅ بارگذاری از `PackageService.GetAllPackagesAsync()` + `PackagePurchaseResult` record
+- ✅ محدودیت دایا: فقط `SupportsDayaPurchase && PurchaseCycleCount == 0`
+- ✅ CSS: `.pkg-tile`, `.pkg-tile-badge`, `.pkg-payment-option` در `site.css`
+- ✅ NuGet: `0.0.188` → `0.0.189`
+
+#### 10d: ۴ فیکس UI پکیج (FO:`3c1a8ff`)
+- ✅ **Toman/Rial**: قیمت از سرور به ریال ← `FormattedPrice` حالا `Price / 10` برای نمایش صحیح تومان
+- ✅ **لیبل**: «ضریب تخفیف» → «ضریب اعتبار» (دیالوگ + صفحه لیست پکیج‌ها)
+- ✅ **دکمه بازگشت**: وجود داشت (`ArrowForward` + `BackToList`) — تأیید عملکرد
+- ✅ **HTML Description**: `@((MarkupString)pkg.Description)` بجای متن ساده
+
+---
+
+## ۸. Timeline (جدول زمانی)
+
+| زمان | رویداد | درصد پروژه |
+|------|--------|-----------|
+| مهر ۱۴۰۳ | شروع پروژه، معماری CMS | 10% |
+| آبان ۱۴۰۳ | CQRS + gRPC + EF Core | 20% |
+| آذر ۱۴۰۳ | باشگاه + درخت باینری + کمیسیون | 35% |
+| دی ۱۴۰۳ | فروشگاه عادی + پرداخت از کیف‌پول | 45% |
+| بهمن ۱۴۰۳ | فروشگاه اعتباری + وام دایا | 55% |
+| اسفند ۱۴۰۳ (هفته ۱) | UI Modernization Phase 1-3 | 65% |
+| اسفند ۱۴۰۳ (هفته ۲) | Site Pages + BackOffice audit | 75% |
+| اسفند ۱۴۰۳ (هفته ۳) | Inventory + Lazy Load + Images | 85% |
+| اسفند ۱۴۰۳ (هفته ۴) | مستندات + نهایی‌سازی | 95% |
+| اسفند ۱۴۰۴ (هفته ۱-۲) | 🪄 کیف‌پول جادویی (فاز 1-6) + اصلاح VAT 10% | 96% |
+| اسفند ۱۴۰۴ (هفته ۳) | 🚀 فعال‌سازی درگاه + بهبود UI ادمین + مرج پروداکشن | 97% |
+| اسفند ۱۴۰۴ (هفته ۴) | 📦 تحول پکیج‌بیس فاز ۰-۶ (Domain → Migration → Business → Package → CRUD → Commission per-pkg → Deprecation) | 97% |
+| اسفند ۱۴۰۴ (هفته ۵) | 📦 فاز 8e: گزارش‌های پورسانت per-package (Proto + CMS + BO + FO) | 98% |
+| اسفند ۱۴۰۴ (هفته ۶) | 📦 فاز ۹: Q24-Q30 (آستانه + SP Worker + History Tables + UI Guidance + Rename + Interceptor + Migration) | 99% |
+| اسفند ۱۴۰۴ (هفته ۷) | 📦 فاز ۱۰: DataMigration Tool + EF Staging + PackagePurchaseDialog + UI Fixes (Toman/Rial + لیبل + HTML) | 99.5% |
+| اسفند ۱۴۰۴ (هفته ۸) | 💳 فاز ۱۱: فیکس ZarinPal Verify + اصلاح تومان/ریال + صفحه موفقیت + حذف دوبار ×۱۰ + امنیت Callback URL | 99.5% |

overview/OVERVIEW-04-GLOSSARY.md

@@ -0,0 +1,235 @@
+# 📖 واژه‌نامه، استانداردها و قراردادهای کد
+
+> **اصطلاحات فارسی/انگلیسی، الگوهای نام‌گذاری و استانداردهای حرفه‌ای**  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet)
+
+---
+
+## ۱. واژه‌نامه اصلی (فارسی ↔ انگلیسی)
+
+### ۱.۱ مفاهیم بیزینسی
+
+| فارسی | انگلیسی | توضیح |
+|-------|---------|--------|
+| کارا بازار سلامت | FourSat | نام تجاری پلتفرم |
+| باشگاه مشتریان | Club Membership | عضویت ویژه با پکیج طلایی |
+| پکیج طلایی | Golden Package | بسته ۵۶M تومان برای ورود به باشگاه |
+| درخت باینری | Binary Tree | ساختار شبکه‌ای ۲ شاخه‌ای |
+| پای چپ / راست | Left Leg / Right Leg | دو شاخه هر نود در درخت |
+| کمیسیون هفتگی | Weekly Commission | سهم از Pool بر اساس بالانس |
+| بالانس هفتگی | Weekly Balance | MIN(فروش‌چپ, فروش‌راست) |
+| سقف هفتگی | Weekly Cap | حداکثر ۳۰۰ واحد هر پا |
+| باقیمانده | Carryover | فروش مازاد قابل‌انتقال به هفته بعد |
+| Pool هفتگی | Weekly Commission Pool | مخزن کمیسیون قابل‌توزیع |
+| هزینه فعالسازی | Activation Fee | ۲۵M تومان از Balance |
+| واریز هدیه | Gift Value | ۲۵.۲M واریز به Pool |
+| فروشگاه اعتباری | Discount Store | فروشگاه اعتباری per-product برای اعضا |
+| پرداخت ترکیبی | Hybrid Payment | DiscountBalance + IPG |
+| وام دایا | Daya Loan | وام آنلاین برای خرید پکیج |
+| کد معرف | Referral Code | کد یکتا هر عضو برای دعوت |
+| موجودی | Inventory | تعداد محصول در انبار |
+| کیف‌پول جادویی | Magic Wallet | حالت ویژه: Balance=0 → شارژ ×2.5 از درگاه |
+| حالت جادویی | Magic Mode | WalletMode=1 — کمیسیون غیرفعال |
+| ضریب شارژ | Magic Multiplier | واریز × 2.5 = اعتبار Balance |
+| سقف دور | Per-Cycle Cap | 100M تومان واریز → 250M اعتبار |
+| دوره عضویت | Membership Cycle | ClubMembershipCycle — هر خرید پکیج = یک دور |
+
+### ۱.۲ مفاهیم فنی
+
+| فارسی | انگلیسی | توضیح |
+|-------|---------|--------|
+| سامانه مدیریت محتوا | CMS Microservice | هسته اصلی backend |
+| پنل مدیریت | BackOffice | رابط ادمین (Blazor WASM) |
+| سایت کاربران | FrontOffice | رابط مشتری (Blazor Server) |
+| درگاه پرداخت | Payment Gateway (IPG) | ZarinPal |
+| سرویس پرداخت | PYMS | Payment Management Service |
+| کیف‌پول نقدی | Balance Wallet | موجودی قابل‌خرج |
+| کیف‌پول طلایی | Network Balance | برای محاسبه کمیسیون (شارژ نمی‌شود) |
+| کیف‌پول اعتباری | Discount Balance | برای فروشگاه اعتباری (IPG و Daya: 112M — دو برابر BasePackageAmount) |
+| بارگذاری تنبل | Lazy Loading | لود محصولات 12تایی (FO) / 10تایی (CMS default) |
+| صفحات سایت | Site Pages | صفحات قابل‌ویرایش (Shopify-style) |
+| ثوابت سیستمی | System Constants | تنظیمات key-value |
+| پردازش پس‌زمینه | Background Job | Hangfire recurring/fire-and-forget |
+
+---
+
+## ۲. مخفف‌ها (Abbreviations)
+
+| مخفف | کامل | توضیح |
+|------|------|--------|
+| **CMS** | Content Management System | مایکروسرویس اصلی |
+| **BO** | BackOffice | پنل مدیریت |
+| **FO** | FrontOffice | سایت کاربران |
+| **BFF** | Backend-for-Frontend | حذف‌شده |
+| **CQRS** | Command Query Responsibility Segregation | الگوی معماری |
+| **gRPC** | Google Remote Procedure Call | پروتکل ارتباطی |
+| **EF** | Entity Framework | ORM |
+| **JWT** | JSON Web Token | احراز هویت |
+| **IPG** | Internet Payment Gateway | درگاه پرداخت آنلاین |
+| **PYMS** | Payment Management Service | سرویس مالی |
+| **SP** | Stored Procedure | رویه ذخیره‌شده SQL |
+| **OTP** | One-Time Password | رمز یکبار مصرف |
+| **K8s** | Kubernetes | ارکستراسیون کانتینر |
+| **CI/CD** | Continuous Integration/Deployment | خط لوله خودکار |
+| **RTL** | Right-to-Left | راست‌به‌چپ (فارسی) |
+| **WASM** | WebAssembly | فرمت اجرایی مرورگر |
+| **PWA** | Progressive Web App | وب‌اپ پیشرفته |
+
+---
+
+## ۳. استانداردهای نام‌گذاری
+
+### ۳.۱ C# / .NET
+
+| نوع | الگو | مثال |
+|-----|------|------|
+| **Class** | PascalCase | `ProductService`, `CreateProductCommand` |
+| **Interface** | I + PascalCase | `IProductService`, `ICurrentUserService` |
+| **Method** | PascalCase + Async | `GetProductsAsync()`, `CreateOrderAsync()` |
+| **Property** | PascalCase | `ProductName`, `IsActive` |
+| **Private field** | _camelCase | `_dbContext`, `_logger` |
+| **Parameter** | camelCase | `productId`, `userId` |
+| **Constant** | PascalCase | `MaxNetworkLevel`, `ActivationFee` |
+| **Enum** | PascalCase (singular) | `OrderStatus`, `PaymentType` |
+| **Namespace** | Company.Project.Feature | `CMSMicroservice.Features.Products` |
+
+### ۳.۲ Protobuf
+
+| نوع | الگو | مثال |
+|-----|------|------|
+| **Service** | PascalCase + Service | `ProductService` |
+| **Method** | PascalCase | `GetProducts`, `CreateOrder` |
+| **Message** | PascalCase + Message/Request/Response | `ProductMessage`, `GetProductsRequest` |
+| **Field** | snake_case | `product_name`, `is_active` |
+| **Enum** | PascalCase | `ORDER_STATUS_PENDING` |
+
+### ۳.۳ Blazor / UI
+
+| نوع | الگو | مثال |
+|-----|------|------|
+| **Page** | PascalCase.razor + .razor.cs | `Products.razor`, `Products.razor.cs` |
+| **Component** | PascalCase.razor | `AppImage.razor`, `ProductCard.razor` |
+| **Parameter** | [Parameter] PascalCase | `[Parameter] public string Title` |
+| **CSS class** | kebab-case | `product-card`, `hero-section` |
+
+### ۳.۴ Database
+
+| نوع | الگو | مثال |
+|-----|------|------|
+| **Table** | PascalCase (plural) | `Products`, `Users`, `Orders` |
+| **Column** | PascalCase | `ProductName`, `CreatedAt` |
+| **FK** | {Entity}Id | `ProductId`, `UserId` |
+| **SP** | SP_ / sp_ + PascalCase | `SP_GetNetworkTree` |
+| **Schema** | [CMS] | `[CMS].Products` |
+
+---
+
+## ۴. الگوهای معماری
+
+### ۴.۱ CQRS Pattern
+
+```
+Command (نوشتن):
+    CreateProductCommand → CreateProductCommandHandler → DB Write
+
+Query (خواندن):
+    GetProductsQuery → GetProductsQueryHandler → DB Read
+
+قوانین:
+    ✅ Command نباید data برگرداند (فقط Id یا void)
+    ✅ Query نباید state تغییر دهد
+    ✅ هر Handler فقط یک مسئولیت
+    ✅ Validation در Validator (FluentValidation)
+```
+
+### ۴.۲ gRPC Client Pattern (FrontOffice/BackOffice)
+
+```
+Service Layer:
+    1. Inject GrpcClient via DI
+    2. Map UI model → Proto Request
+    3. Call gRPC method
+    4. Map Proto Response → UI model
+    5. Handle RpcException → user-friendly message
+```
+
+### ۴.۳ Hangfire Job Pattern
+
+```
+Recurring Job:
+    1. Register in Startup: RecurringJob.AddOrUpdate<T>(...)
+    2. Implement Execute() method
+    3. Use Polly for retry
+    4. Log start/end/error
+    5. Idempotent — safe to re-run
+```
+
+---
+
+## ۵. Git Workflow
+
+### ۵.۱ شاخه‌ها
+
+| شاخه | کاربرد | Deploy Target |
+|------|--------|--------------|
+| `kub-stage` | توسعه فعال | Staging server |
+| `production` | محیط نهایی | Production server |
+| `main` | مستندات (totalDoc) | — |
+
+### ۵.۲ مخازن
+
+| مخزن | Remote | شاخه اصلی |
+|------|--------|-----------|
+| CMS | `gitea` → git.se.kbs1.ir | `kub-stage` |
+| BackOffice | `kub-stage` → git.se.kbs1.ir | `kub-stage` |
+| FrontOffice | `kub-stage` → git.se.kbs1.ir | `kub-stage` |
+| Docs (totalDoc) | `foursatDocs` → git.se.kbs1.ir/admin/docs | `main` |
+
+### ۵.۳ Commit Convention
+
+```
+feat: add lazy loading for products
+fix: correct counter animation on landing
+docs: consolidate 53 files into 15
+refactor: remove BFF layer
+chore: update MudBlazor to v8
+```
+
+---
+
+## ۶. ساختار پروژه
+
+```
+FourSat/                          ← Root workspace
+├── CMS/                          ← مایکروسرویس اصلی (.NET 9)
+│   ├── src/CMSMicroservice/      ← کد اصلی
+│   └── Dockerfile
+├── BackOffice/                   ← پنل مدیریت (Blazor WASM)
+│   └── src/BackOffice/
+├── FrontOffice/                  ← سایت کاربران (Blazor Server)
+│   └── src/FrontOffice/
+├── DataMigration/                ← ابزار مهاجرت داده
+├── deployment/                   ← اسکریپت‌های استقرار
+│   ├── k8s-manifests/
+│   └── docker-compose.yml
+├── dbbkup/                       ← SQL scripts و backup
+├── totalDoc/                     ← 📚 مستندات (15 فایل)
+│   ├── business/                 ← بیزینسی (5 فایل)
+│   ├── technical/                ← فنی (5 فایل)
+│   └── overview/                 ← کلان (5 فایل)
+└── nupkg/                        ← Proto NuGet packages
+```
+
+---
+
+## ۷. Definition of Done (DoD)
+
+هر فیچر قبل از merge باید:
+
+- [ ] کد review شده باشد
+- [ ] بیلد موفق باشد (CI green)
+- [ ] خطای compile نداشته باشد
+- [ ] در Staging تست شده باشد
+- [ ] مستندات بروز شده باشد
+- [ ] RTL درست کار کند
+- [ ] Error handling مناسب داشته باشد

overview/OVERVIEW-05-ROADMAP.md

@@ -0,0 +1,233 @@
+# 🗺️ نقشه راه، ریسک‌ها و کارهای باقیمانده
+
+> **Roadmap + Risk Register + Dependencies + Priorities**  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: فاز ۱۱ — فیکس‌های پرداخت ZarinPal + امنیت Callback URL + تومان/ریال)
+
+---
+
+## ۱. وضعیت فعلی پروژه
+
+```
+██████████████████████████████████████████████████ 95%
+
+Core Platform     ████████████████████████████████████████████████ 98%
+Club System       ████████████████████████████████████████████████ 98%
+E-Commerce        ████████████████████████████████████████████████ 98%
+Payment           ████████████████████████████████████████████████ 99%
+Magic Wallet      ████████████████████████████████████████████████ 100%
+Package-Based     ███████████████████████████████████████████████░░ 97%
+UI/UX             ██████████████████████████████████████████████░░░ 95%
+Deployment        ██████████████████████████████████████████████░░ 95%
+Documentation     ████████████████████████████████████████████████ 100%
+```
+
+---
+
+## ۲. کارهای باقیمانده (Backlog)
+
+### 🔴 اولویت بالا (High Priority)
+
+| # | آیتم | حوزه | پیش‌نیاز | تخمین |
+|---|------|------|---------|-------|
+| H1 | Product Bundle | Business | Proto + Handler | ۳ روز |
+| H2 | Mobile Responsive (Phase 7) | UI/UX | — | ۵ روز |
+| H3 | API Rate Limiting | CMS | — | ۲ روز |
+| H4 | Error Boundary (Global) | FO/BO | — | ۱ روز |
+
+### 🟡 اولویت متوسط (Medium Priority)
+
+| # | آیتم | حوزه | پیش‌نیاز | تخمین |
+|---|------|------|---------|-------|
+| M1 | Manual Payment System | Business | تصمیم مدیریت | ۳ روز |
+| M2 | SignalR for Chatika | CMS | — | ۲ روز |
+| M3 | Dark Mode | UI/UX | — | ۲ روز |
+| M4 | SEO Meta Tags | FO | — | ۲ روز |
+| M5 | Order Notifications (SMS) | CMS | — | ۱ روز |
+| M6 | BackOffice Dashboard Charts | BO | — | ۳ روز |
+
+### 🟢 اولویت پایین (Low Priority)
+
+| # | آیتم | حوزه | پیش‌نیاز | تخمین |
+|---|------|------|---------|-------|
+| L1 | PWA Support | FO | Mobile first | ۳ روز |
+| L2 | API Versioning | CMS | — | ۲ روز |
+| L3 | Monitoring (Prometheus) | Infra | — | ۳ روز |
+| L4 | Log Aggregation (Seq/ELK) | Infra | — | ۳ روز |
+| L5 | Product Compare | FO | — | ۲ روز |
+| L6 | Wishlist | FO | — | ۲ روز |
+| L7 | Email Templates (HTML) | CMS | — | ۲ روز |
+| L8 | Refund System | CMS/PYMS | — | ۵ روز |
+
+### ⛔ بلاک‌شده (Blocked)
+
+| # | آیتم | بلاکر | اقدام لازم |
+|---|------|-------|-----------|
+| B1 | وام دایا (Production) | API دایا تکمیل نشده | پیگیری تیم دایا |
+| B2 | پرداخت دستی | تصمیم‌گیری مدیریت | جلسه با مدیر محصول |
+
+---
+
+## ۳. نقشه راه (Roadmap)
+
+### Q1 1404 (فروردین-خرداد)
+
+```mermaid
+gantt
+    title Q1 1404 — فروردین تا خرداد
+    dateFormat YYYY-MM-DD
+    section Sprint 1 فروردین
+        H2 Mobile Responsive     :a1, 2025-03-21, 5d
+        H1 Product Bundle        :a2, after a1, 3d
+        M4 SEO Meta Tags         :a3, after a2, 2d
+    section Sprint 2 اردیبهشت
+        M1 Manual Payment        :b1, 2025-04-21, 3d
+        M2 SignalR Chatika       :b2, after b1, 2d
+        M6 Dashboard Charts      :b3, after b2, 3d
+    section Sprint 3 خرداد
+        M3 Dark Mode             :c1, 2025-05-22, 2d
+        H3 Rate Limiting         :c2, after c1, 2d
+        L1 PWA                   :c3, after c2, 3d
+```
+
+### Q2 1404 (تیر-شهریور)
+
+```mermaid
+gantt
+    title Q2 1404 — تیر تا شهریور
+    dateFormat YYYY-MM-DD
+    section Sprint 4 تیر
+        L3 Monitoring            :d1, 2025-06-22, 3d
+        L4 Log Aggregation       :d2, after d1, 3d
+        L2 API Versioning        :d3, after d2, 2d
+    section Sprint 5 مرداد
+        L5 Product Compare       :e1, 2025-07-23, 2d
+        L6 Wishlist              :e2, after e1, 2d
+        L7 Email Templates       :e3, after e2, 2d
+    section Sprint 6 شهریور
+        L8 Refund System         :f1, 2025-08-23, 5d
+        Performance Optimization :f2, after f1, 3d
+        Security Audit           :f3, after f2, 3d
+```
+
+---
+
+## ۴. ریسک‌ها (Risk Register)
+
+### ۴.۱ ریسک‌های فنی
+
+| # | ریسک | احتمال | تأثیر | شدت | اقدام |
+|---|------|--------|------|-----|--------|
+| R1 | MSSQL 2022 عدم scalability | Medium | High | 🟡 | مانیتورینگ + index optimization |
+| R2 | gRPC breaking changes هنگام ارتقا proto | Low | High | 🟡 | Backward compatible changes |
+| R3 | Hangfire job failure (commission) | Low | Critical | 🔴 | Polly retry + alerting + manual trigger |
+| R4 | ZarinPal downtime | Medium | High | 🟡 | Fallback queue + manual payment |
+| R5 | Ingress-nginx CVE | Low | Critical | 🔴 | Regular updates + WAF |
+| R6 | Disk space (SQL backups) | Medium | Medium | 🟡 | Auto cleanup + offsite backup |
+
+### ۴.۲ ریسک‌های بیزینسی
+
+| # | ریسک | احتمال | تأثیر | شدت | اقدام |
+|---|------|--------|------|-----|--------|
+| R7 | دایا Loan API تغییر | High | Medium | 🟡 | Mock mode + adapter pattern |
+| R8 | تغییر درصد تخفیف باشگاه | Low | Low | 🟢 | SystemConstants قابل‌تنظیم |
+| R9 | رشد سریع کاربران (>10K) | Low | High | 🟡 | Load test + horizontal scale |
+| R10 | تغییر قوانین مالیاتی | Medium | Medium | 🟡 | VAT configurable |
+
+---
+
+## ۵. وابستگی‌های خارجی (External Dependencies)
+
+| سرویس | وابستگی | وضعیت | SLA |
+|--------|---------|--------|-----|
+| **ZarinPal** | درگاه پرداخت IPG | ✅ فعال | 99.5% |
+| **Kavenegar** | ارسال SMS (OTP) | ✅ فعال | 99% |
+| **Daya Loan** | API وام | ⚠️ Mock mode | نامشخص |
+| **Chatika** | AI Chat | ✅ فعال | 95% |
+| **Docker Hub** | Base images | ✅ با mirror | — |
+| **NuGet.org** | .NET packages | ✅ با Nexus cache | — |
+| **Gitea** | Source control | ✅ Self-hosted | 99% |
+
+---
+
+## ۶. معیارهای کیفیت (Quality Metrics)
+
+### ۶.۱ فعلی
+
+| معیار | مقدار فعلی | هدف |
+|-------|-----------|------|
+| Build Success Rate | ~95% | 99% |
+| Average Response Time | ~200ms | <150ms |
+| gRPC Error Rate | ~2% | <1% |
+| Test Coverage | ~0% | >60% |
+| Uptime (Staging) | ~98% | 99% |
+| Documentation Coverage | 100% | 100% ✅ |
+
+### ۶.۲ اقدامات بهبود
+
+| اقدام | اولویت | تأثیر |
+|-------|---------|-------|
+| Unit Tests اضافه شود | High | Test Coverage +40% |
+| Integration Tests | Medium | Reliability +20% |
+| Load Testing (k6/JMeter) | Medium | Performance insight |
+| Structured Logging (Serilog) | Medium | Debug time -50% |
+| Health check endpoints | Done ✅ | Uptime monitoring |
+
+---
+
+## ۷. Definition of Done — Release Checklist
+
+### Pre-Release (Staging)
+
+- [ ] همه تست‌ها پاس شوند
+- [ ] Review توسط حداقل ۱ نفر
+- [ ] Migration scripts اجرا شوند
+- [ ] Smoke test روی staging
+- [ ] مستندات بروز باشد
+
+### Production Release
+
+- [ ] Staging sign-off
+- [ ] Database backup
+- [ ] Docker images tagged
+- [ ] K8s rollout
+- [ ] Health check green
+- [ ] Post-deploy smoke test
+- [ ] Rollback plan ready
+
+---
+
+## ۸. خلاصه اولویت‌بندی
+
+```
+DONE (اسفند ۱۴۰۴):
+    → Documentation consolidation ✅
+    → 🪄 Magic Wallet فاز 1-6 ✅ (کامل)
+    → اصلاح VAT 9% → 10% ✅
+    → فعال‌سازی درگاه ZarinPal (پروداکشن) ✅
+    → تنظیمات محیطی Staging/Production ✅
+    → بهبود UI ادمین (UserAutoComplete + نام کاربر در کیف‌پول) ✅
+    → مرج پروداکشن هر ۳ ریپو (CMS + FO + BO) ✅
+    → اجرای Migration روی پروداکشن ✅
+    → 📦 تحول پکیج‌بیس فاز 0-6 ✅ (Domain → Migration → Business → Package → CRUD → Commission per-pkg → Deprecation)
+    → 📦 فاز ۹: Q24-Q30 + History + Rename + Interceptor ✅
+    → 📦 فاز ۱۰: DataMigration Tool + EF Staging + PackagePurchaseDialog + UI Fixes ✅
+    → 💳 فاز ۱۱: فیکس ZarinPal Verify (amount=0) + تصحیح مدل تومان/ریال + صفحه موفقیت پرداخت + حذف دوبار ×۱۰ + امنیت Callback URL ✅
+    
+ NOW (این ماه):
+    → تست کامل پروداکشن
+    → فیکس باگ‌های کشف‌شده در تست
+    
+NEXT (فروردین):
+    → Mobile Responsive (H2)
+    → Product Bundle (H1)
+    → SEO (M4)
+
+LATER (Q2):
+    → Monitoring + Logging (L3, L4)
+    → PWA (L1)
+    → Refund (L8)
+
+BLOCKED:
+    → Daya Loan Production (B1) — waiting on Daya
+    → Manual Payment (B2) — waiting on decision
+```

roadmap/FEATURE-BACKLOG.md

@@ -0,0 +1,81 @@
+# 📋 فیچر بکلاگ — RPCهای آماده (بدون UI)
+
+> تاریخ: ۱۴۰۴/۱۲/۱۰  
+> منبع: آدیت gRPC (کامیت `3575e48`) → ۱۲ RPC کامل بدون فرانت  
+> اولویت‌بندی: بر اساس ارزش کسب‌وکار + نیازمندی پکیج‌بیس
+
+---
+
+## 🎯 خلاصه
+
+از ۲۴ RPC مُرده شناسایی‌شده، **۱۲ عدد پیاده‌سازی کامل** دارند ولی هرگز از فرانت‌ها وصل نشدند. این‌ها فیچرهای آماده هستند که فقط نیاز به UI دارند.
+
+---
+
+## 📊 ماتریس فیچر × اولویت
+
+### 🔴 اولویت بالا — مرتبط با پکیج‌بیس کردن
+
+| # | RPC | تارگت | صفحه | اقدام | تخمین |
+|---|-----|-------|------|-------|-------|
+| F1 | `AssignFeatureToMembership` | BackOffice | ClubFeaturesPage.razor | دکمه «اختصاص فیچر به عضو» + ماتریس PackageFeature | ۴ ساعت |
+| F2 | `ChangeNetworkParent` | BackOffice | UserNetworkInfo.razor | ✅ دکمه «تغییر والد» + مودال ChangeParentDialog | BO:`e020354` |
+| F3 | `CalculateOrderPV` | FrontOffice | Store/OrderDetail.razor | ✅ نمایش PV سفارش + PV هر محصول | FO:`3bffc13` |
+
+### 🟡 اولویت متوسط — بهبود UX فروشگاه
+
+| # | RPC | تارگت | صفحه | اقدام | تخمین |
+|---|-----|-------|------|-------|-------|
+| F4 | `CustomerReorderPreviousOrder` | FrontOffice | OrderHistory (Store/Discount) | دکمه «تکرار سفارش» در هر ردیف تاریخچه | ۳ ساعت |
+| F5 | `CustomerTrackOrder` | FrontOffice | OrderTracking.razor | وصل Tracking API → نمایش TrackingCode + وضعیت ارسال | ۴ ساعت |
+| F6 | `UpdateCustomerSettings` | FrontOffice | Profile/Settings.razor | فرم تنظیمات اعلان (Email/SMS/Push) + دکمه ذخیره | ۳ ساعت |
+| F7 | `GetLowStockProducts` | BackOffice | LowStockPage.razor | وصل API → فیلتر threshold + هشدار بصری | ۳ ساعت |
+
+### 🟢 اولویت پایین — گزارش‌دهی و عملیات انبوه
+
+| # | RPC | تارگت | صفحه | اقدام | تخمین |
+|---|-----|-------|------|-------|-------|
+| F8 | `GetInventorySummary` | BackOffice | InventoryMainPage.razor | کارت خلاصه بالای صفحه (تعداد کل + ارزش ریالی) | ۳ ساعت |
+| F9 | `GetStockValueReport` | BackOffice | InventoryMainPage.razor | تب «گزارش ارزش» + دانلود Excel | ۴ ساعت |
+| F10 | `BulkAddStock` | BackOffice | InventoryMainPage.razor | دکمه «افزودن دسته‌ای» + آپلود CSV/فرم چندتایی | ۶ ساعت |
+| F11 | `BulkUpdateProductStock` | BackOffice | InventoryMainPage.razor | دکمه «بروزرسانی دسته‌ای» (Set/Add/Subtract) | ۶ ساعت |
+| F12 | `GetConfigurationByKey` | Internal | — | بدون UI — استفاده داخلی بهینه بجای GetAll | ۰ |
+
+---
+
+## 📐 نقشه پیاده‌سازی
+
+### فاز A — همراه پکیج‌بیس (فاز ۴ BIZ-PACKAGE-BASED-SYSTEM)
+
+```
+F1 (AssignFeatureToMembership) → با T4.6 (ماتریس PackageFeature) ادغام
+F2 (ChangeNetworkParent) ✅ تکمیل → BO:`e020354`
+F3 (CalculateOrderPV) ✅ تکمیل → FO:`3bffc13`
+```
+
+### فاز B — بعد از پکیج‌بیس (Sprint بعدی)
+
+```
+F4 → F7: بهبود UX فروشگاه و مشتری
+تخمین: ۱۳ ساعت = ~۲ روز
+```
+
+### فاز C — آینده (بدون فوریت)
+
+```
+F8 → F12: گزارش‌دهی و عملیات انبوه
+تخمین: ۱۹ ساعت = ~۳ روز
+```
+
+---
+
+## 🔗 ارجاعات
+
+| مستند | محتوا |
+|-------|-------|
+| [GRPC-SERVICES-AUDIT.md](../cms/GRPC-SERVICES-AUDIT.md) | آدیت کامل ۳۴۲ RPC — ۱۲ نگهداری + ۱۲ آرشیو |
+| [BIZ-PACKAGE-BASED-SYSTEM.md](../business/BIZ-PACKAGE-BASED-SYSTEM.md) | طراحی سیستم پکیج‌بیس — ۳۹ تغییر |
+
+---
+
+*آخرین بروزرسانی: ۱۴۰۴/۱۲/۱۰ — F2+F3 تکمیل | باقی‌مانده فاز A: F1*

roadmap/MAGIC-WALLET-PLAN.md

@@ -0,0 +1,225 @@
+# 🪄 پلن پیاده‌سازی کیف‌پول جادویی
+
+> **مرجع:** [MAGIC-WALLET-SPEC](./MAGIC-WALLET-SPEC.md)  
+> **تخمین کل:** ~۷ روز کاری  
+> **وضعیت:** ✅ کامل — همه ۶ فاز پیاده‌سازی و مرج شده  
+> **وابستگی مستقل:** تکمیل ChargeDiscountWallet (ربطی به جادویی ندارد) ✅
+
+---
+
+## فازبندی
+
+### فاز ۱ — مدل داده و Migration (روز ۱)
+
+**هدف:** زیرساخت دیتابیس و enum‌ها
+
+```
+فایل‌های تغییری:
+├── UserWallet.cs                    → + WalletMode, MagicTotalDeposited, MagicTotalCredited, MagicActivatedAt, MagicCompletedAt
+├── WalletMode.cs                    → enum جدید (Normal=0, Magic=1)
+├── TransactionType.cs               → + MagicWalletDeposit=14, MagicWalletBonus=15
+├── SystemConstants.cs               → + MagicWalletMultiplier, MagicWalletMaxDeposit, MagicWalletMaxCredit
+├── UserWalletConfiguration.cs       → EF config برای فیلدهای جدید
+├── ClubMembershipCycle.cs           → 🆕 entity جدید (حل مشکل تاریخ کمیسیون)
+├── ClubMembershipCycleConfiguration.cs → EF config
+├── Migration: AddMagicWalletFields  → dotnet ef migrations add
+└── Migration: AddClubMembershipCycle → dotnet ef migrations add + data seed
+```
+
+**تست:** Migration اجرا بشه، فیلدها در DB ایجاد بشن، default‌ها درست باشن. هر ClubMembership موجود یه رکورد Cycle=1 داشته باشه.
+
+---
+
+### فاز ۲ — Trigger ورود/خروج Magic (روز ۲)
+
+**هدف:** State Machine خودکار
+
+```
+فایل‌های تغییری:
+├── SubmitShopBuyOrderCommandHandler.cs
+│   ├── بعد از کسر Balance: check ورود به Magic
+│   └── بعد از کسر Balance: check خروج از Magic
+│
+├── ActivateClubMembershipCommandHandler.cs
+│   ├── ActivatedAt فقط بار اول ست بشه (دیگه overwrite نشه)
+│   └── هر بار یک ClubMembershipCycle جدید اضافه بشه
+│
+├── (Optional) Domain Event: WalletModeChangedEvent
+│   └── برای لاگ و نوتیفیکیشن
+│
+└── User.cs (یا UserWallet)
+    └── + PurchaseCycleCount (int) — تعداد دور خرید پکیج
+```
+
+**تست:** 
+- سناریو ۱: Balance=0 بعد از خرید → WalletMode=Magic ✅
+- سناریو ۲: بدون پکیج + Balance=0 → نباید Magic بشه ❌
+- سناریو ۳: Magic + Balance=0 + **TotalDeposited=50M** (سقف پر نشده) → **هنوز Magic!** نباید خارج بشه ❌
+- سناریو ۴: Magic + Balance=0 + **TotalDeposited=100M** (سقف پر) → خروج ✅
+- سناریو ۵: Magic + Balance=30M + TotalDeposited=100M → **هنوز Magic!** (بالانس داره) ❌
+- سناریو ۶: خروج از Magic → خرید مجدد پکیج → Balance=0 → Magic مجدد با **سقف ریست‌شده** ✅
+- سناریو ۷: دور دوم → TotalDeposited, TotalCredited = 0 (ریست) ✅
+
+---
+
+### فاز ۳ — API شارژ جادویی (روز ۳-۴)
+
+**هدف:** مسیر کامل شارژ از درگاه با ضریب ×2.5
+
+```
+فایل‌های جدید:
+├── InitiateMagicChargeCommand.cs
+├── InitiateMagicChargeCommandHandler.cs
+├── InitiateMagicChargeCommandValidator.cs
+├── VerifyMagicChargeCommand.cs
+├── VerifyMagicChargeCommandHandler.cs
+├── MagicWalletController.cs          → GET /api/wallet/verify-magic-charge
+│
+├── userwallet.proto                  → + InitiateMagicCharge, GetMagicWalletStatus RPCs
+└── UserWalletService.cs              → implement new RPCs
+
+نکات مهم:
+├── هر شارژ = ۲ تراکنش (Deposit + Bonus)
+├── هر شارژ = ۱ WalletChangeLog (اجباری)
+├── Validation: WalletMode==Magic && TotalDeposited+Amount <= Cap
+└── Callback: /api/wallet/verify-magic-charge → redirect FrontOffice
+```
+
+**تست:**
+- واریز 10M → Balance += 25M, TotalDeposited += 10M ✅
+- واریز بیشتر از سقف → خطا ❌
+- واریز در Normal Mode → خطا ❌
+- ۲ تراکنش + ۱ لاگ ثبت شده ✅
+
+---
+
+### فاز ۴ — غیرفعال‌سازی کمیسیون + تاریخ Cycle (روز ۴.۵)
+
+**هدف:** کاربرهای Magic از کمیسیون خارج بشن + تاریخ کمیسیون از Cycle بخونه
+
+```
+فایل‌های تغییری:
+├── CalculateWeeklyBalancesCommandHandler.cs
+│   ├── فیلتر: WHERE wallet.WalletMode != Magic
+│   └── تاریخ: ActivatedAt → ClubMembershipCycle.PackagePurchasedAt
+│
+├── sp_CalculateWeeklyBalances.sql
+│   ├── + JOIN UserWallets WHERE WalletMode = 0
+│   └── WHERE cm.ActivatedAt → cc.PackagePurchasedAt (AND cc.IsCurrentCycle = 1)
+│
+└── WeekRepository (اگه date range query داره)
+    └── آپدیت query
+```
+
+**تست:** 
+- کاربر Magic در محاسبات هفتگی شرکت نکنه ✅
+- کاربر دور ۲ (پکیج مجدد): با تاریخ PackagePurchasedAt جدید امتیاز بگیره ✅
+- تاریخ اصلی ActivatedAt تغییر نکرده باشه ✅
+
+---
+
+### فاز ۵ — صفحات FrontOffice (روز ۵-۶)
+
+**هدف:** UI شارژ جادویی + نمایش وضعیت
+
+```
+فایل‌های جدید:
+├── Pages/Profile/MagicWallet.razor           → فرم شارژ + پروگرس‌بار سقف
+├── Pages/Profile/MagicWallet.razor.cs        → code-behind
+├── Pages/Profile/MagicPaymentCallback.razor  → نتیجه پرداخت
+└── Pages/Profile/MagicPaymentCallback.razor.cs
+
+فایل‌های تغییری:
+├── WalletService.cs                → + InitiateMagicChargeAsync, GetMagicWalletStatusAsync
+├── RouteConstants.cs               → + MagicWallet, MagicPaymentCallback
+├── Pages/Profile/Index.razor       → بنر Magic Mode
+├── Pages/Profile/Wallet.razor      → پروگرس سقف + لینک شارژ
+└── NavMenu / Sidebar               → لینک شرطی به صفحه جادویی
+```
+
+**UI شارژ جادویی:**
+```
+┌──────────────────────────────────────────────┐
+│  🪄 کیف‌پول جادویی                           │
+│                                              │
+│  وضعیت: فعال ✅                               │
+│  مجموع واریزی: 30M / 100M تومان              │
+│  ██████████░░░░░░░░░░░░░░░░░░░░  30%         │
+│  مجموع اعتبار دریافتی: 75M تومان             │
+│                                              │
+│  ┌──────────────────────────────────────┐    │
+│  │  مبلغ واریز: [________] تومان        │    │
+│  │  اعتبار دریافتی: 0 × 2.5 = 0 تومان  │    │
+│  │  باقیمانده سقف: 70M تومان            │    │
+│  │                                      │    │
+│  │  [ 🔒 پرداخت از درگاه ]              │    │
+│  └──────────────────────────────────────┘    │
+└──────────────────────────────────────────────┘
+```
+
+---
+
+### فاز ۶ — محدودیت خرید مجدد پکیج (روز ۷)
+
+**هدف:** بعد از Magic فقط IPG مجاز باشه
+
+```
+فایل‌های تغییری:
+├── CheckAndProcessDayaLoansCommandHandler.cs
+│   └── if PurchaseCycleCount > 0 → reject
+│
+├── Package Purchase UI (FrontOffice)
+│   └── if PurchaseCycleCount > 0 → hide Daya button
+│
+└── ActivateClubMembershipCommandHandler.cs
+    └── if WalletMode == Magic → "ابتدا جادویی تمام شود"
+```
+
+---
+
+## Checklist پیاده‌سازی
+
+- [x] **فاز ۱:** WalletMode enum
+- [x] **فاز ۱:** UserWallet entity + 5 فیلد جدید
+- [x] **فاز ۱:** ClubMembershipCycle entity (جدید)
+- [x] **فاز ۱:** TransactionType + 2 مقدار
+- [x] **فاز ۱:** SystemConstants + 3 ثابت
+- [x] **فاز ۱:** EF Configuration (UserWallet + ClubMembershipCycle)
+- [x] **فاز ۱:** Migration: AddMagicWalletFields (u21 — اعمال شده ✅)
+- [x] **فاز ۱:** Migration: AddClubMembershipCycle + data seed (74 رکورد seed شده ✅)
+- [x] **فاز ۲:** Trigger ورود Magic (SubmitShopBuyOrder)
+- [x] **فاز ۲:** Trigger خروج Magic
+- [x] **فاز ۲:** ActivateClubMembership → ActivatedAt نگه‌داشته بشه + Cycle جدید
+- [x] **فاز ۲:** PurchaseCycleCount
+- [x] **فاز ۳:** InitiateMagicChargeCommand + Handler
+- [x] **فاز ۳:** VerifyMagicChargeCommand + Handler
+- [x] **فاز ۳:** MagicWalletController (HTTP callback)
+- [x] **فاز ۳:** gRPC Proto + Service
+- [x] **فاز ۳:** ۲ تراکنش + ۱ لاگ (اجباری)
+- [x] **فاز ۴:** فیلتر کمیسیون Magic (C# handler + SP)
+- [x] **فاز ۴:** تاریخ کمیسیون: ActivatedAt → Cycle.PackagePurchasedAt (C# + SP)
+- [x] **فاز ۵:** MagicWallet.razor
+- [x] **فاز ۵:** MagicPaymentCallback — نتیجه پرداخت از طریق ?payment= query param در همان MagicWallet.razor هندل میشه
+- [x] **فاز ۵:** WalletService gRPC client
+- [x] **فاز ۵:** Profile + Wallet page updates
+- [x] **فاز ۶:** Daya restriction (CheckAndProcessDayaLoansCommandHandler + FO Purchase UI)
+- [x] **فاز ۶:** Club activation restriction (ActivateClubMembershipCommandHandler + WalletMode guard)
+
+---
+
+## وابستگی مستقل: تکمیل ChargeDiscountWallet ✅
+
+> ✅ **تکمیل شد** — مستقل از کیف‌پول جادویی پیاده‌سازی شد.
+
+```
+انجام شده:
+├── ChargeDiscountWalletCommandHandler — CQRS handler ✅
+├── VerifyDiscountWalletChargeCommandHandler — ✅
+├── PaymentCallbackController → GET /api/wallet/verify-discount-charge ✅
+├── userwallet.proto → rpc InitiateDiscountCharge ✅
+├── UserWalletService.cs → InitiateDiscountCharge override ✅
+├── WalletService.cs (FO) → InitiateDiscountChargeAsync ✅
+├── ChargeDiscountWallet.razor + .razor.cs (FO) ✅
+├── RouteConstants → ChargeDiscountWallet ✅
+└── Wallet.razor → دکمه شارژ اعتباری ✅
+```

roadmap/MAGIC-WALLET-SPEC.md

@@ -0,0 +1,600 @@
+# 🪄 کیف‌پول جادویی (Magic Wallet)
+
+> **وضعیت:** طراحی — آماده پیاده‌سازی  
+> **تاریخ:** اسفند ۱۴۰۴  
+> **وابستگی:** خرید پکیج پایه، فروشگاه عادی، سیستم کمیسیون
+
+---
+
+## ۱. خلاصه بیزینسی
+
+کاربر بعد از خرید پکیج پایه (۵۶M) و خرج کردن کامل Balance از فروشگاه عادی، وارد **حالت جادویی** می‌شه. در این حالت می‌تونه کیف‌پولش رو از درگاه شارژ کنه و **۲.۵ برابر** اعتبار بگیره — بدون هیچ کمیسیون یا پورسانتی.
+
+> ⚠️ **سقف ۱۰۰M ورودی / ۲۵۰M خروجی per-cycle هست** — هر بار که کاربر دوباره پکیج ۵۶M بخره و وارد Magic بشه، سقف ریست میشه. این چرخه تا بی‌نهایت تکرار میشه.
+
+```mermaid
+stateDiagram-v2
+    [*] --> NewUser: ثبت‌نام
+    NewUser --> Normal: خرید پکیج 56M\n(IPG یا دایا)
+    Normal --> Magic: Balance = 0\n(همه رو خرج کرد)
+    Magic --> PostMagic: Balance = 0\n(250M رو خرج کرد)
+    PostMagic --> Normal: خرید مجدد پکیج 56M\n(فقط IPG — دایا ❌)
+    Normal --> Magic: Balance = 0\n(دوباره خرج کرد)
+
+    state Normal {
+        [*] --> خرید_عادی
+        خرید_عادی: Balance -= مبلغ خرید
+        خرید_عادی --> کمیسیون_فعال
+        کمیسیون_فعال: ✅ پورسانت + 25.2M Pool
+    }
+
+    state Magic {
+        [*] --> شارژ_جادویی
+        شارژ_جادویی: واریز × 2.5 = اعتبار
+        شارژ_جادویی --> خرید_با_اعتبار
+        خرید_با_اعتبار: Balance -= مبلغ خرید
+        خرید_با_اعتبار --> بدون_کمیسیون
+        بدون_کمیسیون: ❌ هیچ پورسانتی آزاد نمیشه
+    }
+```
+
+---
+
+## ۲. چرخه کامل کیف‌پول
+
+### فاز ۱ — خرید پکیج (Normal Mode)
+
+| مرحله | عملیات | نتیجه |
+|--------|---------|--------|
+| ۱ | کاربر پکیج ۵۶M می‌خره (IPG یا دایا) | `Balance += 56M`, `DiscountBalance += 112M` |
+| ۲ | فعال‌سازی باشگاه | `25.2M → Pool`, فیچرها باز میشه |
+| ۳ | کمیسیون هفتگی | `NetworkBalance += سهم` ✅ |
+| ۴ | خرید از فروشگاه عادی | `Balance -= مبلغ` |
+| ۵ | Balance = 0 | **→ ورود به Magic Mode** |
+
+### فاز ۲ — کیف‌پول جادویی (Magic Mode)
+
+| مرحله | عملیات | نتیجه |
+|--------|---------|--------|
+| ۱ | کاربر از صفحه شارژ جادویی مبلغ واریز میکنه | درگاه ZarinPal |
+| ۲ | تراکنش واریز ثبت میشه (مبلغ اصلی) | `Transaction(MagicDeposit, 10M)` |
+| ۳ | اعتبار ×2.5 به Balance اضافه میشه | `Balance += 25M` |
+| ۴ | تراکنش بونوس ثبت میشه | `Transaction(MagicBonus, 15M)` |
+| ۵ | لاگ کیف‌پول ثبت میشه | `WalletChangeLog` ✅ (اجباری) |
+| ۶ | MagicTotalDeposited += مبلغ واریزی | ترک سقف |
+| ۷ | خرید از فروشگاه عادی | `Balance -= مبلغ` |
+| ۸ | Balance = 0 و سقف پر شده | **→ خروج از Magic Mode** |
+
+### فاز ۳ — بازگشت (Post-Magic)
+
+| مرحله | عملیات | نتیجه |
+|--------|---------|--------|
+| ۱ | کیف‌پول جادویی تمام شد | `WalletMode = Normal` |
+| ۲ | برای ادامه باید دوباره پکیج ۵۶M بخره | **فقط IPG** (دایا ❌) |
+| ۳ | خرید مجدد پکیج | `Balance += 56M`, `DiscountBalance += 112M` |
+| ۴ | همه آپشن‌ها دوباره فعال | کمیسیون ✅, Pool ✅ |
+| ۵ | دوباره Balance = 0 بشه | **→ Magic Mode مجدد** |
+
+---
+
+## ۳. قوانین Magic Mode
+
+### ۳.۱ ضریب و سقف (per-cycle)
+
+| پارامتر | مقدار | ثابت پیشنهادی | اسکوپ |
+|----------|-------|---------------|--------|
+| ضریب شارژ | **×2.5** | `MagicWalletMultiplier = 2.5m` | — |
+| سقف ورودی | **100M تومان** (1B ریال) | `MagicWalletMaxDeposit = 1_000_000_000` | **هر دور** |
+| سقف خروجی | **250M تومان** (2.5B ریال) | `MagicWalletMaxCredit = 2_500_000_000` | **هر دور** |
+| سود کاربر | **150%** | — | — |
+
+> 🔄 **سقف per-cycle هست نه lifetime.** هر بار که کاربر از Magic خارج بشه و دوباره پکیج ۵۶M بخره،
+> `MagicTotalDeposited` و `MagicTotalCredited` به **صفر ریست** میشن و یه دور جدید شروع میشه.
+
+### ۳.۲ مثال عددی (یک شارژ)
+
+```
+واریز: 10,000,000 تومان (100M ریال)
+  ├── تراکنش واریز:    10,000,000 تومان   (Transaction: MagicDeposit)
+  ├── بونوس داخلی:     15,000,000 تومان   (Transaction: MagicBonus)  
+  ├── اعتبار نهایی:    25,000,000 تومان   (Balance += 250M ریال)
+  └── WalletChangeLog:  BalanceChange = +250,000,000 ریال ✅
+
+سقف (این دور):
+  ├── مجموع واریزی:    MagicTotalDeposited += 100,000,000 ریال
+  ├── مجموع اعتبار:    MagicTotalCredited  += 250,000,000 ریال  
+  └── باقیمانده سقف:    MaxDeposit - TotalDeposited
+```
+
+### ۳.۳ مثال چند دوری (چرخه تکرار)
+
+```
+══════════════════════════════════════════════════════════════
+  دور ۱ (اولین بار)
+══════════════════════════════════════════════════════════════
+  ① خرید پکیج 56M (IPG یا دایا) → Balance=56M, Discount=112M
+  ② فعال‌سازی باشگاه → کمیسیون ✅
+  ③ خرید از فروشگاه عادی → Balance کم میشه...
+  ④ Balance = 0 → 🪄 Magic Mode فعال!
+     MagicTotalDeposited = 0 (ریست)
+  ⑤ شارژ جادویی: مجموعاً 100M واریز → 250M اعتبار
+  ⑥ خرید از فروشگاه عادی → Balance کم میشه...
+  ⑦ Balance = 0 → خروج از Magic → Normal Mode
+
+══════════════════════════════════════════════════════════════
+  دور ۲ (خرید مجدد پکیج — فقط IPG، دایا ❌)
+══════════════════════════════════════════════════════════════
+  ① خرید پکیج 56M (فقط IPG) → Balance=56M, Discount=112M
+  ② کمیسیون دوباره فعال ✅
+  ③ خرید از فروشگاه عادی → Balance کم میشه...
+  ④ Balance = 0 → 🪄 Magic Mode فعال!
+     MagicTotalDeposited = 0 (ریست)
+                          ─────────
+  ⑤ شارژ جادویی: مجموعاً 100M واریز → 250M اعتبار
+  ⑥ خرید → Balance = 0 → خروج از Magic
+
+══════════════════════════════════════════════════════════════
+  دور ۳, ۴, ۵, ... (تا بی‌نهایت — همین چرخه تکرار)
+══════════════════════════════════════════════════════════════
+```
+
+### ۳.۴ چه چیزهایی غیرفعال میشه
+
+| قابلیت | Normal Mode | Magic Mode |
+|--------|-------------|------------|
+| خرید از فروشگاه عادی | ✅ | ✅ |
+| خرید از فروشگاه اعتباری | ✅ | ✅ (DiscountBalance قبلی) |
+| کمیسیون هفتگی | ✅ | ❌ |
+| پورسانت ۲۵.۲M | ✅ | ❌ |
+| شارژ جادویی ×2.5 | ❌ | ✅ |
+| خرید مجدد پکیج | ✅ | ❌ |
+
+---
+
+## ۴. شرایط ورود و خروج
+
+### ۴.۱ ورود به Magic Mode
+
+```
+شرط‌ها (همه باید true باشن):
+  ├── wallet.Balance == 0                       (کیف‌پول خالی شد)
+  ├── user.PackagePurchaseMethod != None         (قبلاً پکیج خریده)
+  ├── wallet.WalletMode == Normal                (الان عادیه)
+  └── user.ClubMembership.IsActive == true       (باشگاه فعاله)
+
+نتیجه:
+  ├── wallet.WalletMode = Magic
+  ├── wallet.MagicActivatedAt = DateTime.UtcNow
+  ├── wallet.MagicTotalDeposited = 0
+  └── wallet.MagicTotalCredited = 0
+```
+
+### ۴.۲ خروج از Magic Mode
+
+```
+شرط‌ها (هر دو باید همزمان true باشن):
+  ├── wallet.Balance == 0                              (همه رو خرج کرده)
+  └── wallet.MagicTotalDeposited >= MagicWalletMaxDeposit  (سقف 100M پر شده)
+
+نتیجه:
+  ├── wallet.WalletMode = Normal
+  ├── wallet.MagicCompletedAt = DateTime.UtcNow
+  └── user.PurchaseCycleCount++
+
+⚠️ توضیح مهم:
+  اگه Balance=0 بشه ولی هنوز سقف شارژ پر نشده → هنوز Magic هست!
+  کاربر میتونه دوباره شارژ کنه (تا سقف 100M).
+  
+  مثال:
+    TotalDeposited = 50M, Balance = 0
+    → هنوز Magic → میتونه 50M دیگه شارژ کنه (125M اعتبار بگیره)
+    
+    TotalDeposited = 100M, Balance = 30M
+    → هنوز Magic → نمیتونه شارژ کنه ولی هنوز بالانس داره
+    
+    TotalDeposited = 100M, Balance = 0
+    → ✅ خروج از Magic → Normal Mode
+```
+
+### ۴.۳ ریست سقف در دور بعدی
+
+```
+وقتی کاربر دوباره پکیج ۵۶M بخره و Balance=0 بشه → Magic Mode:
+  ├── MagicTotalDeposited = 0    ← ریست!
+  ├── MagicTotalCredited = 0     ← ریست!
+  ├── MagicActivatedAt = now     ← زمان جدید
+  └── MagicCompletedAt = null    ← پاک میشه
+
+⚠️ سقف per-cycle هست:
+  ├── هر دور: حداکثر 100M واریز → 250M اعتبار
+  ├── تعداد دور: بی‌نهایت (تا وقتی پکیج بخره)
+  └── PurchaseCycleCount: فقط برای ترک تعداد دورها (محدودیت نداره)
+```
+
+---
+
+## ۵. تراکنش‌ها و لاگ
+
+### ۵.۱ انواع تراکنش جدید
+
+| TransactionType | کد | توضیح |
+|-----------------|-----|--------|
+| `MagicWalletDeposit` | 14 | واریز اصلی از درگاه (مبلغ واقعی) |
+| `MagicWalletBonus` | 15 | بونوس داخلی (مبلغ × 1.5) |
+
+### ۵.۲ لاگ کیف‌پول (اجباری)
+
+هر شارژ جادویی **باید** یک رکورد `UserWalletChangeLog` ایجاد کنه:
+
+```
+UserWalletChangeLog:
+  ├── UserWalletId          = wallet.Id
+  ├── CurrentBalance        = wallet.Balance (بعد از تغییر)
+  ├── BalanceChange          = creditAmount (مبلغ × 2.5)
+  ├── IsIncrement            = true
+  ├── ReferenceId            = transaction.Id
+  ├── CurrentDiscountBalance = wallet.DiscountBalance (بدون تغییر)
+  ├── DiscountBalanceChange  = 0
+  ├── CurrentNetworkBalance  = wallet.NetworkBalance (بدون تغییر)
+  └── NetworkBalanceChange   = 0
+```
+
+> ⚠️ **لاگ کیف‌پول دلخواه نیست — اجباریه.** هر تغییر Balance باید لاگ بخوره.
+
+---
+
+## ۶. مسیر شارژ جادویی (API)
+
+### ۶.۱ فلوی کامل
+
+```mermaid
+sequenceDiagram
+    participant U as کاربر
+    participant FO as FrontOffice
+    participant CMS as CMS (gRPC)
+    participant PYMS as PYMS
+    participant ZP as ZarinPal
+
+    U->>FO: مبلغ واریز (مثلاً 10M)
+    FO->>CMS: InitiateMagicCharge(userId, amount)
+    
+    Note over CMS: Validations:<br/>WalletMode == Magic<br/>TotalDeposited + amount <= 100M
+
+    CMS->>PYMS: CreatePaymentRequest(amount)
+    PYMS->>ZP: Request Authority
+    ZP-->>PYMS: Authority
+    PYMS-->>CMS: PaymentUrl
+    CMS-->>FO: PaymentUrl
+    FO->>U: Redirect to ZarinPal
+
+    U->>ZP: پرداخت
+    ZP->>CMS: Callback /api/wallet/verify-magic-charge
+
+    Note over CMS: creditAmount = amount × 2.5<br/>bonusAmount = amount × 1.5
+
+    CMS->>CMS: Balance += creditAmount
+    CMS->>CMS: Transaction #1 (MagicDeposit, amount)
+    CMS->>CMS: Transaction #2 (MagicBonus, bonusAmount)
+    CMS->>CMS: WalletChangeLog ✅
+    CMS->>CMS: MagicTotalDeposited += amount
+
+    CMS-->>FO: Redirect to callback page
+    FO->>U: نتیجه + بالانس جدید
+```
+
+### ۶.۲ تفاوت با ChargeDiscountWallet
+
+| ویژگی | ChargeDiscountWallet | MagicCharge |
+|--------|---------------------|-------------|
+| **هدف** | شارژ DiscountBalance | شارژ Balance (جادویی) |
+| **ضریب** | ×1 (مبلغ واقعی) | ×2.5 |
+| **سقف** | ندارد | 100M تومان ورودی |
+| **شرط** | همیشه فعال | فقط WalletMode == Magic |
+| **کمیسیون** | — | ❌ غیرفعال |
+| **Callback** | `/api/wallet/verify-discount-charge` | `/api/wallet/verify-magic-charge` |
+| **وضعیت** | ⚠️ نیمه‌کاره (controller ندارد) | 🆕 باید ساخته بشه |
+
+> ⚠️ **ChargeDiscountWallet ناقصه و باید مستقل کامل بشه — ربطی به کیف‌پول جادویی نداره.**
+
+---
+
+## ۷. تغییرات مدل داده
+
+### ۷.۱ UserWallet — فیلدهای جدید
+
+```csharp
+// اضافه به UserWallet entity:
+public WalletMode WalletMode { get; set; } = WalletMode.Normal;
+public long MagicTotalDeposited { get; set; }    // مجموع واریزی واقعی (ریال)
+public long MagicTotalCredited { get; set; }     // مجموع اعتبار داده‌شده (ریال)  
+public DateTime? MagicActivatedAt { get; set; }
+public DateTime? MagicCompletedAt { get; set; }
+```
+
+### ۷.۲ WalletMode enum (جدید)
+
+```csharp
+public enum WalletMode
+{
+    Normal = 0,    // حالت عادی — کمیسیون فعال
+    Magic = 1      // حالت جادویی — شارژ ×2.5، بدون کمیسیون
+}
+```
+
+### ۷.۳ TransactionType — مقادیر جدید
+
+```csharp
+// اضافه به TransactionType enum:
+MagicWalletDeposit = 14,    // واریز از درگاه (مبلغ واقعی)
+MagicWalletBonus = 15       // بونوس داخلی (مبلغ × 1.5)
+```
+
+### ۷.۴ SystemConstants — ثابت‌های جدید
+
+```csharp
+public const decimal MagicWalletMultiplier = 2.5m;
+public const long MagicWalletMaxDeposit = 1_000_000_000;   // 100M تومان = 1B ریال
+public const long MagicWalletMaxCredit = 2_500_000_000;    // 250M تومان = 2.5B ریال
+```
+
+### ۷.۵ ClubMembershipCycle — جدول جدید (حل مشکل تاریخ کمیسیون)
+
+#### مشکل فعلی
+
+```
+⚠️ الان محاسبه کمیسیون هفتگی از ClubMembership.ActivatedAt استفاده میکنه:
+
+   WHERE cm.ActivatedAt >= @StartDate AND cm.ActivatedAt <= @EndDate
+
+وقتی کاربر دور دوم پکیج بخره، ActivateClubMembership این تاریخ رو overwrite میکنه:
+   entity.ActivatedAt = DateTime.Now;  // ← تاریخ اصلی از بین میره!
+
+مشکل: تاریخ اولین فعال‌سازی باشگاه از دست میره.
+```
+
+#### راه‌حل: جدول `ClubMembershipCycle`
+
+به‌جای آپدیت کردن `ActivatedAt`، هر بار که پکیج خریده میشه یک رکورد جدید در جدول `ClubMembershipCycle` ایجاد میشه. محاسبه کمیسیون از این جدول استفاده میکنه.
+
+```csharp
+// Entity جدید:
+public class ClubMembershipCycle : BaseAuditableEntity
+{
+    public long UserId { get; set; }
+    public User User { get; set; }
+    public long ClubMembershipId { get; set; }
+    public ClubMembership ClubMembership { get; set; }
+    public int CycleNumber { get; set; }                // شماره دور (1, 2, 3...)
+    public DateTime PackagePurchasedAt { get; set; }     // تاریخ خرید پکیج
+    public DateTime? MagicStartedAt { get; set; }        // شروع Magic (Balance=0)
+    public DateTime? MagicCompletedAt { get; set; }      // پایان Magic
+    public PackagePurchaseMethod PurchaseMethod { get; set; } // IPG یا Daya
+    public long PackageAmount { get; set; }               // 56M
+    public bool IsCurrentCycle { get; set; }              // فقط یکی true
+}
+```
+
+#### تغییرات در منطق کمیسیون
+
+```sql
+-- قبل (غلط — ActivatedAt از بین میره):
+WHERE cm.ActivatedAt >= @StartDate AND cm.ActivatedAt <= @EndDate
+
+-- بعد (درست — از جدول Cycle):
+WHERE cc.PackagePurchasedAt >= @StartDate 
+  AND cc.PackagePurchasedAt <= @EndDate
+  AND cc.IsCurrentCycle = 1
+```
+
+#### ClubMembership — بدون تغییر ساختاری
+
+```
+ClubMembership:
+  ├── ActivatedAt          → تاریخ اولین فعال‌سازی (هرگز overwrite نمیشه ✅)
+  ├── IsActive             → وضعیت فعلی باشگاه
+  └── + Cycles (nav prop)  → لیست دورها
+```
+
+#### مثال عملی
+
+```
+ClubMembership #42:
+  UserId = 100
+  ActivatedAt = 1403/10/15      ← اولین بار (حفظ میشه ✅)
+  IsActive = true
+
+ClubMembershipCycles:
+  ┌────┬──────┬───────────────────┬──────────────┬─────────────┐
+  │ Id │ Cycle│ PackagePurchasedAt│ PurchaseMethod│IsCurrentCycle│
+  ├────┼──────┼───────────────────┼──────────────┼─────────────┤
+  │  1 │   1  │ 1403/10/15        │ DayaLoan     │ false       │
+  │  2 │   2  │ 1404/01/20        │ DirectIPG    │ false       │
+  │  3 │   3  │ 1404/04/05        │ DirectIPG    │ true ✅     │
+  └────┴──────┴───────────────────┴──────────────┴─────────────┘
+
+→ کمیسیون هفته 1404/04/05 تا 1404/04/11:
+  PackagePurchasedAt (دور ۳) = 1404/04/05 → ✅ در بازه هست → امتیاز میگیره
+→ تاریخ اولین فعال‌سازی: 1403/10/15 → حفظ شده ✅
+```
+
+### ۷.۶ EF Migration
+
+```
+Migration: AddMagicWalletFields
+  ├── ALTER TABLE UserWallets ADD WalletMode int NOT NULL DEFAULT 0
+  ├── ALTER TABLE UserWallets ADD MagicTotalDeposited bigint NOT NULL DEFAULT 0
+  ├── ALTER TABLE UserWallets ADD MagicTotalCredited bigint NOT NULL DEFAULT 0
+  ├── ALTER TABLE UserWallets ADD MagicActivatedAt datetime2 NULL
+  └── ALTER TABLE UserWallets ADD MagicCompletedAt datetime2 NULL
+
+Migration: AddClubMembershipCycle
+  ├── CREATE TABLE ClubMembershipCycles (
+  │     Id bigint IDENTITY PRIMARY KEY,
+  │     UserId bigint NOT NULL FK → Users,
+  │     ClubMembershipId bigint NOT NULL FK → ClubMemberships,
+  │     CycleNumber int NOT NULL,
+  │     PackagePurchasedAt datetime2 NOT NULL,
+  │     MagicStartedAt datetime2 NULL,
+  │     MagicCompletedAt datetime2 NULL,
+  │     PurchaseMethod int NOT NULL,
+  │     PackageAmount bigint NOT NULL,
+  │     IsCurrentCycle bit NOT NULL DEFAULT 0,
+  │     + BaseAuditableEntity fields
+  │   )
+  └── Data Migration: INSERT یک رکورد Cycle=1 برای هر ClubMembership موجود
+      (PackagePurchasedAt = ClubMembership.ActivatedAt)
+```
+
+---
+
+## ۸. تغییرات Handler‌ها
+
+### ۸.۱ SubmitShopBuyOrderCommandHandler (تغییر)
+
+```
+بعد از کسر Balance:
+  if (wallet.Balance == 0 
+      && user.PackagePurchaseMethod != None
+      && wallet.WalletMode == Normal
+      && user.ClubMembership?.IsActive == true)
+  {
+      → ورود به Magic Mode
+  }
+
+  if (wallet.WalletMode == Magic 
+      && wallet.Balance == 0 
+      && wallet.MagicTotalDeposited >= SystemConstants.MagicWalletMaxDeposit)
+  {
+      → خروج از Magic Mode
+      // سقف 100M پر شده + همه رو خرج کرده
+  }
+  // ⚠️ اگه Balance=0 ولی سقف پر نشده → هنوز Magic!
+  // کاربر میتونه دوباره شارژ کنه
+```
+
+### ۸.۲ CalculateWeeklyBalancesCommandHandler (تغییر)
+
+```
+تغییر ۱ — فیلتر Magic:
+  فقط کاربرهایی که wallet.WalletMode == Normal
+  (کاربرهای Magic از محاسبه کمیسیون خارج میشن)
+
+تغییر ۲ — تاریخ از Cycle (به‌جای ActivatedAt):
+  قبل:
+    WHERE cm.ActivatedAt >= @StartDate AND cm.ActivatedAt <= @EndDate
+  
+  بعد:
+    WHERE cc.PackagePurchasedAt >= @StartDate 
+      AND cc.PackagePurchasedAt <= @EndDate
+      AND cc.IsCurrentCycle = 1
+    
+  (هم در C# handler و هم در SP باید تغییر کنه)
+```
+
+### ۸.۳ ActivateClubMembershipCommandHandler (تغییر مهم)
+
+```
+قبل (غلط — تاریخ overwrite میشه):
+  entity.ActivatedAt = DateTime.Now;
+
+بعد (درست):
+  // ActivatedAt فقط بار اول ست میشه:
+  if (entity.ActivatedAt == default)
+      entity.ActivatedAt = DateTime.Now;
+  
+  // هر بار یه Cycle جدید:
+  var previousCycle = entity.Cycles.FirstOrDefault(c => c.IsCurrentCycle);
+  if (previousCycle != null)
+      previousCycle.IsCurrentCycle = false;
+  
+  entity.Cycles.Add(new ClubMembershipCycle
+  {
+      CycleNumber = (previousCycle?.CycleNumber ?? 0) + 1,
+      PackagePurchasedAt = DateTime.Now,
+      PurchaseMethod = user.PackagePurchaseMethod,
+      PackageAmount = SystemConstants.BasePackageAmount,
+      IsCurrentCycle = true
+  });
+```
+
+### ۸.۴ CheckAndProcessDayaLoansCommandHandler (تغییر)
+
+```
+Validation اضافه:
+  if (user.PurchaseCycleCount > 0)
+      → reject: "وام دایا فقط برای خرید اولین پکیج"
+```
+
+### ۸.۵ InitiateMagicChargeCommandHandler (جدید)
+
+```
+Input: UserId, Amount
+Validations:
+  ├── wallet.WalletMode == Magic
+  ├── Amount > 0
+  └── MagicTotalDeposited + Amount <= MagicWalletMaxDeposit
+Action:
+  ├── PaymentTransaction → PYMS → ZarinPal
+  └── CallbackUrl = "/api/wallet/verify-magic-charge"
+Return: PaymentUrl
+```
+
+### ۸.۶ VerifyMagicChargeCommandHandler (جدید)
+
+```
+Input: Authority, Status
+On Success:
+  ├── creditAmount = amount × 2.5
+  ├── bonusAmount = creditAmount - amount
+  ├── wallet.Balance += creditAmount
+  ├── wallet.MagicTotalDeposited += amount
+  ├── wallet.MagicTotalCredited += creditAmount
+  ├── Transaction #1 (MagicWalletDeposit, amount)
+  ├── Transaction #2 (MagicWalletBonus, bonusAmount)
+  └── WalletChangeLog ✅ (اجباری)
+```
+
+---
+
+## ۹. تغییرات UI (FrontOffice)
+
+### ۹.۱ صفحات جدید
+
+| صفحه | Route | توضیح |
+|-------|-------|--------|
+| MagicWallet.razor | `/profile/magic-wallet` | فرم شارژ + پروگرس‌بار سقف |
+| MagicPaymentCallback.razor | `/profile/magic-payment-callback` | نتیجه پرداخت شارژ جادویی |
+
+### ۹.۲ تغییر صفحات موجود
+
+| صفحه | تغییر |
+|-------|--------|
+| Profile/Index.razor | بنر "🪄 کیف‌پول جادویی فعال" + لینک شارژ |
+| Profile/Wallet.razor | نمایش وضعیت Magic + پروگرس (deposited/100M) |
+| Club membership page | اگه Magic → پیام "بعد از اتمام جادویی می‌تونید پکیج بخرید" |
+
+### ۹.۳ gRPC Proto اضافات
+
+```protobuf
+// userwallet.proto — RPCهای جدید:
+rpc InitiateMagicCharge (MagicChargeRequest) returns (MagicChargeResponse);
+rpc GetMagicWalletStatus (MagicWalletStatusRequest) returns (MagicWalletStatusResponse);
+
+message MagicChargeRequest {
+    int64 user_id = 1;
+    int64 amount = 2;
+}
+
+message MagicChargeResponse {
+    string payment_url = 1;
+    int64 remaining_deposit_cap = 2;
+}
+
+message MagicWalletStatusResponse {
+    bool is_magic_mode = 1;
+    int64 total_deposited = 2;
+    int64 total_credited = 3;
+    int64 remaining_cap = 4;
+    string activated_at = 5;
+}
+```

roadmap/PACKAGE-TRANSFORMATION-TASKS.md

@@ -0,0 +1,864 @@
+# 🔄 نقشه‌راه تحول پکیج‌بیس — تسک‌های گام‌به‌گام
+
+> **وضعیت:** در حال اجرا — **فاز ۰-۱۰ (تکمیل کد + استقرار staging) ✅** | NuGet v0.0.189 | تست باقی‌مانده  
+> **تاریخ:** ۱۴۰۴/۱۲/۰۸  
+> **پیش‌نیاز:** [BIZ-PACKAGE-BASED-SYSTEM.md](../business/BIZ-PACKAGE-BASED-SYSTEM.md) **v6** (تکمیل Q24-Q30 + History + Rename)  
+> **هدف:** شکستن **۴۸+ تغییر** به تسک‌های اتمیک با ترتیب اجرا و وابستگی‌ها  
+> **کامیت‌ها:**  
+> CMS: `8b9c317`→`fe3edd1`→`ae92ab8`→`a9cd2fd`→`8e5c7c5`→`ccb938e`→`0002a5a`→`607f791`→`7176fe4`→`d19c569`→`469d97b`→`161f796`→`8446e0e`→`ce8e248`→`7554d70`→`aaaf7fc`→`dcd1135`→`a1024a3`→`fdbb91d`→`10d2ca2`  
+> FrontOffice: `b82cac4`→`71f391a`→`0bbc11e`→`d71d463`→`40882c8`→`a956cb9`→`3bffc13`→`474d364`  
+> BackOffice: `f1b0085`→`89f5241`→`c96377a`→`8be98ae`→`e020354`→`6939780`
+
+> ⚠️ **تغییرات v3:** پورسانت per-package، carryover مجزا، SP parameters داینامیک، گزارش‌دهی FO/BO per-package
+
+---
+
+## 📊 نمای کلی
+
+```
+مرحله ۰: فیکس باگ فوری (۱ روز)                           ✅ `8b9c317` + `fe3edd1`
+    └─→ مرحله ۱: زیرساخت Domain + DB (۴ روز)         ✅ `ae92ab8`
+        └─→ مرحله ۱.۵: Migration + Seed                    ✅ `a9cd2fd`
+            ├─→ مرحله ۲: منطق کسب‌وکار (۴ روز)           ✅ `8e5c7c5`
+            │       └─→ مرحله ۳: بازسازی لایه Package       ✅ `ccb938e`
+            │               └─→ مرحله ۴: CRUD + Legacy Fixes   ✅ `0002a5a`
+            │                       └─→ مرحله UI (۵ روز)  ✅
+            └─→ مرحله ۳: پورسانت (۴ روز)               ✅ `607f791`+`7176fe4`
+                    └─→ مرحله ۶: Deprecation cleanup    ✅ `d19c569`
+                            └─→ مرحله ۷: Migration + Cleanup  ✅
+                                ├─→ 7a: Cosmetic cleanup      ✅ CMS:`469d97b` FO:`b82cac4` BO:`f1b0085`
+                                ├─→ 7b: FO RPC migration      ✅ CMS:`161f796` FO:`71f391a`
+                                └─→ 7c: Delete deprecated      ✅ CMS:`8446e0e`
+                                        └─→ مرحله ۸: FO/BO Completion
+                                            ├─→ 8a: Checkout wire-up    ✅ FO:`0bbc11e`
+                                            ├─→ 8b: BO CRUD expansion  ✅ CMS:`ce8e248` BO:`89f5241`
+                                            ├─→ 8c: FO Package pages   ✅ FO:`d71d463`
+                                            └─→ 8d: Proto cleanup      ✅ CMS:`7554d70` FO:`40882c8` BO:`c96377a`
+                                                └─→ 8e: Per-package reports ✅ CMS:`aaaf7fc` FO:`a956cb9` BO:`8be98ae`
+                                                    └─→ 8f: UI completion   ✅ CMS:`dcd1135` FO:`3bffc13` BO:`e020354`
+                                                            └─→ مرحله ۹: Q24-Q30 + History + Rename
+                                                                ├─→ 9a: Q24+Q26 (threshold+SP) ✅ CMS:`a1024a3`
+                                                                ├─→ 9b: Q27 History entities  ✅ CMS:`fdbb91d`
+                                                                ├─→ 9c: Q28 UI Guidance       ✅ FO:`474d364` BO:`6939780`
+                                                                └─→ 9d: Rename+Interceptor+Mig ✅ CMS:`10d2ca2`
+                                                                    └─→ مرحله ۱۰: استقرار + DataMigration + UI
+                                                                        ├─→ 10a: DataMigration Tool   ✅ Local: `0e8c6fd`→`31cc464`
+                                                                        ├─→ 10b: EF Staging Migrations ✅
+                                                                        ├─→ 10c: PackagePurchaseDialog ✅ FO:`a3681a8`
+                                                                        └─→ 10d: UI Fixes (Rial/Toman+لیبل+HTML) ✅ FO:`3c1a8ff`
+                                                                            └─→ مرحله ۵: تست + نهایی  ⬜
+
+مسیر بحرانی: ۰→۱→۱.۵→۲→۳→۴→UI→۹→۱۰→۵ = ~۲۲ روز | انجام‌شده: ۰→10d (~۲۰ روز)
+```
+
+---
+
+## مرحله ۰ — فیکس باگ‌های فوری ✅
+
+> ✅ تکمیل‌شده | کامیت: `8b9c317` + `fe3edd1`
+
+### ✅ وضعیت باگ‌ها (بررسی اولیه لازم)
+
+| # | باگ | Handler | شرح فیکس |
+|---|------|---------|----------|
+| B1 | DiscountBalance شارژ نمی‌شود | `VerifyGoldenPackagePurchaseCommandHandler` | اضافه `DiscountBalance += Amount × 2` + WalletChangeLog |
+| B2 | UserPackagePurchase ساخته نمی‌شود | `VerifyGoldenPackagePurchaseCommandHandler` | ساخت record بعد verify موفق |
+| B3 | UserPackagePurchase ساخته نمی‌شود | `VerifyPackagePurchaseCommandHandler` | ساخت record بعد verify موفق |
+| B4 | UserPackagePurchase ساخته نمی‌شود | `VerifyBasePackagePaymentCommandHandler` | ساخت record بعد verify موفق |
+
+#### دستور کار B1:
+```
+1. باز کردن VerifyGoldenPackagePurchaseCommandHandler.cs
+2. پیدا کردن جایی که Balance شارژ می‌شود
+3. اضافه کردن:
+   wallet.DiscountBalance += command.Amount * 2;
+   // + ساخت WalletChangeLog برای DiscountBalance
+4. تست: verify → چک DiscountBalance در DB
+```
+
+#### دستور کار B2-B4 (الگوی مشترک):
+```
+1. بعد از verify موفق و شارژ wallet:
+   var purchase = new UserPackagePurchase
+   {
+       UserId = userId,
+       PackageId = packageId,         // فعلاً BasePackageId = 4
+       PurchaseDate = DateTime.UtcNow,
+       Amount = amount,
+       PurchaseMethod = purchaseMethod, // ZarinPal, BFF, etc.
+       TransactionId = transactionId,
+       IsVerified = true
+   };
+   _context.UserPackagePurchases.Add(purchase);
+2. تست: verify → چک UserPackagePurchases table
+```
+
+---
+
+## مرحله ۱ — زیرساخت (Domain + DB) ✅
+
+> ✅ تکمیل‌شده | کامیت: `ae92ab8` (Phase 1) + `a9cd2fd` (Phase 1.5 Migration)
+
+### T1.1 — بروزرسانی Package Entity (۱۱ فیلد جدید — v3)
+
+**فایل:** `CMS/src/CMSMicroservice.Domain/Entities/Package.cs`
+
+```diff
++ public int SortOrder { get; set; }
++ public bool IsActive { get; set; } = true;
++ public bool IsBasePackage { get; set; }
++ public bool SupportsDayaPurchase { get; set; }
++ public bool SupportsDirectPurchase { get; set; } = true;
++ public long ActivationFee { get; set; }
++ public decimal DiscountMultiplier { get; set; } = 2.0m;
++ public decimal MagicWalletMultiplier { get; set; } = 2.5m;
++ // === v3: تنظیمات پورسانت per-package ===
++ public int MaxBalancesPerLeg { get; set; } = 300;         // نقره‌ای=۳۰
++ public int MaxNetworkLevel { get; set; } = 15;
++ // === v3: سقف کیف‌پول جادویی per-package ===
++ public long MagicWalletMaxDeposit { get; set; } = 1_000_000_000;
++ public long MagicWalletMaxCredit { get; set; } = 2_500_000_000;
++
++ public virtual ICollection<PackageFeature> PackageFeatures { get; set; }
+```
+
+**EF Config:** `PackageConfiguration.cs`
+- حداکثر یک `IsBasePackage = true` (Index filter)
+- Precision for decimal fields
+
+### T1.2 — ایجاد PackageFeature Entity
+
+**فایل جدید:** `CMS/src/CMSMicroservice.Domain/Entities/PackageFeature.cs`
+
+```csharp
+public class PackageFeature : BaseAuditableEntity
+{
+    public long PackageId { get; set; }
+    public virtual Package Package { get; set; }
+    public long ClubFeatureId { get; set; }
+    public virtual ClubFeature ClubFeature { get; set; }
+    public bool IsIncluded { get; set; } = true;
+}
+```
+
+### T1.3-T1.6 — اضافه PackageId به entityها
+
+| Entity | فیلد | Required? | توضیح | v3? |
+|--------|------|-----------|-------|-----|
+| ClubMembership | `long? PackageId` | nullable (بعد migration → required) | آخرین پکیج | |
+| ClubMembershipCycle | `long PackageId` | required | پکیج این چرخه | |
+| WeeklyCommissionPool | `long PackageId` | required + Unique(WeekDefId, PkgId) | Pool هر پکیج | |
+| UserCommissionPayout | `long? PackageId` | nullable + **Unique(UserId, WeekId, PkgId)** | ردیابی | 🔄 |
+| **NetworkWeeklyBalance** | **`long PackageId`** | **required + Unique(UserId, WeekId, PkgId)** | **تعادل per-package** | **🆕** |
+
+### T1.7 — حذف SystemConstants (v3: ۷ ثابت)
+
+**فایل:** `CMS/src/CMSMicroservice.Domain/Common/SystemConstants.cs`
+
+```diff
+- public const long BasePackageAmount = 56_000_000;
+- public const long DayaLoanAmount = 56_000_000;
+- public const long ClubActivationFee = 25_200_000;
+- public const long ClubMembershipGiftValue = 25_200_000;
+- public const decimal MagicWalletMultiplier = 2.5m;
+- // === v3: انتقال به Package entity ===
+- public const int CommissionMaxWeeklyBalancesPerLeg = 300;
+- public const int CommissionMaxNetworkLevel = 15;
+```
+
+> ⚠️ **قبل از حذف:** grep تمام مصرف‌کننده‌ها → جایگزین با `Package.Property`  
+> ⚠️ **v3:** `CommissionMaxWeeklyBalancesPerLeg` و `CommissionMaxNetworkLevel` هم باید per-package شوند
+
+### T1.8 — Database Migration
+
+```bash
+dotnet ef migrations add AddPackageBasedSystem
+```
+
+**شامل:**
+- ستون‌های جدید Package
+- جدول PackageFeatures
+- FKها در 4 entity
+- Unique constraint
+
+### T1.9 — Data Migration Script
+
+```sql
+-- 1. بروزرسانی پکیج فعلی (ID=4 → اضافه فیلدهای جدید)
+UPDATE "CMS"."Packages" SET
+    "SortOrder" = 2,
+    "IsActive" = true,
+    "IsBasePackage" = true,
+    "SupportsDayaPurchase" = true,
+    "SupportsDirectPurchase" = true,
+    "ActivationFee" = 25200000,
+    "DiscountMultiplier" = 2.0,
+    "MagicWalletMultiplier" = 2.5,
+    -- v3: تنظیمات پورسانت
+    "MaxBalancesPerLeg" = 300,
+    "MaxNetworkLevel" = 15,
+    "MagicWalletMaxDeposit" = 1000000000,
+    "MagicWalletMaxCredit" = 2500000000
+WHERE "Id" = 4;
+
+-- 2. Link existing data to base package
+UPDATE "CMS"."ClubMemberships" SET "PackageId" = 4 WHERE "PackageId" IS NULL;
+UPDATE "CMS"."ClubMembershipCycles" SET "PackageId" = 4 WHERE "PackageId" IS NULL;
+UPDATE "CMS"."WeeklyCommissionPools" SET "PackageId" = 4 WHERE "PackageId" IS NULL;
+UPDATE "CMS"."UserCommissionPayouts" SET "PackageId" = 4 WHERE "PackageId" IS NULL;
+-- v3: NetworkWeeklyBalance هم PackageId می‌گیره
+UPDATE "CMS"."NetworkWeeklyBalances" SET "PackageId" = 4 WHERE "PackageId" IS NULL;
+
+-- 3. Seed Silver package (شامل فیلدهای v3)
+INSERT INTO "CMS"."Packages" (..., "MaxBalancesPerLeg", "MaxNetworkLevel",
+    "MagicWalletMaxDeposit", "MagicWalletMaxCredit", ...)
+VALUES ('پکیج نقره‌ای', 5600000, ..., 30, 15, 100000000, 250000000, ...);
+```
+
+### T1.10 — بروزرسانی Protoها
+
+| Proto File | تغیر | v3? |
+|-----------|-------|-----|
+| package.proto | فیلدهای جدید Package message (۱۱ فیلد) | 🔄 |
+| clubmembership.proto | package_id در request/response | |
+| commission.proto | **`package_id` + `package_title`** در ۴ message | **🆕** |
+| commission.proto | **Message جدید: `CustomerCommissionPackageSummary`** | **🆕** |
+| commission.proto | **فیلتر `package_id` در Requestها** | **🆕** |
+
+### T1.11 — اضافه PackageId به NetworkWeeklyBalance (🆕 v3)
+
+**فایل:** `CMS/src/CMSMicroservice.Domain/Entities/NetworkWeeklyBalance.cs`
+
+```diff
++ public long PackageId { get; set; }
++ public virtual Package Package { get; set; }
+```
+
+**EF Config:** اضافه Unique Index:
+```csharp
+builder.HasIndex(e => new { e.UserId, e.WeekDefinitionId, e.PackageId }).IsUnique();
+builder.HasOne(e => e.Package).WithMany().HasForeignKey(e => e.PackageId);
+```
+
+> ⚠️ **تاثیر حجم:** رکوردهای تعادل ×N (تعداد پکیج). مثلاً ۱۰۰۰ کاربر × ۲ پکیج = ۲۰۰۰ رکورد هفتگی
+
+### T1.12 — Data Migration: NetworkWeeklyBalance (🆕 v3)
+
+```sql
+-- رکوردهای موجود → پکیج پایه
+UPDATE "CMS"."NetworkWeeklyBalances" 
+SET "PackageId" = (SELECT "Id" FROM "CMS"."Packages" WHERE "IsBasePackage" = true LIMIT 1)
+WHERE "PackageId" IS NULL;
+```
+
+---
+
+## مرحله ۲ — منطق کسب‌وکار ✅
+
+> ✅ تکمیل‌شده | کامیت: `8e5c7c5` (Phase 2) + `ccb938e` (Phase 3) + `0002a5a` (Phase 4)
+
+### T2.1 — Generic Verify Handler
+
+**هدف:** ادغام VerifyGolden + VerifyBase + VerifyGeneric → یک handler
+
+**الگوریتم:**
+```
+1. دریافت TransactionId از request
+2. خواندن Transaction → PackageId → Package entity
+3. verify با درگاه (ZarinPal/BFF/...)
+4. اگر موفق:
+   a. wallet.Balance += Package.Price
+   b. wallet.DiscountBalance += Package.Price × Package.DiscountMultiplier
+   c. ساخت WalletChangeLog (Balance)
+   d. ساخت WalletChangeLog (DiscountBalance)
+   e. ساخت UserPackagePurchase record
+   f. اگر اولین خرید: JoinNetwork
+   g. بروزرسانی ClubMembershipCycle.PackageId
+5. return success + receipt
+```
+
+### T2.2 — Generic Purchase Handler
+
+**هدف:** ادغام PurchaseGolden + PurchasePackage + InitiateBase → یک handler
+
+**تغییرات:**
+- حذف فیلتر `Title.Contains("طلایی")`
+- حذف `BasePackageId = 4`
+- خواندن Package entity از DB بر اساس `request.PackageId`
+- Gateway URL + Amount از Package.Price
+
+### T2.3-T2.4 — ActivateClubMembership بهبود
+
+**تغییرات:**
+```diff
+- var features = await GetAllFeatureIds();        // همه فیچرها
++ var features = await GetPackageFeatures(packageId);  // فیچرهای پکیج
+
+- membership.PackageAmount = SystemConstants.BasePackageAmount;
++ membership.PackageAmount = package.Price;
+
+- var activationFee = SystemConstants.ClubActivationFee;
++ var activationFee = package.ActivationFee;
+```
+
+### T2.5-T2.6 — Re-Purchase Logic
+
+**EXIT Magic Mode — تغییرات:**
+```diff
+  wallet.WalletMode = WalletMode.Normal;
+  wallet.MagicCompletedAt = DateTime.UtcNow;
+  cycle.MagicCompletedAt = DateTime.UtcNow;
++ user.PackagePurchaseMethod = PackagePurchaseMethod.None;
++ membership.IsActive = false;
++ cycle.IsCurrentCycle = false;
+```
+
+**Guard تغییرات:**
+```diff
+- if (user.PackagePurchaseMethod != PackagePurchaseMethod.None)
+-     throw new RpcException("قبلاً پکیج خریداری شده");
++ if (user.PackagePurchaseMethod != PackagePurchaseMethod.None 
++     && !HasCompletedMagicCycle(membership))
++     throw new RpcException("چرخه جاری هنوز تکمیل نشده");
+```
+
+### T2.7 — JWT Claims جدید
+
+```diff
+  claims.Add("HasPurchasedPackage", "true");
++ claims.Add("CanRepurchase", HasCompletedMagicCycle(membership).ToString());
++ claims.Add("PackageId", membership.PackageId?.ToString() ?? "");
++ claims.Add("PackageTitle", package?.Title ?? "");
+```
+
+---
+
+## مرحله ۳ — محاسبه پورسانت (موازی با مرحله ۲) ✅
+
+> ✅ تکمیل‌شده | کامیت: `607f791` + `7176fe4` | ⏱️ **۴ روز** | ریسک: بحرانی (مالی)
+
+### T3.1-T3.2 — SPs + PackageId + پارامترهای داینامیک (🔄 v3)
+
+```sql
+-- sp_CalculateWeeklyBalances — v3: حذف hardcode
+ALTER PROCEDURE sp_CalculateWeeklyBalances
+    @WeekDefinitionId BIGINT,
+    @PackageId BIGINT,
+    @MaxBalancesPerLeg INT,          -- v3: از Package entity (نه ۳۰۰ hardcode!)
+    @MaxNetworkLevel INT             -- v3: از Package entity (نه ۱۵ hardcode!)
+AS
+BEGIN
+    -- فیلتر: فقط کاربرانی که این پکیج را دارند
+    -- carryover: فقط رکوردهای PackageId = @PackageId
+    -- cap: از @MaxBalancesPerLeg (نه ۳۰۰)
+    -- depth: CTE تا @MaxNetworkLevel (نه ۱۵)
+    INSERT INTO "CMS"."NetworkWeeklyBalances" ("PackageId", ...)
+    SELECT @PackageId, ...
+    FROM "CMS"."UserWallets" w
+    INNER JOIN "CMS"."ClubMemberships" m ON m."UserId" = w."UserId"
+    WHERE m."PackageId" = @PackageId
+      AND m."IsActive" = true;
+END;
+```
+
+### T3.3 — Loop Service (🔄 v3: ارسال تنظیمات پکیج)
+
+```csharp
+// WeeklyCommissionCalculationService.cs
+var activePackages = await _context.Packages
+    .Where(p => p.IsActive && !p.IsDeleted)
+    .ToListAsync();
+
+foreach (var package in activePackages)
+{
+    _logger.LogInformation(
+        "Calculating commission for package {Id}: {Title} " +
+        "(MaxBalances={Max}, MaxLevel={Level})", 
+        package.Id, package.Title, 
+        package.MaxBalancesPerLeg, package.MaxNetworkLevel);
+    
+    // v3: پاس دادن تنظیمات پکیج
+    await strategy.CalculateWeeklyBalancesAsync(
+        weekId, package.Id, 
+        package.MaxBalancesPerLeg, package.MaxNetworkLevel);
+    
+    await strategy.CalculateWeeklyPoolAsync(weekId, package.Id);
+}
+```
+
+### T3.4 — OrmCommissionCalculationStrategy (🔄 v3)
+
+**تغییرات:**
+```diff
+- var maxBalances = SystemConstants.CommissionMaxWeeklyBalancesPerLeg; // 300
+- var maxLevel = SystemConstants.CommissionMaxNetworkLevel;           // 15
++ // پارامتر از بیرون — per-package
++ int maxBalances = maxBalancesPerLeg;  // e.g., نقره‌ای=30, پایه=300
++ int maxLevel = maxNetworkLevel;
+
+- // فیلتر کاربران
++ // فیلتر کاربران بر اساس پکیج
++ .Where(m => m.PackageId == packageId && m.IsActive)
+
+- // carryover
++ // carryover: فقط رکوردهای همان PackageId
++ .Where(b => b.PackageId == packageId && b.WeekDefinitionId == prevWeekId)
+```
+
+### T3.5 — SpCommissionCalculationStrategy (🆕 v3)
+
+```csharp
+// قبل: فقط WeekDefinitionId
+await connection.ExecuteAsync("CMS.sp_CalculateWeeklyBalances",
+    new { WeekDefinitionId = weekId, ForceRecalculate = true });
+
+// بعد (v3): پکیج + تنظیمات داینامیک
+await connection.ExecuteAsync("CMS.sp_CalculateWeeklyBalances",
+    new { 
+        WeekDefinitionId = weekId, 
+        PackageId = package.Id,
+        MaxBalancesPerLeg = package.MaxBalancesPerLeg,
+        MaxNetworkLevel = package.MaxNetworkLevel,
+        ForceRecalculate = true 
+    });
+```
+
+### T3.6 — Carryover per-package (🆕 v3)
+
+> ⚠️ **بحرانی:** week-shifting باید فقط رکوردهای همان PackageId را shift کند
+
+```
+هفته ۱۰ → هفته ۱۱:
+    علی: carryover_پایه = {Left: surplus, Right: surplus}    ← جداگانه
+    علی: carryover_نقره‌ای = {Left: 0, Right: 0}             ← جداگانه
+    
+    ✖ اشتباه: قاطی کردن carryover پایه و نقره‌ای!
+    ✔ صحیح: هر PackageId فقط carryover خودش را می‌بینه
+```
+
+### ⚠️ نکته بحرانی
+
+> پورسانت = پول واقعی. **هر تغییر در SPs باید:**
+> 1. ابتدا در staging با داده واقعی تست شود
+> 2. نتایج قبل و بعد مقایسه شوند
+> 3. Rollback plan آماده باشد
+> 4. در production ابتدا read-only اجرا شود (بدون commit)
+
+---
+
+## مرحله ۷ — Migration + Cleanup (سه‌گانه) ✅
+
+> ✅ تکمیل‌شده | ⏱️ **۱ روز** | ریسک: پایین
+
+### فاز 7a — Cosmetic Cleanup ✅
+
+> کامیت: CMS `469d97b` | FO `b82cac4` | BO `f1b0085`
+
+**CMS:**
+- حذف orphaned `PurchasePackage` handler (۳ فایل، بدون caller)
+- فیکس doc-comments: `طلایی` → `پکیج` در ۶ فایل (enums, entities, handlers)
+
+**FrontOffice:**
+- حذف hardcoded `پکیج طلایی` از `MyPackages.razor` و `Packages.razor`
+- اضافه `PackageTitle` property به `UserPackageStatusDto` record
+
+**BackOffice:**
+- تغییر label `پکیج طلایی` → `خرید پکیج` در `UserNetworkInfo.razor`
+
+### فاز 7b — FrontOffice RPC Migration ✅
+
+> کامیت: CMS `161f796` | FO `71f391a`
+
+**CMS:**
+- `CustomerPurchasePackage`: embed `orderId` در callback URL قبل از ارسال به درگاه
+  - `$"{request.CallbackUrl}{separator}orderId={purchase.Id}"`
+
+**FrontOffice:**
+- `Profile/Index.razor.cs`: مهاجرت `InitiateBasePackagePaymentAsync` → `CustomerPurchasePackageAsync`
+- `Profile/PaymentCallback.razor`: مهاجرت `VerifyBasePackagePaymentAsync` → `CustomerVerifyPackagePurchaseAsync`
+- پارامترهای جدید: `PackageId`, `CallbackUrl`, `PurchaseMethod`, `OrderId`, `Authority`, `Status`
+
+### فاز 7c — Delete Deprecated Handlers ✅
+
+> کامیت: CMS `8446e0e` (14 فایل، 1125 حذف)
+
+**حذف ۴ handler CQRS (۱۲ فایل):**
+- `PurchaseGoldenPackage/` (Command, Handler, Validator)
+- `VerifyGoldenPackagePurchase/` (Command, Handler, Validator)
+- `InitiateBasePackagePayment/` (Command, Handler, Validator)
+- `VerifyBasePackagePayment/` (Command, Handler, Validator)
+
+**Cleanup:**
+- `PackageService.cs`: حذف ۴ gRPC override method (proto RPCs حالا auto-throw `Unimplemented`)
+- `PackageProfile.cs`: حذف ۶ Mapster mapping block + ۴ using directive
+- Build: 0 Error ✅
+
+---
+
+## مرحله ۸ — FrontOffice Checkout + NuGet
+
+> 🔄 در حال اجرا | فاز 8a تکمیل ✅
+
+### فاز 8a — Checkout Wire-up ✅
+
+> کامیت: FO `0bbc11e`
+
+**Checkout.razor.cs:**
+- حذف dead code: `ProcessPayment()` از flow قدیمی `TransactionsContract + UserOrderContract` استفاده می‌کرد
+- Rewrite با `CustomerPurchasePackageAsync` (مثل Profile/Index.razor.cs)
+- Callback URL → `/profile/payment-callback` (از صفحه verify موجود استفاده مجدد)
+- حذف DI بلااستفاده: `UserOrderContract`, `TransactionContract`
+- حذف usings: `Transactions`, `UserOrder`, `WellKnownTypes`
+
+**Profile/Index.razor.cs (cosmetic):**
+- Rename `basePackage` → `selectedPackage`, `tempCallbackUrl` → `callbackUrl`
+
+### فاز 8b — BackOffice Package CRUD Expansion ✅
+
+> کامیت: CMS `ce8e248` | BO `89f5241` (7 فایل، +138/-23)
+
+**NuGet Rebuild:**
+- Proto version bump: `0.0.184` → `0.0.185`
+- Pack و deploy به local feed (`/nupkg`)
+- BackOffice NuGet.config: اضافه local feed source
+
+**CreateDialog.razor (۱۲ فیلد جدید):**
+- `SortOrder` — MudNumericField<int> ترتیب نمایش
+- `ActivationFee` — MudNumericField<long> هزینه فعال‌سازی
+- `DiscountMultiplier` — MudNumericField<double> ضریب تخفیف
+- `MagicWalletMultiplier` — MudNumericField<double> ضریب کیف پول جادویی
+- `MagicWalletMaxDeposit` — MudNumericField<long> سقف واریز جادویی
+- `MagicWalletMaxCredit` — MudNumericField<long> سقف اعتبار جادویی
+- `MaxBalancesPerLeg` — MudNumericField<int> حداکثر تعادل هر پا
+- `MaxNetworkLevel` — MudNumericField<int> حداکثر سطح شبکه
+- `IsActive` — MudCheckBox فعال/غیرفعال
+- `IsBasePackage` — MudCheckBox پکیج پایه
+- `SupportsDirectPurchase` — MudCheckBox پرداخت مستقیم
+- `SupportsDayaPurchase` — MudCheckBox اعتبار دایا
+
+**UpdateDialog.razor:** همان ۱۲ فیلد
+
+**PackageMainPage Grid (۴ ستون جدید):**
+- `Price` — فرمت‌شده با N0
+- `SortOrder` — ترتیب
+- `IsActive` — MudChip فعال/غیرفعال
+- `IsBasePackage` — MudChip پایه/عادی
+
+**سایر:**
+- Dialog size: `MaxWidth.Small` → `MaxWidth.Medium`
+- CreateNew defaults: `IsActive=true, DiscountMultiplier=2.0, MagicWalletMultiplier=2.5, ...`
+- فیکس `HasPurchasedGoldenPackage` → `HasPurchasedPackage` در `UserNetworkInfo.razor`
+
+### فاز 8c — FrontOffice Package Pages ✅
+
+> کامیت: FO `d71d463` (5 فایل، +109/-56)
+
+**NuGet:** `0.0.182` → `0.0.185` + local feed source
+
+**PackageDetail.razor.cs:**
+- مهاجرت `GetPackageAsync` (admin RPC) → `GetCustomerPackageDetailsAsync` (customer RPC)
+- Features: از hardcoded ثابت → از `PackageFeature` API داینامیک
+- Specifications: از hardcoded → از `PackageFeature.IsHighlighted` API
+- حذف ۵ hardcoded feature string + ۴ hardcoded specification
+
+**PackageService.cs:**
+- `PackageDto`: اضافه ۸ فیلد جدید (ActivationFee, DiscountMultiplier, MagicWalletMultiplier, etc.)
+- `GetAllPackagesAsync`: مپ فیلدهای جدید از `CustomerPackageModel`
+- `GetUserPackageStatusAsync`: از stub → اتصال واقعی به `GetUserPackageStatusAsync` RPC
+
+**Packages.razor:**
+- Un-exclude از build (حذف `<Content Remove>` + `<Compile Remove>`)
+- جایگزینی ۳ feature bullet hardcoded → dynamic features:
+  - `SupportsDirectPurchase` → پرداخت مستقیم
+  - `SupportsDayaPurchase` → پرداخت با اعتبار دایا
+  - `DiscountMultiplier` → ضریب تخفیف: X.Xx
+  - `MagicWalletMultiplier` → کیف پول جادویی: X.Xx
+  - `IsBasePackage` → پکیج پایه ⭐
+
+### فاز 8d — Proto Cleanup ✅
+
+> کامیت: CMS `7554d70` (2 فایل، -103) | FO `40882c8` | BO `c96377a`
+
+**حذف ۴ deprecated RPC:**
+- `PurchaseGoldenPackage` — جایگزین: `CustomerPurchasePackage`
+- `VerifyGoldenPackagePurchase` — جایگزین: `CustomerVerifyPackagePurchase`
+- `InitiateBasePackagePayment` — جایگزین: `CustomerPurchasePackage`
+- `VerifyBasePackagePayment` — جایگزین: `CustomerVerifyPackagePurchase`
+
+**حذف ۸ deprecated message type:**
+- `PurchaseGoldenPackageRequest` / `PurchaseGoldenPackageResponse`
+- `VerifyGoldenPackagePurchaseRequest` / `VerifyGoldenPackagePurchaseResponse`
+- `InitiateBasePackagePaymentRequest` / `InitiateBasePackagePaymentResponse`
+- `VerifyBasePackagePaymentRequest` / `VerifyBasePackagePaymentResponse`
+
+**حفظ شده:** `GetUserPackageStatus` RPC + messages (هنوز در استفاده)
+
+**NuGet:** `0.0.185` → `0.0.186` (همه ریپوها)
+
+### فاز 8e — Per-Package Commission Reports ✅
+
+> کامیت: CMS `aaaf7fc` | FO `a956cb9` | BO `8be98ae`
+
+**Proto (commission.proto):**
+- اضافه `package_id` فیلتر به ۴ request message: `GetUserCommissionPayoutsRequest`, `GetUserWeeklyBalancesRequest`, `GetMyCommissionPayoutsRequest`, `GetMyWeeklyBalancesRequest`
+- اضافه `package_id` + `package_title` به ۴ response model: `UserCommissionPayoutModel`, `UserWeeklyBalanceModel`, `CustomerCommissionPayoutModel`, `CustomerWeeklyBalanceModel`
+
+**CMS (12 فایل):**
+- ۴ Query record: اضافه `public long? PackageId { get; init; }`
+- ۴ Handler: اضافه `.Include(x => x.Package)` + فیلتر `Where(x => x.PackageId == request.PackageId.Value)` + map `PackageId`/`PackageTitle`
+- ۳ Response DTO: اضافه `PackageId` + `PackageTitle`
+- `CommissionProfile.cs`: تنظیم mapping‌های Mapster برای admin + customer
+
+**BackOffice (6 فایل):**
+- کامپوننت جدید `PackageSelect.razor/.cs`: dropdown قابل استفاده مجدد با بارگذاری پکیج‌ها از `PackageContract`
+- `UserPayouts.razor/.cs`: فیلتر PackageSelect + ستون پکیج با MudChip
+- `BalancesReport.razor`: فیلتر PackageSelect + ستون پکیج با MudChip + mapping PackageTitle
+
+**FrontOffice (7 فایل):**
+- `CommissionDtos.cs`: اضافه `PackageId` + `PackageTitle` به `CommissionPayoutDto` و `WeeklyBalanceDto`
+- `CommissionService.cs`: اضافه پارامتر `packageId` به `GetMyCommissionPayoutsAsync` و `GetMyWeeklyBalanceAsync`
+- `CommissionDashboardPage.razor/.cs`: فیلتر dropdown پکیج + ستون «پکیج» با MudChip (دسکتاپ + موبایل)
+- `WeeklyBalancePage.razor/.cs`: فیلتر MudSelect پکیج + نمایش MudChip پکیج در بخش اطلاعات هفته
+
+**NuGet:** `0.0.186` → `0.0.187` (همه ریپوها)
+
+### فاز 8f — UI Completion (T4.2 + T4.3 + T4.13 + F2 + F3) ✅
+
+> کامیت: CMS `dcd1135` | FO `3bffc13` | BO `e020354`
+
+**CMS (T4.13 — PackageFeature CRUD):**
+- Proto: اضافه `repeated int64 feature_ids` به ۴ message (Create/Update Request, Get/GetAll Response)
+- `CreateNewPackageCommand/Handler`: sync FeatureIds → ساخت `PackageFeature` records
+- `UpdatePackageCommand/Handler`: sync FeatureIds → حذف قبلی‌ها + ساخت جدید
+- `GetPackage/GetAllPackageByFilter`: اضافه `.Include(x => x.PackageFeatures)` + map FeatureIds
+
+**BackOffice (F2 + T4.13):**
+- **F2:** کامپوننت جدید `ChangeParentDialog.razor/.cs` — مودال جابجایی در شبکه با NewParentId, NewLeg, Reason
+- **F2:** دکمه «تغییر والد» در `UserNetworkInfo.razor`
+- **T4.13:** checkbox matrix فیچرها در `CreateDialog` و `UpdateDialog` — بارگذاری از `ConfigurationContractClient`
+
+**FrontOffice (T4.2 + T4.3 + F3):**
+- **T4.2:** پرداخت شرطی در `Checkout.razor` بر اساس `SupportsDirectPurchase`/`SupportsDayaPurchase`
+- **T4.3:** منطق خرید مجدد در `MyPackages.razor` — بارگذاری `MagicWalletStatus` + CTA شرطی + progress bar
+- **F3:** نمایش PV سفارش در `Store/OrderDetail.razor` — `CalculateOrderPVAsync` + جدول PV هر محصول
+
+**NuGet:** `0.0.187` → `0.0.188` (همه ریپوها)
+
+---
+
+## مرحله ۴ — UI (FrontOffice + BackOffice)
+
+> ⏱️ **۵ روز** (v3: +۲) | وابستگی: مرحله ۲ + ۳ | ریسک: متوسط
+
+### T4.1 — کاشی‌های پکیج داینامیک
+
+**فایل:** `FrontOffice/src/.../Pages/Package/Packages.razor`
+
+```razor
+@* قبل: hardcoded *@
+@* بعد: *@
+@foreach (var package in _packages.OrderBy(p => p.SortOrder))
+{
+    <PackageCard Package="@package" 
+                 OnPurchase="StartPurchase"
+                 ShowFeatures="true"
+                 ShowPV="true" />
+}
+```
+
+### T4.2 — مودال پرداخت شرطی ✅ FO:`3bffc13`
+
+**پیاده‌سازی:**
+- `Checkout.razor.cs`: اضافه `PackageService` injection، بارگذاری پکیج‌ها با `GetAllPackagesAsync()`
+- `Checkout.razor`: دکمه‌های پرداخت شرطی بر اساس `SupportsDirectPurchase` و `SupportsDayaPurchase`
+- اضافه `DayaLoanPayment()` method + alert برای عدم وجود روش پرداخت
+- `Pack` record: اضافه `SupportsDirectPurchase` و `SupportsDayaPurchase`
+
+### T4.3 — MyPackages + Re-Purchase ✅ FO:`3bffc13`
+
+**پیاده‌سازی:**
+- `MyPackages.razor.cs`: بارگذاری `MagicWalletStatus` از `WalletService.GetMagicWalletStatusAsync()`
+- فرمول خرید مجدد: `WalletMode == 0 && PurchaseCycleCount >= 1 && MagicRemainingDeposit == 0`
+- `MyPackages.razor`: CTA شرطی «🎉 چرخه جادویی تکمیل شد!» + دکمه «خرید پکیج جدید»
+- بخش پیشرفت کیف پول جادویی: مبلغ واریزی، باقی‌مانده، اعتبار دریافتی + progress bar
+
+### T4.8 — FrontOffice: CommissionDashboard per-package (🆕 v3) ✅ FO:`a956cb9`
+
+**پیاده‌سازی:**
+- `CommissionDtos.cs`: اضافه `PackageId` + `PackageTitle` به `CommissionPayoutDto` و `WeeklyBalanceDto`
+- `CommissionService.cs`: اضافه پارامتر `packageId` به `GetMyCommissionPayoutsAsync` و `GetMyWeeklyBalanceAsync`
+- `CommissionDashboardPage.razor`: اضافه dropdown فیلتر پکیج + ستون «پکیج» با MudChip + نمایش پکیج در card موبایل
+- `CommissionDashboardPage.razor.cs`: inject `PackageService`، فیلد `_filterPackageId`، بارگذاری لیست پکیج‌ها
+
+### T4.9 — FrontOffice: WeeklyBalance per-package (🆕 v3) ✅ FO:`a956cb9`
+
+**پیاده‌سازی:**
+- `WeeklyBalancePage.razor`: اضافه MudSelect فیلتر پکیج کنار WeekSelector + نمایش MudChip پکیج در بخش اطلاعات هفته
+- `WeeklyBalancePage.razor.cs`: inject `PackageService`، فیلد `_filterPackageId`، ارسال به `CommissionService.GetMyWeeklyBalanceAsync`
+
+### T4.10-T4.12 — BackOffice: گزارش‌های پورسانت per-package (🆕 v3) ✅ BO:`8be98ae`
+
+**پیاده‌سازی:**
+- کامپوننت جدید `PackageSelect.razor/.cs`: dropdown قابل استفاده مجدد با بارگذاری پکیج‌ها از `PackageContract`
+- `UserPayouts.razor/.cs`: فیلتر PackageSelect + ستون پکیج با MudChip
+- `BalancesReport.razor`: فیلتر PackageSelect + ستون پکیج با MudChip + mapping `PackageTitle`
+
+### T4.13 — BackOffice: Package CRUD + Quick Access فیچرها (🆕 v3) ✅ CMS:`dcd1135` BO:`e020354`
+
+**CMS پیاده‌سازی:**
+- Proto: اضافه `repeated int64 feature_ids` به ۴ message (Create/Update Request, Get/GetAll Response)
+- `CreateNewPackageCommand/Handler`: اضافه `FeatureIds` + ساخت `PackageFeature` records
+- `UpdatePackageCommand/Handler`: اضافه `FeatureIds` + sync (حذف قبلی‌ها + ساخت جدید)
+- `GetPackageQueryHandler`: اضافه `.Include(x => x.PackageFeatures)` + map `FeatureIds`
+- `GetAllPackageByFilterQueryHandler`: اضافه `.Include(x => x.PackageFeatures)` قبل از `PaginatedListAsync`
+- NuGet: `0.0.187` → `0.0.188`
+
+**BO پیاده‌سازی:**
+- `CreateDialog.razor/.cs`: بارگذاری `ClubFeatures` از `ConfigurationContractClient` + checkbox matrix
+- `UpdateDialog.razor/.cs`: همان pattern + pre-populate از `Model.FeatureIds`
+- Mapster: `Adapt<UpdatePackageRequest>()` خودکار `FeatureIds` را map می‌کند
+
+---
+
+## مرحله ۹ — Q24-Q30 Business Decisions + History Infrastructure ✅
+
+> ✅ تکمیل‌شده | وابستگی: مرحله ۸ | کامیت‌ها: CMS:`a1024a3`→`fdbb91d`→`10d2ca2` FO:`474d364` BO:`6939780`
+
+### 9a: Q24 آستانه موجودی + Q26 SP Worker ✅ (CMS:`a1024a3`)
+
+**Q24 — آستانه موجودی:**
+- شرط ورود به Magic و خرید مجدد از `Balance == 0` به `Balance <= 1_000_000` ریال تغییر کرد
+- چون قیمت محصولات متفاوته، Balance دقیقاً صفر نمی‌شه
+- فایل‌ها: `UserOrderService.cs` (شرط EXIT Magic + Re-purchase guard)
+
+**Q26 — SP Worker:**
+- `StoredProcedureDeploymentService` (IHostedService) — در startup فایل‌های `.sql` از embedded resource خوانده می‌شوند
+- مقایسه checksum با جدول `__SPChecksums` — فقط SP‌های تغییریافته re-deploy می‌شوند
+- فایل‌ها: `StoredProcedureDeploymentService.cs`, embedded `.sql` resources
+
+### 9b: Q27 History Tables Entities ✅ (CMS:`fdbb91d`)
+
+**Entity‌های جدید:**
+- `PackageHistory`: فیلدهای Old*/New* برای Price, ActivationFee, MagicMultiplier, MagicMaxDeposit, MaxBalancesPerLeg, IsActive + Action + PerformedBy + Reason
+- `ClubMembershipCycleHistory`: فیلدهای Old*/New* برای IsCurrentCycle, MagicStartedAt, MagicCompletedAt + Action + UserId + CycleNumber
+
+**Enums جدید:**
+- `PackageAction`: Created, Updated, Activated, Deactivated, PriceChanged, FeaturesChanged
+- `ClubMembershipCycleAction`: Created, MagicStarted, MagicCompleted, Closed, AdminModified
+
+**زیرساخت:**
+- EF Configurations (indexes, maxLength, precision)
+- DbSets در `IApplicationDbContext` و `ApplicationDbContext`
+- Navigation Properties: `Package.Histories`, `ClubMembershipCycle.Histories`
+
+### 9c: Q28 UI Guidance ✅ (FO:`474d364` BO:`6939780`)
+
+**FrontOffice — ۷ صفحه با MudAlert آموزشی:**
+- G1: Packages.razor — توضیح سیستم پکیج‌بیس
+- G2: Checkout — هشدار شارژ کیف‌پول اعتباری
+- G3: MyPackages — توضیح وضعیت پکیج‌ها
+- G4: MagicWallet — هشدار شرایط خروج + سقف شارژ
+- G5: CommissionDashboard — توضیح per-package
+- G6: ClubMembership — آموزش چرخه عضویت
+- G7: ActivationSection — هشدار هزینه فعال‌سازی
+
+**BackOffice — ۶ صفحه با MudAlert:**
+- G8: PackageCRUD — هشدار ثبت تغییرات در History
+- G9: ClubFeatures — توضیح ارتباط فیچر-پکیج
+- G10: ManualPayments — هشدار مبلغ بر اساس پکیج
+- G11: Commission Dashboard — توضیح Pool per-package
+- G12: UserPayouts — توضیح فیلتر پکیج
+- G13: ClubMembers — اطلاعات چرخه عضویت
+
+### 9d: Rename + History Interceptor + EF Migration ✅ (CMS:`10d2ca2`)
+
+**Rename (86 فایل):**
+- `UserWalletChangeLog` → `UserWalletHistory` در 54+ فایل (entities, configs, DTOs, commands, queries, protos, services)
+- 34 فایل rename شده + 11 دایرکتوری rename شده
+- Proto: `userwalletchangelog.proto` → `userwallethistory.proto`
+
+**History Interceptor:**
+- `IHasHistory<T>` generic interface در `Domain/Common` — متد `CreateHistorySnapshot(action, performedBy)`
+- `HistoryTrackingSaveChangesInterceptor` در `Infrastructure/Persistence/Interceptors` — reflection-based
+  - شناسایی entity‌های `IHasHistory<>` از ChangeTracker
+  - فراخوانی `CreateHistorySnapshot` برای Modified/Added
+  - Auto-fill فیلدهای `Old*` از `OriginalValues` با naming convention
+- `Package` implements `IHasHistory<PackageHistory>` — اولین entity
+
+**EF Migration (`Q27_HistoryTables_And_RenameWalletHistory`):**
+- ⚠️ EF Core اتوماتیک `DropTable` + `CreateTable` تولید کرد → **دستی اصلاح شد** به `RenameTable` (حفظ داده‌ها)
+- `RenameTable` + `RenameIndex` × 2 + `sp_rename` برای PK و FK‌ها
+- `CreateTable` برای `ClubMembershipCycleHistories` و `PackageHistories` (جداول جدید)
+- Down method: reverse rename + drop new tables
+
+---
+
+## مرحله ۵ — تست و استقرار
+
+> ⏱️ **۳ روز** (v3: +۱) | وابستگی: مرحله ۴
+
+### Checklist تست
+
+**خرید + فعال‌سازی:**
+- [ ] خرید پکیج نقره‌ای (ZarinPal)
+- [ ] خرید پکیج پایه (ZarinPal)
+- [ ] خرید پکیج پایه (Daya Loan)
+- [ ] خرید پکیج پایه (Manual Payment)
+- [ ] فعالسازی باشگاه با پکیج نقره‌ای → فیچرهای محدود
+- [ ] فعالسازی باشگاه با پکیج پایه → همه فیچرها
+
+**چرخه Magic + خرید مجدد:**
+- [ ] تکمیل چرخه Magic → ریست وضعیت
+- [ ] خرید مجدد بعد تکمیل چرخه (همان پکیج)
+- [ ] خرید مجدد با پکیج متفاوت (پایه → نقره‌ای)
+
+**پورسانت per-package (v3):**
+- [ ] Commission Pool جداگانه هر پکیج
+- [ ] تعادل per-package: MaxBalancesPerLeg متفاوت (پایه=۳۰۰, نقره‌ای=۳۰)
+- [ ] Carryover مجزا: shift فقط رکوردهای همان PackageId
+- [ ] SP پارامترها صحیح: @MaxBalancesPerLeg و @MaxNetworkLevel از Package
+- [ ] NetworkWeeklyBalance رکوردها: ۲ پکیج = ۲× رکورد
+
+**گزارش per-package (v3):**
+- [ ] FO: مشتری کارت‌های خلاصه per-package را می‌بیند
+- [ ] FO: مجموع پاداش = جمع همه پکیج‌ها
+- [ ] BO: فیلتر dropdown پکیج کار می‌کند
+- [ ] BO: CSV export شامل ستون پکیج
+
+**Migration + سایر:**
+- [ ] Data Migration — PackageId در رکوردهای قبلی (شامل NetworkWeeklyBalance)
+- [ ] JWT claims جدید (CanRepurchase, PackageId)
+- [x] UI: کاشی‌های داینامیک FrontOffice
+- [x] UI: ماتریس فیچر + Quick Access BackOffice
+- [ ] Rollback: بدون data loss
+
+---
+
+## 📅 تقویم پیشنهادی (v3)
+
+| هفته | روز | تسک |
+|------|-----|------|
+| هفته ۱ | روز ۱ | مرحله ۰: فیکس ۴ باگ |
+| | روز ۲-۳ | مرحله ۱: Package entity (۱۱ فیلد) + PackageFeature |
+| | روز ۴-۵ | مرحله ۱: FKها + NetworkWeeklyBalance + Migration |
+| هفته ۲ | روز ۶-۷ | مرحله ۲: Generic handlers + re-purchase |
+| | روز ۶-۸ | مرحله ۳: SP params + carryover per-package (موازی) |
+| | روز ۸-۱۰ | مرحله ۲: Guards + JWT + Manual |
+| هفته ۳ | روز ۱۱-۱۲ | مرحله ۴: FrontOffice UI + گزارش per-package |
+| | روز ۱۳-۱۴ | مرحله ۴: BackOffice UI + گزارش per-package |
+| | روز ۱۵-۱۷ | مرحله ۵: تست + deploy |
+
+---
+
+## 🔗 ارجاعات
+
+| مستند | محتوا |
+|-------|-------|
+| [BIZ-PACKAGE-BASED-SYSTEM.md](../business/BIZ-PACKAGE-BASED-SYSTEM.md) | طراحی فنی — **۴۸+ تغییر** (v3) + باگ‌ها |
+| [PACKAGE-TRANSFORMATION-UX.md](PACKAGE-TRANSFORMATION-UX.md) | تاثیر UX بر فرانت‌ها |
+| [FEATURE-BACKLOG.md](FEATURE-BACKLOG.md) | بکلاگ ۱۲ RPC آماده |
+| [GRPC-SERVICES-AUDIT.md](../cms/GRPC-SERVICES-AUDIT.md) | آدیت ۳۴۲ RPC |
+
+---
+
+*آخرین بروزرسانی: ۱۴۰۴/۱۲/۰۸ — فاز ۰-۹d تکمیل (۳۰ کامیت: ۲۰ CMS + ۸ FO + ۶ BO) | NuGet v0.0.188 | باقی‌مانده: تست + deploy*

roadmap/PACKAGE-TRANSFORMATION-UX.md

@@ -0,0 +1,494 @@
+# 🏗️ تحلیل تحول پکیج‌بیس — تاثیر بر تجربه کاربر (UX)
+
+> **وضعیت:** در حال تحلیل  
+> **تاریخ:** ۱۴۰۴/۱۲/۰۶  
+> **پیش‌نیاز:** [BIZ-PACKAGE-BASED-SYSTEM.md](../business/BIZ-PACKAGE-BASED-SYSTEM.md) v2  
+> **هدف:** مستندسازی تاثیر تغییر رویکرد پکیج‌بیس بر تجربه مشتری و ادمین در فرانت‌ها
+
+---
+
+## فهرست
+
+1. [چشم‌انداز کلی](#۱-چشمانداز-کلی)
+2. [تجربه مشتری (FrontOffice) — قبل و بعد](#۲-تجربه-مشتری-frontoffice--قبل-و-بعد)
+3. [تجربه ادمین (BackOffice) — قبل و بعد](#۳-تجربه-ادمین-backoffice--قبل-و-بعد)
+4. [تسک‌های تحول — مرحله‌به‌مرحله](#۴-تسکهای-تحول--مرحلهبهمرحله)
+5. [پیش‌بینی نیازمندی‌های آینده](#۵-پیشبینی-نیازمندیهای-آینده)
+6. [ماتریس تاثیرگذاری بر صفحات](#۶-ماتریس-تاثیرگذاری-بر-صفحات)
+
+---
+
+## ۱. چشم‌انداز کلی
+
+### فلسفه تغییر
+
+| بُعد | **فعلی (تک‌پکیج)** | **هدف (چند‌پکیج)** |
+|------|-------------------|--------------------|
+| **مدل قیمتی** | فقط ۵۶M تومان — "همه یا هیچ" | سطوح متنوع (نقره‌ای ۵.۶M, پایه ۵۶M, ...) — "ورود تدریجی" |
+| **تجربه ورود** | سنگین — کاربر باید ۵۶M بپردازد | سبک — شروع از ۵.۶M و ارتقا بعدی |
+| **چرخه عمر** | یک‌بار خرید → برای همیشه | چند‌بار خرید → هر چرخه Magic Wallet |
+| **فیچرها** | ثابت — همه فیچرها برای همه | پویا — هر پکیج فیچرهای خودش |
+| **کمیسیون** | یک Pool مشترک | Pool جداگانه هر پکیج |
+| **مدیریت** | hardcoded — تغییر = deploy | داینامیک — ادمین از پنل تغییر می‌دهد |
+
+### چه کسانی تاثیر می‌بینند؟
+
+```
+👤 مشتری (FrontOffice):
+    ├── ثبت‌نام‌کننده جدید: گزینه‌های بیشتر → تصمیم‌گیری آسان‌تر
+    ├── مشتری فعال: دکمه "ارتقا" + "خرید مجدد"
+    └── مشتری Magic: نمایش پیشرفت چرخه + آماده‌سازی خرید بعدی
+
+👔 ادمین (BackOffice):
+    ├── مدیر محصول: CRUD پکیج + ماتریس فیچر
+    ├── مدیر مالی: Commission Pool جداگانه + گزارش‌ها
+    └── پشتیبان: فعالسازی دستی با انتخاب پکیج
+```
+
+---
+
+## ۲. تجربه مشتری (FrontOffice) — قبل و بعد
+
+### ۲.۱ صفحه لیست پکیج‌ها (`Packages.razor`)
+
+#### قبل (فعلی):
+```
+┌─────────────────────────────────────────────┐
+│  پکیج طلایی                                  │
+│  ────────────                                 │
+│  ✅ دسترسی به باشگاه مشتریان                  │
+│  ✅ کیف‌پول جادویی                            │
+│  ✅ فروشگاه تخفیفی                            │
+│                                               │
+│  💰 ۵۶,۰۰۰,۰۰۰ تومان                        │
+│                                               │
+│  [خرید پکیج]                                  │
+└─────────────────────────────────────────────┘
+```
+
+#### بعد (پکیج‌بیس):
+```
+┌──────────────────────┐  ┌──────────────────────┐  ┌──────────────────────┐
+│  🥈 پکیج نقره‌ای       │  │  🏆 پکیج پایه         │  │  💎 پکیج ویژه         │
+│  ────────────         │  │  ────────────         │  │  ────────────         │
+│  ✅ باشگاه مشتریان    │  │  ✅ باشگاه مشتریان    │  │  ✅ باشگاه مشتریان    │
+│  ✅ کیف‌پول جادویی    │  │  ✅ کیف‌پول جادویی    │  │  ✅ کیف‌پول جادویی    │
+│  ❌ فروشگاه تخفیفی    │  │  ✅ فروشگاه تخفیفی    │  │  ✅ فروشگاه تخفیفی    │
+│  ❌ پشتیبانی اختصاصی  │  │  ❌ پشتیبانی اختصاصی  │  │  ✅ پشتیبانی اختصاصی  │
+│                        │  │                        │  │                        │
+│  💰 ۵,۶۰۰,۰۰۰ تومان  │  │  💰 ۵۶,۰۰۰,۰۰۰ تومان │  │  💰 ??? تومان          │
+│                        │  │  ⭐ محبوب‌ترین          │  │  🆕 بزودی              │
+│  [خرید]  [جزئیات]      │  │  [خرید]  [جزئیات]      │  │  [در انتظار]            │
+│  ──────────────────    │  │  ──────────────────    │  │  ──────────────────    │
+│  📊 PV: 5,600,000      │  │  📊 PV: 56,000,000     │  │                        │
+│  🎁 هدیه: 11,200,000   │  │  🎁 هدیه: 112,000,000  │  │                        │
+└──────────────────────┘  └──────────────────────┘  └──────────────────────┘
+```
+
+**تغییرات کلیدی:**
+- کاشی‌ها از API می‌آیند (نه hardcoded)
+- فیچرهای هر پکیج از `PackageFeature` خوانده می‌شود
+- نمایش PV (Point Value) برای هر پکیج
+- نمایش Gift Value (= `Price × DiscountMultiplier`)
+- دکمه‌های شرطی: دایا فقط برای پکیج‌های `SupportsDayaPurchase`
+- Badge «محبوب‌ترین» / «ارزان‌ترین» بر اساس `SortOrder`
+
+### ۲.۲ صفحه پکیج‌های من (`MyPackages.razor`)
+
+#### قبل:
+```
+وضعیت عضویت: فعال ✅
+پکیج: طلایی
+تاریخ فعالسازی: ۱۴۰۳/۰۹/۱۵
+```
+
+#### بعد:
+```
+┌─────────────────────────────────────────────────────────────┐
+│  📦 پکیج فعال: پکیج پایه                                    │
+│  ────────────                                                 │
+│  وضعیت: فعال ✅  |  چرخه: ۲  |  مدت: ۱۸۰ روز               │
+│                                                               │
+│  ┌──── کیف‌پول جادویی ────┐                                   │
+│  │  موجودی: ۱۲,۳۰۰,۰۰۰    │                                   │
+│  │  شارژ: ۴۳۵,۰۰۰,۰۰۰     │                                   │
+│  │  سقف: ۱,۰۰۰,۰۰۰,۰۰۰   │                                   │
+│  │  ████████░░░░ ۴۳.۵%     │                                   │
+│  └─────────────────────────┘                                   │
+│                                                               │
+│  ┌──── PV انباشته ────┐                                       │
+│  │  PV کل: ۸۹,۶۰۰,۰۰۰ │                                       │
+│  │  آخرین سفارش: ۴.۲M  │                                       │
+│  └─────────────────────┘                                       │
+│                                                               │
+│  ❌ چرخه جادویی تکمیل نشده — هنوز امکان خرید مجدد نیست       │
+│  ───── یا ─────                                               │
+│  ✅ چرخه جادویی تکمیل شد! [خرید پکیج جدید]                    │
+└─────────────────────────────────────────────────────────────┘
+
+┌─── تاریخچه چرخه‌ها ───┐
+│ چرخه ۱: پایه — ۱۴۰۳/۰۹ تا ۱۴۰۴/۰۳ — ✅ تکمیل │
+│ چرخه ۲: پایه — ۱۴۰۴/۰۳ تا ادامه دارد — 🔄 فعال │
+└────────────────────────┘
+```
+
+**تغییرات کلیدی:**
+- نمایش شماره چرخه و نوع پکیج
+- نوار پیشرفت Magic Wallet (چقدر تا تکمیل چرخه)
+- PV انباشته (از `CalculateOrderPV`)
+- دکمه شرطی «خرید مجدد» (فقط بعد تکمیل چرخه)
+- تاریخچه چرخه‌ها (از `ClubMembershipCycle`)
+
+### ۲.۳ صفحه چک‌اوت (`Checkout.razor`)
+
+#### قبل:
+```
+سبد خرید:
+  محصول A × 2 = ۲,۰۰۰,۰۰۰ تومان
+  مالیات (۹%): ۱۸۰,۰۰۰ تومان
+  ────────────────
+  جمع: ۲,۱۸۰,۰۰۰ تومان
+```
+
+#### بعد:
+```
+سبد خرید:
+  محصول A × 2 = ۲,۰۰۰,۰۰۰ تومان
+  مالیات (۹%): ۱۸۰,۰۰۰ تومان
+  ────────────────
+  جمع: ۲,۱۸۰,۰۰۰ تومان
+  
+  📊 PV این سفارش: ۲,۰۰۰,۰۰۰    ← جدید
+  💎 PV انباشته: ۹۱,۶۰۰,۰۰۰     ← جدید
+```
+
+### ۲.۴ پرداخت پکیج — مودال خرید
+
+#### قبل:
+```
+┌─── خرید پکیج طلایی ───┐
+│                          │
+│  مبلغ: ۵۶,۰۰۰,۰۰۰ تومان │
+│                          │
+│  [پرداخت آنلاین]          │
+│  [اقساط دایا]             │
+│  [پرداخت دستی]            │
+└──────────────────────────┘
+```
+
+#### بعد:
+```
+┌─── خرید پکیج نقره‌ای ───┐      ┌─── خرید پکیج پایه ───┐
+│                            │      │                        │
+│  مبلغ: ۵,۶۰۰,۰۰۰ تومان    │      │  مبلغ: ۵۶,۰۰۰,۰۰۰ تومان│
+│                            │      │                        │
+│  سهم باشگاه: ۲,۵۲۰,۰۰۰    │      │  سهم باشگاه: ۲۵,۲۰۰,۰۰│
+│  شارژ کیف‌پول: ۵,۶۰۰,۰۰۰  │      │  شارژ کیف‌پول: ۵۶,۰۰۰,۰│
+│  هدیه تخفیفی: ۱۱,۲۰۰,۰۰۰  │      │  هدیه تخفیفی: ۱۱۲,۰۰۰,۰│
+│                            │      │                        │
+│  [پرداخت آنلاین] ✅         │      │  [پرداخت آنلاین] ✅      │
+│  [اقساط دایا] ❌ ندارد      │      │  [اقساط دایا] ✅         │
+│  [پرداخت دستی] ✅            │      │  [پرداخت دستی] ✅        │
+└────────────────────────────┘      └────────────────────────┘
+```
+
+**تغییرات کلیدی:**
+- نمایش breakdown مالی: سهم باشگاه + شارژ کیف‌پول + هدیه تخفیفی
+- دکمه‌های پرداخت شرطی بر اساس `SupportsDayaPurchase` / `SupportsDirectPurchase`
+- متن قرارداد داینامیک بر اساس پکیج انتخاب‌شده
+
+### ۲.۵ صفحه تنظیمات مشتری (`Settings.razor`) — جدید
+
+```
+┌─── تنظیمات اعلان‌ها ───┐
+│                          │
+│  📧 اعلان ایمیل:  [✅]    │
+│  📱 اعلان SMS:    [✅]    │
+│  🔔 اعلان Push:   [❌]    │
+│                          │
+│  [ذخیره تغییرات]           │
+└──────────────────────────┘
+```
+> وصل به RPC: `UpdateCustomerSettings`
+
+### ۲.۶ تاریخچه سفارشات — دکمه تکرار
+
+```
+┌─── تاریخچه سفارشات ────────────────────────────────────────┐
+│ # │ تاریخ      │ مبلغ       │ وضعیت     │ PV        │ عملیات │
+│───┼────────────┼────────────┼───────────┼───────────┼────────│
+│ 1 │ ۱۴۰۴/۱۱/۰۲│ ۴,۲۰۰,۰۰۰ │ تحویل ✅  │ ۴,۲۰۰,۰۰ │ [🔄] [📍]│
+│ 2 │ ۱۴۰۴/۱۰/۱۵│ ۱,۸۰۰,۰۰۰ │ ارسال 📦  │ ۱,۸۰۰,۰۰ │      [📍]│
+│ 3 │ ۱۴۰۴/۰۹/۲۰│ ۳,۵۰۰,۰۰۰ │ تحویل ✅  │ ۳,۵۰۰,۰۰ │ [🔄] [📍]│
+└─────────────────────────────────────────────────────────────┘
+
+🔄 = تکرار سفارش (CustomerReorderPreviousOrder)
+📍 = ردیابی سفارش (CustomerTrackOrder)
+```
+
+---
+
+## ۳. تجربه ادمین (BackOffice) — قبل و بعد
+
+### ۳.۱ مدیریت پکیج‌ها (`PackageMainPage.razor`)
+
+#### قبل:
+```
+┌─── مدیریت پکیج‌ها ────────────────────────────────┐
+│ # │ عنوان    │ قیمت        │ وضعیت │ عملیات       │
+│───┼──────────┼─────────────┼───────┼──────────────│
+│ 1 │ طلایی    │ ۵۶,۰۰۰,۰۰۰ │ فعال  │ [ویرایش]     │
+└────────────────────────────────────────────────────┘
+```
+
+#### بعد:
+```
+┌─── مدیریت پکیج‌ها ──────────────────────────────────────────────────────┐
+│ # │ عنوان   │ قیمت        │ سهم باشگاه │ ضریب   │ دایا │ پایه │ ترتیب│ عملیات        │
+│───┼─────────┼─────────────┼────────────┼────────┼──────┼──────┼──────┼───────────────│
+│ 1 │ نقره‌ای  │ ۵,۶۰۰,۰۰۰  │ ۲,۵۲۰,۰۰۰ │ ×2.0  │ ❌   │ ❌   │ 1    │ [✏️] [📋] [❌] │
+│ 2 │ پایه    │ ۵۶,۰۰۰,۰۰۰ │ ۲۵,۲۰۰,۰۰│ ×2.0  │ ✅   │ ✅   │ 2    │ [✏️] [📋] [❌] │
+└──────────────────────────────────────────────────────────────────────────┘
+
+✏️ = ویرایش   📋 = مدیریت فیچرها   ❌ = حذف
+```
+
+### ۳.۲ ماتریس فیچر × پکیج (`PackageFeatureMatrixPage.razor`) — صفحه جدید
+
+```
+┌─── ماتریس فیچر × پکیج ─────────────────────────────────────────┐
+│                                                                   │
+│  فیچر                    │ نقره‌ای │ پایه   │ ویژه              │
+│  ─────────────────────────┼─────────┼────────┼──────────────────│
+│  دسترسی به باشگاه         │   ✅    │   ✅   │   ✅              │
+│  کیف‌پول جادویی           │   ✅    │   ✅   │   ✅              │
+│  فروشگاه عادی             │   ✅    │   ✅   │   ✅              │
+│  فروشگاه تخفیفی           │   ❌    │   ✅   │   ✅              │
+│  محصولات ClubExclusive    │   ❌    │   ✅   │   ✅              │
+│  پشتیبانی اختصاصی         │   ❌    │   ❌   │   ✅              │
+│  کمیسیون شبکه             │   ✅    │   ✅   │   ✅              │
+│  ─────────────────────────┼─────────┼────────┼──────────────────│
+│                            │ [ذخیره] │ [ذخیره]│ [ذخیره]          │
+└─────────────────────────────────────────────────────────────────┘
+
+ادمین با checkbox فیچرها را به هر پکیج اختصاص می‌دهد.
+وصل به RPC: AssignFeatureToMembership
+```
+
+### ۳.۳ فعالسازی باشگاه (`ActivateClubDialog.razor`)
+
+#### قبل:
+```
+فعالسازی باشگاه مشتریان
+  کاربر: علی محمدی
+  [فعالسازی] ← hardcoded 56M + همه فیچرها
+```
+
+#### بعد:
+```
+فعالسازی باشگاه مشتریان
+  کاربر: علی محمدی
+  پکیج: [▼ انتخاب پکیج ▼]          ← dropdown از API
+         ├── نقره‌ای (۵,۶۰۰,۰۰۰)
+         └── پایه (۵۶,۰۰۰,۰۰۰)
+  
+  جزئیات:
+    سهم باشگاه: _________ (خودکار)
+    فیچرها: _________ (از ماتریس پکیج)
+  
+  [فعالسازی]
+```
+
+### ۳.۴ داشبورد (`Index.razor`) — بهبود
+
+```
+┌─── آمار باشگاه ────────────────────────────────────────────────┐
+│                                                                 │
+│  👥 کل اعضا: ۱,۲۴۰                                             │
+│  📦 پکیج نقره‌ای: ۸۲۰  |  پکیج پایه: ۴۲۰                       │
+│  💰 Pool نقره‌ای: ۲,۰۶۶,۴۰۰,۰۰۰  |  Pool پایه: ۱۰,۵۸۴,۰۰۰,۰۰│
+│  ⚠️ هشدار: ۱۲ محصول موجودی کم                                   │
+│                                                                 │
+│  ┌── موجودی انبار ──┐  ┌── ارزش کل انبار ──┐                    │
+│  │  ۳,۴۵۰ آیتم       │  │  ۸۹,۲۰۰,۰۰۰,۰۰۰ │                    │
+│  │  ۱۲ نوع محصول     │  │  ریال              │                    │
+│  └───────────────────┘  └───────────────────┘                    │
+└─────────────────────────────────────────────────────────────────┘
+
+وصل به: GetInventorySummary, GetStockValueReport, GetLowStockProducts
+```
+
+### ۳.۵ مدیریت شبکه (`UserNetworkInfo.razor`) — بهبود
+
+```
+┌─── مدیریت شبکه ─────────────────────────────────────────┐
+│                                                           │
+│  کاربر: سارا احمدی (ID: 1045)                             │
+│  پکیج: نقره‌ای   │   چرخه: ۱   │   PV: ۵,۶۰۰,۰۰۰        │
+│  Parent: علی محمدی (ID: 1001)                             │
+│  شاخه: چپ   │   عمق: ۳                                   │
+│                                                           │
+│  [جابجایی در شبکه] ← مودال: انتخاب parent جدید            │
+│                                                           │
+└───────────────────────────────────────────────────────────┘
+
+وصل به: ChangeNetworkParent
+```
+
+---
+
+## ۴. تسک‌های تحول — مرحله‌به‌مرحله
+
+### مرحله ۱: زیرساخت Domain + DB (پایه)
+
+> ⚠️ **بدون این مرحله هیچ‌کدام از تغییرات UI ممکن نیست**
+
+| # | تسک | لایه | فایل‌ها | شرح |
+|---|------|------|--------|------|
+| T1.1 | اضافه ۷ فیلد به Package entity | Domain | Package.cs, PackageConfiguration.cs | SortOrder, IsActive, IsBasePackage, SupportsDayaPurchase, SupportsDirectPurchase, ActivationFee, DiscountMultiplier, MagicWalletMultiplier |
+| T1.2 | ایجاد PackageFeature entity | Domain | PackageFeature.cs, PackageFeatureConfiguration.cs | join table: Package ↔ ClubFeature |
+| T1.3 | اضافه PackageId به ClubMembership | Domain | ClubMembership.cs | FK nullable → بعد migration → required |
+| T1.4 | اضافه PackageId به ClubMembershipCycle | Domain | ClubMembershipCycle.cs | FK nullable → بعد migration → required |
+| T1.5 | اضافه PackageId به WeeklyCommissionPool | Domain | WeeklyCommissionPool.cs | FK + Unique(WeekDefinitionId, PackageId) |
+| T1.6 | اضافه PackageId به UserCommissionPayout | Domain | UserCommissionPayout.cs | FK nullable |
+| T1.7 | حذف ۵ SystemConstants | Domain | SystemConstants.cs | BasePackageAmount, DayaLoanAmount, ClubActivationFee, ClubMembershipGiftValue, MagicWalletMultiplier |
+| T1.8 | EF Migration + Seed | Infrastructure | Migration file | ۲ پکیج + فیچرها + FKها |
+| T1.9 | Data Migration Script | Infrastructure | SQL script | کاربران فعلی → PackageId = پکیج پایه |
+| T1.10 | بروزرسانی Protoها | Proto | package.proto, clubmembership.proto, commission.proto | فیلدهای جدید |
+
+### مرحله ۲: منطق کسب‌وکار (Handlers)
+
+> **هر handler باید از Package entity مقادیر مالی بخواند**
+
+| # | تسک | فایل | شرح |
+|---|------|------|------|
+| T2.1 | Generic Verify Handler | VerifyPackagePurchaseCommandHandler.cs | DiscountMultiplier از Package + ساخت UserPackagePurchase |
+| T2.2 | Generic Purchase Handler | PurchasePackageCommandHandler.cs | حذف "طلایی" و ID=4 |
+| T2.3 | ActivateClubMembership بهبود | ActivateClubMembershipCommandHandler.cs | فیچر از PackageFeature + ActivationFee از Package |
+| T2.4 | EXIT Magic Mode ریست | UserOrderService.cs | PackagePurchaseMethod=None, membership.IsActive=false |
+| T2.5 | Guards re-purchase | G1-G3 handlers | اجازه خرید اگر MagicCompletedAt پر |
+| T2.6 | Re-contract | AcceptClubMembershipContractCommandHandler.cs | اجازه قرارداد مجدد |
+| T2.7 | Manual Payment بهبود | CreateManualPaymentCommandHandler.cs | DiscountMultiplier از Package |
+| T2.8 | Daya Loan بهبود | CheckAndProcessDayaLoansCommandHandler.cs | حذف ID=4 |
+| T2.9 | PackageFeature CRUD | جدید | ادمین بتواند فیچر ↔ پکیج مدیریت کند |
+| T2.10 | JWT claims جدید | JWT builder | اضافه CanRepurchase + PackageType |
+
+### مرحله ۳: محاسبه پورسانت (Commission)
+
+| # | تسک | فایل | شرح |
+|---|------|------|------|
+| T3.1 | SP WeeklyBalances + PackageId | sp_CalculateWeeklyBalances.sql | فیلتر بر اساس PackageId |
+| T3.2 | SP CommissionPool + PackageId | sp_CalculateWeeklyCommissionPool.sql | Pool جداگانه هر پکیج |
+| T3.3 | Loop روی پکیج‌ها | WeeklyCommissionCalculationService.cs | هر پکیج فعال → محاسبه جداگانه |
+| T3.4 | ORM Strategy بهبود | OrmCommissionCalculationStrategy.cs | فیلتر PackageId |
+| T3.5 | تست محاسبات | — | با داده واقعی staging |
+
+### مرحله ۴: FrontOffice UI
+
+| # | تسک | صفحه | شرح |
+|---|------|------|------|
+| T4.1 | کاشی‌های داینامیک | Packages.razor | لود از API + فیچر مقایسه |
+| T4.2 | مودال پرداخت شرطی | PackageDetail.razor | دکمه دایا فقط اگر SupportsDayaPurchase |
+| T4.3 | MyPackages re-purchase | MyPackages.razor | نوار پیشرفت + دکمه خرید مجدد |
+| T4.4 | ActivationSection داینامیک | ActivationSection.razor | قیمت از پکیج |
+| T4.5 | قرارداد داینامیک | ClubMembershipContractDialog.razor | متن متناسب با پکیج |
+| T4.6 | PV در Checkout | Checkout.razor | نمایش PV سفارش |
+| T4.7 | تکرار سفارش | Store Orders pages | دکمه 🔄 |
+| T4.8 | ردیابی سفارش | OrderTracking.razor | وصل به API |
+| T4.9 | تنظیمات اعلان | Settings.razor | فرم Email/SMS/Push |
+
+### مرحله ۵: BackOffice UI
+
+| # | تسک | صفحه | شرح |
+|---|------|------|------|
+| T5.1 | CRUD پکیج بهبود | PackageMainPage.razor | فیلدهای جدید + ستون‌های اضافه |
+| T5.2 | ماتریس فیچر | PackageFeatureMatrixPage.razor (جدید) | checkbox grid |
+| T5.3 | ActivateClub dropdown | ActivateClubDialog.razor | انتخاب پکیج |
+| T5.4 | داشبورد بهبود | Index.razor | آمار Pool جداگانه + موجودی |
+| T5.5 | شبکه بهبود | UserNetworkInfo.razor | جابجایی parent |
+| T5.6 | موجودی کم | LowStockPage.razor | وصل API |
+| T5.7 | گزارش ارزش انبار | InventoryMainPage.razor | تب گزارش |
+| T5.8 | عملیات دسته‌ای | InventoryMainPage.razor | Bulk Add/Update |
+
+### مرحله ۶: تست و استقرار
+
+| # | تسک | شرح |
+|---|------|------|
+| T6.1 | تست خرید هر پکیج | ZarinPal + Manual |
+| T6.2 | تست re-purchase | تکمیل چرخه → خرید مجدد |
+| T6.3 | تست Commission Pool | جداگانه بودن هر پکیج |
+| T6.4 | تست Migration | rollback plan |
+| T6.5 | Deploy staging → production | blue-green |
+
+---
+
+## ۵. پیش‌بینی نیازمندی‌های آینده
+
+### ۵.۱ نیازمندی‌های مشتری (که فعلاً اولویت پایین هستند)
+
+| # | نیاز | RPC آماده? | توضیح |
+|---|------|-----------|-------|
+| N1 | ارتقای پکیج (نقره‌ای → پایه) | ❌ جدید | پرداخت تفاضل + فعالسازی فیچرهای جدید |
+| N2 | مقایسه پکیج‌ها side-by-side | ❌ جدید | جدول فیچر مقایسه‌ای (client-side) |
+| N3 | اعلان قبل از اتمام چرخه | ❌ جدید | Background service: 5 روز قبل → push/SMS |
+| N4 | گزارش PV ماهانه | CalculateOrderPV ✅ | جدول PV هر ماه + نمودار |
+| N5 | پروفایل شبکه | ❌ جدید | مشتری درخت خودش را ببیند |
+
+### ۵.۲ نیازمندی‌های ادمین (که فعلاً اولویت پایین هستند)
+
+| # | نیاز | RPC آماده? | توضیح |
+|---|------|-----------|-------|
+| N6 | پکیج تخفیفی زمان‌دار | ❌ جدید | پکیج با قیمت ویژه برای مدت محدود |
+| N7 | گزارش تبدیل (conversion) | ❌ جدید | چند نفر از نقره‌ای به پایه ارتقا دادند |
+| N8 | هشدار Pool خالی | ❌ جدید | اگر Pool یک پکیج خالی شد → هشدار |
+| N9 | export گزارش مالی | GetStockValueReport ✅ | دانلود Excel |
+| N10 | تخصیص فیچر bulk | AssignFeatureToMembership ✅ | فیچر به همه اعضای یک پکیج |
+
+---
+
+## ۶. ماتریس تاثیرگذاری بر صفحات
+
+### FrontOffice
+
+| صفحه | تغییر | شدت | مرحله |
+|------|-------|------|-------|
+| Packages.razor | بازنویسی کامل — کاشی‌های داینامیک | 🔴 | مرحله ۴ |
+| PackageDetail.razor | فیچرها از API + دکمه شرطی | 🟡 | مرحله ۴ |
+| MyPackages.razor | چرخه + پیشرفت + re-purchase | 🔴 | مرحله ۴ |
+| Checkout.razor | PV display | 🟢 | مرحله ۴ |
+| ActivationSection.razor | قیمت داینامیک | 🟡 | مرحله ۴ |
+| ClubMembershipContractDialog.razor | متن داینامیک | 🟡 | مرحله ۴ |
+| PaymentCallback.razor | تغییر JWT claims | 🟡 | مرحله ۴ |
+| MembershipPage.razor | نمایش نوع پکیج | 🟢 | مرحله ۴ |
+| Settings.razor | فرم اعلان جدید | 🟡 | مرحله ۴ |
+| Store Orders | دکمه تکرار + ردیابی | 🟡 | مرحله ۴ |
+
+### BackOffice
+
+| صفحه | تغییر | شدت | مرحله |
+|------|-------|------|-------|
+| PackageMainPage.razor | ستون‌های جدید + CRUD بهبود | 🟡 | مرحله ۵ |
+| PackageFeatureMatrixPage.razor | **صفحه کاملاً جدید** | 🔴 | مرحله ۵ |
+| ActivateClubDialog.razor | dropdown پکیج | 🟡 | مرحله ۵ |
+| Index.razor (Dashboard) | آمار Pool جداگانه + موجودی | 🟡 | مرحله ۵ |
+| UserNetworkInfo.razor | جابجایی + نمایش پکیج | 🟡 | مرحله ۵ |
+| ClubMembers.razor | ستون پکیج | 🟢 | مرحله ۵ |
+| Statistics.razor | چارت توزیع پکیج | 🟡 | مرحله ۵ |
+| InventoryMainPage.razor | خلاصه + گزارش + bulk | 🟡 | مرحله ۵ |
+| LowStockPage.razor | وصل API | 🟢 | مرحله ۵ |
+
+---
+
+## 🔗 ارجاعات
+
+| مستند | ربط |
+|-------|-----|
+| [BIZ-PACKAGE-BASED-SYSTEM.md](../business/BIZ-PACKAGE-BASED-SYSTEM.md) | طراحی فنی ۳۹ تغییر |
+| [FEATURE-BACKLOG.md](FEATURE-BACKLOG.md) | بکلاگ ۱۲ RPC آماده |
+| [GRPC-SERVICES-AUDIT.md](../cms/GRPC-SERVICES-AUDIT.md) | آدیت ۳۴۲ RPC |
+| [BUSINESS-01-CLUB-COMMISSION.md](../business/BUSINESS-01-CLUB-COMMISSION.md) | مستند باشگاه و کمیسیون |
+| [BUSINESS-04-USER-MEMBERSHIP.md](../business/BUSINESS-04-USER-MEMBERSHIP.md) | مستند عضویت کاربر |
+
+---
+
+*آخرین بروزرسانی: ۱۴۰۴/۱۲/۰۶*

technical/TECH-01-CMS-ARCHITECTURE.md

@@ -0,0 +1,319 @@
+# ⚙️ معماری CMS و زیرساخت فنی
+
+> **منابع ادغام‌شده:** `CMS-README.md`, `ICURRENTUSERSERVICE-IMPLEMENTATION.md`, `FILE-MANAGEMENT-ARCHITECTURE.md`, `FRONTOFFICE-CMS-API-COMPATIBILITY.md`, `BFF-REMOVAL-PLAN.md`, `system-constants.md`  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: فیکس ZarinPal Verify + Callback URL امنیت + appsettings.Development.json)
+
+---
+
+## ۱. Stack فنی
+
+| لایه | تکنولوژی | نسخه |
+|------|----------|------|
+| **Runtime** | .NET | 9.0 |
+| **ORM** | Entity Framework Core | 9.0 |
+| **Communication** | gRPC (Protobuf) | v3 |
+| **Pattern** | CQRS + MediatR | — |
+| **Database** | SQL Server (MSSQL) | 2022-CU16 |
+| **Job Scheduler** | Hangfire | — |
+| **Auth** | JWT Bearer + Identity | — |
+| **API Gateway** | حذف‌شده (Direct gRPC) | — |
+
+---
+
+## ۲. معماری لایه‌ای CMS
+
+```mermaid
+flowchart TD
+    subgraph PRES["💻 Presentation Layer"]
+        FO["FrontOffice\nBlazor Server"]
+        BO["BackOffice\nBlazor WASM"]
+    end
+
+    FO & BO -->|gRPC| APP
+
+    subgraph APP["⚙️ Application Layer"]
+        CMD["Commands\nMediatR IRequest"]
+        QRY["Queries\nMediatR IRequest"]
+        VAL["Validators\nFluentValidation"]
+        HND["Handlers\nIRequestHandler"]
+    end
+
+    APP --> DOM
+
+    subgraph DOM["📦 Domain Layer"]
+        ENT["Entities, Enums\nValue Objects\nDomain Events"]
+    end
+
+    DOM --> INF
+
+    subgraph INF["🔧 Infrastructure Layer"]
+        EF["EF Core DbContext"]
+        SVC["External Services"]
+        HF["Hangfire Jobs"]
+        FS["File Storage"]
+    end
+
+    INF --> DB[("🗄️ SQL Server\nSchema: CMS")]
+```
+
+---
+
+## ۳. CQRS با MediatR
+
+### ۳.۱ ساختار فولدرها
+
+```
+CMS/src/
+├── CMSMicroservice/
+│   ├── Features/
+│   │   ├── Products/
+│   │   │   ├── Commands/
+│   │   │   │   ├── CreateProductCommand.cs
+│   │   │   │   └── CreateProductCommandHandler.cs
+│   │   │   ├── Queries/
+│   │   │   │   ├── GetProductsQuery.cs
+│   │   │   │   └── GetProductsQueryHandler.cs
+│   │   │   └── Validators/
+│   │   │       └── CreateProductCommandValidator.cs
+│   │   ├── Orders/
+│   │   ├── Users/
+│   │   ├── Club/
+│   │   ├── Payment/
+│   │   └── Blog/
+│   ├── Services/
+│   │   ├── gRPC/          ← gRPC service implementations
+│   │   ├── Background/    ← Hangfire jobs
+│   │   └── External/      ← ZarinPal, Kavenegar, Daya, Chatika
+│   ├── Infrastructure/
+│   │   ├── Persistence/   ← DbContext, Migrations
+│   │   └── Identity/      ← JWT, Claims, ICurrentUserService
+│   └── Protos/            ← .proto files
+```
+
+### ۳.۲ مثال Command
+
+```csharp
+// Command
+public record CreateProductCommand(
+    string Name, string Description, decimal Price,
+    Guid CategoryId, string ImageUrl
+) : IRequest<Guid>;
+
+// Handler
+public class CreateProductCommandHandler 
+    : IRequestHandler<CreateProductCommand, Guid>
+{
+    private readonly CMSDbContext _db;
+    
+    public async Task<Guid> Handle(
+        CreateProductCommand request, CancellationToken ct)
+    {
+        var product = new Product { /* map fields */ };
+        _db.Products.Add(product);
+        
+        // Auto-create inventory record
+        _db.Inventories.Add(new Inventory { ProductId = product.Id });
+        
+        await _db.SaveChangesAsync(ct);
+        return product.Id;
+    }
+}
+```
+
+---
+
+## ۴. gRPC Services
+
+### ۴.۱ لیست سرویس‌ها
+
+| سرویس | proto | متدهای اصلی |
+|--------|-------|-------------|
+| `ProductService` | product.proto | GetProducts, GetProduct, Create, Update, Delete |
+| `OrderService` | order.proto | CreateOrder, GetOrders, UpdateStatus |
+| `UserService` | user.proto | Register, Login, GetProfile, UpdateProfile |
+| `ClubService` | club.proto | GetNetworkTree, GetBalance, AcceptContract |
+| `PaymentService` | payment.proto | CreatePayment, VerifyPayment |
+| `BlogService` | blog.proto | GetPosts, GetPost, Create, Update |
+| `InventoryService` | inventory.proto | GetInventory, UpdateStock |
+| `FileService` | file.proto | Upload, Download, Delete |
+| `SitePageService` | sitepage.proto | GetPage, SaveSettings |
+| `CategoryService` | category.proto | GetCategories, Create, Update |
+| `SystemConfigService` | config.proto | GetConfig, UpdateConfig |
+| `UserWalletService` | userwallet.proto | GetCustomerWallet, InitiateMagicCharge, GetMagicWalletStatus |
+| `UserWalletHistoryService` | userwallethistory.proto | *(renamed from UserWalletChangeLogService)* |
+
+### ۴.۲ PaginationState (مشترک)
+
+```protobuf
+message PaginationState {
+    int32 skip = 1;
+    int32 take = 2;
+}
+```
+
+**Namespace صحیح:**
+```csharp
+using CMSMicroservice.Protobuf.Protos.PaginationState;
+// ⚠️ نه: CMSMicroservice.Protobuf.Protos.PublicMessages.PaginationState
+```
+
+---
+
+## ۵. Database
+
+### ۵.۱ اتصال
+
+```
+Staging:  Server=194.5.195.53; Database=FourSatCMS; Schema=CMS
+Production: Server=45.149.79.127; Database=FourSatCMS; Schema=CMS
+Engine: MSSQL 2022-CU16, Collation=Arabic_CI_AS
+```
+
+### ۵.۲ جداول اصلی
+
+| جدول | توضیح | رکوردهای تقریبی |
+|------|--------|----------------|
+| Users | کاربران + فیلدهای شبکه (NetworkParentId, LegPosition) | ~5K |
+| Products | محصولات (+ MaxDiscountPercent) | ~200 |
+| Categories | دسته‌بندی‌ها | ~30 |
+| Orders | سفارشات | ~2K |
+| Inventories | موجودی | ~200 |
+| BlogPosts | پست‌های بلاگ | ~50 |
+| SitePages | صفحات سایت | ~10 |
+| UserClubMemberships | عضویت باشگاه | ~500 |
+| UserContracts | قراردادها (SignGuid, SignedPdfFile) | ~500 |
+| UserWallets | کیف‌پول (Balance, NetworkBalance, DiscountBalance, WalletMode) | ~5K |
+| ClubMembershipCycles | دوره‌های عضویت (CycleNumber, PackagePurchasedAt, IsCurrentCycle) | ~500 |
+| Transactions | تراکنش‌ها | ~5K |
+| SystemConfigurations | تنظیمات | ~30 |
+| ChatMessages | پیام‌های چاتیکا | ~1K |
+
+### ۵.۳ Stored Procedures
+
+| SP | کاربرد |
+|----|--------|
+| `SP_GetNetworkTree` | بازگشتی — استخراج درخت باینری |
+| `sp_CalculateWeeklyBalances` | محاسبه بالانس هفتگی هر عضو |
+| `sp_CalculateWeeklyCommissionPool` | توزیع Pool هفتگی |
+
+### ۵.۴ SP Auto-Deploy Worker (Q26)
+
+```csharp
+// StoredProcedureDeploymentService : IHostedService
+// در startup:
+// 1. خواندن فایل‌های .sql از embedded resource
+// 2. مقایسه checksum با جدول __SPChecksums
+// 3. فقط SP‌های تغییریافته re-deploy می‌شوند
+```
+
+---
+
+## ۵.۵ History Tracking System (Q27)
+
+### IHasHistory<T> Interface
+
+```csharp
+public interface IHasHistory<THistory> where THistory : BaseAuditableEntity, new()
+{
+    THistory CreateHistorySnapshot(string action, string? performedBy);
+}
+```
+
+### HistoryTrackingSaveChangesInterceptor
+
+- **مکان:** `Infrastructure/Persistence/Interceptors/HistoryTrackingSaveChangesInterceptor.cs`
+- **مکانیسم:** `SaveChangesInterceptor` — قبل از `SaveChanges` اجرا می‌شود
+- **شناسایی:** از `ChangeTracker` entity‌هایی که `IHasHistory<>` پیاده‌سازی کردن (Modified/Added)
+- **Auto-fill:** فیلدهای `Old*` از `entry.OriginalValues` با naming convention (مثلاً `OldPrice` ← `OriginalValues["Price"]`)
+- **Entity‌های فعال:** `Package` → `PackageHistory`
+
+### History Tables
+
+| جدول | Entity مرتبط | فیلدهای Old/New |
+|------|-------------|----------------|
+| `PackageHistories` | Package | Price, ActivationFee, MagicMultiplier, MagicMaxDeposit, MaxBalancesPerLeg, IsActive |
+| `ClubMembershipCycleHistories` | ClubMembershipCycle | IsCurrentCycle, MagicStartedAt, MagicCompletedAt |
+| `UserWalletHistories` | UserWallet | *(renamed from UserWalletChangeLogs — RenameTable migration)* |
+
+---
+
+## ۶. حذف BFF / Gateway
+
+### ۶.۱ قبل vs بعد
+
+```mermaid
+flowchart LR
+    subgraph BEFORE["قبل"]
+        F1["FrontOffice"] -->|REST| BFF1["BFF"]
+        B1["BackOffice"] -->|REST| BFF1
+        BFF1 -->|gRPC| C1["CMS"]
+    end
+
+    subgraph AFTER["بعد — فعلی ✅"]
+        F2["FrontOffice"] -->|gRPC| C2["CMS"]
+        B2["BackOffice"] -->|gRPC| C2
+    end
+```
+
+> مزایا: حذف لایه واسط → کاهش latency • Type-safe از proto تا UI • کاهش ۱ سرویس در deployment
+
+### ۶.۲ سازگاری API
+
+```
+FrontOffice Service Layer:
+    • ProductService.cs → gRPC client wrapper
+    • OrderService.cs → gRPC client wrapper
+    • UserService.cs → gRPC client wrapper
+    
+هر Service:
+    • Constructor: inject GrpcChannel
+    • Methods: wrap gRPC calls + map to DTOs
+    • Error handling: try/catch RpcException
+```
+
+---
+
+## ۷. Hangfire Jobs
+
+| Job | فرکانس (cron) | کاربرد |
+|-----|---------|--------|
+| `WeeklyCommissionCalculation` | `5 0 * * 0` (یکشنبه ۰۰:۰۵) | محاسبه و توزیع کمیسیون |
+| `DayaLoanProcessorJob` | `*/20 * * * *` (هر ۲۰ دقیقه) | پردازش درخواست‌های وام |
+| `ChatikaAccountActivation` | `*/5 * * * *` (هر ۵ دقیقه) | فعال‌سازی حساب چاتیکا |
+
+---
+
+## ۸. پیکربندی
+
+### ۸.۱ appsettings.json ساختار
+
+```json
+{
+    "ConnectionStrings": {
+        "DefaultConnection": "Server=...;Database=FourSatCMS"
+    },
+    "Jwt": {
+        "Secret": "***",
+        "Issuer": "FourSat",
+        "ExpiryMinutes": 1440
+    },
+    "Grpc": {
+        "CmsUrl": "https://localhost:5001"
+    },
+    "Hangfire": {
+        "DashboardPath": "/hangfire",
+        "WorkerCount": 4
+    },
+    "Kavenegar": { "ApiKey": "***" },
+    "ZarinPal": { "MerchantId": "***", "UseSandbox": true },
+    "DayaLoan": { "UseMock": true },
+    "CmsBaseUrl": "https://cms.se.kbs1.ir",
+    "FrontOfficeBaseUrl": "http://localhost:5268"
+}
+```
+
+> **⚠️ نکات مهم appsettings:**
+> - `CmsBaseUrl` — برای callback URL‌های درگاه (شارژ کیف‌پول جادویی/اعتباری)
+> - `FrontOfficeBaseUrl` — برای redirect بعد پرداخت (خرید پکیج/تراکنش عمومی)
+> - `appsettings.Development.json` — URL‌های localhost برای توسعه محلی
+> - همه callback URL‌ها از config خوانده می‌شوند — هیچ URL از ورودی کاربر نمی‌آید (امنیت Open Redirect)

technical/TECH-02-BACKOFFICE-FRONTOFFICE.md

@@ -0,0 +1,274 @@
+# 🖥️ 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`  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: فیکس‌های پرداخت Phase 11 + صفحه موفقیت + تومان/ریال + امنیت Callback)
+
+---
+
+## ۱. 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  ← 🪄 کیف‌پول جادویی
+│   │   └── PaymentCallback.razor ← 💳 صفحه نتیجه پرداخت (TransactionId + موجودی واقعی)
+│   ├── 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
+    ├── PackagePurchaseDialog.razor ← دیالوگ ۲-مرحله‌ای خرید پکیج (NEW)
+    └── 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% |
+| PackagePurchaseDialog | ✅ | 100% |
+| Toman/Rial فیکس نمایش قیمت | ✅ | 100% |
+| صفحه نتیجه پرداخت (PaymentCallback) | ✅ | 100% |
+| امنیت Callback URL | ✅ | 100% |
+| Mobile Responsive (Phase 7) | ⬜ | 0% |
+| Dark Mode | ⬜ | 0% |
+| PWA | ⬜ | 0% |

technical/TECH-03-DEPLOYMENT-INFRA.md

@@ -0,0 +1,540 @@
+# 🚀 استقرار، CI/CD و زیرساخت
+
+> **منابع ادغام‌شده:** `CICD-PIPELINE-GUIDE.md`, `DEPLOYMENT-README.md`, `INFRASTRUCTURE-GUIDE.md`, `INGRESS-NGINX-WARNING.md`, `OFFLINE-DEPLOYMENT-GUIDE.md`, `SERVER-MIRRORS-CONFIG.md`  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: فیکس URL پروداکشن + چری‌پیک فیکس‌های WalletChangeLog/Validation/Expiry)
+
+---
+
+## ۱. سرورها
+
+| سرور | IP | نقش | منابع |
+|------|-----|------|--------|
+| **Staging** | 194.5.195.53 | توسعه + تست | 4 CPU, 8GB RAM |
+| **Production** | 45.149.79.127 | محیط نهایی | 4 CPU, 16GB RAM |
+| **Git** | git.se.kbs1.ir | Gitea (مخازن کد) | — |
+| **Registry** | داخلی | Docker Registry / Nexus | — |
+
+---
+
+## ۲. Docker و Container
+
+### ۲.۱ سرویس‌ها
+
+```yaml
+# docker-compose.yml (production)
+services:
+  cms:
+    image: foursat/cms:latest
+    ports: ["5001:5001"]           # gRPC
+    environment:
+      - ConnectionStrings__Default=Server=db;Database=FourSatCMS
+      - ASPNETCORE_ENVIRONMENT=Production
+    depends_on: [db]
+    
+  backoffice:
+    image: foursat/backoffice:latest
+    ports: ["5002:80"]             # Static Blazor WASM
+    
+  frontoffice:
+    image: foursat/frontoffice:latest
+    ports: ["5003:5003"]           # Blazor Server
+    
+  db:
+    image: mcr.microsoft.com/mssql/server:2022-CU16-ubuntu-22.04
+    ports: ["1433:1433"]
+    volumes: ["sqldata:/var/opt/mssql"]
+    
+  nexus:                           # NuGet + Docker registry
+    image: sonatype/nexus3
+    ports: ["8081:8081"]
+
+volumes:
+  sqldata:
+```
+
+### ۲.۲ Dockerfile (CMS)
+
+```dockerfile
+FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS base
+WORKDIR /app
+EXPOSE 5001
+
+FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
+WORKDIR /src
+COPY ["CMSMicroservice/CMSMicroservice.csproj", "CMSMicroservice/"]
+RUN dotnet restore
+COPY . .
+RUN dotnet publish -c Release -o /app/publish
+
+FROM base AS final
+COPY --from=build /app/publish .
+ENTRYPOINT ["dotnet", "CMSMicroservice.dll"]
+```
+
+---
+
+## ۳. Kubernetes
+
+### ۳.۱ Manifests ساختار
+
+مانیفست‌های K8s **داخل ریپوی CMS** نگهداری می‌شن و توسط CI/CD اعمال می‌شن:
+
+```
+CMS/
+  k8s/
+    staging/
+      cms-config.yaml            ← K8s Secret (appsettings.Staging.json)
+      cms-deployment.yaml        ← PVC + Deployment + Service + Ingress
+    production/
+      cms-config.yaml            ← K8s Secret (appsettings.Production.json)
+      cms-deployment.yaml        ← PVC + Deployment + Service + Ingress
+```
+
+> ⚠️ **هر دو محیط از namespace `default` استفاده می‌کنن.**
+
+### ۳.۲ PersistentVolume برای آپلود فایل
+
+فایل‌های آپلود‌شده (عکس محصولات، بلاگ، آواتار و ...) در `/app/Uploads` ذخیره می‌شن.  
+برای جلوگیری از حذف فایل‌ها با ریستارت Pod، یک **PersistentVolumeClaim** مونت شده:
+
+```yaml
+# PVC — 20Gi ذخیره‌سازی دائمی
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: cms-uploads-pvc
+  namespace: default
+spec:
+  accessModes: [ReadWriteOnce]
+  resources:
+    requests:
+      storage: 20Gi
+```
+
+```yaml
+# Volume Mount در Deployment
+volumeMounts:
+- name: cms-uploads
+  mountPath: /app/Uploads
+volumes:
+- name: cms-uploads
+  persistentVolumeClaim:
+    claimName: cms-uploads-pvc
+```
+
+| تنظیم | مقدار |
+|--------|-------|
+| **PVC Name** | `cms-uploads-pvc` |
+| **Mount Path** | `/app/Uploads` |
+| **Access Mode** | `ReadWriteOnce` |
+| **حجم** | `20Gi` |
+| **StorageClass** | `local-path` (K3s default) |
+| **Replicas** | `1` (محدودیت RWO) |
+
+> 💡 **نکته مهم:** چون `ReadWriteOnce` هست، فقط **1 replica** می‌تونه بنویسه. برای 2+ replica نیاز به NFS/CephFS با `ReadWriteMany` هست.
+
+### ۳.۳ تنظیمات محیطی (K8s Secret)
+
+تنظیمات حساس (ConnectionString, Email, SMS, ZarinPal) **در K8s Secret** نگهداری می‌شن — نه داخل Docker image.  
+فایل `appsettings.{Environment}.json` از Secret به `/app/` مونت می‌شه و .NET اون رو override می‌خونه.
+
+```mermaid
+flowchart LR
+    S["K8s Secret<br/>cms-appsettings"] -->|volumeMount| F["/app/appsettings.*.json"]
+    F --> D[".NET reads config"]
+    I["Docker Image<br/>appsettings.json (base)"] --> D
+```
+
+| محیط | `ASPNETCORE_ENVIRONMENT` | فایل Config (از Secret) |
+|------|---------------------------|-------------|
+| **Staging** | `Staging` | `appsettings.Staging.json` |
+| **Production** | `Production` | `appsettings.Production.json` |
+
+**Secret manifest** (`cms-config.yaml`):
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: cms-appsettings
+  namespace: default
+type: Opaque
+stringData:
+  appsettings.Staging.json: |   # یا appsettings.Production.json
+    { "ConnectionStrings": { ... }, "ZarinPal": { ... }, ... }
+```
+
+**Volume mount در Deployment:**
+```yaml
+volumeMounts:
+- name: cms-config
+  mountPath: /app/appsettings.Staging.json
+  subPath: appsettings.Staging.json
+  readOnly: true
+volumes:
+- name: cms-config
+  secret:
+    secretName: cms-appsettings
+```
+
+env var‌های K8s manifest (فقط environment و URL):
+```yaml
+env:
+- name: ASPNETCORE_ENVIRONMENT
+  value: "Staging"           # یا "Production"
+- name: ASPNETCORE_URLS
+  value: "http://+:8080"
+```
+
+> 💡 **تغییر config بدون deploy:** `kubectl edit secret cms-appsettings && kubectl rollout restart deployment/cms`
+
+### ۳.۴ مثال Deployment (واقعی)
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: cms
+  namespace: default
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: cms
+  template:
+    spec:
+      containers:
+      - name: cms
+        image: 194.5.195.53:30080/admin/cms:latest
+        imagePullPolicy: Always
+        ports:
+        - containerPort: 8080
+        env:
+        - name: ASPNETCORE_ENVIRONMENT
+          value: "Staging"
+        - name: ASPNETCORE_URLS
+          value: "http://+:8080"
+        volumeMounts:
+        - name: cms-uploads
+          mountPath: /app/Uploads
+        - name: cms-config
+          mountPath: /app/appsettings.Staging.json
+          subPath: appsettings.Staging.json
+          readOnly: true
+        resources:
+          requests: { memory: "512Mi", cpu: "500m" }
+          limits:   { memory: "1Gi",   cpu: "1000m" }
+      volumes:
+      - name: cms-uploads
+        persistentVolumeClaim:
+          claimName: cms-uploads-pvc
+      - name: cms-config
+        secret:
+          secretName: cms-appsettings
+```
+
+### ۳.۵ Ingress
+
+**Staging:**
+```yaml
+spec:
+  ingressClassName: nginx
+  rules:
+  - host: cms.se.kbs1.ir
+```
+
+**Production:**
+```yaml
+spec:
+  ingressClassName: nginx
+  tls:
+  - hosts: [cms.kbs1.ir, cms.kbs2.ir]
+    secretName: cms-tls
+  rules:
+  - host: cms.kbs2.ir
+  - host: cms.kbs1.ir
+```
+
+> ⚠️ **هشدار:** از `spec.ingressClassName: nginx` استفاده کنید، نه `kubernetes.io/ingress.class` annotation (deprecated).
+
+### ۳.۶ جداسازی appsettings در Git
+
+هر برنچ فقط فایل config مربوط به محیط خودش رو داره:
+
+| برنچ | `appsettings.json` | `appsettings.Staging.json` | `appsettings.Production.json` |
+|------|---|---|---|
+| `kub-stage` | ✅ | ✅ | ❌ حذف شده |
+| `production` | ✅ | ❌ حذف شده | ✅ |
+
+**چرا؟** چون config اصلی از K8s Secret میاد (`cms-config.yaml`)، فایل‌های محیط دیگه داخل ایمیج اضافی و گمراه‌کننده‌ان.  
+همچنین وقتی merge/cherry-pick می‌کنید، فایل config محیط دیگه دیگه conflict ایجاد نمی‌کنه.
+
+> ⚠️ **کامیت‌های حذف فایل config رو هرگز cherry-pick نکنید به برنچ دیگه!**  
+> `e72673c` (حذف Production از staging) و `3ebe0f9` (حذف Staging از production)
+
+### ۳.۷ خلاصه: چه چیزهایی دائمی هستند (مستقل از ایمیج)
+
+| چه چیزی | مکانیزم K8s | محل Mount |
+|---------|-------------|------------|
+| **فایل‌های آپلود** (عکس، آواتار، ...) | `PersistentVolumeClaim` | `/app/Uploads` |
+| **تنظیمات اپلیکیشن** (DB, SMS, IPG, ...) | `Secret` (`cms-appsettings`) | `/app/appsettings.{Env}.json` |
+
+---
+
+## ۴. CI/CD Pipeline
+
+### ۴.۱ Gitea Actions Workflows (CMS)
+
+فایل‌های پایپلاین:
+```
+CMS/.gitea/workflows/
+├── kub-deploy.yml       ← Staging (branch: kub-stage)
+├── prod-deploy.yml      ← Production (branch: production)
+└── cms-stage.yml        ← قدیمی (IIS روی Windows — غیرفعال)
+```
+
+### ۴.۲ فلوی Staging (`kub-deploy.yml`)
+
+```mermaid
+flowchart TD
+    A["Push to kub-stage"] --> B["Start Docker daemon"]
+    B --> C["Clone repo"]
+    C --> D["Pack & Push Proto NuGet"]
+    D --> E["Docker build → tag :latest"]
+    E --> F["Push to 194.5.195.53:30080"]
+    F --> G["SCP cms-config.yaml + cms-deployment.yaml"]
+    G --> H["kubectl apply -f cms-config.yaml (Secret)"]
+    H --> I["kubectl apply -f cms-deployment.yaml"]
+    I --> J["kubectl rollout restart"]
+    J --> K["✅ Deployed to Staging"]
+```
+
+### ۴.۳ فلوی Production (`prod-deploy.yml`)
+
+```mermaid
+flowchart TD
+    A["Push to production"] --> B["Start Docker daemon"]
+    B --> C["Clone repo"]
+    C --> D["Pack & Push Proto NuGet"]
+    D --> E["Docker build → tag :sha + :prod"]
+    E --> F["Push to 194.5.195.53:30080"]
+    F --> G["SCP cms-config.yaml + cms-deployment.yaml"]
+    G --> H["kubectl apply -f cms-config.yaml (Secret)"]
+    H --> I["kubectl apply -f cms-deployment.yaml"]
+    I --> J["kubectl set image → sha"]
+    J --> K["✅ Deployed to Production"]
+```
+
+### ۴.۴ شاخه‌ها و محیط‌ها
+
+| شاخه | محیط | سرور | Image Tag | Deploy |
+|------|------|------|-----------|--------|
+| `kub-stage` | Staging | 194.5.195.53 | `:latest` | Auto |
+| `production` | Production | 45.149.79.127 | `:sha` + `:prod` | Auto |
+
+### ۴.۵ نکات مهم CI/CD
+
+- **Proto NuGet:** هر deploy ابتدا proto packages رو build و به Nexus push می‌کنه
+- **Manifest apply:** پایپلاین ابتدا `cms-config.yaml` (Secret) رو apply می‌کنه، بعد `cms-deployment.yaml`  
+  → Secret + PVC + Deployment + Service + Ingress هر بار اعمال می‌شه
+- **Image registry:** `194.5.195.53:30080` (داخلی Nexus) — نه `git.se.kbs1.ir`
+- **Config دائمی:** تنظیمات در K8s Secret هست، نه داخل Docker image — تغییر config بدون rebuild ایمیج ممکنه
+- **جداسازی برنچ:** هر برنچ فقط appsettings محیط خودش رو داره (بخش ۳.۶)
+
+---
+
+## ۵. استقرار آفلاین (Offline Deployment)
+
+### ۵.۱ فلوی آماده‌سازی
+
+```mermaid
+flowchart TD
+    subgraph ONLINE["🌐 سرور اینترنت‌دار"]
+        A1["pull-base-images.sh\nدانلود Docker images"] --> A2["cache-nuget-packages.sh\nدانلود NuGet packages"]
+        A2 --> A3["save-images.sh\nذخیره تصاویر به tar"]
+        A3 --> A4["بسته‌بندی"]
+    end
+
+    A4 -->|"💾 انتقال فیزیکی\nUSB / HDD"| B1
+
+    subgraph OFFLINE["🔒 سرور آفلاین"]
+        B1["load-images.sh\nبارگذاری تصاویر"] --> B2["setup-nexus-complete.sh\nراه‌اندازی Nexus"]
+        B2 --> B3["build-all-offline.sh\nبیلد با Nexus محلی"]
+        B3 --> B4["k8s-deploy.sh\nاستقرار در K8s"]
+    end
+```
+
+### ۵.۲ اسکریپت‌های کلیدی
+
+| اسکریپت | کاربرد |
+|----------|--------|
+| `pull-base-images.sh` | دانلود ۱۵+ Docker image پایه |
+| `save-images.sh` | Export به tar (4-8 GB) |
+| `load-images.sh` | Import از tar به Docker |
+| `cache-nuget-packages.sh` | دانلود NuGet offline |
+| `setup-nexus-complete.sh` | راه‌اندازی NuGet proxy |
+| `build-all-offline.sh` | بیلد بدون اینترنت |
+| `k8s-deploy.sh` | Deploy تمام سرویس‌ها |
+| `k8s-health-check.sh` | بررسی سلامت سرویس‌ها |
+
+---
+
+## ۶. Nexus Repository Manager
+
+### ۶.۱ نقش
+
+```mermaid
+graph TD
+    NEXUS["Nexus داخلی"] --> NP["NuGet proxy\ncache nuget.org"]
+    NEXUS --> NH["NuGet hosted\nبسته‌های proto داخلی"]
+    NEXUS --> DP["Docker proxy\ncache Docker Hub"]
+    NEXUS --> DH["Docker hosted\nتصاویر داخلی FourSat"]
+```
+
+### ۶.۲ NuGet.config
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <packageSources>
+    <add key="nexus" value="http://localhost:8081/repository/nuget-group/index.json" />
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+  </packageSources>
+</configuration>
+```
+
+---
+
+## ۷. Mirror و Cache
+
+### ۷.۱ Docker Mirror
+
+```json
+// /etc/docker/daemon.json
+{
+    "registry-mirrors": [
+        "https://mirror.gcr.io",
+        "https://docker.arvancloud.ir"
+    ],
+    "insecure-registries": [
+        "localhost:8082"
+    ]
+}
+```
+
+### ۷.۲ NuGet Mirror
+
+```
+Primary: nuget.org
+Fallback: Nexus local proxy
+Proto packages: BaGet (internal) at http://localhost:5555
+```
+
+---
+
+## ۸. Proto Packages (NuGet)
+
+### ۸.۱ فلوی بسته‌بندی
+
+```mermaid
+flowchart TD
+    A["CMS/src/Protos/*.proto"] --> B["pack-protos.sh\ndotnet pack → .nupkg"]
+    B --> C["Push to BaGet / Nexus"]
+    C --> D["BackOffice + FrontOffice\ndotnet restore → مصرف proto"]
+```
+
+### ۸.۲ نام بسته
+
+```xml
+<PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="1.0.x" />
+```
+
+---
+
+## ۹. مانیتورینگ و Health Check
+
+### ۹.۱ مرج پروداکشن (اسفند ۱۴۰۴)
+
+| ریپو | شاخه مبدأ | commit | نکات |
+|------|------------|--------|------|
+| **CMS** | `kub-stage` → `production` | `eb1b249` | حل conflict در `appsettings.Production.json` + حذف migration تکراری `u21` |
+| **FrontOffice** | `kub-stage` → `production` | `f02d082` | 21 فایل، 400 insertion + فیکس GwUrl به `cms.kbs2.ir` |
+| **BackOffice** | `kub-stage` → `production` | `bdea2e8` | 36 فایل، بدون conflict |
+
+### ۹.۲ کامیت‌های PVC و اصلاحات K8s (تیر ۱۴۰۴)
+
+| commit | شرح |
+|--------|------|
+| `3153fd8` | feat: add PersistentVolume for CMS uploads + apply manifests in CI/CD |
+| `68da3f4` | fix: staging uses namespace default, not foursat |
+| `e41747a` | fix: production ingress — add cms.kbs2.ir, use ingressClassName |
+| `2d6c95e` | fix: use local registry 194.5.195.53:30080 instead of git.se.kbs1.ir |
+| `f8dc4ab` | fix: staging ASPNETCORE_ENVIRONMENT=Staging, remove secretKeyRef |
+| `de83c31` | fix: production uses namespace default + remove foursat namespace references |
+| `9288d06` | feat: externalize appsettings to K8s Secret — config persists independently |
+| `e72673c` | chore(staging): remove appsettings.Production.json (فقط kub-stage) |
+| `3ebe0f9` | chore(production): remove appsettings.Staging.json (فقط production) |
+| `f3ac5ad` | fix: add missing UserWalletChangeLog for discount shop purchases |
+| `0457ef6` | fix: validate discount wallet balance before applying discount |
+| `e206b71` | fix: reduce discount order expiry from 30 to 15 minutes |
+| `2620a24` | fix: correct production URLs from kbs1 to kbs2 in cms-config |
+
+> کامیت‌های PVC و Secret به هر دو شاخه push شده‌اند.  
+> ⚠️ کامیت‌های حذف appsettings فقط به برنچ مربوطه push شده — cherry-pick نکنید!
+
+### ۹.۳ فیکس URL پروداکشن (اسفند ۱۴۰۴)
+
+> **مشکل:** در `cms-config.yaml` پروداکشن، URL‌ها به اشتباه `kbs1.ir` (استیج) بودند.
+> زرین‌پال callback را به سرور استیج می‌فرستاد → خطای 401 → `Code=-1` (خطای ناشناخته).
+
+| فیلد | مقدار اشتباه | مقدار صحیح |
+|------|-------------|------------|
+| `CmsBaseUrl` | `https://cms.kbs1.ir` | `https://cms.kbs2.ir` |
+| `FrontOfficeBaseUrl` | `https://kbs1.ir` | `https://kbs2.ir` |
+
+```bash
+# فیکس مستقیم روی سرور (بدون نیاز به rebuild)
+kubectl apply -f cms-config.yaml
+kubectl rollout restart deployment/cms
+```
+
+### ۹.۴ نام‌گذاری کیف‌پول‌ها (اسفند ۱۴۰۴)
+
+> تغییر عنوان کیف‌پول‌ها در تمام UI (FrontOffice: 5 فایل، BackOffice: 7 فایل):
+
+| فیلد | نام قدیم | نام جدید |
+|------|---------|----------|
+| `Balance` | عادی / نقدی | **کیف پول اصلی** |
+| `DiscountBalance` | تخفیفی / تخفیف | **کیف پول اعتباری** |
+| `NetworkBalance` | شبکه / طلایی | **پاداش تیمی** |
+
+**تنظیمات محیطی Production (`appsettings.Production.json`):**
+
+| تنظیم | مقدار |
+|--------|-------|
+| `ZarinPal.MerchantId` | `4225d555-5fa9-4df0-9b61-1ce152cbbba8` |
+| `ZarinPal.UseSandbox` | `false` |
+| `CmsBaseUrl` | `https://cms.kbs2.ir` |
+| `FrontOfficeBaseUrl` | `https://kbs2.ir` |
+| `SeedWorkers.MagicWalletCycleSeed.Enabled` | `true` |
+| `Kestrel.Endpoints.Grpc.Protocols` | `Http2` |
+| `Seq.ServerUrl` | `http://seq-svc:5341` |
+| `ConnectionStrings.Default` | `Server=mssql-svc;Database=KBS` |
+
+> ⚠️ **مهم:** URL‌ها باید `kbs2.ir` باشند نه `kbs1.ir` — اشتباه در URL باعث خطای 401 زرین‌پال می‌شود.
+
+```bash
+# k8s-health-check.sh  (namespace = default)
+kubectl get pods
+kubectl top pods
+kubectl logs deployment/cms --tail=50
+
+# بررسی PVC
+kubectl get pvc cms-uploads-pvc
+kubectl exec deployment/cms -- ls /app/Uploads | wc -l
+
+# تست سرویس‌ها
+grpcurl -plaintext localhost:5001 list                    # لیست سرویس‌ها
+grpcurl -plaintext localhost:5001 grpc.health.v1.Health/Check  # Health
+curl http://localhost:5002/index.html                      # BackOffice
+curl http://localhost:5003/                                 # FrontOffice
+```

technical/TECH-04-MIGRATION.md

@@ -0,0 +1,258 @@
+# 🔄 مهاجرت داده، BFF و Gateway
+
+> **منابع ادغام‌شده:** `BACKOFFICE-BFF-MIGRATION.md`, `customer-facing-capabilities-codex.md`, `DATA-TABLE-MAPPINGS.md`, `DATAMIGRATION-README.md`, `FRONTOFFICE-TO-CMS-MIGRATION.md`, `GATEWAY-REMOVAL-MIGRATION-PLAN.md`, `MIGRATION-PROGRESS.md`  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: DataMigration Tool + EF Staging Migrations)
+
+---
+
+## ۱. تاریخچه مهاجرت‌ها
+
+```
+Timeline:
+    ▸ فاز ۱: FrontOffice REST → CMS gRPC (مستقیم)
+    ▸ فاز ۲: BackOffice REST → CMS gRPC (مستقیم)
+    ▸ فاز ۳: حذف BFF/Gateway
+    ▸ فاز ۴: حذف API Gateway (Ocelot)
+    ▸ فاز ۵: یکپارچه‌سازی Proto packages
+    ▸ فاز ۶: Data migration از سیستم قدیم
+```
+
+---
+
+## ۲. حذف BFF (Backend-for-Frontend)
+
+### ۲.۱ قبل
+
+```mermaid
+flowchart LR
+    FO1["FrontOffice"] -->|HTTP/REST| BFF["BFF"]
+    BO1["BackOffice"] -->|HTTP/REST| BFF
+    BFF -->|gRPC| CMS1["CMS"]
+```
+
+**BFF مسئولیت‌ها:** تبدیل REST↔gRPC • Aggregation • Auth proxy • Rate limiting
+
+### ۲.۲ بعد (فعلی)
+
+```mermaid
+flowchart LR
+    FO2["FrontOffice"] -->|gRPC| CMS2["CMS مستقیم"]
+    BO2["BackOffice"] -->|gRPC| CMS2
+```
+
+**مزایا:** ✅ حذف ۱ سرویس • کاهش ~50ms latency • Type-safety از proto تا UI • ساده‌سازی debug
+
+### ۲.۳ مراحل مهاجرت
+
+```
+مرحله ۱: ایجاد gRPC client wrappers در FrontOffice
+    ProductService.cs → _client.GetProductsAsync(request)
+    OrderService.cs → _client.GetOrdersAsync(request)
+    ...
+
+مرحله ۲: جایگزینی HttpClient با GrpcChannel
+    services.AddGrpcClient<ProductServiceClient>(o => {
+        o.Address = new Uri(config["Grpc:CmsUrl"]);
+    });
+
+مرحله ۳: حذف BFF project
+    - حذف BFF از solution
+    - حذف BFF از docker-compose
+    - حذف BFF از K8s manifests
+
+مرحله ۴: تست end-to-end
+    - تست هر صفحه FrontOffice
+    - تست هر صفحه BackOffice
+    - Performance benchmark
+```
+
+---
+
+## ۳. حذف API Gateway (Ocelot)
+
+### ۳.۱ قبل
+
+```mermaid
+flowchart LR
+    CL1["Client"] --> NG1["nginx"] --> OC["Ocelot Gateway"]
+    OC --> CMS3["CMS"]
+    OC --> BFF2["BFF"]
+    OC --> FS1["FileService"]
+```
+
+### ۳.۲ بعد
+
+```mermaid
+flowchart LR
+    CL2["Client"] --> NG2["nginx"] --> ING["K8s Ingress"]
+    ING --> CMS4["CMS"]
+    ING --> BO3["BackOffice"]
+    ING --> FO3["FrontOffice"]
+```
+
+### ۳.۳ دلایل حذف
+
+```
+✅ Ocelot maintenance burden → حذف
+✅ K8s Ingress → routing بومی
+✅ Let's Encrypt → TLS بومی
+✅ gRPC → type-safe بدون نیاز به gateway
+```
+
+---
+
+## ۴. FrontOffice to CMS Migration
+
+### ۴.۱ Service Mapping
+
+| FrontOffice Service | BFF Endpoint (حذف‌شده) | CMS gRPC Service |
+|--------------------|-----------------------|-------------------|
+| `ProductService` | `GET /api/products` | `ProductService.GetProducts` |
+| `OrderService` | `POST /api/orders` | `OrderService.CreateOrder` |
+| `UserService` | `POST /api/auth/login` | `UserService.Login` |
+| `ClubService` | `GET /api/club/tree` | `ClubService.GetNetworkTree` |
+| `BlogService` | `GET /api/blog/posts` | `BlogService.GetPosts` |
+| `PaymentService` | `POST /api/payment/create` | `PaymentService.CreatePayment` |
+| `FileService` | `POST /api/files/upload` | `FileService.Upload` |
+| `SitePageService` | `GET /api/pages/{type}` | `SitePageService.GetPage` |
+
+### ۴.۲ DTO Mapping
+
+```
+BFF DTOs (حذف‌شده) → Proto Messages (فعلی)
+    ProductDto → ProductMessage
+    OrderDto → OrderMessage
+    UserDto → UserMessage
+    
+Proto-generated classes مستقیم در UI استفاده می‌شوند
+یا به local DTOs map می‌شوند (برای UI-specific fields)
+```
+
+---
+
+## ۵. Data Migration (سیستم قدیم → جدید)
+
+### ۵.۱ پروژه DataMigration
+
+```
+DataMigration/
+├── FourSat.DataMigration/      ← Console app (.NET 9 + Dapper + Polly + Serilog)
+│   ├── Program.cs              ← Entry point
+│   ├── appsettings.json        ← Source/Target connection strings + TruncateTargetTables
+│   ├── Services/
+│   │   └── MigrationService.cs ← Smart retry, FK disable/enable, fallback table names
+│   ├── Scripts/
+│   │   └── PostMigration_DataTransformation.sql ← Guardشده با IF COL_LENGTH/OBJECT_ID
+│   └── Mappings/
+│       └── TableMappings.cs    ← Source → Target table/column mappings
+└── FourSat.GeographySeeder/    ← Seed geography data
+    ├── Program.cs
+    └── Data/
+        ├── provinces.json
+        └── cities.json
+```
+
+### ۵.۱.۱ ویژگی‌های DataMigration Tool (اسفند ۱۴۰۴)
+
+| ویژگی | توضیح |
+|--------|--------|
+| **Smart Retry** | فقط خطاهای transient SQL (deadlock, timeout, transport) — نه خطاهای منطقی |
+| **FK Disable/Enable** | `ALTER TABLE NOCHECK/CHECK CONSTRAINT ALL` حول هر مهاجرت |
+| **TruncateTargetTables** | حل duplicate key (`IX_ClubMembership_UserId`) هنگام re-run |
+| **Fallback Table Name** | اگر جدول rename شده (`UserWalletChangeLogs` → `UserWalletHistories`) |
+| **PostMigration Guards** | همه مراحل با `IF COL_LENGTH`/`OBJECT_ID` برای سازگاری با هر دو schema |
+| **Polly Retry** | exponential backoff (2s, 8s, 32s) + لاگ structured |
+| **Serilog** | لاگ فایل + کنسول با جزئیات هر جدول |
+
+> **کامیت‌ها:** `0e8c6fd` → `8385c90` (MERGE fix) → `31cc464` (FK+truncate+PostMigration)
+> **وضعیت:** Local only — بدون remote (در workspace `DataMigration/` قرار دارد)
+
+### ۵.۲ Data Table Mappings
+
+| جدول مبدأ (قدیم) | جدول مقصد (CMS) | نکات |
+|------------------|-----------------|------|
+| `dbo.Users` | `CMS.Users` | PhoneNumber as primary identifier |
+| `dbo.Products` | `CMS.Products` | ImageUrl migration needed |
+| `dbo.Orders` | `CMS.Orders` | Status enum remapping |
+| `dbo.Categories` | `CMS.Categories` | Hierarchical → ParentId |
+| `dbo.NetworkTree` | `CMS.Users` | Binary tree via NetworkParentId + LegPosition روی User |
+| `dbo.Wallets` | `CMS.UserWallets` | ۳ wallet types: Balance, NetworkBalance, DiscountBalance |
+| `dbo.Transactions` | `CMS.Transactions` | Type enum remapping |
+| `dbo.Memberships` | `CMS.UserClubMemberships` | + Contract creation |
+
+### ۵.۳ SQL Scripts مهاجرت
+
+| اسکریپت | کاربرد |
+|----------|--------|
+| `MigrateUsersToClubMembership.sql` | انتقال همه کاربران |
+| `MigrateSpecificUsersToClubMembership.sql` | انتقال انتخابی |
+| `ChargeUserWallets.sql` | شارژ اولیه کیف‌پول‌ها |
+| `AddIsActiveToUserClubFeatures.sql` | افزودن فیلد IsActive |
+| `SeedSitePages.sql` | داده اولیه صفحات سایت |
+| `SystemConfigurations.sql` | مقادیر پیش‌فرض تنظیمات |
+| `populate-weekly-commission-pools.sql` | داده تاریخی Pool |
+| `update_products_price_10_percent.sql` | افزایش قیمت ۱۰% |
+
+### ۵.۴ Migrationهای EF Core اجراشده روی Production/Staging (اسفند ۱۴۰۴)
+
+| Migration | توضیح | DB |
+|-----------|--------|----||
+| `ExpandDiscountProductFullInformation` | گسترش فیلدهای محصول تخفیفی | KBS (Production `45.149.79.127`) |
+| `AddMagicWalletFields` (u21) | فیلدهای کیف‌پول جادویی + ClubMembershipCycle | KBS (Production) |
+| ۵۵ migration کامل | از Initial تا `Q27_HistoryTables_And_RenameWalletHistory` | KBS Staging (`185.252.31.42,2019/KBS`) |
+| ۵۵ migration کامل | از Initial تا `Q27_HistoryTables_And_RenameWalletHistory` | App DB (`194.5.195.53,31433/Foursat`) |
+
+> ✅ **نکته:** CMS به ۲ DB مختلف وصل می‌شود — هر دو باید migrate شوند.
+> ✅ Migration `u21` در زمان merge تکراری بود — فایل تکراری حذف شد.
+
+---
+
+## ۶. Geography Seeder
+
+```
+FourSat.GeographySeeder:
+    • ۳۱ استان
+    • ~۱۲۰۰ شهر
+    • منبع: دیتای رسمی تقسیمات کشوری
+    • فرمت: JSON → EF Core Seed
+    
+استفاده:
+    dotnet run --project FourSat.GeographySeeder
+```
+
+---
+
+## ۷. Customer-Facing Capabilities Codex
+
+### ۷.۱ خلاصه (بزرگ‌ترین سند — ۵,۳۰۰ خط)
+
+این سند شامل مستندسازی کامل تمام قابلیت‌های کاربرمحور سیستم است:
+
+| بخش | محتوا |
+|------|--------|
+| **User Journey** | فلوی کامل از ثبت‌نام تا خرید |
+| **Store Features** | لیست محصول، فیلتر، سبد، پرداخت |
+| **Club Features** | عضویت، درخت، کمیسیون، قرارداد |
+| **Content** | بلاگ، صفحات، SEO |
+| **Admin Features** | مدیریت محصول، سفارش، کاربر |
+| **Integration** | Chatika، ZarinPal، Kavenegar، Daya |
+| **Mobile** | Responsive، PWA (planned) |
+
+---
+
+## ۸. وضعیت مهاجرت
+
+| مهاجرت | وضعیت | درصد |
+|--------|--------|------|
+| FrontOffice BFF → gRPC | ✅ | 100% |
+| BackOffice BFF → gRPC | ✅ | 100% |
+| API Gateway حذف | ✅ | 100% |
+| Data Migration (Users) | ✅ | 100% |
+| Data Migration (Products) | ✅ | 100% |
+| Data Migration (Orders) | ✅ | 100% |
+| Data Migration (Club/Network) | ✅ | 100% |
+| Geography Seeder | ✅ | 100% |
+| Proto package unification | ✅ | 100% |
+| EF Migration پروداکشن | ✅ | 100% |
+| DataMigration Tool (Prod→Staging) | ✅ | 100% |
+| EF Migration استیجینگ (KBS + Foursat) | ✅ | 100% |

technical/TECH-05-API-INTEGRATION.md

@@ -0,0 +1,329 @@
+# 🔌 API، Protobuf و یکپارچه‌سازی خارجی
+
+> **منابع ادغام‌شده:** `FRONTOFFICE-CMS-API-COMPATIBILITY.md`, `REMAINING-TASKS.md`, `chatika-integration.md`, `payment-gateway.md`, `club-feature-management-services.md`  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet gRPC RPCs)
+
+---
+
+## ۱. معماری ارتباطات
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                    External Services                              │
+│  ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌─────────┐              │
+│  │ ZarinPal│ │ Kavenegar│ │ DayaLoan│ │ Chatika │              │
+│  │ (IPG)   │ │ (SMS)    │ │ (Loan)  │ │ (AI)    │              │
+│  └────┬────┘ └────┬─────┘ └────┬────┘ └────┬────┘              │
+│       │           │            │            │                    │
+│  ┌────▼───────────▼────────────▼────────────▼────┐              │
+│  │              CMS Microservice                  │              │
+│  │    (gRPC Server + Hangfire + EF Core)          │              │
+│  └────────────────┬───────────────────────────────┘              │
+│                   │ gRPC (Protobuf v3)                           │
+│       ┌───────────┼───────────┐                                  │
+│  ┌────▼────┐ ┌────▼────┐                                        │
+│  │BackOffice│ │FrontOffice│                                      │
+│  │(Blazor  │ │(Blazor   │                                       │
+│  │ WASM)   │ │ Server)  │                                       │
+│  └─────────┘ └──────────┘                                       │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ۲. gRPC Proto Definitions
+
+### ۲.۱ لیست کامل سرویس‌ها
+
+```protobuf
+// ===== product.proto =====
+service ProductService {
+    rpc GetProducts (GetProductsRequest) returns (GetProductsResponse);
+    rpc GetProductById (GetProductByIdRequest) returns (ProductMessage);
+    rpc CreateProduct (CreateProductRequest) returns (CreateProductResponse);
+    rpc UpdateProduct (UpdateProductRequest) returns (UpdateProductResponse);
+    rpc DeleteProduct (DeleteProductRequest) returns (Empty);
+    rpc GetProductsPaged (GetProductsPagedRequest) returns (GetProductsPagedResponse);
+}
+
+// ===== order.proto =====
+service OrderService {
+    rpc CreateOrder (CreateOrderRequest) returns (CreateOrderResponse);
+    rpc GetOrders (GetOrdersRequest) returns (GetOrdersResponse);
+    rpc GetOrderById (GetOrderByIdRequest) returns (OrderMessage);
+    rpc UpdateOrderStatus (UpdateOrderStatusRequest) returns (Empty);
+}
+
+// ===== user.proto =====
+service UserService {
+    rpc Register (RegisterRequest) returns (AuthResponse);
+    rpc Login (LoginRequest) returns (AuthResponse);
+    rpc GetProfile (GetProfileRequest) returns (UserProfileMessage);
+    rpc UpdateProfile (UpdateProfileRequest) returns (Empty);
+    rpc SendOtp (SendOtpRequest) returns (SendOtpResponse);
+    rpc VerifyOtp (VerifyOtpRequest) returns (VerifyOtpResponse);
+}
+
+// ===== club.proto =====
+service ClubService {
+    rpc GetNetworkTree (GetNetworkTreeRequest) returns (NetworkTreeResponse);
+    rpc GetBalance (GetBalanceRequest) returns (BalanceResponse);
+    rpc ReadContract (ReadContractRequest) returns (ContractResponse);
+    rpc RequestContractOtp (RequestOtpRequest) returns (OtpResponse);
+    rpc VerifyContractOtp (VerifyOtpRequest) returns (VerifyOtpResponse);
+    rpc AcceptContract (AcceptContractRequest) returns (AcceptContractResponse);
+    rpc GetClubFeatures (GetFeaturesRequest) returns (FeaturesResponse);
+}
+
+// ===== payment.proto =====
+service PaymentService {
+    rpc CreatePayment (CreatePaymentRequest) returns (CreatePaymentResponse);
+    rpc VerifyPayment (VerifyPaymentRequest) returns (VerifyPaymentResponse);
+    rpc GetPaymentStatus (PaymentStatusRequest) returns (PaymentStatusResponse);
+}
+
+// ===== blog.proto =====
+service BlogService {
+    rpc GetPosts (GetPostsRequest) returns (GetPostsResponse);
+    rpc GetPostBySlug (GetPostBySlugRequest) returns (BlogPostMessage);
+    rpc CreatePost (CreatePostRequest) returns (CreatePostResponse);
+    rpc UpdatePost (UpdatePostRequest) returns (Empty);
+    rpc DeletePost (DeletePostRequest) returns (Empty);
+}
+
+// ===== inventory.proto =====
+service InventoryService {
+    rpc GetInventory (GetInventoryRequest) returns (InventoryMessage);
+    rpc UpdateStock (UpdateStockRequest) returns (Empty);
+    rpc GetAllInventories (GetAllRequest) returns (InventoryListResponse);
+}
+
+// ===== sitepage.proto =====
+service SitePageService {
+    rpc GetPage (GetPageRequest) returns (SitePageMessage);
+    rpc SaveSettings (SaveSettingsRequest) returns (Empty);
+    rpc GetAllPages (Empty) returns (PageListResponse);
+}
+
+// ===== file.proto =====
+service FileService {
+    rpc Upload (stream UploadRequest) returns (UploadResponse);
+    rpc Download (DownloadRequest) returns (stream DownloadResponse);
+    rpc Delete (DeleteFileRequest) returns (Empty);
+}
+
+// ===== category.proto =====
+service CategoryService {
+    rpc GetCategories (GetCategoriesRequest) returns (CategoryListResponse);
+    rpc CreateCategory (CreateCategoryRequest) returns (CreateCategoryResponse);
+    rpc UpdateCategory (UpdateCategoryRequest) returns (Empty);
+}
+
+// ===== config.proto =====
+service SystemConfigService {
+    rpc GetConfig (GetConfigRequest) returns (ConfigResponse);
+    rpc UpdateConfig (UpdateConfigRequest) returns (Empty);
+    rpc GetAllConfigs (Empty) returns (ConfigListResponse);
+}
+
+// ===== userwallet.proto ===== (NEW — Magic Wallet)
+service UserWalletService {
+    rpc GetCustomerWallet (GetCustomerWalletRequest) returns (GetCustomerWalletResponse);
+    rpc InitiateMagicCharge (InitiateMagicChargeRequest) returns (InitiateMagicChargeResponse);
+    rpc GetMagicWalletStatus (GetMagicWalletStatusRequest) returns (MagicWalletStatusResponse);
+}
+```
+
+### ۲.۲ Shared Messages
+
+```protobuf
+// ===== common.proto =====
+message PaginationState {
+    int32 skip = 1;
+    int32 take = 2;
+}
+
+message PaginatedResponse {
+    int32 totalCount = 1;
+    int32 pageSize = 2;
+    int32 currentPage = 3;
+}
+
+message Empty {}
+```
+
+---
+
+## ۳. External Service Integration
+
+### ۳.۱ ZarinPal (پرداخت)
+
+```csharp
+public class ZarinPalService : IPaymentGateway
+{
+    // Config
+    private readonly string _merchantId;
+    private readonly bool _isSandbox;
+    
+    // Endpoints
+    const string PAYMENT_URL = "https://api.zarinpal.com/pg/v4/payment/request.json";
+    const string VERIFY_URL = "https://api.zarinpal.com/pg/v4/payment/verify.json";
+    const string SANDBOX_URL = "https://sandbox.zarinpal.com/pg/v4/payment/request.json";
+    
+    // Flow
+    // 1. CreatePayment → Authority token
+    // 2. Redirect → https://www.zarinpal.com/pg/StartPay/{Authority}
+    // 3. Callback → VerifyPayment(Authority, Amount)
+    // 4. Result → RefID (reference number)
+}
+```
+
+### ۳.۲ Kavenegar (SMS)
+
+```csharp
+public class KavenegarService : ISmsService
+{
+    // Templates — فقط یک تمپلیت در کد موجود است
+    const string OTP_TEMPLATE = "Afrino";  // تنها تمپلیت استفاده‌شده
+    // Sender: "1000001110100"
+    
+    // Rate Limiting
+    // ۱ SMS per phone per 60 seconds
+    // ۵ SMS per phone per hour
+    // ۲۰ SMS per phone per day
+    
+    public async Task SendOtpAsync(string phone, string code)
+    {
+        await _api.VerifyLookup(phone, code, OTP_TEMPLATE);
+    }
+}
+```
+
+### ۳.۳ Daya Loan (وام)
+
+```csharp
+public class DayaLoanService : ILoanService
+{
+    // Hangfire job — هر ۲۰ دقیقه (*/20 * * * *)
+    // Polly retry: 3 attempts, exponential backoff (2s, 4s, 8s)
+    // Mock mode for staging (auto-approve)
+    
+    public async Task<LoanResult> RequestLoanAsync(Guid userId, decimal amount)
+    {
+        if (_options.UseMock)
+            return LoanResult.Approved(amount);
+            
+        var response = await _httpClient.PostAsync(
+            $"{_baseUrl}/api/loans/request",
+            new { UserId = userId, Amount = amount });
+        
+        return MapResponse(response);
+    }
+}
+```
+
+### ۳.۴ Chatika (AI)
+
+```csharp
+public class ChatikaService : IAiChatService
+{
+    // Hangfire job — هر ۵ دقیقه
+    // Polly retry: 3 attempts
+    // Only for active club members
+    
+    public async Task<string> GetResponseAsync(string userMessage)
+    {
+        var response = await _httpClient.PostAsync(
+            $"{_baseUrl}/api/chat",
+            new { Message = userMessage });
+        
+        return response.Content.ReadAsStringAsync();
+    }
+}
+```
+
+---
+
+## ۴. API Compatibility Layer
+
+### ۴.۱ FrontOffice Service Pattern
+
+```csharp
+// هر سرویس در FrontOffice یک wrapper بر gRPC client است
+public class ProductService : IProductService
+{
+    private readonly ProductServiceClient _client;
+    
+    public ProductService(ProductServiceClient client)
+    {
+        _client = client;
+    }
+    
+    public async Task<ProductListResult> GetProductsPagedAsync(
+        int skip, int take, Guid? categoryId = null, string? search = null)
+    {
+        try
+        {
+            var request = new GetProductsPagedRequest {
+                Pagination = new PaginationState { Skip = skip, Take = take },
+                CategoryId = categoryId?.ToString() ?? "",
+                SearchTerm = search ?? ""
+            };
+            
+            var response = await _client.GetProductsPagedAsync(request);
+            
+            return new ProductListResult(
+                response.Products.Select(MapToDto).ToList(),
+                response.TotalCount);
+        }
+        catch (RpcException ex) when (ex.StatusCode == StatusCode.Unavailable)
+        {
+            // CMS is down — show cached data or error
+            throw new ServiceUnavailableException("CMS service unavailable");
+        }
+    }
+}
+```
+
+### ۴.۲ Error Handling
+
+| gRPC Status | HTTP Equivalent | Handling |
+|------------|-----------------|----------|
+| `OK` | 200 | Return data |
+| `NotFound` | 404 | Show "not found" message |
+| `InvalidArgument` | 400 | Show validation errors |
+| `Unauthenticated` | 401 | Redirect to login |
+| `PermissionDenied` | 403 | Show "access denied" |
+| `Unavailable` | 503 | Show "service down" |
+| `Internal` | 500 | Show generic error |
+
+---
+
+## ۵. Proto Package Distribution
+
+```mermaid
+flowchart TD
+    A["CMS/src/Protos/*.proto"] --> B["pack-protos.sh"]
+    B --> C["Foursat.CMSMicroservice.Protobuf.nupkg\nv1.0.x"]
+    C --> D["Push to BaGet / Nexus"]
+    D --> E["BackOffice\nPackageReference"]
+    D --> F["FrontOffice\nProjectReference ✅"]
+```
+
+> ⚠️ FrontOffice از NuGet package به **ProjectReference** مستقیم سوییچ شده (برای دسترسی به پروتوهای جدید Magic Wallet)
+
+---
+
+## ۶. Remaining Tasks / Integration Gaps
+
+| آیتم | اولویت | وضعیت |
+|------|---------|--------|
+| Product Bundle API | Medium | ⬜ Proto + Handler needed |
+| Manual Payment API | Low | ⬜ Design only |
+| SignalR for Chatika | Low | ⬜ Replace polling |
+| File upload streaming | Done | ✅ |
+| Blog search | Done | ✅ |
+| Inventory autocomplete | Done | ✅ |
+| Lazy load pagination | Done | ✅ |
+| Rate limiting (API level) | Medium | ⬜ |
+| API versioning | Low | ⬜ |

technical/TECH-06-CLUB-POOL-CHARGE-FLOW.md

@@ -0,0 +1,246 @@
+# TECH-06 — جریان شارژ Pool کمیسیون هفتگی
+
+> تاریخ: ۱۴۰۵/۰۲/۱۰  
+> وضعیت: **باگ شناسایی‌شده — منتظر Fix**  
+> مرتبط با: `ActivateClubMembershipCommandHandler.cs` · `AcceptClubMembershipContractCommandHandler.cs` · `CreateManualPaymentCommandHandler.cs`
+
+---
+
+## ۱. مسیر مشتری جدید (اولین خرید پکیج)
+
+```mermaid
+sequenceDiagram
+    actor U as کاربر (FrontOffice)
+    participant CB as PaymentCallback.razor
+    participant PI as Profile/Index.razor
+    participant CD as ClubMembershipContractDialog
+    participant CMS as CMS (gRPC)
+
+    U->>CB: بازگشت از درگاه<br/>?type=package&orderId=X&Authority=Y
+    CB->>CMS: CustomerVerifyPackagePurchase(orderId, authority)
+
+    Note over CMS: PackageService.VerifyPackagePurchase()
+    CMS->>CMS: تأیید با درگاه ✓
+    CMS->>CMS: ActivateClubMembership(ForceActivation=false)
+
+    Note over CMS: isNewMembership = true
+    CMS->>CMS: ClubMembership(IsActive=false) ایجاد
+    CMS->>CMS: ClubMembershipCycle #1 ایجاد
+    CMS->>CMS: ⚡ Pool += ActivationFee  ← شارژ اول ❌
+
+    CMS-->>CB: Success=true
+    CB->>CB: RefreshToken<br/>HasPurchasedPackage=true<br/>IsClubMemberActive=false
+
+    U->>PI: کلیک "بازگشت به پروفایل"
+    PI->>PI: OnAfterRenderAsync<br/>CheckAndShowClubContractModal()
+
+    Note over PI: HasPurchasedPackage=true<br/>AND IsClubMemberActive=false → نمایش مودال
+
+    PI->>CD: DialogService.ShowAsync (غیرقابل بستن)
+    U->>CD: مطالعه قرارداد + درخواست OTP
+    CD->>CMS: CreateNewOtpToken(purpose=signClubContract)
+    CMS-->>CD: OTP ارسال شد
+    U->>CD: وارد کردن OTP ۶ رقمی
+    CD->>CMS: AcceptClubMembershipContract(otp, signGuid)
+
+    Note over CMS: AcceptClubMembershipContractCommandHandler
+    CMS->>CMS: IsActive == false → guard رد می‌شه ✓
+    CMS->>CMS: IsActive = true
+    CMS->>CMS: ⚡ Pool += ActivationFee  ← شارژ دوم ❌
+
+    CMS-->>CD: Success=true
+    CD->>PI: dialog.Close(Ok)
+    PI->>PI: LoadUserAuthInfo → IsClubMemberActive=true
+```
+
+> **نتیجه**: Pool برای عضو جدید **۲ برابر** شارژ می‌شود.
+
+---
+
+## ۲. مسیر خرید مجدد (بعد از تکمیل چرخه Magic)
+
+```mermaid
+sequenceDiagram
+    actor U as کاربر (FrontOffice)
+    participant CB as PaymentCallback.razor
+    participant PI as Profile/Index.razor
+    participant CMS as CMS (gRPC)
+
+    Note over CMS: وضعیت: IsActive=true<br/>IsCurrentCycle=true (باگ B6 — ریست نشده)
+
+    U->>CB: بازگشت از درگاه (خرید مجدد)
+    CB->>CMS: CustomerVerifyPackagePurchase(orderId, authority)
+
+    CMS->>CMS: ActivateClubMembership(ForceActivation=false)
+    Note over CMS: isNewMembership = false<br/>existingMembership.IsActive=true<br/>hasCurrentCycle=true
+
+    CMS->>CMS: return true زودهنگام ❌
+
+    Note over CMS: Cycle جدید ساخته نمی‌شه ❌<br/>Pool شارژ نمی‌شه ❌
+
+    CMS-->>CB: Success=true
+    CB->>CB: RefreshToken → IsClubMemberActive=true
+
+    U->>PI: بازگشت به پروفایل
+    PI->>PI: IsClubMemberActive=true<br/>→ مودال نمایش داده نمی‌شه ✓
+
+    Note over PI,CMS: Pool هرگز شارژ نشد ❌<br/>Cycle جدید وجود ندارد ❌
+```
+
+> **نتیجه**: Pool برای خرید مجدد **هرگز** شارژ نمی‌شود. ریشه مشکل: باگ B6 — `IsCurrentCycle` هنگام خروج از Magic ریست نمی‌شود.
+
+---
+
+## ۳. مسیر ادمین (BackOffice — فعال‌سازی دستی)
+
+```mermaid
+sequenceDiagram
+    actor A as ادمین (BackOffice)
+    participant DL as ActivateClubDialog.razor
+    participant CMS as CMS (gRPC)
+
+    A->>DL: باز کردن دیالوگ فعال‌سازی برای کاربر X
+    DL->>DL: انتخاب UserId و PackageId
+    A->>DL: کلیک "تایید و فعال‌سازی"
+
+    DL->>CMS: ActivateClubMembership(UserId=X, ForceActivation=true)
+    Note over CMS: ActivateClubMembershipCommandHandler<br/>skip همه validation‌های مالی
+
+    alt کاربر جدید (isNewMembership=true)
+        CMS->>CMS: ClubMembership(IsActive=false) ایجاد
+        CMS->>CMS: Cycle #1 ایجاد
+        CMS->>CMS: ⚡ Pool += ActivationFee  ← شارژ اول ❌
+        Note over CMS: کاربر هنوز عضو فعال نیست!<br/>IsActive=false
+
+        Note over A,CMS: کاربر باید به FO رود و قرارداد امضا کند
+        Note over A,CMS: AcceptContract → Pool += fee  ← شارژ دوم ❌
+    else خرید مجدد (isNewMembership=false، IsCurrentCycle ریست شده)
+        CMS->>CMS: IsActive=true, hasCurrentCycle=false → ادامه می‌دهد
+        CMS->>CMS: Cycle جدید ایجاد
+        CMS->>CMS: ⚡ Pool += ActivationFee  ← شارژ یک بار ✅
+    end
+
+    CMS-->>DL: Empty (success)
+    DL->>A: "عضویت با موفقیت فعال شد"
+    Note over A,CMS: AcceptContract از BO هرگز فراخوانی نمی‌شود
+```
+
+> **نتیجه**: ادمین برای کاربر جدید نیز باعث double-charge می‌شود (چون کاربر بعداً از FO قرارداد امضا می‌کند). برای خرید مجدد رفتار درست است.
+
+---
+
+## ۵. خلاصه باگ‌ها
+
+| سناریو | Pool شارژ واقعی | Pool شارژ انتظاری | Cycle ساخته می‌شود | وضعیت |
+|--------|----------------|-------------------|--------------------|--------|
+| مشتری جدید (IPG) | **2×fee** | 1×fee | ✅ بله | ❌ Double-charge |
+| خرید مجدد مشتری | **0×fee** | 1×fee | ❌ خیر (B6) | ❌ هرگز شارژ نمی‌شود |
+| ادمین — ForceActivate کاربر جدید | **2×fee** | 1×fee | ✅ بله | ❌ Double-charge |
+| ادمین — ForceActivate خرید مجدد | **1×fee** | 1×fee | ✅ بله | ✅ درست |
+| ادمین — ManualPayment (پرداخت دستی) | **1×fee** | 1×fee | ❌ خیر | ⚠️ Pool درست، ولی والدین امتیاز نمی‌گیرند |
+
+---
+
+## ۵. ریشه مشکلات
+
+### باگ A — Double-charge در عضو جدید
+**فایل**: `ActivateClubMembershipCommandHandler.cs` — بخش Pool (خط ~۳۱۱)  
+**علت**: هنگامی که `isNewMembership=true`، Pool شارژ می‌شود؛ بعداً `AcceptContract` هم Pool را شارژ می‌کند.  
+**Fix**: شارژ Pool در `ActivateClubMembership` را فقط برای `!isNewMembership` انجام بده:
+
+```csharp
+// ⭐ 8. اضافه کردن مبلغ به Pool هفته جاری
+// عضو جدید: Pool توسط AcceptClubMembershipContract شارژ می‌شه (هنگام امضای قرارداد)
+// خرید مجدد: قرارداد مجدد امضا نمی‌شه — Pool همین‌جا شارژ می‌شه
+if (!isNewMembership)
+{
+    // ... کد موجود شارژ Pool ...
+}
+```
+
+### باگ B6 — خرید مجدد کار نمی‌کند
+**فایل**: `UserOrderService.cs` — بخش خروج از Magic  
+**علت**: هنگام خروج از Magic، `cycle.IsCurrentCycle` به `false` ریست نمی‌شود → `ActivateClubMembership` با `hasCurrentCycle=true` زودهنگام برمی‌گردد.  
+**Fix**: در `ExitMagicMode`:
+```csharp
+cycle.IsCurrentCycle = false;  // ← اضافه شود
+```
+
+### باگ C — پرداخت دستی: Cycle هرگز ساخته نمی‌شود
+**فایل**: `CreateManualPaymentCommandHandler.cs`  
+**علت**: پرداخت دستی `ActivateClubMembership` را صدا نمی‌زند → هیچ `ClubMembershipCycle` ساخته نمی‌شود → SP این کاربر را به عنوان "عضو جدید" برای والدینش حساب نمی‌کند.  
+**تأثیر**: Pool یک‌بار شارژ می‌شود (توسط AcceptContract ✓) ولی balance والدین در sp_CalculateWeeklyBalances افزایش نمی‌یابد (چون Cycle ندارد ❌).
+
+---
+
+## ۴. مسیر پرداخت دستی (BackOffice — ManualPayment)
+
+```mermaid
+sequenceDiagram
+    actor A as ادمین (BackOffice)
+    participant DL as ManualPaymentDialog.razor
+    participant CMS as CMS (gRPC)
+    actor U as کاربر (FrontOffice)
+    participant PI as Profile/Index.razor
+    participant CD as ClubMembershipContractDialog
+
+    A->>DL: باز کردن دیالوگ پرداخت دستی
+    DL->>DL: انتخاب کاربر + پکیج + نوع پرداخت + تصویر رسید
+    A->>DL: کلیک "ثبت پرداخت"
+
+    DL->>CMS: CreateManualPayment(userId, packageId, type, referenceNumber)
+    Note over CMS: CreateManualPaymentCommandHandler
+
+    CMS->>CMS: Transaction(DepositExternal1) ایجاد
+    CMS->>CMS: ManualPayment(Status=Approved) ایجاد ← بدون نیاز به تایید دو مرحله
+    CMS->>CMS: wallet.Balance += package.Price
+    CMS->>CMS: wallet.DiscountBalance += package.Price × DiscountMultiplier
+    CMS->>CMS: user.PackagePurchaseMethod = DirectPurchase
+
+    Note over CMS: ❌ ActivateClubMembership صدا زده نمی‌شود<br/>❌ ClubMembershipCycle ساخته نمی‌شود<br/>❌ Pool شارژ نمی‌شود
+
+    CMS-->>DL: ManualPaymentId
+    DL->>A: "پرداخت دستی با موفقیت ثبت شد"
+
+    Note over A,U: کاربر باید به FO مراجعه کند
+    U->>PI: ورود به پروفایل
+    PI->>PI: OnAfterRenderAsync → CheckAndShowClubContractModal()
+    Note over PI: HasPurchasedPackage=true (PackagePurchaseMethod=DirectPurchase)<br/>IsClubMemberActive=false → نمایش مودال
+
+    PI->>CD: DialogService.ShowAsync (غیرقابل بستن)
+    U->>CD: امضای قرارداد + OTP
+    CD->>CMS: AcceptClubMembershipContract(otp, signGuid)
+
+    Note over CMS: AcceptClubMembershipContractCommandHandler
+    CMS->>CMS: user.ClubMembership == null → isNewMembership = true
+    CMS->>CMS: ClubMembership(IsActive=true) ایجاد
+    CMS->>CMS: ⚡ Pool += ActivationFee  ← شارژ یک‌بار ✅
+
+    Note over CMS: ❌ ClubMembershipCycle هرگز ساخته نمی‌شود<br/>(AcceptContract از Cycle خبری ندارد)
+
+    CMS-->>CD: Success=true
+    CD->>PI: dialog.Close(Ok)
+```
+
+> **نتیجه**:
+> - Pool: **1×** شارژ می‌شود ✅ (درست)
+> - `ClubMembershipCycle`: **هرگز ساخته نمی‌شود** ❌
+> - در `sp_CalculateWeeklyBalances`: کاربر `IsActive=true` دارد → خودش می‌تواند کمیسیون دریافت کند ✅
+> - ولی والدین این کاربر **هیچ "عضو جدید" برای این هفته دریافت نمی‌کنند** ❌ (چون SP از `ClubMembershipCycles.PackagePurchasedAt` می‌خواند)
+
+---
+
+## ۶. validation داشبورد کمیسیون
+
+پس از رفع باگ A، validation باید از **فقط یک منبع** استفاده کند:
+
+```csharp
+// درست: فقط ClubMembershipCycles.PackagePurchasedAt
+// این جدول برای هر خرید (چه جدید چه مجدد) یک رکورد دارد
+var activations = await _context.ClubMembershipCycles
+    .CountAsync(c => c.PackageId == packageId
+        && c.PackagePurchasedAt >= weekDef.StartDate
+        && c.PackagePurchasedAt < weekDef.EndDate);
+```
+
+> قبل از رفع باگ A، validation فعلی (firstActivations + cycleActivations) تصادفاً با double-charge جبران می‌شد.

technical/TECH-07-SESSION-LOG-20260430.md

@@ -0,0 +1,334 @@
+# TECH-07 — لاگ کامل Session 1404/02/10 (2026-04-30)
+
+> نوع سند: **گزارش کار**  
+> تاریخ: ۱۴۰۵/۰۲/۱۰  
+> مرتبط با: CMS · BackOffice · FrontOffice · Database
+
+---
+
+## فهرست مطالب
+
+1. [بخش اول — رفع باگ Double-Charge Pool](#۱-رفع-باگ-double-charge-pool)
+2. [بخش دوم — بررسی داده‌های هفته‌های ۲۲ و ۲۳](#۲-بررسی-داده‌های-هفته‌های-۲۲-و-۲۳)
+3. [بخش سوم — ویژگی Network Tree (اطلاعات هفتگی)](#۳-ویژگی-network-tree-نوع-فعالسازی--پکیج)
+4. [بخش چهارم — بهبود UI نمودار درختی](#۴-بهبود-ui-نمودار-درختی)
+5. [بخش پنجم — رفع باگ Pagination فروشگاه تخفیف](#۵-رفع-باگ-pagination-فروشگاه-تخفیف)
+6. [خلاصه فایل‌های تغییریافته](#خلاصه-فایل‌های-تغییریافته)
+7. [وظایف باقی‌مانده (Pending)](#وظایف-باقی‌مانده)
+
+---
+
+## ۱. رفع باگ Double-Charge Pool
+
+### مشکل
+در جریان فعال‌سازی عضویت باشگاه، Pool کمیسیون هفتگی **دوبار** شارژ می‌شد:
+- بار اول: در `ActivateClubMembership` (از طریق `VerifyPackagePurchase`)
+- بار دوم: در `AcceptClubMembershipContract` (تأیید قرارداد توسط کاربر)
+
+همچنین `CreateManualPayment` هم یک مسیر مستقل داشت که بدون Check هفته، Pool اشتباه را شارژ می‌کرد.
+
+### ریشه مشکل
+تابع `GetOrCreateCurrentWeeklyPool` بدون در نظر گرفتن هفته واقعی `PackagePurchasedAt`، Pool هفته جاری را انتخاب می‌کرد.
+
+### فایل‌های اصلاح‌شده
+
+#### `ActivateClubMembershipCommandHandler.cs`
+```csharp
+// قبل: همیشه Pool هفته جاری را شارژ می‌کرد
+// بعد: فقط یک‌بار در محل صحیح (AcceptContract) شارژ می‌شود
+// حذف: شارژ Pool از داخل ActivateClubMembership (for isNewMembership scenario)
+```
+
+#### `AcceptClubMembershipContractCommandHandler.cs`
+```csharp
+// اضافه: بررسی هفته قرارداد — اگر هفته PackagePurchasedAt با هفته جاری فرق دارد
+// از Pool هفته مناسب استفاده می‌کند نه Pool هفته جاری
+```
+
+#### `CreateManualPaymentCommandHandler.cs`
+```csharp
+// اصلاح: Cross-week fix — Pool هفته صحیح بر اساس تاریخ پرداخت دستی
+```
+
+#### `sp_CalculateWeeklyCommissionPool.sql` (SP در Infrastructure)
+```sql
+-- اصلاح: IsCurrentCycle check برای جلوگیری از Double-Count
+-- هر کاربر فقط یک‌بار در محاسبه Pool شمرده می‌شود
+```
+
+---
+
+## ۲. بررسی داده‌های هفته‌های ۲۲ و ۲۳
+
+### تشخیص
+
+با اجرای diagnostic SQL روی DB، دو anomaly کشف شد:
+
+#### هفته ۲۲ — Pool Ghost (PoolId=10056)
+| فیلد | مقدار |
+|------|-------|
+| TotalPoolAmount | 2,520,000 |
+| AllCycles | 0 |
+| ریشه | هانیه سادات عشاقی (UserId=189) — خرید 1404/01/12 (هفته ۲۱) ولی AcceptContract در 17:02 دقیقه بعد Pool هفته ۲۲ را شارژ کرد |
+
+**دلیل:** CreatedAt و ModifiedAt timestamp مغایرت داشت — Pool در هفته ۲۲ ایجاد شد اما Cycle در هفته ۲۱ بود.
+
+**اصلاح دستی DB (Pending):**
+```sql
+UPDATE CMS.WeeklyCommissionPools
+SET TotalPoolAmount = 0, LastModified = GETUTCDATE()
+WHERE Id = 10056 AND WeekDefinitionId = 22;
+```
+
+#### هفته ۲۳ — Pool ناقص (PoolId=10054)
+| فیلد | مقدار |
+|------|-------|
+| TotalPoolAmount | 0 |
+| IsCalculated | False |
+| ریشه | محمدصادق عسلی (UserId=190) — خرید هفته ۲۳، Cycle وجود دارد ولی Pool=0 (قبل از fix) |
+
+**اصلاح دستی DB (Pending):**
+```sql
+UPDATE CMS.WeeklyCommissionPools
+SET TotalPoolAmount = 2520000, LastModified = GETUTCDATE()
+WHERE Id = 10054 AND WeekDefinitionId = 23;
+```
+
+---
+
+## ۳. ویژگی Network Tree (نوع فعالسازی + پکیج)
+
+### هدف
+صفحه `/network/tree` در BackOffice باید در هر node نشان دهد:
+- آیا این کاربر در هفته انتخابی **عضو جدید** بوده یا **تمدید کرده**؟
+- نام پکیجی که خریداری کرده؟
+
+### پیاده‌سازی Full-Stack
+
+#### الف) SP_GetNetworkTree (dbbkup/SP_GetNetworkTree.sql)
+```sql
+-- اضافه شد:
+OUTER APPLY (
+    SELECT TOP 1 cc.*
+    FROM CMS.ClubMembershipCycles cc
+    WHERE cc.ClubMembershipId = cm.Id
+      AND cc.PackagePurchasedAt >= @WeekStartDate
+      AND cc.PackagePurchasedAt < @WeekEndDate
+      AND (@ActivationWeekDefinitionId IS NULL OR @WeekStartDate IS NOT NULL)
+) AS cc_target
+
+-- ستون‌های جدید در output:
+IsActivatedInTargetWeek  -- آیا در هفته انتخابی فعال شده؟
+IsNewActivation          -- 1=اولین فعالسازی (CycleNumber=1), 0=تمدید, NULL=بدون Cycle
+PackageName              -- نام پکیج اون هفته
+PackageId                -- شناسه پکیج
+```
+
+**نکته:** منطق هفته‌بندی از `cm.ActivatedAt` به `Cycle.PackagePurchasedAt` تغییر کرد.
+
+**Deploy SP:**
+```
+SP مستقیم روی DB اجرا شد (نه EmbeddedResource Infrastructure)
+اجرا شد در: /tmp/DbDiag با C# script
+تأیید شد: SELECT OBJECT_ID('[CMS].[GetNetworkTree]') → موجود
+```
+
+#### ب) Application Layer
+**`NetworkTreeNodeDto.cs`** — فیلدهای جدید:
+```csharp
+bool? IsNewActivation
+string? PackageName
+long? PackageId
+```
+
+**`NetworkTreeDto.cs`** — همین فیلدها
+
+**`GetNetworkTreeQueryHandler.cs`**:
+```csharp
+// خواندن از DataReader:
+IsNewActivation = reader.IsDBNull(reader.GetOrdinal("IsNewActivation"))
+    ? null
+    : reader.GetInt32(reader.GetOrdinal("IsNewActivation")) == 1,
+PackageName = reader["PackageName"] as string,
+PackageId = reader.IsDBNull(reader.GetOrdinal("PackageId"))
+    ? null
+    : reader.GetInt64(reader.GetOrdinal("PackageId"))
+```
+
+#### ج) Proto (networkmembership.proto)
+```protobuf
+// NetworkTreeNodeModel — فیلدهای جدید:
+google.protobuf.BoolValue is_new_activation = 22;
+string package_name = 23;
+google.protobuf.Int64Value package_id = 24;
+```
+
+**NuGet Package:** `Foursat.CMSMicroservice.Protobuf` → از `0.0.194` به **`0.0.195`** bump و push شد.
+
+#### د) Mapping (NetworkMembershipProfile.cs)
+```csharp
+PackageName = node.PackageName ?? string.Empty,
+PackageId = node.PackageId.HasValue ? node.PackageId.Value : null,
+IsNewActivation = node.IsNewActivation.HasValue ? node.IsNewActivation.Value : null
+```
+
+#### هـ) BackOffice — NetworkTreeViewer.razor
+**DataGrid — دو ستون جدید:**
+```razor
+<!-- ستون نوع فعالسازی -->
+<PropertyColumn Property="x => x.IsNewActivation" Title="نوع فعالسازی">
+    @if (context.Item.IsNewActivation == true)
+    {
+        <MudChip Color="Color.Success">🆕 عضو جدید</MudChip>
+    }
+    else if (context.Item.IsNewActivation == false)
+    {
+        <MudChip Color="Color.Secondary">🔄 خرید مجدد</MudChip>
+    }
+</PropertyColumn>
+
+<!-- ستون پکیج -->
+<PropertyColumn Property="x => x.PackageName" Title="پکیج" />
+```
+
+**JS (jsNodes):**
+```js
+isNewActivation: n.IsNewActivation,
+packageName: n.PackageName ?? ""
+```
+
+---
+
+## ۴. بهبود UI نمودار درختی
+
+### مشکل اولیه
+بج «🆕 جدید» با `position: absolute` از گوشه کارت بیرون می‌زد و با محتوای دیگر برخورد می‌کرد.
+
+### فایل‌های تغییریافته
+
+#### `admin-org-chart.js` (wwwroot/js)
+
+**ساختار کارت بازنویسی شد:**
+```
+┌─────────────────────────────┐
+│ [Avatar]  نام کاربر          │
+│           پکیج نقره...       │  ← inline زیر اسم
+│           L13  چپ  عضو جدید  │  ← pill در meta row
+├─────────────────────────────┤
+│ ✓ فعال           1404/12/24 │
+└─────────────────────────────┘
+```
+
+**تغییرات:**
+- `activationTypeBadge` (absolute positioning) → `activationTypePill` (inline span)
+- `highlightBadge` (✨ floating) → حذف شد
+- `packageBadge` به زیر اسم کاربر منتقل شد (نه footer)
+- ابعاد کارت: `160×80` → `178×92` px
+
+#### `admin-org-chart.css` (wwwroot/css)
+
+```css
+/* جدید: activation pill به جای badge */
+.admin-node-card .activation-pill { /* inline flex */ }
+.admin-node-card .new-member-pill { background: #e8f5e9; color: #2e7d32; border: 1px solid #a5d6a7; }
+.admin-node-card .renewal-pill { background: #ede7f6; color: #5e35b1; border: 1px solid #b39ddb; }
+
+/* بهبود: پکیج روشن‌تر */
+.admin-node-card .package-name-badge { background: #eceff1; color: #546e7a; border: 1px solid #b0bec5; }
+```
+
+---
+
+## ۵. رفع باگ Pagination فروشگاه تخفیف
+
+### مشکل
+در صفحه `/discount-store/products`، دکمه «نمایش محصولات بیشتر» کار نمی‌کرد — همیشه صفحه اول برمی‌گشت.
+
+### ریشه مشکل
+
+**فایل غایب:** `DiscountProductProfile.cs` (Mapster) وجود نداشت.
+
+**جریان mapping:**
+```
+GetDiscountProductsRequest (proto)
+    ↓ request.Adapt<GetDiscountProductsQuery>()
+GetDiscountProductsQuery
+```
+
+بدون profile، auto-mapping دو مشکل داشت:
+1. `request.SearchQuery (string)` → `query.SearchTerm (string?)` → نامتطابق نام، NULL می‌شد
+2. `request.PageNumber (int)` → `query.PaginationQuery.PageNumber` — **Mapster نمی‌توانست به nested object مپ کند** → `PaginationQuery = null` → default: `PageNumber=1` همیشه!
+
+### راه‌حل
+
+**فایل جدید:** `CMS/src/CMSMicroservice.WebApi/Common/Mappings/DiscountProductProfile.cs`
+
+```csharp
+config.NewConfig<GetDiscountProductsRequest, GetDiscountProductsQuery>()
+    .Map(dest => dest.SearchTerm,
+        src => string.IsNullOrEmpty(src.SearchQuery) ? null : src.SearchQuery)
+    .Map(dest => dest.CategoryId,
+        src => src.CategoryId != null ? src.CategoryId.Value : (long?)null)
+    .Map(dest => dest.IsActive,
+        src => src.IsActive != null ? src.IsActive.Value : (bool?)null)
+    .Map(dest => dest.PaginationQuery, src => new PaginationState
+    {
+        PageNumber = src.PageNumber > 0 ? src.PageNumber : 1,
+        PageSize = src.PageSize > 0 ? src.PageSize : 12
+    });
+```
+
+همچنین `GetDiscountProductsResponseDto → GetDiscountProductsResponse` هم به صورت صریح مپ شد تا `MetaData` و `Models` درست انتقال یابند.
+
+---
+
+## خلاصه فایل‌های تغییریافته
+
+| فایل | نوع تغییر | پروژه |
+|------|-----------|-------|
+| `ActivateClubMembershipCommandHandler.cs` | Fix — حذف Double-Charge | CMS Application |
+| `AcceptClubMembershipContractCommandHandler.cs` | Fix — Cross-week Pool | CMS Application |
+| `CreateManualPaymentCommandHandler.cs` | Fix — Cross-week Pool | CMS Application |
+| `sp_CalculateWeeklyCommissionPool.sql` | Fix — IsCurrentCycle | CMS Infrastructure |
+| `SP_GetNetworkTree.sql` | Feature — IsNewActivation, PackageName, PackageId | DB/dbbkup |
+| `NetworkTreeNodeDto.cs` | Feature — فیلدهای جدید | CMS Application |
+| `NetworkTreeDto.cs` | Feature — فیلدهای جدید | CMS Application |
+| `GetNetworkTreeQueryHandler.cs` | Feature — خواندن فیلدهای جدید | CMS Application |
+| `networkmembership.proto` | Feature — ۳ فیلد جدید در NetworkTreeNodeModel | Protobuf |
+| `NetworkMembershipProfile.cs` | Feature — mapping فیلدهای جدید | CMS WebApi |
+| `NetworkTreeViewer.razor` | Feature — DataGrid ستون‌های جدید | BackOffice |
+| `admin-org-chart.js` | Feature+Fix — inline pill، پکیج زیر اسم | BackOffice wwwroot |
+| `admin-org-chart.css` | Feature+Fix — استایل pill‌های مرتب | BackOffice wwwroot |
+| `DiscountProductProfile.cs` | Fix — Pagination mapping صحیح | CMS WebApi (جدید) |
+
+### NuGet Package
+| پکیج | نسخه قبل | نسخه جدید |
+|------|----------|-----------|
+| `Foursat.CMSMicroservice.Protobuf` | 0.0.194 | **0.0.195** |
+
+---
+
+## وظایف باقی‌مانده
+
+### ضروری — اصلاح داده‌های DB
+
+```sql
+BEGIN TRANSACTION;
+
+-- هفته ۲۲: Pool Ghost (هانیه سادات عشاقی ← AcceptContract هفته اشتباه)
+UPDATE CMS.WeeklyCommissionPools
+SET TotalPoolAmount = 0, LastModified = GETUTCDATE()
+WHERE Id = 10056 AND WeekDefinitionId = 22;
+
+-- هفته ۲۳: Pool ناقص (محمدصادق عسلی ← Pool قبل از Fix ایجاد شده بود)
+UPDATE CMS.WeeklyCommissionPools
+SET TotalPoolAmount = 2520000, LastModified = GETUTCDATE()
+WHERE Id = 10054 AND WeekDefinitionId = 23;
+
+COMMIT;
+```
+
+### بهبود آینده
+- [ ] `SP_GetNetworkTree.sql` به Infrastructure EmbeddedResource اضافه شود (auto-deploy)
+- [ ] `DiscountProductDto` در Application — اضافه کردن فیلد `Created` از DB
+- [ ] تست pagination فروشگاه پس از restart CMS

technical/TECH-08-SESSION-LOG-20260513.md

@@ -0,0 +1,303 @@
+# TECH-08 — لاگ Session 1404/02/23 (2026-05-13)
+
+> نوع سند: **گزارش کار**  
+> تاریخ: ۱۴۰۵/۰۲/۲۳  
+> مرتبط با: CMS · FrontOffice  
+> کامیت CMS: `683ed37` (branch: `kub-stage`)  
+> کامیت FrontOffice: `231da2c` (branch: `kub-stage`)
+
+---
+
+## فهرست مطالب
+
+1. [هدف و خلاصه](#هدف-و-خلاصه)
+2. [تغییرات CMS (Backend)](#تغییرات-cms-backend)
+3. [تغییرات FrontOffice](#تغییرات-frontoffice)
+4. [معماری GuestActionGate](#معماری-guestactiongate)
+5. [فلوچارت تجربه کاربر](#فلوچارت-تجربه-کاربر)
+6. [فایل‌های تغییر یافته](#فایلهای-تغییر-یافته)
+
+---
+
+## هدف و خلاصه
+
+هدف این session:
+
+1. **نمایش ۶ محصول پرفروش معمولی + ۶ محصول پرفروش فروشگاه اعتباری** در لندینگ پیج FrontOffice، زیر هدر اصلی (۳ محصول در هر ردیف، دو section مجزا).
+2. **دسترسی guest** (کاربر بدون لاگین) به مرور محصولات برای پرزنت به مشتریان بالقوه.
+3. **Hybrid auth flow**: کاربر guest محصولات را می‌بیند؛ اگر روی "افزودن به سبد" کلیک کرد، مودال لاگین باز می‌شود و پس از ورود موفق، عمل به صورت خودکار انجام می‌شود.
+
+---
+
+## تغییرات CMS (Backend)
+
+### ۱. `discountproduct.proto`
+
+```proto
+// اضافه شده به GetDiscountProductsRequest
+google.protobuf.StringValue sort_by = 9;
+
+// اضافه شده به DiscountProductDto
+int32 sale_count = 12;
+```
+
+**چرا:** برای واکشی پرفروش‌ترین محصولات فروشگاه اعتباری باید امکان sort بر اساس `sale_count` وجود داشته باشد. قبلاً این فیلد در DTO برگردانده نمی‌شد.
+
+### ۲. `CMSMicroservice.Protobuf.csproj`
+
+نسخه از `0.0.195` به `0.0.196` بالا رفت تا پکیج NuGet جدید publish شود.
+
+### ۳. `GetDiscountProductsQuery.cs`
+
+```csharp
+public string? SortBy { get; set; }
+```
+
+### ۴. `GetDiscountProductsQueryHandler.cs`
+
+```csharp
+// قبل: همیشه OrderByDescending(p => p.Created)
+// بعد: dynamic sort با fallback
+if (!string.IsNullOrEmpty(request.SortBy))
+    query = query.ApplyOrder(request.SortBy);
+else
+    query = query.OrderByDescending(p => p.Created);
+
+// و در SELECT:
+SaleCount = p.SaleCount,
+```
+
+از extension method موجود `ApplyOrder` (کتابخانه `System.Linq.Dynamic.Core`) استفاده شد تا نیازی به تغییر جداگانه نباشد.
+
+### ۵. `DiscountProductProfile.cs` (Mapster)
+
+```csharp
+// Request mapping
+.Map(dest => dest.SortBy, src => string.IsNullOrEmpty(src.SortBy) ? null : src.SortBy)
+
+// Response mapping
+SaleCount = p.SaleCount,
+```
+
+---
+
+## تغییرات FrontOffice
+
+### ۱. `GuestActionGate.cs` (فایل جدید)
+
+```
+FrontOffice.Main/Utilities/GuestActionGate.cs
+```
+
+سرویس utility جدید که هر action نیازمند لاگین را wrap می‌کند:
+
+```csharp
+public async Task<bool> RunAsync(Func<Task> action)
+{
+    if (await _authService.IsAuthenticatedAsync())
+    {
+        await action();
+        return true;
+    }
+    await _authDialogService.ShowAuthDialogAsync();
+    if (await _authService.IsAuthenticatedAsync())
+    {
+        await action();
+        return true;
+    }
+    return false;
+}
+```
+
+در `ConfigureServices.cs` به صورت Scoped ثبت شد:
+
+```csharp
+services.AddScoped<GuestActionGate>();
+```
+
+### ۲. `ProductService.cs`
+
+```csharp
+public Task<ProductListResult> GetTopSellingAsync(int count = 6)
+    => GetProductsPagedAsync(sortBy: "SaleCount desc", page: 1, pageSize: count);
+```
+
+### ۳. `DiscountProductService.cs`
+
+```csharp
+// پارامتر جدید به GetProductsAsync اضافه شد
+public async Task<DiscountProductListResult> GetProductsAsync(
+    ..., string? sortBy = null)
+{
+    if (!string.IsNullOrWhiteSpace(sortBy))
+        request.SortBy = sortBy;
+    ...
+}
+
+public Task<DiscountProductListResult> GetTopSellingAsync(int count = 6)
+    => GetProductsAsync(page: 1, pageSize: count, sortBy: "SaleCount desc");
+```
+
+### ۴. `Index.razor` و `Index.razor.cs`
+
+دو section جدید در لندینگ پیج زیر hero اضافه شد:
+
+**Section 1 — محصولات پرفروش معمولی:**
+- عنوان: "محصولات پرفروش"
+- ۶ کارت (۳ در هر ردیف با MudGrid)
+- هر کارت: تصویر، نام، قیمت با VAT، دکمه "افزودن به سبد"
+- دکمه "بیشتر" → `/products`
+
+**Section 2 — محصولات پرفروش فروشگاه اعتباری:**
+- عنوان: "فروشگاه اعتباری"
+- ۶ کارت (۳ در هر ردیف)
+- هر کارت: تصویر، نام، قیمت، درصد تخفیف
+- دکمه "بیشتر" → `/discount-store`
+
+**Loading state:** در حین بارگذاری یک spinner نشان داده می‌شود و سپس section‌ها fade-in می‌شوند.
+
+**Data loading (parallel):**
+```csharp
+var topRegTask  = ProductService.GetTopSellingAsync(6);
+var topDiscTask = DiscountProductService.GetTopSellingAsync(6);
+var featuredPostsTask = BlogPostService.GetFeaturedPostsAsync(2);
+await Task.WhenAll(topRegTask, topDiscTask, featuredPostsTask);
+```
+
+**Cart actions با GuestActionGate:**
+```csharp
+private async Task AddRegularToCart(Product p)
+    => await GuestGate.RunAsync(() => Cart.Add(p, 1));
+
+private async Task AddDiscountToCart(DiscountProductCard p)
+    => await GuestGate.RunAsync(() => DiscountCart.AddAsync(p.Id));
+```
+
+### ۵. Hybridize کردن صفحات موجود
+
+#### صفحات لیست و جزئیات محصول (GuestActionGate):
+
+| فایل | تغییر |
+|------|-------|
+| `Store/Products.razor.cs` | `AddToCart` → `GuestGate.RunAsync(...)` |
+| `Store/ProductDetail.razor.cs` | `AddToCart` و `RemoveFromCart` → `GuestGate.RunAsync(...)` |
+| `DiscountStore/Products.razor.cs` | `AddToCart` → `GuestGate.RunAsync(...)` |
+| `DiscountStore/ProductDetail.razor.cs` | `AddToCart` → `GuestGate.RunAsync(...)` |
+
+#### صفحات Cart و Checkout (Soft Auth Gate):
+
+```csharp
+protected override async Task OnInitializedAsync()
+{
+    if (!await AuthService.IsAuthenticatedAsync())
+    {
+        await AuthDialogService.ShowAuthDialogAsync();
+    }
+    // ادامه بارگذاری...
+}
+```
+
+این pattern روی:
+- `Store/Cart.razor.cs`
+- `Store/CheckoutSummary.razor.cs`
+- `DiscountStore/Cart.razor.cs`
+- `DiscountStore/Checkout.razor.cs`
+
+اعمال شد. اگر guest مستقیماً وارد سبد خرید شود، مودال لاگین نشان داده می‌شود.
+
+### ۶. `MembershipPage.razor` (fix متنی)
+
+```diff
+- شارژ ۵۶ میلیون تومان کیف پول فروشگاه اعتباری
++ شارژ برابر ارزش پکیج فعال در کیف پول فروشگاه اعتباری
+```
+
+متن hardcode‌شده با مقدار دینامیک جایگزین شد.
+
+---
+
+## معماری GuestActionGate
+
+```
+کاربر کلیک می‌کند
+        │
+        ▼
+GuestActionGate.RunAsync(action)
+        │
+        ├─► آیا لاگین است؟ ──YES──► action() اجرا می‌شود ✅
+        │
+        NO
+        │
+        ▼
+AuthDialogService.ShowAuthDialogAsync()
+(مودال OTP باز می‌شود)
+        │
+        ├─► آیا لاگین شد؟ ──YES──► action() اجرا می‌شود ✅
+        │
+        NO (بستن مودال)
+        │
+        ▼
+        return false (هیچ اتفاقی نمی‌افتد) ❌
+```
+
+این pattern **defense-in-depth** است: `CartService.Add` هم به تنهایی چک `IsAuthenticatedAsync` دارد؛ `GuestActionGate` لایه UX روی آن اضافه می‌کند.
+
+---
+
+## فلوچارت تجربه کاربر
+
+```
+کاربر وارد لندینگ پیج می‌شود (بدون لاگین)
+        │
+        ├─► ۶ محصول پرفروش معمولی نمایش داده می‌شود
+        ├─► ۶ محصول پرفروش اعتباری نمایش داده می‌شود
+        │
+        ├─► "بیشتر" کلیک → /products یا /discount-store
+        │         (صفحات لیست کامل، بدون لاگین قابل مرور)
+        │
+        ├─► روی محصول کلیک → صفحه جزئیات
+        │         (بدون لاگین قابل مشاهده)
+        │
+        └─► "افزودن به سبد" کلیک
+                  │
+                  ▼
+            مودال لاگین (OTP)
+                  │
+                  ├─► ورود موفق → محصول به سبد اضافه می‌شود ✅
+                  └─► بستن مودال → هیچ اتفاقی نمی‌افتد
+```
+
+---
+
+## فایل‌های تغییر یافته
+
+### CMS — کامیت `683ed37`
+
+```
+src/CMSMicroservice.Protobuf/Protos/discountproduct.proto          (+2)
+src/CMSMicroservice.Protobuf/CMSMicroservice.Protobuf.csproj       (~2)
+src/CMSMicroservice.Application/DiscountShopCQ/Queries/
+  GetDiscountProducts/GetDiscountProductsQuery.cs                   (+1)
+  GetDiscountProducts/GetDiscountProductsQueryHandler.cs            (+7 -3)
+src/CMSMicroservice.WebApi/Common/Mappings/DiscountProductProfile.cs (+3)
+```
+
+### FrontOffice — کامیت `231da2c`
+
+```
+src/FrontOffice.Main/Utilities/GuestActionGate.cs                  (NEW +42)
+src/FrontOffice.Main/ConfigureServices.cs                          (+1)
+src/FrontOffice.Main/Utilities/ProductService.cs                   (+3)
+src/FrontOffice.Main/Utilities/DiscountProductService.cs           (+8)
+src/FrontOffice.Main/Pages/Index.razor                             (+~180)
+src/FrontOffice.Main/Pages/Index.razor.cs                          (+45)
+src/FrontOffice.Main/Pages/Store/Products.razor.cs                 (+5)
+src/FrontOffice.Main/Pages/Store/ProductDetail.razor.cs            (+5)
+src/FrontOffice.Main/Pages/Store/Cart.razor.cs                     (+8)
+src/FrontOffice.Main/Pages/Store/CheckoutSummary.razor.cs          (+8)
+src/FrontOffice.Main/Pages/DiscountStore/Products.razor.cs         (+5)
+src/FrontOffice.Main/Pages/DiscountStore/ProductDetail.razor.cs    (+5)
+src/FrontOffice.Main/Pages/DiscountStore/Cart.razor.cs             (+8)
+src/FrontOffice.Main/Pages/DiscountStore/Checkout.razor.cs         (+8)
+src/FrontOffice.Main/Pages/Club/MembershipPage.razor               (~1)
+```

ui-modernization/BACKOFFICE-ARCHITECTURE.md

@@ -1,359 +0,0 @@
-# 🏗️ BackOffice — مرجع معماری و الگوها
-
-> **تاریخ:** ۱۴۰۴/۱۱/۲۴ (February 13, 2026)  
-> **پروژه:** BackOffice Admin Panel (Blazor WebAssembly)
-
----
-
-## ۱. معماری کلی
-
-```
-┌─────────────────────────────────────────────────┐
-│                  BackOffice                      │
-│              (Blazor WebAssembly)                │
-│  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
-│  │ MudBlazor│  │ Mapster  │  │ DateTimeCvt  │  │
-│  │   v8     │  │ (mapping)│  │ (تاریخ شمسی) │  │
-│  └──────────┘  └──────────┘  └──────────────┘  │
-│        │              │              │           │
-│  ┌─────────────────────────────────────────┐    │
-│  │         Pages / Components / Shared      │    │
-│  │   BasePageComponent, Hub Pages, Dialogs  │    │
-│  └─────────────────────────────────────────┘    │
-│        │                                         │
-│  ┌──────────────┐    ┌──────────────────┐       │
-│  │ gRPC Clients │    │ HTTP REST Services│       │
-│  │ (Protobuf)   │    │ (DiscountShop)   │       │
-│  └──────┬───────┘    └────────┬─────────┘       │
-└─────────┼──────────────────────┼─────────────────┘
-          │                      │
-          ▼                      ▼
-┌──────────────────────────────────────────┐
-│          CMS Microservice                 │
-│       (ASP.NET Core + gRPC)              │
-│  Domain → Application (CQRS) → Infra     │
-└──────────────────────────────────────────┘
-```
-
----
-
-## ۲. Technology Stack
-
-| لایه | تکنولوژی | نسخه |
-|------|----------|------|
-| Frontend Framework | Blazor WebAssembly | .NET 9 |
-| UI Library | MudBlazor | v8 |
-| Backend Communication (عادی) | gRPC / Protobuf | — |
-| Backend Communication (تخفیفی) | HTTP REST | — |
-| Object Mapping | Mapster | — |
-| تاریخ شمسی | DateTimeConverterCL | — |
-| Client State | Blazored.LocalStorage | — |
-| Auth | JWT Role-based | Administrator, Admin, Author |
-| Permission | IAuthorizationService.HasPermissionAsync | 18 permission |
-
----
-
-## ۳. ساختار پوشه‌ها
-
-```
-BackOffice/src/BackOffice/
-├── Common/
-│   ├── BaseComponents/         ← کامپوننت‌های پایه (BasePageComponent, DateRangePicker, Image)
-│   ├── Utilities/              ← RouteConstance, Extensions, Helpers
-│   └── ...
-├── Pages/
-│   ├── Category/               ← دسته‌بندی فروشگاه عادی
-│   ├── Products/               ← محصولات فروشگاه عادی
-│   ├── UserOrder/              ← سفارشات + گزارش فروش (Hub)
-│   ├── DiscountShop/           ← فروشگاه تخفیفی (محصولات + دسته‌بندی + سفارشات)
-│   │   └── Components/         ← دیالوگ‌ها و کامپوننت‌های اختصاصی
-│   ├── Inventory/              ← انبارداری (4 صفحه)
-│   ├── Package/                ← پکیج‌ها
-│   ├── Commission/             ← کمیسیون (5 صفحه)
-│   ├── Network/                ← شبکه (4 صفحه)
-│   ├── Club/                   ← باشگاه مشتریان (Hub: اعضا + آمار + فیچرها)
-│   ├── Blog/                   ← بلاگ (Hub: پست + دسته‌بندی + تگ)
-│   ├── Content/                ← صفحات سایت
-│   ├── Wallet/                 ← کیف‌پول (تب‌ها: لیست + تاریخچه)
-│   ├── Contract/               ← قراردادها
-│   ├── SystemManagement/       ← سیستم (Hub: تنظیمات + Worker + Health)
-│   └── ...
-├── Services/
-│   ├── DiscountProduct/        ← IDiscountProductService + implementation
-│   ├── DiscountCategory/       ← IDiscountCategoryService + implementation
-│   ├── DiscountOrder/          ← IDiscountOrderService + implementation
-│   └── Authorization/          ← IAuthorizationService
-├── Shared/
-│   ├── MainLayout.razor        ← لایوت اصلی (AppBar + NavMenu + MudContainer)
-│   ├── NavMenu.razor           ← منوی ناوبری
-│   ├── GlobalSearch.razor      ← جستجوی سراسری
-│   └── AppBreadcrumb.razor     ← Breadcrumb فارسی
-└── wwwroot/
-    ├── js/main.js              ← jsSaveAsFile (Excel export)
-    └── appsettings.json        ← تنظیمات endpoints
-```
-
----
-
-## ۴. الگوهای اصلی
-
-### ۴.۱ BasePageComponent — پترن صفحات لیست
-
-**هر صفحه لیست** از `BasePageComponent` استفاده می‌کند:
-
-```
-┌──────────────────────────────────────┐
-│ BasePageComponent                     │
-│  ┌────────────────────────────────┐  │
-│  │ 📋 Filter Panel (collapsible)  │  │
-│  │  [فیلد ۱]  [فیلد ۲]  [فیلد ۳] │  │
-│  │  [پاک کردن فیلتر] [جستجو]     │  │
-│  └────────────────────────────────┘  │
-│  ┌────────────────────────────────┐  │
-│  │ 📊 Content (DataGrid)          │  │
-│  │  ToolBar: [عنوان] [Excel] [+]  │  │
-│  │  Columns: ...                   │  │
-│  │  Pager: 20/50/100              │  │
-│  └────────────────────────────────┘  │
-└──────────────────────────────────────┘
-```
-
-**فایل:** `Common/BaseComponents/BasePageComponent.razor`
-
-**پراپرتی‌ها:**
-- `RenderFragment Filters` — محتوای فیلتر
-- `RenderFragment Content` — محتوای اصلی
-- `EventCallback OnSubmitClick` — کلیک جستجو
-- `EventCallback OnClearFilterClick` — کلیک پاک کردن
-- `bool IsFiltered` — آیا فیلتر فعال است (نشان‌دهنده badge «فعال»)
-
----
-
-### ۴.۲ Hub Pages — پترن ادغام صفحات
-
-صفحات مرتبط در یک Hub با `MudTabs` ادغام می‌شوند:
-
-| Hub | Route‌ها | تب‌ها |
-|-----|---------|-------|
-| `OrdersHub` | `/OrdersPage/`, `/OrdersSalesReportsPage/` | سفارشات + گزارش فروش |
-| `DiscountShopHub` | `/discount-shop`, `/discount-orders`, `/discount-sales-reports` | سفارشات + گزارش فروش |
-| `ClubHub` | `/club`, `/club/members`, `/club/statistics` | اعضا + آمار |
-| `BlogHub` | `/blog`, `/blog/posts`, `/blog/categories`, `/tags` | پست + دسته‌بندی + تگ |
-| `SystemHub` | `/system`, `/system/configuration`, `/system/worker-control`, `/system/health` | تنظیمات + Worker + Health |
-
----
-
-### ۴.۳ Code-Behind — پترن جداسازی markup/logic
-
-```
-MyPage.razor       →  فقط HTML/Razor markup
-MyPage.razor.cs    →  partial class + [Inject] + methods
-```
-
-**قوانین:**
-1. فایل‌هایی که سرویس inject دارند **باید** code-behind داشته باشند (محدودیت Razor source generator)
-2. سرویس‌های global (`_Imports.razor`) **نباید** دوباره `[Inject]` شوند
-3. `namespace` باید با مسیر فایل match کند
-
-**سرویس‌های Global (از `_Imports.razor`):**
-
-| سرویس | نام متغیر | توضیح |
-|--------|-----------|-------|
-| `IDialogService` | `DialogService` | دیالوگ MudBlazor |
-| `ISnackbar` | `Snackbar` | نوتیفیکیشن MudBlazor |
-| `IJSRuntime` | `jsRuntime` | ⚠️ حرف کوچک `j` |
-| `NavigationManager` | `Navigation` | ناوبری |
-| `ILocalStorageService` | `LocalStorageService` | ذخیره محلی |
-| `AuthenticationStateProvider` | `AuthenticationStateProvider` | احراز هویت |
-
----
-
-### ۴.۴ Excel Export — پترن خروجی CSV
-
-```csharp
-private async Task ExportToExcel()
-{
-    var sb = new StringBuilder();
-    sb.AppendLine("ستون ۱,ستون ۲,ستون ۳");  // هدر فارسی
-    foreach (var item in items)
-    {
-        sb.AppendLine($"{EscapeCsv(item.Col1)},{item.Col2},{item.Col3}");
-    }
-    var bytes = Encoding.UTF8.GetPreamble()  // UTF-8 BOM
-        .Concat(Encoding.UTF8.GetBytes(sb.ToString())).ToArray();
-    var base64 = Convert.ToBase64String(bytes);
-    await jsRuntime.InvokeVoidAsync("jsSaveAsFile", "filename.csv", base64);
-}
-
-private string EscapeCsv(string? value)
-{
-    if (string.IsNullOrEmpty(value)) return "";
-    if (value.Contains(',') || value.Contains('"') || value.Contains('\n'))
-        return $"\"{value.Replace("\"", "\"\"")}\"";
-    return value;
-}
-```
-
-**صفحات دارای Excel:** Products, UserOrders, ClubMembers, WithdrawalRequests, WeeklyReports, StockMovements, Users, DiscountOrders, ManualPayments, Inventory, DiscountProducts
-
----
-
-### ۴.۵ Server-Side DataGrid — پترن بارگذاری صفحه‌ای
-
-```razor
-<MudDataGrid T="MyDto"
-             ServerData="LoadServerData"
-             Height="calc(100vh - 240px)"
-             FixedHeader="true"
-             Hover="true" Dense="true">
-```
-
-```csharp
-private async Task<GridData<MyDto>> LoadServerData(GridState<MyDto> state)
-{
-    var filter = new MyFilter
-    {
-        PageNumber = state.Page + 1,  // MudDataGrid is 0-based
-        PageSize = state.PageSize
-    };
-    var (items, totalCount, _) = await MyService.GetAsync(filter);
-    return new GridData<MyDto> { Items = items, TotalItems = totalCount };
-}
-```
-
----
-
-### ۴.۶ Permission System
-
-NavMenu از `IAuthorizationService.HasPermissionAsync()` برای نمایش/مخفی کردن آیتم‌ها استفاده می‌کند:
-
-| Permission | صفحه(ها) |
-|-----------|----------|
-| `dashboard.view` | داشبورد |
-| `packages.manage` | پکیج‌ها |
-| `products.manage` | محصولات + دسته‌بندی + ویرایش دسته‌جمعی |
-| `orders.view` | سفارشات |
-| `inventory.manage` | انبارداری (4 صفحه) |
-| `discountshop.manage` | فروشگاه تخفیفی |
-| `users.view` | کاربران |
-| `roles.manage` | نقش‌ها |
-| `manualpayments.create` | پرداخت دستی |
-| `blog.manage` | بلاگ |
-| `sitepages.manage` | صفحات سایت |
-| `publicmessages.view` | پیام‌های عمومی |
-| `settings.manage_configuration` | تنظیمات سیستم |
-
----
-
-## ۵. مسیرهای (Routing)
-
-### مسیرهای ثابت (`RouteConstance.cs`)
-```
-/                          → Dashboard
-/PackagePage/              → Packages
-/ProductsPage/             → Products
-/CategoryPage/             → Categories
-/OrdersPage/               → Orders Hub
-/OrdersSalesReportsPage/   → Orders Sales Reports
-/InventoryPage/            → Inventory
-/InventoryLowStockPage/    → Low Stock
-/InventoryWarehousesPage/  → Warehouses
-/InventoryMovementsPage/   → Stock Movements
-/UserPage/                 → Users
-/RolePage/                 → Roles
-/ProductsBulkEditPage/     → Bulk Edit
-/ProductCategoriesPage/    → Product-Category DragDrop
-/CategoryProductsPage/     → Category-Product DragDrop
-```
-
-### مسیرهای hardcode (فروشگاه تخفیفی + سایر)
-```
-/discount-products         → Discount Products
-/discount-categories       → Discount Categories
-/discount-shop             → Discount Orders Hub
-/discount-orders           → Discount Orders
-/discount-sales-reports    → Discount Sales Reports
-/commission/*              → Commission pages
-/network/*                 → Network pages
-/club/*                    → Club pages
-/blog/*                    → Blog pages
-/wallets                   → Wallets
-/contracts                 → Contracts
-/payment/manual-payments   → Manual Payments
-/system/*                  → System pages
-/settings                  → Settings
-/content/pages             → Content Pages
-/public-messages           → Public Messages
-```
-
----
-
-## ۶. ارتباط فروشگاه عادی vs تخفیفی
-
-| جنبه | فروشگاه عادی | فروشگاه تخفیفی |
-|------|-------------|---------------|
-| **سرویس محصولات** | gRPC `ProductsContractClient` | HTTP `IDiscountProductService` |
-| **سرویس دسته‌بندی** | gRPC `CategoryContractClient` | HTTP `IDiscountCategoryService` |
-| **سرویس سفارشات** | gRPC `UserOrderContractClient` | HTTP `IDiscountOrderService` |
-| **Entity بکند** | `Product` | `DiscountProduct` |
-| **پرداخت** | فقط درگاه | ترکیبی (کیف تخفیفی + درگاه) |
-| **فیلد اختصاصی** | — | `MaxDiscountPercent` |
-| **UI Pattern** | BasePageComponent | BasePageComponent (یکسان) |
-| **ستون‌ها** | یکسان | یکسان + ستون تخفیف |
-
----
-
-## ۷. نقشه NavMenu
-
-```
-داشبورد
-─────────────────────
-کمیسیون و شبکه
-├── کمیسیون (NavGroup)
-│   ├── داشبورد کمیسیون
-│   ├── گزارش‌های هفتگی
-│   ├── پرداخت کاربران
-│   ├── درخواست‌های برداشت [Badge]
-│   └── گزارش برداشت‌ها
-├── شبکه (NavGroup)
-│   ├── درخت شبکه
-│   ├── گزارش موجودی‌ها
-│   └── آمار شبکه
-└── باشگاه مشتریان (NavGroup)
-    ├── اعضا و آمار
-    └── فیچرهای باشگاه
-─────────────────────
-فروشگاه [AuthorizeView: Administrator]
-├── پکیج‌ها
-├── فروشگاه عادی (NavGroup)
-│   ├── محصولات
-│   ├── دسته‌بندی‌ها
-│   └── سفارشات و گزارش
-├── انبارداری (NavGroup)
-│   ├── موجودی انبار
-│   ├── محصولات کم‌موجود
-│   ├── مدیریت انبارها
-│   └── تاریخچه تغییرات
-└── فروشگاه تخفیفی (NavGroup)
-    ├── محصولات
-    ├── دسته‌بندی‌ها
-    └── سفارشات و گزارش
-─────────────────────
-مدیریت [AuthorizeView: Administrator]
-├── کاربران
-├── نقش‌ها
-├── پرداخت دستی
-├── کیف‌پول
-└── قراردادها
-─────────────────────
-مدیریت محتوا
-├── بلاگ
-├── صفحات سایت
-└── پیام‌های عمومی
-─────────────────────
-سیستم [AuthorizeView: Administrator]
-├── مدیریت سیستم
-└── نسخه اپلیکیشن‌ها
-─────────────────────
-تنظیمات
-```

ui-modernization/BACKOFFICE-STORE-UNIFICATION.md

@@ -1,195 +0,0 @@
-# 🏪 یکسان‌سازی فروشگاه عادی و تخفیفی — BackOffice
-
-> **تاریخ:** ۱۴۰۴/۱۱/۲۴ (February 13, 2026)  
-> **وضعیت:** ✅ کامل  
-> **Build:** 0 Error ✅
-
----
-
-## ۱. هدف
-
-فروشگاه عادی و فروشگاه تخفیفی در پنل مدیریت باید از نظر **ظاهری و UX** کاملاً یکسان باشند.
-قبل از این تغییرات، صفحات فروشگاه تخفیفی ظاهر و ساختار متفاوتی داشتند. هدف این فاز:
-
-1. **NavMenu** — جداسازی دو فروشگاه در گروه‌بندی‌های مجزا
-2. **دسته‌بندی‌ها** — ظاهر یکسان با فروشگاه عادی (ستون‌ها، درخت، اکشن‌ها)
-3. **محصولات** — ظاهر یکسان (گالری، فیلترها، ستون‌های گرید، اکسپورت)
-4. **سفارشات** — حذف گزارش‌های کوچک اضافی، فقط لیست خالص + رفع باگ لیست خالی
-
----
-
-## ۲. خلاصه تغییرات
-
-### ۲.۱ بازسازی NavMenu
-
-| قبل | بعد |
-|-----|-----|
-| یک بخش «فروشگاه» با زیرگروه‌های محصولات + دسته‌بندی + سفارش + ویرایش دسته‌جمعی | دو گروه مجزا: «فروشگاه عادی» و «فروشگاه تخفیفی» |
-| ویرایش دسته‌جمعی در منو | حذف شد از منو |
-| انبارداری داخل فروشگاه | انبارداری گروه مجزا |
-| پکیج‌ها داخل فروشگاه | پکیج‌ها آیتم مستقل |
-
-**ساختار جدید:**
-```
-فروشگاه (بخش)
-├── پکیج‌ها (مستقل)
-├── فروشگاه عادی (NavGroup)
-│   ├── محصولات → /ProductsPage/
-│   ├── دسته‌بندی‌ها → /CategoryPage/
-│   └── سفارشات و گزارش → /OrdersPage/
-├── انبارداری (NavGroup مستقل)
-│   ├── موجودی انبار
-│   ├── محصولات کم‌موجود
-│   ├── مدیریت انبارها
-│   └── تاریخچه تغییرات
-└── فروشگاه تخفیفی (NavGroup)
-    ├── محصولات → /discount-products
-    ├── دسته‌بندی‌ها → /discount-categories
-    └── سفارشات و گزارش → /discount-orders
-```
-
-**فایل:** `Shared/NavMenu.razor`
-
----
-
-### ۲.۲ رفع لیست خالی سفارشات + حذف گزارش‌های کوچک
-
-**مشکل ۱ — لیست خالی:**
-- `PaymentDate.ToDateTime()` بدون null check باعث exception در WASM می‌شد
-- Exception در Blazor WASM silent است و grid خالی نشان می‌دهد
-- **رفع:** اضافه کردن `@if (context.Item.PaymentDate != null)` با fallback `"-"`
-
-**مشکل ۲ — گزارش‌های اضافی:**
-- کارت‌های آماری (تعداد سفارشات + مجموع مبلغ) و نمودار Bar وضعیت ارسال بالای گرید بودند
-- این آمار اضافی بود چون تب جداگانه «گزارش فروش» وجود دارد
-- **رفع:** حذف کامل `MudGrid` (کارت‌ها)، `MudChart` (نمودار)، فیلدهای `_stats`/`_statusChartLabels`/`_statusChartSeries`، متد `UpdateStats()`، کلاس `OrderStatsViewModel`
-- عنوان تولبار از «سفارش‌های کاربر» به «لیست سفارشات» تغییر کرد
-
-**فایل‌ها:**
-- `Pages/UserOrder/UserOrderMainPage.razor`
-- `Pages/UserOrder/UserOrderMainPage.razor.cs`
-
----
-
-### ۲.۳ بازنویسی صفحه محصولات تخفیفی
-
-**قبل:** markup سفارشی بدون `BasePageComponent`، ستون‌های ساده، بدون image preview
-**بعد:** کاملاً مطابق با `ProductsMainPage` فروشگاه عادی
-
-| ویژگی | قبل | بعد |
-|-------|-----|-----|
-| Wrapper | markup دستی | `BasePageComponent` |
-| فیلترها | جستجو + دسته‌بندی | جستجو + دسته‌بندی + وضعیت + موجودی |
-| ستون عنوان | متن ساده | تصویر inline (MudAvatar) + متن truncate + tooltip |
-| ستون موجودی | عدد ساده | چیپ رنگی (قرمز/نارنجی/سبز) |
-| ستون وضعیت | متن | چیپ Error/Success |
-| خروجی Excel | ✅ (داشت) | ✅ (حفظ شد) |
-| گالری تصاویر | ✅ (داشت) | ✅ (حفظ شد) |
-| Server-side paging | ✅ | ✅ |
-
-**فایل‌ها:**
-- `Pages/DiscountShop/DiscountProductsMainPage.razor` — بازنویسی کامل
-- `Pages/DiscountShop/DiscountProductsMainPage.razor.cs` — بازنویسی کامل (code-behind)
-
----
-
-### ۲.۴ بازنویسی صفحه دسته‌بندی‌های تخفیفی
-
-**قبل:** markup دستی بدون `BasePageComponent`، ستون‌های متفاوت
-**بعد:** کاملاً مطابق با `CategoryMainPage` فروشگاه عادی
-
-| ویژگی | قبل | بعد |
-|-------|-----|-----|
-| Wrapper | markup دستی | `BasePageComponent` |
-| لایوت | درخت + گرید | درخت (3 col) + گرید (9 col) — بدون تغییر |
-| ستون‌ها | شناسه، عنوان، توضیحات، وضعیت | شناسه، نام لاتین، عنوان، دسته‌بندی والد، تعداد محصولات، ترتیب، فعال؟ |
-| ستون والد | نداشت | resolve نام والد از لیست |
-| ستون محصولات | نداشت | چیپ Info |
-| ستون ترتیب | نداشت | PropertyColumn |
-| فیلتر | داخل page | داخل `BasePageComponent` |
-| حذف با فرزند | disabled | disabled (حفظ شد) |
-
-**فایل‌ها:**
-- `Pages/DiscountShop/DiscountCategoriesMainPage.razor` — بازنویسی کامل
-- `Pages/DiscountShop/DiscountCategoriesMainPage.razor.cs` — ایجاد (code-behind جدید)
-
----
-
-## ۳. فایل‌های تغییر یافته
-
-| فایل | نوع تغییر | توضیح |
-|------|----------|-------|
-| `Shared/NavMenu.razor` | ✏️ ویرایش | بازسازی ساختار فروشگاه |
-| `Pages/UserOrder/UserOrderMainPage.razor` | ✏️ ویرایش | حذف آمار، رفع PaymentDate |
-| `Pages/UserOrder/UserOrderMainPage.razor.cs` | ✏️ ویرایش | حذف فیلدها/متدهای آمار |
-| `Pages/DiscountShop/DiscountProductsMainPage.razor` | 🔄 بازنویسی | BasePageComponent + ستون‌های جدید |
-| `Pages/DiscountShop/DiscountProductsMainPage.razor.cs` | 🔄 بازنویسی | code-behind کامل |
-| `Pages/DiscountShop/DiscountCategoriesMainPage.razor` | 🔄 بازنویسی | BasePageComponent + ستون‌های جدید |
-| `Pages/DiscountShop/DiscountCategoriesMainPage.razor.cs` | 🆕 ایجاد | code-behind جدید (از @code درون‌خطی) |
-
----
-
-## ۴. الگوی پیاده‌سازی — BasePageComponent
-
-تمام صفحات لیست در BackOffice از `BasePageComponent` استفاده می‌کنند:
-
-```razor
-<BasePageComponent @ref="_basePage" OnClearFilterClick="OnFilterCleared" OnSubmitClick="OnFilterSubmit">
-    <Filters>
-        <!-- فیلدهای فیلتر در MudItem -->
-    </Filters>
-    <Content>
-        <!-- MudDataGrid اصلی -->
-    </Content>
-</BasePageComponent>
-```
-
-**در code-behind:**
-```csharp
-private BasePageComponent _basePage = default!;
-
-private async Task OnFilterSubmit()
-{
-    _basePage.IsFiltered = true;
-    // اعمال فیلتر
-}
-
-private async Task OnFilterCleared()
-{
-    _basePage.IsFiltered = false;
-    // ریست فیلترها
-}
-```
-
----
-
-## ۵. الگوی Code-Behind
-
-به دلیل محدودیت Razor source generator در پروژه، **همه فایل‌هایی که سرویس inject دارند باید code-behind داشته باشند**:
-
-```
-Page.razor         → فقط markup (بدون @code)
-Page.razor.cs      → partial class با [Inject] و منطق
-```
-
-**نکته مهم:** سرویس‌های global از `_Imports.razor` نباید دوباره با `[Inject]` تعریف شوند:
-- ❌ `[Inject] public IDialogService DialogService { get; set; }` — از قبل global
-- ❌ `[Inject] public ISnackbar Snackbar { get; set; }` — از قبل global
-- ❌ `[Inject] public IJSRuntime jsRuntime { get; set; }` — از قبل global (حرف کوچک!)
-- ✅ `[Inject] public IDiscountProductService DiscountProductService { get; set; }` — باید inject شود
-
----
-
-## ۶. مقایسه نهایی فروشگاه عادی و تخفیفی
-
-| جنبه | فروشگاه عادی | فروشگاه تخفیفی | وضعیت |
-|------|-------------|---------------|-------|
-| ارتباط با بکند | gRPC/Protobuf | HTTP REST (IDiscountXxxService) | تفاوت ذاتی |
-| BasePageComponent | ✅ | ✅ | 🟢 یکسان |
-| فیلترهای محصول | جستجو+دسته‌بندی+وضعیت | جستجو+دسته‌بندی+وضعیت+موجودی | 🟢 یکسان+ |
-| ستون‌های محصول | تصویر+عنوان، قیمت، موجودی (چیپ)، وضعیت (چیپ) | تصویر+عنوان، قیمت، تخفیف، موجودی (چیپ)، وضعیت (چیپ) | 🟢 یکسان+ |
-| گالری تصاویر | ✅ GalleryDialog | ✅ ProductImageGallery | 🟢 هر دو دارند |
-| خروجی Excel | ✅ | ✅ | 🟢 یکسان |
-| درخت دسته‌بندی | ✅ | ✅ | 🟢 یکسان |
-| ستون‌های دسته‌بندی | شناسه+نام+عنوان+والد+محصولات+ترتیب+فعال | شناسه+نام+عنوان+والد+محصولات+ترتیب+فعال | 🟢 یکسان |
-| سفارشات Hub | MudTabs (سفارشات + گزارش فروش) | MudTabs (سفارشات + گزارش فروش) | 🟢 یکسان |

ui-modernization/PHASE-1-COMPLETE.md

@@ -1,118 +0,0 @@
-# فاز ۱ — موجودیت‌های بکند CMS ✅ تکمیل شد
-
-> **تاریخ تکمیل:** ۱۴۰۴/۰۴/۲۱ (2026-02-11)  
-> **وضعیت:** ✅ تکمیل — بیلد موفق + Migration ساخته شد
-
----
-
-## خلاصه کارهای انجام شده
-
-### 1.1 موجودیت‌های دامین (8 فایل)
-
-| فایل | مسیر | توضیح |
-|------|------|-------|
-| `BlogPostStatus.cs` | `Domain/Enums/` | enum: Draft=0, Published=1, Scheduled=2, Archived=3 |
-| `BlogPost.cs` | `Domain/Entities/Blog/` | پست بلاگ — عنوان، اسلاگ، خلاصه، محتوای HTML، تصویر، وضعیت، شمارنده بازدید |
-| `BlogCategory.cs` | `Domain/Entities/Blog/` | دسته‌بندی بلاگ — عنوان، اسلاگ، آیکون، ترتیب |
-| `BlogPostCategory.cs` | `Domain/Entities/Blog/` | جدول واسط پست-دسته‌بندی (Many-to-Many) |
-| `BlogPostTag.cs` | `Domain/Entities/Blog/` | جدول واسط پست-تگ (از Tag موجود استفاده شد) |
-| `BlogPostImage.cs` | `Domain/Entities/Blog/` | گالری تصاویر پست — مسیر، عنوان جایگزین، ترتیب |
-| `SitePage.cs` | `Domain/Entities/Content/` | صفحات سایت (درباره ما، تماس با ما) — با کلید یکتا |
-| `SitePageSection.cs` | `Domain/Entities/Content/` | بخش‌های هر صفحه — محتوای HTML، آیکون، تصویر، داده اضافی JSON |
-
-### 1.2 تنظیمات Entity Framework (7 فایل)
-
-| فایل | مسیر | ایندکس‌ها |
-|------|------|----------|
-| `BlogPostConfiguration.cs` | `Configurations/Blog/` | Slug (unique), Status, PublishedAt, IsFeatured, AuthorUserId, Status+PublishedAt |
-| `BlogCategoryConfiguration.cs` | `Configurations/Blog/` | Slug (unique), IsActive |
-| `BlogPostCategoryConfiguration.cs` | `Configurations/Blog/` | FK: BlogPostId + BlogCategoryId |
-| `BlogPostTagConfiguration.cs` | `Configurations/Blog/` | FK: BlogPostId + TagId |
-| `BlogPostImageConfiguration.cs` | `Configurations/Blog/` | FK: BlogPostId |
-| `SitePageConfiguration.cs` | `Configurations/Content/` | PageKey (unique) |
-| `SitePageSectionConfiguration.cs` | `Configurations/Content/` | SitePageId + SectionKey (compound) |
-
-### 1.3 DbContext (2 فایل ویرایش شده)
-
-- `IApplicationDbContext.cs` — افزودن 7 DbSet
-- `ApplicationDbContext.cs` — افزودن 7 DbSet property
-
-### 1.4 تعاریف Proto (4 فایل + csproj)
-
-| فایل | RPCها | csharp_namespace |
-|------|-------|-----------------|
-| `blogpost.proto` | 11 RPC (CRUD + Publish/Archive/ViewCount + BySlug + Published/Featured) | `BlogPost` |
-| `blogcategory.proto` | 6 RPC (CRUD + GetAll + GetActive) | `BlogCategory` |
-| `blogpostimage.proto` | 4 RPC (Add/Delete/Get/Reorder) | `BlogPostImage` |
-| `sitepage.proto` | 8 RPC (Get/GetByKey/Update/GetAll + Section CRUD + Reorder) | `SitePage` |
-
-### 1.5 لایه CQRS Application (≈50 فایل)
-
-#### BlogPost Commands (6 گروه، 14 فایل)
-- `CreateBlogPost` — Command + Handler + Validator (با اعتبارسنجی اسلاگ regex)
-- `UpdateBlogPost` — Command + Handler + Validator (الگوی delete-recreate برای دسته‌بندی/تگ)
-- `DeleteBlogPost` — Command + Handler (soft-delete)
-- `PublishBlogPost` — Command + Result + Handler (تنظیم Status و PublishedAt)
-- `ArchiveBlogPost` — Command + Result + Handler
-- `IncrementViewCount` — Command + Handler
-
-#### BlogPost Queries (5 گروه، 10 فایل)
-- `GetBlogPost` — Query + DTO + Handler (با Include chain)
-- `GetBlogPostBySlug` — Query + Handler (بازاستفاده از BlogPostDto)
-- `GetAllBlogPosts` — Query + ResponseDto + Handler (فیلتر + مرتب‌سازی + صفحه‌بندی)
-- `GetPublishedBlogPosts` — Query + Handler (مشتری‌محور، فقط Published)
-- `GetFeaturedBlogPosts` — Query + Handler (برای لندینگ پیج)
-
-#### BlogCategory CQRS (11 فایل)
-- Commands: Create + Update + Delete (با Validator)
-- Queries: GetBlogCategory + GetAllBlogCategories + GetActiveBlogCategories
-
-#### BlogPostImage CQRS (8 فایل)
-- Commands: Add + Delete + Reorder (با ImageSortItem)
-- Queries: GetBlogPostImages
-
-#### SitePage CQRS (14 فایل)
-- Commands: UpdateSitePage + CreateSection + UpdateSection + DeleteSection + ReorderSections
-- Queries: GetSitePage + GetSitePageByKey + GetAllSitePages
-
-### 1.6 سرویس‌های gRPC WebApi (4 فایل)
-
-| سرویس | الگو | توضیح |
-|-------|------|-------|
-| `BlogPostService.cs` | ترکیبی (دستی + dispatcher) | مپینگ دستی برای لیست‌ها و RepeatedField |
-| `BlogCategoryService.cs` | ترکیبی | dispatcher برای CRUD ساده، دستی برای لیست‌ها |
-| `BlogPostImageService.cs` | ترکیبی | dispatcher + مپینگ دستی Reorder |
-| `SitePageService.cs` | ترکیبی | dispatcher + مپینگ دستی Sections |
-
-### 1.7 Mapping Profiles (2 فایل)
-
-- `BlogPostProfile.cs` — مپینگ PublishBlogPostResult و ArchiveBlogPostResult
-- `BlogCategoryProfile.cs` — مپینگ long → CreateBlogCategoryResponse
-
-### 1.8 EF Migration
-
-- `20260210232742_AddBlogAndContentEntities.cs` — ایجاد 7 جدول جدید
-- **Build:** ✅ موفق (0 Error, warnings مربوط به کد قدیمی)
-
----
-
-## آمار فاز ۱
-
-| متریک | تعداد |
-|-------|-------|
-| فایل‌های جدید | ~65 |
-| فایل‌های ویرایش شده | ~4 |
-| موجودیت‌های دامین | 7 (+1 enum) |
-| تنظیمات EF | 7 |
-| تعاریف Proto | 4 |
-| RPCهای gRPC | 29 |
-| Commands CQRS | 16 |
-| Queries CQRS | 12 |
-| سرویس‌های WebApi | 4 |
-| جداول دیتابیس جدید | 7 |
-
----
-
-## فاز بعدی
-
-**فاز ۲ — پنل مدیریت بلاگ (BackOffice)** — صفحات Blazor WASM برای مدیریت پست‌ها، دسته‌بندی‌ها، تصاویر و صفحات سایت.

ui-modernization/PHASE-3-COMPLETE.md

@@ -1,104 +0,0 @@
-# فاز ۳: صفحات محتوای پویا (Dynamic Content Pages) ✅
-
-## 📋 خلاصه
-تبدیل صفحات **درباره ما** و **تماس با ما** از محتوای هاردکد (hardcoded) به محتوای پویا که از CMS (سرویس SitePage) بارگذاری می‌شود، با پشتیبانی fallback به محتوای پیش‌فرض.
-
----
-
-## 🏗️ معماری
-
-```
-FrontOffice (Blazor Server)
-  ├── About.razor/cs      ─── SitePageService ──► gRPC ──► CMS SitePageContract
-  └── Contact.razor/cs    ─── SitePageService ──► gRPC ──► CMS SitePageContract
-```
-
-### الگوی Fallback:
-```
-OnInitializedAsync() → SitePageService.GetByKeyAsync("about")
-  ├── ✅ Data received → Render dynamic content
-  └── ❌ Error/null    → Render hardcoded fallback content
-```
-
----
-
-## 📁 فایل‌های ایجاد/تغییر یافته
-
-### فایل‌های جدید:
-| فایل | توضیحات |
-|------|---------|
-| `FrontOffice/src/FrontOffice.Main/Utilities/SitePageService.cs` | سرویس SitePage + DTOs (SitePageDto, SitePageSectionDto) |
-| `dbbkup/SeedSitePages.sql` | اسکریپت Seed Data برای درج محتوای اولیه صفحات |
-
-### فایل‌های تغییر یافته:
-| فایل | تغییرات |
-|------|---------|
-| `FrontOffice/src/FrontOffice.Main/ConfigureServices.cs` | اضافه شدن SitePageService + SitePageContractClient به DI |
-| `FrontOffice/src/FrontOffice.Main/Pages/About.razor` | تبدیل به محتوای پویا با fallback |
-| `FrontOffice/src/FrontOffice.Main/Pages/About.razor.cs` | اضافه شدن OnInitializedAsync + بارگذاری sections |
-| `FrontOffice/src/FrontOffice.Main/Pages/Contact.razor` | تبدیل hero/info/social به پویا، فرم بدون تغییر |
-| `FrontOffice/src/FrontOffice.Main/Pages/Contact.razor.cs` | اضافه شدن OnInitializedAsync + ExtraData DTOs |
-
----
-
-## 🔧 جزئیات فنی
-
-### SitePageService
-```csharp
-public class SitePageService
-{
-    Task<SitePageDto?> GetByKeyAsync(string pageKey)  // "about" | "contact"
-}
-```
-
-### SitePageDto Helpers
-```csharp
-GetSection(string sectionKey)      // e.g. "vision", "mission", "contact-info"
-GetSections(string prefix)         // e.g. "value-" → value-1, value-2, ...
-```
-
-### SitePageSectionDto.GetExtraData<T>()
-JSON deserializer برای فیلد ExtraData — استفاده شده در Contact:
-- `ContactInfoData`: address, phone, email, hours
-- `SocialMediaData`: telegram, instagram, linkedin, whatsapp
-
----
-
-## 📄 SectionKey Mapping
-
-### صفحه درباره ما (PageKey: `about`)
-| SectionKey | کاربرد | فیلدهای اصلی |
-|------------|--------|--------------|
-| `vision` | کارت چشم‌انداز | Title, HtmlContent, IconName |
-| `mission` | کارت مأموریت | Title, HtmlContent, IconName |
-| `value-1` ... `value-6` | کارت‌های ارزش‌ها | Title, HtmlContent, IconName |
-| `team-1` ... `team-3` | کارت‌های اعضای تیم | Title(نام), Subtitle(سمت), HtmlContent(توضیحات), ImagePath(آواتار) |
-
-### صفحه تماس با ما (PageKey: `contact`)
-| SectionKey | کاربرد | فیلدهای اصلی |
-|------------|--------|--------------|
-| `contact-info` | اطلاعات تماس | ExtraData → `{address, phone, email, hours}` |
-| `social-media` | شبکه‌های اجتماعی | ExtraData → `{telegram, instagram, linkedin, whatsapp}` |
-
----
-
-## 🗃️ Seed Data
-فایل `dbbkup/SeedSitePages.sql` شامل:
-- **2 صفحه**: about, contact
-- **13 سکشن**: 2 (vision/mission) + 6 (values) + 3 (team) + 2 (contact-info/social-media)
-- تمام محتوای فعلی hardcoded به عنوان داده اولیه درج شده
-
----
-
-## ✅ بیلد
-```
-FrontOffice.Main: 0 Error(s), Build succeeded
-```
-
----
-
-## 📌 نکات مهم
-1. **فرم تماس** (Contact Form) بدون تغییر باقی ماند — منطق سمت کلاینت است نه محتوای CMS
-2. **Fallback**: اگر CMS در دسترس نباشد، محتوای hardcoded نمایش داده می‌شود
-3. **Loading State**: صفحه About دارای حالت loading با spinner
-4. آیکون‌ها در CMS به صورت string ذخیره می‌شوند (مثل `@Icons.Material.Filled.Security`)