spree_core 5.6.1 → 6.0.0.beta1

data/app/models/spree/seller_requirements/complete_profile.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Spree
+  module SellerRequirements
+    # The seller's public profile is filled in. A name is always required —
+    # the model will not save without one — so the preferences decide how
+    # much more the marketplace wants before it will show the seller to
+    # shoppers.
+    class CompleteProfile < Spree::SellerRequirement
+      preference :require_about, :boolean, default: true
+      preference :require_logo, :boolean, default: true
+      preference :require_cover_photo, :boolean, default: false
+      preference :require_contact_email, :boolean, default: true
+
+      def met_by_seller?(seller)
+        return false if seller.name.blank?
+        return false if preferred_require_about && seller.about.blank?
+        return false if preferred_require_logo && !seller.logo.attached?
+        return false if preferred_require_cover_photo && !seller.cover_photo.attached?
+        return false if preferred_require_contact_email && seller.contact_email.blank?
+
+        true
+      end
+    end
+  end
+end

data/app/models/spree/seller_requirements/delivery_method.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Spree
+  module SellerRequirements
+    # The seller has at least one way to ship. Without one their goods quote
+    # no rates at checkout, so the listing looks live and cannot be bought.
+    #
+    # Satisfied either way a marketplace can be run
+    # (docs/plans/6.0-multi-vendor-marketplace.md, Decision 13): the seller
+    # created a method of their own, or the operator ships for everyone and
+    # has shared at least one of theirs.
+    class DeliveryMethod < Spree::SellerRequirement
+      def met_by_seller?(seller)
+        return true if seller.delivery_methods.storefront_visible.exists?
+
+        store.delivery_methods.shared_with_sellers.storefront_visible.exists?
+      end
+    end
+  end
+end

data/app/models/spree/seller_requirements/document.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Spree
+  module SellerRequirements
+    # A file the marketplace collects and checks — a business registration,
+    # an identity document, proof of insurance. One row per document the
+    # operator wants, each carrying its own instructions.
+    #
+    # The file lives on the submission rather than the seller: what matters
+    # is which document was reviewed and by whom, and a seller may be asked
+    # for a replacement without the previous one disappearing.
+    class Document < Spree::SellerRequirement
+      # What a business registration, an insurance certificate or an identity
+      # document actually arrives as: a PDF, a photo or scan of one, or an
+      # office file. Fixed rather than configurable — the answer is the same
+      # for every marketplace, and asking an operator to type MIME types is a
+      # way to get `image/jpg` typed and nothing accepted.
+      #
+      # Reopen this constant to take something else.
+      ACCEPTED_CONTENT_TYPES = %w[
+        application/pdf
+        image/jpeg
+        image/png
+        image/heic
+        image/webp
+        application/msword
+        application/vnd.openxmlformats-officedocument.wordprocessingml.document
+      ].freeze
+
+      def self.allow_multiple?
+        true
+      end
+
+      def self.accepts_submissions?
+        true
+      end
+
+      def self.reviewed_by_operator?
+        true
+      end
+
+      def self.requires_file?
+        true
+      end
+
+      # A document requirement is met by an accepted submission that actually
+      # carries a file — accepting an empty one would record a check nobody
+      # could repeat. (A waiver settles it without one, but that is the base
+      # class's business, not this method's.)
+      def met_by_seller?(seller)
+        submission = latest_submission(seller)
+
+        submission.present? && submission.accepted? && submission.file.attached?
+      end
+
+      # @return [Array<String>] content types a seller may upload
+      def self.accepted_content_types
+        ACCEPTED_CONTENT_TYPES
+      end
+    end
+  end
+end

data/app/models/spree/seller_requirements/minimum_products.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Spree
+  module SellerRequirements
+    # The seller has listed something. A marketplace that admits sellers with
+    # an empty catalog fills its storefront with shops that sell nothing.
+    class MinimumProducts < Spree::SellerRequirement
+      preference :minimum_count, :integer, default: 1
+
+      def met_by_seller?(seller)
+        minimum = preferred_minimum_count.to_i
+        return true if minimum <= 0
+
+        # The seller's memoized count: the operator's list already pays for
+        # it once per row, so this reads that rather than counting again.
+        seller.products_count >= minimum
+      end
+    end
+  end
+end

