spree_core 5.6.0 → 6.0.0.beta1

data/app/models/spree/payout_provider/base.rb

@@ -0,0 +1,218 @@
+module Spree
+  module PayoutProvider
+    # Contract for whatever actually moves money to a seller.
+    #
+    # Core records both levels of the ledger for every marketplace — what each
+    # seller earned as their orders shipped, and what has been settled to them.
+    # A provider decides whether that money moves on its own: the built-in one
+    # records and leaves the operator to pay by bank, while a connected
+    # provider performs the transfer and reports back.
+    #
+    # Three verbs, one per thing that can happen to money:
+    #
+    #   transfer! — a seller earned on a fulfilled order (level one)
+    #   pay!      — their accrued earnings are settled (level two)
+    #   reverse!  — a refund takes some of an earning back
+    #
+    # Every verb must be **idempotent**, keyed on the record's prefixed id: a
+    # crash between the remote call and the local commit is retried, and a
+    # retry must find the movement it already made rather than make a second.
+    #
+    # Providers are stateless and constructed without arguments, as tax and
+    # delivery-rate providers are; anything request-specific arrives as an
+    # argument.
+    class Base
+      # The name a merchant sees when choosing how sellers are paid.
+      #
+      # @return [String]
+      def self.display_name
+        name.demodulize.titleize
+      end
+
+      # What a ledger row records as having moved its money.
+      #
+      # The full class name rather than its last segment: every provider gem
+      # calls its class `PayoutProvider`, so the leaf alone identifies nothing
+      # and would make two gems' rows indistinguishable — including to the
+      # unique index on (provider, reference) that guards retries.
+      #
+      # @return [String]
+      def self.provider_key
+        name
+      end
+
+      # The key a seller's account with this provider is recorded under, as a
+      # {Spree::ExternalReference} system.
+      #
+      # Underscored rather than the class name, because a system key is a
+      # lowercase identifier by contract — and where a provider gem also ships
+      # a {Spree::Integration}, the convention is that the two agree, so a
+      # connector, its references and its settings page name the same thing.
+      #
+      # How a provider describes itself to the settings picker, so an operator
+      # chooses from what is actually installed and can see which of them this
+      # store could use today.
+      #
+      # @param store [Spree::Store]
+      # @return [Hash]
+      def self.to_api_hash(store)
+        {
+          id: name,
+          name: display_name,
+          available: available_for_store?(store),
+          requires_payout_account: requires_payout_account?,
+          default: name == Spree.default_payout_provider.to_s
+        }
+      end
+
+      # @return [String]
+      def self.reference_system
+        name.demodulize.underscore
+      end
+
+      # Whether this provider can be selected for a store — an external one
+      # overrides it to require connected credentials.
+      #
+      # @param store [Spree::Store]
+      # @return [Boolean]
+      def self.available_for_store?(_store)
+        true
+      end
+
+      # Whether this provider needs sellers to hold an account with it before
+      # they can be paid. A marketplace settling by bank transfer does not; a
+      # connected provider does, and core will not credit a seller it cannot
+      # pay through one.
+      #
+      # @return [Boolean]
+      def self.requires_payout_account?
+        false
+      end
+
+      # Where a seller goes to give this provider what it needs before it will
+      # pay them — bank details, identity documents, whatever it asks.
+      #
+      # Nil when there is nowhere to send them, which is the built-in
+      # provider's answer: an operator paying by bank transfer collects those
+      # details themselves, so the requirement is met by the operator marking
+      # it so rather than by the seller going anywhere.
+      #
+      # Implementations mint the link per call — hosted onboarding links are
+      # short-lived and single-use by design, so one is never stored.
+      #
+      # @param seller [Spree::Seller]
+      # @param refresh_url [String] where the provider sends a seller whose
+      #   link expired before they finished
+      # @param return_url [String] where it sends them when they are done
+      # @return [String, nil]
+      def onboarding_url(_seller, refresh_url:, return_url:)
+        nil
+      end
+
+      # Whether this provider will now accept money for a seller. Asked of the
+      # provider rather than read off the seller, because only the provider
+      # knows — and its answer can change without anything happening in Spree.
+      #
+      # @param seller [Spree::Seller]
+      # @return [Boolean]
+      def onboarded?(seller)
+        !self.class.requires_payout_account? || seller.payouts_enabled?
+      end
+
+      # Why a seller is not payable yet, in terms any provider can answer.
+      #
+      # Deliberately a state rather than a list of outstanding fields. What
+      # each provider is missing is its own vocabulary — field paths, document
+      # codes, review case ids — and none of it survives translation into a
+      # shared one. The reference provider goes further and asks not to be
+      # enumerated at all: its guidance is to send the seller back to the
+      # hosted flow, which already knows what it wants, rather than to
+      # reimplement its form badly.
+      #
+      # What a seller actually needs from this is which of three things is
+      # true, because each deserves different words and a different button:
+      #
+      #   nil       — nothing to say; they are payable, or no provider asks
+      #   :action   — the provider wants something from them
+      #   :pending  — the provider is checking, and nobody can hurry it
+      #   :rejected — the provider has refused them
+      #
+      # A provider may add a sentence of its own through {#onboarding_message},
+      # which is best-effort and unlocalized.
+      #
+      # @param _seller [Spree::Seller]
+      # @return [Symbol, nil]
+      def onboarding_state(_seller)
+        nil
+      end
+
+      # A provider's own words about what is outstanding, when it has any.
+      #
+      # Best-effort and **unlocalized** — providers write these in English and
+      # say so. Shown as supporting detail beside copy the panel has
+      # translated, never as the only explanation a seller gets.
+      #
+      # @param _seller [Spree::Seller]
+      # @return [String, nil]
+      def onboarding_message(_seller)
+        nil
+      end
+
+      # Credits a seller for one fulfilled order.
+      #
+      # @param seller_transfer [Spree::SellerTransfer]
+      # @return [Spree::SellerTransfer]
+      def transfer!(_seller_transfer)
+        raise NotImplementedError
+      end
+
+      # Settles a seller's accrued earnings.
+      #
+      # @param seller_payout [Spree::SellerPayout]
+      # @return [Spree::SellerPayout]
+      def pay!(_seller_payout)
+        raise NotImplementedError
+      end
+
+      # How much of what a seller is owed this provider can move right now.
+      #
+      # What the ledger says a seller has earned and what their account can
+      # actually send are different figures: money credited on fulfilment is
+      # only payable once the customer's payment settles. A provider that knows
+      # the difference answers it here, and the sweep settles what fits.
+      #
+      # Nil means there is no limit — the built-in provider moves no money, so
+      # everything owed is payable. A provider that cannot find out must raise
+      # rather than answer nil: the sweep settles the whole balance on nil, and
+      # asking for more than an account holds is what this exists to prevent.
+      #
+      # @param seller [Spree::Seller]
+      # @param currency [String]
+      # @return [BigDecimal, nil]
+      def available_payout(_seller, _currency)
+        nil
+      end
+
+      # Takes back part of an earning after a refund.
+      #
+      # The ledger row is written by core either way — the books stay correct
+      # in every tier — so a provider that cannot pull money back implements
+      # this as a no-op rather than refusing.
+      #
+      # @param seller_transfer [Spree::SellerTransfer] the reversal row
+      # @return [Spree::SellerTransfer]
+      def reverse!(_seller_transfer)
+        raise NotImplementedError
+      end
+
+      # The key a provider passes to its own API so a retried call cannot move
+      # money twice.
+      #
+      # @param record [Spree::SellerTransfer, Spree::SellerPayout]
+      # @return [String]
+      def idempotency_key(record)
+        "spree-#{record.prefixed_id}"
+      end
+    end
+  end
+end

