‫طراحی سیستم‌های مالی ایرانی با واحد پولی جدید

• ۱ ریال جدید = ۱۰۰ قِران.
• ۱ قِران = ۰.۰۱ ریال جدید.

• چون ۱ ریال جدید = ۱۰,۰۰۰ ریال فعلی، بنابراین:
• ۱ قِران = ۱۰۰ ریال فعلی (محاسبه: ۱۰,۰۰۰ ÷ ۱۰۰ = ۱۰۰).

• چون ۱ تومان = ۱۰ ریال فعلی، بنابراین:
• ۱ قِران = ۱۰ تومان.

• تراکنش‌های خرد: قِران برای پرداخت‌های کوچک (مثل خریدهای روزمره، کرایه تاکسی، یا هزینه‌های جزئی) استفاده می‌شود.
• جایگزینی اعشار: قِران جایگزین اعشار در محاسبات مالی با ریال جدید است، مشابه نقش سنت یا پنی در سیستم‌های پولی دیگر.
• دوره گذار: در دوره گذار سه‌ساله (تا حدود ۱۴۰۷ شمسی)، قِران در کنار ریال فعلی و ریال جدید استفاده خواهد شد و به‌عنوان واحد خرد در کنار آن‌ها استفاده می‌شود. بنابراین، سیستم باید بتواند تبدیل‌های قِران به هر دو واحد (ریال جدید و ریال فعلی) و همچنین به تومان (به دلیل استفاده محاوره‌ای) را پشتیبانی کند.

• مثال: اگر قیمت یک کالا ۲۵۰,۰۰۰ ریال فعلی باشد، معادل ۲۵ ریال جدید یا ۲,۵۰۰ قران است. شما باید این مقدار را به صورت 2500 در پایگاه داده ذخیره کنید.

• چرا decimal؟ نوع داده decimal به طور خاص برای محاسبات دقیق مالی طراحی شده و از مشکلات دقت شناور (Floating-point Precision) که در انواع float یا double وجود دارد، جلوگیری می‌کند. این امر در سیستم‌های مالی که حتی کوچک‌ترین خطا نیز می‌تواند منجر به مشکلات بزرگ شود، حیاتی است.

public class Invoice
{
    public int Id { get; set; }
    
    // Store the total amount in Qeran to maintain consistency
    public decimal TotalAmountInQeran { get; set; } 
    
    // Other properties...
}

• لایه منطق برنامه (Business Logic Layer): تمامی محاسبات (جمع، تفریق، ضرب، تقسیم) باید با استفاده از واحد پایه (قران) انجام شوند.
• لایه نمایش (Presentation Layer): در زمان نمایش به کاربر، از توابع کمکی (Helper Functions) برای تبدیل مقدار ذخیره‌شده به واحد مورد نظر کاربر (مثلاً ریال جدید، تومان یا حتی ریال فعلی) استفاده کنید. این توابع تبدیل، فقط برای فرمت‌دهی خروجی هستند و داده‌های اصلی برنامه را تغییر نمی‌دهند.

public class CurrencyHelper
{
    // Converts a value from Qeran to Toman for display
    public static string ToTomanString(decimal amountInQeran)
    {
        // 1 New Rial = 100 Qeran, and 1 New Rial is essentially 1 Toman
        // Therefore, 1 Qeran = 0.01 Toman
        decimal amountInToman = amountInQeran / 100;
        
        return $"{amountInToman:N0}"; // N0 for no decimal places, for example
    }
}

// In a UI component:
// var invoice = dbContext.Invoices.Find(1);
// string displayAmount = CurrencyHelper.ToTomanString(invoice.TotalAmountInQeran); 
// // displayAmount will be formatted as a Toman value

• استانداردسازی: یک واحد پایه و ثابت (مانند قران) برای تمام داده‌های مالی انتخاب کنید.
• دقت بالا: از نوع داده decimal برای تمامی فیلدهای مالی در مدل‌ها و پایگاه داده استفاده کنید.
• یکپارچگی در منطق: تمامی محاسبات را با استفاده از واحد پایه انجام دهید.
• جداسازی لایه‌ها: تبدیل واحد را فقط در زمان نمایش اطلاعات به کاربر و در لایه رابط کاربری انجام دهید.

