spree_core 5.6.0 → 6.0.0.beta1

data/app/models/spree/store.rb

@@ -8,14 +8,16 @@ module Spree
 
     include FriendlyId
     include Spree::TranslatableResource
-    include Spree::Metafields
+    include Spree::HasCustomFields
     include Spree::Metadata
     include Spree::Stores::Setup
     include Spree::Stores::Markets
     include Spree::Stores::Channels
+    include Spree::StoreDataSources
     include Spree::Security::Stores if defined?(Spree::Security::Stores)
     include Spree::UserManagement
     include Spree::OrderRouting::HasStrategyPreference
+    include Spree::CaptureMethod
 
     #
     # Magic methods
@@ -45,6 +47,44 @@ module Spree
     preference :unit_system, :string, default: 'imperial'
     # email preferences
     preference :send_consumer_transactional_emails, :boolean, default: true
+    # Sellers are a different audience from shoppers, with their own reasons to
+    # be silenced — a marketplace fronting its own seller comms turns these off
+    # without also stopping customer receipts.
+    preference :send_seller_transactional_emails, :boolean, default: true
+    # Marketplace preferences
+    #
+    # VAT on the commission itself, as a fraction, when neither the rate nor
+    # the tax provider names one. Zero by default: a marketplace outside the EU
+    # charges no tax on its fee, and inventing one would overcharge sellers.
+    preference :default_commission_tax_rate, :decimal, default: 0
+    # Admit a seller the moment they finish the checklist, without waiting for
+    # anyone to look at them. Off by default: a marketplace decides who trades
+    # under its name, and letting that happen by omission is the wrong
+    # default for the operator who never thought about it.
+    preference :auto_approve_sellers, :boolean, default: false
+    # Put a seller's product on sale the moment they submit it. Off for the
+    # same reason as auto_approve_sellers: what the marketplace lists is what
+    # it vouches for.
+    preference :auto_approve_seller_products, :boolean, default: false
+    # Who pays this store's sellers. Blank means core's record-only provider,
+    # so a marketplace that has connected nothing still keeps a correct ledger
+    # and settles by hand.
+    preference :payout_provider, :string, default: nil
+    # Refused at write time rather than silently falling back at read time: an
+    # operator who mistypes a provider would otherwise get a bookkeeping-only
+    # ledger and no indication anywhere that their choice was ignored.
+    validates :preferred_payout_provider,
+              inclusion: { in: ->(_store) { Spree.payout_providers.map(&:to_s) } }, allow_blank: true
+    # How often sellers are settled, unless one carries its own schedule.
+    # Monthly by default because it is the interval that needs least of an
+    # operator paying by hand, which is what the built-in provider expects.
+    preference :default_payouts_schedule_interval, :string, default: 'monthly'
+    validates :preferred_default_payouts_schedule_interval,
+              inclusion: { in: Spree::Seller::PAYOUT_INTERVALS }, allow_blank: true
+    # What a seller's balance must reach before a settlement is worth sending;
+    # below it the balance carries to the next period. Zero pays whatever is
+    # owed, which is right for a provider that moves money for free.
+    preference :default_minimum_payout_amount, :decimal, default: 0
     # Checkout preferences
     # Store-level fallback for the channel-owned `guest_checkout` preference
     # (see Spree::Channel::Gating). Retained so existing accessors keep working.
@@ -56,8 +96,49 @@ module Spree
     preference :storefront_url, :string
     preference :special_instructions_enabled, :boolean, default: false
     preference :stock_reservation_ttl_minutes, :integer, default: 10
