Add auto-update strategies for current balance on manual accounts (#2460)

* Add auto-update strategies for current balance on manual accounts

* Remove deprecated BalanceUpdater, replace with new methods

Author: zachgoll

app/controllers/concerns/accountable_resource.rb

@@ -45,12 +45,13 @@ def create
   def update
     # Handle balance update if provided
     if account_params[:balance].present?
-      result = @account.update_balance(balance: account_params[:balance], currency: account_params[:currency])
+      result = @account.set_current_balance(account_params[:balance].to_d)
       unless result.success?
         @error_message = result.error_message
         render :edit, status: :unprocessable_entity
         return
       end
+      @account.sync_later
     end
 
     # Update remaining account attributes

app/controllers/properties_controller.rb

@@ -37,10 +37,10 @@ def balances
   end
 
   def update_balances
-    result = @account.update_balance(balance: balance_params[:balance], currency: balance_params[:currency])
+    result = @account.set_current_balance(balance_params[:balance].to_d)
 
     if result.success?
-      @success_message = result.updated? ? "Balance updated successfully." : "No changes made. Account is already up to date."
+      @success_message = "Balance updated successfully."
 
       if @account.active?
         render :balances

app/models/account.rb

@@ -114,11 +114,6 @@ def current_holdings
             .order(amount: :desc)
   end
 
-
-  def update_balance(balance:, date: Date.current, currency: nil, notes: nil, existing_valuation_id: nil)
-    Account::BalanceUpdater.new(self, balance:, currency:, date:, notes:, existing_valuation_id:).update
-  end
-
   def start_date
     first_entry_date = entries.minimum(:date) || Date.current
     first_entry_date - 1.day
@@ -146,4 +141,23 @@ def short_subtype_label
   def long_subtype_label
     accountable_class.long_subtype_label_for(subtype) || accountable_class.display_name
   end
+
+  # The balance type determines which "component" of balance is being tracked.
+  # This is primarily used for balance related calculations and updates.
+  #
+  # "Cash" = "Liquid"
+  # "Non-cash" = "Illiquid"
+  # "Investment" = A mix of both, including brokerage cash (liquid) and holdings (illiquid)
+  def balance_type
+    case accountable_type
+    when "Depository", "CreditCard"
+      :cash
+    when "Property", "Vehicle", "OtherAsset", "Loan", "OtherLiability"
+      :non_cash
+    when "Investment", "Crypto"
+      :investment
+    else
+      raise "Unknown account type: #{accountable_type}"
+    end
+  end
 end

app/models/account/anchorable.rb

@@ -10,7 +10,9 @@ module Account::Anchorable
   end
 
   def set_opening_anchor_balance(**opts)
-    opening_balance_manager.set_opening_balance(**opts)
+    result = opening_balance_manager.set_opening_balance(**opts)
+    sync_later if result.success?
+    result
   end
 
   def opening_anchor_date
@@ -25,8 +27,10 @@ def has_opening_anchor?
     opening_balance_manager.has_opening_anchor?
   end
 
-  def set_current_anchor_balance(balance)
-    current_balance_manager.set_current_balance(balance)
+  def set_current_balance(balance)
+    result = current_balance_manager.set_current_balance(balance)
+    sync_later if result.success?
+    result
   end
 
   def current_anchor_balance

app/models/account/balance_updater.rb

@@ -31,22 +31,77 @@ def current_date
   end
 
   def set_current_balance(balance)
-    # A current balance anchor implies there is an external data source that will keep it updated. Since manual accounts
-    # are tracked by the user, a current balance anchor is not appropriate.
-    raise InvalidOperation, "Manual accounts cannot set current balance anchor. Set opening balance or use a reconciliation instead." if account.manual?
-
-    if current_anchor_valuation
-      changes_made = update_current_anchor(balance)
-      Result.new(success?: true, changes_made?: changes_made, error: nil)
+    if account.linked?
+      result = set_current_balance_for_linked_account(balance)
     else
-      create_current_anchor(balance)
-      Result.new(success?: true, changes_made?: true, error: nil)
+      result = set_current_balance_for_manual_account(balance)
     end
+
+    # Update cache field so changes appear immediately to the user
+    account.update!(balance: balance)
+
+    result
+  rescue => e
+    Result.new(success?: false, changes_made?: false, error: e.message)
   end
 
   private
     attr_reader :account
 
+    def opening_balance_manager
+      @opening_balance_manager ||= Account::OpeningBalanceManager.new(account)
+    end
+
+    def reconciliation_manager
+      @reconciliation_manager ||= Account::ReconciliationManager.new(account)
+    end
+
+    # Manual accounts do not manage the `current_anchor` valuation (otherwise, user would need to continually update it, which is bad UX)
+    # Instead, we use a combination of "auto-update strategies" to set the current balance according to the user's intent.
+    #
+    # The "auto-update strategies" are:
+    # 1. Value tracking - If the account has a reconciliation already, we assume they are tracking the account value primarily with reconciliations, so we append a new one
+    # 2. Transaction adjustment - If the account doesn't have recons, we assume user is tracking with transactions, so we adjust the opening balance with a delta until it
+    #                             gets us to the desired balance. This ensures we don't append unnecessary reconciliations to the account, which "reset" the value from that
+    #                             date forward (not user's intent).
+    #
+    # For more documentation on these auto-update strategies, see the test cases.
+    def set_current_balance_for_manual_account(balance)
+      # If we're dealing with a cash account that has no reconciliations, use "Transaction adjustment" strategy (update opening balance to "back in" to the desired current balance)
+      if account.balance_type == :cash && account.valuations.reconciliation.empty?
+        adjust_opening_balance_with_delta(new_balance: balance, old_balance: account.balance)
+      else
+        existing_reconciliation = account.entries.valuations.find_by(date: Date.current)
+
+        result = reconciliation_manager.reconcile_balance(balance: balance, date: Date.current, existing_valuation_entry: existing_reconciliation)
+
+        # Normalize to expected result format
+        Result.new(success?: result.success?, changes_made?: true, error: result.error_message)
+      end
+    end
+
+    def adjust_opening_balance_with_delta(new_balance:, old_balance:)
+      delta = new_balance - old_balance
+
+      result = opening_balance_manager.set_opening_balance(balance: account.opening_anchor_balance + delta)
+
+      # Normalize to expected result format
+      Result.new(success?: result.success?, changes_made?: true, error: result.error)
+    end
+
+    # Linked accounts manage "current balance" via the special `current_anchor` valuation.
+    # This is NOT a user-facing feature, and is primarily used in "processors" while syncing
+    # linked account data (e.g. via Plaid)
+    def set_current_balance_for_linked_account(balance)
+      if current_anchor_valuation
+        changes_made = update_current_anchor(balance)
+        Result.new(success?: true, changes_made?: changes_made, error: nil)
+      else
+        create_current_anchor(balance)
+        Result.new(success?: true, changes_made?: true, error: nil)
+      end
+    end
+
     def current_anchor_valuation
       @current_anchor_valuation ||= account.valuations.current_anchor.includes(:entry).first
     end

app/models/account/current_balance_manager.rb

@@ -2,11 +2,15 @@ module Account::Reconcileable
   extend ActiveSupport::Concern
 
   def create_reconciliation(balance:, date:, dry_run: false)
-    reconciliation_manager.reconcile_balance(balance: balance, date: date, dry_run: dry_run)
+    result = reconciliation_manager.reconcile_balance(balance: balance, date: date, dry_run: dry_run)
+    sync_later if result.success?
+    result
   end
 
   def update_reconciliation(existing_valuation_entry, balance:, date:, dry_run: false)
-    reconciliation_manager.reconcile_balance(balance: balance, date: date, existing_valuation_entry: existing_valuation_entry, dry_run: dry_run)
+    result = reconciliation_manager.reconcile_balance(balance: balance, date: date, existing_valuation_entry: existing_valuation_entry, dry_run: dry_run)
+    sync_later if result.success?
+    result
   end
 
   private

app/models/account/reconcileable.rb

@@ -12,7 +12,6 @@ def reconcile_balance(balance:, date: Date.current, dry_run: false, existing_val
 
     unless dry_run
       prepared_valuation.save!
-      account.sync_later
     end
 
     ReconciliationResult.new(

app/models/account/reconciliation_manager.rb

@@ -20,9 +20,9 @@ def holdings_value_for_date(date)
     end
 
     def derive_cash_balance_on_date_from_total(total_balance:, date:)
-      if balance_type == :investment
+      if account.balance_type == :investment
         total_balance - holdings_value_for_date(date)
-      elsif balance_type == :cash
+      elsif account.balance_type == :cash
         total_balance
       else
         0
@@ -32,7 +32,7 @@ def derive_cash_balance_on_date_from_total(total_balance:, date:)
     def derive_cash_balance(cash_balance, date)
       entries = sync_cache.get_entries(date)
 
-      if balance_type == :non_cash
+      if account.balance_type == :non_cash
         0
       else
         cash_balance + signed_entry_flows(entries)
@@ -42,9 +42,9 @@ def derive_cash_balance(cash_balance, date)
     def derive_non_cash_balance(non_cash_balance, date, direction: :forward)
       entries = sync_cache.get_entries(date)
       # Loans are a special case (loan payment reducing principal, which is non-cash)
-      if balance_type == :non_cash && account.accountable_type == "Loan"
+      if account.balance_type == :non_cash && account.accountable_type == "Loan"
         non_cash_balance + signed_entry_flows(entries)
-      elsif balance_type == :investment
+      elsif account.balance_type == :investment
         # For reverse calculations, we need the previous day's holdings
         target_date = direction == :forward ? date : date.prev_day
         holdings_value_for_date(target_date)
@@ -57,19 +57,6 @@ def signed_entry_flows(entries)
       raise NotImplementedError, "Directional calculators must implement this method"
     end
 
-    def balance_type
-      case account.accountable_type
-      when "Depository", "CreditCard"
-        :cash
-      when "Property", "Vehicle", "OtherAsset", "Loan", "OtherLiability"
-        :non_cash
-      when "Investment", "Crypto"
-        :investment
-      else
-        raise "Unknown account type: #{account.accountable_type}"
-      end
-    end
-
     def build_balance(date:, cash_balance:, non_cash_balance:)
       Balance.new(
         account_id: account.id,

app/models/balance/base_calculator.rb

@@ -57,7 +57,7 @@ def process_account!
         # to properly track the holdings vs. cash breakdown, but for now we're only tracking
         # the total balance in the current anchor. The cash_balance field on the account model
         # is still being used for the breakdown.
-        account.set_current_anchor_balance(balance_calculator.balance)
+        account.set_current_balance(balance_calculator.balance)
       end
     end