Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Let a marketplace define what it asks of its sellers

Damian Legawiec427a676eacfe
diff --git a/spree/core/app/models/spree/seller_requirement.rb b/spree/core/app/models/spree/seller_requirement.rb
new file mode 100644
index 0000000000..6e34b0e5bc
--- /dev/null
+++ b/spree/core/app/models/spree/seller_requirement.rb
@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module Spree
+ # One thing a marketplace asks of its sellers before it will let them
+ # trade — accepting the terms, giving a returns address, uploading a
+ # business registration (docs/plans/6.0-seller-onboarding-requirements.md).
+ #
+ # A row is a configured instance of a *kind* (an STI subclass registered in
+ # `Spree.seller_requirements`), so the operator composes the checklist from
+ # the dashboard and only a genuinely new kind of check needs code. Rows are
+ # configuration; what a particular seller has done about one is either
+ # computed from their own data or recorded as a
+ # {Spree::SellerRequirementSubmission}.
+ class SellerRequirement < Spree.base_class
+ include Spree::SingleStoreResource
+ include Spree::PreferenceSchema
+ include Spree::Metadata
+
+ has_prefix_id :selreq
+
+ acts_as_list scope: :store
+
+ #
+ # Associations
+ #
+ belongs_to :store, class_name: 'Spree::Store', inverse_of: :seller_requirements
+ has_many :submissions, class_name: 'Spree::SellerRequirementSubmission',
+ foreign_key: :seller_requirement_id, inverse_of: :requirement, dependent: :destroy
+
+ #
+ # Validations
+ #
+ validates :type, presence: true
+ validate :type_must_be_registered
+ # Most kinds answer one question, so a second row of the same kind would
+ # either repeat it or contradict it. The generic kinds — where the
+ # question is the operator's own words — opt out.
+ validates :type, uniqueness: { scope: [:store_id, *spree_base_uniqueness_scope] },
+ unless: -> { self.class.allow_multiple? }
+ # A kind that can appear more than once has nothing else to tell the
+ # seller apart by, so its label is the row's own.
+ validates :name, presence: true, if: -> { self.class.allow_multiple? }
+
+ registers_subclasses_via { Spree.seller_requirements }
+
+ #
+ # Scopes
+ #
+ scope :active, -> { where(active: true) }
+ scope :required, -> { where(required: true) }
+
+ # The kinds a marketplace starts with, in the order a seller meets them:
+ # agree to the terms, say who you are, tell us where to invoice and where
+ # returns go, then list something.
+ #
+ # Only the kinds that ask a question core already knows how to answer.
+ # The generic ones (an attestation, a document, a manual check) are absent
+ # on purpose — they mean nothing until the operator has written what they
+ # are asking for.
+ DEFAULT_KINDS = %w[
+ Spree::SellerRequirements::AcceptTerms
+ Spree::SellerRequirements::CompleteProfile
+ Spree::SellerRequirements::BillingAddress
+ Spree::SellerRequirements::ReturnsAddress
+ Spree::SellerRequirements::MinimumProducts
+ ].freeze
+
+ # Writes the default checklist for a store, skipping kinds it already
+ # has. Idempotent, so a store seeded before a kind existed picks it up on
+ # the next run — but a requirement the operator deleted stays deleted
+ # only until then, which is the same bargain the seeded commission rate
+ # makes.
+ #
+ # @param store [Spree::Store]
+ # @return [Array<Spree::SellerRequirement>] the rows created
+ def self.provision_defaults(store)
+ registered = Spree.seller_requirements.map(&:to_s)
+ # `reorder(nil)`: the association orders by position, and PostgreSQL
+ # refuses SELECT DISTINCT with an ORDER BY on a column it does not select.
+ existing = store.seller_requirements.where(type: DEFAULT_KINDS).reorder(nil).distinct.pluck(:type)
+
+ ((DEFAULT_KINDS & registered) - existing).map do |kind|
+ store.seller_requirements.create!(type: kind)
+ end
+ end
+
+ # @return [String] the localized name of the kind, used by operator pickers
+ def self.human_name
+ Spree.t("seller_requirement_types.#{api_type}.name", default: api_type.titleize)
+ end
+
+ # @return [String] the localized description of the kind
+ def self.human_description
+ Spree.t("seller_requirement_types.#{api_type}.description", default: '')
+ end
+
+ # Whether the operator may configure this kind more than once per store.
+ # True for the kinds whose meaning comes from the operator's own copy.
+ #
+ # @return [Boolean]
+ def self.allow_multiple?
+ false
+ end
+
+ # Whether a seller can record having done this themselves. False for
+ # computed kinds, where a submission would be a second, disagreeing
+ # answer to a question the data already settles.
+ #
+ # @return [Boolean]
+ def self.accepts_submissions?
+ false
+ end
+
+ # Whether a seller's submission waits for someone to confirm it.
+ #
+ # @return [Boolean]
+ def self.reviewed_by_operator?
+ false
+ end
+
+ # Whether a submission has to carry a file to mean anything. Declared by
+ # the kind rather than tested for by class, so a gem shipping its own
+ # document-style kind gets the same enforcement.
+ #
+ # @return [Boolean]
+ def self.requires_file?
+ false
+ end
+
+ # Content types a submission's file may carry. Empty accepts anything.
+ # Declared beside {.requires_file?} so a kind that collects files gets
+ # both halves of the contract rather than only the one it remembered.
+ #
+ # @return [Array<String>]
+ def self.accepted_content_types
+ []
+ end
+
+ delegate :accepted_content_types, to: :class
+
+ # @return [String] what the seller sees; the kind's name unless the
+ # operator wrote their own
+ def display_name
+ name.presence || self.class.human_name
+ end
+
+ # @return [String, nil]
+ def display_description
+ description.presence || self.class.human_description.presence
+ end
+
+ # Whether this requirement applies to the given seller at all. A kind
+ # narrows itself here — a payout-account kind only applies once the store
+ # has a payout provider — and a requirement that does not apply is absent
+ # from the checklist rather than shown as unmet.
+ #
+ # @param _seller [Spree::Seller]
+ # @return [Boolean]
+ def applicable?(_seller)
+ true
+ end
+
+ # Whether this requirement stands met for the seller.
+ #
+ # A waiver settles it whatever the kind would otherwise say: the operator
+ # is recording that they dealt with this outside the marketplace, and a
+ # kind reading its own data — the terms column, the address — would
+ # never see that. Not overridable for exactly that reason; kinds
+ # override {#met_by_seller?} instead.
+ #
+ # @param seller [Spree::Seller]
+ # @return [Boolean]
+ def satisfied?(seller)
+ return true if latest_submission(seller)&.waived?
+
+ met_by_seller?(seller)
+ end
+
+ # Whether the seller themselves has met this requirement. Computed kinds
+ # override this to read seller data; the default answers from the latest
+ # submission, which is what the attested and verified kinds need.
+ #
+ # @param seller [Spree::Seller]
+ # @return [Boolean]
+ def met_by_seller?(seller)
+ submission = latest_submission(seller)
+
+ submission.present? && submission.satisfies_requirement?
+ end
+
+ # The seller's standing on this requirement.
+ #
+ # `pending` means someone else has to act — an operator review, a
+ # provider still working through its own checks — which is worth telling
+ # the seller apart from "you have not done this yet".
+ #
+ # @param seller [Spree::Seller]
+ # @return [String] complete | incomplete | pending | rejected
+ def status_for(seller)
+ return Spree::SellerRequirementStatus::COMPLETE if satisfied?(seller)
+
+ case latest_submission(seller)&.status
+ when 'pending' then Spree::SellerRequirementStatus::PENDING
+ when 'rejected' then Spree::SellerRequirementStatus::REJECTED
+ else Spree::SellerRequirementStatus::INCOMPLETE
+ end
+ end
+
+ # Somewhere for the seller to go to get this done — a hosted onboarding
+ # link, for instance. Nil when the seller finishes it inside their own
+ # panel, which is the usual case.
+ #
+ # @param _seller [Spree::Seller]
+ # @return [String, nil]
+ def action_url(_seller)
+ nil
+ end
+
+ # The submission that decides this requirement's standing for a seller:
+ # the most recent one. Earlier rows are the audit trail.
+ #
+ # Read through the seller rather than through this requirement: a seller
+ # has a handful of submissions, a requirement has one per seller on the
+ # marketplace, and evaluating a checklist asks about one seller. The
+ # seller's association loads once and every requirement reads from it.
+ #
+ # @param seller [Spree::Seller]
+ # @return [Spree::SellerRequirementSubmission, nil]
+ def latest_submission(seller)
+ return nil if seller.nil?
+
+ seller.requirement_submissions
+ .select { |submission| submission.seller_requirement_id == id }
+ .max_by { |submission| [submission.created_at, submission.id] }
+ end
+
+ private
+
+ def type_must_be_registered
+ return if type.blank?
+ return if Spree.seller_requirements.any? { |kind| kind.to_s == type }
+
+ errors.add(
+ :type,
+ Spree.t(:invalid_seller_requirement, scope: [:errors, :messages],
+ default: 'is not a registered seller requirement')
+ )
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/seller_requirement_custom_field.rb b/spree/core/app/models/spree/seller_requirement_custom_field.rb
new file mode 100644
index 0000000000..e64b0abd7b
--- /dev/null
+++ b/spree/core/app/models/spree/seller_requirement_custom_field.rb
@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Spree
+ # Joins a requirement to a custom field definition it asks the seller to
+ # fill in. A concrete row rather than a key in preferences: a definition
+ # that is renamed keeps its id, and one that is deleted takes this row with
+ # it — a stored key would survive both and quietly satisfy every seller.
+ class SellerRequirementCustomField < Spree.base_class
+ belongs_to :seller_requirement, class_name: 'Spree::SellerRequirement'
+ belongs_to :custom_field_definition, class_name: 'Spree::CustomFieldDefinition'
+
+ validates :seller_requirement, :custom_field_definition, presence: true
+ validates :custom_field_definition_id, uniqueness: { scope: :seller_requirement_id }, allow_nil: true
+ validate :definition_must_describe_a_seller
+
+ private
+
+ # A definition for products or orders asks the seller for something they
+ # have no field to answer with, so the requirement could never be met.
+ def definition_must_describe_a_seller
+ return if custom_field_definition.nil?
+ return if custom_field_definition.resource_type == Spree::Seller.to_s
+
+ errors.add(:custom_field_definition, :invalid,
+ message: Spree.t('seller_requirements.custom_field_not_for_sellers',
+ default: 'must be a custom field defined for sellers'))
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/seller_requirement_status.rb b/spree/core/app/models/spree/seller_requirement_status.rb
new file mode 100644
index 0000000000..d1a2c0c1e5
--- /dev/null
+++ b/spree/core/app/models/spree/seller_requirement_status.rb
@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Spree
+ # One line of a seller's onboarding checklist: a requirement evaluated
+ # against a seller. A value object — the answer is derived from the
+ # seller's own data and their submissions every time it is asked for, so
+ # there is nothing here worth storing and a stored copy would go stale the
+ # moment a product or an address changed.
+ #
+ # See {Spree::Sellers::Requirements}, which builds these.
+ class SellerRequirementStatus
+ include ActiveModel::Model
+ include ActiveModel::Attributes
+
+ COMPLETE = 'complete'
+ INCOMPLETE = 'incomplete'
+ PENDING = 'pending'
+ REJECTED = 'rejected'
+
+ STATUSES = [COMPLETE, INCOMPLETE, PENDING, REJECTED].freeze
+
+ # The requirement's prefixed id, so a client can act on it.
+ attribute :id, :string
+ # The kind, e.g. 'accept_terms' — what a frontend keys presentation off.
+ attribute :kind, :string
+ attribute :name, :string
+ attribute :description, :string
+ attribute :required, :boolean, default: true
+ attribute :position, :integer
+ attribute :status, :string
+ attribute :action_url, :string
+
+ # The submission behind the status, when there is one.
+ # @return [Spree::SellerRequirementSubmission, nil]
+ attr_accessor :submission
+
+ # ActiveModel::Attributes gives readers, not predicates.
+ def required?
+ !!required
+ end
+
+ def complete?
+ status == COMPLETE
+ end
+
+ # Whether this is standing between the seller and approval.
+ #
+ # @return [Boolean]
+ def blocking?
+ required? && !complete?
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/seller_requirements/accept_terms.rb b/spree/core/app/models/spree/seller_requirements/accept_terms.rb
new file mode 100644
index 0000000000..0617409285
--- /dev/null
+++ b/spree/core/app/models/spree/seller_requirements/accept_terms.rb
@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Spree
+ module SellerRequirements
+ # The seller has accepted the marketplace's terms.
+ #
+ # `terms_effective_from` is how a marketplace asks again after rewriting
+ # them: everyone who accepted before that date falls back to unmet, and
+ # the seller sees the requirement return to their checklist.
+ class AcceptTerms < Spree::SellerRequirement
+ preference :terms_effective_from, :string, default: nil
+
+ # A date nobody can parse would otherwise read as "no date at all", and
+ # this requirement would quietly count sellers on years-old terms as
+ # having accepted the current ones. Refused on save so it cannot be
+ # stored, rather than interpreted generously afterwards.
+ validate :terms_effective_from_must_be_a_date
+
+ def met_by_seller?(seller)
+ accepted_at = seller.terms_accepted_at
+ return false if accepted_at.blank?
+ return true if effective_from.blank?
+
+ accepted_at >= effective_from
+ end
+
+ # `iso8601`, not `parse`: parse fills in whatever a value leaves out, so
+ # "09:00" becomes nine o'clock *today* and the threshold would move every
+ # midnight — sellers who met it yesterday would fall out of compliance
+ # overnight. A cut-off has to be a fixed instant.
+ #
+ # Read in the store's timezone, not the server's: a date the operator
+ # types means midnight where they trade, and interpreting "2026-01-01"
+ # in UTC would move the deadline by hours for everyone else.
+ #
+ # @return [ActiveSupport::TimeWithZone, nil]
+ def effective_from
+ return nil if preferred_terms_effective_from.blank?
+
+ # `find_zone` answers nil for a zone it does not know, so a store
+ # carrying a bad value falls back rather than raising here.
+ zone = Time.find_zone(store&.preferred_timezone.to_s) || Time.zone
+
+ zone.iso8601(preferred_terms_effective_from.to_s)
+ rescue ArgumentError, Date::Error
+ nil
+ end
+
+ private
+
+ def terms_effective_from_must_be_a_date
+ return if preferred_terms_effective_from.blank?
+ return if effective_from.present?
+
+ errors.add(:base, Spree.t('seller_requirements.invalid_terms_effective_from',
+ default: 'Terms effective from is not a date'))
+ end
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/seller_requirements/attestation.rb b/spree/core/app/models/spree/seller_requirements/attestation.rb
new file mode 100644
index 0000000000..aeca934fc6
--- /dev/null
+++ b/spree/core/app/models/spree/seller_requirements/attestation.rb
@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Spree
+ module SellerRequirements
+ # Something the marketplace asks the seller to confirm in their own
+ # right — that their delivery rates are correct, that they hold the
+ # licence their category needs. The seller ticks it and it is met; the
+ # value is the record that they were asked and answered.
+ #
+ # The question is whatever the operator wrote in the row's name and
+ # description, so a store may configure as many as it likes.
+ class Attestation < Spree::SellerRequirement
+ def self.allow_multiple?
+ true
+ end
+
+ def self.accepts_submissions?
+ true
+ end
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/seller_requirements/billing_address.rb b/spree/core/app/models/spree/seller_requirements/billing_address.rb
new file mode 100644
index 0000000000..29cf5dc1bb
--- /dev/null
+++ b/spree/core/app/models/spree/seller_requirements/billing_address.rb
@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Spree
+ module SellerRequirements
+ # Where the seller is invoiced — what a commission invoice is addressed
+ # to, so a marketplace charging commission cannot do without it.
+ class BillingAddress < Spree::SellerRequirement
+ def met_by_seller?(seller)
+ seller.billing_address.present? && seller.billing_address.persisted?
+ end
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/seller_requirements/complete_profile.rb b/spree/core/app/models/spree/seller_requirements/complete_profile.rb
new file mode 100644
index 0000000000..6e42c3a903
--- /dev/null
+++ b/spree/core/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
diff --git a/spree/core/app/models/spree/seller_requirements/document.rb b/spree/core/app/models/spree/seller_requirements/document.rb
new file mode 100644
index 0000000000..27be04b028
--- /dev/null
+++ b/spree/core/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
diff --git a/spree/core/app/models/spree/seller_requirements/minimum_products.rb b/spree/core/app/models/spree/seller_requirements/minimum_products.rb
new file mode 100644
index 0000000000..1c7f234d0a
--- /dev/null
+++ b/spree/core/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
diff --git a/spree/core/app/models/spree/seller_requirements/operator_review.rb b/spree/core/app/models/spree/seller_requirements/operator_review.rb
new file mode 100644
index 0000000000..e232cb228d
--- /dev/null
+++ b/spree/core/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
diff --git a/spree/core/app/models/spree/seller_requirements/required_custom_fields.rb b/spree/core/app/models/spree/seller_requirements/required_custom_fields.rb
new file mode 100644
index 0000000000..e38fdcac97
--- /dev/null
+++ b/spree/core/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
diff --git a/spree/core/app/models/spree/seller_requirements/returns_address.rb b/spree/core/app/models/spree/seller_requirements/returns_address.rb
new file mode 100644
index 0000000000..9055eb6d60
--- /dev/null
+++ b/spree/core/app/models/spree/seller_requirements/returns_address.rb
@@ -0,0 +1,13 @@
+# 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.
+ class ReturnsAddress < Spree::SellerRequirement
+ def met_by_seller?(seller)
+ seller.returns_address.present? && seller.returns_address.persisted?
+ end
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/store.rb b/spree/core/app/models/spree/store.rb
index 4db0a6737f..3b79c85687 100644
--- a/spree/core/app/models/spree/store.rb
+++ b/spree/core/app/models/spree/store.rb
@@ -66,6 +66,11 @@ module Spree
# the tax provider names one. Zero by default: a marketplace outside the EU
# charges no tax on its fee, and inventing one would overcharge sellers.
preference :default_commission_tax_rate, :decimal, default: 0
+ # Admit a seller the moment they finish the checklist, without waiting for
+ # anyone to look at them. Off by default: a marketplace decides who trades
+ # under its name, and letting that happen by omission is the wrong
+ # default for the operator who never thought about it.
+ preference :auto_approve_sellers, :boolean, default: false
# Checkout preferences
# Store-level fallback for the channel-owned `guest_checkout` preference
# (see Spree::Channel::Gating). Retained so existing accessors keep working.
@@ -195,6 +200,9 @@ module Spree
has_many :sellers, class_name: 'Spree::Seller', dependent: :destroy, inverse_of: :store
has_many :commission_rates, class_name: 'Spree::CommissionRate', dependent: :destroy, inverse_of: :store
+ # What this marketplace asks of a seller before it will let them trade.
+ has_many :seller_requirements, -> { order(:position, :id) }, class_name: 'Spree::SellerRequirement',
+ dependent: :destroy, inverse_of: :store
has_many :wishlists, class_name: 'Spree::Wishlist'
diff --git a/spree/core/app/services/spree/seeds/all.rb b/spree/core/app/services/spree/seeds/all.rb
index 13d875335a..9853e2461e 100644
--- a/spree/core/app/services/spree/seeds/all.rb
+++ b/spree/core/app/services/spree/seeds/all.rb
@@ -37,6 +37,9 @@ module Spree
# The marketplace's catch-all rate, at the bottom of the list so
# narrower rates added later resolve ahead of it.
CommissionRates.call
+ # What a new seller has to do before this marketplace will let
+ # them trade. Runs after stores for the same reason roles do.
+ SellerRequirements.call
ApiKeys.call
AllowedOrigins.call
end
diff --git a/spree/core/app/services/spree/seeds/seller_requirements.rb b/spree/core/app/services/spree/seeds/seller_requirements.rb
new file mode 100644
index 0000000000..3825b7fb05
--- /dev/null
+++ b/spree/core/app/services/spree/seeds/seller_requirements.rb
@@ -0,0 +1,19 @@
+module Spree
+ module Seeds
+ # The marketplace's starting checklist for new sellers.
+ #
+ # Only the requirements core can answer on its own — accept the terms,
+ # fill in a profile, give both addresses, list something. What a
+ # particular marketplace additionally asks for (a business registration,
+ # a licence) is theirs to add, and there is no sensible default for it.
+ class SellerRequirements
+ prepend Spree::ServiceModule::Base
+
+ def call
+ Spree::Store.find_each do |store|
+ Spree::SellerRequirement.provision_defaults(store)
+ end
+ end
+ end
+ end
+end
diff --git a/spree/core/app/services/spree/sellers/requirements.rb b/spree/core/app/services/spree/sellers/requirements.rb
new file mode 100644
index 0000000000..ecaba79aa1
--- /dev/null
+++ b/spree/core/app/services/spree/sellers/requirements.rb
@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Spree
+ module Sellers
+ # Evaluates a seller against their marketplace's onboarding requirements
+ # (docs/plans/6.0-seller-onboarding-requirements.md).
+ #
+ # The single place that answers "what does this seller still have to do",
+ # so the seller's own panel, the operator's view of them and the two
+ # workflows that gate approval all say the same thing. Every answer is
+ # computed on read: a stored copy would disagree with the data the moment
+ # a product, an address or a document changed.
+ #
+ # requirements = Spree::Sellers::Requirements.new(seller)
+ # requirements.met? # => false
+ # requirements.blocking # => [#<SellerRequirementStatus name: "Returns address">]
+ class Requirements
+ # @param seller [Spree::Seller]
+ # @param preloaded [Boolean] read the store's checklist off its loaded
+ # association rather than querying. Only a caller that eager-loaded it
+ # should say so — a page of sellers shares one store, so its rows load
+ # once for all of them — because trusting whatever happens to be
+ # cached would let a gate measure against a stale checklist.
+ def initialize(seller, preloaded: false)
+ @seller = seller
+ @preloaded = preloaded
+ end
+
+ # The checklist, in the operator's order. Requirements a kind says do
+ # not apply to this seller are absent rather than shown as unmet.
+ #
+ # @return [Array<Spree::SellerRequirementStatus>]
+ def statuses
+ @statuses ||= applicable_requirements.map { |requirement| build_status(requirement) }
+ end
+
+ # What stands between the seller and approval: required, and not met.
+ #
+ # @return [Array<Spree::SellerRequirementStatus>]
+ def blocking
+ statuses.select(&:blocking?)
+ end
+
+ # @return [Boolean] whether every required requirement is met
+ def met?
+ blocking.empty?
+ end
+
+ # Records what is outstanding on an errors object, naming each one: the
+ # seller has to act on the refusal, and a bare "not ready" leaves them
+ # guessing which of eight things it meant.
+ #
+ # @param errors [ActiveModel::Errors]
+ # @return [Array<Spree::SellerRequirementStatus>] what was recorded
+ def record_blocking(errors)
+ blocking.each do |requirement|
+ errors.add(:requirements, :incomplete,
+ message: Spree.t('seller_requirements.incomplete', name: requirement.name,
+ default: "#{requirement.name} is not complete"))
+ end
+ end
+
+ # Progress over the whole checklist, optional requirements included —
+ # a seller reads it as how far through they are, not as how close to
+ # approval, and hiding the optional ones would make it jump.
+ #
+ # @return [Hash{Symbol => Integer}]
+ def progress
+ self.class.progress_of(statuses)
+ end
+
+ # The one definition of "how far along", so the evaluator and the
+ # seller's own readers cannot drift apart. A checklist that asks for
+ # nothing reads as finished.
+ #
+ # @param statuses [Array<Spree::SellerRequirementStatus>]
+ # @return [Hash{Symbol => Integer}]
+ def self.progress_of(statuses)
+ total = statuses.size
+ done = statuses.count(&:complete?)
+
+ {
+ done: done,
+ total: total,
+ percentage: total.zero? ? 100 : (done / total.to_f * 100).round
+ }
+ end
+
+ private
+
+ attr_reader :seller
+
+ # Requirements are configuration on the store, so an unsaved or
+ # store-less seller has nothing to be measured against.
+ #
+ # `seller_requirements` carries its own order. Submissions are read
+ # through the seller (see SellerRequirement#latest_submission), so
+ # nothing here loads other sellers' rows.
+ def applicable_requirements
+ return [] if seller.nil? || seller.store.nil?
+
+ rows = @preloaded ? seller.store.seller_requirements.to_a : seller.store.seller_requirements.active.to_a
+
+ rows.select { |requirement| requirement.active? && requirement.applicable?(seller) }
+ end
+
+ def build_status(requirement)
+ Spree::SellerRequirementStatus.new(
+ id: requirement.prefixed_id,
+ kind: requirement.class.api_type,
+ name: requirement.display_name,
+ description: requirement.display_description,
+ required: requirement.required,
+ position: requirement.position,
+ status: requirement.status_for(seller),
+ action_url: requirement.action_url(seller),
+ submission: requirement.latest_submission(seller)
+ )
+ end
+ end
+ end
+end
diff --git a/spree/core/db/migrate/20260818000001_create_spree_seller_requirements.rb b/spree/core/db/migrate/20260818000001_create_spree_seller_requirements.rb
new file mode 100644
index 0000000000..ae20ba7d55
--- /dev/null
+++ b/spree/core/db/migrate/20260818000001_create_spree_seller_requirements.rb
@@ -0,0 +1,60 @@
+class CreateSpreeSellerRequirements < ActiveRecord::Migration[8.1]
+ def change
+ create_table :spree_seller_requirements do |t|
+ t.references :store, null: false
+ t.string :type, null: false
+
+ # The operator's own copy, shown to sellers. Blank falls back to the
+ # kind's translated name, so only the generic kinds have to fill it in.
+ t.string :name
+ t.text :description
+
+ t.integer :position, null: false, default: 0
+ t.boolean :active, null: false, default: true
+ t.boolean :required, null: false, default: true
+
+ t.text :preferences
+
+ if t.respond_to?(:jsonb)
+ t.jsonb :metadata
+ else
+ t.json :metadata
+ end
+
+ t.timestamps
+ end
+
+ add_index :spree_seller_requirements, [:store_id, :position]
+ add_index :spree_seller_requirements, [:store_id, :type]
+
+ create_table :spree_seller_requirement_submissions do |t|
+ t.references :seller, null: false
+ t.references :seller_requirement, null: false
+ t.string :status, null: false # no DB default: set by the creating workflow
+
+ t.references :submitted_by
+ t.references :reviewed_by
+ t.datetime :reviewed_at
+
+ # What the seller said, and what the operator said back.
+ t.text :note
+ t.text :review_note
+ # An external identifier the kind understands (a provider account, say).
+ t.string :reference
+
+ if t.respond_to?(:jsonb)
+ t.jsonb :metadata
+ else
+ t.json :metadata
+ end
+
+ t.timestamps
+ end
+
+ # The latest row for a pair is the one that counts; older rows are the
+ # audit trail, so the index leads with the pair and ends with recency.
+ add_index :spree_seller_requirement_submissions,
+ [:seller_id, :seller_requirement_id, :created_at],
+ name: 'index_seller_requirement_submissions_on_pair_and_date'
+ end
+end
diff --git a/spree/core/db/migrate/20260819000001_create_spree_seller_requirement_custom_fields.rb b/spree/core/db/migrate/20260819000001_create_spree_seller_requirement_custom_fields.rb
new file mode 100644
index 0000000000..1a75dca6eb
--- /dev/null
+++ b/spree/core/db/migrate/20260819000001_create_spree_seller_requirement_custom_fields.rb
@@ -0,0 +1,15 @@
+class CreateSpreeSellerRequirementCustomFields < ActiveRecord::Migration[8.1]
+ def change
+ create_table :spree_seller_requirement_custom_fields do |t|
+ t.references :seller_requirement, null: false, index: false
+ t.references :custom_field_definition, null: false
+
+ t.timestamps
+ end
+
+ # A requirement asks for a field once; the pair is the row's identity.
+ add_index :spree_seller_requirement_custom_fields,
+ [:seller_requirement_id, :custom_field_definition_id],
+ unique: true, name: 'idx_seller_requirement_custom_fields_uniqueness'
+ end
+end
diff --git a/spree/core/lib/spree/core.rb b/spree/core/lib/spree/core.rb
index bf14991e0e..4fea548de5 100644
--- a/spree/core/lib/spree/core.rb
+++ b/spree/core/lib/spree/core.rb
@@ -390,6 +390,18 @@ module Spree
Rails.application.config.spree.commission_rules = value
end
+ # Seller onboarding requirement kinds an operator can configure
+ # (docs/plans/6.0-seller-onboarding-requirements.md).
+ #
+ # @return [Array<Class>]
+ def self.seller_requirements
+ Rails.application.config.spree.seller_requirements
+ end
+
+ def self.seller_requirements=(value)
+ Rails.application.config.spree.seller_requirements = value
+ end
+
def self.delivery_method_rules
Rails.application.config.spree.delivery_method_rules
end
diff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rb
index 86f594463f..cc6c3e8914 100644
--- a/spree/core/lib/spree/core/engine.rb
+++ b/spree/core/lib/spree/core/engine.rb
@@ -18,6 +18,7 @@ module Spree
:stock_splitters,
:commission_rules,
:delivery_method_rules,
+ :seller_requirements,
:delivery_rate_providers,
:delivery_profile_types,
:order_routing,
@@ -138,6 +139,12 @@ module Spree
app.config.spree.delivery_method_rules = []
end
+ # Seeded early like the other kind registries: an initializer file adds
+ # a marketplace's own requirement kinds, core's concatenate after.
+ initializer 'spree.register.seller_requirements', before: :load_config_initializers do |app|
+ app.config.spree.seller_requirements = []
+ end
+
initializer 'spree.register.delivery_rate_providers', before: :load_config_initializers do |app|
app.config.spree.delivery_rate_providers = []
end
@@ -300,6 +307,20 @@ module Spree
Spree::CommissionRules::ItemTotalRule
]
+ # Seller onboarding requirement kinds
+ # (docs/plans/6.0-seller-onboarding-requirements.md).
+ Rails.application.config.spree.seller_requirements.concat [
+ Spree::SellerRequirements::AcceptTerms,
+ Spree::SellerRequirements::CompleteProfile,
+ Spree::SellerRequirements::BillingAddress,
+ Spree::SellerRequirements::ReturnsAddress,
+ Spree::SellerRequirements::MinimumProducts,
+ Spree::SellerRequirements::RequiredCustomFields,
+ Spree::SellerRequirements::Attestation,
+ Spree::SellerRequirements::OperatorReview,
+ Spree::SellerRequirements::Document
+ ]
+
# Delivery-method eligibility rule kinds (docs/plans/6.0-delivery-method-rules.md).
Rails.application.config.spree.delivery_method_rules.concat [
Spree::DeliveryMethodRules::ItemTotalRule,
@@ -514,6 +535,7 @@ module Spree
Spree::ExportSubscriber,
Spree::ReportSubscriber,
Spree::InvitationEmailSubscriber,
+ Spree::SellerOnboardingSubscriber,
Spree::AdminUserEmailSubscriber,
Spree::ProductMetricsSubscriber,
Spree::TaxIdentifierValidationSubscriber
diff --git a/spree/core/lib/spree/core/permission_configuration.rb b/spree/core/lib/spree/core/permission_configuration.rb
index f4518557a5..3a7d10cd62 100644
--- a/spree/core/lib/spree/core/permission_configuration.rb
+++ b/spree/core/lib/spree/core/permission_configuration.rb
@@ -339,7 +339,12 @@ module Spree
# Running the marketplace: admitting sellers, approving them, suspending
# them. Deliberately not opened to the seller audience — a seller
# administering other sellers is the one thing this key must not allow.
- register_resource(:sellers, group: :access, subjects: -> { [Spree::Seller] })
+ # The seller records themselves, plus what the marketplace asks of them
+ # before admitting them: who decides admission is who admits, so the
+ # checklist rides the same key rather than becoming a settings matter.
+ register_resource(:sellers, group: :access, subjects: -> {
+ [Spree::Seller, Spree::SellerRequirement, Spree::SellerRequirementSubmission]
+ })
# What the marketplace charges its sellers. Its own resource rather than
# part of `settings`, and closed to the seller audience for the same
diff --git a/spree/core/lib/spree/testing_support/factories/seller_requirement_factory.rb b/spree/core/lib/spree/testing_support/factories/seller_requirement_factory.rb
new file mode 100644
index 0000000000..d677e83304
--- /dev/null
+++ b/spree/core/lib/spree/testing_support/factories/seller_requirement_factory.rb
@@ -0,0 +1,47 @@
+FactoryBot.define do
+ factory :seller_requirement, class: Spree::SellerRequirement do
+ store { Spree::Store.default || create(:store) }
+ type { 'Spree::SellerRequirements::AcceptTerms' }
+ active { true }
+ required { true }
+
+ factory :accept_terms_requirement, class: Spree::SellerRequirements::AcceptTerms do
+ type { 'Spree::SellerRequirements::AcceptTerms' }
+ end
+
+ factory :billing_address_requirement, class: Spree::SellerRequirements::BillingAddress do
+ type { 'Spree::SellerRequirements::BillingAddress' }
+ end
+
+ factory :returns_address_requirement, class: Spree::SellerRequirements::ReturnsAddress do
+ type { 'Spree::SellerRequirements::ReturnsAddress' }
+ end
+
+ factory :complete_profile_requirement, class: Spree::SellerRequirements::CompleteProfile do
+ type { 'Spree::SellerRequirements::CompleteProfile' }
+ end
+
+ factory :minimum_products_requirement, class: Spree::SellerRequirements::MinimumProducts do
+ type { 'Spree::SellerRequirements::MinimumProducts' }
+ end
+
+ factory :required_custom_fields_requirement, class: Spree::SellerRequirements::RequiredCustomFields do
+ type { 'Spree::SellerRequirements::RequiredCustomFields' }
+ end
+
+ factory :attestation_requirement, class: Spree::SellerRequirements::Attestation do
+ type { 'Spree::SellerRequirements::Attestation' }
+ sequence(:name) { |n| "Confirm something #{n}" }
+ end
+
+ factory :operator_review_requirement, class: Spree::SellerRequirements::OperatorReview do
+ type { 'Spree::SellerRequirements::OperatorReview' }
+ sequence(:name) { |n| "Manual check #{n}" }
+ end
+
+ factory :document_requirement, class: Spree::SellerRequirements::Document do
+ type { 'Spree::SellerRequirements::Document' }
+ sequence(:name) { |n| "Document #{n}" }
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/seller_requirement_spec.rb b/spree/core/spec/models/spree/seller_requirement_spec.rb
new file mode 100644
index 0000000000..303bae35ce
--- /dev/null
+++ b/spree/core/spec/models/spree/seller_requirement_spec.rb
@@ -0,0 +1,165 @@
+require 'spec_helper'
+
+RSpec.describe Spree::SellerRequirement, type: :model do
+ let(:store) { @default_store }
+ let(:seller) { create(:seller, store: store) }
+
+ describe 'validations' do
+ it 'refuses a kind that is not registered' do
+ requirement = build(:seller_requirement, store: store, type: 'Spree::SellerRequirements::Imaginary')
+
+ expect(requirement).not_to be_valid
+ expect(requirement.errors[:type]).to include('is not a registered seller requirement')
+ end
+
+ it 'allows a single-instance kind only once per store' do
+ create(:accept_terms_requirement, store: store)
+ duplicate = build(:accept_terms_requirement, store: store)
+
+ expect(duplicate).not_to be_valid
+ end
+
+ it 'allows the same single-instance kind on another store' do
+ create(:accept_terms_requirement, store: store)
+ other = build(:accept_terms_requirement, store: create(:store))
+
+ expect(other).to be_valid
+ end
+
+ it 'allows several rows of a kind whose meaning is the operator’s own words' do
+ create(:document_requirement, store: store, name: 'Business registration')
+ second = build(:document_requirement, store: store, name: 'Proof of insurance')
+
+ expect(second).to be_valid
+ end
+
+ it 'requires a name on a kind that can appear more than once' do
+ requirement = build(:document_requirement, store: store, name: nil)
+
+ expect(requirement).not_to be_valid
+ expect(requirement.errors[:name]).to be_present
+ end
+ end
+
+ describe '#display_name' do
+ it 'uses the operator’s wording when they wrote some' do
+ requirement = build(:accept_terms_requirement, store: store, name: 'Agree to our rules')
+
+ expect(requirement.display_name).to eq('Agree to our rules')
+ end
+
+ it 'falls back to the kind’s own name' do
+ requirement = build(:accept_terms_requirement, store: store, name: nil)
+
+ expect(requirement.display_name).to eq('Accept terms')
+ end
+ end
+
+ describe '#latest_submission' do
+ let(:requirement) { create(:attestation_requirement, store: store) }
+
+ it 'returns the most recent row for that seller' do
+ create(:seller_requirement_submission, seller: seller, requirement: requirement,
+ status: 'rejected', created_at: 2.days.ago)
+ newest = create(:seller_requirement_submission, seller: seller, requirement: requirement,
+ status: 'accepted', created_at: 1.hour.ago)
+
+ expect(requirement.latest_submission(seller)).to eq(newest)
+ end
+
+ it 'ignores another seller’s submissions' do
+ other_seller = create(:seller, store: store)
+ create(:seller_requirement_submission, seller: other_seller, requirement: requirement)
+
+ expect(requirement.latest_submission(seller)).to be_nil
+ end
+ end
+
+ describe '#status_for' do
+ let(:requirement) { create(:operator_review_requirement, store: store) }
+
+ it 'is incomplete with nothing submitted' do
+ expect(requirement.status_for(seller)).to eq('incomplete')
+ end
+
+ it 'is pending while someone still has to look at it' do
+ create(:seller_requirement_submission, seller: seller, requirement: requirement, status: 'pending')
+
+ expect(requirement.status_for(seller)).to eq('pending')
+ end
+
+ it 'is rejected when it was sent back' do
+ create(:seller_requirement_submission, :rejected, seller: seller, requirement: requirement)
+
+ expect(requirement.status_for(seller)).to eq('rejected')
+ end
+
+ it 'is complete once accepted' do
+ create(:seller_requirement_submission, :accepted, seller: seller, requirement: requirement)
+
+ expect(requirement.status_for(seller)).to eq('complete')
+ end
+
+ it 'is complete when the operator waived it' do
+ create(:seller_requirement_submission, :waived, seller: seller, requirement: requirement)
+
+ expect(requirement.status_for(seller)).to eq('complete')
+ end
+ end
+
+ describe 'kind capabilities' do
+ # These are what the generic workflows read instead of testing for a
+ # class by name, so a gem's own kind gets the same treatment.
+ it 'declares no file requirement by default' do
+ expect(described_class.requires_file?).to be false
+ expect(Spree::SellerRequirements::AcceptTerms.requires_file?).to be false
+ end
+
+ it 'lets a kind ask for a file' do
+ expect(Spree::SellerRequirements::Document.requires_file?).to be true
+ end
+
+ it 'enforces the file on any kind that asks for one, not just Document' do
+ custom_kind = Class.new(Spree::SellerRequirements::OperatorReview) do
+ def self.name = 'Spree::SellerRequirements::InsuranceCertificate'
+ def self.requires_file? = true
+ end
+ stub_const('Spree::SellerRequirements::InsuranceCertificate', custom_kind)
+ allow(Spree).to receive(:seller_requirements).and_return(
+ Spree.seller_requirements + [custom_kind]
+ )
+
+ requirement = custom_kind.create!(store: store, name: 'Insurance certificate')
+
+ result = Spree::SellerRequirementSubmissions::Create.call(seller: seller, requirement: requirement)
+
+ expect(result).to be_failure
+ expect(result.error.value.full_messages.join).to match(/file is required/i)
+ end
+ end
+
+ describe '.provision_defaults' do
+ it 'writes the default checklist in order' do
+ store.seller_requirements.destroy_all
+
+ described_class.provision_defaults(store)
+
+ expect(store.seller_requirements.reload.map(&:class)).to eq(
+ [
+ Spree::SellerRequirements::AcceptTerms,
+ Spree::SellerRequirements::CompleteProfile,
+ Spree::SellerRequirements::BillingAddress,
+ Spree::SellerRequirements::ReturnsAddress,
+ Spree::SellerRequirements::MinimumProducts
+ ]
+ )
+ end
+
+ it 'does not duplicate what the store already has' do
+ store.seller_requirements.destroy_all
+ described_class.provision_defaults(store)
+
+ expect { described_class.provision_defaults(store) }.not_to change { store.seller_requirements.reload.count }
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/seller_requirements_spec.rb b/spree/core/spec/models/spree/seller_requirements_spec.rb
new file mode 100644
index 0000000000..8d80b4f562
--- /dev/null
+++ b/spree/core/spec/models/spree/seller_requirements_spec.rb
@@ -0,0 +1,196 @@
+require 'spec_helper'
+
+RSpec.describe 'seller requirement kinds', type: :model do
+ let(:store) { @default_store }
+ let(:seller) { create(:seller, store: store) }
+
+ describe Spree::SellerRequirements::AcceptTerms do
+ let(:requirement) { create(:accept_terms_requirement, store: store) }
+
+ it 'is unmet until the seller accepts' do
+ expect(requirement.satisfied?(seller)).to be false
+ end
+
+ it 'is met once they have' do
+ seller.update!(terms_accepted_at: Time.current)
+
+ expect(requirement.satisfied?(seller)).to be true
+ end
+
+ it 'asks again when the terms were rewritten after the seller accepted' do
+ seller.update!(terms_accepted_at: 1.year.ago)
+ requirement.update!(preferred_terms_effective_from: 1.month.ago.iso8601)
+
+ expect(requirement.satisfied?(seller)).to be false
+ end
+
+ # A cut-off that is not a fixed instant would move on its own: parse turns
+ # "09:00" into nine o'clock today, so a seller compliant yesterday would
+ # fall out overnight.
+ it 'refuses a time with no date, which would move every midnight' do
+ requirement.preferred_terms_effective_from = '09:00'
+
+ expect(requirement).not_to be_valid
+ expect(requirement.errors.full_messages.join).to match(/not a date/i)
+ end
+
+ it 'refuses a relative date' do
+ requirement.preferred_terms_effective_from = 'tomorrow'
+
+ expect(requirement).not_to be_valid
+ end
+
+ # The operator types a date meaning midnight where they trade. Reading it
+ # in the server's zone would move the deadline by hours for every store
+ # that is not on it.
+ it 'reads the date in the store’s timezone, not the server’s' do
+ stub_store_preferences(store, timezone: 'Asia/Tokyo')
+ requirement.update!(preferred_terms_effective_from: '2026-01-01')
+
+ expect(requirement.effective_from).to eq(Time.find_zone('Asia/Tokyo').iso8601('2026-01-01'))
+ expect(requirement.effective_from.utc).to eq(Time.utc(2025, 12, 31, 15, 0, 0))
+ end
+
+ it 'falls back when the store carries a timezone nothing recognizes' do
+ stub_store_preferences(store, timezone: 'Not/AZone')
+ requirement.update!(preferred_terms_effective_from: '2026-01-01')
+
+ expect(requirement.effective_from).to be_present
+ end
+
+ it 'takes a date and a full timestamp' do
+ requirement.preferred_terms_effective_from = '2026-01-01'
+ expect(requirement).to be_valid
+
+ requirement.preferred_terms_effective_from = '2026-01-01T09:00:00Z'
+ expect(requirement).to be_valid
+ end
+
+ it 'stays met for a seller who accepted the current terms' do
+ requirement.update!(preferred_terms_effective_from: 1.month.ago.iso8601)
+ seller.update!(terms_accepted_at: 1.day.ago)
+
+ expect(requirement.satisfied?(seller)).to be true
+ end
+ end
+
+ describe Spree::SellerRequirements::CompleteProfile do
+ let(:requirement) { create(:complete_profile_requirement, store: store) }
+
+ it 'asks for the fields the operator ticked' do
+ requirement.update!(preferred_require_about: true, preferred_require_logo: false,
+ preferred_require_contact_email: false)
+
+ expect(requirement.satisfied?(seller)).to be false
+
+ seller.update!(about: 'We sell things.')
+
+ expect(requirement.satisfied?(seller)).to be true
+ end
+
+ it 'ignores the fields they did not' do
+ requirement.update!(preferred_require_about: false, preferred_require_logo: false,
+ preferred_require_cover_photo: false, preferred_require_contact_email: false)
+
+ expect(requirement.satisfied?(seller)).to be true
+ end
+ end
+
+ describe Spree::SellerRequirements::BillingAddress do
+ let(:requirement) { create(:billing_address_requirement, store: store) }
+
+ it 'is met once an address is saved' do
+ expect(requirement.satisfied?(seller)).to be false
+
+ seller.update!(billing_address: create(:address))
+
+ expect(requirement.satisfied?(seller.reload)).to be true
+ end
+ end
+
+ describe Spree::SellerRequirements::MinimumProducts do
+ let(:requirement) { create(:minimum_products_requirement, store: store) }
+
+ it 'counts the seller’s own listings' do
+ expect(requirement.satisfied?(seller)).to be false
+
+ create(:product, store: store, seller: seller)
+
+ expect(requirement.satisfied?(seller.reload)).to be true
+ end
+
+ it 'asks for as many as the operator configured' do
+ requirement.update!(preferred_minimum_count: 2)
+ create(:product, store: store, seller: seller)
+
+ expect(requirement.satisfied?(seller.reload)).to be false
+ end
+
+ it 'asks for nothing when configured to zero' do
+ requirement.update!(preferred_minimum_count: 0)
+
+ expect(requirement.satisfied?(seller)).to be true
+ end
+ end
+
+ describe Spree::SellerRequirements::RequiredCustomFields do
+ let(:requirement) { create(:required_custom_fields_requirement, store: store) }
+
+ it 'asks nothing while the operator has named no fields' do
+ expect(requirement.satisfied?(seller)).to be true
+ end
+
+ it 'is unmet until the chosen field has a value' do
+ definition = create(:custom_field_definition, resource_type: 'Spree::Seller',
+ namespace: 'compliance', key: 'vat_number')
+ requirement.update!(custom_field_definitions: [definition])
+
+ expect(requirement.satisfied?(seller)).to be false
+
+ seller.custom_fields.create!(custom_field_definition: definition, value: 'PL1234567890')
+
+ expect(requirement.satisfied?(seller.reload)).to be true
+ end
+
+ it 'refuses a field defined for something other than a seller' do
+ product_field = create(:custom_field_definition, resource_type: 'Spree::Product')
+
+ link = requirement.seller_requirement_custom_fields.new(custom_field_definition: product_field)
+
+ expect(link).not_to be_valid
+ expect(link.errors[:custom_field_definition].join).to match(/defined for sellers/i)
+ end
+
+ it 'forgets a field the operator deleted rather than asking for it forever' do
+ definition = create(:custom_field_definition, resource_type: 'Spree::Seller')
+ requirement.update!(custom_field_definitions: [definition])
+
+ definition.destroy
+
+ expect(requirement.reload.custom_field_definitions).to be_empty
+ expect(requirement.satisfied?(seller)).to be true
+ end
+ end
+
+ describe Spree::SellerRequirements::Document do
+ let(:requirement) { create(:document_requirement, store: store) }
+
+ it 'is not met by an accepted submission carrying no file' do
+ create(:seller_requirement_submission, :accepted, seller: seller, requirement: requirement)
+
+ expect(requirement.satisfied?(seller)).to be false
+ end
+
+ it 'is met by an accepted submission with a file' do
+ create(:seller_requirement_submission, :accepted, :with_file, seller: seller, requirement: requirement)
+
+ expect(requirement.satisfied?(seller)).to be true
+ end
+
+ it 'is met by a waiver, which is the point of one' do
+ create(:seller_requirement_submission, :waived, seller: seller, requirement: requirement)
+
+ expect(requirement.satisfied?(seller)).to be true
+ end
+ end
+end
diff --git a/spree/core/spec/services/spree/sellers/requirements_spec.rb b/spree/core/spec/services/spree/sellers/requirements_spec.rb
new file mode 100644
index 0000000000..62895b2899
--- /dev/null
+++ b/spree/core/spec/services/spree/sellers/requirements_spec.rb
@@ -0,0 +1,70 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Sellers::Requirements do
+ let(:store) { @default_store }
+ let(:seller) { create(:seller, store: store) }
+
+ subject(:requirements) { described_class.new(seller.reload) }
+
+ before { store.seller_requirements.destroy_all }
+
+ describe '#statuses' do
+ it 'is empty when the marketplace asks for nothing' do
+ expect(requirements.statuses).to be_empty
+ expect(requirements).to be_met
+ end
+
+ it 'follows the operator’s order' do
+ second = create(:billing_address_requirement, store: store)
+ first = create(:accept_terms_requirement, store: store)
+ first.move_to_top
+
+ expect(requirements.statuses.map(&:kind)).to eq(%w[accept_terms billing_address])
+ expect(second.reload.position).to be > first.reload.position
+ end
+
+ it 'leaves out requirements the operator switched off' do
+ create(:accept_terms_requirement, store: store, active: false)
+
+ expect(requirements.statuses).to be_empty
+ end
+
+ it 'carries the submission behind a status' do
+ requirement = create(:operator_review_requirement, store: store)
+ submission = create(:seller_requirement_submission, seller: seller, requirement: requirement)
+
+ expect(requirements.statuses.first.submission).to eq(submission)
+ end
+ end
+
+ describe '#blocking' do
+ it 'holds only the required ones that are unmet' do
+ create(:accept_terms_requirement, store: store, required: true)
+ create(:billing_address_requirement, store: store, required: false)
+
+ expect(requirements.blocking.map(&:kind)).to eq(['accept_terms'])
+ expect(requirements).not_to be_met
+ end
+
+ it 'is empty once every required one is met' do
+ create(:accept_terms_requirement, store: store)
+ seller.update!(terms_accepted_at: Time.current)
+
+ expect(described_class.new(seller.reload).blocking).to be_empty
+ end
+ end
+
+ describe '#progress' do
+ it 'counts optional requirements too, so it does not jump' do
+ create(:accept_terms_requirement, store: store, required: true)
+ create(:billing_address_requirement, store: store, required: false)
+ seller.update!(terms_accepted_at: Time.current)
+
+ expect(described_class.new(seller.reload).progress).to eq(done: 1, total: 2, percentage: 50)
+ end
+
+ it 'reads as finished when nothing is asked' do
+ expect(requirements.progress).to eq(done: 0, total: 0, percentage: 100)
+ end
+ end
+end