# 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 کیف پول با تراکنش‌های کامل)