适配模式

邮包险（SP）的适配模式决定了两件事：费用行何时写入购物车，以及结账按钮应调用哪个 SDK 方法。适配模式由客户经理（AM）在后台配置，前端代码只能读取、无法修改：

window.xcotton.sp.getMode() // 'cart' | 'checkout' | 'checkoutPlus'

三种模式共用同一套 init、syncCart 与 adapter。切换模式会改变费用行写入时机、首次同步的清理方式和结账按钮的调用逻辑；快速开始中的初始化与同步代码无需改动。

三种模式一览

对比维度	`cart`	`checkout`	`checkout+`
`getMode()` 返回值	`'cart'`	`'checkout'`	`'checkoutPlus'`
面板形态（后台配置）	带开关	带开关	不带开关，仅展示报价
拨动开关时	立即向购物车写入或移除费用行	仅记录顾客选择并刷新报价，不修改购物车	—
费用行写入时机	拨动开关时即时写入；首次同步与 SP 输入变化后的同步也按意愿对齐	点击结账时，由 `resolveSP()` 按开关意愿写入或移除	点击「含保护结账」调 `addSpFee()`；「不含保护结账」调 `declineSpFee()`
结账按钮调用逻辑	`await resolveSP()` 后再跳转	同左	两个按钮分别 `await addSpFee()` 与 `await declineSpFee()`
站点需额外编写代码	结账按钮调用 `resolveSP()`，失败阻断，忙时重试	结账按钮点击处理函数	渲染两个结账按钮并绑定各自的处理函数

在 cart 模式下，开关的费用写入是异步的。SDK 不拦截原生结账链接，也不会让浏览器导航自动等待写入完成。站点必须在结账边界调用 resolveSP()：意愿为开时它重新报价并对齐费用行，意愿为关时移除费用行或确认本来没有费用行（返回 added / removed / skipped），写入或移除失败时 reject。resolveSP() 不会排队等待开关写入；拨动开关的写入还在进行时，它会以 OPERATION_IN_PROGRESS 拒绝，此时等写入结束再重试。只有解析完成才跳转，其他拒绝留在当前页并展示错误。

仅等待站点自己的购物车请求、监听 onCartChange，或看到一次成功的补读，都不足以证明刚拨动的开关写入已经成功：失败后的补读也可能触发 onCartChange。结账前的 resolveSP()（或 checkout+ 的 addSpFee() / declineSpFee()）是能观察写入结果的公开入口。

首次同步购物车时

首次调用 syncCart(cartId)（或 init({ cartId })），以及切换到另一个购物车时，SDK 按模式执行入场处理。checkout 与 checkout+ 先清掉残留费用行，再更新报价；cart 在取得报价后按开关意愿对齐费用行：

cart 模式——开关意愿按以下规则确定：

车上有费用行和主商品：保留并打开开关。例外：本机保存过关闭意愿且缓存未过期时，按该意愿移除费用行。
车上没有费用行：按本机保存的开关意愿补行或不补。本机没有保存过意愿时，采用客户经理（AM）在后台配置的默认开关状态；本机有意愿但首次进入 /cart 页且车上有主商品时，也采用该默认值。

缓存写入后 2 小时过期。过期不会把意愿统一改回后台默认值，只影响第 1 条：缓存过期且车上有费用行与主商品时，开关固定取开。

在 cart 模式下，SDK 结合意愿和当前可保条件对齐费用行。开关意愿为开且当前购物车可保时，SDK 确保恰好一条数量为 1 的费用行；意愿为关或不满足可保条件时移除全部费用行。

checkout 与 checkout+ 模式——直接清理购物车中残留的费用行，不参考开关状态。在这两种模式下，费用行仅在顾客发起结账时写入。checkout+ 的开关意愿只是通用模型占位（初始固定为开），不读取、不写入、也不续期开关缓存。

完成首次整理后，syncCart(cart.id) 对比同步前后的购物车事实，只有主商品行、折扣码或车级属性等 SP 输入变化时才重新调和报价；仅追加或移除 PP 保障行不触发 SP 报价。换到另一个购物车会重新执行本模式的首次整理。在 cart 模式下，若购物车被清空或订单金额超出可保范围，SDK 会一并移除费用行；而在 checkout 和 checkout+ 模式下则仅更新报价，费用行留待结账时处理。

站点要渲染什么

SP 选择器用于发现站点容器，不匹配 SDK 自身的面板或弹窗内部节点。容器首次匹配后会持续持有面板，直到节点从文档移除或配置的选择器改变；挂载后仅改变容器的 class 等属性不会释放面板。这使 :empty 等选择器不会因 SDK 插入内容而反复装卸。要销毁面板，请移除对应容器节点。

SDK 仅负责渲染面板，不会替换你原有的结账按钮，也不会自动插入「不含保护结账」按钮。面板样式由客户经理（AM）按适配模式在后台配置，站点负责渲染面板容器与结账按钮：

渲染项	`cart`	`checkout`	`checkout+`
面板样式	带开关	带开关	推荐使用不带开关的纯报价面板
结账按钮	原有按钮的点击处理函数 `await resolveSP()`，失败阻断	沿用原有按钮，点击时先调用 `resolveSP()`	两个按钮分别调 `addSpFee()` 与 `declineSpFee()`

checkout+ 没有开关意愿。如果后台仍给该模式配置了带开关的面板，开关只会改变占位意愿，既不写车也不被结账流程读取。因此顾客的选择只能由两个结账按钮表达，页面上必须同时提供「不含保护结账」按钮。不要调用 resolveSP()（会被拒绝并指引改用两个写入口），弹窗也不展示意愿按钮。容器挂载与按钮点击逻辑均由站点实现。

下一步

cart 模式：快速开始完成基础接入后，还须按本页要求实现结账调用、失败阻断与忙时重试。
checkout 模式：继续阅读 Checkout 适配模式。
checkout+ 模式：继续阅读 Checkout+ 适配模式。