docs/CHANGELOG-2025-12-26.md

📝 Changelog - ۶ دی ۱۴۰۴ (26 December 2025)

Session: سیستم مدیریت نسخه اپلیکیشن (App Version Management) + نمایش کد معرف در درخت شبکه

---

🎯 خلاصه Session

این session شامل موارد زیر بود:

1. App Version Management - سیستم کامل مدیریت نسخه اپلیکیشن‌های موبایل
2. ReferralCode در NetworkTree - نمایش کد معرف در درخت شبکه FrontOffice
3. BackOffice UI - صفحه مدیریت نسخه‌ها در پنل ادمین

---

✨ New Features

1. 📱 سیستم مدیریت نسخه اپلیکیشن (App Version Management) ✅

نیاز: مدیریت نسخه‌های اپلیکیشن‌های موبایل و کنترل به‌روزرسانی اجباری

معماری:

┌─────────────────────────────────────────────────────────────┐
│                     Flow Diagram                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  BackOffice UI ──(gRPC)──► BackOffice.BFF ──(gRPC)──► CMS  │
│     (Blazor)              (API Gateway)        (Database)  │
│                                                             │
│  /settings/app-versions   AppVersionService   AppVersions  │
│                                                  Table      │
└─────────────────────────────────────────────────────────────┘

---

1.1 CMS Layer (Database + gRPC) ✅

Entity: AppVersion.cs (موجود)

public class AppVersion : BaseAuditableEntity
{
    public string AppName { get; set; }           // FoursatMarketApp, FoursatClubApp
    public string CurrentVersion { get; set; }    // 1.2.0
    public string MinRequiredVersion { get; set; } // 1.0.0
    public bool RequiresFullCacheClear { get; set; }
    public string UpdateMessage { get; set; }
    public string ReleaseNotes { get; set; }
    public bool IsActive { get; set; }
}

Protobuf: appversion.proto

service AppVersionContract {
    rpc GetAllAppVersions(GetAllAppVersionsRequest) returns (GetAllAppVersionsResponse);
    rpc GetAppVersion(GetAppVersionRequest) returns (GetAppVersionResponse);
    rpc UpdateAppVersion(UpdateAppVersionRequest) returns (google.protobuf.Empty);
}

فایل‌ها:

• CMSMicroservice.Protobuf/Protos/appversion.proto
• CMSMicroservice.WebApi/Services/AppVersionService.cs
• پکیج NuGet: CMSMicroservice.Protobuf v0.0.159

---

1.2 BackOffice.BFF Layer ✅

Protobuf اختصاصی: BackOffice.BFF.Configuration.Protobuf/Protos/appversion.proto

option csharp_namespace = "BackOffice.BFF.Configuration.Protobuf.Protos.AppVersion";

service AppVersionContract {
    rpc GetAllAppVersions(GetAllAppVersionsRequest) returns (GetAllAppVersionsResponse) {
        option (google.api.http) = { get: "/AppVersion/GetAll" };
    };
    rpc GetAppVersion(GetAppVersionRequest) returns (GetAppVersionResponse) {
        option (google.api.http) = { get: "/AppVersion/Get" };
    };
    rpc UpdateAppVersion(UpdateAppVersionRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = { post: "/AppVersion/Update" body: "*" };
    };
}

CQRS Components:

Component	Path	Description
GetAllAppVersionsQuery	ConfigurationCQ/Queries/	Query با IncludeInactive
GetAllAppVersionsResponseDto	ConfigurationCQ/Queries/	Response DTO با لیست آیتم‌ها
GetAllAppVersionsQueryHandler	ConfigurationCQ/Queries/	Handler که CMS رو کال می‌کنه
UpdateAppVersionCommand	ConfigurationCQ/Commands/	Command برای آپدیت
UpdateAppVersionCommandHandler	ConfigurationCQ/Commands/	Handler که CMS رو کال می‌کنه

gRPC Service: AppVersionService.cs

public class AppVersionService : AppVersionContract.AppVersionContractBase
{
    public override async Task<GetAllAppVersionsResponse> GetAllAppVersions(...)
    public override async Task<GetAppVersionResponse> GetAppVersion(...)
    public override async Task<Empty> UpdateAppVersion(...)
}

