update

archive/TECHNICAL-NOTES.md

@@ -0,0 +1,230 @@
+# 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
+```