data/app/models/spree/payout_provider/system.rb

@@ -0,0 +1,36 @@
+module Spree
+  module PayoutProvider
+    # The built-in provider: it keeps the books and moves no money.
+    #
+    # This is what a marketplace runs before it connects anything. Sellers
+    # accrue earnings as their orders ship, those earnings batch into
+    # settlements on schedule, and the operator sees exactly what is owed to
+    # whom — then pays it by bank transfer and marks the settlement complete.
+    #
+    # An earning is confirmed immediately, because with no remote party there
+    # is nothing to confirm: the seller has shipped and the marketplace holds
+    # their money. A settlement, by contrast, stays pending until somebody says
+    # it was actually sent — that is a claim about the outside world, and only
+    # a person can make it here.
+    class System < Base
+      def transfer!(seller_transfer)
+        seller_transfer.update!(status: 'completed')
+        seller_transfer
+      end
+
+      # Deliberately does nothing. The payout waits in the operator's queue
+      # until it is marked paid — recording it as settled here would assert a
+      # bank transfer nobody has made.
+      def pay!(seller_payout)
+        seller_payout
+      end
+
+      # The ledger row is the whole reversal. Nothing was ever sent, so
+      # nothing has to come back.
+      def reverse!(seller_transfer)
+        seller_transfer.update!(status: 'completed')
+        seller_transfer
+      end
+    end
+  end
+end

