spree_core 5.6.1 → 6.0.0.beta2

data/app/models/concerns/spree/acted_by.rb

@@ -0,0 +1,210 @@
+module Spree
+  # Declares a "who performed this action" association — the canceler of an
+  # order, the receiver of a stock delivery, the opener of a return.
+  #
+  #   class Spree::Order < Spree.base_class
+  #     include Spree::ActedBy
+  #     acted_by :created_by, :approver, :canceler
+  #   end
+  #
+  # Each name becomes an optional polymorphic `belongs_to` whose type column is
+  # validated against `Spree.actor_classes`, so a row can only ever name a
+  # registered actor — an admin user, an API key, or a class an extension
+  # registered. See docs/plans/6.0-action-actors.md.
+  #
+  # Association names, readers and writers are the ones a plain `belongs_to`
+  # would give, so the workflows that assign these (`order.canceler = canceler`)
+  # are untouched by the conversion.
+  module ActedBy
+    extend ActiveSupport::Concern
+
+    # Every model that declares at least one `acted_by` association, so a
+    # caller sweeping actor columns — the backfill task, a user's erasure —
+    # walks all of them without being handed a list.
+    #
+    # The registry fills as models load, so it eager-loads first: in
+    # development nothing is loaded until something references it, and a
+    # caller that silently skipped an unloaded model would leave a deleted
+    # person's id behind or half-finish an upgrade.
+    #
+    # Names are held rather than classes, and resolved on read, so a code
+    # reload does not leave the registry pointing at superseded copies of the
+    # same model.
+    #
+    # @return [Array<Class>]
+    def self.models
+      Rails.application&.eager_load! unless Rails.application&.config&.eager_load
+
+      registered_model_names.filter_map(&:safe_constantize)
+    end
+
+    # @api private
+    # @return [Set<String>]
+    def self.registered_model_names
+      @registered_model_names ||= Set.new
+    end
+
+    included do
+      # The names declared on this class, so the backfill task can ask a model
+      # what it records without being told. Inherited and extended per class,
+      # never assigned, so a subclass adding one does not blank its parent's.
+      class_attribute :acted_by_associations, default: [], instance_writer: false
+    end
+
+    # The class an actor column names, answering what the reader would resolve
+    # rather than what the column literally holds: a row the backfill has not
+    # reached carries an id and no type, and the reader resolves it through
+    # the admin user class. Serializers read this so `<name>_id` and
+    # `<name>_type` never disagree about the same row.
+    #
+    # @param name [Symbol, String] the acted_by association
+    # @return [String, nil]
+    def acted_by_type(name)
+      stored = self[:"#{name}_type"]
+      return stored if stored.present?
+
+      Spree.admin_user_class.to_s if self[:"#{name}_id"].present?
+    end
+
+    # The actor's prefixed id, encoded from the columns without loading the
+    # row — so a page of orders costs no query per actor it names. Paired with
+    # {#acted_by_type} so the id and the kind always describe the same row,
+    # including one the backfill has not reached.
+    #
+    # @param name [Symbol, String] the acted_by association
+    # @return [String, nil]
+    def acted_by_prefixed_id(name)
+      Spree::Base.polymorphic_prefixed_id(acted_by_type(name), self[:"#{name}_id"])
+    end
+
+    # Names the admin user class on every un-backfilled row of `record`'s
+    # lazily-preloaded group, so the association preloads as one query rather
+    # than one per row. Writes the in-memory attribute only; nothing is saved.
+    #
+    # @api private
+    # @param record [ActiveRecord::Base]
+    # @param name [Symbol] the acted_by association
+    # @return [void]
+    def self.assume_admin_actor_type(record, name)
+      type_column = :"#{name}_type"
+      admin_type = Spree.admin_user_class.to_s
+      group = record.try(:lazy_preload_context)&.records.presence || [record]
+
+      group.each do |sibling|
+        next unless sibling.instance_of?(record.class)
+        next if sibling[type_column].present? || sibling[:"#{name}_id"].blank?
+
+        sibling[type_column] = admin_type
+      end
+    end
+
+    # Both halves of an actor column, for a caller writing through
+    # `update_columns` or `update_all` rather than through the association —
+    # an id without its type names nothing, so the pair is produced together
+    # and never by hand.
+    #
+    #   changes.merge!(Spree::ActedBy.columns_for(:canceler, canceler))
+    #
+    # The actor is checked against the registry here because these writes go
+    # through `update_columns` / `update_all`, which skip validation — without
+    # it an unregistered actor persists as a row the model itself calls
+    # invalid.
+    #
+    # @param name [Symbol, String] the acted_by association
+    # @param actor [Object, nil]
+    # @raise [ArgumentError] when the actor's class is not registered
+    # @return [Hash{Symbol => Object, nil}]
+    def self.columns_for(name, actor)
+      type = actor && actor.class.polymorphic_name
+
+      if type.present? && Spree.actor_classes.exclude?(type)
+        raise ArgumentError, "#{type} is not a registered actor class — add it to Spree.actor_classes"
+      end
+
+      { :"#{name}_id" => actor&.id, :"#{name}_type" => type }
+    end
+
+    class_methods do
+      # @param names [Array<Symbol>] the association names to declare
+      # @return [void]
+      def acted_by(*names)
+        names = names.map(&:to_sym)
+        self.acted_by_associations = acted_by_associations + names
+        # An anonymous class — one built in a spec or a console — has no name
+        # to register, and a nil in the registry would break every later read.
+        Spree::ActedBy.registered_model_names << name_for_actor_registry if name_for_actor_registry
+
+        names.each do |name|
+          belongs_to name, polymorphic: true, optional: true
+
+          validate_actor_type(name)
+          define_transitional_actor_reader(name)
+        end
+      end
+
+      private
+
+      # STI subclasses register under the base class, whose table the backfill
+      # updates; an anonymous class registers nothing.
+      def name_for_actor_registry
+        base_class.name
+      end
+
+      def validate_actor_type(name)
+        type_column = :"#{name}_type"
+
+        validate do
+          value = self[type_column]
+          next if value.blank? || Spree.actor_classes.include?(value)
+
+          errors.add(type_column, :unregistered_actor,
+                     message: Spree.t('errors.messages.unregistered_actor'))
+        end
+      end
+
+      # Rows written before the type column existed carry an id and no type,
+      # which a polymorphic association reads as nil. Until the backfill task
+      # has run they resolve through the admin user class, the only thing they
+      # could ever have pointed at.
+      #
+      # The type is filled in on the in-memory attribute and the ordinary
+      # association reader does the rest, so the fallback keeps every benefit
+      # the association has — preloading included. Resolving it with a direct
+      # `find_by` instead would sidestep `ar_lazy_preload`, turning a page of
+      # 25 orders into 75 queries while the backfill is outstanding.
+      #
+      # Nothing is saved: `[]=` writes the attribute, and a record whose only
+      # change is this would still need an explicit save to persist it.
+      # Prepended rather than defined outright, so `super` reaches the
+      # generated reader.
+      #
+      # Removed in 6.1, once the backfill is a release behind.
+      def define_transitional_actor_reader(name)
+        transitional_actor_readers.module_eval do
+          define_method(name) do
+            return super() if self[:"#{name}_type"].present?
+            return super() if self[:"#{name}_id"].blank?
+
+            Spree::Deprecation.warn(
+              "#{self.class.name}##{name} resolved through #{Spree.admin_user_class} because " \
+              "#{name}_type is blank. Run `rake spree:upgrade:backfill_actor_types`; the fallback " \
+              'is removed in Spree 6.1.'
+            )
+
+            # Fill the type across the whole lazily-preloaded group, not just
+            # this record: the preloader batches on the type it finds, and
+            # filling one row at a time as each is read produces a query per
+            # row instead of one for the page.
+            Spree::ActedBy.assume_admin_actor_type(self, name)
+            super()
+          end
+        end
+      end
+
+      # The per-class module the transitional readers live in, prepended once.
+      def transitional_actor_readers
+        @transitional_actor_readers ||= Module.new.tap { |mod| prepend(mod) }
+      end
+    end
+  end
+end

