spree_core 5.6.0 → 6.0.0.beta1

data/app/models/spree/import.rb

@@ -5,7 +5,16 @@ module Spree
     has_prefix_id :imp
 
     include Spree::NumberIdentifier
-    include Spree::Core::NumberGenerator.new(prefix: 'IM')
+    has_spree_number prefix: 'IM'
+
+    # Where the downloadable example CSVs are served from — see `sample_csv_url`.
+    #
+    # Pinned to the installed version's tag rather than `main`: whether a type
+    # *has* an example is answered by the local `db/sample_data`, so pointing
+    # elsewhere would let a released install link to a newer, incompatible
+    # schema (or a file that has since been removed).
+    SAMPLE_DATA_BASE_URL_TEMPLATE =
+      'https://raw.githubusercontent.com/spree/spree/refs/tags/v%<version>s/spree/core/db/sample_data'.freeze
 
     publishes_lifecycle_events
 
@@ -13,10 +22,19 @@ module Spree
     # This ensures Spree::Imports::Products publishes 'import.create' not 'products.create'
     self.event_prefix = 'import'
 
+    include Spree::SingleStoreResource
+
     #
     # Associations
     #
-    belongs_to :owner, polymorphic: true # Store, Vendor, etc.
+    # Which marketplace this import belongs to, and — when a seller ran it —
+    # whose it is. A null seller means the operator's own, which is what lets
+    # one store-scoped list carry both (see `Spree::Export`, the same pair).
+    #
+    # `with_deleted` because a seller is soft-deleted and their import history
+    # has to stay readable afterwards; an operator debugging a departed
+    # seller's catalog is exactly when it matters.
+    belongs_to :seller, -> { with_deleted }, class_name: 'Spree::Seller', optional: true
     belongs_to :user, class_name: Spree.admin_user_class.to_s, optional: true
     has_many :mappings, class_name: 'Spree::ImportMapping', dependent: :destroy, inverse_of: :import
     alias import_mappings mappings
@@ -26,20 +44,28 @@ module Spree
     #
     # Validations
     #
-    validates :owner, :user, :type, presence: true
+    validates :user, :type, presence: true
     validates :attachment, presence: true, unless: -> { Rails.env.test? }
     validate :ensure_whitelisted_type
     validate :ensure_attachment_content_type
+    validate :ensure_seller_belongs_to_store
 
     #
     # Ransack configuration
     #
-    self.whitelisted_ransackable_attributes = %w[number type status]
+    self.whitelisted_ransackable_attributes = %w[number type status seller_id]
+    # Lets an operator filter their list by who ran the job — the seller's
+    # name, not an id they would have to look up first.
+    self.whitelisted_ransackable_associations = %w[seller]
 
     #
     # Scopes
     #
-    scope :for_store, ->(store) { where(owner: store) }
+    # `for_store` comes from Spree::SingleStoreResource and now includes a
+    # store's sellers' imports, which is what puts them in the operator's list.
+    scope :for_seller, ->(seller) { where(seller_id: seller) }
+    # The operator's own, as opposed to those their sellers ran.
+    scope :first_party, -> { where(seller_id: nil) }
 
     #
     # Attachments
@@ -47,52 +73,71 @@ module Spree
     has_one_attached :attachment, service: Spree.private_storage_service_name
 
     #
-    # State machine
+    # Status
     #
