spree_core 5.6.0 → 6.0.0.beta1

data/lib/tasks/migrate_returns.rake

@@ -0,0 +1,322 @@
+# Defined here rather than in lib/spree/core/ — this is a one-release upgrade
+# step that dies with the legacy tables in 6.1, not engine infrastructure.
+# Same placement as Spree::TypedAdjustmentsMigration in the sibling task.
+module Spree
+  # Copies the legacy ReturnAuthorization chain onto the 6.0 Return and
+  # Exchange models. Driven by `rake spree:upgrade:migrate_returns`.
+  #
+  # Reads the legacy tables through throwaway model classes rather than the
+  # legacy models, which no longer exist in 6.0. Historical rows are written
+  # with `save(validate: false)`: they can reference deleted variants and
+  # stock locations that today's validations reject, and refusing to copy
+  # history is worse than copying it imperfectly.
+  #
+  # Resumable by construction. The legacy `number` is copied onto the new
+  # record and uniquely indexed there, so the work still outstanding is a
+  # query — `where.not(number: already_migrated)` — rather than tracked
+  # state. An interrupted run picks up exactly where it stopped, a re-run is
+  # a no-op, and there is no cursor or checkpoint that can drift out of sync
+  # with what was actually written.
+  class ReturnsMigrator
+    LEGACY_TABLE = 'spree_return_authorizations'.freeze
+
+    def initialize(batch_size: 500)
+      @batch_size = batch_size
+      @returns = 0
+      @exchanges = 0
+      @skipped = 0
+      @failed = []
+      # Schema facts, fixed for the life of the run. The column outlives the
+      # table by a release: Spree::Refund stopped declaring the association
+      # in 6.0 and the column drops in 6.1.
+      @relink_refunds = connection.table_exists?('spree_reimbursements') &&
+                        connection.column_exists?(Spree::Refund.table_name, :reimbursement_id)
+    end
+
+    # @return [Hash, nil] counts, or nil when there is nothing to migrate
+    def call
+      return nil unless connection.table_exists?(LEGACY_TABLE)
+
+      pending.find_each(batch_size: batch_size) do |authorization|
+        migrate_one(authorization)
+      end
+
+      { returns: @returns, exchanges: @exchanges, skipped: @skipped, failed: @failed }
+    end
+
+    private
+
+    attr_reader :batch_size
+
+    def connection
+      ActiveRecord::Base.connection
+    end
+
+    # Authorizations not yet carried across.
+    #
+    # Two subqueries rather than a plucked IN-list: on a resumed run over a
+    # large store the list would be every number already migrated, shipped
+    # back as bind params. Both sides hit the unique index on `number`. Same
+    # shape as migrate_users_to_customers' `where.not(id: model.select(:id))`.
+    #
+    # The NULL branch is load-bearing: `NULL NOT IN (...)` is UNKNOWN, not
+    # true, so a numberless legacy row would be filtered out by the two
+    # subqueries and never migrate at all. Those rows can't be matched by
+    # number, so `migrated_numberless_ids` tracks them by legacy id instead —
+    # otherwise a second run would copy them again under a fresh number.
+    def pending
+      scope = legacy_authorization.
+              where.not(number: Spree::Return.select(:number)).
+              where.not(number: Spree::Exchange.select(:number))
+
+      numberless = legacy_authorization.where(number: nil).
+                   where.not(id: migrated_numberless_ids)
+
+      legacy_authorization.where(id: scope.select(:id)).or(
+        legacy_authorization.where(id: numberless.select(:id))
+      )
+    end
+
+    # Numberless rows are stamped with their legacy id at copy time, which is
+    # the only durable link back to the source row.
+    def migrated_numberless_ids
+      @migrated_numberless_ids ||=
+        (Spree::Return.where.not(metadata: nil).pluck(:metadata) +
+         Spree::Exchange.where.not(metadata: nil).pluck(:metadata)).
+        filter_map { |data| parse_metadata(data)['legacy_return_authorization_id'] }
+    end
+
+    def parse_metadata(data)
+      return data if data.is_a?(Hash)
+
+      JSON.parse(data.to_s)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def legacy_authorization
+      @legacy_authorization ||= Class.new(Spree.base_class) do
+        self.table_name = LEGACY_TABLE
+        def self.name = 'LegacyReturnAuthorization'
+      end
+    end
+
+    def legacy_item
+      @legacy_item ||= Class.new(Spree.base_class) do
+        self.table_name = 'spree_return_items'
+        def self.name = 'LegacyReturnItem'
+      end
+    end
+
+    def migrate_one(authorization)
+      items = legacy_item.where(return_authorization_id: authorization.id).to_a
+      order = Spree::Order.find_by(id: authorization.order_id)
+
+      if items.empty? || order.nil?
+        @skipped += 1
+        return
+      end
+
+      # One lookup for the whole authorization rather than one per item.
+      fulfillment_items = Spree::FulfillmentItem.
+                          where(id: items.filter_map(&:fulfillment_item_id).uniq).index_by(&:id)
+
+      exchange = items.any? { |item| item.exchange_variant_id.present? }
+
+      ActiveRecord::Base.transaction do
+        record =
+          if exchange
+            build_exchange(authorization, items, order, fulfillment_items)
+          else
+            build_return(authorization, items, order, fulfillment_items)
+          end
+
+        relink_refunds(items, record)
+      end
+
+      # After the transaction commits, never before: a row that raises is
+      # recorded in @failed only, so the counts and the failure list can't
+      # both claim the same authorization.
+      exchange ? @exchanges += 1 : @returns += 1
+    rescue StandardError => error
+      @failed << "##{authorization.id} (#{authorization.number || 'no number'}): #{error.message}"
+    end
+
+    # A legacy authorization only ever reached "authorized" or "canceled";
+    # how far the return actually got is recorded on its items instead.
+    #
+    # `settled_as` is what a reimbursed row becomes: a Return was refunded,
+    # an Exchange was fulfilled — money back on an exchange is the price
+    # difference, which the legacy chain settled at reimbursement time.
+    def status_for(authorization, items, settled_as: 'refunded')
+      return 'canceled' if authorization.state == 'canceled'
+      return settled_as if items.any? { |item| item.reimbursement_id.present? }
+      return 'received' if items.any? { |item| item.reception_status == 'received' }
+
+      'approved'
+    end
+
+    # The header both record types share: same attributes, same preserved
+    # number, same unvalidated save. Only the class and the settled status
+    # differ, and keeping this in one place is what stops the two save paths
+    # drifting apart.
+    def build_header(klass, authorization, order, status)
+      record = klass.new(
+        store: order.store,
+        order: order,
+        stock_location_id: authorization.stock_location_id,
+        reason_id: authorization.return_authorization_reason_id,
+        memo: authorization.memo,
+        status: status,
+        created_at: authorization.created_at,
+        updated_at: authorization.updated_at
+      )
+      # Required, not an optimisation: Spree::HasNumber assigns the number in a
+      # before_validation hook, which save!(validate: false) below skips — so
+      # without this the NOT NULL constraint on `number` rejects the row. The
+      # legacy number is also what makes a re-run idempotent, so a generated
+      # one would break resumption as well as lose the link to history.
+      #
+      # A legacy row with no number can't participate in either, so it falls
+      # back to a generated one and records where it came from — that stamp is
+      # what `migrated_numberless_ids` reads to keep a re-run from copying it
+      # a second time under a different generated number.
+      if authorization.number.present?
+        record.number = authorization.number
+      else
+        record.generate_number
+        # write_attribute, not #metadata= — see migrated_numberless_ids.
+        record.write_attribute(:metadata, { 'legacy_return_authorization_id' => authorization.id })
+      end
+
+      record.save!(validate: false)
+      record
+    end
+
+    def build_return(authorization, items, order, fulfillment_items)
+      record = build_header(Spree::Return, authorization, order, status_for(authorization, items))
+
+      items.each do |item|
+        fulfillment_item = fulfillment_items[item.fulfillment_item_id]
+
+        record.return_line_items.new(
+          line_attributes_for(item, fulfillment_item).merge(
+            variant_id: fulfillment_item&.variant_id,
+            pre_tax_amount: item.pre_tax_amount,
+            resellable: item.resellable
+          )
+        ).save!(validate: false)
+      end
+
+      record
+    end
+
+    def build_exchange(authorization, items, order, fulfillment_items)
+      record = build_header(
+        Spree::Exchange, authorization, order,
+        status_for(authorization, items, settled_as: 'fulfilled')
+      )
+
+      items.each do |item|
+        next if item.exchange_variant_id.blank?
+
+        fulfillment_item = fulfillment_items[item.fulfillment_item_id]
+
+        record.exchange_line_items.new(
+          line_attributes_for(item, fulfillment_item).merge(
+            original_variant_id: fulfillment_item&.variant_id,
+            new_variant_id: item.exchange_variant_id
+          )
+        ).save!(validate: false)
+      end
+
+      record
+    end
+
+    def line_attributes_for(item, fulfillment_item)
+      {
+        fulfillment_item_id: item.fulfillment_item_id,
+        line_item_id: fulfillment_item&.line_item_id,
+        quantity: 1,
+        received_quantity: item.reception_status == 'received' ? 1 : 0,
+        created_at: item.created_at,
+        updated_at: item.updated_at
+      }
+    end
+
+    # Keeps the money history attached to something the admin can still see.
+    #
+    # Addresses spree_refunds.reimbursement_id by column name rather than
+    # through the association: Spree::Refund no longer declares it in 6.0,
+    # and the column itself is dropped in 6.1.
+    def relink_refunds(items, record)
+      return unless @relink_refunds
+
+      reimbursement_ids = items.filter_map(&:reimbursement_id).uniq
+      return if reimbursement_ids.empty?
+
+      Spree::Refund.where(reimbursement_id: reimbursement_ids).
+        update_all(originator_type: record.class.to_s, originator_id: record.id)
+    end
+  end
+end
+
+namespace :spree do
+  namespace :upgrade do
+    desc <<~DESC
+      Moves the legacy ReturnAuthorization chain onto the 6.0 returns models
+      (docs/plans/6.0-returns-exchanges-claims.md).
+
+      Each +spree_return_authorizations+ row becomes a +Spree::Return+, or a
+      +Spree::Exchange+ when any of its return items named an exchange variant.
+      Refunds produced through a reimbursement are re-pointed at the new record
+      via the polymorphic +originator+, so the money history stays attached to
+      something the admin can still see.
+
+      Resumable by construction: the legacy +number+ is copied onto the new
+      record and uniquely indexed there, so the task scopes itself to the
+      authorizations whose number isn't present yet. An interrupted run picks
+      up exactly where it stopped, and re-running when nothing is left is a
+      no-op — no cursor to track, no state to reset.
+
+      Reads the legacy tables by name through throwaway model classes; the
+      legacy models themselves are deleted in 6.0. The tables stay in place as
+      a rollback safety net and drop in 6.1.
+
+      A row that can't be converted is reported and skipped so one bad
+      authorization doesn't stop the batch, but the task then aborts, because
+      an upgrade must not continue on top of incomplete returns history.
+      Re-run to retry those rows, or pass SKIP_FAILED_ROWS=true to accept the
+      gap and continue.
+
+      Set BATCH_SIZE to tune how many authorizations are loaded at a time
+      (default 500).
+    DESC
+    task migrate_returns: :environment do
+      options = ENV['BATCH_SIZE'] ? { batch_size: ENV['BATCH_SIZE'].to_i } : {}
+      result = Spree::ReturnsMigrator.new(**options).call
+
+      if result.nil?
+        puts '  spree_return_authorizations not found — nothing to migrate.'
+        next
+      end
+
+      puts "  Migrated #{result[:returns]} return(s) and #{result[:exchanges]} exchange(s); " \
+           "skipped #{result[:skipped]}."
+
+      next if result[:failed].empty?
+
+      # Aborts so upgrade automation stops here rather than carrying on with
+      # returns history that is missing rows. Every failure is retried by
+      # simply re-running — the task scopes itself to what isn't migrated yet.
+      puts "  #{result[:failed].size} row(s) could not be migrated:"
+      result[:failed].each { |line| puts "  #{line}" }
+
+      if ENV['SKIP_FAILED_ROWS'] == 'true'
+        puts '  Continuing anyway (SKIP_FAILED_ROWS=true).'
+      else
+        abort '  Re-run to retry them, or pass SKIP_FAILED_ROWS=true to accept the gap and continue.'
+      end
+    end
+  end
+end

