spree_core 5.6.1 → 6.0.0.beta1

data/app/services/spree/orders/update_item.rb

@@ -0,0 +1,105 @@
+module Spree
+  module Orders
+    # Draft-order line item update: quantity, metadata and the negotiated
+    # unit price in one place. Recalculates the order only when money moved —
+    # metadata-only edits carry no money impact. Unlike the cart side
+    # (Carts::SetQuantity), drafts hold no checkout stock reservations, so
+    # there is nothing to re-reserve here.
+    #
+    # +price+ is tri-state: not passed leaves pricing alone, an amount
+    # negotiates the line (stamping +price_source: 'manual'+ so nothing
+    # re-prices it), an explicit nil reverts a negotiated line to catalog
+    # pricing through the resolver. Overrides are pre-placement only — a
+    # placed order's money edits stay fees and discounts.
+    class UpdateItem
+      prepend Spree::ServiceModule::Base
+
+      # Distinguishes "price not passed" from the explicit +price: nil+ revert.
+      PRICE_NOT_PROVIDED = Object.new.freeze
+
+      def call(order:, line_item:, quantity: nil, metadata: nil, price: PRICE_NOT_PROVIDED)
+        price_provided = !price.equal?(PRICE_NOT_PROVIDED)
+
+        if price_provided && order.completed?
+          return reject_price(line_item, :price_override_not_allowed, Spree.t('cart_line_item.price_override_not_allowed'))
+        end
+
+        attributes = {}
+        attributes[:quantity] = quantity unless quantity.nil?
+        attributes[:metadata] = metadata unless metadata.nil?
+
+        if price_provided && !price.nil?
+          manual_price = parse_manual_price(price)
+          return reject_price(line_item, :invalid_price, Spree.t('cart_line_item.invalid_price')) if manual_price.nil?
+
+          attributes[:price] = manual_price
+          attributes[:price_source] = Spree::LineItem::MANUAL_PRICE_SOURCE
+          attributes[:price_list_id] = nil
+        end
+
+        quantity_changing = attributes.key?(:quantity) && attributes[:quantity].to_i != line_item.quantity
+        reverting = price_provided && price.nil?
+
+        # The revert consults the pricing provider — a network call for an
+        # external-pricing store — so it runs before the transaction opens.
+        revert_manual_price(order, line_item, attributes) if reverting
+
+        ActiveRecord::Base.transaction do
+          return failure(line_item) unless line_item.update(attributes)
+
+          Spree::Orders::Recalculate.call(order: order, line_item: line_item) if quantity_changing || price_provided
+        end
+
+        success(line_item)
+      end
+
+      private
+
+      # failure(record, message) drops the message when the record responds to
+      # +errors+; :base rather than :price so Rails does not prefix the
+      # attribute name onto it.
+      #
+      # @param line_item [Spree::LineItem]
+      # @param code [Symbol] symbolic rejection carried in +details+
+      # @param message [String] human-readable explanation
+      # @return [Spree::ServiceModule::Result]
+      def reject_price(line_item, code, message)
+        line_item.errors.add(:base, code, message: message)
+        failure(line_item)
+      end
+
+      # finite? is not redundant: BigDecimal parses "NaN" and "Infinity" and
+      # neither is negative.
+      # @return [BigDecimal, nil]
+      def parse_manual_price(value)
+        parsed = BigDecimal(value.to_s)
+        return if parsed.negative? || !parsed.finite?
+
+        parsed
+      rescue ArgumentError
+        nil
+      end
+
+      # Clears the manual marker in memory, then re-prices through the
+      # resolver at the quantity this update lands on. A resolver with no
+      # answer (no catalog price in this currency) leaves the amount as it
+      # stands — only the marker is guaranteed to clear.
+      def revert_manual_price(order, line_item, attributes)
+        line_item.assign_attributes(
+          attributes.merge(price_source: nil, price_list_id: nil)
+        )
+
+        result = Spree::Carts::PriceItems.new.call(cart: order, line_items: [line_item])
+        Spree::Carts::PriceItems.apply(result.value, persist: false) if result.success?
+
+        # The in-memory assignments (including any resolved price) ride the
+        # transactional update below.
+        attributes.merge!(
+          price: line_item.price,
+          price_source: line_item.price_source,
+          price_list_id: line_item.price_list_id
+        )
+      end
+    end
+  end
+end

data/app/services/spree/orders/update_statuses.rb

