spree_core 5.6.1 → 6.0.0.beta2

data/app/models/spree/consent_record.rb

@@ -0,0 +1,125 @@
+module Spree
+  # Proof that a person accepted something at a moment in time.
+  #
+  # GDPR Art. 7(1) puts the burden of demonstrating consent on the controller,
+  # and a boolean on the customer cannot carry that burden: it says what is
+  # true now, not what was agreed when. So acceptance is recorded as an event.
+  # A person consents more than once — at registration, then again at each
+  # checkout — and each occasion is its own row.
+  #
+  # The owner is a customer where one exists and the cart or order otherwise,
+  # because guest checkout produces consent with no account behind it.
+  class ConsentRecord < Spree.base_class
+    has_prefix_id :consent
+
+    include Spree::SingleStoreResource
+
+    # What was agreed to. An open set: a store with its own consent gesture
+    # records it under its own purpose without reopening this class.
+    TERMS_OF_SERVICE = 'terms_of_service'.freeze
+    EMAIL_MARKETING = 'email_marketing'.freeze
+
+    # Where the gesture happened.
+    CHECKOUT = 'checkout'.freeze
+    REGISTRATION = 'registration'.freeze
+    ACCOUNT = 'account'.freeze
+    # A staff member changed it on the person's behalf. Distinct from ACCOUNT,
+    # which claims the person did it themselves — recording one as the other
+    # is evidence of a gesture that never happened.
+    ADMIN = 'admin'.freeze
+    # The person confirmed a newsletter sign-up, which is a different gesture
+    # from editing their profile and is the stronger evidence of the two: a
+    # double opt-in proves the address reaches them.
+    NEWSLETTER = 'newsletter'.freeze
+    # Core's own: erasure withdraws marketing consent on the person's behalf,
+    # and that withdrawal is a consent event like any other.
+    ANONYMIZATION = 'anonymization'.freeze
+    # The flag changed but nothing said where. Recording it as ACCOUNT would
+    # claim the person visited their profile and clicked, which is the same
+    # fabrication the ADMIN constant exists to avoid.
+    UNKNOWN = 'unknown'.freeze
+
+    SOURCES = [CHECKOUT, REGISTRATION, ACCOUNT, ADMIN, NEWSLETTER, ANONYMIZATION,
+               UNKNOWN, 'import', 'storefront'].freeze
+
+    belongs_to :store, class_name: 'Spree::Store'
+    belongs_to :owner, polymorphic: true
+
+    validates :purpose, presence: true
+    validates :source, presence: true, inclusion: { in: SOURCES }
+    validates :recorded_at, presence: true
+
+    scope :for_purpose, ->(purpose) { where(purpose: purpose.to_s) }
+    scope :recent_first, -> { order(recorded_at: :desc) }
+
+    self.whitelisted_ransackable_attributes = %w[purpose source accepted email recorded_at]
+
+    before_validation :set_recorded_at, on: :create
+
+    # Records acceptance of the store's consent-gated policies, snapshotting
+    # each document as it read at the time. The digest is what makes the row
+    # evidence rather than an assertion: a merchant who later edits their
+    # terms can still show which text this person agreed to.
+    #
+    # @param store [Spree::Store]
+    # @param owner [Spree::Customer, Spree::Order] the consenting party
+    # @param purpose [String]
+    # @param source [String] one of SOURCES
+    # @param accepted [Boolean]
+    # @param email [String, nil]
+    # @param ip_address [String, nil]
+    # @param user_agent [String, nil]
+    # @param policies [Array<Spree::Policy>, nil] documents shown at the time
+    # @return [Spree::ConsentRecord]
+    def self.record!(store:, owner:, purpose:, source:, accepted: true, email: nil,
+                     ip_address: nil, user_agent: nil, policies: nil)
+      create!(
+        store: store,
+        owner: owner,
+        purpose: purpose.to_s,
+        source: source.to_s,
+        accepted: accepted,
+        email: email,
+        ip_address: ip_address,
+        user_agent: user_agent,
+        documents: policies.present? ? policies.map { |policy| document_snapshot(policy) } : nil
+      )
+    end
+
+    # The document as it read at the moment of agreement.
+    #
+    # Stores the body itself, not only a hash of it. A digest can show that a
+    # policy has since changed, but it cannot say what the person actually
+    # read — and reproducing the text they agreed to is the whole point of
+    # keeping the row. The digest rides along as a cheap equality check.
+    #
+    # The locale is recorded because policies are translated: the same document
+    # is different text in each language.
+    #
+    # @param policy [Spree::Policy]
+    # @return [Hash]
+    def self.document_snapshot(policy)
+      body = policy.body.to_s
+
+      {
+        'slug' => policy.slug,
+        'name' => policy.name,
+        'locale' => Spree::Current.locale || I18n.locale.to_s,
+        'body' => body,
+        'digest' => Digest::SHA256.hexdigest(body),
+        'updated_at' => policy.updated_at&.iso8601
+      }
+    end
+
+    # @return [Array<Hash>]
+    def documents_list
+      Array(documents)
+    end
+
+    private
+
+    def set_recorded_at
+      self.recorded_at ||= Time.current
+    end
+  end
+end