data/app/models/concerns/spree/actor.rb

@@ -0,0 +1,51 @@
+module Spree
+  # What a model must answer to be recorded as the performer of an action.
+  #
+  # Included in the admin user class and in {Spree::ApiKey}; an extension's App
+  # or bot class includes it too and registers itself in
+  # `Spree.actor_classes` (see docs/plans/6.0-action-actors.md).
+  #
+  # Both methods have defaults that read whatever the including class already
+  # offers, so a class that names itself in one of the usual ways needs no
+  # override.
+  module Actor
+    extend ActiveSupport::Concern
+
+    # The kinds core itself registers, for the generated `ActorKind` type.
+    #
+    # A literal list rather than one derived from `Spree.actor_classes`: that
+    # registry is filled after serializer classes load, so deriving it would
+    # make the generated types depend on boot order and on which extensions
+    # are installed. The union stays open on the wire, so an extension's kind
+    # is still a valid value — it just does not autocomplete.
+    BUILT_IN_KINDS = %w[admin_user api_key].freeze
+
+    # How a timeline names this actor: a person's full name or email, an API
+    # key's name, an app's title.
+    #
+    # @return [String, nil]
+    def actor_label
+      %i[full_name name email].each do |method|
+        next unless respond_to?(method)
+
+        value = public_send(method)
+        value = value.to_s if value.present?
+        return value if value.present?
+      end
+
+      nil
+    end
+
+    # The wire shorthand for this actor's kind — `admin_user`, `api_key`, …
+    # The same derivation every polymorphic type column on the Admin API uses.
+    #
+    # Read from `polymorphic_name`, which is what the `*_type` column stores,
+    # so an STI subclass of an actor answers the same kind on the expansion
+    # as it does in the column beside it.
+    #
+    # @return [String]
+    def actor_kind
+      Spree::Base.polymorphic_api_type(self.class.polymorphic_name)
+    end
+  end
+end