@@ -0,0 +1,109 @@
+module Spree
+  module Orders
+    # The ONLY writer of +payment_status+ and +fulfillment_status+.
+    # Derive-then-persist: statuses are recomputed from payment/refund/
+    # fulfillment records and stored in indexed columns so admin filtering
+    # keeps working. Triggered from payment/refund/fulfillment/return event
+    # subscribers — never inline from controllers.
+    class UpdateStatuses
+      prepend Spree::ServiceModule::Base
+
+      PAYMENT_STATUSES = Spree::Order::PAYMENT_STATUSES
+
+      def call(order:)
+        order.update_columns(
+          payment_status: payment_status_for(order),
+          fulfillment_status: fulfillment_status_for(order),
+          updated_at: Time.current
+        )
+        success(order)
+      end
+
+      private
+
+      # Money is quantized to currency precision before comparing, and
+      # granted refunds are subtracted from the target total — the two rules
+      # every derivation implementation gets wrong first.
+      def payment_status_for(order)
+        currency = ::Money::Currency.find(order.currency) || ::Money::Currency.find('USD')
+        precision = currency.exponent
+
+        captured, authorized, refunded = money_for(order).map { |amount| quantize(amount, precision) }
+        target = quantize(order.total, precision) - refunded
+        net_captured = captured - refunded
+
+        if order.canceled? && net_captured <= 0 && captured.positive?
+          'voided'
+        elsif refunded.positive? && net_captured <= 0
+          'refunded'
+        elsif refunded.positive?
+          'partially_refunded'
+        elsif captured.zero? && authorized.zero?
+          'none'
+        elsif captured.zero?
+          'authorized'
+        elsif net_captured > target
+          'overcharged'
+        elsif net_captured >= target
+          'paid'
+        else
+          'partially_paid'
+        end
+      end
+
+      # What has been authorised, captured and refunded against this order.
+      #
+      # An order placed in a split checkout owns no payments — the customer
+      # made one payment against the group — so its figures come from its share
+      # of them. That is precisely what a payment split records, and it is why
+      # the shares are stored rather than recomputed: once one seller has
+      # shipped and been captured while another has not, no proportion of the
+      # group's totals can describe either.
+      #
+      # @return [Array(BigDecimal, BigDecimal, BigDecimal)] captured,
+      #   authorized and refunded, in that order
+      def money_for(order)
+        unless order.order_group_id.present?
+          return [
+            order.payments.valid.completed.sum(:amount),
+            order.payments.valid.pending.sum(:amount),
+            order.refunds.sum(:amount)
+          ]
+        end
+
+        splits = order.payment_splits.to_a
+        captured = splits.sum(&:captured_amount)
+
+        # Authorized means still to draw: what the shares allow, less what has
+        # already been taken against them.
+        [captured, splits.sum(&:authorized_amount) - captured, splits.sum(&:refunded_amount)]
+      end
+
+      # Rolls the fulfillments up into one word for filtering and display.
+      #
+      # Canceled fulfillments are ignored unless they are all there is: an
+      # order whose second parcel was recalled is still described by the first.
+      # A mix that includes anything handed over reads as `partial`; otherwise
+      # the shared status stands. `delivered` only when every parcel arrived.
+      def fulfillment_status_for(order)
+        return 'backorder' if order.backordered?
+
+        statuses = order.fulfillments.reload.pluck(:status).uniq
+        return if statuses.empty?
+
+        live = statuses - ['canceled']
+        # Every parcel recalled: on a canceled order that is the end of the
+        # story, on a placed one the goods are still owed and a new fulfillment
+        # is how they go out — so it reads as work remaining, not as canceled.
+        return (order.canceled? ? 'canceled' : 'unfulfilled') if live.empty?
+        return live.first if live.size == 1
+
+        live.intersect?(%w[fulfilled delivered]) ? 'partial' : 'unfulfilled'
+      end
+
+      def quantize(amount, precision)
+        Spree::Money::Rounding.quantize(amount, precision)
+      end
+    end
+  end
+end

data/app/services/spree/payments/create.rb

@@ -1,5 +1,16 @@
 module Spree
   module Payments
+    # @deprecated Unused since 6.0 and removed in 7.0. Nothing in Spree
+    #   calls this: the storefront creates payments through the Store API
+    #   controller, store credit through Spree::Checkout::AddStoreCredit,
+    #   gift cards through Spree::GiftCards::Apply, and a partial capture's
+    #   remainder through Spree::Payment#split_uncaptured_amount.
+    #
+    #   It also cannot serve those callers as written — it resolves the
+    #   payment method from +params[:payment_method_id]+ against the
+    #   storefront-visible list and builds a source from client attributes,
+    #   while they already hold both (the gift card flow creates its payment
+    #   method by type when the store has none).
     class Create
       prepend Spree::ServiceModule::Base
 
