add: implement Sepehr payment gateway integration and enhance financial invoice handling

CompanyManagment.App.Contracts/FinancialInvoice/CreateFinancialInvoice.cs

@@ -8,7 +8,7 @@ public class CreateFinancialInvoice
     public double Amount { get; set; }
     public long ContractingPartyId { get; set; }
     public string Description { get; set; }
-    public List<CreateFinancialInvoiceItem>? Items { get; set; }
+    public List<CreateFinancialInvoiceItem> Items { get; set; }
 }
 
 public class CreateFinancialInvoiceItem

CompanyManagment.App.Contracts/FinancialStatment/IFinancialStatmentApplication.cs

@@ -6,6 +6,7 @@ using System.Collections.Generic;
 using System.Linq;
 using System.Text;
 using System.Threading.Tasks;
+using CompanyManagment.App.Contracts.SepehrPaymentGateway;
 
 namespace CompanyManagment.App.Contracts.FinancialStatment;
 
@@ -62,7 +63,17 @@ public interface IFinancialStatmentApplication
     /// <returns></returns>
     Task<FinancialStatmentDetailsByContractingPartyViewModel> GetDetailsByContractingParty(long contractingPartyId,
         FinancialStatementSearchModel searchModel);
+
+    /// <summary>
+    /// پردازش شارژ حساب از طریق درگاه پرداخت سپهر
+    /// </summary>
+    /// <param name="request"></param>
+    /// <param name="gateWayCallBackUrl">مسیر برگشت درگاه پرداخت</param>
+    /// 
+    Task<OperationResult<CreateSepehrPaymentGatewayResponse>> CreatePaymentGateWayAndCreateInvoice(
+        CreateFinancialPayRequest request, string gateWayCallBackUrl);
 }
+public record CreateFinancialPayRequest(long Id,  string BaseUrl);
 
 public class FinancialStatmentDetailsByContractingPartyViewModel
 {

CompanyManagment.App.Contracts/SepehrPaymentGateway/CreateSepehrPaymentGatewayResponse.cs

@@ -0,0 +1,22 @@
+namespace CompanyManagment.App.Contracts.SepehrPaymentGateway;
+
+/// <summary>
+/// پاسخ ایجاد درگاه پرداخت سپهر
+/// </summary>
+public class CreateSepehrPaymentGatewayResponse
+{
+    /// <summary>
+    /// توکن درگاه
+    /// </summary>
+    public string Token { get; set; }
+
+    /// <summary>
+    /// شناسه تراکنش
+    /// </summary>
+    public long TransactionId { get; set; }
+
+    /// <summary>
+    /// URL درگاه پرداخت
+    /// </summary>
+    public string PaymentUrl { get; set; }
+}

CompanyManagment.App.Contracts/SepehrPaymentGateway/ISepehrPaymentGatewayService.cs

@@ -0,0 +1,32 @@
+using _0_Framework.Application;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace CompanyManagment.App.Contracts.SepehrPaymentGateway;
+
+/// <summary>
+/// رابط برای سرویس مشترک ایجاد درگاه پرداخت سپهر
+/// </summary>
+public interface ISepehrPaymentGatewayService
+{
+    /// <summary>
+    /// ایجاد درگاه پرداخت سپهر برای یک تراکنش
+    /// </summary>
+    /// <param name="amount">مبلغ</param>
+    /// <param name="contractingPartyId">شناسه طرف قرارداد</param>
+    /// <param name="frontCallbackUrl">آدرس بازگشتی به فرانت برای نمایش نتیجه</param>
+    /// <param name="gatewayCallbackUrl">آدرس بازگشتی درگاه پرداخت</param>
+    /// <param name="financialInvoiceId">شناسه فاکتور مالی (اختیاری) - این پارامتر مستقیماً به درگاه فرستاده می‌شود</param>
+    /// <param name="extraData">داده‌های اضافی سفارشی برای payload (اختیاری)</param>
+    /// <param name="cancellationToken">توکن لغو</param>
+    /// <returns>شامل Token درگاه یا OperationResult با خطا</returns>
+    Task<OperationResult<CreateSepehrPaymentGatewayResponse>> CreateSepehrPaymentGateway(
+        double amount,
+        long contractingPartyId,
+        long financialInvoiceId,
+        string gatewayCallbackUrl,
+        string frontCallbackUrl="https://client.gozareshgir.ir",
+        Dictionary<string, object> extraData = null,
+        CancellationToken cancellationToken = default);
+}