spree_core 5.6.1 → 6.0.0.beta2

data/app/workflows/spree/products/create.rb

@@ -0,0 +1,82 @@
+module Spree
+  module Products
+    # Creates a product. The single gate for product creation — the Admin
+    # API, the CSV importer and seeds all run through it, so a :validate
+    # handler sees every product a store gains rather than only the ones
+    # typed into the dashboard.
+    #
+    # Nested data — variants and media — is applied here rather than by the
+    # model, because it cannot be written until the product has an id and
+    # because it is a reconciliation, not an assignment: the payload is the
+    # writer's whole intent and variants missing from it are removed.
+    #
+    # :validate runs before the insert, and therefore before any variant or
+    # image exists, so a rejection leaves nothing to clean up.
+    class Create < Spree::Workflow
+      include Spree::Products::NestedAttributes
+
+      hooks :validate, :after_create
+
+      # The unsaved record a :validate handler reads (with its `changes`).
+      attr_reader :product
+
+      # @param store [Spree::Store]
+      # @param attributes [Hash] product attributes
+      # @param record [Spree::Product, nil] an already-built unsaved product.
+      #   The CSV importer assigns its own attributes across several steps and
+      #   hands the record over rather than a hash.
+      # @return [Spree::ServiceModule::Result] value is the product
+      def perform(store:, attributes: {}, record: nil)
+        super
+
+        step :build_product
+
+        # Before the insert: a rejection costs no rollback, and a handler
+        # reading `product` sees exactly what would have been saved.
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :save_product
+          step :apply_nested_attributes
+          run_hooks :after_create
+        end
+
+        success(product)
+      end
+
+      private
+
+      def build_product
+        @product = record || store.products.new
+        # A supplied record must belong to the store the caller named — a
+        # product resolved outside that scope would otherwise be persisted
+        # against the wrong tenant, and every :validate handler reading
+        # `store` would be told the wrong thing.
+        @product.store = store
+        return if attributes.blank?
+
+        # Indifferent access because this is a public entry point: a host app
+        # or importer passing a plain string-keyed hash must not have its
+        # nested payloads fall through to the ActiveRecord collection setters.
+        attrs = attributes.to_h.with_indifferent_access
+
+        # Held back from the record: these are reconciled after the insert,
+        # against a product that has an id.
+        @variants_params = attrs[:variants]
+        @media_params = attrs[:media]
+        @digital_assets_params = attrs[:digital_assets]
+        @product.assign_attributes(attrs.except(:variants, :media, :digital_assets))
+      end
+
+      def save_product
+        failure(product) unless product.save
+      end
+
+      def apply_nested_attributes
+        apply_variants(product, @variants_params)
+        apply_media(product, @media_params)
+        apply_digital_assets(product, @digital_assets_params)
+      end
+    end
+  end
+end

data/app/workflows/spree/products/destroy.rb

@@ -0,0 +1,35 @@
+module Spree
+  module Products
+    # Soft-deletes a product. A workflow rather than a bare `destroy` so
+    # cleanup that belongs to the host — unpublishing from a channel, telling
+    # an ERP, archiving assets — has a place to attach, and so a store can
+    # refuse the deletion outright (an active supplier contract, a product
+    # still on a live campaign).
+    class Destroy < Spree::Workflow
+      hooks :validate, :after_destroy
+
+      # `product` — the record about to be soft-deleted.
+
+      # @param product [Spree::Product]
+      # @return [Spree::ServiceModule::Result] value is the destroyed product
+      def perform(product:)
+        super
+
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :destroy_product
+          run_hooks :after_destroy
+        end
+
+        success(product)
+      end
+
+      private
+
+      def destroy_product
+        failure(product) unless product.destroy
+      end
+    end
+  end
+end

data/app/workflows/spree/products/draft.rb

