spree_core 5.6.0 → 6.0.0.beta1

data/app/models/concerns/spree/purchase/taxation.rb

@@ -0,0 +1,146 @@
+module Spree
+  module Purchase
+    # Tax location and pre-tax sums shared by Spree::Cart and Spree::Order.
+    module Taxation
+      # The address tax is computed against, honoring the store's
+      # tax_using_ship_address preference.
+      #
+      # @return [Spree::Address, nil]
+      def tax_address
+        Spree::StorePreferences.read(store, :tax_using_ship_address) ? ship_address : bill_address
+      end
+
+      # The country whose tax applies. Before the customer enters an address
+      # that is the market's own country, which is what lets a storefront show
+      # tax-inclusive prices from the first page view.
+      #
+      # @return [Spree::Country, nil]
+      def tax_country
+        tax_address&.country || market&.default_country || store&.default_country
+      end
+
+      # The tax engine for this sale, chosen by its market. Falls back to the
+      # store-wide default when the market names none, or when there is no
+      # market yet (an empty cart before currency resolution).
+      #
+      # @return [Spree::TaxProvider::Base]
+      def tax_provider
+        market&.tax_provider_instance || Spree.default_tax_provider.new
+      end
+
+      # The typed inputs every +estimate+ call carries. Assembled here rather
+      # than at each call site so a single-item re-estimate reaches the provider
+      # with the same buyer registration and exemption evidence as a full
+      # recalculation — the provider replaces the item's rows either way, so a
+      # partial call missing them would silently re-tax an exempt line.
+      #
+      # @return [Hash]
+      def tax_estimate_inputs
+        {
+          tax_date: Time.current,
+          tax_identifier: resolved_tax_identifier,
+          exemptions: usable_exemptions
+        }
+      end
+
+      # Everything a provider taxes when +estimate+ is called without an
+      # explicit item list: line items, fulfillments and fees.
+      #
+      # Customs duties are deliberately absent. A duty is an import charge
+      # levied by the destination's customs authority, not a supply that a
+      # domestic sales tax or VAT applies to — taxing it here would both
+      # invent tax the merchant never owed and double-count against the
+      # import VAT a landed-cost provider writes itself, as a TaxLine against
+      # the duty fee. Providers that do tax duties (import VAT is levied on
+      # the duty in most regimes) pass their own item list.
+      #
+      # Each set is read through a fresh scope rather than the cached
+      # association: recalculation runs after adjusters have just written
+      # fees, and an association loaded earlier in the same request (empty at
+      # order creation, typically) would leave those rows untaxed.
+      #
+      # @return [Array<Spree::LineItem, Spree::Fulfillment, Spree::Fee>]
+      def taxable_items
+        line_items.reload.to_a + fulfillments.reload.to_a + fees.where.not(kind: 'duty').to_a
+      end
+
+      # The buyer's tax registration to compute against: a checkout-time
+      # override first, then the customer's own. Nil means treat the sale as a
+      # consumer sale, which is the legally safe default — charging normal tax
+      # to an unidentified buyer is a presumption EU law explicitly protects.
+      #
+      # A completed order reads its own frozen snapshot instead of resolving
+      # again, so its tax can still be explained after the customer edits or
+      # withdraws the registration.
+      #
+      # A business customer's own registration outranks the buyer's, because the
+      # invoice is addressed to the entity rather than the person who placed the
+      # order. Among a customer's registrations a verified one wins, then the
+      # most recent — a plain fallback chain, which is why this is an
+      # overridable method rather than a Dependencies seam.
+      #
+      # @return [Spree::TaxIdentifier, nil]
+      def resolved_tax_identifier
+        return tax_identifier if is_a?(Spree::Order) && completed?
+
+        tax_identifier || company_tax_identifier || customer_tax_identifier
+      end
+
+      def tax_total
+        included_tax_total + additional_tax_total
+      end
+
+      # Sum of all line item amounts pre-tax
+      def pre_tax_item_amount
+        line_items.sum(:pre_tax_amount)
+      end
+
+      # Sum of all line item and fulfillment amounts pre-tax
+      def pre_tax_total
+        pre_tax_item_amount + fulfillments.sum(:pre_tax_amount)
+      end
+
+      private
+
+      # The resolver is swappable, so what it returns is host code. An entry
+      # whose per-line overrides cannot name their line is not a narrower claim
+      # but a wider one — the provider would read it as the whole order being
+      # exempt — so it is dropped rather than trusted. Charging tax is the safe
+      # direction: under-exempting surfaces as a customer query, over-exempting
+      # is tax the merchant owes and never collected.
+      def usable_exemptions
+        resolved = Array(Spree.tax_resolve_exemptions_service.new.call(order: self).value)
+
+        resolved.select do |exemption|
+          next true unless exemption.respond_to?(:valid?)
+          next true if exemption.valid?
+
+          Rails.error.report(
+            Spree::Tax::UnusableExemptionError.new(
+              "Discarded an unusable tax exemption: #{exemption.errors.full_messages.to_sentence}"
+            ),
+            handled: true,
+            context: { order_id: id, reason_code: exemption.try(:reason_code) },
+            source: 'spree.core'
+          )
+          false
+        end
+      end
+
+      # Read through the legal entity, never the node — a division holds no
+      # registrations of its own.
+      def company_tax_identifier
+        best_of(company_legal_entity&.tax_identifiers)
+      end
+
+      def customer_tax_identifier
+        best_of(customer&.tax_identifiers)
+      end
+
+      def best_of(identifiers)
+        identifiers = identifiers.to_a
+        identifiers.find(&:verified?) || identifiers.max_by(&:created_at)
+      end
+    end
+  end
+end

