spree_cm_commissioner 2.13.4 → 2.13.7

data/app/controllers/spree/api/v2/tenant/cart_payment_fees_controller.rb

@@ -0,0 +1,43 @@
+module Spree
+  module Api
+    module V2
+      module Tenant
+        # See Spree::Api::V2::Storefront::CartPaymentFeesController.
+        class CartPaymentFeesController < BaseController
+          include Spree::Api::V2::Storefront::OrderConcern
+
+          before_action :ensure_order
+
+          # override
+          def index
+            render_serialized_payload do
+              collection_serializer.new(collection).serializable_hash
+            end
+          end
+
+          # override
+          def collection
+            @collection ||= requested_payment_methods.map do |payment_method|
+              SpreeCmCommissioner::PaymentFees::Preview.call(order: spree_current_order, payment_method: payment_method)
+                                                       .value[:payment_fee_preview]
+            end
+          end
+
+          # override
+          def collection_serializer
+            SpreeCmCommissioner::V2::Storefront::PaymentFeePreviewSerializer
+          end
+
+          private
+
+          # Ids the order can't actually pay with are dropped rather than rejected, so a stale client
+          # list (e.g. a method disabled since the catalog was cached) still gets the rest.
+          def requested_payment_methods
+            ids = Array(params[:payment_method_ids]).map(&:to_s)
+            spree_current_order.available_payment_methods.select { |pm| ids.include?(pm.id.to_s) }
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v2/tenant/draft_orders_controller.rb

@@ -7,6 +7,10 @@ module Spree
 
           before_action -> { ensure_anonymous_booking_allowed!(draft_order_products) }, only: :create
 
+          # A top-up credits a wallet, which must belong to a real user -- unlike #create,
+          # this action has no guest-checkout path.
+          before_action :require_spree_current_user, only: [:topup]
+
           # Creates a generic draft order from a locally-assembled cart in a single request.
           # Endpoint: POST /api/v2/tenant/draft_orders
           # Params:
@@ -33,6 +37,44 @@ module Spree
             end
           end
 
+          # Builds a prepaid top-up order from just an amount and a payment method -- the client
+          # never fetches/knows the prepaid_top_up product or variant. Tenant-scoped: the resulting
+          # order.tenant_id makes PrepaidTopUpCreditJob produce tenant-issued (not platform-issued)
+          # credit.
+          # Endpoint: POST /api/v2/tenant/draft_orders/topup
+          # Params:
+          # - amount: the custom top-up amount (required)
+          # - payment_method_id: id of the payment method to attach (required)
+          # - currency: optional -- must be inside this tenant's own supported_currencies_list if
+          #   given; omitted, resolves to Tenant#preferred_currency_or_default (see
+          #   BaseController#resolve_requested_currency). This deliberately doesn't read
+          #   current_currency here even though it's tenant-aware now too -- resolve_requested_currency
+          #   hard-rejects an out-of-list currency (422), where current_currency would silently
+          #   fall back instead, which would make this endpoint's own validation cosmetic.
+          def topup
+            currency, error = resolve_requested_currency
+            return render_error_payload(error) if error
+
+            result = SpreeCmCommissioner::TopupDraftOrders::Create.call(
+              amount: params[:amount],
+              payment_method_id: params[:payment_method_id],
+              user: spree_current_user,
+              store: current_store,
+              currency: currency,
+              tenant: @tenant,
+              options: {
+                device_id: params[:device_id],
+                last_ip_address: request.remote_ip
+              }
+            )
+
+            if result.success?
+              render_serialized_payload(201) { serialize_resource(serializable_order(result.value[:order])) }
+            else
+              render_error_payload(result.error)
+            end
+          end
+
           private
 
           # Re-fetch the created order with everything the enriched payload touches eager-loaded, so

data/app/controllers/spree/api/v2/tenant/prepaid_config_controller.rb

