feat: Update documentation with recent fixes and enhancements including Commission System and mapping issues

2025-12-27 22:03:21 +03:30
parent 6220049161
commit 4f999033bd
4 changed files with 577 additions and 15 deletions
@@ -1,6 +1,6 @@
 # 📝 Changelog - ۷ دی ۱۴۰۴ (27 December 2025)

-> **Session**: بهینه‌سازی‌های Mapping + SystemConstants + SMS Templates + AppVersion UI
+> **Session**: بهینه‌سازی‌های Mapping + SystemConstants + SMS Templates + AppVersion UI + Commission System Fixes

 ---

@@ -12,6 +12,12 @@
 3. **SMS for Daya Loan** - ارسال پیامک هنگام تأیید وام دایا
 4. **AppVersion UI** - تکمیل صفحه مدیریت نسخه در BackOffice
 5. **Mapping Fixes** - رفع مشکلات Mapster
+6. **Commission Status Refactoring** - انتقال تبدیل Status از BFF به FrontOffice
+7. **ProcessWithdrawal Fix** - رفع خطای "PayoutId invalid" در BackOffice
+8. **WeekDisplayName Fix** - نمایش صحیح نام هفته به جای فرمت 1404-W40
+9. **Withdrawals Page Fix** - رفع مشکل لود نشدن صفحه تأیید برداشت‌ها
+10. **Network Balances Enhancement** - افزودن نام کاربر و جزئیات Carryover به صفحه balance‌ها
+11. **WeekDefinitionId Mapping Fix** - رفع مشکل ارسال WeekDefinitionId=0 در FrontOffice.BFF

 ---

@@ -269,6 +275,272 @@ config.NewConfig<MediatR.Unit, Google.Protobuf.WellKnownTypes.Empty>()

 ---

