dscf-credit 0.1.6 → 0.1.8

data/app/services/dscf/credit/disbursement_service.rb

@@ -60,11 +60,7 @@ module Dscf::Credit
         loan_profile: loan_profile,
         credit_line: credit_line,
         principal_amount: amount,
-        facilitation_fee: loan_terms[:facilitation_fee],
-        total_loan_amount: loan_terms[:total_amount],
-        remaining_amount: loan_terms[:total_amount],
-        accrued_interest: 0,
-        accrued_penalty: 0,
+        remaining_amount: amount,  # Only principal amount, not total
         status: "disbursed",
         due_date: loan_terms[:due_date],
         disbursed_at: Time.current,
@@ -73,6 +69,12 @@ module Dscf::Credit
 
       raise "Failed to create loan: #{loan.errors.full_messages.join(', ')}" unless loan.save
 
+      # Create facilitator fee accrual
+      create_facilitator_fee_accrual(loan, loan_terms[:facilitation_fee])
+
+      # Create VAT accrual if applicable
+      create_vat_accrual(loan, loan_terms[:vat_amount]) if loan_terms[:vat_amount] > 0
+
       loan
     end
 
@@ -104,19 +106,59 @@ module Dscf::Credit
       }
     end
 
+    def create_facilitator_fee_accrual(loan, facilitation_fee)
+      return if facilitation_fee <= 0
+
+      Dscf::Credit::LoanAccrual.create!(
+        loan: loan,
+        accrual_type: "facilitation_fee",
+        amount: facilitation_fee,
+        applied_on: Date.current,
+        status: "pending"
+      )
+    end
+
+    def create_vat_accrual(loan, vat_amount)
+      return if vat_amount <= 0
+
+      Dscf::Credit::LoanAccrual.create!(
+        loan: loan,
+        accrual_type: "tax",
+        amount: vat_amount,
+        applied_on: Date.current,
+        status: "pending"
+      )
+    end
+
     def update_credit_line_limits(loan)
-      new_available_limit = eligible_credit_line.available_limit - loan.total_loan_amount
+      # Calculate total amount from accruals: principal + facilitation_fee + vat
+      facilitation_fee = loan.loan_accruals.find_by(accrual_type: "facilitation_fee")&.amount || 0
+      vat = loan.loan_accruals.find_by(accrual_type: "tax")&.amount || 0
+      total_amount = loan.principal_amount + facilitation_fee + vat
+
+      new_available_limit = eligible_credit_line.available_limit - total_amount
       eligible_credit_line.update!(available_limit: [ new_available_limit, 0 ].max)
     end
 
     def success_result(loan)
