Spree 6.1 产品市场可用性设计以例外行实现地区级隐藏的实战方案【免费下载链接】spreeOpen Source eCommerce Platform for B2B, Marketplace, and Enterprise. REST API, TypeScript SDK, and production-ready Next.js storefront. Self-host it. Own your stack. No vendor lock-in. Zero platform fees.项目地址: https://gitcode.com/GitHub_Trending/sp/spree本文基于 docs/plans/6.1-product-market-availability.md 展开结合当前仓库中已落地的 Channel 发布、市场解析、目录上下文等源码完整讲解 Spree 即将推出的产品级市场可用性轴Territory Exclusions它解决什么问题、为何采用NULL全部 例外行的存储模型、如何与现有发布机制做交集组合、以及它如何覆盖从浏览到结算的完整链路。状态说明该文档目前处于Draft 草稿阶段设计定稿于 2026-09-07尚未进入实现目标是 Spree 6.1且为纯增量改动一个可空列 异常关联行。文章中的代码示例来自设计计划现有仓库源码则用于佐证设计所依赖的既有机制。一、背景与问题定义为什么需要产品级地区排除一个门店通常把同一产品线卖到多个市场但现实中往往会有少数产品在特定地区不能卖——原因可能是独家分销协议exclusive distribution agreements、授权许可licensing或法规限制regulation。例如某品牌产品在欧洲由当地经销商独家代理因此在欧洲市场必须隐藏或某产品只在澳大利亚和新西兰获得销售许可。在现有 Spree 中唯一的表达方式是为每个地区单独建一个 Channel——通过为不同地区配置不同的渠道发布来达到这两个产品在那个渠道看不到的效果。但这种方式重复了整个发布表面duplicates surfaces为了隐藏两款产品商家必须为每个地区复制整套渠道配置维护成本极高且语义混乱。该计划引入一个产品级市场可用性轴product-level market availability axis在产品上直接声明这个产品在哪些市场可用/不可用与渠道发布机制做交集组合。核心设计原则Channel 管表面Market 管领土Catalog 管买家文档明确重申了 Spree 的核心教义本次设计刻意不越界Channel 回答 surface在哪儿卖——对应已上线的渠道发布ProductPublicationMarket 回答 territory买家在哪个地区——本计划要补上的领土答案Catalog 回答 buyer谁能买——B2B 场景下目录/商品池解决买家可见哪些商品见 Products::ForContext 服务。因此本次设计不是市场目录market catalog——2026-08-28 的 decisions 中关于市场目录之门已关闭的决定保持不变。二、关键决策五个不可偏离的设计定论该计划在 2026-09-07 的交互式评审中定下了五个核心决策任何实现都不得偏离。1. 仅存例外Exceptions-only storage零回填zero backfill存储模型是本次设计的灵魂spree_products.market_availability为可空字符串列NULL 即所有市场每个已有产品在迁移时天然正确——什么都不用写受限产品翻转模式all_except或only并且只为点名市场named markets写入关联行。举例100 个产品 × 20 个市场 × 每个产品只排除 2 个市场全部表达只需要100 × 2 200 行每个产品 2 个例外行而非 100 × 20 的笛卡尔积。文档原话是100-products × 20-markets × 2-exceptions 的场景只需 3 行即该产品 2 行关联 1 行模式标记。新市场无需任何操作all_except模式下新市场自动包含only模式下新市场自动排除——正确性由构造保证correct by construction。关于默认值的说明项目有字符串列上不设默认值的规则该规则针对的是工作流状态类字段此处NULL-as-all是刻意的 fallthrough读取时按market_availability || all理解。2. 完全隐藏而非可看不可买警告被排除的市场永远看不到该产品——不提供您所在市场不可购买的商品详情页。原因很直白一个显示not available in your market的 PDP恰恰是在向拥有该地区独家权益的分销商广告这款产品。行业里唯一把 Channel 和 Market 作为同一产品上两个轴来运行的平台同样选择了完全隐藏redirect/null不存在可见但不可售状态。可见但被阻止购买的展示模式被记录为可能的后续补充但不是 v1。3. 组合Composition而非第二套可见性机制可用性 published(channel) AND available(market)两者都按请求实时求值availability published(channel) ∧ available(market)读取时基于Spree::Current.channel/Spree::Current.market逐请求计算不派生、不落库任何有效可见性标志——因此不存在数据不同步的问题。商家理解成本的处理方式与双轴平台一致产品页上一张 Availability 卡片同时展示渠道发布与市场可用性二者默认都是everywhere——任何一个轴在被刻意收窄之前都不存在。4. 结算时对市场变更重新校验超越所有先例没有任何平台在结算环节强制领土限制它们的限制在浏览上下文就消解了——但 Spree 的 market 可能通过地址address在购物车中途变化。因此Carts::Complete以及地址驱动的市场变更路径会基于新市场重新校验所有 line items对不可用商品给出明确的code: not_available_in_market移除/错误码已完成的订单不受影响history is history。文档明确称之为对每一个先例的正确性改进。5. 拒绝列表一等公民Deny-list first-classall_except卖出全球、减去个别领土是主模式——这正是独家分销的形态只有一个平台在 UX 上提供、且没有任何平台原生建模only仅限 AUNZ这类许可形态复用同一套关联行。三、设计细节从数据模型到 Ruby 实现3.1 表结构与模型草案# spree_products.market_availability string, nullable (NULL all) # spree_product_market_availabilities: # product_id bigint, null: false # market_id bigint, null: false # unique index (product_id, market_id); partial index on # spree_products.market_availability WHERE NOT NULL (restricted set is tiny) class Spree::Product MARKET_AVAILABILITY_MODES %w[all_except only].freeze # nil all has_many :market_availability_entries, class_name: Spree::ProductMarketAvailability, dependent: :destroy has_many :restricted_markets, through: :market_availability_entries, source: :market def available_in_market?(market) case market_availability when nil then true when all_except then !restricted_market_ids.include?(market.id) when only then restricted_market_ids.include?(market.id) end end end要点拆解唯一索引(product_id, market_id)保证每个产品对每个市场最多一条例外记录部分索引partial index只在market_availability IS NOT NULL的行上建索引——受限产品集通常极小避免为全表浪费索引空间模式取值被冻结为%w[all_except only]nil 表示全部可用。3.2 现有市场的形态以Spree::Market佐证仓库中 Market 模型 已定义了市场的基本形态belongs_to :store、has_many :market_countries通过国家码引用国家注册表、acts_as_paranoid与acts_as_list排序并带return_window_days、withdrawal_period_days等偏好。本计划新增的Spree::ProductMarketAvailability关联行将product_id指向产品、market_id指向这里的Spree::Market构成产品↔市场的例外关系表。3.3 读取路径一个 scope 贯穿所有表面设计定义了一个核心 scope——Product.available_in_market(market)它被应用在与渠道发布过滤相同的基座上覆盖所有读取表面表面行为商店产品列表store products listing过滤掉不可用产品Products::ForContext在同一基座中组合搜索索引/过滤搜索 provider 索引例外数据使数据库与 Meilisearch provider 过滤行为一致商品集合collections同样过滤sitemap / feeds同样过滤被排除市场中的商品详情页show返回 not foundstorefront 自行决定重定向还是 404API 在该市场上下文中返回 404SQL 成本可控IS NULL短路覆盖几乎所有行绝大多数产品未受限EXISTS只触碰被标记的产品。现有基座佐证Products::ForContext与渠道发布设计中的同一基座在当前仓库中已有清晰对应。查看 Products::ForContext 服务def call(store:, channel:, customer: nil, company: nil, base: nil) base || store.products.for_channel(channel) # 根据公司/客户组/渠道默认目录解析 catalogs # 再用 CatalogProduct 限定 base 的 product_id 集合 ... success(base.where( id: Spree::CatalogProduct.where(catalog_id: catalog_ids).select(:product_id) )) end它的基座正是store.products.for_channel(channel)——即渠道发布过滤所在层。市场可用性 scope 的设计意图就是叠加在这个 for_channel 基座之上形成published(channel) ∧ available(market)的交集而不是另起一套独立可见性机制。渠道发布的现有形态佐证ProductPublication 模型 展示了发布如何被建模belongs_to :productbelongs_to :channel唯一性校验(product_id, channel_id)并用published_at/unpublished_at时间窗控制客户可见性scope :published, lambda { where(published_at IS NULL OR published_at ?, Time.current) .where(unpublished_at IS NULL OR unpublished_at ?, Time.current) }这正是published(channel)一轴在仓库中的现成实现——市场可用性将作为第二个轴与它做逐请求的交集运算。逐请求上下文佐证Spree::Current设计声明两个轴都基于Spree::Current.channel/Spree::Current.market逐请求求值。仓库中的 Current 模型 已经以ActiveSupport::CurrentAttributes线程安全地维护这两个上下文并带有合理的回退链def channel super || (self.channel store.default_channel) end def market super || store.default_market endmarket回退到 store 默认市场——这意味着无市场上下文的访客guest / 未解析到市场天然视为全部可用与设计中guest/no-market context available的测试预期一致。3.4 购物车/结算路径环节行为Carts::AddItem/UpsertItems校验 variant 所属产品对当前购物车 market 的可用性Carts::Complete重新校验market 可能已通过地址改变错误码not_available_in_market已完成订单不受影响历史即历史仓库的 spree/core/app/services/spree/carts 目录下已有check_availability.rb、remove_out_of_stock_items.rb等服务展示了在购物车写入/完成路径中做可用性校验的既有模式——市场可用性校验将作为新的校验步骤接入同一批服务。3.5 管理端Admin产品页的Availability 卡片新增 Markets 区模式下拉 通过标准 combobox 做市场多选紧挨现有渠道发布区三个新属性模式 例外市场列表走产品既有写入路径批量编辑spreadsheet editor留待后续按需支持。3.6 序列化器SerializersAdmin API产品序列化器暴露模式mode 市场列表Store API被排除市场中直接不返回该产品——不泄露任何标志字段。四、迁移路径三阶段纯增量Schema 模型 scope 规格测试覆盖模式语义、新市场行为、guest / 无市场上下文 可用读取路径接线列表、ForContext、搜索 provider、show、feeds 购物车/完成校验Admin API 仪表盘 Availability 卡片 SDK 类型。文档特别强调Nothing to migrate无需数据迁移——因为 NULL 全部存量产品天然正确。五、对当前工作的约束Constraints on Current Work这三个约束是后续任何相关开发都必须遵守的硬性规则可用性 发布 ∧ 市场可用性读取时求值——任何地方都不得反规范化出一个有效可见性标志永远不要把领土可用性建模为目录无论是否通过分配——目录回答的是买家问题2026-08-28 的市场目录关闭决定依然有效任何新的市场上下文读取表面feeds、推荐、API都必须应用该 scope——跳过它的表面会泄露受限产品。六、未决问题与参考Open Questions可见但不可购买visible-but-unpurchasable展示模式按产品 opt-in已推迟。目前不存在领土先例完全隐藏是安全默认。触发条件某个商家确实需要更柔和的模式。参考资料仓库内相邻计划 docs/plans/6.0-channel-markets.md——Channel↔Market 允许列表哪个 surface 服务哪些领土与本计划哪些产品在领土内可买正交Spree::Channel#allowed_markets空允许列表 全市场、serves_market?、default_market请求解析Spree::Api::V3::LocaleAndCurrency#set_market_from_country渠道不服务该市场时回退渠道默认市场订单完整性market must be served by the orders channel校验Store API 的/api/v3/store/markets只返回当前渠道允许的市场。决策日志 docs/plans/decisions.md2026-08-28市场目录关闭、2026-08-30每实体一问题、2026-09-07本次决策。七、总结该设计在 Spree 6.1 中的位置产品市场可用性轴补上了 Spree 多市场能力中缺失的领土维度存储单列可空模式 仅限例外行的关联表零回填、新市场免维护、SQL 成本恒定语义published(channel) ∧ available(market)逐请求交集与现有 ProductPublication 和 Products::ForContext 的基座自然组合不引入第二套可见性机制范围从列表、搜索、集合、feeds 到直接 URL 的完全隐藏并在购物车写入与完成路径上超越行业先例地强制市场变更后的再校验方向拒绝列表all_except为一等公民迎合独家分销的主流形态only覆盖许可场景边界领土≠买家市场目录的关闭决定不受影响。由于该功能处于设计定稿、尚未实现的状态感兴趣的开发者可以追踪上游 issueGitHub spree/spree#14613 / Linear V-3618或先阅读相邻已实现机制 6.0-channel-markets.md、ProductPublication 源码、ForContext 服务 与 Current 上下文模型即可完整理解该设计将要挂接的所有挂点。【免费下载链接】spreeOpen Source eCommerce Platform for B2B, Marketplace, and Enterprise. REST API, TypeScript SDK, and production-ready Next.js storefront. Self-host it. Own your stack. No vendor lock-in. Zero platform fees.项目地址: https://gitcode.com/GitHub_Trending/sp/spree创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考