spree_core 5.6.1 → 6.0.0.beta2

data/db/migrate/20260902000001_add_store_and_filter_key_to_custom_field_definitions.rb

@@ -0,0 +1,143 @@
+class AddStoreAndFilterKeyToCustomFieldDefinitions < ActiveRecord::Migration[8.1]
+  def up
+    add_reference :spree_custom_field_definitions, :store unless column_exists?(:spree_custom_field_definitions, :store_id)
+
+    unless column_exists?(:spree_custom_field_definitions, :filter_key)
+      add_column :spree_custom_field_definitions, :filter_key, :string
+    end
+
+    # Read through SQL rather than Spree::Store: a migration that loads a model
+    # breaks the moment that model's columns move ahead of this point in the
+    # migration history.
+    default_store_id = select_value(
+      "SELECT id FROM spree_stores ORDER BY #{quote_column_name(:default)} DESC, id ASC LIMIT 1"
+    )
+
+    execute("UPDATE spree_custom_field_definitions SET store_id = #{default_store_id.to_i} WHERE store_id IS NULL") if default_store_id.present?
+
+    # The same value the model's callback writes. Definitions predating this
+    # migration are backfilled here so the unique index below has something to
+    # constrain.
+    execute(<<~SQL.squish)
+      UPDATE spree_custom_field_definitions
+      SET filter_key = #{concat_filter_key}
+      WHERE filter_key IS NULL
+    SQL
+
+    remove_index :spree_custom_field_definitions, column: [:resource_type, :namespace, :key], unique: true, if_exists: true
+
+    disambiguate_colliding_filter_keys
+
+    add_index :spree_custom_field_definitions, [:store_id, :resource_type, :filter_key],
+              unique: true, name: 'index_custom_field_definitions_on_store_and_filter_key'
+    add_index :spree_custom_field_definitions, [:store_id, :resource_type, :namespace, :key],
+              unique: true, name: 'index_custom_field_definitions_on_store_and_key'
+
+    # Enforce once nothing is left unowned — true on a fresh install (empty
+    # table) and after the backfill above. A leftover orphan skips the
+    # constraint rather than failing the migration;
+    # spree:upgrade:backfill_custom_field_definition_stores is the recovery path.
+    return if select_value('SELECT COUNT(*) FROM spree_custom_field_definitions WHERE store_id IS NULL OR filter_key IS NULL').to_i.positive?
+
+    change_column_null :spree_custom_field_definitions, :store_id, false
+    change_column_null :spree_custom_field_definitions, :filter_key, false
+  end
+
+  def down
+    # Two stores may each hold `custom.material` once this migration has run —
+    # that is the point of it. The pre-migration index was global, so rolling
+    # back over such a pair has no correct answer: one of them would have to
+    # lose its key. Refuse before anything is dropped rather than fail halfway
+    # with the columns already gone.
+    duplicated = select_value(<<~SQL.squish).to_i
+      SELECT COUNT(*) FROM (
+        SELECT 1 FROM spree_custom_field_definitions
+        GROUP BY resource_type, namespace, #{quote_column_name(:key)}
+        HAVING COUNT(*) > 1
+      ) AS duplicated_keys
+    SQL
+
+    if duplicated.positive?
+      raise ActiveRecord::IrreversibleMigration,
+            "#{duplicated} custom field definition key(s) are held by more than one store. " \
+            'The pre-6.0 schema indexes them globally, so rolling back would have to discard one of each pair. ' \
+            'Remove the duplicates you do not want to keep, then roll back.'
+    end
+
+    remove_index :spree_custom_field_definitions, name: 'index_custom_field_definitions_on_store_and_filter_key', if_exists: true
+    remove_index :spree_custom_field_definitions, name: 'index_custom_field_definitions_on_store_and_key', if_exists: true
+
+    add_index :spree_custom_field_definitions, [:resource_type, :namespace, :key], unique: true
+
+    remove_column :spree_custom_field_definitions, :filter_key
+    remove_reference :spree_custom_field_definitions, :store
+  end
+
+  private
+
+  # `key` and `namespace` both normalize to underscored slugs, so ("a_b", "c")
+  # and ("a", "b_c") flatten to one filter_key. Nothing forbade that before
+  # this migration, so an existing install can hold a pair the unique index
+  # below would reject. The later row keeps its namespace and key and gets a
+  # suffixed filter_key, which keeps it addressable and leaves the operator a
+  # visible thing to rename.
+  def disambiguate_colliding_filter_keys
+    duplicate_groups = select_rows(<<~SQL.squish)
+      SELECT store_id, resource_type, filter_key
+      FROM spree_custom_field_definitions
+      GROUP BY store_id, resource_type, filter_key
+      HAVING COUNT(*) > 1
+    SQL
+
+    duplicate_groups.each do |store_id, resource_type, filter_key|
+      ids = select_values(<<~SQL.squish)
+        SELECT id FROM spree_custom_field_definitions
+        WHERE store_id #{store_id.nil? ? 'IS NULL' : "= #{store_id.to_i}"}
+          AND resource_type = #{quote(resource_type)}
+          AND filter_key = #{quote(filter_key)}
+        ORDER BY id ASC
+      SQL
+
+      ids.drop(1).each do |id|
+        replacement = free_filter_key(filter_key, store_id, resource_type)
+        execute("UPDATE spree_custom_field_definitions SET filter_key = #{quote(replacement)} WHERE id = #{quote(id)}")
+        say "  filter_key collision on #{filter_key} — definition #{id} renamed to #{replacement}", true
+      end
+    end
+  end
+
+  # The first +cf_..._2+, +_3+, ... not already taken in this store. An install
+  # can legitimately hold the suffixed form as a definition of its own
+  # (namespace +a_b_c+, key +2+), and handing it out twice would fail the
+  # unique index halfway through this migration.
+  def free_filter_key(filter_key, store_id, resource_type)
+    suffix = 2
+
+    loop do
+      candidate = "#{filter_key}_#{suffix}"
+      taken = select_value(<<~SQL.squish)
+        SELECT 1 FROM spree_custom_field_definitions
+        WHERE store_id #{store_id.nil? ? 'IS NULL' : "= #{store_id.to_i}"}
+          AND resource_type = #{quote(resource_type)}
+          AND filter_key = #{quote(candidate)}
+        LIMIT 1
+      SQL
+      return candidate if taken.nil?
+
+      suffix += 1
+    end
+  end
+
+  # `CONCAT` is MySQL/PostgreSQL; SQLite spells the same thing `||`. Both
+  # column names are quoted — `key` is reserved on MySQL.
+  def concat_filter_key
+    namespace = quote_column_name(:namespace)
+    key = quote_column_name(:key)
+
+    if connection.adapter_name.match?(/sqlite/i)
+      "'cf_' || #{namespace} || '_' || #{key}"
+    else
+      "CONCAT('cf_', #{namespace}, '_', #{key})"
+    end
+  end
+end

