feat: Update changelog and documentation for version 2.7, including Commission Data Flow Fix, UI improvements, and terminology cleanup

2025-12-29 00:40:13 +03:30
parent 4f999033bd
commit df650c3886
3 changed files with 282 additions and 22 deletions
@@ -0,0 +1,216 @@
+# 📝 Changelog - ۹ دی ۱۴۰۴ (29 December 2025)
+
+> **Session**: Commission Data Flow Fix + UI Improvements + Terminology Cleanup (MLM-sensitive words)
+
+---
+
+## 🎯 خلاصه Session
+
+این session شامل موارد زیر بود:
+
+1. **Commission Carryover Data Flow** - رفع مشکل نمایش 0 برای carryover در صفحه weekly-balance
+2. **WeekSelector Autocomplete** - افزودن انتخابگر هفته به صفحه داشبورد کمیسیون
+3. **Responsive Commission Pages** - بهبود رسپانسیو صفحات با MudGrid
+4. **Merge Dashboard & History Pages** - ادغام دو صفحه تکراری کمیسیون
+5. **Terminology Cleanup** - جایگزینی کلمات حساس MLM با معادل‌های خنثی
+
+---
+
+## ✨ تغییرات
+
+### 1. 💰 Commission Carryover Data Flow ✅
+
+**مشکل**: صفحه `weekly-balance` مقادیر carryover را همیشه 0 نشان می‌داد در حالی که API مقادیر صحیح برمی‌گرداند.
+
+**علت**: FrontOffice client carryover را خودش محاسبه می‌کرد به جای استفاده از مقادیر سرور.
+
+**فایل‌های تغییر یافته**:
+
+| فایل | تغییر |
+|------|-------|
+| `FrontOffice.BFF/commission.proto` | افزودن fields 11-14: carryover و new_members |
+| `FrontOffice.BFF/CommissionProfile.cs` | Mapping جدید برای carryover fields |
+| `FrontOffice/CommissionDtos.cs` | Properties جدید: LeftCarryover, RightCarryover, LeftNewMembers, RightNewMembers |
+| `FrontOffice/CommissionService.cs` | استفاده از مقادیر واقعی سرور به جای محاسبه محلی |
+
+**Proto Fields جدید**:
+```protobuf
+message WeeklyBalanceResponse {
+    // ... existing fields ...
+    int32 left_leg_carryover = 11;
+    int32 right_leg_carryover = 12;
+    int32 left_leg_new_members = 13;
+    int32 right_leg_new_members = 14;
+}
+```
+
+---
+
+### 2. 🎯 WeekSelector Autocomplete ✅
+
+**نیاز**: انتخاب آسان هفته‌ها در صفحه داشبورد کمیسیون به جای dropdown ساده.
+
+**پیاده‌سازی**:
+```razor
+<MudAutocomplete T="WeekSelectorItem"
+                 Label="انتخاب هفته"
+                 @bind-Value="_selectedWeek"
+                 SearchFunc="SearchWeeks"
+                 ToStringFunc="@(w => w?.DisplayName ?? "")"
+                 Variant="Variant.Outlined"
+                 Dense="true" />
+```
+
+**فایل**: `FrontOffice.Main/Pages/Commission/CommissionDashboardPage.razor`
+
+---
+
+### 3. 📱 Responsive Commission Pages ✅
+
+**تغییرات UI**:
+- استفاده از `MudGrid` با breakpoints مناسب (`xs`, `sm`, `md`)
+- `MudHidden` برای نمایش/مخفی کردن المان‌ها در موبایل/دسکتاپ
+- کارت‌های آماری (Summary Stats) در بالای صفحه
+- جدول در دسکتاپ، کارت در موبایل
+
+**Summary Stats Cards**:
+```razor
+<MudGrid Spacing="2" Class="mb-4">
+    <MudItem xs="6" sm="3">
+        <MudPaper Class="pa-3 text-center" Elevation="2">
+            <MudText Typo="Typo.h5" Color="Color.Primary">@TotalCommissions.ToString("N0")</MudText>
+            <MudText Typo="Typo.caption">کل پاداش‌ها</MudText>
+        </MudPaper>
+    </MudItem>
+    <!-- ... more stats ... -->
+</MudGrid>
+```
+
+---
+
+### 4. 🔀 Merge Dashboard & History Pages ✅
+
+**قبل**: دو صفحه جداگانه با functionality تکراری
+- `/commission/dashboard` - داشبورد با فیلتر
+- `/commission/history` - تاریخچه با pagination
+
+**بعد**: یک صفحه واحد با dual routing
+```csharp
+@attribute [Route(RouteConstants.Commission.Dashboard)]
+@attribute [Route(RouteConstants.Commission.History)]
+```
+
+**فایل‌های حذف شده**:
+- `CommissionHistoryPage.razor` ❌
+- `CommissionHistoryPage.razor.cs` ❌
+
+**فایل نهایی**: `CommissionDashboardPage.razor` با تمام قابلیت‌ها
+
+---
+
+### 5. 📝 Terminology Cleanup (MLM-Sensitive Words) ✅
+
+**هدف**: جایگزینی کلمات حساس MLM با معادل‌های خنثی برای جلوگیری از حساسیت مشتریان.
+
+#### جایگزینی‌های انجام شده:
+
+| کلمه قبلی | کلمه جدید | توضیح |
+|-----------|-----------|-------|
+| کمیسیون | **پاداش** | Commission → Reward |
+| شبکه‌سازی | **تیم‌سازی** | Network Building → Team Building |
+| شبکه‌های فروش | **تیم‌های فروش** | Sales Networks → Sales Teams |
+| مشاهده شبکه | **مشاهده تیم** | View Network → View Team |
+| آمار شبکه | **آمار تیم** | Network Stats → Team Stats |
+| رشد میانگین شبکه | **رشد میانگین تیم** | Network Growth → Team Growth |
+
+#### فایل‌های تغییر یافته:
+
+| فایل | تغییرات |
+|------|---------|
+| `WeeklyBalancePage.razor` | کمیسیون → پاداش |
+| `CommissionDashboardPage.razor` | کمیسیون → پاداش، PageTitle |
+| `MyPackages.razor` | کمیسیون → پاداش، مشاهده شبکه → مشاهده تیم |
+| `Packages.razor` | کمیسیون → پاداش |
+| `Index.razor` | شبکه‌سازی → تیم‌سازی، رشد میانگین شبکه → تیم |
+| `About.razor` | شبکه‌سازی → تیم‌سازی، شبکه‌های فروش → تیم‌های فروش |
+| `Footer.razor` | شبکه‌های فروش → تیم‌های فروش |
+| `NetworkStatisticsPage.razor` | آمار شبکه → آمار تیم |
+
+#### کلمات بدون تغییر (صحیح هستند):
+
+| کلمه | دلیل عدم تغییر |
+|------|---------------|
+| شبکه‌های اجتماعی | Social Networks - مرتبط با MLM نیست |
+| درخت دسته‌بندی‌ها | Category Tree - مرتبط با MLM نیست |
+| درخت شبکه (BackOffice) | پنل ادمین - نیاز به صراحت دارد |
+| زیرمجموعه (BackOffice) | پنل ادمین - نیاز به صراحت دارد |
+
+---
+
+## 📁 فایل‌های تغییر یافته
+
+### FrontOffice.BFF:
+```
+src/FrontOffice.BFF.Domain/Domain.csproj          # CMS proto v0.0.162
+src/BackOffice.BFF.Application/.../CommissionProfile.cs  # Carryover mapping
+src/Protobufs/commission.proto                    # Fields 11-14
+```
+
+### FrontOffice Client:
+```
+src/FrontOffice.Main/FrontOffice.Main.csproj      # Commission.Protobuf v0.0.6
+src/FrontOffice.Main/Utilities/CommissionDtos.cs  # New properties
+src/FrontOffice.Main/Utilities/CommissionService.cs # Server values
+src/FrontOffice.Main/Pages/Commission/CommissionDashboardPage.razor    # Merged + Responsive
+src/FrontOffice.Main/Pages/Commission/CommissionDashboardPage.razor.cs # Dual routes
+src/FrontOffice.Main/Pages/Commission/WeeklyBalancePage.razor          # UI + Terminology
+src/FrontOffice.Main/Pages/Package/MyPackages.razor                    # Terminology
+src/FrontOffice.Main/Pages/Store/Packages.razor                        # Terminology
+src/FrontOffice.Main/Pages/Index.razor                                 # Terminology
+src/FrontOffice.Main/Pages/About.razor                                 # Terminology
+src/FrontOffice.Main/Pages/Network/NetworkStatisticsPage.razor         # Terminology
+src/FrontOffice.Main/Shared/Footer.razor                               # Terminology
+```
+
+### فایل‌های حذف شده:
+```
+src/FrontOffice.Main/Pages/Commission/CommissionHistoryPage.razor      ❌
+src/FrontOffice.Main/Pages/Commission/CommissionHistoryPage.razor.cs   ❌
+```
+
+---
+
+## 🧪 تست و تأیید
+
+- ✅ صفحه weekly-balance مقادیر صحیح carryover نمایش می‌دهد
+- ✅ WeekSelector در داشبورد کار می‌کند
+- ✅ صفحات در موبایل responsive هستند
+- ✅ هر دو route به یک صفحه می‌روند
+- ✅ همه terminology ها تغییر کرده‌اند
+
+---
+
+## 📋 لیست کلمات MLM-حساس (مرجع)
+
+برای آینده، این کلمات در UI مشتری باید با دقت استفاده شوند:
+
+| کلمه حساس | جایگزین پیشنهادی | وضعیت |
+|-----------|-----------------|-------|
+| کمیسیون | پاداش | ✅ انجام شد |
+| شبکه‌سازی | تیم‌سازی | ✅ انجام شد |
+| شبکه (در context MLM) | تیم | ✅ انجام شد |
+| زیرمجموعه | اعضای تیم | ⏸️ فقط BackOffice |
+| درخت شبکه | نمودار سازمانی | ⏸️ فقط BackOffice |
+| شاخه چپ/راست | تیم اول/دوم | ✅ قبلاً انجام شده |
+| تعادل | امتیاز/جفت | ✅ قبلاً انجام شده |
+| سقف | حداکثر | ✅ قبلاً انجام شده |
+| Downline | اعضا | ⏸️ فقط BackOffice |
+| Binary Tree | ساختار تیم | ⏸️ فقط BackOffice |
+
+---
+
+## 🔗 Related Files
+
+- [`CHANGELOG-2025-12-27.md`](CHANGELOG-2025-12-27.md) - Session قبلی
+- [`04-FRONTEND/FrontOffice/README.md`](04-FRONTEND/FrontOffice/README.md) - مستندات FrontOffice
+- [`01-BUSINESS/network-commission-system.md`](01-BUSINESS/network-commission-system.md) - منطق تجاری کمیسیون