spree_core 5.6.0 → 6.0.0.beta1

data/app/services/spree/imports/row_processors/product_variant.rb

@@ -7,20 +7,19 @@ module Spree
         def initialize(row, **)
           super
           @store = row.store
+          @seller = import.seller
           @product = ensure_product_exists
         end
 
-        attr_reader :product, :store
+        attr_reader :product, :store, :seller
 
         def process!
-          variant_scope = options.empty? ? product.variants_including_master : product.variants
-
           variant = if attributes['sku'].present?
-                      variant_scope.where(
+                      product.variants.where(
                         Spree::Variant.arel_table[:sku].lower.eq(attributes['sku'].strip.downcase)
                       ).first || product.variants.new
                     elsif options.empty?
-                      product.master
+                      product.default_variant
                     else
                       product.variants.new
                     end
@@ -28,12 +27,25 @@ module Spree
           variant.sku = attributes['sku'] if attributes['sku'].present?
           variant.cost_price = attributes['cost_price'] if attributes['cost_price'].present?
           variant.weight = attributes['weight'] if attributes['weight'].present?
+          variant.weight_unit = attributes['weight_unit'] if attributes['weight_unit'].present?
           variant.height = attributes['height'] if attributes['height'].present?
           variant.width = attributes['width'] if attributes['width'].present?
           variant.depth = attributes['depth'] if attributes['depth'].present?
+          variant.dimensions_unit = attributes['dimensions_unit'] if attributes['dimensions_unit'].present?
           variant.track_inventory = attributes['track_inventory'] if attributes['track_inventory'].present?
+          variant.hs_code = attributes['hs_code'] if attributes['hs_code'].present?
+          variant.country_of_origin = attributes['country_of_origin'] if attributes['country_of_origin'].present?
+          variant.customs_description = attributes['customs_description'] if attributes['customs_description'].present?
+          variant.units_per_carton = attributes['units_per_carton'] if attributes['units_per_carton'].present?
+          variant.carton_weight = attributes['carton_weight'] if attributes['carton_weight'].present?
+          variant.cartons_per_pallet = attributes['cartons_per_pallet'] if attributes['cartons_per_pallet'].present?
           variant.option_value_variants = prepare_option_value_variants if options.any?
 
+          if attributes['carton'].present?
+            carton = prepare_carton
+            variant.carton_package_type = carton if carton.present?
+          end
+
           if attributes['tax_category'].present?
             tax_category = prepare_tax_category
             variant.tax_category = tax_category if tax_category.present?
@@ -47,19 +59,41 @@ module Spree
           end
 
           if attributes['inventory_count'].present?
-            variant.set_stock(attributes['inventory_count'].to_i, attributes['inventory_backorderable']&.to_b)
+            variant.set_stock(
+              attributes['inventory_count'].to_i,
+              attributes['inventory_backorderable']&.to_b,
+              import_stock_location
+            )
           end
 
           handle_images(variant)
 
-          variant
+          remove_placeholder_default_variant if options.any?
+
+          # A row that resolves to a real option variant owns that Variant; a
+          # product/header row resolves to the option-less default (a placeholder
+          # that may later be removed), so it owns the Product instead — keeping the
+          # import row linked to a record that always survives.
+          variant.option_values.any? ? variant : product
         end
 
         private
 
+        # A product-header (options-empty) row creates an option-less default
+        # variant to hold product-level attributes. Once an option-bearing
+        # variant exists, that placeholder is a leftover — remove it and
+        # re-point the default so the product has exactly its option variants.
+        def remove_placeholder_default_variant
+          placeholders = product.variants.where.missing(:option_value_variants)
+          return if placeholders.empty?
+
+          placeholders.destroy_all
+          product.update_column(:default_variant_id, product.variants.reload.first&.id)
+        end
+
         def ensure_product_exists
           if options.empty?
-            # For master variants, create or update the product
+            # For product/header rows (no options), create or update the product
             product = Spree::Product.new
             if attributes['slug'].present?
               existing_product = product_scope.find_by(slug: attributes['slug'].strip.downcase)
@@ -69,18 +103,18 @@ module Spree
             # Store is touched when the import completes
             Spree::Store.no_touching do
               product = assign_attributes_to_product(product)
-              product.save!
+              save_through_workflow!(product)
             end
 
             handle_tags(product) if attributes['tags'].present?
             if has_product_attributes?
-              handle_metafields(product)
+              handle_custom_fields(product)
               handle_categories(product)
             end
 
             product
           else
-            # For non-master variants, only look up the product
+            # For variant rows (with options), only look up the product
             if attributes['slug'].present?
               product_scope.find_by!(slug: attributes['slug'].strip.downcase)
             else
@@ -89,16 +123,57 @@ module Spree
           end
         end
 
+        # Which products this import may resolve an existing row onto.
+        #
+        # A seller's import reaches only that seller's own products. The
+        # ability cannot answer this: it grants capability, never tenancy —
+        # a seller holding `write_products` gets `can :manage, Spree::Product`,
+        # the whole class (see Spree::Ability). On the API that is safe because
+        # the controller scope-fetches through `current_seller`; a background
+        # row processor has no controller, so the narrowing has to happen here
+        # or a CSV naming another seller's slug would edit their product.
         def product_scope
-          Spree::Product.accessible_by(import.current_ability, :manage)
+          scope = Spree::Product.accessible_by(import.current_ability, :manage)
+          seller.present? ? scope.where(seller_id: seller.id) : scope
+        end
+
+        # Imported rows pass the same :validate hook dashboard edits do — one
+        # gate, so a store's product rules can't be sidestepped by uploading
+        # a CSV. Attributes are already assigned, so the workflow gets the
+        # dirty record and nothing more.
+        def save_through_workflow!(product)
+          result =
+            if product.new_record?
+              Spree.product_create_workflow.call(store: product.store, record: product)
+            else
+              Spree.product_update_workflow.call(product: product)
+            end
+
+          if result.failure?
+            # A hook rejection carries its own errors, not the product's, so
+            # copy them across — otherwise the failed row records an empty
+            # validation_errors and the merchant sees no reason.
+            rejection = result.error&.value
+            if rejection.is_a?(ActiveModel::Errors) && product.errors.empty?
+              rejection.each { |error| product.errors.add(error.attribute, error.message) }
+            end
+
+            raise ActiveRecord::RecordInvalid, product
+          end
+
+          product
         end
 
         def assign_attributes_to_product(product)
-          # setting SKU for master variant so it will be picked up in process! and won't try to create a non-master variant
+          # set the SKU on a product/header row so process! updates the default variant instead of creating a new one
           if product.new_record?
             product.slug = attributes['slug']
             product.sku = attributes['sku'] if attributes['sku'].present? && options.empty?
             product.store = store
+            # A seller's import creates the seller's products. Without this the
+            # rows would land unowned — belonging to the store, invisible in the
+            # seller's own panel and unattributable at commission time.
+            product.seller = seller if seller.present?
             # Publish to the store's default channel so imported products surface
             # in the storefront.
             product.channels << store.default_channel if store.default_channel && product.channels.empty?
@@ -109,22 +184,53 @@ module Spree
           product.meta_title = attributes['meta_title'] if attributes['meta_title'].present?
           product.meta_description = attributes['meta_description'] if attributes['meta_description'].present?
           product.meta_keywords = attributes['meta_keywords'] if attributes['meta_keywords'].present?
-          product.status = to_spree_status(attributes['status']) if attributes['status'].present?
+          # A seller never reaches `active` by their own hand, so the CSV's
+          # status column is ignored on a seller's import — otherwise
+          # `status,active` would publish to the marketplace catalog with
+          # nobody having looked at it, which is the hole the JSON endpoint
+          # already closed (docs/plans/6.0-seller-product-submission.md).
+          # Imported products land as `draft`; the seller submits each for
+          # review afterwards.
+          if attributes['status'].present? && seller.blank?
+            product.status = to_spree_status(attributes['status'])
+          end
 
           if options.empty?
-            if attributes['shipping_category'].present?
-              shipping_category = prepare_shipping_category
-              product.shipping_category = shipping_category if shipping_category.present?
+            if attributes['product_type'].present?
+              product_type = prepare_product_type
+              product.product_type = product_type if product_type.present?
             end
           end
 
           product
         end
 
-        def prepare_shipping_category
-          shipping_category_name = attributes['shipping_category'].strip
-          cached_lookup(:shipping_category, shipping_category_name) do
-            Spree::ShippingCategory.find_by(name: shipping_category_name)
+        def prepare_product_type
+          product_type_name = attributes['product_type'].strip
+          cached_lookup(:product_type, product_type_name) do
+            existing = Spree::ProductType.where(store_id: store.id).find_by(name: product_type_name)
+            # A seller fills in a type's fields; they do not define types
+            # (`product_types` is read-only for the seller audience). An
+            # unknown name is ignored rather than created, so a CSV cannot
+            # extend the marketplace's own vocabulary.
+            next existing if seller.present?
+
+            existing || Spree::ProductType.create!(name: product_type_name, store_id: store.id)
+          end
+        end
+
+        # Named rather than referenced by id, like the tax category beside it —
+        # a merchant's spreadsheet says "Large carton", not a prefixed id.
+        def prepare_carton
+          carton_name = attributes['carton'].strip
+          cached_lookup(:carton_package_type, carton_name) do
+            # A seller's import reaches their own cartons and the
+            # marketplace's, ordered so their own row wins when both owners
+            # named a carton the same way — a seller's spreadsheet means their
+            # own measurements. An operator's import sees the marketplace's.
+            store.package_types.cartons.available_to_seller(seller).
+              order(Arel.sql('CASE WHEN seller_id IS NULL THEN 1 ELSE 0 END')).
+              find_by(name: carton_name)
           end
         end
 
@@ -135,6 +241,25 @@ module Spree
           end
         end
 
+        # Where an imported row's stock lands.
+        #
+        # Nil for an operator's import, which leaves `set_stock` to pick the
+        # store's default. A seller's stock belongs in their own warehouse:
+        # `Variant#default_stock_location` answers the *store's*, so without
+        # this a seller's `inventory_count` would deposit their goods in the
+        # marketplace's location — the same mistake the seller products
+        # endpoint narrows `stock_levels` to prevent.
+        #
+        # A seller with no location of their own falls back to the store's
+        # rather than dropping the count on the floor.
+        def import_stock_location
+          return nil if seller.blank?
+
+          cached_lookup(:seller_stock_location, seller.id) do
+            seller.stock_locations.active.order_default.first
+          end
+        end
+
         def prepare_option_value_variants
           return [] if options.empty?
 
@@ -174,26 +299,26 @@ module Spree
         # Recover the losing worker by re-fetching the peer's row whether the conflict
         # surfaces via the DB unique index (RecordNotUnique) or the AR uniqueness
         # validator (RecordInvalid with a :taken error on the relevant attribute).
-        def find_or_create_option_type!(presentation)
-          cached_lookup(:option_type, presentation) do
+        def find_or_create_option_type!(label)
+          cached_lookup(:option_type, label) do
             begin
-              Spree::OptionType.search_by_name(presentation).first || Spree::OptionType.create!(presentation: presentation)
+              Spree::OptionType.search_by_name(label).first || Spree::OptionType.create!(label: label)
             rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid => e
               raise unless uniqueness_conflict?(e, :name)
 
-              Spree::OptionType.search_by_name(presentation).first!
+              Spree::OptionType.search_by_name(label).first!
             end
           end
         end
 
-        def find_or_create_option_value!(option_type, presentation)
-          cached_lookup(:option_value, option_type.id, presentation) do
+        def find_or_create_option_value!(option_type, label)
+          cached_lookup(:option_value, option_type.id, label) do
             begin
-              option_type.option_values.search_by_name(presentation).first || option_type.option_values.create!(presentation: presentation)
+              option_type.option_values.search_by_name(label).first || option_type.option_values.create!(label: label)
             rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid => e
               raise unless uniqueness_conflict?(e, :name)
 
-              option_type.option_values.search_by_name(presentation).first!
+              option_type.option_values.search_by_name(label).first!
             end
           end
         end
@@ -226,9 +351,10 @@ module Spree
           return if image_urls.empty?
 
           # Always attach to the product so blobs aren't duplicated across
-          # variants. For non-master rows, pass the variant id so the job links
-          # the resulting product-level asset to that variant via VariantMedia.
-          link_variant_id = variant.is_master? ? nil : variant.id
+          # variants. For option rows, pass the variant id so the job links the
+          # resulting product-level asset to that variant via VariantMedia; a
+          # simple product's default variant keeps images product-level.
+          link_variant_id = options.empty? ? nil : variant.id
 
           image_urls.each do |image_url|
             Spree::Images::SaveFromUrlJob.perform_later(
@@ -246,60 +372,75 @@ module Spree
           %w[name status description category1 category2 category3].any? { |key| attributes[key].present? }
         end
 
-        def handle_metafields(product)
-          return unless product.class.included_modules.include?(Spree::Metafields)
+        def handle_custom_fields(product)
+          return unless product.class.included_modules.include?(Spree::HasCustomFields)
 
-          metafield_attributes = attributes.select { |key, _value| key.to_s.start_with?('metafield.') }
-          return if metafield_attributes.empty?
+          custom_field_attributes = attributes.select { |key, _value| key.to_s.start_with?('custom_field.') }
+          return if custom_field_attributes.empty?
 
-          # Build nested attributes for metafields
+          # Build nested attributes for custom_fields
           nested_attrs = []
 
-          metafield_attributes.each do |attribute_key, value|
-            # Extract namespace.key from "metafield.namespace.key"
-            full_key = attribute_key.to_s.sub(/^metafield\./, '')
+          custom_field_attributes.each do |attribute_key, value|
+            # Extract namespace.key from "custom_field.namespace.key"
+            full_key = attribute_key.to_s.sub(/^custom_field\./, '')
             namespace, key = product.extract_namespace_and_key(full_key)
 
-            # Find or initialize metafield definition
-            metafield_definition = cached_lookup(:metafield_definition, namespace, key, product.class.name) do
-              Spree::MetafieldDefinition.find_by(
+            # Find or initialize custom_field definition
+            custom_field_definition = cached_lookup(:custom_field_definition, namespace, key, product.class.name) do
+              store.custom_field_definitions.find_by(
                 namespace: namespace,
                 key: key,
                 resource_type: product.class.name
               )
             end
 
-            next unless metafield_definition
+            next unless custom_field_definition
 
-            # Find existing metafield if product is persisted
-            existing_metafield = product.persisted? ? product.metafields.find_by(metafield_definition: metafield_definition) : nil
+            # Find existing custom_field if product is persisted
+            existing_custom_field = product.persisted? ? product.custom_fields.find_by(custom_field_definition: custom_field_definition) : nil
 
-            # Skip blank values for new metafields
-            next if value.blank? && existing_metafield.nil?
+            # Skip blank values for new custom_fields
+            next if value.blank? && existing_custom_field.nil?
 
-            # For existing metafields with blank values, we'll mark them for destruction
-            # For new metafields, we skip them (handled above)
-            # For existing or new metafields with values, we create/update them
-            metafield_attrs = {
-              metafield_definition_id: metafield_definition.id,
+            # For existing custom_fields with blank values, we'll mark them for destruction
+            # For new custom_fields, we skip them (handled above)
+            # For existing or new custom_fields with values, we create/update them
+            custom_field_attrs = {
+              custom_field_definition_id: custom_field_definition.id,
               value: value.to_s.strip,
-              type: metafield_definition.metafield_type
+              type: custom_field_definition.field_type_class_name
             }
 
-            metafield_attrs[:id] = existing_metafield.id if existing_metafield
+            custom_field_attrs[:id] = existing_custom_field.id if existing_custom_field
 
-            nested_attrs << metafield_attrs
+            nested_attrs << custom_field_attrs
           end
 
-          product.update(metafields_attributes: nested_attrs) unless nested_attrs.empty?
+          product.update!(custom_fields_attributes: nested_attrs) unless nested_attrs.empty?
         end
 
+        # Tags are tenanted to the store (`acts_as_taggable_tenant :store_id`),
+        # so a seller typing one adds a term to the marketplace's shared
+        # vocabulary rather than labelling their own product — which is why the
+        # seller products endpoint does not permit them either.
         def handle_tags(product)
+          return if seller.present?
+          return Spree::Imports::AssignTagsJob.perform_now(product.id, attributes['tags']) if import.preferred_inline
+
           Spree::Imports::AssignTagsJob.perform_later(product.id, attributes['tags'])
         end
 
+        # How a product is filed is the marketplace's own merchandising, and
+        # this job *creates* the categories it cannot find. `categories` has no
+        # seller audience in the permission catalog at all.
         def handle_categories(product)
-          Spree::Imports::CreateCategoriesJob.perform_later(product.id, store.id, prepare_taxon_pretty_names)
+          return if seller.present?
+
+          names = prepare_taxon_pretty_names
+          return Spree::Imports::CreateCategoriesJob.perform_now(product.id, store.id, names) if import.preferred_inline
+
+          Spree::Imports::CreateCategoriesJob.perform_later(product.id, store.id, names)
         end
 
         def prepare_taxon_pretty_names

data/app/services/spree/imports/row_processors/purchase_order.rb

@@ -0,0 +1,157 @@
+module Spree
+  module Imports
+    module RowProcessors
+      # One line of a purchase order. The first row carrying a reference opens
+      # a draft for it through the same workflow the screen uses; every later
+      # row with that reference adds its line. Suppliers, warehouses and SKUs
+      # are named, not created: a typo must fail the row, not spawn a record.
+      class PurchaseOrder < Base
+        QUANTITY_FORMAT = /\A\d+\z/
+        AMOUNT_FORMAT = /\A\d+(\.\d+)?\z/
+
+        def initialize(row, **)
+          super
+          @store = import.store
+        end
+
+        attr_reader :store
+
+        def process!
+          reference = attributes['reference'].to_s.strip
+          raise ArgumentError, Spree.t(:purchase_order_import_reference_required) if reference.blank?
+
+          line = {
+            variant: find_variant,
+            quantity_ordered: quantity_for(attributes['quantity']),
+            unit_cost: amount_for(attributes['unit_cost'])
+          }
+
+          cache = import.row_lookup_cache
+          key = [:purchase_order_import_order, reference]
+          if cache.key?(key)
+            add_line(cache[key], line)
+          else
+            cache[key] = open_draft(reference, line)
+          end
+        end
+
+        private
+
+        def open_draft(reference, line)
+          result = Spree::PurchaseOrders::Create.call(
+            store: store,
+            supplier: find_supplier,
+            destination_location: find_destination,
+            items: [line],
+            currency: currency_for(attributes['currency']),
+            expected_at: date_for(attributes['expected_at'], 'expected_at'),
+            cancel_by: date_for(attributes['cancel_by'], 'cancel_by'),
+            reference: reference,
+            notes: attributes['notes'].to_s.strip.presence,
+            created_by: import.user
+          )
+          raise ArgumentError, failure_message(result) unless result.success?
+
+          result.value
+        end
+
+        # The update replaces the lines wholesale, so the ones already on the
+        # draft go back with the new one. A SKU repeated under one reference
+        # is one line with the quantities added, the way a picker would total
+        # two cartons of the same thing.
+        def add_line(purchase_order, line)
+          lines = purchase_order.items.map do |item|
+            { variant: item.variant, quantity_ordered: item.quantity_ordered, unit_cost: item.unit_cost }
+          end
+          existing = lines.find { |entry| entry[:variant].id == line[:variant].id }
+          if existing
+            existing[:quantity_ordered] += line[:quantity_ordered]
+          else
+            lines << line
+          end
+
+          result = Spree::PurchaseOrders::Update.call(purchase_order: purchase_order, items: lines)
+          raise ArgumentError, failure_message(result) unless result.success?
+
+          result.value
+        end
+
+        def find_supplier
+          name = attributes['supplier'].to_s.strip
+          raise ArgumentError, Spree.t(:purchase_order_import_supplier_required) if name.blank?
+
+          cached_lookup(:purchase_order_import_supplier, name.downcase) do
+            store.suppliers.find_by(Spree::Supplier.arel_table[:name].lower.eq(name.downcase))
+          end || raise(ArgumentError, Spree.t(:purchase_order_import_unknown_supplier, name: name))
+        end
+
+        def find_destination
+          name = attributes['destination'].to_s.strip
+          raise ArgumentError, Spree.t(:purchase_order_import_destination_required) if name.blank?
+
+          cached_lookup(:purchase_order_import_destination, name.downcase) do
+            store.stock_locations.find_by(Spree::StockLocation.arel_table[:name].lower.eq(name.downcase))
+          end || raise(ArgumentError, Spree.t(:purchase_order_import_unknown_destination, name: name))
+        end
+
+        def find_variant
+          sku = attributes['sku'].to_s.strip
+          raise ArgumentError, Spree.t(:purchase_order_import_sku_required) if sku.blank?
+
+          variants = cached_lookup(:purchase_order_import_variant, sku.downcase) do
+            store.variants.where(Spree::Variant.arel_table[:sku].lower.eq(sku.downcase)).limit(2).to_a
+          end
+          raise ArgumentError, Spree.t(:purchase_order_import_unknown_sku, sku: sku) if variants.empty?
+          raise ArgumentError, Spree.t(:purchase_order_import_ambiguous_sku, sku: sku) if variants.many?
+
+          variants.first
+        end
+
+        def quantity_for(value)
+          text = value.to_s.strip
+          unless text.match?(QUANTITY_FORMAT) && text.to_i.positive?
+            raise ArgumentError, Spree.t(:purchase_order_import_invalid_quantity, value: text)
+          end
+
+          text.to_i
+        end
+
+        def amount_for(value)
+          text = value.to_s.strip
+          raise ArgumentError, Spree.t(:purchase_order_import_invalid_cost, value: text) unless text.match?(AMOUNT_FORMAT)
+
+          BigDecimal(text)
+        end
+
+        def currency_for(value)
+          currency = value.to_s.strip.upcase.presence || store.default_currency
+          return currency if supported_currencies.include?(currency)
+
+          raise ArgumentError, Spree.t(:purchase_order_import_unsupported_currency, currency: currency)
+        end
+
+        def supported_currencies
+          cached_lookup(:purchase_order_import_currencies) { store.supported_currencies_list.map(&:iso_code) }
+        end
+
+        # A complete date only: `Date.parse` would take "March" and guess the
+        # rest, and a guessed delivery date is worse than none.
+        def date_for(value, column)
+          text = value.to_s.strip
+          return nil if text.blank?
+
+          Date.iso8601(text)
+        rescue Date::Error
+          raise ArgumentError, Spree.t(:purchase_order_import_invalid_date, column: column, value: text)
+        end
+
+        def failure_message(result)
+          error = result.error
+          return error.full_messages.to_sentence if error.respond_to?(:full_messages)
+
+          error.to_s.presence || Spree.t(:purchase_order_import_failed)
+        end
+      end
+    end
+  end
+end

data/app/services/spree/media/destroy.rb

@@ -0,0 +1,88 @@
+module Spree
+  class Media
+    # Deletes a library file everywhere at once: every placement sharing its
+    # blob, every plain attachment (a category image slot, a store logo)
+    # holding it, then the row itself — whose purge takes the blob with it once
+    # nothing references it. The alternative was refusing until the merchant
+    # cleared each use by hand, which is busywork the usage list already knows
+    # how to do.
+    #
+    # Scoped to the file's own store: a blob another tenant happens to share
+    # keeps their attachments, and the foreign key keeps the file in storage
+    # for them. Rich text embeds are plain URLs with nothing to detach — those
+    # descriptions lose the image, which is what the caller's confirmation
+    # acknowledged.
+    class Destroy
+      prepend Spree::ServiceModule::Base
+
+      # @param media [Spree::Media] the library row being deleted
+      # @return [Spree::ServiceModule::Result]
+      def call(media:)
+        # Only the file this row *is*, never its poster: a poster is a still
+        # another row may legitimately use as its own picture, and deleting a
+        # video must not take that image with it. The row's own poster goes
+        # when the row does.
+        blob_ids = [media.attachment_blob&.id].compact
+
+        # Detaching is collected inside the transaction and enqueued after it
+        # commits: purge_later hands the file to a worker that may run before
+        # the transaction ends, so a rollback would leave the rows intact with
+        # their file already gone.
+        detachable = nil
+
+        ApplicationRecord.transaction do
+          destroy_placements(media, blob_ids)
+          detachable = plain_attachments(media, blob_ids)
+          media.destroy!
+        end
+
+        # ActiveRecord::Rollback is swallowed by the transaction block, so a
+        # surviving row is how a rolled-back delete reports itself. Detaching
+        # then would strip the file from records the delete did not remove.
+        return failure(media) if media.persisted?
+
+        detachable.each(&:purge_later)
+
+        success(media)
+      end
+
+      private
+
+      # Other rows sharing the file — placements on products, categories,
+      # collections. destroy, not delete: the callbacks are what refresh the
+      # owners' thumbnails and counters.
+      def destroy_placements(media, blob_ids)
+        return if blob_ids.empty?
+
+        Spree::Media
+          .where(store_id: media.store_id)
+          .where.not(id: media.id)
+          .joins(:attachment_attachment)
+          .where(ActiveStorage::Attachment.table_name => { blob_id: blob_ids })
+          .find_each(&:destroy!)
+      end
+
+      # The plain attachments this store holds on the file — a category image
+      # slot, a store logo. Media rows are handled by destroy_placements.
+      #
+      # @return [Array<ActiveStorage::Attachment>]
+      def plain_attachments(media, blob_ids)
+        ActiveStorage::Attachment.where(blob_id: blob_ids).select do |attachment|
+          owner = attachment.record
+          next false if owner.blank? || owner.is_a?(Spree::Media)
+
+          owned_by_store?(owner, media.store_id)
+        end
+      end
+
+      # Ownership must be proven, never assumed. A Spree::Store has no
+      # store_id of its own, so treating a blank one as "mine" made every
+      # other store's logo look local — and deleting a file would strip it.
+      def owned_by_store?(owner, store_id)
+        return owner.id == store_id if owner.is_a?(Spree::Store)
+
+        owner.try(:store_id) == store_id
+      end
+    end
+  end
+end