+      # Reload to get associated accruals
+      loan.reload
+
+      facilitation_fee_accrual = loan.loan_accruals.find_by(accrual_type: "facilitation_fee")
+      vat_accrual = loan.loan_accruals.find_by(accrual_type: "tax")
+
+      facilitation_fee = facilitation_fee_accrual&.amount&.to_f || 0.0
+      vat_amount = vat_accrual&.amount&.to_f || 0.0
+      total_amount = loan.principal_amount.to_f + facilitation_fee + vat_amount
+
       {
         success: true,
         loan: loan,
         disbursement_details: {
           principal_amount: loan.principal_amount.to_f,
-          facilitation_fee: loan.facilitation_fee.to_f,
-          total_loan_amount: loan.total_loan_amount.to_f,
+          facilitation_fee: facilitation_fee,
+          vat_amount: vat_amount,
+          total_loan_amount: total_amount,
           due_date: loan.due_date,
           disbursed_at: loan.disbursed_at
         },

data/app/services/dscf/credit/loan_accrual_generator_service.rb

@@ -0,0 +1,272 @@
+module Dscf::Credit
+  # LoanAccrualGeneratorService generates daily interest and penalty accruals for active loans.
+  # This service is designed to be run daily by a background job/cron job.
+  #
+  # @example Run for all active loans
+  #   service = Dscf::Credit::LoanAccrualGeneratorService.new
+  #   result = service.generate_daily_accruals
+  #
+  # @example Run for specific loans
+  #   loan_ids = [1, 2, 3]
+  #   service = Dscf::Credit::LoanAccrualGeneratorService.new(loan_ids: loan_ids)
+  #   result = service.generate_daily_accruals
+  #
+  # @example Run for specific date (useful for backfilling)
+  #   service = Dscf::Credit::LoanAccrualGeneratorService.new(accrual_date: Date.yesterday)
+  #   result = service.generate_daily_accruals
+  #
+  # @see docs/LOAN_ACCRUAL_GENERATOR_DOCUMENTATION.md for detailed documentation
+  class LoanAccrualGeneratorService
+    attr_reader :loan_ids, :accrual_date, :force_regenerate
+
+    # Initialize the loan accrual generator service
+    #
+    # @param loan_ids [Array<Integer>, nil] Optional array of specific loan IDs to process.
+    #   If nil, processes all eligible loans.
+    # @param accrual_date [Date] The date for which to generate accruals. Defaults to today.
+    # @param force_regenerate [Boolean] If true, regenerates accruals even if they already exist
+    #   for the given date. Defaults to false.
+    def initialize(loan_ids: nil, accrual_date: Date.current, force_regenerate: false)
+      @loan_ids = loan_ids
+      @accrual_date = accrual_date
+      @force_regenerate = force_regenerate
+    end
+
+    # Generate daily accruals for eligible loans
+    #
+    # Eligible loans are those with:
+    # - Status: active, overdue, or disbursed
+    # - Have outstanding balance (remaining_amount > 0 or pending accruals exist)
+    #
+    # For each eligible loan:
+    # 1. Calculate daily interest based on principal and interest rate
+    # 2. Calculate penalty if loan is overdue
+    # 3. Create accrual records with status='pending'
+    #
+    # @return [Hash] Result hash with the following structure:
+    #   - :success [Boolean] Whether the operation succeeded
+    #   - :accruals_created [Integer] Number of accruals created
+    #   - :loans_processed [Integer] Number of loans processed
+    #   - :accrual_details [Array<Hash>] Details of each accrual created
+    #   - :errors [Array<Hash>] Any errors encountered (loan_id, error message)
+    #   - :message [String] Summary message
+    #
+    # @example Success response
+    #   {
+    #     success: true,
+    #     accruals_created: 45,
+    #     loans_processed: 30,
+    #     accrual_details: [
+    #       { loan_id: 1, accrual_type: 'interest', amount: 50.00 },
+    #       { loan_id: 1, accrual_type: 'penalty', amount: 25.00 },
+    #       ...
+    #     ],
+    #     errors: [],
+    #     message: "Successfully generated 45 accruals for 30 loans on 2025-10-03"
+    #   }
+    def generate_daily_accruals
+      loans = fetch_eligible_loans
+
+      return success_result([], []) if loans.empty?
+
+      accrual_details = []
+      errors = []
+
+      loans.each do |loan|
+        begin
+          loan_accruals = generate_accruals_for_loan(loan)
+          accrual_details.concat(loan_accruals)
+        rescue StandardError => e
+          errors << {
+            loan_id: loan.id,
+            error: e.message
+          }
+        end
+      end
+
+      success_result(accrual_details, errors)
+    rescue StandardError => e
+      error_result("Accrual generation failed: #{e.message}")
+    end
+
+    private
+
+    # Fetch loans eligible for accrual generation
+    #
+    # Eligible criteria:
+    # - Status is active, overdue, or disbursed
+    # - Has outstanding balance (remaining_amount > 0)
+    # - If loan_ids provided, only fetch those specific loans
+    #
+    # @return [ActiveRecord::Relation<Loan>] Collection of eligible loans
+    def fetch_eligible_loans
+      loans = Dscf::Credit::Loan
+                .where(status: %w[active overdue disbursed])
+                .where("remaining_amount > 0")
+                .includes(:credit_line, credit_line: :credit_line_specs)
+
+      loans = loans.where(id: loan_ids) if loan_ids.present?
+
+      loans
+    end
+
+    # Generate accruals for a single loan
+    #
+    # Generates:
+    # 1. Interest accrual based on daily interest rate and principal
+    # 2. Penalty accrual if loan is overdue
+    #
+    # @param loan [Dscf::Credit::Loan] The loan to generate accruals for
+    # @return [Array<Hash>] Array of accrual details created
+    def generate_accruals_for_loan(loan)
+      return [] if accrual_exists_for_date?(loan) && !force_regenerate
+
+      accruals = []
+
+      # Generate interest accrual
+      if loan.remaining_amount > 0
+        interest_accrual = generate_interest_accrual(loan)
+        accruals << interest_accrual if interest_accrual
+      end
+
+      # Generate penalty accrual if overdue
+      if loan_is_overdue?(loan)
+        penalty_accrual = generate_penalty_accrual(loan)
+        accruals << penalty_accrual if penalty_accrual
+      end
+
+      accruals
+    end
+
+    # Check if accruals already exist for the loan on the given date
+    #
+    # @param loan [Dscf::Credit::Loan] The loan to check
+    # @return [Boolean] True if accruals exist for the date
+    def accrual_exists_for_date?(loan)
+      loan.loan_accruals.where(applied_on: accrual_date).exists?
+    end
+
+    # Generate interest accrual for a loan
+    #
+    # Interest calculation:
+    # - Gets daily interest rate from active credit line spec
+    # - Daily interest = principal × daily_interest_rate
+    # - Note: interest_rate in credit_line_spec is already a daily rate, not annual
+    #
+    # @param loan [Dscf::Credit::Loan] The loan to generate interest for
+    # @return [Hash, nil] Accrual detail hash or nil if no interest
+    def generate_interest_accrual(loan)
+      credit_line_spec = loan.credit_line.credit_line_specs.active.first
+
+      return nil unless credit_line_spec
+
+      daily_interest_rate = credit_line_spec.interest_rate
+      return nil unless daily_interest_rate > 0
+
+      # Calculate daily interest (rate is already daily, no need to divide by 365)
+      daily_interest = (loan.remaining_amount * daily_interest_rate).round(2)
+
+      return nil if daily_interest <= 0
+
+      # Create interest accrual
+      accrual = Dscf::Credit::LoanAccrual.create!(
+        loan: loan,
+        accrual_type: "interest",
+        amount: daily_interest,
+        applied_on: accrual_date,
+        status: "pending"
+      )
+
+      {
+        loan_id: loan.id,
+        accrual_id: accrual.id,
+        accrual_type: "interest",
+        amount: daily_interest,
+        applied_on: accrual_date
+      }
+    end
+
+    # Generate penalty accrual for overdue loans
+    #
+    # Penalty calculation:
+    # - Gets daily penalty rate from active credit line spec
+    # - Daily penalty = principal × daily_penalty_rate
+    # - Only applies if loan.due_date < accrual_date
+    # - Note: penalty_rate in credit_line_spec is already a daily rate, not annual
+    #
+    # @param loan [Dscf::Credit::Loan] The loan to generate penalty for
+    # @return [Hash, nil] Accrual detail hash or nil if no penalty
+    def generate_penalty_accrual(loan)
+      credit_line_spec = loan.credit_line.credit_line_specs.active.first
+
+      return nil unless credit_line_spec
+
+      daily_penalty_rate = credit_line_spec.penalty_rate
+      return nil unless daily_penalty_rate > 0
+
+      # Calculate daily penalty (rate is already daily, no need to divide by 365)
+      daily_penalty = (loan.remaining_amount * daily_penalty_rate).round(2)
+
+      return nil if daily_penalty <= 0
+
+      # Create penalty accrual
+      accrual = Dscf::Credit::LoanAccrual.create!(
+        loan: loan,
+        accrual_type: "penalty",
+        amount: daily_penalty,
+        applied_on: accrual_date,
+        status: "pending"
+      )
+
+      {
+        loan_id: loan.id,
+        accrual_id: accrual.id,
+        accrual_type: "penalty",
+        amount: daily_penalty,
+        applied_on: accrual_date
+      }
+    end
+
+    # Check if loan is overdue based on due date and accrual date
+    #
+    # @param loan [Dscf::Credit::Loan] The loan to check
+    # @return [Boolean] True if loan is overdue
+    def loan_is_overdue?(loan)
+      loan.due_date < accrual_date || loan.status == "overdue"
+    end
+
+    # Build success result hash
+    #
+    # @param accrual_details [Array<Hash>] Details of accruals created
+    # @param errors [Array<Hash>] Any errors encountered
+    # @return [Hash] Success response
+    def success_result(accrual_details, errors)
+      loans_processed = accrual_details.map { |a| a[:loan_id] }.uniq.size
+      accruals_created = accrual_details.size
+
+      {
+        success: true,
+        accruals_created: accruals_created,
+        loans_processed: loans_processed,
+        accrual_details: accrual_details,
+        errors: errors,
+        message: "Successfully generated #{accruals_created} accruals for #{loans_processed} loans on #{accrual_date}"
+      }
+    end
+
+    # Build error result hash
+    #
+    # @param message [String] Error message
+    # @return [Hash] Error response
+    def error_result(message)
+      {
+        success: false,
+        accruals_created: 0,
+        loans_processed: 0,
+        accrual_details: [],
+        errors: [],
+        message: message
+      }
+    end
+  end
+end