spree_core 5.6.0 → 6.0.0.beta1

data/app/workflows/spree/carts/recalculate_totals.rb

@@ -0,0 +1,233 @@
+module Spree
+  module Carts
+    # Money recalculation — item counts, money totals, one update_columns
+    # persist. Money ONLY: payment_status/fulfillment_status are written
+    # exclusively by Spree::Orders::UpdateStatuses, and completed-order
+    # fulfillment repricing belongs to the explicit post-placement edit
+    # path, never to a totals refresh.
+    #
+    # Completed orders are money-frozen one level down: their typed rows
+    # (discounts, fees, tax lines) are never regenerated — no promotion
+    # competition, no tax estimation — but the denormalized sums are always
+    # re-derived from the rows. That makes this the single totals seam for
+    # both live checkout math and post-placement edits (the admin
+    # tax_lines/discounts/fees endpoints write rows directly, then run
+    # this).
+    class RecalculateTotals < Spree::Workflow
+      hooks :set_tax_line_context
+
+      # Untyped provider extras contributed by set_tax_line_context handlers —
+      # anything a specific provider needs that the typed estimate arguments
+      # don't carry. Exemptions and the buyer's tax identity are NOT this: they
+      # are typed inputs of their own. Nil until the typed rows are regenerated.
+      attr_reader :tax_line_context
+
+      # @param cart [Spree::Cart, Spree::Order]
+      # @param resum_only [Boolean] re-sum the rows the record already carries
+      #   without regenerating them. A placed order is frozen by its own
+      #   lifecycle, but an order can also hold rows that must not be
+      #   re-derived before it is placed — the seller split moves already-costed
+      #   rows onto child orders that are still drafts, and re-running the
+      #   promotion and tax engines against one seller's subset would answer a
+      #   question the checkout already answered against the whole basket.
+      def perform(cart:, resum_only: false)
+        super
+
+        step :reset_association_caches
+        step :update_item_count
+        step :refresh_money_inputs
+        step :regenerate_typed_rows unless money_frozen?
+        step :fold_typed_rows
+        step :refresh_grand_total
+        step :persist_totals
+
+        success(cart)
+      end
+
+      private
+
+      # An earlier recalculation on this instance may have loaded the
+      # associations mid-mutation.
+      def reset_association_caches
+        return unless cart.persisted?
+
+        cart.association(:line_items).reset
+        cart.association(:fulfillments).reset
+      end
+
+      def update_item_count
+        cart.total_quantity = cart.line_items.sum(:quantity)
+      end
+
+      # Two passes: adjusters persist the discounted taxable base first,
+      # then tax is estimated on it.
+      def regenerate_typed_rows
+        Spree.adjusters.each { |adjuster| adjuster.adjust(cart) }
+        refresh_discount_and_fee_columns
+        @tax_line_context = run_hooks :set_tax_line_context
+        cart.tax_provider.estimate(cart, **cart.tax_estimate_inputs, context: tax_line_context)
+      end
+
+      # Re-derives the denormalized per-adjustable columns and the record's
+      # own sums from the typed rows — safe on frozen orders, where the
+      # rows are the source of truth.
+      def fold_typed_rows
+        refresh_discount_and_fee_columns if money_frozen?
+        refresh_tax_columns
+
+        discounts_sum = cart.discounts.reload.sum(&:amount)
+        fees = cart.fees.reload.to_a
+        tax_sums = cart.tax_lines.reload.group_by(&:included?).transform_values { |lines| lines.sum(&:amount) }
+
+        cart.discount_total = cart.discounts.select(&:promotion?).sum(&:amount)
+        cart.fee_total = fees.sum(&:amount)
+        cart.included_tax_total = tax_sums.fetch(true, 0)
+        cart.additional_tax_total = tax_sums.fetch(false, 0)
+        cart.adjustment_total = discounts_sum + cart.fee_total + cart.additional_tax_total
+        refresh_commission_totals
+
+        # The record's own adjustable columns cover order-level rows only:
+        # discounts distribute to line items, so fees are the only residents.
+        cart.taxable_adjustment_total = 0
+        cart.non_taxable_adjustment_total = fees.select(&:order_level?).sum(&:amount)
+      end
+
+      # What the marketplace earned on this sale, re-summed from the order's
+      # commission lines.
+      #
+      # Deliberately outside adjustment_total and the grand total: a
+      # commission is charged to the seller, not to the shopper, so it is
+      # reported beside what the customer owes and never added to it. Carts
+      # never carry commission — it is written once the order is placed.
+      #
+      # Kept in three parts because the tax is separately reportable: the
+      # platform files it as output tax and the seller reclaims it as input
+      # tax, and neither figure can be recovered from the gross alone.
+      #
+      # The gross is added up from the two parts rather than summed from the
+      # rows' own `total`, so the three columns always agree. They need not
+      # otherwise: a line rounds to its currency's precision (three places for
+      # KWD and its neighbours) while every column is scale 2, and the parts
+      # and the gross each round independently on the way in.
+      def refresh_commission_totals
+        return unless cart.is_a?(Spree::Order)
+
+        lines = cart.commission_lines.reload.to_a
+        cart.commission_amount_total = lines.sum(&:amount)
+        cart.commission_tax_total = lines.sum(&:tax_amount)
+        cart.commission_total = cart.commission_amount_total + cart.commission_tax_total
+      end
+
+      # Runs before the adjusters: promotion-rule eligibility (item-total
+      # thresholds, free shipping) reads these attributes, so they must
+      # reflect the current line items — not the previous recalculation.
+      def refresh_money_inputs
+        cart.payment_total = paid_so_far
+        cart.item_total = cart.line_items.to_a.sum(&:amount)
+        cart.delivery_total = cart.fulfillments.to_a.sum(&:cost)
+      end
+
+      # What has actually been paid towards this record.
+      #
+      # An order placed in a split checkout owns no payments — the customer
+      # paid once, against the group — so its position is the sum of its
+      # shares. Reading its own payments would persist nothing paid and report
+      # the whole total as outstanding.
+      #
+      # @return [BigDecimal]
+      def paid_so_far
+        if cart.is_a?(Spree::Order) && cart.grouped?
+          return cart.payment_splits.to_a.sum(&:net_captured_amount)
+        end
+
+        cart.payments.completed.includes(:refunds).inject(0) do |sum, payment|
+          sum + payment.amount - payment.refunds.sum(:amount)
+        end
+      end
+
+      def refresh_grand_total
+        cart.total = cart.item_total + cart.delivery_total + cart.adjustment_total
+      end
+
+      def persist_totals
+        columns = {
+          item_total: cart.item_total,
+          total_quantity: cart.total_quantity,
+          adjustment_total: cart.adjustment_total,
+          included_tax_total: cart.included_tax_total,
+          additional_tax_total: cart.additional_tax_total,
+          taxable_adjustment_total: cart.taxable_adjustment_total,
+          non_taxable_adjustment_total: cart.non_taxable_adjustment_total,
+          payment_total: cart.payment_total,
+          delivery_total: cart.delivery_total,
+          discount_total: cart.discount_total,
+          fee_total: cart.fee_total,
+          total: cart.total,
+          updated_at: Time.current
+        }
+        if cart.is_a?(Spree::Order)
+          columns[:commission_amount_total] = cart.commission_amount_total
+          columns[:commission_tax_total] = cart.commission_tax_total
+          columns[:commission_total] = cart.commission_total
+        end
+        cart.update_columns(columns)
+      end
+
+      def money_frozen?
+        resum_only || (cart.is_a?(Spree::Order) && cart.completed?)
+      end
+
+      # Pass one of the two-pass recalculation: persist per-adjustable
+      # discount and fee sums so the tax provider estimates on the
+      # discounted base.
+      def refresh_discount_and_fee_columns
+        discounts = cart.discounts.reload.to_a
+        fees = cart.fees.reload.to_a
+
+        each_adjustable do |adjustable, key|
+          rows = discounts.select { |row| row.public_send(key) == adjustable.id }
+          fee_rows = fees.select { |row| row.public_send(key) == adjustable.id }
+
+          update_adjustable_columns(
+            adjustable,
+            taxable_adjustment_total: rows.sum(&:amount),
+            non_taxable_adjustment_total: fee_rows.sum(&:amount),
+            discount_total: rows.select(&:promotion?).sum(&:amount)
+          )
+        end
+      end
+
+      # Pass two: fold the freshly estimated (or frozen) tax rows into the
+      # per-adjustable columns.
+      def refresh_tax_columns
+        tax_lines = cart.tax_lines.reload.to_a
+
+        each_adjustable do |adjustable, key|
+          rows = tax_lines.select { |row| row.public_send(key) == adjustable.id }
+          included, additional = rows.partition(&:included?)
+
+          update_adjustable_columns(
+            adjustable,
+            included_tax_total: included.sum(&:amount),
+            additional_tax_total: additional.sum(&:amount),
+            adjustment_total: adjustable.taxable_adjustment_total +
+              adjustable.non_taxable_adjustment_total +
+              additional.sum(&:amount)
+          )
+        end
+      end
+
+      def each_adjustable
+        cart.line_items.each { |line_item| yield line_item, :line_item_id }
+        cart.fulfillments.each { |fulfillment| yield fulfillment, :fulfillment_id }
+      end
+
+      def update_adjustable_columns(adjustable, attributes)
+        return unless adjustable.persisted?
+        return if attributes.all? { |key, value| adjustable.public_send(key) == value }
+
+        adjustable.update_columns(attributes.merge(updated_at: Time.current))
+      end
+    end
+  end
+end