@@ -9,12 +20,15 @@ module Spree
           run :find_or_create_payment_source
           run :save_payment
         end
+        # Gateway I/O — after the transaction, on the in-memory graph (some
+        # gateways need the raw card number, which never persists).
+        run :store_gateway_profile
       end
 
       protected
 
       def prepare_payment_attributes(order:, params:)
-        payment_method = order.collect_frontend_payment_methods.find { |pm| pm.id.to_s == params[:payment_method_id]&.to_s }
+        payment_method = order.payment_methods.find { |pm| pm.id.to_s == params[:payment_method_id]&.to_s }
 
         payment_attributes = {
           amount: params[:amount] || order.order_total_after_store_credit,
@@ -30,15 +44,15 @@ module Spree
         payment_method = payment_attributes[:payment_method]
 
         if payment_method&.source_required?
-          if order.user.present? && params[:source_id].present?
-            source = payment_method.payment_source_class.find_by(id: params[:source_id], user: order.user)
+          if order.customer.present? && params[:source_id].present?
+            source = payment_method.payment_source_class.find_by(id: params[:source_id], customer: order.customer)
 
             return failure(nil, :source_not_found) if source.nil?
           else
             result = Wallet::CreatePaymentSource.call(
               payment_method: payment_method,
               params: params.delete(:source_attributes),
-              user: order.user
+              user: order.customer
             )
 
             return failure(nil, result.error.value) if result.failure?
@@ -56,11 +70,23 @@ module Spree
         payment = order.payments.new(payment_attributes)
 
         if payment.save
-          success(payment)
+          success(payment: payment)
         else
           failure(payment)
         end
       end
+
+      # A payment that cannot be profiled must not linger half-created — the
+      # old after_save callback rolled the whole save back on gateway failure.
+      def store_gateway_profile(payment:)
+        return success(payment) unless payment.profiles_supported?
+
+        payment.create_payment_profile
+        success(payment)
+      rescue Spree::Core::GatewayError => e
+        payment.destroy
+        failure(payment, e.message)
+      end
     end
   end
 end

data/app/services/spree/prices/bulk_upsert.rb

@@ -6,7 +6,8 @@ module Spree
     # `spree_prices` is guarded by two partial unique indexes on PG/SQLite
     # (collapsed to one composite index on MySQL):
     #   - base prices (price_list_id IS NULL): unique on (variant_id, currency)
-    #   - overrides   (price_list_id IS NOT NULL): unique on (variant_id, currency, price_list_id)
+    #   - overrides   (price_list_id IS NOT NULL): unique on
+    #     (variant_id, currency, price_list_id, min_quantity)
     # A single `upsert_all` can only target one index, so rows ship in two
     # batches — base vs override — each routed to the correct ON CONFLICT.
     #
@@ -19,34 +20,54 @@ module Spree
 
       # Two partial unique indexes guard `spree_prices` on PG/SQLite:
       #   - base prices (price_list_id IS NULL): unique on (variant_id, currency)
-      #   - overrides   (price_list_id IS NOT NULL): unique on (variant_id, currency, price_list_id)
+      #   - overrides   (price_list_id IS NOT NULL): unique on
+      #     (variant_id, currency, price_list_id, min_quantity)
       # A single `upsert_all` can only target one index, so base-price rows
       # and override rows ship in separate batches.
       BASE_UNIQUE_BY = %i[variant_id currency].freeze
-      OVERRIDE_UNIQUE_BY = %i[variant_id currency price_list_id].freeze
+      OVERRIDE_UNIQUE_BY = %i[variant_id currency price_list_id min_quantity].freeze
 
       # @param rows [Array<Hash>] each row must carry
-      #   `variant_id`, `currency`, and `amount`; `price_list_id` and
-      #   `compare_at_amount` are optional. A blank `amount` is treated
-      #   as "clear this price."
+      #   `variant_id`, `currency`, and `amount`; `price_list_id`,
+      #   `min_quantity` and `compare_at_amount` are optional. A blank
+      #   `amount` is treated as "clear this price", and a blank
+      #   `min_quantity` means the ladder's bottom rung.
       # @return [Spree::ServiceModule::Result] success carries
-      #   `{ price_count: N }` — the number of rows passed to
-      #   `upsert_all`.
+      #   `{ price_count: N }` — the number of rows passed to `upsert_all`.
+      #   Fails with the offending rows when a batch carries an unusable
+      #   `min_quantity`, or would take a variant past
+      #   {Spree::Price::MAXIMUM_BREAKS_PER_VARIANT} breaks on one list. This
+      #   path writes in SQL and runs no model validations, so both checks
+      #   live here rather than in each of the three controllers that reach
+      #   it (docs/plans/6.0-volume-pricing.md).
       def call(rows:)
         rows = Array(rows).map { |r| r.with_indifferent_access }
+        # Amounts are parsed once, here; everything below reads numbers.
         keyed = rows.select { |r| r[:variant_id].present? && r[:currency].present? }
-        # PG rejects an upsert with two rows hitting the same unique-key
-        # triple in one statement ("ON CONFLICT DO UPDATE command cannot
-        # affect row a second time"). Last-write-wins: keep the last
-        # occurrence of each triple.
-        deduped = keyed.reverse.uniq { |r| [r[:variant_id], r[:currency], r[:price_list_id]] }.reverse
+                    .map { |r| r.merge(amount: parse_amount(r[:amount]), compare_at_amount: parse_amount(r[:compare_at_amount])) }
+        # Checked before anything is deduped: `row_key` coerces the quantity,
+        # so two malformed rows would collapse into one and the batch would be
+        # judged on a shape the caller never sent.
+        malformed = rows_with_unusable_quantity(keyed)
+        return failure(nil, invalid_quantities: malformed) if malformed.any?
+
+        negative = rows_with_negative_amount(keyed)
+        return failure(nil, invalid_amounts: negative) if negative.any?
+
+        # PG rejects an upsert with two rows hitting the same unique key in one
+        # statement ("ON CONFLICT DO UPDATE command cannot affect row a second
+        # time"). Last-write-wins: keep the last occurrence of each key.
+        deduped = keyed.reverse.uniq { |r| row_key(r) }.reverse
         upsert_rows, clear_rows = deduped.partition { |r| r[:amount].present? }
 
         payload = build_payload(upsert_rows)
-        affected_keys = deduped.map { |r| [r[:variant_id], r[:currency], r[:price_list_id]] }
+        affected_keys = deduped.map { |r| row_key(r) }
 
         return success(price_count: 0) if affected_keys.empty?
 
+        over_cap = ladders_over_cap(upsert_rows, clear_rows)
+        return failure(nil, over_cap: over_cap) if over_cap.any?
+
         base_rows, override_rows = payload.partition { |r| r[:price_list_id].nil? }
 
         Spree::Price.transaction do
@@ -65,7 +86,7 @@ module Spree
           # `Price -> Variant -> Product` `touch:` chain never fires —
           # downstream caches (`cache_key_with_version`) would stay stale.
           # Re-trigger the chain with one `.touch` per affected variant.
-          touch_variants(affected_keys.map(&:first).uniq)
+          touch_variants(affected_keys.map { |k| k[0] }.uniq)
         end
 
         success(price_count: payload.length)
@@ -95,14 +116,121 @@ module Spree
             variant_id: row[:variant_id],
             currency: row[:currency],
             price_list_id: row[:price_list_id],
-            amount: parse_amount(row[:amount]),
-            compare_at_amount: parse_amount(row[:compare_at_amount]),
+            min_quantity: quantity_of(row),
+            amount: row[:amount],
+            compare_at_amount: row[:compare_at_amount],
             created_at: now,
             updated_at: now
           }
         end
       end
 