@@ -0,0 +1,49 @@
+module Spree
+  module Products
+    # Returns a product to draft, hiding it from the storefront while it is
+    # worked on. Replaces the `draft` state machine event.
+    class Draft < Spree::Workflow
+      hooks :validate, :after_draft
+
+      # @param product [Spree::Product]
+      # @return [Spree::ServiceModule::Result] value is the product
+      def perform(product:)
+        super
+
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :mark_draft
+          step :withdraw_submission
+          run_hooks :after_draft
+        end
+
+        # Its siblings (Activate, Archive, Propose, Approve, Reject) all
+        # announce themselves, and this one now carries a marketplace meaning
+        # too: taking a listing back withdraws an open submission, which a
+        # seller's integration has the same reason to hear about.
+        product.publish_event('product.drafted')
+
+        success(product)
+      end
+
+      private
+
+      def mark_draft
+        failure(product) unless product.update(status: 'draft')
+      end
+
+      # Taking a listing back before the marketplace ruled on it settles the
+      # open row, so `pending` never means "abandoned".
+      #
+      # Only an open row: a rejected product has already been decided, and
+      # inventing a `withdrawn` row for it would bury that decision under an
+      # entry nobody made.
+      def withdraw_submission
+        return unless product.submissions.latest_first.first&.pending?
+
+        Spree::ProductSubmissions::Close.call(product: product, status: 'withdrawn')
+      end
+    end
+  end
+end

data/app/workflows/spree/products/nested_attributes.rb

