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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
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.rbindex dfc37a6036..1f31d5139b 100644--- a/spree/core/app/models/spree/address.rb+++ b/spree/core/app/models/spree/address.rb@@ -86,6 +86,19 @@ module Spreealias_attribute :first_name, :firstnamealias_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.abbrdef country_iso=(value)diff --git a/spree/core/app/models/spree/delivery_zone.rb b/spree/core/app/models/spree/delivery_zone.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/models/spree/delivery_zone_member.rb b/spree/core/app/models/spree/delivery_zone_member.rbnew file mode 100644index 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+enddiff --git a/spree/core/db/migrate/20260728000002_create_spree_delivery_zones.rb b/spree/core/db/migrate/20260728000002_create_spree_delivery_zones.rbnew file mode 100644index 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+enddiff --git a/spree/core/lib/spree/testing_support/factories/delivery_zone_factory.rb b/spree/core/lib/spree/testing_support/factories/delivery_zone_factory.rbnew file mode 100644index 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+enddiff --git a/spree/core/spec/models/spree/address_spec.rb b/spree/core/spec/models/spree/address_spec.rbindex 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 doendend+ 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' dolet(: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.rbnew file mode 100644index 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+enddiff --git a/spree/core/spec/models/spree/delivery_zone_spec.rb b/spree/core/spec/models/spree/delivery_zone_spec.rbnew file mode 100644index 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