data/db/migrate/20260902000002_add_eu_legal_compliance.rb

@@ -0,0 +1,68 @@
+class AddEuLegalCompliance < ActiveRecord::Migration[8.1]
+  def change
+    change_table :spree_customers do |t|
+      t.datetime :email_marketing_consent_updated_at
+      t.string :email_marketing_consent_source
+      t.datetime :anonymized_at, index: true
+    end
+
+    # Proof that a person accepted something at a moment in time. Kept as rows
+    # rather than columns because acceptance is an event that recurs — a
+    # customer accepts terms at registration and again at each checkout.
+    create_table :spree_consent_records do |t|
+      t.belongs_to :store, null: false, index: true
+      t.references :owner, polymorphic: true, null: false, index: true
+      t.string :purpose, null: false
+      t.string :source, null: false
+      t.boolean :accepted, null: false, default: true
+      t.string :email
+      t.string :ip_address
+      t.string :user_agent
+      # The policies as they read when accepted — slug, name and the digest of
+      # the body the person actually saw.
+      if t.respond_to?(:jsonb)
+        t.jsonb :documents
+      else
+        t.json :documents
+      end
+      t.datetime :recorded_at, null: false
+      t.timestamps
+    end
+
+    add_index :spree_consent_records, [:store_id, :purpose, :recorded_at],
+              name: 'index_spree_consent_records_on_store_purpose_recorded'
+    # Erasure and export match consent records case-insensitively, so the
+    # useful index is on the lowered column rather than the raw one.
+    if ActiveRecord::Base.connection.adapter_name == 'PostgreSQL'
+      add_index :spree_consent_records, 'LOWER(email)',
+                name: 'index_spree_consent_records_on_lower_email'
+    else
+      add_index :spree_consent_records, :email
+    end
+
+    # A GDPR data subject request — access (Art. 15) or erasure (Art. 17).
+    create_table :spree_data_requests do |t|
+      t.belongs_to :store, null: false, index: true
+      t.belongs_to :customer, null: false, index: true
+      t.string :number, null: false
+      t.string :download_token
+      t.string :kind, null: false
+      t.string :status, null: false
+      t.string :email, null: false
+      t.datetime :requested_at, null: false
+      t.datetime :completed_at
+      t.datetime :expires_at
+      t.text :error_message
+      # Null when the subject asked for it themselves; set when staff acted on
+      # a request that arrived by email.
+      t.bigint :requested_by_id
+      t.timestamps
+    end
+
+    add_index :spree_data_requests, [:store_id, :number], unique: true
+    add_index :spree_data_requests, :download_token, unique: true
+    add_index :spree_data_requests, [:customer_id, :kind, :status],
+              name: 'index_spree_data_requests_on_customer_kind_status'
+    add_index :spree_data_requests, :requested_by_id
+  end
+end

