spree_core 5.6.0 → 6.0.0.beta1

data/app/models/spree/return.rb

@@ -0,0 +1,150 @@
+module Spree
+  # A customer sends items back and gets their money back.
+  #
+  # One record owns the whole operation — permission, physical receipt and
+  # money back (docs/plans/6.0-returns-exchanges-claims.md), replacing the
+  # ReturnAuthorization → CustomerReturn → Reimbursement chain removed in 6.0.
+  #
+  # The model holds associations, validations and pure reads only. Every
+  # transition is a workflow — `Spree::Returns::Receive.call(...)`, never
+  # `return.receive!` — so receiving can take the quantities the warehouse
+  # actually counted, and refunding can call a payment gateway outside the
+  # transaction that writes the status.
+  class Return < Spree.base_class
+    has_prefix_id :ret
+
+    has_spree_number prefix: 'RET'
+    include Spree::NumberIdentifier
+    include Spree::SingleStoreResource
+    include Spree::HasStatus
+    include Spree::HasCustomFields
+    include Spree::Metadata
+
+    publishes_lifecycle_events
+
+    has_status :requested, :approved, :received, :refunded, :canceled,
+               default: :requested
+
+    belongs_to :store, class_name: 'Spree::Store'
+    belongs_to :order, class_name: 'Spree::Order', inverse_of: :returns
+    belongs_to :stock_location, class_name: 'Spree::StockLocation'
+    belongs_to :reason, class_name: 'Spree::ReturnReason', optional: true, inverse_of: :returns
+    # Staff only. Customer-initiated returns leave this nil — the requester
+    # is always order.customer, so no second association is needed.
+    belongs_to :created_by, class_name: Spree.admin_user_class.to_s, optional: true
+
+    has_many :return_line_items, class_name: 'Spree::ReturnLineItem',
+                                 dependent: :destroy, inverse_of: :return
+    has_many :refunds, class_name: 'Spree::Refund', as: :originator, dependent: :nullify
+    has_many :store_credits, class_name: 'Spree::StoreCredit', as: :originator, dependent: :nullify
+    # The return label and the inbound parcel's journey
+    # (docs/plans/6.0-shipping-labels-and-deliveries.md). A delivery reporting
+    # arrival never receives the return: arrival is not inspection.
+    has_many :shipping_labels, -> { order(:created_at, :id) }, class_name: 'Spree::ShippingLabel', as: :owner, dependent: :destroy
+    has_many :deliveries, -> { order(:created_at, :id) }, class_name: 'Spree::Delivery', as: :owner, dependent: :destroy
+
+    validates :return_line_items, presence: true, on: :create
+
+    accepts_nested_attributes_for :return_line_items, allow_destroy: true
+
+    delegate :currency, to: :order
+
+    self.whitelisted_ransackable_attributes = %w[number status created_at]
+    self.whitelisted_ransackable_associations = %w[order reason]
+
+    # The label that currently binds the inbound parcel — bought or uploaded,
+    # not refunded. The label workflows refuse a second active one.
+    #
+    # @return [Spree::ShippingLabel, nil]
+    def active_shipping_label
+      shipping_labels.active.last
+    end
+
+    # The provider that ships this return's label — the one that handled the
+    # outbound parcel the returned items travelled in, since that is the
+    # carrier account the merchant connected. Manual when nothing shipped
+    # through a provider.
+    #
+    # @return [Spree::FulfillmentProvider::Base]
+    def provider
+      return_line_items.first&.fulfillment_item&.fulfillment&.provider || Spree::FulfillmentProvider::Manual.new
+    end
+
+    # The address the inbound parcel leaves from: where the order shipped to.
+    #
+    # @return [Spree::Address, nil]
+    def ship_from_address
+      order.ship_address
+    end
+
+    # The returned goods as a package, for providers that need a weight and
+    # dimensions to rate a return label. Built at the return's stock
+    # location, which is where the parcel is going.
+    #
+    # @return [Spree::Stock::Package]
+    def to_package
+      package = Spree::Stock::Package.new(stock_location)
+      package.owner = order
+      units = returned_units
+      units.group_by(&:status).each { |status, items| package.add_multiple(items, status.to_sym) }
+      package
+    end
+
+    # The units as the parcel coming back holds them: a partial return sends
+    # back what the customer is returning, not everything that shipped. The
+    # copies are never saved — the shipment's own record of what left is not
+    # ours to rewrite, and it is what a second return is measured against.
+    #
+    # @return [Array<Spree::FulfillmentItem>]
+    def returned_units
+      return_line_items.includes(:fulfillment_item).filter_map do |return_line_item|
+        unit = return_line_item.fulfillment_item
+        next if unit.nil?
+
+        quantity = return_line_item.quantity.to_i
+        next unit if quantity <= 0 || quantity == unit.quantity.to_i
+
+        # `dup` rather than a new record: the packer reads variant, line item
+        # and status off the unit, and a copy carries all of it.
+        unit.dup.tap { |returned| returned.quantity = quantity }
+      end
+    end
+
+    # What the customer is owed for the items being returned.
+    def refund_total
+      return_line_items.sum(&:pre_tax_amount)
+    end
+
+    # What a refund from this return paid for, line by line. Counts what the
+    # warehouse received rather than what the customer announced, so it agrees
+    # with the amount {Spree::Returns::Refund} works out for itself.
+    #
+    # @return [Hash{Integer => BigDecimal}] line item id => amount
+    def refunded_line_amounts
+      return_line_items.each_with_object(Hash.new(0)) do |line, amounts|
+        next if line.quantity.to_i.zero? || line.received_quantity.to_i.zero?
+
+        amounts[line.line_item_id] += (line.pre_tax_amount / line.quantity) * line.received_quantity.to_i
+      end
+    end
+
+    # What has actually been refunded so far — a return can be refunded in
+    # more than one step (part to store credit, part to the card), and store
+    # credit is its own ledger rather than a Spree::Refund row.
+    def refunded_total
+      refunds.sum(:amount) + store_credits.sum(:amount)
+    end
+
+    def refundable_total
+      refund_total - refunded_total
+    end
+
+    def display_refund_total
+      Spree::Money.new(refund_total, currency: currency)
+    end
+
+    def display_refunded_total
+      Spree::Money.new(refunded_total, currency: currency)
+    end
+  end
+end