• نرخ‌های تبدیل ثابت: طبق مصوبه، نرخ‌های تبدیل بین قِران، ریال جدید، ریال فعلی، و تومان ثابت هستند (۱ قِران = ۰.۰۱ ریال جدید = ۱۰۰ ریال فعلی = ۱۰ تومان).
• ذخیره در قِران: تمام مقادیر مالی در پایگاه داده به قِران ذخیره می‌شوند تا پیچیدگی کاهش یابد.
• تبدیل در رابط کاربری: تبدیل به واحدهای دیگر (ریال جدید، ریال فعلی، تومان) فقط در زمان نمایش یا گزارش‌گیری انجام می‌شود.
• انتخاب واحد توسط کاربر: کاربر از طریق یک منوی کشویی (Dropdown) واحد پولی موردنظر را انتخاب می‌کند، و مقادیر در رابط کاربری به واحد انتخاب‌شده نمایش داده می‌شوند.

• سادگی پایگاه داده: ذخیره فقط به قِران، نیاز به مدیریت چندین واحد در پایگاه داده را حذف می‌کند.
• کاهش پیچیدگی: استفاده از enum و دیکشنری به جای جداول پایگاه داده، پیچیدگی کدها و پرس‌وجوها را کاهش می‌دهد.
• انعطاف‌پذیری در نمایش: تبدیل‌ها در زمان گزارش‌گیری یا نمایش در رابط کاربری انجام می‌شوند، که تجربه کاربری را بهبود می‌بخشد.

public enum CurrencyUnit
{
    Qeran,      // قِران
    RialNew,    // ریال جدید
    RialOld,    // ریال فعلی
    Toman       // تومان
}

• نام‌های enum کوتاه و معنادار هستند.
• این enum شامل تمام واحدهای موردنیاز (قِران، ریال جدید، ریال فعلی، تومان) است.

public static class CurrencyConversionRates
{
    private static readonly Dictionary<(CurrencyUnit From, CurrencyUnit To), decimal> Rates = new()
    {
        // قِران به سایر واحدها
        { (CurrencyUnit.Qeran, CurrencyUnit.RialNew), 0.01m },  // ۱ قِران = ۰.۰۱ ریال جدید
        { (CurrencyUnit.Qeran, CurrencyUnit.RialOld), 100m },   // ۱ قِران = ۱۰۰ ریال فعلی
        { (CurrencyUnit.Qeran, CurrencyUnit.Toman), 10m },      // ۱ قِران = ۱۰ تومان

        // ریال جدید به سایر واحدها
        { (CurrencyUnit.RialNew, CurrencyUnit.Qeran), 100m },   // ۱ ریال جدید = ۱۰۰ قِران
        { (CurrencyUnit.RialNew, CurrencyUnit.RialOld), 10000m }, // ۱ ریال جدید = ۱۰,۰۰۰ ریال فعلی
        { (CurrencyUnit.RialNew, CurrencyUnit.Toman), 1000m },  // ۱ ریال جدید = ۱,۰۰۰ تومان

        // ریال فعلی به سایر واحدها
        { (CurrencyUnit.RialOld, CurrencyUnit.Qeran), 0.01m },  // ۱ ریال فعلی = ۰.۰۱ قِران
        { (CurrencyUnit.RialOld, CurrencyUnit.RialNew), 0.0001m }, // ۱ ریال فعلی = ۰.۰۰۰۱ ریال جدید
        { (CurrencyUnit.RialOld, CurrencyUnit.Toman), 0.1m },   // ۱ ریال فعلی = ۰.۱ تومان

        // تومان به سایر واحدها
        { (CurrencyUnit.Toman, CurrencyUnit.Qeran), 0.1m },     // ۱ تومان = ۰.۱ قِران
        { (CurrencyUnit.Toman, CurrencyUnit.RialNew), 0.001m }, // ۱ تومان = ۰.۰۰۱ ریال جدید
        { (CurrencyUnit.Toman, CurrencyUnit.RialOld), 10m }     // ۱ تومان = ۱۰ ریال فعلی
    };