+      # A row identifies one rung of one ladder. Rows arriving without a
+      # quantity address the bottom rung, which is every row written before
+      # breaks existed (docs/plans/6.0-volume-pricing.md).
+      def row_key(row)
+        [row[:variant_id], row[:currency], row[:price_list_id], quantity_of(row)]
+      end
+
+      # Absent means the ladder's bottom rung. Anything present must be a
+      # positive whole number — see #rows_with_unusable_quantity, which
+      # refuses the batch before this coerces anything.
+      def quantity_of(row)
+        return 1 if row[:min_quantity].blank?
+
+        parse_quantity(row[:min_quantity])
+      end
+
+      # Base ten, strictly: `to_i` would read "0x10" as 0 and `Integer()`
+      # would read "010" as octal, and the two disagreeing is how a rung lands
+      # at a quantity nobody typed. Nil for anything that is not a whole number.
+      def parse_quantity(raw)
+        return raw if raw.is_a?(Integer)
+
+        Integer(raw.to_s.strip, 10, exception: false)
+      end
+
+      # Rows pricing below zero. This path runs no model validations, so the
+      # sign is checked here for every caller rather than in each of them.
+      def rows_with_negative_amount(rows)
+        rows.each_with_index.filter_map do |row, index|
+          { index: index } if row[:amount]&.negative? || row[:compare_at_amount]&.negative?
+        end
+      end
+
+      # Rows whose `min_quantity` is present but not a positive whole number.
+      #
+      # Coercing these with `to_i` would turn a typo into quantity 1 and
+      # overwrite the contracted price the variant is actually sold at — the
+      # row a customer is charged (docs/plans/6.0-volume-pricing.md). This
+      # path writes in SQL and runs no model validations, so the check has to
+      # happen here.
+      #
+      # @param rows [Array<Hash>]
+      # @return [Array<Hash>] `[{ index: }, ...]` for the offending rows
+      def rows_with_unusable_quantity(rows)
+        rows.each_with_index.filter_map do |row, index|
+          raw = row[:min_quantity]
+          next if raw.blank?
+
+          quantity = parse_quantity(raw)
+          { index: index } if quantity.nil? || quantity < 1
+        end
+      end
+
+      # Which ladders this batch would take past the cap, counted the way the
+      # constant is named: breaks *above* the bottom rung, so a variant priced
+      # at one figure plus ten breaks is exactly at the limit.
+      #
+      # Only ladders the batch actually adds a break to are checked, so an
+      # ordinary spreadsheet save — one quantity-1 row per variant — costs no
+      # extra queries at all.
+      #
+      # @param rows [Array<Hash>] the rows carrying an amount
+      # @param cleared_rows [Array<Hash>] the rows whose blank amount removes a rung
+      # @return [Array<Hash>] `[{ variant_id:, currency:, price_list_id: }, ...]`
+      def ladders_over_cap(rows, cleared_rows = [])
+        touched = rows.
+                  reject { |row| row[:price_list_id].blank? || quantity_of(row) == 1 }.
+                  group_by { |row| [row[:variant_id].to_s, row[:currency], row[:price_list_id].to_s] }.
+                  transform_values { |group| group.map { |row| quantity_of(row) }.to_set }
+        return [] if touched.empty?
+
+        cleared = cleared_rows.
+                  reject { |row| row[:price_list_id].blank? || quantity_of(row) == 1 }.
+                  group_by { |row| [row[:variant_id].to_s, row[:currency], row[:price_list_id].to_s] }.
+                  transform_values { |group| group.map { |row| quantity_of(row) }.to_set }
+
+        # One query for every ladder in the batch rather than one each: an
+        # import writing a ladder across two hundred variants would otherwise
+        # issue two hundred round trips inside the request. Cross-pairs the
+        # `IN` clauses pull in are dropped by the lookup below, the same way
+        # #sweep handles them.
+        # Placeholder rows charge nothing, so they do not fill a ladder — the
+        # model's own guard counts the same way, and a cap two writers
+        # disagree about is one that refuses what it just allowed.
+        stored = Spree::Price.
+                 where(variant_id: touched.keys.map { |key| key[0] },
+                       currency: touched.keys.map { |key| key[1] },
+                       price_list_id: touched.keys.map { |key| key[2] }).
+                 breaks.
+                 where.not(amount: nil).
+                 pluck(:variant_id, :currency, :price_list_id, :min_quantity).
+                 group_by { |variant_id, currency, price_list_id, _| [variant_id.to_s, currency, price_list_id.to_s] }
+
+        touched.filter_map do |key, incoming|
+          # Stored rungs this batch does not name are the ones that survive it;
+          # counting the rest as well would refuse a merchant who deleted two
+          # rungs and added two others, whose ladder ends the size it began.
+          # The deletions ride in `clear_rows` and the sweep applies them, so
+          # what is left after this batch is (survivors + incoming).
+          survivors = stored.fetch(key, []).map(&:last).to_set - cleared.fetch(key, Set.new)
+          next if (survivors | incoming).size <= Spree::Price::MAXIMUM_BREAKS_PER_VARIANT
+
+          { variant_id: key[0], currency: key[1], price_list_id: key[2] }
+        end
+      end
+
       # Parses locale-aware decimal input ("1.234,56" in DE, "1,234.56"
       # in en-US). Numeric values pass through; blank values become nil.
       def parse_amount(value)