data/app/models/spree/seller_requirements/operator_review.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Spree
+  module SellerRequirements
+    # Something a person at the marketplace checks by hand — a tax number
+    # against a public register, a trading history elsewhere. The seller says
+    # they are ready and gives whatever reference the operator asked for; the
+    # requirement is met when someone accepts it.
+    class OperatorReview < Spree::SellerRequirement
+      def self.allow_multiple?
+        true
+      end
+
+      def self.accepts_submissions?
+        true
+      end
+
+      def self.reviewed_by_operator?
+        true
+      end
+    end
+  end
+end

data/app/models/spree/seller_requirements/package_type.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Spree
+  module SellerRequirements
+    # The seller has told the marketplace what they ship in. Without it their
+    # parcels are quoted with the marketplace's box, which is the wrong size
+    # and the wrong tare for anyone shipping from their own warehouse — a
+    # quote that is wrong rather than missing, so nothing at checkout reveals
+    # it (docs/plans/6.0-seller-package-types.md).
+    #
+    # Measurements, not merely a row: a default box with blank sides quotes
+    # the goods alone, which is the silent under-pricing the package type's
+    # own guards exist to prevent.
+    #
+    # Deliberately not satisfied by the marketplace's box, unlike the
+    # delivery-method kind beside it: a seller quoting through the operator's
+    # shared rates still packs and posts their own parcel. An operator who
+    # ships everything themselves switches this requirement off.
+    class PackageType < Spree::SellerRequirement
+      MEASUREMENTS = %i[length width height weight].freeze
+
+      # Read through the association rather than queried, so the operator's
+      # seller list costs one batched load for the whole page instead of a
+      # query per row — `ar_lazy_preload` groups it into a single
+      # `seller_id IN (...)` once the checklist renders for several sellers,
+      # which a `.exists?` per seller would defeat.
+      #
+      # The trade-off: a caller that loaded this association before the box
+      # was recorded reads the cached answer. Neither gate workflow touches
+      # it, and the evaluator is told never to trust a preload it merely
+      # happens to find, so that needs a caller going out of its way.
+      def met_by_seller?(seller)
+        box = seller.default_package_type
+        return false if box.nil?
+
+        MEASUREMENTS.all? { |measurement| box.public_send(measurement).to_d.positive? }
+      end
+    end
+  end
+end

data/app/models/spree/seller_requirements/payout_account.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Spree
+  module SellerRequirements
+    # Somewhere to send the seller their money.
+    #
+    # A checklist row like any other, rather than a card of its own bolted
+    # beside the checklist: whether a marketplace asks this before admitting a
+    # seller is the operator's decision, exactly as it is for a returns address
+    # or a business document. A marketplace paying by hand may not need it at
+    # all, which is why the kind is registered but not provisioned by default.
+    #
+    # What "done" means belongs to the provider, not here. The built-in one
+    # never refuses a seller, so this reads as complete the moment it is asked
+    # — an operator collecting bank details by email has nothing for the seller
+    # to do. A connected provider answers only once it has run its own checks,
+    # which can be days after the seller stops typing.
+    #
+    # The link itself is deliberately not `action_url`. Hosted onboarding links
+    # are short-lived and single-use, so one minted while rendering a checklist
+    # may be dead before the seller clicks it — the panel asks for a fresh one
+    # at the moment of clicking, through the seller API.
+    class PayoutAccount < Spree::SellerRequirement
+      # Asked of the provider, since only it knows for certain — except on a
+      # listing, which reads the stamp a webhook last wrote. Otherwise a page
+      # of sellers makes one call to the payment provider per row, and the
+      # operator's list is as slow as their network.
+      def met_by_seller?(seller)
+        return seller.payouts_enabled? if prefer_cached
+
+        provider_for(seller).onboarded?(seller)
+      end
+
+      # Which of the three is true: go and finish, wait, or you have been
+      # refused. Each wants different words, and only the provider knows — so
+      # a listing, which is not asking, says nothing rather than guessing from
+      # the stamp.
+      def blocker(seller)
+        return nil if prefer_cached
+
+        provider = provider_for(seller)
+        state = provider.onboarding_state(seller)
+        return nil if state.nil?
+
+        { state: state.to_s, message: provider.onboarding_message(seller) }
+      end
+
+      private
+
+      def provider_for(seller)
+        (seller.store || store).payout_provider_instance
+      end
+    end
+  end
+end

