用途:Spree 6 通过 provider 契约连接外部系统,接入点包括税费计算、配送运费、履约/面单/WMS、支付、搜索、卖家打款、数字资产交付、认证策略与集成凭据。核心流程无需 fork 或装饰。
主要能力:各契约均有基类、注册表和选择位置。税费继承 Spree::TaxProvider::Base,写入 Spree::TaxLine;运费继承 Spree::DeliveryRateProvider::Base,返回 Estimate 数组;履约继承 Spree::FulfillmentProvider::Base,实现面单购买、履约创建与取消、追踪 URL;支付继承 Spree::PaymentMethod 并配套 PaymentSession STI 子类;搜索继承 Spree::SearchProvider::Base,实现检索与索引方法;打款继承 Spree::PayoutProvider::Base,实现 transfer!、pay!、reverse! 与入驻流程;数字资产继承 Spree::DigitalAssetProvider::Base,实现 deliver。SSO 支持核心内置的 OidcStrategy.configure,或继承 BaseStrategy 处理非 OIDC JWT。凭据使用 Spree::Integration 定义,按店铺存储,不进 ENV。
使用方式:在 config.after_initialize 中注册(如 Spree.integrations << 'MyApp::AcmeIntegration'、Spree.delivery_rate_providers << MyApp::AcmeRates、Spree.fulfillment_providers << MyApp::AcmeFulfillment、Spree.payment_methods << MyApp::AcmeGateway),search_provider 可直接赋值。
限制与注意:必须在 after_initialize 内注册,否则会被静默清除;注册表兼作校验白名单。运费与履约 provider 不得中断结账,需捕获供应商错误并降级;税费 provider 失败即关闭,无法生成完整 TaxLine 时应抛错。provider 必须无状态、以无参构造。入站 webhook 需自行校验签名并保持幂等,且必须在无密钥时抛错。事务邮件不是 provider,仅通过 SMTP_* 环境变量配置,使用 STARTTLS 587 端口。ERP/PIM/DAM 等仍属路线图,接口可能变化。