spree_core 5.6.1 → 6.0.0.beta2

data/app/workflows/spree/sellers/suspend.rb

@@ -0,0 +1,55 @@
+module Spree
+  module Sellers
+    # Halts a trading seller: their catalog stops selling, their record and
+    # history stay. Reversible through Spree::Sellers::Approve.
+    class Suspend < Spree::Workflow
+      hooks :validate, :after_suspend
+
+      # @param seller [Spree::Seller]
+      # @param reason [String, nil] why, for the seller and the audit trail
+      # @param suspended_by [Object, nil] the staff member suspending
+      def perform(seller:, reason: nil, suspended_by: nil)
+        super
+
+        step :ensure_suspendable
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :mark_suspended
+        end
+
+        run_hooks :after_suspend
+        seller.publish_event('seller.suspended')
+        success(seller.reload)
+      end
+
+      private
+
+      # Anyone already admitted can be stopped — including a seller still
+      # setting themselves up, since a marketplace may need to halt someone
+      # mid-onboarding. What cannot be suspended is a seller who has not been
+      # admitted at all; turning those away is Reject, which says something
+      # different and is not the same undo.
+      def ensure_suspendable
+        failure(seller, :already_suspended) if seller.suspended?
+
+        return if seller.approved? || seller.onboarding? || seller.ready_for_review?
+
+        failure(seller, :not_suspendable)
+      end
+
+      def mark_suspended
+        seller.update!(status: 'suspended')
+        record_reason
+      end
+
+      # Kept in metadata rather than a column: it is a note about one event,
+      # and the next suspension will have its own.
+      def record_reason
+        return if reason.blank?
+
+        seller.update!(metadata: seller.metadata.to_h.merge('suspension_reason' => reason))
+      end
+    end
+  end
+end

data/app/workflows/spree/shipping_labels/purchase.rb