data/app/models/spree/seller_requirements/policy.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Spree
+  module SellerRequirements
+    # The seller has published one named legal document — a returns policy, a
+    # shipping policy, whatever this marketplace asks for.
+    #
+    # One row per document rather than a list on a single row: a marketplace
+    # asking for two policies is asking two things, and a seller who has
+    # written one of them should see that line go green rather than a single
+    # line that stays blocked. It also means the operator names the document
+    # in the row's own `name` — which `allow_multiple?` already requires — so
+    # there is no second vocabulary to keep in step with it.
+    #
+    # The seller's policy matches on that name, case- and whitespace-
+    # insensitively, and must actually have something written in it.
+    class Policy < Spree::SellerRequirement
+      # The row's name IS the document required, so a marketplace adds this
+      # kind once per policy it asks for.
+      def self.allow_multiple?
+        true
+      end
+
+      def met_by_seller?(seller)
+        required = required_policy_name
+        return true if required.blank?
+
+        seller.policies.any? do |policy|
+          policy.name.to_s.strip.casecmp?(required) && policy.with_body?
+        end
+      end
+
+      # The document this row asks for: the operator's own wording, which the
+      # seller panel pre-fills when creating the policy so the two match by
+      # construction.
+      #
+      # @return [String]
+      def required_policy_name
+        display_name.to_s.strip
+      end
+    end
+  end
+end

data/app/models/spree/seller_requirements/required_custom_fields.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Spree
+  module SellerRequirements
+    # The seller has filled in the custom fields the marketplace asks for — a
+    # VAT number, a company registration number, whatever this marketplace
+    # needs. The operator defines the fields once as custom field definitions
+    # on Spree::Seller and picks them here.
+    #
+    # The fields are joined rows, not keys in preferences: a definition that
+    # is renamed keeps its id, and one that is deleted takes its row with it.
+    # A stored `namespace.key` would survive both, match nothing, and count as
+    # satisfied for every seller — a compliance check failing open.
+    class RequiredCustomFields < Spree::SellerRequirement
+      has_many :seller_requirement_custom_fields, class_name: 'Spree::SellerRequirementCustomField',
+                                                  foreign_key: :seller_requirement_id,
+                                                  dependent: :destroy, inverse_of: :seller_requirement
+      has_many :custom_field_definitions, class_name: 'Spree::CustomFieldDefinition',
+                                          through: :seller_requirement_custom_fields
+
+      def self.additional_permitted_attributes
+        [custom_field_definition_ids: []]
+      end
+
+      # The chosen definitions in prefixed form, read through the association
+      # so a deleted one drops out rather than being echoed back at a client
+      # that can no longer address it.
+      #
+      # @return [Array<String>]
+      def custom_field_definition_prefixed_ids
+        custom_field_definitions.pluck(:id).sort.map { |id| Spree::CustomFieldDefinition.prefixed_id_for(id) }
+      end
+
+      def met_by_seller?(seller)
+        # `target` covers definitions assigned but not yet saved, matching
+        # how the admin controller assigns before saving.
+        definition_ids = if new_record?
+                           seller_requirement_custom_fields.target.map(&:custom_field_definition_id)
+                         else
+                           custom_field_definitions.ids
+                         end
+        # A requirement naming no field asks nothing, and must not quietly
+        # hold every seller back while the operator finishes configuring it.
+        return true if definition_ids.empty?
+
+        # `custom_fields` eager-loads its definitions, so this is one query
+        # regardless of how many fields the operator asked for.
+        answered = seller.custom_fields.filter_map do |field|
+          field.custom_field_definition_id if field.value.present?
+        end
+
+        (definition_ids - answered).empty?
+      end
+    end
+  end
+end