@@ -0,0 +1,29 @@
+module Spree
+  module Api
+    module V2
+      module Tenant
+        # Endpoint: GET /api/v2/tenant/prepaid_config
+        # Mirrors Spree::Api::V2::Storefront::PrepaidConfigController, resolved with this tenant
+        # so supported_currencies/preferred_currency reflect Tenant#supported_currencies_list/
+        # #preferred_currency_or_default -- the same values BaseController#
+        # resolve_requested_currency already validates/defaults `?currency=` against on
+        # GET account/prepaid_balances and POST draft_orders/topup, now discoverable up front
+        # instead of only enforced after the fact on submit. Not under account/ -- this is
+        # tenant-wide config, not per-user account data (identical response for every user).
+        class PrepaidConfigController < BaseController
+          before_action :require_spree_current_user
+
+          def show
+            render_serialized_payload { serialize_resource(SpreeCmCommissioner::PrepaidConfig.resolve(tenant: @tenant)) }
+          end
+
+          private
+
+          def resource_serializer
+            Spree::V2::Tenant::PrepaidConfigSerializer
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree_cm_commissioner/admin/store_credits_controller_decorator.rb

@@ -0,0 +1,217 @@
+module SpreeCmCommissioner
+  module Admin
+    # Core's admin/users/:user_id/store_credits form (Spree::Admin::StoreCreditsController) builds
+    # a raw Spree::StoreCredit directly -- fine for ordinary store credit, but for the prepaid
+    # category (still named "Wallet" at the DB row level -- see #prepaid_category? below) it would
+    # silently bypass everything Prepaid::AdminCredit exists for: the ledger
+    # (cm_prepaid_transactions), the one-row-per-(user,currency,issuer_tenant_id) invariant
+    # (Mutation#find_or_create_prepaid_credit!), and the credit_type the prepaid system actually
+    # looks up by (core's own associate_credit_type would set "Expiring"/"Non-expiring" here, not
+    # our "prepaid" type -- the row wouldn't even show up in GET /prepaid). Route a prepaid-category
+    # submission through AdminCredit instead; everything else keeps core's original behavior.
+    module StoreCreditsControllerDecorator
+      TABS = %w[credits transactions].freeze
+      TRANSACTIONS_PER_PAGE = 25
+
+      # override
+      # Adds a per-currency balance summary (actual balance, topped up, reversed, held) for this
+      # user's prepaid-category credits, same shape as the admin store-credit dashboard's overview
+      # tab (StoreCreditOverviewQuery) -- see UserStoreCreditSummaryQuery for why it's a separate
+      # query rather than reusing that one directly. Also adds a second, filterable "Transactions"
+      # tab across this user's own prepaid ledger, same tab/search pattern as that dashboard's own
+      # Transactions tab -- see build_transactions_search below.
+      def index
+        super
+        @currency_summaries = SpreeCmCommissioner::UserStoreCreditSummaryQuery.new(user: @user).call
+        @current_tab = TABS.include?(params[:tab]) ? params[:tab] : 'credits'
+        build_transactions_search if @current_tab == 'transactions'
+      end
+
+      # override
+      def create
+        return super unless prepaid_category?
+
+        result = SpreeCmCommissioner::Prepaid::AdminCredit.call(
+          user: @user,
+          amount: params[:store_credit][:amount],
+          currency: params[:store_credit][:currency],
+          reason: params[:store_credit][:memo].presence || 'admin credit',
+          admin: try_spree_current_user,
+          idempotency_key: admin_credit_idempotency_key
+        )
+
+        if result.success?
+          flash[:success] = flash_message_for(result.value, :successfully_created)
+          redirect_to spree.admin_user_store_credits_path(@user)
+        else
+          @store_credit = @user.store_credits.new(permitted_store_credit_params)
+          load_categories
+          flash[:error] = result.error.value || result.error.to_s
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      # override
+      # A prepaid credit's amount is derived entirely from the ledger (top-ups, admin credits,
+      # reversals) -- letting this form edit it directly would silently desync amount from
+      # cm_prepaid_transactions with no ledger row to explain the change. destroy is already safe
+      # (prepaid_transactions has dependent: :restrict_with_exception), so only update needs a guard.
+      #
+      # For a non-prepaid credit, core's own #update leaves `action`/`action_originator` unset, so
+      # Spree::StoreCredit#store_event (store_credit_decorator.rb) reuses/overwrites the single
+      # `allocation` event instead of appending one -- the prior amount and who changed it are
+      # both lost, and originator ends up nil. Setting `action` here makes store_event build a new
+      # event row per edit instead, so amount history survives.
+      def update
+        return credit_not_editable if prepaid_category?
+
+        @store_credit.assign_attributes(permitted_store_credit_params)
+        @store_credit.action = SpreeCmCommissioner::StoreCreditDecorator::ADMIN_ADJUSTMENT_ACTION
+        @store_credit.action_originator = try_spree_current_user
+        @store_credit.created_by = try_spree_current_user
+
+        if @store_credit.save
+          flash[:success] = flash_message_for(@store_credit, :successfully_updated)
+          redirect_to spree.admin_user_store_credits_path(@user)
+        else
+          load_categories
+          flash[:error] = Spree.t('store_credit.errors.unable_to_update')
+          render :edit, status: :unprocessable_entity
+        end
+      end
+
+      # Reverses a single top_up/admin_credit ledger row (member route, admin/users/:user_id/
+      # store_credits/:id/reverse_top_up -- :id is the store_credit, params[:transaction_id]
+      # picks which ledger row). Keyed off the transaction id so a resubmitted form (double-click,
+      # retried request) can't reverse the same row twice.
+      def reverse_top_up
+        @store_credit = @user.store_credits.find(params[:id])
+        transaction = @store_credit.prepaid_transactions.find(params[:transaction_id])
+
+        error = not_reversible_reason(transaction)
+        if error
+          flash[:error] = error
+          return redirect_to spree.admin_user_store_credits_path(@user)
+        end
+
+        result = SpreeCmCommissioner::Prepaid::ReverseTopUp.call(
+          store_credit: @store_credit,
+          amount: transaction.amount,
+          idempotency_key: "admin_reverse:#{transaction.id}",
+          reason: params[:reason].presence || "admin reversal of #{transaction.transaction_type} ##{transaction.id}",
+          admin: try_spree_current_user
+        )
+
+        if result.success?
+          flash[:success] = Spree.t(:successfully_updated, resource: Spree::StoreCredit.model_name.human)
+        else
+          flash[:error] = result.error.value || result.error.to_s
+        end
+
+        redirect_to spree.admin_user_store_credits_path(@user)
+      end
+
+      # Freezes a prepaid-category store_credit (member route, admin/users/:user_id/store_credits/
+      # :id/freeze). 'full' blocks both spend and top-up; 'topup_only' blocks only top-up -- see
+      # StoreCreditDecorator#spend_blocked?/#topup_blocked?.
+      def freeze
+        @store_credit = @user.store_credits.find(params[:id])
+
+        result = SpreeCmCommissioner::Prepaid::Freeze.call(
+          store_credit: @store_credit,
+          admin: try_spree_current_user,
+          reason: params[:reason],
+          level: params[:level].presence || 'full',
+          until_at: params[:until_at].presence
+        )
+
+        if result.success?
+          flash[:success] = Spree.t(:successfully_updated, resource: Spree::StoreCredit.model_name.human)
+        else
+          flash[:error] = result.error.value || result.error.to_s
+        end
+
+        redirect_to spree.admin_user_store_credits_path(@user)
+      end
+
+      # Lifts a freeze on a prepaid-category store_credit (member route, admin/users/:user_id/
+      # store_credits/:id/unfreeze).
+      def unfreeze
+        @store_credit = @user.store_credits.find(params[:id])
+        SpreeCmCommissioner::Prepaid::Unfreeze.call(store_credit: @store_credit, admin: try_spree_current_user)
+
+        flash[:success] = Spree.t(:successfully_updated, resource: Spree::StoreCredit.model_name.human)
+        redirect_to spree.admin_user_store_credits_path(@user)
+      end
+
+      private
+
+      # This user's own prepaid ledger rows across every currency/tenant, filtered via Ransack
+      # (q[currency_eq], q[transaction_type_eq], q[created_at_gteq]/[created_at_lteq], ...) --
+      # same fields the admin store-credit dashboard's own Transactions tab filters on, minus
+      # user_email_cont (already scoped to one user here). Also carries the per-credit "recent
+      # activity + Reverse" behavior formerly on an inline <details> block under each credit row
+      # -- @reversed_transaction_ids is computed over this user's *entire* ledger, not just the
+      # current page, since a reversal row and the top_up/admin_credit it reverses can land on
+      # different pages once this is paginated.
+      def build_transactions_search
+        params[:q] = {} if params[:q].blank?
+        @transactions_search = SpreeCmCommissioner::PrepaidTransaction.where(user: @user).ransack(params[:q])
+        @transactions = @transactions_search.result
+                                            .includes(:order, :tenant, :store_credit, :admin)
+                                            .order(created_at: :desc)
+                                            .page(params[:page])
+                                            .per(TRANSACTIONS_PER_PAGE)
+
+        @reversed_transaction_ids = SpreeCmCommissioner::PrepaidTransaction
+                                    .where(user: @user, transaction_type: 'reverse_top_up')
+                                    .pluck(:idempotency_key)
+                                    .filter_map { |key| key[/\Aadmin_reverse:(\d+)\z/, 1]&.to_i }
+                                    .to_set
+      end
+
+      # Deterministic within a 30s window so a double-clicked/retried submit of the same form
+      # collides on the ledger's unique idempotency_key (see Mutation#write_ledger!) instead of
+      # double-crediting the user; a genuinely separate credit made later (new window) or with a
+      # different amount/currency/memo still gets its own row.
+      def admin_credit_idempotency_key
+        memo_digest = Digest::SHA256.hexdigest(params[:store_credit][:memo].to_s)[0, 12]
+        window = Time.current.to_i / 30
+        "admin_credit:#{@user.id}:#{params[:store_credit][:amount]}:#{params[:store_credit][:currency]}:#{memo_digest}:#{window}"
+      end
+
+      # See SpreeCmCommissioner::StoreCreditCategoryDecorator::WALLET_CATEGORY_NAME for why this
+      # is still "Wallet" at the DB level -- renaming that row's `name` is a data migration
+      # outside this refactor's scope; this method just gives the DB-level check a
+      # codebase-consistent name to call.
+      def prepaid_category?
+        category_id = params.dig(:store_credit, :category_id) || @store_credit&.category_id
+        wallet_name = SpreeCmCommissioner::StoreCreditCategoryDecorator::WALLET_CATEGORY_NAME
+        category_id.present? && Spree::StoreCreditCategory.find_by(id: category_id)&.name == wallet_name
+      end
+
+      def credit_not_editable
+        flash[:error] = I18n.t('spree_cm_commissioner.store_credit.credit_not_editable')
+        redirect_to spree.admin_user_store_credits_path(@user)
+      end
+
+      def not_reversible_reason(transaction)
+        unless %w[top_up admin_credit].include?(transaction.transaction_type) && transaction.status == 'completed'
+          return I18n.t('spree_cm_commissioner.store_credit.transaction_not_reversible')
+        end
+
+        # ReverseTopUp only ever adjusts the prepaid ledger -- it never touches the order/payment. For
+        # an order-backed top_up (a real payment the customer made), reversing here would silently
+        # claw back store credit without refunding the original payment, leaving the order looking
+        # paid while the money it credited is gone. Route that case through a real refund instead.
+        return I18n.t('spree_cm_commissioner.store_credit.order_backed_transaction_not_reversible') if transaction.order.present?
+
+        nil
+      end
+    end
+  end
+end
+
+unless Spree::Admin::StoreCreditsController.ancestors.include?(SpreeCmCommissioner::Admin::StoreCreditsControllerDecorator)
+  Spree::Admin::StoreCreditsController.prepend(SpreeCmCommissioner::Admin::StoreCreditsControllerDecorator)
+end

