spree_core 5.6.1 → 6.0.0.beta2

data/app/workflows/spree/seller_payouts/sweep.rb

@@ -0,0 +1,192 @@
+module Spree
+  module SellerPayouts
+    # Settles what a seller has accrued in one currency.
+    #
+    # The second level of the ledger. It gathers every earning that has been
+    # confirmed and not yet settled, batches them into one payout, and asks the
+    # provider to send it. A settlement therefore names exactly which orders it
+    # covered, which is what a seller needs to reconcile a deposit.
+    #
+    # **The stamp is the claim.** Creating the payout and marking its transfers
+    # with its id happen in one transaction, and a sweep only ever looks at
+    # transfers with no payout — so a batch can never be swept twice, and a
+    # re-run after a crash finds nothing left to take.
+    #
+    # A refused send releases them again, because a payout is created here and
+    # nowhere else: transfers left stamped to a failed one would be invisible
+    # to every later sweep while the balance still reported them owed. The
+    # next sweep is the retry.
+    #
+    # A send whose outcome nobody knows is the exception, and keeps them. The
+    # money may already have gone, so releasing them is how the same earnings
+    # get sent twice — they wait with the settlement until it resolves.
+    class Sweep < Spree::Workflow
+      hooks :validate, :after_sweep
+
+      attr_reader :payout
+
+      # @param seller [Spree::Seller]
+      # @param currency [String] settled per currency, since nothing is ever
+      #   converted
+      # @return [Spree::ServiceModule::Result] value is the payout, or the
+      #   seller when there was nothing to settle
+      def perform(seller:, currency:)
+        super
+
+        step :ensure_payable
+        external_step :resolve_available_payout
+        step :collect_transfers
+        step :ensure_worth_sending
+        run_hooks :validate
+
+        step :claim_transfers
+        external_step :execute_payout
+        run_hooks :after_sweep
+
+        success(payout)
+      end
+
+      private
+
+      # A provider that moves money cannot pay a seller it has no account for.
+      # The earnings simply stay unsettled until one exists — they are not
+      # lost, and the next sweep will find them.
+      def ensure_payable
+        halt!(seller) unless seller.payouts_enabled?
+      end
+
+      # What a seller has earned and what their account can send are different
+      # figures — money credited on fulfilment is only payable once the
+      # customer's payment settles. Asked before anything is claimed, so a
+      # provider that refuses to answer costs a period rather than a payout.
+      def resolve_available_payout
+        @available = provider.available_payout(seller, currency)
+      rescue StandardError => e
+        # A refusal rather than a halt: halting reads as "nothing to settle",
+        # which is what an operator pressing Settle would be told while the
+        # provider was simply unreachable.
+        Rails.error.report(e, handled: true, context: { seller_id: seller.id, currency: currency }, source: 'spree.core')
+        failure(seller, e.message)
+      end
+
+      # Selected and summed on what the seller's account holds, not on what the
+      # sale was priced in: a cross-border account settles in its own currency,
+      # and that is the only figure a payout can move.
+      def collect_transfers
+        rows = seller.seller_transfers.unsettled.settling_in(currency).order(:created_at, :id).to_a
+        halt!(seller) if rows.empty?
+
+        @transfers = payable_within(rows)
+        halt!(seller) if @transfers.empty?
+
+        @amount = @transfers.sum(&:settlement_amount)
+      end
+
+      # Every reversal counts, whatever is available: it is money already taken
+      # back, and leaving one out would settle earnings it cancels. Earnings
+      # then join oldest first until the next one would not fit, so a payout
+      # stays a contiguous period a seller can reconcile rather than a
+      # selection made to hit a number.
+      def payable_within(rows)
+        return rows if @available.nil?
+
+        reversals, earnings = rows.partition { |row| row.settlement_amount.negative? }
+        running = reversals.sum(&:settlement_amount)
+
+        reversals + earnings.take_while do |earning|
+          fits = (running + earning.settlement_amount) <= @available
+          running += earning.settlement_amount if fits
+          fits
+        end
+      end
+
+      # Below the threshold the balance carries to the next period rather than
+      # being sent — a payout costs the marketplace a fee either way, and a
+      # seller would rather have one meaningful deposit than five trivial ones.
+      # A balance that has gone negative (reversals outrunning earnings) is
+      # likewise left to be absorbed by what comes next.
+      def ensure_worth_sending
+        halt!(seller) if @amount <= 0
+        halt!(seller) if @amount < seller.resolved_minimum_payout_amount
+      end
+
+      def claim_transfers
+        ApplicationRecord.transaction do
+          @payout = Spree::SellerPayout.create!(
+            store: seller.store,
+            seller: seller,
+            amount: @amount,
+            currency: currency,
+            provider: provider_name,
+            status: 'pending',
+            period_start: @transfers.map(&:created_at).min,
+            period_end: Time.current
+          )
+
+          # The claim. A concurrent sweep can only take rows this one has not,
+          # so the same earning is never in two payouts.
+          claimed = Spree::SellerTransfer.where(id: @transfers.map(&:id), payout_id: nil).
+                    update_all(payout_id: @payout.id, updated_at: Time.current)
+
+          # Another sweep beat this one to some of them; the amount would be a
+          # lie, so this payout takes only what it actually claimed.
+          restate_amount if claimed != @transfers.size
+        end
+
+        # The threshold was checked against what this sweep hoped to claim. If
+        # a concurrent one took some of it the figure has changed, and a
+        # restated payout can even come to nothing — which must not be sent: a
+        # provider asked to move zero either errors or moves nothing, and
+        # either way it is not a settlement.
+        # Re-checked, not just tested against zero: a concurrent sweep taking
+        # some of the rows changes the figure the threshold was weighed
+        # against, and a restated payout can fall below a minimum the original
+        # amount cleared.
+        discard_empty_payout if @payout.amount <= 0 || @payout.amount < seller.resolved_minimum_payout_amount
+      end
+
+      # Both the figure and the period: a settlement whose window covers
+      # earnings that ended up in a different payout answers the
+      # reconciliation question wrongly, which is the only question the
+      # period fields exist for.
+      def restate_amount
+        @payout.update!(
+          amount: @payout.transfers_total,
+          period_start: @payout.transfers.minimum(:created_at) || @payout.period_start
+        )
+      end
+
+      # Nothing was claimed, so there is nothing to release and nothing to
+      # record. The earnings this sweep meant to take are already in the payout
+      # that won them.
+      def discard_empty_payout
+        @payout.release_transfers
+        @payout.destroy!
+        halt!(seller)
+      end
+
+      def execute_payout
+        provider.pay!(payout)
+      rescue Spree::Core::AmbiguousGatewayError => e
+        # The provider could not say whether the money moved. Its earnings stay
+        # claimed so no later sweep can send them again, and the row waits for
+        # a person or a webhook to say which way it went.
+        payout.unresolve!
+        Rails.error.report(e, handled: true, context: { seller_payout_id: payout.id }, source: 'spree.core')
+        failure(payout, e.message)
+      rescue StandardError => e
+        payout.fail!
+        Rails.error.report(e, handled: true, context: { seller_payout_id: payout.id }, source: 'spree.core')
+        failure(payout, e.message)
+      end
+
+      def provider
+        @provider ||= seller.store.payout_provider_instance
+      end
+
+      def provider_name
+        provider.class.provider_key
+      end
+    end
+  end
+end