data/app/models/spree/seller_requirements/returns_address.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Spree
+  module SellerRequirements
+    # Where customer returns go. Without it a shopper cannot be told where to
+    # send anything back, which is why most marketplaces ask for it up front.
+    #
+    # Satisfied by a stock location rather than a loose address: a received
+    # return has to restock somewhere the catalog can see, so the address on
+    # its own would leave the goods arriving nowhere (Decision 12).
+    class ReturnsAddress < Spree::SellerRequirement
+      def met_by_seller?(seller)
+        # Boolean rather than the bare `&.`: `satisfied?` is public API and
+        # sibling kinds all answer true or false.
+        seller.returns_location&.postable? == true
+      end
+    end
+  end
+end

data/app/models/spree/seller_transfer.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Spree
+  # What one seller earned on one order, credited when the goods went out.
+  #
+  # The first of the ledger's two levels. A seller earns on **fulfillment**,
+  # not on payment: the marketplace holds the money until the goods actually
+  # ship, and a digital order fulfils immediately so it earns immediately. The
+  # second level — {Spree::SellerPayout} — sweeps these into a bank settlement
+  # on the seller's own schedule.
+  #
+  # The amount is the seller's sale less what the marketplace charged them, and
+  # is deliberately **payment-source-agnostic**: store credit and gift cards are
+  # how the customer paid, which is the platform's funding concern, not the
+  # seller's. They are owed their cut either way.
+  #
+  # A refund writes a second row against the same order rather than editing
+  # this one, so what a seller has earned is always the sum of their transfers
+  # and the history stays readable.
+  class SellerTransfer < Spree.base_class
+    has_prefix_id :vtr
+
+    include Spree::Metadata
+    # Denormalized from the seller, which never changes store — so the copy
+    # cannot drift, and tenancy is structural rather than a subquery every
+    # consumer must remember. Always set explicitly from the seller: ledger
+    # rows are written by jobs and subscribers, where the request-scoped
+    # default store is absent or wrong.
+    include Spree::SingleStoreResource
+
+    KINDS = %w[earning refund_reversal].freeze
+
+    #
+    # Associations
+    #
+    belongs_to :seller, class_name: 'Spree::Seller'
+    belongs_to :order, class_name: 'Spree::Order'
+    # Nil until a sweep settles this transfer; the stamp is what claims it, so
+    # a re-run sweep can never batch the same earning twice.
+    belongs_to :payout, class_name: 'Spree::SellerPayout', optional: true, inverse_of: :transfers
+    belongs_to :reversed_from, class_name: 'Spree::SellerTransfer', optional: true, inverse_of: :reversals
+    # What caused a reversal. Nil on an earning, and the reversal's natural
+    # key: one clawback per refund, enforced by a unique index.
+    belongs_to :refund, class_name: 'Spree::Refund', optional: true
+    has_many :reversals, class_name: 'Spree::SellerTransfer', foreign_key: :reversed_from_id,
+                         inverse_of: :reversed_from, dependent: :nullify
+
+    #
+    # Validations
+    #
+    validates :amount, numericality: true
+    validates :currency, presence: true
+    validates :kind, presence: true, inclusion: { in: KINDS }
+    validates :provider, presence: true
+    validates :settled_amount, numericality: true
+    validates :settled_currency, presence: true
+
+    # A row settles in the currency it was sold in until a provider says
+    # otherwise — which is the truth outright for the built-in provider, since
+    # it converts nothing and moves no money. One that does convert overwrites
+    # both when it reports what actually arrived.
+    #
+    # Written rather than worked out on read, so every query that groups or
+    # sums by settlement is a plain one against a column.
+    before_validation :assume_settled_as_sold, on: :create
+
+    #
+    # Statuses. No state machine: a transfer moves through the payout
+    # workflows, which can explain a refusal, rather than through a transition
+    # graph (docs/plans/6.0-service-workflows.md).
+    #
+    include Spree::HasStatus
+    # `processing` is an attempt that failed and will be tried again;
+    # `unresolved` is one whose outcome the provider could not report, which
+    # nothing may retry until a person establishes what happened.
+    has_status :pending, :processing, :completed, :failed, :unresolved, default: :pending
+
+    #
+    # Scopes
+    #
+    scope :earnings, -> { where(kind: 'earning') }
+    scope :reversals_only, -> { where(kind: 'refund_reversal') }
+    # Safe to ask the provider about again: never sent, or refused outright.
+    # Deliberately excludes `unresolved`, where the provider could not say
+    # whether the money moved — asking again is how it moves twice.
+    scope :retryable, -> { with_status('pending', 'processing') }
+    # Earnings still owing the provider a call.
+    # Reversals are excluded for the same reason the job excludes them: their
+    # amount is negative, and sending one as a transfer pays the seller the
+    # money it exists to take back.
+    scope :awaiting_provider, -> { earnings.retryable.where(payout_id: nil) }
+    # Earned and confirmed, but not yet swept into a settlement — what the next
+    # payout will pick up.
+    scope :unsettled, -> { completed.where(payout_id: nil) }
+    # Rows whose money can be paid out in this currency. A seller's account
+    # settles in its own currency, so what a payout can move is the settled
+    # currency, not the one the sale was priced in.
+    scope :settling_in, ->(currency) { where(settled_currency: currency) }
+
+    # What these rows are worth in the currency they settle in.
+    #
+    # @return [BigDecimal]
+    def self.settlement_total
+      sum(:settled_amount)
+    end
+
+    # The currencies this seller can actually be paid in.
+    #
+    # @return [Array<String>]
+    def self.settlement_currencies
+      distinct.pluck(:settled_currency)
+    end
+
+    self.whitelisted_ransackable_attributes = %w[amount currency kind status provider reference created_at seller_id order_id payout_id]
+    self.whitelisted_ransackable_associations = %w[seller order payout refund]
+
+    extend Spree::DisplayMoney
+    money_methods :amount
+
+    # What is left of this earning to give back.
+    #
+    # Original less what reversals have already taken, floored at zero — a
+    # refund can never claw back more than the seller was credited, however
+    # many times the order is refunded.
+    #
+    # @return [BigDecimal]
+    def reversible_amount
+      return 0.to_d unless earning?
+
+      [amount - reversals.sum(:amount).abs, 0].max
+    end
+
+    # @return [Boolean]
+    def earning?
+      kind == 'earning'
+    end
+
+    # What the seller's account actually holds for this row, and in what.
+    #
+    # A sale is priced in the customer's currency; an account settles in its
+    # own, and the provider converts on the way in. Both are recorded facts —
+    # Spree holds no exchange rates and converts nothing.
+    #
+    # @return [BigDecimal]
+    def settlement_amount
+      settled_amount
+    end
+
+    # @return [String]
+    def settlement_currency
+      settled_currency
+    end
+
+    # @return [Boolean] whether the provider converted this on the way in
+    def converted?
+      settled_currency != currency
+    end
+
+    private
+
+    def assume_settled_as_sold
+      self.settled_amount = amount if settled_amount.nil?
+      self.settled_currency = currency if settled_currency.blank?
+    end
+  end
+end

data/app/models/spree/setup_tasks.rb

@@ -1,7 +1,7 @@
 module Spree
   # Registry of onboarding tasks for a given subject type. `Spree.store_setup_tasks`
   # holds the Getting Started checklist evaluated against a store; future
-  # registries (e.g. vendor onboarding) instantiate the same class against
+  # registries (e.g. seller onboarding) instantiate the same class against
   # their own subject. Defaults are registered in
   # `config/initializers/spree_store_setup_tasks.rb`; extensions and host apps
   # can add or remove tasks at boot:
@@ -15,11 +15,8 @@ module Spree
   #   end
   #
   # The registry holds domain data only — each frontend maps task keys to its
-  # own presentation: the legacy admin renders the
-  # `spree/admin/dashboard/setup_tasks/_<key>` partial titled by the
-  # `admin.store_setup_tasks.<key>` translation (both resolved across engine
-  # paths, so extensions ship theirs by convention), and the React dashboard
-  # consumes tasks as {Spree::SetupTask} records via the Admin API.
+  # own presentation: the React dashboard consumes tasks as {Spree::SetupTask}
+  # records via the Admin API.
   class SetupTasks
     class Definition
       attr_reader :key, :position