+### 6. 🔄 Commission Status Refactoring ✅
+
+**مشکل**: تبدیل enum عددی `CommissionPayoutStatus` به متن فارسی در BFF gateway انجام می‌شد.
+
+**راه‌حل**: انتقال منطق به FrontOffice client برای معماری بهتر.
+
+#### 6.1 FrontOffice.BFF - Simplify Response
+
+**فایل**: `FrontOffice.BFF.Application/.../GetMyWeeklyBalancesQueryHandler.cs`
+
+**قبل**:
+```csharp
+Status = MapStatusToString(x.Status)
+```
+
+**بعد**:
+```csharp
+Status = x.Status  // Return int directly
+```
+
+#### 6.2 FrontOffice - CommissionService
+
+**فایل**: `FrontOffice.Main/Utilities/CommissionService.cs`
+
+```csharp
+public static string MapStatus(int status) => status switch
+{
+    0 => "در انتظار",      // Pending
+    1 => "پرداخت شده",     // Paid
+    2 => "درخواست برداشت", // WithdrawRequested
+    3 => "برداشت شده",     // Withdrawn
+    4 => "خطای پرداخت",    // PaymentFailed
+    5 => "لغو شده",        // Cancelled
+    _ => "نامشخص"
+};
+
+public static string GetStatusColor(int status) => status switch
+{
+    0 => "warning",   // Pending - زرد
+    1 => "success",   // Paid - سبز
+    2 => "info",      // WithdrawRequested - آبی
+    3 => "success",   // Withdrawn - سبز
+    4 => "error",     // PaymentFailed - قرمز
+    5 => "default",   // Cancelled - خاکستری
+    _ => "default"
+};
+```
+
+**Enum مرجع** (`CommissionPayoutStatus`):
+```csharp
+public enum CommissionPayoutStatus
+{
+    Pending = 0,
+    Paid = 1,
+    WithdrawRequested = 2,
+    Withdrawn = 3,
+    PaymentFailed = 4,
+    Cancelled = 5
+}
+```
+
+---
+
+### 7. 🛠️ ProcessWithdrawal Fix ✅
+
+**مشکل**: خطای "PayoutId invalid" هنگام تأیید/رد برداشت در BackOffice
+
+**علت**: `PayoutId` در mapping از CMS request به BackOffice.BFF command map نمی‌شد.
+
+**فایل**: `BackOffice.BFF.Application/Common/Mappings/CommissionProfile.cs`
+
+**قبل**:
+```csharp
+config.NewConfig<ProcessWithdrawalRequest, ProcessWithdrawalCommand>();
+// PayoutId ignored!
+```
+
+**بعد**:
+```csharp
+config.NewConfig<ProcessWithdrawalRequest, ProcessWithdrawalCommand>()
+    .Map(dest => dest.PayoutId, src => src.PayoutId)
+    .Map(dest => dest.Approve, src => src.Approve)
+    .Map(dest => dest.RejectionReason, src => src.RejectionReason);
+```
+
+---
+
+### 8. 📅 WeekDisplayName Fix ✅
+
+**مشکل**: نمایش "1404-W40" به جای "هفته چهلم" در dropdown انتخاب هفته
+
+**علت**: استفاده از `PersianWeekNumber` به جای `DisplayName`
+
+**فایل**: `CMS.Application/.../GetAllWeeklyPoolsQueryHandler.cs`
+
+**قبل**:
+```csharp
+WeekDisplayName = x.WeekDefinition.PersianWeekNumber  // "1404-W40"
+```
+
+**بعد**:
+```csharp
+WeekDisplayName = x.WeekDefinition.DisplayName  // "هفته چهلم"
+```
+
+---
+
+### 9. 📋 Withdrawals Page Fix ✅
+
+**مشکل**: صفحه تأیید برداشت‌ها در BackOffice لود نمی‌شد
+
+**علت**: mismatch بین نام propertyها در CMS proto و BackOffice.BFF DTO
+
+**فایل**: `BackOffice.BFF.Application/.../GetWithdrawalRequestsResponseDto.cs`
+
+**قبل**:
+```csharp
+public int TotalPages { get; set; }
+public int TotalCount { get; set; }
+```
+
+**بعد**:
+```csharp
+public int TotalPage { get; set; }   // Match CMS proto
+public int TotalCount { get; set; }
+```
+
+**فایل**: `BackOffice.BFF.Application/.../GetWithdrawalRequestsQueryHandler.cs`
+
+**قبل**:
+```csharp
+return response.Adapt<GetWithdrawalRequestsResponseDto>();
+```
+
+**بعد**:
+```csharp
+return new GetWithdrawalRequestsResponseDto
+{
+    TotalCount = (int)response.MetaData.TotalCount,
+    TotalPage = (int)response.MetaData.TotalPage,
+    // ... explicit mapping
+};
+```
+
+---
+
+### 10. 👤 Network Balances Enhancement ✅
+
+**نیاز**: نمایش نام کامل کاربر و جزئیات breakdown پای چپ/راست در صفحه balance‌های شبکه
+
+#### 10.1 CMS Proto Update
+
+**فایل**: `CMS/Protobufs/Protos/commission.proto`
+
+```protobuf
+message UserWeeklyBalanceModel {
+    // ... existing fields
+    string user_full_name = 13;
+    int64 left_leg_new_members = 14;
+    int64 left_leg_carryover = 15;
+    int64 left_leg_total = 16;
+    int64 right_leg_new_members = 17;
+    int64 right_leg_carryover = 18;
+    int64 right_leg_total = 19;
+}
+```
+
+#### 10.2 CMS Handler Update
+
+**فایل**: `CMS.Application/.../GetUserWeeklyBalancesQueryHandler.cs`
+
+```csharp
+var query = _dbContext.NetworkWeeklyBalances
+    .Include(x => x.User)  // NEW: Include User
+    .Include(x => x.WeekDefinition)
+    .Where(x => x.WeekDefinitionId == request.WeekDefinitionId);
+
+// In projection:
+UserFullName = $"{x.User.FirstName} {x.User.LastName}".Trim(),
+LeftLegNewMembers = x.LeftLegNewMembers,
+LeftLegCarryover = x.LeftLegCarryover,
+LeftLegTotal = x.LeftLegTotal,
+RightLegNewMembers = x.RightLegNewMembers,
+RightLegCarryover = x.RightLegCarryover,
+RightLegTotal = x.RightLegTotal,
+```
+
+#### 10.3 BackOffice UI Update
+
+**فایل**: `BackOffice/Pages/Network/BalancesReport.razor`
+
+```razor
+@* ستون نام کاربر *@
+<PropertyColumn Property="x => x.UserFullName" Title="نام کاربر" />
+
+@* ستون پای چپ با Tooltip *@
+<TemplateColumn Title="پای چپ">
+    <CellTemplate>
+        <MudTooltip Text="@($"جدید: {FormatNumber(context.Item.LeftLegNewMembers)} | انتقالی: {FormatNumber(context.Item.LeftLegCarryover)}")">
+            <MudText>@FormatNumber(context.Item.LeftLegTotal)</MudText>
+        </MudTooltip>
+    </CellTemplate>
+</TemplateColumn>
+
+@* ستون پای راست با Tooltip *@
+<TemplateColumn Title="پای راست">
+    <CellTemplate>
+        <MudTooltip Text="@($"جدید: {FormatNumber(context.Item.RightLegNewMembers)} | انتقالی: {FormatNumber(context.Item.RightLegCarryover)}")">
+            <MudText>@FormatNumber(context.Item.RightLegTotal)</MudText>
+        </MudTooltip>
+    </CellTemplate>
+</TemplateColumn>
+```
+
+#### 10.4 Proto Package Update
+
+```bash
+# Publish new proto package
+cd CMS/Protobufs
+# Update version in .csproj to 0.0.14
+dotnet pack
+dotnet nuget push ...
+
+# Update BackOffice
+cd BackOffice/src/BackOffice
+# Update package reference in .csproj
+<PackageReference Include="Foursat.BackOffice.BFF.Commission.Protobuf" Version="0.0.14" />
+```
+
+---
+
+### 11. 🔢 WeekDefinitionId Mapping Fix ✅
+
+**مشکل**: `WeekDefinitionId` همیشه `0` به BFF ارسال می‌شد، حتی اگر در client مقدار صحیح ست شده بود.
+
+**علت**: در protobuf، فیلد `week_definition_id` از نوع `google.protobuf.Int64Value` است که یک wrapper type هست. در mapping مستقیم assign می‌شد بدون extract کردن `.Value`.
+
+**فایل**: `FrontOffice.BFF/src/FrontOffice.BFF.WebApi/Common/Mappings/CommissionProfile.cs`
+
+**Proto Definition**:
+```protobuf
+message GetMyWeeklyBalancesRequest {
+    google.protobuf.Int64Value week_definition_id = 3;
+}
+```
+
+**قبل**:
+```csharp
+config.NewConfig<GetMyWeeklyBalancesRequest, GetMyWeeklyBalancesQuery>()
+    .Map(dest => dest.WeekDefinitionId, src => src.WeekDefinitionId);  // BUG: assigns Int64Value object, not the value
+```
+
+**بعد**:
+```csharp
+config.NewConfig<GetMyWeeklyBalancesRequest, GetMyWeeklyBalancesQuery>()
+    .Map(dest => dest.WeekDefinitionId, 
+         src => src.WeekDefinitionId != null ? src.WeekDefinitionId.Value : null);
+```
+
+**توضیح**:
+- `Int64Value` یک wrapper class در protobuf هست برای nullable long
+- وقتی مستقیم assign کنید، implicit conversion اتفاق نمیفته
+- باید explicit از `.Value` استفاده کنید
+
+---
+
 ## 📦 فایل‌های تغییر یافته

 ### CMS