    public static decimal GetRate(CurrencyUnit from, CurrencyUnit to)
    {
        if (from == to)
            return 1m;

        if (Rates.TryGetValue((from, to), out var rate))
            return rate;

        throw new InvalidOperationException($"نرخ تبدیل از {from} به {to} تعریف نشده است.");
    }
}

• کلید دیکشنری: از یک تاپل (CurrencyUnit From, CurrencyUnit To) برای شناسایی جفت واحدهای مبدا و مقصد استفاده شده است.
• ثابت بودن نرخ‌ها: این دیکشنری نرخ‌های ثابت را نگه می‌دارد، که با فرض عدم تغییر نرخ‌ها در دوره گذار سازگار است.
• مدیریت خطا: اگر نرخ تبدیل برای یک جفت واحد وجود نداشته باشد، خطا تولید می‌شود.
• دقت: از نوع decimal برای جلوگیری از خطاهای گرد کردن استفاده شده است.

public class CurrencyService
{
    public decimal Convert(decimal amount, CurrencyUnit fromCurrency, CurrencyUnit toCurrency)
    {
        if (fromCurrency == toCurrency)
            return amount;

        var rate = CurrencyConversionRates.GetRate(fromCurrency, toCurrency);
        return amount * rate;
    }

    public decimal ConvertToQeran(decimal amount, CurrencyUnit fromCurrency)
    {
        return Convert(amount, fromCurrency, CurrencyUnit.Qeran);
    }

    public decimal ConvertFromQeran(decimal amountInQeran, CurrencyUnit toCurrency)
    {
        return Convert(amountInQeran, CurrencyUnit.Qeran, toCurrency);
    }
}

• سادگی: نیازی به اتصال به پایگاه داده نیست، و نرخ‌ها مستقیماً از دیکشنری خوانده می‌شوند.
• عملکرد بالا: حذف پرس‌وجوهای پایگاه داده و کش کردن (که در این حالت نیازی نیست، زیرا دیکشنری در حافظه است) باعث بهبود عملکرد می‌شود.
• مدیریت تبدیل به/از قِران: متدهای اختصاصی برای تبدیل به قِران و از قِران برای راحتی استفاده اضافه شده‌اند.

public class Transaction
{
    public int Id { get; set; }
    public decimal AmountInQeran { get; set; } // مقدار به قِران
    public DateTime Date { get; set; }
    public string Notes { get; set; } // یادداشت‌ها (اختیاری)
}

modelBuilder.Entity<Transaction>()
    .Property(t => t.AmountInQeran)
    .HasColumnType("decimal(18,4)"); // دقت بالا برای مقادیر خرد

• واحد پایه قِران: تمام مقادیر مالی به قِران ذخیره می‌شوند، که نیاز به ذخیره واحد پولی در هر تراکنش را حذف می‌کند.
• دقت اعشاری: نوع decimal(18,4) برای پشتیبانی از مقادیر خرد (مثلاً ۰.۰۱ قِران) مناسب است.

public class TransactionService
{
    private readonly AppDbContext _context;
    private readonly CurrencyService _currencyService;

    public TransactionService(AppDbContext context, CurrencyService currencyService)
    {
        _context = context;
        _currencyService = currencyService;
    }

    public async Task RecordTransaction(decimal amount, CurrencyUnit currency, DateTime transactionDate, string notes = null)
    {
        var amountInQeran = _currencyService.ConvertToQeran(amount, currency);
        var transaction = new Transaction
        {
            AmountInQeran = amountInQeran,
            Date = transactionDate,
            Notes = notes ?? "تراکنش ثبت‌شده به قِران"
        };

        _context.Transactions.Add(transaction);
        await _context.SaveChangesAsync();
    }
}

var transactionService = new TransactionService(dbContext, currencyService);
await transactionService.RecordTransaction(5000m, CurrencyUnit.Toman, DateTime.Now); // ۵,۰۰۰ تومان = ۵۰۰ قِران
await transactionService.RecordTransaction(5m, CurrencyUnit.RialNew, DateTime.Now); // ۵ ریال جدید = ۵۰۰ قِران

<select name="currency" asp-items="@Enum.GetValues(typeof(CurrencyUnit)).Cast<CurrencyUnit>().Select(c => new SelectListItem { Value = c.ToString(), Text = c.ToString() })">
    <option value="">انتخاب واحد پولی</option>