@@ -0,0 +1,154 @@
+module Spree
+  module ShippingLabels
+    # Buys a carrier label for a parcel through the owner's fulfillment
+    # provider and records it as a Spree::ShippingLabel with the delivery it
+    # mints (docs/plans/6.0-shipping-labels-and-deliveries.md).
+    #
+    # Idempotency lives here, not in the provider: an owner already holding an
+    # active label is refused, so a provider is never asked twice and needs no
+    # bookkeeping of its own. The file is fetched into private storage right
+    # after purchase; a fetch that fails is retried in the background and the
+    # provider's URL is kept until then.
+    #
+    # In the workflow tier for the carrier I/O and its hooks: a host app that
+    # wants to veto a purchase (a cut-off window, a carrier allowlist) or act
+    # on a bought label (print queue, cost ledger) hangs it here.
+    class Purchase < Spree::Workflow
+      hooks :validate, :after_purchase
+
+      # The label that was bought, readable by hook handlers.
+      attr_reader :shipping_label
+
+      # @param owner [Spree::Fulfillment, Spree::Return] what the label ships
+      # @return [Spree::ServiceModule::Result] the shipping label on success
+      def perform(owner:)
+        super
+
+        run_hooks :validate
+
+        step :ensure_purchasable
+        step :claim_purchase, on_flow_failure: :release_claim
+
+        # Carrier I/O — never inside a transaction.
+        external_step :purchase
+
+        ApplicationRecord.transaction do
+          step :record_label
+          step :record_delivery
+        end
+
+        step :store_file
+
+        shipping_label.publish_event('shipping_label.purchased')
+        run_hooks :after_purchase
+        success(shipping_label.reload)
+      end
+
+      private
+
+      def provider
+        @provider ||= owner.provider
+      end
+
+      def ensure_purchasable
+        failure(owner, Spree.t('shipping_labels.errors.provider_has_no_labels')) unless provider.class.generates_labels?
+        failure(owner, Spree.t('shipping_labels.errors.already_purchased')) if owner.shipping_labels.active.exists?
+
+        case owner
+        when Spree::Fulfillment
+          failure(owner, Spree.t('fulfillments.errors.cannot_purchase_label')) unless owner.unfulfilled?
+          failure(owner, Spree.t('fulfillments.errors.order_draft')) if owner.order&.draft?
+        when Spree::Return
+          failure(owner, Spree.t('shipping_labels.errors.return_closed')) if owner.received? || owner.refunded? || owner.canceled?
+        end
+      end
+
+      # The claim, not the check above, is what makes a double click buy one
+      # label: it inserts the row before the carrier is called, so the loser
+      # of the race is refused rather than charged. A partial unique index
+      # settles it where the database has one; everywhere else the owner's
+      # row lock serializes the two claims, which is why the check is
+      # re-read inside it.
+      def claim_purchase
+        owner.with_lock do
+          failure(owner, Spree.t('shipping_labels.errors.already_purchased')) if owner.shipping_labels.active.exists?
+
+          @shipping_label = owner.shipping_labels.create!(
+            store: owner.store,
+            integration: provider.integration_for(owner),
+            source: 'purchased',
+            status: 'purchased'
+          )
+        end
+      rescue ActiveRecord::RecordNotUnique
+        failure(owner, Spree.t('shipping_labels.errors.already_purchased'))
+      end
+
+      # Undoes the claim when the carrier refuses, so a failed purchase does
+      # not leave a row that refuses every later attempt.
+      #
+      # Only while nothing has been bought: once the carrier has charged for a
+      # label, the row is the merchant's only record of it — destroying it
+      # would leave postage paid and nothing to print or refund.
+      def release_claim
+        return if @purchase.present?
+
+        @shipping_label&.destroy
+        @shipping_label = nil
+      end
+
+      # A provider that knows why the carrier said no raises with its words;
+      # anything else falls back to the generic line, since a nil tells us
+      # nothing worth passing on.
+      def purchase
+        @purchase = provider.purchase_label(owner)
+
+        return if @purchase.is_a?(Spree::LabelPurchase) && @purchase.valid?
+
+        failure(owner, Spree.t('fulfillments.errors.label_purchase_failed'))
+      rescue Spree::Core::LabelPurchaseRefused => e
+        failure(owner, e.message)
+      end
+
+      def record_label
+        shipping_label.update!(
+          external_id: @purchase.external_id,
+          carrier: @purchase.carrier,
+          service: @purchase.service,
+          tracking_number: @purchase.tracking_number,
+          cost: @purchase.cost || 0,
+          currency: @purchase.currency,
+          format: @purchase.format,
+          metadata: (@purchase.metadata || {}).merge('file_url' => @purchase.file_url).compact
+        )
+      end
+
+      # A label mints its own consignment. When the merchant already typed the
+      # same number by hand, the delivery service binds that row rather than
+      # letting a duplicate be refused.
+      def record_delivery
+        result = Spree.delivery_create_service.call(
+          adopt: true,
+          owner: owner,
+          tracking_number: @purchase.tracking_number,
+          carrier: @purchase.carrier,
+          service: @purchase.service,
+          tracking_url: @purchase.tracking_url,
+          shipping_label: shipping_label
+        )
+        failure(shipping_label, result.error.to_s) if result.failure?
+      end
+
+      # Fetched in the background rather than in the request: the merchant has
+      # already waited on one carrier call, and a slow label CDN would hold
+      # the order lock the controller took for as long as it stalls. Until it
+      # lands the download proxies the carrier's own copy, which is what
+      # +file_pending?+ is for.
+      def store_file
+        return if @purchase.file_url.blank?
+
+        Spree::ShippingLabels::StoreFileJob.perform_later(shipping_label.id)
+      end
+    end
+  end
+end

data/app/workflows/spree/shipping_labels/record.rb

