spree_core 5.6.0 → 6.0.0.beta1

data/app/models/spree/seller_requirement_submission.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Spree
+  # What a seller did about one requirement, and what the operator made of
+  # it (docs/plans/6.0-seller-onboarding-requirements.md).
+  #
+  # Only the requirements a seller attests to, or someone verifies, need a
+  # row: the computed kinds read the seller's own data and would be
+  # contradicted by a stored answer. The latest row for a
+  # (seller, requirement) pair decides the standing; the ones before it are
+  # the record of how the marketplace got there.
+  class SellerRequirementSubmission < Spree.base_class
+    include Spree::HasStatus
+    include Spree::Metadata
+
+    has_prefix_id :selsub
+
+    publishes_lifecycle_events
+
+    # `waived` is the operator excusing one seller from something the store
+    # asks of everyone — a requirement they have already satisfied off the
+    # marketplace, say. It reads as met without pretending the seller did it.
+    has_status :pending, :accepted, :rejected, :waived, default: :pending
+
+    #
+    # Associations
+    #
+    belongs_to :seller, class_name: 'Spree::Seller', inverse_of: :requirement_submissions
+    belongs_to :requirement, class_name: 'Spree::SellerRequirement',
+                             foreign_key: :seller_requirement_id, inverse_of: :submissions
+    belongs_to :submitted_by, class_name: Spree.admin_user_class.to_s, optional: true
+    belongs_to :reviewed_by, class_name: Spree.admin_user_class.to_s, optional: true
+
+    #
+    # Attachments
+    #
+    # Private, and served only through the admin and seller branches: these
+    # are business registrations and identity documents.
+    has_one_attached :file, service: Spree.private_storage_service_name
+
+    #
+    # Validations
+    #
+    validate :requirement_belongs_to_sellers_store
+
+    validates :file,
+              size: { less_than_or_equal_to: ->(_record) { Spree::Config.max_seller_document_upload_size } },
+              if: -> { file.attached? }
+
+    # Sellers are the marketplace's lower-trust writers and an operator opens
+    # these files on their own machine, so the bytes decide what a file is,
+    # not the header the uploader sent: without that check a script named
+    # `certificate.pdf` passes.
+    #
+    # The accepted list comes from the requirement's own kind, the same value
+    # the seller API serializes so the panel's picker can hint it.
+    validates_with Spree::AttachmentContentTypeValidator,
+                   attributes: [:file],
+                   in: ->(record) { record.requirement&.accepted_content_types || [] },
+                   if: -> { file.attached? }
+
+    #
+    # Scopes
+    #
+    scope :for_seller, ->(seller) { where(seller_id: seller.id) }
+
+    self.whitelisted_ransackable_attributes = %w[status created_at reviewed_at]
+    self.whitelisted_ransackable_associations = %w[seller requirement]
+
+    # Whether this row counts as the requirement being met.
+    #
+    # @return [Boolean]
+    def satisfies_requirement?
+      accepted? || waived?
+    end
+
+    private
+
+    # A submission joins a seller to a requirement, and both belong to a
+    # store — so a mismatch means one of the two ids came from somewhere it
+    # should not have. Cheaper to refuse here than to rely on every caller
+    # having scope-fetched both.
+    def requirement_belongs_to_sellers_store
+      return if seller.nil? || requirement.nil?
+      return if seller.store_id == requirement.store_id
+
+      errors.add(:requirement, :seller_requirement_store_mismatch, message: Spree.t('errors.messages.seller_requirement_store_mismatch',
+                                       default: 'must belong to the same store as the seller'))
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# 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
+      # What the seller reads in the panel. Optional: a marketplace that
+      # already publishes customer Terms of Service can leave this blank
+      # and the checklist falls back to that policy, so the two cannot
+      # drift. A seller agreement that is not the shopper-facing document
+      # is written here instead.
+      preference :terms_body, :text, default: nil, nullable: true
+      # `:date`, so the dashboard renders a date picker rather than a text box
+      # an operator can type a malformed date into. The value stays a
+      # `yyyy-MM-dd` string on the wire and in storage — see `effective_from`
+      # for why the timezone is applied on read rather than at coercion.
+      preference :terms_effective_from, :date, default: nil
+      # A published copy of the same terms, for a marketplace that also
+      # hosts them on a public page. Optional — the panel renders the
+      # body above; this is the "open the full document" link.
+      preference :terms_url, :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
+
+      # The terms themselves, so the seller can read what they are accepting.
+      # `action_url` is the checklist's existing "go here" channel for a
+      # published copy; the body is what the panel renders inline.
+      #
+      # @return [String, nil]
+      def action_url(_seller)
+        preferred_terms_url.presence
+      end
+
+      # Sanitized markup the seller reads before accepting. The requirement's
+      # own body wins; otherwise the store's Terms of Service, so a
+      # marketplace that already wrote that policy does not write it twice.
+      #
+      # @return [String, nil]
+      def terms_html
+        source = preferred_terms_body.presence || store_terms_body
+        return if source.blank?
+
+        Spree::RichTextSanitizer.sanitize(source).presence
+      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?
+
+        # On the preference rather than :base, so the operator's form marks the
+        # field they got wrong instead of only showing a summary line.
+        errors.add(:preferred_terms_effective_from, :invalid_terms_effective_from,
+                   message: Spree.t('seller_requirements.invalid_terms_effective_from',
+                                    default: 'Terms effective from is not a date'))
+      end
+
+      def store_terms_body
+        return if store.nil?
+
+        store.policies.with_matching_name(Spree.t(:terms_of_service)).detect(&:with_body?)&.body
+      end
+    end
+  end
+end

data/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

data/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

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