data/db/migrate/20260902000002_replace_order_cancellation_tables_with_cancel_columns.rb

@@ -0,0 +1,88 @@
+class ReplaceOrderCancellationTablesWithCancelColumns < ActiveRecord::Migration[8.1]
+  def up
+    # Checked explicitly rather than with `if_not_exists: true`: that option
+    # skips the CREATE TABLE but still emits the index statements the block
+    # declares, which then fail against a table that lacks those columns.
+    unless table_exists?(:spree_order_cancellation_reasons)
+      create_table :spree_order_cancellation_reasons do |t|
+        t.string :name, null: false
+        t.references :store, null: false
+        t.boolean :active, null: false, default: true
+        if t.respond_to?(:jsonb)
+          t.jsonb :metadata
+        else
+          t.json :metadata
+        end
+        t.timestamps
+      end
+    end
+
+    add_index :spree_order_cancellation_reasons, [:store_id, :name], unique: true,
+              name: 'idx_order_cancellation_reasons_on_store_and_name', if_not_exists: true
+
+    add_reference :spree_orders, :cancel_reason, index: true unless column_exists?(:spree_orders, :cancel_reason_id)
+    add_column :spree_orders, :cancel_note, :text unless column_exists?(:spree_orders, :cancel_note)
+
+    # Nothing ever read these tables: no API, admin view, mail or export
+    # consulted a row, and every row written carried the default reason.
+    drop_table :spree_order_cancellations, if_exists: true
+    drop_table :spree_order_approvals, if_exists: true
+  end
+
+  # Restores the two dropped tables as well as undoing this migration's own
+  # additions. The migrations that created them are deleted in this same
+  # change, so nothing else can put them back — without this, a rollback
+  # would leave a schema with neither the old tables nor the new columns.
+  # Their rows are gone either way: they were write-only, so there is nothing
+  # to preserve.
+  def down
+    unless table_exists?(:spree_order_cancellations)
+      create_table :spree_order_cancellations do |t|
+        t.references :order, null: false, index: false
+        t.string :reason, null: false
+        t.text :note
+        t.boolean :restock_items, null: false
+        t.boolean :refund_payments, null: false
+        t.decimal :refund_amount, precision: 10, scale: 2
+        t.boolean :notify_customer, null: false
+        t.references :canceled_by, polymorphic: true, index: false
+        if t.respond_to?(:jsonb)
+          t.jsonb :metadata
+        else
+          t.json :metadata
+        end
+        t.timestamps
+      end
+
+      add_index :spree_order_cancellations, :order_id
+      add_index :spree_order_cancellations, [:canceled_by_id, :canceled_by_type],
+                name: 'idx_order_cancellations_canceled_by'
+      add_index :spree_order_cancellations, :created_at
+    end
+
+    unless table_exists?(:spree_order_approvals)
+      create_table :spree_order_approvals do |t|
+        t.references :order, null: false, index: false
+        t.string :status, null: false
+        t.string :level
+        t.text :note
+        t.references :approver, polymorphic: true, index: false
+        t.datetime :decided_at
+        if t.respond_to?(:jsonb)
+          t.jsonb :metadata
+        else
+          t.json :metadata
+        end
+        t.timestamps
+      end
+
+      add_index :spree_order_approvals, [:order_id, :status]
+      add_index :spree_order_approvals, [:approver_id, :approver_type],
+                name: 'idx_order_approvals_approver'
+    end
+
+    remove_column :spree_orders, :cancel_note, if_exists: true
+    remove_reference :spree_orders, :cancel_reason, if_exists: true
+    drop_table :spree_order_cancellation_reasons, if_exists: true
+  end
+end

