spree_core 5.6.0 → 6.0.0.beta1

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

@@ -0,0 +1,258 @@
+module Spree
+  module Purchase
+    # The full address surface shared by Spree::Cart and Spree::Order:
+    # the bill/ship associations and their public aliases, default filling
+    # from the customer's saved addresses, address-row deduplication on
+    # write, ownership-guarded address_id assignment, promotion of checkout
+    # addresses to the customer's defaults, and the ship→bill cloning
+    # predicate. The shipping address is canonical: use_shipping copies it
+    # onto the billing address; the reverse use_billing direction is a
+    # deprecated 6.1-removal bridge. Clone callbacks are wired per model.
+    module Addresses
+      extend ActiveSupport::Concern
+
+      included do
+        belongs_to :bill_address, class_name: 'Spree::Address', optional: true, dependent: :destroy
+        belongs_to :ship_address, class_name: 'Spree::Address', optional: true, dependent: :destroy
+
+        # The writers these generate are shadowed by the hand-written ones
+        # below, which deduplicate address rows. The declarations still earn
+        # their place: ParamsNormalizer reads nested_attributes_options to
+        # rewrite an incoming `ship_address` hash to `ship_address_attributes`,
+        # so dropping them sends a raw hash to the belongs_to writer instead.
+        accepts_nested_attributes_for :bill_address
+        accepts_nested_attributes_for :ship_address
+
+        alias_method :billing_address, :bill_address
+        alias_method :billing_address=, :bill_address=
+        alias_attribute :billing_address_id, :bill_address_id
+        alias_method :shipping_address, :ship_address
+        alias_method :shipping_address=, :ship_address=
+        alias_attribute :shipping_address_id, :ship_address_id
+
+        alias_method :shipping_address_attributes=, :ship_address_attributes=
+        alias_method :billing_address_attributes=, :bill_address_attributes=
+
+        attr_accessor :temporary_address, :use_shipping
+        attr_reader :use_billing
+
+        before_validation :clone_billing_address, if: :use_billing?
+        before_validation :clone_shipping_address, if: :use_shipping?
+      end
+
+      # @return [Boolean]
+      def shipping_eq_billing_address?
+        bill_address == ship_address
+      end
+
+      # Whether checkout must collect a customer shipping address. Selected
+      # delivery methods are the source of truth — their fulfillment
+      # providers decide (digital and pickup deliveries need none). Before
+      # any selection, falls back to the record's merchant-pickup intent and
+      # the items' possible fulfillment types, matched against the store's
+      # configured address-requiring delivery methods.
+      #
+      # @return [Boolean]
+      def shipping_address_required?
+        selected_methods = fulfillments.filter_map(&:delivery_method)
+        return selected_methods.any?(&:requires_address?) if selected_methods.any?
+
+        return false if preferred_stock_location_id.present?
+
+        # An address is needed when any item's profile ships to one —
+        # answered by the profile kind, resolved once per profile.
+        profile_requires_address = Hash.new do |cache, profile|
+          cache[profile] = profile.present? && profile.requires_shipping_address?
+        end
+
+        # Both profile paths are preloaded: the variant's own override, and the
+        # product's for the variants that inherit it.
+        line_items.includes(variant: [:delivery_profile, { product: :delivery_profile }]).any? do |line_item|
+          profile_requires_address[line_item.variant&.resolved_delivery_profile]
+        end
+      end
+
+      # @deprecated The shipping address is canonical — use +use_shipping+ to
+      #   copy it onto the billing address. Removed in 6.1.
+      def use_billing=(value)
+        Spree::Deprecation.warn('use_billing is deprecated and will be removed in Spree 6.1. The shipping address comes first — use use_shipping to copy it onto the billing address.')
+        @use_billing = value
+      end
+
+      # @deprecated See {#use_billing=}; removed in 6.1.
+      # @return [Boolean]
+      def use_billing?
+        use_billing.in?([true, 'true', '1'])
+      end
+
+      # @return [Boolean]
+      def use_shipping?
+        use_shipping.in?([true, 'true', '1'])
+      end
+
+      # Fills any blank bill/ship address from the customer's valid saved
+      # defaults. The ship address is skipped when no physical delivery is
+      # required, so shipping-address validations never fire on digital-only
+      # purchases.
+      #
+      # @return [void]
+      def assign_default_addresses!
+        return unless customer
+
+        self.bill_address = customer.bill_address if !bill_address_id && customer.bill_address&.valid?
+        # Skip the ship address only for all-digital records to avoid
+        # triggering shipping-address validations (an empty record still
+        # gets one — items usually arrive after the address).
+        self.ship_address = customer.ship_address if !ship_address_id && customer.ship_address&.valid? && !digital?
+      end
+
+      # Copies the ship address onto the bill address and promotes it to the
+      # customer's default bill address.
+      #
+      # @return [true]
+      def clone_shipping_address
+        self.bill_address = ship_address if ship_address
+        customer.bill_address = ship_address if should_assign_user_default_address?(ship_address)
+        true
+      end
+
+      # Copies the bill address onto the ship address and promotes it to the
+      # customer's default ship address.
+      #
+      # @deprecated The shipping address is canonical (see {#use_billing=});
+      #   removed in 6.1 together with the use_billing bridge.
+      # @return [true]
+      def clone_billing_address
+        self.ship_address = bill_address if bill_address
+        customer.ship_address = bill_address if should_assign_user_default_address?(bill_address)
+        true
+      end
+
+      # Ownership-guarded writer: the id is applied only when the address is
+      # one this purchase may ship to — the buyer's own book, or the book of
+      # the company it is for. Anything else, including any id on a guest
+      # record, resolves to nil.
+      #
+      # @param id [Integer, String, nil]
+      def bill_address_id=(id)
+        return if bill_address_id == id
+
+        self['bill_address_id'] = selectable_address(id)&.id
+        reset_bill_address
+      end
+
+      # Deduplicating writer: reuses or updates an existing address row when
+      # possible, then promotes the result to the customer's default bill
+      # address.
+      #
+      # @param attributes [Hash, ActionController::Parameters]
+      def bill_address_attributes=(attributes)
+        self.bill_address = update_or_create_address(attributes, guest_row: guest_editable_address(bill_address, ship_address_id))
+        customer.bill_address = bill_address if should_assign_user_default_address?(bill_address)
+      end
+
+      # Ownership-guarded writer — see {#bill_address_id=}.
+      #
+      # @param id [Integer, String, nil]
+      def ship_address_id=(id)
+        return if ship_address_id == id
+
+        self['ship_address_id'] = selectable_address(id)&.id
+        reset_ship_address
+      end
+
+      # Deduplicating writer — see {#bill_address_attributes=}. Quick-checkout
+      # (wallet) addresses are never promoted to defaults, and an unpersisted
+      # quick-checkout address is discarded.
+      #
+      # @param attributes [Hash, ActionController::Parameters]
+      def ship_address_attributes=(attributes)
+        self.ship_address = update_or_create_address(attributes, guest_row: guest_editable_address(ship_address, bill_address_id))
+        customer.ship_address = ship_address if should_assign_user_default_address?(ship_address)
+        self.ship_address = nil if quick_checkout_address?(attributes[:quick_checkout]) && !ship_address.persisted?
+      end
+
+      private
+
+      # The address behind an id a client may select, or nil when the id names
+      # one this purchase has no business shipping to.
+      #
+      # Two books qualify. The buyer's own is the ordinary case. The company's
+      # is the B2B one: a purchase for a node ships to that node's sites, and
+      # to its ancestors' — the same self-and-ancestors chain the node's
+      # default address is prefilled from, so a division can pick the
+      # headquarters address it already inherits.
+      #
+      # Standing is not re-checked here: a cart cannot name a company its
+      # customer lacks standing over, so reaching this point already means the
+      # buyer may act for the node.
+      #
+      # @param id [Integer, String, nil]
+      # @return [Spree::Address, nil]
+      def selectable_address(id)
+        address = ::Spree::Address.find_by(id: id)
+        return nil if address.nil?
+
+        return address if customer_id.present? && address.customer_owned? && address.owner_id == customer_id
+
+        company = resolved_company
+        return nil if company.nil? || address.owner_type != 'Spree::Company'
+
+        company.self_and_ancestors.any? { |node| node.id == address.owner_id } ? address : nil
+      end
+
+      # Reuse never reaches past what the buyer already owns: a signed-in buyer
+      # may name any entry of their own address book, and a guest — who keeps
+      # no book — may only edit the row already in the slot being written.
+      # Every other ownerless row is someone else's cart address or the
+      # snapshot a placed order keeps, and reaching into those would let one
+      # checkout read or rewrite another's address.
+      def update_or_create_address(attributes = {}, guest_row: nil)
+        return if attributes.blank?
+
+        attributes.transform_values!(&:presence)
+        attributes = attributes.to_h.symbolize_keys
+
+        reusable_address = customer ? customer.addresses.find_by(id: attributes[:id]) : guest_row
+
+        if reusable_address&.editable?
+          reusable_address.update(attributes)
+
+          return reusable_address
+        end
+
+        attributes = attributes.except(:id, :updated_at, :created_at)
+        return ::Spree::Address.create(attributes) if customer.nil?
+
+        attributes[:owner] = customer
+
+        ::Spree::Address.find_duplicate(attributes) || ::Spree::Address.create(attributes)
+      end
+
+      # The row a guest write may edit in place rather than replace: the one
+      # already in this slot, which is the only address a guest owns. Editing
+      # it keeps a correction from leaving the row it corrected behind as an
+      # orphan carrying someone's name and street.
+      #
+      # It is left alone while the other slot points at the same row — checkout
+      # shares one row between the two whenever shipping is copied onto billing,
+      # and editing it there would move the parcel as well as the invoice.
+      #
+      # @return [Spree::Address, nil]
+      def guest_editable_address(address, other_slot_address_id)
+        return nil if customer.present? || address.nil? || !address.persisted?
+        return nil if address.owner_id.present? || address.id == other_slot_address_id
+
+        address
+      end
+
+      def quick_checkout_address?(quick_checkout_param)
+        quick_checkout_param.present? ? quick_checkout_param.to_b : false
+      end
+
+      def should_assign_user_default_address?(address)
+        customer.present? && address.present? && address.valid? && address.customer_owner == customer && !address.quick_checkout?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module Spree
+  module Purchase
+    module Channel
+      extend ActiveSupport::Concern
+
+      included do
+        belongs_to :channel, class_name: 'Spree::Channel'
+
+        before_validation :ensure_channel_presence
+      end
+
+      def ensure_channel_presence
+        return if channel_id.present?
+
+        self.channel = store&.default_channel
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+module Spree
+  module Purchase
+    # Data-driven checkout-step introspection for Spree::Cart — computed
+    # from what the cart actually requires (Spree::Checkout::Requirements),
+    # never from a state column. Cart-only: an order is past checkout by
+    # definition. The payment predicates the step list reads
+    # (payment_required?/confirmation_required?) live in
+    # {Spree::Purchase::PaymentProcessing}.
+    module CheckoutSteps
+      # The Registry owns the step vocabulary and applicability — built-in
+      # and registered custom steps alike (see
+      # Spree::Checkout::Registry.base_steps / .register_step).
+      #
+      # @return [Array<String>]
+      def checkout_steps
+        Spree::Checkout::Registry.step_names_for(self)
+      end
+
+      # @param step [String, Symbol]
+      # @return [Boolean]
+      def has_checkout_step?(step)
+        step.present? && checkout_steps.include?(step.to_s)
+      end
+
+      # @param step [String]
+      # @return [Integer] position of the step, 0 when unknown
+      def checkout_step_index(step)
+        checkout_steps.index(step).to_i
+      end
+
+      # Customer-facing checkout step. Completed carts are past checkout;
+      # open ones report the first unmet requirement's step ('cart' —
+      # missing line items — is not customer-facing and reports as
+      # 'address').
+      #
+      # Only a completed cart reports 'complete'. An open cart with nothing
+      # outstanding is not finished, it is ready to be placed, so it waits
+      # on {#final_checkout_step}
+      # @return [String]
+      def current_checkout_step
+        return 'complete' if completed?
+
+        first_unmet = Spree::Checkout::Requirements.new(self).call.first
+        return final_checkout_step if first_unmet.nil?
+
+        step = first_unmet[:step].to_s
+        step == 'cart' ? 'address' : step
+      end
+
+      # @return [String]
+      def final_checkout_step
+        checkout_steps.reject { |step| step == 'complete' }.last || 'address'
+      end
+
+      # Checkout steps before {#current_checkout_step}; never includes
+      # 'complete'.
+      #
+      # @return [Array<String>]
+      def completed_checkout_steps
+        steps = checkout_steps.reject { |step| step == 'complete' }
+        return steps if current_checkout_step == 'complete'
+
+        index = steps.index(current_checkout_step) || 0
+        steps.first(index)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+module Spree
+  module Purchase
+    # Which company node a sale is for, shared by Spree::Cart and
+    # Spree::Order. The purchase points at any node in the tree — buying *for*
+    # a division is pointing at it — and tax reads through the node's legal
+    # entity, never the node itself
+    # (docs/plans/6.0-b2b-companies-and-catalogs.md).
+    module Company
+      extend ActiveSupport::Concern
+
+      included do
+        belongs_to :company, class_name: 'Spree::Company', optional: true
+
+        # Guarded on the model rather than in the controller so every path is
+        # covered — the admin write, the storefront one, and the console.
+        # Companies are store-scoped, so a node from another store would tax
+        # this sale against a business the merchant does not trade as.
+        validate :company_belongs_to_store, if: :company_id_changing?
+        # The storefront's write path is the cart; an order's company arrives
+        # from completion (already validated on the cart) or from staff, whose
+        # authority is the admin credential rather than a membership. A guest
+        # cart has no standing at all, so naming a company on one is refused
+        # outright — company ids are not secrets, and a token-authorized cart
+        # must not be able to claim another business's tax exemptions and
+        # catalog prices.
+        validate :customer_has_standing_over_company,
+                 if: -> { is_a?(Spree::Cart) && company_id_changing? }
+      end
+
+      # @return [Boolean] whether this sale is for a business customer
+      def b2b?
+        resolved_company.present?
+      end
+
+      # The node this sale is for. An explicit choice wins; otherwise a buyer
+      # whose standing in this store resolves to exactly one membership is
+      # unambiguous and resolves to that membership's node.
+      #
+      # A buyer with several memberships resolves to nothing until the cart
+      # says which node it is for — refusing to guess, because guessing would
+      # invoice one business for another's purchase.
+      #
+      # @return [Spree::Company, nil]
+      def resolved_company
+        # A placed order answers from what it was stamped with, never by
+        # resolving again — otherwise adding a buyer to a company months later
+        # would reach back and exempt an order that legitimately charged tax.
+        return company if is_a?(Spree::Order) && completed?
+        return company if company_id.present?
+
+        sole_standing_company
+      end
+
+      # The tax anchor for this sale: the resolved node's nearest
+      # self-or-ancestor legal entity. Registrations and exemption
+      # certificates are always read through it — a division holds none, and
+      # reading the node's own would silently lose the exemption.
+      #
+      # @return [Spree::Company, nil]
+      def company_legal_entity
+        resolved_company&.legal_entity
+      end
+
+      private
+
+      def company_id_changing?
+        new_record? ? company_id.present? : will_save_change_to_company_id?
+      end
+
+      def company_belongs_to_store
+        return if company.nil? || store_id.nil?
+        return if company.store_id == store_id
+
+        errors.add(:company, :invalid)
+      end
+
+      def customer_has_standing_over_company
+        return if company.nil?
+        return if customer&.standing_for?(company)
+
+        errors.add(:company, :invalid)
+      end
+
+      # Deliberately not memoized. An instance variable survives #reload, so a
+      # value cached before a membership was added stays stale for the life of
+      # the object — which silently dropped the company at completion. Caching
+      # this safely needs the reset-on-reload machinery; the repeated query is
+      # the cheaper problem.
+      def sole_standing_company
+        return nil if store_id.nil?
+
+        Spree::Company.sole_standing_for(store: store, customer: customer)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module Spree
+  module Purchase
+    module Currency
+      extend ActiveSupport::Concern
+
+      included do
+        validates :currency, presence: true
+        validate :currency_must_be_supported_by_store
+
+        before_validation :ensure_currency
+      end
+
+      def currency_must_be_supported_by_store
+        return if currency.blank? || store.blank?
+
+        supported_codes = store.supported_currencies_list.map(&:iso_code)
+        unless supported_codes.include?(currency)
+          errors.add(:currency, :currency_not_supported_by_store, message: Spree.t(:currency_not_supported_by_store))
+        end
+      end
+
+      def ensure_currency
+        return if currency.present?
+
+        self.currency = market&.currency
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+module Spree
+  module Purchase
+    # Digitality predicates over line items, shared by Spree::Cart and
+    # Spree::Order (fulfillment-side digital delivery stays order-only in
+    # Spree::Order::Digital).
+    module DigitalItems
+      # @return [Boolean] true when every line item is digital
+      def digital?
+        if total_quantity.zero? || line_items.empty?
+          false
+        else
+          line_items.includes(variant: :product).all?(&:digital?)
+        end
+      end
+
+      # @return [Boolean] true when any line item is digital
+      def some_digital?
+        if total_quantity.zero? || line_items.empty?
+          false
+        else
+          line_items.includes(variant: :product).any?(&:digital?)
+        end
+      end
+
+      # @return [Boolean] true when any line item has digital assets
+      def with_digital_assets?
+        if total_quantity.zero? || line_items.empty?
+          false
+        else
+          line_items.includes(:variant).any?(&:with_digital_assets?)
+        end
+      end
+
+      # @return [ActiveRecord::Relation<Spree::LineItem>]
+      def digital_line_items
+        line_items.joins(:variant).with_digital_assets.distinct
+      end
+
+      # One query rather than one per line item — this is read for every
+      # digital order's email. `reorder(nil)` drops the line-item default order:
+      # PostgreSQL rejects SELECT DISTINCT ordered by a column that is not in
+      # the select list, and ordering a subquery buys nothing anyway.
+      #
+      # @return [ActiveRecord::Relation<Spree::DigitalLink>]
+      def digital_links
+        Spree::DigitalLink.where(line_item_id: digital_line_items.reorder(nil).select(:id))
+      end
+
+      # Whether the customer must choose a delivery option in checkout —
+      # shipping and both pickup kinds are chosen; digital fulfillments are
+      # created by their provider without a selection. Delivery itself
+      # happens for all of them.
+      #
+      # @return [Boolean]
+      def delivery_step_required?
+        line_items.any? && !digital?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+module Spree
+  module Purchase
+    # The logistics rollup a freight forwarder quotes against — units,
+    # cartons, pallets, cubic meters and gross weight — shared by
+    # Spree::Cart and Spree::Order.
+    #
+    # Read only from what the freight provider froze onto the rates a
+    # purchase ships under, never derived from the live catalog. Until a
+    # freight rate is selected there is nothing to report, and a purchase
+    # that ships by parcel reports nothing at all: a parcel carrier does not
+    # read cubic meters. Once quoted, a carton size corrected next month must
+    # not rewrite what this container held. Same doctrine as the duty
+    # snapshot (docs/plans/6.0-duties-and-custom-fees.md).
+    module Freight
+      extend ActiveSupport::Concern
+
+      # @return [Spree::FreightSummary, nil] nil unless a selected rate
+      #   carries a frozen summary
+      def freight_summary
+        return @freight_summary if defined?(@freight_summary)
+
+        summary = build_freight_summary
+        # Assigned on every path, including the empty one: every retail
+        # purchase answers "nothing", and a conditional assignment would leave
+        # that case unmemoized — querying the fulfillments again on each call,
+        # which is the opposite of what memoizing is for.
+        @freight_summary = (summary unless summary.nil? || summary.empty?)
+      end
+
+      # Dropped on reload, so a purchase whose rate selection changed in the
+      # same request reads again rather than answering from the load it had
+      # before.
+      def reload(*)
+        remove_instance_variable(:@freight_summary) if defined?(@freight_summary)
+        super
+      end
+
+      private
+
+      # Only the consignments actually shipping: a canceled fulfillment keeps
+      # its frozen summary, so counting it would report a re-allocated load
+      # twice. Two freight consignments are still one load to the forwarder,
+      # so they are merged rather than listed.
+      def build_freight_summary
+        summaries = fulfillments.valid.filter_map { |fulfillment| fulfillment.selected_delivery_rate&.freight_summary }
+        return if summaries.empty?
+
+        Spree::FreightSummary.merge(summaries)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+module Spree
+  module Purchase
+    # Gift-card application surface shared by Spree::Cart and Spree::Order.
+    # One gift card can be used on many carts/orders, until it runs out.
+    module GiftCards
+      extend ActiveSupport::Concern
+
+      included do
+        belongs_to :gift_card, class_name: 'Spree::GiftCard', optional: true
+
+        money_methods :gift_card_total
+      end
+
+      # The amount of the gift card applied to this record.
+      #
+      # @return [BigDecimal]
+      def gift_card_total
+        return 0.to_d unless gift_card.present?
+
+        store_credit_ids = payments.store_credits.valid.pluck(:source_id)
+        Spree::StoreCredit.where(id: store_credit_ids, originator: gift_card).sum(:amount)
+      end
+
+      def total_minus_gift_cards
+        total - gift_card_total
+      end
+
+      # @param gift_card [Spree::GiftCard]
+      def apply_gift_card(gift_card)
+        Spree.gift_card_apply_workflow.call(gift_card: gift_card, order: self)
+      end
+
+      def remove_gift_card
+        Spree.gift_card_remove_workflow.call(order: self)
+      end
+
+      # @return [Spree::ServiceModule::Result, nil] the caller decides what a
+      #   refusal means; Orders::Complete reports it rather than failing the
+      #   order, since the card was already drawn down when it was applied.
+      def redeem_gift_card
+        return unless gift_card.present?
+
+        Spree.gift_card_redeem_workflow.call(gift_card: gift_card)
+      end
+
+      # In-lock read-compute-write keeping the gift-card payment amount in
+      # sync with the current total. Updates the payment in place instead
+      # of remove + re-apply to avoid creating invalid payment records.
+      def recalculate_gift_card
+        return unless gift_card.present?
+
+        payment = payments.checkout.store_credits.where(source: gift_card.store_credits).first
+        return unless payment
+
+        gift_card.with_lock do
+          new_amount = [gift_card.amount_remaining + payment.amount, total].min
+          next if payment.amount == new_amount
+
+          difference = new_amount - payment.amount
+          # update_column bypasses Payment#max_amount validation which can
+          # fail on stale in-memory state; bounds enforced via min() above.
+          payment.update_column(:amount, new_amount)
+          payment.source.update_column(:amount, new_amount)
+          gift_card.amount_used += difference
+          gift_card.save!
+        end
+      end
+    end
+  end
+end