data/app/models/spree/country.rb

@@ -1,63 +1,121 @@
 module Spree
-  class Country < Spree.base_class
-    self.whitelisted_ransackable_attributes = %w[iso iso3 iso_name name]
+  # A country, identified by its ISO 3166-1 alpha-2 code.
+  #
+  # Countries are reference data, not records: they are supplied by the
+  # +countries+ gem through {Spree::IsoData} and are the same for every store.
+  # Nothing stores a country id — addresses, delivery zones, markets and stock
+  # locations all name a country by its ISO code.
+  #
+  # Being a plain object rather than an ActiveRecord model, this has no
+  # +.where+, +.find+ or associations. Use {.by_iso} to look one up and
+  # {.all} to enumerate.
+  class Country
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    attribute :iso, :string
+    attribute :iso3, :string
+    attribute :numcode, :integer
+
+    class << self
+      # @return [Array<Spree::Country>] every country a store can sell to
+      def all
+        @all ||= Spree::IsoData.countries.map { |data| from_iso3166(data) }.freeze
+      end
+
+      # @param code [String] alpha-2 or alpha-3 code, in any case
+      # @return [Spree::Country, nil]
+      def by_iso(code)
+        data = Spree::IsoData.country(code)
+        data && from_iso3166(data)
+      end
+
+      # @param code [String] alpha-2 or alpha-3 code, in any case
+      # @return [Spree::Country]
+      # @raise [ActiveRecord::RecordNotFound] when no country has that code
+      def find_by_iso!(code)
+        by_iso(code) || raise(ActiveRecord::RecordNotFound, "Couldn't find Spree::Country with iso #{code.inspect}")
+      end
+
+      # @param iso [String]
+      # @return [String] the country's flag as regional indicator characters
+      def iso_to_emoji_flag(iso)
+        iso.to_s.upcase.chars.map { |char| (char.ord + 127_397).chr(Encoding::UTF_8) }.join
+      end
+
+      # Drops the memoized list. Only needed when the gem's locale
+      # configuration changes after boot, which in practice means specs.
+      # @return [void]
+      def reset!
+        @all = nil
+      end
+
+      private
+
+      def from_iso3166(data)
+        new(iso: data.alpha2, iso3: data.alpha3, numcode: data.number)
+      end
+    end
 
-    has_many :addresses, dependent: :restrict_with_error
-    has_many :states,
-             -> { order name: :asc },
-             inverse_of: :country,
-             dependent: :destroy
-    has_many :zone_members,
-             -> { where(zoneable_type: 'Spree::Country') },
-             class_name: 'Spree::ZoneMember',
-             dependent: :destroy,
-             foreign_key: :zoneable_id
-    has_many :zones, through: :zone_members, class_name: 'Spree::Zone'
-    has_many :market_countries, class_name: 'Spree::MarketCountry', dependent: :destroy
-    has_many :markets, through: :market_countries, class_name: 'Spree::Market'
+    # @return [String] localized name, e.g. "Germany" or "Deutschland"
+    def name
+      localized_name
+    end
 
-    validates :name, :iso_name, :iso, :iso3, presence: true, uniqueness: { case_sensitive: false, scope: spree_base_uniqueness_scope }
+    # The ISO's own uppercase name, kept for the API field of the same name.
+    # @return [String]
+    def iso_name
+      (iso3166_country&.iso_short_name || iso.to_s).upcase
+    end
 
