Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Make refund reasons store-owned

Damian Legawiec71189c7a5688
diff --git a/CLAUDE.md b/CLAUDE.md
index dd96de4252..3205958b0a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -141,7 +141,7 @@ One-time machine setup: Homebrew `postgresql@18` running on :5432 (with a `postg
- Follow Rails conventions and the Rails Security Guide
- RESTful routes and action names
- CanCanCan for authorization: listings use `accessible_by(current_ability, :show)`, other actions use `authorize!`
-- Always use scope fetching for security (e.g. `current_store.orders` not `Spree::Order`)
+- Always use scope fetching for security (e.g. `current_store.orders` not `Spree::Order`). This applies to **every** lookup in a controller, including the incidental ones — resolving a `reason_id` or `stock_location_id` from a create param through the model constant accepts an id belonging to another store. Reading it through `current_store.<association>` turns that into a 404, which is the cheapest defence against IDOR. `accessible_by(current_ability, ...)` is not a substitute: it filters by role, not by tenant.
- Ransack for filtering/searching, Pagy for pagination
- Use services only when necessary — prefer standard Rails models and concerns
- DO NOT call `Spree::User` directly, use `Spree.user_class`; same for `Spree.admin_user_class`
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index 7fd1918e76..21ae217323 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -1,3 +1,31 @@
+## 2026-08-06: All three reason vocabularies are store-owned
+
+`ReturnReason`, `ClaimReason` and now `RefundReason` include
+`SingleStoreResource`. Name uniqueness moves from global to per-store, so
+two stores can each have their own "Damaged" or "Order Canceled".
+
+This is what makes the controller rule enforceable: every reason lookup
+reads `current_store.return_reasons` rather than the model constant, so a
+prefixed id from another store is a 404 instead of a silent success — the
+cheapest defence against IDOR, and now uniform across the returns surface
+alongside `current_store.stock_locations`.
+
+Refund reasons carried one wrinkle the others did not. Core looks three
+of them up by name (`RETURN_PROCESSING_REASON` and friends) to attach to
+refunds it issues itself, and a global `find_or_create_by(name:)` under a
+per-store unique index would either find another store's row or create a
+storeless one. The class methods therefore take the store explicitly —
+`return_processing_reason(store)` — defaulting to `Spree::Current.store`
+but never relying on it from a workflow, because a background job or
+console session has no current store and would bind the reason to the
+wrong one. All four call sites pass the store they already hold.
+
+Existing rows are backfilled by `spree:upgrade:backfill_reason_store_ids`,
+registered before `migrate_returns` in the 5.6→6.0 manifest. The
+migration only adds the column — data transformations stay in rake tasks,
+matching `backfill_delivery_and_stock_store_ids`.
+
+
## 2026-08-06: Return shipping labels are carrier output, not return state — cut from 6.0
`Spree::Return` briefly carried a `return_label_url` column written by a
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/refund_reasons_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/refund_reasons_controller_spec.rb
index b127328cf8..884b466cc8 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/refund_reasons_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/refund_reasons_controller_spec.rb
@@ -21,6 +21,26 @@ RSpec.describe Spree::Api::V3::Admin::RefundReasonsController, type: :controller
to change(Spree::RefundReason, :count).by(1)
end
+ # The seeded reasons are per store now, so one store's "Return processing"
+ # is invisible to another rather than shared.
+ describe 'store scoping' do
+ let!(:other_store) { create(:store) }
+ let!(:other_store_reason) { Spree::RefundReason.return_processing_reason(other_store) }
+
+ it 'excludes another store\'s reason from the listing' do
+ get :index, as: :json
+
+ expect(json_response['data'].map { |r| r['id'] }).not_to include(other_store_reason.prefixed_id)
+ end
+
+ it 'gives each store its own seeded reason' do
+ mine = Spree::RefundReason.return_processing_reason(@default_store)
+
+ expect(mine.id).not_to eq(other_store_reason.id)
+ expect(mine.name).to eq(other_store_reason.name)
+ end
+ end
+
# Core looks this one up by name to attach to every return refund.
context 'with the seeded return-processing reason' do
let!(:locked) { Spree::RefundReason.return_processing_reason }
diff --git a/spree/core/app/models/spree/refund_reason.rb b/spree/core/app/models/spree/refund_reason.rb
index 658ef0f563..a43c073178 100644
--- a/spree/core/app/models/spree/refund_reason.rb
+++ b/spree/core/app/models/spree/refund_reason.rb
@@ -1,27 +1,51 @@
module Spree
+ # Why money went back — "Return processing", "Order Canceled". Store-owned
+ # like {Spree::ReturnReason} and {Spree::ClaimReason}.
class RefundReason < Spree.base_class
has_prefix_id :rr
include Spree::NamedType
+ include Spree::SingleStoreResource
+
+ # Names are unique per store, not globally — two stores can each have
+ # their own "Order Canceled" without colliding.
+ validates :name, uniqueness: { case_sensitive: false, scope: :store_id }
self.whitelisted_ransackable_attributes = %w[name active mutable]
- RETURN_PROCESSING_REASON = 'Return processing'
- ORDER_CANCELED_REASON = 'Order Canceled'
- SHIPMENT_CANCELED_REASON = 'Shipment Canceled'
+ RETURN_PROCESSING_REASON = 'Return processing'.freeze
+ ORDER_CANCELED_REASON = 'Order Canceled'.freeze
+ SHIPMENT_CANCELED_REASON = 'Shipment Canceled'.freeze
has_many :refunds, dependent: :restrict_with_error
- def self.return_processing_reason
- find_or_create_by(name: RETURN_PROCESSING_REASON, mutable: false)
- end
+ class << self
+ # The seeded reasons core attaches to refunds it issues itself.
+ #
+ # Each takes the store explicitly rather than reading
+ # `Spree::Current.store`: these are called from workflows that already
+ # hold the record's store, and a background job or console session has
+ # no current store to fall back on — which would silently create the
+ # reason against the wrong one.
+ def return_processing_reason(store = Spree::Current.store)
+ seeded(RETURN_PROCESSING_REASON, store)
+ end
- def self.order_canceled_reason
- find_or_create_by(name: ORDER_CANCELED_REASON, mutable: false)
- end
+ def order_canceled_reason(store = Spree::Current.store)
+ seeded(ORDER_CANCELED_REASON, store)
+ end
+
+ def shipment_canceled_reason(store = Spree::Current.store)
+ seeded(SHIPMENT_CANCELED_REASON, store)
+ end
+
+ private
- def self.shipment_canceled_reason
- find_or_create_by(name: SHIPMENT_CANCELED_REASON, mutable: false)
+ def seeded(name, store)
+ where(store: store).find_or_create_by(name: name) do |reason|
+ reason.mutable = false
+ end
+ end
end
end
end
diff --git a/spree/core/app/models/spree/store.rb b/spree/core/app/models/spree/store.rb
index c0f29d6582..28b5801347 100644
--- a/spree/core/app/models/spree/store.rb
+++ b/spree/core/app/models/spree/store.rb
@@ -84,6 +84,7 @@ module Spree
has_many :claims, class_name: 'Spree::Claim', inverse_of: :store
has_many :return_reasons, class_name: 'Spree::ReturnReason', inverse_of: :store, dependent: :destroy
has_many :claim_reasons, class_name: 'Spree::ClaimReason', inverse_of: :store, dependent: :destroy
+ has_many :refund_reasons, class_name: 'Spree::RefundReason', inverse_of: :store, dependent: :destroy
# :nullify (not :destroy) — clearing the collection must not cascade into
# Promotion#not_used? / payment records; orphaned rows are detached, not deleted.
diff --git a/spree/core/app/services/spree/seeds/returns_environment.rb b/spree/core/app/services/spree/seeds/returns_environment.rb
index 77514b36d6..fe989f5312 100644
--- a/spree/core/app/services/spree/seeds/returns_environment.rb
+++ b/spree/core/app/services/spree/seeds/returns_environment.rb
@@ -26,13 +26,13 @@ module Spree
].freeze
def call
- # Through the model helper, not a literal — the workflows look this
- # row up by the same constant, so a hard-coded string here would
- # silently create a second, unfindable reason if the name ever moves.
- Spree::RefundReason.return_processing_reason
-
- # Reasons are store-owned, so every store gets its own vocabulary.
+ # All three vocabularies are store-owned, so every store gets its own.
Spree::Store.all.find_each do |store|
+ # Through the model helper, not a literal — the workflows look this
+ # row up by the same constant, so a hard-coded string here would
+ # silently create a second, unfindable reason if the name ever moves.
+ Spree::RefundReason.return_processing_reason(store)
+
RETURN_REASONS.each { |name| Spree::ReturnReason.where(store: store).find_or_create_by!(name: name) }
CLAIM_REASONS.each { |name| Spree::ClaimReason.where(store: store).find_or_create_by!(name: name) }
end
diff --git a/spree/core/app/workflows/spree/claims/resolve.rb b/spree/core/app/workflows/spree/claims/resolve.rb
index 925ba7eaa9..fd28f09cf2 100644
--- a/spree/core/app/workflows/spree/claims/resolve.rb
+++ b/spree/core/app/workflows/spree/claims/resolve.rb
@@ -142,7 +142,7 @@ module Spree
@refunds << payment.refunds.create!(
amount: creditable,
- reason: Spree::RefundReason.return_processing_reason,
+ reason: Spree::RefundReason.return_processing_reason(claim.store),
refunder: resolver,
originator: claim
)
diff --git a/spree/core/app/workflows/spree/exchanges/fulfill.rb b/spree/core/app/workflows/spree/exchanges/fulfill.rb
index a50c1bc02e..043ed479f0 100644
--- a/spree/core/app/workflows/spree/exchanges/fulfill.rb
+++ b/spree/core/app/workflows/spree/exchanges/fulfill.rb
@@ -121,7 +121,7 @@ module Spree
@refunds << payment.refunds.create!(
amount: creditable,
- reason: Spree::RefundReason.return_processing_reason,
+ reason: Spree::RefundReason.return_processing_reason(exchange.store),
refunder: refunder,
originator: exchange
)
diff --git a/spree/core/app/workflows/spree/payments/refund.rb b/spree/core/app/workflows/spree/payments/refund.rb
index e5d6a69219..ce34ff2b4e 100644
--- a/spree/core/app/workflows/spree/payments/refund.rb
+++ b/spree/core/app/workflows/spree/payments/refund.rb
@@ -61,7 +61,7 @@ module Spree
def issue_refund
@refund = payment.refunds.create!(
amount: @amount_to_refund,
- reason: reason || Spree::RefundReason.return_processing_reason,
+ reason: reason || Spree::RefundReason.return_processing_reason(payment.order&.store),
refunder: refunder
)
rescue Spree::Core::GatewayError => error
diff --git a/spree/core/app/workflows/spree/returns/refund.rb b/spree/core/app/workflows/spree/returns/refund.rb
index 3beeac5fcd..bc25d56631 100644
--- a/spree/core/app/workflows/spree/returns/refund.rb
+++ b/spree/core/app/workflows/spree/returns/refund.rb
@@ -107,7 +107,7 @@ module Spree
@refunds << payment.refunds.create!(
amount: creditable,
- reason: Spree::RefundReason.return_processing_reason,
+ reason: Spree::RefundReason.return_processing_reason(return_record.store),
refunder: refunder,
originator: return_record
)
diff --git a/spree/core/db/migrate/20260805100001_rename_return_authorization_reasons_to_return_reasons.rb b/spree/core/db/migrate/20260805100001_rename_return_authorization_reasons_to_return_reasons.rb
index ea6f7e2ec3..685fb52596 100644
--- a/spree/core/db/migrate/20260805100001_rename_return_authorization_reasons_to_return_reasons.rb
+++ b/spree/core/db/migrate/20260805100001_rename_return_authorization_reasons_to_return_reasons.rb
@@ -17,10 +17,23 @@ class RenameReturnAuthorizationReasonsToReturnReasons < ActiveRecord::Migration[
# Store-owned like every other reason vocabulary, so two stores can each
# have their own "Damaged" without colliding. The uniqueness scope moves
# with it: name is unique per store, not globally.
+ #
+ # Refund reasons join them: all three answer "why", differ only in which
+ # record they explain, and a single-store install can't tell the
+ # difference.
+ #
+ # Existing rows are backfilled by `spree:backfill_reason_store_ids`, not
+ # here — data transformations belong in a rake task. That matters more
+ # than usual for refund reasons: core looks three of them up by name, so
+ # until the task runs those lookups see a null store_id and would mint a
+ # duplicate per store.
add_reference :spree_return_reasons, :store
+ add_reference :spree_refund_reasons, :store
remove_index :spree_return_reasons, :name
+ remove_index :spree_refund_reasons, :name
add_index :spree_return_reasons, [:store_id, :name], unique: true
+ add_index :spree_refund_reasons, [:store_id, :name], unique: true
add_index :spree_claim_reasons, [:store_id, :name], unique: true
end
end
diff --git a/spree/core/lib/spree/testing_support/factories/refund_factory.rb b/spree/core/lib/spree/testing_support/factories/refund_factory.rb
index 7cd93a93d8..88ba082066 100644
--- a/spree/core/lib/spree/testing_support/factories/refund_factory.rb
+++ b/spree/core/lib/spree/testing_support/factories/refund_factory.rb
@@ -15,6 +15,7 @@ FactoryBot.define do
end
factory :refund_reason, class: Spree::RefundReason do
+ store { Spree::Store.find_by(default: true) || association(:store) }
sequence(:name) { |n| "Refund for return #{n}" }
active { true }
mutable { false }
diff --git a/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml b/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml
index b292ae2f5a..eae71080c9 100644
--- a/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml
+++ b/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml
@@ -130,6 +130,17 @@ steps:
migration. spree_adjustments stays intact as the rollback source.
Idempotent — orders that already have typed rows are skipped.
+ - id: backfill_reason_store_ids
+ name: "Bind return and refund reasons to the default store"
+ task: "spree:upgrade:backfill_reason_store_ids"
+ notes: |
+ Return and refund reasons are store-owned in Spree 6. Unassigned rows go
+ to the default store; additional stores manage their own afterwards.
+
+ Run before migrate_returns. Core looks three refund reasons up by name
+ scoped to a store, so until every row carries one those lookups miss and
+ mint a duplicate on the next refund. Idempotent.
+
- id: migrate_returns
name: "Move returns onto the new returns models"
task: "spree:upgrade:migrate_returns"
diff --git a/spree/core/lib/tasks/backfill_reason_store_ids.rake b/spree/core/lib/tasks/backfill_reason_store_ids.rake
new file mode 100644
index 0000000000..6d26452aec
--- /dev/null
+++ b/spree/core/lib/tasks/backfill_reason_store_ids.rake
@@ -0,0 +1,27 @@
+namespace :spree do
+ namespace :upgrade do
+ desc <<~DESC
+ Assigns the default store to return and refund reasons that predate
+ their store binding (Spree 6.0). Idempotent — rows that already carry a
+ store_id are skipped.
+
+ Run this immediately after db:migrate. Core looks three refund reasons
+ up by name (RefundReason::RETURN_PROCESSING_REASON and friends) scoped
+ to a store, so until every row carries one those lookups miss and mint
+ a duplicate on the next refund.
+
+ Claim reasons need no backfill — the table is new in 6.0 and its rows
+ are born with a store.
+ DESC
+ task backfill_reason_store_ids: :environment do
+ store = Spree::Store.default
+ abort ' No default store found — create a store first.' if store.nil?
+
+ return_reasons = Spree::ReturnReason.where(store_id: nil).update_all(store_id: store.id)
+ refund_reasons = Spree::RefundReason.where(store_id: nil).update_all(store_id: store.id)
+
+ puts " Assigned #{return_reasons} return reason(s) and #{refund_reasons} refund reason(s) " \
+ "to store #{store.name} (#{store.id})."
+ end
+ end
+end