data/app/errors/spree_cm_commissioner/reschedule_policies/invalid_policyable_error.rb

@@ -0,0 +1,8 @@
+# Raised when a policy is assigned to an unsupported policyable type, or when
+# the policy's vendor does not match the policyable's vendor.
+module SpreeCmCommissioner
+  module ReschedulePolicies
+    class InvalidPolicyableError < StandardError
+    end
+  end
+end

data/app/errors/spree_cm_commissioner/reschedule_policies/not_reschedulable_error.rb

@@ -0,0 +1,11 @@
+# Raised when one or more line items are explicitly excluded from rescheduling.
+module SpreeCmCommissioner
+  module ReschedulePolicies
+    class NotReschedulableError < StandardError
+      # override
+      def message
+        I18n.t('reschedule_policies.resolve.not_reschedulable')
+      end
+    end
+  end
+end

data/app/errors/spree_cm_commissioner/reschedule_requests/cancel_not_allowed_error.rb

@@ -0,0 +1,6 @@
+module SpreeCmCommissioner
+  module RescheduleRequests
+    class CancelNotAllowedError < StandardError
+    end
+  end
+end

data/app/errors/spree_cm_commissioner/reschedule_requests/complete_cash_payment_error.rb

@@ -0,0 +1,6 @@
+module SpreeCmCommissioner
+  module RescheduleRequests
+    class CompleteCashPaymentError < StandardError
+    end
+  end
+end

