spree_core 5.6.1 → 6.0.0.beta2

data/lib/spree/category_permalink_deduplicator.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+module Spree
+  # Resolves duplicate category permalinks within a store.
+  #
+  # Before 6.0 a permalink only had to be unique within its taxonomy, so one store
+  # could legitimately hold two "catalog" roots under different taxonomies. In 6.0
+  # the permalink is the category's full path and is unique per store, so those
+  # rows have to be separated before the unique index can exist.
+  #
+  # Runs on raw SQL rather than through Spree::Category: it is called from a
+  # migration, where the model's callbacks, validations and default scopes may not
+  # match the schema on disk.
+  class CategoryPermalinkDeduplicator
+    # Spelled out per schema rather than interpolated from #effective_store_id:
+    # this query binds no values, so writing it as constants keeps it provably
+    # free of interpolated input (Brakeman flags the assembled form). The queries
+    # below interpolate the same fragments but bind their values via #sanitize.
+    DUPLICATE_GROUPS_WITH_TAXONOMY_SQL = <<~SQL.freeze
+      SELECT COALESCE(c.store_id, t.store_id) AS sid, c.permalink
+      FROM spree_categories c
+      LEFT JOIN spree_taxonomies t ON t.id = c.taxonomy_id
+      WHERE c.permalink IS NOT NULL AND COALESCE(c.store_id, t.store_id) IS NOT NULL
+      GROUP BY COALESCE(c.store_id, t.store_id), c.permalink
+      HAVING COUNT(*) > 1
+    SQL
+
+    TRANSLATION_GROUPS_WITH_TAXONOMY_SQL = <<~SQL.freeze
+      SELECT COALESCE(c.store_id, t.store_id) AS sid, tr.locale, tr.permalink
+      FROM spree_category_translations tr
+      INNER JOIN spree_categories c ON c.id = tr.spree_category_id
+      LEFT JOIN spree_taxonomies t ON t.id = c.taxonomy_id
+      WHERE tr.permalink IS NOT NULL AND COALESCE(c.store_id, t.store_id) IS NOT NULL
+      GROUP BY COALESCE(c.store_id, t.store_id), tr.locale, tr.permalink
+      HAVING COUNT(*) > 1
+    SQL
+
+    TRANSLATION_GROUPS_SQL = <<~SQL.freeze
+      SELECT c.store_id AS sid, tr.locale, tr.permalink
+      FROM spree_category_translations tr
+      INNER JOIN spree_categories c ON c.id = tr.spree_category_id
+      WHERE tr.permalink IS NOT NULL AND c.store_id IS NOT NULL
+      GROUP BY c.store_id, tr.locale, tr.permalink
+      HAVING COUNT(*) > 1
+    SQL
+
+    DUPLICATE_GROUPS_SQL = <<~SQL.freeze
+      SELECT c.store_id AS sid, c.permalink
+      FROM spree_categories c
+      WHERE c.permalink IS NOT NULL AND c.store_id IS NOT NULL
+      GROUP BY c.store_id, c.permalink
+      HAVING COUNT(*) > 1
+    SQL
+
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter]
+    def initialize(connection = ActiveRecord::Base.connection)
+      @connection = connection
+      @permalinks_by_store = {}
+    end
+
+    # Rewrites every duplicate permalink, keeping the lowest-id row in each group
+    # and re-prefixing each rewritten row's descendants so subtree paths stay
+    # consistent with their parents.
+    #
+    # @return [Integer] number of categories whose permalink changed
+    def call
+      return 0 unless connection.table_exists?('spree_categories')
+
+      renamed = 0
+
+      # Re-queried each round rather than snapshotted once: re-prefixing a
+      # subtree can move a descendant onto a path some other row already holds,
+      # and that collision has to be resolved too or the unique index cannot be
+      # created. Each round strictly reduces the duplicates, so this terminates.
+      while (groups = duplicate_groups).any?
+        # A cascade rewrites descendants directly, so the cached permalink sets
+        # are stale by the end of a round.
+        @permalinks_by_store.clear
+        moved = resolve_groups(groups)
+        break if moved.zero? # defensive: never spin if a group cannot be moved
+
+        renamed += moved
+      end
+
+      # Independent of the base pass: a store whose base permalinks are already
+      # unique can still hold colliding translated ones, and the storefront
+      # resolves categories through that table.
+      renamed + rewrite_translations
+    end
+
+    private
+
+    # @return [Integer] rows moved in this round
+    def resolve_groups(groups)
+      moved = 0
+
+      groups.each do |store_id, permalink|
+        ids = ids_for(store_id, permalink)
+        # The first row keeps the permalink; the rest have to move.
+        ids.drop(1).each do |id|
+          candidate = unique_permalink(permalink, id, store_id)
+          rewrite(id, permalink, candidate)
+          permalinks_for(store_id) << candidate
+          moved += 1
+        end
+      end
+
+      moved
+    end
+
+    private
+
+    attr_reader :connection
+
+    # Binds values as parameters rather than interpolating them, so no user- or
+    # data-derived string is ever spliced into SQL text.
+    def sanitize(sql, *binds)
+      ActiveRecord::Base.sanitize_sql_array([sql, *binds])
+    end
+
+    # Groups by the store a category belongs to *or is about to*: rows still
+    # awaiting the upgrade backfill have a NULL store_id but resolve one through
+    # their taxonomy, and they collide the moment that backfill assigns it. Both
+    # cases have to be resolved before the unique index sees them.
+    #
+    # @return [Array<Array(Integer, String)>] (store_id, permalink) pairs appearing more than once
+    # Shallowest paths first. A parent must be rewritten before its children, so
+    # the subtree re-prefix in #rewrite fixes them; otherwise a child rewritten
+    # first gets a suffix of its own and is then re-prefixed too, leaving paths
+    # like "catalog-shop-b/kids-shop-b". SQL returns groups in no defined order.
+    def duplicate_groups
+      rows = connection.select_rows(taxonomies_table? ? DUPLICATE_GROUPS_WITH_TAXONOMY_SQL : DUPLICATE_GROUPS_SQL)
+      rows.sort_by { |_store_id, permalink| permalink.to_s.count('/') }
+    end
+
+    def ids_for(store_id, permalink)
+      connection.select_values(sanitize(<<~SQL, store_id, permalink))
+        SELECT c.id FROM spree_categories c
+        #{taxonomy_join}
+        WHERE #{effective_store_id} = ? AND c.permalink = ?
+        ORDER BY c.id
+      SQL
+    end
+
+    def taxonomy_join
+      return '' unless taxonomies_table?
+
+      'LEFT JOIN spree_taxonomies t ON t.id = c.taxonomy_id'
+    end
+
+    def effective_store_id
+      taxonomies_table? ? 'COALESCE(c.store_id, t.store_id)' : 'c.store_id'
+    end
+
+    def taxonomies_table?
+      return @taxonomies_table unless @taxonomies_table.nil?
+
+      @taxonomies_table = connection.table_exists?('spree_taxonomies')
+    end
+
+    # Appends the owning taxonomy's name, falling back to a numeric suffix when
+    # that is absent or itself taken.
+    def unique_permalink(permalink, id, store_id)
+      candidate = [permalink, taxonomy_suffix(id)].compact.join('-')
+      return candidate unless taken?(candidate, store_id)
+
+      counter = 2
+      counter += 1 while taken?("#{candidate}-#{counter}", store_id)
+      "#{candidate}-#{counter}"
+    end
+
+    def taxonomy_suffix(id)
+      return nil unless taxonomies_table?
+
+      name = connection.select_value(sanitize(<<~SQL, id))
+        SELECT t.name FROM spree_taxonomies t
+        INNER JOIN spree_categories c ON c.taxonomy_id = t.id
+        WHERE c.id = ?
+      SQL
+
+      name.presence && name.to_s.parameterize.presence
+    end
+
+    def taken?(permalink, store_id)
+      permalinks_for(store_id).include?(permalink)
+    end
+
+    # Every permalink in the store, loaded once. COALESCE on store_id defeats the
+    # index, so testing candidates in memory beats a scan per candidate — and the
+    # numeric-suffix loop tries several per collision.
+    def permalinks_for(store_id)
+      @permalinks_by_store[store_id] ||= connection.select_values(sanitize(<<~SQL, store_id)).compact.to_set
+        SELECT c.permalink FROM spree_categories c
+        #{taxonomy_join}
+        WHERE #{effective_store_id} = ? AND c.permalink IS NOT NULL
+      SQL
+    end
+
+    # Moves the row and re-prefixes its subtree, so a child of "catalog" becomes a
+    # child of "catalog-shop-b" rather than keeping the old parent's path.
+    def rewrite(id, old_permalink, candidate)
+      connection.update(sanitize('UPDATE spree_categories SET permalink = ? WHERE id = ?', candidate, id))
+
+      descendants(id).each do |descendant_id, current|
+        next if current.blank? || !current.start_with?("#{old_permalink}/")
+
+        moved = current.sub("#{old_permalink}/", "#{candidate}/")
+        connection.update(sanitize('UPDATE spree_categories SET permalink = ? WHERE id = ?', moved, descendant_id))
+      end
+    end
+
+    # The storefront resolves a category by its *translated* permalink
+    # (`scope.i18n.find_by!(permalink:)`), and that table carries no uniqueness
+    # constraint — so a collision there survives the base-column pass and makes
+    # the lookup return whichever row it happens to reach first. Each locale is a
+    # separate namespace, so each is deduplicated on its own.
+    def rewrite_translations
+      return 0 unless connection.table_exists?('spree_category_translations')
+
+      renamed = 0
+
+      while (groups = translation_duplicate_groups).any?
+        moved = resolve_translation_groups(groups)
+        break if moved.zero?
+
+        renamed += moved
+      end
+
+      renamed
+    end
+
+    # @return [Integer] translation rows moved in this round
+    def resolve_translation_groups(groups)
+      renamed = 0
+
+      groups.each do |store_id, locale, permalink|
+        rows = translation_rows_for(store_id, locale, permalink)
+        taken = translation_permalinks_for(store_id, locale)
+
+        # The first row keeps the permalink; the rest have to move.
+        rows.drop(1).each do |translation_id, category_id|
+          counter = 2
+          counter += 1 while taken.include?("#{permalink}-#{counter}")
+          candidate = "#{permalink}-#{counter}"
+          taken << candidate
+
+          move_translation(translation_id, candidate)
+          # Children's translated paths are built from the parent's, so they have
+          # to follow it exactly as they do on the base column.
+          reprefix_descendant_translations(category_id, locale, permalink, candidate)
+          renamed += 1
+        end
+      end
+
+      renamed
+    end
+
+    def move_translation(translation_id, permalink)
+      connection.update(
+        sanitize('UPDATE spree_category_translations SET permalink = ? WHERE id = ?', permalink, translation_id)
+      )
+    end
+
+    def reprefix_descendant_translations(category_id, locale, old_permalink, new_permalink)
+      descendants(category_id).each do |descendant_id, _base_permalink|
+        row = connection.select_rows(sanitize(<<~SQL, descendant_id, locale)).first
+          SELECT id, permalink FROM spree_category_translations
+          WHERE spree_category_id = ? AND locale = ?
+        SQL
+        next if row.nil?
+
+        translation_id, current = row
+        next if current.blank? || !current.start_with?("#{old_permalink}/")
+
+        move_translation(translation_id, current.sub("#{old_permalink}/", "#{new_permalink}/"))
+      end
+    end
+
+    # Every (store, locale, permalink) appearing more than once, across all stores.
+    # Shallowest first, for the same reason as #duplicate_groups.
+    def translation_duplicate_groups
+      rows = connection.select_rows(taxonomies_table? ? TRANSLATION_GROUPS_WITH_TAXONOMY_SQL : TRANSLATION_GROUPS_SQL)
+      rows.sort_by { |_store_id, _locale, permalink| permalink.to_s.count('/') }
+    end
+
+    def translation_rows_for(store_id, locale, permalink)
+      connection.select_rows(sanitize(<<~SQL, store_id, locale, permalink))
+        SELECT tr.id, tr.spree_category_id
+        FROM spree_category_translations tr
+        INNER JOIN spree_categories c ON c.id = tr.spree_category_id
+        #{taxonomy_join}
+        WHERE #{effective_store_id} = ? AND tr.locale = ? AND tr.permalink = ?
+        ORDER BY tr.id
+      SQL
+    end
+
+    def translation_permalinks_for(store_id, locale)
+      connection.select_values(sanitize(<<~SQL, store_id, locale)).compact.to_set
+        SELECT tr.permalink
+        FROM spree_category_translations tr
+        INNER JOIN spree_categories c ON c.id = tr.spree_category_id
+        #{taxonomy_join}
+        WHERE #{effective_store_id} = ? AND tr.locale = ? AND tr.permalink IS NOT NULL
+      SQL
+    end
+
+    # Walks the parent chain rather than using lft/rgt, which may be stale on rows
+    # an installation has not rebuilt. One query per depth level, not per node.
+    #
+    # @return [Array<Array(Integer, String)>] (id, permalink) of every descendant
+    def descendants(id)
+      collected = []
+      frontier = [id]
+
+      until frontier.empty?
+        rows = connection.select_rows(
+          sanitize('SELECT id, permalink FROM spree_categories WHERE parent_id IN (?)', frontier)
+        )
+        break if rows.empty?
+
+        collected.concat(rows)
+        frontier = rows.map(&:first)
+      end
+
+      collected
+    end
+  end
+end