data/app/models/concerns/spree/purchase/totals.rb

@@ -0,0 +1,116 @@
+module Spree
+  module Purchase
+    # Money readers shared by Spree::Cart and Spree::Order. The raw
+    # +outstanding_balance+ stays host-specific on purpose: an order nets
+    # reimbursement payouts and inverts on cancellation, a cart is plain
+    # total minus payments.
+    module Totals
+      # @return [Integer] total units across line items
+      def quantity
+        line_items.sum(:quantity)
+      end
+
+      # @return [BigDecimal]
+      def amount
+        line_items.sum(BigDecimal('0'), &:amount)
+      end
+
+      # Re-sums what the customer has actually paid, and nothing else. A
+      # payment settling moves only the payment side of the ledger — item
+      # and delivery money is the totals workflow's business, and
+      # re-deriving it here would overwrite figures a caller set
+      # deliberately.
+      #
+      # Shared by Cart and Order: both carry payment_total, and payments
+      # settle on a cart during checkout.
+      #
+      # @return [BigDecimal] the persisted payment_total
+      def refresh_payment_total!
+        # One atomic statement: the sum and the write have to be a single
+        # step, or two handlers settling different payments interleave and
+        # the older one writes its smaller total last, leaving the record
+        # short-paid with no further event coming to correct it.
+        #
+        # Deliberately not with_lock, which refuses a record carrying
+        # unsaved changes — callers legitimately hold dirty attributes while
+        # a payment is destroyed (cart teardown, order merging), and this
+        # must never disturb their in-memory state.
+        settled = settled_payments_arel
+        self.class.where(id: id).update_all(payment_total: settled)
+        self.payment_total = self.class.where(id: id).pick(:payment_total)
+      end
+
+      # @return [Boolean]
+      def outstanding_balance?
+        outstanding_balance != 0
+      end
+
+      # Balance still to collect after applied store credit, never negative.
+      #
+      # @return [BigDecimal]
+      def amount_due
+        [outstanding_balance - total_applied_store_credit, 0].max
+      end
+
+      # @return [Boolean]
+      def paid?
+        total.positive? && payment_total >= total
+      end
+
+      # What has to be paid before this purchase can be placed and
+      # dispatched — the whole total unless an arrangement collects only part
+      # of it up front. See {Spree::Purchases::AmountDueAtCheckout}, which is
+      # where a deposit or net terms would answer differently.
+      #
+      # @return [BigDecimal]
+      def amount_due_at_checkout
+        Spree.purchase_amount_due_at_checkout_service.new.call(purchase: self)
+      end
+
+      # Total fulfillment discount applied by promotions, as a positive amount.
+      #
+      # @return [BigDecimal]
+      def fulfillment_discount
+        discounts.for_fulfillments.sum(:amount) * -1
+      end
+
+      private
+
+      # Completed payments less their refunds, as a scalar subquery so the
+      # sum and the write are one statement.
+      #
+      # @return [Arel::Nodes::Grouping]
+      def settled_payments_arel
+        payments_table = Spree::Payment.arel_table
+        refunds_table = Spree::Refund.arel_table
+
+        settled = payments_table.project(payments_table[:id]).
+                  where(payments_table[owner_foreign_key].eq(id)).
+                  where(payments_table[:status].eq('completed'))
+
+        captured = payments_table.project(payments_table[:amount].sum).
+                   where(payments_table[owner_foreign_key].eq(id)).
+                   where(payments_table[:status].eq('completed'))
+
+        refunded = refunds_table.project(refunds_table[:amount].sum).
+                   where(refunds_table[:payment_id].in(settled))
+
+        Arel::Nodes::NamedFunction.new(
+          'COALESCE',
+          [
+            Arel::Nodes::Subtraction.new(
+              Arel::Nodes::NamedFunction.new('COALESCE', [Arel::Nodes::Grouping.new(captured), Arel.sql('0')]),
+              Arel::Nodes::NamedFunction.new('COALESCE', [Arel::Nodes::Grouping.new(refunded), Arel.sql('0')])
+            ),
+            Arel.sql('0')
+          ]
+        )
+      end
+
+      # @return [Symbol] the column payments use to point at this record
+      def owner_foreign_key
+        is_a?(Spree::Cart) ? :cart_id : :order_id
+      end
+    end
+  end
+end

