spree_core 5.6.0 → 6.0.0.beta1

data/app/models/spree/seller_balance.rb

@@ -0,0 +1,86 @@
+module Spree
+  # One seller's position in one currency, read off the fund ledger.
+  #
+  # Never persisted: every figure is a sum over {Spree::SellerTransfer} and
+  # {Spree::SellerPayout} rows, so the ledger stays the only record and this
+  # only presents it. One per currency — a marketplace paying a seller in two
+  # currencies has two ledgers, and adding them would answer a question nobody
+  # asked.
+  #
+  # A position has two sides when the seller's account settles in a currency
+  # other than the one they sold in: what the sale was worth, and what their
+  # account received once the provider converted it. Both are recorded figures.
+  # They are never added together, and Spree converts nothing itself.
+  class SellerBalance
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    attribute :seller
+    # What the sales were priced in.
+    attribute :currency, :string
+    # What the seller's account holds, and is paid in. The same as `currency`
+    # unless the provider converted on the way in.
+    attribute :settlement_currency, :string
+    # What the seller has earned: completed transfers, reversals included.
+    attribute :earned, :decimal, default: 0
+    # Earnings still with the provider — a transfer not yet confirmed, or one
+    # whose outcome is unknown. Shown so a shipped order does not read as
+    # unpaid while the money is in flight.
+    attribute :pending, :decimal, default: 0
+    # The same completed earnings, as their account received them.
+    attribute :payable, :decimal, default: 0
+    # How much of that has reached them, through settlements that completed.
+    attribute :paid, :decimal, default: 0
+
+    extend Spree::DisplayMoney
+    money_methods :earned, :pending
+
+    # @param seller [Spree::Seller]
+    # @param currency [String] what the sales were priced in
+    # @param settlement_currency [String] what the account settles in
+    # @return [Spree::SellerBalance]
+    def self.for(seller, currency, settlement_currency = currency)
+      transfers = seller.seller_transfers.where(currency: currency).settling_in(settlement_currency)
+
+      new(
+        seller: seller,
+        currency: currency,
+        settlement_currency: settlement_currency,
+        earned: transfers.completed.sum(:amount),
+        pending: transfers.with_status('pending', 'processing', 'unresolved').sum(:amount),
+        payable: transfers.completed.settlement_total,
+        # Read through the transfers a settlement claimed rather than off the
+        # settlement's own total: two sale currencies can settle into one, and
+        # the payout's figure would then count against both of them.
+        paid: transfers.completed.joins(:payout).
+              merge(Spree::SellerPayout.completed).settlement_total
+      )
+    end
+
+    # What the marketplace still owes, in the currency it can actually be sent
+    # in.
+    #
+    # A payout settles every position sharing that currency, so a seller who
+    # sells in two currencies that settle into one is paid the sum of both
+    # rather than either. The figures reconcile — both sides read the same
+    # transfer rows — but one position is not one deposit.
+    #
+    # @return [BigDecimal]
+    def balance
+      payable - paid
+    end
+
+    # @return [Boolean] whether the provider converted this seller's earnings
+    def converted?
+      settlement_currency != currency
+    end
+
+    # Formatted in the settlement currency rather than the sale's, since these
+    # are what the account holds.
+    %i[payable paid balance].each do |figure|
+      define_method(:"display_#{figure}") do
+        Spree::Money.new(public_send(figure), currency: settlement_currency)
+      end
+    end
+  end
+end

