QBO-bound ledger cutover

app/admin/contributors.rb

@@ -48,13 +48,15 @@ def manual_deel_invoice_visible?(contributor)
   # write against, so the buttons short-circuit to a JS alert instead.
   LEDGER_REQUIRED_ALERT = "Select the appropriate ledger before you can perform this action.".freeze
 
-  action_item :deel_invoice, only: :show, if: proc {
-    manual_deel_invoice_visible?(resource)
-  } do
+  action_item :new_deel_withdrawal, only: :show do
     selected_ledger = params[:ledger].present? && resource.ledgers.find_by(id: params[:ledger])
-    if selected_ledger
-      link_to "New Deel Withdrawal",
-        new_admin_contributor_deel_invoice_adjustment_path(resource, ledger: selected_ledger.id)
+    if selected_ledger&.deel_enabled?
+      link_to "New Deel Withdrawal", new_admin_contributor_deel_invoice_adjustment_path(resource, ledger: selected_ledger.id)
+    elsif selected_ledger
+      # Ledger selected but Deel not in payment_methods — keep the button visible but inert,
+      # mirroring the other action_items' UX.
+      link_to "New Deel Withdrawal", "#",
+        onclick: "alert(#{"Deel is not enabled for this ledger's payment methods.".to_json}); return false;"
     else
       link_to "New Deel Withdrawal", "#",
         onclick: "alert(#{LEDGER_REQUIRED_ALERT.to_json}); return false;"
@@ -119,7 +121,7 @@ def manual_deel_invoice_visible?(contributor)
 
     # Keep QBO in sync after either toggle. sync_qbo_bill! is idempotent —
     # creates if missing, updates the existing bill otherwise. Best-effort:
-    # log + continue on failure; admin can retry manually.
+    # log + continue on failure; admin can retry via the Payable QBO Bills page.
     begin
       r.sync_qbo_bill!
     rescue => e

app/admin/deel_invoice_adjustments.rb

@@ -27,6 +27,16 @@ def manual_deel_invoice_submission_allowed?(contributor)
     end
 
     def verify_deel_invoice_access!
+      # :new / :create are admin-only (for legacy backfills / corrections).
+      # :index and :show stay available to the owning contributor so they
+      # can audit their existing Deel withdrawals.
+      if [:new, :create].include?(action_name.to_sym)
+        return if current_admin_user.is_admin?
+        redirect_to admin_contributor_path(parent),
+          alert: "Direct Deel withdrawals are admin-only."
+        return
+      end
+
       return if manual_deel_invoice_submission_allowed?(parent)
 
       redirect_to admin_contributor_path(parent), alert: "That action is not available."

app/admin/ledgers.rb

@@ -7,4 +7,157 @@
   # the parent's index. Without it, the breadcrumb link is missing.
   actions :index, :show
   permit_params