@@ -0,0 +1,242 @@
+module Spree
+  module Products
+    # Applies the nested data a product write can carry: its variants and its
+    # media. Shared by Spree::Products::Create and ::Update so both write paths
+    # — and any host importing from an external system — reconcile them the
+    # same way.
+    #
+    # Both are full replacements. The payload is the writer's whole intent, so
+    # a variant absent from it is removed, and this is the operator's write
+    # path: it sees and writes every seller's variants on a shared listing, so
+    # nothing here narrows by seller. A seller's own path scope-fetches through
+    # `current_seller` at the controller
+    # (docs/plans/6.0-multi-vendor-marketplace.md, Decision 10) and never
+    # reaches here with a payload naming another seller's rows.
+    module NestedAttributes
+      extend ActiveSupport::Concern
+
+      private
+
+      # @param product [Spree::Product]
+      # @param variants_params [Array<Hash>, nil] nil leaves variants alone
+      # @return [void]
+      def apply_variants(product, variants_params)
+        return if variants_params.blank?
+
+        variant_ids_in_payload = []
+        mutated = false
+
+        variants_params.each do |raw|
+          variant_data = raw.to_h.with_indifferent_access
+          variant_id = variant_data.delete(:id)
+
+          variant = write_variant(product, variant_data, variant_id, variant_ids_in_payload)
+
+          variant_ids_in_payload << variant.id
+          mutated = true
+        end
+
+        if variant_ids_in_payload.any?
+          removed = product.variants.where.not(id: variant_ids_in_payload).destroy_all
+          mutated ||= removed.any?
+        end
+
+        sync_variant_state(product) if mutated
+      end
+
+      # Delegates to the variant workflows rather than assigning and saving
+      # here, so a variant written as part of a product payload passes the
+      # same gate — and the same :validate handlers — as one written through
+      # the variants endpoint.
+      def write_variant(product, variant_data, variant_id, consumed_ids)
+        existing = resolve_variant(product, variant_data, variant_id, consumed_ids)
+
+        result =
+          if existing
+            Spree.variant_update_workflow.call(variant: existing, attributes: variant_data)
+          else
+            Spree.variant_create_workflow.call(product: product, attributes: variant_data)
+          end
+
+        # A rejection inside the nested write is the product write failing;
+        # raising rolls the whole payload back rather than leaving a product
+        # with half its variants.
+        raise ActiveRecord::RecordInvalid, result.value if result.failure?
+
+        result.value
+      end
+
+      # The variant this entry names, or nil when it describes a new one.
+      def resolve_variant(product, variant_data, variant_id, consumed_ids)
+        return product.variants.find_by_param!(variant_id) if variant_id.present?
+
+        # An id-less, option-less entry targets the product's existing
+        # option-less default variant — the simple-product case. Updating it in
+        # place keeps its id, the order lines referencing it, and any prices or
+        # stock the payload does not mention.
+        # nil means "a new variant", which Spree::Variants::Create builds.
+        reuse_default_variant?(product, variant_data, consumed_ids) ? product.default_variant : nil
+      end
+
+      def reuse_default_variant?(product, variant_data, consumed_ids)
+        variant_data[:options].blank? &&
+          variant_data[:option_value_variants_attributes].blank? &&
+          product.default_variant.present? &&
+          product.default_variant.option_values.empty? &&
+          consumed_ids.exclude?(product.default_variant.id)
+      end
+
+      # variant_count is bumped by a counter cache in a Variant callback and the
+      # default_variant association is cached, so both are stale after writing
+      # variants out of band. Without this a product serialized in the same
+      # request reports the count and price it had before the write.
+      def sync_variant_state(product)
+        product[:variant_count] = product.class.where(id: product.id).pick(:variant_count)
+        product.variants.reset
+        product.association(:default_variant).reset
+      end
+
+      # Media entries come in five kinds: an `id` patches an existing asset, a
+      # `signed_id` attaches an already-uploaded blob, a `source_media_id`
+      # places a file already in the library, an `external_url` hands the fetch
+      # to a background job, and an external video carries a URL instead of a
+      # file. Omitting an entry leaves it alone — removal is the dedicated
+      # DELETE endpoint's job, so a form shipping stale state cannot destroy a
+      # merchant's images.
+      #
+      # @param product [Spree::Product]
+      # @param media_params [Array<Hash>, nil]
+      # @return [void]
+      def apply_media(product, media_params)
+        return if media_params.blank?
+
+        media_params.each do |raw|
+          attrs = (raw.respond_to?(:to_h) ? raw.to_h : raw).with_indifferent_access
+
+          # Every way of getting at a file comes off first, so whichever branch
+          # runs is left with attributes alone. Pulling one out inside its own
+          # branch leaves the others in the hash, and an entry carrying two of
+          # them reaches assign_attributes with a key no column matches.
+          asset_id = attrs.delete(:id)
+          source_media_id = attrs.delete(:source_media_id)
+          external_url = attrs.delete(:external_url)
+          signed_id = attrs.delete(:signed_id)
+
+          if asset_id.present?
+            asset = product.media.find_by_param(asset_id) || next
+            asset.update!(attrs)
+            next
+          end
+
+          next place_from_library(product, source_media_id, attrs) if source_media_id.present?
+          next enqueue_media_download(product, external_url, attrs) if external_url.present?
+          next if signed_id.blank? && attrs[:media_type] != 'external_video'
+
+          asset = product.media.build(attrs)
+          asset.attachment.attach(signed_id) if signed_id.present?
+          asset.save!
+        end
+      end
+
+      # Places a file already in the store's library onto this product. The new
+      # row shares the source's blob rather than copying the file.
+      #
+      # The source is looked up through the product's own store, so an id from
+      # another store is ignored rather than copying a file across the tenancy
+      # boundary — the same rule the media endpoint enforces with a 404.
+      #
+      # @param product [Spree::Product]
+      # @param source_media_id [String] prefixed or raw id of the library row
+      # @param attrs [Hash] attributes for the new placement
+      # @return [void]
+      def place_from_library(product, source_media_id, attrs)
+        source = product.store&.media&.find_by_param(source_media_id)
+        return if source.blank?
+
+        copy = source.duplicate_for(product)
+        copy.assign_attributes(attrs)
+        copy.save!
+      end
+
+      # Downloading is a job rather than a step: it reaches out over the
+      # network, and the job already owns the parts that makes necessary —
+      # SSRF filtering, a size cap, and skipping a URL this product has
+      # already fetched.
+      #
+      # Enqueued after the transaction commits, because the job loads the
+      # product by id: a worker picking it up mid-transaction would not find
+      # a product that is not visible to its connection yet.
+      #
+      # The asset is always attached to the product so one file is not
+      # downloaded once per variant; `variant_id` links the resulting asset to
+      # a variant afterwards.
+      def enqueue_media_download(product, external_url, attrs)
+        arguments = [
+          product.id,
+          'Spree::Product',
+          external_url,
+          attrs[:external_id],
+          attrs[:position],
+          attrs[:variant_id]
+        ]
+
+        ActiveRecord.after_all_transactions_commit do
+          Spree::Images::SaveFromUrlJob.perform_later(*arguments)
+        end
+      end
+
+      # Attaches downloadable files a product write ships inline, so a new
+      # product can carry its digital files in the same request. Additive, like
+      # {#apply_media}: each entry carries a `signed_id` (an uploaded file) or a
+      # `provider_type` (a provider-backed asset), and attaches to the default
+      # variant unless `variant_id` names another. An entry carrying an `id`
+      # patches that asset rather than building a duplicate — so a client
+      # replaying a product's existing digital_assets list on update does not
+      # accumulate copies. Omitting an entry leaves it alone; removal is the
+      # nested digital_assets DELETE endpoint's job.
+      #
+      # @param product [Spree::Product]
+      # @param digital_assets_params [Array<Hash>, nil]
+      # @return [void]
+      def apply_digital_assets(product, digital_assets_params)
+        return if digital_assets_params.blank?
+
+        digital_assets_params.each do |raw|
+          attrs = (raw.respond_to?(:to_h) ? raw.to_h : raw).with_indifferent_access
+
+          asset_id = attrs.delete(:id)
+          signed_id = attrs.delete(:signed_id)
+          variant_id = attrs.delete(:variant_id)
+
+          # An id patches an existing asset; without one this is a new asset on
+          # the named variant (or the default). A patch for an asset that is
+          # gone is skipped rather than recreated.
+          if asset_id.present?
+            asset = product.digital_assets.find_by_param(asset_id) || next
+          else
+            target = variant_id.present? ? product.variants.find_by_param!(variant_id) : product.default_variant
+            next unless target
+
+            asset = target.digital_assets.build
+          end
+
+          asset.assign_attributes(attrs)
+
+          if signed_id.present?
+            # Attaching never moves a blob between storage services, so a file
+            # uploaded to the public bucket would stay publicly readable. Refuse
+            # it rather than attaching it wrongly.
+            blob = ActiveStorage::Blob.find_signed(signed_id)
+            unless blob && blob.service_name.to_s == Spree.private_storage_service_name.to_s
+              asset.errors.add(:attachment, :digital_assets_attachment_must_be_private, message: Spree.t(:digital_assets_attachment_must_be_private))
+              raise ActiveRecord::RecordInvalid.new(asset)
+            end
+
+            asset.attachment.attach(signed_id)
+          end
+          asset.save!
+        end
+      end
+    end
+  end
+end