-    def self.by_iso(iso)
-      where(['LOWER(iso) = ?', iso.downcase]).or(where(['LOWER(iso3) = ?', iso.downcase])).take
+    # @return [Array<Spree::State>] the country's subdivisions, ordered by name
+    # Not memoized: .all hands out process-lifetime instances, and the names
+    # are localized — caching here would pin one request's locale onto every
+    # later one. IsoData holds the per-locale cache this reads from.
+    def states
+      Spree::IsoData.subdivisions(iso).map do |abbr, subdivision_name|
+        Spree::State.new(abbr: abbr, name: subdivision_name, country_code: iso)
+      end.freeze
     end
 
-    def default?(store = nil)
-      store ||= Spree::Store.default
-      self == store.default_country
+    # @return [Boolean] whether an address here must name a subdivision
+    def states_required
+      Spree::Address::STATES_REQUIRED.include?(iso.to_s.upcase)
     end
+    alias states_required? states_required
 
-    def self.to_tom_select_json
-      pluck(:name, :id, :iso).map do |name, id, iso|
-        {
-          id: id,
-          name: new(iso: iso, name: name).option_label
-        }
-      end.as_json
+    # @return [Boolean] whether an address here must carry a postal code
+    def zipcode_required
+      !Spree::Address::NO_ZIPCODE_ISO_CODES.include?(iso.to_s.upcase)
     end
+    alias zipcode_required? zipcode_required
 
-    def self.iso_to_emoji_flag(iso)
-      iso.upcase.chars.map { |c| (c.ord + 127397).chr(Encoding::UTF_8) }.join
+    # @param store [Spree::Store, nil]
+    # @return [Boolean] whether this is the store's default country
+    def default?(store = nil)
+      store ||= Spree::Store.default
+      self == store&.default_country
     end
 
-    # Lookups Market for Country for the current Store
+    # Looks up the Market covering this country for the current Store.
     # @return [Spree::Market, nil]
+    # Not memoized, for the same reason as #states: these instances are shared
+    # across the process, so caching a market here would serve one store's
+    # market to every other store — and would never notice a market edit.
     def current_market
-      @current_market ||= Spree::Current.store&.market_for_country(self)
+      Spree::Current.store&.market_for_country(self)
     end
 
-    # Display name localized to +locale+ via the countries gem (CLDR), falling
-    # back to the stored +name+ (or the ISO when there is no name) for an
-    # unknown ISO or missing translation.
+    # Display name for +locale+, falling back to the ISO's own name when the
+    # gem carries no translation for it.
     # @param locale [Symbol, String]
     # @return [String]
     def localized_name(locale: I18n.locale)
-      fallback = name.presence || iso.to_s
-      data = ISO3166::Country[iso.to_s.upcase]
-      return fallback unless data
+      data = iso3166_country
+      return iso.to_s unless data
 
       base_locale = locale.to_s.downcase.tr('_', '-').split('-').first
-      (data.translation(base_locale) || data.translation(:en)).presence || fallback
+      (data.translation(base_locale) || data.iso_short_name).presence || iso.to_s
     end
 
     # Flag emoji + localized name, for select options.
@@ -67,30 +125,48 @@ module Spree
       "#{self.class.iso_to_emoji_flag(iso)} #{localized_name(locale: locale)}"
     end
 
-    def <=>(other)
-      name <=> other.name
-    end
-
-    def to_s
-      name
-    end
-
-    # Returns the default currency code for this country (e.g., 'USD', 'EUR')
-    # Uses the countries gem (ISO3166) for accurate currency data
+    # @return [String, nil] e.g. 'USD'
     def default_currency
       iso3166_country&.currency_code
     end
 
-    # Returns the default locale/language for this country (e.g., 'en', 'de')
-    # Uses the countries gem (ISO3166) for accurate language data
+    # @return [String, nil] e.g. 'en'
     def default_locale
       iso3166_country&.languages&.first
     end
 
+    # Every official language, not just the first — Switzerland speaks four,
+    # and a merchant setting up there should be offered all of them.
+    # @return [Array<String>] e.g. ['de', 'fr', 'it', 'rm']
+    def official_locales
+      iso3166_country&.languages_official.presence || []
+    end
+
+    # Countries are equal when they name the same place, so they can be
+    # compared, deduplicated and used as hash keys.
+    def ==(other)
+      other.is_a?(Spree::Country) && other.iso == iso
+    end
+    alias eql? ==
+
+    def hash
+      iso.hash
+    end
+
+    def <=>(other)
+      return nil unless other.is_a?(Spree::Country)
+
+      name <=> other.name
+    end
+
+    def to_s
+      name
+    end
+
     private
 
     def iso3166_country