@@ -0,0 +1,102 @@
+module Spree
+  module ShippingLabels
+    # Records a label the merchant bought elsewhere — postage from a carrier
+    # site, a 3PL's PDF — so the parcel still has its file, its tracking
+    # number and what it cost, with no carrier integration involved.
+    #
+    # The uploaded label mints its delivery like a purchased one; what it
+    # cannot do is be refunded through Spree, so deleting it is the way out.
+    class Record < Spree::Workflow
+      hooks :validate, :after_record
+
+      # The label that was recorded, readable by hook handlers.
+      attr_reader :shipping_label
+
+      # @param owner [Spree::Fulfillment, Spree::Return]
+      # @param file [ActionDispatch::Http::UploadedFile, String] the file, or a signed blob id from a direct upload
+      # @param tracking_number [String] the number printed on the label
+      # @param carrier [String, nil] free text; detected from the number when omitted
+      # @param service [String, nil]
+      # @param cost [Numeric, nil] what the merchant paid; 0 when unknown
+      # @param currency [String, nil]
+      # @param file_format [String, nil] pdf | png | zpl; taken from the file when omitted
+      # @param tracking_url [String, nil]
+      # @return [Spree::ServiceModule::Result] the shipping label on success
+      def perform(owner:, file:, tracking_number:, carrier: nil, service: nil, cost: nil, currency: nil, file_format: nil, tracking_url: nil)
+        super
+
+        run_hooks :validate
+
+        step :ensure_recordable
+
+        ApplicationRecord.transaction do
+          step :record_label
+          step :record_delivery
+        end
+
+        run_hooks :after_record
+        success(shipping_label.reload)
+      end
+
+      private
+
+      def ensure_recordable
+        failure(owner, Spree.t('shipping_labels.errors.already_purchased')) if owner.shipping_labels.active.exists?
+        failure(owner, Spree.t('shipping_labels.errors.tracking_number_required')) if tracking_number.blank?
+        failure(owner, Spree.t('shipping_labels.errors.file_required')) if file.blank?
+
+        case owner
+        when Spree::Fulfillment
+          failure(owner, Spree.t('fulfillments.errors.cannot_purchase_label')) if owner.canceled? || owner.delivered?
+        when Spree::Return
+          failure(owner, Spree.t('shipping_labels.errors.return_closed')) if owner.received? || owner.refunded? || owner.canceled?
+        end
+      end
+
+      def record_label
+        @shipping_label = owner.shipping_labels.new(
+          store: owner.store,
+          source: 'uploaded',
+          status: 'purchased',
+          carrier: carrier,
+          service: service,
+          tracking_number: tracking_number,
+          cost: cost || 0,
+          currency: currency.presence || owner.store.default_currency,
+          file: file
+        )
+        @shipping_label.format = file_format.presence || format_from_file
+        failure(@shipping_label) unless @shipping_label.save
+      end
+
+      # A direct-upload blob carries the type the client declared, which the
+      # attachment validator re-decides from the bytes; either way the
+      # extension is the merchant-visible answer, so it wins when it names a
+      # format Spree knows.
+      def format_from_file
+        blob = @shipping_label.file.blob
+        extension = File.extname(blob&.filename.to_s).delete('.').downcase
+        return extension if Spree::ShippingLabel::FORMATS.include?(extension)
+
+        case blob&.content_type.to_s
+        when 'image/png' then 'png'
+        when 'text/plain', 'application/zpl' then 'zpl'
+        else 'pdf'
+        end
+      end
+
+      def record_delivery
+        result = Spree.delivery_create_service.call(
+          adopt: true,
+          owner: owner,
+          tracking_number: shipping_label.tracking_number,
+          carrier: carrier,
+          service: service,
+          tracking_url: tracking_url,
+          shipping_label: shipping_label
+        )
+        failure(shipping_label, result.error.to_s) if result.failure?
+      end
+    end
+  end
+end

data/app/workflows/spree/shipping_labels/refund.rb