data/db/migrate/20260902100001_rename_wished_items_to_wishlist_items.rb

@@ -0,0 +1,8 @@
+class RenameWishedItemsToWishlistItems < ActiveRecord::Migration[8.1]
+  # WishedItem becomes WishlistItem (docs/plans/5.4-store-api-naming-standardization.md).
+  # All three indexes carry the default name Rails derives from the table, so
+  # they are renamed along with it and none need moving by hand.
+  def change
+    rename_table :spree_wished_items, :spree_wishlist_items
+  end
+end

data/db/migrate/20260902100002_rename_promo_total_to_discount_total.rb

@@ -0,0 +1,9 @@
+class RenamePromoTotalToDiscountTotal < ActiveRecord::Migration[8.1]
+  # The last two tables still carrying promo_total; spree_orders moved in
+  # 20260729120001 and spree_carts was born with the new name, which left
+  # LineItem and Fulfillment aliasing in the opposite direction to Order.
+  def change
+    rename_column :spree_line_items, :promo_total, :discount_total
+    rename_column :spree_fulfillments, :promo_total, :discount_total
+  end
+end

data/db/migrate/20260902100003_rename_address_name_and_postal_code_columns.rb

@@ -0,0 +1,24 @@
+class RenameAddressNameAndPostalCodeColumns < ActiveRecord::Migration[8.1]
+  # docs/plans/5.4-store-api-naming-standardization.md. The API has spoken
+  # first_name / last_name / postal_code since 5.4, but Ransack filter keys and
+  # validation error keys carry the column name, so both still leaked the old
+  # ones. The two indexes are named after the columns rather than derived from
+  # them, so they have to move by hand.
+  def up
+    rename_column :spree_addresses, :firstname, :first_name
+    rename_column :spree_addresses, :lastname, :last_name
+    rename_column :spree_addresses, :zipcode, :postal_code
+
+    rename_index :spree_addresses, 'index_addresses_on_firstname', 'index_addresses_on_first_name'
+    rename_index :spree_addresses, 'index_addresses_on_lastname', 'index_addresses_on_last_name'
+  end
+
+  def down
+    rename_index :spree_addresses, 'index_addresses_on_first_name', 'index_addresses_on_firstname'
+    rename_index :spree_addresses, 'index_addresses_on_last_name', 'index_addresses_on_lastname'
+
+    rename_column :spree_addresses, :postal_code, :zipcode
+    rename_column :spree_addresses, :last_name, :lastname
+    rename_column :spree_addresses, :first_name, :firstname
+  end
+end

data/db/migrate/20260902100004_rename_option_presentation_to_label.rb

@@ -0,0 +1,13 @@
+class RenameOptionPresentationToLabel < ActiveRecord::Migration[8.1]
+  # docs/plans/5.4-store-api-naming-standardization.md. The API has exposed
+  # `label` since 5.4 through a locale-aware delegation, but the Ransack
+  # whitelist and the validation error keys both carry the column name. The
+  # Mobility translation tables move in the same change — the translated value
+  # lives there, so leaving them behind would split the field in two.
+  def change
+    rename_column :spree_option_types, :presentation, :label
+    rename_column :spree_option_values, :presentation, :label
+    rename_column :spree_option_type_translations, :presentation, :label
+    rename_column :spree_option_value_translations, :presentation, :label
+  end
+end

data/db/migrate/20260903000001_create_spree_shipping_labels_and_deliveries.rb