data/app/models/spree/return_authorization_reason.rb

@@ -1,9 +1,14 @@
-module Spree
-  class ReturnAuthorizationReason < Spree.base_class
-    has_prefix_id :rar
+# frozen_string_literal: true
 
-    include Spree::NamedType
+module Spree
+  # Deprecation alias for Spree::ReturnReason, renamed in 6.0 along with the
+  # removal of the ReturnAuthorization chain. Retained for one release so
+  # existing code and extensions keep working; removed in 6.1.
+  #
+  # A true constant alias — the class, table (spree_return_reasons), prefix
+  # (rar) and model_name are all Spree::ReturnReason, so is_a?, polymorphic
+  # type strings and class_name: references keep resolving correctly.
+  ReturnAuthorizationReason = ReturnReason
 
-    has_many :return_authorizations, dependent: :restrict_with_error
-  end
+  Spree::Deprecation.warn('Spree::ReturnAuthorizationReason is deprecated and will be removed in Spree 6.1. Use Spree::ReturnReason instead.')
 end

data/app/models/spree/return_line_item.rb

@@ -0,0 +1,42 @@
+module Spree
+  # One line on a {Spree::Return} — a quantity of a fulfilled item coming back.
+  #
+  # Named for {Spree::LineItem}, which it mirrors: `quantity` is what the
+  # customer said was coming, `received_quantity` what the warehouse counted.
+  class ReturnLineItem < Spree.base_class
+    has_prefix_id :rli
+
+    belongs_to :return, class_name: 'Spree::Return', inverse_of: :return_line_items
+    belongs_to :fulfillment_item, class_name: 'Spree::FulfillmentItem'
+    belongs_to :line_item, class_name: 'Spree::LineItem'
+    belongs_to :variant, -> { with_deleted }, class_name: 'Spree::Variant'
+
+    validates :quantity, numericality: { greater_than: 0 }
+    validates :received_quantity, numericality: { greater_than_or_equal_to: 0 }
+    validates :pre_tax_amount, numericality: { greater_than_or_equal_to: 0 }
+
+    before_validation :set_defaults_from_line_item, on: :create
+
+    delegate :order, :currency, to: :return
+
+    def display_pre_tax_amount
+      Spree::Money.new(pre_tax_amount, currency: currency)
+    end
+
+    private
+
+    # The refundable amount defaults to this item's share of what the
+    # customer actually paid for the line, after discounts — refunding the
+    # list price would give back more than was taken.
+    def set_defaults_from_line_item
+      self.variant ||= line_item&.variant
+      self.pre_tax_amount = default_pre_tax_amount if pre_tax_amount.blank? || pre_tax_amount.zero?
+    end
+
+    def default_pre_tax_amount
+      return 0 if line_item.nil? || line_item.quantity.to_i.zero?
+
+      (line_item.amount / line_item.quantity) * quantity.to_i
+    end
+  end
+end