data/app/models/spree/permission_sets.rb

@@ -0,0 +1,17 @@
+module Spree
+  # Removed in Spree 6.0 — roles are data now (docs/plans/6.0-admin-rbac.md).
+  # The module survives only so 5.x initializers referencing the old set
+  # classes fail at boot with directions instead of a bare NameError.
+  module PermissionSets
+    UPGRADE_GUIDE_URL = 'https://spreecommerce.org/docs/developer/upgrades/5.6-to-6.0'
+
+    def self.const_missing(name)
+      raise Spree::PermissionConfiguration::PermissionSetsRemovedError,
+            "Spree::PermissionSets::#{name} was removed in Spree 6.0. Roles and their " \
+            'permissions are data now — manage them in the dashboard (Settings → Roles), ' \
+            'via the Admin API, or in seeds. Remove the permission lines from ' \
+            "config/initializers/spree.rb and recreate custom roles before deploying. " \
+            "Upgrade guide: #{UPGRADE_GUIDE_URL}"
+    end
+  end
+end

data/app/models/spree/pickup_point_option.rb

@@ -0,0 +1,28 @@
+module Spree
+  # Ephemeral value object returned by PickupPointProvider queries. Never
+  # persisted — the selected option is frozen into
+  # +fulfillment.pickup_point_data+ as plain JSON.
+  class PickupPointOption
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    attribute :external_id, :string
+    attribute :name, :string
+    attribute :address1, :string
+    attribute :address2, :string
+    attribute :city, :string
+    attribute :zipcode, :string
+    attribute :country_code, :string
+    attribute :latitude, :float
+    attribute :longitude, :float
+    attribute :provider, :string
+    attribute :metadata
+
+    validates :external_id, :name, presence: true
+
+    # @return [Hash] the JSON shape persisted into fulfillment.pickup_point_data
+    def to_pickup_point_data
+      attributes.compact.stringify_keys
+    end
+  end
+end

data/app/models/spree/pickup_point_provider/base.rb

@@ -0,0 +1,24 @@
+module Spree
+  module PickupPointProvider
+    # Contract for third-party pickup point networks (InPost lockers, DHL
+    # ServicePoints, ...). Points are ephemeral value objects — never
+    # persisted; the selected point is validated via +find_by_external_id+
+    # and frozen into +fulfillment.pickup_point_data+.
+    #
+    # Not yet a stable extension point: in 6.1 the constructor becomes
+    # +new(delivery_method)+ (credential access via the method's store
+    # integrations) and +find_nearby+ gains +zipcode:+/+query:+ params.
+    # Build third-party providers against 6.1, not this shape.
+    class Base
+      # @return [Array<Spree::PickupPointOption>]
+      def find_nearby(latitude:, longitude:, limit: 20)
+        raise NotImplementedError, "Please implement 'find_nearby' in your pickup point provider: #{self.class.name}"
+      end
+
+      # @return [Spree::PickupPointOption, nil]
+      def find_by_external_id(external_id)
+        raise NotImplementedError, "Please implement 'find_by_external_id' in your pickup point provider: #{self.class.name}"
+      end
+    end
+  end
+end

data/app/models/spree/policy.rb

@@ -4,6 +4,7 @@ module Spree
 
     extend FriendlyId
     include Spree::TranslatableResource