@@ -0,0 +1,77 @@
+module Spree
+  module ShippingLabels
+    # Asks the carrier to refund a purchased label. The carrier answers
+    # either way at once (+refunded+) or later (+refund_requested+, settled
+    # through Spree::ShippingLabels::ConfirmRefund); an uploaded label has
+    # nothing to refund and is deleted instead.
+    #
+    # The delivery the label minted is removed only when the consignment
+    # never moved — once the parcel has shipped the journey is history and
+    # the delivery stays, label or no label.
+    class Refund < Spree::Workflow
+      hooks :validate, :after_refund
+
+      # @param shipping_label [Spree::ShippingLabel]
+      # @return [Spree::ServiceModule::Result] the label on success
+      def perform(shipping_label:)
+        super
+
+        run_hooks :validate
+
+        step :ensure_refundable
+
+        # Carrier I/O — never inside a transaction.
+        external_step :refund
+
+        ApplicationRecord.transaction do
+          step :record_outcome
+          step :remove_delivery_if_never_moved
+        end
+
+        shipping_label.publish_event('shipping_label.refunded') if shipping_label.refunded?
+        run_hooks :after_refund
+        success(shipping_label.reload)
+      end
+
+      private
+
+      # A label the carrier is still deciding on is re-askable: some carriers
+      # settle refunds asynchronously, and re-filing is how a request that
+      # never came back is re-driven.
+      def ensure_refundable
+        return if shipping_label.refundable?
+
+        reason = shipping_label.uploaded? ? 'uploaded_not_refundable' : 'not_refundable'
+        failure(shipping_label, Spree.t("shipping_labels.errors.#{reason}"))
+      end
+
+      # A provider that knows why the carrier said no raises with its words;
+      # anything else falls back to the generic line.
+      def refund
+        @outcome = shipping_label.provider.refund_label(shipping_label).to_s
+
+        return if %w[refunded refund_requested].include?(@outcome)
+
+        failure(shipping_label, Spree.t('shipping_labels.errors.refund_failed'))
+      rescue Spree::Core::LabelRefundRefused => e
+        failure(shipping_label, e.message)
+      end
+
+      def record_outcome
+        attributes = { status: @outcome }
+        attributes[:refunded_at] = Time.current if @outcome == 'refunded'
+        shipping_label.update!(attributes)
+      end
+
+      # Only once the carrier has actually refunded. A refund the carrier is
+      # still deciding on may never settle, and the parcel keeps travelling
+      # under this tracking number meanwhile — ShippingLabels::ConfirmRefund
+      # releases it when the answer arrives.
+      def remove_delivery_if_never_moved
+        return unless shipping_label.refunded?
+
+        shipping_label.release_unmoved_delivery
+      end
+    end
+  end
+end

data/app/workflows/spree/stock_receipts/recording.rb