data/app/errors/spree_cm_commissioner/reschedule_requests/eligibility_denied_error.rb

@@ -0,0 +1,7 @@
+# Raised when one or more line items are explicitly excluded from rescheduling.
+module SpreeCmCommissioner
+  module RescheduleRequests
+    class EligibilityDeniedError < StandardError
+    end
+  end
+end

data/app/factory/spree_cm_commissioner/order_telegram_message_factory.rb

@@ -200,10 +200,14 @@ module SpreeCmCommissioner
       grouped.map { |nationality_group, guests| customer_type_summary(nationality_group, guests) }.join(', ')
     end
 
-    # e.g. "Local (Adult x1, Child x1)". age_group is NOT NULL, so it is always present.
+    # e.g. "Local (Adult x1, Child x1)". `cm_saved_guests.age_group` is declared `null: false` in
+    # the migration, but a dev/staging DB whose column predates that migration (added via
+    # `add_column ... if_not_exists: true`, which silently skips the constraint if the column
+    # already exists) can still carry real NULL rows - group those under "Unknown" rather than
+    # crashing the whole order-completion Telegram notification on nil.humanize.
     def customer_type_summary(nationality_group, guests)
       age_breakdown = guests
-                      .group_by { |sg| sg.age_group.humanize }
+                      .group_by { |sg| sg.age_group&.humanize || 'Unknown' }
                       .map { |age_group, age_guests| "#{age_group} x#{age_guests.count}" }
                       .join(', ')
 