-    state_machine initial: :pending, attribute: :status do
-      event :start_mapping do
-        transition to: :mapping
-      end
-      before_transition to: :mapping, do: :create_mappings
-
-      event :complete_mapping do
-        transition from: :mapping, to: :completed_mapping
-      end
-      after_transition to: :completed_mapping, do: :create_rows_async
-
-      event :start_processing do
-        transition from: :completed_mapping, to: :processing
-      end
-
-      event :complete do
-        transition from: :processing, to: :completed
-      end
-      after_transition to: :completed, do: :touch_store
-      after_transition to: :completed, do: :publish_import_completed_event
-      # NOTE: send_import_completed_email and update_loader_in_import_view
-      # are now handled by Spree::Admin::ImportSubscriber listening to 'import.completed' event
-
-      event :fail do
-        transition to: :failed
-      end
-
-      # Re-processes rows that failed: the dispatcher targets pending_and_failed
-      # rows, so retry is just a transition + re-dispatch.
-      event :retry_failed_rows do
-        transition from: :completed, to: :processing, if: ->(import) { import.rows.failed.exists? }
-      end
-      after_transition on: :retry_failed_rows, do: :process_rows_async
-    end
+    # No state machine — the pipeline's steps are the Spree::Imports workflows
+    # (docs/plans/6.0-service-workflows.md), which is also what let the row
+    # dispatch stop tiptoeing around a transition's transaction.
+    include Spree::HasStatus
+    has_status :pending, :mapping, :completed_mapping, :processing, :completed, :failed,
+               default: :pending
 
     #
     # Preferences
     #
     preference :delimiter, :string, default: ','
+    # Run the pipeline in-process instead of enqueuing it. For rake tasks, seeds
+    # and the console, where the caller needs the data to exist when the call
+    # returns and there may be no worker attached. Never set it from a request:
+    # a large CSV blocks for minutes.
+    #
+    # A preference, not a virtual attribute, so it survives the `Import.find`
+    # each processing job does — otherwise every job would have to take (and
+    # forward) an `inline:` argument.
+    preference :inline, :boolean, default: false
+    # Suppress the events the *rows* publish — a `product.created` per imported
+    # product, plus `import_row.*`. The import's own `import.*` events still
+    # fire: a handful per import is useful, thousands from a seeded catalog are
+    # not.
+    #
+    # For seeding demo or sample data, where subscribers would otherwise deliver
+    # webhooks and analytics for a catalog nobody actually created. A preference
+    # rather than a virtual attribute because the processing jobs each reload
+    # the record, so it has to outlive the enqueue. Independent of `inline`: a
+    # background import can still be silent, and an inline one observed.
+    preference :skip_events, :boolean, default: false
     # Absolute URL of the dashboard's imports view, captured at create and
     # validated against the store's allowed origins — the import-done email
     # links back to it. Blank for legacy-admin or app-created imports.
     preference :results_url, :string, default: nil
 
+    # Publicly downloadable example CSV for this import's type, or nil when the
+    # type has no sample file. Resolved from the `type` column rather than the
+    # instance's class, so it works on a record built as the base
+    # `Spree::Import` with `type` assigned (which is how the admin's new-import
+    # form builds it).
+    #
+    # @return [String, nil]
+    def sample_csv_url
+      self.class.available_types.find { |klass| klass.to_s == type.to_s }&.sample_csv_url
+    end
+
+    # Header-only CSV for this import's schema — the blank counterpart to
+    # `sample_csv_url`. One line, so callers can inline it (e.g. as a `data:`
+    # URI) instead of round-tripping to the server for it.
+    #
+    # @return [String]
+    def template_csv
+      ::CSV.generate_line(schema_fields.map { |field| field[:name] })
+    end
+
+    # Suggested filename for `template_csv`, e.g. "products_import_template.csv".
+    #
+    # @return [String]
+    def template_csv_filename
+      "#{self.class.api_type_for(type)}_import_template.csv"
+    end
+
     # Returns true if the import has more rows than the large import threshold.
     # Large imports skip per-row UI broadcasts and use bulk processing.
     # @return [Boolean]
@@ -108,6 +153,44 @@ module Spree
       nil
     end
 