+    include Spree::SanitizableRichText
 
     UNIQUENESS_SCOPE = %i[owner_id owner_type].freeze
 
@@ -15,7 +16,7 @@ module Spree
     #
     # Associations
     #
-    belongs_to :owner, polymorphic: true, touch: true # can be a store or a vendor or organization
+    belongs_to :owner, polymorphic: true, touch: true # can be a store or a seller or organization
 
     #
     # Translations
@@ -25,9 +26,15 @@ module Spree
     translates(*TRANSLATABLE_FIELDS, column_fallback: Spree.mobility_column_fallback)
 
     #
-    # ActionText
+    # Rich text
     #
-    translates :body, backend: :action_text
+    has_spree_rich_text :body
+
+    self::Translation.class_eval do
+      include Spree::SanitizableRichText
+
+      sanitizes_rich_text :body
+    end
 
     #
     # Validations
@@ -39,8 +46,8 @@ module Spree
     #
     # Scopes
     #
-    scope :with_body, -> { joins(:rich_text_body).distinct }
-    scope :without_body, -> { where.missing(:rich_text_body) }
+    scope :with_body, -> { where.not(body: [nil, '']) }
+    scope :without_body, -> { where(body: [nil, '']) }
     scope :with_matching_name, ->(name_to_match) do
       value = name_to_match.to_s.strip.downcase
 
@@ -58,12 +65,6 @@ module Spree
 
     before_destroy :really_destroy_slugs!
 
-    # For policies, store.policies returns all policies owned by the store
-    # We don't want to filter out other policies in requests that use `for_store` when they have a different owner type
-    def self.for_store(store)
-      store.policies.or(where.not(owner_type: 'Spree::Store'))
-    end
-
     def with_body?
       body.present?
     end

data/app/models/spree/price.rb

@@ -1,8 +1,16 @@
 module Spree
   class Price < Spree.base_class
+    # Which engine produced this answer — nil for Spree's own catalog, a
+    # provider's registry key otherwise. Transient: set by
+    # Spree::Pricing::PriceResolution on the way out and copied onto the line
+    # item as price_source. Not a column, because a catalog row is the same
+    # row whoever asked for it.
+    attr_accessor :price_source
+
     has_prefix_id :price
 
     include Spree::VatPriceCalculation
+    include Spree::StorePreferences
 
     publishes_lifecycle_events
 
@@ -10,6 +18,12 @@ module Spree
 
     MAXIMUM_AMOUNT = BigDecimal('99_999_999.99')
 
+    # How many breaks one variant may carry on one list in one currency. A UI
+    # sanity bound rather than a technical one — but enforced here so no
+    # writer can get past it, since the resolver scans a variant's rows for
+    # every priced line (docs/plans/6.0-volume-pricing.md).
+    MAXIMUM_BREAKS_PER_VARIANT = 10
+
     belongs_to :variant, -> { with_deleted }, class_name: 'Spree::Variant', inverse_of: :prices, touch: true
     belongs_to :price_list, class_name: 'Spree::PriceList', optional: true
 
@@ -38,10 +52,17 @@ module Spree
 
     validates :currency, presence: true
 
+    validates :min_quantity, presence: true,
+              numericality: { only_integer: true, greater_than: 0 }
+    validate :break_requires_price_list
+    validate :breaks_within_cap
+
     scope :with_currency, ->(currency) { where(currency: currency) }
     scope :non_zero, -> { where.not(amount: [nil, 0]) }
     scope :discounted, -> { where('compare_at_amount > amount') }
     scope :base_prices, -> { where(price_list_id: nil) }
+    # A variant's rungs above its ordinary price on a list.
+    scope :breaks, -> { where.not(min_quantity: 1) }
     scope :for_price_list, ->(price_list) { where(price_list_id: price_list) }
     scope :for_products, lambda { |products, currency = nil|
       currency ||= Spree::Store.default.default_currency
@@ -55,7 +76,7 @@ module Spree
     money_methods :amount, :price, :compare_at_amount
     alias display_compare_at_price display_compare_at_amount
 
-    self.whitelisted_ransackable_attributes = %w[amount compare_at_amount currency price_list_id variant_id]
+    self.whitelisted_ransackable_attributes = %w[amount compare_at_amount currency min_quantity price_list_id variant_id]
     self.whitelisted_ransackable_associations = %w[variant price_list]
     self.whitelisted_ransackable_scopes = %i[search]
 
@@ -70,9 +91,9 @@ module Spree
       where(variant_id: Spree::Variant.search(query).select(:id))
     }
 