data/app/models/concerns/spree/purchase/validations.rb

@@ -0,0 +1,45 @@
+module Spree
+  module Purchase
+    # Column-level validations shared by Spree::Cart and Spree::Order: the
+    # money-column battery and item counts. Email validation stays
+    # host-specific (orders require one via require_email; carts validate
+    # shape only, with presence enforced by Checkout::Requirements) — as do
+    # the order-only status inclusions.
+    module Validations
+      extend ActiveSupport::Concern
+
+      MONEY_THRESHOLD  = 100_000_000
+      MONEY_VALIDATION = {
+        presence: true,
+        numericality: {
+          greater_than: -MONEY_THRESHOLD,
+          less_than: MONEY_THRESHOLD,
+          allow_blank: true
+        },
+        format: { with: /\A-?\d+(?:\.\d{1,2})?\z/, allow_blank: true }
+      }.freeze
+
+      POSITIVE_MONEY_VALIDATION = MONEY_VALIDATION.deep_dup.tap do |validation|
+        validation.fetch(:numericality)[:greater_than_or_equal_to] = 0
+      end.freeze
+
+      NEGATIVE_MONEY_VALIDATION = MONEY_VALIDATION.deep_dup.tap do |validation|
+        validation.fetch(:numericality)[:less_than_or_equal_to] = 0
+      end.freeze
+
+      included do
+        validates :total_quantity, presence: true,
+                                   numericality: { greater_than_or_equal_to: 0, less_than: 2**31, only_integer: true, allow_blank: true }
+
+        validates :item_total,           POSITIVE_MONEY_VALIDATION
+        validates :adjustment_total,     MONEY_VALIDATION
+        validates :included_tax_total,   POSITIVE_MONEY_VALIDATION
+        validates :additional_tax_total, POSITIVE_MONEY_VALIDATION
+        validates :payment_total,        MONEY_VALIDATION
+        validates :delivery_total,       MONEY_VALIDATION
+        validates :discount_total,       NEGATIVE_MONEY_VALIDATION
+        validates :total,                MONEY_VALIDATION
+      end
+    end
+  end
+end

data/app/models/concerns/spree/receivable.rb