data/app/models/concerns/spree/admin_user_methods.rb

@@ -2,17 +2,13 @@ module Spree
   module AdminUserMethods
     extend ActiveSupport::Concern
 
+    include Spree::Actor
     include Spree::PrefixedId
     include Spree::UserRoles
     include Spree::RansackableAttributes
 
     included do
-      # Wins over Devise's implementation regardless of module include order, so
-      # host apps that add `devise ...` after this concern still send admin auth
-      # emails through Spree's mailer.
-      prepend Spree::AdminUserMethods::DeviseNotifications
-
-      has_prefix_id :admin
+      has_prefix_id :adm
 
       has_person_name
 
@@ -21,10 +17,11 @@ module Spree
       # Token auto-invalidates when password changes (salt changes)
       # Expiration is configurable via Spree::Config.admin_password_reset_expires_in (in minutes)
       generates_token_for :password_reset, expires_in: Spree::Config.admin_password_reset_expires_in.minutes do
-        # `try` rather than `&.`: models without a password_salt method or
-        # column at all (modern Devise) must fall through to encrypted_password
-        # — a bare call would raise NameError before the fallback.
-        try(:password_salt)&.last(10) || encrypted_password&.last(10)
+        # `try` rather than `&.`: a model that lacks the method/column entirely
+        # must fall through rather than raise NameError. `password_salt` covers
+        # has_secure_password (which derives it from password_digest);
+        # `encrypted_password` covers a legacy bcrypt column on a custom model.
+        try(:password_salt)&.last(10) || try(:encrypted_password)&.last(10)
       end
 
       def self.find_by_password_reset_token(token)
@@ -37,16 +34,23 @@ module Spree
 
       # Associations
       has_many :identities, class_name: 'Spree::UserIdentity', as: :user, dependent: :destroy
-      has_many :canceled_orders, class_name: 'Spree::Order', foreign_key: :canceler_id
-      has_many :created_orders, class_name: 'Spree::Order', foreign_key: :created_by_id
-      has_many :approved_orders, class_name: 'Spree::Order', foreign_key: :approver_id
+      # The order operations became polymorphic in 6.0, so these read through
+      # the association rather than a bare foreign key: matching on the id
+      # alone would hand this user the rows an API key with the same numeric
+      # id performed. The rest still point at admin users only and convert in
+      # 6.1 (see docs/plans/6.0-action-actors.md).
+      has_many :canceled_orders, class_name: 'Spree::Order', as: :canceler
+      has_many :created_orders, class_name: 'Spree::Order', as: :created_by
+      has_many :approved_orders, class_name: 'Spree::Order', as: :approver
+      has_many :refunded_refunds, class_name: 'Spree::Refund', as: :refunder
+      has_many :created_returns, class_name: 'Spree::Return', as: :created_by
+      has_many :created_exchanges, class_name: 'Spree::Exchange', as: :created_by
+      has_many :created_claims, class_name: 'Spree::Claim', as: :created_by
       has_many :created_gift_cards, class_name: 'Spree::GiftCard', foreign_key: :created_by_id
       has_many :created_gift_card_batches, class_name: 'Spree::GiftCardBatch', foreign_key: :created_by_id