data/app/workflows/spree/products/propose.rb

@@ -0,0 +1,62 @@
+module Spree
+  module Products
+    # A seller submitting a product for the marketplace to review.
+    #
+    # The only way onto `proposed`: a seller never assigns a status, so this
+    # is what separates "listed something" from "asked for it to go on sale"
+    # (docs/plans/6.0-seller-product-submission.md).
+    #
+    # Chains straight into Approve when the store does not review listings,
+    # mirroring how `auto_approve_sellers` chains seller onboarding.
+    class Propose < Spree::Workflow
+      hooks :validate, :after_propose
+
+      # @param product [Spree::Product]
+      # @param submitted_by [Spree.admin_user_class, nil] who asked
+      # @return [Spree::ServiceModule::Result] value is the product
+      def perform(product:, submitted_by: nil)
+        super
+
+        # Only a listing that is being worked on can be submitted. Guarding
+        # `active?` alone let an archived product through — and with
+        # auto-approval on, a withdrawn listing went straight back on sale
+        # without anybody reviewing it. Re-submitting one already in review
+        # is equally meaningless.
+        unless product.draft? || product.rejected?
+          reject!(:cannot_propose, message: I18n.t('activerecord.errors.models.spree/product.attributes.base.cannot_propose'))
+        end
+
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :mark_proposed
+          step :open_submission
+          run_hooks :after_propose
+        end
+
+        product.publish_event('product.proposed')
+
+        return Spree.product_approve_workflow.call(product: product, auto: true) if auto_approve?
+
+        success(product)
+      end
+
+      private
+
+      def mark_proposed
+        failure(product) unless product.update(status: 'proposed')
+      end
+
+      # A resubmission opens a fresh row rather than reopening the decided
+      # one: the trail is how many times this was asked for, and rewriting
+      # the last answer would erase that.
+      def open_submission
+        product.submissions.create!(status: 'pending', submitted_by: submitted_by)
+      end
+
+      def auto_approve?
+        product.store&.preferred_auto_approve_seller_products.present?
+      end
+    end
+  end
+end