@@ -278,12 +550,20 @@ config.NewConfig<MediatR.Unit, Google.Protobuf.WellKnownTypes.Empty>()
 | `Domain/Common/SmsTemplates.cs` | **New** - قالب‌های پیامک |
 | `Application/.../ProcessDayaLoanApprovalCommandHandler.cs` | Modified - اضافه شدن SMS |
 | `WebApi/Common/Mappings/AppVersionProfile.cs` | **New** - Mapster profile |
+| `Application/.../GetAllWeeklyPoolsQueryHandler.cs` | Modified - تغییر WeekDisplayName از PersianWeekNumber به DisplayName |
+| `Application/.../GetUserWeeklyBalancesQueryHandler.cs` | Modified - اضافه شدن User include و فیلدهای جدید |
+| `Application/.../GetUserWeeklyBalancesResponseDto.cs` | Modified - اضافه شدن UserFullName و breakdown fields |
+| `WebApi/Common/Mappings/CommissionProfile.cs` | Modified - mapping جدید برای UserWeeklyBalanceModel |
+| `Protobufs/Protos/commission.proto` | Modified - اضافه شدن فیلدهای جدید به UserWeeklyBalanceModel |

 ### BackOffice.BFF
 | فایل | نوع تغییر |
 |------|-----------|