-      @iso3166_country ||= ISO3166::Country.new(iso)
+      @iso3166_country ||= ISO3166::Country[iso.to_s.upcase]
     end
   end
 end

data/app/models/spree/coupon_code.rb

@@ -14,10 +14,22 @@ module Spree
     scope :not_in_promotions, ->(promotion_ids) { where.not(promotion_id: promotion_ids) }
 
     belongs_to :promotion, class_name: 'Spree::Promotion', touch: true
-    belongs_to :order, class_name: 'Spree::Order'
+    belongs_to :order, class_name: 'Spree::Order', optional: true
+    belongs_to :cart, class_name: 'Spree::Cart', optional: true
+
+    # Bridge for legacy callers assigning +current_order+ (now a Spree::Cart)
+    # to the order association — routes carts to the cart FK instead.
+    def order=(record)
+      if record.is_a?(Spree::Cart)
+        self.cart = record
+        super(nil)
+      else
+        super
+      end
+    end
 
     validates :code, presence: true, uniqueness: { scope: spree_base_uniqueness_scope, conditions: -> { where(deleted_at: nil) } }
-    validates :state, :promotion, presence: true
+    validates :state, presence: true
 
     self.whitelisted_ransackable_attributes = %w[state code promotion_id]
     self.whitelisted_ransackable_associations = %w[promotion]
@@ -26,12 +38,13 @@ module Spree
       used_with_code(code).any?
     end
 
-    def apply_order!(order)
-      update(order: order, state: 'used')
+    def apply_order!(owner)
+      owner_key = owner.is_a?(Spree::Cart) ? :cart : :order
+      update(owner_key => owner, state: 'used')
     end
 
     def remove_from_order
-      update(order: nil, state: 'unused')
+      update(order: nil, cart: nil, state: 'unused')
     end
 
     def display_code

data/app/models/spree/credit_card.rb

@@ -2,7 +2,7 @@ module Spree
   class CreditCard < Spree.base_class
     has_prefix_id :card  # Stripe: card_
 
-    include Spree::Metafields
+    include Spree::HasCustomFields
     include Spree::Metadata
     include Spree::PaymentSourceConcern
 
@@ -13,7 +13,8 @@ module Spree
     acts_as_paranoid
 
     belongs_to :payment_method
-    belongs_to :user, class_name: Spree.user_class.to_s, foreign_key: 'user_id', optional: true
+    belongs_to :customer, class_name: Spree.customer_class.to_s, optional: true
+    include Spree::DeprecatedCustomerAlias
     belongs_to :gateway_customer, class_name: 'Spree::GatewayCustomer', optional: true
 
     has_many :payments, as: :source
@@ -38,9 +39,9 @@ module Spree
     end
 
     # Prevents saving the same physical card (same gateway fingerprint + expiry)
-    # twice for a user and payment method. Skipped when the gateway does not
-    # provide a fingerprint.
-    validate :fingerprint_not_duplicated, if: -> { fingerprint.present? }
+    # twice for a user and payment method. Guest payment sources are not saved
+    # cards owned by a customer, so they are excluded from this validation.
+    validate :fingerprint_not_duplicated, if: -> { fingerprint.present? && user_id.present? }
 
     scope :with_payment_profile, -> { where.not(gateway_customer_profile_id: nil) }
     scope :capturable, -> { where.not(gateway_customer_profile_id: nil).or(where.not(gateway_payment_profile_id: nil)) }
@@ -68,7 +69,7 @@ module Spree
     alias_attribute :brand, :cc_type
     alias_attribute :last4, :last_digits
 
-    store_accessor :private_metadata, :wallet
+    store_accessor :metadata, :wallet
 
     # Returns the type of wallet the card is associated with, eg. "apple_pay", "google_pay", etc.
     # @return [String]
@@ -187,7 +188,7 @@ module Spree
     # match must go through #by_fingerprint's decimal cast rather than a plain
     # equality (which Postgres rejects as `character varying = integer`).
     def fingerprint_not_duplicated
-      duplicates = self.class.where(user_id: user_id, payment_method_id: payment_method_id).
+      duplicates = self.class.where(customer_id: customer_id, payment_method_id: payment_method_id).
                    by_fingerprint(fingerprint, month, year)
       duplicates = duplicates.where.not(id: id) if persisted?
 
