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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
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.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/workflows/spree/seller_requirement_submissions/accept.rb b/spree/core/app/workflows/spree/seller_requirement_submissions/accept.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/workflows/spree/seller_requirement_submissions/create.rb b/spree/core/app/workflows/spree/seller_requirement_submissions/create.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/workflows/spree/seller_requirement_submissions/reject.rb b/spree/core/app/workflows/spree/seller_requirement_submissions/reject.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/workflows/spree/seller_requirement_submissions/reviewable.rb b/spree/core/app/workflows/spree/seller_requirement_submissions/reviewable.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/workflows/spree/seller_requirement_submissions/waive.rb b/spree/core/app/workflows/spree/seller_requirement_submissions/waive.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --git a/spree/core/spec/workflows/spree/seller_requirement_submissions/lifecycle_spec.rb b/spree/core/spec/workflows/spree/seller_requirement_submissions/lifecycle_spec.rbnew file mode 100644index 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