用途:当用户询问 Spree 领域模型之间的关联时使用,帮助快速定位模型关系;字段级文档位于已安装的 @spree/docs 包的 node_modules/@spree/docs/dist/developer/core-concepts/ 目录。
主要关系:目录到购物车链路为 Product → Variant → LineItem → Order;Product 为品牌级实体,Variant 为可售 SKU(每个 Product 至少一个),LineItem 将 Variant 关联到 Order 并冻结加购时的数量与价格,Order 同时表示进行中的购物车与结账后的交易,用 state 列区分(如 Spree::Order.where(state: 'cart')、where(state: 'complete'));注意 Order.complete 作用域是 where.not(completed_at: nil),不等同于 state 为 complete。Variant 通过 StockItem(每个 Variant 每个 StockLocation 一条)与 StockMovement 关联库存。
变体:master 变体为遗留概念(is_master: true),default_variant 是计算得出,5.5 中二者都不是数据库列,不要查询或迁移 default_variant_id;6.0 计划加入该外键但尚未开始实现。一般用 product.variants 获取非 master 可售变体。
多店铺/多渠道:自 Spree 5.5 起 Store → Channel → ProductPublication → Product;Channel 是店铺内的销售面(如线上、POS、亚马逊等),ProductPublication 决定哪些 Product 在哪些 Channel 可见并支持发布窗口;Order 含 channel_id。Store API 按请求头 X-Spree-Channel 解析渠道,Admin API 不消费该头。
Market:Market 拥有多个国家,含 currency、default_locale 列,Order 属于 Market,用于决定货币与税务规则;Market 可选,无 Market 时回退到店铺默认值。
结账相关:Order 关联 Payment/PaymentMethod、Shipment/ShippingRate/ShippingMethod、Address;Payment 与 Shipment 各自有状态机。Adjustment 为多态,挂载到 Order、LineItem 或 Shipment,可用 order.adjustments.tax 等作用域按来源类型过滤。
其他:v3 API 模型使用基于 Sqids 计算的预固定 ID(无数据库列),如 product.prefixed_id、order.prefixed_id。请使用 Spree.user_class 而非直接引用 Spree::User。5.5 中 state 与 status 列名混用,需按模型实际列名书写代码。跨请求上下文用 Spree::Current.store / currency / locale / channel / market,而非传参。
限制与延伸:分类表无对应电商框架分类,暂未提供更细的字段说明与版本兼容细节;扩展模型请参考 spree-decorators 技能,新增资源参考 spree-resource 技能。