data/lib/spree/checkout/default_requirements.rb

@@ -0,0 +1,134 @@
+module Spree
+  module Checkout
+    # Built-in checkout requirements that map to the standard Spree checkout flow.
+    #
+    # Checks line items, email, shipping address, shipping method, and payment
+    # against the cart — checkout is a cart-phase concern. The heavier
+    # completion-only checks (per-item stock, discontinued products, guest
+    # policy) run only when +completion: true+ is passed, so the advisory
+    # requirements feed on cart reads stays cheap.
+    #
+    # @see Requirements
+    class DefaultRequirements
+      # @param cart [Spree::Cart]
+      def initialize(cart)
+        @cart = cart
+      end
+
+      # @param completion [Boolean] include the completion-only checks
+      # @return [Array<Hash{Symbol => String}>] unmet requirements as
+      #   +{ step:, field:, code:, message: }+ hashes
+      def call(completion: false)
+        requirements = advisory_requirements
+        return requirements unless completion
+
+        requirements + completion_requirements
+      end
+
+      private
+
+      def advisory_requirements
+        [].tap do |r|
+          r << req('cart', 'line_items', Spree.t('checkout_requirements.line_items_required')) unless @cart.line_items.any?
+          r << req('address', 'email', Spree.t('checkout_requirements.email_required')) unless @cart.email.present?
+          r << req('address', 'ship_address', Spree.t('checkout_requirements.ship_address_required')) if @cart.shipping_address_required? && @cart.ship_address.blank?
+          r << req('delivery', 'delivery_method', Spree.t('checkout_requirements.delivery_method_required')) if delivery_step_required? && !delivery_method_selected?
+          r << req('payment', 'payment', Spree.t('checkout_requirements.payment_required')) if payment_required? && !payment_satisfied?
+          r << req('address', 'po_number', Spree.t('checkout_requirements.po_number_required')) if po_number_missing?
+          r << order_minimum_requirement if below_order_minimum?
+        end
+      end
+
+      def completion_requirements
+        errors = stock_errors + quantity_rule_errors
+        errors << req('address', 'email', Spree.t(:guest_checkout_not_allowed), code: 'guest_checkout_not_allowed') if @cart.guest_checkout_disallowed?
+        errors
+      end
+
+      # Re-checked at completion because an agreement can change between the
+      # add and the checkout — a company moved to a different tier, a term
+      # edited. Naming the nearest valid quantities rather than rounding: a
+      # silent adjustment on a wholesale order is a five-figure surprise.
+      def quantity_rule_errors
+        @cart.quantity_rule_violations.map do |_line_item, message|
+          req('cart', 'line_items', message, code: 'quantity_rule_violated')
+        end
+      end
+
+      # Advisory rather than completion-only: a buyer has to be able to build
+      # the order below the threshold and read how far off they are while
+      # they can still add to it. Completion refuses it because the advisory
+      # feed is included there too.
+      def below_order_minimum?
+        !@cart.staff_initiated? && @cart.below_order_minimum?
+      end
+
+      def order_minimum_requirement
+        minimum = @cart.order_minimum
+        shortfall = Spree::Money.new(@cart.order_minimum_shortfall, currency: minimum.currency)
+
+        req('cart', 'order_minimum',
+            Spree.t('checkout_requirements.order_minimum_not_met',
+                    minimum: minimum.display_amount.to_s, shortfall: shortfall.to_s),
+            code: 'order_minimum_not_met')
+      end
+
+      # Discontinuation is checked at both levels: a product can stay active
+      # while an individual variant hit its discontinue_on date after it
+      # entered the cart.
+      def stock_errors
+        @cart.line_items.includes(variant: :product).filter_map do |line_item|
+          if line_item.variant.nil? || line_item.variant.discontinued? || line_item.variant.product.discontinued?
+            req('cart', 'line_items', Spree.t('cart_line_item.discontinued', li_name: line_item.name), code: 'discontinued')
+          elsif !line_item.sufficient_stock?
+            req('cart', 'line_items', Spree.t('cart_line_item.out_of_stock', li_name: line_item.name), code: 'out_of_stock')
+          end
+        end
+      end
+
+      def delivery_step_required?
+        @cart.delivery_step_required?
+      end
+
+      def delivery_method_selected?
+        @cart.fulfillments.any? && @cart.fulfillments.all? { |fulfillment| fulfillment.delivery_method.present? }
+      end
+
+      def payment_required?
+        @cart.payment_required?
+      end
+
+      # What checkout has to collect, which is the whole total unless an
+      # arrangement collects only part of it up front.
+      def payment_satisfied?
+        @cart.payments.valid.sum(:amount) >= @cart.amount_due_at_checkout
+      end
+
+      # Advisory rather than completion-only: the buyer has to be told the
+      # reference is needed while they can still type it, not refused at the
+      # end of checkout. Staff keying an order in are exempt — the buyer's PO
+      # commonly arrives with the paperwork rather than at the till.
+      #
+      # Reported against `address` rather than `payment`: payment is dropped
+      # from the steps of a cart that owes nothing, and a requirement naming a
+      # step the buyer never visits is one they cannot clear.
+      def po_number_missing?
+        @cart.po_number.blank? && @cart.po_number_required? && !keyed_in_by_staff?
+      end
+
+      # Narrower than {Spree::Purchase::QuantityRules#staff_initiated?} on
+      # purpose. A buyer's PO reference commonly arrives with the paperwork,
+      # so only an order someone actually keyed in is excused — a draft with
+      # no recorded creator still has to ask for it. Quantity terms take the
+      # wider exemption: any draft order is the admin surface, and refusing
+      # staff there would make an agreed exception impossible to record.
+      def keyed_in_by_staff?
+        @cart.respond_to?(:created_by_id) && @cart.created_by_id.present?
+      end
+
+      def req(step, field, message, code: nil)
+        { step: step, field: field, code: code || "#{field}_required", message: message }
+      end
+    end
+  end
+end

