spree_core 5.6.1 → 6.0.0.beta2

data/db/migrate/20260816210001_create_spree_commission_rates.rb

@@ -0,0 +1,229 @@
+class CreateSpreeCommissionRates < ActiveRecord::Migration[8.1]
+  INDEX_NAME = 'index_spree_commission_rates_on_store_id_and_code'.freeze
+  RULE_INDEX_NAME = 'index_commission_rules_on_rate_and_type'.freeze
+  RULE_PRODUCT_INDEX_NAME = 'index_commission_rule_products_on_rule_and_product'.freeze
+  RATE_VALUE_INDEX_NAME = 'index_commission_rate_values_on_rate_and_currency'.freeze
+
+  def change
+    create_table :spree_commission_rates do |t|
+      t.references :store, null: false
+      t.string :name, null: false
+      t.string :code
+      t.boolean :enabled, null: false, default: true
+      # Resolution order: the list is walked top-down and the first matching
+      # rate wins, so what an operator sees in the table IS the precedence.
+      # Seeds arrive product-before-category-before-seller, which is the
+      # conventional ladder; reordering is dragging a row.
+      t.integer :position, null: false, default: 0
+
+      t.string :kind, null: false # percentage | fixed
+      # A percentage. Every *amount* a rate states — a flat fee, and a
+      # percentage's floor and cap alike — lives in
+      # spree_commission_rate_values, one row per currency, since "2" means
+      # nothing without saying 2 of what.
+      t.decimal :value, precision: 10, scale: 5, null: false, default: 0
+
+      # Commission base: net (ex-VAT) item price by default, which is the EU
+      # rule — the fee is a separate supply from the consumer's item sale.
+      t.boolean :tax_inclusive, null: false, default: false
+      # Also commission the seller order's delivery revenue.
+      t.boolean :include_shipping, null: false, default: false
+
+      # Overrides the tax provider's answer for VAT on the commission. Null
+      # means ask the provider, which is what keeps the rate jurisdiction-correct.
+      t.decimal :commission_tax_rate, precision: 8, scale: 5
+
+      if t.respond_to?(:jsonb)
+        t.jsonb :metadata
+      else
+        t.json :metadata
+      end
+
+      t.timestamps
+      t.datetime :deleted_at
+    end
+
+    add_code_uniqueness_index
+    add_index :spree_commission_rates, [:store_id, :enabled, :position]
+    add_index :spree_commission_rates, :deleted_at
+
+    # What a rate charges, and the bounds it charges within, in one currency.
+    # Every amount a rate states lives here: a marketplace writes each one
+    # deliberately rather than having a figure converted on its behalf, since
+    # a converted number would drift daily against a fee a seller has agreed.
+    #
+    # A flat fee uses +amount+; a percentage leaves it at zero and may state a
+    # floor and a cap instead, which is why only +amount+ carries a default.
+    create_table :spree_commission_rate_values do |t|
+      t.references :commission_rate, null: false
+      t.string :currency, null: false
+      t.decimal :amount, precision: 10, scale: 2, null: false, default: 0
+      t.decimal :min_amount, precision: 10, scale: 2
+      t.decimal :max_amount, precision: 10, scale: 2
+
+      t.timestamps
+      t.datetime :deleted_at
+    end
+
+    add_index :spree_commission_rate_values, :deleted_at
+    add_rate_value_uniqueness_index
+
+    create_table :spree_commission_rules do |t|
+      t.references :commission_rate, null: false
+      # The rule kind, as a class name. Typed rather than a subject reference
+      # so a rule can carry its own configuration — a value band or a date
+      # window has nothing to point at.
+      t.string :type, null: false
+
+      if t.respond_to?(:jsonb)
+        t.jsonb :preferences
+      else
+        t.json :preferences
+      end
+
+      t.timestamps
+      # Rules are retired with their rate, and separately as an operator edits
+      # a rate's conditions. Kept rather than deleted so a commission line
+      # stays explainable: "why was this charged" is answered by the rule that
+      # matched, which must still be readable afterwards.
+      t.datetime :deleted_at
+    end
+
+    add_index :spree_commission_rules, :deleted_at
+    # One rule of each kind per rate: a second would repeat the first or
+    # contradict it, and under AND semantics contradiction means the rate
+    # silently never applies. Live rows only, or replacing a rule would
+    # collide with the retired one it supersedes.
+    add_rule_uniqueness_index
+
+    # Catalog-scale references get a table of their own — a marketplace naming
+    # a thousand products should not put a thousand ids in a JSON column.
+    create_table :spree_commission_rule_products do |t|
+      t.references :commission_rule, null: false
+      t.references :product, null: false
+
+      t.timestamps
+      t.datetime :deleted_at
+    end
+
+    add_index :spree_commission_rule_products, :deleted_at
+    # Unique among live rows only: a rule that named a product, dropped it and
+    # named it again keeps the retired row beside the live one, but must never
+    # hold the same product twice at once.
+    add_rule_product_uniqueness_index
+  end
+
+  private
+
+  # A code is unique per store among the rates that are still there. Rates are
+  # paranoid, so a store that retires one must be able to reuse its code.
+  #
+  # Written per adapter because only PostgreSQL and SQLite have partial
+  # indexes. MySQL and MariaDB instead index a stored generated column holding
+  # the code only while the row is live, so a retired rate drops out of the
+  # index altogether — NULLs compare distinct there, which also lets a store
+  # retire and reuse the same code repeatedly.
+  #
+  # Verified against MySQL 8 and MariaDB 11: the two disagree sharply about
+  # what a generated column may contain. A DATETIME sentinel (`COALESCE(
+  # deleted_at, CAST(...))`) is MySQL-only, `UNIX_TIMESTAMP` is MariaDB-only,
+  # and a functional index on COALESCE — the older precedent in this tree — is
+  # MySQL-only too. This expression is the one both accept.
+  # One amount per currency per rate, among live rows.
+  def add_rate_value_uniqueness_index
+    if Spree.mysql?
+      reversible do |dir|
+        dir.up do
+          execute <<~SQL.squish
+            ALTER TABLE spree_commission_rate_values
+            ADD COLUMN currency_key VARCHAR(255)
+            AS (IF(deleted_at IS NULL, currency, NULL)) STORED
+          SQL
+          add_index :spree_commission_rate_values, [:commission_rate_id, :currency_key],
+                    unique: true, name: RATE_VALUE_INDEX_NAME
+        end
+
+        dir.down do
+          remove_index :spree_commission_rate_values, name: RATE_VALUE_INDEX_NAME
+          remove_column :spree_commission_rate_values, :currency_key
+        end
+      end
+    else
+      add_index :spree_commission_rate_values, [:commission_rate_id, :currency],
+                unique: true, where: 'deleted_at IS NULL', name: RATE_VALUE_INDEX_NAME
+    end
+  end
+
+  def add_rule_product_uniqueness_index
+    if Spree.mysql?
+      reversible do |dir|
+        dir.up do
+          execute <<~SQL.squish
+            ALTER TABLE spree_commission_rule_products
+            ADD COLUMN product_key BIGINT
+            AS (IF(deleted_at IS NULL, product_id, NULL)) STORED
+          SQL
+          add_index :spree_commission_rule_products, [:commission_rule_id, :product_key],
+                    unique: true, name: RULE_PRODUCT_INDEX_NAME
+        end
+
+        dir.down do
+          remove_index :spree_commission_rule_products, name: RULE_PRODUCT_INDEX_NAME
+          remove_column :spree_commission_rule_products, :product_key
+        end
+      end
+    else
+      add_index :spree_commission_rule_products, [:commission_rule_id, :product_id],
+                unique: true, where: 'deleted_at IS NULL', name: RULE_PRODUCT_INDEX_NAME
+    end
+  end
+
+  # Same per-adapter split as the rate's code index below, and for the same
+  # reason: only PostgreSQL and SQLite have partial indexes.
+  def add_rule_uniqueness_index
+    if Spree.mysql?
+      reversible do |dir|
+        dir.up do
+          execute <<~SQL.squish
+            ALTER TABLE spree_commission_rules
+            ADD COLUMN type_key VARCHAR(255)
+            AS (IF(deleted_at IS NULL, type, NULL)) STORED
+          SQL
+          add_index :spree_commission_rules, [:commission_rate_id, :type_key],
+                    unique: true, name: RULE_INDEX_NAME
+        end
+
+        dir.down do
+          remove_index :spree_commission_rules, name: RULE_INDEX_NAME
+          remove_column :spree_commission_rules, :type_key
+        end
+      end
+    else
+      add_index :spree_commission_rules, [:commission_rate_id, :type],
+                unique: true, where: 'deleted_at IS NULL', name: RULE_INDEX_NAME
+    end
+  end
+
+  def add_code_uniqueness_index
+    if Spree.mysql?
+      reversible do |dir|
+        dir.up do
+          execute <<~SQL.squish
+            ALTER TABLE spree_commission_rates
+            ADD COLUMN code_key VARCHAR(255)
+            AS (IF(deleted_at IS NULL, code, NULL)) STORED
+          SQL
+          add_index :spree_commission_rates, [:store_id, :code_key], unique: true, name: INDEX_NAME
+        end
+
+        dir.down do
+          remove_index :spree_commission_rates, name: INDEX_NAME
+          remove_column :spree_commission_rates, :code_key
+        end
+      end
+    else
+      add_index :spree_commission_rates, [:store_id, :code],
+                unique: true, where: 'deleted_at IS NULL', name: INDEX_NAME
+    end
+  end
+end