data/app/workflows/spree/carts/upsert_items.rb

@@ -0,0 +1,368 @@
+module Spree
+  module Carts
+    # Applies a batch of item changes to a cart in one pass — the single gate
+    # for every item mutation that is not a plain add-increment (bulk
+    # payloads, a quantity edit, a removal). AddItem stays the increment
+    # ("add 2 more"); this workflow SETS quantity, and quantity zero removes.
+    #
+    # Two things make it worth a workflow rather than a loop over AddItem.
+    # Extensions get one veto point covering every non-increment path, and
+    # the cart recalculates ONCE for the whole batch instead of once per
+    # item — the money math is the expensive part, so a dozen items cost
+    # roughly one item's work.
+    #
+    # Rejections are per item, not per batch: a validate handler that vetoes
+    # one line skips that line and the rest still apply, so a customer
+    # restoring a saved cart keeps everything still purchasable and hears
+    # about what was dropped. The skipped items come back as +warnings+
+    # (see Spree::Carts::ItemWarning) beside a successful result.
+    class UpsertItems < Spree::Workflow
+      hooks :validate, :after_items_upserted
+
+      # Readers a :validate handler uses. variant/quantity/metadata describe
+      # the item currently being validated — the same reader names AddItem
+      # exposes, so one handler class registers on both keys unchanged.
+      # +items+ is the whole resolved batch, for rules that need to see it
+      # (a per-order unit cap, a mixed-category restriction).
+      attr_reader :variant, :quantity, :metadata, :items, :warnings
+
+      # @param cart [Spree::Cart, Spree::Order]
+      # @param items [Array<Hash>] :variant_id (prefixed or raw), :quantity,
+      #   :metadata, :price. Quantity defaults to 1; zero or less removes.
+      #   :price is tri-state — absent leaves pricing to the resolver, an
+      #   amount negotiates the line (+price_source: 'manual'+), an explicit
+      #   nil reverts a negotiated line to catalog pricing. Admin surface
+      #   only (draft orders); refused once the order is placed.
+      # @return [Spree::ServiceModule::Result] value is the cart
+      def perform(cart:, items:)
+        super
+        @warnings = []
+
+        step :resolve_items
+        return success(cart) if resolved_items.empty?
+
+        # Before the transaction: both may be external systems, and a database
+        # transaction held open across a network call is how a slow warehouse
+        # becomes a table of stuck locks.
+        external_step :check_availability
+        external_step :resolve_prices
+
+        ApplicationRecord.transaction do
+          step :apply_items
+          step :handle_stock_reservations if cart.in_checkout?
+          step :recalculate, with: -> { Spree.cart_recalculate_workflow } if recalculate?
+          run_hooks :after_items_upserted
+        end
+
+        # Warnings ride on the cart itself — the same channel the
+        # out-of-stock sweep uses — so they reach the serializer without
+        # every caller forwarding them by hand. Set after the reload, which
+        # would otherwise drop them.
+        cart.reload
+        cart.warnings |= warnings.map(&:to_h) if warnings.any?
+
+        success(cart)
+      end
+
+      private
+
+      attr_reader :resolved_items
+
+      # The cart side recalculates here because nothing else will. The order
+      # side overrides this: admin edits run items, fulfillments and coupons
+      # as one pipeline and recalculate once at the end of it.
+      def recalculate?
+        true
+      end
+
+      # A customer restoring a saved cart should keep whatever is still
+      # purchasable, so a bad line becomes a warning. A merchant editing an
+      # order should not: a struck-out or repriced row silently not applying
+      # is worse than the edit failing, so the order twin turns this off.
+      def partial_success?
+        true
+      end
+
+      # One pass for lookup and currency checks, before anything is written,
+      # so a batch naming an unknown variant fails before it has half
+      # applied.
+      def resolve_items
+        store = cart.store || Spree::Current.store
+
+        @resolved_items = Array(items).filter_map do |item_params|
+          item_params = item_params.to_h.deep_symbolize_keys
+          quantity = (item_params[:quantity] || 1).to_i
+          variant = resolve_variant(store, item_params[:variant_id], removing: quantity <= 0)
+          next if variant.nil?
+
+          Spree::Carts::ResolvedItem.new(
+            variant: variant,
+            quantity: quantity,
+            metadata: item_params[:metadata].to_h,
+            price_provided: item_params.key?(:price),
+            price: parse_manual_price(item_params[:price])
+          )
+        end
+
+        # Price overrides are pre-placement only. reject! rather than
+        # failure(cart, message), which would drop the message.
+        if cart.completed? && @resolved_items.any?(&:price_provided)
+          errors.add(:base, :price_override_not_allowed, message: Spree.t('cart_line_item.price_override_not_allowed'))
+          reject!(nil, cart)
+        end
+      end
+
+      # Never coerced — "12,50".to_d is 12, a mispriced order. finite? is not
+      # redundant: BigDecimal parses "NaN"/"Infinity" and neither is negative.
+      #
+      # @param value [Object] raw price from the request
+      # @return [BigDecimal, nil] parsed amount, or nil for an explicit revert
+      def parse_manual_price(value)
+        return nil if value.nil?
+
+        if cart.completed?
+          errors.add(:base, :price_override_not_allowed, message: Spree.t('cart_line_item.price_override_not_allowed'))
+          reject!(nil, cart)
+        end
+
+        parsed = BigDecimal(value.to_s)
+        if parsed.negative? || !parsed.finite?
+          errors.add(:base, :invalid_price, message: Spree.t('cart_line_item.invalid_price'))
+          reject!(nil, cart)
+        end
+
+        parsed
+      rescue ArgumentError
+        errors.add(:base, :invalid_price, message: Spree.t('cart_line_item.invalid_price'))
+        reject!(nil, cart)
+      end
+
+      # Only external inventory is asked here: Spree's own records are already
+      # checked by the line item's availability validator on save, and two
+      # answers that can disagree is worse than one.
+      def check_availability
+        @unsupplyable_variant_ids = Set.new
+        return if cart.store.nil? || cart.store.internal_inventory?
+
+        return if additions.empty?
+
+        result = Spree::Carts::CheckAvailability.call(
+          cart: cart, items: additions.map { |item| { variant: item.variant, quantity: item.quantity } }
+        )
+        failure(cart, result.error) if result.failure?
+
+        @unsupplyable_variant_ids = Array(result.value).map { |variant, _quantity| variant.id }.to_set
+      end
+
+      # One provider round per batch rather than one per line: a fifty-line
+      # cart restore must not become fifty calls to an ERP. Lines arriving
+      # with a negotiated price are not asked about — the caller already
+      # answered; reverts still are, they need the catalog answer back.
+      def resolve_prices
+        priceable = additions.reject(&:manual_price?)
+        return if priceable.empty?
+
+        probes = priceable.map do |item|
+          Spree::Carts::PriceItems.probe(cart: cart, variant: item.variant, quantity: item.quantity)
+        end
+
+        result = Spree::Carts::PriceItems.new.call(cart: cart, line_items: probes)
+        failure(cart, result.error) if result.failure?
+
+        @resolved_prices = Array(result.value).index_by { |probe, _price| probe.variant_id }
+      end
+
+      def additions
+        @additions ||= resolved_items.reject(&:remove?)
+      end
+
+      def apply_resolved_price(line_item)
+        resolution = resolved_prices[line_item.variant_id]
+        return if resolution.blank?
+
+        _probe, price = resolution
+        Spree::Carts::PriceItems.apply([[line_item, price]], persist: false)
+      end
+
+      def resolved_prices
+        @resolved_prices ||= {}
+      end
+
+      # Applies the entry's price directive on top of whatever the resolver
+      # answered: an amount stamps the line manual (and detaches it from any
+      # matched price list), an explicit nil clears the marker and hands the
+      # line back to the resolution already fetched for this batch.
+      def apply_price_directive(item, line_item)
+        return unless item.price_provided
+
+        if item.manual_price?
+          line_item.assign_attributes(
+            price: item.price,
+            price_source: Spree::LineItem::MANUAL_PRICE_SOURCE,
+            price_list_id: nil
+          )
+          # The quantity-change callback must not re-ask the provider for a
+          # price this save already carries.
+          line_item.price_resolved = true
+        else
+          line_item.assign_attributes(price_source: nil, price_list_id: nil)
+          apply_resolved_price(line_item)
+        end
+      end
+
+      def unsupplyable?(item)
+        @unsupplyable_variant_ids.include?(item.variant.id)
+      end
+
+      def apply_items
+        resolved_items.each_with_index do |item, index|
+          next unless validated?(item, index)
+
+          line_item = Spree.line_item_by_variant_finder.new.execute(owner: cart, variant: item.variant)
+
+          if item.remove?
+            line_item&.destroy!
+            next
+          end
+
+          # A provider that already quoted this line is proof the currency is
+          # sellable, even when the local catalog holds no price for it — an
+          # external system can be the only source for a currency. A
+          # negotiated price is a quote too, made by the merchant.
+          if !item.manual_price? && resolved_prices[item.variant.id]&.at(1)&.amount.nil? && item.variant.amount_in(cart.currency).nil?
+            message = Spree.t('cart_line_item.currency_unavailable', li_name: item.variant.name, currency: cart.currency)
+            failure(item.variant, message) unless partial_success?
+
+            warn(index, item, :currency_unavailable, message)
+            next
+          end
+
+          if unsupplyable?(item)
+            message = Spree.t(:selected_quantity_not_available, item: item.variant.name.inspect)
+            failure(item.variant, message) unless partial_success?
+
+            warn(index, item, :selected_quantity_not_available, message)
+            next
+          end
+
+          apply_item(item, line_item, index)
+        end
+      end
+
+      # Dispatches :validate for one item with that item's readers bound, and
+      # converts a handler's rejection into a warning instead of failing the
+      # batch. FailureSignal is what reject! raises; catching it here is the
+      # deliberate difference between this workflow and every other one.
+      def validated?(item, index)
+        bind_current_item(item)
+        # Core behaviour rather than a hook: an agreement's quantity terms are
+        # what the merchant sold. Removals are exempt — a buyer must always be
+        # able to empty a line, whatever the rules now say about holding it.
+        check_quantity_rules(item) unless item.remove?
+        run_hooks :validate
+        true
+      rescue Spree::Workflow::FailureSignal
+        raise unless partial_success?
+
+        rejection = errors
+        @errors = nil
+        warnings << Spree::Carts::ItemWarning.new(
+          item_index: index,
+          variant: item.variant,
+          code: rejection.details.values.flatten.first&.dig(:error) || :rejected,
+          message: rejection.full_messages.to_sentence
+        )
+        false
+      ensure
+        bind_current_item(nil)
+      end
+
+      # This workflow SETS the quantity, so the submitted number is already
+      # the resulting one — no increment to add on.
+      def check_quantity_rules(item)
+        message = cart.quantity_rule_violation(item.variant, item.quantity)
+        return if message.nil?
+
+        # A symbolic type rather than a bare string, so the warning this
+        # becomes carries `quantity_rule_violated` as its code — a client
+        # switching on the code must not be handed the sentence.
+        errors.add(:base, :quantity_rule_violated, message: message)
+        failure(cart, errors)
+      end
+
+      def bind_current_item(item)
+        @variant = item&.variant
+        @quantity = item&.quantity
+        @metadata = item&.metadata || {}
+      end
+
+      def apply_item(item, line_item, index)
+        if line_item
+          line_item.quantity = item.quantity
+          line_item.metadata = line_item.metadata.merge(item.metadata) if item.metadata.present?
+        else
+          line_item = cart.line_items.new(
+            quantity: item.quantity,
+            variant: item.variant,
+            options: { currency: cart.currency }
+          )
+          line_item.metadata = item.metadata if item.metadata.present?
+        end
+
+        created = line_item.new_record?
+        # Before the save, so the resolved price rides the same write and the
+        # quantity-change callback sees the line as already priced.
+        apply_resolved_price(line_item)
+        apply_price_directive(item, line_item)
+
+        # A line that won't save — most often the stock availability
+        # validator — is this item's problem, not the batch's. Failing here
+        # would roll back every other line, which is exactly what a customer
+        # restoring a saved cart must not lose.
+        unless line_item.save
+          failure(line_item) unless partial_success?
+
+          warn(index, item, line_item.errors.details.values.flatten.first&.dig(:error) || :invalid,
+               line_item.errors.full_messages.to_sentence)
+          return
+        end
+
+        line_item.reload
+        return unless created
+
+        # Per-market provider rather than a global one, and carrying the same
+        # typed inputs as a full recalculation so a single new line is taxed
+        # with the buyer's registration and exemptions.
+        owner = line_item.owner
+        owner.tax_provider.estimate(owner, [line_item], **owner.tax_estimate_inputs)
+      end
+
+      def handle_stock_reservations
+        result = Spree::StockReservations::Reserve.call(cart: cart)
+        failure(cart, result.error) if result.failure?
+      end
+
+      # Adds resolve through the store, so a variant belonging to another
+      # tenant is a 404 rather than a cross-store add. Removals resolve
+      # through the cart's own items instead: the line is already there, and
+      # a product that has since been deleted or unpublished has left
+      # store.variants — refusing to remove it would strand the customer
+      # with a line they cannot get rid of.
+      def resolve_variant(store, variant_id, removing: false)
+        return nil if variant_id.blank?
+
+        if removing
+          cart.line_items.detect { |line_item| line_item.variant_id.to_s == variant_id.to_s }&.variant ||
+            Spree::Variant.with_deleted.find_by_param(variant_id)
+        else
+          store.variants.find_by_param(variant_id) ||
+            raise(ActiveRecord::RecordNotFound.new("Variant '#{variant_id}' not found in this store", 'Spree::Variant', 'id', variant_id))
+        end
+      end
+
+      def warn(index, item, code, message)
+        warnings << Spree::Carts::ItemWarning.new(item_index: index, variant: item.variant, code: code, message: message)
+      end
+    end
+  end
+end

