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

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 @@ module Account::Anchorable
     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

@@ -1,53 +0,0 @@
-class Account::BalanceUpdater
-  def initialize(account, balance:, currency: nil, date: Date.current, notes: nil, existing_valuation_id: nil)
-    @account = account
-    @balance = balance.to_d
-    @currency = currency
-    @date = date.to_date
-    @notes = notes
-    @existing_valuation_id = existing_valuation_id
-  end
-
-  def update
-    return Result.new(success?: true, updated?: false) unless requires_update?
-
-    Account.transaction do
-      if date == Date.current
-        account.balance = balance
-        account.currency = currency if currency.present?
-        account.save!
-      end
-
-      valuation_entry = if existing_valuation_id
-        account.entries.find(existing_valuation_id)
-      else
-        account.entries.valuations.find_or_initialize_by(date: date) do |entry|
-          entry.entryable = Valuation.new(kind: "reconciliation")
-        end
-      end
-
-      valuation_entry.date = date
-      valuation_entry.amount = balance
-      valuation_entry.currency = currency if currency.present?
-      valuation_entry.name = Valuation.build_reconciliation_name(account.accountable_type)
-      valuation_entry.notes = notes if notes.present?
-      valuation_entry.save!
-    end
-
-    account.sync_later
-
-    Result.new(success?: true, updated?: true)
-  rescue => e
-    message = Rails.env.development? ? e.message : "Unable to update account values. Please try again."
-    Result.new(success?: false, updated?: false, error_message: message)
-  end
-
-  private
-    attr_reader :account, :balance, :currency, :date, :notes, :existing_valuation_id
-
-    Result = Struct.new(:success?, :updated?, :error_message)
-
-    def requires_update?
-      date != Date.current || account.balance != balance || account.currency != currency
-    end
-end

app/models/account/current_balance_manager.rb

@@ -31,22 +31,77 @@ class Account::CurrentBalanceManager
   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/reconcileable.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/reconciliation_manager.rb

@@ -12,7 +12,6 @@ class Account::ReconciliationManager
 
     unless dry_run
       prepared_valuation.save!
-      account.sync_later
     end
 
     ReconciliationResult.new(