data/app/models/spree/seller_payout.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Spree
+  # One settlement to one seller: the earnings they had accrued, batched and
+  # sent on their own schedule.
+  #
+  # The second of the ledger's two levels. Transfers credit a seller as each
+  # order ships; a payout is the money actually leaving — daily, weekly,
+  # monthly, or whenever an operator says so. It names exactly which transfers
+  # it settled, so a seller asking "what is this deposit for" has an answer,
+  # and so a reversal arriving after a payout closed lands in the next period
+  # rather than rewriting a settlement that already happened.
+  #
+  # Core records both levels for every marketplace. Whether money actually
+  # moves is the {Spree::PayoutProvider}'s business: the built-in one records
+  # and leaves the operator to pay by bank, while a provider like Stripe
+  # Connect performs the transfer itself.
+  class SellerPayout < Spree.base_class
+    has_prefix_id :vpo
+
+    include Spree::Metadata
+    # Denormalized from the seller, which never changes store — so the copy
+    # cannot drift, and tenancy is structural rather than a subquery every
+    # consumer must remember. Always set explicitly from the seller: ledger
+    # rows are written by jobs and subscribers, where the request-scoped
+    # default store is absent or wrong.
+    include Spree::SingleStoreResource
+
+    #
+    # Associations
+    #
+    belongs_to :seller, class_name: 'Spree::Seller'
+    # What this payout settles. Deliberately nullify rather than destroy: a
+    # transfer is the record of an earning and outlives the settlement that
+    # paid it, so a deleted payout releases its transfers back to the next
+    # sweep instead of erasing what the seller earned.
+    has_many :transfers, class_name: 'Spree::SellerTransfer', foreign_key: :payout_id,
+                         inverse_of: :payout, dependent: :nullify
+
+    #
+    # Validations
+    #
+    validates :amount, numericality: true
+    validates :currency, presence: true
+    validates :provider, presence: true
+
+    #
+    # Statuses. As with transfers, movement is through workflows rather than a
+    # transition graph.
+    #
+    include Spree::HasStatus
+    has_status :pending, :processing, :completed, :failed, :unresolved, default: :pending
+
+    #
+    # Scopes
+    #
+    # Money promised but not yet gone — what an operator's queue is for.
+    scope :owed, -> { where(status: %w[pending processing]) }
+
+    self.whitelisted_ransackable_attributes = %w[amount currency status provider reference period_start period_end created_at seller_id]
+    self.whitelisted_ransackable_associations = %w[seller transfers]
+
+    extend Spree::DisplayMoney
+    money_methods :amount
+
+    # @return [BigDecimal] what the transfers this payout holds actually come
+    #   to, for checking a stored amount against its parts
+    # Summed on what the seller's account actually received, since that is
+    # what this payout moves.
+    def transfers_total
+      transfers.settlement_total
+    end
+
+    # Gives up on this settlement and puts its earnings back.
+    #
+    # Releasing them is what makes a failure recoverable, and it is the one
+    # thing a caller must not forget: a sweep only ever collects unstamped
+    # rows, so earnings left stamped to a failed payout are invisible to every
+    # later sweep while the balance still reports the seller as owed them.
+    # Released, they simply fall into the next one.
+    #
+    # Lives here rather than in the flows that call it — core's sweep and any
+    # provider's failure webhook — because the association and the status both
+    # belong to the payout, and a provider gem should not have to know the
+    # invariant to honour it.
+    def fail!
+      transaction do
+        release_transfers
+        # The amount stays: an operator investigating a failed settlement has
+        # to see what was attempted, and the `owed` scope already excludes it
+        # from what is still to be sent.
+        update!(status: 'failed')
+      end
+    end
+
+    # Records that nobody knows whether this settlement happened, and
+    # deliberately keeps its earnings claimed.
+    #
+    # The opposite of {#fail!} in the one way that matters. Releasing here
+    # would let the next sweep assemble the same earnings into a second
+    # payout, and a provider's idempotency key only protects a retry for as
+    # long as the provider keeps the record — Stripe prunes after a day, so a
+    # monthly sweep is well past it. Held instead, the earnings stay out of
+    # every later sweep until a person or a webhook settles what actually
+    # happened.
+    def unresolve!
+      update!(status: 'unresolved')
+    end
+
+    # Hands the earnings back to the next sweep without recording a failure —
+    # for a settlement that never had anything to send.
+    def release_transfers
+      transfers.update_all(payout_id: nil, updated_at: Time.current)
+    end
+  end
+end

data/app/models/spree/seller_requirement.rb

@@ -0,0 +1,274 @@
+# 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::HasListPosition
+    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, have a way to ship, 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::DeliveryMethod
+      Spree::SellerRequirements::PackageType
+      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.
+    #
+    # Whether this evaluation may answer from what Spree already knows rather
+    # than asking the outside world. Set by `Spree::Sellers::Requirements` for
+    # a listing, where one network call per row is the difference between a
+    # page that loads and one that does not. A kind that never leaves the
+    # database can ignore it; one that calls a provider should read the value
+    # it last recorded instead.
+    #
+    # False everywhere it matters — the two approval gates and a seller's own
+    # page ask for the current answer.
+    attr_accessor :prefer_cached
+
+    # @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
+
+    # Why this line is not done, when the answer is somewhere the seller
+    # cannot see. Nil for every kind whose own description already says what
+    # is wanted, which is nearly all of them — a requirement asking for an
+    # address explains itself.
+    #
+    # @param _seller [Spree::Seller]
+    # @return [Hash, nil] `{ state:, message: }`
+    def blocker(_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, :invalid_seller_requirement, message: Spree.t(:invalid_seller_requirement, scope: [:errors, :messages],
+                                             default: 'is not a registered seller requirement')
+      )
+    end
+  end
+end