@@ -113,19 +241,20 @@ module Spree
       end
 
       def sweep(affected_keys, clear_rows)
-        cleared_keys = clear_rows.map { |r| [r[:variant_id], r[:currency], r[:price_list_id]] }.to_set
+        cleared_keys = clear_rows.map { |r| row_key(r) }.to_set
         affected_set = affected_keys.to_set
 
         candidates = Spree::Price
           .where(
-            variant_id: affected_keys.map(&:first).uniq,
+            variant_id: affected_keys.map { |k| k[0] }.uniq,
             currency: affected_keys.map { |k| k[1] }.uniq,
-            price_list_id: affected_keys.map(&:last).uniq
+            price_list_id: affected_keys.map { |k| k[2] }.uniq,
+            min_quantity: affected_keys.map { |k| k[3] }.uniq
           )
-          .pluck(:id, :variant_id, :currency, :price_list_id, :amount)
+          .pluck(:id, :variant_id, :currency, :price_list_id, :min_quantity, :amount)
 
-        doomed_ids = candidates.filter_map do |id, variant_id, currency, price_list_id, amount|
-          key = [variant_id, currency, price_list_id]
+        doomed_ids = candidates.filter_map do |id, variant_id, currency, price_list_id, min_quantity, amount|
+          key = [variant_id, currency, price_list_id, min_quantity]
           next unless affected_set.include?(key)
           next id if amount.nil?
           next id if cleared_keys.include?(key)