data/db/migrate/20260816210002_create_spree_commission_lines.rb

@@ -0,0 +1,72 @@
+class CreateSpreeCommissionLines < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_commission_lines do |t|
+      t.references :order, null: false
+      t.references :seller, null: false
+      # Exactly one of these two: the commissioned item, or the commissioned
+      # delivery when the rate carries include_shipping. Their indexes are
+      # declared below, unique.
+      t.references :line_item, index: false
+      t.references :fulfillment, index: false
+      # Nullable: the rate is mutable config and may be deleted long after the
+      # sale, but the line's snapshot below stays the record either way.
+      t.references :commission_rate
+
+      # Snapshot of what was applied, frozen at placement. A later rate change
+      # never reaches an existing line.
+      t.decimal :rate, precision: 8, scale: 5, null: false, default: 0
+      t.string :kind, null: false # percentage | fixed
+      # What the platform charges the seller.
+      t.decimal :amount, precision: 10, scale: 2, null: false, default: 0
+      # VAT on that commission — a separate B2B supply from the item sale.
+      t.decimal :tax_amount, precision: 10, scale: 2, null: false, default: 0
+      # The rate that tax was charged at, so the row explains its own figure
+      # once the configuration behind it has moved on.
+      t.decimal :tax_rate, precision: 8, scale: 5, null: false, default: 0
+      t.decimal :total, precision: 10, scale: 2, null: false, default: 0
+      t.string :currency, null: false
+
+      # How the commission was treated for tax, in the vocabulary
+      # Spree::TaxLine already uses — an invoice has to say why a fee was
+      # zero-rated or reverse-charged, and there is no reason for the
+      # marketplace's own invoices to speak a second language.
+      #
+      # One tax per line, deliberately: a marketplace fee is a single supply to
+      # a single business. Should a fee ever attract two levies at once, these
+      # columns are the ones that would move to child rows.
+      t.string :taxability_reason
+      # Where the fee was taxed — the seller's own jurisdiction, not the
+      # shopper's, since the platform invoices the seller's business. Named
+      # plainly so Spree::HasIsoGeography can validate and read them.
+      t.string :country_code
+      t.string :state_code
+
+      if t.respond_to?(:jsonb)
+        t.jsonb :metadata
+      else
+        t.json :metadata
+      end
+
+      t.timestamps
+
+      # Written portably rather than with num_nonnulls: the same schema has to
+      # build on MySQL and SQLite.
+      t.check_constraint '(line_item_id IS NULL) <> (fulfillment_id IS NULL)',
+                         name: 'chk_spree_commission_lines_one_subject'
+    end
+
+    add_index :spree_commission_lines, [:seller_id, :created_at]
+    # Reporting asks "what did we charge, where, and how was it treated" —
+    # the same questions Spree::TaxLine indexes for.
+    add_index :spree_commission_lines, :taxability_reason
+    add_index :spree_commission_lines, [:country_code, :state_code]
+    # One commission per item, and per fulfillment, so a replayed placement
+    # cannot double-charge a seller. Plain unique indexes rather than partial
+    # ones: every adapter treats NULLs as distinct here, so the rows carrying
+    # the other subject never collide.
+    add_index :spree_commission_lines, :line_item_id, unique: true,
+                                                      name: 'index_commission_lines_on_line_item'
+    add_index :spree_commission_lines, :fulfillment_id, unique: true,
+                                                        name: 'index_commission_lines_on_fulfillment'
+  end
+end

