feat(transactions): add ledger transactions feature and update related components

- Introduced new ledger transactions page in NavMenu.razor and AppBreadcrumb.razor. - Enhanced ReportLabels.cs with transaction status and type labels. - Updated ConfigureService.cs to include TransactionsContractClient for gRPC. - Bumped Foursat.CMSMicroservice.Protobuf version to 0.0.203 for compatibility with new features. - Added deployment notes for June 1405 regarding read-only reports and proto updates.
2026-06-26 16:38:58 +03:30
parent 5a004e5c88
commit b53d9facc9
7 changed files with 307 additions and 2 deletions
@@ -4,7 +4,7 @@

 - **مسیر wrapper سرویس‌ها:** `BackOffice/src/BackOffice/Services/`
 - **ثبت gRPC:** `BackOffice/src/BackOffice/Common/Configure/ConfigureService.cs`
- **تاریخ:** ۱۴۰۵/۰۳/۱۷
+- **تاریخ:** ۱۴۰۵/۰۳/۱۷ (بروز: خرداد ۱۴۰۵ — گزارش‌های read-only + proto 0.0.201)

 ---

@@ -388,3 +388,18 @@ flowchart LR
 | Wallet | My balances | All users wallet + history log |

 مرجع مشابه برای فرانت مشتری: [`FrontOffice/docs/CUSTOMER-SERVICES.md`](../FrontOffice/docs/CUSTOMER-SERVICES.md)
+
+---
+
+## یادداشت deploy (خرداد ۱۴۰۵)
+
+| گام | جزئیات |
+|-----|--------|
+| Proto | `Foursat.CMSMicroservice.Protobuf` **0.0.201** |
+| CMS | deploy WebApi (شامل CQRS + gRPC گزارش‌ها) |
+| BackOffice | NuGet 0.0.201 یا ProjectReference در monorepo |
+| FrontOffice | **redeploy لازم نیست** — روی 0.0.199 می‌ماند؛ RPCهای admin در FO register نشده |
+
+گزارش‌های read-only (بخش ۱۰ و ۱۵): فقط فیلتر + grid + summary — بدون CRUD، detail dialog، یا لینک cross-page.
+
+مستندات فنی کامل: [`totalDoc/technical/TECH-08-SESSION-LOG-202606.md`](../../totalDoc/technical/TECH-08-SESSION-LOG-202606.md)
@@ -143,7 +143,7 @@
        <ProjectReference Include="../../../CMS/src/CMSMicroservice.Protobuf/CMSMicroservice.Protobuf.csproj" />
    </ItemGroup>
    <ItemGroup Condition="!Exists('../../../CMS/src/CMSMicroservice.Protobuf/CMSMicroservice.Protobuf.csproj')">
-        <PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="0.0.201" />
+        <PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="0.0.203" />
    </ItemGroup>
    
    <!-- ============================================================ -->
@@ -32,6 +32,7 @@ using CMSMicroservice.Protobuf.Protos.UserContract;
 using CMSMicroservice.Protobuf.Protos.UserWallet;
 using CMSMicroservice.Protobuf.Protos.UserWalletHistory;
 using CMSMicroservice.Protobuf.Protos.PaymentTransaction;
+using CMSMicroservice.Protobuf.Protos.Transactions;
 using CMSMicroservice.Protobuf.Protos.UserPackagePurchase;
 using CMSMicroservice.Protobuf.Protos.ClubMembershipCycle;
 using CMSMicroservice.Protobuf.Protos.ClubMembershipCycleHistory;
@@ -175,6 +176,7 @@ public static class ConfigureServices

        // Admin Report Services
        services.AddTransient(sp => new PaymentTransactionContract.PaymentTransactionContractClient(sp.GetRequiredService<CallInvoker>()));
+        services.AddTransient(sp => new TransactionsContract.TransactionsContractClient(sp.GetRequiredService<CallInvoker>()));
        services.AddTransient(sp => new UserPackagePurchaseContract.UserPackagePurchaseContractClient(sp.GetRequiredService<CallInvoker>()));
        services.AddTransient(sp => new ClubMembershipCycleContract.ClubMembershipCycleContractClient(sp.GetRequiredService<CallInvoker>()));
        services.AddTransient(sp => new ClubMembershipCycleHistoryContract.ClubMembershipCycleHistoryContractClient(sp.GetRequiredService<CallInvoker>()));