-| `Application/Common/Mappings/CommissionProfile.cs` | Modified - اضافه شدن GetAllWeeklyPools mapping |
+| `Application/Common/Mappings/CommissionProfile.cs` | Modified - اضافه شدن GetAllWeeklyPools mapping + ProcessWithdrawal mapping |
 | `WebApi/Common/Mappings/GeneralMapping.cs` | Modified - اضافه شدن Unit to Empty |
+| `Application/.../GetWithdrawalRequestsQueryHandler.cs` | Modified - explicit mapping به جای Adapt<> |
+| `Application/.../GetWithdrawalRequestsResponseDto.cs` | Modified - تطابق با CMS proto |
+| `Protobufs/Protos/commission.proto` | Modified - اضافه شدن فیلدهای جدید |

 ### BackOffice
 | فایل | نوع تغییر |
@@ -291,6 +571,20 @@ config.NewConfig<MediatR.Unit, Google.Protobuf.WellKnownTypes.Empty>()
 | `Shared/NavMenu.razor` | Modified - اضافه شدن لینک app-versions |
 | `Pages/Settings/AppVersions.razor` | Modified - دکمه افزودن + OpenCreateDialog |
 | `Pages/Settings/Components/AppVersionEditDialog.razor` | Modified - پارامتر IsNew + Select |
+| `Pages/Network/BalancesReport.razor` | Modified - ستون‌های جدید با MudTooltip |
+| `BackOffice.csproj` | Modified - آپدیت proto package به v0.0.14 |
+
+### FrontOffice.BFF
+| فایل | نوع تغییر |
+|------|-----------|
+| `WebApi/Common/Mappings/CommissionProfile.cs` | Modified - رفع WeekDefinitionId mapping (Int64Value.Value) |
+| `Application/.../GetMyWeeklyBalancesQueryHandler.cs` | Modified - simplify status handling |
+
+### FrontOffice
+| فایل | نوع تغییر |
+|------|-----------|
+| `Utilities/CommissionService.cs` | Modified - اضافه شدن GetStatusColor و MapStatus (انتقال از BFF) |
+| `Pages/Commission/WeeklyBalancePage.razor.cs` | Modified - استفاده از متدهای جدید CommissionService |

 ---

@@ -308,6 +602,14 @@ dotnet build BackOffice.BFF.WebApi/BackOffice.BFF.WebApi.csproj
 # BackOffice
 dotnet build BackOffice/BackOffice.csproj
 # Build succeeded. 0 Error(s)
+
+# FrontOffice.BFF
+dotnet build FrontOffice.BFF.WebApi/FrontOffice.BFF.WebApi.csproj
+# Build succeeded. 0 Error(s)
+
+# FrontOffice
+dotnet build FrontOffice.Main/FrontOffice.Main.csproj
+# Build succeeded. 0 Error(s)
 ```

 ---
@@ -317,9 +619,10 @@ dotnet build BackOffice/BackOffice.csproj
 | متریک | مقدار |
 |-------|-------|
 | فایل‌های جدید | 2 |
-| فایل‌های تغییر یافته | 8 |
-| خطوط کد اضافه شده | ~300 |
-| باگ‌های Mapping رفع شده | 3 |
+| فایل‌های تغییر یافته | 18 |
+| خطوط کد اضافه شده | ~500 |
+| باگ‌های Mapping رفع شده | 5 |
+| پروژه‌های تأثیرگذار | 5 (CMS, BackOffice, BackOffice.BFF, FrontOffice, FrontOffice.BFF) |

 ---