Mapster Profile: AppVersionProfile.cs

فایل‌های جدید:

• src/BackOffice.BFF.Application/ConfigurationCQ/Queries/GetAllAppVersions/*
• src/BackOffice.BFF.Application/ConfigurationCQ/Commands/UpdateAppVersion/*
• src/BackOffice.BFF.WebApi/Services/AppVersionService.cs
• src/BackOffice.BFF.WebApi/Common/Mappings/AppVersionProfile.cs
• src/Protobufs/BackOffice.BFF.Configuration.Protobuf/Protos/appversion.proto

پکیج NuGet: Foursat.BackOffice.BFF.Configuration.Protobuf v1.0.20

---

1.3 BackOffice UI (Blazor) ✅

مسیر صفحه: /settings/app-versions

Service Layer:

IAppVersionService.cs:

public interface IAppVersionService
{
    Task<List<AppVersionDto>> GetAllAsync(bool includeInactive = false);
    Task<AppVersionDto?> GetByNameAsync(string appName);
    Task UpdateAsync(UpdateAppVersionDto dto);
}

AppVersionDto.cs:

public class AppVersionDto
{
    public long Id { get; set; }
    public string AppName { get; set; }
    public string AppNameDisplay { get; }  // ترجمه فارسی
    public string CurrentVersion { get; set; }
    public string MinRequiredVersion { get; set; }
    public bool RequiresFullCacheClear { get; set; }
    public string UpdateMessage { get; set; }
    public string ReleaseNotes { get; set; }
    public bool IsActive { get; set; }
    public DateTime? Created { get; set; }
    public DateTime? LastModified { get; set; }
}

UI Components:

Component	Description
AppVersions.razor	صفحه اصلی با جدول و کارت‌ها
AppVersionEditDialog.razor	Dialog ویرایش نسخه

ویژگی‌های صفحه:

• 📋 جدول MudDataGrid با اطلاعات همه نسخه‌ها
• 🔍 فیلتر نمایش نسخه‌های غیرفعال
• 🃏 کارت خلاصه برای هر اپلیکیشن فعال
• ✏️ ویرایش با Dialog شامل:
  • نسخه فعلی
  • حداقل نسخه مورد نیاز
  • نیاز به پاکسازی کش
  • پیام به‌روزرسانی
  • یادداشت‌های انتشار
  • دلیل تغییر (برای لاگ)

فایل‌های جدید:

• Services/AppVersion/IAppVersionService.cs
• Services/AppVersion/AppVersionService.cs
• Pages/Settings/AppVersions.razor
• Pages/Settings/Components/AppVersionEditDialog.razor

تغییرات در فایل‌های موجود:

• Common/Configure/ConfigureService.cs - ثبت service و gRPC client
• BackOffice.csproj - آپدیت پکیج به v1.0.20

---

2. 🔗 نمایش کد معرف در درخت شبکه FrontOffice ✅

نیاز: نمایش کد معرف افرادی که در باشگاه فعالند کنار هر نود

تغییرات:

2.1 CMS - Stored Procedure

SP_GetNetworkTree.sql - فیلد ReferralCode اضافه شده:

SELECT 
    ...
    u.ReferralCode,
    ...
FROM NetworkTree_CTE t
JOIN AspNetUsers u ON t.UserId = u.Id

2.2 FrontOffice DTOs

NetworkMembershipDtos.cs:

public class NetworkNodeDto
{
    // ... existing fields
    public string? ReferralCode { get; set; }  // جدید
}

public class FlatNetworkNodeDto
{
    // ... existing fields
    public string? ReferralCode { get; set; }  // جدید
}

2.3 JavaScript - org-chart.js

// فقط برای کاربران فعال باشگاه نمایش بده
${d.isClubActive && d.referralCode ? `
    <div class="node-referral">
        <span class="referral-label">کد معرف:</span>
        <span class="referral-code">${d.referralCode}</span>
        <button class="copy-btn" onclick="copyReferralCode('${d.referralCode}', event)">
            <i class="fas fa-copy"></i>
        </button>
    </div>
` : ''}

2.4 CSS - org-chart.css

.node-referral {
    display: flex;
    align-items: center;
    gap: 4px;
    margin-top: 4px;
    padding: 3px 6px;
    background: rgba(76, 175, 80, 0.1);
    border-radius: 4px;
    font-size: 11px;
}

.referral-code {
    font-weight: bold;
    color: #4CAF50;
    font-family: monospace;
}

.copy-btn {
    background: transparent;
    border: none;
    cursor: pointer;
    padding: 2px;
    color: #666;
}

.copy-toast {
    position: fixed;
    bottom: 20px;
    left: 50%;
    transform: translateX(-50%);
    background: #333;
    color: white;
    padding: 8px 16px;
    border-radius: 4px;
    z-index: 10000;
}

فایل‌های تغییر یافته:

• FrontOffice/Utilities/NetworkMembershipDtos.cs
• FrontOffice/Utilities/NetworkMembershipService.cs
• FrontOffice/wwwroot/js/org-chart.js
• FrontOffice/wwwroot/css/org-chart.css

---

📦 Package Updates

Package	From	To	Project
CMSMicroservice.Protobuf	0.0.156	0.0.159	BackOffice.BFF.Domain
Foursat.BackOffice.BFF.Configuration.Protobuf	1.0.7	1.0.20	BackOffice

---

🗄️ Git Commits

BackOffice.BFF

commit 6bc45e4
feat(bff): Add App Version management endpoints

- Add appversion.proto with GetAll, Get, Update RPCs
- Add GetAllAppVersionsQuery and handler
- Add UpdateAppVersionCommand and handler
- Add AppVersionService gRPC service
- Add AppVersionProfile for Mapster mappings
- Update IApplicationContractContext with AppVersions client
- Bump Configuration.Protobuf to 1.0.20

BackOffice

commit 6b140c3
feat(backoffice): Add App Version management UI

- Add IAppVersionService interface and implementation
- Add AppVersions.razor page for managing app versions
- Add AppVersionEditDialog component for editing versions
- Register AppVersion gRPC client and service in DI
- Update Foursat.BackOffice.BFF.Configuration.Protobuf to 1.0.20

CMS

commit bca3b7f
feat: Add ReferralCode to NetworkTree and NetworkMembershipProfile

- Add ReferralCode to SP_GetNetworkTree stored procedure
- Map ReferralCode in NetworkMembershipProfile
- Update networkmembership.proto with referral_code field

---

✅ Build Status

# CMS
cd /home/masoud/Apps/project/FourSat/CMS/src
dotnet build CMSMicroservice.WebApi/CMSMicroservice.WebApi.csproj
# Result: Build succeeded. 0 Error(s)

# BackOffice.BFF
cd /home/masoud/Apps/project/FourSat/BackOffice.BFF/src
dotnet build BackOffice.BFF.WebApi/BackOffice.BFF.WebApi.csproj
# Result: Build succeeded. 200 Warning(s), 0 Error(s)

# BackOffice
cd /home/masoud/Apps/project/FourSat/BackOffice/src
dotnet build BackOffice/BackOffice.csproj
# Result: Build succeeded. 246 Warning(s), 0 Error(s)

---

📊 آمار Session

متریک	مقدار
فایل‌های جدید	12
فایل‌های تغییر یافته	10
قابلیت‌های جدید	2
خطوط کد اضافه شده	~1000
پکیج‌های NuGet آپدیت شده	2
Commits	3

---

📍 مسیرهای دسترسی

Feature	URL	Project
مدیریت نسخه اپ‌ها	/settings/app-versions	BackOffice
درخت شبکه با کد معرف	/profile/tree	FrontOffice

---

⚠️ یادآوری‌ها

1. Stored Procedure: اسکریپت SP_GetNetworkTree.sql باید روی دیتابیس production اجرا شود
2. منوی BackOffice: صفحه /settings/app-versions در منوی سایدبار اضافه نشده - در صورت نیاز NavMenu.razor آپدیت شود

---

🔗 Related Changelogs

• CHANGELOG-2025-12-25.md - درخت شبکه BackOffice با d3-org-chart
• CHANGELOG-2025-12-23.md - پیاده‌سازی Worker چتیکا