data/lib/tasks/migrate_rich_text_to_columns.rake

@@ -0,0 +1,128 @@
+namespace :spree do
+  desc <<~DESC
+    Copies rich text out of Action Text into the plain text columns that own it
+    in Spree 6.0 — category and collection descriptions, policy bodies, and the
+    order and customer internal notes.
+
+    Run through +spree:upgrade+. Two steps must come first:
+
+    - spree:migrate_taxons_to_categories_and_collections, which retypes the
+      Action Text rows from Spree::Taxon to Spree::Category so they stay
+      findable here.
+    - spree:upgrade:migrate_users_to_customers, which populates spree_customers.
+      A note is copied onto the customer row it belongs to, so running before
+      those rows exist would count every legacy customer note as orphaned and
+      skip it permanently.
+
+    Only copies where an Action Text row exists, so a description already living
+    in the column is never overwritten with a blank. Per-locale rows land in the
+    model's translation table. Content is sanitized on the way in, through the
+    same allowlist as any other write.
+
+    Idempotent — a row whose column already matches the sanitized Action Text
+    body is skipped, and writes go through +update_all+ so timestamps and
+    webhooks don't churn. Source rows are left in place as the rollback path and
+    are dropped with the Action Text tables in 6.1.
+  DESC
+  task migrate_rich_text_to_columns: :environment do
+    # Action Text is not loaded by Spree any more — 6.0 stores rich text in its
+    # own columns. It ships with Rails, so this one-off copy pulls it in itself
+    # rather than making every app carry the engine for a task it runs once.
+    loaded = begin
+      require 'action_text/engine'
+      ActionText::RichText.table_exists?
+    rescue LoadError, NameError, ActiveRecord::StatementInvalid
+      false
+    end
+
+    unless loaded
+      puts '  No action_text_rich_texts table — nothing to migrate.'
+      next
+    end
+
+    # Each entry maps an Action Text attachment to the column that now owns it.
+    # +translation_class+ is nil for models whose field isn't translated.
+    #
+    # +record_types+ lists the class names to match in action_text_rich_texts.
+    # migrate_users_to_customers retypes those rows; matching the legacy name as
+    # well covers an install that ran an earlier build of that task, before it
+    # retyped them. It does NOT make this step safe to run first — see above.
+    targets = [
+      { model: Spree::Category, translation_class: Spree::Category::Translation, name: 'description', column: :description },
+      { model: Spree::Collection, translation_class: Spree::Collection::Translation, name: 'description', column: :description },
+      { model: Spree::Policy, translation_class: Spree::Policy::Translation, name: 'body', column: :body },
+      { model: Spree::Order, translation_class: nil, name: 'internal_note', column: :internal_note },
+      {
+        model: Spree.customer_class, translation_class: nil, name: 'internal_note', column: :internal_note,
+        record_types: [Spree.customer_class(constantize: false), ENV.fetch('SOURCE_USER_TYPE', 'Spree::User')].compact.uniq
+      }
+    ]
+
+    default_locale = I18n.default_locale.to_s
+
+    # Writes only when the target still holds the value that was read, so an
+    # edit landing between read and write is never clobbered. Selecting the id
+    # alongside the column distinguishes a missing row from a NULL column, so
+    # this doubles as the orphan check.
+    copy = lambda do |relation, id, column, html|
+      found = relation.where(id: id).pick(:id, column)
+      next :missing if found.nil?
+
+      current = found.last
+      sanitized = Spree::RichTextSanitizer.sanitize(html)
+      next false if current == sanitized
+
+      relation.where(id: id, column => current).update_all(column => sanitized).positive?
+    end
+
+    targets.each do |target|
+      model = target[:model]
+      next if model.nil? || !model.table_exists?
+
+      column = target[:column]
+      next unless model.column_names.include?(column.to_s)
+
+      base = model.unscoped
+      copied = 0
+      translated = 0
+      missing = 0
+
+      translation_class = target[:translation_class]
+      # Mobility names the join column after the model (spree_category_id);
+      # read it off the association rather than rebuilding it by hand.
+      foreign_key = translation_class&.reflect_on_association(:translated_model)&.foreign_key
+
+      record_types = target[:record_types] || [model.name]
+      rows = ActionText::RichText.where(record_type: record_types, name: target[:name]).where.not(body: [nil, ''])
+
+      rows.find_each do |row|
+        # Read the stored column, not +body.to_s+ — the Action Text renderer
+        # wraps output in <div class="trix-content">, and migrating that wrapper
+        # would carry Trix's presentation into every column.
+        html = row.read_attribute_before_type_cast('body').to_s
+        locale = row.locale.presence || default_locale
+
+        if locale == default_locale
+          case copy.call(base, row.record_id, column, html)
+          when :missing then missing += 1
+          when true then copied += 1
+          end
+          next
+        end
+
+        next if translation_class.nil?
+
+        translation = translation_class.find_or_initialize_by(foreign_key => row.record_id, locale: locale)
+        # Create the row empty, then let the one +copy+ path fill it, so both
+        # branches share a single sanitize and a single write mechanism.
+        translation.save(validate: false) if translation.new_record?
+
+        translated += 1 if copy.call(translation_class, translation.id, column, html) == true
+      end
+
+      puts "  #{model.name}: copied #{copied} #{column}(s)."
+      puts "  #{model.name}: copied #{translated} translated #{column}(s)." if translated.positive?
+      puts "  #{model.name}: skipped #{missing} orphaned row(s)." if missing.positive?
+    end
+  end
+end