@@ -0,0 +1,73 @@
+class CreateSpreeShippingLabelsAndDeliveries < ActiveRecord::Migration[8.1]
+  # Two records with a polymorphic owner (Fulfillment | Return): a shipping
+  # label is the carrier document the merchant bought or uploaded, a delivery
+  # is one consignment's carrier journey (docs/plans/6.0-shipping-labels-and-deliveries.md).
+  # `status` on both is written by the creating workflow, never a database
+  # default.
+  def change
+    create_table :spree_shipping_labels do |t|
+      t.references :owner, polymorphic: true, null: false
+      t.references :store, null: false
+      t.references :integration
+      t.string :source, null: false
+      t.string :external_id
+      t.string :carrier
+      t.string :service
+      t.string :tracking_number
+      t.decimal :cost, precision: 10, scale: 2, null: false, default: 0
+      t.string :currency
+      t.string :format
+      t.string :status, null: false
+      t.datetime :refunded_at
+
+      if t.respond_to?(:jsonb)
+        t.jsonb :metadata
+      else
+        t.json :metadata
+      end
+
+      t.timestamps
+    end
+
+    add_index :spree_shipping_labels, [:owner_type, :owner_id]
+
+    # One live label per parcel, enforced where the race actually happens: two
+    # clicks on "buy label" both pass an application-level check, and the
+    # loser has to be refused before the carrier is charged. A refunded label
+    # is history and does not count, so the index is partial where the
+    # database supports it.
+    if connection.supports_partial_index?
+      add_index :spree_shipping_labels, [:owner_type, :owner_id],
+                unique: true,
+                where: "status <> 'refunded'",
+                name: 'index_spree_shipping_labels_on_active_owner'
+    end
+
+    create_table :spree_deliveries do |t|
+      t.references :owner, polymorphic: true, null: false
+      t.references :store, null: false
+      t.references :shipping_label, index: { unique: true }
+      t.string :tracking_number, null: false
+      t.string :tracking_url
+      t.string :carrier
+      t.string :service
+      t.string :status, null: false
+      t.datetime :estimated_delivery_at
+      t.datetime :delivered_at
+
+      if t.respond_to?(:jsonb)
+        t.jsonb :details
+      else
+        t.json :details
+      end
+
+      t.timestamps
+    end
+
+    # Carrier webhooks arrive keyed by tracking number and are matched inside
+    # the integration's store.
+    add_index :spree_deliveries, [:store_id, :tracking_number]
+    add_index :spree_deliveries, [:owner_type, :owner_id, :tracking_number],
+              unique: true, name: 'index_spree_deliveries_on_owner_and_tracking_number'
+  end
+end

data/db/migrate/20260903120000_create_spree_saved_reports.rb

@@ -0,0 +1,57 @@
+class CreateSpreeSavedReports < ActiveRecord::Migration[8.1]
+  INDEX_NAME = 'index_spree_saved_reports_on_store_and_lower_name'.freeze
+
+  # docs/plans/6.0-analytics-semantic-layer.md — a saved report is a reporting
+  # contract query owned by the store and shared with every staff member who
+  # may read reports; its visualization is inferred from the query's shape.
+  def change
+    create_table :spree_saved_reports do |t|
+      # No standalone store index: the unique [store_id, name] index leads with it.
+      t.belongs_to :store, null: false, foreign_key: false, index: false
+      t.belongs_to :user, foreign_key: false, index: true
+      t.string :name, null: false
+      t.text :description
+      if t.respond_to?(:jsonb)
+        t.jsonb :query, null: false
+      else
+        t.json :query, null: false
+      end
+      t.boolean :seeded, null: false, default: false
+      t.timestamps
+    end
+
+    add_name_uniqueness_index
+  end
+
+  private
+
+  # One report per name per store, compared case-insensitively so it matches
+  # the model's validation and the seeder's idempotency check — both of which
+  # already downcase. A case-sensitive index lets "Top products" and
+  # "top products" both land, which is exactly the pair re-seeding produces.
+  #
+  # Written per adapter because MySQL and MariaDB reject the functional-index
+  # syntax PostgreSQL and SQLite accept; they index a stored generated column
+  # instead. Expression per the spree_price_lists precedent.
+  def add_name_uniqueness_index
+    if Spree.mysql?
+      reversible do |dir|
+        dir.up do
+          execute <<~SQL.squish
+            ALTER TABLE spree_saved_reports
+            ADD COLUMN name_key VARCHAR(255)
+            AS (LOWER(name)) STORED
+          SQL
+          add_index :spree_saved_reports, [:store_id, :name_key], unique: true, name: INDEX_NAME
+        end
+
+        dir.down do
+          remove_index :spree_saved_reports, name: INDEX_NAME
+          remove_column :spree_saved_reports, :name_key
+        end
+      end
+    else
+      add_index :spree_saved_reports, 'store_id, LOWER(name)', unique: true, name: INDEX_NAME
+    end
+  end
+end