data/db/migrate/20260817000001_add_seller_to_spree_line_items.rb

@@ -0,0 +1,15 @@
+class AddSellerToSpreeLineItems < ActiveRecord::Migration[8.1]
+  # Which seller this line was bought from, snapshotted at the moment it was
+  # added. Nil is the operator's own first-party item.
+  #
+  # Denormalized on purpose rather than walked through the variant on read:
+  # the order split partitions on it, seller order lists and ability scoping
+  # filter on it, and once a product can be sold by several sellers the
+  # *product* can no longer answer which one a customer actually bought from.
+  #
+  # Snapshotting also keeps a placed order truthful — a seller's catalog can
+  # change hands afterwards, and the line still records who sold it.
+  def change
+    add_reference :spree_line_items, :seller, index: true
+  end
+end

data/db/migrate/20260817000002_add_seller_and_delivery_profile_to_spree_variants.rb

@@ -0,0 +1,17 @@
+class AddSellerAndDeliveryProfileToSpreeVariants < ActiveRecord::Migration[8.1]
+  # Which seller sells this variant, and how they ship it.
+  #
+  # The seller sits on the variant rather than only on the product because
+  # several sellers may sell the same item: one product page carries the
+  # marketplace's own new unit beside a seller's refurbished one, and only the
+  # variant can say which of them a customer chose. Nil is first-party.
+  #
+  # The delivery profile follows Spree::Variant#tax_category — nil defers to
+  # the product. Without it two sellers sharing a product would also share
+  # whichever shipping configuration resolved first, packing and pricing one
+  # seller's goods with another's.
+  def change
+    add_reference :spree_variants, :seller, index: true
+    add_reference :spree_variants, :delivery_profile, index: true
+  end
+end