-      has_many :refunded_refunds, class_name: 'Spree::Refund', foreign_key: :refunder_id
-      has_many :performed_reimbursements, class_name: 'Spree::Reimbursement', foreign_key: :performed_by_id
       has_many :created_store_credits, class_name: 'Spree::StoreCredit', foreign_key: :created_by_id
-      has_many :reports, class_name: 'Spree::Report', foreign_key: :user_id
       has_many :exports, class_name: 'Spree::Export', foreign_key: :user_id
+      has_many :saved_reports, class_name: 'Spree::SavedReport', foreign_key: :user_id
 
       # Callbacks
       after_destroy :nullify_approver_id_in_approved_orders
@@ -81,46 +85,53 @@ module Spree
     def nullify_approver_id_in_approved_orders
       return if self.class != Spree.admin_user_class
 
-      approved_orders.update_all(approver_id: nil, updated_at: Time.current)
+      clear_actor(Spree::Order, :approver)
     end
 
     def cleanup_admin_user_resources
       return if self.class != Spree.admin_user_class
 
-      # resources to nullify
-      # TODO: we should change these associations to polymorphic and resolve this via standard rails association
-      # declarations with dependent: :nullify
-      canceled_orders.update_all(canceler_id: nil, updated_at: Time.current)
-      created_orders.update_all(created_by_id: nil, updated_at: Time.current)
+      # Every actor column that names this user, derived from the `acted_by`
+      # declarations rather than listed here, so the 6.1 conversion of the
+      # remaining associations needs no edit in this file.
+      clear_every_actor
+
+      # The plain foreign keys that are still admin-user-only. They join the
+      # loop above once they convert in 6.1.
       created_gift_cards.update_all(created_by_id: nil, updated_at: Time.current)
       created_gift_card_batches.update_all(created_by_id: nil, updated_at: Time.current)
-      refunded_refunds.update_all(refunder_id: nil, updated_at: Time.current)
-      performed_reimbursements.update_all(performed_by_id: nil, updated_at: Time.current)
       created_store_credits.update_all(created_by_id: nil, updated_at: Time.current)
+      saved_reports.update_all(user_id: nil, updated_at: Time.current)
 
       # resources to destroy
-      reports.destroy_all
       exports.destroy_all
     end
 
-    # Routes Devise's auth notifications through Spree's own mailer so admin
-    # password reset and account confirmation emails carry the store design and
-    # locale instead of Devise's built-in templates. Other notification kinds
-    # (e.g. unlock instructions) fall through to Devise.
-    module DeviseNotifications
-      def send_devise_notification(notification, *args)
-        token = args.first
-        store = Spree::Current.store || Spree::Store.default
-
-        case notification
-        when :reset_password_instructions
-          Spree::AdminUserMailer.password_reset_email(self, token, store).deliver_later
-        when :confirmation_instructions
-          Spree::AdminUserMailer.confirmation_email(self, token, store).deliver_later
-        else
-          super
-        end
+    # Erases this user from every actor column any model declares with
+    # `acted_by`.
+    def clear_every_actor
+      Spree::ActedBy.models.each do |model|
+        model.acted_by_associations.each { |name| clear_actor(model, name) }
       end
     end
+
+    # Erases this user from one polymorphic actor column, clearing both halves
+    # together — a type left behind names a class no id points at.
+    #
+    # Matched on the id with either this class or no class at all, because a
+    # row written before the type column existed carries only the id until
+    # `spree:upgrade:backfill_actor_types` runs. Skipping those would leave a
+    # deleted person's id on the record through exactly the upgrade window the
+    # backfill exists for. The id alone cannot collide here: it is paired with
+    # a type that is ours or absent, and absent meant an admin user.
+    #
+    # @param model [Class]
+    # @param name [Symbol] the acted_by association
+    def clear_actor(model, name)
+      model.
+        where(:"#{name}_id" => id).
+        where(:"#{name}_type" => [self.class.polymorphic_name, nil]).
+        update_all(Spree::ActedBy.columns_for(name, nil).merge(updated_at: Time.current))
+    end
   end
 end

data/app/models/concerns/spree/calculated_adjustments.rb

@@ -14,26 +14,20 @@ module Spree
         spree_calculators.send model_name_without_spree_namespace
       end
 
+      # The public API shorthand (`'flat_rate'`), never the Ruby class name.
       def calculator_type