+    # @deprecated Call the Spree::Imports workflows — removed in 6.1.
+    def start_mapping!
+      Spree::Deprecation.warn('Spree::Import#start_mapping! is deprecated and will be removed in Spree 6.1. Call Spree.import_start_mapping_workflow instead.')
+      run_pipeline_workflow(Spree.import_start_mapping_workflow)
+    end
+
+    # @deprecated Call Spree.import_complete_mapping_workflow — removed in 6.1.
+    def complete_mapping!
+      Spree::Deprecation.warn('Spree::Import#complete_mapping! is deprecated and will be removed in Spree 6.1. Call Spree.import_complete_mapping_workflow instead.')
+      run_pipeline_workflow(Spree.import_complete_mapping_workflow)
+    end
+
+    # @deprecated Call Spree.import_start_processing_workflow — removed in 6.1.
+    def start_processing!
+      Spree::Deprecation.warn('Spree::Import#start_processing! is deprecated and will be removed in Spree 6.1. Call Spree.import_start_processing_workflow instead.')
+      run_pipeline_workflow(Spree.import_start_processing_workflow)
+    end
+
+    # @deprecated Call Spree.import_complete_workflow — removed in 6.1.
+    def complete!
+      Spree::Deprecation.warn('Spree::Import#complete! is deprecated and will be removed in Spree 6.1. Call Spree.import_complete_workflow instead.')
+      run_pipeline_workflow(Spree.import_complete_workflow)
+    end
+
+    # @deprecated Set the status — removed in 6.1. Failure was never a step of
+    #   its own; the controller records the parse error directly.
+    def fail!
+      Spree::Deprecation.warn('Spree::Import#fail! is deprecated and will be removed in Spree 6.1. Write the status instead.')
+      update!(status: 'failed')
+    end
+
+    # @deprecated Call Spree.import_retry_failed_rows_workflow — removed in 6.1.
+    #   Returns false when there is nothing to retry, as the guarded event did.
+    def retry_failed_rows
+      Spree::Deprecation.warn('Spree::Import#retry_failed_rows is deprecated and will be removed in Spree 6.1. Call Spree.import_retry_failed_rows_workflow instead.')
+      Spree.import_retry_failed_rows_workflow.call(import: self).success?
+    end
+
     # Returns true if the import is in mapping state
     # @return [Boolean]
     def mapping?
@@ -127,7 +210,7 @@ module Spree
     end
 
     # Imports are deletable only while no processing jobs can be in flight —
-    # CreateRowsJob/ProcessGroupJob re-load the record mid-run.
+    # ProcessJob/ProcessGroupJob re-load the record mid-run.
     # @return [Boolean]
     def can_be_deleted?
       %w[pending mapping completed failed].include?(status)
@@ -183,7 +266,7 @@ module Spree
     # @return [Class]
     def model_class
       if type == 'Spree::Imports::Customers'
-        Spree.user_class
+        Spree.customer_class
       else
         "Spree::#{type.demodulize.singularize}".safe_constantize
       end
@@ -202,20 +285,20 @@ module Spree
     end
 
     # Returns the fields for the import schema
-    # If model supports metafields, it will include the metafield definitions for this model
+    # If model supports custom_fields, it will include the custom_field definitions for this model
     # @return [Array<Hash>]
     def schema_fields
       base_fields = import_schema.fields
 
-      # Dynamically add metafield definitions if the model supports metafields
-      if model_class_supports_metafields?
-        metafield_fields = metafield_definitions_for_model.map do |definition|
+      # Dynamically add custom_field definitions if the model supports custom_fields
+      if model_class_supports_custom_fields?
+        custom_field_fields = custom_field_definitions_for_model.map do |definition|
           {
             name: definition.csv_header_name,
-            label: definition.name
+            label: definition.label
           }
         end
-        base_fields + metafield_fields
+        base_fields + custom_field_fields
       else
         base_fields
       end
@@ -251,14 +334,6 @@ module Spree
       "#{Spree.t(type.demodulize.pluralize.downcase)} #{number}"
     end
 
-    def touch_store
-      store.touch
-    end
-
-    def publish_import_completed_event
-      publish_event('import.completed')
-    end
-
     # Returns the headers of the csv file
     # @return [Array<String>]
     def csv_headers
@@ -276,47 +351,46 @@ module Spree
       @attachment_file_content ||= attachment.attached? ? attachment.blob.download&.force_encoding('UTF-8') : nil
     end
 