@@ -199,8 +200,8 @@ module Spree
     end
 
     def ensure_one_default
-      if user_id && default
-        CreditCard.where(default: true, user_id: user_id).where.not(id: id).
+      if customer_id && default
+        CreditCard.where(default: true, customer_id: customer_id).where.not(id: id).
           update_all(default: false)
       end
     end

data/app/models/spree/current.rb

@@ -4,9 +4,18 @@ module Spree
   # All attributes are automatically reset between requests by Rails.
   # Fallback chains ensure sensible defaults when attributes are not explicitly set.
   class Current < ::ActiveSupport::CurrentAttributes
-    attribute :store, :channel, :market, :currency, :locale, :content_locale, :zone, :default_tax_zone, :price_lists, :global_pricing_context
+    attribute :store, :channel, :market, :currency, :locale, :content_locale, :tax_country, :price_lists, :applicable_catalogs, :applicable_catalog_groups, :quantity_rules_resolvers, :standing_companies, :global_pricing_context, :provider_cache, :integrations
 
-    resets { @default_tax_zone_loaded = false }
+    # Scratch space for provider strategies to memoize a call across the
+    # request — part of the delivery rate provider contract (nothing in core
+    # writes to it): a carrier gem keys its quote here so several delivery
+    # methods sharing one carrier cost a single API round-trip rather than
+    # one each. Keys must be namespaced by the provider (see the custom
+    # delivery rate provider guide).
+    # @return [Hash]
+    def provider_cache
+      super || (self.provider_cache = {})
+    end
 
     # Returns the current store, falling back to the default store.
     # @return [Spree::Store]
@@ -49,24 +58,32 @@ module Spree
       super.presence || I18n.default_locale.name
     end
 
-    # Returns the current tax zone.
-    # Fallback: market's tax zone (from default country) -> global default tax zone.
-    # @return [Spree::Zone, nil]
-    def zone
-      super || market&.tax_zone || default_tax_zone
+    # The country whose tax applies while browsing, before any address exists.
+    # Fallback: the market being browsed -> the store's own country. An order
+    # in hand answers this better (Spree::Purchase::Taxation#tax_country reads
+    # its address first); this is the storefront's answer without one.
+    #
+    # Assigns the resolved country the way #channel does, because the fallback
+    # costs a query: a product listing builds one pricing context per variant,
+    # and each would otherwise re-ask the market for its default country.
+    # @return [Spree::Country, nil]
+    def tax_country
+      super || (self.tax_country = market&.default_country || store&.default_country)
     end
 
-    # Returns the default tax zone (memoized per request).
-    # @return [Spree::Zone, nil]
-    def default_tax_zone
-      result = super
-      return result if result || @default_tax_zone_loaded
-
-      @default_tax_zone_loaded = true
-      self.default_tax_zone = Spree::Zone.find_by(default_tax: true)
+    # The current store's active integrations, loaded once per request.
+    # Lazy — a request that never asks pays nothing — and assigned on first
+    # read the way #tax_country is, because several consumers ask per request:
+    # every integration-backed provider resolving credentials, and the
+    # settings page checking availability across the whole registry.
+    # @return [Array<Spree::Integration>]
+    def integrations
+      super || (self.integrations = store ? store.integrations.active.to_a : [])
     end
 
-    # Returns the current price lists for the global pricing context.
+    # Returns the standalone (rule-matched) price lists in effect for the
+    # global pricing context. Catalog-owned lists are excluded — pricing
+    # reaches them through {#catalogs_for}.
     # @return [ActiveRecord::Relation<Spree::PriceList>]
     def price_lists
       super || begin
@@ -75,18 +92,135 @@ module Spree
       end
     end
 