data/app/workflows/spree/seller_requirement_submissions/accept.rb

@@ -0,0 +1,40 @@
+module Spree
+  module SellerRequirementSubmissions
+    # The operator confirms what a seller submitted. The requirement is met
+    # from here on, and the row is the record of who decided that.
+    class Accept < Spree::Workflow
+      include Reviewable
+
+      hooks :validate, :after_accept
+
+      # @param submission [Spree::SellerRequirementSubmission]
+      # @param reviewed_by [Object, nil] the staff member accepting
+      # @param review_note [String, nil]
+      def perform(submission:, reviewed_by: nil, review_note: nil)
+        super
+
+        step :ensure_acceptable
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :mark_accepted
+        end
+
+        run_hooks :after_accept
+        submission.publish_event('seller_requirement_submission.accepted')
+        success(submission.reload)
+      end
+
+      private
+
+      def ensure_acceptable
+        failure(submission, :already_accepted) if submission.accepted?
+        failure(submission, :already_waived) if submission.waived?
+      end
+
+      def mark_accepted
+        mark_reviewed('accepted')
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+module Spree
+  module SellerRequirementSubmissions
+    # A seller records having done something the marketplace asked of them —
+    # ticking an attestation, uploading a document, saying a manual check is
+    # ready to run.
+    #
+    # Whether that settles the requirement or only queues it depends on the
+    # kind: an attestation is the seller's word and is taken at face value, a
+    # document or a manual check waits for someone to look at it.
+    #
+    # == Scanning an uploaded document
+    #
+    # A marketplace that runs a virus scanner hooks `after_create` and moves
+    # the submission to `rejected` on a bad verdict. It must be `after_create`
+    # rather than `validate`: at validate time the blob is built but not yet
+    # uploaded, so there is nothing in storage to read. By `after_create` the
+    # bytes are there and the submission is `pending`, a state no operator
+    # acts on. A slow scanner does the same from a background job.
+    #
+    # Core ships no scanner — which one to run is a deployment decision. What
+    # core does guarantee is that a file's type is decided by its bytes rather
+    # than the uploader's header, and that its size is bounded (see
+    # Spree::SellerRequirementSubmission).
+    class Create < Spree::Workflow
+      hooks :validate, :after_create
+
+      # @return [Spree::SellerRequirementSubmission]
+      attr_reader :submission
+
+      # @param seller [Spree::Seller]
+      # @param requirement [Spree::SellerRequirement]
+      # @param note [String, nil] what the seller wants the reviewer to know
+      # @param reference [String, nil] an identifier the kind understands
+      # @param file [Object, nil] an uploaded file or signed blob id
+      # @param submitted_by [Object, nil] the seller's own staff member
+      def perform(seller:, requirement:, note: nil, reference: nil, file: nil, submitted_by: nil)
+        super
+
+        step :ensure_submittable
+        step :build_submission
+        step :ensure_file_acceptable
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :save_submission
+        end
+
+        run_hooks :after_create
+        submission.publish_event('seller_requirement_submission.created')
+        success(submission)
+      end
+
+      private
+
+      # A computed requirement is answered by the seller's own data, so a
+      # submission against one would be a second answer that disagrees with
+      # it the moment the data changes.
+      def ensure_submittable
+        failure(requirement, :submissions_not_accepted) unless requirement.class.accepts_submissions?
+        failure(requirement, :requirement_inactive) unless requirement.active?
+      end
+
+      def build_submission
+        @submission = seller.requirement_submissions.new(
+          requirement: requirement,
+          status: initial_status,
+          note: note,
+          reference: reference,
+          submitted_by: submitted_by
+        )
+        submission.file.attach(file) if file.present?
+      end
+
+      # A document with nothing attached records a check nobody can repeat, so
+      # it is refused here rather than reaching a reviewer empty.
+      #
+      # Only that a file is here at all. What the file *is* — its real type
+      # and its size — is the model's business, where the validation reads the
+      # bytes rather than the uploader's header; repeating a weaker version of
+      # that check here is how the two drift apart.
+      def ensure_file_acceptable
+        return unless requirement.class.requires_file?
+        return if submission.file.attached?
+
+        errors.add(:file, :blank, message: Spree.t('seller_requirements.file_required',
+                                                   default: 'A file is required for this requirement'))
+        failure(submission, errors)
+      end
+
+      # Waiting on a reviewer, or taken at the seller's word.
+      def initial_status
+        requirement.class.reviewed_by_operator? ? 'pending' : 'accepted'
+      end
+
+      def save_submission
+        failure(submission, submission.errors) unless submission.save
+
+        # Accepting at creation means nobody reviewed it — but the record
+        # should still say when it was settled.
+        submission.update!(reviewed_at: Time.current) if submission.accepted?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+module Spree
+  module SellerRequirementSubmissions
+    # The operator sends something back. The requirement returns to unmet and
+    # the seller is told why — a rejection with no reason leaves them
+    # resubmitting the same thing.
+    class Reject < Spree::Workflow
+      include Reviewable
+
+      hooks :validate, :after_reject
+
+      # @param submission [Spree::SellerRequirementSubmission]
+      # @param reviewed_by [Object, nil] the staff member rejecting
+      # @param review_note [String, nil] what was wrong with it
+      def perform(submission:, reviewed_by: nil, review_note: nil)
+        super
+
+        step :ensure_rejectable
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :mark_rejected
+        end
+
+        run_hooks :after_reject
+        submission.publish_event('seller_requirement_submission.rejected')
+        success(submission.reload)
+      end
+
+      private
+
+      # A waiver is the operator's own exception, and rejecting it in place
+      # would overwrite who granted it and when. Withdrawing one is its own
+      # act — the seller submits again, or the requirement changes — so this
+      # refuses rather than quietly rewriting the record.
+      def ensure_rejectable
+        failure(submission, :already_rejected) if submission.rejected?
+        failure(submission, :already_waived) if submission.waived?
+      end
+
+      def mark_rejected
+        mark_reviewed('rejected')
+      end
+    end
+  end
+end