+    # Store-wide default for when a customer is charged rather than only
+    # authorized. A payment method's own capture_method wins when set.
+    # See Spree::CaptureMethod.
+    preference :capture_method, :string, default: Spree::CaptureMethod::DEFAULT_CAPTURE_METHOD
+    preference :stock_reservations_enabled, :boolean, default: true
+    # Which address a sale's tax is computed against. Stores selling where tax
+    # follows the destination keep this on; billing-address jurisdictions turn
+    # it off.
+    preference :tax_using_ship_address, :boolean, default: true
+    # Where prices and stock levels come from. 'internal' is Spree's own
+    # catalog and stock records; a connector gem registers others.
+    preference :pricing_provider, :string, default: 'internal'
+    preference :inventory_provider, :string, default: 'internal'
+    # What happens when an external source cannot be reached.
+    preference :pricing_provider_failure_policy, :string,
+               default: Spree::ProviderFailurePolicy::DEFAULT_PRICING_POLICY
+    preference :inventory_provider_failure_policy, :string,
+               default: Spree::ProviderFailurePolicy::DEFAULT_INVENTORY_POLICY
+    # Catalog preferences
+    preference :track_inventory_levels, :boolean, default: true
+    # On-hand quantity at or below which a tracked variant counts as running
+    # low on the home screen. 0 turns the warning off.
+    preference :low_stock_threshold, :integer, default: 5
+    # How long a cart must sit untouched before reporting counts it abandoned.
+    # Deliberately shorter than the cart-expiry reaper's windows: that job
+    # decides when a cart is deleted, this decides when a merchant should
+    # chase it.
+    preference :abandoned_cart_after_hours, :integer, default: 24
+    preference :show_products_without_price, :boolean, default: false
+    preference :disable_sku_validation, :boolean, default: false
+    # Records price changes so the storefront can show the lowest price of the
+    # last 30 days, as the EU Omnibus Directive requires.
+    preference :track_price_history, :boolean, default: true
+    # How long recorded prices are kept. 30 days is what the Omnibus Directive
+    # asks a shop to be able to show; a longer window is a merchant's own
+    # evidentiary choice.
+    preference :price_history_retention_days, :integer, default: 30
     # Address preferences
     preference :company_field_enabled, :boolean, default: false
+    # Showing the company field and requiring it are separate decisions: a
+    # B2B store collects it from everyone, a mixed store only offers it.
+    preference :address_requires_company, :boolean, default: false
+    preference :address_requires_phone, :boolean, default: false
     # digital assets preferences
     preference :limit_digital_download_count, :boolean, default: true
     preference :limit_digital_download_days, :boolean, default: true
@@ -68,50 +149,144 @@ module Spree
     # decides which StockLocation fulfills which items.
     preference :order_routing_strategy, :string, default: 'Spree::OrderRouting::Strategy::Rules'
 
+    # Document numbering (docs/plans/6.0-document-numbers.md). The format
+    # applies to every numbered document; prefix, suffix and starting value
+    # are order-only — other document types keep their code-level prefixes.
+    # Changes affect future numbers only; existing numbers are permanent.
+    preference :document_number_format, :string, default: 'sequential'
+    preference :order_number_prefix, :string, default: 'R'
+    preference :order_number_suffix, :string, default: ''
+    preference :order_number_sequence_start, :integer, default: 1001
+
     #
     # Associations
     #
-    has_many :carts, -> { incomplete }, class_name: 'Spree::Order', inverse_of: :store
-    has_many :checkouts, -> { incomplete }, class_name: 'Spree::Order', inverse_of: :store
+    has_many :carts, class_name: 'Spree::Cart', inverse_of: :store, dependent: :destroy
     has_many :orders, class_name: 'Spree::Order'
+    has_many :order_groups, class_name: 'Spree::OrderGroup'
+    has_many :customers, through: :orders, source: :customer, class_name: "::#{Spree.customer_class}"
+    has_many :saved_reports, class_name: 'Spree::SavedReport', dependent: :destroy
     has_many :line_items, through: :orders, class_name: 'Spree::LineItem'
     has_many :digital_links, through: :line_items, class_name: 'Spree::DigitalLink'
-    has_many :shipments, through: :orders, class_name: 'Spree::Shipment'
+    has_many :fulfillments, through: :orders, class_name: 'Spree::Fulfillment'
+    has_many :shipments, through: :orders, class_name: 'Spree::Fulfillment', source: :fulfillments, deprecated: true
     has_many :payments, through: :orders, class_name: 'Spree::Payment'
-    has_many :return_authorizations, through: :orders, class_name: 'Spree::ReturnAuthorization'
-    # has_many :reimbursements, through: :orders, class_name: 'Spree::Reimbursement' FIXME: we should fetch this via Customer Return
+    has_many :returns, class_name: 'Spree::Return', inverse_of: :store
+    has_many :shipping_labels, class_name: 'Spree::ShippingLabel', inverse_of: :store
+    has_many :deliveries, class_name: 'Spree::Delivery', inverse_of: :store
+    has_many :exchanges, class_name: 'Spree::Exchange', inverse_of: :store
+    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
+    has_many :order_cancellation_reasons, class_name: 'Spree::OrderCancellationReason', 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.
     has_many :payment_methods, class_name: 'Spree::PaymentMethod', dependent: :nullify
 
     has_many :products, class_name: 'Spree::Product', dependent: :nullify