-    attribute :eligible_for_taxon_matching, :boolean, default: false
-    before_validation -> { self.eligible_for_taxon_matching = new_record? ? discounted? : discounted? != was_discounted? }
-    after_commit -> { variant&.product&.auto_match_taxons }, if: -> { eligible_for_taxon_matching? }
+    attribute :eligible_for_collection_matching, :boolean, default: false
+    before_validation -> { self.eligible_for_collection_matching = new_record? ? discounted? : discounted? != was_discounted? }
+    after_commit -> { variant&.product&.auto_match_collections }, if: -> { eligible_for_collection_matching? }
 
     def money
       Spree::Money.new(amount || 0, currency: currency.upcase)
@@ -119,12 +140,34 @@ module Spree
     alias_attribute :compare_at_price, :compare_at_amount
     alias_method :compare_at_price=, :compare_at_amount=
 
+    # Whether this figure is the merchant's answer for the buyer's geography
+    # already. A price list narrowed by market or country states its prices for
+    # that geography, so they are charged exactly as entered — restating one would
+    # net it out with the *home* rate and destroy the price point the merchant
+    # chose. Lists narrowed by anything else (a quantity, a group) were not set
+    # for a country, so their prices restate like any other.
+    #
+    # @return [Boolean]
+    def final_for_destination?
+      rules = price_list&.price_rules.to_a
+      return false unless rules.any?(&:geographic?)
+
+      # Under 'any' the list can win on a non-geographic rule alone, so a
+      # geographic rule being present does not mean this buyer's geography is why
+      # the price applied. Under 'all' every rule matched, so it does.
+      price_list.match_policy == 'all' || rules.all?(&:geographic?)
+    end
+
     def price_including_vat_for(price_options)
+      return price if final_for_destination?
+
       options = price_options.merge(tax_category: variant.tax_category)
       gross_amount(price, options)
     end
 
     def compare_at_price_including_vat_for(price_options)
+      return compare_at_price if final_for_destination?
+
       options = price_options.merge(tax_category: variant.tax_category)
       gross_amount(compare_at_price, options)
     end
@@ -180,13 +223,56 @@ module Spree
       price_histories.where(recorded_at: 30.days.ago..).order(:amount).first
     end
 
+    # Prices carry no store of their own; the variant's product owns it.
+    # @return [Spree::Store, nil]
+    def preference_store
+      variant&.product&.store
+    end
+
+    # Whether this row is a quantity break rather than the list's ordinary
+    # price for the variant.
+    # @return [Boolean]
+    def quantity_break?
+      min_quantity.to_i > 1
+    end
+
     private
 
+    # Base prices are what a shopper is quoted on a product page, and a
+    # quantity-dependent shop price would make every PDP quantity-dependent —
+    # a storefront surface v1 deliberately does not open
+    # (docs/plans/6.0-volume-pricing.md). Lifting this later is deleting this
+    # method; the column is already the right one.
+    def break_requires_price_list
+      return unless quantity_break?
+      return if price_list_id.present?
+
+      errors.add(:min_quantity, :requires_price_list)
+    end
+
+    # Counted the way the constant is named: breaks *above* the bottom rung,
+    # so a variant priced at one figure plus ten breaks is exactly at the
+    # limit. Placeholder rows carry no amount and charge nothing, so they do
+    # not fill the ladder — the bulk path counts the same rows, and a cap two
+    # writers disagree about is one that refuses what it just allowed.
+    def breaks_within_cap
+      return unless quantity_break?
+      return if price_list_id.blank? || variant_id.blank? || currency.blank?
+      return unless will_save_change_to_attribute?(:min_quantity) || new_record?
+
+      siblings = self.class.where(variant_id: variant_id, currency: currency, price_list_id: price_list_id).
+                 breaks.where.not(amount: nil)
+      siblings = siblings.where.not(id: id) if persisted?
+      return if siblings.count < MAXIMUM_BREAKS_PER_VARIANT
+
+      errors.add(:min_quantity, :too_many_breaks, count: MAXIMUM_BREAKS_PER_VARIANT)
+    end
+
     def should_record_price_history?
       price_list_id.nil? &&
         amount.present? &&
         saved_change_to_amount? &&