-    # Creates mappings from the schema fields
-    # TODO: get mappings from the previous import if it exists, so user won't have to map the same columns again
-    def create_mappings
-      schema_fields.each do |schema_field|
-        mapping = mappings.find_or_create_by!(schema_field: schema_field[:name])
-        mapping.try_to_auto_assign_file_column(csv_headers)
-        mapping.save!
-      end
-    end
-
-    # Creates rows asynchronously
-    # @return [void]
-    def create_rows_async
-      Spree::Imports::CreateRowsJob.set(wait: 2.seconds).perform_later(id)
-    end
-
-    # Processes rows asynchronously
-    # @return [void]
-    def process_rows_async
-      Spree::Imports::ProcessRowsJob.perform_later(id)
-    end
-
-    # Returns the store for the import
-    # @return [Spree::Store]
-    def store
-      if owner.is_a?(Spree::Store)
-        owner
+    # Who ran this import — the seller when one did, otherwise the store.
+    #
+    # @deprecated Read `seller` and `store` — removed in 6.1. Kept because the
+    #   polymorphic `owner` shipped in 5.6 and the v3 serializer still emits
+    #   `owner_type`/`owner_id` from it.
+    # @return [Spree::Seller, Spree::Store]
+    def owner
+      seller || store
+    end
+
+    # @deprecated Assign `seller:` or `store:` — removed in 6.1.
+    def owner=(record)
+      Spree::Deprecation.warn('Spree::Import#owner= is deprecated and will be removed in Spree 6.1. Assign seller: or store: instead.')
+
+      case record
+      when Spree::Seller
+        self.seller = record
+        self.store = record.store
       else
-        owner.respond_to?(:store) ? owner.store : Spree::Store.default
+        self.seller = nil
+        self.store = record
       end
     end
 
-    # Returns the current ability for the import
+    # The ability the row processors scope-fetch through.
+    #
+    # Built against whoever ran the import, because that is where the importing
+    # user holds their roles: a marketplace seller's staff hold theirs on the
+    # `Spree::Seller`, never on the store, so an ability resolved against the
+    # store compiles no rules at all and every scope-fetch through it comes
+    # back empty.
+    #
     # @return [Spree::Ability]
     def current_ability
-      @current_ability ||= Spree.ability_class.new(user, { store: store })
+      @current_ability ||= Spree.ability_class.new(user, { store: store, resource: seller || store })
     end
 
     # Per-instance cache shared by row processors within a single processing job.
     # Group jobs funnel every row through the same Import instance, so lookups of
-    # shared records (tax/shipping categories, option types, metafield definitions)
+    # shared records (tax/shipping categories, option types, custom_field definitions)
     # resolve once per job instead of once per row.
     # @return [Hash]
     def row_lookup_cache
@@ -360,9 +434,39 @@ module Spree
         to_s.demodulize.underscore.to_sym
       end
 
+      # Publicly downloadable example CSV for this import type — the same file
+      # `rake spree:load_sample_data` feeds through this very pipeline, so it is
+      # a working example rather than a hand-maintained sample that can drift
+      # from the schema.
+      #
+      # Whether a type *has* an example is answered by `db/sample_data` itself,
+      # so adding or removing a CSV there needs no change here; a type with no
+      # sample file returns nil and the UI omits the link. The URL is pinned to
+      # the installed version's tag so the file served always matches the schema
+      # that check was made against.
+      #
+      # @return [String, nil]
+      def sample_csv_url
+        return nil if self == Spree::Import
+        return nil unless Spree::Core::Engine.root.join('db', 'sample_data', sample_csv_filename).exist?
+
+        [sample_data_base_url, sample_csv_filename].join('/')
+      end
+
+      # @return [String]
+      def sample_data_base_url
+        format(SAMPLE_DATA_BASE_URL_TEMPLATE, version: Spree.version)
+      end
+
+      # eg. Spree::Imports::ProductTranslations => "product_translations.csv"
+      # @return [String]
+      def sample_csv_filename
+        "#{api_type}.csv"
+      end
+
       # eg. Spree::Imports::Orders => Spree::Order
       def model_class
-        return Spree.user_class if to_s == 'Spree::Imports::Customers'
+        return Spree.customer_class if to_s == 'Spree::Imports::Customers'
 
         klass = "Spree::#{to_s.demodulize.singularize}".safe_constantize
 
@@ -374,6 +478,30 @@ module Spree
 
     private
 
