dscf-banking 0.5.1 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f558728cc00fd36f502cc21c0f342a1db0102f7c2b08b92b4fdc224e7a3a4839
-  data.tar.gz: 47c41262ad655e43365f13a974cd253474e3dbf4ac0abdb46e03564288f20b42
+  metadata.gz: '0086738f163c88e967b2850c3b0c2e29804725e059996dd2edfd152a98c874b5'
+  data.tar.gz: 2bc163e912db1cb78a491610f88efc8d99f8455f034ed90f64031628bce1375c
 SHA512:
-  metadata.gz: c2c57799b26eb5bbe257e20c9a044298021268e55689fbb62e32157dc1b674595b0406f603f95e82356bc865c63a313a662d1266588d967700846579341ae465
-  data.tar.gz: 8d04ca7ec5e9ead3fa0d026999962fd5026a1cfb98825465ee455ba961f4606b406175bfe9152943cb5c2dbc19b1579ea5301b235e642116a34dc2eb0759da47
+  metadata.gz: 970cd3f5b838bcd3a5c74a9b2511569cd4ec7eeb7ecf28d90e32d9efda437707214514088d562a2e35bff1a43f7dc8b89a5abff66c56071a5ff3f2e2f3abc832
+  data.tar.gz: 29f3c5f3299b0b1dc1da0cfb11594f22a0c2970865482701097bd0492552165a90a76817b8acef394f63e4de15a5758571635236edd482f633ed700117af684f

data/app/controllers/dscf/banking/accounts_controller.rb

@@ -274,6 +274,46 @@ module Dscf::Banking
       }, status: :not_found
     end
 
+    def interest_simulations
+      account_number = params[:account_number].presence || params[:id]
+      account = Dscf::Banking::Account.find_by(account_number: account_number)
+
+      unless account
+        return render json: {
+          success: false,
+          error: "Account not found"
+        }, status: :not_found
+      end
+
+      validation_errors = interest_simulation_validation_errors
+      if validation_errors.any?
+        return render json: {
+          success: false,
+          error: "Invalid interest simulation parameters",
+          errors: validation_errors
+        }, status: :unprocessable_entity
+      end
+
+      simulation = Dscf::Banking::InterestSimulationService.new(
+        account: account,
+        initial_balance: params[:initial_balance],
+        start_date: params[:start_date],
+        end_date: params[:end_date],
+        transactions: params[:transactions] || []
+      ).call
+
+      render json: {
+        success: true,
+        data: simulation
+      }
+    rescue ArgumentError => e
+      render json: {
+        success: false,
+        error: "Invalid interest simulation parameters",
+        errors: [ e.message ]
+      }, status: :unprocessable_entity
+    end
+
     private
 
     def transaction_data(transaction)
@@ -375,5 +415,52 @@ module Dscf::Banking
         update: [ :virtual_account_product, :application ]
       }
     end
+
+    def interest_simulation_validation_errors
+      errors = []
+      errors << "initial_balance is required" if params[:initial_balance].blank?
+      errors << "start_date is required" if params[:start_date].blank?
+      errors << "end_date is required" if params[:end_date].blank?
+
+      if params[:transactions].present? && !params[:transactions].is_a?(Array)
+        errors << "transactions must be an array"
+      end
+
+      if params[:initial_balance].present? && !valid_decimal?(params[:initial_balance])
+        errors << "initial_balance must be a valid number"
+      end
+
+      start_date = nil
+      end_date = nil
+
+      if params[:start_date].present?
+        start_date = parse_iso_date(params[:start_date])
+        errors << "start_date must be a valid date" unless start_date
+      end
+
+      if params[:end_date].present?
+        end_date = parse_iso_date(params[:end_date])
+        errors << "end_date must be a valid date" unless end_date
+      end
+
+      if start_date && end_date && start_date > end_date
+        errors << "start_date must be before or equal to end_date"
+      end
+
+      errors
+    end
+
+    def valid_decimal?(value)
+      BigDecimal(value.to_s)
+      true
+    rescue ArgumentError
+      false
+    end
+
+    def parse_iso_date(value)
+      Date.iso8601(value.to_s)
+    rescue Date::Error
+      nil
+    end
   end
 end

data/app/services/dscf/banking/interest_simulation_service.rb