@@ -1,9 +1,44 @@
 namespace BackOffice.Common.Utilities;

+using CMSMicroservice.Protobuf.Protos;
+using MudBlazor;
+
 public static class ReportLabels
 {
    public static string GetPaymentStatusLabel(bool success) => success ? "موفق" : "در انتظار / ناموفق";

+    public static string GetTransactionPaymentStatusLabel(PaymentStatus? status) => status switch
+    {
+        PaymentStatus.Success => "موفق",
+        PaymentStatus.Pending => "در انتظار",
+        PaymentStatus.Reject => "رد شده",
+        _ => "—"
+    };
+
+    public static Color GetTransactionPaymentStatusColor(PaymentStatus? status) => status switch
+    {
+        PaymentStatus.Success => Color.Success,
+        PaymentStatus.Pending => Color.Warning,
+        PaymentStatus.Reject => Color.Error,
+        _ => Color.Default
+    };
+
+    public static string GetTransactionTypeLabel(TransactionType? type) => type switch
+    {
+        TransactionType.Buy => "خرید",
+        TransactionType.DepositIpg => "واریز درگاه",
+        TransactionType.DepositExternal1 => "واریز خارجی",
+        TransactionType.Withdraw => "برداشت",
+        TransactionType.NetworkCommission => "کمیسیون شبکه",
+        TransactionType.ClubActivation => "فعال‌سازی باشگاه",
+        TransactionType.DiscountWalletCharge => "شارژ کیف تخفیف",
+        TransactionType.DiscountShopPurchase => "خرید فروشگاه تخفیف",
+        TransactionType.MagicWalletDeposit => "واریز کیف جادویی",
+        TransactionType.MagicWalletBonus => "بونوس کیف جادویی",
+        TransactionType.CreditWalletCharge => "شارژ کیف اصلی",
+        _ => type?.ToString() ?? "—"
+    };
+
    public static string GetPurchaseMethodLabel(int method) => method switch
    {
        1 => "وام دایا",
@@ -0,0 +1,246 @@
+@page "/payment/ledger-transactions"
+@using BackOffice.Common.BaseComponents
+@using CMSMicroservice.Protobuf.Protos
+@using CMSMicroservice.Protobuf.Protos.Transactions
+@using Google.Protobuf.WellKnownTypes
+
+@inject TransactionsContract.TransactionsContractClient TransactionsClient
+
+<BasePageComponent @ref="_basePage" OnSubmitClick="OnFilterSubmit" OnClearFilterClick="OnFilterCleared">
+    <Filters>
+        <MudItem xs="12">
+            <MudAlert Severity="Severity.Info" Variant="Variant.Text" Dense="true">
+                گزارش read-only دفتر تراکنش‌های مالی (جدول Transactions). برای جزئیات درگاه پرداخت به «گزارش تراکنش درگاه» مراجعه کنید.
+            </MudAlert>
+        </MudItem>
+        <MudItem xs="12" sm="6" md="3">
+            <MudTextField T="long?" Label="شناسه" Variant="Variant.Outlined" Margin="Margin.Dense" @bind-Value="_id" />
+        </MudItem>
+        <MudItem xs="12" sm="6" md="3">
+            <MudTextField T="string" Label="RefId" Variant="Variant.Outlined" Margin="Margin.Dense" @bind-Value="_refId" />
+        </MudItem>
+        <MudItem xs="12" sm="6" md="3">
+            <MudTextField T="string" Label="توضیحات" Variant="Variant.Outlined" Margin="Margin.Dense" @bind-Value="_description" />
+        </MudItem>
+        <MudItem xs="12" sm="6" md="3">
+            <MudSelect T="PaymentStatus?" Clearable="true" Label="وضعیت پرداخت" Variant="Variant.Outlined"
+                       Margin="Margin.Dense" @bind-Value="_paymentStatus">
+                <MudSelectItem T="PaymentStatus?" Value="PaymentStatus.Success">موفق</MudSelectItem>
+                <MudSelectItem T="PaymentStatus?" Value="PaymentStatus.Pending">در انتظار</MudSelectItem>
+                <MudSelectItem T="PaymentStatus?" Value="PaymentStatus.Reject">رد شده</MudSelectItem>
+            </MudSelect>
+        </MudItem>
+        <MudItem xs="12" sm="6" md="3">
+            <MudSelect T="TransactionType?" Clearable="true" Label="نوع تراکنش" Variant="Variant.Outlined"
+                       Margin="Margin.Dense" @bind-Value="_type">
+                <MudSelectItem T="TransactionType?" Value="TransactionType.Buy">خرید</MudSelectItem>
+                <MudSelectItem T="TransactionType?" Value="TransactionType.DepositIpg">واریز درگاه</MudSelectItem>
+                <MudSelectItem T="TransactionType?" Value="TransactionType.DepositExternal1">واریز خارجی</MudSelectItem>
+                <MudSelectItem T="TransactionType?" Value="TransactionType.Withdraw">برداشت</MudSelectItem>
+                <MudSelectItem T="TransactionType?" Value="TransactionType.NetworkCommission">کمیسیون شبکه</MudSelectItem>
+                <MudSelectItem T="TransactionType?" Value="TransactionType.ClubActivation">فعال‌سازی باشگاه</MudSelectItem>
+                <MudSelectItem T="TransactionType?" Value="TransactionType.DiscountWalletCharge">شارژ کیف تخفیف</MudSelectItem>
+                <MudSelectItem T="TransactionType?" Value="TransactionType.DiscountShopPurchase">خرید فروشگاه تخفیف</MudSelectItem>
+                <MudSelectItem T="TransactionType?" Value="TransactionType.MagicWalletDeposit">واریز کیف جادویی</MudSelectItem>
+                <MudSelectItem T="TransactionType?" Value="TransactionType.MagicWalletBonus">بونوس کیف جادویی</MudSelectItem>
+                <MudSelectItem T="TransactionType?" Value="TransactionType.CreditWalletCharge">شارژ کیف اصلی</MudSelectItem>
+            </MudSelect>
+        </MudItem>
+        <MudItem xs="12" sm="6" md="4">
+            <DateRangePicker @bind-From="_createdFrom" @bind-To="_createdTo" Label="بازه ثبت" />
+        </MudItem>
+    </Filters>
+    <Content>
+        <MudGrid Class="mb-3" Spacing="2">
+            <MudItem xs="6" sm="3">
+                <MudPaper Class="pa-3" Outlined="true">
+                    <MudText Typo="Typo.caption" Color="Color.Secondary">تعداد</MudText>
+                    <MudText Typo="Typo.h6">@_summaryTotalCount.ToString("N0")</MudText>
+                </MudPaper>
+            </MudItem>
+            <MudItem xs="6" sm="3">
+                <MudPaper Class="pa-3" Outlined="true">
+                    <MudText Typo="Typo.caption" Color="Color.Secondary">جمع مبلغ (تومان)</MudText>
+                    <MudText Typo="Typo.h6">@_summaryTotalAmount.ToString("N0")</MudText>
+                </MudPaper>
+            </MudItem>
+            <MudItem xs="6" sm="2">
+                <MudPaper Class="pa-3" Outlined="true">
+                    <MudText Typo="Typo.caption" Color="Color.Secondary">موفق</MudText>
+                    <MudText Typo="Typo.h6" Color="Color.Success">@_summarySuccess.ToString("N0")</MudText>
+                </MudPaper>
+            </MudItem>
+            <MudItem xs="6" sm="2">
+                <MudPaper Class="pa-3" Outlined="true">
+                    <MudText Typo="Typo.caption" Color="Color.Secondary">در انتظار</MudText>
+                    <MudText Typo="Typo.h6" Color="Color.Warning">@_summaryPending.ToString("N0")</MudText>
+                </MudPaper>
+            </MudItem>
+            <MudItem xs="6" sm="2">
+                <MudPaper Class="pa-3" Outlined="true">
+                    <MudText Typo="Typo.caption" Color="Color.Secondary">رد شده</MudText>
+                    <MudText Typo="Typo.h6" Color="Color.Error">@_summaryReject.ToString("N0")</MudText>
+                </MudPaper>
+            </MudItem>
+        </MudGrid>
+
+        <MudDataGrid @ref="_dataGrid" T="GetAllTransactionsByFilterResponseModel"
+                     ServerData="LoadData" ReadOnly="true"
+                     Hover="true" Dense="true" Height="calc(100vh - 400px)">
+            <ToolBarContent>
+                <MudText Typo="Typo.subtitle1">دفتر تراکنش‌های مالی</MudText>
+                <MudSpacer />
+                <MudButton Variant="Variant.Outlined" Color="Color.Info" Size="Size.Small"
+                           StartIcon="@Icons.Material.Filled.FileDownload" OnClick="ExportCsv">CSV</MudButton>
+            </ToolBarContent>
+            <Columns>
+                <PropertyColumn Property="x => x.Id" Title="شناسه" />
+                <TemplateColumn Title="نوع">
+                    <CellTemplate>
+                        <MudChip T="string" Size="Size.Small" Variant="Variant.Text">
+                            @ReportLabels.GetTransactionTypeLabel(context.Item.HasType ? context.Item.Type : null)
+                        </MudChip>
+                    </CellTemplate>
+                </TemplateColumn>
+                <TemplateColumn Title="مبلغ (تومان)">
+                    <CellTemplate>@context.Item.Amount.ToString("N0")</CellTemplate>
+                </TemplateColumn>
+                <PropertyColumn Property="x => x.Description" Title="توضیحات" />
+                <TemplateColumn Title="وضعیت">
+                    <CellTemplate>
+                        <MudChip T="string" Size="Size.Small" Color="@ReportLabels.GetTransactionPaymentStatusColor(context.Item.HasPaymentStatus ? context.Item.PaymentStatus : null)">
+                            @ReportLabels.GetTransactionPaymentStatusLabel(context.Item.HasPaymentStatus ? context.Item.PaymentStatus : null)
+                        </MudChip>
+                    </CellTemplate>
+                </TemplateColumn>
+                <PropertyColumn Property="x => x.RefId" Title="RefId" />
+                <TemplateColumn Title="تاریخ پرداخت">
+                    <CellTemplate>
+                        @(context.Item.PaymentDate != null
+                            ? context.Item.PaymentDate.ToDateTime().ToLocalTime().MiladiToJalaliWithTime()
+                            : "—")
+                    </CellTemplate>
+                </TemplateColumn>
+                <TemplateColumn Title="تاریخ ثبت">
+                    <CellTemplate>@context.Item.Created.ToDateTime().ToLocalTime().MiladiToJalaliWithTime()</CellTemplate>
+                </TemplateColumn>
+            </Columns>
+            <NoRecordsContent>
+                <MudAlert Severity="Severity.Info" Dense="true" Variant="Variant.Text" Class="my-4">
+                    با فیلتر فعلی موردی یافت نشد — بازه تاریخ یا فیلترها را تغییر دهید.
+                </MudAlert>
+            </NoRecordsContent>
+            <PagerContent>
+                <MudDataGridPager T="GetAllTransactionsByFilterResponseModel" PageSizeOptions="@(new int[] { 20, 50, 100 })"
+                                  InfoFormat="سطر {first_item} تا {last_item} از {all_items}"
+                                  RowsPerPageString="تعداد در صفحه" />
+            </PagerContent>
+        </MudDataGrid>
+    </Content>
+</BasePageComponent>
+
+@code {
+    private BasePageComponent? _basePage;
+    private MudDataGrid<GetAllTransactionsByFilterResponseModel>? _dataGrid;
+    private long? _id;
+    private string? _refId, _description;
+    private PaymentStatus? _paymentStatus;
+    private TransactionType? _type;
+    private DateTime? _createdFrom, _createdTo;
+    private long _summaryTotalCount, _summaryTotalAmount, _summarySuccess, _summaryPending, _summaryReject;
+
+    private GetAllTransactionsByFilterFilter BuildFilter()
+    {
+        var filter = new GetAllTransactionsByFilterFilter
+        {
+            Id = _id > 0 ? _id : null,
+            RefId = string.IsNullOrWhiteSpace(_refId) ? null : _refId,
+            Description = string.IsNullOrWhiteSpace(_description) ? null : _description,
+            CreatedFrom = _createdFrom.HasValue ? Timestamp.FromDateTime(DateTime.SpecifyKind(_createdFrom.Value, DateTimeKind.Utc)) : null,
+            CreatedTo = _createdTo.HasValue ? Timestamp.FromDateTime(DateTime.SpecifyKind(_createdTo.Value.Date.AddDays(1).AddTicks(-1), DateTimeKind.Utc)) : null
+        };
+
+        if (_paymentStatus.HasValue)
+            filter.PaymentStatus = _paymentStatus.Value;
+        else
+            filter.ClearPaymentStatusItem();
+
+        if (_type.HasValue)
+            filter.Type = _type.Value;
+        else
+            filter.ClearTypeItem();
+
+        return filter;
+    }
+
+    private async Task LoadSummary()
+    {
+        try
+        {
+            var s = await TransactionsClient.GetTransactionSummaryAsync(new GetTransactionSummaryRequest { Filter = BuildFilter() });
+            _summaryTotalCount = s.TotalCount;
+            _summaryTotalAmount = s.TotalAmount;
+            _summarySuccess = s.SuccessCount;
+            _summaryPending = s.PendingCount;
+            _summaryReject = s.RejectCount;
+        }
+        catch { }
+    }
+
+    private async Task<GridData<GetAllTransactionsByFilterResponseModel>> LoadData(GridState<GetAllTransactionsByFilterResponseModel> state)
+    {
+        try
+        {
+            await LoadSummary();
+            var result = await TransactionsClient.GetAllTransactionsByFilterAsync(new GetAllTransactionsByFilterRequest
+            {
+                PaginationState = new PaginationState { PageNumber = state.Page + 1, PageSize = state.PageSize },
+                SortBy = "-Created",
+                Filter = BuildFilter()
+            });
+            return new GridData<GetAllTransactionsByFilterResponseModel>
+            {
+                Items = result?.Models?.ToList() ?? new(),
+                TotalItems = (int)(result?.MetaData?.TotalCount ?? 0)
+            };
+        }
+        catch (Exception ex)
+        {
+            Snackbar.Add($"خطا: {ex.Message}", Severity.Error);
+            return new GridData<GetAllTransactionsByFilterResponseModel>();
+        }
+    }
+
+    private async Task OnFilterSubmit() { if (_dataGrid != null) await _dataGrid.ReloadServerData(); }
+    private async Task OnFilterCleared()
+    {
+        _id = null; _refId = _description = null;
+        _paymentStatus = null; _type = null;
+        _createdFrom = _createdTo = null;
+        if (_dataGrid != null) await _dataGrid.ReloadServerData();
+    }
+
+    private async Task ExportCsv()
+    {
+        try
+        {
+            var result = await TransactionsClient.GetAllTransactionsByFilterAsync(new GetAllTransactionsByFilterRequest
+            {
+                PaginationState = new PaginationState { PageNumber = 1, PageSize = 5000 },
+                SortBy = "-Created",
+                Filter = BuildFilter()
+            });
+            var sb = new System.Text.StringBuilder();
+            sb.AppendLine("Id,Type,Amount,Description,Status,RefId,PaymentDate,Created");
+            foreach (var r in result.Models)
+            {
+                var type = r.HasType ? ReportLabels.GetTransactionTypeLabel(r.Type) : "";
+                var status = r.HasPaymentStatus ? ReportLabels.GetTransactionPaymentStatusLabel(r.PaymentStatus) : "";
+                var paymentDate = r.PaymentDate != null ? r.PaymentDate.ToDateTime().ToString("yyyy-MM-dd HH:mm") : "";
+                sb.AppendLine($"{r.Id},{type},{r.Amount},\"{r.Description}\",{status},{r.RefId},{paymentDate},{r.Created.ToDateTime():yyyy-MM-dd HH:mm}");
+            }
+            await jsRuntime.InvokeVoidAsync("jsSaveAsFile", "ledger-transactions.csv", sb.ToString());
+        }
+        catch (Exception ex) { Snackbar.Add($"خطا در export: {ex.Message}", Severity.Error); }
+    }
+}
@@ -96,6 +96,7 @@
            // Payment
            "payment" => "پرداخت",
            "transactions" => "تراکنش‌ها",
+            "ledger-transactions" => "دفتر تراکنش‌های مالی",
            "manual-payments" => "پرداخت دستی",

            // Network
@@ -206,6 +206,12 @@
                گزارش تراکنش درگاه
            </MudNavLink>

+            <MudNavLink Match="NavLinkMatch.Prefix"
+                        Href="/payment/ledger-transactions"
+                        Icon="@Icons.Material.Filled.AccountBalance">
+                دفتر تراکنش‌های مالی
+            </MudNavLink>
+
            <MudNavLink Match="NavLinkMatch.Prefix"
                        Href="/wallets"
                        Icon="@Icons.Material.Filled.AccountBalanceWallet">