+    # Mirrors the machine's bang events: an illegal move raised.
+    def run_pipeline_workflow(workflow)
+      result = workflow.call(import: self)
+
+      if result.failure?
+        # ResultError#to_s unwraps an ActiveModel::Errors into its full
+        # messages; its `value` would inspect the object into the message.
+        errors.add(:base, result.error.to_s)
+        raise ActiveRecord::RecordInvalid, self
+      end
+
+      true
+    end
+
+    # A seller can only run imports for the marketplace they belong to. Without
+    # this a payload naming another store's seller would file the import under
+    # a store that seller has no standing in.
+    def ensure_seller_belongs_to_store
+      return if seller.blank? || store.blank?
+      return if seller.store_id == store_id
+
+      errors.add(:seller, :invalid)
+    end
+
     def ensure_whitelisted_type
       return if type.blank?
 
@@ -387,16 +515,18 @@ module Spree
       errors.add(:attachment, :content_type) unless attachment.content_type.in?(%w[text/csv])
     end
 
-    def model_class_supports_metafields?
+    def model_class_supports_custom_fields?
       return false unless model_class.present?
 
-      model_class.included_modules.include?(Spree::Metafields)
+      model_class.included_modules.include?(Spree::HasCustomFields)
     end
 
-    def metafield_definitions_for_model
+    def custom_field_definitions_for_model
       return [] unless model_class.present?
 
-      Spree::MetafieldDefinition.for_resource_type(model_class.name)
+      # `store` is assigned at before_validation, so the unsaved import the
+      # template CSV is built on has none yet.
+      (store || Spree::Current.store).custom_field_definitions.for_resource_type(model_class.name)
     end
   end
 end

data/app/models/spree/import_mapping.rb

@@ -10,7 +10,7 @@ module Spree
     #
     # Validations
     #
-    validates :import, :schema_field, presence: true
+    validates :schema_field, presence: true
     validates :schema_field, uniqueness: { scope: [:import_id] }
     validates :file_column, uniqueness: { scope: [:import_id] }, allow_blank: true
 

data/app/models/spree/import_row.rb

@@ -15,7 +15,7 @@ module Spree
     #
     # Validations
     #
-    validates :import, :data, presence: true
+    validates :data, presence: true
     validates :row_number, uniqueness: { scope: :import_id }, numericality: { only_integer: true, greater_than: 0 }, presence: true
 
     #
@@ -24,27 +24,13 @@ module Spree
     self.whitelisted_ransackable_attributes = %w[status row_number]
 
     #
-    # State machine
+    # Status
     #
-    state_machine initial: :pending, attribute: :status do
-      event :start_processing do
-        transition to: :processing
-      end
-
-      event :fail do
-        transition to: :failed
-      end
-      after_transition to: :failed, do: :publish_import_row_failed_event
-      # NOTE: add_row_to_import_view and update_footer_in_import_view
-      # are now handled by Spree::Admin::ImportRowSubscriber
-
-      event :complete do
-        transition to: :completed
-      end
-      after_transition to: :completed, do: :publish_import_row_completed_event
-      # NOTE: add_row_to_import_view and update_footer_in_import_view
-      # are now handled by Spree::Admin::ImportRowSubscriber
-    end
+    # No state machine — a row's whole lifecycle already lives in +process!+,
+    # which is the only thing that moves it. The events publish from the write
+    # rather than a transition callback.
+    include Spree::HasStatus
+    has_status :pending, :processing, :completed, :failed, default: :pending
 
     # How long a row may sit in `processing` before we consider its owning worker dead
     # (OOM, SIGKILL, deploy without graceful drain — none of these trigger a Sidekiq
@@ -94,15 +80,40 @@ module Spree
       data_json[mapping.file_column]
     end
 
