Feat/loans overview new insights

app/controllers/loans_controller.rb

@@ -2,6 +2,6 @@ class LoansController < ApplicationController
   include AccountableResource
 
   permitted_accountable_attributes(
-    :id, :subtype, :rate_type, :interest_rate, :term_months, :initial_balance
+    :id, :subtype, :rate_type, :interest_rate, :insurance_rate_type, :insurance_rate, :term_months, :initial_balance, :down_payment, :start_date
   )
 end

app/models/demo/generator.rb

@@ -278,9 +278,45 @@ def create_realistic_accounts!(family)
       @coinbase_usdc = family.accounts.create!(accountable: Crypto.new, name: "Coinbase USDC", balance: 0, currency: "USD")
 
       # Loans / Liabilities (USD)
-      @mortgage      = family.accounts.create!(accountable: Loan.new, name: "Home Mortgage", balance: 0, currency: "USD")
-      @car_loan      = family.accounts.create!(accountable: Loan.new, name: "Car Loan", balance: 0, currency: "USD")
-      @student_loan  = family.accounts.create!(accountable: Loan.new, name: "Student Loan", balance: 0, currency: "USD")
+      @mortgage = family.accounts.create!(
+        accountable: Loan.new(
+          subtype: "mortgage",
+          rate_type: "fixed",
+          interest_rate: 6.5,
+          term_months: 360,
+          start_date: 3.years.ago.to_date,
+          down_payment: 60_000,
+          insurance_rate: 0.5,
+          insurance_rate_type: "level_term",
+          initial_balance: 320_000
+        ),
+        name: "Home Mortgage", balance: 0, currency: "USD"
+      )
+
+      @car_loan = family.accounts.create!(
+        accountable: Loan.new(
+          subtype: "auto",
+          rate_type: "fixed",
+          interest_rate: 7.0,
+          term_months: 60,
+          start_date: 1.year.ago.to_date,
+          down_payment: 5_000,
+          initial_balance: 25_000
+        ),
+        name: "Car Loan", balance: 0, currency: "USD"
+      )
+
+      @student_loan = family.accounts.create!(
+        accountable: Loan.new(
+          subtype: "student",
+          rate_type: "fixed",
+          interest_rate: 5.0,
+          term_months: 120,
+          start_date: 2.years.ago.to_date,
+          initial_balance: 30_000
+        ),
+        name: "Student Loan", balance: 0, currency: "USD"
+)
 
       @personal_loc  = family.accounts.create!(accountable: OtherLiability.new, name: "Personal Line of Credit", balance: 0, currency: "USD")
 

app/models/loan.rb

@@ -8,26 +8,214 @@ class Loan < ApplicationRecord
     "other" => { short: "Other Loan", long: "Other Loan" }
   }.freeze
 
+  LEVERAGE_BANDS = {
+  conservative: 0..4,
+  moderate: 4..8,
+  high: 8..
+  }.freeze
+
+  before_validation :set_default_start_date, on: :create
+
   validates :subtype, inclusion: { in: SUBTYPES.keys }, allow_blank: true
 
+  validates :interest_rate,
+            numericality: { greater_than_or_equal_to: 0 },
+            allow_nil: true
+
+  validates :insurance_rate,
+            numericality: { greater_than_or_equal_to: 0 },
+            allow_nil: true
+
+  validates :insurance_rate_type,
+            inclusion: { in: %w[level_term decreasing_life] },
+            allow_nil: true
+
+  validates :term_months,
+            numericality: { only_integer: true, greater_than: 0 },
+            allow_nil: true
+
+  validates :rate_type,
+            inclusion: { in: %w[fixed variable adjustable] },
+            allow_nil: true
+
+  validates :down_payment,
+            numericality: { greater_than_or_equal_to: 0 },
+            allow_nil: true
+
+  validates :start_date, presence: true
+
+
+
+
+  def original_balance
+    Money.new(account.first_valuation_amount, account.currency)
+  end
+
   def monthly_payment