data/app/workflows/spree/products/reject.rb

@@ -0,0 +1,54 @@
+module Spree
+  module Products
+    # The operator turning a submitted product down.
+    #
+    # The reason lands on the product's submission row, never on the product
+    # itself: a seller can write their own product's metadata, and an
+    # operator's decision must not be erasable by its subject
+    # (docs/plans/6.0-seller-product-submission.md).
+    class Reject < Spree::Workflow
+      hooks :validate, :after_reject
+
+      # @param product [Spree::Product]
+      # @param reason [String, nil] shown to the seller
+      # @param reviewer [Spree.admin_user_class, nil] who decided
+      # @return [Spree::ServiceModule::Result] value is the product
+      def perform(product:, reason: nil, reviewer: nil)
+        super
+
+        # Already rejected counts: correcting the note you gave a seller is
+        # not a second decision, and the panel offers exactly that. Anything
+        # else has not been submitted, so there is nothing to turn down.
+        unless product.proposed? || product.rejected?
+          reject!(:not_awaiting_review, message: I18n.t('activerecord.errors.models.spree/product.attributes.base.not_awaiting_review'))
+        end
+
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :mark_rejected
+          step :close_submission
+          run_hooks :after_reject
+        end
+
+        product.publish_event('product.rejected')
+        success(product)
+      end
+
+      private
+
+      def mark_rejected
+        failure(product) unless product.update(status: 'rejected')
+      end
+
+      def close_submission
+        Spree::ProductSubmissions::Close.call(
+          product: product,
+          status: 'rejected',
+          reviewed_by: reviewer,
+          review_note: reason
+        )
+      end
+    end
+  end
+end

data/app/workflows/spree/products/update.rb