+    # The media library: every file uploaded to this store, whether or not it
+    # has been placed on a product yet.
+    has_many :media, class_name: 'Spree::Media', dependent: :destroy_async
     has_many :product_publications, through: :channels, source: :publications, class_name: 'Spree::ProductPublication'
-    has_many :variants, through: :products, class_name: 'Spree::Variant', source: :variants_including_master
-    has_many :stock_items, through: :variants, class_name: 'Spree::StockItem'
+    has_many :variants, through: :products, class_name: 'Spree::Variant', source: :variants
+    has_many :stock_levels, through: :variants, class_name: 'Spree::StockLevel'
     has_many :prices, through: :variants, class_name: 'Spree::Price'
     has_many :price_lists, class_name: 'Spree::PriceList', inverse_of: :store
-    has_many :inventory_units, through: :variants, class_name: 'Spree::InventoryUnit'
+    has_many :fulfillment_items, through: :variants, class_name: 'Spree::FulfillmentItem'
+    has_many :inventory_units, through: :variants, class_name: 'Spree::FulfillmentItem', source: :fulfillment_items, deprecated: true
     has_many :option_value_variants, through: :variants, class_name: 'Spree::OptionValueVariant'
-    has_many :customer_returns, class_name: 'Spree::CustomerReturn', inverse_of: :store
 
     has_many :store_credits, class_name: 'Spree::StoreCredit'
     has_many :store_credit_events, through: :store_credits, class_name: 'Spree::StoreCreditEvent'
 
-    has_many :taxonomies, class_name: 'Spree::Taxonomy'
-    has_many :taxons, class_name: 'Spree::Taxon'
+    # @deprecated Taxonomy is data-only in 6.0 and dropped in 6.1; use #categories.
+    has_many :taxonomies, class_name: 'Spree::Taxonomy', deprecated: true
     has_many :categories, class_name: 'Spree::Category'
+    has_many :collections, class_name: 'Spree::Collection', dependent: :destroy_async
+
+    # restrict, not destroy — a type in use is refused deletion, so wiping a
+    # store's types out from under its products would contradict that guard.
+    has_many :product_types, class_name: 'Spree::ProductType', dependent: :restrict_with_error
+
+    # The store's custom-field schema. Destroying a definition takes its values
+    # with it, which is a large fan-out on a busy store, so it runs in a job.
+    has_many :custom_field_definitions, class_name: 'Spree::CustomFieldDefinition',
+             inverse_of: :store, dependent: :destroy_async
+
+    # @deprecated Use #categories; removed in 6.1.
+    def taxons
+      Spree::Deprecation.warn('Spree::Store#taxons is deprecated and will be removed in Spree 6.1. Use #categories instead.')
+      categories
+    end
+
+    def taxons=(value)
+      Spree::Deprecation.warn('Spree::Store#taxons= is deprecated and will be removed in Spree 6.1. Use #categories= instead.')
+      self.categories = value
+    end
+
+    # @deprecated Use {#stock_levels}; removed in 6.1.
+    def stock_items
+      Spree::Deprecation.warn('Spree::Store#stock_items is deprecated and will be removed in Spree 6.1. Use #stock_levels instead.')
+      stock_levels
+    end
 