+
+  member_action :refresh_qbo_vendor, method: :post do
+    qa = resource.enterprise&.qbo_account
+    if qa.nil?
+      redirect_to admin_ledger_path(resource), alert: "No QBO account connected for #{resource.enterprise&.name}."
+      return
+    end
+    qa.sync_all_vendors!
+    redirect_to admin_ledger_path(resource), notice: "Refreshed QBO vendor data for #{resource.enterprise.name}."
+  rescue => e
+    Rails.logger.error("[refresh_qbo_vendor] ledger=#{resource.id}: #{e.class}: #{e.message}")
+    redirect_to admin_ledger_path(resource), alert: "Refresh failed: #{e.message}"
+  end
+
+  member_action :migrate_to_qbo_bound, method: :post do
+    unless resource.legacy?
+      redirect_to admin_ledger_path(resource), alert: "Already QBO-bound."
+      return
+    end
+    result = Ledgers::QboBoundMigrationCheck.call(resource)
+    if result.ready?
+      resource.update!(mode: :qbo_bound)
+      redirect_to admin_ledger_path(resource), notice: "Migrated to QBO-bound."
+    elsif result.qbo_vendor_missing?
+      redirect_to admin_ledger_path(resource),
+        alert: "Cannot migrate: no QBO vendor mapping for this contributor on #{resource.enterprise.name}."
+    else
+      redirect_to admin_ledger_path(resource),
+        alert: "Cannot migrate: Stacks total #{helpers.number_to_currency(result.stacks_open_total)} does not match QBO vendor balance #{helpers.number_to_currency(result.qbo_vendor_balance)} (diff #{helpers.number_to_currency(result.qbo_diff)})."
+    end
+  end
+
+  show do
+    attributes_table do
+      row :id
+      row :enterprise
+      row :contributor
+      row :mode
+      row :payment_methods
+    end
+
+    if resource.legacy?
+      panel "Migrate to QBO-bound" do
+        result = Ledgers::QboBoundMigrationCheck.call(resource)
+
+        div do
+          h4 "QBO match check"
+          if result.qbo_vendor_missing?
+            para strong("No QBO vendor mapping for this contributor on #{resource.enterprise.name}.")
+            para "Set up the vendor mapping before migrating — we can't compare against QBO without it."
+          else
+            para "Stacks (proposed qbo_bound) open total: #{number_to_currency(result.stacks_open_total)} = balance #{number_to_currency(result.proposed_balance)} + unsettled #{number_to_currency(result.proposed_unsettled)}"
+            para "QBO vendor AP balance:                 #{number_to_currency(result.qbo_vendor_balance)}"
+            if result.qbo_match?
+              para strong("Match. Safe to migrate — qbo_bound will mirror QBO one-to-one.")
+            else
+              para strong("Does NOT match. Diff: #{number_to_currency(result.qbo_diff)} (Stacks − QBO).")
+              if result.qbo_diff > 0
+                para "Stacks shows MORE owed than QBO. Likely cause: an Expense-to-AP or vendor credit in QBO that reduces AP, which Stacks can't see. Reconcile in QBO first (add the missing offset in Stacks, or verify the QBO entry is correct)."
+              else
+                para "QBO shows MORE owed than Stacks. Likely cause: an open Bill in QBO that Stacks doesn't know about (host without qbo_bill_id, or a Bill created outside Stacks). Sync the missing Bill or verify the QBO entry."
+              end
+              div style: "margin-top: 0.5em;" do
+                button_to "Refresh QBO vendor data",
+                          refresh_qbo_vendor_admin_ledger_path(resource),
+                          method: :post,
+                          data: { confirm: "Fetch all vendors for #{resource.enterprise.name} from QBO? Takes a few seconds." }
+                para style: "font-size: 0.85em; opacity: 0.7;" do
+                  text_node "Refreshes the cached vendor balance. Use if you just synced a new bill to QBO and the diff matches a known Stacks-side amount."
+                end
+              end
+            end
+          end
+        end
+
+        if result.ready?
+          div do
+            button_to "Migrate to QBO-bound", migrate_to_qbo_bound_admin_ledger_path(resource), method: :post, data: { confirm: "Flip this ledger to qbo_bound? Stacks total and QBO balance match — this is safe." }
+          end
+        else
+          div do
+            h4 "Diagnostic — legacy vs qbo_bound (independent of QBO check)"
+            para "Current (legacy):    balance #{number_to_currency(result.current_balance)}   unsettled #{number_to_currency(result.current_unsettled)}"
+            para "Proposed (qbo_bound):  balance #{number_to_currency(result.proposed_balance)}   unsettled #{number_to_currency(result.proposed_unsettled)}"
+            para "Δ balance #{number_to_currency(result.balance_delta)}, Δ unsettled #{number_to_currency(result.unsettled_delta)}"
+          end
+
+          neg_ca_sum = result.removed_neg_cas.sum { |ca| ca.amount.to_f }.round(2)
+          dia_sum    = result.removed_dias.sum    { |d|  d.amount.to_f }.round(2)
+          paid_sum   = result.dropped_paid_hosts.sum { |b| b.amount.to_f }.round(2)
+
+          if result.removed_neg_cas.any? || result.removed_dias.any? || result.dropped_paid_hosts.any?
+            div do
+              h4 "Items behaving differently under qbo_bound"
+
+              if result.removed_neg_cas.any?
+                para strong("Negative CAs ignored as audit-only: #{number_to_currency(neg_ca_sum)} (+#{number_to_currency(neg_ca_sum.abs)} to Δ)")
+                ul do
+                  result.removed_neg_cas.first(15).each do |ca|
+                    li "CA ##{ca.id} — #{number_to_currency(ca.amount.to_f)}    #{ca.description.to_s.truncate(70)}"
+                  end
+                  li "… and #{result.removed_neg_cas.size - 15} more" if result.removed_neg_cas.size > 15
+                end
+              end
+
+              if result.removed_dias.any?
+                para strong("DIAs ignored as audit-only: #{number_to_currency(dia_sum)} (+#{number_to_currency(dia_sum.abs)} to Δ)")
+                ul do
+                  result.removed_dias.first(15).each do |d|
+                    li "DIA ##{d.id} — #{number_to_currency(d.amount.to_f)}    #{d.description.to_s.truncate(70)}"
+                  end
+                  li "… and #{result.removed_dias.size - 15} more" if result.removed_dias.size > 15
+                end
+              end
+
+              if result.dropped_paid_hosts.any?
+                para strong("Paid QBO bills dropping out: #{number_to_currency(paid_sum)} (−#{number_to_currency(paid_sum.abs)} to Δ)")
+                ul do
+                  result.dropped_paid_hosts.first(15).each do |b|
+                    li do
+                      text_node "#{b.host.class.name} ##{b.host.id} — #{number_to_currency(b.amount.to_f)} — "
+                      link_to "View in QBO ↗", b.qbo_bill.qbo_url, target: "_blank", rel: "noopener"
+                    end
+                  end
+                  li "… and #{result.dropped_paid_hosts.size - 15} more" if result.dropped_paid_hosts.size > 15
+                end
+              end
+            end
+          end
+
+          if result.open_qbo_bills.any?
+            div do
+              h4 "Open QBO bills on this ledger"
+              para "Marking one Paid in QBO turns it into a dropped paid host and reduces Stacks open total by its amount."
+              ul do
+                result.open_qbo_bills.first(20).each do |b|
+                  li do
+                    text_node "#{b.host.class.name} ##{b.host.id} — #{number_to_currency(b.amount.to_f)} — "
+                    link_to "Pay in QBO ↗", b.qbo_bill.qbo_url, target: "_blank", rel: "noopener"
+                  end
+                end
+                li "… and #{result.open_qbo_bills.size - 20} more" if result.open_qbo_bills.size > 20
+              end
+            end
+          end
+
+          div do
+            button_to "Re-check", admin_ledger_path(resource), method: :get
+          end
+        end
+      end
+    end
+  end
 end

