spree_core 5.6.1 → 6.0.0.beta2

data/app/workflows/spree/seller_transfers/reverse.rb

@@ -0,0 +1,241 @@
+module Spree
+  module SellerTransfers
+    # Takes back part of what a seller earned, after a refund.
+    #
+    # Written as its own negative row rather than by editing the earning, so
+    # what a seller has earned is always the sum of their transfers and the
+    # history stays readable. If the earning was already settled in a closed
+    # payout, the reversal simply lands in the next period — a settlement that
+    # happened is never rewritten.
+    #
+    # The ledger row is written in every tier. Whether money is actually pulled
+    # back is the provider's business, and the built-in one pulls back nothing.
+    class Reverse < Spree::Workflow
+      hooks :validate, :after_reverse
+
+      attr_reader :reversal
+
+      # @param order [Spree::Order] the seller order being refunded
+      # @param amount [BigDecimal, Numeric] how much of the earning to take
+      #   back; capped at what is left of it
+      # @param refund [Spree::Refund, nil] what caused the clawback. The
+      #   reversal's natural key, so a redelivered event reverses once.
+      # @return [Spree::ServiceModule::Result] value is the reversal, or the
+      #   order when there was nothing to reverse
+      def perform(order:, amount:, refund: nil)
+        super
+
+        step :find_earning
+        step :replay_existing
+        run_hooks :validate
+
+        step :build_reversal
+        external_step :execute_reversal
+        run_hooks :after_reverse
+
+        success(reversal)
+      end
+
+      private
+
+      def find_earning
+        @earning = Spree::SellerTransfer.earnings.find_by(order_id: order.id)
+        # Nothing was ever credited — the order was refunded before it shipped,
+        # which is the ordinary case and not an error.
+        halt!(order) if @earning.nil?
+      end
+
+      # An event can be delivered twice, and a job can retry.
+      def replay_existing
+        return if refund.nil?
+
+        existing = Spree::SellerTransfer.reversals_only.find_by(refund_id: refund.id)
+        halt!(existing) if existing.present?
+      end
+
+      # Bounded and written under the earning's own lock, so two refunds
+      # landing together cannot each read the same untouched earning and each
+      # take the whole of it. The unique index on `refund_id` covers the other
+      # race — the same refund arriving twice — and resolves to the row that
+      # won rather than failing the caller.
+      def build_reversal
+        @reversal = write_reversal
+        halt!(order) if @reversal.nil?
+      rescue ActiveRecord::RecordNotUnique
+        # Only a refund-keyed reversal can collide, since that index is what
+        # makes it unique. Re-raising anything else keeps the real error
+        # visible rather than replacing it with a lookup that cannot succeed.
+        raise if refund.nil?
+
+        halt!(Spree::SellerTransfer.reversals_only.find_by!(refund_id: refund.id))
+      end
+
+      # The seller's share of a refunded amount.
+      #
+      # A refund is the customer's gross figure — it carries the tax and the
+      # marketplace's commission, while the seller only ever received their net
+      # cut. Taking the gross back would charge them the commission on goods
+      # that came back, so what comes back is always the seller's share of it.
+      #
+      # Which share depends on what the refund can say about itself. A return or
+      # a claim names the lines it paid for, and those lines earned a knowable
+      # amount. Anything else — a manual refund, a cancellation — is only an
+      # amount against an order, and the order's own ratio is the best available
+      # answer.
+      def seller_share_of(refunded)
+        attributed_share(refunded) || blended_share(refunded)
+      end
+
+      # What the named lines actually earned, scaled to what this refund paid.
+      #
+      # The scaling is not a refinement: one return is refunded once per payment
+      # it draws on, and every one of those refunds names the same lines. Taking
+      # them at face value would claw the same units back once per payment.
+      # Scaling also absorbs an operator who refunded a different amount than the
+      # lines are worth — a restocking fee, or goodwill on top.
+      #
+      # Nil when the refund names nothing, which sends the caller to the blend.
+      def attributed_share(refunded)
+        amounts = refund&.refunded_line_amounts
+        return if amounts.blank?
+
+        gross = amounts.values.sum.to_d
+        return if gross <= 0
+
+        # Nil from any line means the attribution cannot be trusted whole, so
+        # the blend answers for the refund rather than part of it.
+        earnings = amounts.map { |line_item_id, amount| line_earning(line_item_id, amount.to_d) }
+        return if earnings.any?(&:nil?)
+
+        quantize(earnings.sum * (refunded.to_d.abs / gross))
+      end
+
+      def blended_share(refunded)
+        paid = order.total.to_d
+        return refunded.to_d.abs if paid.zero?
+
+        quantize(refunded.to_d.abs * (@earning.amount / paid))
+      end
+
+      # What one line's refunded value earned the seller: their money less the
+      # commission charged on it, and less the consumer tax when the marketplace
+      # remits it — mirroring how the earning itself was worked out.
+      #
+      # The commission comes from the row written against that line at
+      # placement, not from today's rate: rates change, a clamped fee is not the
+      # rate times the base, and a fixed rate is charged per unit.
+      def line_earning(line_item_id, amount)
+        line_item = order_line_items[line_item_id]
+        paid = line_item&.amount.to_d
+        # A line this order does not carry, or one worth nothing, says nothing
+        # about what the seller earned. Answering the gross would claw back the
+        # commission and the tax they never received, which is the whole thing
+        # this is here to avoid, so the caller falls back to the order's ratio.
+        return if paid.zero?
+
+        # Only ever a fraction of the line, so a clamped commission is divided
+        # rather than reasoned about — the best available attribution.
+        share = amount / paid
+        earned = amount - (commission_totals[line_item_id].to_d * share)
+        earned -= line_item.tax_total.to_d * share if order.seller&.tax_remittance == 'platform'
+        earned
+      end
+
+      def order_line_items
+        @order_line_items ||= order.line_items.index_by(&:id)
+      end
+
+      def commission_totals
+        @commission_totals ||= Spree::CommissionLine.for_line_items.
+                               where(line_item_id: order_line_items.keys).
+                               pluck(:line_item_id, :total).to_h
+      end
+
+      def quantize(amount)
+        Spree::Money::Rounding.quantize(amount, Spree::Money::Rounding.precision(@earning.currency))
+      end
+
+      # Nil when there is nothing left to take back, which the caller turns
+      # into a halt outside the transaction — `halt!` refuses to run inside one.
+      def write_reversal
+        @earning.with_lock do
+          bounded = [seller_share_of(amount), @earning.reversible_amount].min
+          next nil if bounded <= 0
+
+          Spree::SellerTransfer.create!(
+            {
+              store: @earning.store,
+              seller: @earning.seller,
+              order: order,
+              reversed_from: @earning,
+              refund: refund,
+              # Negative, so what a seller has earned is the plain sum of the rows.
+              amount: -bounded,
+              currency: @earning.currency,
+              kind: 'refund_reversal',
+              provider: @earning.provider,
+              status: 'pending'
+            }.merge(settlement_of(bounded))
+          )
+        end
+      end
+
+      # A clawback has to settle where its earning settled. Payouts are swept by
+      # settlement currency, so a reversal left in the sale's currency would
+      # never join the batch that pays the earning it cancels — the seller would
+      # be paid in full for goods that came back, and the row would sit in a
+      # currency their account cannot pay.
+      #
+      # Prorated from the earning's own settled figure rather than converted at
+      # today's rate, so the money comes back at the rate it went out at.
+      def settlement_of(bounded)
+        return {} if @earning.settled_amount.blank? || @earning.amount.zero?
+
+        share = @earning.settled_amount * (bounded / @earning.amount)
+
+        {
+          settled_amount: -Spree::Money::Rounding.quantize(
+            share, Spree::Money::Rounding.precision(@earning.settlement_currency)
+          ),
+          settled_currency: @earning.settled_currency
+        }
+      end
+
+      def execute_reversal
+        provider.reverse!(reversal)
+      rescue Spree::Core::AmbiguousGatewayError => e
+        # Whether the clawback happened is the provider's to say. Recorded as
+        # such rather than as a refusal, so an operator reconciling knows which
+        # rows are questions and which are simply owed.
+        reversal.update!(status: 'unresolved')
+        Rails.error.report(e, handled: true, context: { seller_transfer_id: reversal.id }, source: 'spree.core')
+        failure(reversal, e.message)
+      rescue StandardError => e
+        reversal.update!(status: 'processing')
+        Rails.error.report(e, handled: true, context: { seller_transfer_id: reversal.id }, source: 'spree.core')
+        failure(reversal, e.message)
+      end
+
+      # The provider that made the earning, not whichever one the store uses
+      # now. A marketplace that changes provider still has money sitting with
+      # the old one, and asking the new one to reverse a transfer it never
+      # made leaves the original standing — the seller keeps a refunded sale.
+      def provider
+        @provider ||= begin
+          configured = Spree.payout_providers.find { |candidate| candidate.to_s == @earning.provider }
+
+          # No silent fallback to whatever the store uses now. A provider that
+          # is no longer installed still holds the transfer this reverses, and
+          # handing the job to a different one would mark the row reversed
+          # while the money stayed where it was. An operator has to know.
+          if configured.nil?
+            raise Spree::Core::GatewayError,
+                  "Payout provider #{@earning.provider} is not registered, so its transfer cannot be reversed"
+          end
+
+          configured.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+module Spree
+  module Sellers
+    # Lets a seller trade. Also the way back for one that was suspended or
+    # turned down, which is why the guard admits more than the linear path.
+    class Approve < Spree::Workflow
+      hooks :validate, :after_approve
+
+      # Requirement statuses that were outstanding at approval — empty
+      # unless the operator overrode them.
+      # @return [Array<Spree::SellerRequirementStatus>]
+      attr_reader :unmet_requirements
+
+      # @param seller [Spree::Seller]
+      # @param approver [Object, nil] the staff member approving
+      # @param override_requirements [Boolean] admit the seller even though
+      #   the marketplace's checklist is not finished — the operator's
+      #   deliberate exception, recorded on the event
+      def perform(seller:, approver: nil, override_requirements: false)
+        super
+
+        step :ensure_approvable
+        step :ensure_requirements_met
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :mark_approved
+        end
+
+        run_hooks :after_approve
+        seller.publish_event('seller.approved', nil,
+                             requirements_overridden: override_requirements,
+                             unmet_requirements: unmet_requirement_names)
+        success(seller.reload)
+      end
+
+      private
+
+      def ensure_approvable
+        failure(seller, :already_approved) if seller.approved?
+
+        return if seller.onboarding? || seller.ready_for_review? ||
+                  seller.suspended? || seller.rejected?
+
+        failure(seller, :not_approvable)
+      end
+
+      # The checklist gates admission, and the operator can step over it —
+      # they know things about a seller the marketplace never asked for. What
+      # they cannot do is step over it without saying so, which is what makes
+      # the override worth recording on the event.
+      #
+      # A suspended seller being reinstated is not re-measured: they were
+      # admitted once, and lifting a suspension undoes that decision rather
+      # than making it again.
+      #
+      # A rejected seller is the opposite case, even though both are
+      # "reinstatements" in the loose sense: Sellers::Reject refuses an
+      # approved seller outright, so every rejected seller is an applicant
+      # who was turned away before admission. Approving one is the original
+      # decision, and skipping the checklist for it would admit a seller with
+      # unmet requirements while the event recorded no override.
+      def ensure_requirements_met
+        @unmet_requirements = []
+        return if seller.suspended?
+
+        requirements = Spree::Sellers::Requirements.new(seller)
+        @unmet_requirements = requirements.blocking
+        return if unmet_requirements.empty?
+        return if override_requirements
+
+        requirements.record_blocking(errors)
+        failure(seller, errors)
+      end
+
+      # @return [Array<String>]
+      def unmet_requirement_names
+        Array(unmet_requirements).map(&:name)
+      end
+
+      # Lifting a suspension clears the holiday with it: a seller coming back
+      # is coming back to sell, and leaving them invisible would look like the
+      # approval had not worked.
+      def mark_approved
+        seller.update!(status: 'approved', holiday_mode_until: nil)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+module Spree
+  module Sellers
+    # Creates a seller and gives them somewhere to keep stock.
+    #
+    # A workflow rather than plain CRUD because a seller is not usable without
+    # a stock location: it is where their inventory lives and where customer
+    # returns are sent, so provisioning it belongs to creating them rather than
+    # being a step an operator can forget. The legacy multi-vendor gem reached
+    # the same conclusion but did it in an `after_create` callback with a
+    # fallback inside the reader, which put a write inside a read.
+    class Create < Spree::Workflow
+      hooks :validate, :after_create
+
+      # @return [Spree::Seller]
+      attr_reader :seller
+
+      # @return [Spree::StockLocation] provisioned for the new seller
+      attr_reader :stock_location
+
+      # @param store [Spree::Store]
+      # @param attributes [Hash] seller attributes
+      def perform(store:, attributes: {})
+        super
+
+        step :build_seller
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :save_seller
+          step :provision_stock_location
+        end
+
+        # No explicit `seller.created` here: `publishes_lifecycle_events` on the
+        # model already emits it on commit, and publishing again would run every
+        # subscriber and webhook twice per seller. The sibling workflows publish
+        # names the concern does not emit, which is why they do it themselves.
+        run_hooks :after_create
+        success(seller.reload)
+      end
+
+      private
+
+      def build_seller
+        @seller = store.sellers.new(attributes)
+        @seller.status ||= Spree::Seller.default_status
+      end
+
+      def save_seller
+        failure(seller, seller.errors) unless seller.save
+      end
+
+      # Named after the seller, since that is what an operator scanning every
+      # location in the marketplace needs to see. `default` is per-owner, so
+      # this is the default among *this seller's* locations and leaves the
+      # operator's own alone.
+      def provision_stock_location
+        @stock_location = seller.stock_locations.new(
+          store: seller.store,
+          name: seller.name,
+          default: true,
+          active: true,
+          country_code: seller.store.default_country_code
+        )
+        # A new seller has no catalog, so there is nothing to propagate — the
+        # levels arrive with their products.
+        @stock_location.propagate_all_variants = false
+
+        failure(@stock_location, @stock_location.errors) unless @stock_location.save
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+module Spree
+  module Sellers
+    # Invites someone to run a seller: sends them an invitation to the seller's
+    # own team and marks the seller as awaiting their acceptance.
+    #
+    # Accepting the invitation is what creates the membership — that happens on
+    # the existing invitation rail, not here, so this workflow only opens the
+    # door.
+    class Invite < Spree::Workflow
+      hooks :validate, :after_invite
+
+      # The invitation sent, so hook handlers can reach it.
+      attr_reader :invitation
+
+      # @param seller [Spree::Seller]
+      # @param email [String] who to invite
+      # @param inviter [Object] the staff member inviting them
+      # @param role [Spree::Role, nil] the seller role they accept into;
+      #   defaults to the seller's own admin role
+      def perform(seller:, email:, inviter:, role: nil)
+        super
+
+        step :ensure_invitable
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :send_invitation
+          step :mark_invited
+        end
+
+        run_hooks :after_invite
+        seller.publish_event('seller.invited')
+        success(seller.reload)
+      end
+
+      private
+
+      # Re-inviting is deliberate: an invitation expires, or the first one goes
+      # to the wrong address. What cannot be re-opened is a seller already
+      # trading or already turned away.
+      def ensure_invitable
+        return if seller.pending? || seller.invited? || seller.canceled?
+
+        failure(seller, :not_invitable)
+      end
+
+      # The invitation validates that the role is one this seller owns, so a
+      # role naming somewhere else comes back as a 422 rather than access
+      # granted elsewhere.
+      def send_invitation
+        @invitation = seller.invitations.new(email: email, role: role, inviter: inviter)
+
+        failure(@invitation, @invitation.errors) unless @invitation.save
+      end
+
+      def mark_invited
+        seller.update!(status: 'invited')
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+module Spree
+  module Sellers
+    # Turns down an applicant. Distinct from suspension: this one never traded,
+    # so what they are told is that they were not admitted rather than that
+    # they have been stopped.
+    class Reject < Spree::Workflow
+      hooks :validate, :after_reject
+
+      # @param seller [Spree::Seller]
+      # @param reason [String, nil] why, for the applicant and the audit trail
+      # @param rejected_by [Object, nil] the staff member rejecting
+      def perform(seller:, reason: nil, rejected_by: nil)
+        super
+
+        step :ensure_rejectable
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :mark_rejected
+        end
+
+        run_hooks :after_reject
+        seller.publish_event('seller.rejected')
+        success(seller.reload)
+      end
+
+      private
+
+      # Only an applicant can be turned down. A trading seller is suspended,
+      # which is reversible and says something different.
+      def ensure_rejectable
+        failure(seller, :already_rejected) if seller.rejected?
+        failure(seller, :cannot_reject_approved) if seller.approved?
+
+        return if seller.pending? || seller.invited? || seller.onboarding? || seller.ready_for_review?
+
+        failure(seller, :not_rejectable)
+      end
+
+      def mark_rejected
+        seller.update!(status: 'rejected')
+        record_reason
+      end
+
+      def record_reason
+        return if reason.blank?
+
+        seller.update!(metadata: seller.metadata.to_h.merge('rejection_reason' => reason))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+module Spree
+  module Sellers
+    # Sends a seller back to onboarding: the operator looked at them and
+    # something has to be redone.
+    #
+    # Distinct from Reject, which turns a seller away. This one expects them
+    # back, which is why it carries a note — a seller told only "not yet" has
+    # nothing to act on.
+    class ReopenOnboarding < Spree::Workflow
+      hooks :validate, :after_reopen
+
+      # @param seller [Spree::Seller]
+      # @param note [String, nil] what the seller has to fix
+      # @param reopened_by [Object, nil] the staff member sending it back
+      def perform(seller:, note: nil, reopened_by: nil)
+        super
+
+        step :ensure_reopenable
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :mark_onboarding
+        end
+
+        run_hooks :after_reopen
+        seller.publish_event('seller.onboarding_reopened')
+        success(seller.reload)
+      end
+
+      private
+
+      # Only a seller waiting on the operator can be sent back. One already
+      # approved is suspended instead, which says the right thing to the
+      # shopper as well as to the seller.
+      def ensure_reopenable
+        return if seller.ready_for_review?
+
+        failure(seller, :not_reopenable)
+      end
+
+      def mark_onboarding
+        seller.update!(status: 'onboarding')
+        record_note
+      end
+
+      # A note about one decision, replaced by the next one — metadata rather
+      # than a column, like the suspension reason beside it.
+      def record_note
+        return if note.blank?
+
+        seller.update!(metadata: seller.metadata.to_h.merge('onboarding_reopened_note' => note))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+module Spree
+  module Sellers
+    # Opens onboarding: the seller now has someone who can sign in and work
+    # through the marketplace's requirements.
+    #
+    # Run when an invitation to a seller's team is accepted, which is the
+    # moment the seller stops being a record the operator created and starts
+    # being a business doing something about it.
+    class StartOnboarding < Spree::Workflow
+      hooks :validate, :after_start_onboarding
+
+      # @param seller [Spree::Seller]
+      def perform(seller:)
+        super
+
+        step :ensure_startable
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :mark_onboarding
+        end
+
+        run_hooks :after_start_onboarding
+        seller.publish_event('seller.onboarding_started')
+        success(seller.reload)
+      end
+
+      private
+
+      # A seller already working through their checklist is left alone rather
+      # than refused: a second teammate accepting an invitation must not read
+      # as an error, and it must not reset anything either.
+      def ensure_startable
+        halt!(seller) if seller.onboarding?
+
+        return if seller.pending? || seller.invited?
+
+        failure(seller, :not_startable)
+      end
+
+      def mark_onboarding
+        seller.update!(status: 'onboarding')
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+module Spree
+  module Sellers
+    # The seller says they are ready. One of the two places the onboarding
+    # checklist is enforced (docs/plans/6.0-seller-onboarding-requirements.md);
+    # the other is Spree::Sellers::Approve.
+    #
+    # A marketplace that trusts its checklist can let this approve outright —
+    # the `auto_approve_sellers` store preference — which is what turns the
+    # checklist from a queue for the operator into the admission decision.
+    class SubmitForReview < Spree::Workflow
+      hooks :validate, :after_submit
+
+      # Requirement statuses that stood in the way, for hook handlers and
+      # for the caller rendering the refusal.
+      # @return [Array<Spree::SellerRequirementStatus>]
+      attr_reader :blocking_requirements
+
+      # @param seller [Spree::Seller]
+      # @param submitted_by [Object, nil] the seller's own staff member
+      def perform(seller:, submitted_by: nil)
+        super
+
+        step :ensure_submittable
+        step :ensure_requirements_met
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :mark_ready_for_review
+        end
+
+        run_hooks :after_submit
+        seller.publish_event('seller.submitted_for_review')
+
+        # Approval is its own workflow with its own mail and hooks, so
+        # automatic admission runs it rather than reproducing it — and does so
+        # outside this workflow's transaction, since approving is not part of
+        # submitting and must not roll it back.
+        return step :auto_approve if auto_approve?
+
+        success(seller.reload)
+      end
+
+      private
+
+      def ensure_submittable
+        failure(seller, :already_submitted) if seller.ready_for_review?
+        failure(seller, :already_approved) if seller.approved?
+
+        return if seller.onboarding?
+
+        failure(seller, :not_submittable)
+      end
+
+      def ensure_requirements_met
+        requirements = Spree::Sellers::Requirements.new(seller)
+        @blocking_requirements = requirements.blocking
+        return if blocking_requirements.empty?
+
+        requirements.record_blocking(errors)
+        failure(seller, errors)
+      end
+
+      def mark_ready_for_review
+        seller.update!(status: 'ready_for_review')
+      end
+
+      def auto_approve?
+        seller.store&.preferred_auto_approve_sellers.present?
+      end
+
+      def auto_approve
+        Spree::Sellers::Approve.call(seller: seller.reload, approver: nil)
+      end
+    end
+  end
+end