data/app/factory/spree_cm_commissioner/reschedule_telegram_message_factory.rb

@@ -0,0 +1,141 @@
+# 🔁 --- [RESCHEDULE REQUESTED] ---
+#
+# Request Number: <code>RS525393292</code>
+# Booking: <code>R898147633</code>
+#
+# <b>Leg 1</b>
+# <i>🗓️ Aug 24, 2026 - 08:00 → Aug 26, 2026 - 08:00</i>
+# <i>💺 A1, A2 → B3, B4</i>
+#
+# <b>Leg 2</b>
+# <i>🗓️ Aug 27, 2026 - 18:00 → Aug 29, 2026 - 18:00</i>
+#
+# <b>Fee:</b> $5.00
+# <b>Balance due:</b> $12.00
+# <i>⏳ Respond before Aug 24, 2026 - 20:00</i>
+
+module SpreeCmCommissioner
+  class RescheduleTelegramMessageFactory < TelegramMessageFactory
+    attr_reader :reschedule_request
+
+    def initialize(title:, reschedule_request:, subtitle: nil)
+      @reschedule_request = reschedule_request
+
+      # `subtitle` carries `last_error` for the ops escalation - exception text, the
+      # likeliest place for `<` and `&`. Telegram rejects malformed HTML with a 400,
+      # so an unescaped one loses the very alert that needed a human.
+      super(title: title, subtitle: escape(subtitle))
+    end
+
+    # override
+    def body
+      text = []
+      text << "Request Number: #{inline_code(reschedule_request.number)}\nBooking: #{inline_code(reschedule_request.order&.number)}"
+      text << leg_blocks.join("\n\n") if leg_blocks.any?
+      text << money_lines.join("\n")
+      text.compact_blank.join("\n\n")
+    end
+
+    # override
+    def footer
+      return if reschedule_request.expires_at.blank?
+
+      italic("⏳ Respond before #{pretty_datetime(reschedule_request.expires_at)}")
+    end
+
+    private
+
+    # Snapshots are paired by `position`, so zipping the two sides gives one
+    # before -> after block per leg. Seats, checkout and product only get a line when
+    # they changed; the date is always shown, because a seat-only move still needs to
+    # say which departure it is about.
+    def leg_blocks
+      @leg_blocks ||= begin
+        before = reschedule_request.previous_request_snapshots.sort_by(&:position)
+        after  = reschedule_request.new_request_snapshots.sort_by(&:position)
+        pairs  = before.zip(after)
+
+        pairs.each_with_index.filter_map do |(before_snapshot, after_snapshot), index|
+          next if before_snapshot.nil?
+
+          lines = []
+          lines << bold("Leg #{index + 1}") if pairs.size > 1
+          lines << product_line(before_snapshot, after_snapshot)
+          lines << date_line(before_snapshot, after_snapshot)
+          lines << checkout_line(before_snapshot, after_snapshot)
+          lines << seat_line(before_snapshot, after_snapshot)
+          lines.compact.join("\n").presence
+        end
+      end
+    end
+
+    def date_line(before_snapshot, after_snapshot)
+      from = pretty_datetime(before_snapshot&.from_date)
+      to   = pretty_datetime(after_snapshot&.from_date)
+      return if from.blank? && to.blank?
+      return italic("🗓️ #{from}") if from == to
+
+      italic("🗓️ #{from} → #{to}")
+    end
+
+    # Accommodation legs carry a checkout date; transit legs do not.
+    def checkout_line(before_snapshot, after_snapshot)
+      from = checkout_text(before_snapshot)
+      to   = checkout_text(after_snapshot)
+      return if from.blank? && to.blank?
+      return if from == to
+
+      italic("🏁 until #{from} → until #{to}")
+    end
+
+    def checkout_text(snapshot)
+      return '' if snapshot.nil? || snapshot.to_date.blank?
+      return '' if snapshot.from_date.present? && snapshot.to_date.to_date == snapshot.from_date.to_date
+
+      pretty_date(snapshot.to_date)
+    end
+
+    # Blank when the seats did not move, or when the product has no seating at all.
+    def seat_line(before_snapshot, after_snapshot)
+      from = seat_text(before_snapshot)
+      to   = seat_text(after_snapshot)
+      return if from.blank? && to.blank?
+      return if from == to
+
+      italic("💺 #{from.presence || '-'} → #{to.presence || 'to be assigned'}")
+    end
+
+    # Only meaningful when the policy allowed a variant change.
+    def product_line(before_snapshot, after_snapshot)
+      from = before_snapshot.variant&.product&.name.to_s
+      to   = after_snapshot&.variant&.product&.name.to_s
+      return if from.blank? || from == to
+
+      bold("#{escape(from)} → #{escape(to)}")
+    end
+
+    def seat_text(snapshot)
+      escape(Array(snapshot&.block_labels).compact_blank.join(', '))
+    end
+
+    # Telegram's HTML parse mode only tolerates `<`, `>` and `&` as entities, and
+    # rejects the whole message otherwise. Vendor-supplied names ("Bed & Breakfast")
+    # hit this in normal use.
+    def escape(text)
+      return text if text.blank?
+
+      text.to_s.gsub('&', '&amp;').gsub('<', '&lt;').gsub('>', '&gt;')
+    end
+
+    def money_lines
+      lines = [bold_amount('Fee', reschedule_request.display_fee_amount)]
+      lines << bold_amount('Balance due', reschedule_request.display_amount_due_total) if reschedule_request.amount_due_total.to_f.positive?
+      lines << bold_amount('Credit', reschedule_request.display_credit_amount_total) if reschedule_request.credit_amount_total.to_f.positive?
+      lines.compact
+    end
+
+    def bold_amount(label, money)
+      "#{bold("#{label}:")} #{money}"
+    end
+  end
+end