data/db/migrate/20260818000001_create_spree_external_references.rb

@@ -0,0 +1,33 @@
+class CreateSpreeExternalReferences < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_external_references do |t|
+      t.references :store, null: false, index: false
+      t.string :system, null: false
+      t.references :resource, polymorphic: true, null: false, index: false
+      t.string :external_id, null: false
+      if t.respond_to?(:jsonb)
+        t.jsonb :metadata
+      else
+        t.json :metadata
+      end
+      t.timestamps
+    end
+
+    # One reference per system per record.
+    add_index :spree_external_references,
+              [:store_id, :system, :resource_type, :resource_id],
+              unique: true, name: 'idx_external_references_on_resource'
+
+    # An external id maps to exactly one record — what makes upsert-by-external-id safe.
+    add_index :spree_external_references,
+              [:store_id, :system, :resource_type, :external_id],
+              unique: true, name: 'idx_external_references_on_external_id'
+
+    # Reverse lookup for the resource-side association (resource → its references).
+    add_index :spree_external_references, [:resource_type, :resource_id],
+              name: 'idx_external_references_on_resource_lookup'
+
+    # No column moves: the company tree migration (20260807000001) is born
+    # without external_id — ERP/CRM identity lives here from the start.
+  end
+end

data/db/migrate/20260818000001_create_spree_seller_requirements.rb