data/app/models/spree/return_reason.rb

@@ -0,0 +1,26 @@
+module Spree
+  # Why a customer is sending items back — "wrong size", "changed mind",
+  # "not as described". Shared by returns and exchanges.
+  #
+  # Renamed from Spree::ReturnAuthorizationReason in 6.0 now that the
+  # ReturnAuthorization chain is gone; Spree::ReturnAuthorizationReason
+  # remains as a deprecated alias for one release.
+  class ReturnReason < Spree.base_class
+    has_prefix_id :rar
+
+    include Spree::NamedType
+
+    self.whitelisted_ransackable_attributes = %w[name active]
+
+    has_many :returns, class_name: 'Spree::Return', inverse_of: :reason, dependent: :restrict_with_error
+    has_many :exchanges, class_name: 'Spree::Exchange', inverse_of: :reason, dependent: :restrict_with_error
+
+    # Mirrors what `dependent: :restrict_with_error` enforces, so the dashboard
+    # can hide the delete control rather than offer one the model will refuse.
+    #
+    # @return [Boolean]
+    def can_be_deleted?
+      !returns.exists? && !exchanges.exists?
+    end
+  end
+end

data/app/models/spree/rich_text_sanitizer.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Spree
+  # Allowlist sanitizer for rich text HTML stored in plain text columns
+  # (e.g. +Spree::Product#description+).
+  #
+  # The allowlist is scoped to what the dashboard's editor actually emits —
+  # Tiptap StarterKit plus Link. Anything outside that set is markup no writer
+  # in Spree produces, so permitting it would only widen the attack surface
+  # (inline styles for CSS overlays, +class+ for collisions with storefront
+  # styles, +iframe+/+object+ for framed third-party content).
+  #
+  # Widening it is a deliberate act, not a default: an editor gaining a node
+  # type widens the allowlist in the same change. Merchants whose legacy
+  # descriptions embed richer markup — tables or video +iframe+s from the
+  # pre-6.0 TinyMCE admin — can re-permit it from an initializer, and should,
+  # because content is re-sanitized on its next save:
+  #
+  #   Spree::RichTextSanitizer.allowed_tags += %w[table thead tbody tr th td]
+  #   Spree::RichTextSanitizer.allowed_attributes += %w[colspan rowspan]
+  class RichTextSanitizer
+    # Tiptap StarterKit (paragraph, headings, hard break, horizontal rule,
+    # bold, italic, strike, underline, code, code block, blockquote, lists)
+    # plus Link and Image. Verified against each extension's +renderHTML+.
+    class_attribute :allowed_tags,
+                    default: %w[
+                      p br hr
+                      h1 h2 h3 h4 h5 h6
+                      strong em s u code pre
+                      blockquote ul ol li a img
+                    ].freeze
+
+    # +href+/+target+/+rel+/+title+ come from Link; +src+/+alt+/+width+/+height+
+    # from Image. +class+ is permitted only because a code block carries
+    # +language-*+ on its inner +code+ element; the class scrubber below is what
+    # keeps that from being a free-for-all.
+    #
+    # +src+ needs no protocol allowlist of its own: the permit scrubber drops an
+    # attribute whose value carries an unsafe scheme, so +data:+ and
+    # +javascript:+ URIs are stripped while https and relative URLs survive.
+    class_attribute :allowed_attributes,
+                    default: %w[href target rel title class src alt width height].freeze
+
+    # Classes surviving on +code+ elements. Tiptap writes +language-<name>+
+    # from its +languageClassPrefix+; nothing else in the editor emits a class,
+    # so every other value is stripped rather than trusted.
+    class_attribute :allowed_class_pattern, default: /\Alanguage-[a-z0-9+#-]+\z/i
+
+    # Elements allowed to carry a class at all. Only the code block needs one,
+    # and keeping the list tight stops +language-*+ from becoming a way to put a
+    # class on arbitrary markup.
+    class_attribute :classable_tags, default: %w[code].freeze
+
+    # Tags whose *contents* are dropped along with the tag. Stripping only the
+    # tag would leave the script body or stylesheet behind as visible text.
+    class_attribute :pruned_tags, default: %w[script style].freeze
+
+    # @param html [String, nil] rich text HTML
+    # @return [String, nil] HTML with disallowed tags and attributes removed, or the input unchanged when blank
+    def self.sanitize(html)
+      return html if html.blank?
+
+      # Both scrubbers run against a single parsed fragment. Going through
+      # SafeListSanitizer twice (once to prune, once to allowlist) would parse
+      # and re-serialize the whole document on every save.
+      fragment = Loofah.html5_fragment(html)
+      fragment.scrub!(prune_scrubber)
+      fragment.scrub!(permit_scrubber)
+      fragment.to_html
+    end
+
+    # Drops pruned elements subtree-and-all — allowlisting alone would strip the
+    # tag but leave the script body or stylesheet behind as visible text — and
+    # narrows +class+ to the code-block language hint in the same pass.
+    def self.prune_scrubber
+      tags = pruned_tags
+      classable = classable_tags
+      pattern = allowed_class_pattern
+
+      Loofah::Scrubber.new(direction: :top_down) do |node|
+        next node.remove if tags.include?(node.name)
+        next unless node.element? && node.key?('class')
+        next node.delete('class') unless classable.include?(node.name)
+
+        kept = node['class'].split.select { |name| pattern.match?(name) }
+        kept.empty? ? node.delete('class') : node['class'] = kept.join(' ')
+      end
+    end
+    private_class_method :prune_scrubber
+
+    def self.permit_scrubber
+      Rails::HTML::PermitScrubber.new.tap do |scrubber|
+        scrubber.tags = allowed_tags
+        scrubber.attributes = allowed_attributes
+      end
+    end
+    private_class_method :permit_scrubber
+  end
+end

data/app/models/spree/role.rb

@@ -2,28 +2,203 @@ module Spree
   class Role < Spree.base_class
     has_prefix_id :role
 
-    include Spree::UniqueName
+    # Deliberately NOT validates_store_uniqueness: a role's uniqueness is per owner, while a
+    # role is unique within the resource that owns it (see the name validation
+    # below). The normalization it applies is kept verbatim.
+    normalizes :name, with: ->(value) { value&.to_s&.squish&.presence }
 
     ADMIN_ROLE = 'admin'
 
+    # Grantable capabilities as flat catalog keys (`read_orders`,
+    # `write_products`, …) — see Spree::PermissionConfiguration. Stored as a
+    # JSON array like Spree::ApiKey#scopes; the `admin` role ignores this and
+    # always grants everything.
+    attribute :permissions, default: []
+
+    # Rows predating the column (or raw inserts) hold NULL — the array
+    # contract holds regardless.
+    def permissions
+      super || []
+    end
+
+    def permissions=(value)
+      super(Array(value).map(&:to_s).reject(&:blank?).uniq)
+    end
+
     #
     # Associations
     #
+    # What this role governs: a Spree::Store for back-office staff, a
+    # marketplace seller for a seller's own team. The resource is the role's
+    # owner and its audience at once — a role on a Store is a staff role by
+    # construction, so there is no parallel column to keep in step.
+    belongs_to :resource, polymorphic: true
+
     has_many :role_users, class_name: 'Spree::RoleUser', dependent: :destroy
-    has_many :users, through: :role_users, source: :user, source_type: Spree.user_class.to_s
+    has_many :users, through: :role_users, source: :user, source_type: Spree.customer_class.to_s
     has_many :admin_users, through: :role_users, source: :user, source_type: Spree.admin_user_class.to_s
     has_many :invitations, class_name: 'Spree::Invitation', dependent: :destroy
 
+    #
+    # Validations
+    #
+    validates :resource, presence: true
+    # Unique within the owning resource rather than globally: two stores may
+    # each define a "Manager", and a store may hold one beside a seller's.
+    validates :name, presence: true,
+                     uniqueness: { case_sensitive: false, allow_blank: true,
+                                   scope: [*spree_base_uniqueness_scope, :resource_id, :resource_type] }
+    validate :permissions_must_be_known, if: :permissions_changed?
+    validate :permissions_must_be_grantable_for_resource, if: -> { permissions_changed? || resource_type_changed? }
+    validate :resource_immutable, on: :update, if: -> { resource_id_changed? || resource_type_changed? }
+    validate :name_immutable, on: :update, if: :name_changed?
+    validate :permissions_immutable, on: :update, if: :permissions_changed?
+    validate :description_immutable, on: :update, if: :description_changed?
+
+    #
+    # Callbacks
+    #
+    # Prepended so the guard sees the role's assignments — `dependent: :destroy`
+    # association callbacks would otherwise empty `role_users` before it runs.
+    before_destroy :ensure_can_be_deleted, prepend: true
+
     #
     # Scopes
     #
     scope :admin, -> { where(name: ADMIN_ROLE) }
+    scope :for_resource, ->(resource) { where(resource: resource) }
 
     #
     # Class Methods
     #
-    def self.default_admin_role
-      find_or_create_by(name: ADMIN_ROLE)
+    # The resource's own super-role, created on first ask. Each owns one:
+    # "admin" means everything in *this* store, so it cannot be shared.
+    #
+    # Permissions come from the audience the resource grants to, so a role is
+    # born holding them whichever caller asks first — an invitation filling in
+    # its default role, or the resource seeding its own team. A store's stays
+    # empty by design: its super-role is short-circuited by
+    # `Ability#activate_full_access` and needs no keys, while a seller's is an
+    # ordinary role that would otherwise be refused by every endpoint.
+    #
+    # @param resource [Spree::Store, Object] defaults to the current store
+    # @return [Spree::Role]
+    def self.default_admin_role(resource = nil)
+      resource ||= Spree::Current.store || Spree::Store.current
+
+      for_resource(resource).find_or_create_by(name: ADMIN_ROLE) do |role|
+        role.mutable = false
+        role.permissions = default_admin_permissions_for(resource)
+      end
+    end
+
+    # @return [Array<String>] the keys a resource's own super-role is born with
+    def self.default_admin_permissions_for(resource)
+      audience = resource.try(:role_audience)
+      return [] if audience.blank?
+
+      Spree.permissions.grantable_keys(audience)
+    end
+
+    # The protected super-role: everything in this store. Guarded by the owning
+    # resource as well as the name — names are unique per resource, so a seller
+    # may legitimately call a role "admin" and it must never be mistaken for
+    # this one — and by the `mutable` flag, so a stale flag cannot expose it.
+    #
+    # @return [Boolean]
+    def admin?
+      staff? && (name == ADMIN_ROLE || name_was == ADMIN_ROLE)
+    end
+
+    # Whether this role governs a store's own back office, as opposed to
+    # another panel's.
+    #
+    # @return [Boolean]
+    def staff?
+      resource_type == Spree::Store.to_s
+    end
+
+    # The permission catalog's name for the panel this role belongs to —
+    # derived from the owning resource, never stored, so the two cannot drift.
+    # `Spree::Seller` reads as `:seller`.
+    #
+    # @return [Symbol, nil]
+    def audience
+      return if resource_type.blank?
+
+      resource_type.demodulize.underscore.to_sym
+    end
+
+    # Whether the dashboard may edit or delete this role. False for the admin
+    # role and for host-locked rows (`mutable: false` via seeds/console).
+    #
+    # @return [Boolean]
+    def mutable?
+      super && !admin?
+    end
+
+    # A role can be deleted only when it is mutable and nothing references it:
+    # staff assignments and pending invitations must be reassigned first.
+    # Accepted or expired invitations are history and cascade on destroy.
+    #
+    # @return [Boolean]
+    def can_be_deleted?
+      mutable? && !role_users.exists? && !invitations.pending.exists?
+    end
+
+    private
+
+    def permissions_must_be_known
+      unknown = permissions - Spree.permissions.catalog_keys
+      errors.add(:permissions, :role_permissions_unknown, message: Spree.t(:role_permissions_unknown, keys: unknown.join(', '))) if unknown.any?
+    end
+
+    # Every role is bounded by the catalog: only resources registered as
+    # grantable to its kind may appear on it, so settings/staff/api_keys can
+    # never reach a seller, and a seller's own keys can never reach a store
+    # role — even from a seed.
+    def permissions_must_be_grantable_for_resource
+      return if resource_type.blank?
+
+      ungrantable = permissions - Spree.permissions.grantable_keys(audience)
+      return if ungrantable.none?
+
+      errors.add(
+        :permissions, :role_permissions_not_grantable_for_audience, message: Spree.t(:role_permissions_not_grantable_for_audience, audience: audience, keys: ungrantable.join(', '))
+      )
+    end
+
+    # Re-pointing the resource would move every existing assignment to another
+    # panel — and, for a store, to another tenant.
+    def resource_immutable
+      errors.add(:resource, :role_resource_immutable, message: Spree.t(:role_resource_immutable))
+    end
+
+    def name_immutable
+      errors.add(:name, :role_immutable, message: Spree.t(:role_immutable)) unless mutable_was_and_not_admin?
+    end
+
+    def permissions_immutable
+      errors.add(:permissions, :role_immutable, message: Spree.t(:role_immutable)) unless mutable_was_and_not_admin?
+    end
+
+    def description_immutable
+      errors.add(:description, :role_immutable, message: Spree.t(:role_immutable)) unless mutable_was_and_not_admin?
+    end
+
+    # Guards compare against the persisted `mutable` so flipping it in the same
+    # save cannot smuggle a change past them. `admin?` reads the persisted name
+    # too, and is resource-aware — another resource may call a role "admin"
+    # without inheriting the store super-role's protection.
+    def mutable_was_and_not_admin?
+      mutable_was && !admin?
+    end
+
+    def ensure_can_be_deleted
+      return true if can_be_deleted?
+
+      errors.add(:base, :role_cannot_be_deleted, message: Spree.t(:role_cannot_be_deleted))
+      throw :abort
     end
   end
 end

data/app/models/spree/role_user.rb

@@ -1,41 +1,25 @@
 module Spree
+  # A user holding a role. Where the grant applies is the role's business —
+  # `role.resource` names the store or seller it governs — so an assignment
+  # carries nothing but the pairing.
   class RoleUser < Spree.base_class
-    include Spree::SingleStoreResource
-
     #
     # Associations
     #
     belongs_to :role, class_name: 'Spree::Role', foreign_key: :role_id
     belongs_to :user, polymorphic: true
-    belongs_to :resource, polymorphic: true
-    belongs_to :store, class_name: 'Spree::Store'
     belongs_to :invitation, class_name: 'Spree::Invitation', optional: true, inverse_of: :role_user
 
     #
     # Validations
     #
-    validates :role, presence: true
     validates :user, presence: true
-    validates :resource, presence: true
-    validates :store, presence: true
-    validates :role_id, uniqueness: { scope: [:user_id, :resource_id, :user_type, :resource_type] }
+    validates :role_id, uniqueness: { scope: [:user_id, :user_type] }
 
     #
     # Delegations
     #
     delegate :name, to: :user
-
-    #
-    # Callbacks
-    #
-    before_validation :set_default_resource
-
-    private
-
-    # Set the default resource to the default store if the resource is not set
-    # this will allow a graceful migration from the old roles system to the new one
-    def set_default_resource
-      self.resource ||= Spree::Store.current
-    end
+    delegate :resource, to: :role
   end
 end

data/app/models/spree/saved_report.rb

@@ -0,0 +1,56 @@
+module Spree
+  # A reporting query kept for reuse: the contract JSON (see
+  # Spree::Reporting::Query); its visualization is inferred from the query's
+  # shape. Owned by the store and visible to every staff member who may read
+  # reports; the author is recorded for attribution only — execution
+  # re-authorizes the viewer.
+  class SavedReport < Spree.base_class
+    has_prefix_id :sq
+
+    include Spree::SingleStoreResource
+
+    publishes_lifecycle_events
+
+    belongs_to :user, class_name: Spree.admin_user_class.to_s, optional: true
+
+    validates :name, presence: true, uniqueness: { scope: spree_base_uniqueness_scope + [:store_id], case_sensitive: false }
+    validates :query, presence: true
+    validate :query_must_compile
+    # A built-in report is a fixed reference point: it can be copied or
+    # deleted, never edited in place — the same rule the dashboard shows.
+    validate :seeded_reports_are_read_only, on: :update
+
+    scope :seeded, -> { where(seeded: true) }
+
+    self.whitelisted_ransackable_attributes = %w[name seeded created_at updated_at]
+
+    def event_serializer_class
+      'Spree::Api::V3::Admin::SavedReportSerializer'.safe_constantize
+    end
+
+    # The stored query, normalized against the registry.
+    #
+    # @return [Spree::Reporting::Query]
+    def reporting_query
+      Spree::Reporting::Query.new(store: store, params: query || {})
+    end
+
+    private
+
+    # Refuse to save a query the registry cannot compile — a report must never
+    # 422 the day it is opened.
+    def query_must_compile
+      return if store.blank? || query.blank?
+
+      reporting_query
+    rescue Spree::Reporting::UnknownMember, Spree::Reporting::InvalidQuery => e
+      errors.add(:query, :invalid_reporting_query, message: e.message)
+    end
+
+    def seeded_reports_are_read_only
+      return unless seeded_was && (changed & %w[name description query]).any?
+
+      errors.add(:base, :seeded_report_read_only)
+    end
+  end
+end

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

@@ -13,6 +13,17 @@ module Spree
         @store = store
       end
 
+      # @return [CustomFieldSchema]
+      def custom_field_schema
+        @custom_field_schema ||= CustomFieldSchema.new(store)
+      end
+
+      # Deprecated 6.0 name, removed in 6.1.
+      def metafield_schema
+        Spree::Deprecation.warn('#metafield_schema is deprecated and will be removed in Spree 6.1. Use #custom_field_schema instead.')
+        custom_field_schema
+      end
+
       # Search and paginate products. Does NOT compute filter facets — use #filters for that.
       #
       # @param scope [ActiveRecord::Relation] base scope (store-scoped, visibility-filtered, authorized)