@@ -141,12 +270,9 @@ module Spree
       # `upsert_all` and `delete_all` skip the `Price -> Variant` and
       # `Variant -> Product` `touch:` chains otherwise.
       #
-      # We deliberately bypass AR callbacks: invoking `Variant#touch`
-      # would fire `after_commit :remove_prices_from_master_variant`,
-      # which `delete_all`s the master's prices whenever a non-master
-      # sibling has any prices — wiping exactly the rows the bulk
-      # upsert just persisted on a freshly-created list. `touch_all`
-      # gives us the cache bust without that side effect.
+      # We use `touch_all` rather than per-record `Variant#touch`: it bumps
+      # every affected row in a single UPDATE and skips AR callbacks, giving
+      # the cache bust without extra side effects.
       def touch_variants(variant_ids)
         return if variant_ids.empty?
 
@@ -165,7 +291,7 @@ module Spree
       end
 
       def mysql?
-        ActiveRecord::Base.connection.adapter_name == 'Mysql2'
+        Spree.mysql?
       end
 
       # MySQL-only path: NULLs are distinct in unique indexes, so

data/app/services/spree/product_submissions/close.rb

@@ -0,0 +1,46 @@
+module Spree
+  module ProductSubmissions
+    # Settles the open row in a product's review trail
+    # (docs/plans/6.0-seller-product-submission.md).
+    #
+    # Every exit from review comes through here — approved, rejected, or
+    # withdrawn by the seller — so a `pending` row always means the
+    # marketplace still owes an answer.
+    #
+    # Tier 1 (plain service) by design: it is one write with no hooks and no
+    # external call, and it runs inside the deciding workflow's transaction.
+    class Close
+      prepend Spree::ServiceModule::Base
+
+      # Products that predate the trail, or reached review before this shipped,
+      # have nothing open. They get a row anyway rather than silently no-op:
+      # the decision is what we are recording, and a missing submission is not
+      # a reason to lose it.
+      #
+      # @param product [Spree::Product]
+      # @param status [String] `approved`, `rejected` or `withdrawn`
+      # @param reviewed_by [Spree.admin_user_class, nil] who decided
+      # @param review_note [String, nil] shown to the seller
+      # @param metadata [Hash] merged onto the row
+      # @return [Spree::ServiceModule::Result] value is the submission
+      def call(product:, status:, reviewed_by: nil, review_note: nil, metadata: {})
+        # The head of the trail, and only if it is still open: scanning the
+        # whole history for any pending row could settle a stale one from an
+        # earlier cycle instead of the decision actually in front of us.
+        latest = product.submissions.latest_first.first
+        submission = latest&.pending? ? latest : product.submissions.new(status: 'pending')
+
+        attributes = { status: status, reviewed_at: Time.current, reviewed_by: reviewed_by }
+        # A decision with no note must not wipe the note the row already
+        # carries: re-rejecting without one means "same reason as before".
+        attributes[:review_note] = review_note if review_note.present?
+        attributes[:metadata] = submission.metadata.to_h.merge(metadata) if metadata.present?
+
+        submission.assign_attributes(attributes)
+        submission.save!
+
+        success(submission)
+      end
+    end
+  end
+end