data/lib/spree/checkout/registry.rb

@@ -0,0 +1,164 @@
+module Spree
+  module Checkout
+    # Global registry for custom checkout steps and requirements.
+    #
+    # Provides a composable extension point so developers can add, remove, or
+    # reorder checkout steps and attach extra requirements to existing steps —
+    # all without subclassing or monkey-patching.
+    #
+    # Registered steps and requirements are evaluated by {Requirements} at
+    # serialization time to produce the +requirements+ array on the Cart API.
+    #
+    # @example Add a custom step
+    #   Spree::Checkout::Registry.register_step(
+    #     name: :loyalty,
+    #     before: :payment,
+    #     satisfied: ->(cart) { cart.loyalty_verified? },
+    #     requirements: ->(cart) { [{ step: 'loyalty', field: 'loyalty_number', message: 'Required' }] }
+    #   )
+    #
+    # @example Add a requirement to an existing step
+    #   Spree::Checkout::Registry.add_requirement(
+    #     step: :payment,
+    #     field: :po_number,
+    #     message: 'PO number is required',
+    #     satisfied: ->(cart) { cart.po_number.present? }
+    #   )
+    #
+    # @example Remove a step
+    #   Spree::Checkout::Registry.remove_step(:loyalty)
+    class Registry
+      class << self
+        # Register a new custom checkout step.
+        #
+        # @param name [String, Symbol] unique step identifier
+        # @param satisfied [Proc] lambda accepting a cart, returns true when step is complete
+        # @param requirements [Proc] lambda accepting a cart, returns Array of requirement hashes
+        # @param options [Hash] additional options forwarded to {Step} (+:before+, +:after+, +:applicable+)
+        # @return [Array<Step>] the updated steps list
+        def register_step(name:, satisfied:, requirements:, **options)
+          steps << Step.new(name: name, satisfied: satisfied, requirements: requirements, **options)
+        end
+
+        # Add an extra requirement to an existing checkout step.
+        #
+        # @param step [String, Symbol] checkout step this requirement belongs to
+        # @param field [String, Symbol] field identifier
+        # @param message [String] human-readable validation message
+        # @param satisfied [Proc] lambda accepting a cart, returns true when met
+        # @param options [Hash] additional options forwarded to {Requirement} (+:applicable+)
+        # @return [Array<Requirement>] the updated requirements list
+        def add_requirement(step:, field:, message:, satisfied:, **options)
+          requirements << Requirement.new(step: step, field: field, message: message, satisfied: satisfied, **options)
+        end
+
+        # Remove a previously registered step by name.
+        #
+        # @param name [String, Symbol] step name to remove
+        # @return [Array<Step>] the updated steps list
+        def remove_step(name)
+          steps.reject! { |s| s.name == name.to_s }
+        end
+
+        # Remove a previously registered requirement by step and field.
+        #
+        # @param step [String, Symbol] checkout step the requirement belongs to
+        # @param field [String, Symbol] field identifier
+        # @return [Array<Requirement>] the updated requirements list
+        def remove_requirement(step:, field:)
+          requirements.reject! { |r| r.step == step.to_s && r.field == field.to_s }
+        end
+
+        # Canonical ordered built-in steps with their applicability — the ONE
+        # place the step vocabulary is declared. Keys are step names, values
+        # are nil (always applicable) or a lambda receiving the cart/order.
+        # Installs customize it directly:
+        #
+        #   Spree::Checkout::Registry.base_steps['payment'] = ->(cart) { cart.total > 0 }
+        #   Spree::Checkout::Registry.base_steps.delete('confirm')
+        #
+        # @return [Hash{String => Proc, nil}]
+        def base_steps
+          @base_steps ||= {
+            'address' => nil,
+            'delivery' => ->(record) { record.delivery_step_required? },
+            'payment' => ->(record) { record.payment_required? },
+            'confirm' => ->(record) { record.confirmation_required? },
+            'complete' => nil
+          }
+        end
+
+        # @return [Array<String>]
+        def base_step_names
+          base_steps.keys
+        end
+
+        # Reorder/remove built-in steps by name; known steps keep their
+        # default applicability.
+        #
+        # @param names [Array<String>]
+        def base_step_names=(names)
+          defaults = base_steps
+          @base_steps = names.map(&:to_s).index_with { |name| defaults[name] }
+        end
+
+        # The full ordered step list for a record: applicable base steps with
+        # applicable registered custom steps spliced at their before/after
+        # anchors (unanchored customs land before 'complete').
+        #
+        # @param record [Spree::Cart, Spree::Order]
+        # @return [Array<String>]
+        def step_names_for(record)
+          names = base_steps.filter_map do |name, applicable|
+            name if applicable.nil? || applicable.call(record)
+          end
+
+          ordered_steps.each do |step|
+            next unless step.applicable?(record)
+
+            anchor_index = names.index(step.before) || (names.index(step.after)&.+ 1)
+            names.insert(anchor_index || names.index('complete') || names.length, step.name)
+          end
+
+          names.uniq
+        end
+
+        # Returns steps sorted by +before+/+after+ constraints relative to
+        # {base_step_names}. Steps with anchors are ordered by the anchor's
+        # position; steps without constraints are appended at the end.
+        #
+        # @return [Array<Step>] steps in display order
+        def ordered_steps
+          return steps if steps.empty?
+
+          step_order = base_step_names.map(&:to_s)
+          positioned, unpositioned = steps.partition { |s| s.before || s.after }
+
+          sorted = positioned.sort_by do |s|
+            anchor = s.before || s.after
+            idx = step_order.index(anchor)
+            # before: inserts just before the anchor, after: just after
+            idx ? (s.before ? idx - 0.5 : idx + 0.5) : Float::INFINITY
+          end
+
+          sorted + unpositioned
+        end
+
+        # @return [Array<Step>] all registered steps
+        def steps = (@steps ||= [])
+
+        # @return [Array<Requirement>] all registered requirements
+        def requirements = (@requirements ||= [])
+
+        # Clear all registered steps and requirements. Intended for testing.
+        #
+        # @return [void]
+        def reset!
+          @steps = []
+          @requirements = []
+          @base_steps = nil
+        end
+      end
+    end
+  end
+end