data/app/finders/spree_cm_commissioner/inventory_items/recently_changed_finder.rb

@@ -23,7 +23,7 @@ module SpreeCmCommissioner
       def fetch_recent_items
         query = SpreeCmCommissioner::InventoryItem.active
                                                   .joins(variant: :product)
-                                                  .where(spree_variants: { track_inventory: true })
+                                                  .where(spree_variants: { track_inventory: true }, spree_products: { offline: false })
                                                   .where('cm_inventory_items.updated_at > ?', @time_range)
                                                   .select(
                                                     'cm_inventory_items.id',

data/app/helpers/spree/admin/base_helper_decorator.rb

@@ -26,6 +26,18 @@ module Spree
       rescue StandardError
         nil
       end
+
+      # A small info-circle icon with a native-title hover tooltip, for labeling a metric/column
+      # whose meaning isn't obvious from its name alone (e.g. "Held" -> "Amount currently
+      # authorized ..."). Uses svg_icon/backend-info-circle.svg -- the same inline-SVG mechanism
+      # every other icon in this admin theme already renders through (menu tabs, buttons via
+      # link_to_with_icon) -- rather than a text/Unicode glyph, which can render as an invisible
+      # box depending on the system font and was the reason two earlier attempts here didn't show.
+      def hint_icon(hint)
+        icon = svg_icon(name: 'info-circle.svg', width: 12, height: 12)
+        icon_style = 'cursor: help; margin-left: 4px; display: inline-flex; vertical-align: middle;'
+        content_tag(:span, icon, title: hint, style: icon_style)
+      end
     end
   end
 end

data/app/helpers/spree/admin/reschedule_policies_helper.rb

@@ -0,0 +1,35 @@
+module Spree
+  module Admin
+    module ReschedulePoliciesHelper
+      # Human-readable fee summary for a policy's calculator.
+      def reschedule_policy_fee_label(policy)
+        calculator = policy.calculator
+        return '-' if calculator.blank?
+
+        case calculator
+        when Spree::Calculator::FlatRate
+          Spree::Money.new(calculator.preferred_amount, currency: calculator.preferred_currency).to_s
+        when Spree::Calculator::PercentOnLineItem
+          "#{calculator.preferred_percent}%"
+        else
+          calculator.class.name.demodulize.titleize
+        end
+      end
+
+      # 'percent' or 'flat', used to pre-select the fee-type toggle on the form.
+      def reschedule_policy_fee_type(policy)
+        policy.calculator.is_a?(Spree::Calculator::PercentOnLineItem) ? 'percent' : 'flat'
+      end
+
+      # Bootstrap badge for the policy status enum.
+      def reschedule_policy_status_badge(status)
+        klass = { 'active' => 'badge-success',
+                  'draft' => 'badge-secondary',
+                  'inactive' => 'badge-warning',
+                  'archived' => 'badge-dark'
+                }.fetch(status.to_s, 'badge-light')
+        content_tag :span, status.to_s.titleize, class: "badge #{klass}"
+      end
+    end
+  end
+end