data/lib/tasks/migrate_users_to_customers.rake

@@ -0,0 +1,161 @@
+namespace :spree do
+  namespace :upgrade do
+    desc <<~DESC
+      Moves an existing Devise-based user table onto the gem-owned auth models
+      (Spree 6.0). Copies rows from the legacy customer table (default
+      +spree_users+, override with SOURCE_USER_TABLE) into +spree_customers+ —
+      preserving primary keys so the already-renamed +customer_id+ foreign keys
+      still resolve, and mapping +encrypted_password+ into +password_digest+ —
+      then re-points every polymorphic reference that named the old customer
+      class (default +Spree::User+, override with SOURCE_USER_TYPE) to
+      +Spree.customer_class+ — the +user_type+ columns plus +customer_type+ on
+      customer-group memberships — and backfills +password_digest+ on
+      +spree_admin_users+ from its legacy +encrypted_password+.
+
+      Passwords survive with zero resets only when no Devise pepper was
+      configured — Devise's +encrypted_password+ is a plain bcrypt digest, the
+      exact format +has_secure_password+ reads. The task aborts if a pepper is
+      detected; when Devise is absent (so a former pepper can't be introspected)
+      it aborts until you confirm none was used with CONFIRM_NO_PEPPER=true.
+      Source rows with a blank email, or whose email is already taken by a
+      different customer, abort the task with their ids — reconcile them or pass
+      SKIP_INVALID_ROWS=true to skip and continue. The legacy source table is
+      left in place as a safety net.
+
+      Idempotent — re-running skips rows already present in +spree_customers+.
+      Batch size defaults to 1000 (override with BATCH_SIZE).
+    DESC
+    task migrate_users_to_customers: :environment do
+      connection = ActiveRecord::Base.connection
+
+      source_table = ENV.fetch('SOURCE_USER_TABLE', 'spree_users')
+      old_type     = ENV.fetch('SOURCE_USER_TYPE', 'Spree::User')
+      new_type     = Spree.customer_class.to_s
+      batch_size   = (ENV['BATCH_SIZE'] || 1000).to_i
+
+      unless connection.table_exists?(source_table)
+        puts "  #{source_table} not found — nothing to migrate."
+        next
+      end
+
+      # Peppered digests can't be verified by has_secure_password. Refuse rather
+      # than silently produce accounts nobody can sign into. Once Devise is gone
+      # a former pepper can't be introspected, so require an explicit all-clear.
+      if defined?(Devise) && Devise.respond_to?(:pepper) && Devise.pepper.present?
+        abort "  Devise.pepper is configured — bcrypt digests can't be copied into password_digest. " \
+              "Use the custom-model path (keep the table, alias password_digest) or force password resets."
+      elsif !defined?(Devise) && ENV['CONFIRM_NO_PEPPER'] != 'true'
+        abort "  Devise isn't loaded, so a former Devise pepper can't be detected. A peppered digest " \
+              "copied as-is can't be verified by has_secure_password — every migrated account would be " \
+              "locked out silently. Re-run with CONFIRM_NO_PEPPER=true once you've confirmed the source " \
+              "used no pepper, or use the custom-model path / force password resets."
+      end
+
+      customer_model = Spree.customer_class
+      admin_model    = Spree.admin_user_class
+
+      # Read the legacy table by name only — the Devise-era Spree::User /
+      # Spree::LegacyUser models are gone in 6.0. Inherit from Spree.base_class
+      # so the source shares the customer table's connection (the id-exclusion
+      # subquery below spans both).
+      source = Class.new(Spree.base_class) { self.table_name = source_table }
+
+      # Copy only columns both tables share; map the digest column separately.
+      direct_columns = customer_model.column_names & source.column_names
+      copy_digest_from_encrypted = source.column_names.include?('encrypted_password') &&
+                                    !direct_columns.include?('password_digest')
+      has_marketing_column = customer_model.column_names.include?('accepts_email_marketing')
+
+      # Preflight: catch rows we can't faithfully copy before writing anything, so
+      # a bad row can't leave an already-renamed +customer_id+ foreign key pointing
+      # at a customer that never migrated. Two kinds are rejected:
+      #   1. Blank email — the target column is NOT NULL and uniquely indexed, so
+      #      the row can't be inserted at all.
+      #   2. Email already owned by a different customer — insert_all would abort
+      #      the whole batch on the unique-email index.
+      # Either kind aborts the task with the offending ids unless the operator
+      # passes SKIP_INVALID_ROWS=true to skip them and continue.
+      pending = source.where.not(id: customer_model.select(:id))
+      blank_email_ids = pending.where("email IS NULL OR email = ''").pluck(:id)
+      # Compare case-insensitively to match Spree::Customer's uniqueness
+      # (case_sensitive: false) — emails are stored case-preserved, so a legacy
+      # `Alice@` conflicting with an existing `alice@` must be caught here too.
+      # Blanks are filtered in Ruby: `where.not(email: [nil, ''])` returns no rows
+      # on MySQL (NOT IN with NULL), which would silently drop every conflict.
+      existing_emails = customer_model.pluck(:email).map { |e| e&.downcase.presence }.compact.to_set
+      conflict_ids = pending.where("email IS NOT NULL AND email <> ''").pluck(:id, :email).
+                             filter_map { |id, email| id if existing_emails.include?(email.downcase) }
+      invalid_ids = (blank_email_ids + conflict_ids).uniq
+
+      if invalid_ids.any? && ENV['SKIP_INVALID_ROWS'] != 'true'
+        abort "  #{invalid_ids.size} source row(s) can't be migrated — " \
+              "#{blank_email_ids.size} with a blank email#{blank_email_ids.any? ? " (ids: #{blank_email_ids.first(20).join(', ')})" : ''}, " \
+              "#{conflict_ids.size} whose email is already taken by another customer#{conflict_ids.any? ? " (ids: #{conflict_ids.first(20).join(', ')})" : ''}. " \
+              "Reconcile them, or re-run with SKIP_INVALID_ROWS=true to skip these and continue."
+      end
+
+      copied = 0
+
+      pending.where.not(id: invalid_ids).in_batches(of: batch_size) do |relation|
+        rows = relation.map do |record|
+          attributes = record.attributes.slice(*direct_columns)
+          attributes['password_digest'] = record[:encrypted_password] if copy_digest_from_encrypted
+          # accepts_email_marketing is NOT NULL with no DB default — coalesce so a
+          # legacy NULL (or a source table lacking the column) can't break the insert.
+          attributes['accepts_email_marketing'] = false if has_marketing_column && attributes['accepts_email_marketing'].nil?
+          attributes
+        end
+
+        next if rows.empty?
+
+        customer_model.insert_all(rows)
+        copied += rows.size
+        print '.'
+      end
+
+      # insert_all writes explicit ids without advancing the Postgres sequence.
+      connection.reset_pk_sequence!(customer_model.table_name) if connection.adapter_name.match?(/postgres/i)
+
+      # Re-point polymorphic user references. Ids are preserved, so only the type
+      # string changes; admin rows (Spree::AdminUser) stay put — that class name
+      # is unchanged in 6.0. Customer-group memberships store the type in the
+      # already-renamed +customer_type+ column; every other table still uses
+      # +user_type+/+*_type+.
+      repointed = {
+        role_users:           Spree::RoleUser.where(user_type: old_type).update_all(user_type: new_type),
+        refresh_tokens:       Spree::RefreshToken.where(user_type: old_type).update_all(user_type: new_type),
+        user_identities:      Spree::UserIdentity.where(user_type: old_type).update_all(user_type: new_type),
+        customer_group_users: Spree::CustomerGroupUser.where(customer_type: old_type).update_all(customer_type: new_type),
+        api_keys_created_by:  Spree::ApiKey.where(created_by_type: old_type).update_all(created_by_type: new_type),
+        api_keys_revoked_by:  Spree::ApiKey.where(revoked_by_type: old_type).update_all(revoked_by_type: new_type),
+        # Internal notes, so migrate_rich_text_to_columns can find them under
+        # the new class name whichever order the two steps run in. Action Text
+        # is optional, hence the defined? guard.
+        rich_texts: if defined?(ActionText::RichText) && ActionText::RichText.table_exists?
+                      ActionText::RichText.where(record_type: old_type).update_all(record_type: new_type)
+                    else
+                      0
+                    end
+      }
+
+      # Admins stay in spree_admin_users (in place) — backfill the digest from
+      # the legacy column when present.
+      admin_backfilled = 0
+      if admin_model.column_names.include?('encrypted_password')
+        admin_backfilled = admin_model.where(password_digest: [nil, '']).
+                           where.not(encrypted_password: [nil, '']).
+                           update_all('password_digest = encrypted_password')
+      end
+
+      puts
+      puts "  Customers copied: #{copied} (skipped #{invalid_ids.size} invalid row(s): " \
+           "#{blank_email_ids.size} blank-email, #{conflict_ids.size} email-conflict)."
+      puts "  Admin password_digest backfilled: #{admin_backfilled}."
+      puts "  Re-pointed #{old_type} -> #{new_type}: " \
+           "role_users #{repointed[:role_users]}, refresh_tokens #{repointed[:refresh_tokens]}, " \
+           "user_identities #{repointed[:user_identities]}, customer_group_users #{repointed[:customer_group_users]}, " \
+           "api_keys #{repointed[:api_keys_created_by] + repointed[:api_keys_revoked_by]}."
+      puts "  #{source_table} left in place — drop it once you've verified the migration."
+    end
+  end
+end

data/lib/tasks/order_coupon_code_backfill.rake

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# 5.6 → 6.0: spree_orders gained a coupon_code column (parity with
+# spree_carts). Historical placed orders applied coupons through the
+# promotion join tables only — backfill the column from those records so
+# admin filtering and the serializer answer consistently for old orders.
+namespace :spree do
+  desc 'Backfill spree_orders.coupon_code from applied promotion/coupon-code records'
+  task backfill_order_coupon_codes: :environment do
+    batch_size = ENV.fetch('BATCH_SIZE', 500).to_i
+    updated = 0
+
+    scope = Spree::Order.unscoped.where(coupon_code: nil).where.not(completed_at: nil)
+
+    scope.in_batches(of: batch_size) do |batch|
+      batch.each do |order|
+        code = Spree::CouponCode.where(order_id: order.id).order(:id).limit(1).pick(:code) ||
+               Spree::Promotion.joins(:order_promotions).
+                 where(Spree::OrderPromotion.table_name => { order_id: order.id }).
+                 where.not(code: [nil, '']).order(:id).limit(1).pick(:code)
+        next if code.blank?
+
+        order.update_columns(coupon_code: code.downcase)
+        updated += 1
+      end
+      print '.'
+    end
+
+    puts
+    puts "backfill_order_coupon_codes done. updated: #{updated}"
+  end
+end

data/lib/tasks/order_market_backfill.rake

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# 5.6 → 6.0: market is mandatory on orders in Spree 6. Orders created before
+# markets existed carry NULLs — backfill from the store's default market so
+# the 6.1 NOT NULL constraint can land. (channel_id has no equivalent task
+# here: the 5.4→5.5 manifest's spree:channels:backfill_order_channel_ids
+# already covers it on every upgrade path.)
+namespace :spree do
+  desc 'Backfill missing market on orders from the store default market'
+  task backfill_order_markets: :environment do
+    batch_size = ENV.fetch('BATCH_SIZE', 5_000).to_i
+
+    Spree::Store.all.find_each do |store|
+      market_id = store.default_market&.id
+
+      if market_id
+        count = Spree::Order.unscoped.where(store_id: store.id, market_id: nil).
+          in_batches(of: batch_size).update_all(market_id: market_id)
+        puts "store #{store.code}: #{count} orders assigned market #{market_id}" if count.positive?
+      else
+        puts "store #{store.code}: no default market — orders left as-is"
+      end
+    end
+
+    puts 'backfill_order_markets done. The NOT NULL constraint lands in 6.1.'
+  end
+end