data/app/models/spree/seller_requirement_custom_field.rb

@@ -0,0 +1,38 @@
+# 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 :custom_field_definition_id, uniqueness: { scope: :seller_requirement_id }, allow_nil: true
+    validate :definition_must_describe_a_seller
+    validate :definition_must_belong_to_the_same_store
+
+    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
+
+    # Both sides are store-owned, so a marketplace can only ask its sellers
+    # for fields it defined itself.
+    def definition_must_belong_to_the_same_store
+      return if custom_field_definition.nil? || seller_requirement.nil?
+      return if custom_field_definition.store_id == seller_requirement.store_id
+
+      errors.add(:custom_field_definition, :must_belong_to_same_store)
+    end
+  end
+end

data/app/models/spree/seller_requirement_status.rb

@@ -0,0 +1,144 @@
+# 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
+
+    # Why this line is stuck, when the reason lives somewhere the seller
+    # cannot see — a payout provider still checking their identity, say.
+    #
+    # `state` is one of `action` (they must do something), `pending` (the
+    # provider is looking, and nobody can hurry it) or `rejected`. `message`
+    # is the provider's own sentence when it wrote one: best-effort and
+    # unlocalized, so it is shown as detail beside translated copy rather
+    # than in place of it.
+    #
+    # @return [Hash, nil]
+    attr_accessor :blocker
+
+    # The submission behind the status, when there is one.
+    # @return [Spree::SellerRequirementSubmission, nil]
+    attr_accessor :submission
+
+    # The requirement this was evaluated from.
+    #
+    # Carried so a serializer can ask the kind its own questions — which
+    # custom fields it names, whether it takes a file — without re-fetching a
+    # row the evaluator has already loaded. Not serialized itself: what a
+    # client needs is the answers, not the configuration row.
+    #
+    # @return [Spree::SellerRequirement, nil]
+    attr_accessor :requirement
+
+    # The seller this was evaluated against, so kind-specific readers can ask
+    # about them without the caller passing them a second time.
+    #
+    # @return [Spree::Seller, nil]
+    attr_accessor :seller
+
+    # The custom fields this line asks for, each paired with the seller's
+    # current answer — empty for every kind that asks for none.
+    #
+    # Built here rather than in the serializer because it is the answer to
+    # "what does this requirement want", which is the value object's job; the
+    # serializer only decides how to render it.
+    #
+    # @return [Array<Hash>] `{ definition:, custom_field: }` pairs
+    def custom_fields
+      return @custom_fields if defined?(@custom_fields)
+      return @custom_fields = [] if seller.nil? || !requirement.respond_to?(:custom_field_definitions)
+
+      answered = seller.custom_fields.index_by(&:custom_field_definition_id)
+
+      @custom_fields = requirement.custom_field_definitions.map do |definition|
+        { definition: definition, custom_field: answered[definition.id] }
+      end
+    end
+
+    # The legal document this line asks for, when its kind asks for one —
+    # nil for every other kind.
+    #
+    # Same job as {#custom_fields}: the value object answers "what does this
+    # requirement want", so the seller panel can offer to create that exact
+    # document rather than making the seller retype its name.
+    #
+    # @return [String, nil]
+    def required_policy_name
+      return nil unless requirement.respond_to?(:required_policy_name)
+
+      requirement.required_policy_name.presence
+    end
+
+    # The marketplace terms this line asks the seller to accept, as
+    # sanitized markup. Nil for every other kind, and nil while the
+    # marketplace has not written any.
+    #
+    # @return [String, nil]
+    def terms_html
+      return nil unless requirement.respond_to?(:terms_html)
+
+      requirement.terms_html
+    end
+
+    # The policy the seller actually published against this line, when they
+    # have — nil for every other kind, and nil while the document is still
+    # owed.
+    #
+    # What the operator reads before approving: a line that says "Done"
+    # without showing what was written is not something anyone can approve on.
+    #
+    # @return [Spree::Policy, nil]
+    def published_policy
+      return @published_policy if defined?(@published_policy)
+
+      name = required_policy_name
+      return @published_policy = nil if name.nil? || seller.nil?
+
+      @published_policy = seller.policies.detect do |policy|
+        policy.name.to_s.strip.casecmp?(name) && policy.with_body?
+      end
+    end
+
+    # 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