docs/CHANGELOG-2025-12-29.md

📝 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 جدید:

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 ساده.

پیاده‌سازی:

<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:

<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

@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 - Session قبلی
• 04-FRONTEND/FrontOffice/README.md - مستندات FrontOffice
• 01-BUSINESS/network-commission-system.md - منطق تجاری کمیسیون