app/admin/money.rb

@@ -1,7 +1,32 @@
 ActiveAdmin.register_page "Money" do
+  menu priority: 50
+
   controller do
-    before_action do |_|
-      redirect_to admin_invoice_passes_path
+    before_action :authenticate_admin_user!
+  end
+
+  page_action :payable_qbo_bills, method: :get do
+    @qbo_accounts = QboAccount.includes(:enterprise).order(:id).to_a
+    @active_qa = if params[:qbo_account_id].present?
+      QboAccount.find(params[:qbo_account_id])
+    else
+      @qbo_accounts.first
     end
+    @rows = @active_qa ? Money::PayableQboBills.call(qbo_account: @active_qa) : []
+    render "admin/money/payable_qbo_bills"
+  end
+
+  page_action :refresh_bill, method: :post do
+    klass = params.require(:host_class).to_s.constantize
+    raise ActionController::BadRequest, "unsupported host class" unless Money::PayableQboBills::HOST_KLASSES.include?(klass)
+    host = klass.find(params.require(:host_id))
+    host.sync_qbo_bill!
+    redirect_back(fallback_location: admin_money_payable_qbo_bills_path(qbo_account_id: params[:qbo_account_id]))
+  end
+
+  page_action :refresh_tab, method: :post do
+    qa = QboAccount.find(params.require(:qbo_account_id))
+    Money::RefreshPayableQboBills.call(qbo_account: qa)
+    redirect_back(fallback_location: admin_money_payable_qbo_bills_path(qbo_account_id: qa.id))
   end
 end

app/models/concerns/syncs_as_qbo_bill.rb

@@ -87,6 +87,16 @@ def payable?
     false
   end
 
+  # Contribution to qbo_bound balance. Uses the QBO bill's remaining unpaid
+  # balance when a bill exists so partial payments are reflected one-to-one
+  # with QBO's vendor AP. Falls back to the host amount when there's no
+  # synced bill.
+  def qbo_bound_balance_amount
+    qb = qbo_bill
+    return amount.to_f if qb.nil?
+    qb.remaining_balance
+  end
+
   # Returns the array of Quickbooks::Model::BillLineItem objects that will
   # be pushed for this host's bill. Default implementation produces a single
   # line at the host's `find_qbo_account!` result, matching the historic

app/models/contributor_adjustment.rb

@@ -11,6 +11,15 @@ class ContributorAdjustment < ApplicationRecord
 
   validates :amount, presence: true
   validates :effective_on, presence: true
+  validate :no_negative_on_qbo_bound_ledger
+
+  def no_negative_on_qbo_bound_ledger
+    return unless ledger&.qbo_bound? && amount&.negative?
+    errors.add(
+      :amount,
+      "negative adjustments are not allowed on QBO-bound ledgers — mark the corresponding QBO bill Paid instead",
+    )
+  end
 
   # No linked invoice: counts toward balance like other payable rows. Linked invoice: only when fully paid in QBO.
   def payable?