BackOffice/docs/TECHNICAL-NOTES.md

BackOffice Technical Notes

نکات فنی برای توسعه‌دهندگان

---

1. Mapster Mapping Patterns

1.1 Proto Types (Immutable)

برای proto types که immutable هستند، باید از MapWith استفاده کرد:

config.NewConfig<SourceDto, ProtoResponse>()
    .MapWith(src => new ProtoResponse
    {
        Field1 = src.Field1,
        Field2 = src.Field2 ?? string.Empty,
        RepeatedField = { src.List?.Select(x => new Item { ... }) ?? Enumerable.Empty<Item>() }
    });

1.2 Null-Safe MetaData

MetaData = src.MetaData != null ? new MetaData
{
    PageIndex = src.MetaData.PageIndex,
    TotalPages = src.MetaData.TotalPages,
    TotalCount = src.MetaData.TotalCount
} : null

1.3 Alias Imports برای Disambiguation

وقتی دو proto با نام یکسان داریم:

using BffProtos = BackOffice.BFF.ClubMembership.Protobuf.Protos.ClubMembership;
using CmsProtos = CMSMicroservice.Protobuf.Protos.ClubMembership;

// استفاده:
config.NewConfig<BffProtos.GetRequest, CmsProtos.GetRequest>();

1.4 PaginationState Mapping

config.NewConfig<BffRequest, AppQuery>()
    .Map(dest => dest.PaginationState, src => src.PaginationState);

---

2. MudBlazor 8 Breaking Changes

2.1 Dialog Instance

// ❌ قبلی
[CascadingParameter] MudDialogInstance MudDialog { get; set; }

// ✅ جدید
[CascadingParameter] IMudDialogInstance MudDialog { get; set; }

2.2 Generic Components

<!-- ❌ قبلی -->
<MudSwitch @bind-Value="isActive" />
<MudChip>Text</MudChip>

<!-- ✅ جدید -->
<MudSwitch T="bool" @bind-Value="isActive" />
<MudChip T="string">Text</MudChip>

2.3 Drag Events

<!-- ❌ قبلی -->
@ondragover="e => e.PreventDefault()"

<!-- ✅ جدید -->
@ondragover:preventDefault

2.4 File Upload

// FilesChanged حالا IBrowserFile می‌گیرد
<MudFileUpload T="IBrowserFile" FilesChanged="OnFileSelected">

---

3. gRPC Patterns

3.1 Service Override in BFF

public override async Task<GetResponse> GetData(GetRequest request, ServerCallContext context)
{
    return await _dispatchRequestToCQRS.Handle<GetRequest, GetQuery, GetResponse>(request, context);
}

3.2 CQRS Handler

public class GetQueryHandler : IRequestHandler<GetQuery, GetResponseDto>
{
    private readonly IApplicationContractContext _context;

    public async Task<GetResponseDto> Handle(GetQuery request, CancellationToken ct)
    {
        var cmsRequest = request.Adapt<CmsProtos.GetRequest>();
        var response = await _context.Service.GetAsync(cmsRequest, cancellationToken: ct);
        return response.Adapt<GetResponseDto>();
    }
}

---

4. Proto Update Checklist

هر تغییری در Proto نیاز به این مراحل دارد:

Step 1: Update Version

<!-- در .csproj -->
<Version>0.0.142</Version>  →  <Version>0.0.143</Version>

Step 2: Pack

cd path/to/proto/project
dotnet pack -c Release
# Push به GitLab Registry خودکار انجام می‌شود

Step 3: Update References

<PackageReference Include="Foursat.Proto" Version="0.0.143" />

Step 4: Build & Test

dotnet build
dotnet test

---

5. Common Fixes

5.1 Snackbar Duplicate Injection

اگر در _Imports.razor inject شده، در component نیاز نیست:

// ❌ حذف کن
[Inject] ISnackbar Snackbar { get; set; }

5.2 BasePageComponent Reload

private MudDataGrid<Model>? _gridData;

private async Task OnFilterSubmit()
{
    if (_gridData != null)
        await _gridData.ReloadServerData();
}

5.3 Nullable Wrapper Types

// Proto nullable types:
// google.protobuf.Int64Value → long?
// google.protobuf.BoolValue → bool?

// Set value:
request.UserId = userId;  // نه new Int64Value { Value = userId }

---

6. Build Commands

# Full Solution Build
cd /home/masoud/Apps/project/FourSat/BackOffice/src
dotnet build BackOffice.sln

# Single Project
dotnet build BackOffice/BackOffice.csproj

# With Restore
dotnet build --restore

# Clean Build
dotnet clean && dotnet build

# Check Errors Only
dotnet build 2>&1 | grep -E "error CS"

---

7. Project References

ProjectReference (Local Development):

<ProjectReference Include="../../../BackOffice.BFF/src/Protobufs/X.Protobuf/X.Protobuf.csproj" />

PackageReference (Production):

<PackageReference Include="Foursat.X.Protobuf" Version="0.0.143" />

---

8. File Organization

BackOffice/
├── docs/
│   ├── README.md           # Index
│   ├── STATUS.md           # Current Status
│   ├── CHANGELOG.md        # History
│   ├── TECHNICAL-NOTES.md  # This file
│   └── SESSION-*.md        # Session logs
├── src/
│   └── BackOffice/
│       ├── Pages/          # Blazor pages
│       ├── Services/       # gRPC clients
│       └── Common/         # Shared components