</select>

public class TransactionViewModel
{
    public int Id { get; set; }
    public decimal Amount { get; set; }
    public CurrencyUnit Currency { get; set; }
    public DateTime Date { get; set; }
    public string Notes { get; set; }
}

public class ReportService
{
    private readonly AppDbContext _context;
    private readonly CurrencyService _currencyService;

    public ReportService(AppDbContext context, CurrencyService currencyService)
    {
        _context = context;
        _currencyService = currencyService;
    }

    public List<TransactionViewModel> GetTransactions(CurrencyUnit displayCurrency)
    {
        return _context.Transactions
            .Select(t => new TransactionViewModel
            {
                Id = t.Id,
                Amount = _currencyService.ConvertFromQeran(t.AmountInQeran, displayCurrency),
                Currency = displayCurrency,
                Date = t.Date,
                Notes = t.Notes
            })
            .ToList();
    }
}

var reportService = new ReportService(dbContext, currencyService);
var transactions = reportService.GetTransactions(CurrencyUnit.Toman);
// تراکنش با ۵۰۰ قِران به ۵,۰۰۰ تومان تبدیل می‌شود

@foreach (var transaction in Model.Transactions)
{
    <tr>
        <td>@transaction.Amount.ToString("N2") @transaction.Currency</td>
        <td>@transaction.Date.ToString("yyyy-MM-dd")</td>
        <td>@transaction.Notes</td>
    </tr>
}

• تبدیل در زمان نمایش: مقادیر به قِران ذخیره می‌شوند و فقط در زمان نمایش یا گزارش‌گیری به واحد انتخاب‌شده تبدیل می‌شوند.
• انعطاف‌پذیری: کاربر می‌تواند واحد نمایش (قِران، ریال جدید، ریال فعلی، تومان) را از منوی کشویی انتخاب کند.

public class CurrencyServiceTests
{
    private readonly CurrencyService _service = new();

    [Fact]
    public void ConvertFromQeran_ToRialNew_ReturnsCorrectValue()
    {
        var result = _service.ConvertFromQeran(500m, CurrencyUnit.RialNew);
        Assert.Equal(5m, result); // ۵۰۰ قِران = ۵ ریال جدید
    }

    [Fact]
    public void ConvertToQeran_FromToman_ReturnsCorrectValue()
    {
        var result = _service.ConvertToQeran(5000m, CurrencyUnit.Toman);
        Assert.Equal(500m, result); // ۵,۰۰۰ تومان = ۵۰۰ قِران
    }

    [Fact]
    public void Convert_SameCurrency_ReturnsSameAmount()
    {
        var result = _service.Convert(500m, CurrencyUnit.Qeran, CurrencyUnit.Qeran);
        Assert.Equal(500m, result); // بدون تغییر
    }
}

• در دوره گذار (تا ۱۴۰۷)، کاربران ممکن است از ریال فعلی یا تومان برای ورودی استفاده کنند. سیستم با تبدیل همه ورودی‌ها به قِران، این نیاز را برآورده می‌کند.
• نمایش چندواحدی در رابط کاربری به کاربران کمک می‌کند تا با واحدهای مختلف (مثل تومان) راحت‌تر کار کنند.

• اطمینان حاصل کنید که گزارش‌های مالی به ریال جدید (واحد رسمی) ارائه می‌شوند، اما پشتیبانی از قِران و تومان در رابط کاربری حفظ شود.
• تاریخچه تراکنش‌ها (به قِران) برای حسابرسی قانونی ذخیره شود.

• واحدهای پولی را با CurrencyUnit enum تعریف کنید.
• نرخ‌های تبدیل را در دیکشنری CurrencyConversionRates ذخیره کنید.
• سرویس تبدیل را برای استفاده از دیکشنری تهیه کنید.
• تراکنش‌ها را فقط به قِران در پایگاه داده ذخیره کنید.
• رابط کاربری را با منوی کشویی و نمایش چندواحدی در زمان گزارش‌گیری طراحی کنید.
• تست‌های واحد برای اطمینان از صحت تبدیل‌ها بنویسید.