@@ -0,0 +1,60 @@
+class CreateSpreeSellerRequirements < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_seller_requirements do |t|
+      t.references :store, null: false
+      t.string :type, null: false
+
+      # The operator's own copy, shown to sellers. Blank falls back to the
+      # kind's translated name, so only the generic kinds have to fill it in.
+      t.string :name
+      t.text :description
+
+      t.integer :position, null: false, default: 0
+      t.boolean :active, null: false, default: true
+      t.boolean :required, null: false, default: true
+
+      t.text :preferences
+
+      if t.respond_to?(:jsonb)
+        t.jsonb :metadata
+      else
+        t.json :metadata
+      end
+
+      t.timestamps
+    end
+
+    add_index :spree_seller_requirements, [:store_id, :position]
+    add_index :spree_seller_requirements, [:store_id, :type]
+
+    create_table :spree_seller_requirement_submissions do |t|
+      t.references :seller, null: false
+      t.references :seller_requirement, null: false
+      t.string :status, null: false # no DB default: set by the creating workflow
+
+      t.references :submitted_by
+      t.references :reviewed_by
+      t.datetime :reviewed_at
+
+      # What the seller said, and what the operator said back.
+      t.text :note
+      t.text :review_note
+      # An external identifier the kind understands (a provider account, say).
+      t.string :reference
+
+      if t.respond_to?(:jsonb)
+        t.jsonb :metadata
+      else
+        t.json :metadata
+      end
+
+      t.timestamps
+    end
+
+    # The latest row for a pair is the one that counts; older rows are the
+    # audit trail, so the index leads with the pair and ends with recency.
+    add_index :spree_seller_requirement_submissions,
+              [:seller_id, :seller_requirement_id, :created_at],
+              name: 'index_seller_requirement_submissions_on_pair_and_date'
+  end
+end

data/db/migrate/20260818000001_rename_spree_payments_state_to_status.rb

@@ -0,0 +1,5 @@
+class RenameSpreePaymentsStateToStatus < ActiveRecord::Migration[8.1]
+  def change
+    rename_column :spree_payments, :state, :status
+  end
+end

data/db/migrate/20260818000002_add_price_source_to_spree_line_items.rb

@@ -0,0 +1,9 @@
+class AddPriceSourceToSpreeLineItems < ActiveRecord::Migration[8.1]
+  def change
+    # Which engine priced this line. NULL means Spree's own catalog, where
+    # price_list_id already says which list won; a value names the provider,
+    # because an external price leaves no catalog row to point at and an order
+    # still has to be able to say why it charged what it charged.
+    add_column :spree_line_items, :price_source, :string
+  end
+end

data/db/migrate/20260818090001_rename_assets_to_media.rb

@@ -0,0 +1,10 @@
+class RenameAssetsToMedia < ActiveRecord::Migration[8.1]
+  # The API, the prefixed id (`media_...`) and the join table have all said
+  # "media" since 5.4/5.5. This brings the table and model in line.
+  #
+  # `spree_variant_media.media_id` already points here under the right name, so
+  # no foreign-key column changes.
+  def change
+    rename_table :spree_assets, :spree_media
+  end
+end

data/db/migrate/20260819000001_create_spree_seller_requirement_custom_fields.rb