@@ -0,0 +1,227 @@
+require "bigdecimal"
+require "date"
+
+module Dscf::Banking
+  class InterestSimulationService
+    DEFAULT_ANNUAL_INTEREST_RATE = BigDecimal("0.05")
+    # Fallback tax rate when no product-level tax is configured.
+    DEFAULT_TAX_RATE = BigDecimal("0.15")
+
+    def initialize(account:, initial_balance:, start_date:, end_date:, transactions: [])
+      @account = account
+      @initial_balance = decimal(initial_balance)
+      @start_date = to_date(start_date)
+      @end_date = to_date(end_date)
+      @transactions_by_date = {}
+      @transactions = normalize_transactions(transactions || [])
+    end
+
+    def call
+      raise ArgumentError, "start_date must be before or equal to end_date" if @start_date > @end_date
+
+      balance = @initial_balance
+      gross_interest = BigDecimal("0")
+      accrued_interest = BigDecimal("0")
+      daily_breakdown = []
+
+      (@start_date..@end_date).each do |date|
+        daily_transactions = @transactions_by_date[date] || []
+        daily_transaction_sum = daily_transactions.sum(BigDecimal("0")) { |transaction| transaction[:signed_amount] }
+        balance += daily_transaction_sum
+
+        daily_rate = annual_interest_rate_for(balance) / BigDecimal(day_basis.to_s)
+        raw_daily_interest = eligible_for_interest?(date, balance) ? balance * daily_rate : BigDecimal("0")
+        accrued_interest += raw_daily_interest
+
+        posted_daily_interest = BigDecimal("0")
+        if accrual_posting_due?(date)
+          posted_daily_interest = accrued_interest
+          accrued_interest = BigDecimal("0")
+          gross_interest += posted_daily_interest
+
+          # Compound mode credits posted interest into principal for subsequent days.
+          balance += posted_daily_interest if compound_calculation? && compounding_due?(date)
+        end
+
+        daily_breakdown << {
+          date: date.iso8601,
+          balance: money(balance),
+          transaction_total: money(daily_transaction_sum),
+          daily_interest: money(posted_daily_interest)
+        }
+      end
+
+      tax_amount = gross_interest * tax_rate
+      net_interest = gross_interest - tax_amount
+
+      {
+        gross_interest: money(gross_interest),
+        tax_amount: money(tax_amount),
+        net_interest: money(net_interest),
+        daily_breakdown: daily_breakdown,
+        accounting_records: accounting_records(gross_interest, tax_amount, net_interest)
+      }
+    end
+
+    private
+
+    def interest_configuration
+      @interest_configuration ||= Dscf::Banking::InterestConfiguration
+        .active
+        .find_by(virtual_account_product_id: @account.virtual_account_product_id)
+    end
+
+    def annual_interest_rate
+      configured = interest_configuration&.annual_interest_rate
+      configured.present? ? decimal(configured) : DEFAULT_ANNUAL_INTEREST_RATE
+    end
+
+    def annual_interest_rate_for(balance)
+      interest_rate_tier_for(balance)&.yield_self { |tier| decimal(tier.interest_rate) } || annual_interest_rate
+    end
+
+    def tax_rate
+      configured = interest_configuration&.income_tax_rate
+      configured.present? ? decimal(configured) : DEFAULT_TAX_RATE
+    end
+
+    def day_basis
+      case interest_configuration&.interest_basis
+      when "actual_360", "thirty_360"
+        360
+      else
+        365
+      end
+    end
+
+    def compound_calculation?
+      interest_configuration&.calculation_method == "compound"
+    end
+
+    def accrual_posting_due?(date)
+      return date == date.end_of_month || date == @end_date if monthly_accrual_mode?
+
+      true
+    end
+
+    def compounding_due?(date)
+      return date == date.end_of_month || date == @end_date if monthly_compounding_mode?
+
+      true
+    end
+
+    def monthly_accrual_mode?
+      interest_configuration&.accrual_frequency == "monthly"
+    end
+
+    def monthly_compounding_mode?
+      interest_configuration&.compounding_period == "monthly"
+    end
+
+    def eligible_for_interest?(date, balance)
+      meets_minimum_balance?(balance) && within_promotional_window?(date)
+    end
+
+    def meets_minimum_balance?(balance)
+      balance >= minimum_balance_for_interest
+    end
+
+    def minimum_balance_for_interest
+      configured = interest_configuration&.minimum_balance_for_interest
+      configured.present? ? decimal(configured) : BigDecimal("0")
+    end
+
+    def interest_rate_tier_for(balance)
+      interest_rate_tiers.find do |tier|
+        lower_bound_satisfied = balance >= decimal(tier.balance_min)
+        upper_bound_satisfied = tier.balance_max.blank? || balance <= decimal(tier.balance_max)
+
+        lower_bound_satisfied && upper_bound_satisfied
+      end
+    end
+
+    def interest_rate_tiers
+      @interest_rate_tiers ||= begin
+        if interest_configuration
+          Dscf::Banking::InterestRateTier.by_interest_config(interest_configuration.id).ordered.to_a
+        else
+          []
+        end
+      end
+    end
+
+    def within_promotional_window?(date)
+      return true unless interest_configuration&.promotional_start_date.present? || interest_configuration&.promotional_end_date.present?
+
+      date >= interest_configuration.promotional_start_date && date <= interest_configuration.promotional_end_date
+    end
+
+    def normalize_transactions(transactions)
+      return [] unless transactions.is_a?(Array)
+
+      normalized = transactions.each_with_index.map do |transaction, index|
+        unless transaction.respond_to?(:[]) && (transaction.is_a?(Hash) || transaction.respond_to?(:to_h))
+          raise ArgumentError, "Invalid transaction payload at index #{index}"
+        end
+
+        date = to_date(transaction[:date] || transaction["date"])
+        amount = decimal(transaction[:amount] || transaction["amount"])
+        type = (transaction[:type] || transaction["type"]).to_s.downcase
+
+        {
+          date: date,
+          signed_amount: signed_amount(amount, type)
+        }
+      end
+
+      @transactions_by_date = normalized.group_by { |transaction| transaction[:date] }
+      normalized
+    end
+
+    def signed_amount(amount, type)
+      return amount * -1 if %w[debit withdrawal outflow].include?(type) && amount.positive?
+      return amount.abs if %w[credit deposit inflow].include?(type)
+
+      amount
+    end
+
+    def to_date(value)
+      Date.iso8601(value.to_s)
+    rescue Date::Error
+      raise ArgumentError, "Invalid date value: #{value}"
+    end
+
+    def decimal(value)
+      BigDecimal(value.to_s)
+    rescue ArgumentError
+      raise ArgumentError, "Invalid numeric value: #{value}"
+    end
+
+    def money(amount)
+      format("%.2f", decimal(amount).round(2).to_f)
+    end
+
+    def accounting_records(gross_interest, tax_amount, net_interest)
+      [
+        {
+          date: @end_date.iso8601,
+          type: "gross_interest",
+          amount: money(gross_interest),
+          currency: @account.currency
+        },
+        {
+          date: @end_date.iso8601,
+          type: "tax",
+          amount: money(tax_amount),
+          currency: @account.currency
+        },
+        {
+          date: @end_date.iso8601,
+          type: "net_interest",
+          amount: money(net_interest),
+          currency: @account.currency
+        }
+      ]
+    end
+  end
+end

data/config/routes.rb

@@ -7,6 +7,7 @@ Dscf::Banking::Engine.routes.draw do
       post :activate
       post :suspend
       post :close
+      post :interest_simulations
       get :transactions
       get :full_name
     end

data/lib/dscf/banking/version.rb

@@ -1,5 +1,5 @@
 module Dscf
   module Banking
-    VERSION = "0.5.1"
+    VERSION = "0.5.3"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dscf-banking
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.3
 platform: ruby
 authors:
 - Asrat Efrem
 bindir: bin
 cert_chain: []
-date: 2026-03-14 00:00:00.000000000 Z
+date: 2026-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -472,6 +472,7 @@ files:
 - app/services/dscf/banking/account_creation_service.rb
 - app/services/dscf/banking/base_transaction_service.rb
 - app/services/dscf/banking/deposit_service.rb
+- app/services/dscf/banking/interest_simulation_service.rb
 - app/services/dscf/banking/transfer_service.rb
 - app/services/dscf/banking/voucher_service.rb
 - app/services/dscf/banking/withdrawal_service.rb