BackOffice/docs/TECHNICAL-NOTES.md

# BackOffice Technical Notes

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

---

## 1. Mapster Mapping Patterns

### 1.1 Proto Types (Immutable)
برای proto types که immutable هستند، باید از `MapWith` استفاده کرد:

```csharp
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
```csharp
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 با نام یکسان داریم:

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

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

### 1.4 PaginationState Mapping
```csharp
config.NewConfig<BffRequest, AppQuery>()
    .Map(dest => dest.PaginationState, src => src.PaginationState);
```

---

## 2. MudBlazor 8 Breaking Changes

### 2.1 Dialog Instance
```csharp
// ❌ قبلی
[CascadingParameter] MudDialogInstance MudDialog { get; set; }

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

### 2.2 Generic Components
```razor
<!-- ❌ قبلی -->
<MudSwitch @bind-Value="isActive" />
<MudChip>Text</MudChip>

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

### 2.3 Drag Events
```razor
<!-- ❌ قبلی -->
@ondragover="e => e.PreventDefault()"

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

### 2.4 File Upload
```csharp
// FilesChanged حالا IBrowserFile می‌گیرد
<MudFileUpload T="IBrowserFile" FilesChanged="OnFileSelected">
```

---

## 3. gRPC Patterns

### 3.1 Service Override in BFF
```csharp
public override async Task<GetResponse> GetData(GetRequest request, ServerCallContext context)
{
    return await _dispatchRequestToCQRS.Handle<GetRequest, GetQuery, GetResponse>(request, context);
}
```

### 3.2 CQRS Handler
```csharp
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
```xml
<!-- در .csproj -->
<Version>0.0.142</Version>  →  <Version>0.0.143</Version>
```

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

### Step 3: Update References
```xml
<PackageReference Include="Foursat.Proto" Version="0.0.143" />
```

### Step 4: Build & Test
```bash
dotnet build
dotnet test
```

---

## 5. Common Fixes

### 5.1 Snackbar Duplicate Injection
اگر در `_Imports.razor` inject شده، در component نیاز نیست:
```csharp
// ❌ حذف کن
[Inject] ISnackbar Snackbar { get; set; }
```

### 5.2 BasePageComponent Reload
```csharp
private MudDataGrid<Model>? _gridData;

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

### 5.3 Nullable Wrapper Types
```csharp
// Proto nullable types:
// google.protobuf.Int64Value → long?
// google.protobuf.BoolValue → bool?

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

---

## 6. Build Commands

```bash
# 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):
```xml
<ProjectReference Include="../../../BackOffice.BFF/src/Protobufs/X.Protobuf/X.Protobuf.csproj" />
```

### PackageReference (Production):
```xml
<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
```