+    # @deprecated Write the status — removed in 6.1. A row's lifecycle belongs
+    #   to +process!+, which is the only thing that should move it.
+    def start_processing!
+      Spree::Deprecation.warn('Spree::ImportRow#start_processing! is deprecated and will be removed in Spree 6.1. Use #process! instead.')
+      update!(status: 'processing')
+    end
+
+    # @deprecated Write the status — removed in 6.1.
+    def complete!
+      Spree::Deprecation.warn('Spree::ImportRow#complete! is deprecated and will be removed in Spree 6.1. Use #process! instead.')
+      update!(status: 'completed')
+      publish_event('import_row.completed')
+      true
+    end
+
+    # @deprecated Write the status — removed in 6.1.
+    def fail!
+      Spree::Deprecation.warn('Spree::ImportRow#fail! is deprecated and will be removed in Spree 6.1. Use #process! instead.')
+      update!(status: 'failed')
+      publish_event('import_row.failed')
+      true
+    end
+
     def process!(mappings: nil, schema_fields: nil)
-      start_processing!
+      update!(status: 'processing')
       self.item = import.row_processor_class.new(self, mappings: mappings, schema_fields: schema_fields).process!
       self.validation_errors = nil # clear a stale error when a retried row succeeds
-      complete!
+      update!(status: 'completed')
+      publish_event('import_row.completed')
     rescue StandardError => e
       Rails.error.report(e, handled: true, context: { import_row_id: id }, source: 'spree.core')
       self.validation_errors = e.message
-      fail!
+      update!(status: 'failed')
+      publish_event('import_row.failed')
     end
 
     # Bulk processing mode for large imports.
@@ -117,12 +128,5 @@ module Spree
       update_columns(status: 'failed', validation_errors: e.message, updated_at: Time.current)
     end
 
-    def publish_import_row_completed_event
-      publish_event('import_row.completed')
-    end
-
-    def publish_import_row_failed_event
-      publish_event('import_row.failed')
-    end
   end
 end

data/app/models/spree/import_schemas/price_list_prices.rb

@@ -0,0 +1,13 @@
+module Spree
+  module ImportSchemas
+    class PriceListPrices < Spree::ImportSchema
+      FIELDS = [
+        { name: 'sku', label: 'SKU', required: true },
+        { name: 'currency', label: 'Currency' },
+        { name: 'min_quantity', label: 'Minimum quantity' },
+        { name: 'price', label: 'Price', required: true },
+        { name: 'compare_at_price', label: 'Compare at Price' }
+      ].freeze
+    end
+  end
+end

data/app/models/spree/import_schemas/products.rb

@@ -26,7 +26,14 @@ module Spree
         { name: 'inventory_count', label: 'Inventory Count' },
         { name: 'inventory_backorderable', label: 'Inventory Backorderable' },
         { name: 'tax_category', label: 'Tax Category' },
-        { name: 'shipping_category', label: 'Shipping Category' },
+        { name: 'product_type', label: 'Product Type' },
+        { name: 'hs_code', label: 'HS Code' },
+        { name: 'country_of_origin', label: 'Country of Origin' },
+        { name: 'customs_description', label: 'Customs Description' },
+        { name: 'carton', label: 'Carton' },
+        { name: 'units_per_carton', label: 'Units per Carton' },
+        { name: 'carton_weight', label: 'Carton Weight' },
+        { name: 'cartons_per_pallet', label: 'Cartons per Pallet' },
         { name: 'image1_src', label: 'Image 1 URL' },
         { name: 'image2_src', label: 'Image 2 URL' },
         { name: 'image3_src', label: 'Image 3 URL' },

data/app/models/spree/import_schemas/purchase_orders.rb

@@ -0,0 +1,19 @@
+module Spree
+  module ImportSchemas
+    # One row per line; rows sharing a reference become one draft order.
+    class PurchaseOrders < Spree::ImportSchema
+      FIELDS = [
+        { name: 'reference', label: 'Reference', required: true },
+        { name: 'supplier', label: 'Supplier', required: true },
+        { name: 'destination', label: 'Destination', required: true },
+        { name: 'sku', label: 'SKU', required: true },
+        { name: 'quantity', label: 'Quantity', required: true },
+        { name: 'unit_cost', label: 'Unit cost', required: true },
+        { name: 'currency', label: 'Currency' },
+        { name: 'expected_at', label: 'Expected on' },
+        { name: 'cancel_by', label: 'Cancel by' },
+        { name: 'notes', label: 'Notes' }
+      ].freeze
+    end
+  end
+end