+    has_many :delivery_zones, class_name: 'Spree::DeliveryZone', dependent: :destroy
+    has_many :delivery_methods, class_name: 'Spree::DeliveryMethod', dependent: :nullify
+    has_many :delivery_profiles, class_name: 'Spree::DeliveryProfile', dependent: :destroy
+    has_many :delivery_origin_groups, through: :delivery_profiles, class_name: 'Spree::DeliveryOriginGroup'
+
+    # @return [Spree::DeliveryProfile, nil]
+    def default_delivery_profile
+      Spree::DeliveryProfile.default_for(self)
+    end
+    has_many :stock_locations, class_name: 'Spree::StockLocation', dependent: :nullify
+
+    # The store's packaging vocabulary. The default row is the box it usually
+    # ships in — the tare and dimensions every parcel quote is built on, read
+    # through an association so it is loaded once per store rather than once
+    # per package quoted.
+    has_many :package_types, class_name: 'Spree::PackageType', dependent: :destroy, inverse_of: :store
+    # The marketplace's own default box. A seller's default is read through
+    # the seller (docs/plans/6.0-seller-package-types.md) — without the
+    # `seller_id` filter this would answer with whichever owner's row loaded
+    # first.
+    has_one :default_package_type, -> { where(default: true, seller_id: nil) },
+            class_name: 'Spree::PackageType', inverse_of: :store
+    # Inventory operations (docs/plans/6.0-inventory-operations.md). Transfers
+    # carry their own store rather than borrowing the destination warehouse's,
+    # so the admin endpoint has a scope to fetch through.
+    has_many :stock_transfers, class_name: 'Spree::StockTransfer', dependent: :destroy_async, inverse_of: :store
+    # Purchase orders are declared before suppliers, and both cascade in the
+    # same transaction: a supplier refuses to be destroyed while a purchase
+    # order names it (`restrict_with_error`), so tearing a store down has to
+    # reach the orders first. `destroy_async` on either side would break that
+    # ordering and leave the suppliers behind.
+    has_many :purchase_orders, class_name: 'Spree::PurchaseOrder', dependent: :destroy, inverse_of: :store
+    has_many :suppliers, class_name: 'Spree::Supplier', dependent: :destroy, inverse_of: :store
     has_many :promotions, class_name: 'Spree::Promotion', dependent: :nullify
 
+    has_many :tax_categories, class_name: 'Spree::TaxCategory', dependent: :destroy, inverse_of: :store
+    has_many :tax_rates, class_name: 'Spree::TaxRate', dependent: :destroy, inverse_of: :store
+
+    has_many :sellers, class_name: 'Spree::Seller', dependent: :destroy, inverse_of: :store
+    has_many :commission_rates, class_name: 'Spree::CommissionRate', dependent: :destroy, inverse_of: :store
+    # What this marketplace asks of a seller before it will let them trade.
+    has_many :seller_requirements, -> { order(:position, :id) }, class_name: 'Spree::SellerRequirement',
+                                                                dependent: :destroy, inverse_of: :store
+
     has_many :wishlists, class_name: 'Spree::Wishlist'
 
     has_many :data_feeds, class_name: 'Spree::DataFeed'
 
-    belongs_to :default_country, class_name: 'Spree::Country'
-    belongs_to :checkout_zone, class_name: 'Spree::Zone'
+    # Countries are reference data, so this is a plain writer over the stored
+    # code. Reading goes through Spree::Stores::Markets#default_country, which
+    # prefers the default market's country when the store has markets.
+    def default_country=(value)
+      self[:default_country_code] = value&.iso
+    end
 
-    has_many :reports, class_name: 'Spree::Report'
     has_many :exports, class_name: 'Spree::Export'
 
     has_many :integrations, class_name: 'Spree::Integration'
@@ -128,6 +303,10 @@ module Spree
 
     has_many :customer_groups, class_name: 'Spree::CustomerGroup', dependent: :destroy, inverse_of: :store
 
+    has_many :companies, class_name: 'Spree::Company', dependent: :destroy, inverse_of: :store
+    has_many :external_references, class_name: 'Spree::ExternalReference', dependent: :destroy, inverse_of: :store
+    has_many :catalogs, class_name: 'Spree::Catalog', dependent: :destroy, inverse_of: :store
+
     has_many :api_keys, class_name: 'Spree::ApiKey', dependent: :destroy
     has_many :allowed_origins, class_name: 'Spree::AllowedOrigin', dependent: :destroy
 
@@ -139,9 +318,30 @@ module Spree
     end
     validates :preferred_digital_asset_authorized_clicks, numericality: { only_integer: true, greater_than: 0 }
     validates :preferred_digital_asset_authorized_days, numericality: { only_integer: true, greater_than: 0 }
+    # Sized for starting a transfer, not for keeping the file reachable — the
+    # signed URL it governs is a bearer credential.
+    validates :preferred_digital_asset_link_expire_time,
+              numericality: { only_integer: true, greater_than: 0, less_than_or_equal_to: 1.hour.to_i }
     validates :preferred_stock_reservation_ttl_minutes, numericality: { only_integer: true, greater_than: 0 }