data/app/workflows/spree/seller_requirement_submissions/reviewable.rb

@@ -0,0 +1,19 @@
+module Spree
+  module SellerRequirementSubmissions
+    # Shared by the two operator decisions on a submission. Accepting and
+    # rejecting differ in what they mean and what they announce, but both
+    # record the same thing: who decided, when, and what they said.
+    module Reviewable
+      private
+
+      def mark_reviewed(status)
+        submission.update!(
+          status: status,
+          reviewed_by: reviewed_by,
+          reviewed_at: Time.current,
+          review_note: review_note.presence || submission.review_note
+        )
+      end
+    end
+  end
+end

data/app/workflows/spree/seller_requirement_submissions/waive.rb

@@ -0,0 +1,64 @@
+module Spree
+  module SellerRequirementSubmissions
+    # The operator excuses one seller from something the marketplace asks of
+    # everyone — a seller who satisfied it off the marketplace, or one whose
+    # circumstances the requirement was never written for.
+    #
+    # A waiver reads as met without pretending the seller did it, which is
+    # the distinction that matters when someone reads the record later.
+    class Waive < Spree::Workflow
+      hooks :validate, :after_waive
+
+      # @return [Spree::SellerRequirementSubmission]
+      attr_reader :submission
+
+      # @param seller [Spree::Seller]
+      # @param requirement [Spree::SellerRequirement]
+      # @param reviewed_by [Object, nil] the staff member waiving it
+      # @param review_note [String, nil] why
+      def perform(seller:, requirement:, reviewed_by: nil, review_note: nil)
+        super
+
+        step :ensure_waivable
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :record_waiver
+        end
+
+        run_hooks :after_waive
+        submission.publish_event('seller_requirement_submission.waived')
+        success(submission)
+      end
+
+      private
+
+      # Any active requirement can be waived, computed ones included: excusing
+      # a seller from the terms or from a minimum catalog is exactly what a
+      # waiver is for, and the base class honours it over the kind's own
+      # reading. What cannot be waived is a requirement the store has switched
+      # off — it is already asking nothing, so a waiver would only add a row
+      # that means nothing (`Create` refuses inactive ones for the same
+      # reason).
+      def ensure_waivable
+        failure(requirement, :requirement_store_mismatch) if requirement.store_id != seller.store_id
+        failure(requirement, :requirement_inactive) unless requirement.active?
+      end
+
+      # A waiver is its own submission rather than an edit of whatever came
+      # before: what the seller sent and what the operator decided are two
+      # different acts, and the earlier one stays readable.
+      def record_waiver
+        @submission = seller.requirement_submissions.new(
+          requirement: requirement,
+          status: 'waived',
+          reviewed_by: reviewed_by,
+          reviewed_at: Time.current,
+          review_note: review_note
+        )
+
+        failure(submission, submission.errors) unless submission.save
+      end
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+module Spree
+  module SellerTransfers
+    # Credits a seller for one order whose goods have gone out.
+    #
+    # The first level of the ledger. What the seller earned is their sale less
+    # what the marketplace charged them, and it is **payment-source-agnostic**:
+    # store credit and gift cards are how the customer paid, which is the
+    # platform's funding concern. The seller is owed their cut either way.
+    #
+    # Idempotent by the unique index on `(order_id) WHERE kind = 'earning'` —
+    # the fulfillment event can fire more than once (it is dual-emitted under a
+    # legacy name for one release), and a re-fired event must find the earning
+    # that exists rather than credit the seller twice.
+    class Create < Spree::Workflow
+      hooks :validate, :after_create
+
+      attr_reader :seller_transfer
+
+      # @param order [Spree::Order] the seller's order, fully fulfilled
+      # @return [Spree::ServiceModule::Result] value is the Spree::SellerTransfer,
+      #   or the order when there is nothing to credit
+      def perform(order:)
+        super
+
+        step :ensure_creditable
+        step :replay_existing
+        run_hooks :validate
+
+        step :build_transfer
+        external_step :execute_transfer
+        run_hooks :after_create
+
+        success(seller_transfer)
+      end
+
+      private
+
+      # A first-party order earns nobody anything — the money is already the
+      # operator's. Nor does an order whose goods have not all gone out, or one
+      # with no goods at all: `fully_fulfilled?` answers true for an order with
+      # no fulfillments, since none of nothing is outstanding.
+      def ensure_creditable
+        halt!(order) if order.seller_id.blank?
+        halt!(order) if order.fulfillments.empty?
+        halt!(order) unless order.fully_fulfilled?
+      end
+
+      def replay_existing
+        existing = Spree::SellerTransfer.earnings.find_by(order_id: order.id)
+        halt!(existing) if existing
+      end
+
+      def build_transfer
+        @seller_transfer = Spree::SellerTransfer.create!(
+          store: order.seller.store,
+          seller: order.seller,
+          order: order,
+          amount: earned_amount,
+          currency: order.currency,
+          kind: 'earning',
+          provider: provider_name,
+          status: 'pending'
+        )
+      rescue ActiveRecord::RecordNotUnique
+        # Another delivery of the same event got there first; the unique index
+        # is what makes that safe, and its winner is the answer.
+        halt!(Spree::SellerTransfer.earnings.find_by!(order_id: order.id))
+      end
+
+      # Outside any transaction: a provider that moves money makes a network
+      # call here, and a row lock must not be held across it.
+      def execute_transfer
+        # A seller the provider cannot pay yet keeps the earning as a pending
+        # row. Verification can take days, and an account can lose the
+        # capability again — either way the money is owed, and
+        # `SellerTransfers::ExecutePendingJob` sends it once they are payable,
+        # or on its next scheduled run if that moment went unseen.
+        return unless order.seller.payouts_enabled?
+
+        provider.transfer!(seller_transfer)
+      rescue Spree::Core::AmbiguousGatewayError => e
+        # Nobody knows whether the money moved, so nothing may send it again:
+        # the retry job takes `pending` and `processing` rows, and an
+        # idempotency key only covers a retry while the provider keeps its
+        # record. Parked where no automatic attempt reaches it, for an
+        # operator to resolve against the provider's own books.
+        seller_transfer.update!(status: 'unresolved')
+        Rails.error.report(e, handled: true, context: { seller_transfer_id: seller_transfer.id },
+                              source: 'spree.core')
+        failure(seller_transfer, e.message)
+      rescue StandardError => e
+        # A definite refusal — the money did not move, so the earning is still
+        # owed and the retry job picks it up.
+        seller_transfer.update!(status: 'processing')
+        Rails.error.report(e, handled: true, context: { seller_transfer_id: seller_transfer.id },
+                              source: 'spree.core')
+        failure(seller_transfer, e.message)
+      end
+
+      # What the seller earned: their sale, less the marketplace's commission
+      # including the VAT charged on it — the platform invoices the seller for
+      # both, and the seller reclaims that VAT as input tax.
+      #
+      # A platform-remitted seller does not receive the consumer tax either,
+      # since the marketplace files it (Decision 9).
+      def earned_amount
+        base = order.total.to_d
+        # Both halves of the consumer tax, because a market decides which one
+        # it uses: added on top where prices are quoted net, folded into the
+        # price where they are quoted gross. A marketplace that remits the tax
+        # and only subtracts the added half pays a tax-inclusive seller the VAT
+        # as well as paying it to the tax authority.
+        base -= order.tax_total.to_d if order.seller.tax_remittance == 'platform'
+
+        # Summed from the rows rather than read off order.commission_total:
+        # the column is a reporting figure refreshed when commission is
+        # charged, and money leaving the platform is settled against the
+        # settlement records themselves.
+        [base - order.commission_lines.sum(:total).to_d, 0].max
+      end
+
+      def provider
+        @provider ||= order.store.payout_provider_instance
+      end
+
+      def provider_name
+        provider.class.provider_key
+      end
+    end
+  end
+end