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.

Add DeliveryZone with typed members (delivery-zones Phase A)

Damian Legawiec107fb8ef7fec
diff --git a/spree/core/app/models/spree/address.rb b/spree/core/app/models/spree/address.rb
index dfc37a6036..1f31d5139b 100644
--- a/spree/core/app/models/spree/address.rb
+++ b/spree/core/app/models/spree/address.rb
@@ -86,6 +86,19 @@ module Spree
alias_attribute :first_name, :firstname
alias_attribute :last_name, :lastname
+ # The single home for postal-code normalization (delivery-zone matching) —
+ # don't scatter zipcode munging elsewhere.
+ # @param value [String, nil]
+ # @return [String] value with spaces/dashes stripped, upcased
+ def self.normalize_zipcode(value)
+ value.to_s.gsub(/[\s-]/, '').upcase
+ end
+
+ # @return [String] this address's zipcode, normalized via {.normalize_zipcode}
+ def normalized_zipcode
+ self.class.normalize_zipcode(zipcode)
+ end
+
# Writer methods for API convenience - these set country/state from ISO/abbr codes
# The reader methods (country_iso, state_abbr) are delegates to country.iso and state.abbr
def country_iso=(value)
diff --git a/spree/core/app/models/spree/delivery_zone.rb b/spree/core/app/models/spree/delivery_zone.rb
new file mode 100644
index 0000000000..4359c6923d
--- /dev/null
+++ b/spree/core/app/models/spree/delivery_zone.rb
@@ -0,0 +1,23 @@
+module Spree
+ class DeliveryZone < Spree.base_class
+ has_prefix_id :dz
+
+ # Single consolidated metadata JSON column (docs/plans/decisions.md
+ # 2026-03-16 "Consolidate metadata") — write-only developer escape hatch.
+ attribute :metadata, default: -> { {} }
+
+ has_many :members, class_name: 'Spree::DeliveryZoneMember', dependent: :destroy, inverse_of: :delivery_zone
+
+ validates :name, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }
+
+ self.whitelisted_ransackable_attributes = %w[name]
+
+ # @param address [Spree::Address, nil]
+ # @return [Boolean] whether any member of this zone matches the address
+ def include?(address)
+ return false if address.nil?
+
+ members.any? { |member| member.match?(address) }
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/delivery_zone_member.rb b/spree/core/app/models/spree/delivery_zone_member.rb
new file mode 100644
index 0000000000..c59492dbcf
--- /dev/null
+++ b/spree/core/app/models/spree/delivery_zone_member.rb
@@ -0,0 +1,78 @@
+module Spree
+ class DeliveryZoneMember < Spree.base_class
+ has_prefix_id :dzm
+
+ MEMBER_TYPES = %w[country state postal_code].freeze
+
+ # ISO codes of countries with numeric postal formats, where lexicographic
+ # ranges over normalized codes are meaningful. Prefix members are allowed
+ # for every country; range members only for these. Extend via
+ # `Spree::DeliveryZoneMember.range_capable_country_isos += %w[XY]`.
+ class_attribute :range_capable_country_isos, default: %w[
+ AR AT AU BD BE BG BR CH CN CZ DE DK DZ EE EG ES FI FR GR HR HU ID IL IN
+ IS IT JP KR LK LT LU MA MX MY NO NZ PH PK PL PT RO RS RU SA SE SG SI SK
+ TH TN TR TW UA US UY VN ZA
+ ].freeze
+
+ belongs_to :delivery_zone, class_name: 'Spree::DeliveryZone', inverse_of: :members
+ belongs_to :country, class_name: 'Spree::Country', optional: true
+ belongs_to :state, class_name: 'Spree::State', optional: true
+
+ normalizes :postal_code_prefix, :postal_code_from, :postal_code_to,
+ with: ->(value) { Spree::Address.normalize_zipcode(value).presence }
+
+ validates :member_type, presence: true, inclusion: { in: MEMBER_TYPES }
+ validates :country, presence: true, if: -> { member_type.in?(%w[country postal_code]) }
+ validates :state, presence: true, if: -> { member_type == 'state' }
+ validate :postal_definition, if: -> { member_type == 'postal_code' }
+
+ # @param address [Spree::Address]
+ # @return [Boolean] whether the address falls inside this member
+ def match?(address)
+ case member_type
+ when 'country' then address.country_id == country_id
+ when 'state' then address.state_id == state_id
+ when 'postal_code' then address.country_id == country_id && postal_match?(address.normalized_zipcode)
+ else false
+ end
+ end
+
+ # @return [Boolean] whether this member defines a from/to range (vs a prefix)
+ def postal_range?
+ postal_code_from.present? || postal_code_to.present?
+ end
+
+ private
+
+ # Stored values are normalized on assignment (see +normalizes+ above), so
+ # matching compares normalized against normalized.
+ def postal_match?(zipcode)
+ return false if zipcode.blank?
+
+ if postal_code_prefix.present?
+ zipcode.start_with?(postal_code_prefix)
+ else
+ zipcode >= postal_code_from && zipcode <= postal_code_to
+ end
+ end
+
+ def postal_definition
+ if postal_code_prefix.present?
+ errors.add(:postal_code_prefix, Spree.t('errors.messages.delivery_zone_prefix_and_range_exclusive')) if postal_range?
+ return
+ end
+
+ if postal_code_from.blank? || postal_code_to.blank?
+ errors.add(:base, Spree.t('errors.messages.delivery_zone_postal_definition_required'))
+ return
+ end
+
+ unless country&.iso.present? && range_capable_country_isos.include?(country.iso)
+ errors.add(:base, Spree.t('errors.messages.delivery_zone_range_not_supported'))
+ return
+ end
+
+ errors.add(:postal_code_to, Spree.t('errors.messages.delivery_zone_range_inverted')) if postal_code_to < postal_code_from
+ end
+ end
+end
diff --git a/spree/core/db/migrate/20260728000002_create_spree_delivery_zones.rb b/spree/core/db/migrate/20260728000002_create_spree_delivery_zones.rb
new file mode 100644
index 0000000000..da9b1b4d7f
--- /dev/null
+++ b/spree/core/db/migrate/20260728000002_create_spree_delivery_zones.rb
@@ -0,0 +1,28 @@
+class CreateSpreeDeliveryZones < ActiveRecord::Migration[7.2]
+ def change
+ create_table :spree_delivery_zones do |t|
+ t.string :name, null: false
+ t.string :description
+ if t.respond_to?(:jsonb)
+ t.jsonb :metadata
+ else
+ t.json :metadata
+ end
+
+ t.timestamps
+ end
+ add_index :spree_delivery_zones, :name, unique: true
+
+ create_table :spree_delivery_zone_members do |t|
+ t.references :delivery_zone, null: false
+ t.string :member_type, null: false
+ t.references :country, null: true
+ t.references :state, null: true
+ t.string :postal_code_prefix
+ t.string :postal_code_from
+ t.string :postal_code_to
+
+ t.timestamps
+ end
+ end
+end
diff --git a/spree/core/lib/spree/testing_support/factories/delivery_zone_factory.rb b/spree/core/lib/spree/testing_support/factories/delivery_zone_factory.rb
new file mode 100644
index 0000000000..89b78f1a06
--- /dev/null
+++ b/spree/core/lib/spree/testing_support/factories/delivery_zone_factory.rb
@@ -0,0 +1,22 @@
+FactoryBot.define do
+ factory :delivery_zone, class: Spree::DeliveryZone do
+ sequence(:name) { |n| "Delivery Zone ##{n}" }
+ description { generate(:random_string) }
+
+ factory :delivery_zone_with_country do
+ transient do
+ country { create(:country) }
+ end
+
+ after(:create) do |zone, evaluator|
+ create(:delivery_zone_member, delivery_zone: zone, member_type: 'country', country: evaluator.country)
+ end
+ end
+ end
+
+ factory :delivery_zone_member, class: Spree::DeliveryZoneMember do
+ delivery_zone
+ member_type { 'country' }
+ country
+ end
+end
diff --git a/spree/core/spec/models/spree/address_spec.rb b/spree/core/spec/models/spree/address_spec.rb
index 463a9ec203..e5f0f4d38b 100644
--- a/spree/core/spec/models/spree/address_spec.rb
+++ b/spree/core/spec/models/spree/address_spec.rb
@@ -712,6 +712,13 @@ describe Spree::Address, type: :model do
end
end
+ describe '#normalized_zipcode' do
+ it 'strips spaces and dashes and upcases' do
+ expect(build(:address, zipcode: ' sw1a 1-aa ').normalized_zipcode).to eq('SW1A1AA')
+ expect(build(:address, zipcode: nil).normalized_zipcode).to eq('')
+ end
+ end
+
describe '#to_s' do
let(:address) { create(:address) }
diff --git a/spree/core/spec/models/spree/delivery_zone_member_spec.rb b/spree/core/spec/models/spree/delivery_zone_member_spec.rb
new file mode 100644
index 0000000000..30c90149f9
--- /dev/null
+++ b/spree/core/spec/models/spree/delivery_zone_member_spec.rb
@@ -0,0 +1,102 @@
+require 'spec_helper'
+
+describe Spree::DeliveryZoneMember, type: :model do
+ let(:zone) { create(:delivery_zone) }
+ let(:germany) { create(:country, iso: 'DE', iso3: 'DEU', name: 'Germany', iso_name: 'GERMANY') }
+ let(:uk) { create(:country, iso: 'GB', iso3: 'GBR', name: 'United Kingdom', iso_name: 'UNITED KINGDOM') }
+
+ describe '#match?' do
+ context 'country member' do
+ let(:member) { create(:delivery_zone_member, delivery_zone: zone, member_type: 'country', country: germany) }
+
+ it 'matches addresses in the country and rejects others' do
+ expect(member.match?(build(:address, country: germany))).to be(true)
+ expect(member.match?(build(:address, country: uk))).to be(false)
+ end
+ end
+
+ context 'state member' do
+ let(:state) { create(:state, country: germany) }
+ let(:member) { create(:delivery_zone_member, delivery_zone: zone, member_type: 'state', country: nil, state: state) }
+
+ it 'matches addresses in the state and rejects others' do
+ expect(member.match?(build(:address, country: germany, state: state))).to be(true)
+ expect(member.match?(build(:address, country: germany, state: create(:state, country: germany)))).to be(false)
+ end
+ end
+
+ context 'postal prefix member' do
+ let(:member) do
+ create(:delivery_zone_member, delivery_zone: zone, member_type: 'postal_code',
+ country: uk, postal_code_prefix: 'sw1')
+ end
+
+ it 'matches normalized zipcodes by prefix, scoped to the country' do
+ expect(member.match?(build(:address, country: uk, zipcode: 'SW1A 1AA'))).to be(true)
+ expect(member.match?(build(:address, country: uk, zipcode: 'EC1A 1BB'))).to be(false)
+ expect(member.match?(build(:address, country: germany, zipcode: 'SW1A 1AA'))).to be(false)
+ end
+ end
+
+ context 'postal range member' do
+ let(:member) do
+ create(:delivery_zone_member, delivery_zone: zone, member_type: 'postal_code',
+ country: germany, postal_code_from: '10115', postal_code_to: '10999')
+ end
+
+ it 'matches zipcodes inside the range, scoped to the country' do
+ expect(member.match?(build(:address, country: germany, zipcode: '10 405'))).to be(true)
+ expect(member.match?(build(:address, country: germany, zipcode: '11011'))).to be(false)
+ expect(member.match?(build(:address, country: germany, zipcode: ''))).to be(false)
+ end
+ end
+ end
+
+ describe 'postal member validation' do
+ it 'normalizes prefix and range bounds on save' do
+ member = create(:delivery_zone_member, delivery_zone: zone, member_type: 'postal_code',
+ country: uk, postal_code_prefix: ' sw1-a ')
+
+ expect(member.postal_code_prefix).to eq('SW1A')
+ end
+
+ it 'rejects a prefix combined with a range' do
+ member = build(:delivery_zone_member, delivery_zone: zone, member_type: 'postal_code',
+ country: germany, postal_code_prefix: '10', postal_code_from: '10115', postal_code_to: '10999')
+
+ expect(member).not_to be_valid
+ expect(member.errors[:postal_code_prefix]).to be_present
+ end
+
+ it 'requires a prefix or a complete range' do
+ member = build(:delivery_zone_member, delivery_zone: zone, member_type: 'postal_code',
+ country: germany, postal_code_from: '10115')
+
+ expect(member).not_to be_valid
+ expect(member.errors[:base]).to be_present
+ end
+
+ it 'rejects ranges for countries outside the numeric-postal allowlist' do
+ member = build(:delivery_zone_member, delivery_zone: zone, member_type: 'postal_code',
+ country: uk, postal_code_from: '10115', postal_code_to: '10999')
+
+ expect(member).not_to be_valid
+ expect(member.errors[:base]).to be_present
+ end
+
+ it 'allows prefixes for any country' do
+ member = build(:delivery_zone_member, delivery_zone: zone, member_type: 'postal_code',
+ country: uk, postal_code_prefix: 'SW1')
+
+ expect(member).to be_valid
+ end
+
+ it 'rejects an inverted range' do
+ member = build(:delivery_zone_member, delivery_zone: zone, member_type: 'postal_code',
+ country: germany, postal_code_from: '10999', postal_code_to: '10115')
+
+ expect(member).not_to be_valid
+ expect(member.errors[:postal_code_to]).to be_present
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/delivery_zone_spec.rb b/spree/core/spec/models/spree/delivery_zone_spec.rb
new file mode 100644
index 0000000000..7f57382872
--- /dev/null
+++ b/spree/core/spec/models/spree/delivery_zone_spec.rb
@@ -0,0 +1,24 @@
+require 'spec_helper'
+
+describe Spree::DeliveryZone, type: :model do
+ describe '#include?' do
+ let(:germany) { create(:country, iso: 'DE', iso3: 'DEU', name: 'Germany', iso_name: 'GERMANY') }
+ let(:zone) { create(:delivery_zone_with_country, country: germany) }
+
+ it 'is true when any member matches the address' do
+ expect(zone.include?(build(:address, country: germany))).to be(true)
+ end
+
+ it 'is false when no member matches' do
+ expect(zone.include?(build(:address, country: create(:country)))).to be(false)
+ end
+
+ it 'is false for a nil address' do
+ expect(zone.include?(nil)).to be(false)
+ end
+
+ it 'is false for a zone without members' do
+ expect(create(:delivery_zone).include?(build(:address, country: germany))).to be(false)
+ end
+ end
+end