-        calculator.class.to_s if calculator
+        calculator.class.api_type if calculator
       end
 
-      # Accepts a fully-qualified class name (`'Spree::Calculator::FlatRate'`)
-      # or the public API shorthand (`'flat_rate'`). Shorthand is resolved
-      # against this parent's registered calculators so a CreateAdjustment
-      # can't be assigned a shipping-only calculator just by knowing its
-      # name.
+      # Takes the public API shorthand (`'flat_rate'`), resolved against this
+      # parent's registered calculators — so a CreateAdjustment can't be
+      # assigned a shipping-only calculator just by knowing its name, and
+      # nothing user-supplied ever reaches `constantize`.
       def calculator_type=(calculator_type)
         return if calculator_type.blank?
 
-        str = calculator_type.to_s
-        klass =
-          if str.include?('::')
-            str.safe_constantize
-          else
-            registry = self.class.respond_to?(:calculators) ? self.class.calculators : []
-            registry.find { |k| k.api_type == str }
-          end
+        registry = self.class.respond_to?(:calculators) ? self.class.calculators : []
+        klass = registry.find { |k| k.api_type == calculator_type.to_s }
         self.calculator = klass.new if klass && !calculator.instance_of?(klass)
       end
 

data/app/models/concerns/spree/calculator/currency_amounts.rb

@@ -0,0 +1,43 @@
+module Spree
+  class Calculator < Spree.base_class
+    # Per-currency amounts for amount-based delivery calculators, mirroring
+    # how product prices work: one explicit amount per currency, no FX. The
+    # `amounts` hash ({ "USD" => 5.0, "EUR" => 4.0 }) quotes the cart's
+    # currency directly, so one method serves every currency it has an
+    # amount for — no more method-per-currency duplication.
+    #
+    # The 5.x single `amount` + `currency` preferences keep working as the
+    # fallback for their own currency, so upgraded stores quote unchanged
+    # until they fill in the hash.
+    module CurrencyAmounts
+      extend ActiveSupport::Concern
+
+      included do
+        preference :amounts, :hash, default: {}
+      end
+
+      # The amount this calculator quotes for a currency: the per-currency
+      # hash first, then the legacy single amount when its currency matches.
+      #
+      # @param currency [String]
+      # @return [BigDecimal, nil] nil when the currency has no amount — the
+      #   method is not offered for that cart
+      def amount_for(currency)
+        explicit = preferred_amounts&.transform_keys { |key| key.to_s.upcase }&.dig(currency.to_s.upcase)
+        return BigDecimal(explicit.to_s) if explicit.present?
+
+        legacy_currency = respond_to?(:preferred_currency) ? preferred_currency : nil
+        return preferred_amount if legacy_currency.blank? || legacy_currency.casecmp(currency.to_s).zero?
+
+        nil
+      end
+
+      # Whether this calculator can quote the given currency at all — the
+      # Estimator's method filter, replacing the old exact-match on the
+      # single currency preference.
+      def supports_currency?(currency)
+        amount_for(currency).present?
+      end
+    end
+  end
+end

data/app/models/concerns/spree/capture_method.rb

@@ -0,0 +1,33 @@
+module Spree
+  # When a customer's card is charged, as opposed to only authorized.
+  #
+  # A store sets the default and a payment method may override it, mirroring
+  # +Spree::Channel::Gating+: the method preference is nullable, so an unset
+  # value inherits the store's choice rather than meaning "checkout".
+  module CaptureMethod
+    extend ActiveSupport::Concern
+
+    # - +checkout+     charge as soon as the order is placed
+    # - +on_dispatch+  authorize at checkout, charge when goods are dispatched
+    # - +manual+       authorize at checkout, leave charging to staff
+    CAPTURE_METHODS = %w[checkout on_dispatch manual].freeze
+
+    # The value a store falls back to when nothing has been chosen.
+    DEFAULT_CAPTURE_METHOD = 'checkout'.freeze
+
+    # @return [Boolean] true when the money is taken as the order is placed.
+    def capture_at_checkout?
+      resolved_capture_method == 'checkout'
+    end
+
+    # @return [Boolean] true when dispatching goods is what triggers the charge.
+    def capture_on_dispatch?
+      resolved_capture_method == 'on_dispatch'
+    end
+
+    # @return [Boolean] true when only staff may take the money.
+    def capture_manually?
+      resolved_capture_method == 'manual'
+    end
+  end
+end