该技能面向把 Spree 5.x 升级到 6.0 的场景，也用于修复升级后无法启动或结账失败的代码。升级流程为：前置条件 → gem 调整 → 迁移 → 回填 → 代码修复 → 行为审查，其中代码修复和行为审查耗时最多。
前置条件：先完整升级到 5.6.x；Rails 8.1、Ruby ≥ 3.2；备份数据库并在副本上演练；移除 spree_admin、spree_storefront，按需加入 spree_dashboard；所有 spree_* 扩展需有 6.0 兼容版本；Action Text/Cable 需手动 require；先放宽富文本白名单；把员工角色重建为数据（权限键为 read_<resource> / write_<resource>）；删除 PermissionSets 初始化器；处理 Devise 迁移问题（如 CONFIRM_NO_PEPPER=true）；启用 Active Record 加密并先以 support_unencrypted_data 兼容明文；重新铸造管理员工的 API 密钥。
运行方式：CLI 参考 spree upgrade --plan、spree upgrade --step <id>；经典 Rails 应用用 bundle update、bundle exec rake spree:install:migrations && bin/rails db:migrate、DRY_RUN=1 bundle exec rake spree:upgrade。生产环境按 db:migrate 后发布阶段运行 spree:upgrade，需设维护窗口。
升级清单共 39 步，涵盖元数据合并、媒体类名与图片迁移、移除 master variant、taxon 拆分、用户迁移、富文本列迁移、shipping 转 delivery、调整项转 TaxLine/Discount/Fee、退货与采购迁移、库存重算等；全部幂等，以 --plan 输出为准。
代码修复用 grep 定位状态机、PermittedAttributes、PermissionSets、Spree::Adjustment、.master、finalize!、ReturnAuthorization 等；已弃用但可用的名称会在 6.1 移除。行为审查覆盖购物车只读、line_item.order 可能为 nil、状态派生、金额冻结、赠品不计门槛、取消不可恢复、Spree::Store.default 可为 nil、belongs_to 默认必填、店铺 API 权限、国家/州为参考数据、库存在发货时扣减、后台任务等变化。资料未提供价格、平台、效果等信息。