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.

Record what a seller submitted and what was made of it

Damian Legawiecd751b60220a1
diff --git a/spree/core/app/models/spree/seller_requirement_submission.rb b/spree/core/app/models/spree/seller_requirement_submission.rb
new file mode 100644
index 0000000000..c8c180dd1f
--- /dev/null
+++ b/spree/core/app/models/spree/seller_requirement_submission.rb
@@ -0,0 +1,75 @@
+# 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
+
+ #
+ # 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, Spree.t('errors.messages.seller_requirement_store_mismatch',
+ default: 'must belong to the same store as the seller'))
+ end
+ end
+end
diff --git a/spree/core/app/workflows/spree/seller_requirement_submissions/accept.rb b/spree/core/app/workflows/spree/seller_requirement_submissions/accept.rb
new file mode 100644
index 0000000000..fe643e17e9
--- /dev/null
+++ b/spree/core/app/workflows/spree/seller_requirement_submissions/accept.rb
@@ -0,0 +1,40 @@
+module Spree
+ module SellerRequirementSubmissions
+ # The operator confirms what a seller submitted. The requirement is met
+ # from here on, and the row is the record of who decided that.
+ class Accept < Spree::Workflow
+ include Reviewable
+
+ hooks :validate, :after_accept
+
+ # @param submission [Spree::SellerRequirementSubmission]
+ # @param reviewed_by [Object, nil] the staff member accepting
+ # @param review_note [String, nil]
+ def perform(submission:, reviewed_by: nil, review_note: nil)
+ super
+
+ step :ensure_acceptable
+ run_hooks :validate
+
+ ApplicationRecord.transaction do
+ step :mark_accepted
+ end
+
+ run_hooks :after_accept
+ submission.publish_event('seller_requirement_submission.accepted')
+ success(submission.reload)
+ end
+
+ private
+
+ def ensure_acceptable
+ failure(submission, :already_accepted) if submission.accepted?
+ failure(submission, :already_waived) if submission.waived?
+ end
+
+ def mark_accepted
+ mark_reviewed('accepted')
+ end
+ end
+ end
+end
diff --git a/spree/core/app/workflows/spree/seller_requirement_submissions/create.rb b/spree/core/app/workflows/spree/seller_requirement_submissions/create.rb
new file mode 100644
index 0000000000..e10984fafb
--- /dev/null
+++ b/spree/core/app/workflows/spree/seller_requirement_submissions/create.rb
@@ -0,0 +1,97 @@
+module Spree
+ module SellerRequirementSubmissions
+ # A seller records having done something the marketplace asked of them —
+ # ticking an attestation, uploading a document, saying a manual check is
+ # ready to run.
+ #
+ # Whether that settles the requirement or only queues it depends on the
+ # kind: an attestation is the seller's word and is taken at face value, a
+ # document or a manual check waits for someone to look at it.
+ class Create < Spree::Workflow
+ hooks :validate, :after_create
+
+ # @return [Spree::SellerRequirementSubmission]
+ attr_reader :submission
+
+ # @param seller [Spree::Seller]
+ # @param requirement [Spree::SellerRequirement]
+ # @param note [String, nil] what the seller wants the reviewer to know
+ # @param reference [String, nil] an identifier the kind understands
+ # @param file [Object, nil] an uploaded file or signed blob id
+ # @param submitted_by [Object, nil] the seller's own staff member
+ def perform(seller:, requirement:, note: nil, reference: nil, file: nil, submitted_by: nil)
+ super
+
+ step :ensure_submittable
+ step :build_submission
+ step :ensure_file_acceptable
+ run_hooks :validate
+
+ ApplicationRecord.transaction do
+ step :save_submission
+ end
+
+ run_hooks :after_create
+ submission.publish_event('seller_requirement_submission.created')
+ success(submission)
+ end
+
+ private
+
+ # A computed requirement is answered by the seller's own data, so a
+ # submission against one would be a second answer that disagrees with
+ # it the moment the data changes.
+ def ensure_submittable
+ failure(requirement, :submissions_not_accepted) unless requirement.class.accepts_submissions?
+ failure(requirement, :requirement_inactive) unless requirement.active?
+ end
+
+ def build_submission
+ @submission = seller.requirement_submissions.new(
+ requirement: requirement,
+ status: initial_status,
+ note: note,
+ reference: reference,
+ submitted_by: submitted_by
+ )
+ submission.file.attach(file) if file.present?
+ end
+
+ # A document with nothing attached records a check nobody can repeat, so
+ # it is refused here rather than reaching a reviewer empty — and a file
+ # in a format the operator said they cannot open is refused with it,
+ # since the setting is shown to sellers as a promise.
+ def ensure_file_acceptable
+ return unless requirement.class.requires_file?
+
+ unless submission.file.attached?
+ errors.add(:file, :blank, message: Spree.t('seller_requirements.file_required',
+ default: 'A file is required for this requirement'))
+ failure(submission, errors)
+ end
+
+ accepted = requirement.accepted_content_types
+ return if accepted.blank? || accepted.include?(submission.file.content_type)
+
+ errors.add(:file, :invalid,
+ message: Spree.t('seller_requirements.file_type_not_accepted',
+ types: accepted.join(', '),
+ default: "This requirement accepts #{accepted.join(', ')}"))
+ failure(submission, errors)
+ end
+
+ # Waiting on a reviewer, or taken at the seller's word.
+ def initial_status
+ requirement.class.reviewed_by_operator? ? 'pending' : 'accepted'
+ end
+
+ def save_submission
+ failure(submission, submission.errors) unless submission.save
+
+ # Accepting at creation means nobody reviewed it — but the record
+ # should still say when it was settled.
+ submission.update!(reviewed_at: Time.current) if submission.accepted?
+ end
+ end
+ end
+end
diff --git a/spree/core/app/workflows/spree/seller_requirement_submissions/reject.rb b/spree/core/app/workflows/spree/seller_requirement_submissions/reject.rb
new file mode 100644
index 0000000000..595678d978
--- /dev/null
+++ b/spree/core/app/workflows/spree/seller_requirement_submissions/reject.rb
@@ -0,0 +1,45 @@
+module Spree
+ module SellerRequirementSubmissions
+ # The operator sends something back. The requirement returns to unmet and
+ # the seller is told why — a rejection with no reason leaves them
+ # resubmitting the same thing.
+ class Reject < Spree::Workflow
+ include Reviewable
+
+ hooks :validate, :after_reject
+
+ # @param submission [Spree::SellerRequirementSubmission]
+ # @param reviewed_by [Object, nil] the staff member rejecting
+ # @param review_note [String, nil] what was wrong with it
+ def perform(submission:, reviewed_by: nil, review_note: nil)
+ super
+
+ step :ensure_rejectable
+ run_hooks :validate
+
+ ApplicationRecord.transaction do
+ step :mark_rejected
+ end
+
+ run_hooks :after_reject
+ submission.publish_event('seller_requirement_submission.rejected')
+ success(submission.reload)
+ end
+
+ private
+
+ # A waiver is the operator's own exception, and rejecting it in place
+ # would overwrite who granted it and when. Withdrawing one is its own
+ # act — the seller submits again, or the requirement changes — so this
+ # refuses rather than quietly rewriting the record.
+ def ensure_rejectable
+ failure(submission, :already_rejected) if submission.rejected?
+ failure(submission, :already_waived) if submission.waived?
+ end
+
+ def mark_rejected
+ mark_reviewed('rejected')
+ end
+ end
+ end
+end
diff --git a/spree/core/app/workflows/spree/seller_requirement_submissions/reviewable.rb b/spree/core/app/workflows/spree/seller_requirement_submissions/reviewable.rb
new file mode 100644
index 0000000000..d69c5c221a
--- /dev/null
+++ b/spree/core/app/workflows/spree/seller_requirement_submissions/reviewable.rb
@@ -0,0 +1,19 @@
+module Spree
+ module SellerRequirementSubmissions
+ # Shared by the two operator decisions on a submission. Accepting and
+ # rejecting differ in what they mean and what they announce, but both
+ # record the same thing: who decided, when, and what they said.
+ module Reviewable
+ private
+
+ def mark_reviewed(status)
+ submission.update!(
+ status: status,
+ reviewed_by: reviewed_by,
+ reviewed_at: Time.current,
+ review_note: review_note.presence || submission.review_note
+ )
+ end
+ end
+ end
+end
diff --git a/spree/core/app/workflows/spree/seller_requirement_submissions/waive.rb b/spree/core/app/workflows/spree/seller_requirement_submissions/waive.rb
new file mode 100644
index 0000000000..bc11916385
--- /dev/null
+++ b/spree/core/app/workflows/spree/seller_requirement_submissions/waive.rb
@@ -0,0 +1,64 @@
+module Spree
+ module SellerRequirementSubmissions
+ # The operator excuses one seller from something the marketplace asks of
+ # everyone — a seller who satisfied it off the marketplace, or one whose
+ # circumstances the requirement was never written for.
+ #
+ # A waiver reads as met without pretending the seller did it, which is
+ # the distinction that matters when someone reads the record later.
+ class Waive < Spree::Workflow
+ hooks :validate, :after_waive
+
+ # @return [Spree::SellerRequirementSubmission]
+ attr_reader :submission
+
+ # @param seller [Spree::Seller]
+ # @param requirement [Spree::SellerRequirement]
+ # @param reviewed_by [Object, nil] the staff member waiving it
+ # @param review_note [String, nil] why
+ def perform(seller:, requirement:, reviewed_by: nil, review_note: nil)
+ super
+
+ step :ensure_waivable
+ run_hooks :validate
+
+ ApplicationRecord.transaction do
+ step :record_waiver
+ end
+
+ run_hooks :after_waive
+ submission.publish_event('seller_requirement_submission.waived')
+ success(submission)
+ end
+
+ private
+
+ # Any active requirement can be waived, computed ones included: excusing
+ # a seller from the terms or from a minimum catalog is exactly what a
+ # waiver is for, and the base class honours it over the kind's own
+ # reading. What cannot be waived is a requirement the store has switched
+ # off — it is already asking nothing, so a waiver would only add a row
+ # that means nothing (`Create` refuses inactive ones for the same
+ # reason).
+ def ensure_waivable
+ failure(requirement, :requirement_store_mismatch) if requirement.store_id != seller.store_id
+ failure(requirement, :requirement_inactive) unless requirement.active?
+ end
+
+ # A waiver is its own submission rather than an edit of whatever came
+ # before: what the seller sent and what the operator decided are two
+ # different acts, and the earlier one stays readable.
+ def record_waiver
+ @submission = seller.requirement_submissions.new(
+ requirement: requirement,
+ status: 'waived',
+ reviewed_by: reviewed_by,
+ reviewed_at: Time.current,
+ review_note: review_note
+ )
+
+ failure(submission, submission.errors) unless submission.save
+ end
+ end
+ end
+end
diff --git a/spree/core/lib/spree/testing_support/factories/seller_requirement_submission_factory.rb b/spree/core/lib/spree/testing_support/factories/seller_requirement_submission_factory.rb
new file mode 100644
index 0000000000..d2112281a5
--- /dev/null
+++ b/spree/core/lib/spree/testing_support/factories/seller_requirement_submission_factory.rb
@@ -0,0 +1,32 @@
+FactoryBot.define do
+ factory :seller_requirement_submission, class: Spree::SellerRequirementSubmission do
+ seller
+ requirement { create(:attestation_requirement, store: seller.store) }
+ status { 'pending' }
+
+ trait :accepted do
+ status { 'accepted' }
+ reviewed_at { Time.current }
+ end
+
+ trait :rejected do
+ status { 'rejected' }
+ reviewed_at { Time.current }
+ review_note { 'Please send a clearer copy.' }
+ end
+
+ trait :waived do
+ status { 'waived' }
+ reviewed_at { Time.current }
+ end
+
+ trait :with_file do
+ after(:build) do |submission|
+ submission.file.attach(
+ io: File.new(Spree::Core::Engine.root.join('spec', 'fixtures', 'thinking-cat.jpg')),
+ filename: 'thinking-cat.jpg'
+ )
+ end
+ end
+ end
+end
diff --git a/spree/core/spec/workflows/spree/seller_requirement_submissions/lifecycle_spec.rb b/spree/core/spec/workflows/spree/seller_requirement_submissions/lifecycle_spec.rb
new file mode 100644
index 0000000000..76b0eec983
--- /dev/null
+++ b/spree/core/spec/workflows/spree/seller_requirement_submissions/lifecycle_spec.rb
@@ -0,0 +1,176 @@
+require 'spec_helper'
+
+RSpec.describe 'seller requirement submission workflows' do
+ let(:store) { @default_store }
+ let(:seller) { create(:seller, :onboarding, store: store) }
+ let(:staff) { create(:admin_user) }
+
+ before { store.seller_requirements.destroy_all }
+
+ describe Spree::SellerRequirementSubmissions::Create do
+ it 'takes an attestation at the seller’s word' do
+ requirement = create(:attestation_requirement, store: store)
+
+ result = described_class.call(seller: seller, requirement: requirement)
+
+ expect(result).to be_success
+ expect(result.value).to be_accepted
+ expect(requirement.satisfied?(seller)).to be true
+ end
+
+ it 'queues a manual check for whoever reviews it' do
+ requirement = create(:operator_review_requirement, store: store)
+
+ result = described_class.call(seller: seller, requirement: requirement, note: 'VAT PL123')
+
+ expect(result.value).to be_pending
+ expect(requirement.status_for(seller)).to eq('pending')
+ end
+
+ it 'refuses a submission against a requirement computed from the seller’s data' do
+ requirement = create(:accept_terms_requirement, store: store)
+
+ expect(described_class.call(seller: seller, requirement: requirement)).to be_failure
+ end
+
+ it 'refuses a document with nothing attached' do
+ requirement = create(:document_requirement, store: store)
+
+ result = described_class.call(seller: seller, requirement: requirement)
+
+ expect(result).to be_failure
+ expect(result.error.value.full_messages.join).to match(/file is required/i)
+ end
+
+ it 'refuses a file in a format a document cannot arrive as' do
+ requirement = create(:document_requirement, store: store)
+
+ result = described_class.call(
+ seller: seller,
+ requirement: requirement,
+ file: {
+ io: StringIO.new('#!/bin/sh'),
+ filename: 'script.sh',
+ content_type: 'application/x-sh'
+ }
+ )
+
+ expect(result).to be_failure
+ expect(result.error.value.full_messages.join).to match(/accepts/i)
+ end
+
+ it 'takes a scan of one' do
+ requirement = create(:document_requirement, store: store)
+
+ result = described_class.call(
+ seller: seller,
+ requirement: requirement,
+ file: {
+ io: File.new(Spree::Core::Engine.root.join('spec', 'fixtures', 'thinking-cat.jpg')),
+ filename: 'thinking-cat.jpg',
+ content_type: 'image/jpeg'
+ }
+ )
+
+ expect(result).to be_success
+ expect(result.value).to be_pending
+ end
+ end
+
+ describe Spree::SellerRequirementSubmissions::Accept do
+ it 'settles the requirement and records who decided' do
+ requirement = create(:operator_review_requirement, store: store)
+ submission = create(:seller_requirement_submission, seller: seller, requirement: requirement)
+
+ result = described_class.call(submission: submission, reviewed_by: staff, review_note: 'Checked')
+
+ expect(result).to be_success
+ expect(submission.reload).to be_accepted
+ expect(submission.reviewed_by).to eq(staff)
+ expect(submission.reviewed_at).to be_present
+ expect(requirement.satisfied?(seller)).to be true
+ end
+ end
+
+ describe Spree::SellerRequirementSubmissions::Reject do
+ it 'sends it back with a reason the seller can act on' do
+ requirement = create(:operator_review_requirement, store: store)
+ submission = create(:seller_requirement_submission, seller: seller, requirement: requirement)
+
+ described_class.call(submission: submission, reviewed_by: staff, review_note: 'Wrong number')
+
+ expect(submission.reload).to be_rejected
+ expect(submission.review_note).to eq('Wrong number')
+ expect(requirement.status_for(seller)).to eq('rejected')
+ end
+
+ it 'refuses to reject a waiver, which would erase who granted it' do
+ requirement = create(:operator_review_requirement, store: store)
+ waiver = create(:seller_requirement_submission, :waived, seller: seller, requirement: requirement,
+ reviewed_by: staff)
+
+ expect(described_class.call(submission: waiver, reviewed_by: staff)).to be_failure
+ expect(waiver.reload).to be_waived
+ expect(waiver.reviewed_by).to eq(staff)
+ end
+ end
+
+ describe Spree::SellerRequirementSubmissions::Waive do
+ it 'excuses one seller without pretending they did it' do
+ requirement = create(:document_requirement, store: store)
+
+ result = described_class.call(seller: seller, requirement: requirement, reviewed_by: staff,
+ review_note: 'Verified offline')
+
+ expect(result).to be_success
+ expect(result.value).to be_waived
+ expect(requirement.satisfied?(seller)).to be true
+ end
+
+ it 'leaves what the seller sent earlier readable' do
+ requirement = create(:operator_review_requirement, store: store)
+ earlier = create(:seller_requirement_submission, seller: seller, requirement: requirement, note: 'my note')
+
+ described_class.call(seller: seller, requirement: requirement, reviewed_by: staff)
+
+ expect(earlier.reload).to be_pending
+ expect(seller.requirement_submissions.count).to eq(2)
+ end
+
+ it 'refuses a requirement belonging to another marketplace' do
+ other = create(:document_requirement, store: create(:store))
+
+ expect(described_class.call(seller: seller, requirement: other)).to be_failure
+ end
+
+ it 'refuses a requirement the store has switched off' do
+ requirement = create(:document_requirement, store: store, active: false)
+
+ expect(described_class.call(seller: seller, requirement: requirement)).to be_failure
+ end
+
+ # The bug this guards: a computed kind reads the seller's own data and
+ # never looks at submissions, so before the base class honoured waivers
+ # the operator saw a "Waived" badge next to a requirement that still
+ # counted as unmet and still blocked approval.
+ it 'settles a computed requirement the operator excuses the seller from' do
+ requirement = create(:accept_terms_requirement, store: store)
+ expect(requirement.satisfied?(seller)).to be false
+
+ described_class.call(seller: seller, requirement: requirement, reviewed_by: staff)
+
+ expect(requirement.satisfied?(seller.reload)).to be true
+ expect(requirement.status_for(seller)).to eq('complete')
+ end
+
+ it 'counts a waived requirement as done in the seller’s progress' do
+ store.seller_requirements.destroy_all
+ requirement = create(:accept_terms_requirement, store: store)
+ create(:billing_address_requirement, store: store)
+
+ described_class.call(seller: seller, requirement: requirement, reviewed_by: staff)
+
+ expect(seller.reload.onboarding_progress).to eq(done: 1, total: 2, percentage: 50)
+ end
+ end
+end