data/lib/spree/checkout/requirement.rb

@@ -0,0 +1,49 @@
+module Spree
+  module Checkout
+    # Value object representing a single additional requirement registered via {Registry}.
+    #
+    # Unlike {Step}, a Requirement attaches extra validation to an *existing* checkout step
+    # rather than introducing a new step.
+    #
+    # @example Require a PO number for B2B orders at the payment step
+    #   Spree::Checkout::Registry.add_requirement(
+    #     step: :payment,
+    #     field: :po_number,
+    #     message: 'PO number is required for business accounts',
+    #     satisfied: ->(cart) { cart.po_number.present? },
+    #     applicable: ->(cart) { cart.account&.business? }
+    #   )
+    class Requirement
+      # @return [String] checkout step this requirement belongs to
+      attr_reader :step
+
+      # @return [String] field identifier (e.g. +"po_number"+, +"tax_id"+)
+      attr_reader :field
+
+      # @return [String] human-readable message shown when the requirement is not met
+      attr_reader :message
+
+      # @param step [String, Symbol] checkout step this requirement belongs to
+      # @param field [String, Symbol] field identifier
+      # @param message [String] human-readable validation message
+      # @param satisfied [Proc] lambda accepting a cart, returns true when met
+      # @param applicable [Proc] lambda accepting a cart, returns true when this requirement applies
+      #   (defaults to always applicable)
+      def initialize(step:, field:, message:, satisfied:, applicable: ->(_) { true })
+        @step = step.to_s
+        @field = field.to_s
+        @message = message
+        @satisfied_proc = satisfied
+        @applicable_proc = applicable
+      end
+
+      # @param cart [Spree::Cart]
+      # @return [Boolean] whether the requirement has been met
+      def satisfied?(cart) = @satisfied_proc.call(cart)
+
+      # @param cart [Spree::Cart]
+      # @return [Boolean] whether this requirement applies to the given cart
+      def applicable?(cart) = @applicable_proc.call(cart)
+    end
+  end
+end