+    validates :preferred_low_stock_threshold, numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+    validates :preferred_abandoned_cart_after_hours, numericality: { only_integer: true, greater_than: 0 }
+    # A fraction, not a percentage: 0.21 is 21%. Bounded because the value is
+    # multiplied straight into what a seller is charged, so a negative would
+    # credit them and a figure above 1 would bill more tax than fee.
+    validates :preferred_default_commission_tax_rate,
+              numericality: { greater_than_or_equal_to: 0, less_than_or_equal_to: 1 }
     validates :preferred_storefront_access, inclusion: { in: Spree::Channel::Gating::STOREFRONT_ACCESS }
+    validates :preferred_document_number_format,
+              inclusion: { in: Spree::NumberGenerators::Registry::FORMATS.keys }
+    validates :preferred_order_number_sequence_start,
+              numericality: { only_integer: true, greater_than: 0 }
+    validates :preferred_order_number_prefix, :preferred_order_number_suffix,
+              length: { maximum: 10 },
+              format: { with: /\A[A-Z0-9#-]*\z/,
+                        message: :invalid_document_number_affix }
+    validates :preferred_capture_method, inclusion: { in: Spree::CaptureMethod::CAPTURE_METHODS }
     validate :preferred_storefront_url_is_an_origin
+    validate :order_number_sequence_start_unchanged_after_first_number, on: :update
     validates :mail_from_address, email: { allow_blank: false }
     validates :customer_support_email, email: { allow_blank: true }
     # FIXME: we should remove this condition in v5
@@ -159,12 +359,29 @@ module Spree
     has_one_attached :logo, service: Spree.public_storage_service_name
     has_one_attached :mailer_logo, service: Spree.public_storage_service_name
 
+    # First-run setup credential (docs/plans/6.0-store-context-and-first-run-setup.md):
+    # printed by the installer, only consulted by the setup endpoint while no
+    # admin user exists, cleared when setup completes. Plaintext at rest —
+    # same posture as invitation tokens, and only meaningful while the
+    # database holds nothing but seed data.
+    has_secure_token :setup_token
+
+    # Link that claims this installation: the dashboard's first-run setup
+    # screen with the store's token.
+    # @return [String, nil] nil when no token is outstanding
+    def setup_url
+      return if setup_token.blank?
+
+      "#{Spree::Stores::DashboardUrl.call(store: self)}/setup?token=#{setup_token}"
+    end
+
     #
     # Callbacks
     before_validation :set_default_code, on: :create
     before_validation :normalize_preferred_storefront_url
     before_save :ensure_default_exists_and_is_unique
     after_create :create_default_policies
+    after_create :create_default_delivery_profile
 
     #
     # Scopes
@@ -179,18 +396,9 @@ module Spree
       Spree::Current.store
     end
 
-    # @deprecated The or_initialize behavior will be removed in Spree 5.5.
+    # @return [Spree::Store, nil] the store flagged as default, if one exists
     def self.default
-      # workaround for Mobility bug with first_or_initialize
-      if where(default: true).any?
-        where(default: true).first
-      else
-        Spree::Deprecation.warn(
-          'Spree::Store.default returning a new unpersisted store when no default store exists is deprecated ' \
-          'and will be removed in Spree 6.0. Please ensure a default store is created before calling Store.default.'
-        )
-        new(default: true)
-      end
+      where(default: true).first
     end
 
     def self.available_locales
@@ -206,49 +414,71 @@ module Spree
       channels.default.first || channels.active.first
     end
 
-    # @deprecated Use Markets instead. Will be removed in Spree 5.5.
-    def checkout_zone
-      Spree::Deprecation.warn('Store#checkout_zone is deprecated and will be removed in Spree 5.5. Use Markets instead.')
-      super
-    end
-
-    # @deprecated Use Markets instead. Will be removed in Spree 5.5.
-    def checkout_zone=(zone)
-      Spree::Deprecation.warn('Store#checkout_zone= is deprecated and will be removed in Spree 5.5. Use Markets instead.')
-      super
-    end
-
-    # Virtual attribute — sets the country for the default market created on store creation.
-    # Not persisted on the store itself; only used by the after_create callback.
-    attr_reader :default_country_iso
+    # Sets the stored code and seeds the country for the default market created
+    # on store creation. Reading goes through Spree::Stores::Markets, which
+    # prefers the default market's country once the store has markets.
+    def default_country_code=(code)
+      return if code.blank?
 
-    def default_country_iso=(iso)
-      return if iso.blank?
+      country = Spree::Country.by_iso(code)
+      return if country.nil?
 
-      @default_country_iso = iso
+      self[:default_country_code] = country.iso
+      @default_country_for_market = country
+    end
 
-      country = Spree::Country.by_iso(iso)
+    # @deprecated Use +default_country_code=+. Removed in 6.1.
+    def default_country_iso=(code)
+      Spree::Deprecation.warn('Spree::Store#default_country_iso= is deprecated, use #default_country_code= instead')
+      self.default_country_code = code
+    end
 
-      unless country
-        iso_country = ::Country[iso]
-        return unless iso_country
+    def unique_name
+      @unique_name ||= "#{name} (#{code})"
+    end
 
-        country = Spree::Country.create!(
-          iso_name: iso_country.local_name&.upcase,
-          iso: iso_country.alpha2,
-          iso3: iso_country.alpha3,
-          name: iso_country.local_name,
-          numcode: iso_country.number,
-          states_required: Spree::Address::STATES_REQUIRED.include?(iso),
-          zipcode_required: !Spree::Address::NO_ZIPCODE_ISO_CODES.include?(iso)
-        )
+    # Who pays this store's sellers, ready to be asked.
+    #
+    # Who moves money to this store's sellers.
+    #
+    # Memoized per record, and cleared on reload — `reload` leaves plain
+    # instance variables alone, so without that a provider holding its own
+    # cache (Stripe's account lookups do) would answer from a snapshot taken
+    # arbitrarily long ago, and an operator changing the setting would not be
+    # picked up by a store object already in hand.
+    #
+    # @return [Spree::PayoutProvider::Base]
+    def payout_provider_instance
+      resolved = payout_provider_class
+      # Keyed by the class it was built from, so changing the setting on a
+      # store already in hand cannot keep answering with the old provider —
+      # which would route real money through whoever was configured before.
+      if @payout_provider_instance.nil? || @payout_provider_instance.class != resolved
+        @payout_provider_instance = resolved.new
       end
 
-      @default_country_for_market = country
+      @payout_provider_instance
     end
 
-    def unique_name
-      @unique_name ||= "#{name} (#{code})"
+    def reload(*)
+      @payout_provider_instance = nil
+      super
+    end
+
+    # The class alone, for the questions that are about the provider rather
+    # than about a movement — there is no need to build one to ask what it
+    # requires.
+    #
+    # @return [Class]
+    def payout_provider_class
+      configured = preferred_payout_provider.presence
+      # A name no longer in the registry — a typo, or a gem since removed —
+      # would otherwise raise inside a subscriber on every fulfillment and stop
+      # the ledger recording anything. The built-in provider keeps the books
+      # until an operator fixes the setting.
+      configured = nil unless Spree.payout_providers.any? { |provider| provider.to_s == configured }
+
+      (configured || Spree.default_payout_provider.to_s).constantize
     end
 
     def formatted_url
@@ -316,80 +546,133 @@ module Spree
       country.states.to_a
     end
 
-    # @deprecated Use {Spree::Zone.all} or {#countries_with_shipping_coverage} instead.
-    #   Will be removed in Spree 5.5.
-    def supported_shipping_zones
-      Spree::Deprecation.warn(
-        'Store#supported_shipping_zones is deprecated and will be removed in Spree 5.5. ' \
-        'Use Spree::Zone.all or Store#countries_with_shipping_coverage instead.'
-      )
-      zone = Spree::Zone.find_by(id: read_attribute(:checkout_zone_id))
-      if zone.present?
-        [zone]
-      else
-        Spree::Zone.includes(zone_members: :zoneable).all
-      end
-    end
-
-    # Returns countries covered by at least one shipping zone
-    # that has an active shipping method attached.
-    # Handles both country-type zones (direct membership) and
-    # state-type zones (country inferred from state).
+    # Returns countries covered by delivery methods. Methods without delivery
+    # zones are worldwide, so any such method means every country is covered;
+    # otherwise coverage is the union of the attached zones' country, state,
+    # and postal-code members.
     #
     # @return [ActiveRecord::Relation<Spree::Country>]
     def countries_with_shipping_coverage
-      zone_ids = Spree::Zone
-                 .joins(:shipping_methods)
-                 .select(:id)
+      return Spree::Country.all.sort_by(&:name) if Spree::DeliveryMethod.where(delivery_zone_id: nil).exists?
 
-      country_zone_country_ids = Spree::ZoneMember
-                                 .where(zone_id: zone_ids, zoneable_type: 'Spree::Country')
-                                 .select(:zoneable_id)
+      zone_ids = Spree::DeliveryMethod.where.not(delivery_zone_id: nil).select(:delivery_zone_id)
 
-      state_zone_country_ids = Spree::State
-                               .where(id: Spree::ZoneMember
-                                          .where(zone_id: zone_ids, zoneable_type: 'Spree::State')
-                                          .select(:zoneable_id))
-                               .select(:country_id)
+      # Every member carries its own country, including state members, so
+      # coverage no longer has to resolve a subdivision back to its country.
+      country_codes = Spree::DeliveryZoneMember.where(delivery_zone_id: zone_ids).
+                      where.not(country_code: nil).distinct.pluck(:country_code)
 
-      Spree::Country
-        .where(id: country_zone_country_ids)
-        .or(Spree::Country.where(id: state_zone_country_ids))
-        .order(:name)
+      country_codes.filter_map { |code| Spree::Country.by_iso(code) }.sort_by(&:name)
     end
 
-    # Returns the default stock location for the store or creates a new one if it doesn't exist
+    # The operator's own location that accepts returns, or nil when none does.
+    #
+    # First-party only: `stock_locations` includes every seller's warehouse on a
+    # marketplace, and the operator's goods must never be routed into one.
+    #
+    # Nil rather than a fallback, because the caller's fallback is not ours to
+    # guess: {Spree::Returns::Create} answers nil by sending goods back where
+    # they shipped from, which is a better destination than a location the
+    # merchant told us not to send returns to.
+    #
+    # @return [Spree::StockLocation, nil]
+    def returns_location
+      stock_locations.active.first_party.returns_enabled.order_default.first
+    end
+
+    # The location the address checklist asks the merchant to fill in: the one
+    # that takes returns, falling back to any active location of their own,
+    # since the address is also what carriers rate against.
+    #
+    # Ordered rather than two queries with a fallback — both columns are
+    # NOT NULL, so sorting on the flag puts a returns-enabled location first
+    # and answers the fallback in the same round trip.
+    #
+    # Deliberately not `default_stock_location`, which creates the row when it
+    # is missing: this is read on every dashboard render (the Getting Started
+    # checklist), and a read that writes would provision a location for every
+    # store that loaded the page.
+    #
+    # @return [Spree::StockLocation, nil]
+    def primary_location
+      stock_locations.active.first_party.order(returns_enabled: :desc, default: :desc, name: :asc).first
+    end
+
+    # The store's own default stock location, created if it does not exist yet.
+    #
+    # Scoped to this store's first-party locations on both counts: unscoped it
+    # answered with any store's default, and on a marketplace it would answer
+    # with a seller's — putting the operator's stock on someone else's shelf.
+    #
     # @return [Spree::StockLocation]
     def default_stock_location
       @default_stock_location ||= begin
-        stock_location_scope = Spree::StockLocation.where(default: true)
+        stock_location_scope = stock_locations.first_party.where(default: true)
         stock_location_scope.first || ActiveRecord::Base.connected_to(role: :writing) do
           stock_location_scope.create(default: true, name: Spree.t(:default_stock_location_name),
-                                      country: default_country)
+                                      country_code: default_country&.iso)
         end
       end
     end
 