@@ -0,0 +1,103 @@
+module Spree
+  # What a purchase order and a stock transfer have in common: lines that
+  # promise a quantity, deliveries that bring some of it, and a status that
+  # says how far along that is.
+  module Receivable
+    extend ActiveSupport::Concern
+
+    OPEN_STATUSES = %w[draft ready_to_ship ordered in_transit partially_received].freeze
+    CLOSED_STATUSES = %w[received over_received canceled].freeze
+    # The statuses in which a document's awaited units are on their way — and
+    # so count toward the destination's `incoming_count`. A draft or a packed
+    # box is not moving yet.
+    INCOMING_STATUSES = %w[ordered in_transit partially_received].freeze
+
+    included do
+      has_many :stock_receipts, as: :receivable, class_name: 'Spree::StockReceipt',
+                                inverse_of: :receivable, dependent: :destroy
+
+      scope :open, -> { where(status: OPEN_STATUSES & statuses) }
+      scope :closed, -> { where(status: CLOSED_STATUSES & statuses) }
+      scope :incoming, -> { where(status: INCOMING_STATUSES & statuses) }
+
+      validate :items_name_distinct_variants
+    end
+
+    def items_count
+      items.size
+    end
+
+    def quantity_expected_total
+      items.sum(&:quantity_expected)
+    end
+
+    def quantity_received_total
+      items.sum { |item| item.quantity_received.to_i }
+    end
+
+    def quantity_rejected_total
+      items.sum { |item| item.quantity_rejected.to_i }
+    end
+
+    # Whether any line is still owed units.
+    #
+    # @return [Boolean]
+    def short?
+      items.any?(&:under_received?)
+    end
+
+    # Whether any line took in more than it expected.
+    #
+    # @return [Boolean]
+    def over?
+      items.any?(&:over_received?)
+    end
+
+    def fully_received?
+      items.any? && !short?
+    end
+
+    # Where a delivery leaves the document: over-receipt outranks a shortfall
+    # elsewhere, because the extra units are already on the shelf and nothing
+    # further can be expected once the supplier has sent more than was asked.
+    #
+    # @return [String]
+    def status_after_receive
+      return 'over_received' if over?
+
+      fully_received? ? 'received' : 'partially_received'
+    end
+
+    def open?
+      OPEN_STATUSES.include?(status)
+    end
+
+    # Whether the units still awaited are on their way, and so counted as
+    # incoming at the destination.
+    #
+    # @return [Boolean]
+    def incoming?
+      INCOMING_STATUSES.include?(status)
+    end
+
+    def closed?
+      CLOSED_STATUSES.include?(status)
+    end
+
+    # Closed by the merchant with units still owed, rather than by a delivery.
+    #
+    # @return [Boolean]
+    def closed_short?
+      closed_short_at.present?
+    end
+
+    private
+
+    def items_name_distinct_variants
+      variant_ids = items.reject(&:marked_for_destruction?).filter_map(&:variant_id)
+      return if variant_ids.uniq.size == variant_ids.size
+
+      errors.add(:items, :duplicate_variant, message: Spree.t('errors.messages.duplicate_variant'))
+    end
+  end
+end

data/app/models/concerns/spree/receivable_item.rb