-        Spree::Config[:track_price_history]
+        store_preference(:track_price_history)
     end
 
     def record_price_history

data/app/models/spree/price_adjustment_tier.rb

@@ -0,0 +1,63 @@
+module Spree
+  # One band of a price list's percentage adjustment: from this quantity up,
+  # the list adjusts base prices by this percentage instead of the one on its
+  # own `price_adjustment_percentage` column.
+  #
+  # The column stays the list's quantity-1 value, so a list carrying no tiers
+  # prices exactly as it did before bands existed. A band adjusts the *base*
+  # price, like the column does — never a previous band's result — so a
+  # merchant reading "-20% from fifty" gets twenty percent off the shop price
+  # and not twenty percent off an already-discounted number
+  # (docs/plans/6.0-volume-pricing.md).
+  class PriceAdjustmentTier < Spree.base_class
+    has_prefix_id :pat
+
+    # How many bands one list may carry, matching the break cap so a merchant
+    # meets one number rather than two.
+    MAXIMUM_TIERS_PER_LIST = Spree::Price::MAXIMUM_BREAKS_PER_VARIANT
+
+    belongs_to :price_list, class_name: 'Spree::PriceList', inverse_of: :price_adjustment_tiers, touch: true
+
+    validates :min_quantity, presence: true,
+              numericality: { only_integer: true, greater_than: 1 },
+              uniqueness: { scope: :price_list_id }
+    # The same bounds the list's own column carries: at -100 every derived
+    # price is zero, below it the arithmetic goes negative, and above 1000 the
+    # decimal(6,3) column cannot hold the value.
+    # Zero is refused rather than accepted and then ignored: "0% from ten"
+    # reads as "no further discount at this tier", but a factor of exactly 1
+    # makes the list decline to price the line at all, so it would fall
+    # through to the next list or base — the opposite of what it says
+    # (docs/plans/6.0-volume-pricing.md). Removing the band is how a merchant
+    # says the ladder stops here.
+    validates :percentage, presence: true,
+              numericality: { greater_than: -100, less_than: 1000, other_than: 0 }
+    validate :tiers_within_cap
+
+    scope :by_quantity, -> { order(min_quantity: :asc) }
+
+    # No ransack allowlist: a band is reached only through the list that owns
+    # it, exactly like a PriceRule, and there is no endpoint that filters
+    # bands. An entry here would be a filter any caller could run against a
+    # model that carries no store of its own.
+
+    private
+
+    # Quantity 1 is the list's own column, so a band at 1 would be a second
+    # answer to a question already answered — refused by the numericality
+    # bound above rather than silently shadowing the column.
+    def tiers_within_cap
+      return if price_list.nil?
+
+      # Counted over the ladder the save will leave behind, not the rows
+      # standing now: replacing a full ladder marks the old bands for
+      # destruction and builds the new ones, so counting the database would
+      # see both halves and refuse a swap that ends the size it began
+      # (docs/plans/6.0-volume-pricing.md).
+      siblings = price_list.price_adjustment_tiers.reject { |tier| tier.marked_for_destruction? || tier == self }
+      return if siblings.size < MAXIMUM_TIERS_PER_LIST
+
+      errors.add(:base, :too_many_tiers, count: MAXIMUM_TIERS_PER_LIST)
+    end
+  end
+end

data/app/models/spree/price_history.rb

@@ -3,7 +3,7 @@
 module Spree
   class PriceHistory < Spree.base_class
     belongs_to :price, class_name: 'Spree::Price'
-    belongs_to :variant, class_name: 'Spree::Variant'
+    belongs_to :variant, -> { with_deleted }, class_name: 'Spree::Variant'
 
     validates :amount, presence: true, numericality: { greater_than_or_equal_to: 0 }
     validates :currency, presence: true