-    def admin_users
-      Spree::Deprecation.warn('Store#admin_users is deprecated and will be removed in Spree 5.5. Please use Store#users instead.')
+    def metric_unit_system?
+      preferred_unit_system == 'metric'
+    end
 
-      users
+    # A store is where capture settings bottom out, so it resolves to its own
+    # preference. Payment methods layer their override on top of this.
+    #
+    # @return [String] one of Spree::CaptureMethod::CAPTURE_METHODS
+    def resolved_capture_method
+      preferred_capture_method.presence || Spree::CaptureMethod::DEFAULT_CAPTURE_METHOD
     end
 
-    def metric_unit_system?
-      preferred_unit_system == 'metric'
+    # @deprecated Use #preferred_capture_method; removed in 6.1.
+    def preferred_auto_capture
+      Spree::Deprecation.warn('Store#preferred_auto_capture is deprecated and will be removed in Spree 6.1. Use #preferred_capture_method instead.')
+      capture_at_checkout?
+    end
+
+    # @deprecated Use #preferred_capture_method=; removed in 6.1.
+    def preferred_auto_capture=(value)
+      Spree::Deprecation.warn('Store#preferred_auto_capture= is deprecated and will be removed in Spree 6.1. Use #preferred_capture_method= instead.')
+      # Turning it off only says "not at checkout" — it cannot distinguish
+      # dispatch from manual, so an existing on_dispatch choice is preserved.
+      self.preferred_capture_method = if value.to_b
+                                        'checkout'
+                                      elsif capture_at_checkout?
+                                        'manual'
+                                      else
+                                        preferred_capture_method
+                                      end
     end
 