@@ -0,0 +1,165 @@
+module Spree
+  module StockReceipts
+    # The steps every delivery takes, whichever document it is against. The
+    # workflow including this names the document (`receivable`), says when it
+    # may be received (`ensure_receivable`), which lines are its own
+    # (`line_belongs?`) and what a line's units cost (`unit_cost_for`).
+    #
+    # Quantities are this delivery's counts, not running totals: "forty
+    # arrived, two of them crushed" is what the dock writes down, and what a
+    # second delivery of the same line adds to rather than restates. Accepted
+    # units reach the shelf; rejected ones exist only on the receipt.
+    module Recording
+      private
+
+      def record_delivery
+        # One delivery at a time per document. Each line's running total is
+        # read and then written, so two deliveries booked at once would both
+        # add to the same starting figure. The lock also opens the transaction
+        # the writes need, and is always taken document-then-level, never the
+        # other way, so it cannot cross with the lock
+        # `StockLevel#adjust_count_on_hand` takes underneath.
+        receivable.with_lock do
+          # The caller resolved these before the lock, so their running totals
+          # may predate a delivery that has since committed.
+          items&.each { |item| item[:item]&.reload }
+
+          step :ensure_receivable
+          step :normalize_items
+          run_hooks :validate
+
+          step :build_receipt
+          step :update_lines
+          step :uncount_landed_units
+          run_hooks :before_restock
+          step :restock_accepted
+          step :settle_status
+        end
+
+        run_hooks :after_receive
+        receivable.publish_event("#{event_prefix}.#{receivable.status}")
+        success(stock_receipt.reload)
+      end
+
+      # Nothing named means the whole outstanding balance arrived intact.
+      #
+      # Sorted by variant once, here, because every later step walks this list
+      # while holding the document's transaction open and each stock-level
+      # write keeps its row lock to the end of it. Two deliveries naming the
+      # same variants in opposite order would otherwise wait on each other.
+      def normalize_items
+        @normalized_items =
+          if items.nil?
+            receivable.items.select { |line| line.outstanding.positive? }.map do |line|
+              { line: line, quantity_accepted: line.outstanding, quantity_rejected: 0 }
+            end
+          else
+            reject_repeated_lines
+            Array(items).filter_map { |item| normalize_item(item) }
+          end
+        @normalized_items = @normalized_items.sort_by { |entry| entry[:line].variant_id }
+
+        return if @normalized_items.any?
+
+        failure(receivable, Spree.t("#{error_scope}.errors.no_items_received"))
+      end
+
+      # A line the payload names but counts nothing on is left out rather than
+      # refused: a receive screen submits every row, most of them untouched.
+      def normalize_item(item)
+        line = item[:item]
+        failure(receivable, Spree.t("#{error_scope}.errors.item_not_on_document")) unless line_belongs?(line)
+
+        accepted = item[:quantity_accepted].to_i
+        rejected = item[:quantity_rejected].to_i
+        if accepted.negative? || rejected.negative?
+          failure(receivable, Spree.t("#{error_scope}.errors.invalid_receipt_quantity", variant: line.variant_name))
+        end
+        return nil if accepted.zero? && rejected.zero?
+
+        {
+          line: line,
+          quantity_accepted: accepted,
+          quantity_rejected: rejected,
+          rejection_reason: item[:rejection_reason].presence,
+          notes: item[:notes].presence
+        }
+      end
+
+      # Two entries for one line are genuinely ambiguous — two cartons, or a
+      # correction of the first? — so they are refused rather than merged.
+      def reject_repeated_lines
+        lines = Array(items).map { |item| item[:item] }.compact
+        repeated = lines.group_by(&:id).values.find { |group| group.length > 1 }
+        return if repeated.nil?
+
+        failure(receivable, Spree.t("#{error_scope}.errors.repeated_item", variant: repeated.first.variant_name))
+      end
+
+      def build_receipt
+        @stock_receipt = receivable.stock_receipts.build(
+          store: receivable.store,
+          received_at: received_at.presence || Time.current,
+          reference: reference,
+          notes: notes,
+          received_by: received_by
+        )
+        @normalized_items.each { |entry| @stock_receipt.items.build(entry) }
+
+        failure(@stock_receipt) unless @stock_receipt.save
+      end
+
+      def update_lines
+        @normalized_items.each do |entry|
+          line = entry[:line]
+          entry[:incoming_before] = line.incoming
+          line.update!(
+            quantity_received: line.quantity_received.to_i + entry[:quantity_accepted],
+            quantity_rejected: line.quantity_rejected.to_i + entry[:quantity_rejected]
+          )
+        end
+      end
+
+      # What this delivery settled — accepted or refused — is no longer on its
+      # way. Inside the document lock with the restock below, so no read in
+      # between shows the units both incoming and on hand, or neither.
+      def uncount_landed_units
+        destination = receivable.destination_location
+
+        @normalized_items.each do |entry|
+          landed = entry[:incoming_before] - entry[:line].incoming
+          next if landed.zero?
+
+          destination.stock_level_or_create(entry[:line].variant).adjust_incoming_count(-landed)
+        end
+      end
+
+      # Only accepted units land. The receipt is the cause, and brings the
+      # document's own foreign key with it.
+      def restock_accepted
+        destination = receivable.destination_location
+
+        @normalized_items.each do |entry|
+          next unless entry[:quantity_accepted].positive?
+
+          destination.restock(entry[:line].variant, entry[:quantity_accepted], stock_receipt,
+                              unit_cost: unit_cost_for(entry[:line]))
+        end
+      end
+
+      # `received_at` is stamped only when the document actually closes, in
+      # full or over — a partial delivery leaves it open.
+      def settle_status
+        # The caller's lines are freshly-loaded instances, not the ones the
+        # association is holding, so the totals have to be re-read before they
+        # can decide the status.
+        receivable.items.reset
+        status = receivable.status_after_receive
+        attributes = { status: status }
+        attributes[:received_at] = Time.current if Spree::Receivable::CLOSED_STATUSES.include?(status)
+
+        failure(receivable) unless receivable.update(attributes)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+module Spree
+  module StockTransfers
+    # Calls the trip off.
+    #
+    # Cancelling a draft or a packed transfer costs nothing — no stock has
+    # moved. Cancelling one already in transit is a decision the merchant has
+    # to make, because the units are physically gone from the source: either
+    # they come back (`restock`, as if the box never left) or they are written
+    # off (`write_off`, shrinkage). There is no silent reversal, and no
+    # default: guessing would either invent stock or destroy it.
+    class Cancel < Spree::Workflow
+      include Spree::Receivables::IncomingCounter
+
+      hooks :validate, :after_cancel
+
+      # How in-flight units are accounted for.
+      IN_TRANSIT_RESOLUTIONS = %w[restock write_off].freeze
+
+      # Recorded on every line the merchant wrote off without saying why.
+      DEFAULT_WRITE_OFF_REASON = 'lost_in_transit'.freeze
+
+      # @param stock_transfer [Spree::StockTransfer]
+      # @param on_in_transit [String, nil] `'restock'` or `'write_off'`;
+      #   required once the units have left the source
+      # @param reason [String, nil] audit text for the write-off
+      # @param canceler [Object, nil]
+      def perform(stock_transfer:, on_in_transit: nil, reason: nil, canceler: nil)
+        super
+
+        # One cancellation at a time per document, and no receive alongside it.
+        # Each line's outstanding quantity is what is still in flight, so a
+        # receive committing between reading it and restocking the source
+        # credits the same units twice — once onto the destination shelf, once
+        # back onto the source. Locked document-then-level, as `Receive` does.
+        stock_transfer.with_lock do
+          step :ensure_cancelable
+          run_hooks :validate
+
+          step :uncount_in_flight_units
+          step :resolve_in_flight_units
+          step :mark_canceled
+        end
+
+        run_hooks :after_cancel
+        stock_transfer.publish_event('stock_transfer.canceled')
+        success(stock_transfer.reload)
+      end
+
+      private
+
+      def ensure_cancelable
+        failure(stock_transfer, Spree.t('stock_transfer.errors.already_closed')) if stock_transfer.closed?
+        return unless stock_transfer.in_flight?
+        return if IN_TRANSIT_RESOLUTIONS.include?(on_in_transit)
+
+        failure(stock_transfer, Spree.t('stock_transfer.errors.in_transit_resolution_required'))
+      end
+
+      # Whether the units come back or are written off, the destination is no
+      # longer expecting them.
+      def uncount_in_flight_units
+        uncount_incoming(stock_transfer)
+      end
+
+      # Only the units still in flight are resolved: anything the destination
+      # already counted in is on its shelf and stays there.
+      def resolve_in_flight_units
+        return unless stock_transfer.in_flight?
+
+        # Read the running totals under the lock: an association loaded before
+        # it holds the quantities as they were before any receive that has
+        # since committed, and those are what `outstanding` subtracts from.
+        return write_off if on_in_transit == 'write_off'
+
+        stock_transfer.items.reload.each do |item|
+          next unless item.outstanding.positive?
+
+          restock(item)
+        end
+      end
+
+      # Back onto the source's shelf, as if the box had never left. Written as
+      # a `received` movement carrying this transfer, so the departure and its
+      # reversal reconcile against each other in the ledger.
+      def restock(item)
+        stock_transfer.source_location.restock(item.variant, item.outstanding, stock_transfer)
+      end
+
+      # Nothing to write to the shelf: the units left the source when the
+      # transfer was marked in transit and never arrived anywhere, so the loss
+      # is already in the ledger. What is missing is why, and that is recorded
+      # as the reason the transfer closed — the same place a short close puts
+      # it.
+      def write_off
+        @close_reason = reason.presence || DEFAULT_WRITE_OFF_REASON
+      end
+
+      def mark_canceled
+        failure(stock_transfer) unless stock_transfer.update(status: 'canceled', close_reason: @close_reason)
+      end
+    end
+  end
+end