data/db/migrate/20260904000001_add_returns_enabled_to_stock_locations.rb

@@ -0,0 +1,14 @@
+class AddReturnsEnabledToStockLocations < ActiveRecord::Migration[8.1]
+  # Which locations accept goods coming back — the inbound twin of
+  # pickup_enabled. A merchant who inspects and restocks returns at one
+  # processing centre should not have parcels sent to every warehouse that
+  # happens to ship orders out.
+  #
+  # Defaults true so an upgrading store keeps returning goods wherever they
+  # shipped from, which is what happened before the flag existed. A merchant
+  # narrows it by turning the others off.
+  def change
+    add_column :spree_stock_locations, :returns_enabled, :boolean, null: false, default: true
+    add_index :spree_stock_locations, :returns_enabled
+  end
+end

data/db/migrate/20260906000001_add_commission_total_to_orders.rb

@@ -0,0 +1,22 @@
+class AddCommissionTotalToOrders < ActiveRecord::Migration[8.1]
+  # What this sale earned the marketplace, denormalized from the order's
+  # commission lines the way fee_total is denormalized from its fees.
+  #
+  # Deliberately not part of the grand total: a commission is a platform to
+  # seller settlement the customer never pays, so these are readable sums
+  # beside the money the shopper owes, never an addition to it.
+  #
+  # Split three ways because the tax is the point. The marketplace's
+  # commission is its own taxable B2B supply to the seller, so the platform
+  # files that VAT as output tax and the seller reclaims the same figure as
+  # input tax. A single gross column cannot answer either question — the tax
+  # is not recoverable from it — and a VAT return is not filed from a sum
+  # recomputed in a browser. Mirrors how the order already carries
+  # included_tax_total and additional_tax_total beside the totals they belong
+  # to.
+  def change
+    add_column :spree_orders, :commission_amount_total, :decimal, precision: 10, scale: 2, null: false, default: 0.0
+    add_column :spree_orders, :commission_tax_total, :decimal, precision: 10, scale: 2, null: false, default: 0.0
+    add_column :spree_orders, :commission_total, :decimal, precision: 10, scale: 2, null: false, default: 0.0
+  end
+end

data/db/migrate/20260907000001_add_inventory_operations.rb

