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