-    # Returns the current global pricing context, built from store, currency, zone, and market.
+    # Catalogs that apply to a buyer in this request, keyed by that buyer.
+    # A store can have many catalogs; only the company / customer-group /
+    # channel-default set is kept. Product listings price every variant
+    # through a new resolver, so the first call loads the set and the rest
+    # reuse it.
+    #
+    # @param company [Spree::Company, nil]
+    # @param user [Object, nil]
+    # @param channel [Spree::Channel, nil]
+    # @return [Array<Spree::Catalog>]
+    def catalogs_for(company: nil, user: nil, channel: nil)
+      key = catalog_memo_key(company: company, user: user, channel: channel)
+      applicable_catalogs[key] ||= catalog_groups_for(company: company, user: user, channel: channel).flatten
+    end
+
+    # The same catalogs grouped by precedence rank, which is what pricing
+    # walks ({Spree::Catalog.groups_for_company}). The resolved form — the
+    # flat set above is a cached flattening of it, never a second resolution.
+    #
+    # @param company [Spree::Company, nil]
+    # @param user [Object, nil]
+    # @param channel [Spree::Channel, nil]
+    # @return [Array<Array<Spree::Catalog>>]
+    def catalog_groups_for(company: nil, user: nil, channel: nil)
+      key = catalog_memo_key(company: company, user: user, channel: channel)
+      applicable_catalog_groups[key] ||= Spree::Catalog.groups_for_context(
+        store: store, company: company, user: normalized_catalog_user(user), channel: channel || self.channel
+      )
+    end
+
+    # @return [Hash]
+    def applicable_catalogs
+      super || (self.applicable_catalogs = {})
+    end
+
+    # @return [Hash]
+    def applicable_catalog_groups
+      super || (self.applicable_catalog_groups = {})
+    end
+
+    # The quantity-rule resolver for a buyer in this request, keyed the same
+    # way their catalogs are.
+    #
+    # Request-scoped rather than per-caller because a serializer is built
+    # fresh for every variant on a listing: a per-instance memo would reload
+    # and re-hash each catalog's override rows once per row on the page.
+    #
+    # @param company [Spree::Company, nil]
+    # @param user [Object, nil]
+    # @param channel [Spree::Channel, nil]
+    # @return [Spree::Catalogs::ResolveQuantityRules]
+    def quantity_rules_resolver_for(company: nil, user: nil, channel: nil)
+      key = catalog_memo_key(company: company, user: user, channel: channel)
+      quantity_rules_resolvers[key] ||= Spree::Catalogs::ResolveQuantityRules.new(
+        catalogs_for(company: company, user: user, channel: channel)
+      )
+    end
+
+    # @return [Hash]
+    def quantity_rules_resolvers
+      super || (self.quantity_rules_resolvers = {})
+    end
+
+    # The company a customer unambiguously buys for in this request. Resolved
+    # once: catalog resolution asks for it on every entry, and a product
+    # listing prices every variant through that path — unmemoized it was two
+    # queries per row.
+    #
+    # @param customer [Object, nil]
+    # @return [Spree::Company, nil]
+    def standing_company_for(customer)
+      return nil if store.nil?
+      # Checked before the cache, not only inside the lookup: the key is an
+      # id, so an admin and a customer sharing one would otherwise share an
+      # entry — whichever resolved first deciding for both.
+      return nil unless customer.is_a?(Spree.customer_class)
+
+      key = [store.id, customer.id]
+      return standing_companies[key] if standing_companies.key?(key)
+
+      standing_companies[key] = Spree::Company.sole_standing_for(store: store, customer: customer)
+    end
+
+    # @return [Hash]
+    def standing_companies
+      super || (self.standing_companies = {})
+    end
+
+    # Drops everything derived from the catalog set, so a write in this
+    # request is not read back through a memo it has already superseded.
+    # One call rather than a list every caller has to keep in step.
+    # @return [void]
+    def reset_catalog_memos
+      self.applicable_catalogs = nil
+      self.applicable_catalog_groups = nil
+      self.quantity_rules_resolvers = nil
+      self.standing_companies = nil
+      self.price_lists = nil
+    end
+
+    # Returns the current global pricing context, built from store, currency, country, and market.
     # @return [Spree::Pricing::Context]
     def global_pricing_context
       super || begin
         self.global_pricing_context = Spree::Pricing::Context.new(
           currency: currency,
           store: store,
-          zone: zone,
+          country: tax_country,
           market: market,
           channel: channel
         )
       end
     end
+
+    private
+
+    # One key for every buyer-derived memo, so they cannot drift apart.
+    #
+    # @return [Array]
+    def catalog_memo_key(company: nil, user: nil, channel: nil)
+      [store&.id, company&.id, normalized_catalog_user(user)&.id, (channel || self.channel)&.id]
+    end
+
+    # Normalized before the key is built, not just before the query: the key
+    # is an id, so an admin and a customer sharing one would share an entry.
+    #
+    # @return [Object, nil]
+    def normalized_catalog_user(user)
+      user if user.is_a?(Spree.customer_class)
+    end
   end
 end