@@ -0,0 +1,15 @@
+class CreateSpreeSellerRequirementCustomFields < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_seller_requirement_custom_fields do |t|
+      t.references :seller_requirement, null: false, index: false
+      t.references :custom_field_definition, null: false
+
+      t.timestamps
+    end
+
+    # A requirement asks for a field once; the pair is the row's identity.
+    add_index :spree_seller_requirement_custom_fields,
+              [:seller_requirement_id, :custom_field_definition_id],
+              unique: true, name: 'idx_seller_requirement_custom_fields_uniqueness'
+  end
+end

data/db/migrate/20260819000001_replace_payment_method_display_on_with_storefront_visible.rb

@@ -0,0 +1,25 @@
+class ReplacePaymentMethodDisplayOnWithStorefrontVisible < ActiveRecord::Migration[8.1]
+  # Payment methods are the last host of the tri-state display_on column
+  # (docs/plans/5.5-6.0-display-on-to-boolean.md). Only back_end ever meant
+  # "hide from the storefront"; both and the legacy front_end-only value
+  # collapse to true.
+  def up
+    add_column :spree_payment_methods, :storefront_visible, :boolean, default: true, null: false
+    execute(<<~SQL.squish)
+      UPDATE spree_payment_methods
+      SET storefront_visible = #{connection.quoted_false}
+      WHERE display_on = 'back_end'
+    SQL
+    remove_column :spree_payment_methods, :display_on
+  end
+
+  def down
+    add_column :spree_payment_methods, :display_on, :string, default: 'both'
+    execute(<<~SQL.squish)
+      UPDATE spree_payment_methods
+      SET display_on = 'back_end'
+      WHERE storefront_visible = #{connection.quoted_false}
+    SQL
+    remove_column :spree_payment_methods, :storefront_visible
+  end
+end

data/db/migrate/20260819000002_rename_spree_gift_cards_state_to_status.rb

@@ -0,0 +1,5 @@
+class RenameSpreeGiftCardsStateToStatus < ActiveRecord::Migration[8.1]
+  def change
+    rename_column :spree_gift_cards, :state, :status
+  end
+end

data/db/migrate/20260820000001_add_seller_business_identity_and_stock_locations.rb

@@ -0,0 +1,17 @@
+class AddSellerBusinessIdentityAndStockLocations < ActiveRecord::Migration[8.1]
+  def change
+    # Seller-owned stock. Nullable: an operator's own locations have no seller,
+    # and that is the common case in a store that is not a marketplace.
+    #
+    # No uniqueness index on the name alongside it. Names are unique per owner
+    # once a marketplace has sellers, but that stays a validation as it always
+    # has been on this table — nothing resolves a location by name.
+    add_reference :spree_stock_locations, :seller, null: true
+
+    # The business behind the seller, as a commission invoice must address it.
+    # Distinct from the trading name: "Sparks" sells, "Sparks Trading Ltd"
+    # is invoiced.
+    add_column :spree_sellers, :legal_name, :string
+    add_column :spree_sellers, :registration_number, :string
+  end
+end

data/db/migrate/20260820000001_create_spree_order_groups.rb

@@ -0,0 +1,33 @@
+class CreateSpreeOrderGroups < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_order_groups do |t|
+      t.references :store, null: false
+      t.references :customer, index: true # guest checkouts have no customer
+      # The cart this group was completed from. Unique for the same reason
+      # orders.cart_id is: it is the completion idempotency key, so a replayed
+      # completion finds the group instead of building a second one.
+      t.references :cart, index: { unique: true }
+
+      t.string :number, null: false
+      t.string :currency, null: false
+      # Guest checkouts carry the contact address here, as the order does.
+      t.string :email
+      t.string :token
+
+      t.references :ship_address
+      t.references :bill_address
+
+      if t.respond_to?(:jsonb)
+        t.jsonb :metadata
+      else
+        t.json :metadata
+      end
+
+      t.timestamps
+    end
+
+    add_index :spree_order_groups, :number, unique: true
+    add_index :spree_order_groups, [:store_id, :created_at]
+    add_index :spree_order_groups, :token
+  end
+end

