admin/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: consolidate 53 files into 15 structured files in 3 folders

Browse Source 
- business/ (5): club-commission, payment, ecommerce, membership, content
- technical/ (5): cms-arch, ui, deployment, migration, api
- overview/ (5): flowcharts, index, changelog, glossary, roadmap
- Removed all old folders: backoffice, cms, deployment, docs, frontoffice, migration, ui-modernization, business (old)
- Updated internal links with relative folder paths
This commit is contained in:
masoodafar-web
2026-02-18 22:29:37 +03:30
parent d7c32dab2a
commit efff5e9cd5
71 changed files with 3632 additions and 32267 deletions
Download Patch File Download Diff File Expand all files Collapse all files
INDEX.md
-145
View File
@@ -1,145 +0,0 @@
# 📚 FourSat Documentation Index
> آخرین بروزرسانی: February 18, 2026
> ۲۲۰ فایل → ۳۰ فایل (تجمیع ۳ فازی + cleanup نهایی)
> آخرین تغییرات: بهبود سیستم موجودی، تصاویر مربعی محصولات، ساده‌سازی صفحات سایت، مرج همه به production
---
## 🔍 راهنمای سریع — کدام مستند را باید ببینم؟
| می‌خواهم بدانم... | مستند |
|-------------------|-------|
| **کل تغییرات BackOffice چه بوده؟** | [`backoffice/BACKOFFICE-CHANGELOG.md`](backoffice/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) |
| **باگ cross-deploy چه بود؟** | [`deployment/CICD-PIPELINE-GUIDE.md`](deployment/CICD-PIPELINE-GUIDE.md) |
| **سرور Production کجاست؟** | [`deployment/INFRASTRUCTURE-GUIDE.md`](deployment/INFRASTRUCTURE-GUIDE.md) |
| **تنظیمات VAT/مالیات؟** | [`cms/payment-gateway.md`](cms/payment-gateway.md) (بخش ۱۰) |
| **سرویس انقضای سفارش؟** | [`cms/payment-gateway.md`](cms/payment-gateway.md) (بخش ۱۱) |
| **بهبود سیستم موجودی؟** | [`cms/INVENTORY-IMPROVEMENTS.md`](cms/INVENTORY-IMPROVEMENTS.md) |
| **تصاویر مربعی محصولات؟** | [`ui-modernization/PRODUCT-IMAGES-SQUARE.md`](ui-modernization/PRODUCT-IMAGES-SQUARE.md) |
| **Audit report کامل BackOffice؟** | [`backoffice/BACKOFFICE-AUDIT.md`](backoffice/BACKOFFICE-AUDIT.md) |
| **تغییرات FrontOffice؟** | [`frontoffice/CHANGELOG.md`](frontoffice/CHANGELOG.md) |
| **طرح یکسان‌سازی UI فرانت؟** | [`frontoffice/UI-UNIFICATION-PLAN.md`](frontoffice/UI-UNIFICATION-PLAN.md) |
| **README پروژه CMS؟** | [`cms/CMS-README.md`](cms/CMS-README.md) |
| **README دیپلوی؟** | [`deployment/DEPLOYMENT-README.md`](deployment/DEPLOYMENT-README.md) |
| **README مهاجرت داده؟** | [`migration/DATAMIGRATION-README.md`](migration/DATAMIGRATION-README.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-STORE-STATUS.md](business/DISCOUNT-STORE-STATUS.md) | 🔄 وضعیت فروشگاه تخفیفی: تخفیف ۱۰۰٪ اجباری + ZarinPal + VAT + ExpirePendingOrders — Production Deploy ✅ |
| [discount-shop-business.md](business/discount-shop-business.md) | فروشگاه تخفیفی: پرداخت ترکیبی، درصد تخفیف، entity design |
| [manual-payment-system.md](business/manual-payment-system.md) | پرداخت دستی: کارت به کارت، تأیید ادمین، آپلود FMS |
## 📂 cms/ — مستندات فنی CMS (۱۹ فایل)
| فایل | توضیح |
|------|-------|
| [CMS-README.md](cms/CMS-README.md) | 📘 README اصلی پروژه 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: ZarinPal مستقیم + تخفیف ۱۰۰٪ اجباری + VAT + ExpirePendingOrders + فیکس DeliveryStatus mapping + دیپلوی Production |
| [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 |
| [INVENTORY-IMPROVEMENTS.md](cms/INVENTORY-IMPROVEMENTS.md) | 🆕 بهبود موجودی: ایجاد خودکار رکورد، سرویس مهاجرت، اتوکامپلیت تخفیفی، UX هوشمند AddStockDialog |
| [SITE-PAGES-SIMPLIFICATION.md](cms/SITE-PAGES-SIMPLIFICATION.md) | ✅ ساده‌سازی صفحات سایت: مدل تایپ‌شده، فرم‌های Shopify-style، لندینگ/درباره/تماس/مجوزها |
| [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/ — مستندات استقرار (۶ فایل)
| فایل | توضیح |
|------|-------|
| [DEPLOYMENT-README.md](deployment/DEPLOYMENT-README.md) | 📘 README اصلی پوشه 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، عیب‌یابی، SERVER_PASSWORD، باگ cross-deploy، قالب workflow Production |
| [INFRASTRUCTURE-GUIDE.md](deployment/INFRASTRUCTURE-GUIDE.md) | 🔄 مشخصات سرور Staging + Production، DB credentials دوگانه، Gitea، Kestrel protocol، Ingress annotations، Proto v0.0.179 |
| [SERVER-MIRRORS-CONFIG.md](deployment/SERVER-MIRRORS-CONFIG.md) | 🔄 تنظیمات mirror: K3s registries.yaml Staging + Production، 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، بازنویسی ۴ صفحه |
| [PRODUCT-IMAGES-SQUARE.md](ui-modernization/PRODUCT-IMAGES-SQUARE.md) | 🆕 تصاویر مربعی محصولات: aspect-ratio 1:1 در ۹ فایل، هر دو فروشگاه، همه سایزها |
## 📂 migration/ — مستندات مهاجرت BFF→CMS (۷ فایل)
| فایل | توضیح |
|------|-------|
| [DATAMIGRATION-README.md](migration/DATAMIGRATION-README.md) | 📘 README پروژه DataMigration |
| [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 |
---
## � backoffice/ — مستندات پنل مدیریت (۲ فایل)
| فایل | توضیح |
|------|-------|
| [BACKOFFICE-AUDIT.md](backoffice/BACKOFFICE-AUDIT.md) | 🔍 گزارش آدیت عمیق BackOffice: ۵۸ آیتم، ۹۸٪ تکمیل، ۶ فاز |
| [BACKOFFICE-CHANGELOG.md](backoffice/BACKOFFICE-CHANGELOG.md) | 📝 چنج‌لاگ BackOffice: فاز ۱ تا ۱۷ |
## 📂 frontoffice/ — مستندات فرانت‌آفیس (۲ فایل)
| فایل | توضیح |
|------|-------|
| [CHANGELOG.md](frontoffice/CHANGELOG.md) | 📝 چنج‌لاگ FrontOffice |
| [UI-UNIFICATION-PLAN.md](frontoffice/UI-UNIFICATION-PLAN.md) | 🎨 طرح یکسان‌سازی UI فروشگاه‌ها |
---
## �📊 آمار تجمیع
| مرحله | تعداد فایل | حذف شده |
|-------|-----------|---------|
| اولیه | 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** | — |
| session Inventory + Images + Docs (+2 docs) | **39** | — |
| consolidate project-level docs (+7 files, 2 folders) | **46** | — |
| **نهایی** | **46 + INDEX** | **۱۹۱ فایل حذف/ادغام** |
SHOP-UNIFICATION.md
-521
View File
@@ -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 ← قیمت (ریال)
```
backoffice/BACKOFFICE-AUDIT.md
-1010
View File
File diff suppressed because it is too large Load Diff
backoffice/BACKOFFICE-CHANGELOG.md
-850
View File
@@ -1,850 +0,0 @@
# 📝 BackOffice — Changelog
**آخرین بروزرسانی:** اسفند ۱۴۰۴ (February 18, 2026)
---
## 🏷 فاز ۱۷ — بهبود سیستم موجودی + اتوکامپلیت تخفیفی (اسفند ۱۴۰۴)
> **هدف:** UX هوشمند ورود کالا با autocomplete اختصاصی برای هر نوع فروشگاه
### ۱۷.۱ — کامپوننت DiscountProductsAutoComplete ✅
- **فایل‌ها:** `Pages/AutoComplete/DiscountProductsAutoComplete.razor(.cs)`
- **الگو:** مشابه `ProductsAutoComplete` موجود
- **gRPC Client:** `DiscountProductContract.DiscountProductContractClient`
- **دِبانس:** ۷۰۰ms، حداکثر ۹ نتیجه
- **نکته:** `SearchQuery` از نوع `string` (نه `StringValue`)
### ۱۷.۲ — UX هوشمند AddStockDialog ✅
- **فایل:** `Pages/Inventory/Components/AddStockDialog.razor`
- **تغییر:** فیلد عددی خام شناسه محصول → autocomplete هوشمند
- **رفتار:**
- انتخاب «فروشگاه عادی» → نمایش `ProductsAutoComplete`
- انتخاب «فروشگاه اعتباری» → نمایش `DiscountProductsAutoComplete`
- ولیدیشن قبل از submit
### ۱۷.۳ — Merge به production ✅
- **برنچ:** `kub-stage` → `production`
- **ریموت:** `kub-stage` (Gitea)
---
## 🏷 فاز ۱۶ — ساده‌سازی صفحات سایت + ادیتورهای Shopify-style (اسفند ۱۴۰۴)
> **هدف:** مدیریت typed صفحات سایت با فرم‌های اختصاصی
### ۱۶.۱ — صفحه مدیریت PageSettings ✅
- **فایل‌ها:** `Pages/Content/PageSettingsManagementPage.razor(.cs)`
- **قابلیت‌ها:** لیست ۴ صفحه ثابت (landing/about/contact/licenses)، ویرایش تنظیمات، مدیریت تصاویر
### ۱۶.۲ — ادیتورهای اختصاصی Shopify-style ✅
| فایل | صفحه |
|------|------|
| `AboutSettingsEditor.razor` | درباره ما: ارزش‌ها + اعضای تیم |
| `ContactSettingsEditor.razor` | تماس: آدرس/تلفن/ایمیل/شبکه‌های اجتماعی |
| `LandingSettingsEditor.razor` | لندینگ: Hero + Steps + Features + Stats + FAQ + Testimonials |
| `LicensesSettingsEditor.razor` | مجوزها: JSON array |
### ۱۶.۳ — سرویس gRPC و دیالوگ‌ها ✅
- `ISitePageSettingsService` + `SitePageSettingsService`
- `PageSettingsEditDialog` + `PageImagesDialog` + `PageImageEditDialog`
- `PageSettingsModels.cs` — مدل‌های typed برای JSON
### ۱۶.۴ — Proto v0.0.180 ✅
- **تغییر:** `Foursat.CMSMicroservice.Protobuf` → `0.0.180`
---
## 🏷 فاز ۱۵ — Production Deploy + فیکس CI/CD Cross-Deploy (اسفند ۱۴۰۴)
> **هدف:** دیپلوی به سرور Production و رفع باگ cross-deploy
### ۱۵.۱ — Merge به برنچ production ✅
- **کامیت:** `4454b8d` — merge `kub-stage` → `production`
- **ریموت:** `kub-stage` (Gitea)
### ۱۵.۲ — فیکس باگ Cross-Deploy ✅
- **مشکل:** Gitea Act Runner همه workflowهای `.gitea/workflows/` را اجرا می‌کرد — بدون توجه به `branches:` filter
- **عارضه:** push به `production` باعث دیپلوی همزمان به staging و production می‌شد
- **رفع:** حذف فایل‌های workflow staging از برنچ production
- **فایل حذف شده:** `.gitea/workflows/deploy.yml` (staging) از برنچ production
### ۱۵.۳ — بروزرسانی Proto به v0.0.179 ✅
- **تغییر:** `Foursat.CMSMicroservice.Protobuf` → `0.0.179`
- **فایل:** `BackOffice.csproj`
### ۱۵.۴ — فیکس K8S_SERVER در prod-deploy.yml ✅
- **مشکل:** `K8S_SERVER` هنوز `194.5.195.53` (staging) بود
- **رفع:** تغییر به `45.149.79.127` (production)
- **فیکس اضافی:** `kubectl rollout restart` → `kubectl set image` (تا ایمیج SHA-tagged واقعاً set بشه)
### ۱۵.۵ — ساخت appsettings.Production.json ✅
- **مشکل:** فایل `appsettings.Production.json` وجود نداشت → `GwUrl` fallback به `localhost`
- **رفع:** ساخت `wwwroot/appsettings.Production.json` با `GwUrl=https://cms.kbs1.ir`
### ۱۵.۶ — فیکس nginx image path در Dockerfile (production branch) ✅
- **مشکل:** Dockerfile روی برنچ production از `library/nginx:alpine` استفاده می‌کرد — وجود نداشت
- **ارور:** `manifest for 194.5.195.53:32082/library/nginx:alpine not found`
- **رفع:** تغییر به `194.5.195.53:32082/nginx:alpine`
- **کامیت:** `743403e` (مستقیم روی برنچ production)
---
## 🏷 فاز ۱۴ — فیکس Docker Build + Deployment (بهمن ۱۴۰۴)
> **هدف:** رفع مشکلات Docker build و CI/CD pipeline
### ۱۴.۱ — تغییر به NuGet Package ✅
- **مشکل:** `ProjectReference` به `../../../CMS/src/CMSMicroservice.Protobuf/` خارج از Docker build context بود
- **رفع:** تغییر به `PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="0.0.178"`
- **فایل:** `BackOffice.csproj`
### ۱۴.۲ — حذف COPY libs/ از Dockerfile ✅
- **مشکل:** `COPY ["libs/", "libs/"]` فیل می‌شد — `libs/` خارج از build context
- **رفع:** حذف خط — دیگه نیازی به DLLهای BFF نیست
- **فایل:** `Dockerfile`
### ۱۴.۳ — تغییر nginx:alpine به رجیستری لوکال ✅
- **مشکل:** `FROM nginx:alpine` از Docker Hub → TLS handshake timeout
- **رفع:** `FROM 194.5.195.53:32082/nginx:alpine`
- **فایل:** `Dockerfile`
### ۱۴.۴ — اضافه شدن SERVER_PASSWORD secret ✅
- **مشکل:** مرحله Deploy to Kubernetes با `Permission denied` فیل می‌شد
- **رفع:** سکرت `SERVER_PASSWORD` به ریپو Gitea اضافه شد (BackOffice + FrontOffice)
---
## 🏷 فاز ۱۳ — بهبودهای UI بک‌آفیس (بهمن ۱۴۰۴)
> **هدف:** رفع مشکلات بصری، بهبود UX فرم‌ها و ناوبری
### ۱۳.۱ — فیکس کامپوننت Image (پیشوند `/uploads/`) ✅
- **مشکل:** تصاویر آپلود‌شده (بلاگ، صفحات سایت، سکشن‌ها) در بک‌آفیس نمایش داده نمی‌شدند — مسیر `GwUrl + Src` با مسیر `UploadsController` هماهنگ نبود
- **رفع:** اضافه شدن `/uploads/` بین `FileBaseUrl` و مسیر نسبی تصویر
- **فایل:** `BackOffice/Common/BaseComponents/Image.razor.cs`
### ۱۳.۲ — فیکس فیلتر هفته در گزارش‌های هفتگی ✅
- **مشکل:** فیلتر هفته از `MudTextField` (ورودی متنی) استفاده می‌کرد — کاربر باید عدد حدس می‌زد
- **رفع:** جایگزینی با `WeekNumberPicker` — انتخاب هفته از لیست با بایندینگ `WeekDefinitionId`
- **فایل‌ها:**
- `CMS/src/CMSMicroservice.Protobuf/Protos/commission.proto` — تغییر فیلدها از `StringValue` به `Int64Value`
- `CMS/.../CommissionCQ/Queries/GetAllWeeklyPools/GetAllWeeklyPoolsQuery.cs` + `Handler.cs`
- `BackOffice/Pages/Commission/WeeklyReports.razor`
### ۱۳.۳ — فیکس دانلود PDF قراردادها ✅
- **مشکل:** فیلد `SignedPdfFile` محتوای HTML کامل دارد (نه URL فایل PDF) — دکمه دانلود کار نمی‌کرد
- **رفع:** تابع JS جدید `jsHtmlToPdf()` برای باز کردن HTML در پنجره جدید و چاپ/ذخیره به‌عنوان PDF
- **فایل‌ها:**
- `BackOffice/wwwroot/js/main.js` — تابع `jsHtmlToPdf`
- `BackOffice/Pages/Contract/UserContractPage.razor`
- `BackOffice/Pages/Contract/ContractDetailsDialog.razor`
### ۱۳.۴ — یکسان‌سازی ارتفاع ویرایشگر HTML ✅
- **مشکل:** ارتفاع `MudHtmlEditor` در صفحات مختلف متفاوت بود — برخی خیلی کوتاه
- **رفع:** اضافه شدن `MinHeight="300px"` به تمام ۷ ویرایشگر HTML
- **فایل‌ها:** `BlogPostEditDialog`, `SitePageSectionEditDialog`, `DiscountShop/ProductFormDialog`, `Package/CreateDialog`, `Package/UpdateDialog`, `Products/CreateDialog`, `Products/UpdateDialog`
### ۱۳.۵ — تولید خودکار اسلاگ بلاگ ✅
- **مشکل:** کاربر باید اسلاگ URL را دستی وارد می‌کرد — غیرضروری و مستعد خطا
- **رفع:** حذف فیلد اسلاگ از فرم، تولید خودکار `post-{GUID}` در بک‌اند (حداکثر ۲۰ کاراکتر)
- **فایل‌ها:**
- `CMS/.../BlogPostCQ/Commands/CreateBlogPost/CreateBlogPostCommandHandler.cs`
- `CMS/.../BlogPostCQ/Commands/UpdateBlogPost/UpdateBlogPostCommandHandler.cs`
- `BackOffice/Pages/Blog/Components/BlogPostEditDialog.razor`
### ۱۳.۶ — انتقال تگ‌ها به منوی جداگانه ✅
- **مشکل:** تگ‌ها فقط از تب سوم بلاگ قابل دسترسی بودند — ولی تگ‌ها بین محصولات و بلاگ مشترکند
- **رفع:** اضافه شدن مسیر `/tags` به `TagManagementPage`، لینک جدید «مدیریت تگ‌ها» در منوی ناوبری، حذف تب تگ‌ها از `BlogHub`
- **فایل‌ها:**
- `BackOffice/Pages/Tag/TagManagementPage.razor`
- `BackOffice/Shared/NavMenu.razor`
- `BackOffice/Pages/Blog/BlogHub.razor`
### ۱۳.۷ — تولید خودکار کلید سکشن ✅
- **مشکل:** کاربر باید کلید سکشن صفحه سایت را دستی وارد می‌کرد (مثلاً `about-us-section`)
- **رفع:** فیلد اختیاری شد، تولید خودکار `section-{GUID}` (حداکثر ۲۰ کاراکتر) در هندلر CMS
- **فایل‌ها:**
- `CMS/.../SitePageCQ/Commands/CreateSitePageSection/CreateSitePageSectionCommandHandler.cs`
- `CMS/.../SitePageCQ/Commands/CreateSitePageSection/CreateSitePageSectionCommandValidator.cs`
- `BackOffice/Pages/Content/Components/SitePageSectionEditDialog.razor`
---
## 🏷 فاز ۱۲ — فیکس فلوی ثبت‌نام / ورود FrontOffice (بهمن ۱۴۰۴)
> **هدف:** رفع ۳ باگ بحرانی در فلوی ثبت‌نام و ورود FrontOffice
> **مستند کامل:** [`totalDoc/cms/REGISTRATION-FLOW-FIXES.md`](../../totalDoc/cms/REGISTRATION-FLOW-FIXES.md)
### ۱۲.۱ — رفع ایجاد کاربر جدید در VerifyOtpToken 🔴 ✅
- **مشکل:** `UserCQ/VerifyOtpTokenCommandHandler` کاربران جدید ایجاد نمی‌کرد — فقط خطای «کاربر یافت نشد»
- **رفع:** اضافه شدن لاجیک کامل: اعتبارسنجی کد معرف، بررسی ظرفیت درخت باینری (حداکثر ۲ فرزند)، تعیین شاخه (چپ/راست)، ایجاد User + UserRole + UserWallet، رویدادهای دامنه
- **فایل:** `CMS/src/CMSMicroservice.Application/UserCQ/Commands/VerifyOtpToken/VerifyOtpTokenCommandHandler.cs`
### ۱۲.۲ — رفع جستجوی موبایل در AcceptContract 🔴 ✅
- **مشکل:** `_currentUserService.Username` = `"{FirstName} {LastName}"` — نه شماره موبایل! در نتیجه OTP و کاربر هیچوقت پیدا نمی‌شد
- **رفع:** ابتدا کاربر از `UserId` پیدا شود، سپس `user.Mobile` برای جستجوی OTP استفاده شود
- **فایل:** `CMS/src/CMSMicroservice.Application/UserCQ/Commands/AcceptContract/AcceptContractCommandHandler.cs`
### ۱۲.۳ — رفع `IsCompleteRegister()` در FrontOffice 🟡 ✅
- **مشکل:** `InitUserAuthInfo().GetAwaiter()` بدون `.GetResult()` — عملیات async اجرا نمی‌شود، منوی کناری وضعیت نادرست
- **رفع:** تغییر به `InitUserAuthInfo().GetAwaiter().GetResult()`
- **فایل:** `FrontOffice/src/FrontOffice.Main/Utilities/AuthService.cs`
---
## 🏷 فاز ۱۱ — رفع خطای صفحات + سرویس عمومی تصاویر (بهمن ۱۴۰۴)
> **هدف:** رفع خطای ۳ صفحه BackOffice + ایجاد اندپوینت HTTP عمومی برای سرو تصاویر
### ۱۱.۱ — سرویس عمومی سرو تصاویر (CMS) ✅
- **`UploadsController`** — اندپوینت `GET /uploads/{path}` برای سرو مستقیم فایل‌ها
- `[AllowAnonymous]` — بدون نیاز به احراز هویت
- کش مرورگر ۲۴ ساعته (`ResponseCache`)
- پشتیبانی از Range Requests
- **FMS Fallback:** اگر فایل محلی نباشد، از `dl.afrino.co` دانلود و کش می‌شود
- `IHttpClientFactory` با named client `"FMS"` (timeout: 30s)
- **فایل‌ها:** `CMS/WebApi/Controllers/UploadsController.cs`, `CMS/WebApi/Program.cs`
### ۱۱.۲ — رفع صفحه «صفحات سایت» ✅
- اضافه شدن **دکمه «افزودن صفحه جدید»** به بالای صفحه
- اضافه شدن **دکمه «حذف»** (آیکون قرمز) برای هر ردیف
- ایجاد **`SitePageCreateDialog`** — دیالوگ ایجاد صفحه جدید با فیلدها:
- کلید صفحه (PageKey)، عنوان، توضیحات متا، عنوان هیرو، زیرعنوان هیرو، تصویر هیرو، وضعیت
- Proto: اضافه شدن `CreateSitePage` و `DeleteSitePage` RPC
- CQRS: `CreateSitePageCommand/Handler` و `DeleteSitePageCommand/Handler`
- **فایل‌ها:**
- `sitepage.proto` — 2 RPC جدید + پیام‌های Request/Response
- `SitePageCQ/Commands/CreateSitePage/` — Command + Handler
- `SitePageCQ/Commands/DeleteSitePage/` — Command + Handler
- `CMS/WebApi/Services/SitePageService.cs` — 2 override جدید
- `BackOffice/Services/Content/ISitePageService.cs` — `CreateAsync` + `DeleteAsync` + `SitePageCreateDto`
- `BackOffice/Services/Content/SitePageService.cs` — پیاده‌سازی Create/Delete
- `BackOffice/Pages/Content/SitePageManagementPage.razor` — دکمه‌های Add/Delete
- `BackOffice/Pages/Content/SitePageManagementPage.razor.cs` — متدهای CreatePage/DeletePage
- `BackOffice/Pages/Content/Components/SitePageCreateDialog.razor` + `.razor.cs`
### ۱۱.۳ — رفع صفحه «قراردادها» (Contracts) ✅
- **مشکل:** صفحه `/contracts` اصلاً بارگذاری نمی‌شد — crash در DI
- **علت:** `UserContractContract.UserContractContractClient` در DI ثبت نشده بود
- **رفع:** اضافه شدن `using CMSMicroservice.Protobuf.Protos.UserContract` و ثبت gRPC client
- **فایل:** `BackOffice/Common/Configure/ConfigureService.cs`
### ۱۱.۴ — رفع صفحه «کیف پول کاربران» (Wallets) ✅
- **مشکل:** صفحه `/wallets` اصلاً بارگذاری نمی‌شد — crash در DI
- **علت:** دو سرویس ثبت نشده بود:
- `UserWalletContract.UserWalletContractClient`
- `UserWalletChangeLogContract.UserWalletChangeLogContractClient`
- **رفع:** اضافه شدن using‌ها و ثبت هر دو gRPC client
- **فایل:** `BackOffice/Common/Configure/ConfigureService.cs`
---
## 🏷 فاز ۱۰ — بهبود مدیریت محتوا: بلاگ + صفحات سایت (بهمن ۱۴۰۴)
> **هدف:** فعال‌سازی آپلود تصویر باینری و ادیتور HTML در صفحات بلاگ و صفحات سایت
### ۱۰.۱ — بهبود ادیتور پست بلاگ ✅
- **`MudTextField Lines="10"`** → **`MudHtmlEditor`** برای ویرایش محتوای HTML
- **فیلد متنی مسیر تصویر** → **`MudFileUpload`** با پیش‌نمایش تصویر (`Image` component)
- حذف فیلد `FeaturedImageThumbnailPath` (تولید خودکار توسط بک‌اند)
- اضافه شدن `MudForm` با اعتبارسنجی + حالت بارگذاری (`_loading`)
- مدیریت خطا: try-catch + Snackbar
- **فایل‌ها:** `Pages/Blog/Components/BlogPostEditDialog.razor` + `.razor.cs`
### ۱۰.۲ — بهبود ادیتور صفحه سایت ✅
- **فیلد متنی Hero Image** → **`MudFileUpload`** با پیش‌نمایش تصویر
- اضافه شدن `MudForm` + حالت آپلود + مدیریت خطا
- **فایل‌ها:** `Pages/Content/Components/SitePageEditDialog.razor` + `.razor.cs`
### ۱۰.۳ — بهبود ادیتور بخش صفحه سایت (Section) ✅
- **`MudTextField Lines="8"`** → **`MudHtmlEditor`** برای ویرایش محتوای HTML بخش‌ها
- **فیلدهای متنی تصویر/thumbnail** → **`MudFileUpload`** با پیش‌نمایش
- اضافه شدن `MudForm` + حالت آپلود + مدیریت خطا
- **فایل‌ها:** `Pages/Content/Components/SitePageSectionEditDialog.razor` + `.razor.cs`
### ۱۰.۴ — تغییرات Proto ✅
| Proto | تغییر |
|-------|-------|
| `blogpost.proto` | اضافه شدن `BlogImageFileModel` + فیلد `image_file` در Create/Update |
| `sitepage.proto` | اضافه شدن `SitePageImageFileModel` + فیلد `image_file` در Update/CreateSection/UpdateSection |
### ۱۰.۵ — تغییرات CQRS (بک‌اند CMS) ✅
- **Commands:** اضافه شدن `ImageFileBytes`, `ImageMime`, `ImageFileName` به:
- `CreateBlogPostCommand`, `UpdateBlogPostCommand`
- `UpdateSitePageCommand`, `CreateSitePageSectionCommand`, `UpdateSitePageSectionCommand`
- **Handlers:** تزریق `IFileManager` + فراخوانی `UploadImageAsync`:
- BlogPost → `Images/BlogPosts/`
- SitePage → `Images/SitePages/`
- SitePageSection → `Images/SitePageSections/`
### ۱۰.۶ — تغییرات سرویس‌های BackOffice ✅
- `BlogPostService.cs` — ارسال `BlogImageFileModel` با `ByteString.CopyFrom(dto.ImageFile)`
- `SitePageService.cs` — ارسال `SitePageImageFileModel` در Update/CreateSection/UpdateSection
- **DTOs:** اضافه شدن `ImageFile`, `ImageMime`, `ImageFileName` به `BlogPostEditDto`, `SitePageEditDto`, `SitePageSectionEditDto`
### خلاصه آمار فاز ۱۰
| معیار | تعداد |
|---|---|
| فایل‌های proto تغییریافته | 2 |
| Command‌های بروزشده | 5 |
| Handler‌های بروزشده | 5 |
| سرویس‌های gRPC تغییریافته | 2 (BlogPostService + SitePageService) |
| دیالوگ‌های UI بازنویسی‌شده | 3 (BlogPost, SitePage, SitePageSection) |
| سرویس‌های BackOffice بروزشده | 2 |
| DTO‌های بروزشده | 3 |
| Build | 0 Error ✅ (هر ۳ پروژه) |
---
## 🏷 فاز ۹ — معماری مدیریت فایل + رفع سفارشات + مهاجرت DB (بهمن ۱۴۰۴)
> **مستند کامل معماری فایل:** [`totalDoc/cms/FILE-MANAGEMENT-ARCHITECTURE.md`](../../totalDoc/cms/FILE-MANAGEMENT-ARCHITECTURE.md)
### ۹.۱ — حذف کد مرده FMS ✅
- حذف ۳ فایل غیرقابل استفاده مرتبط با FMS خارجی (`https://dl.afrino.co`):
| فایل حذف‌شده | شرح |
|-------------|------|
| `Infrastructure/Services/FmsFileManager.cs` | پیاده‌سازی HTTP upload به FMS |
| `Application/Common/FileManager/FileManagementService.cs` | سرویس قدیمی مدیریت فایل |
| `Application/Common/FileManager/IFileManagementService.cs` | اینترفیس قدیمی |
### ۹.۲ — رفع صفحه سفارشات (Orders) ✅
**مشکل ۱ — صفحه خالی (بدون پیغام خطا)**
- **علت:** `ServerReload` بدون try-catch — exception‌های gRPC ساکت می‌شدند
- **رفع:** اضافه شدن try-catch + نمایش خطا با Snackbar
- **فایل:** `Pages/UserOrder/UserOrderMainPage.razor.cs`
**مشکل ۲ — Shadow FK تکراری در OrderVAT**
- **علت:** `.WithOne()` بدون inverse navigation → EF Core یک shadow FK اضافی می‌ساخت
- **رفع:** `.WithOne()` → `.WithOne(x => x.OrderVAT)`
- **فایل:** `Persistence/Configurations/OrderVATConfiguration.cs`
**مشکل ۳ — فیلترهای oneof همیشه فعال**
- **علت:** فیلدهای proto `oneof` مقدار پیش‌فرض enum دارند (هیچ‌وقت null نیستند)، پس `PaymentStatus != null` همیشه true بود
- **رفع:** `PaymentStatus != null` → `HasPaymentStatus == true` (و مشابه برای DeliveryStatus و PaymentMethod)
- **فایل‌ها:** `UserOrderService.cs` — هر دو متد `GetAllUserOrderByFilter` و `GetCustomerOrders`
### ۹.۳ — مهاجرت DB: حذف محدودیت طول ستون‌های تصویر ✅
- **علت:** data URI‌های base64 بزرگ‌تر از `nvarchar(500)` بودند → truncation خاموش
- **رفع:** حذف `HasMaxLength(500)` از تمام ستون‌های image path
- **Migration:** `RemoveImagePathMaxLength`
| Entity | ستون‌ها |
|--------|---------|
| Product | `ImagePath`, `ImageThumbnailPath` |
| DiscountProduct | `ImagePath`, `ImageThumbnailPath` |
| Category | `ImagePath` |
| DiscountCategory | `ImagePath` |
| BlogPost | `FeaturedImagePath`, `FeaturedImageThumbnailPath` |
| SitePage | `HeroImagePath` |
| SitePageSection | `ImagePath`, `ImageThumbnailPath` |
### ۹.۴ — بازنویسی کامل مدیریت فایل: ذخیره دیسکی ✅
**معماری قبلی:** ذخیره data URI مستقیم در DB (ناکارآمد + حجم بالا)
**معماری جدید:**
1. فایل‌ها در دیسک ذخیره می‌شوند: `Uploads/Images/{folder}/{guid}.jpg`
2. مسیر نسبی در DB ذخیره می‌شود
3. `ImagePathResolverInterceptor` هنگام serve تبدیل به base64 می‌کند
**فایل‌های اصلی:**
| فایل | شرح |
|------|------|
| `Application/Common/FileManager/IFileManager.cs` | اینترفیس: Upload, UploadImage, Delete, ResolveImageUrl |
| `Infrastructure/Services/LocalFileManager.cs` | پیاده‌سازی: ImageSharp, main 1200×1200 + thumb 300×300, JPEG Q75 |
| `WebApi/Interceptors/ImagePathResolverInterceptor.cs` | gRPC Interceptor: walk بازگشتی response → تبدیل path به data URI |
**تنظیمات:**
- `FileStorage:UploadPath` → پوشه ریشه آپلود (پیش‌فرض: `AppContext.BaseDirectory/Uploads`)
- gRPC MaxReceiveMessageSize: 50MB
### ۹.۵ — پاکسازی LoggingBehaviour ✅
- **قبل:** فیلدهای باینری (byte[] تصاویر) کامل در لاگ چاپ می‌شدند → لاگ‌های چند مگابایتی
- **بعد:**
- فرمت: `JsonFormatter.Default.Format()` به جای `{@Request}`
- Regex: حذف فیلدهای باینری (`File`, `ImageFile`, `image_file`, `file`)
- محدودیت: حداکثر 2000 کاراکتر
- **فایل:** `WebApi/Common/Behaviours/LoggingBehaviour.cs`
### خلاصه آمار فاز ۹
| معیار | تعداد |
|---|---|
| فایل‌های حذف‌شده (کد مرده) | 3 |
| فایل‌های جدید | 2 (LocalFileManager بازنویسی + ImagePathResolverInterceptor) |
| فایل‌های ویرایش‌شده | ~12 |
| باگ‌های رفع‌شده | 4 (Orders page ×3 + DB truncation) |
| Migration‌های جدید | 1 (RemoveImagePathMaxLength) |
| ستون‌های DB تغییریافته | 9 (nvarchar(500) → nvarchar(max)) |
| Build | 0 Error ✅ (هر ۳ پروژه) |
---
## 🏷 فاز ۸ — یکسان‌سازی فروشگاه عادی و تخفیفی (بهمن ۱۴۰۴)
> **مستند کامل:** [`totalDoc/ui-modernization/BACKOFFICE-STORE-UNIFICATION.md`](../../totalDoc/ui-modernization/BACKOFFICE-STORE-UNIFICATION.md)
### ۸.۱ — بازسازی NavMenu ✅
- ایجاد دو NavGroup مجزا: «فروشگاه عادی» و «فروشگاه تخفیفی»
- حذف «ویرایش دسته‌جمعی» از منو
- انبارداری → گروه مستقل | پکیج‌ها → آیتم مستقل
- **فایل:** `Shared/NavMenu.razor`
### ۸.۲ — حذف گزارش‌های کوچک از سفارشات ✅
- حذف کارت‌های آماری (TotalOrders + TotalAmount) و نمودار Bar ارسال
- حذف فیلدها: `_stats`, `_statusChartLabels`, `_statusChartSeries`
- حذف متد `UpdateStats()` و کلاس `OrderStatsViewModel`
- عنوان: «سفارش‌های کاربر» → «لیست سفارشات»
- **فایل‌ها:** `Pages/UserOrder/UserOrderMainPage.razor` + `.razor.cs`
### ۸.۳ — رفع باگ لیست خالی سفارشات ✅
- **علت:** `PaymentDate.ToDateTime()` بدون null check → exception ساکت در WASM
- **رفع:** `@if (context.Item.PaymentDate != null)` + fallback "-"
- **فایل:** `Pages/UserOrder/UserOrderMainPage.razor`
### ۸.۴ — بازنویسی صفحه محصولات تخفیفی ✅
- تبدیل به `BasePageComponent` (مطابق فروشگاه عادی)
- فیلترهای جدید: وضعیت + موجودی
- ستون‌های جدید: تصویر inline + عنوان truncate + چیپ رنگی موجودی + چیپ وضعیت
- **فایل‌ها:** `Pages/DiscountShop/DiscountProductsMainPage.razor` + `.razor.cs` (بازنویسی کامل)
### ۸.۵ — بازنویسی صفحه دسته‌بندی‌های تخفیفی ✅
- تبدیل به `BasePageComponent` (مطابق فروشگاه عادی)
- ستون‌های جدید: نام لاتین، دسته‌بندی والد (resolve شده)، تعداد محصولات، ترتیب
- code-behind جدید (`@code` درون‌خطی → `.razor.cs`)
- **فایل‌ها:** `Pages/DiscountShop/DiscountCategoriesMainPage.razor` + `.razor.cs` (بازنویسی کامل)
### خلاصه آمار فاز ۸
| معیار | تعداد |
|---|---|
| فایل‌های بازنویسی‌شده | 4 |
| فایل‌های ویرایش‌شده | 3 |
| باگ‌های رفع‌شده | 2 (PaymentDate null + لیست خالی) |
| Build | 0 Error ✅ |
---
## 🏷 فاز ۷ — پس از اجرای Audit v7.0 (تیر ۱۴۰۴)
### خلاصه تغییرات
- **۵۷ مورد** از ۵۸ یافته audit اجرا شد (≈98%)
- **تمام ۱۶ مورد بحرانی 🔴** حل شد
- **تمام ۱۸ مورد جزئی 🟢** حل شد
- **فازهای ۱ تا ۶ تکمیل شدند** (به‌جز DayaLoan و Audit Trail که نیاز به بک‌اند دارند)
- **فاز ۷** — Global Search, Notification Bell, NavMenu Badge, Export Excel 4 صفحه جدید
- **۱۳+ فایل جدید** ساخته شد
- **۹ صفحه** ادغام شدند (۱۴ صفحه → ۵ صفحه)
- **Build**: 0 error ✅
---
## فاز ۷ — Global Search + Notifications + Export All + NavMenu Badge (v7.0)
### 6.5 — Badge Pending در NavMenu — ✅
- **`NavMenu.razor`**: اضافه شدن `MudBadge` روی لینک «درخواست‌های برداشت»
- نمایش تعداد درخواست‌های Pending بصورت real-time از gRPC (`CommissionContract.GetWithdrawalRequestsAsync` با `Status=0`)
- fire-and-forget در `OnInitializedAsync` با try/catch silent
### 6.2 — Global Search در AppBar — ✅
- **فایل جدید**: `Shared/GlobalSearch.razor`
- `MudAutocomplete<SearchResultItem>` با Debounce 400ms
- دو نوع جستجو: ۱) نام صفحات (۱۵ صفحه اصلی) ۲) کاربران از gRPC (`UserContract.GetAllUserByFilterAsync`)
- Template سفارشی با آیکون + عنوان + زیرنویس
- ناوبری خودکار با `Navigation.NavigateTo`
- اضافه شده در `MainLayout.razor` داخل `<AuthorizeView>`
- CSS در `app.css` — rounded border-radius 24px, compact padding
### 6.1 — Notification Bell (placeholder) — ✅
- **`MainLayout.razor`**: اضافه شدن `MudMenu` + `MudBadge` (Dot) + آیکون Notifications
- Dropdown با هدر «اعلان‌ها» + placeholder «اعلان جدیدی وجود ندارد»
- آماده اتصال به بک‌اند — فقط `Visible=true` و populate items
### 6.3 — Export Excel صفحات جدید — ✅ (۱۰ صفحه کامل)
- **۴ صفحه جدید** اضافه شدند به ۶ صفحه قبلی:
1. **UserMainPage** — خروجی CSV: شناسه, موبایل, نام, نام خانوادگی, کدملی
2. **DiscountOrdersMainPage** — خروجی CSV: شماره سفارش, تاریخ, مبلغ کل, تخفیف, قابل پرداخت, تعداد, وضعیت, پرداخت
3. **ManualPayments** — خروجی CSV: شناسه, شناسه کاربر, نام کاربر, مبلغ, نوع, وضعیت, تاریخ
4. **InventoryMainPage** — خروجی CSV: شناسه, محصول, انبار, موجودی, رزرو, قابل فروش, حد هشدار, وضعیت
- هر ۴ صفحه: دکمه «خروجی Excel» + `ExportToExcel()` + `EscapeCsv()` + UTF-8 BOM + `jsSaveAsFile`
- فایل‌های code-behind جدید: `ManualPayments.razor.cs`, `DiscountOrdersMainPage.razor.cs`
---
## فاز ۶ — تاریخ شمسی + تاریخچه‌ها + Export Excel (v6.0)
### تاریخ شمسی یکپارچه (3.6) — ✅ کامل
- **۱۹+ فایل** آپدیت شدند: تمام تاریخ‌ها از فرمت میلادی (`yyyy/MM/dd`) به شمسی تبدیل شدند
- از extension method‌های `DateTimeConverterCL` استفاده شد:
- `.MiladiToJalali()` — فرمت تاریخ فقط (مثال: ۱۴۰۴/۰۴/۱۲)
- `.MiladiToJalaliWithTime()` — فرمت تاریخ و ساعت
- **صفحات اصلاح‌شده شامل**: Club (Members, Statistics, Features, MemberDetailsDialog)، Commission (Dashboard, WeeklyReports, WithdrawalRequests, Payouts, WithdrawalReports)، Network (UserNetworkInfo, BalancesReport, Statistics, NetworkTreeViewer)، UserOrder, Products, Package, Inventory, DiscountShop, Blog, Content, و غیره
- `PropertyColumn Format="yyyy/MM/dd"` → `TemplateColumn` با `.MiladiToJalali()`
- `MudDatePicker DateFormat` تغییر نکرد (قابلیت تقویم شمسی نیاز به کتابخانه جداگانه دارد)
### تاریخچه عضویت باشگاه (5.7) — ✅
- **`MemberDetailsDialog.razor`**: تب تاریخچه با فیلدهای صحیح proto:
- ستون‌ها: `Action`, `Created`, `PackageName`, `Reason`, `PerformedBy`
- Request: `PageIndex = 0` (نه PageNumber)
### تاریخچه تغییرات شبکه (5.8) — ✅
- **`UserNetworkInfo.razor`**: تب تاریخچه با فیلدهای تخصصی:
- ستون‌ها: `Action`, `Created`, `OldParentId → NewParentId`, `OldNetworkLeg → NewNetworkLeg` (چپ/راست)
- ستون `Reason` و `PerformedBy` اضافه شد
- Request: `PageIndex = 0`
### لاگ اجرای Worker‌ها (5.6) — ✅
- در تب WorkerControl از SystemHub قبلاً پیاده‌سازی شده بود
### Export Excel / CSV (6.3) — ✅ ۶ صفحه
قابلیت خروجی CSV (سازگار با Excel) به ۶ صفحه اصلی اضافه شد:
| صفحه | فایل(ها) | ستون‌های خروجی |
|---|---|---|
| **Products** (قبلاً موجود) | ProductsMainPage.razor.cs | — |
| **Club Members** | ClubMembers.razor + .razor.cs | شناسه,کاربر,نام,پکیج,کد فعال‌سازی,تاریخ فعال‌سازی,تاریخ انقضا,فعال,منقضی |
| **Withdrawal Requests** | WithdrawalRequests.razor + .razor.cs | شناسه,کاربر,نام,مبلغ,وضعیت,روش,شبا,تاریخ درخواست,تاریخ پردازش,مرجع بانکی |
| **Weekly Reports** | WeeklyReports.razor + .razor.cs | هفته,مبلغ استخر,موجودی‌ها,ارزش,وضعیت,تاریخ محاسبه |
| **User Orders** | UserOrderMainPage.razor + .razor.cs | شناسه,کاربر,نام,مبلغ,وضعیت پرداخت,وضعیت ارسال,روش پرداخت,تاریخ |
| **Stock Movements** | MovementsPage.razor + .razor.cs | شناسه,محصول,نوع,تعداد,قبل,بعد,مرجع,یادداشت,تاریخ |
**الگوی پیاده‌سازی:**
- دکمه `<MudButton>` با آیکون `FileDownload` در ToolBarContent
- `StringBuilder` → CSV با هدرهای فارسی
- UTF-8 BOM (`Encoding.UTF8.GetPreamble()`) برای نمایش صحیح فارسی در Excel
- `jsSaveAsFile(filename, base64)` از `wwwroot/js/main.js`
- متد `EscapeCsv()` برای مقادیر حاوی کاما/کوتیشن
- تاریخ‌ها در خروجی نیز شمسی هستند
### فایل‌های جدید (این نسخه)
| فایل | عملکرد |
|---|---|
| `Pages/Commission/WeeklyReports.razor.cs` | Code-behind برای export (به‌دلیل محدودیت Razor parser با escaped quotes) |
---
## نسخه قبلی — Audit v5.0 (خرداد ۱۴۰۴)
### تم رنگی یکپارچه
- **`CustomMudTheme.cs`**: تم Primary از `#0380C0` به `#6366f1` (Indigo) تغییر کرد — هماهنگ با FrontOffice
- **`PaletteDark`** اضافه شد: Surface `#1a1a2e`, Background `#16213e`, AppbarBackground `#0f3460`
- **`app.css`**: رنگ loading از `#1b6ec2` به `var(--mud-palette-primary)` تغییر کرد
- **`NavMenu.razor.css`**: رنگ active از `#0380C0` هاردکد به CSS variable تغییر کرد
- **`MainLayout.razor`**: حذف inline style `border: 1px solid #5e4df9`
### Dark Mode Toggle
- آیکون ماه/آفتاب در AppBar اضافه شد
- `_isDarkMode` state با `MudThemeProvider` اتصال دارد
- تعویض بین `PaletteLight` و `PaletteDark` در CustomMudTheme
### عنوان اپلیکیشن
- "پنل مدیریت **فرصت**" → "پنل مدیریت **کارا بازار سلامت**"
---
## فاز ۲ — بازطراحی لایوت صفحات
### BasePageComponent بازنویسی کامل
- **قبل**: فیلتر ثابت سمت راست (20%) + جدول (80%)، ارتفاع 85vh هاردکد
- **بعد**: فیلتر collapsible بالای جدول، فیلدها در `MudGrid` با `MudItem`، responsive
- **۱۳ صفحه** آپدیت شدند: User, Products, Package, Category, UserOrder, UserAddress, UserRole, Role, BlogPost, BlogCategory, Tag, Transactions, Content
### DataGrid Height یکسان‌سازی
- همه DataGrid‌ها: `Height="calc(100vh - 240px)"`
- **صفحات اصلاح‌شده**: تمام ~33 صفحه دارای DataGrid
### Pager یکسان‌سازی
- **PageSize**: همه `20, 50, 100`
- **متن فارسی**: `RowsPerPageString="تعداد در صفحه"` و `InfoFormat="سطر {first_item} تا {last_item} از {all_items}"`
### MaxWidth یکسان‌سازی
- `MainLayout.razor` MudContainer wrapper اضافه شد → MaxWidth یکسان برای همه صفحات
- **۳۱ صفحه**: حذف `MudContainer` تکراری (double nesting)
### Breadcrumb
- **`Shared/AppBreadcrumb.razor`** ساخته شد
- جداکننده چپ‌به‌راست (`ChevronLeft`)
- نقشه فارسی URL segments (60+ مسیر)
- آخرین آیتم disabled (صفحه فعلی)
### Login + VerifyCode بازطراحی
- عرض ثابت 35% → responsive `MaxWidth.Small`
- لوگو + برندینگ "کارا بازار سلامت" اضافه شد
- طراحی gradient background
---
## فاز ۲.۵ — پاکسازی ساختاری
### NavMenu بازسازی کامل
- **لینک مرده `categories-dragdrop`**: حذف شد
- **Transactions**: حذف از NavMenu (صفحه stub خالی)
- **AlertsMonitoring**: حذف از NavMenu (100% mock)
- **WorkerControl**: به SystemHub منتقل شد (قبلاً لینک نداشت)
- **«پیام‌های عمومی»**: از بخش فروشگاه تخفیفی به «مدیریت محتوا» منتقل شد
- **ساختار گروه‌بندی** اصلاح شد:
- کمیسیون و شبکه: NavGroup واضح
- باشگاه مشتریان: اعضا و آمار + فیچرها
- فروشگاه: پکیج‌ها، محصولات (group)، سفارش‌ها، فروشگاه تخفیفی (group)
- مدیریت: کاربران، نقش‌ها، پرداخت دستی، **کیف‌پول (جدید)**، **قراردادها (جدید)**
- محتوا: بلاگ، صفحات سایت، پیام‌های عمومی
- سیستم: مدیریت سیستم، نسخه اپ‌ها
---
## فاز ۳ — UX بهبودها
### NoRecordsContent (Empty State)
- **۳۳ DataGrid** آپدیت شدند
- پیام: `<MudAlert Severity="Info">موردی یافت نشد.</MudAlert>`
### Delete Confirmation با نام آیتم
- **۱۱ صفحه** اصلاح شدند:
- Role → `«{model.Title}»`
- User → `«{model.FirstName} {model.LastName}»`
- Package → `«{model.Title}»`
- UserAddress → `«{model.Title}»`
- UserRole → `شناسه «{model.Id}»`
- UserOrder → `شماره «{model.Id}»`
- Category → `«{model.Title}»`
- Products → `«{model.Title}»`
- DiscountCategories → `«{category?.Title}»` (lookup اضافه شد)
- DiscountProducts → `«{product?.Title}»` (lookup اضافه شد)
- PublicMessages → `«{message?.Title}»` (lookup اضافه شد)
### User Menu در AppBar
- `MudMenu` جایگزین متن ساده شماره موبایل شد
- آیتم‌ها: نام کاربر (غیرفعال) + خروج
- آیکون `AccountCircle`
- خروج (`signout`) از NavMenu به AppBar منتقل شد
---
## فاز ۳.۵ — ادغام صفحات
### Dashboard Merge ← `Pages/Index.razor`
- **`Index.razor` + `SystemOverview.razor`** ادغام شدند
- Routes: `/` + `/dashboard/overview`
- بخش‌ها:
- 6 کارت آمار CMS (کاربران، محصولات، پکیج‌ها، دسته‌بندی‌ها، سفارش‌ها، مبلغ پرداخت‌شده)
- آمار کمیسیون (هفته جاری، استخر، موجودی‌ها، وضعیت محاسبه)
- آمار باشگاه (کل/فعال/غیرفعال)
- جدول آخرین ۵ سفارش پرداخت‌شده
- ۶ دکمه Quick Action
- بارگذاری موازی با `Task.WhenAll` + `.ResponseAsync`
- `SystemOverview.razor` **حذف شد**
### DiscountShopHub ← `Pages/DiscountShop/DiscountShopHub.razor`
- Routes: `/discount-shop`, `/discount-orders`, `/discount-sales-reports`
- ۲ تب: DiscountOrdersMainPage + SalesReports
- انتخاب تب از URL
### ClubHub ← `Pages/Club/ClubHub.razor`
- Routes: `/club`, `/club/members`, `/club/statistics`
- ۲ تب: ClubMembers + Statistics
### BlogHub ← `Pages/Blog/BlogHub.razor`
- Routes: `/blog`, `/blog/posts`, `/blog/categories`, `/tags`
- ۳ تب: BlogPostManagementPage + BlogCategoryManagementPage + TagManagementPage
### SystemHub ← `Pages/SystemManagement/SystemHub.razor`
- Routes: `/system`, `/system/configuration`, `/system/worker-control`, `/system/health`
- ۳ تب: Configuration + WorkerControl + HealthDashboard
### ۱۰ صفحه — `@page` directive حذف شد
صفحاتی که به hub منتقل شدند دیگر route مستقل ندارند:
DiscountOrdersMainPage, SalesReports, ClubMembers, Statistics, BlogPostManagementPage, BlogCategoryManagementPage, TagManagementPage, Configuration, WorkerControl, HealthDashboard
---
## فاز ۴ — فیکس‌های بیزینسی
### Dashboard آمار اصلاح شد
- **قبل**: آمار از ۱۰ رکورد اول محاسبه می‌شد (نادرست)
- **بعد**: از `metadata.TotalCount` و API‌های جداگانه استفاده می‌شود
### ManualPayments — تأیید/رد
- دکمه‌های Approve/Reject وقتی `Status==0` (در انتظار) نمایش داده می‌شوند
- Confirmation dialog قبل از اجرا
- از `ManualPaymentId` (نه `Id`) استفاده می‌شود
### UserOrder — فیلتر Cancelled
- `<MudSelectItem Value="@(5)">لغو شده</MudSelectItem>` اضافه شد
### WithdrawalRequests — بهبود کامل
- **Pager**: 10/25/50/100 → 20/50/100
- **`WithdrawalDetailsDialog.razor`** (جدید): نمایش کامل اطلاعات کاربر، درخواست، و بانکی
- **`RejectReasonDialog.razor`** (جدید): ورود دلیل رد با اعتبارسنجی
- ViewDetails: از Snackbar TODO به دیالوگ واقعی تغییر کرد
- RejectRequest: از دلیل هاردکد به دیالوگ custom تغییر کرد
---
## فاز ۵ — صفحات مفقود (CMS-Derived)
### WalletManagementPage ← `Pages/Wallet/WalletManagementPage.razor`
- Route: `/wallets`
- **تب ۱ — کیف‌پول‌ها**: DataGrid با ServerData، فیلتر UserAutoComplete
- ستون‌ها: شناسه، کاربر، موجودی اصلی، موجودی شبکه، مشاهده تغییرات
- نوع: `GetAllUserWalletByFilterResponseModel`
- **تب ۲ — تاریخچه تغییرات**: DataGrid با ServerData، فیلتر کاربر + نوع (افزایش/کاهش)
- ستون‌ها: شناسه، کیف‌پول، نوع (چیپ رنگی)، تغییر موجودی، موجودی فعلی، تغییر شبکه، موجودی شبکه فعلی، شناسه مرجع، تاریخ
- نوع: `GetAllUserWalletChangeLogByFilterResponseModel`
- فیلدهای proto با typo: `ChangeNerworkValue`, `RefrenceId`
### UserContractPage ← `Pages/Contract/UserContractPage.razor`
- Route: `/contracts`
- DataGrid با ServerData، فیلتر UserAutoComplete
- ستون‌ها: شناسه، کاربر، قرارداد، کد امضا، لینک PDF، جزئیات
- نوع: `GetAllUserContractByFilterResponseModel`
### ContractDetailsDialog ← `Pages/Contract/ContractDetailsDialog.razor`
- جدول ساده: شناسه، کاربر، قالب قرارداد، کد امضا، لینک دانلود PDF
### ClubFeaturesPage ← `Pages/Club/ClubFeaturesPage.razor`
- Route: `/club/features`
- **تب ۱ — فیچرهای تعریف‌شده**: کارت‌های MudPaper با عنوان، توضیحات، وضعیت (فعال/غیرفعال)، ترتیب
- از `ConfigClient.GetClubFeaturesAsync`
- **تب ۲ — فیچرهای کاربران**: DataGrid با فیلتر کاربر، سوئیچ فعال/غیرفعال
- از `ClubClient.GetUserClubFeaturesAsync` + `ToggleUserClubFeatureAsync`
---
## ⚠️ نکات فنی مهم
### الگوهای Proto
- **فیلتر**: `new GetAllXxxByFilterFilter()` (سطح بالا، بدون `.Types.`)
- **پاسخ لیست**: `GetAllXxxByFilterResponseModel` (نه `GetXxxResponse`)
- **Typo‌ها در proto**: `ChangeNerworkValue` و `RefrenceId` — باید دقیقاً همین‌ها استفاده شوند
### _Imports.razor — سرویس‌های Global
سرویس‌های زیر از `_Imports.razor` تزریق می‌شوند و نباید در code-behind با `[Inject]` دوباره تعریف شوند:
- `NavigationManager Navigation`
- `ILocalStorageService LocalStorageService`
- `ISnackbar Snackbar`
- `IJSRuntime jsRuntime`
- `IDialogService DialogService`
- `AuthenticationStateProvider`
### MudBlazor محدودیت‌ها
- `Variant.Flat` وجود ندارد → از `Variant.Text` استفاده شود
- `GutterSize` روی `MudGrid` deprecated است
---
## فاز ۴ (ادامه) — تکمیل فیکس‌های بیزینسی
### UserSettings — حذف تب‌های جعلی (2.5.5)
- **`UserSettings.razor`**: تب Notifications (۷ تاگل جعلی بدون بک‌اند) → placeholder «به‌زودی فعال می‌شود» با آیکون NotificationsActive
- **`UserSettings.razor`**: تب Security (فرم تغییر رمز + 2FA بدون بک‌اند) → placeholder «به‌زودی فعال می‌شود» با آیکون Lock
- **حذف کد مرده**: ~۱۵ متغیر notification/security + متدهای `SaveNotificationSettings()`, `SaveSecuritySettings()`, `ChangePassword()`
### HealthDashboard — حذف متریک‌های Mock (2.5.6)
- **`HealthDashboard.razor`**: بخش System Resources (۴ کارت CPU=45.2%, Memory=62.8%, Disk=73.5%, Network) → یک کارت با پیام «مانیتورینگ منابع سیستم در نسخه‌های آینده با اتصال به Prometheus/Grafana فعال خواهد شد»
- **حذف کد مرده**: ۹ متغیر mock (`_cpuUsage`, `_memoryUsage`, etc.) + متد `GetResourceColor()`
### حذف cursor:pointer زائد (4.10)
- `Style="cursor:pointer;"` از **۱۷ فایل** حذف شد (MudButton/MudIconButton خودشان cursor:pointer دارند)
- شامل: ProductsMainPage, GalleryDialog, Image.razor (base component), RoleMainPage, UserOrderMainPage, PackageMainPage, etc.
### حذف Console.WriteLine (4.11)
- از **۱۱ فایل** حذف شد: DiscountProductService, DiscountCategoryService, NetworkTreeViewer, UserSettings, CategoryMainPage, UserOrderMainPage, Commission/Dashboard, DiscountProductsMainPage, DiscountCategoryMultiSelectCombo, UserRole/CreateDialog
- **`Commission/Dashboard.razor.cs`**: `using System.Text.Json` هم حذف شد (دیگر استفاده نمی‌شد)
### DiscountProducts — فیلتر دسته‌بندی (4.7)
- **`DiscountProductsMainPage.razor`**: `@inject IDiscountCategoryService` اضافه شد
- دسته‌بندی‌های فعال از سرویس بارگذاری و در MudSelect نمایش داده می‌شوند
- جایگزینی `@* TODO: Load categories *@` با `@foreach` واقعی
### DiscountProducts — Items → ServerData (4.8)
- **`DiscountProductsMainPage.razor`**: تبدیل از `Items="@_products"` به `ServerData="LoadServerData"`
- متد `LoadServerData(GridState<T>)` اضافه شد با `PageNumber` و `PageSize` از state
- `Height="calc(100vh - 300px)"` + `FixedHeader="true"` اضافه شد
- Snackbar اطلاع‌رسانی اضافی در هر بارگذاری حذف شد (redundant)
### UserOrder — فعال‌سازی آمار (4.6)
- **`UserOrderMainPage.razor`**: بخش آمار (MudCard + MudChart) از حالت comment خارج شد
- نمایش تعداد سفارش‌ها + مجموع مبلغ + نمودار Bar وضعیت ارسال
### UserSettings — persist با localStorage (4.9)
- تب General از قبل با localStorage کار می‌کرد ✅ (فقط تب‌های جعلی حذف شدند)
---
## فاز ۴.۵ — Cross-Navigation
### لینک نام کاربر → پروفایل (4.5.1, 4.5.2)
- **`UserOrderMainPage.razor`**: ستون `UserFullName` از PropertyColumn به TemplateColumn تبدیل شد — MudLink به `/network/user-info/{UserId}`
- **`UserPayouts.razor`**: نام/شناسه کاربر به MudLink تبدیل شد → `/network/user-info/{UserId}`
- **`WithdrawalRequests.razor`**: نام کاربر به MudLink تبدیل شد → `/network/user-info/{UserId}`
### لینک محصول ↔ انبار (4.5.3, 4.5.4) — Skip
- صفحه جزئیات محصول وجود ندارد (فقط لیست + دیالوگ ویرایش)
- لینک cross-navigation بدون صفحه مقصد معنادار نیست
### Extract shared status helpers (3.5.6) — Skip
- بررسی نشان داد هر context مقادیر متفاوتی دارد:
- UserPayouts: status 1 = Success/پرداخت شده
- WithdrawalRequests: status 1 = Info/واریز شده
- PayoutDetailsDialog: فقط ۳ وضعیت (نه ۶)
- استخراج به helper مشترک باعث از دست رفتن معنای domain-specific می‌شود
---
## 📈 آمار تغییرات
| معیار | تعداد |
|---|---|
| فایل‌های جدید | 11 |
| فایل‌های حذف‌شده | 1 (SystemOverview.razor) |
| فایل‌های ویرایش‌شده | ~65+ |
| DataGrid‌های آپدیت‌شده | 33 |
| Delete confirmation اصلاح‌شده | 11 |
| صفحات ادغام‌شده | 14 → 5 |
| خطاهای build حل‌شده | 9+ |
| Console.WriteLine حذف‌شده | 22+ (از ۱۱ فایل) |
| cursor:pointer حذف‌شده | 17 فایل |
| Cross-link اضافه‌شده | 3 صفحه (UserOrder, UserPayouts, WithdrawalRequests) |
business/BUSINESS-01-CLUB-COMMISSION.md
+167
View File
@@ -0,0 +1,167 @@
# 🏆 سیستم باشگاه، کمیسیون و درخت شبکه‌ای
> **منابع ادغام‌شده:** `club-commission-system-complete.md`, `balance-calculation-rules.md`, `club-membership-contract-system.md`
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
---
## ۱. مفاهیم کلیدی
| مفهوم | توضیح |
|-------|--------|
| **عضویت باشگاه** | خرید پکیج طلایی (۵۶M) → فعالسازی (۲۵M) → عضو فعال باشگاه |
| **درخت باینری** | هر کاربر حداکثر ۲ فرزند مستقیم (چپ/راست) — حداکثر ۱۵ سطح |
| **کمیسیون هفتگی** | محاسبه بر اساس تعادل چپ/راست — هفته شمسی شنبه‌تا‌جمعه |
| **۳ کیف پول** | `Balance` (نقدی) + `NetworkBalance` (شبکه‌ای) + `DiscountBalance` (تخفیفی) |
---
## ۲. ساختار درخت باینری
```
Root
/ \
Left Right
/ \ / \
L1 L2 R1 R2
/ \ / \ / \ / \
... ... ... ... ... ← حداکثر ۱۵ سطح
```
**قوانین:**
- هر نود حداکثر ۲ فرزند (Binary)
- جایگذاری: `LegPosition` ∈ {Left, Right}
- عضو جدید → در اولین جای خالی از چپ‌ترین مسیر قرار می‌گیرد
- `SP_GetNetworkTree` — Stored Procedure بازگشتی
---
## ۳. فلوی عضویت و فعالسازی
```
خرید پکیج طلایی (56M تومان)
│
▼
نمایش مودال قرارداد (غیرقابل‌بسته‌شدن)
│
▼
مشاهده متن قرارداد ← ReadContract RPC
│
▼
درخواست OTP ← RequestContractOtp (Kavenegar SMS)
│
▼
وارد کردن کد ← VerifyContractOtp
│
▼
امضای قرارداد ← AcceptContract
│
├─→ شارژ ۳ کیف پول (Balance=56M, Network=56M, Discount=56M)
├─→ کسر هزینه فعالسازی (25M از Balance)
├─→ واریز 25.2M به Pool هفتگی
├─→ قرارگیری در درخت باینری
└─→ رفرش JWT Token (claims جدید)
```
---
## ۴. الگوریتم محاسبه کمیسیون هفتگی
### ۴.۱ فرمول ۴ مرحله‌ای
```
مرحله ۱: جمع فروش هر پا
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 هفتگی و توزیع
```
منبع Pool: هر فعالسازی عضو → 25.2M واریز به Pool
توزیع: بر اساس WeeklyBalance هر عضو / مجموع WeeklyBalance‌ها
SP: sp_CalculateWeeklyBalances → sp_CalculateWeeklyCommissionPool
فرمت هفته: "YYYY-Www" (شمسی، شنبه‌پایه)
```
---
## ۵. تنظیمات سیستمی (SystemConstants)
| ثابت | مقدار | توضیح |
|------|-------|--------|
| `Club.ActivationFee` | 25,000,000 | هزینه فعالسازی (تومان) |
| `Club.GiftValue` | 25,200,000 | واریز به Pool |
| `GoldenPackageAmount` | 56,000,000 | قیمت پکیج طلایی |
| `DayaLoanAmount` | 56,000,000 | مبلغ وام دایا |
| `MaxWeeklyBalancesPerLeg` | 300 | سقف هفتگی هر پا |
| `MaxNetworkLevel` | 15 | حداکثر عمق درخت |
| `ClubJoiningPercentage` | 0.35 | درصد پیوستن |
| `ClubActivationThreshold` | 0.5 | آستانه فعالسازی |
| `MaxCalculationAttempts` | 3 | حداکثر تلاش محاسبه |
---
## ۶. ۳ سناریوی خرید پکیج طلایی
| سناریو | فلو | وضعیت |
|--------|------|--------|
| **وام دایا** | درخواست وام → تأیید خودکار → شارژ ۳ کیف‌پول (۱۶۸M) | ✅ پیاده‌شده |
| **درگاه مستقیم** | IPG (ZarinPal) → callback → شارژ | ✅ پیاده‌شده |
| **پرداخت دستی** | کارت‌به‌کارت → آپلود رسید → تأیید ادمین → شارژ | ⚠️ طراحی‌شده |
---
## ۷. یکپارچه‌سازی وام دایا
```
Hangfire Worker (هر ۱۵ دقیقه)
│
▼
بررسی درخواست‌های pending
│
▼
ارسال به API دایا (Mock/Real switchable)
│
▼
دریافت نتیجه → شارژ ۳ کیف‌پول
│
├─→ Balance = 56M
├─→ NetworkBalance = 56M
└─→ DiscountBalance = 56M (مجموع: 168M)
Polly Retry: 3 attempts, Exponential backoff
```
---
## ۸. Chatika AI — اولین فیچر باشگاه
| آیتم | جزئیات |
|------|---------|
| **نوع** | Hangfire recurring job |
| **فرکانس** | هر ۵ دقیقه |
| **Retry** | Polly — ۳ تلاش، backoff نمایی |
| **فعال‌سازی** | فقط برای اعضای فعال باشگاه |
| **وضعیت** | ✅ Production ready |
business/BUSINESS-02-PAYMENT-FINANCE.md
+223
View File
@@ -0,0 +1,223 @@
# 💰 سیستم مالی، پرداخت و درگاه‌ها
> **منابع ادغام‌شده:** `payment-gateway.md`, `payment-architecture-pyms.md`, `daya-loan-integration.md`, `manual-payment-system.md`, `discount-shop-business.md`
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
---
## ۱. معماری کلی مالی
```
┌──────────────────────────────────────────────────────────────────┐
│ FourSat Payment Architecture │
├──────────────┬──────────────┬──────────────┬─────────────────────┤
│ ZarinPal │ Daya Loan │ Manual Pay │ Discount Wallet │
│ (IPG) │ (API) │ (Card2Card) │ (Internal) │
├──────────────┴──────────────┴──────────────┴─────────────────────┤
│ PYMS (Payment Service) │
│ gRPC ←→ CMS ←→ FrontOffice/BackOffice │
├──────────────────────────────────────────────────────────────────┤
│ 3 Wallet System │
│ Balance (نقدی) │ NetworkBalance (شبکه) │ DiscountBalance │
└──────────────────────────────────────────────────────────────────┘
```
---
## ۲. درگاه ZarinPal (IPG)
### ۲.۱ فلوی پرداخت
```
کاربر → انتخاب محصول → درخواست پرداخت
│
▼
CMS → CreatePaymentRequest (gRPC to PYMS)
│
▼
PYMS → ZarinPal API → دریافت Authority
│
▼
Redirect کاربر → صفحه پرداخت ZarinPal
│
▼
بازگشت با Authority → CMS VerifyPayment
│
├─→ موفق: ثبت سفارش + شارژ کیف‌پول (در صورت نیاز)
└─→ ناموفق: نمایش پیام خطا
```
### ۲.۲ تنظیمات ZarinPal
| پارامتر | مقدار |
|----------|-------|
| `MerchantId` | از appsettings |
| `CallbackUrl` | `/payment/callback` |
| `Sandbox` | true (staging) / false (production) |
| `Currency` | IRR (ریال → تبدیل به تومان در UI) |
---
## ۳. سیستم وام دایا (DayaLoan)
### ۳.۱ معماری
```
Hangfire Recurring Job (هر ۱۵ دقیقه)
│
▼
DayaLoanProcessorJob.Execute()
│
▼
بررسی LoanRequests با Status=Pending
│
▼
برای هر درخواست:
├─→ ارسال به DayaLoan API (با Polly retry ×3)
├─→ در صورت تأیید: شارژ ۳ کیف‌پول (هرکدام ۵۶M)
├─→ ثبت Transaction + Log
└─→ در صورت رد: بروزرسانی Status=Rejected + ارسال SMS
```
### ۳.۲ Mock Mode
```csharp
// appsettings.json
"DayaLoan": {
"UseMock": true, // staging
"BaseUrl": "https://api.dayaloan.ir",
"ApiKey": "***",
"AutoApproveInMock": true
}
```
### ۳.۳ مقادیر
| آیتم | مقدار |
|------|-------|
| مبلغ وام | ۵۶,۰۰۰,۰۰۰ تومان |
| شارژ هر کیف‌پول | ۵۶,۰۰۰,۰۰۰ تومان |
| مجموع شارژ | ۱۶۸,۰۰۰,۰۰۰ تومان |
| بازپرداخت | طبق شرایط دایا |
---
## ۴. پرداخت دستی (کارت‌به‌کارت)
> ⚠️ **وضعیت: طراحی‌شده — پیاده‌سازی نشده**
```
فلوی پیشنهادی:
کاربر → انتخاب "کارت‌به‌کارت"
│
▼
نمایش شماره‌کارت مقصد + مبلغ
│
▼
کاربر → واریز + آپلود تصویر رسید
│
▼
ادمین BackOffice → مشاهده لیست درخواست‌ها
│
▼
تأیید/رد → شارژ خودکار کیف‌پول
```
**موجودیت‌های مورد نیاز:**
- `ManualPaymentRequest` (UserId, Amount, ReceiptImage, Status, AdminNote)
- `ManualPaymentStatus` enum: Pending, Approved, Rejected
---
## ۵. پرداخت ترکیبی فروشگاه تخفیفی (Hybrid Payment)
### ۵.۱ فرمول
```
قیمت محصول = 1,000,000 تومان
تخفیف باشگاه = 30%
پرداخت از DiscountBalance = 1,000,000 × 0.30 = 300,000
پرداخت نقدی (IPG) = 1,000,000 × 0.70 = 700,000
─────────
مجموع = 1,000,000
```
### ۵.۲ فلوی خرید فروشگاه تخفیفی
```
کاربر (عضو باشگاه) → مشاهده محصول
│
▼
قیمت تخفیف‌خورده نمایش داده می‌شود
│
▼
افزودن به سبد → بررسی DiscountBalance
│
├─→ DiscountBalance کافی:
│ سهم تخفیف از DiscountBalance کسر
│ باقیمانده → IPG (ZarinPal)
│
└─→ DiscountBalance ناکافی:
فقط به اندازه موجودی از تخفیف
باقیمانده بیشتر → IPG
```
### ۵.۳ دسترسی فروشگاه تخفیفی
| شرط | نتیجه |
|------|--------|
| `IsClubMember = true` | دسترسی به Discount Store |
| `IsClubMember = false` | فقط Regular Store |
| `DiscountBalance > 0` | می‌تواند از تخفیف استفاده کند |
| `DiscountBalance = 0` | پرداخت ۱۰۰% نقدی |
---
## ۶. 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 | شارژ از وام دایا |
---
## ۷. مالیات و VAT
```
VAT = 10% (configurable via SystemConstants)
قیمت نمایشی = قیمت پایه × (1 + VAT)
در صورتحساب: قیمت پایه + مالیات جداگانه نمایش داده می‌شود
```
---
## ۸. خلاصه وضعیت پیاده‌سازی
| ماژول | وضعیت | یادداشت |
|-------|--------|---------|
| ZarinPal IPG | ✅ کامل | Production ready |
| وام دایا | ✅ کامل | Mock mode فعال در staging |
| پرداخت ترکیبی | ✅ کامل | Discount + IPG |
| Pool هفتگی | ✅ کامل | SP + Hangfire |
| پرداخت دستی | ⬜ طراحی | نیاز به تصمیم مدیریت |
| Refund | ⬜ طراحی | فقط در PYMS تعریف‌شده |
business/BUSINESS-03-ECOMMERCE-STORES.md
+234
View File
@@ -0,0 +1,234 @@
# 🛒 فروشگاه، موجودی و محصولات
> **منابع ادغام‌شده:** `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`
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
---
## ۱. دو فروشگاه FourSat
```
┌─────────────────────────────────────────────────────────┐
│ FourSat Stores │
├───────────────────────┬─────────────────────────────────┤
│ Regular Store │ Discount Store │
│ (/store) │ (/discount-store) │
├───────────────────────┼─────────────────────────────────┤
│ • همه کاربران │ • فقط اعضای باشگاه │
│ • پرداخت 100% نقدی │ • پرداخت ترکیبی (تخفیف+نقد) │
│ • قیمت عادی │ • تخفیف ۳۰% از DiscountBalance │
│ • بدون محدودیت │ • وابسته به موجودی تخفیفی │
├───────────────────────┴─────────────────────────────────┤
│ Shared: Products, Categories, │
│ Inventory, ProductImages (1:1 square) │
└─────────────────────────────────────────────────────────┘
```
---
## ۲. 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 (هر دو فروشگاه)
```
بارگذاری اولیه: 12 محصول
│
▼
اسکرول → نمایش دکمه "نمایش محصولات بیشتر"
│
▼
کلیک → LoadMore() → skip += 12
│
▼
محصولات جدید اضافه به لیست (append)
│
▼
تکرار تا Products.Count >= TotalCount
│
▼
مخفی‌شدن دکمه
```
---
## ۳. مدیریت موجودی (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; } // آیا موجودی رصد شود؟
}
```
### ۳.۳ فلوی سفارش و موجودی
```
سفارش جدید
│
▼
بررسی Quantity - ReservedQuantity >= OrderQuantity?
│
├─→ بله: ReservedQuantity += OrderQuantity
│ پرداخت موفق → Quantity -= OrderQuantity, Reserved -= OrderQuantity
│ پرداخت ناموفق → Reserved -= OrderQuantity (آزادسازی)
│
└─→ خیر: نمایش "موجودی کافی نیست"
```
---
## ۴. تصاویر محصول (۱:۱ مربعی)
```
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; }
}
```
### ۵.۲ فلو
```
ادمین → ساخت باندل → انتخاب محصولات + تعیین قیمت
│
▼
نمایش در فروشگاه با تگ "باندل"
│
▼
خرید → تمام محصولات باندل یکجا به سبد
│
▼
پرداخت → کسر موجودی هر محصول جداگانه
```
---
## ۶. یکپارچه‌سازی فروشگاه‌ها (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)
```
درختی / سلسله‌مراتبی
│
├── سلامت و زیبایی
│ ├── مکمل‌ها
│ ├── مراقبت پوست
│ └── مراقبت مو
├── تغذیه
│ ├── ارگانیک
│ └── رژیمی
└── ورزشی
مدل: Category (Id, Name, ParentId?, ImageUrl, IsActive, SortOrder)
```
---
## ۸. خلاصه وضعیت
| ماژول | وضعیت | درصد |
|-------|--------|------|
| فروشگاه عادی | ✅ کامل | 100% |
| فروشگاه تخفیفی | ✅ کامل | 100% |
| Lazy Loading | ✅ کامل | 100% |
| موجودی خودکار | ✅ کامل | 100% |
| تصاویر مربعی | ✅ کامل | 100% |
| باندل محصولات | ⬜ طراحی | 30% |
| مقایسه محصول | ⬜ ایده | 0% |
business/BUSINESS-04-USER-MEMBERSHIP.md
+236
View File
@@ -0,0 +1,236 @@
# 👤 سفر کاربر، ثبت‌نام و چرخه عضویت
> **منابع ادغام‌شده:** `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`
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
---
## ۱. فلوی کامل چرخه کاربر
```
ورود به سایت
│
▼
ثبت‌نام (موبایل + OTP)
│
▼
تکمیل پروفایل
│
▼
┌─────────────────────┬────────────────────────┐
│ مسیر عادی │ مسیر باشگاه │
├─────────────────────┼────────────────────────┤
│ خرید از فروشگاه │ خرید پکیج طلایی (56M) │
│ مشاهده بلاگ │ امضای قرارداد (OTP) │
│ استفاده از خدمات │ فعالسازی (25M) │
│ │ عضویت در درخت باینری │
│ │ دسترسی فروشگاه تخفیفی │
│ │ دسترسی فیچرهای باشگاه │
│ │ کسب کمیسیون هفتگی │
└─────────────────────┴────────────────────────┘
```
---
## ۲. ثبت‌نام و احراز هویت
### ۲.۱ فلوی ثبت‌نام
```
صفحه ثبت‌نام
│
▼
ورود شماره موبایل
│
▼
ارسال OTP (Kavenegar SMS API)
│
▼
تأیید کد OTP
│
├─→ کاربر جدید: ساخت User + JWT Token
└─→ کاربر موجود: ورود + JWT Token
JWT Claims:
• UserId
• PhoneNumber
• IsClubMember (bool)
• Roles[] (Admin, Customer)
• ReferralCode
```
### ۲.۲ اصلاحات ثبت‌نام
| مشکل | راه‌حل | وضعیت |
|------|---------|--------|
| OTP تکراری | Rate limiting: ۱ درخواست هر ۶۰ ثانیه | ✅ |
| شماره نامعتبر | Regex validation ایران `^09\d{9}$` | ✅ |
| حمله brute-force | قفل حساب بعد از ۵ تلاش ناموفق | ✅ |
| Race condition ثبت‌نام | Unique constraint + transaction | ✅ |
---
## ۳. جداسازی Admin/Customer
### ۳.۱ مشکل قبلی
```
قبل:
Admin و Customer هر دو از یک DbContext و Identity استفاده می‌کردند
یک ادمین می‌توانست به صورت Customer هم ظاهر شود ← تداخل Claims
بعد (اصلاح‌شده):
✅ ICurrentUserService → تشخیص دقیق نقش فعلی
✅ جداسازی Authorization Policy
✅ Admin claims فقط در BackOffice
✅ Customer claims فقط در FrontOffice
```
### ۳.۲ 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>()
```
---
## ۴. قرارداد عضویت باشگاه
### ۴.۱ فلوی امضای قرارداد
```
خرید پکیج طلایی → Redirect به صفحه قرارداد
│
▼
نمایش Modal غیرقابل‌بسته‌شدن
│
▼
ReadContract RPC → نمایش متن قرارداد (Markdown/HTML)
│
▼
کاربر باید تا انتهای متن اسکرول کند
│
▼
فعال شدن دکمه "ارسال کد تأیید"
│
▼
RequestContractOtp → ارسال SMS
│
▼
ورود کد ← VerifyContractOtp
│
├─→ معتبر: AcceptContract → فعالسازی عضویت
└─→ نامعتبر: پیام خطا (حداکثر ۵ تلاش)
```
### ۴.۲ ذخیره‌سازی قرارداد
```csharp
public class UserContract {
public Guid Id { get; set; }
public Guid UserId { get; set; }
public string ContractVersion { get; set; } // e.g., "v1.2"
public string ContractText { get; set; } // snapshot متن
public DateTime AcceptedAt { get; set; }
public string OtpVerificationId { get; set; }
public string IpAddress { get; set; }
public string UserAgent { get; set; }
}
```
---
## ۵. فیچرهای باشگاه (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)
```
هر عضو باشگاه → یک ReferralCode یکتا
لینک: https://foursat.ir/register?ref={ReferralCode}
ثبت‌نام با لینک:
│
▼
ذخیره ReferrerId در پروفایل کاربر جدید
│
▼
هنگام خرید پکیج → زیرمجموعه Referrer در درخت باینری
│
▼
Referrer → دریافت 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
+272
View File
@@ -0,0 +1,272 @@
# 📄 محتوا، صفحات، بلاگ و ایمیل/SMS
> **منابع ادغام‌شده:** `SITE-PAGES-SIMPLIFICATION.md`, `system-constants.md`, `email-sms-configuration.md`, `chatika-integration.md`, `CMS-README.md`
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
---
## ۱. مدیریت صفحات سایت (Site Pages)
### ۱.۱ معماری ساده‌شده (Shopify-style)
```
قبل (پیچیده):
SitePage → SitePageSetting → SitePageContent → Template → ... (7 جدول)
بعد (ساده):
SitePage (PageType, JsonSettings, IsPublished)
│
└─→ هر PageType → یک typed editor در BackOffice
```
### ۱.۲ انواع صفحات
| 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)
### ۳.۱ معماری
```
آپلود فایل (تصویر/سند)
│
▼
FileManagementService → ذخیره در فایل‌سیستم + ثبت در DB
│
▼
مسیر فیزیکی: /app/uploads/{year}/{month}/{guid}.{ext}
مسیر URL: /api/files/{guid}
محدودیت‌ها:
• حداکثر حجم: 10MB (configurable)
• فرمت‌های مجاز: 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": "10008663",
"Templates": {
"OTP": "verify-foursat",
"ContractOTP": "contract-verify",
"WelcomeClub": "club-welcome",
"OrderConfirm": "order-confirm"
}
}
}
```
### ۴.۲ ایمیل
```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 | `Club.ActivationFee` | 25000000 | هزینه فعالسازی |
| Club | `Club.GiftValue` | 25200000 | واریز Pool |
| Club | `GoldenPackageAmount` | 56000000 | قیمت پکیج طلایی |
| Club | `MaxNetworkLevel` | 15 | حداکثر عمق درخت |
| Club | `MaxWeeklyBalance` | 300 | سقف هفتگی |
| Payment | `VAT.Percentage` | 10 | مالیات ارزش افزوده |
| Payment | `DayaLoanAmount` | 56000000 | مبلغ وام |
| Store | `DiscountPercentage` | 30 | تخفیف باشگاه |
| Store | `ProductsPerPage` | 12 | تعداد در صفحه |
| System | `SmsProvider` | Kavenegar | ارائه‌دهنده SMS |
| System | `MaintenanceMode` | false | حالت تعمیر |
---
## ۶. Chatika AI Integration
### ۶.۱ معماری
```
Hangfire Recurring Job (هر ۵ دقیقه)
│
▼
ChatikaJob → بررسی پیام‌های جدید کاربران
│
▼
ارسال به Chatika API (با Polly retry ×3)
│
▼
دریافت پاسخ → ذخیره در ChatMessages
│
▼
نمایش در UI باشگاه (real-time via SignalR planned)
```
### ۶.۲ فعلی vs آینده
| آیتم | فعلی | آینده |
|------|-------|-------|
| ارتباط | Polling (Hangfire) | SignalR real-time |
| دسترسی | فقط اعضای باشگاه | تعمیم به همه؟ |
| نوع پیام | متنی | متنی + تصویری |
---
## ۷. Landing Page
### ۷.۱ ساختار
```
Hero Section (انیمیشن fade-in)
│
▼
ویژگی‌ها (Features Grid — 3 ستونه)
│
▼
محصولات ویژه (Carousel)
│
▼
آمار (Counter animation — اصلاح‌شده)
│
▼
CTA — Call to Action (ثبت‌نام / ورود)
```
### ۷.۲ اصلاح انیمیشن 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
-202
View File
@@ -1,202 +0,0 @@
# فروشگاه تخفیفی — وضعیت پیاده‌سازی و تسک‌ها
> **تاریخ:** ۱۴۰۴/۱۱/۲۲ (2026-02-11)
> **آخرین بروزرسانی:** ۱۴۰۴/۱۱/۲۸ (2026-02-17)
> **وضعیت کلی:** بکند کامل ✅ | بک‌آفیس کامل ✅ | فرانت‌آفیس کامل ✅ | Production Deploy ✅
---
## ۱. خلاصه بیزینس
فروشگاه تخفیفی یک فروشگاه **مجزا** از فروشگاه معمولی است که:
- محصولات خاص خود را دارد (`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
│ جمع کل / جمع تخفیف / مبلغ درگاه
├─ مالیات ۹٪ روی مبلغ درگاه
├─ مبلغ قابل پرداخت = مبلغ درگاه + مالیات
├─ ⚠️ تخفیف اجباری: همیشه حداکثر (MaxDiscountPercent) اعمال می‌شود
└─ [پرداخت]
↓
PlaceOrder RPC:
├─ بررسی موجودی + محاسبه (MaxDiscountPercent اجباری)
├─ ساخت سفارش (PaymentStatus=Pending)
├─ رزرو موجودی انبار
├─ اگر gateway_amount > 0 → ZarinPal payment_url
└─ اگر gateway_amount = 0 → سفارش مستقیم تکمیل
↓
ریدایرکت به ZarinPal
↓
Callback → CompleteOrderPayment RPC:
├─ success → کسر DiscountBalance + تأیید + PaymentTransaction + DeliveryStatus=Pending
└─ failure → آزادسازی رزرو انبار + PaymentStatus=Reject + DeliveryStatus=Cancelled
↓
ExpirePendingOrdersService (Background):
├─ هر ۵ دقیقه چک می‌کند
├─ سفارشات Pending بالای ۳۰ دقیقه → Reject + Cancelled
└─ آزادسازی رزرو انبار
```
---
## ۵. تخمین زمان
| تسک | تخمین |
|-----|-------|
| Routes + DI + Services | ۱ ساعت |
| Products + ProductDetail | ۲ ساعت |
| Cart | ۱ ساعت |
| Checkout (پیچیده‌ترین بخش) | ۲ ساعت |
| Orders + OrderDetail | ۱ ساعت |
| Dashboard tile + Nav | ۰.۵ ساعت |
| CSS + Polish | ۰.۵ ساعت |
| **مجموع** | **~۸ ساعت** |
business/balance-calculation-rules.md
-1484
View File
File diff suppressed because it is too large Load Diff
business/club-commission-system-complete.md
-2275
View File
File diff suppressed because it is too large Load Diff
business/club-membership-contract-system.md
-1422
View File
File diff suppressed because it is too large Load Diff
business/daya-loan-integration.md
-1039
View File
File diff suppressed because it is too large Load Diff
business/discount-shop-business.md
-750
View File
@@ -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
-548
View File
@@ -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
-967
View File
@@ -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
-153
View File
@@ -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
-131
View File
@@ -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/CMS-README.md
-445
View File
@@ -1,445 +0,0 @@
# CMS Microservice - Network & Club Commission + Inventory Management System
[![Status](https://img.shields.io/badge/Status-Active%20Development-success)]()
[![Progress](https://img.shields.io/badge/Inventory%20System-Phase%202%20Complete-blue)]()
[![Phase](https://img.shields.io/badge/Next-Business%20Services-orange)]()
## 📊 Project Status (January 2026)
### 🏪 Inventory Management System - NEW!
**Progress**: Phase 2 Complete (50%)
**Architecture**: Clean Architecture + CQRS + Repository Pattern
#### ✅ Completed Phases
1. ✅ **Phase 1: Infrastructure & Domain Layer**
- Domain Entities: `InventoryItem`, `StockMovement`, `Warehouse`
- Domain Enums: `StockMovementType`
- EF Core Configurations with proper indexing
- Database migration applied
2. ✅ **Phase 2: Repository Pattern & CQRS**
- Repository Interfaces & Implementations
- CQRS Commands (17 commands)
- CQRS Queries (35 queries)
- MediatR Handlers (52 handlers)
#### 🔄 In Progress
3. 🔄 **Phase 3: Business Services Layer**
4. ⏳ **Phase 4: DTOs & AutoMapper**
5. ⏳ **Phase 5: API Controllers**
---
### 💼 Commission System - Production Ready
**Progress**: 85% Complete
**MVP Status**: ✅ 100% Complete
#### ✅ Completed Features
- ✅ Binary network tree with automatic placement
- ✅ Club membership (Member/Trial) with commission rates
- ✅ Weekly commission calculation (Lesser Leg algorithm)
- ✅ Background worker with Hangfire
- ✅ Email + SMS notifications (MailKit + Kavenegar)
- ✅ Health check endpoints (Kubernetes-ready)
### 🟡 Partially Complete
- Phase 10: Withdrawal & Settlement (40%)
- ✅ Commands & Database
- ❌ Payment Gateway Integration
### ❌ Not Started
- Phase 9: Club Shop & Product Integration (0%)
---
## 🚀 Recent Updates (January 2026)
### 🏪 Inventory Management System - NEW! ✅
**Complete CQRS-based inventory management with:**
#### Domain Layer:
- ✅ `InventoryItem` - Multi-warehouse product tracking with min/max thresholds
- ✅ `StockMovement` - Complete audit trail with 8 movement types
- ✅ `Warehouse` - Multi-location support with default warehouse
#### Repository Pattern:
- ✅ `IInventoryItemRepository` - 25+ methods for inventory operations
- ✅ `IStockMovementRepository` - Movement tracking & analytics
- ✅ `IWarehouseRepository` - Warehouse management & statistics
#### CQRS Commands (17 total):
- **Inventory:** Create, Update, Delete, Reserve, Release, Reduce, Increase
- **Movement:** Create, BulkCreate, Delete
- **Warehouse:** Create, Update, Delete, SetDefault, Activate, BulkCreate
#### CQRS Queries (35 total):
- **Inventory:** GetById, Search, LowStock, OutOfStock, CheckAvailability
- **Movement:** GetHistory, GetByOrder, Search, Analytics, DailyVolume, TopMoving
- **Warehouse:** GetById, Search, GetStats, GetLowStock, GetAllStats
#### Business Features:
- ✅ Multi-warehouse inventory management
- ✅ Stock reservation system for orders
- ✅ Automatic movement tracking
- ✅ Low stock & out-of-stock alerts
- ✅ Advanced analytics & reporting
- ✅ Bulk operations support
- ✅ Transaction-safe operations
---
### Email & SMS Notifications - COMPLETED ✅
- ✅ **MailKit 4.14.1** for Email (SMTP with HTML templates)
- ✅ **Kavenegar 1.2.5** for SMS (Iranian SMS gateway)
- ✅ User.Email field added with migration
- ✅ 3 notification types: Commission, Club activation, Errors
- ✅ Persian RTL templates with rich formatting
- ✅ Production configuration guide created
### Hangfire Job Scheduling - COMPLETED ✅
- ✅ Dashboard UI at `/hangfire`
- ✅ Cron schedule: Sunday 00:05 UTC
- ✅ SQL Server persistence
- ✅ Manual trigger API endpoints
- ✅ Distributed execution support
### Infrastructure Enhancements - COMPLETED ✅
- ✅ Health Check endpoints (`/health`, `/health/ready`, `/health/live`)
- ✅ AlertService (structured logging for Sentry/Slack)
- ✅ Retry logic (Polly 8.5.0 with exponential backoff)
- ✅ WorkerExecutionLog (database audit trail)
- ✅ CurrentUserService (JWT authentication context)
---
## 🏗️ Architecture
**Clean Architecture** with 4 layers:
```
CMSMicroservice.Domain/ # Entities, Enums, Interfaces
├── Entities/
│ ├── InventoryItem.cs # NEW: Inventory tracking
│ ├── StockMovement.cs # NEW: Movement audit
│ └── Warehouse.cs # NEW: Multi-warehouse
├── Enums/
│ └── StockMovementType.cs # NEW: Movement types
CMSMicroservice.Application/ # CQRS (Commands, Queries, MediatR)
├── Features/
│ ├── InventoryItems/ # NEW: Inventory CQRS
│ │ ├── Commands/
│ │ ├── Queries/
│ │ └── Handlers/
│ ├── StockMovements/ # NEW: Movement CQRS
│ │ ├── Commands/
│ │ ├── Queries/
│ │ └── Handlers/
│ └── Warehouses/ # NEW: Warehouse CQRS
│ ├── Commands/
│ ├── Queries/
│ └── Handlers/
└── Common/Interfaces/
└── Repositories/ # NEW: Repository interfaces
CMSMicroservice.Infrastructure/ # DbContext, Services, Background Jobs
├── Persistence/
│ ├── Context/
│ ├── Configurations/ # NEW: EF Core configs
│ ├── Repositories/ # NEW: Repository implementations
│ └── Migrations/
└── DependencyInjection.cs # NEW: DI setup
CMSMicroservice.WebApi/ # gRPC Services, Controllers
CMSMicroservice.Protobuf/ # Protocol Buffers definitions
```
**Technology Stack**:
- .NET 9.0
- Entity Framework Core 9.0.11
- gRPC + JSON Transcoding
- Hangfire 1.8.22 (Job Scheduling)
- MediatR 13.0.0 (CQRS)
- Polly 8.5.0 (Resilience)
- MailKit 4.14.1 (Email)
- Kavenegar 1.2.5 (SMS)
- SQL Server
---
## 📖 Documentation
- **[Development Plan](docs/development-plan.md)** - NEW: Inventory system roadmap
- **[Implementation Progress](docs/implementation-progress.md)** - Detailed phase-by-phase progress
- **[Email/SMS Configuration Guide](docs/email-sms-configuration-guide.md)** - Production setup instructions
- **[Balance Calculation Logic](docs/balance-calculation-carryover-logic.md)** - Commission algorithm details
- **[Binary Tree Registration](docs/binary-tree-registration-guide.md)** - Network tree guide
- **[Network Club Commission System](docs/network-club-commission-system-v1.1.md)** - Full system specification
---
## 🏪 Inventory System Usage
### Create Warehouse
```csharp
await mediator.Send(new CreateWarehouseCommand
{
Name = "Main Warehouse",
Code = "WH-001",
IsDefault = true,
IsActive = true
});
```
### Create Inventory Item
```csharp
await mediator.Send(new CreateInventoryItemCommand
{
ProductId = 1,
WarehouseId = 1,
Quantity = 100,
MinQuantity = 10,
MaxQuantity = 1000
});
```
### Reserve Stock for Order
```csharp
await mediator.Send(new ReserveInventoryCommand
{
Id = inventoryId,
Quantity = 5,
OrderId = 12345
});
```
### Check Availability
```csharp
bool available = await mediator.Send(
new CheckInventoryAvailabilityQuery(inventoryId, 10));
```
### Get Low Stock Alerts
```csharp
var lowStock = await mediator.Send(new GetLowStockItemsQuery
{
WarehouseId = 1,
Count = 50
});
```
### Get Movement Analytics
```csharp
var summary = await mediator.Send(new GetMovementSummaryQuery
{
FromDate = DateTime.Now.AddDays(-7),
ToDate = DateTime.Now
});
var topProducts = await mediator.Send(new GetTopMovingProductsQuery
{
FromDate = DateTime.Now.AddDays(-30),
ToDate = DateTime.Now,
Count = 10
});
```
---
## 🚀 Quick Start
### Prerequisites
- .NET 9.0 SDK
- SQL Server (local or remote)
- (Optional) Gmail account for Email
- (Optional) Kavenegar account for SMS
### 1. Clone & Build
```bash
cd /home/masoud/Apps/project/FourSat/CMS/src
dotnet build
```
### 2. Configure Database
Update `appsettings.json` with your SQL Server connection:
```json
"ConnectionStrings": {
"DefaultConnection": "Server=YOUR_SERVER;Database=Foursat_CMS;..."
}
```
### 3. Apply Migrations
```bash
cd CMSMicroservice.WebApi
dotnet ef database update
```
### 4. Configure Notifications (Optional)
See [Email/SMS Configuration Guide](docs/email-sms-configuration-guide.md)
### 5. Run
```bash
dotnet run --urls="http://localhost:5133"
```
### 6. Access Endpoints
- **Health**: http://localhost:5133/health
- **Hangfire Dashboard**: http://localhost:5133/hangfire
- **gRPC**: localhost:5133 (HTTP/2)
---
## 🔧 Configuration
### Email (SMTP)
```json
"Email": {
"Enabled": true,
"SmtpHost": "smtp.gmail.com",
"SmtpPort": 587,
"SmtpUsername": "your-email@gmail.com",
"SmtpPassword": "your-gmail-app-password",
"FromEmail": "noreply@foursat.com",
"FromName": "FourSat CMS",
"EnableSsl": true
}
```
### SMS (Kavenegar)
```json
"Sms": {
"Enabled": true,
"Provider": "Kavenegar",
"KavenegarApiKey": "YOUR_API_KEY",
"Sender": "10008663"
}
```
### Background Worker
```csharp
// Cron: "5 0 * * 0" = Every Sunday at 00:05 UTC
RecurringJob.AddOrUpdate<WeeklyCommissionJob>(
"weekly-commission-calculation",
job => job.ExecuteAsync(CancellationToken.None),
"5 0 * * 0");
```
---
## 🧪 Testing
### Manual Trigger (via API)
```bash
# Trigger weekly calculation immediately
curl -X POST http://localhost:5133/api/admin/trigger-weekly-calculation
# Trigger recurring job now
curl -X POST http://localhost:5133/api/admin/trigger-recurring-job-now
# Get recurring jobs status
curl http://localhost:5133/api/admin/recurring-jobs-status
```
### Health Checks
```bash
curl http://localhost:5133/health # Overall health
curl http://localhost:5133/health/ready # Readiness probe (K8s)
curl http://localhost:5133/health/live # Liveness probe (K8s)
```
---
## 📊 What's Remaining?
### 🏪 Inventory System (Current Focus)
1. **Phase 3: Business Services** (In Progress)
- `IInventoryManagementService` - High-level operations
- `IStockMovementService` - Movement orchestration
- `IWarehouseService` - Warehouse business logic
- `IInventoryReportingService` - Advanced reporting
2. **Phase 4: DTOs & AutoMapper** (Next)
- Request/Response DTOs
- AutoMapper profiles
- Validation rules
3. **Phase 5: API Controllers** (Planned)
- `InventoryController` - REST API
- `WarehouseController` - Warehouse management
- `StockMovementController` - Movement tracking
- Swagger documentation
### 💼 Commission System
1. **Payment Gateway Integration** (Phase 10 - 1 week)
- Daya or Bank Mellat API integration
- IBAN transfer automation
- Admin approval UI in BackOffice
2. **Production Configuration** (30 minutes)
- Gmail App Password setup
- Kavenegar API key registration
- Update `appsettings.Production.json`
### Medium Priority
3. **Club Shop Integration** (Phase 9 - 2 weeks)
- Product catalog for club memberships
- Shopping cart integration
- Auto-activation on purchase
### Low Priority
4. **Testing** (Phase 7 - Postponed)
- Unit tests for business logic
- Integration tests for API
- Load testing for background worker
### Optional Enhancements
- Redis distributed locks (multi-server deployment)
- Sentry error tracking (API key needed)
- Slack notifications (webhook needed)
- FCM push notifications
---
## 🎯 MVP Features (100% Complete)
### 💼 Commission System:
✅ Binary network tree with automatic placement
✅ Club membership (Member/Trial) with different commission rates
✅ Weekly commission calculation (Lesser Leg algorithm)
✅ Background worker with Hangfire (cron scheduling)
✅ Balance carryover logic (rollover unused volumes)
✅ MaxWeeklyBalances cap enforcement
✅ Health check endpoints (Kubernetes-ready)
✅ Manual trigger API (admin control)
✅ Email + SMS notifications (MailKit + Kavenegar)
✅ Retry logic with exponential backoff (Polly)
✅ Audit trail (WorkerExecutionLog, History tables)
✅ Structured logging (AlertService for Sentry/Slack)
✅ JWT authentication context (CurrentUserService)
### 🏪 Inventory System (Phase 2 Complete):
✅ Domain entities (InventoryItem, StockMovement, Warehouse)
✅ Multi-warehouse inventory management
✅ Stock reservation system for orders
✅ 8 movement types with complete audit trail
✅ Repository pattern with 25+ methods per repository
✅ CQRS with 17 commands and 35 queries
✅ 52 MediatR handlers with business logic
✅ Low stock and out-of-stock alerts
✅ Advanced analytics (top products, daily volume)
✅ Bulk operations support
✅ Transaction-safe operations with rollback
✅ DI container configuration
---
## 👥 Team
**Development**: FourSat Team
**Last Updated**: January 2026
---
## 📝 License
Proprietary - FourSat Company
# Multi-remote push enabled
cms/FILE-MANAGEMENT-ARCHITECTURE.md
-251
View File
@@ -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
-619
View File
@@ -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
-38
View File
@@ -1,38 +0,0 @@
# 🎉 به‌روزرسانی جدید - نسخه ۱.۵.۰
**تاریخ انتشار**: ۹ دی ۱۴۰۴
---
## ✨ امکانات جدید
### 💰 بهبود صفحه پاداش‌ها
- **انتخابگر هفته هوشمند**: حالا می‌تونید با تایپ کردن، هفته مورد نظر رو سریع‌تر پیدا کنید
- **نمایش خلاصه**: در بالای صفحه، مجموع پاداش‌ها، مبلغ پرداخت شده و در انتظار رو ببینید
- **طراحی جدید موبایل**: تجربه بهتر در گوشی موبایل
### 📊 جزئیات بیشتر در گزارش هفتگی
- **نمایش اعضای جدید**: تعداد اعضای جدید هر تیم در هفته
- **انتقال از هفته قبل**: مشاهده امتیازات منتقل شده از هفته گذشته
### 🎨 بهبود رابط کاربری
- طراحی زیباتر کارت‌ها و جداول
- نمایش بهتر در تمام اندازه‌های صفحه نمایش
---
## 🐛 رفع اشکال
- رفع مشکل نمایش نادرست امتیازات منتقل شده
- بهبود سرعت بارگذاری صفحات
---
## 💡 نکته
برای دسترسی به پاداش‌های خود، از منوی **پروفایل** گزینه **پاداش‌های من** را انتخاب کنید.
---
با تشکر از همراهی شما 🙏
**تیم کارا بازار سلامت**
cms/ICURRENTUSERSERVICE-IMPLEMENTATION.md
-591
View File
@@ -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-IMPROVEMENTS.md
-144
View File
@@ -1,144 +0,0 @@
# بهبود سیستم موجودی (Inventory System Improvements)
> **تاریخ:** اسفند ۱۴۰۴ (February 2026)
> **وضعیت:** ✅ پیاده‌سازی شده — مرج به production
> **پروژه‌های تغییر یافته:** CMS, BackOffice
---
## ۱. خلاصه تغییرات
| تغییر | پروژه | وضعیت |
|-------|--------|--------|
| ایجاد خودکار رکورد موجودی هنگام ساخت محصول عادی | CMS | ✅ |
| سرویس مهاجرت یکبار‌اجرا برای محصولات بدون رکورد موجودی | CMS | ✅ |
| اتوکامپلیت محصولات تخفیفی | BackOffice | ✅ |
| UX هوشمند دیالوگ ورود کالا | BackOffice | ✅ |
---
## ۲. CMS — ایجاد خودکار رکورد موجودی
### ۲.۱ مشکل
وقتی محصول جدید عادی ساخته می‌شد، رکورد `InventoryItem` ایجاد نمی‌شد. این باعث می‌شد محصول در بخش موجودی نمایش داده نشود تا ادمین دستی آن را اضافه کند.
> **نکته:** `CreateDiscountProductCommandHandler` از قبل `IInventoryService.InitializeInventoryAsync` را فراخوانی می‌کرد — فقط handler محصول عادی این قابلیت را نداشت.
### ۲.۲ تغییر در `CreateNewProductsCommandHandler`
**فایل:** `CMS/src/CMSMicroservice.Application/ProductsCQ/Commands/CreateNewProducts/CreateNewProductsCommandHandler.cs`
```csharp
// تزریق IInventoryService
private readonly IInventoryService _inventoryService;
// بعد از SaveChangesAsync:
try
{
await _inventoryService.InitializeInventoryAsync(entity.Id, ProductType.RegularProduct, 0);
}
catch (Exception ex)
{
_logger.LogWarning(ex, "Failed to auto-initialize inventory for product {ProductId}", entity.Id);
}
```
- موجودی با `qty=0` ایجاد می‌شود
- خطای موجودی باعث شکست ایجاد محصول نمی‌شود (try/catch)
---
## ۳. CMS — InventoryInitializerService (مهاجرت یکبار‌اجرا)
### ۳.۱ هدف
محصولات قدیمی (legacy) که قبل از اضافه شدن منطق خودکار ساخته شده بودند، رکورد `InventoryItem` ندارند. این سرویس هنگام استارت اپلیکیشن اجرا شده و برای آن‌ها رکورد ایجاد می‌کند.
### ۳.۲ پیاده‌سازی
**فایل:** `CMS/src/CMSMicroservice.Infrastructure/BackgroundServices/InventoryInitializerService.cs`
```
BackgroundService (one-time execution on startup)
├── پیدا کردن Products بدون InventoryItem
├── پیدا کردن DiscountProducts بدون InventoryItem
├── ایجاد InventoryItem برای هر کدام (qty = RemainingCount)
└── ذخیره و توقف
```
**ثبت در DI:**
```csharp
// ConfigureServices.cs
services.AddHostedService<InventoryInitializerService>();
```
### ۳.۳ ویژگی‌ها
- **یکبار اجرا:** بعد از اتمام، سرویس متوقف می‌شود
- **موجودی اولیه:** از `RemainingCount` محصول (نه صفر) برای رکوردهای legacy
- **لاگ‌گیری:** تعداد محصولات بدون رکورد و نتیجه عملیات لاگ می‌شود
- **مقاوم در برابر خطا:** خطا باعث شکست اپلیکیشن نمی‌شود
---
## ۴. BackOffice — DiscountProductsAutoComplete
### ۴.۱ هدف
کامپوننت autocomplete برای جستجوی محصولات تخفیفی (مشابه `ProductsAutoComplete` موجود).
### ۴.۲ فایل‌ها
| فایل | توضیح |
|------|-------|
| `Pages/AutoComplete/DiscountProductsAutoComplete.razor` | UI کامپوننت |
| `Pages/AutoComplete/DiscountProductsAutoComplete.razor.cs` | Code-behind |
### ۴.۳ ویژگی‌ها
- استفاده از `DiscountProductContract.DiscountProductContractClient` (gRPC)
- دِبانس ۷۰۰ms
- حداکثر ۹ نتیجه
- پارامتر خروجی `SelectedProductId` (EventCallback)
- `SearchQuery` از نوع `string` (نه `StringValue`)
---
## ۵. BackOffice — UX هوشمند AddStockDialog
### ۵.۱ مشکل قبلی
دیالوگ «ورود کالا» یک فیلد عددی خام برای وارد کردن شناسه محصول داشت. ادمین باید شناسه را حفظ بوده یا از جایی کپی می‌کرد.
### ۵.۲ تغییر
**فایل:** `BackOffice/src/BackOffice/Pages/Inventory/Components/AddStockDialog.razor`
```
وقتی ProductIdParam == null (دکمه «ورود کالا» از نوار ابزار):
├── انتخاب نوع محصول (فروشگاه عادی / فروشگاه اعتباری)
├── if فروشگاه عادی → نمایش ProductsAutoComplete
├── if فروشگاه اعتباری → نمایش DiscountProductsAutoComplete
└── ولیدیشن: محصول باید انتخاب شده باشد
وقتی ProductIdParam != null (از صفحه محصول):
└── فقط فیلد تعداد نمایش داده می‌شود
```
### ۵.۳ UX هوشمند
- انتخاب «فروشگاه عادی» → فقط محصولات عادی در autocomplete
- انتخاب «فروشگاه اعتباری» → فقط محصولات تخفیفی در autocomplete
- جلوگیری از اشتباه ادمین
---
## ۶. خلاصه فایل‌های تغییر یافته
### CMS
| فایل | نوع تغییر |
|------|-----------|
| `ProductsCQ/Commands/CreateNewProducts/CreateNewProductsCommandHandler.cs` | ✏️ ویرایش |
| `BackgroundServices/InventoryInitializerService.cs` | 🆕 جدید |
| `Infrastructure/ConfigureServices.cs` | ✏️ ویرایش (ثبت سرویس) |
### BackOffice
| فایل | نوع تغییر |
|------|-----------|
| `Pages/AutoComplete/DiscountProductsAutoComplete.razor` | 🆕 جدید |
| `Pages/AutoComplete/DiscountProductsAutoComplete.razor.cs` | 🆕 جدید |
| `Pages/Inventory/Components/AddStockDialog.razor` | ✏️ ویرایش |
cms/INVENTORY-REFACTORING-STATUS.md
-190
View File
@@ -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
-303
View File
@@ -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
-187
View File
@@ -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
-158
View File
@@ -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/SITE-PAGES-SIMPLIFICATION.md
-583
View File
@@ -1,583 +0,0 @@
# ساده‌سازی سیستم مدیریت صفحات سایت
> **تاریخ:** ۱۳۹۶/۱۱/۲۸ (2026-02-17)
> **وضعیت:** ✅ پیاده‌سازی کامل شده — مرج به production
> **اولویت:** بالا
---
## ۱. خلاصه مسئله
### وضعیت فعلی (مشکلات)
سیستم فعلی مدیریت صفحات **بیش از حد انعطاف‌پذیر و پیچیده** طراحی شده:
| مشکل | توضیح |
|-------|--------|
| **سیستم عمومی Section/Key** | ادمین باید `SectionKey` رو دقیق تایپ کنه (مثلاً `value-1`, `team-2`). یه اشتباه تایپی باعث میشه فرانت اون بخش رو پیدا نکنه |
| **ExtraData به‌صورت JSON خام** | اطلاعات تماس (آدرس/تلفن/ایمیل) و شبکه‌های اجتماعی داخل textarea به JSON خام نوشته میشه — خطاپذیر |
| **HTML Editor برای همه‌چیز** | حتی برای متن‌های ساده (عنوان یک Value) از HTML Editor استفاده میشه |
| **CRUD نامحدود** | ادمین میتونه صفحات جدید بسازه ولی فرانت فقط `about` و `contact` رو میشناسه |
| **لندینگ پیج کاملاً هاردکد** | محتوای لندینگ (Steps, Features, Stats, FAQ, Testimonials) داخل کد C# هاردکد شده و از CMS استفاده نمیکنه |
| **صفحه مجوزها وجود نداره** | هیچ صفحه‌ای برای نمایش نمادهای اعتماد و مجوزها نداریم |
### هدف
**۴ صفحه مشخص** با **فرم‌های اختصاصی** (نه عمومی) در پنل ادمین:
| # | صفحه | محتوای قابل ویرایش | طراحی |
|---|-------|-------------------|--------|
| 1 | **لندینگ** | عنوان hero، زیرعنوان، متن دکمه‌ها، عناوین سکشن‌ها، متن مراحل/ویژگی‌ها/سوالات/آمار | **چیدمان ثابت** — فقط متن‌ها قابل تغییر |
| 2 | **درباره ما** | عنوان، چشم‌انداز، مأموریت، ارزش‌ها (عنوان+متن+آیکون)، اعضای تیم (نام+سمت+تصویر) | **چیدمان ثابت** — تعداد ارزش‌ها و اعضا قابل تغییر |
| 3 | **تماس با ما** | آدرس، تلفن، ایمیل، ساعات کاری، لینک شبکه‌های اجتماعی | **چیدمان ثابت** — فقط اطلاعات قابل تغییر |
| 4 | **مجوزها** 🆕 | تصاویر مجوزها با عنوان و لینک (نماد اعتماد الکترونیکی و ...) | **ساده و یکپارچه** |
---
## ۲. معماری جدید — Structured Page Settings
### فلسفه طراحی
```
❌ قبلی: Generic Sections + Free-form Keys + Raw JSON
✅ جدید: Typed Settings per Page + Structured Forms + Fixed Layout
```
به‌جای اینکه هر صفحه N تا Section داشته باشه با Key‌های دلخواه، **هر صفحه یک مدل مشخص** با فیلدهای تایپ‌شده داره.
### ۲.۱ مدل‌های داده جدید (Database)
#### جدول `SitePageSettings` (جایگزین SitePage + SitePageSection)
```
┌─────────────────────────────────────────────┐
│ SitePageSettings │
├─────────────────────────────────────────────┤
│ Id : long (PK) │
│ PageKey : string(50) [UNIQUE INDEX] │ ← "landing" | "about" | "contact" | "licenses"
│ Title : string(200) │
│ MetaDescription : string?(300) │
│ HeroTitle : string?(200) │
│ HeroSubtitle : string?(500) │
│ HeroImagePath : string? │
│ IsActive : bool │
│ SettingsJson : string (JSON Column) │ ← ⭐ Typed JSON per PageKey
│ + Audit fields │
└─────────────────────────────────────────────┘
```
#### جدول `SitePageImage` (برای مجوزها و تصاویر تیم)
```
┌─────────────────────────────────────────────┐
│ SitePageImage │
├─────────────────────────────────────────────┤
│ Id : long (PK) │
│ SitePageSettingsId : long (FK) │
│ ImageGroup : string(50) │ ← "licenses" | "team" | "values"
│ Title : string?(200) │
│ Subtitle : string?(300) │
│ Description : string? │
│ ImagePath : string │
│ ThumbnailPath : string? │
│ LinkUrl : string? │ ← برای مجوزها: لینک به سایت مرجع
│ IconName : string?(100) │
│ SortOrder : int │
│ IsActive : bool │
│ + Audit fields │
└─────────────────────────────────────────────┘
```
#### SettingsJson — ساختار به‌ازای هر صفحه
**Landing (`PageKey = "landing"`):**
```json
{
"heroButtonPrimaryText": "شروع کنید",
"heroButtonSecondaryText": "بیشتر بدانید",
"steps": [
{ "title": "ثبت‌نام", "description": "...", "iconName": "PersonAdd" }
],
"features": [
{ "title": "پشتیبانی ۲۴/۷", "description": "...", "iconName": "Support" }
],
"stats": [
{ "label": "کاربران فعال", "value": 15000, "suffix": "+" }
],
"testimonials": [
{ "name": "علی محمدی", "role": "کاربر", "text": "...", "rating": 5 }
],
"faqs": [
{ "question": "سوال ۱", "answer": "جواب ۱", "category": "عمومی" }
],
"featuredBlogEnabled": true,
"ctaTitle": "همین الان شروع کنید",
"ctaDescription": "...",
"ctaButtonText": "ثبت‌نام رایگان"
}
```
**About (`PageKey = "about"`):**
```json
{
"visionTitle": "چشم‌انداز",
"visionText": "...",
"missionTitle": "مأموریت",
"missionText": "...",
"valuesTitle": "ارزش‌های ما",
"teamTitle": "تیم ما"
}
```
+ `SitePageImage` records با `ImageGroup = "values"` برای ارزش‌ها
+ `SitePageImage` records با `ImageGroup = "team"` برای اعضای تیم
**Contact (`PageKey = "contact"`):**
```json
{
"address": "تهران، ...",
"phone": "021-12345678",
"email": "info@kbs1.ir",
"workingHours": "شنبه تا چهارشنبه ۹ تا ۱۸",
"telegramUrl": "https://t.me/...",
"instagramUrl": "https://instagram.com/...",
"linkedinUrl": "https://linkedin.com/...",
"whatsappUrl": "https://wa.me/...",
"mapLatitude": 35.6892,
"mapLongitude": 51.3890,
"formSubjects": ["پشتیبانی فنی", "پیشنهاد همکاری", "سایر"]
}
```
**Licenses (`PageKey = "licenses"`):**
```json
{
"pageDescription": "مجوزها و نمادهای اعتماد",
"displayStyle": "grid"
}
```
+ `SitePageImage` records با `ImageGroup = "licenses"` — هر مجوز: Title + ImagePath + LinkUrl
---
## ۳. تغییرات به‌ازای هر لایه
### ۳.۱ دیتابیس (CMS — Entity Framework)
| عملیات | فایل/محل | توضیح |
|--------|----------|--------|
| **حذف** | `SitePage` entity | جایگزین با `SitePageSettings` |
| **حذف** | `SitePageSection` entity | جایگزین با `SitePageImage` (فقط برای آیتم‌های تصویری) |
| **ایجاد** | `SitePageSettings.cs` | Entity جدید با `SettingsJson` |
| **ایجاد** | `SitePageImage.cs` | Entity جدید برای تصاویر (مجوزها، تیم، ارزش‌ها) |
| **تغییر** | `DbContext` — `SitePageConfiguration` | Configuration جدید |
| **تغییر** | `SitePageSeedData.cs` | Seed data جدید برای ۴ صفحه |
| **Migration** | EF Migration | **Data migration** از ساختار قدیم به جدید |
### ۳.۲ Proto / gRPC Contract
| عملیات | توضیح |
|--------|--------|
| **بازنویسی** | `site_pages.proto` — حذف ۱۰ RPC قبلی، جایگزین با ۴ RPC ساده |
```protobuf
service SitePageSettingsService {
// دریافت تنظیمات صفحه با کلید (FrontOffice)
rpc GetPageSettings (GetPageSettingsRequest) returns (PageSettingsResponse);
// ذخیره تنظیمات صفحه (BackOffice — Admin)
rpc SavePageSettings (SavePageSettingsRequest) returns (SavePageSettingsResponse);
// مدیریت تصاویر صفحه (مجوزها، تیم، ارزش‌ها)
rpc SavePageImage (SavePageImageRequest) returns (SavePageImageResponse);
rpc DeletePageImage (DeletePageImageRequest) returns (DeletePageImageResponse);
// لیست همه صفحات (BackOffice)
rpc GetAllPages (GetAllPagesRequest) returns (GetAllPagesResponse);
}
```
### ۳.۳ CMS Backend (Application Layer)
| عملیات | فایل‌ها | توضیح |
|--------|---------|--------|
| **حذف** | ۲۲ فایل Command/Query فعلی | CQRS handlers قدیمی |
| **ایجاد** | `GetPageSettingsQuery` + Handler | دریافت Settings + Images |
| **ایجاد** | `SavePageSettingsCommand` + Handler + Validator | ذخیره JSON با اعتبارسنجی |
| **ایجاد** | `SavePageImageCommand` + Handler | آپلود/ویرایش تصویر |
| **ایجاد** | `DeletePageImageCommand` + Handler | حذف تصویر |
| **ایجاد** | `GetAllPagesQuery` + Handler | لیست صفحات |
| **تغییر** | gRPC Service | `SitePageGrpcService` بازنویسی |
### ۳.۴ FrontOffice (Blazor Server — سمت مشتری)
| عملیات | فایل | توضیح |
|--------|------|--------|
| **تغییر** | `SitePageService.cs` | ساده‌سازی — فقط `GetPageSettings(pageKey)` |
| **تغییر** | `Index.razor` + `.cs` | **بزرگ‌ترین تغییر:** از هاردکد به CMS-driven. چیدمان ثابت میمونه، فقط متن‌ها از `SettingsJson` خونده میشه |
| **تغییر** | `AboutUs.razor` + `.cs` | ساده‌تر — خواندن مستقیم فیلدهای typed به‌جای key-matching |
| **تغییر** | `ContactUs.razor` + `.cs` | ساده‌تر — خواندن مستقیم فیلدها بدون JSON parsing |
| **ایجاد** | `Licenses.razor` + `.cs` | 🆕 صفحه جدید مجوزها |
### ۳.۵ BackOffice (Blazor WASM — پنل ادمین)
| عملیات | فایل | توضیح |
|--------|------|--------|
| **حذف** | ۵ فایل Dialog فعلی | `CreateSitePageDialog`, `EditSitePageDialog`, `SitePageSectionsDialog`, `SitePageSectionEditDialog` |
| **حذف** | `SitePageManagement.razor` + `.cs` فعلی | جایگزین |
| **ایجاد** | `PageSettingsManagement.razor` | صفحه اصلی — لیست ۴ صفحه ثابت |
| **ایجاد** | `LandingPageSettings.razor` | 🌟 فرم اختصاصی لندینگ |
| **ایجاد** | `AboutPageSettings.razor` | 🌟 فرم اختصاصی درباره‌ما |
| **ایجاد** | `ContactPageSettings.razor` | 🌟 فرم اختصاصی تماس |
| **ایجاد** | `LicensesPageSettings.razor` | 🌟 فرم اختصاصی مجوزها |
| **تغییر** | `ISitePageService` + Impl | ساده‌سازی interface |
---
## ۴. طراحی UI پنل ادمین (BackOffice)
### ۴.۱ صفحه اصلی مدیریت صفحات
```
┌─────────────────────────────────────────────────────────┐
│ مدیریت صفحات سایت │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 🏠 │ │ 👥 │ │ 📞 │ │ 🏅 │ │
│ │ لندینگ │ │ درباره‌ما│ │ تماس │ │ مجوزها │ │
│ │ │ │ │ │ │ │ │ │
│ │ [ویرایش] │ │ [ویرایش] │ │ [ویرایش] │ │ [ویرایش] │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ℹ️ صفحات سایت ثابت هستند و فقط محتوای آنها │
│ قابل ویرایش است │
└─────────────────────────────────────────────────────────┘
```
### ۴.۲ فرم ویرایش لندینگ (نمونه)
```
┌─────────────────────────────────────────────────────────┐
│ ← بازگشت تنظیمات صفحه لندینگ │
├─────────────────────────────────────────────────────────┤
│ │
│ ── Hero Section ────────────────────────────────────── │
│ عنوان: [_______________________________] │
│ زیرعنوان: [_______________________________] │
│ تصویر پس‌زمینه: [📎 انتخاب فایل] │
│ متن دکمه اصلی: [_____________] │
│ متن دکمه ثانویه:[_____________] │
│ │
│ ── مراحل (Steps) ───────────────────────────────────── │
│ ┌────┬──────────────┬──────────────────┬────────┐ │
│ │ # │ عنوان │ توضیح │ آیکون │ │
│ ├────┼──────────────┼──────────────────┼────────┤ │
│ │ 1 │ [ثبت‌نام ] │ [در کمتر از...] │ [🔍] │ │
│ │ 2 │ [دعوت ] │ [لینک اختصاصی ] │ [🔍] │ │
│ │ 3 │ [دریافت ] │ [پاداش‌های... ] │ [🔍] │ │
│ │ │ │ [+ افزودن مرحله]│ │ │
│ └────┴──────────────┴──────────────────┴────────┘ │
│ │
│ ── ویژگی‌ها (Features) ──────────────────────────────── │
│ (مشابه بالا — جدول قابل ویرایش) │
│ │
│ ── آمار (Stats) ────────────────────────────────────── │
│ ┌──────────────┬─────────┬────────┐ │
│ │ برچسب │ مقدار │ پسوند │ │
│ ├──────────────┼─────────┼────────┤ │
│ │ [کاربران ] │ [15000] │ [+] │ │
│ └──────────────┴─────────┴────────┘ │
│ │
│ ── نظرات مشتریان ───────────────────────────────────── │
│ (جدول: نام، نقش، متن، امتیاز) │
│ │
│ ── سوالات متداول (FAQ) ─────────────────────────────── │
│ (جدول: سوال، جواب، دسته‌بندی) │
│ │
│ ── CTA Banner ──────────────────────────────────────── │
│ عنوان: [_______________] │
│ توضیح: [_______________] │
│ متن دکمه: [_______________] │
│ │
│ [💾 ذخیره تغییرات] │
└─────────────────────────────────────────────────────────┘
```
### ۴.۳ فرم ویرایش تماس با ما
```
┌─────────────────────────────────────────────────────────┐
│ ← بازگشت تنظیمات صفحه تماس با ما │
├─────────────────────────────────────────────────────────┤
│ │
│ ── اطلاعات تماس ───────────────────────────────────── │
│ آدرس: [_______________________________] │
│ تلفن: [_______________________________] │
│ ایمیل: [_______________________________] │
│ ساعات کاری: [_______________________________] │
│ │
│ ── شبکه‌های اجتماعی ───────────────────────────────── │
│ تلگرام: [_______________________________] │
│ اینستاگرام: [_______________________________] │
│ لینکدین: [_______________________________] │
│ واتس‌اپ: [_______________________________] │
│ │
│ ── تنظیمات فرم تماس ───────────────────────────────── │
│ موضوعات: [پشتیبانی فنی ×] [پیشنهاد همکاری ×] │
│ [+ افزودن موضوع] │
│ │
│ [💾 ذخیره تغییرات] │
└─────────────────────────────────────────────────────────┘
```
### ۴.۴ فرم مجوزها (جدید)
```
┌─────────────────────────────────────────────────────────┐
│ ← بازگشت مدیریت مجوزها و نمادهای اعتماد │
├─────────────────────────────────────────────────────────┤
│ │
│ توضیح صفحه: [_______________________________] │
│ │
│ ── مجوزها ──────────────────────────────────────────── │
│ ┌──────┬──────────────┬─────────────────┬────────────┐ │
│ │ تصویر│ عنوان │ لینک │ عملیات │ │
│ ├──────┼──────────────┼─────────────────┼────────────┤ │
│ │ [🖼] │ [نماد اعتماد]│ [https://...] │ [🗑] [↕] │ │
│ │ [🖼] │ [ساماندهی ] │ [https://...] │ [🗑] [↕] │ │
│ │ [🖼] │ [مجوز کسب..] │ [https://...] │ [🗑] [↕] │ │
│ └──────┴──────────────┴─────────────────┴────────────┘ │
│ │
│ [+ افزودن مجوز جدید] │
│ │
│ [💾 ذخیره تغییرات] │
└─────────────────────────────────────────────────────────┘
```
---
## ۵. طراحی UI فرانت مشتری (FrontOffice)
### ۵.۱ صفحه مجوزها (جدید — `/licenses`)
```
┌─────────────────────────────────────────────────────────┐
│ [Header / Navbar] │
├─────────────────────────────────────────────────────────┤
│ │
│ 🏅 مجوزها و نمادهای اعتماد │
│ توضیح کوتاه صفحه از CMS │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ │ │ │ │ │ │
│ │ [تصویر] │ │ [تصویر] │ │ [تصویر] │ │
│ │ │ │ │ │ │ │
│ │ نماد │ │ ساماندهی │ │ مجوز │ │
│ │ اعتماد │ │ │ │ کسب‌وکار │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ (هر تصویر لینک‌دار — کلیک = باز شدن سایت مرجع) │
│ │
├─────────────────────────────────────────────────────────┤
│ [Footer] │
└─────────────────────────────────────────────────────────┘
```
### ۵.۲ تغییرات سایر صفحات
- **لندینگ:** بدون تغییر ظاهری — فقط منبع داده از هاردکد به CMS تغییر میکنه
- **درباره ما:** بدون تغییر ظاهری — کد ساده‌تر میشه
- **تماس با ما:** بدون تغییر ظاهری — کد ساده‌تر میشه
---
## ۶. Migration Plan — مراحل اجرا
### فاز ۱: دیتابیس و Backend (CMS)
```
مدت تخمینی: ۱ روز
```
| # | تسک | جزئیات |
|---|------|--------|
| 1.1 | ایجاد Entity‌های جدید | `SitePageSettings`, `SitePageImage` |
| 1.2 | ایجاد EF Configuration | Indexes, relationships, JSON column |
| 1.3 | نوشتن Migration | `SimplifySitePages` — ایجاد جدول‌های جدید |
| 1.4 | نوشتن Data Migration | انتقال داده از `SitePage`/`SitePageSection` به ساختار جدید |
| 1.5 | Seed Data جدید | ۴ صفحه: landing, about, contact, licenses |
| 1.6 | حذف Entity‌های قدیمی | بعد از تأیید migration موفق |
### فاز ۲: Proto و gRPC Service
```
مدت تخمینی: ۰.۵ روز
```
| # | تسک | جزئیات |
|---|------|--------|
| 2.1 | بازنویسی `site_pages.proto` | ۵ RPC جدید (Get, Save, Image CRUD, List) |
| 2.2 | بازنویسی gRPC Service | `SitePageSettingsGrpcService` |
| 2.3 | نوشتن CQRS Handlers | ۵ handler جدید |
| 2.4 | Validators | اعتبارسنجی SettingsJson بر اساس PageKey |
### فاز ۳: BackOffice (پنل ادمین)
```
مدت تخمینی: ۱.۵ روز
```
| # | تسک | جزئیات |
|---|------|--------|
| 3.1 | حذف UI قدیمی | ۵ فایل dialog + management page |
| 3.2 | صفحه اصلی | `PageSettingsManagement.razor` — کارت‌های ۴ صفحه |
| 3.3 | فرم لندینگ | `LandingPageSettings.razor` — فرم با سکشن‌های Steps/Features/Stats/FAQ/Testimonials/CTA |
| 3.4 | فرم درباره‌ما | `AboutPageSettings.razor` — Vision/Mission + مدیریت Values & Team |
| 3.5 | فرم تماس | `ContactPageSettings.razor` — فیلدهای ساده |
| 3.6 | فرم مجوزها | `LicensesPageSettings.razor` — آپلود و مدیریت تصاویر مجوز |
| 3.7 | سرویس BackOffice | `ISitePageSettingsService` + Implementation |
### فاز ۴: FrontOffice (سمت مشتری)
```
مدت تخمینی: ۱ روز
```
| # | تسک | جزئیات |
|---|------|--------|
| 4.1 | بروزرسانی `SitePageService` | ساده‌سازی — فقط `GetPageSettings` |
| 4.2 | بروزرسانی `Index.razor` | خواندن Steps/Features/Stats/FAQ/Testimonials از CMS |
| 4.3 | بروزرسانی `AboutUs.razor` | خواندن مستقیم فیلدها (بدون key-matching) |
| 4.4 | بروزرسانی `ContactUs.razor` | خواندن مستقیم فیلدها (بدون JSON parsing) |
| 4.5 | ایجاد `Licenses.razor` | 🆕 صفحه جدید مجوزها |
| 4.6 | افزودن به Navigation | لینک مجوزها در Footer |
### فاز ۵: تست و Cleanup
```
مدت تخمینی: ۰.۵ روز
```
| # | تسک | جزئیات |
|---|------|--------|
| 5.1 | تست E2E | همه ۴ صفحه در FrontOffice |
| 5.2 | تست ادمین | ویرایش همه ۴ صفحه از BackOffice |
| 5.3 | حذف کدهای قدیمی | فایل‌هایی که دیگه استفاده نمیشن |
| 5.4 | بروزرسانی مستندات | CHANGELOG, INDEX.md |
---
## ۷. مقایسه قبل و بعد
### کاهش پیچیدگی
| معیار | قبل | بعد | تغییر |
|-------|------|------|--------|
| RPC‌های gRPC | 10 | 5 | -50% |
| CQRS Handlers | 10 (22 file) | 5 (~12 file) | -45% |
| Entity‌ها | 2 (generic) | 2 (typed) | = |
| BackOffice Dialogs | 4 generic | 4 specific | کیفیت↑ |
| JSON خام در UI | ✅ بله | ❌ خیر | حذف |
| خطای تایپ SectionKey | ✅ ممکن | ❌ غیرممکن | حذف |
| لندینگ CMS-driven | ❌ هاردکد | ✅ CMS | بهبود |
| صفحه مجوزها | ❌ ندارد | ✅ دارد | 🆕 |
### تجربه ادمین
| قبل | بعد |
|------|------|
| لیست صفحات → انتخاب → مدیریت سکشن‌ها → ویرایش سکشن (4 مرحله) | ۴ کارت → فرم اختصاصی (2 مرحله) |
| JSON خام برای اطلاعات تماس | فیلدهای مشخص (آدرس، تلفن، ایمیل) |
| HTML Editor برای عنوان ساده | Text field ساده |
| امکان ساخت صفحه‌ای که فرانت نمیشناسه | فقط ۴ صفحه مشخص |
---
## ۸. ریسک‌ها و ملاحظات
| ریسک | شدت | راه‌حل |
|------|------|--------|
| Data migration از ساختار قدیم | متوسط | Script migration دقیق + بکاپ قبل از اجرا |
| Breaking change در Proto | بالا | نسخه جدید Proto NuGet + بروزرسانی هر ۳ پروژه همزمان |
| تصاویر موجود (hero, section images) | کم | مسیرها در فایل سیستم ثابت میمونن — فقط reference DB تغییر میکنه |
| Backward compatibility | کم | چون ساختار قبلی فقط ۲ صفحه فعال داشت، migration ساده‌ست |
---
## ۹. فایل‌های تأثیرپذیر (خلاصه)
### حذف (Delete)
```
CMS:
- Domain/Entities/Content/SitePage.cs
- Domain/Entities/Content/SitePageSection.cs
- Application/Features/SitePages/* (22 files)
- Infrastructure/Persistence/Configurations/SitePageConfiguration.cs
- Infrastructure/Persistence/Configurations/SitePageSectionConfiguration.cs
BackOffice:
- Pages/Content/SitePageManagement.razor + .cs
- Pages/Content/CreateSitePageDialog.razor + .cs
- Pages/Content/EditSitePageDialog.razor + .cs
- Pages/Content/SitePageSectionsDialog.razor + .cs
- Pages/Content/SitePageSectionEditDialog.razor + .cs
```
### ایجاد (Create)
```
CMS:
- Domain/Entities/Content/SitePageSettings.cs
- Domain/Entities/Content/SitePageImage.cs
- Application/Features/SitePageSettings/* (~12 files)
- Infrastructure/Persistence/Configurations/SitePageSettingsConfiguration.cs
- Infrastructure/Persistence/Configurations/SitePageImageConfiguration.cs
BackOffice:
- Pages/Content/PageSettingsManagement.razor + .cs
- Pages/Content/LandingPageSettings.razor + .cs
- Pages/Content/AboutPageSettings.razor + .cs
- Pages/Content/ContactPageSettings.razor + .cs
- Pages/Content/LicensesPageSettings.razor + .cs
FrontOffice:
- Pages/Licenses.razor + .cs
Proto:
- site_pages.proto (rewrite)
```
### تغییر (Modify)
```
CMS:
- ApplicationDbContext.cs (DbSets)
- SitePageSeedData.cs
- SitePageGrpcService.cs
BackOffice:
- Services/ISitePageService.cs → ISitePageSettingsService.cs
- Services/SitePageService.cs → SitePageSettingsService.cs
- NavMenu (routing)
FrontOffice:
- Services/SitePageService.cs (simplify)
- Pages/Index.razor + .cs (CMS-driven)
- Pages/AboutUs.razor + .cs (simplify)
- Pages/ContactUs.razor + .cs (simplify)
- Shared/NavMenu or Footer (add Licenses link)
- DI registration
```
---
## ۱۰. نتیجه‌گیری
این تغییر یک **ساده‌سازی معماری** هست که:
1. ✅ پیچیدگی غیرضروری رو حذف میکنه
2. ✅ تجربه ادمین رو بهبود میده (فرم‌های اختصاصی به‌جای فرم‌های عمومی)
3. ✅ خطاهای انسانی رو کاهش میده (بدون JSON خام و SectionKey تایپی)
4. ✅ لندینگ پیج رو CMS-driven میکنه
5. ✅ صفحه مجوزها رو اضافه میکنه
6. ✅ حجم کد رو ~۳۰٪ کاهش میده
> **مرحله بعد:** بعد از تأیید این طرح، شروع پیاده‌سازی از فاز ۱ (دیتابیس)
cms/chatika-integration.md
-424
View File
@@ -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
-490
View File
@@ -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
-191
View File
@@ -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
-410
View File
@@ -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
-1060
View File
File diff suppressed because it is too large Load Diff
cms/system-constants.md
-120
View File
@@ -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
-678
View File
@@ -1,678 +0,0 @@
# 🔧 راهنمای CI/CD Pipeline — Gitea Actions + K3s
> آخرین بروزرسانی: February 17, 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 بدون مشکل استفاده میکنه.
---
### مشکل ۸: `COPY libs/` fails in Docker build (BackOffice)
**خطا:**
```
COPY failed: file not found in build context: stat libs/: file does not exist
```
**علت:** Dockerfile خط `COPY ["libs/", "libs/"]` داشت ولی `libs/` خارج از Docker build context (`src/`) بود. قبلاً BFF DLLها استفاده می‌شدن، ولی حالا از NuGet package مستقیم استفاده می‌شه.
**راه‌حل:**
1. حذف `COPY ["libs/", "libs/"]` از Dockerfile
2. تغییر `ProjectReference` به `PackageReference` در csproj:
```xml
<!-- قبل -->
<ProjectReference Include="../../../CMS/src/CMSMicroservice.Protobuf/CMSMicroservice.Protobuf.csproj" />
<!-- بعد -->
<PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="0.0.178" />
```
---
### مشکل ۹: ProjectReference خارج از Docker context (FrontOffice/BackOffice)
**خطا:**
```
error CS0246: The type or namespace name 'CustomerAddressModel' could not be found
```
**علت:** csproj از `ProjectReference Include="../../../CMS/src/CMSMicroservice.Protobuf/..."` استفاده می‌کرد. در Docker build context فقط `src/` موجوده → CMS قابل دسترسی نیست.
**راه‌حل:**
1. بامپ نسخه پروتوباف (`0.0.177` → `0.0.178`)
2. `dotnet pack -c Release` و push به Nexus
3. تغییر هر دو پروژه (FrontOffice + BackOffice) به `PackageReference`
```bash
# Pack & Push
cd CMS/src/CMSMicroservice.Protobuf
dotnet pack -c Release
dotnet nuget push bin/Release/Foursat.CMSMicroservice.Protobuf.0.0.178.nupkg \
--source http://194.5.195.53:32081/repository/foursat-nuget-hosted/index.json \
--api-key admin:87zH26nbqT --skip-duplicate
```
---
### مشکل ۱۰: `nginx:alpine` TLS handshake timeout
**خطا:**
```
Get "https://registry-1.docker.io/v2/": net/http: TLS handshake timeout
```
**علت:** Dockerfile خط `FROM nginx:alpine` مستقیم از Docker Hub پول می‌کرد ولی سرور به Docker Hub دسترسی نداره.
**راه‌حل:** تغییر به رجیستری لوکال:
```dockerfile
# قبل
FROM nginx:alpine AS final
# بعد
FROM 194.5.195.53:32082/nginx:alpine AS final
```
---
### مشکل ۱۱: SERVER_PASSWORD secret missing → Permission denied
**خطا:**
```
Permission denied, please try again.
```
**علت:** سکرت `SERVER_PASSWORD` در ریپو Gitea تنظیم نشده بود. Pipeline از `sshpass -e` با `${{ secrets.SERVER_PASSWORD }}` برای SSH استفاده می‌کنه.
**راه‌حل:** اضافه کردن سکرت از طریق Gitea API:
```bash
curl -sk -u "admin:87zH26nbqT" -X PUT \
"https://git.se.kbs1.ir/api/v1/repos/admin/BackOffice/actions/secrets/SERVER_PASSWORD" \
-H "Content-Type: application/json" -d '{"data":"87zH26nbqT"}'
```
---
### مشکل ۱۲: CMS ingress 502 — backend-protocol: GRPC
**خطا:** `https://cms.se.kbs1.ir/` → 502 Bad Gateway
**علت:** CMS ingress annotation `backend-protocol: GRPC` داشت + Kestrel فقط `Http2`. مرورگر HTTP/1.1 می‌فرسته → nginx نمی‌تونه به gRPC backend فوروارد کنه.
**راه‌حل (دو تغییر):**
1. Kestrel protocol → `Http1AndHttp2` (هم gRPC هم REST):
```bash
kubectl set env deployment/cms Kestrel__EndpointDefaults__Protocols=Http1AndHttp2
```
2. حذف GRPC annotations از ingress:
```bash
kubectl annotate ingress cms-ingress nginx.ingress.kubernetes.io/backend-protocol-
kubectl annotate ingress cms-ingress nginx.ingress.kubernetes.io/grpc-backend-
```
> ⚠️ FrontOffice از gRPC-Web استفاده می‌کنه که روی HTTP/1.1 هم کار می‌کنه.
---
## 🔄 تغییرات 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) — ⚠️ باید در هر ۳ ریپو ست بشه |
> **نکته:** اگر `SERVER_PASSWORD` ست نباشه، مرحله Deploy با `Permission denied` فیل می‌شه.
> با API اضافه کنید:
> ```bash
> curl -sk -u "admin:PASSWORD" -X PUT \
> "https://git.se.kbs1.ir/api/v1/repos/admin/REPO/actions/secrets/SERVER_PASSWORD" \
> -H "Content-Type: application/json" -d '{"data":"PASSWORD"}'
> ```
---
## 🔧 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
"
```
---
## 🐛 باگ بحرانی: Cross-Deployment — Push به Production ری‌دیپلوی Staging (اسفند ۱۴۰۴)
### علائم:
- Push به برنچ `production` → هم production و هم staging ری‌دیپلوی شدند
- CMS staging pod بعد از push ریستارت شد
- Runner log: **۲ تسک CMS** بجای ۱ تسک اجرا شد
### علت ریشه‌ای:
Gitea Act Runner **تمام فایل‌های workflow** داخل `.gitea/workflows/` برنچ push شده رو اجرا می‌کنه — حتی اگه `on.push.branches` برنچ دیگه‌ای باشه. وقتی production push شد، `kub-deploy.yml` (trigger: `kub-stage`) هم اجرا شد و ایمیج `admin/cms:latest` رو با کد production ساخت → staging از `latest` pull کرد → **staging با DB production بالا اومد!**
### راه‌حل:
حذف workflow‌های staging از برنچ production (هر ۳ ریپو):
```bash
git rm .gitea/workflows/kub-deploy.yml .gitea/workflows/cms-stage.yml # CMS
git rm .gitea/workflows/fo-stage.yml .gitea/workflows/kub-deploy.yml # FrontOffice
git rm .gitea/workflows/bo-stage.yml .gitea/workflows/kub-deploy.yml # BackOffice
```
> ⚠️ **قانون طلایی:** هر برنچ فقط workflow مربوط به خودش رو داشته باشه.
---
## 🐛 مشکل ۱۳: Production deploy ایمیج pull نمی‌شد
**علت:** Production K8s از `git.foursat.afrino.co/admin/cms:prod` pull می‌کرد، ولی CI ایمیج رو به `194.5.195.53:30080` push می‌کرد.
**راه‌حل:**
1. اضافه کردن `194.5.195.53:30080` به `/etc/rancher/k3s/registries.yaml` پروداکشن + ری‌استارت K3s
2. آپدیت deployment image: `kubectl set image deployment/cms cms=194.5.195.53:30080/admin/cms:prod`
3. فیکس `prod-deploy.yml`: `K8S_SSH_PASSWORD` → `SERVER_PASSWORD`, `rollout restart` → `set image :sha`
---
## 🔄 Production Workflow Template (فعلی)
```yaml
name: Build and Deploy to Production
on:
push:
branches: [production]
env:
REGISTRY: 194.5.195.53:30080
IMAGE_NAME: admin/<service>
K8S_SERVER: 45.149.79.127
jobs:
build-and-deploy:
runs-on: ubuntu-latest
container:
image: 194.5.195.53:32082/docker-sshpass:latest
options: --privileged
steps:
# ... (Start Docker, Checkout, Login — مشابه staging)
- name: Build Docker Image
run: |
DOCKER_BUILDKIT=0 docker build --network host \
-t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }} \
-t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:prod .
- name: Push to Registry
run: |
docker push ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
docker push ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:prod
- name: Deploy to Production
run: |
export SSHPASS="${{ secrets.SERVER_PASSWORD }}"
sshpass -e ssh -o StrictHostKeyChecking=no root@${{ env.K8S_SERVER }} "
kubectl set image deployment/<svc> <svc>=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
kubectl rollout status deployment/<svc> --timeout=300s
"
```
> تفاوت staging vs production: staging = tag `latest` + `rollout restart` | production = tag `sha` + `set image`
---
## 🏗️ مشخصات دو محیط
| | Staging | Production |
|--|---------|------------|
| **سرور** | `194.5.195.53` | `45.149.79.127` |
| **DB** | `mssql-svc@Foursat` | `45.149.79.127,31433@KBS` |
| **Registry** | `194.5.195.53:30080` (local) | همان staging registry |
| **Image Tags** | `:latest` | `:prod` + `:sha` |
| **Branch** | `kub-stage` | `production` |
| **Domains** | `*.se.kbs1.ir` | `*.kbs1.ir` |
---
## 🐛 مشکل ۱۴: K8S_SERVER اشتباه در prod-deploy.yml (CMS + BackOffice)
**تاریخ:** February 17, 2026
**علت:** `K8S_SERVER` در `prod-deploy.yml` CMS و BackOffice هنوز `194.5.195.53` (staging) بود بجای `45.149.79.127` (production).
**عارضه:** `kubectl set image` به سرور staging ارسال می‌شد — deployment production آپدیت نمی‌شد.
**فایل‌های فیکس شده:**
- `CMS/.gitea/workflows/prod-deploy.yml` — `K8S_SERVER: 194.5.195.53` → `45.149.79.127`
- `BackOffice/.gitea/workflows/prod-deploy.yml` — `K8S_SERVER: 194.5.195.53` → `45.149.79.127`
- FrontOffice قبلاً درست بود ✅
**فیکس اضافی:** هر دو workflow از `kubectl rollout restart` به `kubectl set image` تغییر کردن تا ایمیج SHA-tagged واقعاً set بشه.
---
## 🐛 مشکل ۱۵: نبود appsettings.Production.json — URLهای staging روی production
**تاریخ:** February 17, 2026
**علت:** هیچکدوم از ۳ پروژه `appsettings.Production.json` نداشتن. از طرفی `ASPNETCORE_ENVIRONMENT=Production` ست بود → fallback به `appsettings.json` (که URLهای staging داشت).
**عارضه‌ها:**
- CMS: `CmsBaseUrl=cms.se.kbs1.ir` → ZarinPal callback به staging برمی‌گشت
- CMS: `FrontOfficeBaseUrl=foursat.se.kbs1.ir` → redirect بعد از پرداخت به staging می‌رفت
- FrontOffice: `GwUrl=localhost:32846` → gRPC به هیچ‌جا وصل نمی‌شد
- BackOffice: `GwUrl=localhost:32847` → gRPC به هیچ‌جا وصل نمی‌شد
**فایل‌های ساخته شده:**
| پروژه | فایل | محتوای کلیدی |
|--------|------|-------------|
| CMS | `src/CMSMicroservice.WebApi/appsettings.Production.json` | `CmsBaseUrl=cms.kbs1.ir`, `FrontOfficeBaseUrl=kbs1.ir`, `DB=KBS`, `ZarinPal.UseSandbox=false` |
| FrontOffice | `src/FrontOffice.Main/appsettings.Production.json` | `GwUrl=cms.kbs1.ir` |
| BackOffice | `src/BackOffice/wwwroot/appsettings.Production.json` | `GwUrl=cms.kbs1.ir` |
> ⚠️ **نکته:** CMS فایل `appsettings.Production.json` در `.gitignore` هست (`**/ appsettings.Production.json`). با `git add -f` ترک شد. بعد از هر تغییر باید دوباره force add بشه.
---
## 🐛 مشکل ۱۶: nginx image path اشتباه در BackOffice Dockerfile (production branch)
**تاریخ:** February 17, 2026
**علت:** Dockerfile روی برنچ `production` از `194.5.195.53:32082/library/nginx:alpine` استفاده می‌کرد که در رجیستری وجود نداشت. روی `kub-stage` قبلاً فیکس شده بود ولی merge به production این خط رو override کرده بود.
**ارور CI:**
```
Step 9/14 : FROM 194.5.195.53:32082/library/nginx:alpine AS final
manifest for 194.5.195.53:32082/library/nginx:alpine not found: manifest unknown
```
**رفع:**
```dockerfile
# قبل (اشتباه)
FROM 194.5.195.53:32082/library/nginx:alpine AS final
# بعد (صحیح)
FROM 194.5.195.53:32082/nginx:alpine AS final
```
**نکته:** این فیکس مستقیماً روی برنچ `production` انجام و push شد (کامیت `743403e`).
deployment/DEPLOYMENT-README.md
-161
View File
@@ -1,161 +0,0 @@
# 🚀 FourSat Offline Deployment
این دایرکتوری شامل scripts و مستندات برای deploy کردن سرویس‌های FourSat **بدون نیاز به اینترنت** است.
## ⚡ Quick Start
### گزینه 1: Setup خودکار (پیشنهادی)
**روی ماشینی با Docker و اینترنت:**
```bash
cd /home/masoud/Apps/project/FourSat/deployment
./setup-offline-complete.sh
```
این اسکریپت:
- ✅ Images را pull می‌کند
- ✅ Export می‌کند به `.tar`
- ✅ به server transfer می‌کند
- ✅ در containerd server import می‌کند
- ✅ تمام!
### گزینه 2: Setup دستی
اگر Docker روی این ماشین نیست، مستندات کامل را بخوانید:
```bash
cat OFFLINE-SETUP-GUIDE.md
```
---
## 📁 فایل‌های مهم
### 🎯 اسکریپت‌های اصلی
- **`setup-offline-complete.sh`** ⭐ - Setup کامل خودکار (نیاز به Docker)
- **`export-import-images.sh`** - Export/Import دستی images
- **`OFFLINE-SETUP-GUIDE.md`** 📚 - راهنمای کامل قدم به قدم
### 📖 مستندات
- **`README.md`** - این فایل
- **`QUICK-REFERENCE.md`** - مرجع سریع commands
- **`DEPLOYMENT-GUIDE.md`** - راهنمای deployment
- **`SERVER-SETUP-GUIDE.md`** - تنظیمات server
- **`CHANGES-SUMMARY.md`** - لیست تغییرات انجام شده
- **`SETUP-INSTRUCTIONS.md`** - دستورالعمل‌های setup
### 🛠️ اسکریپت‌های کمکی
- `pull-base-images.sh` - Pull کردن base images
- `save-images.sh` - ذخیره images به tar
- `load-images.sh` - بارگذاری images از tar
- `cache-nuget-packages.sh` - Cache کردن NuGet packages
- `build-all-offline.sh` - Build تمام سرویس‌ها offline
- `cleanup.sh` - پاکسازی فایل‌های build
- `test-services.sh` - تست سرویس‌های deploy شده
- `k8s-deploy.sh` - Deploy به Kubernetes
- `k8s-health-check.sh` - بررسی سلامت deployments
- `quick-start.sh` - Setup تعاملی
- `server-cache-images.sh` - Cache images روی server
- `load-cached-images.sh` - بارگذاری cached images
- `verify-cache.sh` - بررسی cache
- `pull-images-to-node.sh` - Pull به Kubernetes node
---
## 🔍 چک‌لیست Setup
- [ ] **Base images در containerd server** (روی node نه pod)
- [ ] **Workflows بدون proxy** تنظیم شده‌اند
- [ ] **DNS = "0.0.0.0"** برای جلوگیری از دسترسی به اینترنت
- [ ] **DOCKER_BUILDKIT=0** برای استفاده از legacy builder
- [ ] **Test یک workflow** برای اطمینان از کار کردن offline
---
## 🏗️ معماری Deployment
```
┌─────────────────────────────────────────┐
│ Kubernetes Cluster (194.5.195.53) │
│ │
│ ┌───────────────────────────────────┐ │
│ │ Node (containerd) │ │
│ │ ├─ mcr.microsoft.com/dotnet/* │ │
│ │ └─ nginx:alpine │ │
│ └───────────────────────────────────┘ │
│ ▲ │
│ │ images available to pods │
│ │ │
│ ┌──────┴──────────────────────────┐ │
│ │ gitea-runner pod │ │
│ │ ├─ dind (Docker-in-Docker) │ │
│ │ └─ runner (Gitea Actions) │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────────┘
```
**کلید موفقیت**: Images باید در **containerd روی node** باشند، نه در pod!
---
## 🐛 عیب‌یابی
### ❌ Workflow هنوز download می‌کند؟
```bash
# بررسی images روی server
ssh root@194.5.195.53 "ctr -n k8s.io images list | grep mcr.microsoft.com"
```
اگر خالی است، setup را دوباره اجرا کنید.
### ❌ Build با error می‌خورد؟
```bash
# بررسی logs workflow در Gitea
# اگر "TLS handshake timeout" می‌بینید → DNS هنوز active است
# اگر "image not found" می‌بینید → images در containerd نیستند
```
### ❌ Import به containerd کار نمی‌کند?
```bash
# مطمئن شوید namespace درست است
ssh root@194.5.195.53 "ctr namespaces list"
# باید k8s.io را ببینید
# برای import همیشه از -n k8s.io استفاده کنید:
ctr -n k8s.io images import /path/to/image.tar
```
---
## 📞 Support
مشکل دارید? مستندات کامل را بخوانید:
```bash
# راهنمای کامل setup offline
cat OFFLINE-SETUP-GUIDE.md
# مرجع سریع commands
cat QUICK-REFERENCE.md
# راهنمای deployment
cat DEPLOYMENT-GUIDE.md
```
---
## ✨ ویژگی‌ها
- ✅ **کاملاً Offline** - هیچ download در حین build
- ✅ **خودکار** - یک اسکریپت برای setup کامل
- ✅ **مستند شده** - راهنماهای جامع فارسی
- ✅ **تست شده** - روی Kubernetes با k3s
- ✅ **سریع** - build بدون تاخیر network
---
**نوشته شده برای پروژه FourSat** 🛰️
deployment/INFRASTRUCTURE-GUIDE.md
-570
View File
@@ -1,570 +0,0 @@
# FourSat Infrastructure Deployment Guide
## 📌 Server Information
### سرور Staging
| Item | Value |
|------|-------|
| Server IP | `194.5.195.53` |
| SSH Access | `root / 87zH26nbqT` |
| Kubernetes | K3s with local-path storage |
| ServiceLB | K3s svclb (built-in) |
| Domains | `*.se.kbs1.ir` |
### سرور Production
| Item | Value |
|------|-------|
| Server IP | `45.149.79.127` |
| SSH Access | `root / 87zH26nbqT` |
| Kubernetes | K3s with local-path storage |
| ServiceLB | K3s svclb (built-in) |
| Domains | `*.kbs1.ir` |
---
## 🗄️ 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:
#### Staging (194.5.195.53):
- `gitea` - Gitea metadata
- `Foursat` - Application database (staging)
- `Hosein` - Application database
#### Production (45.149.79.127):
- `KBS` - Application database (production)
### Connection Strings:
```
# Staging
Server=mssql-svc,1433;Database=Foursat;User Id=sa;Password=87zH26nbqT;TrustServerCertificate=true
# Production (appsettings.Production.json)
Server=mssql-svc;Database=KBS;User Id=sa;Password=YourStrong@Passw0rd;TrustServerCertificate=True
# Production (env override — قدیمی، از بیرون cluster)
# Server=45.149.79.127,31433;Database=KBS;User Id=sa;Password=YourStrong@Passw0rd;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 |
|---------|----------|----------|--------|
| Staging SSH | root | 87zH26nbqT | 194.5.195.53 |
| Production SSH | root | 87zH26nbqT | 45.149.79.127 |
| Staging MSSQL | sa | 87zH26nbqT | mssql-svc:1433 |
| Production MSSQL | sa | YourStrong@Passw0rd | 45.149.79.127:31433 |
| Gitea | admin | (set during install) | 194.5.195.53 |
---
## 📋 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
```
---
---
## 🔧 CMS Ingress & Kestrel Protocol (بروز‌شده: February 2026)
### تنظیمات Kestrel:
| متغیر | مقدار قبلی | مقدار فعلی |
|--------|-----------|------------|
| `Kestrel__EndpointDefaults__Protocols` | `Http2` | `Http1AndHttp2` |
> با `Http1AndHttp2` هم gRPC (HTTP/2) و هم REST/HTTP (HTTP/1.1) روی یک پورت کار می‌کنن.
### تنظیمات Ingress CMS:
| Annotation | مقدار قبلی | مقدار فعلی |
|-----------|-----------|------------|
| `backend-protocol` | `GRPC` | حذف شد |
| `grpc-backend` | `true` | حذف شد |
| `ssl-redirect` | `true` | `true` |
| `cert-manager.io/cluster-issuer` | `letsencrypt-prod` | `letsencrypt-prod` |
> ⚠️ FrontOffice از gRPC-Web استفاده می‌کنه که روی HTTP/1.1 هم کار می‌کنه — نیازی به annotation GRPC نیست.
### NuGet Package (Proto):
| پکیج | نسخه | رجیستری |
|-------|-------|--------|
| `Foursat.CMSMicroservice.Protobuf` | `0.0.179` | Nexus (`foursat-nuget-hosted`) |
### Gitea Secrets (هر ۳ ریپو):
| Secret | CMS | FrontOffice | BackOffice |
|--------|-----|-------------|------------|
| `REGISTRY_PASSWORD` | ✅ | ✅ | ✅ |
| `SERVER_PASSWORD` | ✅ | ✅ | ✅ |
| `KUBECONFIG` | ✅ | ✅ | ✅ |
---
*Last Updated: February 17, 2026*
---
# وضعیت استقرار فعلی
# ✅ 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
-82
View File
@@ -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
-832
View File
@@ -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/SERVER-MIRRORS-CONFIG.md
-258
View File
@@ -1,258 +0,0 @@
# Server Mirrors Configuration
**Staging Server:** 194.5.195.53
**Production Server:** 45.149.79.127
**Date:** 2026-02-17
---
## 1. Docker Registry Mirrors (K3s)
### Staging — `/etc/rancher/k3s/registries.yaml` (194.5.195.53)
### ترتیب 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
```
### Production — `/etc/rancher/k3s/registries.yaml` (45.149.79.127)
Production server از staging registry ها pull می‌کنه:
```yaml
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"
"194.5.195.53:30080":
endpoint:
- "http://194.5.195.53:30080"
"git.foursat.afrino.co":
endpoint:
- "https://git.foursat.afrino.co"
"git.se.kbs1.ir":
endpoint:
- "https://git.se.kbs1.ir"
configs:
"194.5.195.53:32082":
auth:
username: admin
password: 87zH26nbqT
"194.5.195.53:30080":
auth:
username: admin
password: 87zH26nbqT
"git.foursat.afrino.co":
auth:
username: admin
password: 87zH26nbqT
tls:
insecure_skip_verify: true
"git.se.kbs1.ir":
auth:
username: admin
password: 87zH26nbqT
tls:
insecure_skip_verify: true
```
> ⚠️ Production از `194.5.195.53:30080` (Gitea container registry) برای pull ایمیج‌های CI/CD استفاده می‌کنه.
---
## 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/MOVED-TO-TOTALDOC.md
-1
View File
@@ -1 +0,0 @@
Docs moved to /totalDoc — see totalDoc/INDEX.md
docs/analyze-backoffice-ui.sh
-49
View File
@@ -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
-65
View File
@@ -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
-162
View File
@@ -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"
frontoffice/CHANGELOG.md
-311
View File
@@ -1,311 +0,0 @@
# 📋 تاریخچه تغییرات FrontOffice — کارا بازار سلامت
> **آخرین بروزرسانی**: اسفند ۱۴۰۴ (فوریه ۲۰۲۶)
> **فریمورک**: Blazor Server + MudBlazor 8.14 + .NET 9
---
## 🔖 نسخه ۲.۷.۰ — اسفند ۱۴۰۴ (February 17, 2026)
### ۱. اجبار تخفیف ۱۰۰٪ و حذف اسلایدر
- **حذف** `MudSlider` و `MudNumericField` از `Checkout.razor` — کاربر دیگه درصد تخفیف انتخاب نمی‌کنه
- **حذف** کامل بخش نمایش موجودی اعتباری
- بکند همیشه حداکثر تخفیف (`MaxDiscountPercent`) رو اعمال می‌کنه
### ۲. رفع متن Badge تخفیف
- **مشکل:** Badge روی محصولات "۱۰۰٪ اعتباری" نشون می‌داد — گمراه‌کننده
- **رفع:** نمایش درصد واقعی محصول (مثلاً "۳۰٪ تخفیف")
- **فایل‌ها:** `Products.razor`, `Cart.razor`, `ProductDetail.razor`
### ۳. نمایش جدول مالیات (VAT) در Checkout
- جمع کل، تخفیف، مبلغ پس از تخفیف، مالیات ۹٪، مبلغ قابل پرداخت
- استفاده از `VatCalculator` برای محاسبه VAT
### ۴. نمایش وضعیت پرداخت در سفارشات
- **فیلد جدید** `payment_status` در proto `discountorder.proto` (v0.0.179)
- **صفحه Orders:** نمایش Chip رنگی بر اساس PaymentStatus (موفق/ناموفق/در انتظار)
- **صفحه OrderDetail:** Alert برای سفارشات ناموفق + دکمه بازگشت + جزئیات وضعیت
- **Helper متدها:** `GetPaymentStatusText()`, `GetPaymentStatusColor()`, `GetDeliveryStatusText()`
### ۵. فیکس مپینگ PaymentStatus و DeliveryStatus
- **مشکل:** Domain enum مقادیر متفاوتی از Proto داشت — مستقیم cast می‌شد
- **رفع:** `MapPaymentStatus()` و `MapDeliveryStatus()` در `DiscountOrderService.cs` (WebApi)
- سفارشات ناموفق حالا `DeliveryStatus=Cancelled` دارن (بجای "در حال پردازش")
### ۶. فیکس Proto به NuGet v0.0.179
- `FrontOffice.Main.csproj`: `PackageReference` به `Foursat.CMSMicroservice.Protobuf` v0.0.179
---
## 🔖 نسخه ۲.۶.۰ — بهمن ۱۴۰۴ (February 16, 2026)
### ۱. درگاه پرداخت زرین‌پال
- **یکپارچه‌سازی ZarinPal** — پرداخت مستقیم بدون PYMS واسط
- صفحه checkout فروشگاه اعتباری: ریدایرکت به ZarinPal → callback → تأیید
- صفحه checkout فروشگاه عادی: همان جریان
- پشتیبانی از sandbox و production
### ۲. جدول PaymentTransaction
- **Entity جدید** `PaymentTransaction` — ذخیره جزئیات سطح درگاه (Authority, CardPan, CardHash, RefId)
- جدا از جدول Transaction اصلی
- Migration: `AddPaymentTransactionTable`
### ۳. فیکس نمایش وضعیت پرداخت
- **مشکل:** سفارشات اعتباری «در انتظار پرداخت» نشان می‌دادند حتی بعد از پرداخت موفق
- **علت:** Mapster نمی‌تونست `PaymentStatus` (enum) رو به `payment_completed` (bool) مپ کنه
- **رفع:** مپینگ دستی در `DiscountOrderService`
### ۴. فیکس DeliveryStatus
- **مشکل:** فروشگاه اعتباری بعد از پرداخت `InTransit` ست می‌کرد
- **رفع:** تغییر به `Pending` — ادمین باید وضعیت پست رو مشخص کنه
### ۵. تغییر به NuGet Package (Docker build fix)
- `ProjectReference` به CMS Protobuf → `PackageReference` (v0.0.178)
- Docker build context فقط `src/` داره → مسیر `../../../CMS` قابل دسترسی نیست
---
## 🔖 نسخه ۲.۵.۰ — بهمن ۱۴۰۴
### ۱. محافظت صفحات نیازمند احراز هویت (Auth Guard)
**فایل‌های تغییریافته:**
- `Shared/MainLayout.razor.cs`
**شرح:**
قبلاً هیچ محافظتی در سطح مسیریابی وجود نداشت — کاربر غیرلاگین می‌توانست مستقیماً به `/profile/*`، `/commission/*`، `/cart` و... دسترسی پیدا کند.
**تغییرات:**
- متد `EnforceAuthGuardAsync()` اضافه شد — در هر تغییر مسیر و اولین بار رندر اجرا می‌شود
- متد `IsProtectedRoute(path)` مسیرهای محافظت‌شده را تشخیص می‌دهد
- کاربر غیرلاگین → ریدایرکت به `/` (صفحه اصلی)
**مسیرهای محافظت‌شده:**
| گروه | مسیرها |
|---|---|
| پروفایل | `/profile/*` |
| کمیسیون | `/commission/*` |
| شبکه | `/network/*` |
| باشگاه | `/club/*` |
| سبد خرید | `/cart`, `/checkout*`, `/orders`, `/order/*`, `/order-tracking/*` |
| پکیج‌ها | `/my-packages` |
| دروازه | `/my-orders`, `/my-cart` |
| فروشگاه اعتباری | `/discount-store/cart`, `/discount-store/checkout`, `/discount-store/orders`, `/discount-store/order/*` |
**مسیرهای عمومی:**
`/`, `/register`, `/about`, `/faq`, `/contact`, `/blog/*`, `/packages`, `/package/*`, `/products`, `/product/*`, `/categories`, `/stores`, `/discount-store`, `/discount-store/product/*`
---
### ۲. استخراج کامپوننت PhoneVerifyForm
**فایل‌های جدید:**
- `Shared/PhoneVerifyForm.razor`
- `Shared/PhoneVerifyForm.razor.cs`
**فایل‌های تغییریافته:**
- `Shared/AuthDialog.razor`
- `Shared/AuthDialog.razor.cs`
**شرح:**
فرم تلفن + تایید OTP + کپچا که قبلاً به‌صورت `RenderFragment` با `__builder` مستقیم در `AuthDialog` نوشته شده بود، به کامپوننت مستقل `PhoneVerifyForm` استخراج شد.
**ساختار قبل:**
```
AuthDialog.razor
└── @code { PhoneOrVerifyContent() => __builder => { ... } } ← RenderFragment پیچیده
```
**ساختار بعد:**
```
AuthDialog.razor
└── <PhoneVerifyForm @ref="_phoneVerifyForm" ... /> ← کامپوننت مستقل
PhoneVerifyForm.razor ← مارکاپ فرم
PhoneVerifyForm.razor.cs ← پارامترها و فرم رف‌ها
```
**پارامترهای PhoneVerifyForm:**
| پارامتر | نوع | توضیح |
|---|---|---|
| `CurrentStep` | `AuthStep` | مرحله فعلی (Phone / Verify) |
| `PhoneRequest` | `CreateNewOtpTokenRequest` | مدل فرم تلفن |
| `VerifyRequest` | `VerifyOtpTokenRequest` | مدل فرم تایید |
| `CaptchaCode` | `string?` | کد کپچا نمایش‌داده‌شده |
| `CaptchaInput` / `CaptchaInputChanged` | `string?` + `EventCallback` | ورودی کپچا (two-way) |
| `OnRefreshCaptcha` | `EventCallback` | رفرش کپچا |
| `IsBusy` | `bool` | وضعیت بارگذاری |
| `ErrorMessage` / `InfoMessage` | `string?` | پیام‌های خطا/اطلاع |
| `PhoneNumber` | `string?` | شماره تایید‌شده |
| `ResendRemaining` | `int` | ثانیه تا ارسال مجدد |
| `OnChangePhone` / `OnResendOtp` | `EventCallback` | اکشن‌های تایید |
**نکته مهم — Two-way binding کپچا:**
فیلد کپچا با `Value` + `ValueChanged` بایند شده (نه `@bind-Value`) تا مقدار تایپ‌شده از فرزند به والد برگردد:
```razor
<MudTextField Value="CaptchaInput"
ValueChanged="@((string v) => CaptchaInputChanged.InvokeAsync(v))" ... />
```
**دسترسی به فرم‌ها از والد:**
```csharp
// AuthDialog.razor.cs
var phoneForm = _phoneVerifyForm?.GetPhoneForm();
var verifyForm = _phoneVerifyForm?.GetVerifyForm();
```
---
### ۳. بهبود لایوت مدال ورود (AuthDialog)
**فایل‌های تغییریافته:**
- `Shared/AuthDialog.razor`
- `Utilities/AuthDialogService.cs`
- `wwwroot/css/site.css`
**مشکلات قبلی:**
- دیالوگ روی موبایل `FullScreen` بود → فضای خالی بزرگ بین فرم و دکمه‌ها
- `TitleContent` و `DialogActions` جدا → گپ عمودی
- ردیف کپچا با `MudStack Row="true"` → آیتم‌ها عمودی رندر می‌شدند
**تغییرات:**
1. **حذف FullScreen**: `AuthDialogService` حالا همیشه `MaxWidth.ExtraSmall, FullWidth=true, CloseButton=true`
2. **ادغام محتوا**: آواتار + عنوان + فرم + دکمه‌ها همه داخل `DialogContent` → بدون `TitleContent` و `DialogActions`
3. **کلاس `auth-dialog-wrapper`**: CSS با `.auth-dialog-wrapper .mud-dialog-title { display: none; }` عنوان پیش‌فرض دیالوگ رو مخفی می‌کنه
4. **ردیف کپچا**: از `MudStack Row` به `div.captcha-row` با CSS flex اختصاصی
5. **حالت Inline**: بدون تغییر ساختاری — فقط از `PhoneVerifyForm` استفاده می‌کنه
**CSS جدید:**
```css
.auth-dialog-wrapper .mud-dialog-title { display: none; }
.auth-dialog-wrapper .mud-dialog-content { padding-bottom: 24px !important; }
.auth-dialog-content { max-width: 400px; margin: 0 auto; }
.captcha-row { display: flex; align-items: center; gap: 10px; }
.captcha-row > .mud-input-control { flex: 1 1 0; min-width: 0; }
.captcha-row > .mud-paper { flex: 0 0 auto; }
.captcha-row > .mud-button-root { flex: 0 0 auto; }
```
---
### ۴. صفحه لندینگ — حذف /pricing و اضافه بنر بلاگ
**فایل‌های تغییریافته:**
- `Pages/Index.razor`
- `wwwroot/css/site.css`
**تغییرات:**
1. دکمه هیرو «مشاهده پکیج‌ها» → **«آخرین اخبار»** با لینک `/blog`
2. **بنر جدیدترین مطلب** بین هیرو و «سه گام تا شروع» اضافه شد
- تصویر بندانگشتی + عنوان + خلاصه + آیکون شیشه‌ای
- هاور: `translateY(-2px)` + سایه بزرگ‌تر
**CSS جدید:**
```css
.landing-blog-banner { border: 1px solid var(--mud-palette-divider); transition: ... }
.landing-blog-banner:hover { box-shadow: var(--mud-elevation-4); transform: translateY(-2px); }
.landing-blog-thumb { width: 80px; height: 80px; border-radius: 12px; }
.landing-blog-title { -webkit-line-clamp: 1; font-weight: 600; }
.landing-blog-summary { -webkit-line-clamp: 1; }
```
---
### ۵. افزایش ارتفاع تکست‌باکس‌ها (Global)
**فایل تغییریافته:**
- `wwwroot/css/site.css`
**قبل:** `padding: 10px 14px`
**بعد:** `padding: 14px 14px` + `font-size: 1rem`
```css
.mud-input-outlined .mud-input-slot {
padding: 14px 14px !important;
font-size: 1rem;
}
```
تمام فیلدهای Outlined در کل اپلیکیشن بزرگ‌تر شدند.
---
### ۶. اصلاح RTL فیلدهای ورودی
**فایل تغییریافته:**
- `wwwroot/css/site.css`
**مشکل:** فیلدهای `type="tel"` به‌صورت پیش‌فرض مرورگر `direction: ltr` می‌گیرن — لیبل سمت راست ولی placeholder/cursor سمت چپ.
**اصلاح:**
```css
.mud-input-slot input,
.mud-input-slot textarea {
direction: rtl !important;
text-align: right !important;
}
```
---
### ۷. اصلاح captcha-box CSS
**فایل تغییریافته:**
- `wwwroot/css/site.css`
**قبل:**
```css
.captcha-box {
min-width: 120px; min-height: 56px;
background: linear-gradient(135deg, rgba(123,97,255,.12), rgba(255,140,189,.12));
}
```
**بعد:**
```css
.captcha-box {
min-width: 96px; min-height: 48px;
border-radius: var(--mud-default-borderradius);
background: rgba(99,102,241,.08);
border: 1px solid var(--mud-palette-divider);
}
```
---
## 📁 نقشه فایل‌ها
```
Shared/
├── AuthDialog.razor ← بازنویسی (کامپوننت PhoneVerifyForm جایگزین RenderFragment)
├── AuthDialog.razor.cs ← بروزرسانی (استفاده از _phoneVerifyForm)
├── PhoneVerifyForm.razor ← ✨ جدید (فرم تلفن + تایید + کپچا)
├── PhoneVerifyForm.razor.cs ← ✨ جدید (پارامترها و فرم رف‌ها)
├── MainLayout.razor.cs ← Auth Guard اضافه شد
Pages/
├── Index.razor ← /pricing → /blog + بنر بلاگ
Utilities/
├── AuthDialogService.cs ← حذف FullScreen، ثابت‌سازی سایز
wwwroot/css/
├── site.css ← captcha-row, auth-dialog, RTL fix, input height
```
---
## 🔍 وضعیت بیلد
| تاریخ | خطا | هشدار | توضیح |
|---|---|---|---|
| بهمن ۱۴۰۴ | **۰** | ۱۰۵ | MUD0002 warnings (بی‌خطر — مربوط به MudBlazor analyzer) |
frontoffice/UI-UNIFICATION-PLAN.md
-542
View File
@@ -1,542 +0,0 @@
# 🎨 پلن جامع یکپارچه‌سازی UI/UX — کارا بازار سلامت
> **تاریخ**: بهمن ۱۴۰۴
> **وضعیت**: ✅ **تمام ۶ فاز + فاز ۷ (ناوبری و امنیت) تکمیل شد**
> **هدف**: یکپارچه‌سازی طراحی FrontOffice با ۲۰٪ تغییر UX و ۵۰٪ تغییر UI
> **فریمورک**: Blazor Server + MudBlazor 8.14
> **📋 تاریخچه تغییرات جزئی**: [CHANGELOG.md](CHANGELOG.md)
---
## 📊 خلاصه اجرایی
| شاخص | وضعیت قبل | وضعیت بعد |
|---|---|---|
| **صفحات کل** | ۴۱ صفحه + ۶ کامپوننت مشترک | ۴۱ صفحه + ۸ کامپوننت مشترک |
| **الگوی PageHeader** | ۱۹ صفحه از ۴۱ | ۳۲+ صفحه ✅ |
| **Inline Style سنگین** | ۱۱ صفحه 🔴 | ≤۲ صفحه (فقط gradient‌های تزئینی) ✅ |
| **Loading State** | ۲ الگوی متفاوت (Circular vs Linear) | `<LoadingState>` واحد ✅ |
| **Empty State** | ۴+ الگوی متناقض | `<EmptyState>` واحد ✅ |
| **Container Spacing** | ۶ الگوی متناقض | `py-6` استاندارد ✅ |
| **رنگ‌بندی** | رنگ‌های hardcoded در ۸+ صفحه | CSS Variable ✅ |
| **تم پالت** | Primary `#0380C0` (آبی ساده) | Indigo `#6366f1` + Full PaletteDark ✅ |
| **Elevation** | مخلوط ۲/۳/۴ | استاندارد ۰–۲ ✅ |
| **Build** | ۰ خطا | ۰ خطا ✅ |
### فازها
| فاز | عنوان | وضعیت |
|---|---|---|
| ۱ | زیرساخت دیزاین سیستم | ✅ تکمیل |
| ۲ | صفحات پروفایل | ✅ تکمیل |
| ۳ | صفحات تخصصی | ✅ تکمیل |
| ۴ | بهبود بصری فروشگاه | ✅ تکمیل |
| ۵ | صفحات عمومی | ✅ تکمیل |
| ۶ | پالیش و تست | ✅ تکمیل |
| ۷ | ناوبری، امنیت و بازسازی کامپوننت‌ها | ✅ تکمیل |
---
## 🔍 بخش ۱: تحلیل ضعف‌های جاری
### ۱.۱ ناسازگاری‌های ساختاری (Structural)
#### ❌ ۱.۱.۱ — PageHeader دوگانه
**مشکل**: نیمی از صفحات از `<PageHeader>` استفاده می‌کنند، نیم دیگر header دستی دارند.
| از `<PageHeader>` استفاده می‌کنند ✅ | Header دستی دارند ❌ |
|---|---|
| Store/* (۸ صفحه) | Profile/* (۷ صفحه) |
| DiscountStore/* (۶ صفحه) | Club/* (۲ صفحه) |
| Gateway/* (۳ صفحه) | Commission/* (۲ صفحه) |
| Package/* (۲ صفحه) | Network/* (۱ صفحه) |
| PackageDetail, Checkout | Blog/*, Index, About, Contact, FAQ |
**تأثیر**: ظاهر متفاوت دکمه بازگشت، فاصله‌بندی ناهماهنگ
#### ❌ ۱.۱.۲ — Container MaxWidth متناقض
```
MaxWidth.Large → اکثر صفحات
MaxWidth.Medium → Personal, Settings, OrderTracking, Blog/Post, Gateway/*
MaxWidth.Small → ChangePassword
ترکیبی (loading≠content) → OrderDetail, ProductDetail, PackageDetail
```
**تأثیر**: برخی صفحات پهن‌تر از حد نیاز هستند (مثلاً فرم‌های ساده با Large)
#### ❌ ۱.۱.۳ — Container Padding متناقض
```
py-6 → اکثریت (استاندارد)
py-8 → Package/Packages, Package/MyPackages
pa-2 pa-md-6 → Store/Products, DiscountStore/Products
py-6 py-md-10 → Gateway/*
py-4 py-md-6 → DiscountStore/ProductDetail
py-16 سکشنی → Index, About, Contact, FAQ
```
**قاعده پیشنهادی**: `py-6` برای صفحات داخلی، section-based برای صفحات عمومی
---
### ۱.۲ ناسازگاری‌های بصری (Visual)
#### ❌ ۱.۲.۱ — Inline Style سنگین (۱۱ صفحه)
| صفحه | نمونه مشکل‌دار |
|---|---|
| **Index.razor** | `Style="color:#fff; font-size:clamp(1.6rem,4.5vw,2.4rem);"` |
| **Profile/Index** | `Style="background:rgba(99,102,241,.12);"` |
| **Store/ProductDetail** | `style="width:100%;height:360px;background-image:url(...);"` |
| **PackageDetail** | `Style="background: radial-gradient(600px 280px..."` |
| **Checkout** | `Style="background: radial-gradient(..."` + `Elevation="4"` |
| **Blog/Index** | `Style="color:#fff; font-weight:700;"`, `Style="font-size:3.5rem;"` |
| **Blog/Post** | `Style="width:100%; height:100%;"`, `Style="font-size:4rem;"` |
| **About** | `Style="background: radial-gradient(...);"` |
| **WeeklyBalance** | `Style="background: linear-gradient(135deg, #e8f5e9..."` |
| **Gateway/**** | `Style="background:rgba(16,185,129,.12)..."`, `Style="color:#10b981;"` |
| **DiscountStore/ProductDetail** | `Style="background:rgba(16,185,129,.06)..."` |
#### ❌ ۱.۲.۲ — رنگ‌های Hardcoded
| رنگ | استفاده | باید باشد |
|---|---|---|
| `#10b981` | Gateway (سبز فروشگاه) | `var(--ds-color-store)` |
| `#ef4444` | Gateway (قرمز اعتباری) | `var(--ds-color-discount)` |
| `#6366f1`, `#818cf8`, `#a78bfa` | Hero/Banner gradients | `var(--ds-gradient-primary)` |
| `rgba(99,102,241,.12)` | Dashboard backgrounds | `var(--ds-primary-soft)` |
| `rgba(16,185,129,.06)` | Discount product highlights | `var(--ds-success-soft)` |
| `#e8f5e9`, `#c8e6c9` | WeeklyBalance stat cards | `var(--ds-success-gradient)` |
#### ❌ ۱.۲.۳ — Elevation ناهماهنگ
```
Elevation="0" → Blog cards (با border)
Elevation="1" → برخی صفحات
Elevation="2" → اکثر صفحات (استاندارد)
Elevation="3" → WeeklyBalance stat cards
Elevation="4" → Checkout.razor
```
**قاعده پیشنهادی**: `Elevation="0"` با `border` = کارت‌های اطلاعاتی، `Elevation="2"` = default
#### ❌ ۱.۲.۴ — Paper Rounding ناهماهنگ
```
rounded-lg (16px) → اکثریت
rounded-xl (20px) → Index, Profile/Index, Gateway, DiscountStore/ProductDetail
بدون class → design system !important → 12px
```
---
### ۱.۳ ناسازگاری‌های UX (تجربه کاربری)
#### ❌ ۱.۳.۱ — Loading State دوگانه
```
MudProgressCircular → Store/*, DiscountStore/*, Package/*, About, Blog, Addresses
MudProgressLinear → Club/*, Commission/*, Network/*, RegisterWizard
```
**مشکل**: کاربر دو تجربه مختلف «در حال بارگذاری» می‌بیند
#### ❌ ۱.۳.۲ — Empty State ناهماهنگ
```
MudAlert Severity.Info → Store/Orders, Categories, DiscountStore/Orders
Icon + Text + Button → Addresses, Package/MyPackages, PackageDetail
MudAlert Severity.Warning → WithdrawalRequests
Custom dashed-border paper → Blog/Index
```
#### ❌ ۱.۳.۳ — Routing Directive ناهماهنگ
```
@attribute [Route(RouteConstants...)] → ۳۹ صفحه ✅
@page "/categories" → Categories.razor ❌
@page "/blog/{Slug}" → Blog/Post.razor ❌
```
#### ❌ ۱.۳.۴ — PackageDetail Loading/Error بدون Container
Loading و Error state در `PackageDetail.razor` بدون `MudContainer` رندر می‌شوند → محتوا تمام‌عرض نمایش می‌یابد.
#### ❌ ۱.۳.۵ — تم فعلی کم‌رنگ
```csharp
// CustomMudTheme.cs فعلی
Primary = "#0380C0" // آبی ساده
// بدون Secondary، Tertiary، Info، Warning تعریف‌شده
// بدون PaletteDark
// بدون LayoutProperties
```
**مشکلات**:
- فقط Primary تعریف شده، بقیه رنگ‌ها default MudBlazor
- Dark mode بدون palette اختصاصی
- بدون `DefaultBorderRadius`، `AppbarHeight` و غیره
- تناقض بین Primary `#0380C0` و gradient‌های CSS با `#6366f1`
---
## 🎯 بخش ۲: معماری دیزاین سیستم هدف
### ۲.۱ سلسله‌مراتب صفحات
```
┌─────────────────────────────────────────────┐
│ MainLayout │
│ ├─ AppBar (fixed, transparent) │
│ ├─ MudMainContent │
│ │ ├─ [Public Pages] → Section-based │
│ │ │ (Index, About, Contact, FAQ, Blog) │
│ │ └─ [Internal Pages] → Container-based │
│ │ ├─ <PageHeader/> │
│ │ ├─ Content (MudStack/MudGrid) │
│ │ └─ </MudContainer> │
│ ├─ Footer (hidden on mobile) │
│ └─ BottomNav (mobile only) │
└─────────────────────────────────────────────┘
```
### ۲.۲ قواعد واحد (Single Source of Truth)
| قاعده | مقدار |
|---|---|
| **Container MaxWidth** | `Large` = لیست/گرید, `Medium` = فرم/جزئیات, `Small` = تک‌فرم ساده |
| **Container Spacing** | `py-6` صفحات داخلی, section-based صفحات عمومی |
| **Paper Elevation** | `0` با border = کارت اطلاعاتی, `2` = default |
| **Paper Rounding** | `rounded-lg` = default, `rounded-xl` = hero/banner |
| **Loading State** | `<LoadingState/>` component واحد |
| **Empty State** | `<EmptyState/>` component واحد |
| **Page Header** | `<PageHeader/>` در تمام صفحات داخلی |
| **Content Wrapper** | `MudStack Spacing="3"` بعد از PageHeader |
### ۲.۳ CSS Variables هدف
```css
:root {
/* ── Brand Colors ── */
--ds-brand-primary: #6366f1; /* Indigo — هویت اصلی */
--ds-brand-secondary: #8b5cf6; /* Purple */
--ds-brand-accent: #a78bfa; /* Light purple */
/* ── Semantic Colors ── */
--ds-color-store: #10b981; /* فروشگاه عادی */
--ds-color-discount: #ef4444; /* فروشگاه اعتباری */
--ds-color-success: #10b981;
--ds-color-warning: #f59e0b;
--ds-color-error: #ef4444;
--ds-color-info: #3b82f6;
/* ── Soft Backgrounds ── */
--ds-primary-soft: rgba(99,102,241,.08);
--ds-success-soft: rgba(16,185,129,.08);
--ds-error-soft: rgba(239,68,68,.08);
--ds-warning-soft: rgba(245,158,11,.08);
/* ── Gradients ── */
--ds-gradient-primary: linear-gradient(135deg, #6366f1 0%, #818cf8 50%, #a78bfa 100%);
--ds-gradient-store: linear-gradient(135deg, #10b981 0%, #34d399 100%);
--ds-gradient-discount: linear-gradient(135deg, #ef4444 0%, #f97316 50%, #f59e0b 100%);
--ds-gradient-success: linear-gradient(135deg, #d1fae5 0%, #a7f3d0 100%);
/* ── Spacing (existing) ── */
--ds-radius-sm: 8px;
--ds-radius-md: 12px;
--ds-radius-lg: 16px;
--ds-radius-xl: 20px;
--ds-transition: 0.2s ease;
--ds-shadow-sm: 0 1px 3px rgba(0,0,0,.06);
--ds-shadow-md: 0 4px 12px rgba(0,0,0,.08);
--ds-shadow-lg: 0 8px 24px rgba(0,0,0,.10);
}
```
---
## 🚀 بخش ۳: فازبندی اجرا
### 🔷 فاز ۱ — زیرساخت دیزاین سیستم (UI ~15%)
> **اولویت**: بالا | **ریسک**: پایین | **حجم**: ۶ فایل
| # | تسک | فایل | نوع تغییر |
|---|---|---|---|
| 1.1 | ارتقاء `CustomMudTheme.cs` — اضافه کردن PaletteDark، LayoutProperties، رنگ‌های Secondary/Tertiary/Info، تغییر Primary به `#6366f1` | `CustomMudTheme.cs` | UI |
| 1.2 | توسعه CSS Variables — اضافه کردن brand colors، semantic colors، soft backgrounds، gradients | `site.css` | UI |
| 1.3 | ساخت `<LoadingState>` component واحد | `Shared/LoadingState.razor` (جدید) | UX |
| 1.4 | ساخت `<EmptyState>` component واحد | `Shared/EmptyState.razor` (جدید) | UX |
| 1.5 | بهبود `<PageHeader>` — اضافه کردن آیکون، subtitle اختیاری | `Shared/PageHeader.razor` | UI |
| 1.6 | اضافه کردن `.page-container` CSS pattern | `site.css` | UI |
---
### 🔷 فاز ۲ — یکپارچه‌سازی صفحات Profile (UI ~10%, UX ~5%)
> **اولویت**: بالا | **ریسک**: پایین | **حجم**: ۹ فایل
| # | تسک | تغییرات |
|---|---|---|
| 2.1 | `Profile/Personal` → جایگزینی header دستی با `<PageHeader>` | UX |
| 2.2 | `Profile/Addresses` → `<PageHeader>` + `<LoadingState>` + `<EmptyState>` | UX |
| 2.3 | `Profile/Wallet` → `<PageHeader>` | UX |
| 2.4 | `Profile/Settings` → `<PageHeader>` | UX |
| 2.5 | `Profile/Tree` → `<PageHeader>` | UX |
| 2.6 | `Profile/WithdrawalRequests` → `<PageHeader>` + `<EmptyState>` | UX |
| 2.7 | `Profile/ChangePassword` → `<PageHeader>` | UX |
| 2.8 | `Profile/Index` (Dashboard) → حذف inline styles، استفاده از CSS Variables | UI |
| 2.9 | `Club/MembershipPage` + `Club/FeaturesPage` → `<PageHeader>` + `<LoadingState>` | UX |
---
### 🔷 فاز ۳ — یکپارچه‌سازی صفحات تخصصی (UI ~5%, UX ~5%)
> **اولویت**: متوسط | **ریسک**: پایین | **حجم**: ۵ فایل
| # | تسک | تغییرات |
|---|---|---|
| 3.1 | `Commission/Dashboard` → `<PageHeader>` + `<LoadingState>` | UX |
| 3.2 | `Commission/WeeklyBalance` → `<PageHeader>` + حذف inline gradient styles | UI + UX |
| 3.3 | `Network/NetworkStatistics` → `<PageHeader>` + `<LoadingState>` | UX |
| 3.4 | `PackageDetail` → wrap loading/error در `MudContainer` | UX bug fix |
| 3.5 | `Checkout` → Elevation=4→2، حذف inline radial-gradient | UI |
---
### 🔷 فاز ۴ — بهبود بصری فروشگاه‌ها (UI ~10%)
> **اولویت**: متوسط | **ریسک**: پایین | **حجم**: ۶ فایل
| # | تسک | تغییرات |
|---|---|---|
| 4.1 | `Store/Products` → حذف inline hero styles، استفاده از CSS class | UI |
| 4.2 | `Store/ProductDetail` → حذف inline image styles، ساخت `.product-image-main` CSS | UI |
| 4.3 | `DiscountStore/ProductDetail` → حذف hardcoded rgba، استفاده از `--ds-success-soft` | UI |
| 4.4 | `Gateway/*` (۳ صفحه) → حذف hardcoded `#10b981`/`#ef4444`، استفاده از `--ds-color-store`/`--ds-color-discount` | UI |
| 4.5 | یکسان‌سازی Elevation → `0` با border یا `2` | UI |
| 4.6 | یکسان‌سازی Container spacing → `py-6` | UI |
---
### 🔷 فاز ۵ — بهبود صفحات عمومی و بلاگ (UI ~10%)
> **اولویت**: پایین | **ریسک**: پایین | **حجم**: ۷ فایل
| # | تسک | تغییرات |
|---|---|---|
| 5.1 | `Index.razor` → حذف inline styles از hero، استفاده از CSS class | UI |
| 5.2 | `About.razor` → حذف inline radial-gradient | UI |
| 5.3 | `Contact.razor` → cleanup minor inline styles | UI |
| 5.4 | `FAQ.razor` → cleanup minor inline styles | UI |
| 5.5 | `Blog/Index` → حذف inline hero styles، استفاده از CSS class | UI |
| 5.6 | `Blog/Post` → حذف inline styles از hero image و typography | UI |
| 5.7 | `RegisterWizard` → بهینه‌سازی wizard-section dark mode | UI |
---
### 🔷 فاز ۶ — Polish نهایی و فرآیندی (UX ~10%)
> **اولویت**: پایین | **ریسک**: بسیار پایین | **حجم**: ۴ فایل + تست
| # | تسک | تغییرات |
|---|---|---|
| 6.1 | Fix routing inconsistency — Categories + Blog/Post | UX |
| 6.2 | MudSnackbar notifications styling | UI |
| 6.3 | Dialog styling consistency (AuthDialog, AddressDialogs) | UI |
| 6.4 | Micro-interactions — button press, card hover, page transition | UI |
| 6.5 | تست کامل Dark Mode در تمام صفحات | UI + QA |
| 6.6 | تست Mobile Responsive در تمام صفحات | UX + QA |
---
## 📈 بخش ۴: جدول تأثیرگذاری
### تأثیر UI (هدف ~۵۰٪ تغییر)
| حوزه | تعداد فایل | درصد تأثیر |
|---|---|---|
| Theme + CSS Variables | ۲ | ۱۵% (تأثیر سراسری) |
| حذف Inline Styles | ۱۱ | ۱۵% |
| یکسان‌سازی Elevation/Rounding | ۲۰+ | ۱۰% |
| بهبود رنگ‌بندی (CSS Variables) | ۸ | ۵% |
| Micro-interactions | سراسری | ۵% |
| **جمع** | | **~۵۰%** |
### تأثیر UX (هدف ~۲۰٪ تغییر)
| حوزه | تعداد فایل | درصد تأثیر |
|---|---|---|
| PageHeader یکپارچه | ۱۲ صفحه | ۸% |
| LoadingState واحد | ۱۵+ صفحه | ۴% |
| EmptyState واحد | ۸+ صفحه | ۳% |
| Container fixes (PackageDetail) | ۲ | ۲% |
| Routing consistency | ۲ | ۱% |
| Flow improvements | ۲ | ۲% |
| **جمع** | | **~۲۰%** |
---
## 🔧 بخش ۵: مشخصات فنی کامپوننت‌های جدید
### ۵.۱ LoadingState Component
```razor
@* Shared/LoadingState.razor *@
<MudStack AlignItems="AlignItems.Center" Class="py-16">
<MudProgressCircular Color="Color.Primary" Indeterminate="true" Size="Size.Large" />
@if (!string.IsNullOrWhiteSpace(Message))
{
<MudText Typo="Typo.body1" Class="mud-text-secondary mt-2">@Message</MudText>
}
</MudStack>
@code {
[Parameter] public string Message { get; set; } = "در حال بارگذاری...";
}
```
### ۵.۲ EmptyState Component
```razor
@* Shared/EmptyState.razor *@
<MudStack AlignItems="AlignItems.Center" Class="py-12" Spacing="3">
<MudIcon Icon="@Icon" Size="Size.Large" Color="Color.Default" Class="mud-text-disabled" />
<MudText Typo="Typo.h6" Class="mud-text-secondary">@Title</MudText>
@if (!string.IsNullOrWhiteSpace(Description))
{
<MudText Typo="Typo.body2" Class="mud-text-secondary" Style="max-width:400px; text-align:center;">
@Description
</MudText>
}
@if (!string.IsNullOrWhiteSpace(ActionText))
{
<MudButton Variant="Variant.Filled" Color="Color.Primary"
Href="@ActionHref" OnClick="@OnAction" Class="mt-2">
@ActionText
</MudButton>
}
</MudStack>
@code {
[Parameter] public string Icon { get; set; } = Icons.Material.Filled.Inbox;
[Parameter] public string Title { get; set; } = "موردی یافت نشد";
[Parameter] public string? Description { get; set; }
[Parameter] public string? ActionText { get; set; }
[Parameter] public string? ActionHref { get; set; }
[Parameter] public EventCallback OnAction { get; set; }
}
```
### ۵.۳ PageHeader ارتقاء‌یافته
```razor
@* Shared/PageHeader.razor — ارتقاء‌یافته *@
<div class="page-header">
<MudStack Spacing="0">
<MudText Typo="Typo.h5">@Title</MudText>
@if (!string.IsNullOrWhiteSpace(Subtitle))
{
<MudText Typo="Typo.body2" Class="mud-text-secondary">@Subtitle</MudText>
}
</MudStack>
@if (!string.IsNullOrWhiteSpace(BackHref))
{
<MudButton Variant="Variant.Text" StartIcon="@Icons.Material.Filled.ArrowBack"
Href="@BackHref">بازگشت</MudButton>
}
else
{
<MudButton Variant="Variant.Text" StartIcon="@Icons.Material.Filled.ArrowBack"
OnClick="GoBack">بازگشت</MudButton>
}
</div>
@code {
[Parameter] public string Title { get; set; } = "";
[Parameter] public string? Subtitle { get; set; }
[Parameter] public string? BackHref { get; set; }
[Inject] private IJSRuntime JS { get; set; } = default!;
private async Task GoBack() => await JS.InvokeVoidAsync("history.back");
}
```
---
## ✅ بخش ۶: چک‌لیست تکمیل هر فاز
### فاز ۱ چک‌لیست:
- [ ] `CustomMudTheme.cs` — Primary→`#6366f1`, PaletteDark اضافه شد
- [ ] `site.css` — CSS Variables جدید (brand, semantic, soft, gradient)
- [ ] `Shared/LoadingState.razor` — ساخته و تست شد
- [ ] `Shared/EmptyState.razor` — ساخته و تست شد
- [ ] `Shared/PageHeader.razor` — Subtitle parameter اضافه شد
- [ ] `.page-container` CSS pattern اضافه شد
- [ ] Build: 0 errors ✅
- [ ] Dark Mode: صحیح ✅
- [ ] Mobile: صحیح ✅
### فاز ۲ چک‌لیست:
- [ ] `Profile/Personal` → `<PageHeader>`
- [ ] `Profile/Addresses` → `<PageHeader>` + `<LoadingState>` + `<EmptyState>`
- [ ] `Profile/Wallet` → `<PageHeader>`
- [ ] `Profile/Settings` → `<PageHeader>`
- [ ] `Profile/Tree` → `<PageHeader>`
- [ ] `Profile/WithdrawalRequests` → `<PageHeader>` + `<EmptyState>`
- [ ] `Profile/ChangePassword` → `<PageHeader>`
- [ ] `Profile/Index` → inline styles → CSS
- [ ] `Club/*` → `<PageHeader>` + `<LoadingState>`
- [ ] Build: 0 errors ✅
### فاز ۳ چک‌لیست:
- [ ] `Commission/*` → `<PageHeader>` + `<LoadingState>`
- [ ] `Network/*` → `<PageHeader>` + `<LoadingState>`
- [ ] `PackageDetail` → MudContainer wrapper برای loading/error
- [ ] `Checkout` → Elevation fix + inline cleanup
- [ ] `WeeklyBalance` → inline gradient → CSS class
- [ ] Build: 0 errors ✅
### فاز ۴ چک‌لیست:
- [ ] `Store/Products` → hero inline → CSS
- [ ] `Store/ProductDetail` → image inline → CSS class
- [ ] `DiscountStore/ProductDetail` → rgba → variable
- [ ] `Gateway/*` → hardcoded → variable
- [ ] Elevation یکسان‌سازی
- [ ] Container spacing یکسان‌سازی
- [ ] Build: 0 errors ✅
### فاز ۵ چک‌لیست:
- [ ] `Index.razor` → hero inline cleanup
- [ ] `About.razor` → radial-gradient cleanup
- [ ] `Blog/Index` + `Blog/Post` → inline cleanup
- [ ] `Contact.razor` + `FAQ.razor` → minor cleanup
- [ ] Build: 0 errors ✅
### فاز ۶ چک‌لیست:
- [ ] Routing fix (Categories, Blog/Post)
- [ ] MudSnackbar styling
- [ ] Dialog consistency
- [ ] Dark mode full test
- [ ] Mobile responsive full test
- [ ] Build: 0 errors ✅
---
## 📋 بخش ۷: خلاصه تغییرات در یک نگاه
```
فایل‌های تغییر‌یافته:
├── CustomMudTheme.cs [فاز ۱] — ارتقاء کامل تم
├── site.css [فاز ۱-۵] — CSS Variables + class‌های جدید
├── Shared/LoadingState.razor [فاز ۱] — جدید
├── Shared/EmptyState.razor [فاز ۱] — جدید
├── Shared/PageHeader.razor [فاز ۱] — بهبود
├── Profile/* (۷ فایل) [فاز ۲] — PageHeader + LoadingState
├── Profile/Index.razor [فاز ۲] — حذف inline styles
├── Club/* (۲ فایل) [فاز ۲] — PageHeader + LoadingState
├── Commission/* (۲ فایل) [فاز ۳] — PageHeader + LoadingState + cleanup
├── Network/* (۱ فایل) [فاز ۳] — PageHeader + LoadingState
├── PackageDetail.razor [فاز ۳] — Container fix
├── Checkout.razor [فاز ۳] — Elevation + cleanup
├── Store/* (۲ فایل) [فاز ۴] — inline → CSS
├── DiscountStore/ProductDetail [فاز ۴] — rgba → variable
├── Gateway/* (۳ فایل) [فاز ۴] — hardcoded → variable
├── Index.razor [فاز ۵] — hero cleanup
├── About.razor [فاز ۵] — gradient cleanup
├── Blog/* (۲ فایل) [فاز ۵] — inline cleanup
├── Contact.razor + FAQ.razor [فاز ۵] — minor cleanup
└── Categories + Blog/Post [فاز ۶] — routing fix
```
**مجموع فایل‌های تأثیرپذیر**: ~۳۵ فایل
**فایل‌های جدید**: ۲ (LoadingState, EmptyState)
**میزان تغییر UI**: ~۵۰٪
**میزان تغییر UX**: ~۲۰٪
**ریسک شکست**: پایین (تغییرات تدریجی، build verification در هر فاز)
migration/BACKOFFICE-BFF-MIGRATION.md
-268
View File
@@ -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
-483
View File
@@ -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/DATAMIGRATION-README.md
-425
View File
@@ -1,425 +0,0 @@
# FourSat Data Migration Tool
## نگاه کلی
این ابزار برای مهاجرت داده‌های دیتابیس از ساختار قدیمی (Production) به ساختار جدید (Stage) طراحی شده است.
**ویژگی‌ها:**
- ✅ Queue-based processing با retry logic
- ✅ Error handling - آیتم‌های ناموفق به صف retry می‌روند
- ✅ Logging کامل با Serilog (Console + File)
- ✅ قابلیت توقف/ادامه (Pause/Resume)
- ✅ Table name mapping (مثل Categorys → Categories)
- ✅ Batch processing برای کارایی بهتر
- ✅ Retry با Exponential Backoff
- ✅ Progress tracking
---
## ساختار پروژه
```
FourSat.DataMigration/
├── Program.cs # Entry point با Hosting
├── appsettings.json # تنظیمات (ConnectionStrings, Mappings)
├── Models/
│ ├── MigrationSettings.cs # تنظیمات migration
│ ├── TableMapping.cs # نگاشت table ها
│ └── MigrationQueueItem.cs # آیتم صف
├── Services/
│ ├── IMigrationService.cs # Interface
│ ├── MigrationService.cs # سرویس اصلی migration
│ ├── QueueManager.cs # مدیریت صف و retry
│ └── TableMigrator.cs # مهاجرت یک table
└── Logs/ # لاگ فایل‌ها (auto-created)
```
---
## تنظیمات (`appsettings.json`)
### 1. ConnectionStrings
```json
{
"SourceDatabase": "Server=185.252.31.42,2019;Database=Foursat;...",
"TargetDatabase": "Server=194.5.195.53,31433;Database=Foursat;..."
}
```
**⚠️ توجه**: حتماً Username و Password را وارد کنید!
### 2. MigrationSettings
- **BatchSize**: تعداد رکوردهای هر batch (پیشنهاد: 1000)
- **MaxRetryAttempts**: حداکثر تلاش مجدد (5 بار)
- **RetryDelaySeconds**: تأخیر بین retry ها (5 ثانیه)
- **MaxConcurrentTables**: تعداد table های همزمان (3 عدد)
- **EnableDetailedLogging**: لاگ جزئیات (true)
- **SkipEmptyTables**: نادیده گرفتن table های خالی (true)
### 3. TableMappings
نگاشت نام table قدیمی به جدید (33 جدول):
```json
{
"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"
}
```
**چگونه کار می‌کند:**
- اگر table در mapping باشد → از نام جدید استفاده می‌کند
- اگر در mapping نباشد → همان نام را استفاده می‌کند
- اگر table در target نباشد → Log می‌کند و skip می‌کند
---
## نحوه اجرا
### 1. ویرایش appsettings.json
```bash
cd /home/masoud/Apps/project/FourSat/DataMigration/FourSat.DataMigration
nano appsettings.json
```
**تغییرات لازم:**
- ✅ `SourceDatabase`: Username و Password را وارد کنید
- ✅ `TargetDatabase`: Username و Password را وارد کنید
- ✅ `TableMappings`: اگر mapping جدید دارید اضافه کنید
### 2. Build پروژه
```bash
dotnet build
```
### 3. اجرای Migration
```bash
dotnet run
```
### 4. مشاهده Logs
```bash
# Real-time console output
# یا
tail -f Logs/migration-20251206.txt
```
---
## جریان کار (Workflow)
```
1. خواندن تنظیمات از appsettings.json
↓
2. اتصال به Source و Target databases
↓
3. کشف تمام table های Source (CMS schema)
↓
4. برای هر table:
├─ بررسی mapping (قدیمی → جدید)
├─ تعداد رکوردها را بخواند
├─ اگر خالی → skip (با log)
├─ اگر پر → افزودن به Queue
└─ Log: "Table X → Y: N records"
↓
5. پردازش Queue:
├─ تا MaxConcurrentTables همزمان
├─ هر table در batch ها (BatchSize)
├─ اگر error → Retry (MaxRetryAttempts)
├─ اگر بعد از retry fail → Log + Skip
└─ پیشرفت را نمایش بده
↓
6. گزارش نهایی:
├─ تعداد table های موفق
├─ تعداد table های ناموفق
├─ جمع رکوردهای migrate شده
└─ مدت زمان کل
```
---
## Retry Logic
### استراتژی:
1. **اولین تلاش**: بلافاصله
2. **تلاش 2**: بعد از 5 ثانیه
3. **تلاش 3**: بعد از 10 ثانیه (exponential backoff)
4. **تلاش 4**: بعد از 20 ثانیه
5. **تلاش 5**: بعد از 40 ثانیه
**اگر همه fail شوند:**
- Log error با جزئیات کامل
- Table را از queue حذف کن
- به table بعدی برو (متوقف نمی‌شود!)
---
## Error Handling
### خطاهای رایج:
| خطا | دلیل | راه حل |
|-----|------|--------|
| **Login failed** | Username/Password اشتباه | appsettings.json را بررسی کنید |
| **Table not found** | Table در target وجود ندارد | Migration بزنید یا از mapping صحیح استفاده کنید |
| **Timeout** | Network کند یا batch زیاد | BatchSize را کاهش دهید |
| **Deadlock** | همزمانی بالا | MaxConcurrentTables را کم کنید |
| **Permission denied** | User دسترسی ندارد | سطح دسترسی SQL را بررسی کنید |
---
## مثال خروجی
```
[12:30:15 INF] Starting migration...
[12:30:16 INF] Source: 30 tables found
[12:30:16 INF] Mapping: Categorys → Categories
[12:30:16 INF] Mapping: Productss → Products
[12:30:17 INF] Queue: 28 tables added (2 empty skipped)
[12:30:18 INF] Migrating: Categories (6 records)
[12:30:18 INF] Success: Categories (6/6) - 100%
[12:30:19 INF] Migrating: Products (150 records)
[12:30:21 INF] Success: Products (150/150) - 100%
...
[12:35:42 INF] === Migration Complete ===
[12:35:42 INF] Success: 28 tables, 45,320 records
[12:35:42 INF] Failed: 0 tables
[12:35:42 INF] Duration: 5 minutes 27 seconds
```
---
## فایل‌های باقی مانده برای پیاده‌سازی
### Models/MigrationSettings.cs
```csharp
public class MigrationSettings
{
public int BatchSize { get; set; } = 1000;
public int MaxRetryAttempts { get; set; } = 5;
public int RetryDelaySeconds { get; set; } = 5;
public int MaxConcurrentTables { get; set; } = 3;
public bool EnableDetailedLogging { get; set; } = true;
public bool SkipEmptyTables { get; set; } = true;
}
```
### Models/TableMapping.cs
```csharp
public class TableMapping
{
public string SourceTable { get; set; } = string.Empty;
public string TargetTable { get; set; } = string.Empty;
public long TotalRecords { get; set; }
public long MigratedRecords { get; set; }
public MigrationStatus Status { get; set; }
}
public enum MigrationStatus
{
Pending,
InProgress,
Completed,
Failed,
Retrying
}
```
### Models/MigrationQueueItem.cs
```csharp
public class MigrationQueueItem
{
public string SourceTable { get; set; } = string.Empty;
public string TargetTable { get; set; } = string.Empty;
public long TotalRecords { get; set; }
public int RetryCount { get; set; }
public DateTime? LastAttempt { get; set; }
public string? LastError { get; set; }
}
```
### Services/IMigrationService.cs
```csharp
public interface IMigrationService
{
Task RunAsync(CancellationToken cancellationToken);
}
```
### Services/MigrationService.cs
```csharp
public class MigrationService : IMigrationService
{
// کلاس اصلی که:
// 1. لیست table ها را از source می‌خواند
// 2. QueueManager را راه‌اندازی می‌کند
// 3. TableMigrator ها را همزمان اجرا می‌کند
// 4. Progress و statistics را نمایش می‌دهد
}
```
### Program.cs
```csharp
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Serilog;
var host = Host.CreateDefaultBuilder(args)
.UseSerilog((context, config) => config.ReadFrom.Configuration(context.Configuration))
.ConfigureServices((context, services) =>
{
services.Configure<MigrationSettings>(context.Configuration.GetSection("MigrationSettings"));
services.AddSingleton<IMigrationService, MigrationService>();
// Register other services...
})
.Build();
await host.Services.GetRequiredService<IMigrationService>().RunAsync(CancellationToken.None);
```
---
## توقف و ادامه (Pause/Resume)
**نحوه توقف:**
```bash
Ctrl+C # Graceful shutdown
```
**نحوه ادامه:**
- هیچ state ذخیره نمی‌شود (stateless)
- دوباره `dotnet run` کنید
- چون `INSERT` استفاده می‌شود، رکوردهای duplicate ایجاد می‌شود
- **پیشنهاد**: قبل از اجرای مجدد، Target را TRUNCATE کنید
**برای Production:**
- از `MERGE` یا `INSERT IF NOT EXISTS` استفاده کنید
- یک جدول `MigrationState` برای ذخیره پیشرفت ایجاد کنید
---
## نکات امنیتی
1. **Credentials**:
- ❌ هرگز appsettings.json را commit نکنید
- ✅ از Environment Variables یا User Secrets استفاده کنید
2. **Network**:
- ✅ از VPN برای اتصال به Production استفاده کنید
- ✅ IP شما در Firewall مجاز باشد
3. **Permissions**:
- Source: فقط `SELECT` کافی است
- Target: نیاز به `INSERT` دارد
---
## بهینه‌سازی عملکرد
### برای دیتابیس کوچک (<100K records):
```json
{
"BatchSize": 5000,
"MaxConcurrentTables": 5
}
```
### برای دیتابیس متوسط (100K-1M):
```json
{
"BatchSize": 2000,
"MaxConcurrentTables": 3
}
```
### برای دیتابیس بزرگ (>1M):
```json
{
"BatchSize": 500,
"MaxConcurrentTables": 2
}
```
---
## حذف یا خاموش کردن
### خاموش کردن موقت:
```bash
# فقط اجرا نکنید!
```
### حذف کامل:
```bash
cd /home/masoud/Apps/project/FourSat
rm -rf DataMigration/
```
---
## لایسنس
این ابزار موقت برای استفاده داخلی FourSat است. بعد از sync کامل، حذف شود.
---
## سوالات متداول (FAQ)
**Q: چرا بعضی table ها migrate نمی‌شوند؟**
A: چک کنید:
1. Table در Target وجود دارد؟
2. Schema match می‌کند؟
3. Mapping صحیح است؟
**Q: چگونه فقط یک table خاص را migrate کنم؟**
A: در کد `MigrationService.cs`، فیلتر اضافه کنید:
```csharp
var tablesToMigrate = allTables.Where(t => t == "Users").ToList();
```
**Q: چگونه از duplicate جلوگیری کنم؟**
A: قبل از اجرا، Target را خالی کنید:
```sql
TRUNCATE TABLE [CMS].[Categories];
TRUNCATE TABLE [CMS].[Products];
-- ...
```
**Q: آیا می‌توانم بدون توقف سرور اجرا کنم؟**
A: بله، فقط `SELECT` روی Source اجرا می‌شود (ReadOnly).
---
**آخرین بروزرسانی**: December 6, 2025
**نسخه**: 1.0
**وضعیت**: آماده برای پیاده‌سازی نهایی
migration/FRONTOFFICE-TO-CMS-MIGRATION.md
-1312
View File
File diff suppressed because it is too large Load Diff
migration/GATEWAY-REMOVAL-MIGRATION-PLAN.md
-350
View File
@@ -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
-431
View File
@@ -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
migration/customer-facing-capabilities-codex.md
-5299
View File
File diff suppressed because it is too large Load Diff
overview/OVERVIEW-01-FLOWCHARTS.md
+280
View File
@@ -0,0 +1,280 @@
# 📊 فلوچارت‌ها و دیاگرام‌های کلان
> **دید بالا (Big Picture): فلوی کاربر، مالی و داده**
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
---
## ۱. فلوی کلان کاربر (User Journey)
```
┌─────────────────────────────────────────────────────────────────────────┐
│ FourSat — User Journey │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ [ورود به سایت] │
│ │ │
│ ▼ │
│ ◆ آیا ثبت‌نام کرده؟ ◆──── خیر ───→ [Landing Page] │
│ │ │ │
│ بله [ثبت‌نام] │
│ │ موبایل + OTP │
│ ▼ │ │
│ [Login + JWT] ▼ │
│ │ [پروفایل] │
│ ▼ │ │
│ ◆ عضو باشگاه؟ ◆ ▼ │
│ │ │ ┌───────────────┐ │
│ بله خیر │ Regular Store │ │
│ │ │ │ خرید عادی │ │
│ │ └──────────────→│ IPG پرداخت │ │
│ │ └───────────────┘ │
│ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Club Member Dashboard │ │
│ ├──────────┬──────────┬──────────┬─────────────┤ │
│ │ فروشگاه │ درخت شبکه │ کمیسیون │ Chatika AI │ │
│ │ تخفیفی │ باینری │ هفتگی │ │ │
│ │ (30%↓) │ │ │ │ │
│ └──────────┴──────────┴──────────┴─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## ۲. فلوی مالی (Financial Flow)
```
┌─────────────────────────────────────────────────────────────────────────┐
│ FourSat — Financial Flow │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ═══════════════════ ورودی پول ═══════════════════ │
│ │
│ [ZarinPal IPG] ──→ ┐ │
│ [Daya Loan] ──→ ├──→ [PYMS Service] ──→ [DB Transaction] │
│ [Manual Pay] ──→ ┘ │ │
│ ▼ │
│ ═══════════ توزیع به ۳ کیف‌پول ═══════════ │
│ │
│ ┌────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │
│ │ 💰 Balance │ │ 🌐 NetworkBal │ │ 🏷️ DiscountBal │ │
│ │ (نقدی) │ │ (شبکه‌ای) │ │ (تخفیفی) │ │
│ │ │ │ │ │ │ │
│ │ • خرید فروشگاه │ │ • محاسبه │ │ • فروشگاه تخفیفی │ │
│ │ • هزینه فعالسازی │ │ کمیسیون │ │ • سهم 30% از │ │
│ │ (25M) │ │ • سقف 300/هفته │ │ قیمت محصول │ │
│ └───────┬────────┘ └────────┬────────┘ └────────┬─────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ═══════════════════ خروجی پول ═══════════════════ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Weekly Commission Pool │ │
│ │ │ │
│ │ Source: هر فعالسازی → 25.2M واریز │ │
│ │ Calculate: sp_CalculateWeeklyBalances │ │
│ │ Distribute: sp_CalculateWeeklyCommissionPool │ │
│ │ Formula: UserShare = UserBalance / TotalBalance │ │
│ │ Cap: MAX 300 per leg per week │ │
│ │ Carryover: به هفته بعد (max 300, else flush) │ │
│ │ │ │
│ │ ┌─ Member A: Balance=150 → Share=150/600 → 25% ─┐ │ │
│ │ │ Member B: Balance=200 → Share=200/600 → 33% │ │ │
│ │ │ Member C: Balance=250 → Share=250/600 → 42% │ │ │
│ │ └─ Total: 600 ─┘ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## ۳. فلوی داده (Data Flow)
```
┌─────────────────────────────────────────────────────────────────────────┐
│ FourSat — Data Flow │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ [Browser/Client] │
│ │ │
│ │ HTTPS │
│ ▼ │
│ [nginx / K8s Ingress] │
│ │ │
│ ├──→ / ──────────→ [FrontOffice :5003] (Blazor Server) │
│ │ │ │
│ ├──→ /admin ─────→ [BackOffice :5002] (Blazor WASM) │
│ │ │ │
│ └──→ /hangfire ──→ [CMS :5001] (Dashboard) │
│ │ │
│ ┌─────────────────────────────┘ │
│ │ gRPC (Protobuf v3, HTTP/2) │
│ ▼ │
│ [CMS Microservice :5001] │
│ │ │
│ ├──→ [MediatR] ──→ Commands/Queries ──→ Handlers │
│ │ │ │
│ ├──→ [Hangfire] ──→ Background Jobs │ │
│ │ • DayaLoan (15min) │ │
│ │ • Commission (weekly) │ │
│ │ • Chatika (5min) │ │
│ │ • InventorySync (hourly) │ │
│ │ │ │
│ └──→ [External Services] │ │
│ • ZarinPal API │ │
│ • Kavenegar API ▼ │
│ • DayaLoan API [EF Core 9] │
│ • Chatika API │ │
│ ▼ │
│ [SQL Server 2022] │
│ Schema: [CMS] │
│ ~15 main tables │
│ + 3 Stored Procs │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## ۴. درخت باینری شبکه (Network Tree)
```
┌─────────┐
│ Root │
│ (Admin) │
└────┬────┘
┌─────────┴─────────┐
┌────▼────┐ ┌────▼────┐
│ User A │ │ User B │
│ L=120 │ │ L=0 │
│ R=80 │ │ R=150 │
└────┬────┘ └────┬────┘
┌───────┴───────┐ ┌──────┴──────┐
┌────▼──┐ ┌────▼──┐ ┌──▼───┐ ┌───▼──┐
│User C │ │User D │ │User E│ │User F│
│Active │ │Active │ │Pend. │ │Active│
└───────┘ └───────┘ └──────┘ └──────┘
Legend:
L = Left leg sales this week
R = Right leg sales this week
Active = فعال (contract signed)
Pend. = در انتظار فعالسازی
Max depth = 15 levels
```
---
## ۵. فلوی خرید — Regular vs Discount Store
```
┌────────────────────────────────┬──────────────────────────────────┐
│ Regular Store │ Discount Store │
├────────────────────────────────┼──────────────────────────────────┤
│ │ │
│ [مشاهده محصولات] │ [مشاهده محصولات] ← فقط باشگاه │
│ │ │ │ │
│ ▼ │ ▼ │
│ [Lazy Load — 12 per page] │ [Lazy Load — 12 per page] │
│ │ │ │ │
│ ▼ │ ▼ │
│ [افزودن به سبد] │ [افزودن به سبد] │
│ │ │ │ │
│ ▼ │ ▼ │
│ [بررسی موجودی] │ [بررسی موجودی] │
│ │ │ [بررسی DiscountBalance] │
│ ▼ │ │ │
│ [Checkout] │ ▼ │
│ │ │ [محاسبه سهم تخفیف (30%)] │
│ ▼ │ [محاسبه سهم نقدی (70%)] │
│ [ZarinPal IPG] │ │ │
│ [100% نقدی] │ ▼ │
│ │ │ [کسر از DiscountBalance] │
│ ▼ │ [ZarinPal IPG برای باقیمانده] │
│ [ثبت سفارش] │ │ │
│ │ │ ▼ │
│ ▼ │ [ثبت سفارش ترکیبی] │
│ [کسر موجودی] │ [کسر موجودی] │
│ │ │ │ │
│ ▼ │ ▼ │
│ [SMS تأیید] │ [SMS تأیید] │
│ │ │
└────────────────────────────────┴──────────────────────────────────┘
```
---
## ۶. معماری Deployment
```
┌──────────────────────────────────────────────────────────────┐
│ Production Server │
│ 45.149.79.127 │
├──────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌────────────────────────────────────┐ │
│ │ nginx │────→│ Kubernetes Cluster │ │
│ │ :80/:443│ │ │ │
│ └─────────┘ │ ┌───────────┐ ┌───────────────┐ │ │
│ │ │CMS ×2 │ │FrontOffice ×2 │ │ │
│ │ │:5001 gRPC │ │:5003 Blazor │ │ │
│ │ └─────┬─────┘ └───────────────┘ │ │
│ │ │ │ │
│ │ ┌─────▼─────┐ ┌───────────────┐ │ │
│ │ │SQL Server │ │BackOffice ×1 │ │ │
│ │ │:1433 │ │:5002 Static │ │ │
│ │ └───────────┘ └───────────────┘ │ │
│ │ │ │
│ │ ┌───────────┐ ┌───────────────┐ │ │
│ │ │Nexus │ │Hangfire │ │ │
│ │ │:8081 │ │(inside CMS) │ │ │
│ │ └───────────┘ └───────────────┘ │ │
│ └────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
```
---
## ۷. Entity Relationship (ساده‌شده)
```
┌──────────┐ ┌──────────────┐ ┌──────────────┐
│ User │────→│ ClubMembership│────→│ NetworkNode │
│ │ │ │ │ (BinaryTree)│
└────┬─────┘ └──────────────┘ └──────────────┘
│
├────→ ┌──────────┐ ┌──────────┐
│ │ Order │────→│ OrderItem│────→ [Product]
│ └──────────┘ └──────────┘
│
├────→ ┌──────────────┐
│ │ Transaction │────→ [Wallet (×3)]
│ └──────────────┘
│
├────→ ┌──────────────┐
│ │ UserContract │
│ └──────────────┘
│
└────→ ┌──────────────┐
│ ChatMessage │
└──────────────┘
┌──────────┐ ┌───────────┐
│ Product │────→│ Inventory │
│ │────→│ Category │
│ │────→│ Images │
└──────────┘
┌──────────┐ ┌──────────────────────┐
│ SitePage │ │ SystemConfiguration │
│ (typed) │ │ (key-value) │
└──────────┘ └──────────────────────┘
┌──────────┐
│ BlogPost │────→ [Tags, Category, Author]
└──────────┘
```
overview/OVERVIEW-02-INDEX.md
+167
View File
@@ -0,0 +1,167 @@
# 📋 شاخص اصلی مستندات (Master Index)
> **فهرست کامل ۱۵ فایل مستند پروژه FourSat (کارا بازار سلامت)**
> **تاریخ تجمیع:** اسفند ۱۴۰۴
> **تعداد فایل‌های مبدأ:** ۵۳ فایل (~۳۲,۰۰۰ خط)
> **تعداد فایل‌های نهایی:** ۱۵ فایل
---
## ساختار مستندات
```
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 نقشه راه و ریسک‌ها
```
---
## خلاصه هر فایل
### 🏆 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 |
| 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) | نقشه راه | ریسک‌ها، وابستگی‌ها، کارهای باقیمانده، اولویت‌ها |
---
## نقشه ارتباط فایل‌ها
```
┌──────────────┐
│ O2: INDEX │ ← شما اینجا هستید
└──────┬───────┘
│
┌─────────────────┼──────────────────┐
│ │ │
┌────▼────┐ ┌────▼─────┐ ┌────▼─────┐
│Business │ │Technical │ │Overview │
│ (B1-B5) │ │ (T1-T5) │ │ (O1-O5) │
└────┬────┘ └────┬─────┘ └────┬─────┘
│ │ │
┌────┴────────────────┴──────────────────┴────┐
│ │
│ B1 ←→ B2 (مالی/باشگاه) │
│ B2 ←→ B3 (پرداخت/فروشگاه) │
│ B3 ←→ B4 (فروشگاه/کاربر) │
│ B4 ←→ B5 (کاربر/محتوا) │
│ B1 ←→ T1 (باشگاه/CMS) │
│ T1 ←→ T2 (CMS/UI) │
│ T1 ←→ T3 (CMS/Deploy) │
│ T3 ←→ T4 (Deploy/Migration) │
│ T1 ←→ T5 (CMS/API) │
│ O1: دیاگرام = بصری B1-B5 + T1-T5 │
│ O3: تاریخچه = changelog B1-B5 + T1-T5 │
│ O5: آینده = roadmap B1-B5 + T1-T5 │
│ │
└──────────────────────────────────────────────┘
```
---
## نقشه ادغام (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
+196
View File
@@ -0,0 +1,196 @@
# 📜 تاریخچه کارهای انجام‌شده
> **همه فعالیت‌های پروژه به صورت بولت با توضیح یک‌خطی و درصد تکمیل**
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
---
## خلاصه کلی
| حوزه | تعداد آیتم | تکمیل‌شده | درصد کل |
|------|-----------|----------|---------|
| **BackOffice** | 58 | 57 | **98%** |
| **FrontOffice** | 35 | 32 | **91%** |
| **CMS Core** | 45 | 42 | **93%** |
| **Deployment** | 20 | 18 | **90%** |
| **Migration** | 15 | 15 | **100%** |
| **مجموع** | **173** | **164** | **95%** |
---
## ۱. 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 آینده)
---
## ۲. FrontOffice — فازها (91% کامل)
### 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
### محتوا و ناوبری
- ✅ بلاگ — لیست + جزئیات + pagination
- ✅ صفحات سایت — About, Contact, FAQ, Terms, Privacy, Licenses
- ✅ ناوبری Auth-Aware — مسیردهی بر اساس نقش
- ✅ Home → Club Dashboard / Store بر اساس وضعیت
- ⬜ Mobile Responsive — Phase 7 (برنامه‌ریزی‌شده)
- ⬜ PWA — نیاز به Service Worker
- ⬜ Bottom Navigation (موبایل) — طراحی نشده
---
## ۳. CMS Core (93% کامل)
### ساختار و معماری
- ✅ 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
### محتوا
- ✅ Blog CRUD — با pagination
- ✅ SitePage Settings — JSON typed
- ✅ SystemConfigurations — key-value
- ⬜ Product Bundle — طراحی‌شده، پیاده‌سازی نشده
- ⬜ Manual Payment — طراحی‌شده، پیاده‌سازی نشده
- ⬜ API Rate Limiting — برنامه‌ریزی‌شده
---
## ۴. Deployment و زیرساخت (90% کامل)
- ✅ 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
- ⬜ Monitoring (Prometheus/Grafana) — برنامه‌ریزی‌شده
- ⬜ Log Aggregation (ELK/Seq) — برنامه‌ریزی‌شده
---
## ۵. 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 — از سیستم قدیم
---
## ۶. مستندات (100% کامل)
- ✅ ایجاد totalDoc repository — مخزن مرکزی docs
- ✅ جمع‌آوری ۵۳ فایل از ۵ مخزن مختلف
- ✅ تجمیع به ۱۵ فایل ساختارمند — Business + Technical + Overview
- ✅ Index و Cross-reference — نقشه ارتباطات
- ✅ واژه‌نامه و استانداردها
- ✅ نقشه راه آینده
---
## ۷. Timeline (جدول زمانی)
| زمان | رویداد | درصد پروژه |
|------|--------|-----------|
| مهر ۱۴۰۳ | شروع پروژه، معماری CMS | 10% |
| آبان ۱۴۰۳ | CQRS + gRPC + EF Core | 20% |
| آذر ۱۴۰۳ | باشگاه + درخت باینری + کمیسیون | 35% |
| دی ۱۴۰۳ | فروشگاه عادی + پرداخت ZarinPal | 45% |
| بهمن ۱۴۰۳ | فروشگاه تخفیفی + وام دایا | 55% |
| اسفند ۱۴۰۳ (هفته ۱) | UI Modernization Phase 1-3 | 65% |
| اسفند ۱۴۰۳ (هفته ۲) | Site Pages + BackOffice audit | 75% |
| اسفند ۱۴۰۳ (هفته ۳) | Inventory + Lazy Load + Images | 85% |
| اسفند ۱۴۰۳ (هفته ۴) | مستندات + نهایی‌سازی | 95% |
overview/OVERVIEW-04-GLOSSARY.md
+230
View File
@@ -0,0 +1,230 @@
# 📖 واژه‌نامه، استانداردها و قراردادهای کد
> **اصطلاحات فارسی/انگلیسی، الگوهای نام‌گذاری و استانداردهای حرفه‌ای**
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
---
## ۱. واژه‌نامه اصلی (فارسی ↔ انگلیسی)
### ۱.۱ مفاهیم بیزینسی
| فارسی | انگلیسی | توضیح |
|-------|---------|--------|
| کارا بازار سلامت | 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 | فروشگاه ۳۰% تخفیف برای اعضا |
| پرداخت ترکیبی | Hybrid Payment | DiscountBalance + IPG |
| وام دایا | Daya Loan | وام آنلاین برای خرید پکیج |
| کد معرف | Referral Code | کد یکتا هر عضو برای دعوت |
| موجودی | Inventory | تعداد محصول در انبار |
### ۱.۲ مفاهیم فنی
| فارسی | انگلیسی | توضیح |
|-------|---------|--------|
| سامانه مدیریت محتوا | CMS Microservice | هسته اصلی backend |
| پنل مدیریت | BackOffice | رابط ادمین (Blazor WASM) |
| سایت کاربران | FrontOffice | رابط مشتری (Blazor Server) |
| درگاه پرداخت | Payment Gateway (IPG) | ZarinPal |
| سرویس پرداخت | PYMS | Payment Management Service |
| کیف‌پول نقدی | Balance Wallet | موجودی قابل‌خرج |
| کیف‌پول شبکه‌ای | Network Balance | برای محاسبه کمیسیون |
| کیف‌پول تخفیفی | Discount Balance | برای فروشگاه تخفیفی |
| بارگذاری تنبل | Lazy Loading | لود محصولات ۱۲تایی |
| صفحات سایت | 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
+214
View File
@@ -0,0 +1,214 @@
# 🗺️ نقشه راه، ریسک‌ها و کارهای باقیمانده
> **Roadmap + Risk Register + Dependencies + Priorities**
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
---
## ۱. وضعیت فعلی پروژه
```
██████████████████████████████████████████████████ 95%
Core Platform ████████████████████████████████████████████████ 98%
Club System █████████████████████████████████████████████░░░ 95%
E-Commerce ████████████████████████████████████████████████ 98%
Payment ██████████████████████████████████████░░░░░░░░░ 80%
UI/UX ████████████████████████████████████████░░░░░░░ 85%
Deployment ████████████████████████████████████████████░░░ 90%
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 (فروردین-خرداد)
```
Sprint 1 (فروردین):
├── H2: Mobile Responsive
├── H1: Product Bundle
└── M4: SEO Meta Tags
Sprint 2 (اردیبهشت):
├── M1: Manual Payment (if approved)
├── M2: SignalR Chatika
└── M6: Dashboard Charts
Sprint 3 (خرداد):
├── M3: Dark Mode
├── H3: Rate Limiting
└── L1: PWA
```
### Q2 1404 (تیر-شهریور)
```
Sprint 4 (تیر):
├── L3: Monitoring
├── L4: Log Aggregation
└── L2: API Versioning
Sprint 5 (مرداد):
├── L5: Product Compare
├── L6: Wishlist
└── L7: Email Templates
Sprint 6 (شهریور):
├── L8: Refund System
├── Performance Optimization
└── Security Audit
```
---
## ۴. ریسک‌ها (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
---
## ۸. خلاصه اولویت‌بندی
```
NOW (این ماه):
→ Documentation consolidation ✅ DONE
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
```
technical/TECH-01-CMS-ARCHITECTURE.md
+262
View File
@@ -0,0 +1,262 @@
# ⚙️ معماری CMS و زیرساخت فنی
> **منابع ادغام‌شده:** `CMS-README.md`, `ICURRENTUSERSERVICE-IMPLEMENTATION.md`, `FILE-MANAGEMENT-ARCHITECTURE.md`, `FRONTOFFICE-CMS-API-COMPATIBILITY.md`, `BFF-REMOVAL-PLAN.md`, `system-constants.md`
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
---
## ۱. 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
```
┌──────────────────────────────────────────────────────┐
│ Presentation Layer │
│ FrontOffice (Blazor Server) ←─gRPC─→ CMS │
│ BackOffice (Blazor WASM) ←─gRPC─→ CMS │
├──────────────────────────────────────────────────────┤
│ Application Layer │
│ Commands (MediatR IRequest<T>) │
│ Queries (MediatR IRequest<T>) │
│ Validators (FluentValidation) │
│ Handlers (IRequestHandler<TReq, TRes>) │
├──────────────────────────────────────────────────────┤
│ Domain Layer │
│ Entities, Enums, Value Objects │
│ Domain Events, Interfaces │
├──────────────────────────────────────────────────────┤
│ Infrastructure Layer │
│ EF Core DbContext (CMSDbContext) │
│ Repositories, External Services │
│ Hangfire Jobs, File Storage │
├──────────────────────────────────────────────────────┤
│ Database │
│ SQL Server — Schema: [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 |
### ۴.۲ 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 | کاربران | ~5K |
| Products | محصولات | ~200 |
| Categories | دسته‌بندی‌ها | ~30 |
| Orders | سفارشات | ~2K |
| Inventories | موجودی | ~200 |
| BlogPosts | پست‌های بلاگ | ~50 |
| SitePages | صفحات سایت | ~10 |
| UserClubMemberships | عضویت باشگاه | ~500 |
| UserContracts | قراردادها | ~500 |
| NetworkNodes | نودهای درخت باینری | ~500 |
| Transactions | تراکنش‌ها | ~5K |
| SystemConfigurations | تنظیمات | ~30 |
| ChatMessages | پیام‌های چاتیکا | ~1K |
### ۵.۳ Stored Procedures
| SP | کاربرد |
|----|--------|
| `SP_GetNetworkTree` | بازگشتی — استخراج درخت باینری |
| `sp_CalculateWeeklyBalances` | محاسبه بالانس هفتگی هر عضو |
| `sp_CalculateWeeklyCommissionPool` | توزیع Pool هفتگی |
---
## ۶. حذف BFF / Gateway
### ۶.۱ قبل vs بعد
```
قبل:
FrontOffice → BFF (REST) → CMS (gRPC)
BackOffice → BFF (REST) → CMS (gRPC)
بعد (فعلی):
FrontOffice → CMS (gRPC مستقیم)
BackOffice → CMS (gRPC مستقیم)
مزایا:
✅ حذف لایه واسط → کاهش latency
✅ حذف maintenance اضافی
✅ 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 | فرکانس | کاربرد |
|-----|---------|--------|
| `DayaLoanProcessorJob` | هر ۱۵ دقیقه | پردازش درخواست‌های وام |
| `WeeklyCommissionJob` | هفتگی (شنبه ۰۰:۰۰) | محاسبه و توزیع کمیسیون |
| `ChatikaJob` | هر ۵ دقیقه | همگام‌سازی پیام‌های AI |
| `InventorySyncJob` | هر ساعت | ایجاد رکوردهای موجودی گمشده |
---
## ۸. پیکربندی
### ۸.۱ 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": "***" },
"DayaLoan": { "UseMock": true }
}
```
technical/TECH-02-BACKOFFICE-FRONTOFFICE.md
+252
View File
@@ -0,0 +1,252 @@
# 🖥️ 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`
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
---
## ۱. 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/
│ ├── 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 ← امضای قرارداد
│ ├── Blog/
│ ├── Auth/
│ │ ├── Login.razor
│ │ └── Register.razor
│ └── About.razor, Contact.razor, ...
├── Services/
│ ├── ProductService.cs ← با GetProductsPagedAsync
│ ├── ClubService.cs
│ └── ...
└── Shared/
├── AppImage.razor
├── ProductCard.razor ← مشترک بین Store و DiscountStore
└── 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% |
| Mobile Responsive (Phase 7) | ⬜ | 0% |
| Dark Mode | ⬜ | 0% |
| PWA | ⬜ | 0% |
technical/TECH-03-DEPLOYMENT-INFRA.md
+340
View File
@@ -0,0 +1,340 @@
# 🚀 استقرار، CI/CD و زیرساخت
> **منابع ادغام‌شده:** `CICD-PIPELINE-GUIDE.md`, `DEPLOYMENT-README.md`, `INFRASTRUCTURE-GUIDE.md`, `INGRESS-NGINX-WARNING.md`, `OFFLINE-DEPLOYMENT-GUIDE.md`, `SERVER-MIRRORS-CONFIG.md`
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
---
## ۱. سرورها
| سرور | 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 ساختار
```
deployment/k8s-manifests/
├── cms-deployment.yaml
├── cms-service.yaml
├── backoffice-deployment.yaml
├── backoffice-service.yaml
├── frontoffice-deployment.yaml
├── frontoffice-service.yaml
├── db-statefulset.yaml
├── db-service.yaml
├── ingress.yaml
├── configmap.yaml
└── secrets.yaml
```
### ۳.۲ مثال Deployment
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: cms
namespace: foursat
spec:
replicas: 2
selector:
matchLabels:
app: cms
template:
spec:
containers:
- name: cms
image: foursat/cms:latest
ports:
- containerPort: 5001
resources:
requests:
memory: "256Mi"
cpu: "250m"
limits:
memory: "512Mi"
cpu: "500m"
livenessProbe:
grpc:
port: 5001
initialDelaySeconds: 15
readinessProbe:
grpc:
port: 5001
```
### ۳.۳ Ingress
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: foursat-ingress
annotations:
nginx.ingress.kubernetes.io/ssl-redirect: "true"
nginx.ingress.kubernetes.io/proxy-body-size: "50m"
spec:
rules:
- host: foursat.ir
http:
paths:
- path: /
backend:
service:
name: frontoffice
port: { number: 5003 }
- path: /admin
backend:
service:
name: backoffice
port: { number: 80 }
```
> ⚠️ **هشدار:** Ingress-nginx نسخه‌های قبل از 1.9.0 مشکل امنیتی CVE-2023-5044 دارند. حتماً بروزرسانی کنید.
---
## ۴. CI/CD Pipeline
### ۴.۱ Gitea Actions Workflow
```yaml
name: Build and Deploy
on:
push:
branches: [kub-stage, production]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup .NET
uses: actions/setup-dotnet@v4
with:
dotnet-version: '9.0.x'
- name: Restore
run: dotnet restore
- name: Build
run: dotnet build --no-restore -c Release
- name: Test
run: dotnet test --no-build -c Release
- name: Docker Build & Push
run: |
docker build -t $REGISTRY/foursat/cms:${{ github.sha }} .
docker push $REGISTRY/foursat/cms:${{ github.sha }}
- name: Deploy to K8s
if: github.ref == 'refs/heads/production'
run: |
kubectl set image deployment/cms cms=$REGISTRY/foursat/cms:${{ github.sha }}
```
### ۴.۲ شاخه‌ها
| شاخه | محیط | Deploy |
|------|------|--------|
| `kub-stage` | Staging (194.5.195.53) | Auto |
| `production` | Production (45.149.79.127) | Manual trigger |
| `main` | — | Development only |
---
## ۵. استقرار آفلاین (Offline Deployment)
### ۵.۱ فلوی آماده‌سازی
```
سرور اینترنت‌دار:
1. pull-base-images.sh → دانلود Docker images
2. cache-nuget-packages.sh → دانلود NuGet packages
3. save-images.sh → ذخیره تصاویر به tar
4. بسته‌بندی همه فایل‌ها
انتقال فیزیکی (USB/HDD):
tar files + nuget packages + k8s manifests
سرور آفلاین:
1. load-images.sh → بارگذاری تصاویر
2. setup-nexus-complete.sh → راه‌اندازی Nexus (NuGet proxy)
3. build-all-offline.sh → بیلد با Nexus محلی
4. k8s-deploy.sh → استقرار در Kubernetes
```
### ۵.۲ اسکریپت‌های کلیدی
| اسکریپت | کاربرد |
|----------|--------|
| `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
### ۶.۱ نقش
```
Nexus (داخلی):
├── NuGet proxy → cache.nuget.org packages
├── NuGet hosted → بسته‌های proto داخلی
├── Docker proxy → cache Docker Hub images
└── Docker hosted → تصاویر داخلی 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)
### ۸.۱ فلوی بسته‌بندی
```
CMS/src/Protos/*.proto
│
▼
pack-protos.sh → dotnet pack → .nupkg
│
▼
push to BaGet/Nexus
│
▼
BackOffice + FrontOffice → dotnet restore → مصرف proto
```
### ۸.۲ نام بسته
```xml
<PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="1.0.x" />
```
---
## ۹. مانیتورینگ و Health Check
```bash
# k8s-health-check.sh
kubectl get pods -n foursat
kubectl top pods -n foursat
kubectl logs deployment/cms -n foursat --tail=50
# تست سرویس‌ها
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
+230
View File
@@ -0,0 +1,230 @@
# 🔄 مهاجرت داده، 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`
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
---
## ۱. تاریخچه مهاجرت‌ها
```
Timeline:
▸ فاز ۱: FrontOffice REST → CMS gRPC (مستقیم)
▸ فاز ۲: BackOffice REST → CMS gRPC (مستقیم)
▸ فاز ۳: حذف BFF/Gateway
▸ فاز ۴: حذف API Gateway (Ocelot)
▸ فاز ۵: یکپارچه‌سازی Proto packages
▸ فاز ۶: Data migration از سیستم قدیم
```
---
## ۲. حذف BFF (Backend-for-Frontend)
### ۲.۱ قبل
```
FrontOffice ──HTTP/REST──→ BFF ──gRPC──→ CMS
BackOffice ──HTTP/REST──→ BFF ──gRPC──→ CMS
BFF مسئولیت‌ها:
• تبدیل REST↔gRPC
• Aggregation
• Auth proxy
• Rate limiting
```
### ۲.۲ بعد (فعلی)
```
FrontOffice ──gRPC──→ CMS (مستقیم)
BackOffice ──gRPC──→ CMS (مستقیم)
مزایا:
✅ حذف ۱ سرویس از deployment
✅ کاهش ~50ms latency per request
✅ Type-safety از proto تا UI
✅ ساده‌سازی debug و logging
✅ کاهش maintenance cost
```
### ۲.۳ مراحل مهاجرت
```
مرحله ۱: ایجاد 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)
### ۳.۱ قبل
```
Client → nginx → Ocelot Gateway → { CMS, BFF, FileService }
↑
URL routing, rate limiting, auth
```
### ۳.۲ بعد
```
Client → nginx → Ingress → { CMS, BackOffice, FrontOffice }
↑
Path-based routing in Ingress
```
### ۳.۳ دلایل حذف
```
✅ 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
│ ├── Program.cs
│ ├── Migrators/
│ │ ├── UserMigrator.cs
│ │ ├── ProductMigrator.cs
│ │ ├── OrderMigrator.cs
│ │ └── ClubMigrator.cs
│ └── Mappings/
│ └── TableMappings.cs
└── FourSat.GeographySeeder/ ← Seed geography data
├── Program.cs
└── Data/
├── provinces.json
└── cities.json
```
### ۵.۲ 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.NetworkNodes` | Binary tree reconstruction |
| `dbo.Wallets` | `CMS.UserWalletBalances` | ۳ wallet types split |
| `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` | افزایش قیمت ۱۰% |
---
## ۶. 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% |
technical/TECH-05-API-INTEGRATION.md
+329
View File
@@ -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`
> **آخرین بروزرسانی:** اسفند ۱۴۰۴
---
## ۱. معماری ارتباطات
```
┌──────────────────────────────────────────────────────────────────┐
│ 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);
}
```
### ۲.۲ 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 = "verify-foursat";
const string CONTRACT_TEMPLATE = "contract-verify";
const string WELCOME_TEMPLATE = "club-welcome";
// 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 — هر ۱۵ دقیقه
// 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
```
CMS/src/Protos/*.proto
│
▼
pack-protos.sh
│
▼
Foursat.CMSMicroservice.Protobuf.nupkg (v1.0.x)
│
▼
Push to BaGet (http://localhost:5555) or Nexus
│
▼
BackOffice: <PackageReference Include="Foursat.CMSMicroservice.Protobuf" />
FrontOffice: <PackageReference Include="Foursat.CMSMicroservice.Protobuf" />
```
---
## ۶. 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 | ⬜ |
ui-modernization/BACKOFFICE-ARCHITECTURE.md
-359
View File
@@ -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
-195
View File
@@ -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
-118
View File
@@ -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
-104
View File
@@ -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`)
ui-modernization/PRODUCT-IMAGES-SQUARE.md
-93
View File
@@ -1,93 +0,0 @@
# تصاویر مربعی محصولات (Product Images 1:1 Square Ratio)
> **تاریخ:** اسفند ۱۴۰۴ (February 2026)
> **وضعیت:** ✅ پیاده‌سازی شده — مرج به production
> **پروژه:** FrontOffice
---
## ۱. خلاصه
تمامی تصاویر محصولات در سمت مشتری (FrontOffice) در هر دو فروشگاه (عادی و اعتباری) به نسبت **1:1 مربعی** تغییر یافت.
---
## ۲. تغییرات اعمال شده
### ۲.۱ لیست محصولات (Products Grid)
| صفحه | تغییر |
|------|-------|
| `Store/Products.razor` | `height:300px` → حذف ارتفاع ثابت کارت |
| | `height:60%` → `aspect-ratio:1/1; width:100%` |
| `DiscountStore/Products.razor` | همان تغییرات |
**قبل:**
```html
<MudCard Style="cursor:pointer;height: 300px">
<div style="height: 60%; background-image: url(...)">
```
**بعد:**
```html
<MudCard Style="cursor:pointer;">
<div style="aspect-ratio:1/1; width:100%; background-image: url(...)">
```
### ۲.۲ جزئیات محصول (Product Detail — Main Image)
| صفحه | تغییر |
|------|-------|
| `Store/ProductDetail.razor` | `max-height:400px` → `aspect-ratio:1/1` |
| `DiscountStore/ProductDetail.razor` | `ObjectFit.Contain` → `ObjectFit.Cover` + `aspect-ratio:1/1` |
### ۲.۳ سبد خرید (Cart)
| صفحه | ویو | تغییر |
|------|-----|-------|
| `Store/Cart.razor` | Desktop (64×64) | `product-thumb` → `rounded-lg` + `ObjectFit.Cover` |
| `Store/Cart.razor` | Mobile (50×50) | `rounded-circle` → `rounded-lg` + `ObjectFit.Cover` |
| `DiscountStore/Cart.razor` | Desktop (64×64) | `product-thumb` → `rounded-lg` + `ObjectFit.Cover` |
| `DiscountStore/Cart.razor` | Mobile (50×50) | `rounded-circle` → `rounded-lg` + `ObjectFit.Cover` |
### ۲.۴ صفحه پرداخت (Checkout Summary)
| صفحه | تغییر |
|------|-------|
| `Store/CheckoutSummary.razor` (48×48) | `rounded-circle` → `rounded-lg` + `ObjectFit.Cover` |
| `DiscountStore/Checkout.razor` (40×40) | `rounded-circle` → `rounded-lg` + `ObjectFit.Cover` |
### ۲.۵ جزئیات سفارش (Order Detail)
| صفحه | ویو | تغییر |
|------|-----|-------|
| `Store/OrderDetail.razor` | Desktop (60×60) | `rounded-circle` → `rounded-lg` + `ObjectFit.Cover` |
| `Store/OrderDetail.razor` | Mobile (60×60) | `rounded-circle` → `rounded-lg` + `ObjectFit.Cover` |
---
## ۳. خلاصه تکنیکال
| الگوی قبلی | الگوی جدید | محل |
|------------|------------|------|
| `height: 60%` + `height: 300px` card | `aspect-ratio: 1/1; width: 100%` + no fixed card height | لیست محصولات |
| `max-height: 400px` | `aspect-ratio: 1/1` | جزئیات محصول |
| `ObjectFit.Contain` | `ObjectFit.Cover` | تصاویر اعتباری |
| `Class="rounded-circle"` | `Class="rounded-lg" ObjectFit="ObjectFit.Cover"` | تمام thumbnailها |
| `Class="product-thumb"` | `Class="rounded-lg" ObjectFit="ObjectFit.Cover"` | سبد خرید Desktop |
---
## ۴. فایل‌های تغییر یافته (۹ فایل)
| فایل | تغییر |
|------|-------|
| `Pages/Store/Products.razor` | ✏️ |
| `Pages/Store/ProductDetail.razor` | ✏️ |
| `Pages/Store/Cart.razor` | ✏️ |
| `Pages/Store/CheckoutSummary.razor` | ✏️ |
| `Pages/Store/OrderDetail.razor` | ✏️ |
| `Pages/DiscountStore/Products.razor` | ✏️ |
| `Pages/DiscountStore/ProductDetail.razor` | ✏️ |
| `Pages/DiscountStore/Cart.razor` | ✏️ |
| `Pages/DiscountStore/Checkout.razor` | ✏️ |
ui-modernization/UI-MODERNIZATION-PLAN.md
-1418
View File
File diff suppressed because it is too large Load Diff