-    return nil if term_months.nil? || interest_rate.nil? || rate_type.nil? || rate_type != "fixed"
-    return Money.new(0, account.currency) if account.loan.original_balance.amount.zero? || term_months.zero?
+    return unless term_months && interest_rate && rate_type == "fixed"
 
-    annual_rate = interest_rate / 100.0
-    monthly_rate = annual_rate / 12.0
+    balance_amount = original_balance.amount
+    months        = term_months
+    currency      = account.currency
+
+    return Money.new(0, currency) if balance_amount.zero? || months.zero?
+
+    balance = BigDecimal(balance_amount)
+    rate    = BigDecimal(interest_rate) / 1200
+
+    payment =
+      if rate.zero?
+        balance / months
+      else
+        factor = (1 + rate) ** months
+        balance * rate * factor / (factor - 1)
+      end
+
+    Money.new(payment.round(0).to_i, currency)
+  end
 
-    if monthly_rate.zero?
-      payment = account.loan.original_balance.amount / term_months
-    else
-      payment = (account.loan.original_balance.amount * monthly_rate * (1 + monthly_rate)**term_months) / ((1 + monthly_rate)**term_months - 1)
+  def months_elapsed(as_of: Date.current)
+    start = start_date
+    term  = term_months
+
+    return 0 unless start && term
+    return 0 if as_of < start
+
+    months = (as_of.year * 12 + as_of.month) - (start.year * 12 + start.month)
+    months -= 1 if start + months.months > as_of
+
+    months.clamp(0, term)
+  end
+
+
+  def remaining_months(as_of: Date.current)
+    term = term_months
+    return unless term
+
+    [ term - months_elapsed(as_of:), 0 ].max
+  end
+
+  def finished?(as_of: Date.current)
+    term = term_months
+    term && months_elapsed(as_of:) >= term
+  end
+
+  def amortization_schedule
+    return [] unless term_months && interest_rate && start_date && rate_type == "fixed"
+    Rails.cache.fetch([ "loan_amortization", cache_key_with_version, original_balance_cache_key ]) do
+      generate_amortization_schedule
     end
+  end
+
+
 
-    Money.new(payment.round, account.currency)
+  def total_insurance
+    Money.new(amortization_schedule.sum { _1[:insurance] }, account.currency)
   end
 