@@ -0,0 +1,113 @@
+class AddInventoryOperations < ActiveRecord::Migration[8.1]
+  def change
+    # A transfer becomes a multi-day operation with its own status, and gains
+    # the store it has never carried (docs/plans/6.0-inventory-operations.md).
+    # `source_location_id` stays nullable: emptying it of the external-receive
+    # rows is the upgrade task's job, not a migration's.
+    add_column :spree_stock_transfers, :store_id, :bigint
+    add_column :spree_stock_transfers, :status, :string
+    add_column :spree_stock_transfers, :shipped_at, :datetime
+    add_column :spree_stock_transfers, :received_at, :datetime
+    add_column :spree_stock_transfers, :notes, :text
+    add_column :spree_stock_transfers, :created_by_id, :bigint
+    # The upgrade task soft-deletes the external receives it converts into
+    # purchase orders, so their T-… numbers stay findable without the receive
+    # showing up twice.
+    add_column :spree_stock_transfers, :deleted_at, :datetime
+    add_index :spree_stock_transfers, :store_id
+    add_index :spree_stock_transfers, :status
+    add_index :spree_stock_transfers, :deleted_at
+
+    # An STI column that never had a subclass to hold: always null, exposed by
+    # nothing (docs/plans/6.0-inventory-operations.md, phase 6).
+    remove_column :spree_stock_transfers, :type, :string
+
+    create_table :spree_stock_transfer_items do |t|
+      t.references :stock_transfer, null: false
+      t.references :variant, null: false
+      t.integer :quantity_shipped, null: false, default: 0
+      t.integer :quantity_received, null: false, default: 0
+      t.string :discrepancy_reason
+      t.timestamps
+    end
+    add_index :spree_stock_transfer_items, [:stock_transfer_id, :variant_id],
+              unique: true, name: 'idx_stock_transfer_items_unique'
+
+    create_table :spree_suppliers do |t|
+      t.string :name, null: false
+      t.string :contact_name
+      t.string :email
+      t.string :phone
+      t.text :notes
+      t.references :store, null: false
+      # Kept by Active Record's counter cache, so the suppliers list can show
+      # "3 purchase orders" without a query per row — and without loading a
+      # supplier's whole purchasing history to count it.
+      t.integer :purchase_orders_count, null: false, default: 0
+      # Inline address columns, mirroring spree_stock_locations: a supplier is
+      # a place goods come from, edited as one flat form.
+      t.string :address1
+      t.string :address2
+      t.string :city
+      t.string :state_name
+      t.string :state_code
+      t.string :country_code
+      t.string :postal_code
+      if t.respond_to?(:jsonb)
+        t.jsonb :metadata
+      else
+        t.json :metadata
+      end
+      t.datetime :deleted_at
+      t.timestamps
+    end
+    # No `where: 'deleted_at IS NULL'`: MySQL has no partial indexes and drops
+    # the condition silently, so a soft-deleted supplier's name would be
+    # reusable on PostgreSQL and a 500 on MySQL. The model's uniqueness
+    # validation matches this index exactly instead — a deleted supplier keeps
+    # its name, and re-using it is refused with a message rather than an error.
+    add_index :spree_suppliers, [:store_id, :name], unique: true
+    add_index :spree_suppliers, :deleted_at
+
+    create_table :spree_purchase_orders do |t|
+      t.string :number, null: false
+      t.string :status
+      t.string :currency, null: false
+      t.string :reference
+      t.references :supplier, null: false
+      t.references :store, null: false
+      t.references :destination_location, null: false
+      t.date :expected_at
+      t.datetime :ordered_at
+      t.datetime :received_at
+      t.text :notes
+      t.bigint :created_by_id
+      if t.respond_to?(:jsonb)
+        t.jsonb :metadata
+      else
+        t.json :metadata
+      end
+      t.timestamps
+    end
+    add_index :spree_purchase_orders, :number, unique: true
+    add_index :spree_purchase_orders, :status
+
+    create_table :spree_purchase_order_items do |t|
+      t.references :purchase_order, null: false
+      t.references :variant, null: false
+      t.integer :quantity_ordered, null: false, default: 0
+      t.integer :quantity_received, null: false, default: 0
+      t.decimal :unit_cost, precision: 10, scale: 2, null: false, default: 0
+      t.timestamps
+    end
+    add_index :spree_purchase_order_items, [:purchase_order_id, :variant_id],
+              unique: true, name: 'idx_purchase_order_items_unique'
+
+    # The purchase order is a new cause flavour for the `received` kind; the
+    # unit cost is what those units landed at, which is what a rolling average
+    # cost will be computed from.
+    add_column :spree_stock_movements, :purchase_order_id, :bigint
+    add_index :spree_stock_movements, :purchase_order_id
+    add_column :spree_stock_movements, :unit_cost, :decimal, precision: 10, scale: 2
+  end
+end

data/db/migrate/20260907000001_add_min_quantity_to_spree_prices.rb

@@ -0,0 +1,28 @@
+class AddMinQuantityToSpreePrices < ActiveRecord::Migration[8.1]
+  def change
+    # The quantity a line must reach for this row to be its price. Defaulting
+    # to 1 makes every existing row a quantity-1 price, so a ladder is purely
+    # additive and there is nothing to backfill
+    # (docs/plans/6.0-volume-pricing.md).
+    add_column :spree_prices, :min_quantity, :integer, null: false, default: 1
+
+    # Row identity gains the column: a variant now holds one price per
+    # (currency, list, break) rather than one per (currency, list).
+    remove_index :spree_prices, name: 'index_spree_prices_on_variant_currency_price_list', if_exists: true
+
+    if ActiveRecord::Base.connection.adapter_name == 'Mysql2'
+      add_index :spree_prices, [:variant_id, :currency, :price_list_id, :min_quantity],
+                name: 'index_spree_prices_on_variant_currency_list_quantity',
+                unique: true
+    else
+      add_index :spree_prices, [:variant_id, :currency, :price_list_id, :min_quantity],
+                name: 'index_spree_prices_on_variant_currency_list_quantity',
+                unique: true,
+                where: 'price_list_id IS NOT NULL AND deleted_at IS NULL AND amount IS NOT NULL'
+    end
+
+    # Reading a ladder means "this variant's rows on this list, ordered by
+    # break" — the unique index above leads with variant_id, so it serves
+    # that read too, and no second index is warranted.
+  end
+end