@@ -0,0 +1,78 @@
+module Spree
+  # A line on a purchase order or a stock transfer: one variant, a promised
+  # quantity, and the running totals of what deliveries have brought.
+  module ReceivableItem
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Names the column holding what the line promised: `quantity_ordered` on
+      # a purchase order line, `quantity_shipped` on a transfer line.
+      def expects_quantity_in(attribute)
+        class_attribute :expected_quantity_attribute, default: attribute.to_sym,
+                                                      instance_writer: false
+      end
+    end
+
+    included do
+      belongs_to :variant, -> { with_deleted }, class_name: 'Spree::Variant'
+      has_many :stock_receipt_items, as: :line, class_name: 'Spree::StockReceiptItem',
+                                     inverse_of: :line, dependent: :destroy
+
+      validates :quantity_received, :quantity_rejected, numericality: {
+        greater_than_or_equal_to: 0, only_integer: true
+      }
+
+      delegate :name, :sku, to: :variant, prefix: true, allow_nil: true
+      delegate :thumbnail, to: :variant, allow_nil: true
+    end
+
+    # How many units this line promised.
+    #
+    # @return [Integer]
+    def quantity_expected
+      public_send(self.class.expected_quantity_attribute).to_i
+    end
+
+    # Units that count against the promise. A supplier's promise is met by
+    # units the dock accepts — refused goods go back and are still owed. A
+    # transfer overrides this: its promise is met by units that arrived at
+    # all, since the damaged ones are not in the van any more.
+    #
+    # @return [Integer]
+    def quantity_settled
+      quantity_received.to_i
+    end
+
+    # Units still owed. Never below zero: anything above the promise is
+    # `quantity_over`, not a negative debt.
+    #
+    # @return [Integer]
+    def outstanding
+      [quantity_expected - quantity_settled, 0].max
+    end
+
+    # Units that arrived beyond what was promised.
+    #
+    # @return [Integer]
+    def quantity_over
+      [quantity_settled - quantity_expected, 0].max
+    end
+
+    # Units still on their way. Not `outstanding`: on a purchase order settled
+    # means received, so outstanding keeps counting units the dock refused,
+    # and those never arrive.
+    #
+    # @return [Integer]
+    def incoming
+      [quantity_expected - quantity_received.to_i - quantity_rejected.to_i, 0].max
+    end
+
+    def under_received?
+      outstanding.positive?
+    end
+
+    def over_received?
+      quantity_over.positive?
+    end
+  end
+end

data/app/models/concerns/spree/refund_methods.rb

@@ -0,0 +1,19 @@
+module Spree
+  # The ways money goes back to a customer on a post-sale record.
+  #
+  # A closed set, unlike claim types: each value picks a different code path —
+  # `store_credit` is an internal ledger write inside the status transaction,
+  # `original_payment` is a gateway call outside it. An unrecognised value
+  # would otherwise fall through the `internal_refund?` branch to the gateway,
+  # moving money by a route the caller did not ask for, so the workflows that
+  # accept one reject anything not listed here.
+  module RefundMethods
+    METHODS = %w[original_payment store_credit].freeze
+
+    # @param value [String, Symbol, nil]
+    # @return [Boolean]
+    def self.valid?(value)
+      METHODS.include?(value.to_s)
+    end
+  end
+end