@@ -0,0 +1,83 @@
+module Spree
+  module Products
+    # Updates a product, reconciling the variants and media the payload
+    # carries (see Spree::Products::NestedAttributes — both are full
+    # replacements).
+    #
+    # Handlers reading `product.changes` in :validate see the pending edit
+    # before it is written, which is what makes rules like "price may not
+    # drop below cost" expressible without a model validation.
+    class Update < Spree::Workflow
+      include Spree::Products::NestedAttributes
+
+      hooks :validate, :after_update
+
+      # `product` — the record with the pending attributes assigned, so a
+      # :validate handler reads `product.changes` to see the edit.
+
+      # @param product [Spree::Product]
+      # @param attributes [Hash]
+      # @return [Spree::ServiceModule::Result] value is the product
+      def perform(product:, attributes: {})
+        super
+
+        step :assign_attributes
+        step :refuse_review_status_write
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :save_product
+          step :apply_nested_attributes
+          run_hooks :after_update
+        end
+
+        success(product)
+      end
+
+      private
+
+      def assign_attributes
+        # See Spree::Products::Create — string-keyed hashes reach this from
+        # host apps and importers, and a missed key would send the nested
+        # payload to the ActiveRecord collection setter instead.
+        attrs = attributes.to_h.with_indifferent_access
+        @status_in_payload = attrs.key?(:status)
+
+        # Held back: variants and media are reconciled after the save, so a
+        # :validate handler reads `product.changes` describing the edit itself
+        # rather than a half-applied collection.
+        @variants_params = attrs[:variants]
+        @media_params = attrs[:media]
+        @digital_assets_params = attrs[:digital_assets]
+        product.assign_attributes(attrs.except(:variants, :media, :digital_assets))
+      end
+
+      # Leaving review is a decision, and a decision belongs to Approve or
+      # Reject — they are what record who made it. A plain status write would
+      # put a product on sale with nobody's name against it, so it refuses
+      # (docs/plans/6.0-seller-product-submission.md).
+      #
+      # Only what this call asked for: the CSV importer assigns attributes
+      # itself and hands over an already-dirty record, so reading the record
+      # rather than the payload would refuse every re-imported row whose
+      # product happens to be in review.
+      def refuse_review_status_write
+        return unless @status_in_payload
+        return unless product.status_changed?
+        return unless product.status_was.in?(Spree::Product::REVIEW_STATUSES)
+
+        reject!(:status_decided_by_review, message: I18n.t('activerecord.errors.models.spree/product.attributes.base.status_decided_by_review'))
+      end
+
+      def save_product
+        failure(product) unless product.save
+      end
+
+      def apply_nested_attributes
+        apply_variants(product, @variants_params)
+        apply_media(product, @media_params)
+        apply_digital_assets(product, @digital_assets_params)
+      end
+    end
+  end
+end

data/app/workflows/spree/purchase_orders/cancel.rb

@@ -0,0 +1,57 @@
+module Spree
+  module PurchaseOrders
+    # Calls the order off.
+    #
+    # Nothing to unwind: a purchase order never moved stock until units were
+    # received, and units already received stay on the shelf — the merchant has
+    # them. Cancelling closes what is still outstanding, which is a message to
+    # accounts payable rather than a stock correction.
+    class Cancel < Spree::Workflow
+      include Spree::Receivables::IncomingCounter
+
+      hooks :validate, :after_cancel
+
+      # @param purchase_order [Spree::PurchaseOrder]
+      # @param reason [String, nil] why it was called off; appended to the
+      #   order's notes, which is what the merchant reads afterwards
+      # @param canceler [Object, nil]
+      def perform(purchase_order:, reason: nil, canceler: nil)
+        super
+
+        # One change at a time per document: the units still awaited are read
+        # from each line and then withdrawn from the counter, so a delivery
+        # committing in between would leave its units counted twice — once
+        # landed, once withdrawn as never coming.
+        purchase_order.with_lock do
+          step :ensure_cancelable
+          run_hooks :validate
+
+          step :uncount_awaited_units
+          step :mark_canceled
+        end
+
+        run_hooks :after_cancel
+        purchase_order.publish_event('purchase_order.canceled')
+        success(purchase_order.reload)
+      end
+
+      private
+
+      def ensure_cancelable
+        return unless purchase_order.closed?
+
+        failure(purchase_order, Spree.t('purchase_order.errors.already_closed'))
+      end
+
+      def uncount_awaited_units
+        uncount_incoming(purchase_order)
+      end
+
+      def mark_canceled
+        notes = [purchase_order.notes, reason].compact_blank.join("\n")
+
+        failure(purchase_order) unless purchase_order.update(status: 'canceled', notes: notes)
+      end
+    end
+  end
+end