data/db/migrate/20260820000002_add_order_group_to_spree_orders_and_payments.rb

@@ -0,0 +1,14 @@
+class AddOrderGroupToSpreeOrdersAndPayments < ActiveRecord::Migration[8.1]
+  def change
+    # Which seller sold this order, and which checkout it was placed in. Both
+    # nullable: a store selling only its own goods never sets either, and the
+    # first-party child of a mixed checkout carries a group but no seller.
+    add_reference :spree_orders, :seller, index: true
+    add_reference :spree_orders, :order_group, index: true
+
+    # A grouped checkout's payment belongs to the group rather than to any one
+    # child order — there is one charge, and the per-order shares are
+    # spree_payment_splits rows. An ungrouped order keeps payments.order_id.
+    add_reference :spree_payments, :order_group, index: true
+  end
+end

data/db/migrate/20260820000003_create_spree_payment_splits.rb

@@ -0,0 +1,21 @@
+class CreateSpreePaymentSplits < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_payment_splits do |t|
+      t.references :payment, null: false, index: false
+      t.references :order, null: false
+
+      # This child order's share of that one payment. Captures and refunds on a
+      # child update its own row and never a sibling's — which is the whole
+      # reason the share is a record rather than a proportion computed on read.
+      t.decimal :authorized_amount, precision: 10, scale: 2, null: false, default: 0
+      t.decimal :captured_amount, precision: 10, scale: 2, null: false, default: 0
+      t.decimal :refunded_amount, precision: 10, scale: 2, null: false, default: 0
+      t.string :currency, null: false
+
+      t.timestamps
+    end
+
+    # One share per (payment, order), so a replayed split cannot write a second.
+    add_index :spree_payment_splits, [:payment_id, :order_id], unique: true
+  end
+end

data/db/migrate/20260820000004_add_order_to_spree_refunds.rb

@@ -0,0 +1,32 @@
+class AddOrderToSpreeRefunds < ActiveRecord::Migration[8.1]
+  def change
+    # Which order this refund is against.
+    #
+    # A refund used to reach its order through its payment, which works while
+    # one payment belongs to one order. In a split checkout the payment belongs
+    # to the group and covers several orders, so the refund has to say which
+    # one it is putting right — the seller's books, the commission reversal and
+    # the payment share all have to agree on the answer.
+    #
+    # Nullable, and backfilled from the payment for existing rows: every refund
+    # written before this column belongs to a payment that belongs to exactly
+    # one order, so the answer is already in the data.
+    add_reference :spree_refunds, :order, index: true
+
+    reversible do |direction|
+      direction.up do
+        # A correlated UPDATE rather than Active Record: the same statement
+        # runs on every adapter, and a migration should not depend on models
+        # that may be renamed long after it has run.
+        execute <<~SQL.squish
+          UPDATE spree_refunds
+          SET order_id = (
+            SELECT order_id FROM spree_payments
+            WHERE spree_payments.id = spree_refunds.payment_id
+          )
+          WHERE order_id IS NULL
+        SQL
+      end
+    end
+  end
+end

data/db/migrate/20260821000001_add_claimed_amount_to_spree_payment_splits.rb

@@ -0,0 +1,14 @@
+class AddClaimedAmountToSpreePaymentSplits < ActiveRecord::Migration[8.1]
+  def change
+    # What a parcel has reserved of this share but not yet drawn.
+    #
+    # A dispatch marks its intention before asking the gateway, so that two
+    # parcels of the same order cannot draw the same money. Recording that in
+    # `captured_amount` conflated it with money the gateway confirmed, and
+    # anything settling against the share — a cancellation, a refund — could
+    # then give back an amount that was never taken. The claim lives here and
+    # moves into `captured_amount` only once the charge lands.
+    add_column :spree_payment_splits, :claimed_amount, :decimal, precision: 10, scale: 2,
+                                                                null: false, default: 0
+  end
+end