data/app/models/concerns/spree/sanitizable_rich_text.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Spree
+  # Sanitizes rich text attributes through {Spree::RichTextSanitizer} before
+  # they hit the database, covering every writer path that ends in a save
+  # (Admin API, CSV import, console, translations upsert).
+  #
+  # Callback-bypassing writes — +update_columns+, +update_all+, raw SQL — are
+  # NOT covered by design; call {Spree::RichTextSanitizer.sanitize} explicitly
+  # when writing rich text through those paths.
+  module SanitizableRichText
+    extend ActiveSupport::Concern
+
+    included do
+      # Which attributes on this class hold rich text. Lets callers that need
+      # to search stored markup — the media library's "where is this file
+      # used" — find the columns without hardcoding a list that goes stale the
+      # moment a model gains a field.
+      class_attribute :spree_rich_text_attributes, instance_writer: false, default: [].freeze
+    end
+
+    # Every model declaring rich text, with the attributes it declared.
+    #
+    # Walks descendants of the base class rather than keeping a registry: a
+    # registry populated at class-definition time is empty under Rails' lazy
+    # loading until something references each model.
+    #
+    # @return [Hash{Class => Array<String>}]
+    def self.declaring_models
+      Spree.base_class.descendants.each_with_object({}) do |model, found|
+        next if model.abstract_class?
+        next unless model.respond_to?(:spree_rich_text_attributes)
+
+        attributes = model.spree_rich_text_attributes
+        found[model] = attributes if attributes.present?
+      end
+    end
+
+    class_methods do
+      # Declares a rich text attribute: sanitized on save, and readable as
+      # +field_html+ for the raw markup. This is what a model wants.
+      #
+      #   has_spree_rich_text :description
+      #
+      # A translated attribute needs the same declaration on the +Translation+
+      # class, because Mobility writes bypass the parent's callbacks — but only
+      # to sanitize, since the reader belongs on the parent:
+      #
+      #   self::Translation.class_eval do
+      #     include Spree::SanitizableRichText
+      #     sanitizes_rich_text :description
+      #   end
+      #
+      # @param attributes [Array<Symbol>] rich text attribute names
+      # @return [void]
+      def has_spree_rich_text(*attributes)
+        sanitizes_rich_text(*attributes)
+        rich_text_html_reader(*attributes)
+      end
+
+      # Installs a +before_save+ pass sanitizing each named attribute. Only
+      # attributes that actually changed are rewritten, so unrelated saves
+      # never touch stored content.
+      #
+      # Prefer {#has_spree_rich_text} — reach for this alone only where the
+      # +field_html+ reader doesn't belong, i.e. on a Mobility +Translation+
+      # class or a model that serializes the value some other way.
+      #
+      # @param attributes [Array<Symbol>] rich text attribute names
+      # @return [void]
+      def sanitizes_rich_text(*attributes)
+        attributes = attributes.map(&:to_s)
+
+        if respond_to?(:spree_rich_text_attributes)
+          # Union, not assignment — a decorator declaring one more field must
+          # not drop what the class already declared.
+          self.spree_rich_text_attributes = (spree_rich_text_attributes | attributes).freeze
+        end
+
+        before_save do
+          attributes.each do |attribute|
+            next unless will_save_change_to_attribute?(attribute)
+
+            value = self[attribute]
+            next if value.blank?
+
+            self[attribute] = Spree::RichTextSanitizer.sanitize(value)
+          end
+        end
+      end
+
+      # Defines +field_html+, the raw stored markup. The API exposes it beside
+      # the plain +field+, which serializers render as text — writes use the
+      # plain name, since the value is HTML either way.
+      #
+      # Reads through the attribute's own reader rather than +self[]+, so a
+      # translated field still goes through Mobility and resolves against the
+      # active locale.
+      #
+      # @param attributes [Array<Symbol>] rich text attribute names
+      # @return [void]
+      def rich_text_html_reader(*attributes)
+        attributes.each do |attribute|
+          define_method(:"#{attribute}_html") { public_send(attribute).to_s }
+        end
+      end
+    end
+  end
+end

data/app/models/concerns/spree/search_indexable.rb

@@ -29,7 +29,10 @@ module Spree
     #   => { id: 1, name: "Shirt", price_USD: 19.99, ... }
     def search_presentation(store = nil)
       store ||= Spree::Current.store
-      Spree::Dependencies.search_product_presenter_class.new(self, store).call
+      presenter_class = Spree::Dependencies.search_product_presenter_class
+      raise Spree::DependencyError, 'No search product presenter is configured. Install a search provider gem (e.g. spree_meilisearch) or set Spree::Dependencies.search_product_presenter.' if presenter_class.nil?
+
+      presenter_class.new(self, store).call
     end
 
     # Remove this record from search index synchronously (inline, no job).
@@ -72,7 +75,7 @@ module Spree
     # we use the record's own +store_id+ (Product, Customer, Order, …). The
     # multi-store extension overrides this to fan out across every store the
     # record is attached to. Falling back to +Spree::Store.default+ covers
-    # records like categories/taxonomies that don't have a +store_id+ column.
+    # records that don't have a +store_id+ column at all.
     def store_ids_for_indexing
       return [store_id] if respond_to?(:store_id) && store_id.present?
 

data/app/models/concerns/spree/single_store_resource.rb

@@ -3,6 +3,8 @@ module Spree
     extend ActiveSupport::Concern
 
     included do
+      belongs_to :store, class_name: 'Spree::Store'
+
       before_validation :ensure_store, unless: :store_id?
       validate :ensure_store_association_is_not_changed
 
@@ -17,7 +19,7 @@ module Spree
 
     def ensure_store_association_is_not_changed
       if store_id_changed? && persisted?
-        errors.add(:store, Spree.t('errors.messages.store_association_can_not_be_changed'))
+        errors.add(:store, :store_association_can_not_be_changed, message: Spree.t('errors.messages.store_association_can_not_be_changed'))
       end
     end
   end