-    def default_shipping_category
-      @default_shipping_category ||= ShippingCategory.find_or_create_by(name: 'Default')
+    # @deprecated Use #preferred_capture_method; removed in 6.1.
+    def preferred_auto_capture_on_dispatch
+      Spree::Deprecation.warn('Store#preferred_auto_capture_on_dispatch is deprecated and will be removed in Spree 6.1. Use #preferred_capture_method instead.')
+      capture_on_dispatch?
     end
 
-    def digital_shipping_category
-      @digital_shipping_category ||= ShippingCategory.find_or_create_by(name: 'Digital')
+    # @deprecated Use #preferred_capture_method=; removed in 6.1.
+    def preferred_auto_capture_on_dispatch=(value)
+      Spree::Deprecation.warn('Store#preferred_auto_capture_on_dispatch= is deprecated and will be removed in Spree 6.1. Use #preferred_capture_method= instead.')
+      self.preferred_capture_method = if value.to_b
+                                        'on_dispatch'
+                                      elsif capture_on_dispatch?
+                                        'manual'
+                                      else
+                                        preferred_capture_method
+                                      end
     end
 
     private
 
+    # Products without a profile fall back to this one, so it must exist
+    # from the store's first moment.
+    def create_default_delivery_profile
+      Spree::DeliveryProfiles::Shipping.create!(store: self, name: 'General', default: true)
+    end
+
     def create_default_policies
       Spree::Events.disable do
         [
@@ -424,8 +707,28 @@ module Spree
       false
     end
 
+    # The very first store keeps the well-known 'default' code (tooling and
+    # seeds reference it); every later store derives its code from the name,
+    # suffixed until unique — a literal 'default' fallback would collide with
+    # the unique index the moment a second store is created. Soft-deleted
+    # stores still occupy their code (the unique index has no deleted_at
+    # scope), so generation checks with_deleted.
     def set_default_code
-      self.code = 'default' if code.blank?
+      return if code.present?
+
+      self.code =
+        if Spree::Store.with_deleted.none?
+          'default'
+        else
+          base = name.to_s.parameterize.presence || 'store'
+          candidate = base
+          sequence = 2
+          while Spree::Store.with_deleted.exists?(code: candidate)
+            candidate = "#{base}-#{sequence}"
+            sequence += 1
+          end
+          candidate
+        end
     end
 
     # The storefront URL preference must always hold a canonical origin — it
@@ -448,5 +751,22 @@ module Spree
 
       errors.add(:preferred_storefront_url, :invalid)
     end
+
+    # The starting value only shapes a counter that does not exist yet — once
+    # the first number is issued the counter owns the value, so accepting a
+    # change here would persist a setting that can never apply again. The
+    # dashboard disables the field; this backs it for API clients.
+    def order_number_sequence_start_unchanged_after_first_number
+      return unless preferences_changed?
+
+      default = preference_default(:order_number_sequence_start)
+      old_value, new_value = changes['preferences'].map do |preferences_hash|
+        ((preferences_hash || {})[:order_number_sequence_start] || default).to_i
+      end
+      return if old_value == new_value
+      return unless Spree::NumberSequence.started?(store: self)
+
+      errors.add(:preferred_order_number_sequence_start, :locked_after_first_number)
+    end
   end
 end