-  def original_balance
-    Money.new(account.first_valuation_amount, account.currency)
+  def total_paid
+    return unless (mp = monthly_payment) && term_months
+    mp * term_months
+  end
+
+  def total_interest
+    return unless (tp = total_paid) && (ob = original_balance)
+    tp - ob
+  end
+
+  def total_cost
+    tint = total_interest
+    ob = original_balance
+    tins = total_insurance
+
+    return nil unless tint && ob && tins
+
+    ob + tint + tins
+  end
+
+  def remaining_balance_at(month_number)
+    return unless month_number&.positive?
+    row = amortization_schedule[month_number - 1]
+    return unless row
+
+    Money.new(row[:remaining_balance].round, account.currency)
+  end
+
+  def payment_breakdown(month_number: nil)
+    month_number ||= months_elapsed(as_of: Date.current)
+    month_number   = month_number.clamp(1, term_months || 1)
+
+    row = amortization_schedule[month_number - 1] or return
+
+    currency  = account.currency
+    principal = Money.new(row[:principal], currency)
+    interest  = Money.new(row[:interest],  currency)
+    insurance = Money.new(row[:insurance], currency)
+    total     = principal + interest + insurance
+
+    ratios =
+      if total.amount.positive?
+        total_f = total.to_f
+
+        {
+          principal: principal.to_f / total_f,
+          interest:  interest.to_f  / total_f,
+          insurance: insurance.to_f / total_f
+        }
+      else
+        { principal: 0.0, interest: 0.0, insurance: 0.0 }
+      end
+    {
+      month:     month_number,
+      date:      row[:date],
+      principal: principal,
+      interest:  interest,
+      insurance: insurance,
+      total:     total,
+      ratios:    ratios
+    }
+  end
+
+  def balance_paid_ratio
+    initial = initial_balance
+    return unless initial&.positive?
+
+    current = account.balance
+    return unless current
+
+    (1 - current.fdiv(initial)).clamp(0.0, 1.0)
+  end
+
+  # Donut-chart segments for the repayment-progress ring, consumed by the
+  # shared `donut-chart` Stimulus controller (the same one Budgets and Goals
+  # use). A warning-colored "paid" arc plus a `--budget-unused-fill` track
+  # segment — both CSS-var driven so the ring themes correctly in light/dark.
+  # The view marks "paid" as the controller's overage segment so its var()
+  # color is passed straight to the SVG fill instead of being parsed by
+  # d3.color() (which returns null for var(...)). Returns nil when paydown
+  # can't be computed, in which case the view hides the ring.
+  def to_donut_segments
+    ratio = balance_paid_ratio
+    return unless ratio
+
+    [
+      { color: "var(--color-warning)", amount: ratio, id: "paid" },
+      { color: "var(--budget-unused-fill)", amount: 1 - ratio, id: "unused" }
+    ]
+  end
+
+  def initial_leverage_ratio
+    dp = down_payment
+    return unless dp&.positive?
+
+    original_balance.to_f.fdiv(dp)
+  end
+
+  def leverage_band
+    ratio = initial_leverage_ratio
+    return unless ratio
+
+    LEVERAGE_BANDS.find { |_, range| range.cover?(ratio) }&.first
   end
 
   class << self
@@ -43,4 +231,62 @@ def classification
       "liability"
     end
   end
+
+  private
+
+    def original_balance_cache_key
+      account&.valuations&.first&.updated_at&.to_i
+    end
+
+    def set_default_start_date
+      self.start_date ||= Date.current
+    end
+
+    def payment_date_for(month_number)
+      start = start_date
+      return unless start && month_number&.positive?
+      start + (month_number - 1).months
+    end
+
+
+    def generate_amortization_schedule
+      return [] if interest_rate.nil? || term_months.nil? || start_date.nil?
+
+      balance          = BigDecimal(original_balance.amount.to_s)
+      initial_balance  = balance
+
+      rate             = BigDecimal(interest_rate.to_s) / 1200
+      insurance_rate_m = BigDecimal((insurance_rate || 0).to_s) / 1200
+
+      return [] unless (monthly = monthly_payment)
+      payment = BigDecimal(monthly.amount.to_s)
+
+      schedule = []
+      months   = term_months
+      date     = start_date
+
+      months.times do |i|
+        interest = (balance * rate).round(0)
+
+        insurance_base =
+          insurance_rate_type == "level_term" ? initial_balance : nil
+        base = insurance_base || balance
+        insurance_amount = (base * insurance_rate_m).round(0)
+
+        principal = payment - interest
+        balance   = [ balance - principal, 0 ].max
+
+        schedule << {
+          month: i + 1,
+          date: start_date >> i,
+          payment: payment.to_i,
+          interest: interest.to_i,
+          principal: principal.to_i,
+          insurance: insurance_amount.to_i,
+          remaining_balance: balance.round(0).to_i
+        }
+      end
+
+      schedule
+    end
 end

app/views/accounts/_summary_card.html.erb

@@ -2,7 +2,7 @@
 
 <div class="rounded-xl bg-container shadow-xs border border-alpha-black-25 p-4">
   <h4 class="text-secondary text-sm"><%= title %></h4>
-  <p class="text-xl font-medium text-primary privacy-sensitive">
+  <div class="text-xl font-medium text-primary privacy-sensitive">
     <%= content %>
-  </p>
+  </div>
 </div>