data/app/workflows/spree/catalogs/activate.rb

@@ -0,0 +1,51 @@
+module Spree
+  module Catalogs
+    # Puts an agreement into effect: from here its audience sees its
+    # assortment and pays its prices.
+    #
+    # A workflow rather than a column write, so what has to happen alongside —
+    # sweeping a buyer's cached catalog set, telling the companies it covers —
+    # attaches to `after_activate` instead of being scattered across every
+    # caller that flips the flag (docs/plans/6.0-catalog-agreement-rework.md).
+    class Activate < Spree::Workflow
+      hooks :validate, :after_activate
+
+      # @param catalog [Spree::Catalog]
+      # @return [Spree::ServiceModule::Result] value is the catalog
+      def perform(catalog:)
+        super
+
+        step :require_someone_to_apply_to
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :mark_active
+          run_hooks :after_activate
+        end
+
+        success(catalog)
+      end
+
+      private
+
+      # An agreement nobody is assigned to reaches no buyer, so activating it
+      # would change nothing — refused, so the emptiness reads as the mistake
+      # it is rather than as a catalog that quietly does nothing.
+      #
+      # A channel's default catalog is the exception the rule needs: it is
+      # reached through the channel rather than through an assignment, and it
+      # is the whole mechanism behind channel-wide pricing.
+      def require_someone_to_apply_to
+        return if catalog.catalog_assignments.exists?
+        return if Spree::Channel.exists?(default_catalog_id: catalog.id)
+
+        catalog.errors.add(:base, :no_audience)
+        failure(catalog)
+      end
+
+      def mark_active
+        failure(catalog) unless catalog.update(active: true)
+      end
+    end
+  end
+end